From b68622bf8e6f4b2b3015bcb9c44646b8ece19491 Mon Sep 17 00:00:00 2001 From: mvertens Date: Sun, 26 Feb 2017 14:39:35 -0700 Subject: [PATCH 001/255] first pass at CLM sphinx documentation --- doc/Makefile | 20 + doc/source/conf.py | 164 +++++ doc/source/index.rst | 26 + ...w-Files-to-the-build-namelist-Database.rst | 24 + .../CLM-3.1-Managing-Your-Own-Data-files.rst | 73 ++ .../CLM-3.2-Adding-Resolution-Names.rst | 45 ++ ...3-Adding-or-Changing-Default-Filenames.rst | 40 + .../adding-new-resolutions/index.rst | 18 + doc/source/users_guide/index.rst | 23 + .../users_guide/overview/getting-help.rst | 117 +++ doc/source/users_guide/overview/index.rst | 18 + .../users_guide/overview/introduction.rst | 199 +++++ .../users_guide/overview/quickstart.rst | 114 +++ .../overview/scientific_validation.rst | 78 ++ .../running-PTCLM/adding-ptclm-site-data.rst | 109 +++ .../users_guide/running-PTCLM/index.rst | 18 + .../running-PTCLM/introduction-to-ptclm.rst | 139 ++++ .../running-PTCLM/ptclm-examples.rst | 70 ++ .../users_guide/running-PTCLM/using-ptclm.rst | 222 ++++++ .../running-single-points/index.rst | 18 + .../running-pts_mode-configurations.rst | 40 + .../running-single-point-configurations.rst | 218 ++++++ ...point-and-regional-grid-configurations.rst | 51 ++ ...tellite-Phenology-Model-(CLMSP-spinup).rst | 10 + ...CLM4.5-biogeochemistry-(CLMBGC-spinup).rst | 75 ++ ...tmospheric-forcing-to-spinup-the-model.rst | 31 + ...tmospheric-forcing-to-spinup-the-model.rst | 75 ++ ...transient-historical-CO2-concentration.rst | 138 ++++ .../running-special-cases/index.rst | 22 + .../running-the-prognostic-crop-model.rst | 31 + .../running-with-irrigation.rst | 33 + .../what-is-a-special-case.rst | 12 + .../choosing-a-compset.rst | 321 ++++++++ .../customizing-the-clm-configuration.rst | 688 ++++++++++++++++++ .../customizing-the-clm-namelist.rst | 251 +++++++ .../customizing-the-datm-namelist.rst | 109 +++ .../setting-up-and-running-a-case/index.rst | 19 + doc/source/users_guide/testing/index.rst | 18 + doc/source/users_guide/testing/testing.rst | 62 ++ .../users_guide/trouble-shooting/index.rst | 15 + .../trouble-shooting/trouble-shooting.rst | 395 ++++++++++ .../building-the-clm-tools.rst | 162 +++++ .../users_guide/using-clm-tools/cprnc.rst | 29 + .../using-clm-tools/creating-domain-files.rst | 27 + ...g-input-for-surface-dataset-generation.rst | 116 +++ .../creating-surface-datasets.rst | 376 ++++++++++ .../datasts-for-observational-sites.rst | 17 + .../users_guide/using-clm-tools/index.rst | 21 + .../observational-sites-datasets.rst | 18 + .../what-are-the-clm-tools.rst | 89 +++ 50 files changed, 5004 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst create mode 100644 doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst create mode 100644 doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst create mode 100644 doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst create mode 100644 doc/source/users_guide/adding-new-resolutions/index.rst create mode 100644 doc/source/users_guide/index.rst create mode 100644 doc/source/users_guide/overview/getting-help.rst create mode 100644 doc/source/users_guide/overview/index.rst create mode 100644 doc/source/users_guide/overview/introduction.rst create mode 100644 doc/source/users_guide/overview/quickstart.rst create mode 100644 doc/source/users_guide/overview/scientific_validation.rst create mode 100644 doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst create mode 100644 doc/source/users_guide/running-PTCLM/index.rst create mode 100644 doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst create mode 100644 doc/source/users_guide/running-PTCLM/ptclm-examples.rst create mode 100644 doc/source/users_guide/running-PTCLM/using-ptclm.rst create mode 100644 doc/source/users_guide/running-single-points/index.rst create mode 100644 doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst create mode 100644 doc/source/users_guide/running-single-points/running-single-point-configurations.rst create mode 100644 doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst create mode 100644 doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst create mode 100644 doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst create mode 100644 doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst create mode 100644 doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst create mode 100644 doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst create mode 100644 doc/source/users_guide/running-special-cases/index.rst create mode 100644 doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst create mode 100644 doc/source/users_guide/running-special-cases/running-with-irrigation.rst create mode 100644 doc/source/users_guide/running-special-cases/what-is-a-special-case.rst create mode 100644 doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst create mode 100644 doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst create mode 100644 doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst create mode 100644 doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst create mode 100644 doc/source/users_guide/setting-up-and-running-a-case/index.rst create mode 100644 doc/source/users_guide/testing/index.rst create mode 100644 doc/source/users_guide/testing/testing.rst create mode 100644 doc/source/users_guide/trouble-shooting/index.rst create mode 100644 doc/source/users_guide/trouble-shooting/trouble-shooting.rst create mode 100644 doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst create mode 100644 doc/source/users_guide/using-clm-tools/cprnc.rst create mode 100644 doc/source/users_guide/using-clm-tools/creating-domain-files.rst create mode 100644 doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst create mode 100644 doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst create mode 100644 doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst create mode 100644 doc/source/users_guide/using-clm-tools/index.rst create mode 100644 doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst create mode 100644 doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000..6d3ce5f50d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = clmdoc +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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) \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000000..bdf2be569c --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,164 @@ +# -*- coding: utf-8 -*- +# +# clmdoc documentation build configuration file, created by +# sphinx-quickstart on Thu Feb 23 17:14:30 2017. +# +# 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. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- 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.ext.intersphinx', + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.githubpages'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'clmdoc' +copyright = u'2017, Erik Kluzek, Bill Sacks, Ben Andre' +author = u'Erik Kluzek, Bill Sacks, Ben Andre' + +# 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 = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- 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 = 'bizstyle' + +# 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 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'clmdocdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'clmdoc.tex', u'clmdoc Documentation', + u'Erik Kluzek, Bill Sacks, Ben Andre', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'clmdoc', u'clmdoc Documentation', + [author], 1) +] + + +# -- 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 = [ + (master_doc, 'clmdoc', u'clmdoc Documentation', + author, 'clmdoc', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000000..a5ec1eb158 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,26 @@ +.. clmdoc documentation master file, created by + sphinx-quickstart on Tue Feb 21 13:37:07 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to the CLM documentation +================================== + +This document has one major sections. + +The :ref:`CLM user's guide ` is a basic guide in utilizing CLM. + +Table of contents +----------------- + +.. toctree:: + :maxdepth: 1 + + users_guide/index.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst new file mode 100644 index 0000000000..de13570b3d --- /dev/null +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst @@ -0,0 +1,24 @@ +.. _adding-resolutions: + +======================== + Adding New Resolutions +======================== + +In the last chapter we gave the details on how to create new files for input into CLM. +These files could be either global resolutions, regional-grids or even a single grid point. +If you want to easily have these files available for continued use in your development you will then want to include them in the build-namelist database so that build-namelist can easily find them for you. +You can deal with them, just by putting the settings in the ``user_nl_clm namelist`` file, or by using ``CLM_USRDAT_NAME``. +Another way to deal with them is to enter them into the database for build-namelist, so that build-namelist can find them for you. +This keeps one central database for all your files, rather than having multiple locations to keep track of files. +If you have a LOT of files to keep track of it also might be easier than keeping track by hand, especially if you have to periodically update your files. +If you just have a few quick experiments to try, for a short time period you might be best off using the other methods mentioned above. + +There are two parts to adding files to the build-namelist database. +The first part is adding new resolution names which is done in the ``models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml`` file (and in the ``models/lnd/clm/bld/config_files/config_definition.xml`` file when adding supported single-point datasets). +You can then use the new resolution by using ``CLM_USRDAT_NAME``. +If you also want to be able to give the resolution into **create_newcase** -- you'll need to add the grid to the ``scripts/ccsm_utils/Case.template/config_grid.xml`` file. + +The second part is actually adding the new filenames which is done in the ``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml`` file (``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5_tools.xml`` file for CLM tools). +If you aren't adding any new resolutions, and you are just changing the files for existing resolutions, you don't need to edit the namelist_definition file. + + diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst new file mode 100644 index 0000000000..a8ebc81ac8 --- /dev/null +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst @@ -0,0 +1,73 @@ +.. _managing-your-data-files: + +============================== + Managing Your Data Own Files +============================== + +If you are running on a supported machine (such as yellowstone or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `CESM1.2.0 Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. + +Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. + +``` +> cd scripts +# First make sure you have a inputdata location that you can write to +# You only need to do this step once, so you won't need to do this in the future +# (except to bring in any updated files in the original $CSMDATA location). +> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data +> ./link_dirtree $CSMDATA $MYCSMDATA +``` + +Then when you create a case you will change ``DIN_LOC_ROOT_CSMDATA`` to point to the location you linked to rather than the default location. + +``> ./xmlchange DIN_LOC_ROOT_CSMDATA=$MYCSMDATA`` + +In order to list the files that you have created you merely need to use the UNIX command find to find the files that are NOT softlinks. So for example executing the following command: + +``> find $MYCSMDATA -type f -print`` + +for me gives the following truncated list of CLM_USRDAT_NAME files that I have created. + +``` +/glade/p/work/erik/inputdata/lnd/clm2/pftdata/pft-physiology.c130503.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-01.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-02.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-03.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-04.nc +``` + +You can also use **find** to list files that have a particular pattern in the name as well (using the -name option with wildcards). Also you can always rerun the **link_dirtree** command if any new files are added that you need to be linked into your directory tree. Since, the files are soft-links -- it doesn't take up much space other than the files that you add there. This way all of the files are kept in one place, they are organized by usage according to CESM standards, and you can easily find your own files, and CLM can find them as well. + + + +If you are running on a supported machine (such as yellowstone or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `CESM1.2.0 Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. + +Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. + +``` +> cd scripts +# First make sure you have a inputdata location that you can write to +# You only need to do this step once, so you won't need to do this in the future +# (except to bring in any updated files in the original $CSMDATA location). +> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data +> ./link_dirtree $CSMDATA $MYCSMDATA +``` + +Then when you create a case you will change ``DIN_LOC_ROOT_CSMDATA`` to point to the location you linked to rather than the default location. + +``> ./xmlchange DIN_LOC_ROOT_CSMDATA=$MYCSMDATA`` + +In order to list the files that you have created you merely need to use the UNIX command find to find the files that are NOT softlinks. So for example executing the following command: + +``> find $MYCSMDATA -type f -print`` + +for me gives the following truncated list of CLM_USRDAT_NAME files that I have created. + +``` +/glade/p/work/erik/inputdata/lnd/clm2/pftdata/pft-physiology.c130503.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-01.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-02.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-03.nc +/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-04.nc +``` + +You can also use **find** to list files that have a particular pattern in the name as well (using the -name option with wildcards). Also you can always rerun the **link_dirtree** command if any new files are added that you need to be linked into your directory tree. Since, the files are soft-links -- it doesn't take up much space other than the files that you add there. This way all of the files are kept in one place, they are organized by usage according to CESM standards, and you can easily find your own files, and CLM can find them as well. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst new file mode 100644 index 0000000000..6d44f73b5b --- /dev/null +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst @@ -0,0 +1,45 @@ +.. _adding-resolution-names: + +========================= + Adding Resolution Names +========================= + +If you are adding files for new resolutions which aren't covered in the namelist_definition file -- you'll need to add them in. +The list of valid resolutions is in the id="res" entry in the ``models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml`` file. +You need to choose a name for your new resolution and simply add it to the comma delimited list of valid_values for the id="res" entry. +The convention for global Gaussian grids is number_of_latitudes x number_of_longitudes. +The convention for global finite volume grids is latitude_grid_size x longitude_grid_size where latitude and longitude is measured in degrees. +The convention for unstructured HOMME grids is nenp4, where corresponds to the resolution. +The higher is the higher the resolution. +So for example, ne60np4 is roughly half-degree while ne240np4 is roughly a eighth degree. +For regional or single-point datasets the names have a grid size number_of_latitudes x number_of_longitudes followed by an underscore and then a descriptive name such as a City name followed by an abbreviation for the Country in caps. +The only hard requirement is that names be unique for different grid files. Here's what the entry for resolutions looks like in the file: +:: + + + Horizontal resolutions + Note: 0.1x0.1, 0.5x0.5, 5x5min, 10x10min, 3x3min, 1km-merge-10min, and 0.33x0.33 are only used for CLM tools + + +As you can see you just add your new resolution names to the end of the valid_values list. + +When using PTCLM and adding supported single-point resolutions, you'll also want to add these resolutions to the ``models/lnd/clm/bld/config_files/config_definition.xml`` under the ``sitespf_pt`` name. +The entry in that file looks like: +:: + + + Flag to turn on site specific special configuration flags for supported single + point resolutions. See the specific config_defaults_*.xml file for the special + settings that are set for a particular site. + + +PTCLM assumes that any supported single-point resolutions are valid settings for ``sitespf_pt``. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst new file mode 100644 index 0000000000..c539d0fd8c --- /dev/null +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst @@ -0,0 +1,40 @@ +.. _changing-default-filenames: + +============================ + Changing Default Filenames +============================ + +To add or change the default filenames you edit the ``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml`` and either change an existing filename or add a new one. +Most entries in the default namelist files, include different attributes that describe the different properties that describe the differences in the datasets. +Attributes include the: resolution, year to simulation, range of years to simulate for transient datafiles, the land-mask, the representative concentration pathway (rcp) for future scenarios, and the type of biogeochemistry (bgc) model used. +For example the fatmgrid for the 1.9x2.5 resolution is as follows: + +``` + +lnd/clm2/surfdata_map/surfdata_0.9x1.25_simyr1850_c130415.nc + +``` + +Other ``fsurdat`` files are distinguished from this one by their resolution (hgrid), simulation year (sim_year) and prognostic crop (crop) attributes. + + +To add or change the default filenames for CLM tools edit the ``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5_tools.xml`` and either change an existing filename or add a new one. +Editing this file is similar to the ``namelist_defaults_clm4_5.xml`` talked about above. + + +---------------------------- +What are the required files? +---------------------------- + +Different types of simulations and different types of configurations for CLM require different lists of files. +The CLM4.5-BGC or Carbon Nitrogen (cn) Biogeochemistry model for example requires ``stream_fldfilename_ndep`` files, which are NOT required by CLMSP. +Transient simulations also require transient datasets, and the names of these datasets are sometimes different from the static versions (sometimes both are required as in the dynamic PFT cases). + + +In the following table we list the different files used by CLM, they are listed in order of importance, dependencies, and customizing. +So the required files are all near the top, and the files used only under different conditions are listed later, and files with the fewest dependencies are near the top, as are the files that are least likely to be customized. + + +Table 3-1. Required Files for Different Configurations and Simulation Types +--------------------------------------------------------------------------- +Insert table 3-1 diff --git a/doc/source/users_guide/adding-new-resolutions/index.rst b/doc/source/users_guide/adding-new-resolutions/index.rst new file mode 100644 index 0000000000..c01aa36ca0 --- /dev/null +++ b/doc/source/users_guide/adding-new-resolutions/index.rst @@ -0,0 +1,18 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _adding-new-resolutions-section: + +##################################### +Adding New Resolutions +##################################### + +.. toctree:: + :maxdepth: 2 + + CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst + CLM-3.1-Managing-Your-Own-Data-files.rst + CLM-3.2-Adding-Resolution-Names.rst + CLM-3.3-Adding-or-Changing-Default-Filenames.rst diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst new file mode 100644 index 0000000000..510d4b22a2 --- /dev/null +++ b/doc/source/users_guide/index.rst @@ -0,0 +1,23 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _users-guide: + +##################################### +CLM User's Guide +##################################### + +.. toctree:: + :maxdepth: 2 + :numbered: + + overview/index.rst + setting-up-and-running-a-case/index.rst + using-clm-tools/index.rst + adding-new-resolutions/index.rst + running-special-cases/index.rst + running-single-points/index.rst + running-PTCLM/index.rst + trouble-shooting/index.rst diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst new file mode 100644 index 0000000000..fb5069226b --- /dev/null +++ b/doc/source/users_guide/overview/getting-help.rst @@ -0,0 +1,117 @@ +.. _getting-help: + +============== + Getting Help +============== +In addition to this users-guide there are several other resources that are available to help you use CLM4.5. The first one is the CESM1.2.0 User's-Guide, which documents the entire process of creating cases with CESM1.2.0. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in CESM1.2.0. + +--------------------------- +The CESM User's-Guide +--------------------------- + +CLM4.5 in CESM1.2.0 is always run from within the standard CESM1.2.0 build and run scripts. Therefore, the user of CLM4.5 should familiarize themselves with the CESM1.2.0 scripts and understand how to work with them. User's-Guide documentation on the CESM1.2.0 scripts are available from the following web-page. The purpose of this CLM4.5 in CESM1.2.0 User's Guide is to give the CLM4.5 user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the CESM1.2.0 Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. + +`cesmrel; Scripts User's-Guide (http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/usersguide/book1.html) `_ + +----------------------- +The CESM Bulletin Board +----------------------- + +There is a rich and diverse set of people that use the CESM, and often it is useful to be in contact with others to get help in solving problems or trying something new. To facilitate this we have an online Bulletin Board for questions on the CESM. There are also different sections in the Bulletin Board for the different component models or for different topics. + +`CESM Online Bulletin Board `_ + +----------------- +The CLM web pages +----------------- + +The main CLM web page contains information on the CLM, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the models/lnd/clm/doc directory that give some quick information on using CLM. + +`CLM web page `_ +`CLM Documentation Text Files `_ + +Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files: + +- `models/lnd/clm/bld/namelist_files/namelist_definition_clm4_0.xml `_ -- definition of CLM4.0 namelist items. +- `models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml `_ -- definition of CLM4.0 namelist items. +- `models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_0.xml `_ -- default values for CLM4.0 namelist items. +- `models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml `_ -- default values for CLM4.5 namelist items. +- `scripts/ccsm_utils/Case.template/config_definition.xml `_ -- definition of all env_*.xml items. +- `scripts/ccsm_utils/Case.template/config_compsets.xml `_ -- definition of all the compsets. +- `models/lnd/clm/bld/namelist_files/history_fields_clm4_0.xml `_ -- definition of CLM4.0 history fields. +- `models/lnd/clm/bld/namelist_files/history_fields_clm4_5.xml `_ -- definition of CLM4.5 history fields. + +------------------------ +Reporting bugs in CLM4.5 +------------------------ + +If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for CLM4.5 in CESM1.2.0 is in the models/lnd/clm/doc/KnownBugs file, and the list of issues for CESM1.2.0 is at... +`http://www.cesm.ucar.edu/models/cesm1.2//tags/cesm1_2_0/#PROBLEMS `_. + +--------------------------------------- +Some Acronym's and Terms We'll be Using +--------------------------------------- + +CAM + Community Atmosphere Model (CAM). The prognostically active atmosphere model component of CESM. + +CESM + Community Earth System Model (CESM). The coupled earth system model that CLM is a component of. + +CLM + Community Land Model (CLM). The prognostically active land model component of CESM. + +CLMBGC + Community Land Model (CLM4.5) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is + + ``./xmlchange CLM_CONFIG_OPTS="phys clm4_5 -bgc cn -vsoilc_centbgc on -clm4me on"`` + +CLMCN + Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or CLM4.5) The CLM_CONFIG_OPTS option for this is + + ``./xmlchange CLM_CONFIG_OPTS="-bgc cn" -append`` + +CLMSP + Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0 or CLM4.5) The CLM_CONFIG_OPTS option for this is + + ``./xmlchange CLM_CONFIG_OPTS="-bgc none" -append`` + +CLMU + Community Land Model (CLM) Urban Model (either CLM4.0 or CLM4.5). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). + +CRUNCEP + The Climate Research Unit (CRU) analysis of the NCEP atmosphere reanalysis atmosphere forcing data. This can be used to drive CLM with atmosphere forcing from 1901 to 2010. We also DO expect to be able to update this dataset beyond 2010 as newer data becomes available. + +DATM + Data Atmosphere Model (DATM) the prescribed data atmosphere component for CESM. Forcing data that we provide are either the Qian or CRUNCEP forcing datasets (see below). + +DV + Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either CLM4.5-BGC or CLMCN for either CLM4.0 or CLM4.5). The CLM_CONFIG_OPTS option for this is + + ``./xmlchange CLM_CONFIG_OPTS="-bgc cndv" -append`` + +ESMF + Earth System Modeling Framework (ESMF). They are a software project that provides a software library to support Earth System modeling. We provide interfaces for ESMF as well as use their regridding capabilities for offline CLM tools. + +NCAR + National Center for Atmospheric Research (NCAR). This is the research facility that maintains CLM with contributions from other national labs and Universities. + +NCEP + The National Center for Environmental Prediction (NCEP). In this document this normally refers to the reanalysis atmosphere data produced by NCEP. + +PFT + Plant Function Type (PFT). A type of vegetation that CLM parameterizes. + +PTCLM + PoinT CLM (PTCLM) a python script that operates on top of CLM for CLM4.5 to run single point simulations for CLM. + +Qian + The Qian et. al. analysis of the NCEP forcing data. This can be used to drive CLM with atmosphere forcing from 1948 to 2004. We do NOT expect to be able to update this dataset beyond 2004. + +SCRIP + Spherical Coordinate Remapping and Interpolation Package (SCRIP). We use it's file format for specifying both grid coordinates as well as mapping between different grids. + +VIC + Variable Infiltration Capacity (VIC) model for hydrology. This is an option to CLM4.5 in place of the standard CLM4.5 hydrology. The CLM_CONFIG_OPTS option for this is + + ``./xmlchange CLM_CONFIG_OPTS="-vichydro on" -append`` diff --git a/doc/source/users_guide/overview/index.rst b/doc/source/users_guide/overview/index.rst new file mode 100644 index 0000000000..1f31037460 --- /dev/null +++ b/doc/source/users_guide/overview/index.rst @@ -0,0 +1,18 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _overview_section: + +##################################### +Overview +##################################### + +.. toctree:: + :maxdepth: 2 + + introduction.rst + quickstart.rst + scientific_validation.rst + getting-help.rst diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst new file mode 100644 index 0000000000..37eb0cb82d --- /dev/null +++ b/doc/source/users_guide/overview/introduction.rst @@ -0,0 +1,199 @@ +.. _introduction: + +============== +Introduction +============== + +The Community Land Model (CLM4.5 in CESM1.2.0) is the latest in a +series of global land models developed by t he CESM Land Model Working +Group (LMWG) and maintained at the National Center for Atmospheric +Research (NCAR). This guide is intended to instruct both the novice +and experienced user on running CLM. This guide pertains to the latest +version CLM4.5 in CESM1.2.0 available for download from the public +release subversion repository as a part of CESM1.2.0. Documentation +may be different if you are using an older version, you should either +use the documentation for that release version, update to the latest +version, or use the documentation inside your own source tree. There +is information in the ChangeLog file and in the `What is new with +CLM4.5 in CESM1.2.0 since previous public releases? `_ +regarding the changes from previous versions of CESM. + +.. note:: This release of CLM4.5 in CESM1.2.0 includes BOTH CLM4.0 + physics used in previous releases as well as the updated CLM4.5 + physics. Both CLM as well as CLM support tools allow you to trigger + between the two physics modes. Most often when we refer to CLM4.0 we + are referring to the CLM4.0 physics in CLM4.5 in CESM1.2.0 rather + than to a specific version of CLM4.0 (where we would give the exact + version). Likewise, when referring to CLM4.5 we are referring to the + CLM4.5 physics in CLM4.5 in CESM1.2.0. + +The novice user should read `Chapter 1 `_ in detail before +beginning work, while the expert user should read `What is new with +CLM4.5 in CESM1.2.0 since previous public releases? `_ and +`Quickstart to using CLM4.5 `_ chapters, and then use the +more detailed chapters as reference. Before novice users go onto more +technical problems covered in `Chapter 2 `_, `Chapter 3 +`_, `Chapter 4 `_, or `Chapter 5 `_ they +should know the material covered in `Chapter 1 `_ and be able +to replicate some of the examples given there. + +All users should read the `How to Use This Document `_ and +`Other resources to get help from `_ sections to understand +the document conventions and the various ways of getting help on using +CLM4.5. Users should also read the `What is scientifically validated +and functional in CLM4.5 in CESM1.2.0? `_ section to see if +their planned use of the model is something that has been +scientifically validated and well tested. Users that are NOT using +NCAR machines or our list of well tested machines should also read the +What are the UNIX utilities required to use CLM4.5? section to make +sure they have all the required UNIX utilities on the system they want +to do their work. + +Developers that are making changes to CLM either for their own +development or for development that they hope will eventually become a +part of the main CLM should read the `Chapter 8 `_ +chapter. We have a suite of test scripts that automatically test many +different model configurations and namelist options, as well as +ensuring things like restarts are bit-for-bit and the like. It's +helpful to use these scripts to ensure your changes are working +correctly. As well as being a required part of the process to bring in +new code developments. And it's far easier to use the automated +scripts rather than having to figure out, what to test, how to do it, +and then finally do it by hand. If you are using non supported +machines you may also want to use the test scripts to make sure your +machine is working correctly. + +.. _what-is-new-with-clm4.5: + +========================= + What is New with CLM4.5 +========================= + +The CESM1.2.0 `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. +More details are given in the `CLM ChangeLog file `_. + +Previous release pages give similar list of changes for previous versions of the model. +The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates for versions up to CLM4 in CESM1.0.5. + +.. _users-guide-overview: + +========================== + Overview of User's Guide +========================== + +In this introduction we first give a simple guide to understand the document conventions in `How to Use This Document `_. +The next section `What is new with CLM4.5 in CESM1.2.0 since previous public releases? `_ gives references to describe the differences between CLM4.5 in CESM1.2.0 and previous CESM releases both from a scientific as well as a software engineering point of view. +For information on previous releases of CLM4.5 before CLM4.5 in CESM1.2.0 see the CESM1.1.1 documentation. +The next section `Quickstart to using CLM4.5 `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use CLM4.5. +The next `What is scientifically validated and functional in CLM4.5 in CESM1.2.0? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. +`What are the UNIX utilities required to use CLM4.5? `_ lists the UNIX utilities required to use CLM4.5 and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. +Next we have `Important Notes and Best Practices for Usage of CLM4.5 `_ to detail some of the best practices for using CLM4.5 for science. +The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and CLM4.5. + +`Chapter 1 `_ goes into detail on how to setup and run simulations with CLM4.5 and especially how to customize cases. +Details of cesm_setup modes and build-namelist options as well as namelist options are given in this chapter. + +`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or CLM4.5 physics for creating input datasets for use by CLM, for the expert user. +There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. +Then each tool is described in detail along with different ways in which the tool might be used. +A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. + +As a followup to the tools chapter, `Chapter 3 `_ tells how to add files to the XML database for build-namelist to use. +This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and CLM4.5 physics). + +In `Chapter 4 `_, again for the expert user, we give details on how to do some particularly difficult special cases. +For example, we give the protocol for spinning up the CLM4.5-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). +We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. +We also give instructions on running both the prognostic crop and irrigation models. +Lastly we tell the user how to use the DATM model to send historical CO2 data to CLM. + +`Chapter 5 `_ outlines how to do single-point or regional simulations using CLM4.5. +This is useful to either compare CLM4.5 simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. +There are several different ways given on how to perform single-point simulations which range from simple PTS_MODE to more complex where you create all your own datasets, tying into `Chapter 2 `_ and also `Chapter 3 `_ to add the files into the build-namelist XML database. +The PTCLM python script to run single-point simulations was added back in for this release (but it has bugs that don't allow it to work out of the box). +CLM4 in CESM1.0.5 has a fully working versions of PTCLM. + +Need `Chapter 6 `_ blurb... + +`Chapter 7 `_ gives some guidance on trouble-shooting problems when using CLM4.5. +It doesn't cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems. + +`Chapter 8 `_ goes over the automated testing scripts for validating that the CLM is working correctly. +The test scripts run many different configurations and options with CLM4.0 physics as well and CLM4.5 physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. +In general this is an activity important only for a developer of CLM4.5, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. + +In the appendices we talk about some issues that are useful for advanced users and developers of CLM4.5. + +Finally in `Appendix A `_ we give instructions on how to build the documentation associated with CLM4.5 (i.e. how to build this document). +This document is included in every CLM distribution and can be built so that you can view a local copy rather than having to go to the CESM website. +This also could be useful for developers who need to update the documentation due to changes they have made. + +.. _best-practices-for-usage: + +================ + Best Practices +================ + +- CLM4.5 includes BOTH the old CLM4.0 physics AND the new CLM4.5 physics and you can toggle between two. + The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. + While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. + "BGC" is the new CLM4.5 biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). + +- When running with CLMCN (either CLM4.0 or CLM4.5 physics) or CLM4.5-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the CLM4.5 biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for CLM4.5 or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). + Simulations without a proper spinup will effectively be starting from an unvegetated world. + See `the Section called Setting Your Initial Conditions File in Chapter 1 `_ for information on how to provide initial conditions for your simulation. + +- Initial condition files are provided for CLM4.0-CN as before, for fully coupled BCN and offline ICN cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. + We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). + There's also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with CLMSP for 2000 at 2deg resolution. + We also have initial conditions for offline CNDV for 1850. + The 1850 initial condition files are in 'reasonable' equilibrium. + The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. + Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. + Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. + +- Initial condition files are also provided for CLM4.5 for several configurations and resolutions. + For CLM4.5-SP and CLM4.5-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. + The CLM4.5-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. + Also the CLM4.5-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg CLM4.5-BGC-DV and 2deg CLM4.5-BGC-Crop. + +- Users can generate initial condition files at different resolutions by using the CLM tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. + Interpolated initial condition files may no longer be in 'reasonable' equilibrium. + +- In CLM4.5 for both CLM4.5-CN and CLM4.5-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). + By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2010 for population density. + Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. + If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. + +- Aerosol deposition is a required field to both CLM4.0 and CLM4.5 physics, sent from the atmosphere model. + Simulations without aerosol deposition will exhibit unreasonably high snow albedos. + The model sends aerosol deposition from the atmospheric model (either CAM or DATM). + When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. + +.. _how-to-use-this-document: + +======================================================== +How To Use This Document +======================================================== + +Links to descriptions and definitions have been provided in the code below. We use the same conventions used in the CESM documentation as outlined below. + +:: + + Throughout the document this style is used to indicate shell + commands and options, fragments of code, namelist variables, etc. + Where examples from an interactive shell session are presented, lines + starting with > indicate the shell prompt. A backslash "\" at the end + of a line means the line continues onto the next one (as it does in + standard UNIX shell). Note that $EDITOR" is used to refer to the + text editor of your choice. $EDITOR is a standard UNIX environment + variable and should be set on most UNIX systems. Comment lines are + signaled with a "#" sign, which is the standard UNIX comment sign as well. + $CSMDATA is used to denote the path to the inputdata directory for + your CESM data. + + > This is a shell prompt with commands \ + that continues to the following line. + > $EDITOR filename # means you are using a text editor to edit "filename" + # This is a comment line + diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst new file mode 100644 index 0000000000..f6784da2ef --- /dev/null +++ b/doc/source/users_guide/overview/quickstart.rst @@ -0,0 +1,114 @@ +.. _quickstart: + +============ + Quickstart +============ + +Running the CLM requires a suite of UNIX utilities and programs and you should make sure you have all of these available before trying to go forward with using it. +If you are missing one of these you should contact the systems administrator for the machine you wish to run on and make sure they are installed. + +List of utilities required for CESM in the "CESM1.2.0 Software/Operating System Prerequisites" section in `http://www.cesm.ucar.edu/models/cesm1.2//cesm/doc/usersguide/book1.html `_ +- UNIX bash shell (for some of the CLM tools scripts) +- NCL (for some of the offline tools for creating/modifying CLM input datasets see `Chapter 2 `_ for more information on NCL) +- Python (optional, needed for PTCLM) +- xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide) + +Before working with CLM4.5 read the QuickStart Guide in the `CESM1.2.0 Scripts User's Guide `_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM. + +For some of the details of setting up cases for CLM4.5 read the README and text files available from the "models/lnd/clm/doc" directory (see the "CLM Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. + +1. `README file `_ describing the directory structure. + +2. `Quickstart.userdatasets `_ file describing how to use your own datasets in the model (also see `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_). + +3. `models/lnd/clm/doc/KnownBugs `_ file describing known problems in CLM4.5 (that we expect to eventually fix). + +4. `models/lnd/clm/doc/KnownLimitationss `_ file describing known limitations in CLM4.5 and workarounds that we do NOT expect to fix. + +The IMPORTANT_NOTES file talks about important things for users to know about using the model scientifically. It content is given in the next chapter on `"What is scientifically validated and functional in CLM4.5 in CESM1.2.0?" `_. + +The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on `"What is new with CLM4.5 in CESM1.2.0 since previous public releases?" `_. + +Note other directories have README files that explain different components and tools used when running CLM and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with CLM see `Chapter 1 `_. + +The Quickstart.GUIDE (which can be found in ``models/lnd/clm/doc``) is repeated here. +:: + + Quick-Start to Using cpl7 Scripts for clm4_5 + + Assumptions: You want to use yellowstone with clm4_5 BGC + to do a clm simulation with data atmosphere and the + latest CRUNCEP atm forcing files and settings. You also want to cycle + the CRUNCEP atm data between 1901 to 1920 and you want to run at + 0.9x1.25 degree resolution. + + Process: + + # Create the case + + cd scripts + + ./create_newcase -case -mach yellowstone_intel -res f09_g16 -compset I1850CRUCLM45BGC + (./create_newcase -help -- to get help on the script) + + # Setup the case + + cd + ./xmlchange id1=val1,id2=val2 # to make changes to any settings in the env_*.xml files + ./cesm_setup + (./cesm_setup -help -- to get help on the script, this creates the ./.run \ + script) + + # Add any namelist changes to the user_nl_* files + + $EDITOR user_nl_* + + # Compile the code + + ./.build + + # Submit the run + + ./.submit + +Information on Compsets: + + "I" compsets are the ones with clm and datm7 without ice and ocean. They + specify either CLM4.0 physics or CLM4.5 physics. + Most of the "I" compsets for CLM4.0 use the CLM_QIAN data with solar following + the cosine of solar zenith angle, precipitation constant, and other + variables linear interpolated in time (and with appropriate time-stamps on + the date). Useful "I" compsets for CLM4.5 use the CRUNCEP data in place + of the CLM_QIAN data. + + To list all the compsets use: + ./create_newcase -list compsets + + Some of the CLM4.5 I compsets are: + + Alias Description + 1850CRUCLM45 CLM4.5 to simulate year=1850 with CLMN45SP (Satellite Phenology) + I1850CRUCLM45BGC CLM4.5 to simulate year=1850 with CLM45BGC biogeophysics model (BGC) + I20TRCRUCLM45BGC CLM4.5 with BGC on with transient PFT over 1850-2000 + + While some of the CLM4 I compsets are: + + Alias Description + ICN CLM4.0 to simulate year=2000 with Carbon-Nitrogen BGC model (CN) + I1850CN CLM4.0 to simulate year=1850 with Carbon-Nitrogen BGC model (CN) + I20TRCN CLM4.0 with CN on with transient PFT over 1850-2000 + IRCP26CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=2.6 scenario + IRCP45CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=4.5 scenario + IRCP60CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=6.0 scenario + IRCP85CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=8.5 scenario + +Automatically resubmitting jobs: + + After doing a short simulation that you believe is correct + + ./xmlchange CONTINUE_RUN=TRUE + + # Change RESUBMIT to number greater than 0, and CONTINUE_RUN to TRUE... + + ./.submit + diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst new file mode 100644 index 0000000000..6ad113adc5 --- /dev/null +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -0,0 +1,78 @@ +.. _scientific-validiation: + +======================== + Scientific Validiation +======================== + +In this section we go over what has been extensively tested and scientifically validated with CLM4.5, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of CLM, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. + +-------------------------------------------------------------- +Standard Configuration and Namelist Options that are Validated +-------------------------------------------------------------- + +See +`http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for CLM4.5. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. + +In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for CLM4.5 while others are for both CLM4.0 AND CLM4.5 we explicitly say which they apply to. + +--------------------------------------------------------------------------------------------------------------- +Configure Modes NOT scientifically validated, documented, supported or, in some cases, even advised to be used: +--------------------------------------------------------------------------------------------------------------- + +These are options that you would add to ``CLM_CONFIG_OPTS``. + +1. exlaklayers on[CLM4.5 only] This mode is NOT tested and may NOT be even functional. + +2. snicar_frc on[CLM4.0 AND CLM4.5] This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. + +3. vichydro on[CLM4.5 only] This mode is tested and functional, but does NOT have long scientific validation simulations run with it so, should be considered experimental. + +4. vsoilc_centbgc[CLM4.5 only] This option is extensively tested for both "on" and "off". The "no-vert" option has limited testing performed on it, but isn't scientifically validated (and it currently has a bug -- see 1746 and 1672 in `models/lnd/clm/doc/KnownBugs `_). The "no-cent" and "no-nitrif" options are NOT tested and as such may NOT ben even functional. + +---------------------------------------------- +Namelist options that should NOT be exercised: +---------------------------------------------- + +---------------------------------------------------- +Build-Namelist options that should NOT be exercised: +---------------------------------------------------- +1. -irrig with -bgc cn and -phys clm4_0 We have only run the irrigation model with CLMSP (i.e. without the CN model). We recommend that if you want to run the irrigation model with CN, that you do a spinup. But, more than that you may need to make adjustments to irrig_factor in models/lnd/clm/src/biogeophys/CanopyFluxesMod.F90. See the notes on this in the description of the irrigation model in the +`Technical Descriptions of the Interactive Crop Management and Interactive Irrigation Models `_. + +2. -irrig with -crop on and -phys clm4_0 Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to generic crop currently, which negates it's practical usage. We also have a known problem when both are on (see bug 1326 in the `models/lnd/clm/doc/KnownBugs `_ file). If you try to run in this mode, the CLM build-namelist will return with an error. + +-------------------------------------------- +Namelist items that should NOT be exercised: +-------------------------------------------- + +suplnitro='ALL' The suplnitro namelist option to the CN Biogeochemistry model supplies unlimited nitrogen and therefore vegetation is over-productive in this mode. + +urban_traffic:Not currently functional + +allowlakeprod:Considered experimental. + +anoxia_wtsat:Considered experimental (deprecated will be removed). + +atm_c14_filename:Considered experimental (dataset not provided). + +exponential_rooting_profile:Considered experimental. + +fin_use_fsat:Considered experimental. + +glc_dyntopo:Not currently functional. + +lake_decomp_fact:Considered experimental. + +more_vertlayers:Considered experimental. + +no_frozen_nitrif_denitrif:Considered experimental. + +perchroot:Considered experimental. + +perchroot_alt:Considered experimental. + +replenishlakec:Considered experimental. + +use_c14_bombspike:Considered experimental (dataset not provided). + +usefrootc:Considered experimental. diff --git a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst new file mode 100644 index 0000000000..81f45a038f --- /dev/null +++ b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst @@ -0,0 +1,109 @@ +.. _adding-ptclm-site-data: + +====================== +Adding PTCLM Site Data +====================== + +The "sitegroupname" option to PTCLM1.110726 looks for groups of sites in the files in the ``PTCLM_sitedata`` directory under the PTCLM directory. +You can add new names available for this option including your own lists of sites, by adding more files in this directory. +There are three files for each "sitegroupname": ``$SITEGROUP_sitedata.txt``, ``$SITEGROUP_soildata.txt`` and ``$SITEGROUP_pftdata.txt`` (where ``$SITEGROUP`` is the name that would be entered as "sitegroupname" to PTCLM). +Each file needs to have the same list of sites, but gives different information: site data, PFT data, and soil data respectively. +Although the site codes need to be the same between the three files, the files do NOT have to be in the same order. +Each file has a one-line header that lists the contents of each column which are separated by commas. +The first column for each of the files is the "site_code" which must be consistent between the three files. +The site code can be any unique character string, but in general we use the AmeriFlux site code. + +Site data file:`` $SITEGROUP_sitedata.txt``): The header for this file is: +:: + + site_code,name,state,lon,lat,elev,startyear,endyear,alignyear + +The columns: name, state, and elevation are informational only. Name is a longer descriptive name of the site, and state is the state for U.S. sites or country for non U.S. sites. The columns: lon and lat are the longitude and latitude of the location in decimal degrees. The last three columns are the start and ending year for the data and the align year for an 1850 case for the data. The align year is currently unused. + +Soil data file: ``$SITEGROUP_soildata.txt``): The header for this file is: +:: + + site_code,soil_depth,n_layers,layer_depth,layer_sand%,layer_clay% + +The first three fields after "site_code" are currently unused. The only two that are used are the percent sand and clay columns to set the soil texture. + +PFT data file: ``$SITEGROUP_pftdata.txt```): The header for this file is: +:: + + site_code,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5 + +This file gives the vegetation coverage for the different vegetation types for the site. The file only supports up to five PFT's at the same time. The columns with "pft_f" are the fractions for each PFT, and the columns with "pft_c" is the integer index of the given PFT. Look at the pft-physiology file to see what the PFT index for each PFT type is. + +---------------------------------------------- +Dynamic Land-Use Change Files for use by PTCLM +---------------------------------------------- + +There is a mechanism for giving site-specific land-use change in PTCLM. Adding site specific files to the ``PTCLM_sitedata`` directory under PTCLM allows you to specify the change in vegetation and change in harvesting (for the CN model) for that site. Files are named: ``$SITE_dynpftdata.txt``. There is a sample file for the US-Ha1 site called: ``US-Ha1_dynpftdata.txt``. The file has a one-line header with the information that the file has, and then one-line for each year with a transition. The header line is as follows: +:: + + trans_year,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5,har_vh1,har_vh2,har_sh1,har_sh2,har_sh3,graze,hold_harv,hold_graze + +This file only requires a line for each year where a transition or harvest happens. As in the "pftdata" file above "pft_f" refers to the fraction and "pft_c" refers to the PFT index, and only up to five vegetation types are allowed to co-exist. The last eight columns have to do with harvesting and grazing. The last two columns are whether to hold harvesting and/or grazing constant until the next transition year and will just be either 1 or 0. This file will be converted by the **PTCLM_sitedata/cnvrt_trnsyrs2_pftdyntxtfile.pl** script in the PTCLM directory to a format that **mksurfdata_map** can read that has an entry for each year for the range of years valid for the compset in question. + +------------------------------------------ +Converting AmeriFlux Data for use by PTCLM +------------------------------------------ + +AmeriFlux data comes in comma separated format and is available from: +`http://public.ornl.gov/ameriflux/dataproducts.shtml `_. Before you download the data you need to agree to the usage terms. + +Here is a copy of the usage terms from the web-site on June/13/2011. + +"The AmeriFlux data provided on this site are freely available and were furnished by individual AmeriFlux scientists who encourage their use. +Please kindly inform the appropriate AmeriFlux scientist(s) of how you are using the data and of any publication plans. +Please acknowledge the data source as a citation or in the acknowledgments if the data are not yet published. +If the AmeriFlux Principal Investigators (PIs) feel that they should be acknowledged or offered participation as authors, they will let you know and we assume that an agreement on such matters will be reached before publishing and/or use of the data for publication. +If your work directly competes with the PI's analysis they may ask that they have the opportunity to submit a manuscript before you submit one that uses unpublished data. +In addition, when publishing, please acknowledge the agency that supported the research. +Lastly, we kindly request that those publishing papers using AmeriFlux data provide preprints to the PIs providing the data and to the data archive at the Carbon Dioxide Information Analysis Center (CDIAC)." + +The above agreement applies to the "US-UMB" dataset imported into our repository as well, and Gil Bohrer is the PI on record for that dataset. + + +The CESM can NOT handle missing data, so we recommend using the "Level 4" Gap filled datasets. +The fields will also need to be renamed. +The "WS" column becomes "WIND", "PREC" becomes "PRECmms", "RH" stays as "RH", "TA" becomes "TBOT", "Rg" becomes "FSDS", "Rgl" becomes "FLDS", "PRESS" becomes "PSRF". +"ZBOT" can just be set to the constant of "30" (m). +The units of Temperature need to be converted from "Celsius" to "Kelvin" (use the value in ``SHR_CONST_TKFRZ`` in the file ``models/csm_share/shr/shr_const.F90`` of ``273.15``. +The units of Pressure also need to be converted from "kPa" to "Pa". LATIXY, and LONGXY should also be set to the latitude and longitude of the site. + + +----------------------------------------------------------- +Example: PTCLM transient example over a shorter time period +----------------------------------------------------------- + +This is an example of using PTCLM for Harvard Forest (AmeriFlux site code US-Ha1) for transient land use 1991-2006. +In order to do this we would've needed to have converted the AmeriFlux data into NetCDF format as show in the `the Section called Converting AmeriFlux Data for use by PTCLM `_ section above. +Also note that this site has a site-specific dynamic land-use change file for it ``PTCLM_sitedata/US-Ha1_dynpftdata.txt`` in the PTCLM directory and this file will be used for land-use change and harvesting rather than the global dataset. + +:: + + > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + # We are going to use forcing data over 1991 to 2006, but we need to start with + # a transient compset to do so, so we use the 20th Century transient: 1850-2000 + # Note: When creating the fpftdyn dataset for this site it will use the + # PTCLM_sitedata/US-Ha1_dynpftdata.txt + # file for land-use change and harvesting + > ./PTCLM.py -m yellowstone_intel -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux -c I20TRCRUCLM45BGC + > mkdir $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 + > cd $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 + # Copy data in NetCDF format to this directory, filenames should be YYYY-MM.nc + # The fieldnames on the file should be: + # FLDS,FSDS,LATIXY, LONGXY, PRECTmms,PSRF,RH,TBOT,WIND,ZBOT + # With units + # W/m2,W/m2,degrees_N,degrees_E,mm/s, Pa, %, K, m/s, m + # The time coordinate units should be: days since YYYY-MM-DD 00:00:00 + > cd ../../../../../US-Ha1_I20TRCRUCLM45BGC + # Now we need to set the start date to 1991, and make sure the align year is for 1991 + > ./xmlchange RUN_STARTDATE=1991-01-01,DATM_CLMNCEP_YR_ALIGN=1991 + # Similarly for Nitrogen deposition data we cycle over: 1991 to 2006 + > cat << EOF >> user_nl_clm + model_year_align_ndep=1991,stream_year_first_ndep=1991,stream_year_last_ndep=2006 + EOF + # Now setup the case, and we'll edit the datm namelist for prescribed aerosols + > ./cesm_setup diff --git a/doc/source/users_guide/running-PTCLM/index.rst b/doc/source/users_guide/running-PTCLM/index.rst new file mode 100644 index 0000000000..d82b7f9624 --- /dev/null +++ b/doc/source/users_guide/running-PTCLM/index.rst @@ -0,0 +1,18 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _running-PTCLM: + +##################################### +Running PTCLM +##################################### + +.. toctree:: + :maxdepth: 2 + + introduction-to-ptclm.rst + using-ptclm.rst + ptclm-examples.rst + adding-ptclm-site-data.rst diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst new file mode 100644 index 0000000000..f710ed0bb4 --- /dev/null +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -0,0 +1,139 @@ +.. _introduction-to-ptclm.rst: + +.. _what-is-ptclm: + +=============== + What is PTCLM +=============== + +PTCLM (pronounced either as point clime or Pee-Tee clime) is a Python script to help you set up PoinT CLM simulations. + +It runs the CLM tools for you to get datasets set up, and copies them to a location you can use them according to the ``CLM_USRDAT_NAME`` naming convention. + +Then it runs **create_newcase** for you and modifies the env settings and namelist appropriately. + +PTCLM has a simple ASCII text file for storing basic information for your sites. + +We also have complete lists for AmeriFlux and Fluxnet-Canada sites, although we only have the meteorology data for one site. + +For other sites you will need to obtain the meteorology data and translate it to a format that the CESM datm model can use. + +But, even without meteorology data PTCLM is useful to setup datasets to run with standard ``CLM_QIAN`` data. + +The original authors of PTCLM are: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, Wilfred M. Post all at Environmental Sciences Division, Oak Ridge National Laboratory (ORNL) and R. Quinn Thomas at Cornell University. It was then modified fairly extensively by Erik Kluzek at NCAR. We want to thank all of these individuals for this contribution to the CESM effort. We also want to thank the folks at University of Michigan Biological Stations (US-UMB) who allowed us to use their Fluxnet station data and import it into our inputdata repository, especially Gil Bohrer the PI on record for this site. + + +.. _details-of-ptclm: + +================== + Details of PTCLM +================== + +To get help on PTCLM1.110726 use the "--help" option as follows. +:: + + > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + > ./PTCLM.py --help + +The output to the above command is as follows: +:: + + Usage: PTCLM.py [options] -d inputdatadir -m machine -s sitename + + Python script to create cases to run single point simulations with tower site data. + + Options: + --version show program's version number and exit + -h, --help show this help message and exit + + Required Options: + -d CCSM_INPUT, --csmdata=CCSM_INPUT + Location of CCSM input data + -m MYMACHINE, --machine=MYMACHINE + Machine, valid CESM script machine (-m list to list valid + machines) + -s MYSITE, --site=MYSITE + Site-code to run, FLUXNET code or CLM1PT name (-s list to list + valid names) + + Configure and Run Options: + -c MYCOMPSET, --compset=MYCOMPSET + Compset for CCSM simulation (Must be a valid 'I' compset [other + than IG compsets], use -c list to list valid compsets) + --coldstart Do a coldstart with arbitrary initial conditions + --caseidprefix=MYCASEID + Unique identifier to include as a prefix to the case name + --cesm_root=BASE_CESM + Root CESM directory (top level directory with models and scripts + subdirs) + --debug Flag to turn on debug mode so won't run, but display what would + happen + --finidat=FINIDAT Name of finidat initial conditions file to start CLM from + --list List all valid: sites, compsets, and machines + --namelist=NAMELIST + List of namelist items to add to CLM namelist (example: + --namelist="hist_fincl1='TG',hist_nhtfrq=-1" + --QIAN_tower_yrs Use the QIAN forcing data year that correspond to the tower + years + --rmold Remove the old case directory before starting + --run_n=MYRUN_N Number of time units to run simulation + --run_units=MYRUN_UNITS + Time units to run simulation (steps,days,years, etc.) + --quiet Print minimul information on what the script is doing + --sitegroupname=SITEGROUP + Name of the group of sites to search for you selected site in + (look for prefix group names in the PTCLM_sitedata directory) + --stdurbpt If you want to setup for standard urban namelist settings + --useQIAN use QIAN input forcing data instead of tower site meterology data + --verbose Print out extra information on what the script is doing + + Input data generation options: + These are options having to do with generation of input datasets. Note: When + running for supported CLM1PT single-point datasets you can NOT generate new + datasets. For supported CLM1PT single-point datasets, you MUST run with the + following settings: --nopointdata And you must NOT set any of these: --soilgrid + --pftgrid --owritesrf + + --nopointdata Do NOT make point data (use data already created) + --owritesrf Overwrite the existing surface datasets if they exist (normally + do NOT recreate them) + --pftgrid Use pft information from global gridded file (rather than site + data) + --soilgrid Use soil information from global gridded file (rather than site + data) + + Main Script Version Id: $Id: PTCLM.py 47576 2013-05-29 19:11:16Z erik $ Scripts URL: $HeadURL: https://svn-ccsm-models.cgd.ucar.edu/PTCLM/trunk_tags/PTCLM1_130529/PTCLM.py $: + +Here we give a simple example of using PTCLM1 for a straightforward case of running at the US-UMB Fluxnet site on yellowstone where we already have the meteorology data on the machine. +Note, see `the Section called Converting AmeriFlux Data for use by PTCLM `_ for permission information to use this data. + +Example 6-1. Example of running PTCLM1 for US-UMB on yellowstone +---------------------------------------------------------------- + +:: + + > setenv CSMDATA $CESMDATAROOT/inputdata + > setenv MYCSMDATA $HOME/inputdata + > setenv SITE US-UMB + > setenv MYMACH yellowstone_intel + > setenv MYCASE testPTCLM + # First link the standard input files to a location you have write access + > cd scripts + > ./link_dirtree $CSMDATA $MYCSMDATA + + # Next build all of the clm tools you will need + > cd ../models/lnd/clm/tools/clm4_5/mksurfdata_map + > gmake + > gmake clean + > cd ../../../../../../tools/mapping/gen_domain_files/src + > ../../../../scripts/ccsm_utils/Machines/configure -mach yellowstone -compiler intel + > gmake + > gmake clean + # next run PTCLM (NOTE -- MAKE SURE python IS IN YOUR PATH) + > cd ../../../../../scripts/ccsm_utils/Tools/lnd/clm/PTCLM + > ./PTCLM.py -m $MYMACH --case=$MYCASE --site=$SITE --csmdata=$MYCSMDATA --aerdepgrid --ndepgrid + # NOTE: we use --aerdepgrid --ndepgrid so that you use the global + # aerosol and Nitrogen deposition files rather than site-specific ones. + > cd ../../../../../$MYCASE + # Finally setup, build, and run the case as normal + diff --git a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst new file mode 100644 index 0000000000..e9a887e89c --- /dev/null +++ b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst @@ -0,0 +1,70 @@ +.. _ptclm-examples: + +========================= + Examples of using PTCLM +========================= + +Now let's give a few more complex examples using some of the options we have discussed above. + +In this first example, we'll demonstrate using a supported single point dataset, which then requires using the "nopointdata". We'll also demonstrate the compset option, "stdurbpt" and "caseidprefix" options. + +Example: Running PTCLM for the Mexicocity supported single point dataset +------------------------------------------------------------------------ +:: + + > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + > ./PTCLM.py -m yellowstone_intel -s 1x1_mexicocityMEX -d $CSMDATA --nopointdata \ + --stdurbpt -c ICRUCLM45 --caseidprefix `pwd`/myPTCLMcases/site + > cd myPTCLMcases/site_1x1_mexicocityMEX_I + > ./cesm_setup + # Now build and run normally + > ./site_1x1_mexicocityMEX_I.build + # Here we show running interactively + > ./site_1x1_mexicocityMEX_I.run + +Now, let's demonstrate using a different group list, doing a spinup, running with Qian global forcing data, but using tower years to set the years to run over. This uses the options: sitegroupname, useQIAN, and QIANtower_years. + +Example: Running PTCLM for a spinup simulation with Qian data for tower years. +------------------------------------------------------------------------------ +:: + + > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + > ./PTCLM.py -m yellowstone_intel -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux --useQIAN --QIAN_tower_yrs + > cd ../../../../../US-Ha1_ICRUCLM45BGC_QIAN + > ./cesm_setup + # Now build and run normally + > ./US-Ha1_ICRUCLM45BGC_QIAN.build + # Here we show running interactively + > ./US-Ha1_ICRUCLM45BGC_QIAN.run + ``` + +Finally, let's demonstrate using a generic machine (which then requires the scratchroot option), using the global grid for PFT and soil types, and setting the run length to two months. + +Example: Running PTCLM on a user-defined machine with global PFT and soil types dataset +--------------------------------------------------------------------------------------- +:: + + > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + # Note, see the the Section called Converting AmeriFlux Data for use by PTCLM with permission information + # to use the US-UMB data. + > ./PTCLM.py -m userdefined_intel -s US-UMB -d $CSMDATA --pftgrid --soilgrid \ + --scratchroot $HOME --run_n 2 --run_units nmonths + > cd ../../../../../US-UMB_ICRUCLM45BGC + # If userdefined is NOT set up for you Uncomment the following and set OS, NTASKS_PER_NODE, TMPDIR + # > ./xmlchange OS=$OS,MAX_TASKS_PER_NODE=$NTASKS_PER_NODE,MPILIB=mpi-serial + # > ./xmlchange RUNDIR=$TMPDIR/$USER/\$CASE/run,DIN_LOC_ROOT=$CSMDATA,COMPILER=intel + # > ./xmlchange EXEROOT=$TMPDIR/$USER/\$CASE + > ./cesm_setup + # Now build + > ./US-UMB_ICRUCLM45BGC.userdefined_intel.build + # To get the files from the svn server... + # First list the files from the streams text file + > ../ccsm_utils/Tools/listfilesin_streams \ + -t $HOME/US-UMB_ICRUCLM45BGC/run/clm1PT.1x1pt_US-UMB.stream.txt -l \ + > Buildconf/datm.input_data_list + # And now run the script to export data to your machine + > ../ccsm_utils/Tools/check_input_data -export + # Here we show running interactively + > ./US-UMB_ICRUCLM45BGC.userdefined_intel.run + +.. warning: Because of Bug 1364, when running this case as above we get a floating point error after reaching time-step 124 for the example exactly as above. Other machines or compilers probably won't have this problem. See the `models/lnd/clm/doc/KnownBugs `_ file for more information on this problem. diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst new file mode 100644 index 0000000000..b644337239 --- /dev/null +++ b/doc/source/users_guide/running-PTCLM/using-ptclm.rst @@ -0,0 +1,222 @@ +.. _using-ptclm.rst: + +************************** +Using PTCLM +************************** + +There are three types of options to PTCLM1: required, setup/run-time, and dataset generation options. +The three required options are the three settings that MUST be specified for PTCLM to work at all. The other settings have default values that will default to something useful. The setup/run-time options control how the simulation will be setup and run. The dataset generation options control the generation of datasets needed when PTCLM is run. Most options use a double dash "--" "longname" such as "--list", but the most common options also have a short-name with a single dash (such as -m instead of --machine). + +The required options to PTCLM are: inputdata directory (-d), machine (-m) and site-name (-s). +Inputdata directory is the directory where you have the CESM inputdata files, you need to have write access to this directory, so if you are running on a machine that you do NOT have write access to the standard inputdata location (such as NCAR yellowstone or LBNL hopper) you need to link the standard files to a location you do have control over. We recommend using the ``scripts/link_dirtree`` tool to do that. "machine" is the scripts name for the machine/compiler you will be using for your case. And finally site-name is the name of the site that you want to run for. Site-name can either be a valid supported dataset name or a Fluxnet site name from the list of sites you are running on (see the --sitegroupname for more information about the site lists). + +After PTCLM is run a case directory where you can then setup, build and run your CESM case as normal. +It also creates a ``README.PTCLM`` in that directory that documents the commandline options to PTCLM that were used to create it. + +After "help" the "list" option is one of the most useful options for getting help on using PTCLM. +This option gives you information about some of the other options to PTCLM. To get a list of the machine, sites, and compsets that can be used for PTCLM use the "--list" option as follows. +:: + + > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + > ./PTCLM.py --list + +The output to the above command is as follows: +:: + + /bin/sh: line 1: PTCLM.py: command not found + +Steps in running PTCLM +========================= + +1. Setup Inputdata directory with write access (use link_dirtree script) + + You need to setup an inputdata directory where you have write access to it. + Normally, for NCAR machines the data is on an inputdata where the user does NOT have write access to it. + A way that you can get around this is to use the **link_dirtree** script to create softlinks from the normal location to a location you have write access to. + So for example on yellowstone: + :: + + > setenv CSMDATA $CESMDATAROOT/inputdata + > setenv MYCSMDATA $HOME/inputdata + > mkdir $MYCSMDATA + > cd scripts + > ./link_dirtree $CSMDATA $MYCSMDATA + + See `the Section called Managing Your Own Data-files in Chapter 3 `_ for more information on this. + +2. Build the CLM tools + Next you need to make sure all the CLM FORTRAN tools are built. + :: + + > cd models/lnd/clm/tools/clm4_5/mksurfdata_map + > gmake + > gmake clean + > cd ../../../../../../tools/mapping/gen_domain_files/src + > ../../../../scripts/ccsm_utils/Machines/configure -mach yellowstone -compiler intel + > gmake + > gmake clean + +3. Run PTCLM + Next you actually run PTCLM1 which does the different things listed below: + + a. PTCLM names your case based on your input + :: + + [Prefix_]SiteCode_Compset[_QIAN] + + Where: + ``Prefix`` is from the caseidprefix option (or blank if not used). + + ``SiteCode`` is the site name you entered with the -s option. + + ``Compset`` is the compset name you entered with the -c option. + + ``_QIAN`` is part of the name only if the useQIAN is used. + + For example, the casename for the following will be: + :: + + > cd scripts + > ./PTCLM.py -m yellowstone_intel -s US-UMB -d $MYCSMDATA -c ICRUCLM45BGC --use QIAN "US-UMB_I_2000_CN_QIAN" + + b. PTCLM creates datasets for you + It will populate $MYCSMDATA with new datasets it creates using the CLM tools. + + c. If a transient compset and PTCLM1 finds a _dynpftdata.txt file + If you are running a transient compset (such as the "I_1850-2000_CN" compset) AND you there is a file in the PTCLM_sitedata directory under the PTCLM directory called $SITE_dynpftdata.txt it will use this file for the land-use changes. + Otherwise it will leave land-use constant, unless you use the pftgrid option so it uses the global dataset for landuse changes. + See the Section called Dynamic Land-Use Change Files for use by PTCLM for more information on this. + There is a sample transient dataset called US-Ha1_dynpftdata.txt. + Transient compsets, are compsets that create transient land-use change and forcing conditions such as: 'I_1850-2000', 'I_1850-2000_CN', 'I_RCP8.5_CN', 'I_RCP6.0_CN', 'I_RCP4.5_CN', or 'I_RCP2.6_CN'. + + d. PTCLM creates a pft-physiology for you + PTCLM1 will create a local copy of the pft-physiology specific for your site that you could then customize with changes specific for that site. + + e. PTCLM creates a README.PTCLM for you + PTCLM1 will create a simple text file with the command line for it in a file called README.PTCLM in the case directory it creates for you. + +4. Customize, setup, build and run case as normal + You then customize your case as you would normally. See the Chapter 1 chapter for more information on doing this. + +PTCLM options +========================= + +Next we discuss the setup and run-time options, dividing them up into setup, initial condition (IC), and run-time options. + +Configure options include: + +- --compset=MYCOMPSET +- --caseidprefix=MYCASEID +- --cesm_root=BASE_CESM +- --namelist=NAMELIST +- --rmold +- --scratchroot=SCRATCHROOT +- --sitegroupname=SITEGROUP +- --QIAN_tower_yrs +- --useQIAN + +``--compset`` + The "-c" option is the most commonly used option after the required options, as it specifies the CESM scripts component set to use with PTCLM1. + The default compset is the "ICN" compset with CN on for present day conditions. + +``--caseidprefix`` + This option gives a prefix to include in the casename when the case is created, in case you want to customize your casenames a bit. + By default, casenames are figured out based on the other options. The argument to this option can either be a name to prefix casenames with and/or a pathname to include. + Hence, if you want cases to appear in a specific directory you can give the pathname to that directory with this option. + +``--cesm_root`` + This option is for running PTCLM1 with a different root directory to CESM than the version PTCLM exists in. Normally you do NOT need to use this option. + +``--namelist`` + This option adds any items given into the CLM user_nl_clm namelist. This allows you to add customizations to the namelist before the clm.buildnml.csh file is created for the case. + +``--rmold`` + This option will remove an old case directory of the same name if one exists. Otherwise, if an old case directory already exists and you try to run PTCLM it will return with an error. + +``--scratchroot`` + This option is ONLY valid when using one of the generic machines (the -m option). This passed onto **create_newcase** and gives the location where cases will be built and run. + +``--sitegroupname`` + In the PTCLM directory there is a subdirectory "PTCLM_sitedata" that contains files with the site, PFT and soil data information for groups of sites. + These site groups are all separate ASCII files with the same prefix followed by a "_*data.txt" name. See `the Section called PTCLM Group Site Lists `_ for more information on these files. By default we have provided three different valid group names: + +EXAMPLE +------- +AmeriFlux + +Fluxnet-Canada + +The EXAMPLE is the group used by default and ONLY includes the US-UMB site as that is the only site we have data provided for. +The other two site groups include the site information for all of both the AmeriFlux and Fluxnet-Canada sites. +You can use the "sitegroupname" option to use one of the other lists, or you can create your own lists using the EXAMPLE file as an example. +Your list of sites could be real world locations or could be theoretical "virtual" sites given to exercise CLM on differing biomes for example. +Note, see `the Section called Converting AmeriFlux Data for use by PTCLM `_ with permission information to use the US-UMB data. + +``--useQIAN`` + This option says to use the standard CLM global Qian T62 atmospheric forcing rather than any tower site forcing data available. Otherwise, PTCLM will try to find tower forcing data for the specific site entered. + +``--QIAN_tower_yrs`` + This option is used with the "useQIAN" option to set the years to cycle over for the Qian data. In this case Qian atmospheric forcing will be used, but the simulation will run over the same years that tower site is available for this site. + +**IC options include:** + +- --coldstart +- --finidat=FINIDAT + +The coldstart option says to startup with OUT an initial condition file, while the finidat option explicitly gives the initial condition file to use. Obviously, the coldstart and finidat options can NOT be used together. + +``--coldstart`` + This option ensures that a cold-start will be done with arbitrary initial conditions. + +``--finidat`` + This option sets the initial condition file to startup the simulation from. + +**Run-time options include:** + +- --debug +- --run_n=MYRUN_N +- --run_units=MYRUN_UNITS +- --stdurbpt +- --debug + +This option tells PTCLM to echo what it would do if it were run, but NOT actually run anything. So it will show you the dataset creation commands it would use. It does however, run **create_newcase**, but then it only displays the **xmlchange** commands and changes that it would do. Also note that if you give the "--rmold" option it won't delete the case directory beforehand. Primarily this is intended for debugging the operation of PTCLM. + +``--run_n`` + This option along with run_units is used to set the length for the simulation. "run_n" is the number of units to use. The default run length depends on the site, compset, and configuration. + +``--run_units`` + This option is the units of time to use for the length of the simulation. It is used along with "run_n" to set the length of the simulation. The default run length depends on the site, compset, and configuration. + +``--stdurbpt`` + This option turns on the "stdurbpt_pd" use-case for CLM_NML_USE_CASE. This option can NOT be used for compsets that set the use-case to something besides present-day. + +**The dataset generation options are:** + +- --pftgrid +- --soilgrid +- --nopointdata +- --owritesrfaer + +The options that with a "grid" suffix all mean to create datasets using the global gridded information rather than using the site specific point data. By default the site specific point data is used. The "nopointdata" and "owritesrfaer" options have to do with file creation. + +Because supported single-point datasets already have the data created for them, you MUST use the "nopointdata" and "ndepgrid" options when you are using a supported single-point site. You must use "ndepgrid" even for a compset without CN. You also can NOT use the options: "soilgrid", "pftgrid", "aerdepgrid", or "owritesrfaer". + +``--pftgrid`` + This option says to use the PFT values provided on the global dataset rather than using the specific site based values from the PTCLM_sitedata/\*_pftdata.txt file when creating the surface dataset. + This option must NOT be used when you you are using a site that is a supported single point dataset. + +``--soilgrid`` + This option says to use the soil values provided on the global dataset rather than using the specific site based values from the PTCLM_sitedata/\*_soildata.txt file when creating the surface dataset. + This option must NOT be used when you you are using a site that is a supported single point dataset. + +``--nopointdata`` + This option says to NOT create any input datasets -- assume this step has already been done. + If datasets weren't already created, your case will fail when you try to run it. + In general the first time you run PTCLM for a new site you want it to generate new datasets, but the next time and future times you want to use this option so that it doesn't waste a lot of time rebuilding datasets over again. + + .. note:: This option is required when you you are using a site that is a supported single point dataset. + +``--owritesrfaer`` + This option says to overwrite any surface and/or aerosol deposition datasets that were already created. + Otherwise, the creation of these files will be skipped if a file is already found (but it WILL create files if they don't exist). + This option must NOT be used when you you are using a site that is a supported single point dataset. diff --git a/doc/source/users_guide/running-single-points/index.rst b/doc/source/users_guide/running-single-points/index.rst new file mode 100644 index 0000000000..2c4ea71bdb --- /dev/null +++ b/doc/source/users_guide/running-single-points/index.rst @@ -0,0 +1,18 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _running-single-points: + +##################################### +Running Single Point Regional Cases +##################################### + +.. toctree:: + :maxdepth: 2 + + single-point-and-regional-grid-configurations.rst + running-pts_mode-configurations.rst + running-single-point-configurations.rst + diff --git a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst new file mode 100644 index 0000000000..56d70b1d7d --- /dev/null +++ b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst @@ -0,0 +1,40 @@ +.. _pts_mode: + +**************************************************** +Running a single point using global data - PTS_MODE +**************************************************** + +``PTS_MODE`` enables you to run the model using global datasets, but just picking a single point from those datasets and operating on it. +It can be a very quick way to do fast simulations and get a quick turnaround. + +To setup a ``PTS_MODE`` simulation you use the "-pts_lat" and "-pts_lon" arguments to **create_newcase** to give the latitude and longitude of the point you want to simulate for (the code will pick the point on the global grid nearest to the point you give. Here's an example to setup a simulation for the nearest point at 2-degree resolution to Boulder Colorado. +:: + + > cd scripts + > ./create_newcase -case testPTS_MODE -res f19_g16 -compset I1850CRUCLM45BGC -pts_lat 40.0 -pts_lon -105 + > cd testPTS_MODE + + # We make sure the model will start up cold rather than using initial conditions + > ./xmlchange CLM_FORCE_COLDSTART=on,RUN_TYPE=startup + +Then setup, build and run as normal. We make sure initial conditions are NOT used since ``PTS_MODE`` currently CAN NOT run with initial conditions. + +.. note:: By default it sets up to run with MPILIB=mpi-serial (in the env_build.xml file) turned on, which allows you to run the model interactively. On some machines this mode is NOT supported and you may need to change it to FALSE before you are able to build. + +.. warning:: ``PTS_MODE`` currently does NOT restart nor is it able to startup from global initial condition files. See bugs "1017 and 1025" in the `models/lnd/clm/doc/KnownLimitationss `_ file. + +.. note:: You can change the point you are simulating for at run-time by changing the values of ``PTS_LAT`` and ``PTS_LON`` in the ``env_run.xml`` file. + +================================== + Running on in a single processor +================================== + +Note, that when running with ``PTS_MODE`` the number of processors is automatically set to one. +When running a single grid point you can only use a single processor. +You might also want to set the ``env_build.xml`` variable: ``MPILIB=mpi-serial`` to ``TRUE`` so that you can also run interactively without having to use MPI to start up your job. + +On many machines, batch queues have a minimum number of nodes or processors that can be used. +On these machines you may have to change the queue and possibly the time-limits of the job, to get it to run in the batch queue. +On the NCAR machine, yellowstone, this is done for you automatically, and the "caldera" queue is used for such single-processor simulations. +Another way to get around this problem is to run the job interactively using ``MPILIB=mpi-serial`` so that you don't submit the job to the batch queue. +For single point mode you also may want to consider using a smaller workstation or cluster, rather than a super-computer, because you can't take advantage of the multi-processing power of the super-computer anyway. diff --git a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst new file mode 100644 index 0000000000..3445b0cab7 --- /dev/null +++ b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst @@ -0,0 +1,218 @@ +.. _running-single-point-datasets: + +****************************************** + Running Single Point Configurations +****************************************** + +In addition to ``PTS_MODE``, CLM supports running using single-point or regional datasets that are customized to a particular region. +CLM supports a a small number of out-of-the-box single-point and regional datasets. +However, users can create their own dataset. + +To get the list of supported dataset resolutions do this: +:: + + > cd models/lnd/clm/doc + > ../bld/build-namelist -res list + + +Which results in the following: +:: + + CLM build-namelist - valid values for res (Horizontal resolutions + Note: 0.1x0.1, 0.5x0.5, 5x5min, 10x10min, 3x3min and 0.33x0.33 are only used for CLM tools): + Values: default 512x1024 360x720cru 128x256 64x128 48x96 32x64 8x16 94x192 \ + 0.23x0.31 0.47x0.63 0.9x1.25 1.9x2.5 2.5x3.33 4x5 10x15 5x5_amazon 1x1_tropicAtl 1x1_camdenNJ \ + 1x1_vancouverCAN 1x1_mexicocityMEX 1x1_asphaltjungleNJ 1x1_brazil 1x1_urbanc_alpha 1x1_numaIA \ + 1x1_smallvilleIA 0.1x0.1 0.5x0.5 3x3min 5x5min 10x10min 0.33x0.33 ne4np4 ne16np4 ne30np4 ne60np4 \ + ne120np4 ne240np4 wus12 us20 + Default = 1.9x2.5 + (NOTE: resolution and mask and other settings may influence what the default is) + +The resolution names that have an underscore in them ("_") are all single-point or regional resolutions. + +To run for the Brazil test site do the following: + +Example: Running CLM over a single-point test site in Brazil with the default Qian atmosphere data forcing. +-------------------------------------------------------------------------------------------------------------------------- +:: + + > cd scripts + > set SITE=1x1_brazil + > ./create_newcase -case testSPDATASET -res $SITE -compset I + > cd testSPDATASET + +Then setup, build and run normally. + +Then to run for the urban Mexico City Mexico test site that also has atmosphere forcing data, but to run it with the Qian forcing data, but over the period for which it's own forcing data is provided do the following: + +Example: Running CLM over the single-point of Mexicocity Mexico with the default Qian atmosphere data forcing. +------------------------------------------------------------------------------------------------------------------------- +:: + + > cd scripts + # Set a variable to the site you want to use (as it's used several times below) + > set SITE=1x1_mexicocityMEX + > ./create_newcase -case testSPDATASET -res $SITE -compset I + > cd testSPDATASET + # Set DATM prescribed aerosols to single-point dataset + # Will then use the dataset with just the point for this $SITE + > ./xmlchange DATM_PRESAERO=pt1_pt1 + +Then setup, build and run normally. + +**Important:** Just like PTS_MODE above, By default it sets up to run with ``MPILIB=mpi-serial`` (in the ``env_build.xml`` file) turned on, which allows you to run the model interactively. On some machines this mode is NOT supported and you may need to change it to FALSE before you are able to build. + +.. warning:: See `the Section called Warning about Running with a Single-Processor on a Batch Machine `_ for a warning about running single-point jobs on batch machines. + +.. note:: When running a ``pt1_pt1`` resolution the number of processors is automatically set to one. When running a single grid point you can only use a single processor. You might also want to set the ``env_build.xml`` variable: ``MPILIB=mpi-serial`` to TRUE so that you can also run interactively without having to use mpi to start up your job. + +Using Supported Single-point Datasets that have their own Atmospheric Forcing +================================================================================ + +Of the supported single-point datasets we have three that also have atmospheric forcing data that go with them: Mexico City (Mexico), Vancouver, (Canada, British Columbia), and ``urbanc_alpha`` (test data for an Urban inter-comparison project). +Mexico city and Vancouver also have "#ifdef" in the source code for them to work with modified urban data parameters that are particular to these locations. +They can be turned on by using the ``CLM_CONFIG_OPTS env_build.xml`` variable to set the "-sitespf_pt" option in the CLM **configure**. +To turn on the atmospheric forcing for these datasets, you set the ``env_run.xml DATM_MODE`` variable to ``CLM1PT``, and then the atmospheric forcing datasets will be used for the point picked. + +When running with datasets that have their own atmospheric forcing you need to be careful to run over the period that data is available. +If you have at least one year of forcing it will cycle over the available data over and over again no matter how long of a simulation you run. +However, if you have less than a years worth of data (or if the start date doesn't start at the beginning of the year, or the end date doesn't end at the end of the year) then you won't be able to run over anything but the data extent. +In this case you will need to carefully set the ``RUN_STARTDATE``, ``START_TOD`` and ``STOP_N/STOP_OPTION`` variables for your case to run over the entire time extent of your data. +For the supported data points, these values are in the XML database and you can use the **queryDefaultNamelist.pl** script to query the values and set them for your case (they are set for the three urban test cases: Mexicocity, Vancouver, and urbanc_alpha). + +In the example below we will show how to do this for the Vancouver, Canada point. + +Example: Running CLM over the single-point of Vancouver Canada with supplied atmospheric forcing data for Vancouver. +------------------------------------------------------------------------------------------------------------------------- +:: + + > cd scripts + + # Set a variable to the site you want to use (as it's used several times below) + > set SITE=1x1_vancouverCAN + + # Create a case at the single-point resolutions with their forcing + > ./create_newcase -case testSPDATASETnAtmForcing -res $SITE -compset I1PTCLM45 + > cd testSPDATASETnAtmForcing + + # Set namelist options for urban test site + > ./xmlchange CLM_NML_USE_CASE=stdurbpt_pd + + # Figure out the start and end date for this dataset + # You can do this by examining the datafile. + > set STOP_N=330 + > set START_YEAR=1992 + > set STARTDATE=${START_YEAR}-08-12 + > @ NDAYS = $STOP_N / 24 + > ./xmlchange RUN_STARTDATE=$STARTDATE,STOP_N=$STOP_N,STOP_OPTION=nsteps + + # Set the User namelist to set the output frequencies of the history files + # Setting the stdurbpt use-case option create three history file streams + # The frequencies and number of time-samples needs to be set + > cat << EOF > user_nl_clm + hist_mfilt = $NDAYS,$STOP_N,$STOP_N + hist_nhtfrq = -1,1,1 + EOF + + # Set DATM prescribed aerosols to single-point dataset + # Will then use the dataset with just the point for this site + > ./xmlchange DATM_PRESAERO=pt1_pt1 + > ./case.setup + + +.. warning:: If you don't set the start-year and run-length carefully as shown above the model will abort with a "dtlimit error" in the atmosphere model (see bug 1110 in the `models/lnd/clm/doc/KnownLimitationss `_ file for documentation on this). Since, the forcing data for this site (and the MexicoCity site) is less than a year, the model won't be able to run for a full year. The ``1x1_urbanc_alpha`` site has data for more than a full year, but neither year is complete hence, it has the same problem (see the problem for this site above). + +.. note:: Just like ``PTS_MODE`` above, By default it sets up to run with ``MPILIB=mpi-serial`` (in the env_build.xml file) turned on, which allows you to run the model interactively. + +.. note:: When running a ``pt1_pt1`` resolution the number of processors is automatically set to one. When running a single grid point you can only use a single processor. You might also want to set the ``env_build.xml`` variable: ``MPILIB=mpi-serial`` to ``TRUE`` so that you can also run interactively without having to use mpi to start up your job. + + +Creating your own single-point dataset +=================================================== + +The following provides an example of setting up a case using ``CLM_USRDAT_NAME`` where you rename the files according to the ``CLM_USRDAT_NAME`` convention. +We have an example of such datafiles in the repository for a specific region over Alaska (actually just a sub-set of the global f19 grid). + +Example: Using CLM_USRDAT_NAME to run a simulation using user datasets for a specific region over Alaska +----------------------------------------------------------------------------------------------------------------------- +:: + + > cd scripts + > ./create_newcase -case my_userdataset_test -res CLM_USRDAT -compset ICRUCLM45 + > cd my_userdataset_test/ + > set GRIDNAME=13x12pt_f19_alaskaUSA + > set LMASK=gx1v6 + > ./xmlchange CLM_USRDAT_NAME=$GRIDNAME,CLM_BLDNML_OPTS="-mask $LMASK" + > ./xmlchange ATM_DOMAIN_FILE=domain.lnd.${GRIDNAME}_$LMASK.nc + > ./xmlchange LND_DOMAIN_FILE=domain.lnd.${GRIDNAME}_$LMASK.nc + + # Make sure the file exists in your $CSMDATA or else use svn to download it there + > ls $CSMDATA/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr2000.nc + + # If it doesn't exist, comment out the following... + #> setenv SVN_INP_URL https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/ + #> svn export $SVN_INP_URL/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr2000.nc $CSMDATA/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr2000.nc + > ./case.setup + +The first step is to create the domain and surface datasets using the process outlined in `the Section called The File Creation Process in Chapter 2 `_. Below we show an example of the process. + +Example: Creating a surface dataset for a single point +--------------------------------------------------------------------- +:: + + # set the GRIDNAME and creation date that will be used later + > setenv GRIDNAME 1x1_boulderCO + > setenv CDATE `date +%y%m%d` + # Create the SCRIP grid file for the location and create a unity mapping file for it. + > cd models/lnd/clm/tools/shared/mkmapdata + > ./mknoocnmap.pl -p 40,255 -n $GRIDNAME + # Set pointer to MAPFILE just created that will be used later + > setenv MAPFILE `pwd`/map_${GRIDNAME}_noocean_to_${GRIDNAME}_nomask_aave_da_${CDATE}.nc + # create the mapping files needed by mksurfdata_map. + > cd ../../shared/mkmapdata + > setenv GRIDFILE ../mkmapgrids/SCRIPgrid_${GRIDNAME}_nomask_${CDATE}.nc + > ./mkmapdata.sh -r $GRIDNAME -f $GRIDFILE -t regional + # create the domain file + > cd ../../../../tools/mapping/gen_domain_files/src + > ../../../scripts/ccsm_utils/Machines/configure -mach yellowstone -compiler intel + > gmake + > cd .. + > setenv OCNDOM domain.ocn_noocean.nc + > setenv ATMDOM domain.lnd.{$GRIDNAME}_noocean.nc + > ./gen_domain -m $MAPFILE -o $OCNDOM -l $ATMDOM + # Save the location where the domain file was created + > setenv GENDOM_PATH `pwd` + # Finally create the surface dataset + > cd ../../../../lnd/clm/tools/clm4_5/mksurfdata_map/src + > gmake + > cd .. + > ./mksurfdata.pl -r usrspec -usr_gname $GRIDNAME -usr_gdate $CDATE + +The next step is to create a case that points to the files you created above. We will still use the ``CLM_USRDAT_NAME`` option as a way to get a case setup without having to add the grid to scripts. + +Example: Setting up a case from the single-point surface dataset just created +-------------------------------------------------------------------------------------------- +:: + + # First setup an environment variable that points to the top of the CESM directory. + > setenv CESMROOT + # Next make sure you have a inputdata location that you can write to + # You only need to do this step once, so you won't need to do this in the future + > setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data + > ./link_dirtree $CSMDATA $MYCSMDATA + # Copy the file you created above to your new $MYCSMDATA location following the CLMUSRDAT + # naming convention (leave off the creation date) + > cp $CESMROOT/models/lnd/clm/tools/clm4_5/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ + $MYCSMDATA/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr1850.nc + > cd $CESMROOT/scripts + > ./create_newcase -case my_usernldatasets_test -res CLM_USRDAT -compset I1850CRUCLM45BGC \ + -mach yellowstone_intel + > cd my_usernldatasets_test + > ./xmlchange DIN_LOC_ROOT=$MYCSMDATA + # Set the path to the location of gen_domain set in the creation step above + > ./xmlchange ATM_DOMAIN_PATH=$GENDOM_PATH,LND_DOMAIN_PATH=$GENDOM_PATH + > ./xmlchange ATM_DOMAIN_FILE=$ATMDOM,LND_DOMAIN_FILE=$ATMDOM + > ./xmlchange CLM_USRDAT_NAME=$GRIDNAME + > ./case.setup + +.. note:: With this and previous versions of the model we recommended using ``CLM_USRDAT_NAME`` as a way to identify your own datasets without having to enter them into the XML database. This has two down-sides. First you can't include creation dates in your filenames, which means you can't keep track of different versions by date. It also means you HAVE to rename the files after you created them with **mksurfdata.pl**. And secondly, you have to use **linkdirtree** in order to place the files in a location outside of the usual ``DIN_LOC_ROOT`` (assuming you don't have write access to adding new files to the standard location on the machine you are using). Now, since ``user_nl`` files are supported for ALL model components, and the same domain files are read by both CLM and DATM and set using the envxml variables: ``ATM_DOMAIN_PATH``, ``ATM_DOMAIN_FILE``, ``LND_DOMAIN_PATH``, and ``LND_DOMAIN_FILE`` -- you can use this mechanism (``user_nl_clm`` and ``user_nl_datm`` and those envxml variables) to point to your datasets in any location. In the future we will deprecate ``CLM_USRDAT_NAME`` and recommend ``user_nl_clm`` and ``user_nl_datm`` and the ``DOMAIN`` envxml variables. diff --git a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst new file mode 100644 index 0000000000..a1514768ee --- /dev/null +++ b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst @@ -0,0 +1,51 @@ +.. _single-point-configurations: + +***************************************** +Single and Regional Grid Configurations +***************************************** + +CLM allows you to set up and run cases with a single-point or a local region as well as global resolutions. +This is often useful for running quick cases for testing, evaluating specific vegetation types, or land-units, or running with observed data for a specific site. + +There are three different ways to do this for normal-supported site + +``PTS_MODE`` + runs for a single point using global datasets. + +``CLM_USRDAT_NAME`` + runs using your own datasets (single-point or regional). + +``PTCLM`` + easily setup simulations to run for tower sites.. + +.. note:: ``PTS_MODE`` and ``PTCLM`` only works for a single point, while the other two options can also work for regional datasets as well. + +.. _options-for-single-points: + +========================================= + Choosing the right single point options +========================================= + +Running for a *normal supported site* is a great solution, if one of the supported single-point/regional datasets, is your region of interest (see `the Section called Running Supported Single-point/Regional Datasets `_). +All the datasets are created for you, and you can easily select one and run, out of the box with it using a supported resolution from the top level of the CESM scripts. +The problem is that there is a very limited set of supported datasets. +You can also use this method for your own datasets, but you have to create the datasets, and add them to the XML database in scripts, CLM and to the DATM. This is worthwhile if you want to repeat many multiple cases for a given point or region. + +In general `the Section called Running PTS_MODE configurations `_ is the quick and dirty method that gets you started without having to create datasets -- but has limitations. +It's good for an initial attempt at seeing results for a point of interest, but since you can NOT restart with it, it's usage is limited. +It is the quickest method as you can create a case for it directly from **create_newcase**. Although you can't restart, running a single point is very fast, and you can run for long simulation times even without restarts. + +Next, ``CLM_USRDAT_NAME`` is the best way to setup cases quickly where you have to create your own datasets (see `the Section called Creating your own single-point/regional surface datasets `_). +With this method you don't have to change DATM or add files to the XML database -- but you have to follow a strict naming convention for files. +However, once the files are named and in the proper location, you can easily setup new cases that use these datasets. +This is good for treating all the required datasets as a "group" and for a particular model version. For advanced CLM developers who need to track dataset changes with different model versions you would be best off adding these datasets as supported datasets with the "normal supported datasets" method. + +Lastly *PTCLM* is a great way to easily create datasets, setup simulations and run simulations for tower sites. +It takes advantage of both normal supported site functionality and CLM_USRDAT_NAME internally. +A big advantage to it, is that it's one-stop shopping, it runs tools to create datasets, and runs **create_newcase** and sets the appropriate env variables for you. So you only have to learn how to run one tool, rather than work with many different ones. PTCLM is described in the next chapter `Chapter 6 `_. + +Finally, if you also have meteorology data that you want to force your CLM simulations with you'll need to setup cases as described in `the Section called Running with your own atmosphere forcing `_. +You'll need to create CLM datasets either according to ``CLM_USRDAT_NAME``. +You may also need to modify DATM to use your forcing data. +And you'll need to change your forcing data to be in a format that DATM can use. In the PTCLM chapter `the Section called Converting AmeriFlux Data for use by PTCLM in Chapter 6 `_ section tells you how to use AmeriFlux data for atmospheric forcing. + diff --git a/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst new file mode 100644 index 0000000000..7c8bd313c5 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst @@ -0,0 +1,10 @@ +.. _spinning-up-sp: + +=========================================== + Spinning up the Satellite Phenology Model +=========================================== + +To spin-up the CLMSP model you merely need to run CLMSP for 50 simulation years starting from arbitrary initial conditions. +You then use the final restart file for initial conditions in other simulations. +Because, this is a straight forward operation we will NOT give the details on how to do that here, but leave it as an exercise for the reader. +See the `Example 4-7 `_ as an example of doing this as the last step for CLMCN. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst new file mode 100644 index 0000000000..efb2f6b4aa --- /dev/null +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst @@ -0,0 +1,75 @@ +.. _spinning-up-clm45-bgc: + +====================== + Spinup of CLM4.5-BGC +====================== + +To get the CLM4.5-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. +After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). + +**1. 45_AD_SPINUP** + For the first step of running 1000+ years in "-bgc_spinup on" mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: + +Example:: AD_SPINUP Simulation for CLM4.5-BGC +-------------------------------------------------------- +:: + + > cd scripts + > ./create_newcase -case BGC_spinup -res f19_g16 -compset I1850CRUCLM45BGC -mach yellowstone_intel + > cd BGC_spinup + # Append "-spinup on" to CLM_BLDNML_OPTS + > ./xmlchange CLM_BLDNML_OPTS="-bgc_spinup on" -append + # The following sets CLM_FORCE_COLDSTART to "on", and run-type to startup (you could also use an editor) + > ./xmlchange CLM_FORCE_COLDSTART=on,RUN_TYPE=startup + # Make the output history files only annual, by adding the following to the user_nl_clm namelist + > echo 'hist_nhtfrq = -8760' >> user_nl_clm + # Now setup + > ./cesm_setup -case + # Now build + > ./BGC_spinup.build + # The following sets RESUBMIT to 30 times in env_run.xml (you could also use an editor) + # The following sets STOP_DATE,STOP_N and STOP_OPTION to Jan/1/1001, 20, "nyears" in env_run.xml (you could also use an editor) + > ./xmlchange RESUBMIT=20,STOP_N=50,STOP_OPTION=nyears,STOP_DATE=10010101 + # Now run normally + > ./BGC_spinup.submit + +.. note:: This same procedure works for CLM4.5-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. + +Afterwards save the last restart file from this simulation to use in the next step. + +**2. Final spinup for CLM4.5-BGC** + Next save the last restart file from this step and use it as the "finidat" file to use for one more spinup for at least 200+ years in normal mode. So do the following: + +Example: Final CLMBGC Spinup Simulation for CLM4.5-BGC +------------------------------------------------------------------ +:: + + > cd scripts + > ./create_newcase -case BGC_finalspinup -res f19_g16 -compset I1850CRUCLM45BGC -mach yellowstone_intel + > cd BGC_finalspinup + # Now, Copy the last CLM restart file from the earlier case into your run directory + > cp /ptmp/$LOGIN/archive/BGC_spinup/rest/BGC_spinup.clm*.r*.1002-01-01-00000.nc \ + /glade/scratch/$LOGIN/CN_finalspinup + # Set the runtype to startup + > ./xmlchange RUN_TYPE=startup + # And copy the rpointer files for datm and drv from the earlier case + > cp /glade/scratch/$LOGIN/archive/BGC_spinup/rest/rpointer.atm /ptmp/$LOGIN/CN_finalspinup + > cp /glade/scratch/$LOGIN/archive/BGC_spinup/rest/rpointer.drv /ptmp/$LOGIN/CN_finalspinup + # Set the finidat file to the last restart file saved in previous step + > echo ' finidat = "BGC_spinup.clm2.r.1002-01-01-00000.nc"' > user_nl_clm + # Now setup + > ./cesm_setup + > Now build + > ./BGC_finalspinup.build + # The following sets RESUBMIT to 4 times in env_run.xml (you could also use an editor) + # The following sets STOP_N and STOP_OPTION to 50 and "nyears" in env_run.xml (you could also use an editor) + > ./xmlchange RESUBMIT=4,STOP_OPTION=nyears,STOP_N=50 + > Now run as normal + > ./BGC_finalspinup.submit + +To assess if the model is spunup plot trends of CLMBGC variables of interest. If you see a trend, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. + +.. note:: This same final spinup procedure works for CLM4.5-CN as well, you can typically shorten the spinup time from 200 years to 50 though. + + + diff --git a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst new file mode 100644 index 0000000000..709a1b26a6 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst @@ -0,0 +1,31 @@ +.. _running-with-moar-data: + +======================== + Running with MOAR data +======================== + +Because it takes so long to spinup the CN model (as we just saw previously), if you are doing fully coupled simulations with active atmosphere and ocean, you will want to do the spinup portion of this "offline". +So instead of doing expensive fully coupled simulations for the spinup duration, you run CLM in a very cheap "I" compset using atmospheric forcing from a shorter fully coupled simulation (or a simulation run previously by someone else). + +In this example we will use the ``I1850SPINUPCN compset`` to setup CLM to run with atmospheric forcing from a previous fully coupled simulation with data that is already stored on disk on yellowstone. +There are several simulations that have high frequency data for which we can do this. You can also do this on a machine other than yellowstone, but would need to download the data from the Earth System Grid and change the datapath similar to `Example 4-11 `_. + +Example: Simulation with MOAR Data on yellowstone +------------------------------------------------------------- +:: + + > cd scripts + > ./create_newcase -case MOARforce1850 -res f19_g16 -compset I1850SPINUPCN -mach yellowstone_intel + > cd MOARforce1850 + # The following sets the casename to point to for atm forcing (you could also use an editor) + > ./xmlchange DATM_CPL_CASE=b40.1850.track1.1deg.006a + # The following sets the align year and years to run over for atm forcing + # (you could also use an editor) + > ./xmlchange DATM_CPL_YR_ALIGN=1,DATM_CPL_YR_START=960,DATM_CPL_YR_END=1030 + > ./cesm_setup + # Now build and run as normal + > ./MOARforce1850.build + > ./MOARforce1850.submit + + +.. warning: Because of bug 1339 (see the `models/lnd/clm/doc/KnownBugs `_ file on this) you can't run with 83 or more years of forcing. If you do need to run with more years of forcing, you'll need to address the issue as outlined in the `models/lnd/clm/doc/KnownBugs `_ file. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst new file mode 100644 index 0000000000..7d523f7324 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst @@ -0,0 +1,75 @@ +.. _running-with-previous-simulation-forcing: + +============================================================= + Running with atmospheric forcing from a previous simulation +============================================================= + +Another way that you might want to spinup the model is to run your own simulation for a relatively short period (either a B, E, or F compset) and then use it as forcing for your "I" case later. +By only running 20 to 50 years for the fully coupled case, you'll save a substantial amount of computer time rather than running the entire spinup period with a fully coupled model. + +The first thing we need to do is to run a fully coupled case and save the atmospheric coupling fields on a three hourly basis. In this example, we will run on yellowstone and archive the data to a local disk that we can then use in the next simulation. + +Example: Fully Coupled Simulation to Create Data to Force Next Example Simulation +---------------------------------------------------------------------------------------------- +:: + + > cd scripts + > ./create_newcase -case myBCN1850 -res f09_g16 -compset B1850CN -mach yellowstone_intel + > cd myBCN1850 + > ./cesm_setup + # Set histaux_a2x3hr to .true. in your user_nl_cpl output from the atmosphere model + # will be saved 3 hourly + echo "histaux_a2x3hr=.true." >> user_nl_cpl + # edit the driver code in order to save the correct list of fields (see note below) + > cp ../../models/drv/driver/ccsm_comp_mod.F90 SourceMods/src.cpl + > $EDITOR SourceMods/src.cpl + # Now build + > ./myBCN1850.build + # The following sets the archival disk space (you could also use an editor) + > ./xmlchange DOUT_S_ROOT='/glade/home/$USER/$CASE' + # Make sure files are archived to disk, but NOT to long term storage + # (you could also use an editor) + > ./xmlchange DOUT_S=TRUE,DOUT_L_MS=FALSE + # Set the run length to run a total of 20 years (you could also use an editor) + > ./xmlchange RESUBMIT=9,STOP_OPTION=nyears,STOP_N=2 + # Now run as normal + > ./myBCN1850.submit + +.. warning:: Because of bug 1733 (see the `models/lnd/clm/doc/KnownBugs `_ file on this) you'll need to edit the driver code in order for it to produce the correct list of fields needed to run the model later. + +Now we run an I compset forced with the data from the previous simulation using the ``CPLHIST3HrWx`` option to DATM_MODE. See `the Section called CPLHIST3HrWx mode and it's DATM settings in Chapter 1 `_ for more information on the DATM settings for ``CPLHIST3HrWx`` mode. + +Example: Simulation Forced with Data from the Previous Simulation +------------------------------------------------------------------------------ +:: + + > cd scripts + > ./create_newcase -case frcwmyBCN1850 -res f09_g16 -compset I1850SPINUPCN -mach yellowstone_intel + > cd frcWmyBCN1850 + # The following sets the casename to point to for atm forcing (you could also use an editor) + > ./xmlchange DATM_CPLHIST_CASE="myBCN1850" + # The following sets the align year and years to run over for atm forcing + # (you could also use an editor) + > ./xmlchange DATM_CPLHIST_YR_ALIGN="1",DATM_CPLHIST_YR_START=1,DATM_CPLHIST_YR_END=20 + # Set the strm_datdir in the namelist_defaults_datm.xml + # file to the archival path of the case above in the form of: /glade/home/achive/$USER/$DATM_CPLHIST_CASE/cpl/hist + # NOTE: THIS WILL CHANGE THE PATH FOR ALL I1850SPINUPCN COMPSET CASES MADE AFTER THIS! + > $EDITOR ../../models/atm/datm/bld/namelist_files/namelist_defaults_datm.xml + > ./cesm_setup + # Now build and run as normal + > ./frcwmyBCN1850.build + > ./frcwmyBCN1850.submit + + +.. note:: We did this by editing the "namelist_defaults_datm.xml" which will change the settings for ALL future ``I1850SPINUPCN`` cases you run. You could also do this by editing the path in the resulting streams text files in the CaseDocs directory, and then create a "user\_" streams file with the correct path. This would change the streams file JUST for this case. The steps do it this way are: + +:: + + > ./preview_namelists + > cp CaseDocs/datm.streams.txt.CPLHIST3HrWx.Precip user_datm.streams.txt.CPLHIST3HrWx.Precip + > cp CaseDocs/datm.streams.txt.CPLHIST3HrWx.Solar user_datm.streams.txt.CPLHIST3HrWx.Solar + > cp CaseDocs/datm.streams.txt.CPLHIST3HrWx.nonSolarNonPrecip user_datm.streams.txt.CPLHIST3HrWx.nonSolarNonPrecip + # Change the field to point to the correct directory i.e.: /glade/home/achive/$USER/$DATM_CPLHIST_CASE/cpl/hist + > $EDITOR user_datm.streams.txt.CPLHIST3HrWx.* + > ./preview_namelists + # Then make sure the CaseDocs/datm.streams.txt.CPLHIST3HrWx.* files have the correct path diff --git a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst new file mode 100644 index 0000000000..854450ff12 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst @@ -0,0 +1,138 @@ +.. _running-with-historical-co2-forcing: + +===================================== + Running with historical CO2 forcing +===================================== + +In this case you want to run a simulation with stand-alone CLM responding to changes in CO2 for a historical period. +For this example, we will start with the "I_1850-2000_CN" compset that has transient: land-use, Nitrogen and Aerosol deposition already. +You could also use another compset if you didn't want these other features to be transient. +In order to get CO2 to be transient we need to add a new streams file and add it to the list of streams in the user_nl_datm file. +You also need a NetCDF datafile that datm can read that gives the variation. You could supply your own file, but we have a standard file that is used by CAM for this and our example will make use of this file. + +.. note:: Most everything here has to do with changing datm rather than CLM to allow this to happen. As such the user that wishes to do this should first become more familiar with datm and read the `CESM Data Model User's Guide `_ especially as it pertains to the datm. + +.. warning:: This section documents the process for doing something that is non-standard. There may be errors with the documentation and process, and you may have to do some work before all of this works for you. If that is the case, we recommend that you do further research into understanding the process and the files, as well as understanding the datm and how it works. You may have to read documentation found in the code for datm as well as "csm_share". + +The datm has "streams" files that have rough XML-like syntax and specify the location and file to get data from, as well as information on the variable names and the data locations of the grid points. +The datm expects specific variable names and the datm "maps" the expected variable names from the file to the names expected by datm. +The file we are working with here is a file with a single-point, that covers the entire globe (so the vertices go from -90 to 90 degrees in latitude and 0 to 360 degrees in longitude). +Since it's a single point it's a little easier to work with than datasets that may be at a given horizontal resolution. +The datm also expects that variables will be in certain units, and only expects a limited number of variables so arbitrary fields can NOT be exchanged this way. +However, the process would be similar for datasets that do contain more than one point. + +The three things that are needed: a domain file, a data file, and a streams text file. +The domain file is a CF-compliant NetCDF file that has information on the grid points (latitudes and longitudes for cell-centers and vertices, mask , fraction, and areas). +The datafile is a CF-compliant NetCDF file with the data that will be mapped. +The streams text file is the XML-like file that tells datm how to find the files and how to map the variables datm knows about to the variable names on the NetCDF files. Note, that in our case the domain file and the data file are the same file. In other cases, the domain file may be separate from the data file. + +First we are going to create a case, and we will edit the ``user_nl_datm`` so that we add a CO2 data stream in. +There is a streams text file available in ``models/lnd/clm/doc/UsersGuide/co2_streams.txt``, that includes file with a CO2 time-series from 1765 to 2007. + + +Example: Transient Simulation with Historical CO2 +-------------------------------------------------------------- +:: + + > cd scripts + > ./create_newcase -case DATM_CO2_TSERIES -res f19_g16 -compset I20TRCRUCLM45BGC + > cd DATM_CO2_TSERIES + + # Set CCSM_BGC to CO2A so that CO2 will be passed from atmosphere to land + # Set CLM_CO2_TYPE to diagnostic so that the land will use the value sent from the atmosphere + > ./xmlchange CCSM_BGC=CO2A,CLM_CO2_TYPE=diagnostic + > ./case.setup + + # Create the streams file for CO2 + > cat << EOF >> datm.streams.txt.co2tseries + + + + This is a streams file to pass historical CO2 from datm8 to the other + surface models. It reads in a historical dataset derived from data used + by CAM. The getco2_historical.ncl script in models/lnd/clm2/tools/ncl_scripts + was used to convert the CAM file to a streams compatible format (adding domain + information and making CO2 have latitude/longitude even if only for a single + point. + + + + Input stream description file for historical CO2 reconstruction data + + 04 March 2010: Converted to form that can be used by datm8 by Erik Kluzek + 18 December 2009: Prepared by B. Eaton using data provided by + Jean-Francois Lamarque. All variables except f11 are directly from + PRE2005_MIDYR_CONC.DAT. Data from 1765 to 2007 with 2006/2007 just + a repeat of 2005. + + + CLMNCEP + + + + time time + lonc lon + latc lat + area area + mask mask + + + $CSMDATA/atm/datm7/CO2 + + + fco2_datm_1765-2007_c100614.nc + + + + + CO2 co2diag + + + $CSMDATA/atm/datm7/CO2 + + + fco2_datm_1765-2007_c100614.nc + + + + + + EOF + + # And copy it to the run directory + > cp datm.streams.txt.co2tseries $RUNDIR + + # Run preview namelist so we have the namelist in CaseDocs + > ./preview_namelists + +The first thing we will do is to edit the ``user_nl_datm`` file to add a CO2 file stream in. +To do this we will copy a ``user_nl_datm`` in with the changes needed. The file ``addco2_user_nl_datm.user_nl`` is in ``models/lnd/clm/doc/UsersGuide`` and looks like this... +:: + + dtlimit = 1.5,1.5,1.5,1.5,1.5 + fillalgo = 'nn','nn','nn','nn','nn' + fillmask = 'nomask','nomask','nomask','nomask','nomask' + mapalgo = 'bilinear','bilinear','bilinear','bilinear','nn' + mapmask = 'nomask','nomask','nomask','nomask',nomask' + streams = "datm.streams.txt.CLM_QIAN.Solar 1895 1948 1972 ", "datm.streams.txt.CLM_QIAN.Precip 1895 1948 1972 ", + "datm.streams.txt.CLM_QIAN.TPQW 1895 1948 1972 ", "datm.streams.txt.presaero.trans_1850-2000 1849 1849 2006", + "datm.streams.txt.co2tseries 1766 1766 2005 " + taxmode = 'cycle','cycle','cycle','cycle','extend' + tintalgo = 'coszen','nearest','linear','linear','linear' + +You just copy this into your case directory. But, also compare it to the version in ``CaseDocs`` to make sure the changes are just to add in the new CO2 stream. Check to see that filenames, and start, end and align years are correct. +:: + + > cp ../../models/lnd/clm/doc/UsersGuide/addco2_user_nl_datm.user_nl user_nl_datm + > diff user_nl_datm CaseDocs/datm_atm_in + +Once, you've done that you can build and run your case normally. + +.. warning:: This procedure assumes you are using a ``I20TRCRUCLM45BGC`` compset out of the box, with ``DATM_PRESAERO`` equal to trans_1850-2000. So it assumes standard CLM4.5 CRUNCEP atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here your ``user_nl_datm`` file will need to be adjusted to work with it. + +.. note:: The intent of the ``user_nl_datm`` is to add an extra streams file for CO2 to the end of the streams variable, and other arrays associated with streams (adding mapalgo as a new array with bilinear for everything, but the CO2 file which should be "nn" for nearest neighbor). Other variables should be the same as the other stream values. + +.. warning:: The streams file above is hard-coded for the path of the file on NCAR computers. To use it on an outside machine you'll need to edit the filepath in the streams file to point to the location where you have the file. + +After going through these steps, you will have a case where you have datm reading in an extra streams text file that points to a data file with CO2 data on it that will send that data to the CLM. + diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst new file mode 100644 index 0000000000..af69b010da --- /dev/null +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -0,0 +1,22 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _running-special-cases-section: + +##################################### +Running Special Cases +##################################### + +.. toctree:: + :maxdepth: 2 + + what-is-a-special-case.rst + running-the-prognostic-crop-model.rst + running-with-irrigation.rst + CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst + CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst + CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst + CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst + CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst diff --git a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst new file mode 100644 index 0000000000..31691e721d --- /dev/null +++ b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst @@ -0,0 +1,31 @@ +.. running-prognostic-crop-model: + +=================================== + Running the prognostic crop model +=================================== + +The prognostic crop model is setup to work with CLM4.5-BGC or CLM4.0-CN (with or without DV) for present day conditions and we have surface and initial condition datasets at f19 resolution. +In order to use the initial condition file, we need to set the ``RUN_TYPE`` to startup rather than ``hybrid`` since the compset for f19 sets up to use an initial condition file without crop active. +To activate the crop model you can choose a compset that has "CROP" in the name such as "ICRUCLM45BGCCROP" or simply add "-crop on" to ``CLM_CONFIG_OPTS``. + +Example: Crop Simulation +------------------------------------ +:: + + > cd scripts + > ./create_newcase -case CROP -res f19_g16 -compset I1850CRUCLM45BGC + > cd CROP + + # Append "-crop on" to CLM_CONFIG_OPTS in env_build.xml (you could also use an editor) + > ./xmlchange CLM_CONFIG_OPTS="-crop on" -append + + # Change to startup type so uses spunup initial conditions file for crop if it exists + # By default the model will do a hybrid startup with an initial condition file + # incompatible with the crop surface dataset. + + > ./xmlchange RUN_TYPE=startup + > ./case.setup + + # Now build and run normally + > ./case.build + > ./case.submit diff --git a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst new file mode 100644 index 0000000000..4a39f6ec5f --- /dev/null +++ b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst @@ -0,0 +1,33 @@ +.. running-with-irrigation: + +=================================== + Running with irrigation +=================================== + +In CLM4.5 irrigation can ONLY be used WITH crop. +To turn on irrigation in CLM4.5 we simply add "-irrig on" to ``CLM_BLDNML_OPTS``. +Just as in the crop example we also change ``RUN_TYPE`` to ``startup`` so that we don't use an initial condition file that is incompatible with irrigation. + +Example: Irrigation Simulation +------------------------------------------ +:: + + # Note here we do a CLMSP simulation as that is what has been validated + > cd scripts + > ./create_newcase -case IRRIG -res f19_g16 -compset I + > cd IRRIG + + # Append "-irrig" to CLM_BLDNML_OPTS in env_run.xml (you could also use an editor) + > ./xmlchange CLM_BLDNML_OPTS="-irrig" -append + + # Change to startup type so uses spunup initial conditions file for irrigation if it exists + # By default the model will do a hybrid startup with an initial condition file + # incompatible with the irrigation surface dataset. + > ./xmlchange RUN_TYPE=startup + > ./case.setup + + # Now build and run normally + > ./case.build + > ./case.submit + + diff --git a/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst b/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst new file mode 100644 index 0000000000..32daabafc6 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst @@ -0,0 +1,12 @@ +.. _what is a special case: + +========================= + What is a special case? +========================= + +All of the following special cases cases that take more than one step to do. +The straightforward cases have compsets and/or build-namelist use-cases setup for them or require simple editing of a single-case. +All of the cases here require you to do at least two simulations with different configurations, or require more complex editing of the case (changing the streams files). + +.. note:: The cases in this chapter are more sophisticated and require more technical knowledge and skill than cases in previous chapters. The user should be very familiar with doing simple cases before moving onto the cases described here. + diff --git a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst new file mode 100644 index 0000000000..806d76d966 --- /dev/null +++ b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst @@ -0,0 +1,321 @@ +.. _choosing-a-compset: + +==================== + Choosing a compset +==================== + +When setting up a new case one of the first choices to make is which "component set" (or compset) to use. +The compset refers to which component models are used as well as specific settings for them. +We label the different types of compsets with a different letter of the alphabet from "A" (for all data model) to "X" (for all dead model). +The compsets of interest when working with CLM are the "I" compsets (which contain CLM with a data atmosphere model and a stub ocean, and stub sea-ice models), "E" and "F" compsets (which contain CLM with the active atmosphere model (CAM), prescribed sea-ice model, and a data ocean model), and "B" compsets which have all active components. +Below we go into details on the "I" compsets which emphasize CLM as the only active model, and just mention the two other categories. + +When working with CLM you usually want to start with a relevant "I" compset before moving to the more complex cases that involve other active model components. +The "I" compsets can exercise CLM in a way that is similar to the coupled modes, but with much lower computational cost and faster turnaround times. + +Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) +------------------------------------------------------------------------- + +`Supported CLM Configurations `_ are listed in `Table 1-1 `_ for the Scientifically Supported compsets (have been scientifically validated with long simulations) and in `Table 1-2 `_ for the Functionally Supported compsets (we've only checked that they function). + + +**Scientifically Supported I Compsets:** + ++------------+--------------+-----------+-----------------+----------------+ +| Short Name | Description | Atm. | Compset Alias | Period | +| | | Forcing | Name | | ++============+==============+===========+=================+================+ +| CLM4.5SP | Satellite | CRUNCEP | 1850CRUCLM45 | 1850 | +| | phenology | | | | +| | with new | | | | +| | biogeophys | | | | ++------------+--------------+-----------+-----------------+----------------+ +| CLM4.5SP | New | CRUNCEP | I1850CRUCLM45BGC| 1850 | +| | biogeophys | +-----------------+----------------+ +| | + CENTURY- | | I20TRCRUCLM45BGC| 20th Century | +| | like | | | | +| | vertically | | | | +| | resolved | | | | +| | soil | | | | +| | BGC + CH4 | | | | +| | emissions, | | | | +| | nitrogen | | | | +| | updates | | | | ++------------+--------------+-----------+-----------------+----------------+ +| CLM4.5CN | New | CRUNCEP | I1850CRUCLM45CN | 1850 | +| | biogeophys | | | | +| | + CN soil | | | | +| | BGC, updates | | | | ++------------+--------------+-----------+-----------------+----------------+ +| CLM4SP | As in | Qian | I1850 | 1850 | +| | CCSM4/CESM1 | +-----------------+----------------+ +| | release | | I | 2000 | +| | | +-----------------+----------------+ +| | | | I20TR | 20th Century | ++------------+--------------+-----------+-----------------+----------------+ +| CLM4CN | As in | Qian | I1850CN | 1850 | +| | CCSM4/CESM1 | +-----------------+----------------+ +| | release | | ICN | 2000 | +| | | +-----------------+----------------+ +| | | | I20TRCN | 20th Century | +| | | +-----------------+----------------+ +| | | | IRCP26CN | RCP 2.6 to 2100| +| | | +-----------------+----------------+ +| | | | IRCP45CN | RCP 4.5 to 2100| +| | | +-----------------+----------------+ +| | | | IRCP60CN | RCP 6.0 to 2100| +| | | +-----------------+----------------+ +| | | | IRCP85CN | RCP 8.5 to 2100| ++------------+--------------+-----------+-----------------+----------------+ + +**Functionally Supported I Compsets:** + ++------------+-------------------+-------------------+-----------------+--------+ +| Short Name | Description | Atm. | Compset Alias | Period | +| | | Forcing | Name | | ++============+===================+===================+=================+========+ +| CLM4.5BGC- | ICRUCLM45BGCCROP | New biogeophys + | CRUNCEP | 2000 | +| CROP | | CENTURY-like | | | +| | | vertically | | | +| | | resolved soil | | | +| | | BGC + CH4 | | | +| | | emissions, | | | +| | | nitrogen updates | | | +| | | with prognostic | | | +| | | CROP | | | +| | | | | | ++------------+-------------------+-------------------+-----------------+--------+ +| CLM4.5BGC- | I1850CRUCLM45BGCDV| New biogeophys | CRUNCEP | 1850 | +| DV | | + CENTURY-like | | | +| | | vertically | | | +| | | resolved soil | | | +| | | BGC + CH4 | | | +| | | emissions, | | | +| | | nitrogen updates | | | +| | | with DV | | | +| | | | | | +| | | | | | +| | | | | | ++------------+-------------------+-------------------+-----------------+--------+ +| CLM4.5SP- | ICLM45VIC | Satellite | Qian | 2000 | +| VIC | | phenology with new| | | +| | | biogeophys with | | | +| | | VIC hydrology | | | ++------------+-------------------+-------------------+-----------------+--------+ +|CLM4CN-CROP | ICNCROP | As in CCSM4/CESM1 | Qian | 2000 | +| | | release | | | ++------------+-------------------+-------------------+-----------------+--------+ +|CLM4CN-DV | ICNDV | As in CCSM4/CESM1 | Qian | 1850 | +| | | release | | | ++------------+-------------------+-------------------+-----------------+--------+ + +Here is the entire list of compsets available. +Note that using the "-user_compset" option even more combinations are possible. +In the list below we give the alias name and then the long name which describes each component in parenthesis. +Alias (Long-name with time-period and each component) + +1. ``I`` (2000_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850`` (1850_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CLM45`` (1850_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CLM45BGC`` (1850_DATM%QIA_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CLM45CN`` (1850_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CLM45CNF`` (1850_DATM%QIA_CLM45%CN_SICE_SOCN_RTM%FLOOD_SGLC_SWAV) + +#. ``I1850CN`` (1850_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CRU`` (1850_DATM%CRU_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CRUCLM45`` (1850_DATM%CRU_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CRUCLM45BGC`` (1850_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CRUCLM45BGCDV`` (1850_DATM%CRU_CLM45%BGCDV_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CRUCLM45CN`` (1850_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850CRUCN`` (1850_DATM%CRU_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850SPINUPCLM45BGC`` (1850_DATM%S1850_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1850SPINUPCN`` (1850_DATM%S1850_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1PT`` (2000_DATM%1PT_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I1PTCLM45`` (2000_DATM%1PT_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TR`` (20TR_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCLM45`` (20TR_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCLM45CN`` (20TR_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCN`` (20TR_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCRU`` (20TR_DATM%CRU_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCRUCLM45`` (20TR_DATM%CRU_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCRUCLM45BGC`` (20TR_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCRUCLM45CN`` (20TR_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I20TRCRUCN`` (20TR_DATM%CRU_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I4804`` (4804_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I4804CLM45`` (4804_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I4804CLM45CN`` (4804_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``I4804CN`` (4804_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45`` (2000_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45BGC`` (2000_DATM%QIA_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45BGCCROP`` (2000_DATM%QIA_CLM45%BGC-CROP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45BGCDV`` (2000_DATM%QIA_CLM45%BGCDV_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45BGCDVCROP`` (2000_DATM%QIA_CLM45%BGCDV-CROP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45BGCNoVS`` (2000_DATM%QIA_CLM45%NoVS_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45CN`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45CNCROP`` (2000_DATM%QIA_CLM45%CN-CROP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45CNDV`` (2000_DATM%QIA_CLM45%CNDV_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45CNTEST`` (2003_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV_TEST) + +#. ``ICLM45CRUBGC`` (2000_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45GLCMEC`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV_TEST) + +#. ``ICLM45SNCRFRC`` (2000_DATM%QIA_CLM45%SP-SNCR_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45USUMB`` (2000_DATM%1PT_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%1x1_US-UMB) + +#. ``ICLM45VIC`` (2000_DATM%QIA_CLM45%SP-VIC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICLM45alaskaCN`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%13x12pt_f19_alaskaUSA) + +#. ``ICN`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICNCROP`` (2000_DATM%QIA_CLM40%CN-CROP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICNDV`` (2000_DATM%QIA_CLM40%CNDV_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICNDVCROP`` (2000_DATM%QIA_CLM40%CNDV-CROP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICNTEST`` (2003_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV_TEST) + +#. ``ICRU`` (2000_DATM%CRU_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICRUCLM45`` (2000_DATM%CRU_CLM45_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICRUCLM45BGC`` (2000_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICRUCLM45BGCCROP`` (2000_DATM%CRU_CLM45%BGC-CROP_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICRUCLM45BGCTEST`` (2003_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV_TEST) + +#. ``ICRUCLM45CN`` (2000_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ICRUCN`` (2000_DATM%CRU_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IG`` (2000_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG1850`` (1850_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG1850CLM45`` (1850_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG1850CLM45CN`` (1850_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG1850CN`` (1850_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG20TR`` (20TR_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG20TRCLM45`` (20TR_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG20TRCLM45CN`` (20TR_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG20TRCN`` (20TR_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG4804`` (4804_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG4804CLM45`` (4804_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG4804CLM45CN`` (4804_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IG4804CN`` (4804_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGCLM45`` (2000_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGCLM45CN`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGCN`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGLCMEC`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV_TEST) + +#. ``IGRCP26CLM45CN`` (RCP2_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP26CN`` (RCP2_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP45CLM45CN`` (RCP4_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP45CN`` (RCP4_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP60CLM45CN`` (RCP6_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP60CN`` (RCP6_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP85CLM45CN`` (RCP8_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IGRCP85CN`` (RCP8_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) + +#. ``IRCP26CLM45CN`` (RCP2_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP26CN`` (RCP2_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP45CLM45CN`` (RCP4_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP45CN`` (RCP4_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP60CLM45CN`` (RCP6_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP60CN`` (RCP6_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP85CLM45CN`` (RCP8_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``IRCP85CN`` (RCP8_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ISNCRFRC`` (2000_DATM%QIA_CLM40%SP-SNCR_SICE_SOCN_RTM_SGLC_SWAV) + +#. ``ITEST`` (2003_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV_TEST) + +#. ``ITESTCLM45`` (2003_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV_TEST) + +#. ``IUSUMB`` (2000_DATM%1PT_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%1x1_US-UMB) + +#. ``IalaskaCN`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%13x12pt_f19_alaskaUSA) + +Compsets coupled to active atmosphere with data ocean +----------------------------------------------------- +CAM compsets are compsets that start with "E" or "F" in the name. They are described more fully in the scripts documentation or the CAM documentation. "E" compsets have a slab ocean model while "F" compsets have a data ocean model. + +Fully coupled compsets with fully active ocean, sea-ice, and atmosphere +----------------------------------------------------------------------- +Fully coupled compsets are compsets that start with "B" in the name. They are described more fully in the scripts documentation. + +Conclusion to choosing a compset +-------------------------------- +We've introduced the basic type of compsets that use CLM and given some further details for the "standalone CLM" (or "I" compsets). +The `config_compsets.xml `_ lists all of the compsets and gives a full description of each of them. +In the next section we look into customizing the setup time options for compsets using CLM. diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst new file mode 100644 index 0000000000..ed00d99483 --- /dev/null +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -0,0 +1,688 @@ +.. _configuring-clm: + +******************************* +Customizing CLM's Configuration +******************************* + +The "Creating a Case" section of the `CESM1.2.0 Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. + +For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called there are two steps that take place: + +1. The CLM "**configure**" script is called to setup the build-time configuration for CLM (more information on **configure** is given in `the Section called More information on the CLM configure script `_). The env variables for **configure** are locked after the **$CASE.build** step. So the results of the CLM **configure** are locked after the build has taken place. + +2. The CLM "**build-namelist**" script is called to generate the run-time namelist for CLM (more information on **build-namelist** is given below in `the Section called Definition of Namelist items and their default values `_. + +When customizing your case at the *8cesm_setup** step you are able to modify the process by effecting either one or both of these steps. The CLM "**configure**" and "**build-namelist**" scripts are both available in the "models/lnd/clm/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. + +There are five different types of customization for the configuration that we will discuss: CLM4.5 in CESM1.2.0 build-time options, CLM4.5 in CESM1.2.0 run-time options, User Namelist, other noteworthy CESM1.2.0 configuration items, the CLM **configure** script options, and the CLM **build-namelist** script options. + +Information on all of the script, configuration, build and run items is found under ``scripts/ccsm_utils/Case.template`` in the `config_definition.xml `_ file. + +================================ + CLM Script configuration items +================================ + +Below we list each of the CESM configuration items that are specific to CLM. All of these are available in your: ``env_build.xml`` and ``env_run.xml`` files. +:: + + CLM_CONFIG_OPTS + CLM_BLDNML_OPTS + CLM_NAMELIST_OPTS + CLM_FORCE_COLDSTART + CLM_NML_USE_CASE + CLM_USRDAT_NAME + CLM_CO2_TYPE + +For the precedence of the different options to **build-namelist** see the section on precedence below. + +The first item ``CLM_CONFIG_OPTS`` has to do with customizing the CLM build-time options for your case, the rest all have to do with generating the namelist. + +CLM_CONFIG_OPTS + The option ``CLM_CONFIG_OPTS`` is all about passing command line arguments to the CLM **configure** script. + It is important to note that some compsets, may already put a value into the ``CLM_CONFIG_OPTS`` variable. + You can still add more options to your ``CLM_CONFIG_OPTS`` but make sure you add to what is already there rather than replacing it. + Hence, we recommend using the "-append" option to the xmlchange script. + In `the Section called More information on the CLM configure script `_ below we will go into more details on options that can be customized in the CLM "**configure**" script. + It's also important to note that the **clm.buildnml.csh** script may already invoke certain CLM **configure** options and as such those command line options are NOT going to be available to change at this step (nor would you want to change them). + The options to CLM **configure** are given with the "-help" option which is given in `the Section called More information on the CLM configure script `_. + .. note:: ``CLM_CONFIG_OPTS`` is locked after the **$CASE.build** script is run. If you want to change something in ``CLM_CONFIG_OPTS`` you'll need to clean the build and rerun **$CASE.build**. The other env variables can be changed at run-time so are never locked. + +CLM_NML_USE_CASE + ``CLM_NML_USE_CASE`` is used to set a particular set of conditions that set multiple namelist items, all centering around a particular usage of the model. To list the valid options do the following: + :: + + > cd models/lnd/clm/doc + > ../bld/build-namelist -use_case list + + The output of the above command is: + :: + + CLM build-namelist - use cases: 1850-2100_rcp2.6_glacierMEC_transient 1850-2100_rcp2.6_transient \ + 1850-2100_rcp4.5_glacierMEC_transient 1850-2100_rcp4.5_transient \ + 1850-2100_rcp6_glacierMEC_transient 1850-2100_rcp6_transient \ + 1850-2100_rcp8.5_glacierMEC_transient 1850-2100_rcp8.5_transient 1850_control \ + 1850_glacierMEC_control 2000-2100_rcp8.5_transient 2000_control 2000_glacierMEC_control \ + 20thC_glacierMEC_transient 20thC_transient glacierMEC_pd stdurbpt_pd + Use cases are:... + + 1850-2100_rcp2.6_glacierMEC_transient = Simulate transient land-use, and aerosol deposition changes \ + with historical data from 1850 to 2005 and then with the RCP2.6 scenario from IMAGE + + 1850-2100_rcp2.6_transient = Simulate transient land-use, and aerosol deposition changes with \ + historical data from 1850 to 2005 and then with the RCP2.6 scenario from IMAGE + + 1850-2100_rcp4.5_glacierMEC_transient = Simulate transient land-use, and aerosol deposition changes \ + with historical data from 1850 to 2005 and then with the RCP4.5 scenario from MINICAM + + 1850-2100_rcp4.5_transient = Simulate transient land-use, and aerosol deposition changes with \ + historical data from 1850 to 2005 and then with the RCP4.5 scenario from MINICAM + + 1850-2100_rcp6_glacierMEC_transient = Simulate transient land-use, and aerosol deposition changes \ + with historical data from 1850 to 2005 and then with the RCP6 scenario from AIM + + 1850-2100_rcp6_transient = Simulate transient land-use, and aerosol deposition changes with \ + historical data from 1850 to 2005 and then with the RCP6 scenario from AIM + + 1850-2100_rcp8.5_glacierMEC_transient = Simulate transient land-use, and aerosol deposition changes \ + with historical data from 1850 to 2005 and then with the RCP8.5 scenario from MESSAGE + + 1850-2100_rcp8.5_transient = Simulate transient land-use, and aerosol deposition changes with \ + historical data from 1850 to 2005 and then with the RCP8.5 scenario from MESSAGE + + 1850_control = Conditions to simulate 1850 land-use + 1850_glacierMEC_control = Running an IG case for 1850 conditions with the ice sheet model glimmer + 2000-2100_rcp8.5_transient = Simulate transient land-use, and aerosol deposition changes with \ + historical data from 2000 to 2005 and then with the RCP8.5 scenario from MESSAGE + + 2000_control = Conditions to simulate 2000 land-use + 2000_glacierMEC_control = Running an IG case for 2000 conditions with the ice sheet model glimmer + 20thC_glacierMEC_transient = Simulate transient land-use, and aerosol deposition changes from 1850 \ + to 2005 + 20thC_transient = Simulate transient land-use, and aerosol deposition changes from 1850 to 2005 + glacierMEC_pd = Running an IG case with the ice sheet model glimmer + stdurbpt_pd = Standard Urban Point Namelist Settings + + .. note::See the `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + +CLM_BLDNML_OPTS + The option CLM_BLDNML_OPTS is for passing options to the CLM "build-namelist" script. + As with the CLM "configure" script the CLM clm.buildnml.csh may already invoke certain options and as such those options will NOT be available to be set here. The best way to see what options can be sent to the "build-namelist" script is to do + :: + + > cd models/lnd/clm/bld + > ./build-namelist -help + + Here is the output from the above. + :: + + ./SYNOPSIS + build-namelist [options] + + Create the namelist for CLM + OPTIONS + -[no-]chk_res Also check [do NOT check] to make sure the resolution and + land-mask is valid. + -clm_demand "list" List of variables to require on clm namelist besides the usuals. + "-clm_demand list" to list valid options. + (can include a list member "null" which does nothing) + -clm_startfile "file" CLM restart file to start from. + -clm_start_type "type" Start type of simulation + (default, cold, arb_ic, startup, continue, or branch) + (default=do the default type for this configuration) + (cold=always start with arbitrary initial conditions) + (arb_ic=start with arbitrary initial conditions if + initial conditions don't exist) + (startup=ensure that initial conditions are being used) + -clm_usr_name "name" Dataset resolution/descriptor for personal datasets. + Default: not used + Example: 1x1pt_boulderCO_c090722 to describe location, + number of pts, and date files created + -co2_type "value" Set CO2 the type of CO2 variation to use. + -co2_ppmv "value" Set CO2 concentration to use when co2_type is constant (ppmv). + -config "filepath" Read the given CLM configuration cache file. + Default: "config_cache.xml". + -csmdata "dir" Root directory of CESM input data. + Can also be set by using the CSMDATA environment variable. + -d "directory" Directory where output namelist file will be written + Default: current working directory. + -drydep Produce a drydep_inparm namelist that will go into the + "drv_flds_in" file for the driver to pass dry-deposition to the atm. + Default: -no-drydep + (Note: buildnml.csh copies the file for use by the driver) + -glc_grid "grid" Glacier model grid and resolution when glacier model, + Only used if glc_nec > 0 for determining fglcmask + Default: gland5UM + (i.e. gland20, gland10 etcetera) + -glc_nec Glacier number of elevation classes [0 | 3 | 5 | 10 | 36] + (default is 0) (standard option with land-ice model is 10) + -glc_smb Only used if glc_nec > 0 + If .true., pass surface mass balance info to GLC + If .false., pass positive-degree-day info to GLC + Default: true + -help [or -h] Print usage to STDOUT. + -ignore_ic_date Ignore the date on the initial condition files + when determining what input initial condition file to use. + -ignore_ic_year Ignore just the year part of the date on the initial condition files + when determining what input initial condition file to use. + -infile "filepath" Specify a file (or list of files) containing namelists to + read values from. + + If used with a CLM build with multiple ensembles (ninst_lnd>1) + and the filename entered is a directory to files of the + form filepath/filepath and filepath/filepath_$n where $n + is the ensemble member number. the "filepath/filepath" + input namelist file is the master input namelist file + that is applied to ALL ensemble members. + + (by default for CESM this is setup for files of the + form $CASEDIR/user_nl_clm/user_nl_clm_????) + -inputdata "filepath" Writes out a list containing pathnames for required input datasets in + + file specified. + -irrig "value" If .true. turn irrigation on with namelist logical irrigate (for CLM4.5 physics) + (requires crop to be on in the clm configuration) + Seek surface datasets with irrigation turned on. (for CLM4.0 physics) + Default: .false. + -l_ncpl "LND_NCPL" Number of CLM coupling time-steps in a day. + -lnd_frac "domainfile" Land fraction file (the input domain file) + -mask "landmask" Type of land-mask (default, navy, gx3v5, gx1v5 etc.) + "-mask list" to list valid land masks. + -namelist "namelist" Specify namelist settings directly on the commandline by supplying + a string containing FORTRAN namelist syntax, e.g., + -namelist "&clm_inparm dt=1800 /" + -no-megan DO NOT PRODUCE a megan_emis_nl namelist that will go into the + "drv_flds_in" file for the driver to pass VOCs to the atm. + MEGAN (Model of Emissions of Gases and Aerosols from Nature) + (Note: buildnml.csh copies the file for use by the driver) + -[no-]note Add note to output namelist [do NOT add note] about the + arguments to build-namelist. + -rcp "value" Representative concentration pathway (rcp) to use for + future scenarios. + "-rcp list" to list valid rcp settings. + -res "resolution" Specify horizontal grid. Use nlatxnlon for spectral grids; + dlatxdlon for fv grids (dlat and dlon are the grid cell size + in degrees for latitude and longitude respectively) + "-res list" to list valid resolutions. + -s Turns on silent mode - only fatal messages issued. + -sim_year "year" Year to simulate for input datasets + (i.e. 1850, 2000, 1850-2000, 1850-2100) + "-sim_year list" to list valid simulation years + -bgc_spinup "on|off" CLM 4.5 Only. For CLM 4.0, spinup is controlled from configure. + Turn on given spinup mode for BGC setting of CN + on : Turn on Accelerated Decomposition (spinup_state = 1) + off : run in normal mode (spinup_state = 0) + + Default is off. + + Spinup is now a two step procedure. First, run the model + with spinup = "on". Then run the model for a while with + spinup = "off". The exit spinup step happens automatically + on the first timestep when using a restart file from spinup + mode. + + The spinup state is saved to the restart file. + If the values match between the model and the restart + file it proceeds as directed. + + If the restart file is in spinup mode and the model is in + normal mode, then it performs the exit spinup step + and proceeds in normal mode after that. + + If the restart file has normal mode and the model is in + spinup, then it enters spinup. This is useful if you change + a parameter and want to rapidly re-equilibrate without doing + a cold start. + + -test Enable checking that input datasets exist on local filesystem. + -verbose [or -v] Turn on verbose echoing of informational messages. + -use_case "case" Specify a use case which will provide default values. + "-use_case list" to list valid use-cases. + -version Echo the SVN tag name used to check out this CLM distribution. + + + + Note: The precedence for setting the values of namelist variables is (highest to lowest): + 0. namelist values set by specific command-line options, like, -d, -sim_year + (i.e. CLM_BLDNML_OPTS env_run variable) + 1. values set on the command-line using the -namelist option, + (i.e. CLM_NAMELIST_OPTS env_run variable) + 2. values read from the file(s) specified by -infile, + (i.e. user_nl_clm files) + 3. datasets from the -clm_usr_name option, + (i.e. CLM_USRDAT_NAME env_run variable) + 4. values set from a use-case scenario, e.g., -use_case + (i.e. CLM_NML_USE_CASE env_run variable) + 5. values from the namelist defaults file. + + +The **clm.buildnml.csh** script already sets the resolution and mask as well as the CLM **configure** file, and defines an input namelist and namelist input file, and the output namelist directory, and sets the start-type (from ``RUN_TYPE``), namelist options (from ``CLM_NAMELIST_OPTS``), co2_ppmv (from ``CCSM_CO2_PPMV``, co2_type (from ``CLM_CO2_TYPE``), lnd_frac (from ``LND_DOMAIN_PATH`` and ``LND_DOMAIN_FILE``), l_ncpl (from ``LND_NCPL``, glc_grid, glc_smb, glc_nec (from ``GLC_GRID``, ``GLC_SMB``, and ``GLC_NEC``), and "clm_usr_name" is set (to ``CLM_USRDAT_NAME >``when the grid is set to ``CLM_USRDAT_NAME``. +Hence only the following different options can be set: + +1. +-bgc_spinup + +#. -chk_res + +#. -clm_demand + +#. -drydep + +#. -ignore_ic_date + +#. -ignore_ic_year + +#. -irrig + +#. -no-megan + +#. -note + +#. -rcp + +#. -sim_year + +#. -verbose + + +"-bgc_spinup" is an option only available for CLM4.5 for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See `the Section called Spinning up the CLM4.5 biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for an example using this option. + +"-chk_res" ensures that the resolution chosen is supported by CLM. If the resolution is NOT supported it will cause the CLM **build-namelist** to abort when run. So when either **preview_namelist**, **$CASE.build** or **$CASE.run** is executed it will abort early. Since, the CESM scripts only support certain resolutions anyway, in general this option is NOT needed in the context of running CESM cases. + +"-clm_demand" asks the **build-namelist** step to require that the list of variables entered be set. Typically, this is used to require that optional filenames be used and ensure they are set before continuing. For example, you may want to require that fpftdyn be set to get dynamically changing vegetation types. To do this you would do the following. +:: + + > ./xmlchange CLM_BLDNML_OPTS="-clm_demand fpftdyn"`` + +To see a list of valid variables that you could set do this: +:: + + > cd models/lnd/clm/doc + > ../bld/build-namelist -clm_demand list + + +.. note:: Using a 20th-Century transient compset or the ``20thC_transient`` use-case using ``CLM_NML_USE_CASE`` would set this as well, but would also use dynamic nitrogen and aerosol deposition files, so using ``-clm_demand`` would be a way to get *just* dynamic vegetation types and NOT the other files as well. + +"-drydep" adds the dry-deposition namelist to the driver. This is a driver namelist, but adding the option here has CLM **build-namelist** create the ``drv_flds_in`` file that the driver will copy over and use. Invoking this option does have an impact on performance even for I compsets and will slow the model down. It's also only useful when running with an active atmosphere model that makes use of this information. + +"-ignore_ic_date" ignores the Initial Conditions (IC) date completely for finding initial condition files to startup from. Without this option or the "-ignore_ic_year" option below, the date of the file comes into play. + +"-ignore_ic_year" ignores the Initial Conditions (IC) year for finding initial condition files to startup from. The date is used, but the year is ignored. Without this option or the "-ignore_ic_date" option below, the date and year of the file comes into play. + +When "-irrig" is used **build-namelist** will try to find surface datasets that have the irrigation model enabled. + +"no-megan" means do NOT add the MEGAN model Biogenic Volatile Organic Compounds (BVOC) namelist to the driver. This namelist is created by default, so normally this WILL be done. This is a driver namelist, so unless "no-megan" is specified the CLM **build-namelist** will create the ``drv_flds_in`` file that the driver will copy over and use (if you are running with CAM and CAM produces this file as well, it's file will have precedence). + +"-note" adds a note to the bottom of the namelist file, that gives the details of how **build-namelist** was called, giving the specific command-line options given to it. + +"-rcp" is used to set the representative concentration pathway for the future scenarios you want the data-sets to simulate conditions for, in the input datasets. To list the valid options do the following: +:: + + > cd models/lnd/clm/doc + > ../bld/build-namelist -rcp list + +"-sim_year" is used to set the simulation year you want the data-sets to simulate conditions for in the input datasets. The simulation "year" can also be a range of years in order to do simulations with changes in the dataset values as the simulation progresses. To list the valid options do the following: +:: + + > cd models/lnd/clm/doc + > ../bld/build-namelist -sim_year list + +``CLM_NAMELIST_OPTS`` + passes namelist items into one of the CLM namelists. + + .. note:: For character namelist items you need to use "'" as quotes for strings so that the scripts don't get confused with other quotes they use. + + Example, you want to set ``hist_dov2xy`` to ``.false.`` so that you get vector output to your history files. To do so edit ``env_run.xml`` and add a setting for ``hist_dov2xy``. So do the following: + :: + + > ./xmlchange CLM_NAMELIST_OPTS="hist_dov2xy=.false." + + Example, you want to set ``hist_fincl1`` to add the variable 'HK' to your history files. To do so edit ``env_run.xml`` and add a setting for ``hist_fincl1``. So do the following: + :: + + > ./xmlchange CLM_NAMELIST_OPTS="hist_fincl1='HK'" + + For a list of the history fields available see `CLM History Fields `_. + + .. note: See the `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + +``CLM_FORCE_COLDSTART`` + when set to on, *requires* that your simulation do a cold start from arbitrary initial conditions. If this is NOT set, it will use an initial condition file if it can find an appropriate one, and otherwise do a cold start. ``CLM_FORCE_COLDSTART`` is a good way to ensure that you are doing a cold start if that is what you want to do. + +``CLM_USRDAT_NAME`` + Provides a way to enter your own datasets into the namelist. + The files you create must be named with specific naming conventions outlined in: `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_. + To see what the expected names of the files are, use the **queryDefaultNamelist.pl** to see what the names will need to be. + For example if your ``CLM_USRDAT_NAME`` will be "1x1_boulderCO", with a "navy" land-mask, constant simulation year range, for 1850, the following will list what your filenames should be: + :: + + > cd models/lnd/clm/bld + > queryDefaultNamelist.pl -usrname "1x1_boulderCO" -options mask=navy,sim_year=1850,sim_year_range="constant" -csmdata $CSMDATA + + An example of using ``CLM_USRDAT_NAME`` for a simulation is given in `Example 5-4 `_. + + .. note:: See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + +``CLM_CO2_TYPE`` + sets the type of input CO2 for either "constant", "diagnostic" or prognostic". + If "constant" the value from ``CCSM_CO2_PPMV`` will be used. + If "diagnostic" or "prognostic" the values MUST be sent from the atmosphere model. + For more information on how to send CO2 from the data atmosphere model see `the Section called Running stand-alone CLM with transient historical CO2 concentration in Chapter 4 `_. + +=============== + User Namelist +=============== + +``CLM_NAMELIST_OPTS`` as described above allows you to set any extra namelist items you would like to appear in your namelist. However, it only allows you a single line to enter namelist items, and strings must be quoted with ' which is a bit awkward. If you have a long list of namelist items you want to set (such as a long list of history fields) a convenient way to do it is to add to the ``user_nl_clm`` that is created after the **cesm_setup** command runs. The file needs to be in valid FORTRAN namelist format (with the exception that the namelist name &namelist and the end of namelist marker "/" are excluded". The **preview_namelist** or **$CASE.run** step will abort if there are syntax errors. All the variable names must be valid and the values must be valid for the datatype and any restrictions for valid values for that variable. Here's an example ``user_nl_clm`` namelist that sets a bunch of history file related items, to create output history files monthly, daily, every six and 1 hours. + +---------------------------------- +Example: user_nl_clm namelist file +---------------------------------- + +:: + + !---------------------------------------------------------------------------------- + ! Users should add all user specific namelist changes below in the form of + ! namelist_var = new_namelist_value + ! + ! Include namelist variables for drv_flds_in ONLY if -megan and/or -drydep options + ! are set in the CLM_NAMELIST_OPTS env variable. + ! + ! EXCEPTIONS: + ! Set co2_ppmv with CCSM_CO2_PPMV option + ! Set dtime with L_NCPL option + ! Set fatmlndfrc with LND_DOMAIN_PATH/LND_DOMAIN_FILE options + ! Set finidat with RUN_REFCASE/RUN_REFDATE/RUN_REFTOD options for hybrid or branch cases + ! (includes $inst_string for multi-ensemble cases) + ! Set glc_grid with GLC_GRID option + ! Set glc_smb with GLC_SMB option + ! Set maxpatch_glcmec with GLC_NEC option + !---------------------------------------------------------------------------------- + hist_fincl2 = 'TG','TBOT','FIRE','FIRA','FLDS','FSDS', + 'FSR','FSA','FGEV','FSH','FGR','TSOI', + 'ERRSOI','BUILDHEAT','SABV','SABG', + 'FSDSVD','FSDSND','FSDSVI','FSDSNI', + 'FSRVD','FSRND','FSRVI','FSRNI', + 'TSA','FCTR','FCEV','QBOT','RH2M','H2OSOI', + 'H2OSNO','SOILLIQ','SOILICE', + 'TSA_U', 'TSA_R', + 'TREFMNAV_U', 'TREFMNAV_R', + 'TREFMXAV_U', 'TREFMXAV_R', + 'TG_U', 'TG_R', + 'RH2M_U', 'RH2M_R', + 'QRUNOFF_U', 'QRUNOFF_R', + 'SoilAlpha_U', + 'Qanth', 'SWup', 'LWup', 'URBAN_AC', 'URBAN_HEAT' + hist_fincl3 = 'TG:I', 'FSA:I', 'SWup:I', 'URBAN_AC:I', 'URBAN_HEAT:I', + 'TG_U:I', 'TG_R:I', + hist_fincl4 = 'TG', 'FSA', 'SWup', 'URBAN_AC', 'URBAN_HEAT' + hist_mfilt = 1, 30, 28, 24 + hist_nhtfrq = 0, -24, -6, -1 + + +**Note:** The comments at the top are some guidance given in the default user_nl_clm and just give some guidance on how to set variables and use the file. + +**Note:** See the `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + +**Note:** You do NOT need to specify the namelist group that the variables are in because the CLM **build-namelist** knows the namelist that specific variable names belong to, and it puts them there. + +Obviously, all of this would be difficult to put in the CLM_NAMELIST_OPTS variable, especially having to put ' around all the character strings. For more information on the namelist variables being set here and what they mean, see the section on CLM namelists below, as well as the namelist definition that gives details on each variable. + +--------------------- +Precedence of Options +--------------------- + +Note: The precedence for setting the values of namelist variables with the different env_build.xml, env_run.xml options is (highest to lowest): + +1. Namelist values set by specific command-line options, like, -d, -sim_year (i.e. CLM_BLDNML_OPTS env_build.xml variable) + +#. Values set on the command-line using the -namelist option, (i.e. CLM_NAMELIST_OPTS env_run.xml variable) + +#. Values read from the file specified by -infile, (i.e. user_nl_clm file) + +#. Datasets from the -clm_usr_name option, (i.e. CLM_USRDAT_NAME env_run.xml variable) + +#. Values set from a use-case scenario, e.g., -use_case (i.e. CLM_NML_USE_CASE env_run.xml variable) + +#. Values from the namelist defaults file. + +Thus a setting in ``CLM_BLDNML_OPTS`` will override a setting for the same thing given in a use case with ``CLM_NML_USE_CASE``. Likewise, a setting in ``CLM_NAMELIST_OPTS`` will override a setting in ``user_nl_clm``. + +------------------------------------ +Setting Your Initial Conditions File +------------------------------------ + +Especially with CLMBGC and CLMCN starting from initial conditions is very important. Even with CLMSP it takes many simulation years to get the model fully spunup. There are a couple different ways to provide an initial condition file. + +- `the Section called Doing a hybrid simulation to provide initial conditions `_ +- `the Section called Doing a branch simulation to provide initial conditions `_ +- `the Section called Providing a finidat file in your user_nl_clm file `_ +- `the Section called Adding a finidat file to the XML database `_ + + **Note:** Your initial condition file MUST agree with the surface dataset you are using to run the simulation. If the two files do NOT agree you will get a run-time about a mis-match in PFT weights, or in the number of PFT's or columns. To get around this you'll need to use the `Section called Using interpinic to interpolate initial conditions to different resolutions in Chapter 2 `_ to interpolate your initial condition dataset. + +------------------------------------------------------- +Doing a hybrid simulation to provide initial conditions +------------------------------------------------------- + +The first option is to setup a hybrid simulation and give a ``RUN_REFCASE`` and ``RUN_REFDATE`` to specify the reference case simulation name to use. When you setup most cases, at the standard resolutions of "f09" or "f19" it will already do this for you. For example, if you run an "I2000CN" compset at "f09_g16" resolution the following settings will already be done for you. + +``./xmlchange RUN_TYPE=hybrid,RUN_REFCASE=I2000CN_f09_g16_c100503,RUN_REFDATE=0001-01-01,GET_REFCASE=TRUE`` + +Setting the ``GET_REFCASE`` option to ``TRUE means`` it will copy the files from the: ``$DIN_LOC_ROOT/ccsm4_init/I2000CN_f09_g16_c100503/0001-01-01`` directory. Note, that the ``RUN_REFCASE`` and ``RUN_REFDATE`` variables are expanded to get the directory name above. If you do NOT set ``GET_REFCASE`` to ``TRUE`` then you will need to have placed the file in your run directory yourself. In either case, the file is expected to be named: ``$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc`` with the variables expanded of course. + +------------------------------------------------------- +Doing a branch simulation to provide initial conditions +------------------------------------------------------- + +The setup for running a branch simulation is essentially the same as for a hybrid. With the exception of setting ``RUN_TYPE`` to branch rather than hybrid. A branch simulation runs the case essentially as restarting from it's place before to exactly reproduce it (but possibly output more or different fields on the history files). While a hybrid simulation allows you to change the configuration or run-time options, as well as use a different code base than the original case that may have fewer fields on it than a full restart file. The ``GET_REFCASE`` option works similarly for a branch case as for a hybrid. + +------------------------------------------------- +Providing a finidat file in your user_nl_clm file +------------------------------------------------- + +Setting up a branch or hybrid simulation requires the initial condition file to follow a standard naming convention, and a standard input directory if you use the ``GET_REFCASE`` option. If you want to name your file willy nilly and place it anywhere, you can set it in your ``user_nl_clm`` file as in this example. +:: + + finidat = '/glade/home/$USER/myinitdata/clmi_I1850CN_f09_g16_0182-01-01.c120329.nc' + +Note, if you provide an initial condition file -- you can NOT set ``CLM_FORCE_COLDSTART`` to ``TRUE``. + +------------------------------------------- + Adding a finidat file to the XML database +------------------------------------------- + +Like other datasets, if you want to use a given initial condition file to be used for all (or most of) your cases you'll want to put it in the XML database so it will be used by default. The initial condition files, are resolution dependent, and dependent on the number of PFT's and other variables such as GLC_NEC or if irrigation is on or off. See Chapter 3 for more information on this. + +------------------------------------ +Other noteworthy configuration items +------------------------------------ + +For running "I" cases there are several other noteworthy configuration items that you may want to work with. +Most of these involve settings for the DATM, but one ``CCSM_CO2_PPMV`` applies to all models. +If you are running an B, E, or F case that doesn't use the DATM obviously the DATM_* settings will not be used. All of the settings below are in your ``env_build.xml`` and ``env_run.xml`` files +:: + + CCSM_CO2_PPMV + CCSM_VOC + DATM_MODE + DATM_PRESAERO + DATM_CLMNCEP_YR_ALIGN + DATM_CLMNCEP_YR_START + DATM_CLMNCEP_YR_END + DATM_CPL_CASE + DATM_CPL_YR_ALIGN + DATM_CPL_YR_START + DATM_CPL_YR_END + +``CCSM_CO2_PPMV`` + Sets the mixing ratio of CO2 in parts per million by volume for ALL CESM components to use. Note that most compsets already set this value to something reasonable. Also note that some compsets may tell the atmosphere model to override this value with either historic or ramped values. If the CCSM_BGC variable is set to something other than "none" the atmosphere model will determine CO2, and CLM will listen and use what the atmosphere sends it. On the CLM side the namelist item co2_type tells CLM to use the value sent from the atmosphere rather than a value set on it's own namelist. + +``CCSM_VOC`` + Enables passing of the Volatile Organic Compounds (VOC) from CLM to the atmospheric model. This of course is only important if the atmosphere model is a fully active model that can use these fields in it's chemistry calculations. + +``DATM_MODE`` + Sets the mode that the DATM model should run in this determines how data is handled as well as what the source of the data will be. Many of the modes are setup specifically to be used for ocean and/or sea-ice modeling. The modes that are designed for use by CLM are: + :: + + CLMCRUNCEP + CLM_QIAN + CLM1PT> + CPLHIST3HrWx + +``CLMCRUNCEP`` + The standard mode for CLM4.5 of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010. + See `the Section called CLMCRUNCEP mode and it's DATM settings `_ for more information on the DATM settings for ``CLMCRUNCEP`` mode. + +``CLM_QIAN`` + The standard mode for CLM4.0 of using global atmospheric data that was developed by Qian et. al. for CLM using NCEP data from 1948 to 2004. See the `Section called CLM_QIAN mode and it's DATM settings `_ for more information on the DATM settings for ``CLM_QIAN`` mode. ``CLM1PT`` is for the special cases where we have single-point tower data for particular sites. Right now we only have data for three urban locations: MexicoCity Mexico, Vancouver Canada, and the urban-c alpha site. And we have data for the US-UMB AmeriFlux tower site for University of Michigan Biological Station. See `the Section called CLM1PT mode and it's DATM settings `_ for more information on the DATM settings for ``CLM1PT`` mode. ``CPLHIST3HrWx`` is for running with atmospheric forcing from a previous CESM simulation. See `the Section called CPLHIST3HrWx mode and it's DATM settings `_ for more information on the DATM settings for ``CPLHIST3HrWx`` mode. + +``DATM_PRESAERO`` + sets the prescribed aerosol mode for the data atmosphere model. The list of valid options include: + + ``clim_1850`` = constant year 1850 conditions + + ``clim_2000`` = constant year 2000 conditions + + ``trans_1850-2000`` = transient 1850 to year 2000 conditions + + ``rcp2.6`` = transient conditions for the rcp=2.6 W/m2 future scenario + + ``rcp4.5`` = transient conditions for the rcp=4.5 W/m2 future scenario + + ``rcp6.0`` = transient conditions for the rcp=6.0 W/m2 future scenario + + ``rcp8.5`` = transient conditions for the rcp=8.5 W/m2 future scenario + + ``pt1_pt1`` = read in single-point or regional datasets + +DATM_CLMNCEP_YR_START + ``DATM_CLMNCEP_YR_START`` sets the beginning year to cycle the atmospheric data over for ``CLM_QIAN`` or ``CLMCRUNCEP`` modes. + +DATM_CLMNCEP_YR_END + ``DATM_CLMNCEP_YR_END`` sets the ending year to cycle the atmospheric data over for ``CLM_QIAN`` or ``CLMCRUNCEP`` modes. + +DATM_CLMNCEP_YR_ALIGN + ``DATM_CLMNCEP_YR_START`` and ``DATM_CLMNCEP_YR_END`` determine the range of years to cycle the atmospheric data over, and ``DATM_CLMNCEP_YR_ALIGN`` determines which year in that range of years the simulation will start with. + +DATM_CPL_CASE + ``DATM_CPL_CASE`` sets the casename to use for the ``CPLHIST3HrWx`` mode. + +DATM_CPL_YR_START + ``DATM_CPL_YR_START`` sets the beginning year to cycle the atmospheric data over for the ``CPLHIST3HrWx`` mode. + +DATM_CPL_YR_END + ``DATM_CPL_YR_END`` sets the ending year to cycle the atmospheric data over for the ``CPLHIST3HrWx`` mode. + +DATM_CPL_YR_ALIGN + ``DATM_CPL_YR_START`` and ``DATM_CPL_YR_END`` determine the range of years to cycle the atmospheric data over, and ``DATM_CPL_YR_ALIGN`` determines which year in that range of years the simulation will start with. + +----------------------------- +Downloading DATM Forcing Data +----------------------------- + +In Chapter One of the `CESM User's Guide `_ there is a section on "Downloading input data". The normal process of setting up cases will use the "scripts/ccsm_utils/Tools/check_input_data" script to retrieve data from the CESM subversion inputdata repository. This is true for the standard `CLM_QIAN` forcing as well. + +The `CLMCRUNCEP` data is uploaded into the subversion inputdata repository as well -- but as it is 1.1 Terabytes of data downloading it is problematic (*IT WILL TAKE SEVERAL DAYS TO DOWNLOAD THE ENTIRE DATASET USING SUBVERSION*). Because of it's size you may also need to download it onto a separate disk space. We have done that on yellowstone for example where it resides in ``$ENV{CESMROOT}/lmwg`` while the rest of the input data resides in ``$ENV{CESMDATAROOT}/inputdata``. The data is also already available on: janus, franklin, and hopper. If you download the data, we recommend that you break your download into several chunks, by setting up a case and setting the year range for ``DATM_CPL_YR_START`` and ``DATM_CPL_YR_END`` in say 20 year sections over 1901 to 2010, and then use **check_input_data** to export the data. + +The ``CPLHIST3HrWx`` DATM forcing data is unique -- because it is large compared to the rest of the input data, and we only have a disk copy on yellowstone. The DATM assumes the path for the previous NCAR machine yellowstone of ``/glade/p/cesm/shared_outputdata/cases/ccsm4/$DATM_CPLHIST_CASE`` for the data. So you will need to change this path in order to run on any other machine. You can download the data itself from NCAR HPSS from ``/CCSM/csm/$DATM_CPLHIST_CASE``. + +-------------------------------------- +Customizing via the build script files +-------------------------------------- + +The final thing that the user may wish to do before **cesm_setup** is run is to edit the build script files which determine the configuration and namelist. The variables in ``env_build.xml`` or ``env_run.xml`` typically mean you will NOT have to edit build script files. But, there are rare instances where it is useful to do so. The build script files are copied to your case directory and are available under Buildconf. The list of build script files you might wish to edit are: + +**clm.buildexe.csh** +**clm.buildnml.csh** +**datm.buildexe.csh** +**datm.buildnml.csh** + +-------------------------------------------- +More information on the CLM configure script +-------------------------------------------- + +The CLM **configure** script defines the details of a clm configuration and summarizes it into a ``config_cache.xml`` file. The ``config_cache.xml`` will be placed in your case directory under ``Buildconf/clmconf``. The `config_definition.xml `_ in ``models/lnd/clm/bld/config_files`` gives a definition of each CLM configuration item, it is viewable in a web-browser. Many of these items are things that you would NOT change, but looking through the list gives you the valid options, and a good description of each. Below we repeat the ``config_definition.xml`` files contents: + +Help on CLM configure +--------------------- + +Coupling this with looking at the options to CLM **configure** with "-help" as below will enable you to understand how to set the different options. +:: + + > cd models/lnd/clm/bld + > configure -help + +The output to the above command is as follows: +:: + + SYNOPSIS + configure [options] + + Configure CLM in preparation to be built. + OPTIONS + User supplied values are denoted in angle brackets (<>). Any value that contains + white-space must be quoted. Long option names may be supplied with either single + or double leading dashes. A consequence of this is that single letter options may + NOT be bundled. + + -bgc Build CLM with BGC package [ none | cn | cndv ] + (default is none). + -cache Name of output cache file (default: config_cache.xml). + -cachedir Name of directory where output cache file is written + (default: CLM build directory). + -clm4me Turn Methane model: [on | off] + Requires bgc=cn/cndv (Carbon Nitrogen model) + (ONLY valid for CLM4.5!) + -clm_root Root directory of clm source code + (default: directory above location of this script) + -cppdefs A string of user specified CPP defines. Appended to + Makefile defaults. e.g. -cppdefs '-DVAR1 -DVAR2' + -vichydro Turn VIC hydrologic parameterizations : [on | off] (default is off) + -crop Toggle for prognostic crop model. [on | off] (default is off) + (can ONLY be turned on when BGC type is CN or CNDV) + -comp_intf Component interface to use (ESMF or MCT) (default MCT) + -defaults Specify full path to a configuration file which will be used + to supply defaults instead of the defaults in bld/config_files. + This file is used to specify model configuration parameters only. + Parameters relating to the build which are system dependent will + be ignored. + -exlaklayers Turn on extra lake layers (25 layers instead of 10) [on | off] + (ONLY valid for CLM4.5!) + -help [or -h] Print usage to STDOUT. + -nofire Turn off wildfires for BGC setting of CN + (default includes fire for CN) + -noio Turn history output completely off (typically for testing). + -phys Value of clm4_0 or clm4_5 (default is clm4_0) + -silent [or -s] Turns on silent mode - only fatal messages issued. + -sitespf_pt Setup for the given site specific single-point resolution. + -snicar_frc Turn on SNICAR radiative forcing calculation. [on | off] + (default is off) + -spinup CLM 4.0 Only. For CLM 4.5, spinup is controlled from build-namelist. + Turn on given spinup mode for BGC setting of CN (level) + AD Turn on Accelerated Decomposition from (2) + bare-soil + exit Jump directly from AD spinup to normal mode (1) + normal Normal decomposition ("final spinup mode") (0) + (default) + The recommended sequence is 2-1-0 + -usr_src [,[,[...]]] + Directories containing user source code. + -verbose [or -v] Turn on verbose echoing of settings made by configure. + -version Echo the SVN tag name used to check out this CLM distribution. + -vsoilc_centbgc Turn on vertical soil Carbon profile, CENTURY model decomposition, \ + + split Nitrification/de-Nitrification into two mineral + pools for NO3 and NH4 (requires clm4me Methane model), and + eliminate inconsistent duplicate soil hydraulic + parameters used in soil biogeochem. + (requires either CN or CNDV) + (ONLY valid for CLM4.5!) + [on,off or colon delimited list of no options] (default off) + no-vert Turn vertical soil Carbon profile off + no-cent Turn CENTURY off + no-nitrif Turn the Nitrification/denitrification off + [no-vert,no-cent,no-nitrif,no-vert:no-cent] + + +We've given details on how to use the options in env_build.xml and env_run.xml to interact with the CLM "configure" and "build-namelist" scripts, as well as giving a good understanding of how these scripts work and the options to them. +In the next section we give further details on the CLM namelist. You could customize the namelist for these options after "cesm_setup" is run. diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst new file mode 100644 index 0000000000..131078c648 --- /dev/null +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst @@ -0,0 +1,251 @@ +.. _customizing-a-case: + +============================ + Customizing CLM's namelist +============================ + +Once a case is **cesm_setup**, we can then customize the case further, by editing the run-time namelist for CLM. First let's list the definition of each namelist item and their valid values, and then we'll list the default values for them. Next for some of the most used or tricky namelist items we'll give examples of their use, and give you example namelists that highlight these features. + +In the following, various examples of namelists are provided that feature the use of different namelist options to customize a case for particular uses. +Most the examples revolve around how to customize the output history fields. +This should give you a good basis for setting up your own CLM namelist. + +----------------------------------------------------- +Definition of Namelist items and their default values +----------------------------------------------------- + +Here we point to you where you can find the definition of each namelist item and separately the default values for them. The default values may change depending on the resolution, land-mask, simulation-year and other attributes. Both of these files are viewable in your web browser, and then expand each in turn. + +1. `Definition of Namelists Relevant for CLM4.5 `_ + +2. `Default values of each CLM4.0 Namelist Item `_ + +3. `Default values of each CLM4.5 Namelist Item `_ + +List of fields that can be added to your output history files by namelist +------------------------------------------------------------------------- + +One set of the namelist items allows you to add fields to the output history files: ``hist_fincl1``, ``hist_fincl2``, ``hist_fincl3``, ``hist_fincl4``, ``hist_fincl5``, and ``hist_fincl6``. The following links for `CLM4.0 History Fields `_ and `CLM4.5 History Fields `_ documents all of the history fields available and gives the long-name and units for each. The table below lists all the CLM4.5 history fields. + +Definition of CLM history variables +----------------------------------- + +Included in the table are the following pieces of information: + +- Variable name. + +- Long name description. + +- units + + +Table 1-3. CLM History Fields +----------------------------- +Table goes here. + + +--------------------------------------------- +Examples of using different namelist features +--------------------------------------------- + +Below we will give examples of user namelists that activate different commonly used namelist features. We will discuss the namelist features in different examples and then show a user namelist that includes an example of the use of these features. First we will show the default namelist that doesn't activate any user options. + +The default namelist +-------------------- + +Here we give the default namelist as it would be created for an "I1850CRUCLM45BGC" compset at 0.9x1.25 resolution with a gx1v6 land-mask on yellowstone. To edit the namelist you would edit the ``user_nl_clm`` user namelist with just the items you want to change. For simplicity we will just show the CLM namelist and NOT the entire file. In the sections below, for simplicity we will just show the user namelist (``user_nl_clm``) that will add (or modify existing) namelist items to the namelist. + +Example 1-2. Default CLM Namelist +--------------------------------- +:: + + &clm_inparm + albice = 0.60,0.40 + co2_ppmv = 284.7 + co2_type = 'constant' + create_crop_landunit = .false. + dtime = 1800 + fatmlndfrc = '/glade/p/cesm/cseg/inputdata/share/domains/domain.lnd.fv0.9x1.25_gx1v6.090309.nc' + finidat = '$DIN_LOC_ROOT/lnd/clm2/initdata_map/clmi.I1850CRUCLM45BGC.0241-01-01.0.9x1.25_g1v6_simyr1850_c130531.nc' + fpftcon = '/glade/p/cesm/cseg/inputdata/lnd/clm2/pftdata/pft-physiology.c130503.nc' + fsnowaging = '/glade/p/cesm/cseg/inputdata/lnd/clm2/snicardata/snicar_drdt_bst_fit_60_c070416.nc' + fsnowoptics = '/glade/p/cesm/cseg/inputdata/lnd/clm2/snicardata/snicar_optics_5bnd_c090915.nc' + fsurdat = '/glade/p/cesm/cseg/inputdata/lnd/clm2/surfdata_map/surfdata_0.9x1.25_simyr1850_c130415.nc' + maxpatch_glcmec = 0 + more_vertlayers = .false. + nsegspc = 20 + spinup_state = 0 + urban_hac = 'ON' + urban_traffic = .false. + / + &ndepdyn_nml + ndepmapalgo = 'bilinear' + stream_fldfilename_ndep = '/glade/p/cesm/cseg/inputdata/lnd/clm2/ndepdata/fndep_clm_hist_simyr1849-2006_1.9x2.5_c100428.nc' + stream_year_first_ndep = 1850 + stream_year_last_ndep = 1850 + / + &popd_streams + popdensmapalgo = 'bilinear' + stream_fldfilename_popdens = '$DIN_LOC_ROOT/lnd/clm2/firedata/clmforc.Li_2012_hdm_0.5x0.5_AVHRR_simyr1850-2010_c130401.nc' + stream_year_first_popdens = 1850 + stream_year_last_popdens = 1850 + / + &light_streams + lightngmapalgo = 'bilinear' + stream_fldfilename_lightng = '/glade/p/cesm/cseg/inputdata/atm/datm7/NASA_LIS/clmforc.Li_2012_climo1995-2011.T62.lnfm_c130327.nc' + stream_year_first_lightng = 0001 + stream_year_last_lightng = 0001 + / + &clm_hydrology1_inparm + / + &clm_soilhydrology_inparm + / + &ch4par_in + fin_use_fsat = .true. + / + +Adding/removing fields on your primary history file +--------------------------------------------------- + +The primary history files are output monthly, and contain an extensive list of fieldnames, but the list of fieldnames can be added to using ``hist_fincl1`` or removed from by adding fieldnames to ``hist_fexcl1``. +A sample user namelist ``user_nl_clm`` adding few new fields (cosine of solar zenith angle, and solar declination) and excluding a few standard fields is (ground temperature, vegetation temperature, soil temperature and soil water).: + +Example 1-3. Example user_nl_clm namelist adding and removing fields on primary history file +-------------------------------------------------------------------------------------------- +:: + + hist_fincl1 = 'COSZEN', 'DECL' + hist_fexcl1 = 'TG', 'TV', 'TSOI', 'H2OSOI' + + +Adding auxiliary history files and changing output frequency +------------------------------------------------------------ + +The ``hist_fincl2`` through ``hist_fincl6`` set of namelist variables add given history fieldnames to auxiliary history file "streams", and ``hist_fexcl2`` through ``hist_fexcl6`` set of namelist variables remove given history fieldnames from history file auxiliary "streams". +A history "stream" is a set of history files that are produced at a given frequency. +By default there is only one stream of monthly data files. +To add more streams you add history fieldnames to ``hist_fincl2`` through ``hist_fincl6``. +The output frequency and the way averaging is done can be different for each history file stream. +By default the primary history files are monthly and any others are daily. You can have up to six active history streams, but you need to activate them in order. So if you activate stream "6" by setting ``hist_fincl6``, but if any of ``hist_fincl2`` through ``hist_fincl5`` are unset, only the history streams up to the first blank one will be activated. + +The frequency of the history file streams is given by the namelist variable ``hist_nhtfrq`` which is an array of rank six for each history stream. The values of the array ``hist_nhtfrq`` must be integers, where the following values have the given meaning: + +*Positive value* means the output frequency is the number of model steps between output. +*Negative value* means the output frequency is the absolute value in hours given (i.e -1 would mean an hour and -24 would mean a full day). Daily (-24) is the default value for all auxiliary files. +*Zero* means the output frequency is monthly. This is the default for the primary history files. + +The number of samples on each history file stream is given by the namelist variable ``hist_mfilt`` which is an array of rank six for each history stream. The values of the array ``hist_mfilt`` must be positive integers. By default the primary history file stream has one time sample on it (i.e. output is to separate monthly files), and all other streams have thirty time samples on them. + +A sample user namelist ``user_nl_clm`` turning on four extra file streams for output: daily, six-hourly, hourly, and every time-step, leaving the primary history files as monthly, and changing the number of samples on the streams to: yearly (12), thirty, weekly (28), daily (24), and daily (48) is: + +Example: user_nl_clm namelist adding auxiliary history files and changing output frequency +------------------------------------------------------------------------------------------------------ +:: + + hist_fincl2 = 'TG', 'TV' + hist_fincl3 = 'TG', 'TV' + hist_fincl4 = 'TG', 'TV' + hist_fincl5 = 'TG', 'TV' + hist_nhtfrq = 0, -24, -6, -1, 1 + hist_mfilt = 12, 30, 28, 24, 48 + +Removing all history fields +--------------------------- + +Sometimes for various reasons you want to remove all the history fields either because you want to do testing without any output, or you only want a very small custom list of output fields rather than the default extensive list of fields. +By default only the primary history files are active, so technically using ``hist_fexcl1`` explained in the first example, you could list ALL of the history fields that are output in ``hist_fexcl1`` and then you wouldn't get any output. +However, as the list is very extensive this would be a cumbersome thing to do. +So to facilitate this ``hist_empty_htapes`` allows you to turn off all default output. +You can still use ``hist_fincl1`` to turn your own list of fields on, but you then start from a clean slate. +A sample user namelist ``user_nl_clm`` turning off all history fields and then activating just a few selected fields (ground and vegetation temperatures and absorbed solar radiation) is: + +Example 1-5. Example user_nl_clm namelist removing all history fields +--------------------------------------------------------------------- +:: + + hist_empty_htapes = .true. + hist_fincl1 = 'TG', 'TV', 'FSA' + + +Various ways to change history output averaging flags +----------------------------------------------------- + +There are two ways to change the averaging of output history fields. +The first is using ``hist_avgflag_pertape`` which gives a default value for each history stream, the second is when you add fields using ``hist_fincl*``, you add an averaging flag to the end of the field name after a colon (for example 'TSOI:X', would output the maximum of TSOI). +The types of averaging that can be done are: + +- *A* Average, over the output interval. +- *I* Instantaneous, output the value at the output interval. +- *X* Maximum, over the output interval. +- *M* Minimum, over the output interval. + +The default averaging depends on the specific fields, but for most fields is an average. +A sample user namelist ``user_nl_clm`` making the monthly output fields all averages (except TSOI for the first two streams and FIRE for the 5th stream), and adding auxiliary file streams for instantaneous (6-hourly), maximum (daily), minimum (daily), and average (daily). +For some of the fields we diverge from the per-tape value given and customize to some different type of optimization. + +Example: user_nl_clm namelist with various ways to average history fields +------------------------------------------------------------------------------------- +:: + + hist_empty_htapes = .true. + hist_fincl1 = 'TSOI:X', 'TG', 'TV', 'FIRE', 'FSR', 'FSH', + 'EFLX_LH_TOT', 'WT' + hist_fincl2 = 'TSOI:X', 'TG', 'TV', 'FIRE', 'FSR', 'FSH', + 'EFLX_LH_TOT', 'WT' + hist_fincl3 = 'TSOI', 'TG:I', 'TV', 'FIRE', 'FSR', 'FSH', + 'EFLX_LH_TOT', 'WT' + hist_fincl4 = 'TSOI', 'TG', 'TV:I', 'FIRE', 'FSR', 'FSH', + 'EFLX_LH_TOT', 'WT' + hist_fincl5 = 'TSOI', 'TG', 'TV', 'FIRE:I', 'FSR', 'FSH', + 'EFLX_LH_TOT', 'WT' + hist_avgflag_pertape = 'A', 'I', 'X', 'M', 'A' + hist_nhtfrq = 0, -6, -24, -24, -24 + +In the example we put the same list of fields on each of the tapes: soil-temperature, ground temperature, vegetation temperature, emitted longwave radiation, reflected solar radiation, sensible heat, total latent-heat, and total water storage. +We also modify the soil-temperature for the primary and secondary auxiliary tapes by outputting them for a maximum instead of the prescribed per-tape of average and instantaneous respectively. +For the tertiary auxiliary tape we output ground temperature instantaneous instead of as a maximum, and for the fourth auxiliary tape we output vegetation temperature instantaneous instead of as a minimum. +Finally, for the fifth auxiliary tapes we output ``FIRE`` instantaneously instead of as an average. + +.. note:: We also use ``hist_empty_htapes`` as in the previous example, so we can list ONLY the fields that we want on the primary history tapes. + +Outputting history files as a vector in order to analyze the plant function types within gridcells +-------------------------------------------------------------------------------------------------- + +By default the output to history files are the grid-cell average of all land-units, and vegetation types within that grid-cell, and output is on the full 2D latitude/longitude grid with ocean masked out. +Sometimes it's important to understand how different land-units or vegetation types are acting within a grid-cell. +The way to do this is to output history files as a 1D-vector of all land-units and vegetation types. +In order to display this, you'll need to do extensive post-processing to make sense of the output. +Often you may only be interested in a few points, so once you figure out the 1D indices for the grid-cells of interest, you can easily view that data. +1D vector output can also be useful for single point datasets, since it's then obvious that all data is for the same grid cell. + +To do this you use ``hist_dov2xy`` which is an array of rank six for each history stream. +Set it to ``.false.`` if you want one of the history streams to be a 1D vector. +You can also use ``hist_type1d_pertape`` if you want to average over all the: Plant-Function-Types, columns, land-units, or grid-cells. +A sample user namelist ``user_nl_clm`` leaving the primary monthly files as 2D, and then doing grid-cell (GRID), column (COLS), and no averaging over auxiliary tapes output daily for a single field (ground temperature) is: + +Example: user_nl_clm namelist outputting some files in 1D Vector format +----------------------------------------------------------------------- +:: + + hist_fincl2 = 'TG' + hist_fincl3 = 'TG' + hist_fincl4 = 'TG' + hist_fincl5 = 'TG' + hist_fincl6 = 'TG' + hist_dov2xy = .true., .false., .false., .false. + hist_type2d_pertape = ' ', 'GRID', 'COLS', ' ' + hist_nhtfrq = 0, -24, -24, -24 + +.. warning:: LAND and COLS are also options to the pertape averaging, but currently there is a bug with them and they fail to work. + +.. note:: Technically the default for hist_nhtfrq is for primary files output monthly and the other auxiliary tapes for daily, so we don't actually have to include hist_nhtfrq, we could use the default for it. Here we specify it for clarity. + +.. caution:: LAND and COLS are also options to the pertape averaging, but currently there is a bug with them and they fail to work. + +Visualizing global 1D vector files will take effort. +You'll probably want to do some post-processing and possibly just extract out single points of interest to see what is going on. +Since, the output is a 1D vector, of only land-points traditional plots won't be helpful. +The number of points per grid-cell will also vary for anything, but grid-cell averaging. +You'll need to use the output fields pfts1d_ixy, and pfts1d_jxy, to get the mapping of the fields to the global 2D array. +pfts1d_itype_veg gives you the PFT number for each PFT. +Most likely you'll want to do this analysis in a data processing tool (such as NCL, Matlab, Mathmatica, IDL, etcetera that is able to read and process NetCDF data files). diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst new file mode 100644 index 0000000000..8cf0916717 --- /dev/null +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst @@ -0,0 +1,109 @@ +.. customizing-the-datm-namelist: + +=============================== + Customizing the DATM namelist +=============================== + +When running "I" compsets with CLM you use the DATM model to give atmospheric forcing data to CLM. There are two ways to customize DATM: + +1. **DATM Main Namelist and Stream Namlist gorup** (``datm_in``) +2. **DATM stream files** + +The `Data Model Documentation `_ gives the details of all the options for the data models and for DATM specifically. +It goes into detail on all namelist items both for DATM and for DATM streams. +So here we won't list ALL of the DATM namelist options, nor go into great details about stream files. +But, we will talk about a few of the different options that are relevant for running with CLM. +All of the options for changing the namelists or stream files is done by editing the ``user_nl_datm`` file. + +Because, they aren't useful for work with CLM we will NOT discuss any of the options for the main DATM namelist. Use the DATM Users Guide at the link above to find details of that. For the streams namelist we will discuss three items: + +1. ``mapalgo`` +#. ``taxmode`` +#. ``tintalgo`` + +And for the streams file itself we will discuss: + +offset + Again everything else (and including the above items) are discussed in the Data Model User's Guide. Of the above the last three: offset, taxmode and tintalgo are all closely related and have to do with the time interpolation of the DATM data. + +mapalgo + ``mapalgo`` sets the spatial interpolation method to go from the DATM input data to the output DATM model grid. The default is ``bilinear``. For ``CLM1PT`` we set it to ``nn`` to just select the nearest neighbor. This saves time and we also had problems running the interpolation for single-point mode. + +taxmode + ``taxmode`` is the time axis mode. + For CLM we usually have it set to ``cycle`` which means that once the end of the data is reached it will start over at the beginning. + The extend modes is used have it use the last time-step of the forcing data once it reaches the end of forcing data (or use the first time-step before it reaches where the forcing data starts). See the warning below about the extend mode. + +.. warning:: *THE extend OPTION NEEDS TO BE USED WITH CAUTION!* It is only invoked by default for the CLM1PT mode and is only intended for the supported urban datasets to extend the data for a single time-step. If you have the model *run extensively through periods in this mode you will effectively be repeating that last time-step over that entire period*. This means the output of your simulation will be worthless. + +offset (in the stream file) + ``offset`` is the time offset in seconds to give to each stream of data. Normally it is NOT used because the time-stamps for data is set correctly for each stream of data. Note, the ``offset`` may NEED to be adjusted depending on the ``taxmode`` described above, or it may need to be adjusted to account for data that is time-stamped at the END of an interval rather than the middle or beginning of interval. The ``offset`` can is set in the stream file rather than on the stream namelist. For data with a ``taxmode`` method of ``coszen`` the time-stamp needs to be for the beginning of the interval, while for other data it should be the midpoint. The ``offset`` can be used to adjust the time-stamps to get the data to line up correctly. + +tintalgo + ``tintalgo`` is the time interpolation algorithm. For CLM we usually use one of three modes: ``coszen``, ``nearest``, or ``linear``. We use ``coszen`` for solar data, nearest for precipitation data, and linear for everything else. If your data is half-hourly or hourly, nearest will work fine for everything. The ``coszen`` scaling is useful for longer periods (three hours or more) to try to get the solar to match the cosine of the solar zenith angle over that longer period of time. If you use linear for longer intervals, the solar will cut out at night-time anyway, and the straight line will be a poor approximation of the cosine of the solar zenith angle of actual solar data. nearest likewise would be bad for longer periods where it would be much higher than the actual values. + +.. note:: For ``coszen`` the time-stamps of the data should correspond to the beginning of the interval the data is measured for. Either make sure the time-stamps on the datafiles is set this way, or use the ``offset`` described above to set it. + +.. note:: For nearest and linear the time-stamps of the data should correspond to the middle of the interval the data is measured for. Either make sure the time-stamps on the datafiles is set this way, or use the ``offset`` described above to set it. + +In the sections below we go over each of the relevant ``DATM_MODE`` options and what the above DATM settings are for each. This gives you examples of actual usage for the settings. We also describe in what ways you might want to customize them for your own case. + +-------------------------------------- +CLMCRUNCEP mode and it's DATM settings +-------------------------------------- + +In ``CLMCRUNCEP`` mode the CRUNCEP dataset is used and all of it's data is on a 6-hourly interval. +Like ``CLM_QIAN`` the dataset is divided into those three data streams: solar, precipitation, and everything else (temperature, pressure, humidity and wind). +The time-stamps of the data were also adjusted so that they are the beginning of the interval for solar, and the middle for the other two. +Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is: ``coszen``, ``nearest``, and ``linear`` for the solar, precipitation and other data respectively. +``taxmode`` is set to ``cycle`` and ``mapalgo`` is set to ``bilinear`` so that the data is spatially interpolated from the input exact half degree grid to the grid the atmosphere model is being run at (to run at this same model resolution use the 360x720cru_360x720cru resolution). + +.. note:: The "everything else" data stream (of temperature, pressure, humidity and wind) also includes the data for longwave downward forcing as well. Our simulations showed sensitivity to this field, so we backed off in using it, and let DATM calculate longwave down from the other fields. + +For more information on CRUNCEP forcing see `http://dods.extra.cea.fr/data/p529viov/cruncep/ `_. + +------------------------------------ +CLM_QIAN mode and it's DATM settings +------------------------------------ + +In ``CLM_QIAN`` mode the Qian dataset is used which has 6-hourly solar and precipitation data, and 3-hourly for everything else. +The dataset is divided into those three data streams: solar, precipitation, and everything else (temperature, pressure, humidity and wind). +The time-stamps of the data were also adjusted so that they are the beginning of the interval for solar, and the middle for the other two. +Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is: ``coszen``, ``nearest``, and ``linear`` for the solar, precipitation and other data respectively. +``taxmode`` is set to ``cycle`` and ``mapalgo`` is set to ``bilinear`` so that the data is spatially interpolated from the input T62 grid to the grid the atmosphere model is being run at. + +Normally you wouldn't customize the ``CLM_QIAN`` settings, but you might replicate it's use for your own global data that had similar temporal characteristics. + +---------------------------------- +CLM1PT mode and it's DATM settings +---------------------------------- + +In ``CLM1PT`` mode the model is assumed to have half-hourly or hourly data for a single-point. +For the supported datasets that is exactly what it has. +But, if you add your own data you may need to make adjustments accordingly. +Using the ``CLM_USRDAT_NAME`` resolution you can easily extend this mode for your own datasets that may be regional or even global and could be at different temporal frequencies. +If you do so you'll need to make adjustments to your DATM settings. +The dataset has all data in a single stream file. +The time-stamps of the data were also adjusted so that they are at the middle of the interval. +Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is set to ``nearest``. +``taxmode`` is set to ``extend`` and ``mapalgo`` is set to ``nn`` so that simply the nearest point is used. + +If you are using your own data for this mode and it's not at least hourly you'll want to adjust the DATM settings for it. If the data is three or six hourly, you'll need to divide it up into separate streams like in ``CLM_QIAN`` mode which will require fairly extensive changes to the DATM namelist and streams files. For an example of doing this see `Example 5-8 `_. + +---------------------------------------- +CPLHIST3HrWx mode and it's DATM settings +---------------------------------------- + +In ``CPLHIST3HrWx`` mode the model is assumed to have 3-hourly for a global grid from a previous CESM simulation. +Like ``CLM_QIAN`` mode the data is divided into three streams: one for precipitation, one for solar, and one for everything else. +The time-stamps for Coupler history files for CESM is at the end of the interval, so the ``offset`` needs to be set in order to adjust the time-stamps to what it needs to be for the ``tintalgo`` settings. +For precipitation ``taxmode`` is set to ``nearest`` so the ``offset`` is set to ``-5400`` seconds so that the ending time-step is adjusted by an hour and half to the middle of the interval. +For solar ``taxmode`` is set to ``coszen`` so the offset is set to ``-10800`` seconds so that the ending time-step is adjust by three hours to the beginning of the interval. +For everything else ``taxmode`` is set to ``linear`` so the offset is set to ``-5400`` seconds so that the ending time-step is adjusted by an hour and half to the middle of the interval. +For an example of such a case see `the Section called Running with MOAR data as atmospheric forcing to spinup the model in Chapter 4 `_. + + +Normally you wouldn't modify the DATM settings for this mode. +However, if you had data at a different frequency than 3-hours you would need to modify the ``offset`` and possibly the ``taxmode``. +The other two things that you might modify would be the path to the data or the domain file for the resolution (which is currently hardwired to f09). +For data at a different input resolution you would need to change the domain file in the streams file to use a domain file to the resolution that the data comes in on. diff --git a/doc/source/users_guide/setting-up-and-running-a-case/index.rst b/doc/source/users_guide/setting-up-and-running-a-case/index.rst new file mode 100644 index 0000000000..a9c1cb7d13 --- /dev/null +++ b/doc/source/users_guide/setting-up-and-running-a-case/index.rst @@ -0,0 +1,19 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _customizing_section: + +##################################### +Setting Up and Running a Case +##################################### + +.. toctree:: + :maxdepth: 2 + + choosing-a-compset.rst + customizing-the-clm-configuration.rst + customizing-the-clm-namelist.rst + customizing-the-datm-namelist.rst + diff --git a/doc/source/users_guide/testing/index.rst b/doc/source/users_guide/testing/index.rst new file mode 100644 index 0000000000..18c418fca4 --- /dev/null +++ b/doc/source/users_guide/testing/index.rst @@ -0,0 +1,18 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _testing: + +##################################### +Testing +##################################### + +.. toctree:: + :maxdepth: 2 + :numbered: + + testing.rst + + diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst new file mode 100644 index 0000000000..91db57fc70 --- /dev/null +++ b/doc/source/users_guide/testing/testing.rst @@ -0,0 +1,62 @@ +.. _testing: + +******* +Testing +******* + +Technically, you could use the customization we gave in `Chapter 1 `_ to test various configuration and namelist options for CLM. +Sometimes, it's also useful to have automated tests though to test that restarts give exactly the same results as without a restart. +It's also useful to have automated tests to run over a wide variety of configurations, resolutions, and namelist options. +To do that we have several different types of scripts set up to make running comprehensive testing of CLM easy. +There are two types of testing scripts for CLM. +The first are the CESM test scripts, which utilize the **create_newcase** scripts that we shown how to use in this User's Guide. +The second are a set of stand-alone scripts that use the CLM **configure** and **build-namelist** scripts to build and test the model as well as testing the CLM tools as well. +Below we will go into further details of how to use both methods. + + +CIME Testing scripts +==================== + +We first introduce the test scripts that work for all CESM components. +The CIME script **create_test** runs a specific type of test, at a given resolution, for a given compset using a given machine. +There is a list of different tests, but the "ERI" tests do several things at once, running from startup, as well as doing exact branch and restart tests. +So to run "ERI" testing at 2-degree with the I1850CRUCLM45 compset on yellowstone_intel you do the following. +:: + + > cd scripts + > ./create_test -testname ERI.f19_g16.I1850CRUCLM45.yellowstone_intel + > cd ERI.f19_g16.I1850CRUCLM45.yellowstone_intel.$id + > ./ERI.f19_g16.I1850CRUCLM45.yellowstone_intel.$id.build + > ERI.f19_g16.I1850CRUCLM45.yellowstone_intel.$id.submit + +When the test is done it will update the file TestStatus with either a PASS or FAIL message. + +We already have a standard list of tests for clm (the "aux_clm" list of tests). To run the CLM yellowstone intel compiler test list, for the same machine and compiler you would do the following: +:: + + > cd scripts + > ./create_test -xml_mach yellowstone -xml_compiler intel -xml_category aux_clm -mach yellowstone -compiler intel + # Normally it will submit the jobs as they are ready, but if it's interrupted you + # may need to submit by hand as follows... + # Submit the suite of tests (note $id refers to the integer job number for this job) + > ./cs.submit.$id.yellowstone + # Later check the tests with... + > ./cs.status.$id + # The above will give a PASS or FAIL message for each test. + +For more information on doing testing with the CESM scripts see the `CESM1.2.0 User's Guide `_ on testing. + +Testing PTCLM +============= + +There is a simple test script for PTCLM called ``testcases.csh`` in the PTCLM directory (``scripts/ccsm_utils/Tools/lnd/clm/PTCLM``). +The test script is setup to run on the machines: yellowstone, frankfurt, yong, and titan. +You simply run the script interactively. +The script will write out the status of tests to a file called: ``tc.job#.status``. + +There are a few environment variables that can be used with ``testcases.csh`` to change it's operation. + +``CESM_ROOT``: To test with a separate root to CESM code set this env variable to the root directory to use. +``CLM_SOFF``: If set to ``TRUE`` - stop on first failed test rather than continuing to run. +``CLM_RETAIN_FILES``: If set to ``FALSE`` - cleanup tools build first. +``DEBUG``: If set to ``TRUE`` - setup cases, but do not build or run. diff --git a/doc/source/users_guide/trouble-shooting/index.rst b/doc/source/users_guide/trouble-shooting/index.rst new file mode 100644 index 0000000000..f4c6d813fc --- /dev/null +++ b/doc/source/users_guide/trouble-shooting/index.rst @@ -0,0 +1,15 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _troubleshooting: + +##################################### +Troubleshooting +##################################### + +.. toctree:: + :maxdepth: 2 + + trouble-shooting.rst diff --git a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst new file mode 100644 index 0000000000..5a2fb07192 --- /dev/null +++ b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst @@ -0,0 +1,395 @@ +.. _trouble-shooting: + +********************* +Trouble Shooting +********************* + +In this chapter we give some guidance on what to do when you encounter some of the most common problems. We can't cover all the problems that a user could potentially have, but we will try to help you recognize some of the most common situations. And we'll give you some suggestions on how to approach the problem to come up with a solution. + +In general you will run into one of three type of problems: + +1. *setup-time* +#. *build-time* +#. *run-time* + + +Setup Problems +============== + +The first type of problem happens when you invoke the **case.setup** command. +This indicates there is something wrong with your input datasets, or the details of what you are trying to setup the model to do. +There's also a trouble-shooting chapter in the `CESM1.2.0 Scripts User's Guide `_. +Many of the problems with configuration can be resolved with the guidelines given there. +Here we will restrict ourselves to problems from the input files. + +Example: Missing datasets +---------------------------------------------------------------- +:: + + > ./create_newcase -case ne60rcp6 -res ne60_g16 -compset IRCP60CN \ + -mach yellowstone_intel + > ./case.setup + +The following is what is displayed to the screen. +:: + + . + . + . + Running preview_namelist script + CLM configure done. + CLM adding use_case 1850-2100_rcp6_transient defaults for var clm_demand with val fpftdyn + CLM adding use_case 1850-2100_rcp6_transient defaults for var clm_start_type with val startup + CLM adding use_case 1850-2100_rcp6_transient defaults for var model_year_align_ndep with val 1850 + CLM adding use_case 1850-2100_rcp6_transient defaults for var rcp with val 6 + CLM adding use_case 1850-2100_rcp6_transient defaults for var sim_year with val 1850 + CLM adding use_case 1850-2100_rcp6_transient defaults for var sim_year_range with val 1850-2100 + CLM adding use_case 1850-2100_rcp6_transient defaults for var stream_year_first_ndep with val 1850 + CLM adding use_case 1850-2100_rcp6_transient defaults for var stream_year_last_ndep with val 2100 + CLM adding use_case 1850-2100_rcp6_transient defaults for var use_case_desc with val Simulate transient land-use, aerosol and Nitrogen deposition changes + with historical data from 1850 to 2005 and then with the RCP6 scenario from AIM + + build-namelist - No default value found for fpftdyn. + Are defaults provided for this resolution and land mask? + ERROR: clm.buildnml.csh failed + ERROR: /Users/erik/clm_cesm1_1_1_rel/scripts/ne60rcp6/preview_namelists failed: 25344 + +The important thing to note here is the line: +:: + + ERROR: clm.buildnml.csh failed + +which tells us that the problem is in the land **clm.buildnml.csh**. It may also indicate problems in one of the other buildnml.csh files (atm, cesm, cpl, glc, ice, or ocn), in which case you should consult the appropriate model user's guide. + +In the example, the error is that the CLM XML database does NOT have a ``finidat`` for the given resolution, rcp scenario and ocean mask. That means you will need to create the file and then supply the file into your case. See `Chapter 2 `_ for more information on creating files, and see `Chapter 3 `_ for more information on adding files to the XML database. Alternatively, you can provide the file to your case by creating a user namelist as shown in `the Section called User Namelist in Chapter 1 `_. + +.. note:: The two most common problems from your **clm.buildnml.csh** will be errors from the CLM **configure** or **build-namelist**. For more information on these scripts see: `the Section called More information on the CLM configure script in Chapter 1 `_ and `the section on CLM_BLDNML_OPTS `_. + + +Build problems +================ + +The following is an example of running the build for a case and having it fail in the land model build. +As you can see it lists which model component is being built and the build log for that component. +:: + + CCSM BUILDEXE SCRIPT STARTING + - Build Libraries: mct pio csm_share + Sat Jun 19 21:21:19 MDT 2010 /ptmp/erik/test_build/mct/mct.bldlog.100619-212107 + Sat Jun 19 21:22:18 MDT 2010 /ptmp/erik/test_build/pio/pio.bldlog.100619-212107 + Sat Jun 19 21:23:18 MDT 2010 + /ptmp/erik/test_build/csm_share/csm_share.bldlog.100619-212107 + Sat Jun 19 21:24:00 MDT 2010 /ptmp/erik/test_build/run/cpl.bldlog.100619-212107 + Sat Jun 19 21:24:00 MDT 2010 /ptmp/erik/test_build/run/atm.bldlog.100619-212107 + Sat Jun 19 21:24:06 MDT 2010 /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 + ERROR: clm.buildexe.csh failed, see /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 + ERROR: cat /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 + +You can then examine the build log that failed and see what went wrong. Most compilers will give the full filepath and line number for the file that filed to compile. + +Run Time Problems +================= + +Tracking down problems while the model is running is much more difficult to do than setup or build problems. +In this section we will give some suggestions on how to find run time problems. +Below we show the log file results of a job that aborted while running. +:: + + CCSM PRESTAGE SCRIPT HAS FINISHED SUCCESSFULLY + Sun Jun 20 18:24:06 MDT 2010 -- CSM EXECUTION BEGINS HERE + Sun Jun 20 18:24:35 MDT 2010 -- CSM EXECUTION HAS FINISHED + Model did not complete - see /ptmp/erik/test_run/run/cpl.log.100620-182358 + +In the next section we will talk about using the different log files to track down problems, and find out where the problem is coming from. In the section after that we give some general advice on debugging problems and some suggestions on ideas that may be helpful to track the problem down. Some of the examples below are from the `models/lnd/clm/doc/KnownBugs `_ file. + +Tracking Problems by Querying Log Files +--------------------------------------- + +The first thing to do when tracking down problems is to query the different log files to see if you can discover where the problem occurs, and any error messages about it. +It's important to figure out if the problem comes in at initialization or in the run phase of the model, and in which model component the problem happens. +There are different log files for the different major components, and they all end with the date and time in YYMMDD-HHMMSS format (2-digit: year, month, day, hour minute and second). +When the model runs to completion the log files will be copied to the logs directory in the script directory, but when the model fails they will remain in the run directory. +Here's an example list of log files from an "I" case where the model dies in the land model initialization. +For "I" cases the sea-ice and ocean components are just stubs and don't create log files (and unless running with the active land-ice model "glc" log files won't be created either). +:: + + atm.log.100620-182358 + cesm.log.100620-182358 + cpl.log.100620-182358 + lnd.log.100620-182358 + +The coupler log file +-------------------- + +The first log file to check is the coupler log file so that you can see where the model dies and which model component it fails in. When the model dies at initialization the last model component listed is the component that failed. + +Example of a case that fails in the CLM land model initialization. +:: + + (seq_timemgr_clockPrint) Prev Time = 00001201 00000 + (seq_timemgr_clockPrint) Next Time = 99991201 00000 + (seq_timemgr_clockPrint) Intervl yms = 9999 0 0 + + (seq_mct_drv) : Initialize each component: atm, lnd, ocn, and ice + (seq_mct_drv) : Initialize atm component + (seq_mct_drv) : Initialize lnd component + +The cesm log file +----------------- + +The cesm log files are to some extent the "garbage collection" of log output. +The CLM sends it's output from it's master processor, but sends other output and possibly errors to the cesm log file. +Because, of this, often error messages are somewhere in the cesm log file. +However, since there is so much other output it may be difficult to find. +For example, here is some output from an older version of CESM (CESM1.0.2) where the RTM river routing file (before it was converted to NetCDF) was not provided and the error on the open statement for the file was embedded near the end of the cesm log file. +:: + + NODE# NAME + ( 0) be1105en.ucar.edu + "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/lnd/clm/src/riverroute/RtmMod.F90", line + 239: 1525-155 The file name provided in the OPEN statement for unit 1 has zero length or + contains all blanks. The program will recover by ignoring the OPEN statement. + "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/lnd/clm/src/riverroute/RtmMod.F90", line + 241: 1525-001 The READ statement on the file fort.1 cannot be completed because the end + of the file was reached. The program will stop. + + Running: ./cesm.exe + Please wait... + + Memory usage for ./cesm.exe (task # 0) is: 51696 KB. Exit status: 1. Signal: 0 + +Although the example is from an earlier version of the model it still serves to illustrate finding problems from the cesm log file. + +When working with the cesm log file, for a run-time problem, you will need to be able to separate it's output into three categories: pre-crash, crash, and post-crash. +The pre-crash section is everything that is normal output for good operation of the model. +The crash section is the section where the model dies and reports on the actual problem. +the post-crash section is the cleanup and finalization after the model dies. +The most important part of this of course is the crash section. +The tricky part is distinguishing it from the other sections. +Also because the cesm log file most likely has duplicated output from multiple processors it is even more difficult to distinguish the different sections and to some extent the sections may be intertwined, as different processors reach the different sections at different times. +Because, of this reducing the number of processors for your simulation may help you sort out the output in the file (see `the Section called Run with a smaller set of processors `_). +Also much of the output from the cesm log file are system level information having to do with MPI multiprocessing. +Usually you can ignore this information, but it makes it more difficult to trudge through. + + +Sometimes the cesm log file is the ONLY file available, because the model terminates early in initialization. +In this case understanding the output in the cesm log file becomes even more important. +This also indicates the model did NOT advance far enough to reach the initialization of the individual model components. +This may mean that the initialization of the multiprocessing for MPI and/or OpenMP failed, or that the reading of the driver namelist file "drv_in" failed. + + +Here we show those three sections for a cesm log file where a two task job failed on reading the namelist file. +For a typical job with many tasks similar sections of this will be repeated not just twice but for each task and hence make it harder to read. + + +*Pre-crash section of the cesm log file* +:: + + ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. + + ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. + ATTENTION: 0031-378 MP_EUIDEVICE setting ignored when LoadLeveler is not being used. + ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. + 0:INFO: 0031-724 Executing program: + 1:INFO: 0031-724 Executing program: + 0:/contrib/bin/cesm_launch: process 401894 bound to logical CPU 0 on host be0310en.ucar.edu ... + 1:/contrib/bin/cesm_launch: process 439264 bound to logical CPU 1 on host be0310en.ucar.edu ... + 0:INFO: 0031-619 64bit(us, Packet striping on) ppe_rmas MPCI_MSG: MPI/MPCI library was compiled on Wed Aug 5 13:36:06 2009 + 0: + 1:LAPI version #14.26 2008/11/23 11:02:30 1.296 src/rsct/lapi/lapi.c, lapi, rsct_rpt53, rpt53s004a 09/04/29 64bit(us) library compiled on Wed Apr 29 15:30:42 2009 + 1:. + 1:LAPI is using lightweight lock. + 0:LAPI version #14.26 2008/11/23 11:02:30 1.296 src/rsct/lapi/lapi.c, lapi, rsct_rpt53, rpt53s004a 09/04/29 64bit(us) library compiled on Wed Apr 29 15:30:42 2009 + 0:. + 0:LAPI is using lightweight lock. + 0:Use health ping for failover/recovery + 1:Use health ping for failover/recovery + 0:Initial communication over instance 2. + 1:Initial communication over instance 0. + 1:IB RDMA initialization completed successfully + 1:The MPI shared memory protocol is used for the job + 0:IB RDMA initialization completed successfully + 0:LAPI job ID for this job is: 1684890719 + 0:The MPI shared memory protocol is used for the job + 0:(seq_comm_setcomm) initialize ID ( 7 GLOBAL ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_setcomm) initialize ID ( 2 ATM ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_setcomm) initialize ID ( 1 LND ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_setcomm) initialize ID ( 4 ICE ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_setcomm) initialize ID ( 5 GLC ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_setcomm) initialize ID ( 3 OCN ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_setcomm) initialize ID ( 6 CPL ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_joincomm) initialize ID ( 8 CPLATM ) join IDs = 6 2 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_joincomm) initialize ID ( 9 CPLLND ) join IDs = 6 1 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_joincomm) initialize ID ( 10 CPLICE ) join IDs = 6 4 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_joincomm) initialize ID ( 11 CPLOCN ) join IDs = 6 3 ( npes = 2) ( nthreads = 1) + 0:(seq_comm_joincomm) initialize ID ( 12 CPLGLC ) join IDs = 6 5 ( npes = 2) ( nthreads = 1) + 0: + 0: (seq_comm_printcomms) ID layout : global pes vs local pe for each ID + 0: gpe LND ATM OCN ICE GLC CPL GLOBAL CPLATM CPLLND CPLICE CPLOCN CPLGLC nthrds + 0: --- ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ + 0: 0 : 0 0 0 0 0 0 0 0 0 0 0 0 1 + 1: 1 : 1 1 1 1 1 1 1 1 1 1 1 1 1 + 1: + 0: (t_initf) Read in prof_inparm namelist from: drv_in + 1: (seq_io_init) cpl_io_stride, iotasks or root out of bounds - resetting to defaults 4 0 1 + 0: piolib_mod.f90 1353 1 2 1 2 + 1: piolib_mod.f90 1353 1 2 1 2 + 0: pio_support::pio_die:: myrank= 0 : ERROR: piolib_mod.f90: 1354 : not enough procs for the stride + 1: pio_support::pio_die:: myrank= 1 : ERROR: piolib_mod.f90: 1354 : not enough procs for the stride + +*Crash section of the cesm log file* +:: + + 0: + 0: Traceback: + 1: + 1: Traceback: + 0: Offset 0x00000c4c in procedure __pio_support_NMOD_piodie, near line 88 in file pio_support.F90.in + 1: Offset 0x00000c4c in procedure __pio_support_NMOD_piodie, near line 88 in file pio_support.F90.in + 0: Offset 0x00000fd0 in procedure __piolib_mod_NMOD_init, near line 1354 in file piolib_mod.F90 + 1: Offset 0x00000fd0 in procedure __piolib_mod_NMOD_init, near line 1354 in file piolib_mod.F90 + 1: Offset 0x00000398 in procedure __seq_io_mod_NMOD_seq_io_init, near line 247 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/shr/seq_io_mod.F90 + 0: Offset 0x00000398 in procedure __seq_io_mod_NMOD_seq_io_init, near line 247 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/shr/seq_io_mod.F90 + 0: Offset 0x0001aa88 in procedure ccsm_driver, near line 465 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/driver/ccsm_driver.F90 + 0: --- End of call chain --- + 1: Offset 0x0001aa88 in procedure ccsm_driver, near line 465 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/driver/ccsm_driver.F90 + 1: --- End of call chain --- + +*Post-crash section of the cesm log file* +:: + + 1:Communication statistics of task 1 is associated with task key: 1684890719_1 + 0:Communication statistics of task 0 is associated with task key: 1684890719_0 + 0: + 0:Running: ./cesm.exe + 0:Please wait... + 0: + 0:Memory usage for ./cesm.exe (task # 0) is: 198892 KB. Exit status: 134. Signal: 0 + 1: + 1:Running: ./cesm.exe + 1:Please wait... + 1: + 1:Memory usage for ./cesm.exe (task # 0) is: 198572 KB. Exit status: 134. Signal: 0 + INFO: 0031-656 I/O file STDOUT closed by task 0 + INFO: 0031-656 I/O file STDERR closed by task 0 + ERROR: 0031-250 task 0: IOT/Abort trap + INFO: 0031-656 I/O file STDOUT closed by task 1 + INFO: 0031-656 I/O file STDERR closed by task 1 + ERROR: 0031-250 task 1: IOT/Abort trap + INFO: 0031-639 Exit status from pm_respond = 0 + ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. + Job /usr/local/lsf/7.0/aix5-64/bin/poejob /contrib/bin/ccsm_launch /contrib/bin/job_memusage.exe ./cesm.exe + + TID HOST_NAME COMMAND_LINE STATUS TERMINATION_TIME + ===== ========== ================ ======================= =================== + 00000 be0310en /contrib/bin/ccs Exit (134) 08/31/2010 12:32:57 + 00001 be0310en /contrib/bin/ccs Exit (134) 08/31/2010 12:32:57 + +The CLM log file +---------------- + +Of course when you are working with and making changes to CLM, most of your focus will be on the CLM log file and the errors it shows. +As already pointed out if you don't see errors in the ``lnd.log.*`` file you should look in the ``cesm.log.*`` to see if any errors showed up there. + +Here's an example of the ``lnd.log.*`` file when running ``PTS_MODE`` with initial conditions (this is bug 1025 in the `models/lnd/clm/doc/KnownLimitationss `_ file). +:: + + Successfully initialized variables for accumulation + + reading restart file I2000CN_f09_g16_c100503.clm2.r.0001-01-01-00000.nc + Reading restart dataset + ERROR - setlatlon.F:Cant get variable dim for lat or lsmlat + ENDRUN: called without a message string + +The DATM log file +----------------- + +When working with "I cases" the second most common problems after CLM problems are problems with the data atmosphere model. So examining the ``atm.log.*`` is important. + +Here's an example of a problem that occurs when the wrong prescribed aerosol file is given to a ``pt1_pt1`` simulation. +:: + + (datm_comp_init) atm mode = CLMNCEP + (shr_strdata_init) calling shr_dmodel_mapSet for fill + (shr_strdata_init) calling shr_dmodel_mapSet for remap + ('shr_map_getWts') ERROR: yd outside bounds 19.5000000000000000 + (shr_sys_abort) ERROR: ('shr_map_getWts') ERROR yd outside 90 degree bounds + (shr_sys_abort) WARNING: calling shr_mpi_abort() and stopping + +The batch log files +------------------- + +The names of the batch log files will depend on the batch system of the machine that is being used. They will normally be in the script directory. Usually, they don't contain important information, but they are a last resort place to look for error messages. On the NCAR system "yellowstone" the batch files are called with names that start with the batch submission script and then either "stderr.o" or "stdout.o", with the job number at the end. + +General Advice on Debugging Run time Problems +============================================= + +Here are some suggestions on how to track down a problem while running. In general if the problem still occurs for a simpler case, it will be easier to track down. + +1. *Run in DEBUG mode* +#. *Run with a smaller set of processors* +#. *Run in serial mode with a single processor* +#. *Run at a lower resolution* +#. *Run a simpler case* +#. *Run with a debugger* + +Run in DEBUG mode +----------------- + +The first thing to try is to run in DEBUG mode so that float point trapping will be triggered as well as array bounds checking and other things the compiler can turn on to help you find problems. +To do this edit the ``env_build.xml`` file and set DEBUG to TRUE as follows: +:: + + > ./xmlchange DEBUG=TRUE + + +Run with a smaller set of processors +------------------------------------ + +Another way to simplify the system is to run with a smaller set of processors. You will need to clean the setup and edit the --env_mach_pes.xml--. For example, to run with four processors: +:: + + > ./case.setup -clean + > ./xmlchange NTASKS_ATM=4,NTASKS_LND=4,NTASKS_ICE=4,NTASKS_OCN=4,NTASKS_CPL=4,NTASKS_GLC=4 + > ./case.setup + +Another recommended simplification is to run without threading, so set the NTHRDS for each component to "1" if it isn't already. Sometimes, multiprocessing problems require a certain number of processors before they occur so you may not be able to debug the problem without enough processors. But, it's always good to reduce it to as low a number as possible to make it simpler. For threading problems you may have to have threading enabled to find the problem, but you can run with 1, 2, or 3 threads to see what happens. + +Run in serial mode with a single processor +------------------------------------------ + +Simplifying to one processor removes all multi-processing problems and makes the case as simple as possible. If you can enable ``MPILIB=mpi-serial`` you will also be able to run interactively rather than having to submit to a job queue, which sometimes makes it easier to run and debug. If you can use ``MPILIB=mpi-serial`` you can also use threading, but still run interactively in order to use more processors to make it faster if needed. +:: + + > ./case.setup -clean + # Set tasks and threads for each component to 1 + # You could also set threads to something > 1 for speed, but still + # run interactively if threading isn't an issue. + + > ./xmlchange NTASKS_ATM=1,NTHRDS_ATM=1,NTASKS_LND=1,NTHRDS_LND=1,NTASKS_ICE=1,NTHRDS_ICE=1 + > ./xmlchange NTASKS_OCN=1,NTHRDS_OCN=1,NTASKS_CPL=1,NTHRDS_CPL=1,NTASKS_GLC=1,NTHRDS_GLC=1 + # set MPILIB to mpi-serial so that you can run interactively + > ./xmlchange MPILIB=mpi-serial + > ./case.setup + # Then build your case + # And finally run, by running the *.run script interactively + +Run at a lower resolution +------------------------- + +If you can create a new case running at a lower resolution and replicate the problem it may be easier to solve. This of course requires creating a whole new case, and trying out different lower resolutions. + +Run a simpler case +------------------ + +Along the same lines, you might try running a simpler case, trying another compset with a simpler setup and see if you can replicate the problem and then debug from that simpler case. Again, of course you will need to create new cases to do this. + +Run with a debugger +------------------- + +Another suggestion is to run the model with a debugger such as: **dbx**, **gdb**, or **totalview**. +Often to run with a debugger you will need to reduce the number of processors as outlined above. +Some debuggers such as **dbx** will only work with one processor, while more advanced debuggers such as **totalview** can work with both MPI tasks and OMP threads. +Even simple debuggers though can be used to query core files, to see where the code was at when it died (for example using the **where** in **dbx** for a core file can be very helpful. +For help in running with a debugger you will need to contact your system administrators for the machine you are running on. + diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst new file mode 100644 index 0000000000..c2633e6522 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -0,0 +1,162 @@ +======================== + Building the CLM tools +======================== + +The FORTRAN tools all have similar makefiles, and similar options for building. +All of the Makefiles use GNU Make extensions and thus require that you use GNU make to use them. +They also auto detect the type of platform you are on, using "uname -s" and set the compiler, compiler flags and such accordingly. +There are also environment variables that can be set to set things that must be customized. +All the tools use NetCDF and hence require the path to the NetCDF libraries and include files. +On some platforms (such as Linux) multiple compilers can be used, and hence there are env variables that can be set to change the FORTRAN and/or "C" compilers used. +The tools other than cprnc also allow finer control, by also allowing the user to add compiler flags they choose, for both FORTRAN and "C", as well as picking the compiler, linker and and add linker options. +Finally the tools other than **cprnc** allow you to turn optimization on (which is off by default but on for the **mksurfdata_map** and **interpinic** programs) with the OPT flag so that the tool will run faster. +To get even faster performance, the **interpinic**, program allows you to also use the SMP to turn on multiple shared memory processors. +When ``SMP=TRUE`` you set the number of threads used by the program with the ``OMP_NUM_THREADS`` environment variable. + +Options used by all: **cprnc**, **interpinic**, and **mksurfdata_map** + +- ``LIB_NETCDF`` -- sets the location of the NetCDF library. +- ``INC_NETCDF`` -- sets the location of the NetCDF include files. +- ``USER_FC`` -- sets the name of the FORTRAN compiler. + +Options used by: **interpinic**, **mkprocdata_map**, **mkmapgrids**, and **mksurfdata_map** + +- ``MOD_NETCDF`` -- sets the location of the NetCDF FORTRAN module. +- ``USER_LINKER`` -- sets the name of the linker to use. +- ``USER_CPPDEFS`` -- adds any CPP defines to use. +- ``USER_CFLAGS`` -- add any "C" compiler flags to use. +- ``USER_FFLAGS`` -- add any FORTRAN compiler flags to use. +- ``USER_LDFLAGS`` -- add any linker flags to use. +- ``USER_CC`` -- sets the name of the "C" compiler to use. +- ``OPT`` -- set to TRUE to compile the code optimized (TRUE or FALSE) +- ``SMP`` -- set to TRUE to turn on shared memory parallelism (i.e. OpenMP) (TRUE or FALSE) +- ``Filepath`` -- list of directories to build source code from. +- ``Srcfiles`` -- list of source code filenames to build executable from. +- ``Makefile`` -- customized makefile options for this particular tool. +- ``mkDepends`` -- figure out dependencies between source files, so make can compile in order.. +- ``Makefile.common`` -- General tool Makefile that should be the same between all tools. + +Options used only by **cprnc**: + +- ``EXEDIR`` -- sets the location where the executable will be built. +- ``VPATH`` -- colon delimited path list to find the source files. + +More details on each environment variable. + +``LIB_NETCDF`` + This variable sets the path to the NetCDF library file (``libnetcdf.a``). If not set it defaults to ``/usr/local/lib``. In order to use the tools you need to build the NetCDF library and be able to link to it. In order to build the model with a particular compiler you may have to compile the NetCDF library with the same compiler (or at least a compatible one). + +``INC_NETCDF`` + This variable sets the path to the NetCDF include directory (in order to find the include file ``netcdf.inc``). if not set it defaults to ``/usr/local/include``. + +``MOD_NETCDF`` + This variable sets the path to the NetCDF module directory (in order to find the NetCDF FORTRAN-90 module file when NetCDF is used with a FORTRAN-90 **use statement**. When not set it defaults to the ``LIB_NETCDF`` value. + +``USER_FC`` + This variable sets the command name to the FORTRAN-90 compiler to use when compiling the tool. The default compiler to use depends on the platform. And for example, on the AIX platform this variable is NOT used + +``USER_LINKER`` + This variable sets the command name to the linker to use when linking the object files from the compiler together to build the executable. By default this is set to the value of the FORTRAN-90 compiler used to compile the source code. + +``USER_CPPDEFS`` + This variable adds additional optional values to define for the C preprocessor. Normally, there is no reason to do this as there are very few CPP tokens in the CLM tools. However, if you modify the tools there may be a reason to define new CPP tokens. + +``USER_CC`` + This variable sets the command name to the "C" compiler to use when compiling the tool. The default compiler to use depends on the platform. And for example, on the AIX platform this variable is NOT used + +``USER_CFLAGS`` + This variable adds additional compiler options for the "C" compiler to use when compiling the tool. By default the compiler options are picked according to the platform and compiler that will be used. + +``USER_FFLAGS`` + This variable adds additional compiler options for the FORTRAN-90 compiler to use when compiling the tool. By default the compiler options are picked according to the platform and compiler that will be used. + +``USER_LDFLAGS`` + This variable adds additional options to the linker that will be used when linking the object files into the executable. By default the linker options are picked according to the platform and compiler that is used. + +``SMP`` + This variable flags if shared memory parallelism (using OpenMP) should be used when compiling the tool. It can be set to either TRUE or FALSE, by default it is set to FALSE, so shared memory parallelism is NOT used. When set to TRUE you can set the number of threads by using the OMP_NUM_THREADS environment variable. Normally, the most you would set this to would be to the number of on-node CPU processors. Turning this on should make the tool run much faster. + +.. warning:: Note, that depending on the compiler answers may be different when SMP is activated. + +``OPT`` + This variable flags if compiler optimization should be used when compiling the tool. It can be set to either ``TRUE`` or ``FALSE``, by default it is set to ``FALSE`` for **mkmapgrids** and ``TRUE`` for **mksurfdata_map**, **mkprocdata_map** and **interpinic**. Turning this on should make the tool run much faster. + +.. warning:: Note, you should expect that answers will be different when ``OPT`` is activated. + +``Filepath`` + All of the tools are stand-alone and don't need any outside code to operate. The Filepath is the list of directories needed to compile and hence is always simply "." the current directory. Several tools use copies of code outside their directory that is in the CESM distribution (either ``csm_share`` code or CLM source code). + +``Srcfiles`` + The ``Srcfiles`` lists the filenames of the source code to use when building the tool. + +``Makefile`` + The ``Makefile`` is the custom GNU Makefile for this particular tool. It will customize the ``EXENAME`` and the optimization settings for this particular tool. + +``Makefile.common`` + The ``Makefile.common`` is the copy of the general GNU Makefile for all the CLM tools. This file should be identical between the different tools. This file has different sections of compiler options for different Operating Systems and compilers. + +``mkDepends`` + The ``mkDepends`` is the copy of the perl script used by the ``Makefile.common`` to figure out the dependencies between the source files so that it can compile in the necessary order. This file should be identical between the different tools. + +``EXEDIR`` + The cprnc tool uses this variable to set the location of where the executable will be built. The default is the current directory. + +``VPATH`` + The **cprnc** tool uses this variable to set the colon delimited pathnames of where the source code exists. The default is the current directory. + +.. note:: There are several files that are copies of the original files from either models``/lnd/clm/src/util_share``, ``models/csm_share/shr``, or copies from other tool directories. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well. + +The *README.filecopies* (which can be found in ``models/lnd/clm/tools``) is repeated here. +:: + + models/lnd/clm/tools/README.filecopies Jun/04/2013 + + There are several files that are copies of the original files from + either models/lnd/clm/src/main, models/csm_share/shr, + models/csm_share/unit_testers, or copies from other tool + directories. By having copies the tools can all be made stand-alone, + but any changes to the originals will have to be put into the tool + directories as well. + + I. Files that are IDENTICAL: + + 1. csm_share files copied that should be identical to models/csm_share/shr: + + shr_const_mod.F90 + shr_log_mod.F90 + shr_timer_mod.F90 + + 2. csm_share files copied that should be identical to models/csm_share/unit_testers: + + test_mod.F90 + + 3. clm/src files copied that should be identical to models/lnd/clm/src/util_share: + + nanMod.F90 + + II. Files with differences + + 1. csm_share files copied with differences: + + shr_kind_mod.F90 --- SHR_KIND_CXX is new + shr_sys_mod.F90 ---- Remove mpi abort and reference to shr_mpi_mod.F90. + shr_infnan_mod.F90 - Earlier version + shr_string_mod.F90 - Earlier version + shr_file_mod.F90 --- mkprocdata_map version is stripped down + clm_varctl.F90 ----- Earlier version + + 2. clm/src files with differences: + + fileutils.F90 --- Remove use of masterproc and spmdMod and endrun in abortutils. + + 4. Files in mkmapgrids + + domainMod.F90 ---- Highly customized based off an earlier version of clm code. + Remove use of abortutils, spmdMod. clm version uses latlon + this version uses domain in names. Distributed memory + parallelism is removed. + + 5. Files in mksurfdata_map + + mkvarpar.F90 --- clm4_0 and clm4_5 versions are different and different from main clm versions. + diff --git a/doc/source/users_guide/using-clm-tools/cprnc.rst b/doc/source/users_guide/using-clm-tools/cprnc.rst new file mode 100644 index 0000000000..e921858b4c --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/cprnc.rst @@ -0,0 +1,29 @@ +.. comparing-history-files: + +========================= + Comparing History Files +========================= + +**cprnc** is a tool shared by both CAM and CLM to compare two NetCDF history files. +It differences every field that has a time-axis that is also shared on both files, and reports a summary of the difference. +The summary includes the three largest differences, as well as the root mean square (RMS) difference. +It also gives some summary information on the field as well. +You have to enter at least one file, and up to two files. +With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. +At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. + +Options: + +-m = do NOT align time-stamps before comparing + +-v = verbose output + +-ipr + +-jpr + +-kpr + +See the **cprnc** `README `_ file for more details. + +.. note:: To compare files with OUT a time axis you can use the **cprnc.ncl** NCL script in ``models/lnd/clm/tools/shared/ncl_scripts``. It won't give you the details on the differences but will report if the files are identical or different. diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst new file mode 100644 index 0000000000..6d4ec7bc12 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -0,0 +1,27 @@ +.. _creating-domain-files: + +***************************** + Creating CLM domain files +***************************** + +*gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH DATM AND CLM to define the grid and land-mask. The general data flow is shown in two figures. `Figure 2-4 `_ shows the general flow for a general global case (or for a regional grid that DOES include ocean). `Figure 2-5 `_ shows the use of **mknoocnmap.pl** (see `the Section called Using mknocnmap.pl to create grid and maps for single-point regional grids `_) to create a regional or single-point map file that is then run through **gen_domain** to create the domain file for it. As stated before `Figure 2-2 `_ is the legend for both of these figures. See `the +tools/mapping/gen_domain_files/README `_ file for more help on **gen_domain**. + +Here we create domain files for a regular global domain. + +Figure 2-4. Global Domain file creation +======================================= + +Insert figure 2-4 + +Starting from SCRIP grid files for both your atmosphere and ocean, you use **tools/mapping/gen_mapping_files/gen_cesm_maps.sh** to create a mapping file between the atmosphere and ocean. That mapping file is then used as input to **gen_domain** to create output domain files for both atmosphere and ocean. The atmosphere domain file is then used by both CLM and DATM for I compsets, while the ocean domain file is ignored. For this process you have to define your SCRIP grid files on your own. For a regional or single-point case that doesn't include ocean see `Figure 2-5 `_. (See `Figure 2-2 `_ for the legend for this figure.) + +Note, that the SCRIP grid file used to start this process, is also used in **mkmapdata.sh** (see `the Section called Creating mapping files that mksurfdata_map will use `_). Next we create domain files for a single-point or regional domain. + +Figure 2-5. Domain file creation using mknoocnmap.pl +==================================================== +Insert figure 2-5 + +For a regular latitude/longitude grid that can be used for regional or single point simulations -- you can use **mknoocnmap.pl**. It creates a SCRIP grid file that can then be used as input to **mkmapdata.sh** as well as a SCRIP mapping file that is then input to **gen_domain**. The output of **gen_domain** is a atmosphere domain file used by both CLM and DATM and a ocean domain file that is ignored. (See `Figure 2-2 `_ for the legend for this figure.) + +In this case the process creates both SCRIP grid files to be used by **mkmapdata.sh** as well as the domain files that will be used by both CLM and DATM. diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst new file mode 100644 index 0000000000..332aa5bd65 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -0,0 +1,116 @@ +.. _creating-maps-for-mksurfdata: + +********************************************* +Creating input for surface dataset generation +********************************************* + +1. Generating SCRIP grid files +================================== + +The utility ``mkmapdata.sh`` requires SCRIP format input files to describe the input and output grids that maps are generated for. CLM provides a utility, ``mkmapgrids`` that generates those files. +The program converts old formats of CAM or CLM grid files to SCRIP grid format. There is also a NCL script (``mkscripgrid.ncl``) to create regular latitude longitude regional or single-point grids at the resolution the user desires. + +SCRIP grid files for all the standard model resolutions and the raw surface datasets have already been done and the files are in the XML database. Hence, this step doesn't need to be done -- EXCEPT WHEN YOU ARE CREATING YOUR OWN GRIDS. If you have a CLM grid or CAM file from previous versions and you want to convert it you can use **mkmapgrids**. + +Using mknocnmap.pl to create grid and maps for single-point regional grids +-------------------------------------------------------------------------- + +If you want to create a regular latitude/longitude single-point or regional grid, we suggest you use **mknoocnmap.pl** in ``models/lnd/clm/tools/shared/mkmapdata`` which will create both the SCRIP grid file you need (using ``models/lnd/clm/tools/shared/mkmapgrids/mkscripgrid.ncl`` AND an identity mapping file assuming there is NO ocean in your grid domain. If you HAVE ocean in your domain you could modify the mask in the SCRIP grid file for ocean, and then use **ESMF_RegridWeightGen** to create the mapping file, and **gen_domain** to create the domain file. Like other tools, ``shared/mkmapdata/mknoocnmap.pl`` has a help option with the following: +:: + + SYNOPSIS + mknoocnmap.pl [options] Gets map and grid files for a single land-only point. + REQUIRED OPTIONS + -centerpoint [or -p] Center latitude,longitude of the grid to create. + -name [-or -n] Name to use to describe point + + OPTIONS + -dx Size of total grid in degrees in longitude direction + (default is 0.1) + -dy Size of total grid in degrees in latitude direction + (default is 0.1) + -silent [or -s] Make output silent + -help [or -h] Print usage to STDOUT. + -verbose [or -v] Make output more verbose. + -nx Number of longitudes (default is 1) + -ny Number of latitudes (default is 1) + +See `Figure 2-5 `_ for a visual representation of this process. + + +2. Creating mapping files for mksurfdata_map +============================================== + +``mkmapdata.sh`` uses the above SCRIP grid input files to create SCRIP mapping data files (uses ESMF). + +The bash shell script ``models/lnd/clm/tools/shared/mkmapgrids/mkmapdata.sh`` uses **ESMF_RegridWeightGen** to create a list of maps from the raw datasets that are input to **mksurfdata_map**. +Each dataset that has a different grid, or land-mask needs a different mapping file for it, but many different raw datasets share the same grid/land-mask as other files. +Hence, there doesn't need to be a different mapping file for EACH raw dataset -- just for each DIFFERENT raw dataset. +See `Figure 2-3 `_ for a visual representation of how this works. +The bash script figures out which mapping files it needs to create and then runs **ESMF_RegridWeightGen** for each one. +You can then either enter the datasets into the XML database (see `Chapter 3 `_ or leave the files in place, and use the "-res usrspec -usr_gname -usr_gdate" options to **mksurfdata_map** (see `the Section called Running mksurfdata.pl `_ below). +Use the "-phys" option to specify if you are creating mapping files for clm4_0 or clm4_5 (the list of raw datafiles is somewhat different between the two). +mkmapdata.sh has a help option with the following +:: + + ../../tools/shared/mkmapdata/mkmapdata.sh + + ********************** + usage on yellowstone: + ./mkmapdata.sh + + valid arguments: + [-f|--gridfile ] + Full pathname of model SCRIP grid file to use + This variable should be set if this is not a supported grid + This variable will override the automatic generation of the + filename generated from the -res argument + the filename is generated ASSUMING that this is a supported + grid that has entries in the file namelist_defaults_clm.xml + the -r|--res argument MUST be specied if this argument is specified + [-r|--res ] + Model output resolution (default is 10x15) + [-t|--gridtype ] + Model output grid type + supported values are [regional,global], (default is global) + [-p|--phys ] + Whether to generate mapping files for clm4_0 or clm4_5 + supported values are [clm4_0,clm4_5], (default is clm4_5) + [-b|--batch] + Toggles batch mode usage. + If you want to run in batch mode + you need to have a separate batch script for a supported machine + that calls this script interactively - you cannot submit this + script directory to the batch system + [-l|--list] + List mapping files required (use check_input_data to get them) + also writes data to clm.input_data_list + [-d|--debug] + Toggles debug-only (don't actually run mkmapdata just echo what would happen) + [-h|--help] + Displays this help message + [-v|--verbose] + Toggle verbose usage -- log more information on what is happening + + You can also set the following env variables: + ESMFBIN_PATH - Path to ESMF binaries + (default is /contrib/esmf-5.3.0-64-O/bin) + CSMDATA ------ Path to CESM input data + (default is /glade/p/cesm/cseg/inputdata) + MPIEXEC ------ Name of mpirun executable + (default is mpirun.lsf) + REGRID_PROC -- Number of MPI processors to use + (default is 8) + + **pass environment variables by preceding above commands + with 'env var1=setting var2=setting ' + ********************** + + +.. warning:: Make sure you specify with the "-phys" option if you are creating files for CLM4.0! The default is CLM4.5. + +Figure 2-3. Details of running mkmapdata.sh +------------------------------------------- +Insert figure 2-3 + +Each of the raw datasets for **mksurfdata_map** needs a mapping file to map from the output grid you are running on to the grid and land-mask for that dataset. This is what **mkmapdata.sh** does. To create the mapping files you need a SCRIP grid file to correspond with each resolution and land mask that you have a raw data file in **mksurfdata_map**. Some raw datasets share the same grid and land mask -- hence they can share the same SCRIP grid file. The output maps created here go into **mksurfdata_map** see `Figure 2-6 `_. diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst new file mode 100644 index 0000000000..e42a46f81f --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -0,0 +1,376 @@ +.. _creating-surface-datasets: + +=========================== + Creating Surface Datasets +=========================== + +When just creating a replacement file for an existing one, the relevant tool should be used directly to create the file. When you are creating a set of files for a new resolution there are some dependencies between the tools that you need to keep in mind when creating them. The main dependency is that you MUST create a SCRIP grid file first as the SCRIP grid dataset is then input into the other tools. Also look at `Table 3-1 `_ which gives information on the files required and when. `Figure 2-1 `_ shows an overview of the general data-flow for creation of the fsurdat datasets. + +Figure 2-1. Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files +-------------------------------------------------------------------------------- +Insert figure 2-1 + +Starting from a SCRIP grid file that describes the grid you will run the model on, you first run **mkmapdata.sh** to create a list of mapping files. See `Figure 2-3 `_ for a more detailed view of how **mkmapdata.sh** works. The mapping files tell **mksurfdata_map** how to map between the output grid and the raw datasets that it uses as input. The output of **mksurfdata_map** is a surface dataset that you then use for running the model. See `Figure 2-6 `_ for a more detailed view of how **mksurfdata_map** works. + +`Figure 2-2 `_ is the legend for this figure (`Figure 2-1 `_) and other figures in this chapter (`Figure 2-4 `_, `Figure 2-5 `_, and `Figure 2-6 `_). +Figure 2-2. Legend for Data Flow Figures +Insert figure 2-2 + +Green arrows define the input to a program, while red arrows define the output. Cylinders define files that are either created by a program or used as input for a program. Boxes are programs. + +You start with a description of a SCRIP grid file for your output grid file and then create mapping files from the raw datasets to it. Once, the mapping files are created **mksurfdata_map** is run to create the surface dataset to run the model. + +Creating a Complete Set of Files for Input to CLM +------------------------------------------------- + +1. Create SCRIP grid datasets (if NOT already done) + + First you need to create a descriptor file for your grid, that includes the locations of cell centers and cell corners. There is also a "mask" field, but in this case the mask is set to one everywhere (i.e. all of the masks for the output model grid are "nomask"). An example SCRIP grid file is: $CSMDATA/lnd/clm2/mappingdata/grids/SCRIPgrid_10x15_nomask_c110308.nc. The mkmapgrids and mkscripgrid.ncl NCL script in the models/lnd/clm/tools/shared/mkmapgrids directory can help you with this. SCRIP grid files for all the standard CLM grids are already created for you. See the Section called Creating an output SCRIP grid file at a resolution to run the model on for more information on this. + +2. Create domain dataset (if NOT already done) + + Next use gen_domain to create a domain file for use by DATM and CLM. This is required, unless a domain file was already created. See the Section called Creating a domain file for CLM and DATM for more information on this. + +3. Create mapping files for mksurfdata_map (if NOT already done) + + Create mapping files for mksurfdata_map with mkmapdata.sh in models/lnd/clm/tools/shared/mkmapdata. See the Section called Creating mapping files that mksurfdata_map will use for more information on this. + +4. Create surface datasets + + Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or clm4_5 for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this. + +5. Create some sort of initial condition dataset + + You then need to do one of the following three options to have an initial dataset to start from. + + a. Use spinup-procedures to create initial condition datasets + + The first option is to do the spinup procedures from arbitrary initial conditions to get good initial datasets. This is the most robust method to use. See the Section called Spinning up the Satellite Phenology Model (CLMSP spinup) in Chapter 4, the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4, or the Section called Spinning up the CLM4.0 Carbon-Nitrogen Dynamic Global Vegetation Model (CNDV spinup) in Chapter 4 for more information on this. + + b. Use interpinic to interpolate existing initial condition datasets + + The next option is to interpolate from spunup datasets at a different resolution, using interpinic. There is a version for either clm4_0 or clm4_5 for this program. See the Section called Using interpinic to interpolate initial conditions to different resolutions for more information on this. + + c. Start up from arbitrary initial conditions + + The last alternative is to run from arbitrary initial conditions without using any spun-up datasets. This is inappropriate when using CLM4.5-BGC or CLMCN (bgc=cn or cndv) as it takes a long time to spinup Carbon pools. + +.. warning:: This is NOT recommended as many fields in CLM take a long time to equilibrate. + +6. Enter the new datasets into the build-namelist XML database + The last optional thing to do is to enter the new datasets into the build-namelist XML database. See Chapter 3 for more information on doing this. This is optional because the user may enter these files into their namelists manually. The advantage of entering them into the database is so that they automatically come up when you create new cases. + +The ``models/lnd/clm/tools/README`` goes through the complete process for creating input files needed to run CLM. We repeat that file here: +:: + + models/lnd/clm/tools/README Jun/04/2013 + + CLM tools for analysis of CLM history files -- or for creation or + modification of CLM input files. + + I. General directory structure: + + clm4_0 + mksurfdata_map --- Create surface datasets. + interpinic ------- Interpolate initial datasets to a different resolution. + (has optimized and OMP options) + clm4_5 + mksurfdata_map --- Create surface datasets. + interpinic ------- Interpolate initial datasets to a different resolution. + (has optimized and OMP options) + + shared + mkmapgrids ------- Create SCRIP grid files needed by mkmapdata + [input is CLM grid files] + (deprecated) + mkmapdata -------- Create SCRIP mapping data from SCRIP grid files (uses ESMF) + gen_domain ------- Create data model domain datasets from SCRIP mapping datasets. + (also in the top level mapping directory [../../../../tools/mapping]) + mkprocdata_map --- Convert output unstructured grids into a 2D format that + can be plotted easily + ncl_scripts ------ NCL post or pre processing scripts. + + + Note that there are different versions of mksurfdata_map and interpinic for + CLM4.0 vs. CLM4.5. Other tools are shared between the two model + versions. + + However, note that mkmapdata makes mapping files for CLM4.5 by default; to + make mapping files for CLM4.0, run the tool with the option: + -p clm4_0 + + II. Notes on building/running for each of the above tools: + + Each tool that has FORTRAN source code has the following files: + + README -------------- Specific help for using the specific tool and help on specific + files in that directory. + src/Filepath -------- List of directories needed to build the tool + (some files in ../src directories are required). + src/Makefile -------- Customization of the make for the particular tool in question + src/Makefile.common - General GNU Makefile for creating FORTRAN tools + (these are identical between tools). + src/Srcfiles -------- List of source files that are needed. + src/Mkdepends ------- Dependency generator program + + mkmapdata and ncl_scripts only contain scripts so don't have the above build files. + + Most tools have copies of files from other directories -- see the README.filecopies + file for more information on this. + + Tools may also have files with the directory name followed by: namelist, or runoptions. + + .namelist ------ Namelist to create a global file. + .runoptions ---- Command line options to use the given tool. + + These files are also used by the test scripts to test the tools (see the + README.testing) file. + + NOTE: Be sure to change the path of the datasets references by these namelists to + point to where you have exported your CESM inputdata datasets. + + To build: + + cd + setenv INC_NETCDF + setenv LIB_NETCDF + gmake + + The process will create a file called "Depends" which has the dependencies + for the build of each file on other files. + + By default some codes may be compiled non-optimized + so that you can use the debugger, and with bounds-checking, and float trapping on. + To speed up do the following... + + gmake OPT=TRUE (by default already on for interpinic and mksurfdata_map) + + Also some of the tools allow for OpenMP shared memory parallelism + (such as interpinic) with + + gmake SMP=TRUE + + To run a program with a namelist: + + ./program < namelist + + To get help on running a program with command line options (e.g., interpinic): + + ./program + + To run a program built with SMP=TRUE: + + setenv OMP_NUM_THREADS= + + run normally as above + + III. Process sequence to create input datasets needed to run CLM + + NOTE: The following assumes you want to create files for CLM4.5. If you want to + use CLM4.0, you will need to do the following: + - In the following commands, change references to the clm4_5 directory to clm4_0 + - Add the option '-p clm4_0' to the mkmapdata.sh command. + + 1.) Create SCRIP grid files (if needed) + + a.) For standard resolutions these files will already be created. (done) + + b.) To create regular lat-lon regional/single-point grids run mknoocnmap.pl + + This will create both SCRIP grid files and a mapping file that will + be valid if the region includes NO ocean whatsoever (so you can skip step 2). + You can also use this script to create SCRIP grid files for a region + (or even a global grid) that DOES include ocean if you use step 2 to + create mapping files for it (simply discard the non-ocean map created by + this script). + + Example, for single-point over Boulder Colorado. + + cd shared/mkmapdata + ./mknoocnmap.pl -p 40,255 -n 1x1_boulderCO + + c.) General case + + You'll need to convert or create SCRIP grid files on your own (using scripts + or other tools) for the general case where you have an unstructured grid, or + a grid that is not regular in latitude and longitude. + + example format + ================== + netcdf fv1.9x2.5_090205 { + dimensions: + grid_size = 13824 ; + grid_corners = 4 ; + grid_rank = 2 ; + variables: + double grid_center_lat(grid_size) ; + grid_center_lat:units = "degrees" ; + double grid_center_lon(grid_size) ; + grid_center_lon:units = "degrees" ; + double grid_corner_lat(grid_size, grid_corners) ; + grid_corner_lat:units = "degrees" ; + double grid_corner_lon(grid_size, grid_corners) ; + grid_corner_lon:units = "degrees" ; + int grid_dims(grid_rank) ; + int grid_imask(grid_size) ; + grid_imask:units = "unitless" ; + + 2.) Create ocean to atmosphere mapping file (if needed) + + a.) Standard resolutions (done) + + If this is a standard resolution with a standard ocean resolution -- this + step is already done, the files already exist. + + b.) Region without Ocean (done in step 1.b) + + IF YOU RAN mknoocnmap.pl FOR A REGION WITHOUT OCEAN THIS STEP IS ALREADY DONE. + + c.) New atmosphere or ocean resolution + + If the region DOES include ocean, use gen_domain to create a + mapping file for it. + + Example: + + cd ../../../../tools/mapping/gen_domain_files/src + ./gen_domain -m $MAPFILE -o $OCNGRIDNAME -l $ATMGRIDNAME + + + 3.) Add SCRIP grid file(s) created in (1) into XML database in CLM (optional) + + See the "Adding New Resolutions or New Files to the build-namelist Database" + Chapter in the CLM User's Guide + + http://www.cesm.ucar.edu/models/cesm1.0/clm/models/lnd/clm/doc/UsersGuide/book1.html + + If you don't do this step, you'll need to specify the file to mkmapdata + in step (3) using the "-f" option. + + 4.) Create mapping files for use by mksurfdata_map with mkmapdata + (See mkmapdata/README for more help on doing this) + + - this step uses the results of (1) that were entered into the XML database + by step (3). If you don't enter datasets in, you need to specify the + SCRIP grid file using the "-f" option to mkmapdata.sh. + + - note that mkmapdata generates maps for CLM4.5 by default; to generate + mapping files for CLM4.0, add the option '-p clm4_0' + + Example: to generate all necessary mapping files for the ne30np4 grid + + cd shared/mkmapdata + ./mkmapdata.sh -r ne30np4 + + 5.) Add mapping file(s) created in step (4) into XML database in CLM (optional) + + See notes on doing this in step (3) above. + Edit ../bld/namelist_files/namelist_defaults_clm.xml to incorporate new + mapping files. + + If you don't do this step, you'll need to specify the grid resolution name + and file creation dates to mksurfdata_map in step (5) below. + + 6.) Convert map of ocean to atm for use by DATM and CLM with gen_domain + (See tools/mapping/README for more help on doing this) + + - gen_domain uses the map from step (2) (or previously created CESM maps) + + Example: + + cd ../../../../tools/mapping/gen_domain_files/src + gmake + cd .. + setenv CDATE 090206 + setenv OCNGRIDNAME gx1v6 + setenv ATMGRIDNAME fv1.9x2.5 + setenv MAPFILE $CSMDATA/cpl/cpl6/map_${OCNGRIDNAME}_to_${ATMGRIDNAME}_aave_da_${CDATE}.nc + ./gen_domain -m $MAPFILE -o $OCNGRIDNAME -l $ATMGRIDNAME + + Normally for I compsets running CLM only you will discard the ocean domain + file, and only use the atmosphere domain file for datm and as the fatmlndfrc + file for CLM. Output domain files will be named according to the input OCN/LND + gridnames. + + 7.) Create surface datasets with mksurfdata_map + (See mksurfdata_map/README for more help on doing this) + + - Run clm4_5/mksurfdata_map/mksurfdata.pl + - This step uses the results of step (4) entered into the XML database + in step (5). + - If datasets were NOT entered into the XML database, set the resolution + to "usrspec" and use the "-usr_gname", and "-usr_gdate" options. + + Example: for 0.9x1.25 resolution + + cd clm4_5/mksurfdata_map/src + gmake + cd .. + ./mksurfdata.pl -r 0.9x1.25 + + NOTE that surface dataset will be used by default for fatmgrid - and it will + contain the lat,lon,edges and area values for the atm grid - ASSUMING that + the atm and land grid are the same + + 8.) Interpolate initial conditions using interpinic (optional) + (See interpinic/README for more help on doing this) + IMPORTANT NOTE on interpinic!!!:: BE SURE TO USE NetCDF4.3 WHEN BUILDING! + If your template file was written using pnetcdf -- interpinic will corrupt + the resulting file and make it unusable! + + 9.) Add new files to XML data or using user_nl_clm (optional) + + See notes on doing this in step (3) above. + + IV. Example of creating single-point datasets without entering into XML database. + + Here we apply the process described in III. for a single-point dataset + where we don't enter the datasets into the XML database (thus skipping + steps 3, 5 and 9), but use the needed command line options to specify where the + files are. This also skips step (2) since step 1 creates the needed mapping file. + We also skip step (8) and do NOT create a finidat file. + + 0.) Set name of grid to use and the creation date to be used later... + setenv GRIDNAME 1x1_boulderCO + setenv CDATE `date +%y%m%d` + 1.) SCRIP grid and atm to ocn mapping file + cd shared/mkmapdata + ./mknoocnmap.pl -p 40,255 -n $GRIDNAME + # Set pointer to MAPFILE that will be used in step (6) + setenv MAPFILE `pwd`/map_${GRIDNAME}_noocean_to_${GRIDNAME}_nomask_aave_da_${CDATE}.nc + cd ../.. + 2.) skip + 3.) skip + 4.) Mapping files needed for mksurfdata_map + cd shared/mkmapdata + setenv GRIDFILE ../mkmapgrids/SCRIPgrid_${GRIDNAME}_nomask_${CDATE}.nc + ./mkmapdata.sh -r $GRIDNAME -f $GRIDFILE -t regional + cd .. + 5.) skip + 6.) Generate domain file for datm and CLM + cd ../../../../tools/mapping/gen_domain_files/src + gmake + cd .. + setenv OCNDOM domain.ocn_noocean.nc + setenv ATMDOM domain.lnd.{$GRIDNAME}_noocean.nc + ./gen_domain -m $MAPFILE -o $OCNDOM -l $ATMDOM + cd ../../../../lnd/clm/tools + 7.) Create surface dataset for CLM + cd clm4_5/mksurfdata_map/src + gmake + cd .. + ./mksurfdata.pl -r usrspec -usr_gname $GRIDNAME -usr_gdate $CDATE + 8.) skip + 9.) skip + + V. Notes on which input datasets are needed for CLM + + global or regional/single-point grids + - need fsurdata and fatmlndfrc + + fsurdata ---- from mksurfdata_map in step (III.7) + fatmlndfrc -- use the domain.lnd file from gen_domain in step (III.6) + (NOTE: THIS FILE IS POINTED TO USING ATM_DOMAIN_PATH/ATM_DOMAIN_FILE/LND_DOMAIN_PATH/ \ + LND_DOMAIN_FILE + env_run.xml variables -- do NOT simply add this to your user_nl_clm as it will fail) + diff --git a/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst b/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst new file mode 100644 index 0000000000..d1824d432e --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst @@ -0,0 +1,17 @@ +================================== + Datasets for Observational Sites +================================== + +There are two ways to customize datasets for a particular observational site. +The first is to customize the input to the tools that create the dataset, and the second is to over-write the default data after you've created a given dataset. +Depending on the tool it might be easier to do it one way or the other. +In `Table 3-1 `_ we list the files that are most likely to be customized and the way they might be customized. +Of those files, the ones you are most likely to customize are: fatmlndfrc, fsurdat, faerdep (for DATM), and stream_fldfilename_ndep. +Note **mksurfdata_map** as documented previously has options to overwrite the vegetation and soil types. +For more information on this also see `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_. +And PTCLM uses these methods to customize datasets see `Chapter 6 `_. + + +Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets. +See `the Section called Running with your own atmosphere forcing in Chapter 5 `_ for more information on this. +Also the chapter on PTCLM in `the Section called Converting AmeriFlux Data for use by PTCLM in Chapter 6 `_ has information on using the AmeriFlux tower site data as atmospheric forcing. diff --git a/doc/source/users_guide/using-clm-tools/index.rst b/doc/source/users_guide/using-clm-tools/index.rst new file mode 100644 index 0000000000..583122cdcd --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/index.rst @@ -0,0 +1,21 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _using-clm-tools-section: + +##################################### +Using CLM tools +##################################### + +.. toctree:: + :maxdepth: 2 + + what-are-the-clm-tools.rst + building-the-clm-tools.rst + creating-input-for-surface-dataset-generation.rst + creating-surface-datasets.rst + datasts-for-observational-sites.rst + creating-domain-files.rst + cprnc.rst diff --git a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst new file mode 100644 index 0000000000..b5e47e861f --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst @@ -0,0 +1,18 @@ +.. _observational-sites-datasets: + +******************************* +Observational Sites Datasets +******************************* + +There are two ways to customize datasets for a particular observational site. +The first is to customize the input to the tools that create the dataset, and the second is to over-write the default data after you've created a given dataset. +Depending on the tool it might be easier to do it one way or the other. +In `Table 3-1 `_ we list the files that are most likely to be customized and the way they might be customized. +Of those files, the ones you are most likely to customize are: fatmlndfrc, fsurdat, faerdep (for DATM), and stream_fldfilename_ndep. +Note **mksurfdata_map** as documented previously has options to overwrite the vegetation and soil types. +For more information on this also see `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_. +And PTCLM uses these methods to customize datasets see `Chapter 6 `_. + +Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets. +See `the Section called Running with your own atmosphere forcing in Chapter 5 `_ for more information on this. +Also the chapter on PTCLM in `the Section called Converting AmeriFlux Data for use by PTCLM in Chapter 6 `_ has information on using the AmeriFlux tower site data as atmospheric forcing. diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst new file mode 100644 index 0000000000..e71c97cf3d --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst @@ -0,0 +1,89 @@ +.. _what-are-the-clm-tools: + +======================== + What are the CLM tools +======================== + +There are several tools provided with CLM that allow you to create your own input datasets at resolutions you choose, or to interpolate initial conditions to a different resolution, or used to compare CLM history files between different cases. +The tools are all available in the ``models/lnd/clm/tools`` directory. +Most of the tools are FORTRAN stand-alone programs in their own directory, but there is also a suite of NCL scripts in the ``shared/ncl_scripts`` directory, and some of the tools are scripts that may also call the ESMF regridding program. +Some of the NCL scripts are very specialized and not meant for general use, and we won't document them here. +They still contain documentation in the script itself and the README file in the tools directory. + +The tools are divided into three directories for three categories: clm4_0, clm4_5, and shared. +The first two are of course for tools that are designed to work with either the CLM4.0 or CLM4.5 versions of the model. +The last one are shared utilities that can be used by either, or have a "-phys" option so you can specify which version you want to use. + +The list of generally important scripts and programs are as follows. + +1. *tools/cprnc* (relative to top level directory) to compare NetCDF files with a time axis. + +#. *shared/mkmapgrids* to create SCRIP grid data files from old CLM format grid files that can then be used to create new CLM datasets (deprecated). There is also a NCL script (``shared/mkmapgrids/mkscripgrid.ncl`` to create SCRIP grid files for regular latitude/longitude grids. + +#. *shared/mkmapdata* to create SCRIP mapping data file from SCRIP grid files (uses ESMF). + +#. *shared/gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. + +#. *mksurfdata_map* to create surface datasets from grid datasets (clm4_0 and clm4_5 versions). + +#. *shared/mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or clm4_5. + +In the sections to come we will go into detailed description of how to use each of these tools in turn. +First, however we will discuss the common environment variables and options that are used by all of the FORTRAN tools. +Second, we go over the outline of the entire file creation process for all input files needed by CLM for a new resolution, then we turn to each tool. +In the last section we will discuss how to customize files for particular observational sites. + +The tools run either one of two ways, with a namelist to provide options, or with command line arguments (and NOT both). +**gen_domain** and **cprnc** run with command line arguments, and the other tools run with namelists. + +In the following sections, we will outline how to make these files available for build-namelist so that you can easily create simulations that include them. +In the chapter on single-point and regional datasets we also give an alternative way to enter new datasets without having to edit files. + +------------------------------------ +Running FORTRAN tools with namelists +------------------------------------ + +**mksurfdata_map** and **mkmapgrids** run with namelists that are read from standard input. +Hence, you create a namelist and then run them by redirecting the namelist file into standard input as follows: +:: + + ./program < namelist + +For programs with namelists there is at least one sample namelist with the name "program".namelist (i.e. +``mksurfdata_map.namelist`` for the **mksurfdata_map** program). +There may also be other sample namelists that end in a different name besides "namelist". +Namelists that you create should be similar to the example namelist. +The namelist values are also documented along with the other namelists in the: +:: + + models/lnd/clm/bld/namelist_files/namelist_definition.xml`` file + and default values in the: + models/lnd/clm/bld/namelist_files/namelist_defaults_clm_tools.xml`` file. + +----------------------------------------------- +Running FORTRAN tools with command line options +----------------------------------------------- + +**gen_domain**, and **cprnc** run with command line arguments. +The detailed sections below will give you more information on the command line arguments specific to each tool. +Also running the tool without any arguments will give you a general synopsis on how to run the tool. + +----------------------------------------- +Running FORTRAN tools built with SMP=TRUE +----------------------------------------- + +When you enable ``SMP=TRUE`` on your build of one of the tools that make use of it, you are using OpenMP for shared memory parallelism (SMP). +In SMP loops are run in parallel with different threads run on different processors all of which access the same memory (called on-node). +Thus you can only usefully run up to the number of processors that are available on a single-node of the machine you are running on. +For example, on the NCAR machine yellowstone there are 16 processors per node, but the SMT hardware on the machine allows you to submit twice as many threads or 32 threads. + + +--------- +Using NCL +--------- + +In the tools directory ``models/lnd/clm/tools/shared/ncl_scripts`` and in a few other locations there are scripts that use NCAR Command Language (NCL). +Unlike the FORTRAN tools, you will need to get a copy of NCL in order to use them. +You also won't have to build an executable in order to use them, hence no Makefile is provided. +NCL is provided for free download as either binaries or source code from: `http://www.ncl.ucar.edu/ `_. +The NCL web-site also contains documentation on NCL and it's use. These scripts are stand-alone and at most use environment variables to control how to use them. In some cases there are perl scripts with command line arguments that call the NCL scripts to control what they do. From 945619d5c5c94ab85dc18f17ea08d20f52e4a4d4 Mon Sep 17 00:00:00 2001 From: mvertens Date: Sun, 26 Mar 2017 11:23:47 -0600 Subject: [PATCH 002/255] first pass at some rst additions --- .../CLM45_Tech_Note_Chpt_1_Introduction.rst | 832 +++++++ .../CLM45_Tech_Note_Chpt_10_Glacier.rst | 169 ++ .../CLM45_Tech_Note_Chpt_11_RTM.rst | 139 ++ .../CLM45_Tech_Note_Chpt_12_Urban.rst | 130 + ...Note_Chpt_13_CN_Allocation_Respiration.rst | 599 +++++ ...Tech_Note_Chpt_14_Vegetation_Phenology.rst | 887 +++++++ .../CLM45_Tech_Note_Chpt_15_Decomposition.rst | 797 ++++++ ...h_Note_Chpt_16_External_Nitrogen_Cycle.rst | 397 +++ ...LM45_Tech_Note_Chpt_17_Plant_Mortality.rst | 505 ++++ .../CLM45_Tech_Note_Chpt_18_Fire.rst | 659 +++++ .../CLM45_Tech_Note_Chpt_19_Methane.rst | 619 +++++ .../CLM45_Tech_Note_Chpt_2_Ecosystem.rst | 782 ++++++ ...LM45_Tech_Note_Chpt_20_Crop_Irrigation.rst | 722 ++++++ ..._Tech_Note_Chpt_21_Transient_Landcover.rst | 359 +++ .../CLM45_Tech_Note_Chpt_22_DGVM.rst | 155 ++ .../CLM45_Tech_Note_Chpt_23_BVOCs.rst | 66 + .../CLM45_Tech_Note_Chpt_24_Dust.rst | 212 ++ .../CLM45_Tech_Note_Chpt_25_Isotopes.rst | 256 ++ .../CLM45_Tech_Note_Chpt_26_Offline.rst | 210 ++ .../CLM45_Tech_Note_Chpt_27_References.rst | 1377 +++++++++++ ...CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst | 1137 +++++++++ ...LM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst | 289 +++ .../CLM45_Tech_Note_Chpt_5_Fluxes.rst | 1773 ++++++++++++++ ...ech_Note_Chpt_6_Soil_Snow_Temperatures.rst | 928 +++++++ .../CLM45_Tech_Note_Chpt_7_Hydrology.rst | 2167 +++++++++++++++++ .../CLM45_Tech_Note_Chpt_8_Photosynthesis.rst | 718 ++++++ .../CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst | 1189 +++++++++ 27 files changed, 18073 insertions(+) create mode 100644 doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst create mode 100644 doc/source/tech_note/CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst create mode 100644 doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst create mode 100644 doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst create mode 100644 doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst create mode 100644 doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst create mode 100644 doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst create mode 100644 doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst create mode 100644 doc/source/tech_note/CHAPTER_17/CLM45_Tech_Note_Chpt_17_Plant_Mortality.rst create mode 100644 doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst create mode 100644 doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst create mode 100644 doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst create mode 100644 doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst create mode 100644 doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst create mode 100644 doc/source/tech_note/CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst create mode 100644 doc/source/tech_note/CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst create mode 100644 doc/source/tech_note/CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst create mode 100644 doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst create mode 100644 doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst create mode 100644 doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst create mode 100644 doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst create mode 100644 doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst create mode 100644 doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst create mode 100644 doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst create mode 100644 doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst create mode 100644 doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst create mode 100644 doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst diff --git a/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst b/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst new file mode 100644 index 0000000000..1bcd54fca7 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst @@ -0,0 +1,832 @@ +.. math:: 188 + +**NCAR/TN-503+STR** + +**NCAR Technical Note** + +**\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** + +**** + +**July 2013** + +**** + +**Technical Description of version 4.5 of the Community Land Model +(CLM)** + +***Coordinating Lead Authors*** + +**Keith W. Oleson, David M. Lawrence** + +**** + +***Lead Authors*** + +**Gordon B. Bonan, Beth Drewniak, Maoyi Huang, Charles D. Koven, Samuel +Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, +Peter E. Thornton** + +**** + +***Contributing Authors*** + +**Anil Bozbiyik, Rosie Fisher, Colette L. Heald, Erik Kluzek, +Jean-Francois Lamarque, Peter J. Lawrence, L. Ruby Leung, William +Lipscomb, Stefan Muszala, Daniel M. Ricciuto, William Sacks, Ying Sun, +Jinyun Tang, Zong-Liang Yang** + +**** + +**** + +**** + +**NCAR Earth System Laboratory** + +**Climate and Global Dynamics +Division\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** + +**NATIONAL CENTER FOR ATMOSPHERIC RESEARCH** + +**P. O. Box 3000** + +**BOULDER, COLORADO 80307-3000** + +**ISSN Print Edition 2153-2397** + +**ISSN Electronic Edition 2153-2400** + +**** + +**NCAR TECHNICAL NOTES** + +http://library.ucar.edu/research/publish-technote\ **** + +**** + +The Technical Notes series provides an outlet for a variety of NCAR +Manuscripts that contribute in specialized ways to the body of +scientific knowledge but that are not yet at a point of a formal +journal, monograph or book publication. Reports in this series are +issued by the NCAR scientific divisions, serviced by OpenSky and +operated through the NCAR Library. Designation symbols for the series +include: + +**EDD – Engineering, Design, or Development Reports** + +Equipment descriptions, test results, instrumentation, + +and operating and maintenance manuals. + +**IA – Instructional Aids** + +** Instruction manuals, bibliographies, film supplements, + +and other research or instructional aids. + +**PPR – Program Progress Reports** + +** Field program reports, interim and working reports, + +survey reports, and plans for experiments. + +**PROC – Proceedings** + +** Documentation or symposia, colloquia, conferences, + +workshops, and lectures. (Distribution maybe limited to + +attendees). + +**STR – Scientific and Technical Reports** + +Data compilations, theoretical and numerical + +investigations, and experimental results. + +The National Center for Atmospheric Research (NCAR) is operated by the +nonprofit University Corporation for Atmospheric Research (UCAR) under +the sponsorship of the National Science Foundation. Any opinions, +findings, conclusions, or recommendations expressed in this publication +are those of the author(s) and do not necessarily reflect the views of +the National Science Foundation. + +National Center for Atmospheric Research + +P. O. Box 3000 + +Boulder, Colorado 80307-300 + +**** + +ii + +**NCAR/TN-503+STR** + +**NCAR Technical Note** + +**\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** + +**** + +**July 2013** + +**** + +**Technical Description of version 4.5 of the Community Land Model +(CLM)** + +***Coordinating Lead Authors*** + +**Keith W. Oleson, David M. Lawrence** + +**** + +***Lead Authors*** + +**Gordon B. Bonan, Beth Drewniak, Maoyi Huang, Charles D. Koven, Samuel +Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, +Peter E. Thornton** + +**** + +***Contributing Authors*** + +**Anil Bozbiyik, Rosie Fisher, Colette L. Heald, Erik Kluzek, +Jean-Francois Lamarque, Peter J. Lawrence, L. Ruby Leung, William +Lipscomb, Stefan Muszala, Daniel M. Ricciuto, William Sacks, Ying Sun, +Jinyun Tang, Zong-Liang Yang** + +**** + +**** + +**** + +**NCAR Earth System Laboratory** + +**Climate and Global Dynamics +Division\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** + +**NATIONAL CENTER FOR ATMOSPHERIC RESEARCH** + +**P. O. Box 3000** + +**BOULDER, COLORADO 80307-3000** + +**ISSN Print Edition 2153-2397** + +**ISSN Electronic Edition 2153-2400** + +xi + +**TABLE OF CONTENTS** + +**** + +**1. Introduction 11.1 Model History 11.1.1 Inception of CLM 11.1.2 CLM2 +31.1.3 CLM3 51.1.4 CLM3.5 61.1.5 CLM4 71.1.6 CLM4.5 81.2 Biogeophysical +and Biogeochemical Processes 112. Surface Characterization and Model +Input Requirements 142.1 Surface Characterization 142.1.1 Surface +Heterogeneity and Data Structure 142.1.2 Vegetation Composition 172.1.3 +Vegetation Structure 192.1.4 Phenology and vegetation burial by snow +212.2 Model Input Requirements 212.2.1 Atmospheric Coupling 212.2.2 +Initialization 272.2.3 Surface Data 282.2.4 Adjustable Parameters and +Physical Constants 353. Surface Albedos 373.1 Canopy Radiative Transfer +373.2 Ground Albedos 463.2.1 Snow Albedo 483.2.2 Snowpack Optical +Properties 523.2.3 Snow Aging 563.3 Solar Zenith Angle 594. Radiative +Fluxes 634.1 Solar Fluxes 634.2 Longwave Fluxes 675. Momentum, Sensible +Heat, and Latent Heat Fluxes 715.1 Monin-Obukhov Similarity Theory 735.2 +Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces 825.3 +Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces +885.3.1 Theory 885.3.2 Numerical Implementation 1025.4 Update of Ground +Sensible and Latent Heat Fluxes 1075.5 Saturation Vapor Pressure 1106. +Soil and Snow Temperatures 1136.1 Numerical Solution 1146.2 Phase Change +1256.2.1 Soil and Snow Layers 1256.2.2 Surface Water 1296.3 Soil and +Snow Thermal Properties 1307. Hydrology 1347.1 Canopy Water 1357.2 Snow +1377.2.1 Snow Covered Area Fraction 1397.2.2 Ice Content 1407.2.3 Water +Content 1427.2.4 Black and organic carbon and mineral dust within snow +1437.2.5 Initialization of snow layer 1467.2.6 Snow Compaction 1467.2.7 +Snow Layer Combination and Subdivision 1497.2.7.1 Combination 1497.2.7.2 +Subdivision 1527.3 Surface Runoff, Surface Water Storage, and +Infiltration 1537.3.1 Surface Runoff 1537.3.2 Surface Water Storage +1557.3.3 Infiltration 1567.4 Soil Water 1587.4.1 Hydraulic Properties +1607.4.2 Numerical Solution 1637.4.2.1 Equilibrium soil matric potential +and volumetric moisture 1697.4.2.2 Equation set for layer i=1 1717.4.2.3 +Equation set for layers i=2,…,N\ :sub:`levsoi` -1 1717.4.2.4 Equation +set for layers i=N\ :sub:`levsoi` ,…N\ :sub:`levsoi` +1 1727.5 Frozen +Soils and Perched Water Table 1747.6 Groundwater-Soil Water Interactions +1757.7 Runoff from glaciers and snow-capped surfaces 1787.8 The Variable +Infiltration Capacity parameterizations as a hydrologic option 1798. +Stomatal Resistance and Photosynthesis 1838.1 Stomatal resistance 1838.2 +Photosynthesis 1868.3 Vcmax25 and canopy scaling 1918.4 Soil water +stress 1938.5 Numerical implementation 1979. Lake Model 2009.1 +Discretization 2019.2 External Data 2029.3 Surface Albedo 2029.4 Surface +Fluxes and Surface Temperature 2039.4.1 Overview of Changes from CLM4 +2039.4.2 Surface Properties 2039.4.3 Surface Flux Solution 2059.5 Lake +Temperature 2119.5.1 Introduction 2119.5.2 Overview of Changes from CLM4 +2129.5.3 Boundary Conditions 2139.5.4 Eddy Diffusivity and Thermal +Conductivities 2139.5.5 Radiation Penetration 2169.5.6 Heat Capacities +2179.5.7 Crank-Nicholson Solution 2179.5.8 Phase Change 2199.5.9 +Convection 2209.5.10 Energy Conservation 2239.6 Lake Hydrology 2239.6.1 +Overview 2239.6.2 Water Balance 2249.6.3 Precipitation, Evaporation, and +Runoff 2259.6.4 Soil Hydrology 2269.6.5 Modifications to Snow Layer +Logic 22710. Glaciers 22910.1 Overview 22910.2 Multiple elevation class +scheme 23110.3 Computation of the surface mass balance 23211. River +Transport Model (RTM) 23512. Urban Model (CLMU) 23913. Carbon and +Nitrogen Pools, Allocation, and Respiration 24413.1 Introduction 24413.2 +Carbon Allocation for Maintenance Respiration Costs 24613.3 Carbon and +Nitrogen Stoichiometry of New Growth 24813.4 Deployment of +retranslocated nitrogen 25213.5 Plant nitrogen uptake from soil mineral +nitrogen pool 25313.6 Final carbon and nitrogen allocation 25313.7 +Autotrophic Respiration 25613.7.1 Maintenance Respiration 25613.7.2 +Growth Respiration 25714. Vegetation Phenology 25914.1 General Phenology +Flux Parameterization 25914.1.1 Onset Periods 26014.1.2 Offset Periods +26214.1.3 Background Onset Growth 26414.1.4 Background Litterfall +26514.1.5 Livewood Turnover 26614.2 Evergreen Phenology 26714.3 +Seasonal-Deciduous Phenology 26814.3.1 Seasonal-Deciduous Onset Trigger +26814.3.2 Seasonal-Deciduous Offset Trigger 27114.4 Stress-Deciduous +Phenology 27114.4.1 Stress-Deciduous Onset Triggers 27114.4.2 +Stress-Deciduous Offset Triggers 27314.4.3 Stress-Deciduous: Long +Growing Season 27414.5 Litterfall Fluxes Merged to the Column Level +27615. Decomposition 27815.1 CLM-CN Pool Structure, Rate Constants and +Parameters 28115.2 Century-based Pool Structure, Rate Constants and +Parameters 28515.3 Environmental modifiers on decomposition rate 28615.4 +N-limitation of Decomposition Fluxes 28915.5 N Competition between plant +uptake and soil immobilization fluxes 29215.6 Final Decomposition Fluxes +29315.7 Vertical Distribution and Transport of Decomposing C and N pools +29515.8 Model Equilibration 29616. External Nitrogen Cycle 29816.1 +Atmospheric Nitrogen Deposition 29816.2 Biological Nitrogen Fixation +29916.3 Nitrification and Denitrification Losses of Nitrogen 30116.3.1 +CLM-CN formulation 30116.3.2 Century-based formulation 30416.4 Leaching +Losses of Nitrogen 30516.5 Losses of Nitrogen Due to Fire 30717. Plant +Mortality 30817.1 Mortality Fluxes Leaving Vegetation Pools 30817.2 +Mortality Fluxes Merged to the Column Level 31118. Fire 31618.1 Non-peat +fires outside cropland and tropical closed forest 31618.1.1 Fire counts +31618.1.2 Average spread area of a fire 32018.1.3 Fire impact 32318.2 +Agricultural fires 32518.3 Deforestation fires 32618.4 Peat fires 32919. +Methane Model 33219.1 Methane Model Structure and Flow 33219.2 Governing +Mass-Balance Relationship 33319.3 CH4 Production 33419.4 Ebullition +33819.5 Aerenchyma Transport 33819.6 CH4 Oxidation 34019.7 Reactive +Transport Solution 34019.7.1 Competition for CH4 and O2 34119.7.2 CH4 +and O2 Source Terms 34119.7.3 Aqueous and Gaseous Diffusion 34219.7.4 +Boundary Conditions 34319.7.5 Crank-Nicholson Solution 34419.7.6 +Interface between water table and unsaturated zone 34519.8 Inundated +Fraction Prediction 34619.9 Seasonal Inundation 34720. Crops and +Irrigation 34820.1 Summary of CLM4.5 updates relative to the CLM4.0 +34820.2 The crop model 34820.2.1 Introduction 34820.2.2 Crop plant +functional types 34920.2.3 Phenology 35020.2.3.1 Planting 35120.2.3.2 +Leaf emergence 35220.2.3.3 Grain fill 35320.2.3.4 Harvest 35320.2.4 +Allocation 35320.2.4.1 Leaf emergence to grain fill 35420.2.4.2 Grain +fill to harvest 35420.2.5 General comments 35520.3 The irrigation model +36020.4 The details about what is new in CLM4.5 36120.4.1 Interactive +irrigation for corn, temperate cereals, and soybean 36120.4.2 +Interactive fertilization 36320.4.3 Biological nitrogen fixation for +soybeans 36420.4.4 Modified C:N ratios for crops 36520.4.5 Nitrogen +retranslocation for crops 36520.4.6 Separate reproductive pool 36721. +Transient Landcover Change 36921.1 Annual Transient Land Cover Data and +Time Interpolation 36921.2 Mass and Energy Conservation 37121.3 Annual +Transient Land Cover Dataset Development 37221.3.1 UNH Transient Land +Use and Land Cover Change Dataset 37221.3.2 Representing Land Use and +Land Cover Change in CLM 37421.3.3 Present Day PFT Dataset 37521.3.4 +Potential PFT Distribution 37621.3.5 Transient Land Cover Change Dataset +37721.3.6 Forest Harvest Dataset Changes 37822. Dynamic Global +Vegetation Model 38122.1 Establishment and survival 38222.2 Light +competition 38322.3 CN processes modified for the CNDV coupling 38323. +Biogenic Volatile Organic Compounds (BVOCs) 38624. Dust Model 38825. +Carbon Isotopes 39325.1 General Form for Calculating 13C and 14C Flux +39325.2 Isotope Symbols, Units, and Reference Standards 39425.3 Carbon +Isotope Discrimination During Photosynthesis 39625.4 14C radioactive +decay and historical atmospheric 14C concentrations 39826. Offline Mode +40027. References 405** + +**LIST OF FIGURES** + +Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes +simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). +13Figure 2.1. Configuration of the CLM subgrid hierarchy. 15Figure 4.1. +Schematic diagram of (a) direct beam radiation, (b) diffuse solar +radiation, and (c) longwave radiation absorbed, transmitted, and +reflected by vegetation and ground. 64Figure 5.1. Schematic diagram of +sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated +surfaces. 91Figure 5.2. Schematic diagram of water vapor fluxes for (a) +non-vegetated surfaces and (b) vegetated surfaces. 92Figure 6.1. +Schematic diagram of numerical scheme used to solve for soil +temperature. 119Figure 7.1. Hydrologic processes represented in CLM. +135Figure 7.2. Example of three layer snow pack (snl=-3). 137Figure 7.3. +Schematic diagram of numerical scheme used to solve for soil water +fluxes. 165Figure 12.1. Schematic representation of the urban land unit. +242Figure 12.2. Schematic of urban and atmospheric model coupling. +243Figure 13.1. Vegetation fluxes and pools. 245Figure 13.2: Carbon and +nitrogen pools. 246Figure 14.1. Example of annual phenology cycle for +seasonal deciduous. 260Figure 14.2. Example fluxes and pools sizes for +an onset growth period of 15 days, with initial transfer pool size of +100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool +(e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its +associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). +262Figure 14.3. Example fluxes and pool sizes for an offset (litterfall) +period of 15 days, with initial display pool size of 100 gC m-2 and a +timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon +content of display pool and litter pool through the litterfall period, +ignoring the losses from litter pool due to decomposition during this +period. 264Figure 15.1. Schematic of decomposition model in CLM. +279Figure 15.2. Pool structure, transitions, respired fractions (numbers +at end of arrows), and turnover times (numbers in boxes) for the 2 +alternate soil decomposition models included in CLM. 281Figure 16.1. +Biological nitrogen fixation as a function of annual net primary +production. 300Figure 19.1. Schematic representation of biological and +physical processes integrated in CLM that affect the net CH4 surface +flux. (left) Fully inundated portion of a CLM gridcell and (right) +variably saturated portion of a gridcell. 334Figure 21.1. Schematic of +land cover change impacts on CLM carbon pools and fluxes. 379Figure +21.2. Schematic of translation of annual UNH land units to CLM4 plant +functional types. 380Figure 25.1. Atmospheric +:math:`\mathrm{\Delta}`\ 14C used to drive 14C model over the historical +period. 399\ **** + +**LIST OF TABLES** + +Table 2.1. Plant functional types 18Table 2.2. Prescribed plant +functional type heights 20Table 2.3. Atmospheric input to land model +23Table 2.4. Land model output to atmospheric model 26Table 2.5. Surface +data required for CLM4.5 and their base spatial resolution 29Table 2.6. +Physical constants 36Table 3.1. Plant functional type optical properties +44Table 3.2. Intercepted snow optical properties 46Table 3.3. Dry and +saturated soil albedos 48Table 3.4. Spectral bands and weights used for +snow radiative transfer 51Table 3.5. Single-scatter albedo values used +for snowpack impurities and ice 54Table 3.6. Mass extinction values (m2 +kg-1) used for snowpack impurities and ice. 55Table 3.7. Asymmetry +scattering parameters used for snowpack impurities and ice. 56Table 3.8. +Orbital parameters 62Table 5.1. Plant functional type aerodynamic +parameters 101Table 5.2. Coefficients for e\ :sub:`sat`\ :sup:`T` +111Table 5.3. Coefficients for 112Table 6.1. Soil layer structure. +115Table 7.1. Meltwater scavenging efficiency for particles within snow +146Table 7.2. Minimum and maximum thickness of snow layers (m) 152Table +8.1. Plant functional type (PFT) photosynthetic parameters. 185Table +8.2. Temperature dependence parameters for C3 photosynthesis. 190Table +8.3. Plant functional type root distribution parameters. 196Table 13.1. +Allocation and carbon:nitrogen ratio parameters 250Table 15.1. +Decomposition rate constants for litter and SOM pools, C:N ratios, and +acceleration parameters (see section 15.8 for explanation) for the +CLM-CN decomposition pool structure. 283Table 15.2. Respiration +fractions for litter and SOM pools 284Table 15.3. Respiration fractions +for litter and SOM pools for Century-based structure 285Table 15.4. +Turnover times, C:N ratios, and acceleration parameters (see section +15.8 for explanation) for the Century-based decomposition cascade. +286Table 18.1. PFT-specific combustion completeness and fire mortality +factors. 331Table 19.1. Parameter descriptions and sensitivity analysis +ranges applied in the methane model. 337Table 19.2. Temperature +dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. +342Table 20.1. Crop plant functional types (pfts) in CLM4.5CNcrop and +their parameters relating to phenology and morphology. Numbers in the +first column correspond to the list of pfts in Table 2.1. 357Table 20.2. +Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. +Numbers in the first column correspond to the list of pfts in Table 2.1. +359Table 20.3. Pre- and post-grain fill C:N ratios for crop leaf, stem, +fine root, and reproductive pools. 367Table 22.1. Plant functional type +(PFT) biogeography rules with respect to climate. 385Table 24.1. Mass +fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric +standard deviation :sub:`g, i` , per dust source mode i 392Table 24.2. +Minimum and maximum particle diameters in each dust transport bin j +392\ **** + +ACKNOWLEDGEMENTS + +The authors would like to acknowledge the substantial contributions of +the following members of the Land Model and Biogeochemistry Working +Groups to the development of the Community Land Model since its +inception in 1996: Benjamin Andre, Ian Baker, Michael Barlage, Mike +Bosilovich, Marcia Branstetter, Tony Craig, Aiguo Dai, Yongjiu Dai, Mark +Decker, Scott Denning, Robert Dickinson, Paul Dirmeyer, Jared Entin, Jay +Famiglietti, Johannes Feddema, Mark Flanner, Jon Foley, Andrew Fox, Inez +Fung, David Gochis, Alex Guenther, Tim Hoar, Forrest Hoffman, Paul +Houser, Trish Jackson, Brian Kauffman, Silvia Kloster, Natalie Mahowald, +Jiafu Mao, Lei Meng, Sheri Michelson, Guo-Yue Niu, Adam Phillips, Taotao +Qian, Jon Radakovich, James Randerson, Nan Rosenbloom, Steve Running, +Koichi Sakaguchi, Adam Schlosser, Andrew Slater, Reto Stöckli, Quinn +Thomas, Mariana Vertenstein, Nicholas Viovy, Aihui Wang, Guiling Wang, +Charlie Zender, Xiaodong Zeng, and Xubin Zeng. + +The authors also thank the following people for their review of this +document: Jonathan Buzan, Kyla Dahlin, Sanjiv Kumar, Hanna Lee, Danica +Lombardozzi, Quinn Thomas, and Will Wieder. + +Current affiliations for the authors are as follows: + +K.W. Oleson, D.M. Lawrence, G.B. Bonan, S. Levis, S.C. Swenson, R. +Fisher, E. Kluzek, J.-F. Lamarque, P.J. Lawrence, S. Muszala, and W. +Sacks (National Center for Atmospheric Research); B. Drewniak (Argonne +National Laboratory); M. Huang, L.R. Leung (Pacific Northwest National +Laboratory); C.D. Koven, W.J. Riley, and J. Tang (Lawrence Berkeley +National Laboratory); F. Li (Chinese Academy of Sciences); Z.M. Subin +(Princeton University); P.E. Thornton and D.M. Ricciuto (Oak Ridge +National Laboratory); A. Bozbiyik (Bern University); C. Heald +(Massachusetts Institute of Technology), W. Lipscomb (Los Alamos +National Laboratory); Ying Sun and Z.-L. Yang (University of Texas at +Austin) + +.. math:: 188 + +.. math:: 7 + +Introduction +=============== + +The purpose of this technical note is to describe the biogeophysical and +biogeochemical parameterizations and numerical implementation of version +4.5 of the Community Land Model (CLM4.5). Scientific justification and +evaluation of these parameterizations can be found in the referenced +scientific papers (Chapter 27). This technical note and the CLM4.5 +User’s Guide together provide the user with the scientific description +and operating instructions for CLM. + +Model History +--------------- + +Inception of CLM +^^^^^^^^^^^^^^^^^^^^^^ + +The early development of the Community Land Model can be described as +the merging of a community-developed land model focusing on +biogeophysics and a concurrent effort at NCAR to expand the NCAR Land +Surface Model (NCAR LSM, Bonan 1996) to include the carbon cycle, +vegetation dynamics, and river routing. The concept of a +community-developed land component of the Community Climate System Model +(CCSM) was initially proposed at the CCSM Land Model Working Group +(LMWG) meeting in February 1996. Initial software specifications and +development focused on evaluating the best features of three existing +land models: the NCAR LSM (Bonan 1996, 1998) used in the Community +Climate Model (CCM3) and the initial version of CCSM; the Institute of +Atmospheric Physics, Chinese Academy of Sciences land model (IAP94) (Dai +and Zeng 1997); and the Biosphere-Atmosphere Transfer Scheme (BATS) +(Dickinson et al. 1993) used with CCM2. A scientific steering committee +was formed to review the initial specifications of the design provided +by Robert Dickinson, Gordon Bonan, Xubin Zeng, and Yongjiu Dai and to +facilitate further development. Steering committee members were selected +so as to provide guidance and expertise in disciplines not generally +well-represented in land surface models (e.g., carbon cycling, +ecological modeling, hydrology, and river routing) and included +scientists from NCAR, the university community, and government +laboratories (R. Dickinson, G. Bonan, X. Zeng, Paul Dirmeyer, Jay +Famiglietti, Jon Foley, and Paul Houser). + +The specifications for the new model, designated the Common Land Model, +were discussed and agreed upon at the June 1998 CCSM Workshop LMWG +meeting. An initial code was developed by Y. Dai and was examined in +March 1999 by Mike Bosilovich, P. Dirmeyer, and P. Houser. At this point +an extensive period of code testing was initiated. Keith Oleson, Y. Dai, +Adam Schlosser, and P. Houser presented preliminary results of offline +1-dimensional testing at the June 1999 CCSM Workshop LMWG meeting. +Results from more extensive offline testing at plot, catchment, and +large scale (up to global) were presented by Y. Dai, A. Schlosser, K. +Oleson, M. Bosilovich, Zong-Liang Yang, Ian Baker, P. Houser, and P. +Dirmeyer at the LMWG meeting hosted by COLA (Center for +Ocean-Land-Atmosphere Studies) in November 1999. Field data used for +validation included sites adopted by the Project for Intercomparison of +Land-surface Parameterization Schemes (Henderson-Sellers et al. 1993) +(Cabauw, Valdai, Red-Arkansas river basin) and others [FIFE (Sellers et +al. 1988), BOREAS (Sellers et al. 1995), HAPEX-MOBILHY (André et al. +1986), ABRACOS (Gash et al. 1996), Sonoran Desert (Unland et al. 1996), +GSWP (Dirmeyer et al. 1999)]. Y. Dai also presented results from a +preliminary coupling of the Common Land Model to CCM3, indicating that +the land model could be successfully coupled to a climate model. + +Results of coupled simulations using CCM3 and the Common Land Model were +presented by X. Zeng at the June 2000 CCSM Workshop LMWG meeting. +Comparisons with the NCAR LSM and observations indicated major +improvements to the seasonality of runoff, substantial reduction of a +summer cold bias, and snow depth. Some deficiencies related to runoff +and albedo were noted, however, that were subsequently addressed. Z.-L. +Yang and I. Baker demonstrated improvements in the simulation of snow +and soil temperatures. Sam Levis reported on efforts to incorporate a +river routing model to deliver runoff to the ocean model in CCSM. Soon +after the workshop, the code was delivered to NCAR for implementation +into the CCSM framework. Documentation for the Common Land Model is +provided by Dai et al. (2001) while the coupling with CCM3 is described +in Zeng et al. (2002). The model was introduced to the modeling +community in Dai et al. (2003). + +CLM2 +^^^^^^^^^^ + +Concurrent with the development of the Common Land Model, the NCAR LSM +was undergoing further development at NCAR in the areas of carbon +cycling, vegetation dynamics, and river routing. The preservation of +these advancements necessitated several modifications to the Common Land +Model. The biome-type land cover classification scheme was replaced with +a plant functional type (PFT) representation with the specification of +PFTs and leaf area index from satellite data (Oleson and Bonan 2000; +Bonan et al. 2002a, b). This also required modifications to +parameterizations for vegetation albedo and vertical burying of +vegetation by snow. Changes were made to canopy scaling, leaf +physiology, and soil water limitations on photosynthesis to resolve +deficiencies indicated by the coupling to a dynamic vegetation model. +Vertical heterogeneity in soil texture was implemented to improve +coupling with a dust emission model. A river routing model was +incorporated to improve the fresh water balance over oceans. Numerous +modest changes were made to the parameterizations to conform to the +strict energy and water balance requirements of CCSM. Further +substantial software development was also required to meet coding +standards. The resulting model was adopted in May 2002 as the Community +Land Model (CLM2) for use with the Community Atmosphere Model (CAM2, the +successor to CCM3) and version 2 of the Community Climate System Model +(CCSM2). + +K. Oleson reported on initial results from a coupling of CCM3 with CLM2 +at the June 2001 CCSM Workshop LMWG meeting. Generally, the CLM2 +preserved most of the improvements seen in the Common Land Model, +particularly with respect to surface air temperature, runoff, and snow. +These simulations are documented in Bonan et al. (2002a). Further small +improvements to the biogeophysical parameterizations, ongoing software +development, and extensive analysis and validation within CAM2 and CCSM2 +culminated in the release of CLM2 to the community in May 2002. + +Following this release, Peter Thornton implemented changes to the model +structure required to represent carbon and nitrogen cycling in the +model. This involved changing data structures from a single vector of +spatially independent sub-grid patches to one that recognizes three +hierarchical scales within a model grid cell: land unit, snow/soil +column, and PFT. Furthermore, as an option, the model can be configured +so that PFTs can share a single soil column and thus “compete†for +water. This version of the model (CLM2.1) was released to the community +in February 2003. CLM2.1, without the compete option turned on, produced +only round off level changes when compared to CLM2. + +CLM3 +^^^^^^^^^^ + +CLM3 implemented further software improvements related to performance +and model output, a re-writing of the code to support vector-based +computational platforms, and improvements in biogeophysical +parameterizations to correct deficiencies in the coupled model climate. +Of these parameterization improvements, two were shown to have a +noticeable impact on simulated climate. A variable aerodynamic +resistance for heat/moisture transfer from ground to canopy air that +depends on canopy density was implemented. This reduced unrealistically +high surface temperatures in semi-arid regions. The second improvement +added stability corrections to the diagnostic 2-m air temperature +calculation which reduced biases in this temperature. Competition +between PFTs for water, in which PFTs share a single soil column, is the +default mode of operation in this model version. CLM3 was released to +the community in June 2004. Dickinson et al. (2006) describe the climate +statistics of CLM3 when coupled to CCSM3.0. Hack et al. (2006) provide +an analysis of selected features of the land hydrological cycle. +Lawrence et al. (2007) examine the impact of changes in CLM3 +hydrological parameterizations on partitioning of evapotranspiration +(ET) and its effect on the timescales of ET response to precipitation +events, interseasonal soil moisture storage, soil moisture memory, and +land-atmosphere coupling. Qian et al. (2006) evaluate CLM3’s performance +in simulating soil moisture content, runoff, and river discharge when +forced by observed precipitation, temperature and other atmospheric +data. + +CLM3.5 +^^^^^^^^^^^^ + +Although the simulation of land surface climate by CLM3 was in many ways +adequate, most of the unsatisfactory aspects of the simulated climate +noted by the above studies could be traced directly to deficiencies in +simulation of the hydrological cycle. In 2004, a project was initiated +to improve the hydrology in CLM3 as part of the development of CLM +version 3.5. A selected set of promising approaches to alleviating the +hydrologic biases in CLM3 were tested and implemented. These included +new surface datasets based on Moderate Resolution Imaging +Spectroradiometer (MODIS) products, new parameterizations for canopy +integration, canopy interception, frozen soil, soil water availability, +and soil evaporation, a TOPMODEL-based model for surface and subsurface +runoff, a groundwater model for determining water table depth, and the +introduction of a factor to simulate nitrogen limitation on plant +productivity. Oleson et al. (2008a) show that CLM3.5 exhibits +significant improvements over CLM3 in its partitioning of global ET +which result in wetter soils, less plant water stress, increased +transpiration and photosynthesis, and an improved annual cycle of total +water storage. Phase and amplitude of the runoff annual cycle is +generally improved. Dramatic improvements in vegetation biogeography +result when CLM3.5 is coupled to a dynamic global vegetation model. +Stöckli et al. (2008) examine the performance of CLM3.5 at local scales +by making use of a network of long-term ground-based ecosystem +observations [FLUXNET (Baldocchi et al. 2001)]. Data from 15 FLUXNET +sites were used to demonstrate significantly improved soil hydrology and +energy partitioning in CLM3.5. CLM3.5 was released to the community in +May, 2007. + +CLM4 +^^^^^^^^^^ + +The motivation for the next version of the model, CLM4, was to +incorporate several recent scientific advances in the understanding and +representation of land surface processes, expand model capabilities, and +improve surface and atmospheric forcing datasets (Lawrence et al. 2011). +Included in the first category are more sophisticated representations of +soil hydrology and snow processes. In particular, new treatments of soil +column-groundwater interactions, soil evaporation, aerodynamic +parameters for sparse/dense canopies, vertical burial of vegetation by +snow, snow cover fraction and aging, black carbon and dust deposition, +and vertical distribution of solar energy for snow were implemented. +Major new capabilities in the model include a representation of the +carbon-nitrogen cycle (CLM4CN, see next paragraph for additional +information), the ability to model land cover change in a transient +mode, inclusion of organic soil and deep soil into the existing mineral +soil treatment to enable more realistic modeling of permafrost, an urban +canyon model to contrast rural and urban energy balance and climate +(CLMU), and an updated biogenic volatile organic compounds (BVOC) model. +Other modifications of note include refinement of the global PFT, +wetland, and lake distributions, more realistic optical properties for +grasslands and croplands, and an improved diurnal cycle and spectral +distribution of incoming solar radiation to force the model in offline +mode. + +Many of the ideas incorporated into the carbon and nitrogen cycle +component of CLM4 derive from the earlier development of the offline +ecosystem process model Biome-BGC (Biome BioGeochemical Cycles), +originating at the Numerical Terradynamic Simulation Group (NTSG) at the +University of Montana, under the guidance of Prof. Steven Running. +Biome-BGC itself is an extension of an earlier model, Forest-BGC +**(Running and Coughlan, 1988; Running and Gower, 1991)**, which +simulates water, carbon, and, to a limited extent, nitrogen fluxes for +forest ecosystems. Forest-BGC was designed to be driven by remote +sensing inputs of vegetation structure, and so used a diagnostic +(prescribed) leaf area index, or, in the case of the dynamic allocation +version of the model **(Running and Gower, 1991)**, prescribed maximum +leaf area index. + +Biome-BGC expanded on the Forest-BGC logic by introducing a more +mechanistic calculation of leaf and canopy scale photosynthesis **(Hunt +and Running, 1992)**, and extending the physiological parameterizations +to include multiple woody and non-woody vegetation types **(Hunt et al. +1996; Running and Hunt, 1993)**. Later versions of Biome-BGC introduced +more mechanistic descriptions of belowground carbon and nitrogen cycles, +nitrogen controls on photosynthesis and decomposition, sunlit and shaded +canopies, vertical gradient in leaf morphology, and explicit treatment +of fire and harvest disturbance and regrowth dynamics **(Kimball et al. +1997; Thornton, 1998; Thornton et al. 2002; White et al. 2000)**. +Biome-BGC version 4.1.2 **(Thornton et al. 2002)** provided a point of +departure for integrating new biogeochemistry components into CLM4. + +CLM4 was released to the community in June, 2010 along with the +Community Climate System Model version 4 (CCSM4). CLM4 is used in CCSM4, +CESM1, CESM1.1, and remains available as the default land component +model option for coupled simulations in CESM1.2. + +CLM4.5 +^^^^^^^^^^^^ + +The motivations for the development of CLM4.5 (the model version +described in this Technical Description) were similar to those for CLM4: +incorporate several recent scientific advances in the understanding and +representation of land surface processes, expand model capabilities, and +improve surface and atmospheric forcing datasets. + +Specifically, several parameterizations were revised to reflect new +scientific understanding and in an attempt to reduce biases identified +in CLM4 simulations including low soil carbon stocks especially in the +Arctic, excessive tropical GPP and unrealistically low Arctic GPP, a dry +soil bias in Arctic soils, unrealistically high LAI in the tropics, a +transient 20\ :math:`{}^{th}` century carbon response that was +inconsistent with observational estimates, and several other more minor +problems or biases. + +The main modifications include updates to canopy processes including a +revised canopy radiation scheme and canopy scaling of leaf processes, +co-limitations on photosynthesis, revisions to photosynthetic parameters +(Bonan et al. 2011), **** temperature acclimation of photosynthesis, and +improved stability of the iterative solution in the photosynthesis and +stomatal conductance model (Sun et al. 2012). Hydrology updates include +modifications such that hydraulic properties of frozen soils are +determined by liquid water content only rather than total water content +and the introduction of an ice impedance function, and other corrections +that increase the consistency between soil water state and water table +position and allow for a perched water table above icy permafrost ground +(Swenson et al. 2012). A new snow cover fraction parameterization is +incorporated that reflects the hysteresis in fractional snow cover for a +given snow depth between accumulation and melt phases (Swenson and +Lawrence, 2012). The lake model in CLM4 is replaced with a completely +revised and more realistic lake model (Subin et al. 2012a). A surface +water store is introduced, replacing the wetland land unit and +permitting prognostic wetland distribution modeling, and the surface +energy fluxes are calculated separately (Swenson and Lawrence, 2012) for +snow-covered, water-covered, and snow/water-free portions of vegetated +and crop land units, and snow-covered and snow-free portions of glacier +land units. Globally constant river flow velocity is replaced with +variable flow velocity based on mean grid cell slope. A vertically +resolved soil biogeochemistry scheme is introduced with base +decomposition rates modified by soil temperature, water, and oxygen +limitations and also including vertical mixing of soil carbon and +nitrogen due to bioturbation, cryoturbation, and diffusion (Koven et al. +2013). The litter and soil carbon and nitrogen pool structure as well as +nitrification and denitrification are modified based on the Century +model and biological fixation is revised to distribute fixation more +realistically over the year (Koven et al. 2013). The fire model is +replaced with a model that includes representations of natural and +anthropogenic triggers and suppression as well as agricultural, +deforestation, and peat fires (Li et al. 2012a,b; Li et al. 2013a). The +biogenic volatile organic compounds model is updated to MEGAN2.1 +(Guenther et al. 2012). + +Additions to the model include a methane production, oxidation, and +emissions model (Riley et al. 2011a) and an extension of the crop model +to include interactive fertilization, organ pools (Drewniak et al. +2013), and irrigation (Sacks et al. 2009). Elements of the Variable +Infiltration Capacity (VIC) model are included as an alternative +optional runoff generation scheme (Li et al. 2011). There is also an +option to run with a multilayer canopy (Bonan et al. 2012). Multiple +urban density classes, rather than the single dominant urban density +class used in CLM4, are modeled in the urban land unit. Carbon +(:math:`{}^{13}`\ C and :math:`{}^{14}`\ C) isotopes are enabled (Koven +et al. 2013). Minor changes include a switch of the C3 Arctic grass and +shrub phenology from stress deciduous to seasonal deciduous and a change +in the glacier bare ice albedo to better reflect recent estimates. +Finally, the carbon and nitrogen cycle spinup is accelerated and +streamlined with a revised spinup method, though the spinup timescale +remains long. + +Finally, the predominantly low resolution input data for provided with +CLM4 to create CLM4 surface datasets is replaced with newer and higher +resolution input datasets where possible (see section 2.2.3 for +details). The default meteorological forcing dataset provided with CLM4 +(Qian et al. 2006) is replaced with the 1901-2010 CRUNCEP forcing +dataset (see Chapter 26) for CLM4.5, though users can also still use the +Qian et al. (2006) dataset or other alternative forcing datasets. + +CLM4.5 was released to the community in June 2013 along with the +Community Earth System Model version 1.2 (CESM1.2). + +Biogeophysical and Biogeochemical Processes +----------------------------------------------- + +Biogeophysical and biogeochemical processes are simulated for each +subgrid land unit, column, and plant functional type (PFT) independently +and each subgrid unit maintains its own prognostic variables (see +section 2.1.1 for definitions of subgrid units). The same atmospheric +forcing is used to force all subgrid units within a grid cell. The +surface variables and fluxes required by the atmosphere are obtained by +averaging the subgrid quantities weighted by their fractional areas. The +processes simulated include (Figure 1.1): + +#. Surface characterization including land type heterogeneity and + ecosystem structure (Chapter 2) + +#. Absorption, reflection, and transmittance of solar radiation (Chapter + 3, 4) + +#. Absorption and emission of longwave radiation (Chapter 4) + +#. Momentum, sensible heat (ground and canopy), and latent heat (ground + evaporation, canopy evaporation, transpiration) fluxes (Chapter 5) + +#. Heat transfer in soil and snow including phase change (Chapter 6) + +#. Canopy hydrology (interception, throughfall, and drip) (Chapter 7) + +#. Snow hydrology (snow accumulation and melt, compaction, water + transfer between snow layers) (Chapter 7) + +#. Soil hydrology (surface runoff, infiltration, redistribution of water + within the column, sub-surface drainage, groundwater) (Chapter 7) + +#. Stomatal physiology and photosynthesis (Chapter 8) + +#. place Lake temperatures and fluxes (Chapter 9) + +#. Glacier processes (Chapter 10) + +#. Routing of runoff from rivers to ocean (Chapter 11) + +#. Urban energy balance and climate (Chapter 12) + +#. Vegetation carbon and nitrogen allocation and respiration (Chapter + 13) + +#. Vegetation phenology (Chapter 14) + +#. Soil and litter carbon decomposition (Chapter 15) + +#. Nitrogen cycling including deposition, biological fixation, + denitrification, leaching, and losses due to fire (Chapter 16) + +#. Plant mortality (Chapter 17) + +#. Fire ignition and suppression, including natural, deforestation, and + agricultural fire (Chapter 18) + +#. Methane production, oxidation, and emissions (Chapter 19) + +#. Crop dynamics and irrigation (Chapter 20) + +#. Land cover and land use change including wood harvest (Chapter 21) + +#. Dynamic global vegetation distribution (Chapter 22) + +#. Biogenic volatile organic compound emissions (Chapter 23) + +#. Dust mobilization and deposition (Chapter 24) + +#. Carbon isotope fractionation (Chapter 25) + +Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes +simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). + +**|image|** + +.. |image| image:: image1 diff --git a/doc/source/tech_note/CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst b/doc/source/tech_note/CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst new file mode 100644 index 0000000000..9bd3e1e11d --- /dev/null +++ b/doc/source/tech_note/CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst @@ -0,0 +1,169 @@ +Glaciers +============ + +This chapter describes features of CLM that are specific to coupling to +an ice sheet model (in the CESM context, this is the Glimmer-CISM model; +Lipscomb and Sacks (2012) provide documentation and user’s guide for +Glimmer-CISM). General information about glacier land units can be found +elsewhere in this document (see Chapter 2 for an overview). + +Overview +------------- + +CLM is responsible for computing three quantities that are passed to the +ice sheet model: + +#. Surface mass balance (SMB) – the net annual accumulation/ablation of + mass at the upper surface (section 10.3) + +#. Ground surface temperature, which serves as an upper boundary + condition for Glimmer-CISM’s temperature calculation + +#. Surface topography, which currently is fixed in time, and is provided + on CLM’s surface dataset + +The ice sheet model is typically run at much higher resolution than CLM +(e.g., :math:`\sim`\ 5 km rather than :math:`\sim`\ 100 km). To improve +the downscaling from CLM’s grid to the ice sheet grid, the glaciated +portion of each grid cell is divided into multiple elevation classes +(section 10.2). The above quantities are computed separately in each +elevation class. Glimmer-CISM then computes high-resolution quantities +via horizontal and vertical interpolation. + +There are several reasons for computing the SMB in CLM rather than in +Glimmer-CISM: + +#. It is much cheaper to compute the SMB in CLM for :math:`\sim`\ 10 + elevation classes than in Glimmer-CISM. For example, suppose we are + running CLM at a resolution of :math:`\sim`\ 50 km and Glimmer at + :math:`\sim`\ 5 km. Greenland has dimensions of about 1000 x 2000 km. + For CLM we would have 20 x 40 x 10 = 8,000 columns, whereas for + Glimmer we would have 200 x 400 = 80,000 columns. + +#. We can use the sophisticated snow physics parameterization already in + CLM instead of implementing a separate scheme for Glimmer-CISM. Any + improvements to the CLM are applied to ice sheets automatically. + +#. The atmosphere model can respond during runtime to ice-sheet surface + changes. As shown by Pritchard et al. (2008), runtime albedo feedback + from the ice sheet is critical for simulating ice-sheet retreat on + paleoclimate time scales. Without this feedback the atmosphere warms + much less, and the retreat is delayed. + +#. Mass is more nearly conserved, given that the rate of surface ice + growth or melting computed in CLM is equal to the rate seen by the + dynamic ice sheet model. (Mass conservation is not exact, however, + because of approximations made in interpolating from the CLM grid to + the ice-sheet grid.) + +#. The improved SMB is available in CLM for all glaciated grid cells + (e.g., in the Alps, Rockies, Andes, and Himalayas), not just those + which are part of ice sheets. + +The current coupling between CLM and Glimmer-CISM is one-way only. That +is, CLM sends the SMB and surface temperature to Glimmer-CISM but does +not do anything with the fields that are returned. The CLM glacier +fraction and surface topography are therefore fixed in time. One-way +coupling is reasonable for runs of :math:`\sim`\ 100 years or less, in +which ice-sheet elevation changes are modest. For longer runs with +larger elevation changes, two-way coupling is highly desirable. A +two-way coupling scheme is under development. + +Multiple elevation class scheme +------------------------------------ + +In the typical operation of CLM, the glacier land unit contains a single +column (section 2.1.1). However, when running CESM with an active ice +sheet model, the glacier land unit is replaced by a glacier\_mec land +unit, where “mec†denotes “multiple elevation classesâ€. In most ways, +glacier\_mec land units behave the same as standard glacier land units. +However, each glacier\_mec land unit is divided into a user-defined set +of columns based on surface elevation. The default is 10 elevation +classes whose lower limits are 0, 200, 400, 700, 1000, 1300, 1600, 2000, +2500, and 3000 m. Each column is characterized by a fractional area and +surface elevation that are read in during model initialization. Each +glacier\_mec column within a grid cell has distinct ice and snow +temperatures, snow water content, surface fluxes, and SMB. + +Glacier\_mec columns, like glacier columns, are initialized with a +temperature of 250 K. While glacier columns are initialized with a snow +liquid water equivalent (LWE) equal to the maximum allowed value of 1 m, +glacier\_mec columns begin with a snow LWE of 0.5 m so that they will +reach their equilibrium mean snow depth sooner. Glacier\_mec columns +typically require several decades of spin-up to equilibrate with a given +climate. + +The atmospheric surface temperature, potential temperature, specific +humidity, density, and pressure are downscaled from the mean grid cell +elevation to the glacier\_mec column elevation using a specified lapse +rate (typically 6.0 deg/km) and an assumption of uniform relative +humidity. At a given time, lower-elevation columns can undergo surface +melting while columns at higher elevations remain frozen. This gives a +more accurate simulation of summer melting, which is a highly nonlinear +function of air temperature. The precipitation rate and radiative fluxes +are not currently downscaled, but could be in the future if care were +taken to preserve the cell-integrated values. + +In contrast to most CLM subgrid units, glacier\_mec columns can be +active (i.e., have model calculations run there) even if their area is +zero. This is done because the ice sheet model may require a SMB even +for some grid cells where CLM does not have glacier land units. To allow +for this, grid overlap files have been pre-computed. For given +resolutions of CLM and Glimmer-CISM, these files identify all +land-covered grid cells that overlap any part of the ice sheet grid. In +these overlapping cells, glacier\_mec columns are defined in all +elevation classes. Some columns may have zero area and are called +“virtual†columns. These columns do not affect energy exchange between +the land and the atmosphere, but are included for potential forcing of +Glimmer-CISM. + +Computation of the surface mass balance +-------------------------------------------- + +The SMB of a glacier or ice sheet is the net annual +accumulation/ablation of mass at the upper surface. Ablation is defined +as the mass of water that runs off to the ocean. Not all the surface +meltwater runs off; some of the melt percolates into the snow and +refreezes. Accumulation is primarily by snowfall and deposition, and +ablation is primarily by melting and evaporation/sublimation. CLM uses a +surface-energy-balance (SEB) scheme to compute the SMB. In this scheme, +the melting depends on the sum of the radiative, turbulent, and +conductive fluxes reaching the surface, as described elsewhere in this +document. + +CLM has a somewhat unrealistic treatment of accumulation and melting for +standard glacier land units. The snow depth is limited to a prescribed +depth of 1 m liquid water equivalent, with any additional snow assumed +to run off to the ocean. (This amounts to a crude parameterization of +iceberg calving.) Snow melting is treated in a realistic fashion, with +meltwater percolating downward through snow layers as long as the snow +is unsaturated. Once the underlying snow is saturated, any additional +meltwater runs off. When glacier ice melts, however, the meltwater is +assumed to remain in place until it refreezes. In warm parts of the ice +sheet, the meltwater does not refreeze, but stays in place indefinitely. + +In the modified glacier\_mec columns, the treatment of melting and +freezing depends on the logical variable *glc\_dyntopo*. This variable +controls whether CLM surface topography changes dynamically as the ice +sheet evolves (i.e., whether the coupling is one-way or two-way). If +*glc\_dyntopo* is true, then CLM receives updated topographic +information from the ice sheet model. In this case, snow in excess of +the prescribed maximum depth is assumed to turn into ice, contributing a +positive SMB to the ice sheet model. Melting ice is assumed to run off +to the ocean, giving a negative SMB. The net SMB associated with ice +formation (by conversion from snow) and melting/runoff is computed for +each column, averaged over the coupling interval, and sent to the +coupler (*qice, mm/s*). If *glc\_dyntopo* is false, then surface runoff +for glacier\_mec land units is computed as for glacier land units: Any +snow in excess of 1 m LWE runs off to the ocean, and Melted ice remains +in place until it refreezes. Excess snow and melted ice still contribute +to positive and negative values, respectively, of *qice*, but only for +the purpose of forcing Glimmer-CISM. Currently, *glc\_dyntopo* = false +is the default, and the only supported option. + +Note that the SMB typically is defined as the total accumulation of ice +and snow, minus the total ablation. The *qice* flux passed to +Glimmer-CISM is the mass balance for ice alone, not snow. We can think +of CLM as owning the snow, whereas Glimmer-CISM owns the underlying ice. +Fluctuations in snow depth between 0 and 1 m LWE are not reflected in +the SMB passed to Glimmer-CISM. diff --git a/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst b/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst new file mode 100644 index 0000000000..2f1fd04e7b --- /dev/null +++ b/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst @@ -0,0 +1,139 @@ +River Transport Model (RTM) +=============================== + +The RTM was developed to route total runoff from the land surface model +to either the active ocean or marginal seas which enables the hydrologic +cycle to be closed (Branstetter 2001, Branstetter and Famiglietti 1999). +This is needed to model ocean convection and circulation, which is +affected by freshwater input. It also provides another method of +diagnosing the performance of the land model because the river flow can +be directly compared to gauging station data (e.g., Dai and Trenberth +2002). + +To improve global energy conservation when CLM is being run as part of +the Community Climate System Model, runoff is split into two streams, a +liquid water stream and an ice water stream (derived from excess +snowfall in snow-capped grid cells, section 7.7). The liquid and ice +streams are routed through the RTM, passed to, and dealt with by the +ocean separately. + +The RTM uses a linear transport scheme to route water from each grid +cell to its downstream neighboring grid cell. The change in storage +:math:`S` of river water, whether it be liquid or ice, within a RTM grid +cell (m\ :math:`{}^{3}` s\ :math:`{}^{-1}`) is + +.. math:: + :label: ZEqnNum723341 + + \frac{dS}{dt} =\sum F_{in} -F_{out} +R + +where :math:`\sum F_{in}` is the sum of inflows of water from +neighboring upstream grid cells (m\ :math:`{}^{3}` s\ :math:`{}^{-1}`), +:math:`F_{out}` is the flux of water leaving the grid cell in the +downstream direction (m :math:`{}^{3}` s\ :math:`{}^{-1}`), and :math:`R` +is the total runoff generated by the land model grid cell +(m\ :math:`{}^{3}` s\ :math:`{}^{-1}`). Downstream water flow direction in +each grid cell is determined as one of eight compass points (north, +northeast, east, southeast, south, southwest, west, and northwest) based +on the steepest downhill slope as determined from a digital elevation +model (Graham et al. 1999). The flux of water leaving the grid cell +:math:`F_{out}` is + +.. math:: + :label: 11.2) + + F_{out} =\frac{v}{d} S + +where :math:`v` is the effective water flow velocity (m +s\ :math:`{}^{-1}`), :math:`d` is the distance between centers of +neighboring grid cells (m), and :math:`S` is the volume of river water +stored within the grid cell (m\ :math:`{}^{3}`). The effective water flow +velocity can be estimated from Manning’s equation, which is a function +of surface water slope, the hydraulic radius of the river channel, and a +channel roughness coefficient (Dingman, 2002). However, hydraulic radius +and channel roughness data are not available globally, so a simplified +effective flow velocity expression is used in RTM + +.. math:: + :label: 11.2) + + v=\max \left(0.05,k\beta ^{1/2} \right) + +where :math:`\beta` is the grid cell mean topographic slope, and +:math:`k=1`. + +The distance :math:`d` between two grid cell centers depends on river +direction, latitude, and longitude as + +.. math:: + :label: 11.3) + + d=\sqrt{\Delta x^{2} +\Delta y^{2} } . + +The distance in the zonal direction :math:`\Delta x` (m) is + +.. math:: + :label: 11.4) + + \Delta x=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right)\left[0.5\left(\cos \phi _{i,\, j} +\cos \phi _{i*,\, j*} \right)\right] + +where :math:`\theta _{i,\, j}` and :math:`\theta _{i*,\, j*}` are the +latitudes (radians) of the upstream and downstream grid cells, +:math:`\phi _{i,\, j}` and :math:`\phi _{i*,\, j*}` are the longitudes +(radians) of the upstream and downstream grid cells, :math:`R_{e}` is +the radius of the earth (km) (Table 2.6), and :math:`i` and :math:`j` +are grid cell indices. The distance in the meridional direction +:math:`\Delta y` (m) is + +.. math:: + :label: 11.5) + + \Delta y=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right). + +The RTM is generally run at a time step greater than that of the CLM +because of computational constraints. The total runoff from the land +model at each time step is accumulated until the RTM is invoked. The +total liquid water runoff at the land model resolution (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is + +.. math:: + :label: 11.6) + + R_{liq} =q_{over} +q_{drai} +q_{rgwl} + +where :math:`q_{over}` is surface runoff (section 7.3), +:math:`q_{drai}` is sub-surface drainage (section 7.6), and +:math:`q_{rgwl}` is liquid runoff from glaciers, wetlands, and lakes +(all in kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) (sections 7.7 and +9.6.3). The total ice water runoff, also at the land model resolution is + +.. math:: + :label: 11.7) + + R_{ice} =q_{snwcp,ice} + +where :math:`q_{snwcp,ice}` is the ice runoff from snow-capped +surfaces (section 7.7). The runoff at the land model resolution is +interpolated to the resolution of RTM and converted to units of +m\ :math:`{}^{3}` s\ :math:`{}^{-1}` for use in equation by multiplying +by :math:`1\times 10^{-3} A` where :math:`A` is the area +(m\ :math:`{}^{2}`) of the RTM grid cell. + +The RTM grid cells that are at river mouths, hence providing freshwater +flux to the ocean, are identified by examining each RTM ocean grid cell +and determining if a RTM land grid cell flows to that ocean grid cell. +River mouth grid cells are also assigned if any overlapping grid cells +at the land model resolution contain land. When used as part of the +Community Climate System Model, the ocean freshwater liquid and ice +fluxes at the RTM resolution are passed to the flux coupler which +distributes the fluxes to the appropriate ocean grid cells. When used +with the Community Atmosphere Model or when run offline, RTM serves only +as a diagnostic tool. The river-routing scheme conserves water globally +as + +.. math:: + :label: 11.8) + + \sum _{i,\, j}\left(\frac{dS}{dt} \right) _{i,\, j} =\sum _{i,\, j}R_{i,\, j} . + + diff --git a/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst b/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst new file mode 100644 index 0000000000..f4e74d3731 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst @@ -0,0 +1,130 @@ +Urban Model (CLMU) +====================== + +At the global scale, and at the coarse spatial resolution of current +climate models, urbanization has negligible impact on climate. However, +the urban parameterization (CLMU; Oleson et al. 2008b,c) allows +simulation of the urban environment within a climate model, and +particularly the temperature where people live. As such, the urban model +allows scientific study of how climate change affects the urban heat +island and possible urban planning and design strategies to mitigate +warming (e.g., white roofs). + +The urban model that was released as a component of CLM4.0 is separately +described in the urban technical note (Oleson et al. 2010b). Here, we +provide a brief overview of the urban model released as a component of +CLM4.5. The main changes in the urban model from CLM4.0 to CLM4.5 are 1) +an expansion of the single urban landunit to up to three landunits per +grid cell stratified by urban density types, 2) the number of urban +layers for roofs and walls is no longer constrained to be equal to the +number of ground layers, 3) space heating and air conditioning wasteheat +factors are now set to zero by default so that the user can customize +these factors for their own application, 4) the elevation threshold used +to eliminate urban areas in the surface dataset creation routines has +been changed from 2200 meters to 2600 meters, 5) hydrologic and thermal +calculations for the pervious road now follows CLM4.5 parameterizations. + +Urban areas in CLM are represented by up to three urban landunits per +gridcell according to density class. The urban landunit is based on the +“urban canyon†concept of Oke (1987) in which the canyon geometry is +described by building height (:math:`H`) and street width (:math:`W`) +(Figure 12.1). The canyon system consists of roofs, walls, and canyon +floor. Walls are further divided into shaded and sunlit components. The +canyon floor is divided into pervious (e.g., to represent residential +lawns, parks) and impervious (e.g., to represent roads, parking lots, +sidewalks) fractions. Vegetation is not explicitly modeled for the +pervious fraction; instead evaporation is parameterized by a simplified +bulk scheme. + +Each of the five urban surfaces is treated as a column within the +landunit (Figure 12.1). Radiation parameterizations account for trapping +of solar and longwave radiation inside the canyon. Momentum fluxes are +determined for the urban landunit using a roughness length and +displacement height appropriate for the urban canyon and stability +formulations from CLM. A one-dimensional heat conduction equation is +solved numerically for a multiple-layer (:math:`N_{levurb} =5`) column +to determine conduction fluxes into and out of canyon surfaces. The +interior boundary conditions for roofs and walls are determined by an +interior building temperature (:math:`T_{iB}` ) held between prescribed +maximum and minimum temperatures +(:math:`T_{iB,\, \max } ,\, T_{iB,\, \min }` ), thus explicitly +resolving space heating and air conditioning fluxes. Anthropogenic +sources of waste heat (:math:`Q_{H,\, waste}` ) from air conditioning +and space heating can be optionally incorporated as modifications to the +canyon energy budget. Turbulent [sensible heat (:math:`Q_{H,\, u}` ) and +latent heat (:math:`Q_{E,\, u}` )] and storage (:math:`Q_{S,\, u}` ) +heat fluxes and surface (:math:`T_{u,\, s}` ) and internal +(:math:`T_{u,\, i=1,\, N_{levgrnd} }` ) temperatures are determined for +each urban surface :math:`u`. Hydrology on the roof and canyon floor is +simulated and walls are hydrologically inactive. A snowpack can form on +the active surfaces. A certain amount of liquid water is allowed to pond +on these surfaces which supports evaporation. Water in excess of the +maximum ponding depth runs off +(:math:`R_{roof} ,\, R_{imprvrd} ,\, R_{prvrd}` ). + +The heat and moisture fluxes from each surface interact with each other +through a bulk air mass that represents air in the urban canopy layer +for which specific humidity (:math:`q_{ac}` ) and temperature +(:math:`T_{ac}` ) are prognosed (Figure 12.2). The air temperature can +be compared with that from surrounding vegetated/soil (rural) surfaces +in the model to ascertain heat island characteristics. As with other +landunits, the CLMU is forced either with output from a host atmospheric +model (e.g., the Community Atmosphere Model (stocktickerCAM)) or +observed forcing (e.g., reanalysis or field observations). The urban +model produces sensible, latent heat, and momentum fluxes, emitted +longwave, and reflected solar radiation, which are area-averaged with +fluxes from non-urban “landunits†(e.g., vegetation, lakes) to supply +grid cell averaged fluxes to the atmospheric model. + +Present day global urban extent and urban properties were developed by +Jackson et al. (2010). Urban extent, defined for four classes [tall +building district (TBD), and high, medium, and low density (HD, MD, +LD)], was derived from LandScan 2004, a population density dataset +derived from census data, nighttime lights satellite observations, road +proximity, and slope (Dobson et al. 2000). The urban extent data for +TBD, HD, and MD classes are aggregated from the original 1 km resolution +to both a 0.05\ :math:`{}^\circ` by 0.05\ :math:`{}^\circ` global grid +for high-resolution studies or a 0.5\ :math:`{}^\circ` by +0.5\ :math:`{}^\circ` grid. For the current implementation, the LD class +is not used because it is highly rural and better modeled as a +vegetated/soil surface. Although the TBD, HD, and MD classes are +represented as individual urban landunits, urban model history output is +currently a weighted average of the output for individual classes. + +For each of 33 distinct regions across the globe, thermal (e.g., heat +capacity and thermal conductivity), radiative (e.g., albedo and +emissivity) and morphological (e.g., height to width ratio, roof +fraction, average building height, and pervious fraction of the canyon +floor) properties are provided for each of the density classes. Building +interior minimum and maximum temperatures are prescribed based on +climate and socioeconomic considerations. The surface dataset creation +routines (see CLM4.5 User’s Guide) aggregate the data to the desired +resolution. + +Figure 12.1. Schematic representation of the urban land unit. + +See the text for description of notation. Incident, reflected, and net +solar and longwave radiation are calculated for each individual surface +but are not shown for clarity. + +.. image:: image1.png + +Figure 12.2. Schematic of urban and atmospheric model coupling. + +The urban model is forced by the atmospheric model wind +(:math:`u_{atm}` ), temperature (**:math:`T_{atm}` **), specific +humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar +(:math:`S_{atm} \, \downarrow` ) and longwave +(:math:`L_{atm} \, \downarrow` ) radiation at reference height +:math:`z'_{atm}` (section 2.2.1). Fluxes from the urban landunit to the +atmosphere are turbulent sensible (:math:`H`) and latent heat +(:math:`\lambda E`), momentum (:math:`\tau` ), albedo + +(:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and +absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature + +(:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed +(:math:`u_{c}` ) within the urban canopy layer are diagnosed by the +urban model. :math:`H` is the average building height. + +.. image:: image2.png diff --git a/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst b/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst new file mode 100644 index 0000000000..c4a4ab2345 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst @@ -0,0 +1,599 @@ +Carbon and Nitrogen Pools, Allocation, and Respiration +========================================================== + +Introduction +----------------- + +CLM includes a fully-prognostic treatment of the terrestrial carbon and +nitrogen cycles including interactions between these cycles as mediated +by biological mechanisms of plants and soil heterotrophs. The model is +fully prognostic with respect to all carbon and nitrogen state variables +in the vegetation, litter, and soil organic matter. The seasonal timing +of new vegetation growth and litterfall is also prognostic, responding +to soil and air temperature, soil water availability, and daylength, in +varying degrees depending on a specified phenology type for each PFT +(see Chapter 14). The prognostic LAI, SAI, and vegetation heights are +utilized by the biophysical model. + +Separate state variables for C and N are tracked for leaf, live stem, +dead stem, live coarse root, dead coarse root, and fine root pools +(Figure 13.1 and 13.2). Each of these pools has two corresponding +storage pools representing, respectively, short-term and long-term +storage of non-structural carbohydrates and labile nitrogen. There are +two additional carbon pools, one for the storage of growth respiration +reserves, and another used to meet excess demand for maintenance +respiration during periods with low photosynthesis. One additional +nitrogen pool tracks retranslocated nitrogen, mobilized from leaf tissue +prior to abscission and litterfall. Altogether there are 20 state +variables for vegetation carbon, and 19 for vegetation nitrogen. + +Figure 13.1. Vegetation fluxes and pools. + +.. image:: image1.png + :width: 800px + :height: 800px + +Figure 13.2: Carbon and nitrogen pools. + +.. image:: image2.png + :width: 400px + :height: 400px + +Carbon Allocation for Maintenance Respiration Costs +-------------------------------------------------------- + +The carbon and nitrogen allocation routines in CLM determine the fate of +newly assimilated carbon, coming from the calculation of photosynthesis, +and available mineral nitrogen, coming from plant uptake of mineral +nitrogen in the soil or being drawn out of plant reserves. Allocation +fluxes are determined in three steps: first :math:`CF_{GPPpot}` is +used to evaluate the potential allocation of carbon and nitrogen +assuming an unlimited nitrogen supply, then the actual nitrogen supply +is compared against the demand, and finally allocation of carbon and +nitrogen are reduced, if necessary, to match nitrogen supply and demand. + +Allocation of available carbon on each time step is prioritized, with +first priority given to the demand for carbon to support maintenance +respiration of live tissues (section 13.7). Second priority is to +replenish the internal plant carbon pool that supports maintenance +respiration during times when maintenance respiration exceeds +photosynthesis (e.g. at night, during winter for perennial vegetation, +or during periods of drought stress) (Sprugel et al., 1995). Third +priority is to support growth of new tissues, including allocation to +storage pools from which new growth will be displayed in subsequent time +steps. + +The total maintenance respiration demand (:math:`CF_{mr}`, gC +m\ :sup:`-2` s\ :math:`{}^{-1}`) is calculated as a function of +tissue mass and nitrogen concentration, and temperature (section 13.7). +The carbon supply to support this demand is composed of fluxes allocated +from carbon assimilated in the current timestep +(:math:`CF_{GPP,mr}`, gC m\ :sup:`-2` s\ :math:`{}^{-1}`) +and from a storage pool that is drawn down when total demand exceeds +photosynthesis ( :math:`CF_{xs,mr}`, gC m\ :sup:`-2` +s\ :math:`{}^{-1}`): + +.. math:: + :label: 13.1) + + CF_{mr} =CF_{GPP,mr} +CF_{xs,mr} + +.. math:: + :label: 13.2) + + CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. + +.. math:: + :label: 13.3) + + CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{mr} -CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. + +The storage pool that supplies carbon for maintenance respiration in +excess of current :math:`CF_{GPPpot}` ( :math:`CS_{xs}`, gC +m\ :sup:`-2`) is permitted to run a deficit (negative state), and +the magnitude of this deficit determines an allocation demand which +gradually replenishes :math:`CS_{xs}`. The logic for allowing a +negative state for this pool is to eliminate the need to know in advance +what the total maintenance respiration demand will be for a particular +combination of climate and plant type. Using the deficit approach, the +allocation to alleviate the deficit increases as the deficit increases, +until the supply of carbon into the pool balances the demand for carbon +leaving the pool in a quasi-steady state, with variability driven by the +seasonal cycle, climate variation, disturbance, and internal dynamics of +the plant-litter-soil system. In cases where the combination of climate +and plant type are not suitable to sustained growth, the deficit in this +pool increases until the available carbon is being allocated mostly to +alleviate the deficit, and new growth approaches zero. The allocation +flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC +m\ :sup:`-2` s\ :math:`{}^{-1}`) is given as + +.. math:: + :label: 13.4) + + CF_{GPP,xs,pot} =\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CS_{xs} \ge 0} \\ {-CS_{xs} /(86400\tau _{xs} )\qquad {\rm for\; }CS_{xs} <0} \end{array}\right. + +.. math:: + :label: 13.5) + + CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPPpot} -CF_{GPP,mr} } \\ {\max (CF_{GPPpot} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPPpot} -CF_{GPP,mr} } \end{array}\right. + +where :math:`\tau_{xs}` is the time constant (currently +set to 30 days) controlling the rate of replenishment of :math:`CS_{xs}`. + +Note that these two top-priority carbon allocation fluxes +(:math:`CF_{GPP,mr}` and :math:`CF_{GPP,xs}`) are not +stoichiometrically associated with any nitrogen fluxes, and so this +initial allocation step can proceed without reference to (or limitation +from) the available mineral nitrogen supply. + +Carbon and Nitrogen Stoichiometry of New Growth +---------------------------------------------------- + +After accounting for the carbon cost of maintenance respiration, the +remaining carbon flux from photosynthesis which can be allocated to new +growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :math:`{}^{-1}`) is + +.. math:: + :label: 13.6) + + CF_{avail\_ alloc} =CF_{GPPpot} -CF_{GPP,mr} -CF_{GPP,xs} . + +Potential allocation to new growth is calculated for all of the plant +carbon and nitrogen state variables based on specified C:N ratios for +each tissue type and allometric parameters that relate allocation +between various tissue types. The allometric parameters are defined as +follows: + +.. math:: + :label: ZEqnNum650137 + + \begin{array}{l} {a_{1} ={\rm \; ratio\; of\; new\; fine\; root\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{2} ={\rm \; ratio\; of\; new\; coarse\; root\; :\; new\; stem\; carbon\; allocation}} \\ {a_{3} ={\rm \; ratio\; of\; new\; stem\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{4} ={\rm \; ratio\; new\; live\; wood\; :\; new\; total\; wood\; allocation}} \\ {g_{1} ={\rm ratio\; of\; growth\; respiration\; carbon\; :\; new\; growth\; carbon.\; }} \end{array} + +Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined as constants for a given PFT (Table +13.1), while :math:`g_{l }` = 0.3 (unitless) is prescribed as a +constant for all PFTs, based on construction costs for a range of woody +and non-woody tissues (Larcher, 1995). + +The model includes a dynamic allocation scheme for woody vegetation +(parameter :math:`a_{3}` = -1, Table 13.1), in which case the +ratio for carbon allocation between new stem and new leaf increases with +increasing net primary production (NPP), as + +.. math:: + :label: 13.8) + + a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 + +where :math:`NPP_{ann}` is the annual sum of NPP from the previous +year. This mechanism has the effect of increasing woody allocation in +favorable growth environments (Allen et al., 2005; Vanninen and Makela, +2005) and during the phase of stand growth prior to canopy closure +(Axelsson and Axelsson, 1986). + +Table 13.1. Allocation and carbon:nitrogen ratio parameters + ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`CN_{leaf}` | :math:`CN_{fr}` | :math:`CN_{lw}` | :math:`CN_{dw}` | ++==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ +| NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| NET Boreal | 1 | 0.3 | -1 | 0.1 | 40 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| NDT Boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BET Tropical | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BET temperate | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDT tropical | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDT temperate | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDT boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BES temperate | 1 | 0.3 | 0.2 | 0.5 | 30 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDS temperate | 1 | 0.3 | 0.2 | 0.5 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| C\ :math:`{}_{3}` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| C\ :math:`{}_{3}` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| C\ :math:`{}_{4}` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Crop R | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Crop I | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Corn R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Corn I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Temp Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Temp Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Winter Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Winter Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Soybean R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Soybean I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + +Carbon to nitrogen ratios are defined for different tissue types as +follows: + +.. math:: + :label: ZEqnNum413927 + + \begin{array}{l} {CN_{leaf} =\_ {\rm \; C:N\; for\; leaf}} \\ {CN_{fr} =\_ {\rm \; C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \; C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\_ {\rm \; C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} + +where all C:N parameters are defined as constants for a given PFT (Table +13.1). + +Given values for the parameters in and , total carbon and nitrogen +allocation to new growth ( :math:`CF_{alloc}`, gC +m\ :sup:`-2` s\ :math:`{}^{-1}`, and :math:`NF_{alloc}`, gN +m\ :sup:`-2` s\ :math:`{}^{-1}`, respectively) can be expressed as +functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC +m\ :sup:`-2` s\ :math:`{}^{-1}`): + +.. math:: + :label: ZEqnNum555154 + + \begin{array}{l} {CF_{alloc} =CF_{GPP,leaf} {\kern 1pt} C_{allom} } \\ {NF_{alloc} =CF_{GPP,leaf} {\kern 1pt} N_{allom} } \end{array} + +where + +.. math:: + :label: 13.11) + + \begin{array}{l} {C_{allom} =\left\{\begin{array}{l} {\left(1+g_{1} \right)\left(1+a_{1} +a_{3} \left(1+a_{2} \right)\right)\qquad {\rm for\; woody\; PFT}} \\ {1+g_{1} +a_{1} \left(1+g_{1} \right)\qquad \qquad {\rm for\; non-woody\; PFT}} \end{array}\right. } \\ {} \end{array} + +.. math:: + :label: 13.12) + + N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. + +Since the C:N stoichiometry for new growth allocation is defined, from +Eq. , as :math:`C_{allom}`/ :math:`N_{allom}`, the total carbon available for new growth allocation +(:math:`CF_{avail\_alloc}`) can be used to calculate the total +plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, +gN m\ :sup:`-2` s\ :math:`{}^{-1}`) as: + +.. math:: + :label: 13.13) + + NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . + +Deployment of retranslocated nitrogen +------------------------------------------ + +In many plants, some portion of the nitrogen used to construct new +tissues is mobilized from senescing tissues, especially leaves, and +retained within the plant when the tissues are lost as litter. This +store of retranslocated nitrogen is used to supply part of the nitrogen +demand for subsequent growth (Magill et al., 1997; Oikawa et al., 2005; +Son and Gower, 1991). CLM includes one pool of retranslocated nitrogen +(:math:`NS_{retrans}`, gN m\ :sup:`-2`), and the +availability of nitrogen from this pool to support new growth +(:math:`NF_{avail\_retrans}`, gN m\ :sup:`-2` +s\ :math:`{}^{-1}`) is proportional to the plant nitrogen demand, as: + +.. math:: + :label: 13.14) + + NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) + +where :math:`NF_{retrans\_ann}` (gN m\ :sup:`-2` y\ :math:`{}^{-1}`) is the previous year’s annual sum of retranslocated +nitrogen extracted from senescing tissues, +:math:`NF_{plant\_demand\_ann}` (gN m\ :sup:`-2` y\ :math:`{}^{-1}`) is the previous year’s annual sum of +:math:`NF_{plant\_demand}`, and :math:`\Delta`\ *t* (s) is the +model’s biogeochemistry time step. This formulation produces an annual +cycle in the extraction of nitrogen from :math:`NS_{retrans}` +which corresponds to the annual cycle of plant nitrogen demand, and +which is scaled to give :math:`NS_{retrans}` approximately a +one-year turnover time. The minimum function prevents extraction of more +than the remaining pool of retranslocated nitrogen, which can be an +important constraint under conditions where high rates of mortality are +modifying the size of the pool. During the first year of an initial +simulation, before :math:`NF_{plant\_demand\_ann}` and +:math:`NF_{retrans\_ann}` have valid values, +:math:`NF_{avail\_retrans}` is set to 0.0. + +The actual flux of nitrogen from the retranslocated N pool into +allocation of new growth (:math:`NF_{retrans,alloc}`, gN +m\ :sup:`-2` s\ :math:`{}^{-1}`) is never greater than the plant +demand for new nitrogen: + +.. math:: + :label: 13.15) + + NF_{retrans,alloc} =\min \left(NF_{plant\_ demand} ,NF_{avail\_ retrans} \right) + +Plant nitrogen uptake from soil mineral nitrogen pool +---------------------------------------------------------- + +The total plant nitrogen demand is reduced by the nitrogen flux from +:math:`NS_{retrans}` to give the plant demand for mineral nitrogen +from the soil (:math:`NF_{plant\_demand\_soil}`, gN +m\ :sup:`-2` s\ :math:`{}^{-1}`): + +.. math:: + :label: ZEqnNum491412 + + NF_{plant\_ demand\_ soil} =NF_{plant\_ demand} -NF_{retrans,alloc} . + +The combined demand from all PFTs sharing space on a soil column and the +demand from the heterotrophic community in the soil (nitrogen +immobilization demand) compete for the available soil mineral nitrogen +pool. The result of this competition is passed back to the allocation +algorithm as :math:`f_{plant\_demand}`, the fraction (from 0 to 1) +of the plant nitrogen demand which can be met given the current soil +mineral nitrogen supply and competition with heterotrophs. Plant uptake +from the soil mineral nitrogen pool is then given as: + +.. math:: + :label: 13.17) + + NF_{sminn,alloc} =NF_{plant\_ demand\_ soil} f_{plant\_ demand} + +Final carbon and nitrogen allocation +----------------------------------------- + +The total flux of allocated nitrogen is given as: + +.. math:: + :label: 13.18) + + NF_{alloc} =NF_{retrans,alloc} +NF_{sminn,alloc} + +From the stoichiometric relationship in Eq. , the associated carbon +allocation flux is: + +.. math:: + :label: 13.19) + + CF_{alloc} =NF_{alloc} \frac{C_{allom} }{N_{allom} } . + +The downregulation of photosynthesis can then be calculated as: + +.. math:: + :label: 13.20) + + f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . + +Total allocation to new leaf carbon +(:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :math:`{}^{-1}`) is calculated as: + +.. math:: + :label: 13.21) + + CF_{alloc,leaf\_ tot} =\frac{CF_{alloc} }{C_{allom} } . + +There are two carbon pools associated with each plant tissue – one which +represents the currently displayed tissue, and another which represents +carbon stored for display in a subsequent growth period. The nitrogen +pools follow this same organization. The model keeps track of stored +carbon according to which tissue type it will eventually be displayed +as, and the separation between display in the current timestep and +storage for later display depends on the parameter :math:`f_{cur}` +(values 0 to 1). Given :math:`CF_{alloc,leaf}` and :math:`f_{cur}`, the allocation fluxes of carbon to display and +storage pools (where storage is indicated with *\_stor*) for the various +tissue types are given as: + +.. math:: + :label: 13.22) + + CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} + +.. math:: + :label: 13.23) + + CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) + +.. math:: + :label: 13.24) + + CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} + +.. math:: + :label: 13.25) + + CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) + +.. math:: + :label: 13.26) + + CF_{alloc,livestem} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} f_{cur} + +.. math:: + :label: 13.27) + + CF_{alloc,livestem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} \left(1-f_{cur} \right) + +.. math:: + :label: 13.28) + + CF_{alloc,deadstem} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)f_{cur} + +.. math:: + :label: 13.29) + + CF_{alloc,deadstem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right) + +.. math:: + :label: 13.30) + + CF_{alloc,livecroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} f_{cur} + +.. math:: + :label: 13.31) + + CF_{alloc,livecroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} \left(1-f_{cur} \right) + +.. math:: + :label: 13.32) + + CF_{alloc,deadcroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)f_{cur} + +.. math:: + :label: 13.33) + + CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). + +The corresponding nitrogen allocation fluxes are given as: + +.. math:: + :label: 13.34) + + NF_{alloc,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} + +.. math:: + :label: 13.35) + + NF_{alloc,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) + +.. math:: + :label: 13.36) + + NF_{alloc,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} + +.. math:: + :label: 13.37) + + NF_{alloc,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) + +.. math:: + :label: 13.38) + + NF_{alloc,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} + +.. math:: + :label: 13.39) + + NF_{alloc,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) + +.. math:: + :label: 13.40) + + NF_{alloc,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} + +.. math:: + :label: 13.41) + + NF_{alloc,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) + +.. math:: + :label: 13.42) + + NF_{alloc,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} + +.. math:: + :label: 13.43) + + NF_{alloc,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) + +.. math:: + :label: 13.44) + + NF_{alloc,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} + +.. math:: + :label: 13.45) + + NF_{alloc,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). + +Autotrophic Respiration +---------------------------- + +The model treats maintenance and growth respiration fluxes separately, +even though it is difficult to measure them as separate fluxes (Lavigne +and Ryan, 1997; Sprugel et al., 1995). Maintenance respiration is +defined as the carbon cost to support the metabolic activity of existing +live tissue, while growth respiration is defined as the additional +carbon cost for the synthesis of new growth. + +13.7.1 Maintenance Respiration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Under the assumption that tissue nitrogen content is a suitable index of +cellular metabolic rate, maintenance respiration costs for live tissues +(leaf, live stem, live coarse root, and fine root) are calculated as +functions tissue nitrogen content and the relevant temperature, +following the empirical relationship reported by Ryan (1991): + +.. math:: + :label: 13.46) + + CF_{mr\_ leaf} \_ =NS_{leaf} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + +.. math:: + :label: 13.47) + + CF_{mr\_ livestem} \_ =NS_{livestem} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + +.. math:: + :label: 13.48) + + CF_{mr\_ livecroot} \_ =NS_{livecroot} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + +.. math:: + :label: 13.49) + + CF_{mr\_ froot} \_ =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} + +where :math:`MR_{base}` (= 2.525e\ :sup:`-6` gC gN\ :sup:`-1` s\ :sup:`-1`) is the base rate of maintenance +respiration per unit nitrogen content, :math:`MR_{q10}` (= 2.0) is +the temperature sensitivity for maintenance respiration, +:math:`T_{2m}` (:math:`{}^\circ`\ C) is the air temperature at 2m +height, :math:`Ts_{j}`* (:math:`{}^\circ`\ C) is the soil +temperature at level *j*, and :math:`rootfr_{j}` is the fraction +of fine roots distributed in soil level *j*. + +Note that, for woody vegetation, maintenance respiration costs are not +calculated for the dead stem and dead coarse root components. These +components are assumed to consist of dead xylem cells, with no metabolic +function. By separating the small live component of the woody tissue +(ray parenchyma, phloem, and sheathing lateral meristem cells) from the +larger fraction of dead woody tissue, it is reasonable to assume a +common base maintenance respiration rate for all live tissue types. + +The total maintenance respiration cost is then given as: + +.. math:: + :label: 13.50) + + CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . + +13.7.2 Growth Respiration +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Growth respiration is calculated as a factor of 0.3 times the total +carbon in new growth on a given timestep, based on construction costs +for a range of woody and non-woody tissues (Larcher, 1995). For new +carbon and nitrogen allocation that enters storage pools for subsequent +display, it is not clear what fraction of the associated growth +respiration should occur at the time of initial allocation, and what +fraction should occur later, at the time of display of new growth from +storage. Eddy covariance estimates of carbon fluxes in forest ecosystems +suggest that the growth respiration associated with transfer of +allocated carbon and nitrogen from storage into displayed tissue is not +significant (Churkina et al., 2003), and so it is assumed in CLM that +all of the growth respiration cost is incurred at the time of initial +allocation, regardless of the fraction of allocation that is displayed +immediately (i.e. regardless of the value of :math:`f_{cur}`, +section 13.5). This behavior is parameterized in such a way that if +future research suggests that some fraction of the growth respiration +cost should be incurred at the time of display from storage, a simple +parameter modification will effect the change. [1]_ + +.. [1] + Parameter :math:`\text{grpnow}` in routines CNGResp and CNAllocation, currently set to 1.0, could be changed to a smaller + value to transfer some portion (1 - :math:`\text{grpnow}` ) of the growth respiration forward in time to occur at the time of growth + display from storage. + diff --git a/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst b/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst new file mode 100644 index 0000000000..65a0cf17a7 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst @@ -0,0 +1,887 @@ +.. math:: 10 + +Vegetation Phenology +======================== + +The CLM phenology model consists of several algorithms controlling the +transfer of stored carbon and nitrogen out of storage pools for the +display of new growth and into litter pools for losses of displayed +growth. PFTs are classified into three distinct phenological types that +are represented by separate algorithms: an evergreen type, for which +some fraction of annual leaf growth persists in the displayed pool for +longer than one year; a seasonal-deciduous type with a single growing +season per year, controlled mainly by temperature and daylength; and a +stress-deciduous type with the potential for multiple growing seasons +per year, controlled by temperature and soil moisture conditions. + +The three phenology types share a common set of control variables. The +calculation of the phenology fluxes is generalized, operating +identically for all three phenology types, given a specification of the +common control variables. The following sections describe first the +general flux parameterization, followed by the algorithms for setting +the control parameters for the three phenology types. + +General Phenology Flux Parameterization +-------------------------------------------- + +Fluxes of carbon and nitrogen from storage pools and into displayed +tissue pools pass through a special transfer pool (denoted *\_xfer*), +maintained as a separate state variable for each tissue type. Storage +(*\_stor*) and transfer (*\_xfer*) pools are maintained separately to +reduce the complexity of accounting for transfers into and out of +storage over the course of a single growing season. + +Figure 14.1. Example of annual phenology cycle for seasonal deciduous. + +|image| + +14.1.1 Onset Periods +^^^^^^^^^^^^^^^^^^^^ + +The deciduous phenology algorithms specify the occurrence of onset +growth periods (Figure 14.1). Carbon fluxes from the transfer pools into +displayed growth are calculated during these periods as: + +.. math:: + + \label{14.1)} + CF_{leaf\_ xfer,leaf} =r_{xfer\_ on} CS_{leaf\_ xfer} + +.. math:: + + \label{14.2)} + CF_{froot\_ xfer,froot} =r_{xfer\_ on} CS_{froot\_ xfer} + +.. math:: + + \label{14.3)} + CF_{livestem\_ xfer,livestem} =r_{xfer\_ on} CS_{livestem\_ xfer} + +.. math:: + + \label{14.4)} + CF_{deadstem\_ xfer,deadstem} =r_{xfer\_ on} CS_{deadstem\_ xfer} + +.. math:: + + \label{14.5)} + CF_{livecroot\_ xfer,livecroot} =r_{xfer\_ on} CS_{livecroot\_ xfer} + +.. math:: + + \label{14.6)} + CF_{deadcroot\_ xfer,deadcroot} =r_{xfer\_ on} CS_{deadcroot\_ xfer} , + +with corresponding nitrogen fluxes: + +.. math:: + + \label{14.7)} + NF_{leaf\_ xfer,leaf} =r_{xfer\_ on} NS_{leaf\_ xfer} + +.. math:: + + \label{14.8)} + NF_{froot\_ xfer,froot} =r_{xfer\_ on} NS_{froot\_ xfer} + +.. math:: + + \label{14.9)} + NF_{livestem\_ xfer,livestem} =r_{xfer\_ on} NS_{livestem\_ xfer} + +.. math:: + + \label{14.10)} + NF_{deadstem\_ xfer,deadstem} =r_{xfer\_ on} NS_{deadstem\_ xfer} + +.. math:: + + \label{14.11)} + NF_{livecroot\_ xfer,livecroot} =r_{xfer\_ on} NS_{livecroot\_ xfer} + +.. math:: + + \label{14.12)} + NF_{deadcroot\_ xfer,deadcroot} =r_{xfer\_ on} NS_{deadcroot\_ xfer} , + +where CF is the carbon flux, CS is stored carbon, NF is the nitrogen +flux, NS is stored nitrogen, *r\ :math:`{}_{xfer\_on}`* +(s:math:`{}^{-1}`) is a time-varying rate coefficient controlling flux +out of the transfer pool: + +.. math:: + + \label{ZEqnNum852972} + r_{xfer\_ on} =\left\{\begin{array}{l} {{2\mathord{\left/ {\vphantom {2 t_{onset} }} \right. \kern-\nulldelimiterspace} t_{onset} } \qquad {\rm for\; }t_{onset} \ne \Delta t} \\ {{1\mathord{\left/ {\vphantom {1 \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \qquad {\rm for\; }t_{onset} =\Delta t} \end{array}\right. + +and *t\ :math:`{}_{onset}`* (s) is the number of seconds remaining in +the current phenology onset growth period (Figure 14.1). The form of Eq. +produces a flux from the transfer pool which declines linearly over the +onset growth period, approaching zero flux in the final timestep. + +14.1.2 Offset Periods +^^^^^^^^^^^^^^^^^^^^^ + +The deciduous phenology algorithms also specify the occurrence of +litterfall during offset periods. In contrast to the onset periods, only +leaf and fine root state variables are subject to litterfall fluxes. +Carbon fluxes from display pools into litter are calculated during these +periods as: + +.. math:: + + \label{14.14)} + CF_{leaf,litter}^{n} =\left\{\begin{array}{l} {CF_{leaf,litter}^{n-1} +r_{xfer\_ off} \left(CS_{leaf} -CF_{leaf,litter}^{n-1} {\kern 1pt} t_{offset} \right)\qquad {\rm for\; }t_{offset} \ne \Delta t} \\ {\left({CS_{leaf} \mathord{\left/ {\vphantom {CS_{leaf} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \right)+CF_{alloc,leaf} \qquad \qquad \qquad \qquad {\rm for\; }t_{offset} =\Delta t} \end{array}\right. + +.. math:: + + \label{14.15)} + CF_{froot,litter}^{n} =\left\{\begin{array}{l} {CF_{froot,litter}^{n-1} +r_{xfer\_ off} \left(CS_{froot} -CF_{froot,litter}^{n-1} {\kern 1pt} t_{offset} \right)\qquad {\rm for\; }t_{offset} \ne \Delta t} \\ {\left({CS_{froot} \mathord{\left/ {\vphantom {CS_{froot} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \right)+CF_{alloc,\, froot} \qquad \qquad \qquad {\rm for\; }t_{offset} =\Delta t} \end{array}\right. + +.. math:: + + \label{14.16)} + r_{xfer\_ off} =\frac{2\Delta t}{t_{offset} ^{2} } + +where superscripts *n* and *n-1* refer to fluxes on the current and +previous timesteps, respectively. The rate coefficient +*r\ :math:`{}_{xfer\_off}`* varies with time to produce a linearly +increasing litterfall rate throughout the offset period, and the special +case for fluxes in the final litterfall timestep +(*t\ :math:`{}_{offset}`* = *:math:`\Delta`\ t*) ensures that all of the +displayed growth is sent to the litter pools for deciduous plant types. + +Corresponding nitrogen fluxes during litterfall take into account +retranslocation of nitrogen out of the displayed leaf pool prior to +litterfall (*NF\ :math:`{}_{leaf,retrans}`*, gN m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`). Retranslocation of nitrogen out of fine roots is +assumed to be negligible. The fluxes are: + +.. math:: + + \label{14.17)} + NF_{leaf,litter} ={CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf\_ litter} }} \right. \kern-\nulldelimiterspace} CN_{leaf\_ litter} } + +.. math:: + + \label{14.18)} + NF_{froot,litter} ={CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{froot} }} \right. \kern-\nulldelimiterspace} CN_{froot} } + +.. math:: + + \label{14.19)} + NF_{leaf,retrans} =\left({CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf} }} \right. \kern-\nulldelimiterspace} CN_{leaf} } \right)-NF_{leaf,litter} . + +where CN is C:N. + +14.1.3 Background Onset Growth +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The stress-deciduous phenology algorithm includes a provision for the +case when stress signals are absent, and the vegetation shifts from a +deciduous habit to an evergreen habit, until the next occurrence of an +offset stress trigger . In that case, the regular onset flux mechanism +is switched off and a background onset growth algorithm is invoked +(*r\ :math:`{}_{bgtr}`* :math:`>` 0). During this period, small fluxes +of carbon and nitrogen from the storage pools into the associated +transfer pools are calculated on each time step, and the entire contents +of the transfer pool are added to the associated displayed growth pool +on each time step. The carbon fluxes from transfer to display pools +under these conditions are: + +.. math:: + + \label{14.20)} + CF_{leaf\_ xfer,leaf} ={CS_{leaf\_ xfer} \mathord{\left/ {\vphantom {CS_{leaf\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.21)} + CF_{froot\_ xfer,froot} ={CS_{froot\_ xfer} \mathord{\left/ {\vphantom {CS_{froot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.22)} + CF_{livestem\_ xfer,livestem} ={CS_{livestem\_ xfer} \mathord{\left/ {\vphantom {CS_{livestem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.23)} + CF_{deadstem\_ xfer,deadstem} ={CS_{deadstem\_ xfer} \mathord{\left/ {\vphantom {CS_{deadstem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.24)} + CF_{livecroot\_ xfer,livecroot} ={CS_{livecroot\_ xfer} \mathord{\left/ {\vphantom {CS_{livecroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.25)} + CF_{deadcroot\_ xfer,deadcroot} ={CS_{deadcroot\_ xfer} \mathord{\left/ {\vphantom {CS_{deadcroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} , + +and the corresponding nitrogen fluxes are: + +.. math:: + + \label{14.26)} + NF_{leaf\_ xfer,leaf} ={NS_{leaf\_ xfer} \mathord{\left/ {\vphantom {NS_{leaf\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.27)} + NF_{froot\_ xfer,froot} ={NS_{froot\_ xfer} \mathord{\left/ {\vphantom {NS_{froot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.28)} + NF_{livestem\_ xfer,livestem} ={NS_{livestem\_ xfer} \mathord{\left/ {\vphantom {NS_{livestem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.29)} + NF_{deadstem\_ xfer,deadstem} ={NS_{deadstem\_ xfer} \mathord{\left/ {\vphantom {NS_{deadstem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.30)} + NF_{livecroot\_ xfer,livecroot} ={NS_{livecroot\_ xfer} \mathord{\left/ {\vphantom {NS_{livecroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.31)} + NF_{deadcroot\_ xfer,deadcroot} ={NS_{deadcroot\_ xfer} \mathord{\left/ {\vphantom {NS_{deadcroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} . + +14.1.4 Background Litterfall +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Both evergreen and stress-deciduous phenology algorithms can specify a +litterfall flux that is not associated with a specific offset period, +but which occurs instead at a slow rate over an extended period of time, +referred to as background litterfall. For evergreen types the background +litterfall is the only litterfall flux. For stress-deciduous types +either the offset period litterfall or the background litterfall +mechanism may be active, but not both at once. Given a specification of +the background litterfall rate (*r\ :math:`{}_{bglf}`*, +s\ :math:`{}^{-1}`), litterfall carbon fluxes are calculated as + +.. math:: + + \label{14.32)} + CF_{leaf,litter} =r_{bglf} CS_{leaf} + +.. math:: + + \label{14.33)} + CS_{froot,litter} =r_{bglf} CS_{froot} , + +with corresponding nitrogen litterfall and retranslocation fluxes: + +.. math:: + + \label{14.34)} + NF_{leaf,litter} ={CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf\_ litter} }} \right. \kern-\nulldelimiterspace} CN_{leaf\_ litter} } + +.. math:: + + \label{14.35)} + NF_{froot,litter} ={CF_{froot,litter} \mathord{\left/ {\vphantom {CF_{froot,litter} CN_{froot} }} \right. \kern-\nulldelimiterspace} CN_{froot} } + +.. math:: + + \label{14.36)} + NF_{leaf,retrans} =\left({CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf} }} \right. \kern-\nulldelimiterspace} CN_{leaf} } \right)-NF_{leaf,litter} . + +14.1.5 Livewood Turnover +^^^^^^^^^^^^^^^^^^^^^^^^ + +The conceptualization of live wood vs. dead wood fractions for stem and +coarse root pools is intended to capture the difference in maintenance +respiration rates between these two physiologically distinct tissue +types. Unlike displayed pools for leaf and fine root, which are lost to +litterfall, live wood cells reaching the end of their lifespan are +retained as a part of the dead woody structure of stems and coarse +roots. A mechanism is therefore included in the phenology routine to +effect the transfer of live wood to dead wood pools, which also takes +into account the different nitrogen concentrations typical of these +tissue types. + +A live wood turnover rate (*r\ :math:`{}_{lwt}`*, s\ :math:`{}^{-1}`) is +defined as + +.. math:: + + \label{14.37)} + r_{lwt} ={p_{lwt} \mathord{\left/ {\vphantom {p_{lwt} \left(365\cdot 86400\right)}} \right. \kern-\nulldelimiterspace} \left(365\cdot 86400\right)} + +where *p\ :math:`{}_{lwt}`* = 0.7 is the assumed annual live wood +turnover fraction. Carbon fluxes from live to dead wood pools are: + +.. math:: + + \label{14.38)} + CF_{livestem,deadstem} =CS_{livestem} r_{lwt} + +.. math:: + + \label{14.39)} + CF_{livecroot,deadcroot} =CS_{livecroot} r_{lwt} , + +and the associated nitrogen fluxes, including retranslocation of +nitrogen out of live wood during turnover, are: + +.. math:: + + \label{14.40)} + NF_{livestem,deadstem} ={CF_{livestem,deadstem} \mathord{\left/ {\vphantom {CF_{livestem,deadstem} CN_{dw} }} \right. \kern-\nulldelimiterspace} CN_{dw} } + +.. math:: + + \label{14.41)} + NF_{livestem,retrans} =\left({CF_{livestem,deadstem} \mathord{\left/ {\vphantom {CF_{livestem,deadstem} CN_{lw} }} \right. \kern-\nulldelimiterspace} CN_{lw} } \right)-NF_{livestem,deadstem} + +.. math:: + + \label{14.42)} + NF_{livecroot,deadcroot} ={CF_{livecroot,deadcroot} \mathord{\left/ {\vphantom {CF_{livecroot,deadcroot} CN_{dw} }} \right. \kern-\nulldelimiterspace} CN_{dw} } + +.. math:: + + \label{14.43)} + NF_{livecroot,retrans} =\left({CF_{livecroot,deadcroot} \mathord{\left/ {\vphantom {CF_{livecroot,deadcroot} CN_{lw} }} \right. \kern-\nulldelimiterspace} CN_{lw} } \right)-NF_{livecroot,deadcroot} . + +Evergreen Phenology +------------------------ + +The evergreen phenology algorithm is by far the simplest of the three +possible types. It is assumed for all evergreen types that all carbon +and nitrogen allocated for new growth in the current timestep goes +immediately to the displayed growth pools (i.e. *f\ :math:`{}_{cur}`* = +(Chapter 13)). As such, there is never an accumulation of carbon or +nitrogen in the storage or transfer pools, and so the onset growth and +background onset growth mechanisms are never invoked for this type. +Litterfall is specified to occur only through the background litterfall +mechanism – there are no distinct periods of litterfall for evergreen +types, but rather a continuous (slow) shedding of foliage and fine +roots. This is an obvious area for potential improvements in the model, +since it is known, at least for evergreen needleleaf trees in the +temperate and boreal zones, that there are distinct periods of higher +and lower leaf litterfall (Ferrari, 1999; Gholz et al., 1985). The rate +of background litterfall (*r\ :math:`{}_{bglf}`*, section 14.1.4) +depends on the specified leaf longevity +(*:math:`\tau`\ :math:`{}_{leaf}`*, y), as + +.. math:: + + \label{14.44)} + r_{bglf} =\frac{1}{\tau _{leaf} \cdot 365\cdot 86400} . + +Seasonal-Deciduous Phenology +--------------------------------- + +The seasonal-deciduous phenology algorithm derives directly from the +treatment used in the offline model Biome-BGC v. 4.1.2, (Thornton et +al., 2002), which in turn is based on the parameterizations for leaf +onset and offset for temperate deciduous broadleaf forest from White et +al. (1997). Initiation of leaf onset is triggered when a common +degree-day summation exceeds a critical value, and leaf litterfall is +initiated when daylength is shorter than a critical value. Because of +the dependence on daylength, the seasonal deciduous phenology algorithm +is only valid for latitudes outside of the tropical zone, defined here +as :math:`\left|{\rm latitude}\right|>19.5{\rm {}^\circ }`. Neither the +background onset nor background litterfall mechanism is invoked for the +seasonal-deciduous phenology algorithm. The algorithm allows a maximum +of one onset period and one offset period each year. + +The algorithms for initiation of onset and offset periods use the winter +and summer solstices as coordination signals. The period between winter +and summer solstice is identified as *dayl\ :math:`{}_{n}`* :math:`>` +*dayl\ :math:`{}_{n-1}`*, and the period between summer and winter +solstice is identified as *dayl\ :math:`{}_{n}`* :math:`<` +*dayl\ :math:`{}_{n-1}`*, where *dayl\ :math:`{}_{n}`* and +*dayl\ :math:`{}_{n-1}`* are the daylength (s) calculated for the +current and previous timesteps, respectively, using + +.. math:: + + \label{14.45)} + dayl=2\cdot 13750.9871\cdot acos\left(\frac{-\sin (lat)\sin (decl)}{\cos (lat)\cos (decl)} \right), + +where *lat* and *decl* are the latitude and solar declination (radians), +respectively, and the factor 13750.9871 is the number of seconds per +radian of hour-angle. + +14.3.1 Seasonal-Deciduous Onset Trigger +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The onset trigger for the seasonal-deciduous phenology algorithm is +based on an accumulated growing-degree-day approach (White et al., +1997). The growing-degree-day summation (*GDD\ :math:`{}_{sum}`*) is +initiated (*GDD\ :math:`{}_{sum}`* = 0) when the phenological state is +dormant and the model timestep crosses the winter solstice. Once these +conditions are met, *GDD\ :math:`{}_{sum}`* is updated on each timestep +as + +.. math:: + + \label{ZEqnNum510730} + GDD_{sum}^{n} =\left\{\begin{array}{l} {GDD_{sum}^{n-1} +\left(T_{s,3} -TKFRZ\right)f_{day} \qquad {\rm for\; }T_{s,3} >TKFRZ} \\ {GDD_{sum}^{n-1} \qquad \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \end{array}\right. + +where *T\ :math:`{}_{s,3}`* (K) is the temperature of the third soil +layer, and +:math:`f_{day} ={\Delta t\mathord{\left/ {\vphantom {\Delta t 86400}} \right. \kern-\nulldelimiterspace} 86400}` . +The onset period is initiated if :math:`GDD_{sum} >GDD_{sum\_ crit}` , +where + +.. math:: + + \label{ZEqnNum598907} + GDD_{sum\_ crit} =\exp \left(4.8+0.13{\kern 1pt} \left(T_{2m,ann\_ avg} -TKFRZ\right)\right) + +and where *T\ :math:`{}_{2m,ann\_avg}`* (K) is the annual average of +the 2m air temperature, and TKFRZ is the freezing point of water (273.15 +K). The following control variables are set when a new onset growth +period is initiated: + +.. math:: + + \label{14.48)} + GDD_{sum} =0 + +.. math:: + + \label{14.49)} + t_{onset} =86400\cdot n_{days\_ on} , + +where *n\ :math:`{}_{days\_on}`* is set to a constant value of 30 days. +Fluxes from storage into transfer pools occur in the timestep when a new +onset growth period is initiated. Carbon fluxes are: + +.. math:: + + \label{ZEqnNum904388} + CF_{leaf\_ stor,leaf\_ xfer} ={f_{stor,xfer} CS_{leaf\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{leaf\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.51)} + CF_{froot\_ stor,froot\_ xfer} ={f_{stor,xfer} CS_{froot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{froot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.52)} + CF_{livestem\_ stor,livestem\_ xfer} ={f_{stor,xfer} CS_{livestem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{livestem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.53)} + CF_{deadstem\_ stor,deadstem\_ xfer} ={f_{stor,xfer} CS_{deadstem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{deadstem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.54)} + CF_{livecroot\_ stor,livecroot\_ xfer} ={f_{stor,xfer} CS_{livecroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{livecroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.55)} + CF_{deadcroot\_ stor,deadcroot\_ xfer} ={f_{stor,xfer} CS_{deadcroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{deadcroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{ZEqnNum195642} + CF_{gresp\_ stor,gresp\_ xfer} ={f_{stor,xfer} CS_{gresp\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{gresp\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +and the associated nitrogen fluxes are: + +.. math:: + + \label{ZEqnNum812152} + NF_{leaf\_ stor,leaf\_ xfer} ={f_{stor,xfer} NS_{leaf\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{leaf\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.58)} + NF_{froot\_ stor,froot\_ xfer} ={f_{stor,xfer} NS_{froot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{froot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.59)} + NF_{livestem\_ stor,livestem\_ xfer} ={f_{stor,xfer} NS_{livestem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{livestem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.60)} + NF_{deadstem\_ stor,deadstem\_ xfer} ={f_{stor,xfer} NS_{deadstem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{deadstem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{14.61)} + NF_{livecroot\_ stor,livecroot\_ xfer} ={f_{stor,xfer} NS_{livecroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{livecroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{ZEqnNum605338} + NF_{deadcroot\_ stor,deadcroot\_ xfer} ={f_{stor,xfer} NS_{deadcroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{deadcroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +where *f\ :math:`{}_{stor,xfer}`* is the fraction of current storage +pool moved into the transfer pool for display over the incipient onset +period. This fraction is set to 0.5, based on the observation that +seasonal deciduous trees are capable of replacing their canopies from +storage reserves in the event of a severe early-season disturbance such +as frost damage or defoliation due to insect herbivory. + +If the onset criterion (*GDD\ :math:`{}_{sum}`* :math:`>` +*GDD\ :math:`{}_{sum\_crit}`*) is not met before the summer solstice, +then *GDD\ :math:`{}_{sum}`* is set to 0.0 and the growing-degree-day +accumulation will not start again until the following winter solstice. +This mechanism prevents the initiation of very short growing seasons +late in the summer in cold climates. The onset counter is decremented on +each time step after initiation of the onset period, until it reaches +zero, signaling the end of the onset period: + +.. math:: + + \label{14.63)} + t_{onfset}^{n} =t_{onfset}^{n-1} -\Delta t + +14.3.2 Seasonal-Deciduous Offset Trigger +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After the completion of an onset period, and once past the summer +solstice, the offset (litterfall) period is triggered when daylength is +shorter than 39300 s. The offset counter is set at the initiation of the +offset period: :math:`t_{offset} =86400\cdot n_{days\_ off}` , where +*n\ :math:`{}_{days\_off}`* is set to a constant value of 15 days. The +offset counter is decremented on each time step after initiation of the +offset period, until it reaches zero, signaling the end of the offset +period: + +.. math:: + + \label{14.64)} + t_{offset}^{n} =t_{offset}^{n-1} -\Delta t + +Stress-Deciduous Phenology +------------------------------- + +The stress-deciduous phenology algorithm was developed specifically for +the CLM based in part on the grass phenology model proposed by White et +al. (1997). The algorithm handles phenology for vegetation types such as +grasses and tropical drought-deciduous trees that respond to both cold +and drought-stress signals, and that can have multiple growing seasons +per year. The algorithm also allows for the possibility that leaves +might persist year-round in the absence of a suitable stress trigger. In +that case the phenology switches to an evergreen habit, maintaining a +marginally-deciduous leaf longevity (one year) until the occurrence of +the next stress trigger. + +14.4.1 Stress-Deciduous Onset Triggers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In climates that are warm year-round, onset triggering depends on soil +water availability. At the beginning of a dormant period (end of +previous offset period), an accumulated soil water index +(*SWI\ :math:`{}_{sum}`*, d) is initialized (*SWI\ :math:`{}_{sum}`* = +0), with subsequent accumulation calculated as: + +.. math:: + + \label{ZEqnNum503826} + SWI_{sum}^{n} =\left\{\begin{array}{l} {SWI_{sum}^{n-1} +f_{day} \qquad {\rm for\; }\Psi _{s,3} \ge \Psi _{onset} } \\ {SWI_{sum}^{n-1} \qquad \qquad {\rm for\; }\Psi _{s,3} <\Psi _{onset} } \end{array}\right. + +where :math:`\Psi`\ *:math:`{}_{s,3}`* is the soil water potential (MPa) +in the third soil layer and :math:`\Psi`\ *:math:`{}_{onset}`* = -2 MPa +is the onset soil water potential threshold. Onset triggering is +possible once *SWI\ :math:`{}_{sum}`* :math:`>` 15. If the cold climate +growing degree-day accumulator is not active at the time when this +threshold is reached (see below), and if the daylength is greater than 6 +hours, then onset is triggered. Except as noted below, +*SWI\ :math:`{}_{sum}`* continues to accumulate according to Eq. during +the dormant period if the daylength criterion prevents onset triggering, +and onset is then triggered at the timestep when daylength exceeds 6 +hours. + +In climates with a cold season, onset triggering depends on both +accumulated soil temperature summation and adequate soil moisture. At +the beginning of a dormant period a freezing day accumulator +(*FD\ :math:`{}_{sum}`*, d) is initialized (*FD\ :math:`{}_{sum}`* = 0), +with subsequent accumulation calculated as: + +.. math:: + + \label{14.66)} + FD_{sum}^{n} =\left\{\begin{array}{l} {FD_{sum}^{n-1} +f_{day} \qquad {\rm for\; }T_{s,3} >TKFRZ} \\ {FD_{sum}^{n-1} \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \end{array}\right. . + +If *FD\ :math:`{}_{sum}`* :math:`>` 15 during the dormant period, then a +cold-climate onset triggering criterion is introduced, following exactly +the growing degree-day summation (*GDD\ :math:`{}_{sum}`*) logic of Eqs. +and . At that time *SWI\ :math:`{}_{sum}`* is reset +(*SWI\ :math:`{}_{sum}`* = 0). Onset triggering under these conditions +depends on meeting all three of the following criteria: +*SWI\ :math:`{}_{sum}`* :math:`>` 15, *GDD\ :math:`{}_{sum}`* :math:`>` +*GDD\ :math:`{}_{sum\_crit}`*, and daylength greater than 6 hrs. + +The following control variables are set when a new onset growth period +is initiated: *SWI\ :math:`{}_{sum}`* = 0, *FD\ :math:`{}_{sum}`* = 0, +*GDD\ :math:`{}_{sum}`* = 0, *n\ :math:`{}_{days\_active}`* = 0, and +:math:`t_{onset} =86400\cdot n_{days\_ on}` , where +*n\ :math:`{}_{days\_on}`* is set to a constant value of 30 days. Fluxes +from storage into transfer pools occur in the timestep when a new onset +growth period is initiated, and are handled identically to Eqs. - for +carbon fluxes, and to Eqs. - for nitrogen fluxes. The onset counter is +decremented on each time step after initiation of the onset period, +until it reaches zero, signaling the end of the onset period: + +.. math:: + + \label{14.67)} + t_{onfset}^{n} =t_{onfset}^{n-1} -\Delta t + +14.4.2 Stress-Deciduous Offset Triggers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Any one of the following three conditions is sufficient to initiate an +offset period for the stress-deciduous phenology algorithm: sustained +period of dry soil, sustained period of cold temperature, or daylength +shorter than 6 hours. Offset triggering due to dry soil or cold +temperature conditions is only allowed once the most recent onset period +is complete. Dry soil condition is evaluated with an offset soil water +index accumulator (*OSWI\ :math:`{}_{sum}`*, d). To test for a sustained +period of dry soils, this control variable can increase or decrease, as +follows: + +.. math:: + + \label{14.68)} + OSWI_{sum}^{n} =\left\{\begin{array}{l} {OSWI_{sum}^{n-1} +f_{day} \qquad \qquad \qquad {\rm for\; }\Psi _{s,3} \le \Psi _{offset} } \\ {{\rm max}\left(OSWI_{sum}^{n-1} -f_{day} ,0\right)\qquad {\rm for\; }\Psi _{s,3} >\Psi _{onset} } \end{array}\right. + +where :math:`\Psi`\ *:math:`{}_{offset}`* = -2 MPa is the offset soil +water potential threshold. An offset period is triggered if the previous +onset period is complete and *OSWI\ :math:`{}_{sum}`* +:math:`\mathrm{\ge}` *OSWI\ :math:`{}_{sum\_crit}`*, where +*OSWI\ :math:`{}_{sum\_crit}`* = 15. + +The cold temperature trigger is calculated with an offset freezing day +accumulator (*OFD\ :math:`{}_{sum}`*, d). To test for a sustained period +of cold temperature, this variable can increase or decrease, as follows: + +.. math:: + + \label{14.69)} + OFD_{sum}^{n} =\left\{\begin{array}{l} {OFD_{sum}^{n-1} +f_{day} \qquad \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \\ {{\rm max}\left(OFD_{sum}^{n-1} -f_{day} ,0\right)\qquad \qquad {\rm for\; }T_{s,3} >TKFRZ} \end{array}\right. + +An offset period is triggered if the previous onset period is complete +and *OFD\ :math:`{}_{sum}`* :math:`>` *OFD\ :math:`{}_{sum\_crit}`*, +where *OFD\ :math:`{}_{sum\_crit}`* = 15. + +The offset counter is set at the initiation of the offset period: +:math:`t_{offset} =86400\cdot n_{days\_ off}` , where +*n\ :math:`{}_{days\_off}`* is set to a constant value of 15 days. The +offset counter is decremented on each time step after initiation of the +offset period, until it reaches zero, signaling the end of the offset +period: + +.. math:: + + \label{14.70)} + t_{offset}^{n} =t_{offset}^{n-1} -\Delta t + +14.4.3 Stress-Deciduous: Long Growing Season +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Under conditions when the stress-deciduous conditions triggering offset +are not met for one year or longer, the stress-deciduous algorithm +shifts toward the evergreen behavior. This can happen in cases where a +stress-deciduous vegetation type is assigned in a climate where suitably +strong stresses occur less frequently than once per year. This condition +is evaluated by tracking the number of days since the beginning of the +most recent onset period (*n\ :math:`{}_{days\_active}`*, d). At the end +of an offset period *n\ :math:`{}_{days\_active}`* is reset to 0. A long +growing season control variable (*LGS*, range 0 to 1) is calculated as: + +.. math:: + + \label{14.71)} + LGS=\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }n_{days\_ active} <365} \\ {\left({n_{days\_ active} \mathord{\left/ {\vphantom {n_{days\_ active} 365}} \right. \kern-\nulldelimiterspace} 365} \right)-1\qquad {\rm for\; }365\le n_{days\_ active} <730} \\ {1\qquad \qquad \qquad {\rm for\; }n_{days\_ active} \ge 730} \end{array}\right. . + +The rate coefficient for background litterfall (*r\ :math:`{}_{bglf}`*, +s\ :math:`{}^{-1}`) is calculated as a function of *LGS*: + +.. math:: + + \label{14.72)} + r_{bglf} =\frac{LGS}{\tau _{leaf} \cdot 365\cdot 86400} + +where *:math:`\tau`\ :math:`{}_{leaf}`* is the leaf longevity. The +result is a shift to continuous litterfall as +*n\ :math:`{}_{days\_active}`* increases from 365 to 730. When a new +offset period is triggered *r\ :math:`{}_{bglf}`* is set to 0. + +The rate coefficient for background onset growth from the transfer pools +(*r\ :math:`{}_{bgtr}`*, s\ :math:`{}^{-1}`) also depends on *LGS*, as: + +.. math:: + + \label{14.73)} + r_{bgtr} =\frac{LGS}{365\cdot 86400} . + +On each timestep with *r\ :math:`{}_{bgtr}`* :math:`\neq` 0, carbon +fluxes from storage to transfer pools are calculated as: + +.. math:: + + \label{14.74)} + CF_{leaf\_ stor,leaf\_ xfer} =CS_{leaf\_ stor} r_{bgtr} + +.. math:: + + \label{14.75)} + CF_{froot\_ stor,froot\_ xfer} =CS_{froot\_ stor} r_{bgtr} + +.. math:: + + \label{14.76)} + CF_{livestem\_ stor,livestem\_ xfer} =CS_{livestem\_ stor} r_{bgtr} + +.. math:: + + \label{14.77)} + CF_{deadstem\_ stor,deadstem\_ xfer} =CS_{deadstem\_ stor} r_{bgtr} + +.. math:: + + \label{14.78)} + CF_{livecroot\_ stor,livecroot\_ xfer} =CS_{livecroot\_ stor} r_{bgtr} + +.. math:: + + \label{14.79)} + CF_{deadcroot\_ stor,deadcroot\_ xfer} =CS_{deadcroot\_ stor} r_{bgtr} , + +with corresponding nitrogen fluxes: + +.. math:: + + \label{14.80)} + NF_{leaf\_ stor,leaf\_ xfer} =NS_{leaf\_ stor} r_{bgtr} + +.. math:: + + \label{14.81)} + NF_{froot\_ stor,froot\_ xfer} =NS_{froot\_ stor} r_{bgtr} + +.. math:: + + \label{14.82)} + NF_{livestem\_ stor,livestem\_ xfer} =NS_{livestem\_ stor} r_{bgtr} + +.. math:: + + \label{14.83)} + NF_{deadstem\_ stor,deadstem\_ xfer} =NS_{deadstem\_ stor} r_{bgtr} + +.. math:: + + \label{14.84)} + NF_{livecroot\_ stor,livecroot\_ xfer} =NS_{livecroot\_ stor} r_{bgtr} + +.. math:: + + \label{14.85)} + NF_{deadcroot\_ stor,deadcroot\_ xfer} =NS_{deadcroot\_ stor} r_{bgtr} . + +The result, in conjunction with the treatment of background onset +growth, is a shift to continuous transfer from storage to display pools +at a rate that would result in complete turnover of the storage pools in +one year at steady state, once *LGS* reaches 1 (i.e. after two years +without stress-deciduous offset conditions). If and when conditions +cause stress-deciduous triggering again, *r\ :math:`{}_{bgtr}`* is rest +to 0. + +Litterfall Fluxes Merged to the Column Level +------------------------------------------------- + +CLM uses three litter pools, defined on the basis of commonly measured +chemical fractionation of fresh litter into labile (LIT1 = hot water and +alcohol soluble fraction), cellulose/hemicellulose (LIT2 = acid soluble +fraction) and remaining material, referred to here for convenience as +lignin (LIT3 = acid insoluble fraction) (Aber et al., 1990; Taylor et +al., 1989). While multiple plant functional types can coexist on a +single CLM soil column, each soil column includes a single instance of +the litter pools. Fluxes entering the litter pools due to litterfall are +calculated using a weighted average of the fluxes originating at the PFT +level. Carbon fluxes are calculated as: + +.. math:: + + \label{14.86)} + CF_{leaf,lit1} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{lab\_ leaf,p} wcol_{p} + +.. math:: + + \label{14.87)} + CF_{leaf,lit2} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{cel\_ leaf,p} wcol_{p} + +.. math:: + + \label{14.88)} + CF_{leaf,lit3} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{lig\_ leaf,p} wcol_{p} + +.. math:: + + \label{14.89)} + CF_{froot,lit1} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{lab\_ froot,p} wcol_{p} + +.. math:: + + \label{14.90)} + CF_{froot,lit2} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{cel\_ froot,p} wcol_{p} + +.. math:: + + \label{14.91)} + CF_{froot,lit3} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{lig\_ froot,p} wcol_{p} , + +where *f\ :math:`{}_{lab\_leaf,p}`*, *f\ :math:`{}_{cel\_leaf,p}`*, and +*f\ :math:`{}_{lig\_leaf,p}`* are the labile, cellulose/hemicellulose, +and lignin fractions of leaf litter for PFT *p*, +*f\ :math:`{}_{lab\_froot,p}`*, *f\ :math:`{}_{cel\_froot,p}`*, and +*f\ :math:`{}_{lig\_froot,p}`* are the labile, cellulose/hemicellulose, +and lignin fractions of fine root litter for PFT *p*, +*wtcol\ :math:`{}_{p}`* is the weight relative to the column for PFT +*p*, and *p* is an index through the plant functional types occurring on +a column. Nitrogen fluxes to the litter pools are assumed to follow the +C:N of the senescent tissue, and so are distributed using the same +fractions used for carbon fluxes: + +.. math:: + + \label{14.92)} + NF_{leaf,lit1} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{lab\_ leaf,p} wcol_{p} + +.. math:: + + \label{14.93)} + NF_{leaf,lit2} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{cel\_ leaf,p} wcol_{p} + +.. math:: + + \label{14.94)} + NF_{leaf,lit3} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{lig\_ leaf,p} wcol_{p} + +.. math:: + + \label{14.95)} + NF_{froot,lit1} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{lab\_ froot,p} wcol_{p} + +.. math:: + + \label{14.96)} + NF_{froot,lit2} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{cel\_ froot,p} wcol_{p} + +.. math:: + + \label{14.97)} + NF_{froot,lit3} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{lig\_ froot,p} wcol_{p} . + +.. |image| image:: image1 diff --git a/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst b/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst new file mode 100644 index 0000000000..eefab609fb --- /dev/null +++ b/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst @@ -0,0 +1,797 @@ +Decomposition +================= + +Decomposition of fresh litter material into progressively more +recalcitrant forms of soil organic matter is represented in CLM is +defined as a cascade of *k\ :math:`{}_{tras}`* transformations between +*m\ :math:`{}_{pool}`* decomposing coarse woody debris (CWD), litter, +and soil organic matter (SOM) pools, each defined at +*n\ :math:`{}_{lev}`* vertical levels. CLM allows the user to define, at +compile time, between 2 contrasting hypotheses of decomposition as +embodied by two separate decomposition submodels: the CLM-CN pool +structure used in CLM4.0, or a second pool structure, characterized by +slower decomposition rates, based on the Century model (Parton et al. +1988). In addition, the user can choose, at compile time, whether to +allow *n\ :math:`{}_{lev}`* to equal 1, as in CLM4.0, or to equal the +number of soil levels used for the soil hydrology (default 10). + +Figure 15.1. Schematic of decomposition model in CLM. + +Model is structured to allow different representations of the soil C and +N decomposition cascade, as well as a vertically-explicit treatment of +soil biogeochemistry. + +|image| + +For the single-level model structure, the fundamental equation for +carbon balance of the decomposing pools is: + +.. math:: + + \label{15.1)} + \frac{\partial C_{i} }{\partial t} =R_{i} +\sum _{j\ne i}\left(i-r_{j} \right)T_{ji} k_{j} C_{j} -k_{i} C_{i} + +where *C\ :math:`{}_{i}`* is the carbon content of pool *i*, +*R\ :math:`{}_{i}`* are the carbon inputs from plant tissues directly to +pool *i* (only non-zero for CWD and litter pools), *k\ :math:`{}_{i}`* +is the decay constant of pool *i*; *T\ :math:`{}_{ji}`* is the fraction +of carbon directed from pool *j* to pool *i* with fraction +*r\ :math:`{}_{j}`* lost as a respiration flux along the way. + +Adding the vertical dimension to the decomposing pools changes the +balance equation to the following: + +.. math:: + + \label{15.2)} + \begin{array}{l} {\frac{\partial C_{i} (z)}{\partial t} =R_{i} (z)+\sum _{i\ne j}\left(1-r_{j} \right)T_{ji} k_{j} (z)C_{j} (z) -k_{i} (z)C_{i} (z)} \\ {+\frac{\partial }{\partial z} \left(D(z)\frac{\partial C_{i} }{\partial z} \right)+\frac{\partial }{\partial z} \left(A(z)C_{i} \right)} \end{array} + +where *C\ :math:`{}_{i}`\ (z)* is now defined at each model level, and +in volumetric (gC m\ :math:`{}^{-3}`) rather than areal (gC +m\ :math:`{}^{-2}`) units, along with *R\ :math:`{}_{i}`\ (z)* and +*k\ :math:`{}_{j}`\ (z)*. In addition, vertical transport is handled by +the last two terms, for diffusive and advective transport. In the base +model, advective transport is set to zero, leaving only a diffusive flux +with diffusivity *D(z)* defined for all decomposing carbon and nitrogen +pools. Further discussion of the vertical distribution of carbon inputs +*R\ :math:`{}_{i}`\ (z)*, vertical turnover times +*k\ :math:`{}_{j}`\ (z)*, and vertical transport *D(z)* is below. +Discussion of the vertical model and analysis of both decomposition +structures is in Koven et al (2013). + +Figure 15.2. Pool structure, transitions, respired fractions (numbers at +end of arrows), and turnover times (numbers in boxes) for the 2 +alternate soil decomposition models included in CLM. + +|image| + +CLM-CN Pool Structure, Rate Constants and Parameters +--------------------------------------------------------- + +The CLM-CN structure in CLM45 uses three state variables for fresh +litter and four state variables for soil organic matter (SOM). The +masses of carbon and nitrogen in the live microbial community are not +modeled explicitly, but the activity of these organisms is represented +by decomposition fluxes transferring mass between the litter and SOM +pools, and heterotrophic respiration losses associated with these +transformations. The litter and SOM pools in CLM-CN are arranged as a +converging cascade (Figure 15.2), derived directly from the +implementation in Biome-BGC v4.1.2 (Thornton et al. 2002; Thornton and +Rosenbloom, 2005). + +Model parameters are estimated based on a synthesis of microcosm +decomposition studies using radio-labeled substrates (Degens and +Sparling, 1996; Ladd et al. 1992; Martin et al. 1980; Mary et al. 1993; +Saggar et al. 1994; Sørensen, 1981; van Veen et al. 1984). Multiple +exponential models are fitted to data from the microcosm studies to +estimate exponential decay rates and respiration fractions (Thornton, +1998). The microcosm experiments used for parameterization were all +conducted at constant temperature and under moist conditions with +relatively high mineral nitrogen concentrations, and so the resulting +rate constants are assumed not limited by the availability of water or +mineral nitrogen. Table 15.1 lists the base decomposition rates for each +litter and SOM pool, as well as a base rate for physical fragmentation +for the coarse woody debris pool (CWD). + +Table 15.1. Decomposition rate constants for litter and SOM pools, C:N +ratios, and acceleration parameters (see section 15.8 for explanation) +for the CLM-CN decomposition pool structure. + ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| | Biome-BGC | CLM-CN | | | ++==========================+================================================+===============================================+===============+=========================================+ +| | *k\ :math:`{}_{disc1 }`*\ (d:math:`{}^{-1}`) | *k\ :math:`{}_{disc2}`* (hr:math:`{}^{-1}`) | *C:N ratio* | *Acceleration term (a:math:`{}_{i}`)* | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{Lit1}`* | 0.7 | 0.04892 | - | 1 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{Lit2}`* | 0.07 | 0.00302 | - | 1 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{Lit3}`* | 0.014 | 0.00059 | - | 1 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{SOM1}`* | 0.07 | 0.00302 | 12 | 1 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{SOM2}`* | 0.014 | 0.00059 | 12 | 1 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{SOM3}`* | 0.0014 | 0.00006 | 10 | 5 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{SOM4}`* | 0.0001 | 0.000004 | 10 | 70 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ +| *k\ :math:`{}_{CWD}`* | 0.001 | 0.00004 | - | 1 | ++--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + +The first column of Table 15.1 gives the rates as used for the Biome-BGC +model, which uses a discrete-time model with a daily timestep. The +second column of Table 15.1 shows the rates transformed for a one-hour +discrete timestep typical of CLM-CN. The transformation is based on the +conversion of the initial discrete-time value (*k\ :math:`{}_{disc1}`*) +first to a continuous time value (*k\ :math:`{}_{cont}`*), then to the +new discrete-time value with a different timestep +(*k\ :math:`{}_{disc2}`*) , following Olson (1963): + +.. math:: + + \label{ZEqnNum608251} + k_{cont} =-\log \left(1-k_{disc1} \right) + +.. math:: + + \label{ZEqnNum772630} + k_{disc2} =1-\exp \left(-k_{cont} \frac{\Delta t_{2} }{\Delta t_{1} } \right) + +where :math:`\Delta`\ *t\ :math:`{}_{1}`* (s) and +:math:`\Delta`\ *t\ :math:`{}_{2}`* (s) are the time steps of the +initial and new discrete-time models, respectively. + +Respiration fractions are parameterized for decomposition fluxes out of +each litter and SOM pool. The respiration fraction (*rf*, unitless) is +the fraction of the decomposition carbon flux leaving one of the litter +or SOM pools that is released as CO\ :math:`{}_{2}` due to heterotrophic +respiration. Respiration fractions and exponential decay rates are +estimated simultaneously from the results of microcosm decomposition +experiments (Thornton, 1998). The same values are used in CLM-CN and +Biome-BGC (Table 15.2). + +Table 15.2. Respiration fractions for litter and SOM pools + ++---------------------------+-----------------------+ +| Pool | *rf* | ++===========================+=======================+ +| *rf\ :math:`{}_{Lit1}`* | 0.39 | ++---------------------------+-----------------------+ +| *rf\ :math:`{}_{Lit2}`* | 0.55 | ++---------------------------+-----------------------+ +| *rf\ :math:`{}_{Lit3}`* | 0.29 | ++---------------------------+-----------------------+ +| *rf\ :math:`{}_{SOM1}`* | 0.28 | ++---------------------------+-----------------------+ +| *rf\ :math:`{}_{SOM2}`* | 0.46 | ++---------------------------+-----------------------+ +| *rf\ :math:`{}_{SOM3}`* | 0.55 | ++---------------------------+-----------------------+ +| *rf\ :math:`{}_{SOM4}`* | 1.0\ :math:`{}^{a}` | ++---------------------------+-----------------------+ + +:math:`{}^{a}` The respiration fraction for pool SOM4 is 1.0 by +definition: since there is no pool downstream of SOM4, the entire carbon +flux leaving this pool is assumed to be respired as CO\ :math:`{}_{2}`. + +Century-based Pool Structure, Rate Constants and Parameters +---------------------------------------------------------------- + +The Century-based decomposition cascade is, like CLM-CN, a first-order +decay model; the two structures differ in the number of pools, the +connections between those pools, the turnover times of the pools, and +the respired fraction during each transition (Figure 15.2). The turnover +times are different for the Century-based pool structure, following +those described in Parton et al. (1988) (Table 15.3). + +Table 15.3. Turnover times, C:N ratios, and acceleration parameters (see +section 15.8 for explanation) for the Century-based decomposition +cascade. + ++------------+------------------------+-------------+-------------------------------------------+ +| | Turnover time (year) | C:N ratio | Acceleration term (*a\ :math:`{}_{i}`*) | ++============+========================+=============+===========================================+ +| CWD | 4.1 | - | 1 | ++------------+------------------------+-------------+-------------------------------------------+ +| Litter 1 | 0.066 | - | 1 | ++------------+------------------------+-------------+-------------------------------------------+ +| Litter 2 | 0.25 | - | 1 | ++------------+------------------------+-------------+-------------------------------------------+ +| Litter 3 | 0.25 | - | 1 | ++------------+------------------------+-------------+-------------------------------------------+ +| SOM 1 | 0.17 | 8 | 1 | ++------------+------------------------+-------------+-------------------------------------------+ +| SOM 2 | 6.1 | 11 | 15 | ++------------+------------------------+-------------+-------------------------------------------+ +| SOM 3 | 270 | 11 | 675 | ++------------+------------------------+-------------+-------------------------------------------+ + +Likewise, values for the respiration fraction of Century-based structure +are in Table 15.4. + +Table 15.4. Respiration fractions for litter and SOM pools for +Century-based structure + ++---------------------------+----------+ +| Pool | *rf* | ++===========================+==========+ +| *rf\ :math:`{}_{Lit1}`* | 0.55 | ++---------------------------+----------+ +| *rf\ :math:`{}_{Lit2}`* | 0.5 | ++---------------------------+----------+ +| *rf\ :math:`{}_{Lit3}`* | 0.5 | ++---------------------------+----------+ +| *rf\ :math:`{}_{SOM1}`* | f(txt) | ++---------------------------+----------+ +| *rf\ :math:`{}_{SOM2}`* | 0.55 | ++---------------------------+----------+ +| *rf\ :math:`{}_{SOM3}`* | 0.55 | ++---------------------------+----------+ + +Environmental modifiers on decomposition rate +-------------------------------------------------- + +These base rates are modified on each timestep by functions of the +current soil environment. For the single-level model, there are two rate +modifiers, temperature (*r\ :math:`{}_{tsoil}`*, unitless) and moisture +(*r\ :math:`{}_{water}`*, unitless), both of which are calculated using +the average environmental conditions of the top five model levels (top +29 cm of soil column). For the vertically-resolved model, two additional +environmental modifiers are calculated beyond the temperature and +moisture limitations: an oxygen scalar (*r\ :math:`{}_{oxygen}`*, +unitless), and a depth scalar (*r\ :math:`{}_{depth}`*, unitless). + +The Temperature scalar *r\ :math:`{}_{tsoil}`* is calculated in CLM +using a *Q\ :math:`{}_{10}`* approach, with *Q\ :math:`{}_{10}`\ =1.5:* + +.. math:: + + \label{15.5)} + r_{tsoil} =Q_{10} ^{\left(\frac{T_{soil,\, j} -T_{ref} }{10} \right)} + +where *j* is the soil layer index, *T\ :math:`{}_{soil,j}`* (K) is the +temperature of soil level *j*. The reference temperature +*T\ :math:`{}_{ref}`* = 25C. + +The rate scalar for soil water potential (*r\ :math:`{}_{water}`*, +unitless) is calculated using a relationship from Andrén and Paustian +(1987) and supported by additional data in Orchard and Cook (1983): + +.. math:: + + \label{15.6)} + r_{water} =\sum _{j=1}^{5}\left\{\begin{array}{l} {0\qquad {\rm for\; }\Psi _{j} <\Psi _{\min } } \\ {\frac{\log \left({\Psi _{\min } \mathord{\left/ {\vphantom {\Psi _{\min } \Psi _{j} }} \right. \kern-\nulldelimiterspace} \Psi _{j} } \right)}{\log \left({\Psi _{\min } \mathord{\left/ {\vphantom {\Psi _{\min } \Psi _{\max } }} \right. \kern-\nulldelimiterspace} \Psi _{\max } } \right)} w_{soil,\, j} \qquad {\rm for\; }\Psi _{\min } \le \Psi _{j} \le \Psi _{\max } } \\ {1\qquad {\rm for\; }\Psi _{j} >\Psi _{\max } \qquad \qquad } \end{array}\right\} + +where :math:`\Psi`\ *:math:`{}_{j}`* is the soil water potential in +layer *j*, :math:`\Psi`\ *:math:`{}_{min}`* is a lower limit for soil +water potential control on decomposition rate (set to -10 MPa). +:math:`\Psi`\ *:math:`{}_{sat,j}`* (MPa) is the saturated soil water +potential, calculated using the multivariate regression model from Cosby +et al. (1984): + +.. math:: + + \label{15.7)} + \Psi _{sat,\, j} =-\left(9.8e-5\right)\exp \left(\left(1.54-0.0095P_{sand,\, j} +0.0063\left(100-P_{sand,\, j} -P_{clay,\, j} \right)\right)\log \left(10\right)\right) + +where *P\ :math:`{}_{sand,j}`* and *P\ :math:`{}_{clay,j}`* are the +volume percentages of sand and clay in soil layer *j*. + +For frozen soils, the bulk of the rapid dropoff in decomposition with +decreasing temperature is due to the moisture limitation, since matric +potential is limited by temperature in the supercooled water formulation +of Niu and Yang (2006), + +.. math:: + + \label{15.8)} + \psi \left(T\right)=-\frac{L_{f} \left(T-T_{f} \right)}{10^{3} T} + +An additional frozen decomposition limitation can be specified using a +‘frozen Q\ :math:`{}_{10}`’ following Koven et al. (2011), however the +default value of this is the same as the unfrozen Q\ :math:`{}_{10}` +value, and therefore the basic hypothesis is that frozen respiration is +limited by liquid water availability, and can be modeled following the +same approach as thawed but dry soils. + +An additional rate scalar, *r\ :math:`{}_{oxygen}`* is enabled when the +CH\ :math:`{}_{4}` submodel is used (set equal to 1 for the single layer +model or when the CH\ :math:`{}_{4}` submodel is disabled). This limits +decomposition when there is insufficient molecular oxygen to satisfy +stoichiometric demand (1 mol O\ :math:`{}_{2}` consumed per mol +CO\ :math:`{}_{2}` produced) from heterotrophic decomposers, and supply +from diffusion through soil layers (unsaturated and saturated) or +aerenchyma (Chapter 19). A minimum value of *r\ :math:`{}_{oxygen}`* is +set at 0.2, with the assumption that oxygen within organic tissues can +supply the necessary stoichiometric demand at this rate. This value lies +between estimates of 0.025–0.1 (Frolking et al. 2001), and 0.35 (Wania +et al. 2009); the large range of these estimates poses a large +unresolved uncertainty. + +Lastly, a possible explicit depth dependence, *r\ :math:`{}_{depth}`*, +(set equal to 1 for the single layer model) can be applied to soil C +decomposition rates to account for processes other than temperature, +moisture, and anoxia that can limit decomposition. This depth dependence +of decomposition was shown by Jenkinson and Coleman (2008) to be an +important term in fitting total C and 14C profiles, and implies that +unresolved processes, such as priming effects, microscale anoxia, soil +mineral surface and/or aggregate stabilization may be important in +controlling the fate of carbon at depth (Koven et al. 2013). CLM +includes these unresolved depth controls via an exponential decrease in +the soil turnover time with depth: + +.. math:: + + \label{15.9)} + r_{depth} =\exp \left(-\frac{z}{z_{\tau } } \right) + +where *z\ :math:`{}_{\tau}`* is the e-folding depth for decomposition, +set by default to 0.5m. + +The combined decomposition rate scalar (*r\ :math:`{}_{total}`*, +unitless) is: + +.. math:: + + \label{15.10)} + r_{total} =r_{tsoil} r_{water} r_{oxygen} r_{depth} . + +N-limitation of Decomposition Fluxes +----------------------------------------- + +Decomposition rates can also be limited by the availability of mineral +nitrogen, but calculation of this limitation depends on first estimating +the potential rates of decomposition, assuming an unlimited mineral +nitrogen supply. The general case is described here first, referring to +a generic decomposition flux from an “upstream†pool (*u*) to a +“downstream†pool (*d*), with an intervening loss due to respiration. +The potential carbon flux out of the upstream pool +(*CF\ :math:`{}_{pot,u}`*, gC m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is: + +.. math:: + + \label{15.11)} + CF_{pot,\, u} =CS_{u} k_{u} + +where *CS\ :math:`{}_{u}`* (gC m\ :math:`{}^{-2}`) is the initial mass +in the upstream pool and *k\ :math:`{}_{u}`* is the decay rate constant +(s:math:`{}^{-1}`) for the upstream pool, adjusted for temperature and +moisture conditions. Depending on the C:N ratios of the upstream and +downstream pools and the amount of carbon lost in the transformation due +to respiration (the respiration fraction), the execution of this +potential carbon flux can generate either a source or a sink of new +mineral nitrogen +(*NF\ :math:`{}_{pot\_min,u}`\ :math:`{}_{\rightarrow}`\ :math:`{}_{d}`*, +gN m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`). The governing equation +(Thornton and Rosenbloom, 2005) is: + +.. math:: + + \label{15.12)} + NF_{pot\_ min,\, u\to d} =\frac{CF_{pot,\, u} \left(1-rf_{u} -\frac{CN_{d} }{CN_{u} } \right)}{CN_{d} } + +where *rf\ :math:`{}_{u}`* is the respiration fraction for fluxes +leaving the upstream pool, *CN\ :math:`{}_{u}`* and *CN\ :math:`{}_{d}`* +are the C:N ratios for upstream and downstream pools, respectively. +Negative values of +*NF\ :math:`{}_{pot\_min,u}`\ :math:`{}_{\rightarrow}`\ :math:`{}_{d}`* +indicate that the decomposition flux results in a source of new mineral +nitrogen, while positive values indicate that the potential +decomposition flux results in a sink (demand) for mineral nitrogen. + +Following from the general case, potential carbon fluxes leaving +individual pools in the decomposition cascade, for the example of the +CLM-CN pool structure, are given as: + +.. math:: + + \label{15.13)} + CF_{pot,\, Lit1} ={CS_{Lit1} k_{Lit1} r_{total} \mathord{\left/ {\vphantom {CS_{Lit1} k_{Lit1} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{15.14)} + CF_{pot,\, Lit2} ={CS_{Lit2} k_{Lit2} r_{total} \mathord{\left/ {\vphantom {CS_{Lit2} k_{Lit2} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{15.15)} + CF_{pot,\, Lit3} ={CS_{Lit3} k_{Lit3} r_{total} \mathord{\left/ {\vphantom {CS_{Lit3} k_{Lit3} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{15.16)} + CF_{pot,\, SOM1} ={CS_{SOM1} k_{SOM1} r_{total} \mathord{\left/ {\vphantom {CS_{SOM1} k_{SOM1} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{15.17)} + CF_{pot,\, SOM2} ={CS_{SOM2} k_{SOM2} r_{total} \mathord{\left/ {\vphantom {CS_{SOM2} k_{SOM2} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{15.18)} + CF_{pot,\, SOM3} ={CS_{SOM3} k_{SOM3} r_{total} \mathord{\left/ {\vphantom {CS_{SOM3} k_{SOM3} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +.. math:: + + \label{15.19)} + CF_{pot,\, SOM4} ={CS_{SOM4} k_{SOM4} r_{total} \mathord{\left/ {\vphantom {CS_{SOM4} k_{SOM4} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} + +where the factor (1/:math:`\Delta`\ *t*) is included because the rate +constant is calculated for the entire timestep (Eqs. and ), but the +convention is to express all fluxes on a per-second basis. Potential +mineral nitrogen fluxes associated with these decomposition steps are, +again for the example of the CLM-CN pool structure (the CENTURY +structure will be similar but without the different terminal step): + +.. math:: + + \label{ZEqnNum934998} + NF_{pot\_ min,\, Lit1\to SOM1} ={CF_{pot,\, Lit1} \left(1-rf_{Lit1} -\frac{CN_{SOM1} }{CN_{Lit1} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit1} \left(1-rf_{Lit1} -\frac{CN_{SOM1} }{CN_{Lit1} } \right) CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } + +.. math:: + + \label{15.21)} + NF_{pot\_ min,\, Lit2\to SOM2} ={CF_{pot,\, Lit2} \left(1-rf_{Lit2} -\frac{CN_{SOM2} }{CN_{Lit2} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit2} \left(1-rf_{Lit2} -\frac{CN_{SOM2} }{CN_{Lit2} } \right) CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } + +.. math:: + + \label{15.22)} + NF_{pot\_ min,\, Lit3\to SOM3} ={CF_{pot,\, Lit3} \left(1-rf_{Lit3} -\frac{CN_{SOM3} }{CN_{Lit3} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit3} \left(1-rf_{Lit3} -\frac{CN_{SOM3} }{CN_{Lit3} } \right) CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } + +.. math:: + + \label{15.23)} + NF_{pot\_ min,\, SOM1\to SOM2} ={CF_{pot,\, SOM1} \left(1-rf_{SOM1} -\frac{CN_{SOM2} }{CN_{SOM1} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM1} \left(1-rf_{SOM1} -\frac{CN_{SOM2} }{CN_{SOM1} } \right) CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } + +.. math:: + + \label{15.24)} + NF_{pot\_ min,\, SOM2\to SOM3} ={CF_{pot,\, SOM2} \left(1-rf_{SOM2} -\frac{CN_{SOM3} }{CN_{SOM2} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM2} \left(1-rf_{SOM2} -\frac{CN_{SOM3} }{CN_{SOM2} } \right) CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } + +.. math:: + + \label{15.25)} + NF_{pot\_ min,\, SOM3\to SOM4} ={CF_{pot,\, SOM3} \left(1-rf_{SOM3} -\frac{CN_{SOM4} }{CN_{SOM3} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM3} \left(1-rf_{SOM3} -\frac{CN_{SOM4} }{CN_{SOM3} } \right) CN_{SOM4} }} \right. \kern-\nulldelimiterspace} CN_{SOM4} } + +.. math:: + + \label{ZEqnNum473594} + NF_{pot\_ min,\, SOM4} =-{CF_{pot,\, SOM4} \mathord{\left/ {\vphantom {CF_{pot,\, SOM4} CN_{SOM4} }} \right. \kern-\nulldelimiterspace} CN_{SOM4} } + +where the special form of Eq. arises because there is no SOM pool +downstream of SOM4 in the converging cascade: all carbon fluxes leaving +that pool are assumed to be in the form of respired CO\ :math:`{}_{2}`, +and all nitrogen fluxes leaving that pool are assumed to be sources of +new mineral nitrogen. + +Steps in the decomposition cascade that result in release of new mineral +nitrogen (mineralization fluxes) are allowed to proceed at their +potential rates, without modification for nitrogen availability. Steps +that result in an uptake of mineral nitrogen (immobilization fluxes) are +subject to rate limitation, depending on the availability of mineral +nitrogen, the total immobilization demand, and the total demand for soil +mineral nitrogen to support new plant growth. The potential mineral +nitrogen fluxes from Eqs. - are evaluated, summing all the positive +fluxes to generate the total potential nitrogen immobilization flux +(*NF\ :math:`{}_{immob\_demand}`*, gN m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`), and summing absolute values of all the negative +fluxes to generate the total nitrogen mineralization flux +(*NF\ :math:`{}_{gross\_nmin}`*, gN m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`). Since *NF\ :math:`{}_{griss\_nmin}`* is a source of +new mineral nitrogen to the soil mineral nitrogen pool it is not limited +by the availability of soil mineral nitrogen, and is therefore an actual +as opposed to a potential flux. + +N Competition between plant uptake and soil immobilization fluxes +---------------------------------------------------------------------- + +Once *NF\ :math:`{}_{immob\_demand }`* is known, the competition between +plant and microbial nitrogen demand can be resolved. Mineral nitrogen in +the soil pool (*NS\ :math:`{}_{sminn}`*, gN m\ :math:`{}^{-2}`) at the +beginning of the timestep is considered the available supply. Total +demand for mineral nitrogen from this pool +(*NF\ :math:`{}_{total\_demand}`*, gN m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`) is: + +.. math:: + + \label{15.27)} + NF_{total\_ demand} =NF_{immob\_ demand} +NF_{plant\_ demand\_ soil} + +If *NF\ :math:`{}_{total\_demand}`*\ :math:`\Delta`\ *t* :math:`<` +*NS\ :math:`{}_{sminn}`*, then the available pool is large enough to +meet both plant and microbial demand, and neither plant growth nor +immobilization steps in the decomposition cascade are limited by +nitrogen availability in the timestep. In that case, the signaling +variables *f\ :math:`{}_{plant\_demand}`* and +*f\ :math:`{}_{immob\_demand}`* are both set to 1.0, where +*f\ :math:`{}_{plant\_demand}`* is defined and used in section 15.4, and +*f\ :math:`{}_{immob\_demand}`* is the fraction of potential +immobilization demand that can be met given current supply of mineral +nitrogen. + +If *NF\ :math:`{}_{total\_demand}`*\ :math:`\Delta`\ *t* +:math:`\mathrm{\ge}` *NS\ :math:`{}_{sminn}`*, then there is not enough +mineral nitrogen to meet the combined demands for plant growth and +heterotrophic immobilization, and both of these processes proceed at +lower-than-potential rates, defined by the fractions +*f\ :math:`{}_{plant\_demand}`* and *f\ :math:`{}_{immob\_demand}`*, +where: + +.. math:: + + \label{15.28)} + f_{plant\_ demand} =f_{immob\_ demand} =\frac{NS_{sminn} }{\Delta t\, NF_{total\_ demand} } + +This treatment of competition for nitrogen as a limiting resource is +referred to a demand-based competition, where the fraction of the +available resource that eventually flows to a particular process depends +on the demand from that process in comparison to the total demand from +all processes. Processes expressing a greater demand acquire a larger +fraction of the available resource. + +Final Decomposition Fluxes +------------------------------- + +With *f\ :math:`{}_{immob\_demand}`* known, final decomposition fluxes +can be calculated. Actual carbon fluxes leaving the individual litter +and SOM pools, again for the example of the CLM-CN pool structure (the +CENTURY structure will be similar but, again without the different +terminal step), are calculated as: + +.. math:: + + \label{15.29)} + CF_{Lit1} =\left\{\begin{array}{l} {CF_{pot,\, Lit1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {CF_{pot,\, Lit1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} + +.. math:: + + \label{15.30)} + CF_{Lit2} =\left\{\begin{array}{l} {CF_{pot,\, Lit2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {CF_{pot,\, Lit2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} + +.. math:: + + \label{15.31)} + CF_{Lit3} =\left\{\begin{array}{l} {CF_{pot,\, Lit3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {CF_{pot,\, Lit3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} + +.. math:: + + \label{15.32)} + CF_{SOM1} =\left\{\begin{array}{l} {CF_{pot,\, SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {CF_{pot,\, SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} + +.. math:: + + \label{15.33)} + CF_{SOM2} =\left\{\begin{array}{l} {CF_{pot,\, SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {CF_{pot,\, SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} + +.. math:: + + \label{15.34)} + CF_{SOM3} =\left\{\begin{array}{l} {CF_{pot,\, SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {CF_{pot,\, SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} + +.. math:: + + \label{15.35)} + CF_{SOM4} =CF_{pot,\, SOM4} + +Heterotrophic respiration fluxes (losses of carbon as +CO\ :math:`{}_{2}` to the atmosphere) are: + +.. math:: + + \label{15.36)} + CF_{Lit1,\, HR} =CF_{Lit1} rf_{Lit1} + +.. math:: + + \label{15.37)} + CF_{Lit2,\, HR} =CF_{Lit2} rf_{Lit2} + +.. math:: + + \label{15.38)} + CF_{Lit3,\, HR} =CF_{Lit3} rf_{Lit3} + +.. math:: + + \label{15.39)} + CF_{SOM1,\, HR} =CF_{SOM1} rf_{SOM1} + +.. math:: + + \label{15.40)} + CF_{SOM2,\, HR} =CF_{SOM2} rf_{SOM2} + +.. math:: + + \label{15.41)} + CF_{SOM3,\, HR} =CF_{SOM3} rf_{SOM3} + +.. math:: + + \label{15.42)} + CF_{SOM4,\, HR} =CF_{SOM4} rf_{SOM4} + +Transfers of carbon from upstream to downstream pools in the +decomposition cascade are given as: + +.. math:: + + \label{15.43)} + CF_{Lit1,\, SOM1} =CF_{Lit1} \left(1-rf_{Lit1} \right) + +.. math:: + + \label{15.44)} + CF_{Lit2,\, SOM2} =CF_{Lit2} \left(1-rf_{Lit2} \right) + +.. math:: + + \label{15.45)} + CF_{Lit3,\, SOM3} =CF_{Lit3} \left(1-rf_{Lit3} \right) + +.. math:: + + \label{15.46)} + CF_{SOM1,\, SOM2} =CF_{SOM1} \left(1-rf_{SOM1} \right) + +.. math:: + + \label{15.47)} + CF_{SOM2,\, SOM3} =CF_{SOM2} \left(1-rf_{SOM2} \right) + +.. math:: + + \label{15.48)} + CF_{SOM3,\, SOM4} =CF_{SOM3} \left(1-rf_{SOM3} \right) + +In accounting for the fluxes of nitrogen between pools in the +decomposition cascade and associated fluxes to or from the soil mineral +nitrogen pool, the model first calculates a flux of nitrogen from an +upstream pool to a downstream pool, then calculates a flux either from +the soil mineral nitrogen pool to the downstream pool (immobilization) +or from the downstream pool to the soil mineral nitrogen pool +(mineralization). Transfers of nitrogen from upstream to downstream +pools in the decomposition cascade are given as: + +.. math:: + + \label{15.49)} + NF_{Lit1,\, SOM1} ={CF_{Lit1} \mathord{\left/ {\vphantom {CF_{Lit1} CN_{Lit1} }} \right. \kern-\nulldelimiterspace} CN_{Lit1} } + +.. math:: + + \label{15.50)} + NF_{Lit2,\, SOM2} ={CF_{Lit2} \mathord{\left/ {\vphantom {CF_{Lit2} CN_{Lit2} }} \right. \kern-\nulldelimiterspace} CN_{Lit2} } + +.. math:: + + \label{15.51)} + NF_{Lit3,\, SOM3} ={CF_{Lit3} \mathord{\left/ {\vphantom {CF_{Lit3} CN_{Lit3} }} \right. \kern-\nulldelimiterspace} CN_{Lit3} } + +.. math:: + + \label{15.52)} + NF_{SOM1,\, SOM2} ={CF_{SOM1} \mathord{\left/ {\vphantom {CF_{SOM1} CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } + +.. math:: + + \label{15.53)} + NF_{SOM2,\, SOM3} ={CF_{SOM2} \mathord{\left/ {\vphantom {CF_{SOM2} CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } + +.. math:: + + \label{15.54)} + NF_{SOM3,\, SOM4} ={CF_{SOM3} \mathord{\left/ {\vphantom {CF_{SOM3} CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } + +Corresponding fluxes to or from the soil mineral nitrogen pool depend on +whether the decomposition step is an immobilization flux or a +mineralization flux: + +.. math:: + + \label{15.55)} + NF_{sminn,\, Lit1\to SOM1} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit1\to SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {NF_{pot\_ min,\, Lit1\to SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} + +.. math:: + + \label{15.56)} + NF_{sminn,\, Lit2\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit2\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {NF_{pot\_ min,\, Lit2\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} + +.. math:: + + \label{15.57)} + NF_{sminn,\, Lit3\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit3\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {NF_{pot\_ min,\, Lit3\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} + +.. math:: + + \label{15.58)} + NF_{sminn,SOM1\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM1\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {NF_{pot\_ min,\, SOM1\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} + +.. math:: + + \label{15.59)} + NF_{sminn,SOM2\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM2\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {NF_{pot\_ min,\, SOM2\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} + +.. math:: + + \label{15.60)} + NF_{sminn,SOM3\to SOM4} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM3\to SOM4} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {NF_{pot\_ min,\, SOM3\to SOM4} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} + +.. math:: + + \label{15.61)} + NF_{sminn,\, SOM4} =NF_{pot\_ min,\, SOM4} + +Vertical Distribution and Transport of Decomposing C and N pools +--------------------------------------------------------------------- + +Additional terms are needed to calculate the vertically-resolved soil C +and N budget: the initial vertical distribution of C and N from PFTs +delivered to the litter and CWD pools, and the vertical transport of C +and N pools. + +For initial vertical inputs, CLM uses separate profiles for aboveground +(leaf, stem) and belowground (root) inputs. Aboveground inputs are given +a single exponential with default e-folding depth = 0.1m. Belowground +inputs are distributed according to rooting profiles with default values +based on the Jackson et al. (1996) exponential parameterization. + +Vertical mixing is accomplished by an advection-diffusion equation. The +goal of this is to consider slow, soild- and adsorbed-phase transport +due to bioturbation, cryoturbation, and erosion. Faster aqueous-phase +transport is not included in CLM, but has been developed as part of the +CLM-BeTR suite of parameterizations (Tang and Riley 2013). The default +value of the advection term is 0 cm/yr, such that transport is purely +diffusive. Diffusive transport differs in rate between permafrost soils +(where cryoturbation is the dominant transport term) and non-permafrost +soils (where bioturbation dominates). For permafrost soils, a +parameterization based on that of Koven et al. (2009) is used: the +diffusivity parameter is constant through the active layer, and +decreases linearly from the base of the active layer to zero at a set +depth (default 3m); the default permafrost diffusivity is 5 +cm\ :math:`{}^{2}`/yr. For non-permafrost soils, the default diffusivity +is 1 cm\ :math:`{}^{2}`/yr. + +Model Equilibration +------------------------ + +Because of the coupling between the slowest SOM pools and productivity +through N downregulation of photosynthesis, equilibration of the model +for initialization purposes will take an extremely long time in the +standard mode. This is particularly true for the CENTURY-based +decomposition cascade, which includes a passive pool. In order to +rapidly equilibrate the model, a modified version of the “accelerated +decomposition†(Thornton and Rosenbloom, 2005) is used. The fundamental +idea of this approach is to allow fluxes between the various pools (both +turnover-defined and vertically-defined fluxes) adjust rapidly, while +keeping the pool sizes themselves small so that they can fill quickly. +To do this, the base decomposition rate *k\ :math:`{}_{i}`* for each +pool *i* is accelerated by a term *a\ :math:`{}_{i}`* such that the slow +pools are collapsed onto an approximately annual timescale (Koven et al. +2013). Accelerating the pools beyond this timescale distorts the +seasonal and/or diurnal cycles of decomposition and N mineralization, +thus leading to a substantially different ecosystem productivity than +the full model. For the vertical model, the vertical transport terms are +also accelerated by the same term *a\ :math:`{}_{i}`*, as is the +radioactive decay when :math:`{}^{14}`\ C is enabled, following the same +principle of keeping fluxes between pools (or fluxes lost to decay) +close to the full model while keeping the pools sizes small. When +leaving the accelerated decomposition mode, the concentration of C and N +in pools that had been accelerated are multiplied by the same term +*a\ :math:`{}_{i}`*, to bring the model into approximate equilibrium. +Note that in CLM, the model can also transition into accelerated +decomposition mode from the standard mode (by dividing the pools by +*a\ :math:`{}_{i}`*), and that the transitions into and out of +accelerated decomposition mode are handled automatically by CLM upon +loading from restart files (which preserve information about the mode of +the model when restart files were written). + +The acceleration terms for the two decomposition cascades are shown in +Tables 15.1 and 15.3. + +.. |image| image:: image1 +.. |image| image:: image2 diff --git a/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst b/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst new file mode 100644 index 0000000000..b6dd7a2b1a --- /dev/null +++ b/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst @@ -0,0 +1,397 @@ +.. math:: 1 + +.. math:: 1 + +External Nitrogen Cycle +=========================== + +In addition to the relatively rapid cycling of nitrogen within the plant +– litter – soil organic matter system, CLM also represents several slow +processes which couple the internal nitrogen cycle to external sources +and sinks. Inputs of new mineral nitrogen are from atmospheric +deposition and biological nitrogen fixation. Losses of mineral nitrogen +are due to nitrification, denitrification, leaching, and losses in fire. +While the short-term dynamics of nitrogen limitation depend on the +behavior of the internal nitrogen cycle, establishment of total +ecosystem nitrogen stocks depends on the balance between sources and +sinks in the external nitrogen cycle. + +CLM includes two separate treatments of the slow nitrogen cycle. The +first is the original CLM-CN formulations, which includes a single soil +mineral nitrogen pool to represent both +NO\ :math:`{}_{3}`\ :math:`{}^{-}` and +NH\ :math:`{}_{4}`\ :math:`{}^{+}`, and with nitrogen losses via +denitrification calculated as a constant fraction of mineralization plus +a fixed first-order loss of unutilized mineral nitrogen at the end of +every timestep. The second is based on the Century N-gas model; this +includes separate NH\ :math:`{}_{4}`\ :math:`{}^{+}` and +NO\ :math:`{}_{3}`\ :math:`{}^{-}`\ :math:`{}^{ }`\ pools, as well as +environmentally controlled nitrification and denitrification rates. Both +are described below. + +Atmospheric Nitrogen Deposition +------------------------------------ + +CLM uses a single variable to represent the total deposition of mineral +nitrogen onto the land surface, combining wet and dry deposition of +NO\ :math:`{}_{y}` and NH\ :math:`{}_{x}` as a single flux +(*NF\ :math:`{}_{ndep\_sminn}`*, gN m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`). This flux is intended to represent total reactive +nitrogen deposited to the land surface which originates from the +following natural and anthropogenic sources (Galloway et al. 2004): +formation of NO\ :math:`{}_{x}` during lightning, +NO\ :math:`{}_{x }`\ and NH\ :math:`{}_{3}` emission from wildfire, +NO\ :math:`{}_{x}` emission from natural soils, NH\ :math:`{}_{3}` +emission from natural soils, vegetation, and wild animals, +NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` emission during fossil fuel +combustion (both thermal and fuel NO\ :math:`{}_{x}` production), +NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` emission from other industrial +processes, NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` emission from fire +associated with deforestation, NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` +emission from agricultural burning, NO\ :math:`{}_{x}` emission from +agricultural soils, NH\ :math:`{}_{3}` emission from agricultural crops, +NH\ :math:`{}_{3}` emission from agricultural animal waste, and +NH\ :math:`{}_{3}` emission from human waste and waste water. The +deposition flux is provided as a spatially and (potentially) temporally +varying dataset (see section 2.2.3 for a description of the default +input dataset). + +In the CLM-CN mineral N pool model, the nitrogen deposition flux is +assumed to enter the soil mineral nitrogen pool +(*NS\ :math:`{}_{sminn}`*) directly; while in the Century-based model, +all of the nitrogen is assumed to enter the +NH\ :math:`{}_{4}`\ :math:`{}^{+}` pool. Real pathways for wet and dry +nitrogen deposition can be more complex than currently represented in +the CLM-CN, including release from melting snowpack and direct foliar +uptake of deposited NO\ :math:`{}_{y}` (e.g. Tye et al. 2005; Vallano +and Sparks, 2007). + +Biological Nitrogen Fixation +--------------------------------- + +The fixation of new reactive nitrogen from atmospheric N\ :math:`{}_{2}` +by soil microorganisms is an important component of both preindustrial +and modern-day nitrogen budgets, but a mechanistic understanding of +global-scale controls on biological nitrogen fixation (BNF) is still +only poorly developed (Cleveland et al. 1999; Galloway et al. 2004). +Cleveland et al. (1999) suggested empirical relationships that predict +BNF as a function of either evapotranspiration rate or net primary +productivity for natural vegetation. CLM assumes that BNF is a function +of net primary production (*CF\ :math:`{}_{ann\_NPP}`*, gC +m\ :math:`{}^{-2}` y\ :math:`{}^{-1}`). The rationale for choosing net +primary production over evapotranspiration as the predictor is that the +two are well-correlated (Parton et al. 1993; Running et al. 1989), and +the use of primary production also introduces a known dependence of BNF +on the carbon supply to nitrogen fixing microorganisms (Cleveland et al. +1999). The expression used is: + +.. math:: + + \label{ZEqnNum802819} + NF_{nfix,sminn} ={1.8\left(1-\exp \left(-0.003{\kern 1pt} CF_{ann\_ NPP} \right)\right)\mathord{\left/ {\vphantom {1.8\left(1-\exp \left(-0.003{\kern 1pt} CF_{ann\_ NPP} \right)\right) \left(86400\cdot 365\right)}} \right. \kern-\nulldelimiterspace} \left(86400\cdot 365\right)} + +where *NF\ :math:`{}_{nfix,sminn}`* (gN m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`) is the rate of BNF. Eq. is plotted over a range of +annual NPP in Figure 16.1. + +Figure 16.1. Biological nitrogen fixation as a function of annual net +primary production. + +|image| + +Because of the empirical nature of this NPP-BNF relationship, the +timescale for calculating NPP and thus BNF is unconstrained. Using +annual NPP, as in CLM4.0, introduces an error at high latitudes because +the aseasonal BNF inputs mean that much of the nitrogen is added when +the vegetation is dormant and may be lost before it is ever taken up by +vegetation. Thus an option was added to CLM to allow for an exponential +relaxation (with default e-folding time of 10 days) calculation of NPP, +and BNF calculated from that using equation 16.1. + +As with Atmospheric N deposition, BNF N inputs are added directly to the +mineral N pools. In the CLM-CN N model, this is the single mineral N +pool; in the Century-based model, this is the +NH\ :math:`{}_{4}`\ :math:`{}^{+}` pool. + +Nitrification and Denitrification Losses of Nitrogen +--------------------------------------------------------- + +In order to better understand the structural uncertainty in +biogeochemical responses to climate change, CLM includes two alternate +representations of the mineral N transformations and losses that define +the slow N cycle. Each of these is described below. + +16.3.1 CLM-CN formulation +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Under aerobic conditions in the soil oxygen is the preferred electron +acceptor supporting the metabolism of heterotrophs, but anaerobic +conditions favor the activity of soil heterotrophs which use nitrate as +an electron acceptor (e.g. *Pseudomonas* and *Clostridium*) supporting +respiration. This process, known as denitrification, results in the +transformation of nitrate to gaseous N\ :math:`{}_{2}`, with smaller +associated production of NO\ :math:`{}_{x}` and N\ :math:`{}_{2}`\ O. It +is typically assumed that nitrogen fixation and denitrification were +approximately balanced in the preindustrial biosphere (Galloway et al. +2004). It is likely that denitrification can occur within anaerobic +microsites within an otherwise aerobic soil environment, leading to +large global denitrification fluxes even when fluxes per unit area are +rather low (Galloway et al. 2004). + +Because the vertical distribution of soil organic matter is not resolved +explicitly in CLM-CN, a simple denitrification parameterization is used +that treats denitrification as a constant fraction of gross nitrogen +mineralization. At each step in the decomposition cascade, if the +transformation from an upstream to a downstream pool is predicted to +mineralize (as opposed to immobilize) nitrogen, then a constant fraction +of the nitrogen mineralization flux is assumed to be lost via +denitrification. Due to large uncertainties in the mechanistic +understanding of the environmental controls on denitrification, no +modifications to the denitrification fraction are made for different +soil moisture conditions. This is identified as a high-priority area for +future model development. + +Denitrification fluxes associated with gross mineralization in the +decomposition cascade are calculated as follows: + +.. math:: + + \label{16.2)} + NF_{denit,Lit1\to SOM1} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} >0} \\ {-NF_{pot\_ min,Lit1\to SOM1} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} \le 0} \end{array}\right. + +.. math:: + + \label{16.3)} + NF_{denit,Lit2\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} >0} \\ {-NF_{pot\_ min,Lit2\to SOM2} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} \le 0} \end{array}\right. + +.. math:: + + \label{16.4)} + NF_{denit,Lit3\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} >0} \\ {-NF_{pot\_ min,Lit3\to SOM3} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} \le 0} \end{array}\right. + +.. math:: + + \label{16.5)} + NF_{denit,SOM1\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} >0} \\ {-NF_{pot\_ min,SOM1\to SOM2} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} \le 0} \end{array}\right. + +.. math:: + + \label{16.6)} + NF_{denit,SOM2\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} >0} \\ {-NF_{pot\_ min,SOM2\to SOM3} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} \le 0} \end{array}\right. + +.. math:: + + \label{16.7)} + NF_{denit,SOM3\to SOM4} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} >0} \\ {-NF_{pot\_ min,SOM3\to SOM4} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} \le 0} \end{array}\right. + +.. math:: + + \label{16.8)} + NF_{denit,SOM4} =-NF_{pot\_ min,SOM4} + +where *f\ :math:`{}_{denit}`* = 0.01 is the constant denitrification +fraction of gross mineralization, and the denitrification fluxes are +assumed to be leaving the soil mineral nitrogen pool +(*NS\ :math:`{}_{sminn}`*) and entering the atmosphere. The speciation +of gaseous nitrogen fluxes entering the atmosphere (e.g. +N\ :math:`{}_{2}` vs. NO\ :math:`{}_{x}` or N\ :math:`{}_{2}`\ O) is not +specified. Providing an explicit speciation of these nitrogen losses is +another high-priority area for future model development. + +The model includes one other denitrification pathway, intended to +represent the observed losses of mineral nitrogen in systems +experiencing nitrogen saturation. One reason this mechanism has been +included is in anticipation of an agricultural fertilization flux, +provided either through a prescribed dataset or through a prognostic +agricultural management routine. The model does not currently include an +explicit representation of the fertilization flux, but when it is +introduced, it will be necessary to account for the substantial +denitrification losses associated with high nitrate concentrations in +some heavily fertilized agricultural soils. Nitrogen saturation can also +occur in natural vegetation systems, especially under conditions of high +atmospheric nitrogen deposition, and so this mechanism plays a useful +role even prior to the introduction within the model of agricultural +fertilization. + +For the purpose of this calculation, nitrogen saturation is evaluated on +each timestep, by comparing the total demand for new mineral nitrogen +from plants and immobilization with the available soil mineral nitrogen +pool. The denitrification of excess soil mineral nitrogen is non-zero +whenever the supply of mineral nitrogen exceeds the demand: + +.. math:: + + \label{16.9)} + NF_{sminn,denit} =\left\{\begin{array}{l} {\left(\frac{NS_{sminn} }{\Delta t} \right)-NF_{total\_ demand} f_{dnx} \qquad {\rm for\; }NF_{total\_ demand} \Delta tB_{up} } \end{array} + +where :math:`B_{ag}` (g C m\ :math:`{}^{--2}`) is the aboveground +biomass of combined leaf, stem and aboveground litter (leaf litter and +woody debris) pools; :math:`B_{low}` \ =155 g C m\ :math:`{}^{--2 }`\ is +the lower fuel threshold below which fire does not occur; +:math:`B_{up}` \ = 1050 g C m\ :math:`{}^{--2}` is the upper fuel +threshold above which fire occurrence is not limited by fuel +availability. **** + +Fuel combustibility :math:`f_{m}` is estimated by + +.. math:: + + \label{18.7)} + f_{m} =f_{RH} f_{\theta } f_{T} + +where\ :math:`f_{RH}` , **:math:`f_{\theta }` **, :math:`f_{T}` +represent the dependence of fuel combustibility on relative humidity +*RH* (%), surface soil wetness :math:`\theta` , and surface air +temperature *T* (ºC), respectively.\ :math:`f_{RH}` is calculated by + +.. math:: + + \label{18.8)} + f_{RH} =\left\{\begin{array}{cccc} {1} & {} & {} & {RH\le RH_{low} } \\ {\frac{RH_{up} -RH}{RH_{up} -RH_{low} } ,} & {} & {} & {RH_{low} 0.1` person km\ :math:`{}^{-2}`, we parameterize the +fraction of anthropogenic and natural fires unsuppressed by human +activities as + +.. math:: + + \label{18.10)} + f_{se,o} =f_{d} f_{e} + +where *f\ :math:`{}_{d}`* and *:math:`{}_{ }`\ f\ :math:`{}_{e}`* are +the effects of the demographic and economic conditions on fire +occurrence. The demographic influence on fire occurrence is + +.. math:: + + \label{18.11)} + f_{d} =0.01+0.98\exp (-0.025D_{P} ). + +For shrub and grass PFTs, the economic influence on fire occurrence is +parameterized as a function of Gross Domestic Product GDP (k 1995US$ +capita\ :math:`{}^{-1}`): + +.. math:: + + \label{18.12)} + f_{e} =0.1+0.9\times \exp [-\pi (\frac{GDP}{8} )^{0.5} ] + +which captures 73% of the observed MODIS fire counts with variable GDP +in regions where shrub and grass PFTs are dominant (fractional coverage +of shrub and grass PFTs :math:`>` 50%). In regions outside tropical +closed forests and dominated by trees (fractional coverage of tree PFTs +:math:`>` 50%), we divide the MODIS fire counts into only two bins +(:math:`GDP\ge 20` k 1995US$ capita\ :math:`{}^{-1}`, and :math:`GDP<20` +k 1995US$ capita\ :math:`{}^{-1}`) and parameterize the economic +influence on fire occurrence for tree PFTs as + +.. math:: + + \label{18.13)} + f_{e} =\left\{\begin{array}{cc} {0.39,} & {GDP\ge 20} \\ {1} & {GDP<20} \end{array}\right. + +to reproduce that the MODIS fire counts in tree-dominated regions of +GDP\ :math:`\ge 20` k 1995US$ capita\ :math:`{}^{-1}` is 39% of that in +other **** tree-dominated regions. + +18.1.2 Average spread area of a fire +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Fire fighting capacity depends on socioeconomic conditions and affects +fire spread area. Due to a lack of observations, we consider the +socioeconomic impact on the average burned area rather than separately +on fire spread rate and fire duration： + +.. math:: + + \label{18.14)} + a=a^{*} F_{se} + +where :math:`a^{*}` is the average burned area of a fire without +anthropogenic suppression and :math:`F_{se}` is the socioeconomic +effect on fire spread area. + +Average burned area of a fire without anthropogenic suppression is +assumed elliptical in shape with the wind direction along the major axis +and the point of ignition at one of the foci. According to the area +formula for an ellipse, average burned area of a fire can be represented +as: + +.. math:: + + \label{18.15)} + a^{*} =\pi \frac{l}{2} \frac{w}{2} \times 10^{-6} =\frac{\pi u_{p}^{2} \tau ^{2} }{4L_{B} } (1+\frac{1}{H_{B} } )^{2} \times 10^{-6} + +where :math:`u_{p}` \ (m s\ :math:`{}^{--1}`) is the fire spread rate in +the downwind direction; :math:`\tau` \ (s) is average fire +duration;\ :math:`L_{B}` and :math:`H_{B}` are length-to-breadth ratio +and head-to-back ratio of the ellipse; 10\ :math:`{}^{-6 }`\ converts +m\ :math:`{}^{2}` to km\ :math:`{}^{2}`. + +According to Arora and Boer (2005), + +.. math:: + + \label{ZEqnNum696342} + L_{B} =1.0+10.0[1-\exp (-0.06W)] + +where :math:`W`\ (m s\ :math:`{}^{--1}`) is the wind speed. According to +the mathematical properties of the ellipse, the head-to-back ratio +:math:`H_{B}` is + +.. math:: + + \label{ZEqnNum179757} + H_{B} =\frac{u_{p} }{u_{b} } =\frac{L_{B} +(L_{B} ^{2} -1)^{0.5} }{L_{B} -(L_{B} ^{2} -1)^{0.5} } . + +The fire spread rate in the downwind direction is represented as + +.. math:: + + \label{18.18)} + u_{p} =u_{\max } C_{m} g(W) + + (Arora and Boer, 2005), where :math:`u_{\max }` (m +s\ :math:`{}^{--1}`) is the PFT-dependent average maximum fire spread +rate in natural vegetation regions; :math:`C_{m}` and :math:`g(W)` +represent the dependence of :math:`u_{p}` on fuel wetness and wind +speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.55 m +s\ :math:`{}^{--1 }`\ for grass PFTs, 0.46 m s\ :math:`{}^{--1}` for +shrub PFTs, 0.43 m s\ :math:`{}^{--1}` for\ :math:`{}^{ }`\ needleleaf +tree PFTs, and 0.40 m s\ :math:`{}^{--1}` for other tree PFTs. +:math:`C_{m} =C_{\beta } C_{RH}` is estimated by the dependence of +:math:`u_{p}` \ on root zone soil wetness (:math:`C_{\beta }` ) and +relative humidity (:math:`C_{RH}` ). Here,\ :math:`\beta` is a root +zone soil moisture limitation function. Due to a lack of observations to +calibrate :math:`C_{\beta }` , we adopt a simple linear function, where +:math:`\beta _{low}` \ =0.3 and :math:`\beta _{up}` \ =0.7 are the lower +and upper thresholds of root zone soil wetness, respectively. +**:math:`C_{RH}` ** is set equal to :math:`f_{RH}` . :math:`g(W)` is +derived from the mathematical properties of the ellipse and Eqs and + +.. math:: + + \label{18.19)} + g(W)=\frac{2L_{B} }{1+\frac{1}{H_{B} } } g(0). + +Since g(\ *W*)=1.0, and\ :math:`L_{B}` and :math:`H_{B}` are at their +maxima\ :math:`L_{B} ^{\max } =11.0`\ and :math:`H_{B} ^{\max } =482.0` +when :math:`W\to \infty` , g(0) can be derived as + +.. math:: + + \label{18.20)} + g(0)=\frac{1+\frac{1}{H_{B} ^{\max } } }{2L_{B} ^{\max } } =0.05. + +In the absence of globally gridded data on barriers to fire (e.g. +rivers, lakes, roads, firebreaks) and human fire-fighting efforts, +average fire duration is simply assumed equal to 1 which is the observed +2001–2004 mean persistence of most fires in the world (Giglio et al. +2006). + +As with the socioeconomic influence on fire occurrence, we assume that +the socioeconomic influence on fire spreading is negligible in regions +of\ :math:`D_{p} \le 0.1` person km\ :math:`{}^{-2}`, i.e., +:math:`F_{se} =1.0`. In regions of :math:`D_{p} >0.1` person +km\ :math:`{}^{-2}`, we parameterize such socioeconomic influence as: + +.. math:: + + \label{18.21)} + F_{se} =F_{d} F_{e} + +where *F\ :math:`{}_{d}`* and\ *:math:`{}_{ }`\ F\ :math:`{}_{e}`* are +effects of the demographic and economic conditions on the average spread +area of a fire, and are identified by maximizing the explained +variability of the GFED3 burned area fraction with both socioeconomic +indices in grid cells with various dominant vegetation types. For shrub +and grass PFTs, the demographic impact factor is + +.. math:: + + \label{ZEqnNum900584} + F_{d} =0.2+0.8\times \exp [-\pi (\frac{D_{p} }{450} )^{0.5} ] + +and the economic impact factor is + +.. math:: + + \label{ZEqnNum213480} + F_{e} =0.2+0.8\times \exp (-\pi \frac{GDP}{7} ). + +For tree PFTs outside tropical closed forests, the demographic and +economic impact factors are given as + +.. math:: + + \label{18.24)} + F_{d} =0.4+0.6\times \exp (-\pi \frac{D_{p} }{125} ) + +and + +.. math:: + + \label{ZEqnNum543524} + F_{e} =\left\{\begin{array}{cc} {0.62,} & {GDP>20} \\ {0.83,} & {8`\ *T\ :math:`{}_{f}`* if no agricultural fires occurred +earlier in the year; *f\ :math:`{}_{t}`* is set to 0 otherwise. Peak +month in this dataset correlates with the month after harvesting or the +month before planting. In CLM we use this dataset the same way whether +the CROP option is active or not, without regard to the CROP option’s +simulated planting and harvesting dates. + +In the post-fire region, fire impact is parameterized similar to section +18.1.3 but with combustion completeness factors and tissue mortality +factors for crop PFTs (Table 18.1). + +Deforestation fires +------------------------ + +CLM focuses on deforestation fires in tropical closed forests. Tropical +closed forests are defined as grid cells with tropical tree coverage +:math:`>`\ 60% according to the FAO classification. Deforestation fires +are defined as fires caused by deforestation, including escaped +deforestation fires, termed degradation fires. Deforestation and +degradation fires are assumed to occur outside of cropland areas in +these grid cells. Burned area is controlled by the deforestation rate +and climate: + +.. math:: + + \label{18.34)} + A_{b} =bf_{lu} f_{cli,d} A_{g} + +where *b* (time step)\ :math:`{}^{-1 }`\ is a global constant; +:math:`f_{lu}` (fraction) represents the effect of decreasing +fractional coverage of tree PFTs derived from land use data; and +:math:`f_{cli,d}` (fraction) represents the effect of climate +conditions on the burned area. + +Constants *b* and\ :math:`{}^{ }`\ :math:`{}^{f_{lu} }` are calibrated +based on observations and reanalysis datasets in the Amazon rainforest +(tropical closed forests within 15.5ºS\ :math:`\mathrm{-}`\ 10.5ºN, +30.5ºW\ :math:`\mathrm{-}`\ 91ºW). *b=*\ 0.035 d\ :math:`{}^{-1}` and +:math:`f_{lu}` is defined as + +.. math:: + + \label{18.35)} + f_{lu} =\max (0.0005,0.19D-0.0011) + +where :math:`D`\ (yr:math:`{}^{-1}`) is the annual loss of tree cover +based on CLM4’s land use and land cover change data. + +The effect of climate on deforestation fires is parameterized as: + +.. math:: + + \label{ZEqnNum336915} + \begin{array}{l} {f_{cli,d} =\max [0,\min (1,\frac{b_{2} -P_{60d} }{b_{2} } )]^{0.5} \max [0,\min (1,\frac{b_{3} -P_{10d} }{b_{3} } )]^{0.5} } \\ {\qquad \max [0,\min (1,\frac{0.25-P}{0.25} )]} \end{array} + +where\ :math:`P`\ (mm d\ :math:`{}^{-1}`) is instantaneous +precipitation, while :math:`P_{60d}` (mm d\ :math:`{}^{-1}`) and +:math:`P_{10d}` (mm d\ :math:`{}^{-1}`) are 60-day and 10-day running +means of precipitation, respectively; :math:`b_{2}` (mm +d\ :math:`{}^{-1}`) and :math:`b_{3}` (mm d\ :math:`{}^{-1}`) are the +grid-cell dependent thresholds of :math:`P_{60d}` and :math:`P_{10d}` ; +0.25 mm d\ :math:`{}^{-1}` is the maximum precipitation rate for +drizzle. Le Page et al. (2010) analyzed the relationship between +large-scale deforestation fire counts and precipitation during +2003\ :math:`\mathrm{-}`\ 2006 in southern Amazonia where tropical +evergreen trees (BET Tropical) are dominant. Figure 2 in Le Page et al. +(2010) showed that fires generally occurred if both :math:`P_{60d}` and +:math:`P_{10d}` were less than about 4.0 mm d\ :math:`{}^{-1}`, and +fires occurred more frequently in a drier environment. Based on the +30-yr (1985:math:`\mathrm{-}`\ 2004) precipitation data in Qian et al. +(2006), the climatological precipitation of dry months (P:math:`<`\ 4.0 +mm d\ :math:`{}^{-1}`) in a year over tropical deciduous tree (BDT +Tropical) dominated regions is 46% of that over BET Tropical dominated +regions, so we set the PFT-dependent thresholds of :math:`P_{60d}` and +:math:`P_{10d}` as 4.0 mm d\ :math:`{}^{-1}` for BET Tropical and 1.8 +mm d\ :math:`{}^{-1}` (= 4.0 mm d\ :math:`{}^{-1}` :math:`\times` 46%) +for BDT Tropical, and *b\ :math:`{}_{2}`* and *b\ :math:`{}_{3}`* are +the average of thresholds of BET Tropical and BDT Tropical weighted by +their coverage. + +The post-fire area due to deforestation is not limited to land-type +conversion regions. In the tree-reduced region, the maximum fire carbon +emissions are assumed to be 80% of the total conversion flux. According +to the fraction of conversion flux for tropical trees in the +tree-reduced region (60%) assigned by CLM, to reach the maximum fire +carbon emissions in a conversion region requires burning this region +about twice when we set PFT-dependent combustion completeness factors to +about 0.3 for stem [the mean of 0.2\ :math:`\mathrm{-}`\ 0.4 used in van +der Werf (2010)]. Therefore, when the burned area calculated from Eq. is +no more than twice the tree-reduced area, we assume no escaped fires +outside the land-type conversion region, and the fire-related fraction +of the total conversion flux is estimated as +:math:`\frac{A_{b} /A_{g} }{2D}` . Otherwise, 80% of the total +conversion flux is assumed to be fire carbon emissions, and the biomass +combustion and vegetation mortality outside the tree-reduced regions +with an area fraction of :math:`\frac{A_{b} }{A_{g} } -2D` are set as in +section 18.1.3. + +Peat fires +--------------- + +The burned area due to peat fires is given as *A\ :math:`{}_{b}`*: + +.. math:: + + \label{18.37)} + A_{b} =cf_{cli,p} f_{peat} (1-f_{sat} )A_{g} + +where *c* (time step)\ :math:`{}^{-1}` is a constant; :math:`f_{cli,p}` +represents the effect of climate on the burned area;\ :math:`f_{peat}` +is the fractional coverage of peatland in the grid cell; and +:math:`f_{sat}` is the fraction of the grid cell with a water table at +the surface or higher. *c*\ =1.0\ :math:`\times`\ 10\ :math:`{}^{-3}` +hr\ :math:`{}^{-1 }`\ for tropical peat fires and +*c*\ =4.2\ :math:`\times`\ 10\ :math:`{}^{-5}`\ :math:`{}^{ }`\ hr\ :math:`{}^{-1 }`\ for +boreal peat fires are derived using an inverse +method,\ :math:`{}^{ }`\ by matching simulations from an unreleased +CLM4.5 version driven by Qian et al. (2006) atmospheric forcing and +climatological lightning data to earlier studies: about 2.4 Mha peatland +was burned over Indonesia in 1997 (Page et al. 2002) and the average +burned area of peat fires in Western Canada was 0.2 Mha +yr\ :math:`{}^{-1}` for 1980\ :math:`\mathrm{-}`\ 1999 (Turestky et al. +2004). + +For tropical peat fires, :math:`f_{cli,p}` is set as a function of +long-term precipitation :math:`P_{60d}` : + +.. math:: + + \label{18.38)} + f_{cli,p} =\max [0,\min (1,\frac{4-P_{60d} }{4} )]^{2} . + +For boreal peat fires, :math:`f_{cli,p}` is set to + +.. math:: + + \label{18.39)} + f_{cli,p} =\exp (-\pi \frac{\theta _{17cm} }{0.3} )\cdot \max [0,\min (1,\frac{T_{17cm} -T_{f} }{10} )] + +where :math:`\theta _{17cm}` and :math:`T_{17cm}` are the wetness and +temperature of the top 17 cm of soil; :math:`T_{f}` \ =273.15 K is the +freezing temperature. + +Peat fires lead to peat combustion and the combustion and mortality of +vegetation in peatlands. For tropical peat fires, based on Page et al. +(2002), about 6% of the peat carbon loss from stored carbon is caused by +33.9% of the peatland burned. Carbon emissions due to peat combustion (g +C m\ :math:`{}^{-2}` (time step)\ :math:`{}^{-1}`) are therefore set as +the product of 6%/33.9%, by burned area fraction of peat fire ((time +step)\ :math:`{}^{-1}`), by soil organic carbon (g C +m\ :math:`{}^{-2}`). For boreal peat fires, the carbon emissions due to +peat combustion are set as 2.2 kg C +m\ :math:`{}^{-}`\ :math:`{}^{2 }`\ peat fire area (Turetsky et al. +2002). Biomass combustion and vegetation mortality in post-fire +peatlands are set the same as section 18.1.3 for non-crop PFTs and as +section 18.2 for crops PFTs. + +Table 18.1. PFT-specific combustion completeness and fire mortality +factors. + ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| PFT | *CC*\ :math:`{}_{leaf}` | *CC*\ :math:`{}_{stem}` | *CC*\ :math:`{}_{root}` | *CC*\ :math:`{}_{ts}` | *M*\ :math:`{}_{leaf}` | *M*\ :math:`{}_{livestem}` | *M*\ :math:`{}_{deadstem}` | *M*\ :math:`{}_{root}` | *M*\ :math:`{}_{ts}` | *M*\ :math:`{}_{livestem}` | *:math:`\xi`*\ :math:`{}_{j}` | ++==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+ +| NET Temperate | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| NET Boreal | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| NDT Boreal | - | - | - | - | - | - | - | - | - | - | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BET Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BET Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BDT Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BDT Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BDT Boreal | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BES Temperate | - | - | - | - | - | - | - | - | - | - | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BDS Temperate | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| BDS Boreal | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| C\ :math:`{}_{3}` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| C\ :math:`{}_{3}` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| C\ :math:`{}_{4}` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| Crop 1 | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +| Crop 2 | - | - | - | - | - | - | - | - | - | - | - | ++----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + +Leaves (:math:`CC_{{\rm leaf}}` ), stems (:math:`CC_{{\rm stem}}` ), +roots (:math:`CC_{{\rm root}}` ) , and transfer and storage carbon +(:math:`CC_{{\rm ts}}` ); mortality factors for leaves +(:math:`M_{{\rm leaf}}` ), live stems (:math:`M_{{\rm livestem,1}}` ), +dead stems (:math:`M_{{\rm deadstem}}` ), roots +(:math:`M_{{\rm root}}` ), and transfer and storage carbon +(:math:`M_{{\rm ts}}` ) related to the carbon transfers from these pools +to litter pool; mortality factors for live stems +(:math:`M_{{\rm livestem,2}}` ) related to the carbon transfer from live +stems to dead stems; whole-plant mortality factor (:math:`\xi _{j}` ). +Parameters are calibrated in an unreleased CLM4.5 version driven by Qian +et al. (2006) atmospheric forcing and climatological lightning data. diff --git a/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst b/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst new file mode 100644 index 0000000000..980ed65268 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst @@ -0,0 +1,619 @@ +Methane Model +================= + +The representation of processes in the methane biogeochemical model +integrated in CLM [CLM4Me; (Riley et al. 2011a)] is based on several +previously published models (Cao et al. 1996; Petrescu et al. 2010; Tian +et al. 2010; Walter et al. 2001; Wania et al. 2010; Zhang et al. 2002; +Zhuang et al. 2004). Although the model has similarities with these +precursor models, a number of new process representations and +parameterization have been integrated into CLM. + +Mechanistically modeling net surface CH\ :math:`{}_{4}` emissions +requires representing a complex and interacting series of processes. We +first (section 19.1) describe the overall model structure and flow of +information in the CH\ :math:`{}_{4}` model, then describe the methods +used to represent: CH\ :math:`{}_{4}` mass balance; CH\ :math:`{}_{4}` +production; ebullition; aerenchyma transport; CH\ :math:`{}_{4}` +oxidation; reactive transport solution, including boundary conditions, +numerical solution, water table interface, etc.; seasonal inundation +effects; and impact of seasonal inundation on CH\ :math:`{}_{4}` +production. + +Methane Model Structure and Flow +------------------------------------- + +The driver routine for the methane biogeochemistry calculations (ch4, in +ch4Mod.F) controls the initialization of boundary conditions, +inundation, and impact of redox conditions; calls to routines to +calculate CH\ :math:`{}_{4}` production, oxidation, transport through +aerenchyma, ebullition, and the overall mass balance (for unsaturated +and saturated soils and, if desired, lakes); resolves changes to +CH\ :math:`{}_{4}` calculations associated with a changing inundated +fraction; performs a mass balance check; and calculates the average +gridcell CH\ :math:`{}_{4}` production, oxidation, and exchanges with +the atmosphere. + +Governing Mass-Balance Relationship +---------------------------------------- + +The model (Figure 19.1) accounts for CH\ :math:`{}_{4}` production in +the anaerobic fraction of soil (*P*, mol m\ :math:`{}^{-3}` +s\ :math:`{}^{-1}`), ebullition (*E*, mol m\ :math:`{}^{-3}` +s\ :math:`{}^{-1}`), aerenchyma transport (*A*, mol m\ :math:`{}^{-3}` +s\ :math:`{}^{-1}`), aqueous and gaseous diffusion (*F\ :math:`{}_{D}`*, +mol m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), and oxidation (*O*, mol +m\ :math:`{}^{-3}` s\ :math:`{}^{-1}`) via a transient reaction +diffusion equation: + +.. math:: + + \label{ZEqnNum628535} + \frac{\partial \left(RC\right)}{\partial t} =\frac{\partial F_{D} }{\partial z} +P\left(z,t\right)-E\left(z,t\right)-A\left(z,t\right)-O\left(z,t\right) + +Here *z* (m) represents the vertical dimension, *t* (s) is time, and *R* +accounts for gas in both the aqueous and gaseous +phases:\ :math:`R=\varepsilon _{a} +K_{H}^{} \varepsilon _{w}` , with +*:math:`\epsilon`\ :math:`{}_{a}`*, *:math:`\epsilon`\ :math:`{}_{w}`,* +and :math:`K_{H}^{}` (-) the air-filled porosity, water-filled +porosity, and partitioning coefficient for the species of interest, +respectively, and :math:`C` represents CH\ :math:`{}_{4}` or +O\ :math:`{}_{2}` concentration with respect to water volume (mol +m\ :math:`{}^{-3}`). + +An analogous version of equation is concurrently solved for +O\ :math:`{}_{2}`, but with the following differences relative to +CH\ :math:`{}_{4}`: *P* = *E* = 0 (i.e., no production or ebullition), +and the oxidation sink includes the O\ :math:`{}_{2}` demanded by +methanotrophs, heterotroph decomposers, nitrifiers, and autotrophic root +respiration. + +As currently implemented, each gridcell contains an inundated and a +non-inundated fraction. Therefore, equation is solved four times for +each gridcell and time step: in the inundated and non-inundated +fractions, and for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}`. If desired, +the CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` mass balance equation is +solved again for lakes (Chapter 9). For non-inundated areas, the water +table interface is defined at the deepest transition from greater than +95% saturated to less than 95% saturated that occurs above frozen soil +layers. The inundated fraction is allowed to change at each time step, +and the total soil CH\ :math:`{}_{4}` quantity is conserved by evolving +CH\ :math:`{}_{4}` to the atmosphere when the inundated fraction +decreases, and averaging a portion of the non-inundated concentration +into the inundated concentration when the inundated fraction increases. + +Figure 19.1. Schematic representation of biological and physical +processes integrated in CLM that affect the net CH\ :math:`{}_{4}` +surface flux (Riley et al. 2011a). (left) Fully inundated portion of a +CLM gridcell and (right) variably saturated portion of a gridcell. + +|image| + +19.3 CH\ :math:`{}_{4}` Production +---------------------------------- + +Because CLM does not currently specifically represent wetland plant +functional types or soil biogeochemical processes, we used +gridcell-averaged decomposition rates as proxies. Thus, the upland +(default) heterotrophic respiration is used to estimate the wetland +decomposition rate after first dividing off the O\ :math:`{}_{2}` +limitation. The O\ :math:`{}_{2}` consumption associated with anaerobic +decomposition is then set to the unlimited version so that it will be +reduced appropriately during O\ :math:`{}_{2}` competition. +CH\ :math:`{}_{4}` production at each soil level in the anaerobic +portion (i.e., below the water table) of the column is related to the +gridcell estimate of heterotrophic respiration from soil and litter +(*R\ :math:`{}_{H}`*; mol C m\ :math:`{}^{-2}` +s\ :math:`{}^{-}`\ :math:`{}^{1}`) corrected for its soil temperature +(*T\ :math:`{}_{s}`*) dependence, soil temperature through a +*Q*\ :math:`{}_{10}` factor (:math:`f_{T}` ), pH (:math:`f_{pH}` ), +redox potential (:math:`f_{pE}` ), and a factor accounting for the +seasonal inundation fraction (*S*, described below): + +.. math:: + + \label{ZEqnNum109798} + P=R_{H} f_{CH_{4} } f_{T} f_{pH} f_{pE} S. + +Here, :math:`f_{CH_{4} }` is the baseline ratio between +CO\ :math:`{}_{2}` and CH\ :math:`{}_{4}` production (all parameters +values are given in Table 19.1). Currently, :math:`f_{CH_{4} }` is +modified to account for our assumptions that methanogens may have a +higher Q\ :math:`{}_{10}` than aerobic decomposers; are not N limited; +and do not have a low-moisture limitation. + +When the single BGC soil level is used in CLM (Chapter 15), the +temperature factor, :math:`f_{T}` , is set to 0 for temperatures equal +to or below freezing, even though CLM allows heterotrophic respiration +below freezing. However, if the vertically resolved BGC soil column is +used, CH\ :math:`{}_{4}` production continues below freezing because +liquid water stress limits decomposition. The base temperature for the +*Q*\ :math:`{}_{10}` factor, *T\ :math:`{}_{B}`*, is 22 +:math:`{}^\circ`\ C and effectively modified the base +:math:`f_{CH_{4} }` value. + +For the single-layer BGC version, *R\ :math:`{}_{H}`* is distributed ** +among soil levels by assuming that 50% is associated with the roots +(using the CLM PFT-specific rooting distribution) and the rest is evenly +divided among the top 0.28 m of soil (to be consistent with CLM’s soil +decomposition algorithm). For the vertically resolved BGC version, the +prognosed distribution of *R\ :math:`{}_{H}`* is used to estimate +CH\ :math:`{}_{4}` production. + +The factor :math:`f_{pH}` is nominally set to 1, although a static +spatial map of *pH* can be used to determine this factor (Dunfield et +al. 1993) by applying: + +.. math:: + + \label{19.3)} + f_{pH} =10^{-0.2235pH^{2} +2.7727pH-8.6} . + +The :math:`f_{pE}` factor assumes that alternative electron acceptors +are reduced with an e-folding time of 30 days after inundation. The +default version of the model applies this factor to horizontal changes +in inundated area but not to vertical changes in the water table depth +in the upland fraction of the gridcell. We consider both :math:`f_{pH}` +and :math:`f_{pE}` to be poorly constrained in the model and identify +these controllers as important areas for model improvement. + +As a non-default option to account for CH\ :math:`{}_{4}` production in +anoxic microsites above the water table, we apply the Arah and Stephen +(1998) estimate of anaerobic fraction: + +.. math:: + + \label{19.4)} + \varphi =\frac{1}{1+\eta C_{O_{2} } } . + +Here, *:math:`\varphi`* is the factor by which production is inhibited +above the water table (compared to production as calculated in equation +, :math:`C_{O_{2} }` (mol m\ :math:`{}^{-3}`) is the bulk soil oxygen +concentration, and *:math:`\eta`* = 400 mol m\ :math:`{}^{-3}`. + +The O\ :math:`{}_{2}` required to facilitate the vertically resolved +heterotrophic decomposition and root respiration is estimated assuming 1 +mol O\ :math:`{}_{2}` is required per mol CO\ :math:`{}_{2}` produced. +The model also calculates the O\ :math:`{}_{2}` required during +nitrification, and the total O\ :math:`{}_{2}` demand is used in the +O\ :math:`{}_{2}` mass balance solution. + +Table 19.1. Parameter descriptions and sensitivity analysis ranges +applied in the methane model. + ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| Mechanism | Parameter | Baseline Value | Range for Sensitivity Analysis | Units | Description | ++==============+============================+==============================================+==================================================================================================+=============================================+============================================================================================+ +| Production | *Q\ :math:`{}_{10}`* | 2 | 1.5 – 4 | - | CH\ :math:`{}_{4}` production Q\ :math:`{}_{10}` | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| | :math:`f_{pH}` | 1 | On, off | - | Impact of pH on CH\ :math:`{}_{4}` production | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| | :math:`f_{pE}` | 1 | On, off | - | Impact of redox potential on CH\ :math:`{}_{4}` production | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| ** | *S* | Varies | NA | - | Seasonal inundation factor | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| | *:math:`\beta`* | 0.2 | NA | - | Effect of anoxia on decomposition rate (used to calculate *S* only) | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| | :math:`f_{CH_{4} }` | 0.2 | NA | - | Ratio between CH\ :math:`{}_{4}` and CO\ :math:`{}_{2}` production below the water table | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| Ebullition | *C\ :math:`{}_{e,max}`* | 0.15 | NA | mol m\ :math:`{}^{-3}` | CH\ :math:`{}_{4}` concentration to start ebullition | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| ** | *C\ :math:`{}_{e,min}`* | 0.15 | NA | - | CH\ :math:`{}_{4}` concentration to end ebullition | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| Diffusion | :math:`f_{D_{0} }` \ ** | 1 | 1, 10 | m\ :math:`{}^{2}` s\ :math:`{}^{-1}` | Diffusion coefficient multiplier (Table 19.2) | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| Aerenchyma | *p* | 0.3 | NA | - | Grass aerenchyma porosity | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| ** | *R* | 2.9\ :math:`\times`\ 10\ :math:`{}^{-3}` m | NA | m | Aerenchyma radius | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| ** | *r\ :math:`{}_{L}`* | 3 | NA | - | Root length to depth ratio | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| | *F\ :math:`{}_{a}`* | 1 | 0.5 – 1.5 | - | Aerenchyma conductance multiplier | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| Oxidation | :math:`K_{CH_{4} }` | 5 x 10\ :math:`{}^{-3}` | 5\ :math:`\times`\ 10\ :math:`{}^{-4}`\ :math:`{}_{ }`- 5\ :math:`\times`\ 10\ :math:`{}^{-2}` | mol m\ :math:`{}^{-3}` | CH\ :math:`{}_{4}` half-saturation oxidation coefficient (wetlands) | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| ** | :math:`K_{O_{2} }` \ ** | 2 x 10\ :math:`{}^{-2}` | 2\ :math:`\times`\ 10\ :math:`{}^{-3}` - 2\ :math:`\times`\ 10\ :math:`{}^{-1}` | mol m\ :math:`{}^{-3}` | O\ :math:`{}_{2}` half-saturation oxidation coefficient | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +| | :math:`R_{o,\max }` \ ** | 1.25 x 10\ :math:`{}^{-5}` | 1.25\ :math:`\times`\ 10\ :math:`{}^{-6}` - 1.25\ :math:`\times`\ 10\ :math:`{}^{-4}` | mol m\ :math:`{}^{-3}` s\ :math:`{}^{-1}` | Maximum oxidation rate (wetlands) | ++--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + +.. math:: 8 + +.. math:: 17 + +Ebullition +--------------- + +Briefly, the simulated aqueous CH\ :math:`{}_{4}` concentration in each +soil level is used to estimate the expected equilibrium gaseous partial +pressure (:math:`C_{e}` ), as a function of temperature and depth below +the water table, by first estimating the Henry’s law partitioning +coefficient (:math:`k_{h}^{C}` ) by the method described in Wania et al. +(2010): + +.. math:: + + \label{19.5)} + \log \left(\frac{1}{k_{H} } \right)=\log k_{H}^{s} -\frac{1}{C_{H} } \left(\frac{1}{T} -\frac{1}{T^{s} } \right) + +.. math:: + + \label{ZEqnNum493232} + k_{h}^{C} =Tk_{H} R_{g} + +.. math:: + + \label{19.7)} + C_{e} =\frac{C_{w} R_{g} T}{\theta _{s} k_{H}^{C} p} + +where :math:`C_{H}` \ is a constant, :math:`R_{g}` is the universal +gas constant, :math:`k_{H}^{s}` is Henry’s law partitioning coefficient +at standard temperature (:math:`T^{s}` ),\ :math:`C_{w}` \ is local +aqueous CH\ :math:`{}_{4}` concentration, and *p* is pressure. + +The local pressure is calculated as the sum of the ambient pressure, +water pressure down to the local depth, and pressure from surface +ponding (if applicable). When the CH\ :math:`{}_{4}` partial pressure +exceeds 15% of the local pressure (Baird et al. 2004; Strack et al. +2006; Wania et al. 2010), bubbling occurs to remove CH\ :math:`{}_{4}` +to below this value, modified by the fraction of CH\ :math:`{}_{4}` in +the bubbles [taken as 57%; (Kellner et al. 2006; Wania et al. 2010)]. +Bubbles are immediately added to the surface flux for saturated columns +and are placed immediately above the water table interface in +unsaturated columns. + +Aerenchyma Transport +------------------------- + +Aerenchyma transport is modeled in CLM as gaseous diffusion driven by a +concentration gradient between the specific soil layer and the +atmosphere and, if specified, by vertical advection with the +transpiration stream. There is evidence that pressure driven flow can +also occur, but we did not include that mechanism in the current model. + +The diffusive transport through aerenchyma (*A*, mol m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`) from each soil layer is represented in the model as: + +.. math:: + + \label{ZEqnNum158128} + A=\frac{C\left(z\right)-C_{a} }{{\raise0.7ex\hbox{$ r_{L} z $}\!\mathord{\left/ {\vphantom {r_{L} z D}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ D $}} +r_{a} } pT\rho _{r} , + +where *D* is the free-air gas diffusion coefficient (m:math:`{}^{2}` +s\ :math:`{}^{-1}`); *C(z)* (mol m\ :math:`{}^{-3}`) is the gaseous +concentration at depth *z* (m); :math:`r_{L}` is the ratio of root +length to depth; *p* is the porosity (-); *T* is specific aerenchyma +area (m:math:`{}^{2}` m\ :math:`{}^{-2}`); *r\ :math:`{}_{a}`* is the +aerodynamic resistance between the surface and the atmospheric reference +height (s m:math:`{}^{-1}`); and :math:`\rho _{r}` is the rooting +density as a function of depth (-). The gaseous concentration is +calculated with Henry’s law as described in equation . + +Based on the ranges reported in Colmer (2003), we have chosen baseline +aerenchyma porosity values of 0.3 for grass and crop PFTs and 0.1 for +tree and shrub PFTs. The aerenchyma area varies over the course of the +growing season; we parameterize this dependency using the simulated leaf +area index *L* (m:math:`{}^{2}` m\ :math:`{}^{-2}`), as in Wania et al. +(2010): + +.. math:: + + \label{19.9)} + T=\frac{f_{N} N_{a} L}{0.22} \pi R^{2} . + +Here :math:`N_{a}` is annual net primary production (NPP, mol +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`); *R* is the aerenchyma radius +(2.9:math:`\times`\ 10\ :math:`{}^{-3}` m); *f\ :math:`{}_{N}`* is the +belowground fraction of annual NPP; and the 0.22 factor represents the +amount of C per tiller. O\ :math:`{}_{2}` can also diffuse in from the +atmosphere to the soil layer via the reverse of the same pathway, with +the same representation as Equation but with the gas diffusivity of +oxygen. + +CLM also simulates the direct emission of CH\ :math:`{}_{4}` from leaves +to the atmosphere via transpiration of dissolved methane. We calculate +this flux (:math:`F_{CH_{4} -T}` ; mol m\ :math:`{}^{-}`\ :math:`{}^{2}` +s\ :math:`{}^{-1}`) using the simulated soil water methane concentration +(:math:`C_{CH_{4} ,j}` (mol m\ :math:`{}^{-3}`)) in each soil layer *j* +and the CLM predicted transpiration (:math:`F_{T}` ) for each PFT, +assuming that no methane was oxidized inside the plant tissue: + +.. math:: + + \label{19.10)} + F_{CH_{4} -T} =\sum _{j}\rho _{r,j} F_{T} C_{CH_{4} ,j} . + +CH\ :math:`{}_{4}` Oxidation +--------------------------------- + +CLM represents CH\ :math:`{}_{4}` oxidation with double Michaelis-Menten +kinetics (Arah and Stephen 1998; Segers 1998), dependent on both the +gaseous CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` concentrations: + +.. math:: + + \label{19.11)} + R_{oxic} =R_{o,\max } \left[\frac{C_{CH_{4} } }{K_{CH_{4} } +C_{CH_{4} } } \right]\left[\frac{C_{O_{2} } }{K_{O_{2} } +C_{O_{2} } } \right]Q_{10} F_{\vartheta } + +where :math:`K_{CH_{4} }` and :math:`K_{O_{2} }` \ are the half +saturation coefficients (mol m\ :math:`{}^{-3}`) with respect to +CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` concentrations, respectively; +:math:`R_{o,\max }` is the maximum oxidation rate (mol +m\ :math:`{}^{-3}` s\ :math:`{}^{-1}`); and *Q\ :math:`{}_{10}`* +specifies the temperature dependence of the reaction with a base +temperature set to 12 :math:`{}^\circ`\ C. The soil moisture limitation +factor :math:`F_{\vartheta }` is applied above the water table to +represent water stress for methanotrophs. Based on the data in Schnell +and King (1996), we take :math:`F_{\vartheta } =e^{{\raise0.7ex\hbox{` +-P +:math:`}\!\mathord{\left/ {\vphantom {-P P_{c} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{` +P\ :sub:`c` :math:`}} }` , where *P* is the soil moisture potential and +*P\ :math:`{}_{c}`* = -2.4:math:`\times`\ 10\ :math:`{}^{5}` mm. + +Reactive Transport Solution +-------------------------------- + +The solution to equation is solved in several sequential steps: resolve +competition for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` (section +19.7.1); add the ebullition flux into the layer directly above the water +table or into the atmosphere; calculate the overall CH\ :math:`{}_{4}` +or O\ :math:`{}_{2}` source term based on production, aerenchyma +transport, ebullition, and oxidation; establish boundary conditions, +including surface conductance to account for snow, ponding, and +turbulent conductances and bottom flux condition (section 19.7.2); +calculate diffusivity (section 19.7.3); and solve the resulting mass +balance using a tridiagonal solver (section 19.7.5). + +19.7.1 Competition for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For each time step, the unlimited CH\ :math:`{}_{4}` and +O\ :math:`{}_{2}` demands in each model depth interval are computed. If +the total demand over a time step for one of the species exceeds the +amount available in a particular control volume, the demand from each +process associated with the sink is scaled by the fraction required to +ensure non-negative concentrations. Since the methanotrophs are limited +by both CH\ :math:`{}_{4}` and O\ :math:`{}_{2}`, the stricter +limitation is applied to methanotroph oxidation, and then the +limitations are scaled back for the other processes. The competition is +designed so that the sinks must not exceed the available concentration +over the time step, and if any limitation exists, the sinks must sum to +this value. Because the sinks are calculated explicitly while the +transport is semi-implicit, negative concentrations can occur after the +tridiagonal solution. When this condition occurs for O\ :math:`{}_{2}`, +the concentrations are reset to zero; if it occurs for +CH\ :math:`{}_{4}`, the surface flux is adjusted and the concentration +is set to zero if the adjustment is not too large. + +19.7.2 CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` Source Terms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The overall CH\ :math:`{}_{4}` net source term consists of production, +oxidation at the base of aerenchyma, transport through aerenchyma, +methanotrophic oxidation, and ebullition (either to the control volume +above the water table if unsaturated or directly to the atmosphere if +saturated). For O\ :math:`{}_{2}` below the top control volume, the net +source term consists of O\ :math:`{}_{2}` losses from methanotrophy, SOM +decomposition, and autotrophic respiration, and an O\ :math:`{}_{2}` +source through aerenchyma. + +19.7.3 Aqueous and Gaseous Diffusion +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For gaseous diffusion, we adopted the temperature dependence of +molecular free-air diffusion coefficients (*D\ :math:`{}_{0}`* +(m:math:`{}^{2}` s\ :math:`{}^{-1}`)) as described by Lerman et al. +(1979) and applied by Wania et al. (2010) (Table 19.2). + +Table 19.2. Temperature dependence of aqueous and gaseous diffusion +coefficients for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}`. + ++----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ +| D\ :math:`{}_{0}` (m:math:`{}^{2}` s\ :math:`{}^{-1}`) | CH\ :math:`{}_{4}` | O\ :math:`{}_{2}` | ++==========================================================+==========================================================+========================================================+ +| Aqueous | 0.9798 + 0.02986\ *T* + 0.0004381\ *T*\ :math:`{}^{2}` | 1.172+ 0.03443\ *T* + 0.0005048\ *T*\ :math:`{}^{2}` | ++----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ +| Gaseous | 0.1875 + 0.0013\ *T* | 0.1759 + 0.0011\ *T* | ++----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ + +Gaseous diffusivity in soils also depends on the molecular diffusivity, +soil structure, porosity, and organic matter content. Moldrup et al. +(2003), using observations across a range of unsaturated mineral soils, +showed that the relationship between effective diffusivity +(:math:`D_{e}` (m:math:`{}^{2}` s\ :math:`{}^{-1}`)) and soil +properties can be represented as: + +.. math:: + + \label{ZEqnNum730978} + D_{e} =D_{0} \theta _{a}^{2} \left(\frac{\theta _{a} }{\theta _{s} } \right)^{{\raise0.7ex\hbox{$ 3 $}\!\mathord{\left/ {\vphantom {3 b}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ b $}} } , + +where :math:`\theta _{a}` and :math:`\theta _{s}` are the air-filled +and total (saturated water-filled) porosities (-), respectively, and *b* +is the slope of the water retention curve (-). However, Iiyama and +Hasegawa (2005) have shown that the original Millington-Quirk +(Millington and Quirk 1961) relationship matched measurements more +closely in unsaturated peat soils: + +.. math:: + + \label{ZEqnNum437147} + D_{e} =D_{0} \frac{\theta _{a} ^{{\raise0.7ex\hbox{$ 10 $}\!\mathord{\left/ {\vphantom {10 3}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ 3 $}} } }{\theta _{s} ^{2} } + +In CLM, we applied equation for soils with zero organic matter content +and equation for soils with more than 130 kg m\ :math:`{}^{-3}` organic +matter content. A linear interpolation between these two limits is +applied for soils with SOM content below 130 kg m\ :math:`{}^{-3}`. For +aqueous diffusion in the saturated part of the soil column, we applied +(Moldrup et al. 2003): + +.. math:: + + \label{19.14)} + D_{e} =D_{0} \theta _{s} ^{2} . + +To simplify the solution, we assumed that gaseous diffusion dominates +above the water table interface and aqueous diffusion below the water +table interface. Descriptions, baseline values, and dimensions for +parameters specific to the CH\ :math:`{}_{4}` model are given in Table +19.1. For freezing or frozen soils below the water table, diffusion is +limited to the remaining liquid (CLM allows for some freezing point +depression), and the diffusion coefficients are scaled by the +volume-fraction of liquid. For unsaturated soils, Henry’s law +equilibrium is assumed at the interface with the water table. + +19.7.4 Boundary Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We assume the CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` surface fluxes +can be calculated from an effective conductance and a gaseous +concentration gradient between the atmospheric concentration and either +the gaseous concentration in the first soil layer (unsaturated soils) or +in equilibrium with the water (saturated +soil\ :math:`w\left(C_{1}^{n} -C_{a} \right)` and +:math:`w\left(C_{1}^{n+1} -C_{a} \right)` for the fully explicit and +fully implicit cases, respectively (however, see Tang and Riley (2013) +for a more complete representation of this process). Here, *w* is the +surface boundary layer conductance as calculated in the existing CLM +surface latent heat calculations. If the top layer is not fully +saturated, the :math:`\frac{D_{m1} }{\Delta x_{m1} }` term is replaced +with a series combination: +:math:`\left[\frac{1}{w} +\frac{\Delta x_{1} }{D_{1} } \right]^{-1}` , +and if the top layer is saturated, this term is replaced with +:math:`\left[\frac{K_{H} }{w} +\frac{\frac{1}{2} \Delta x_{1} }{D_{1} } \right]^{-1}` , +where *K\ :math:`{}_{H}`* is the Henry’s law equilibrium constant. + +When snow is present, a resistance is added to account for diffusion +through the snow based on the Millington-Quirk expression (equation ) +and CLM’s prediction of the liquid water, ice, and air fractions of each +snow layer. When the soil is ponded, the diffusivity is assumed to be +that of methane in pure water, and the resistance as the ratio of the +ponding depth to diffusivity. The overall conductance is taken as the +series combination of surface, snow, and ponding resistances. We assume +a zero flux gradient at the bottom of the soil column. + +19.7.5 Crank-Nicholson Solution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Equation is solved using a Crank-Nicholson solution (Press et al. 1992), +which combines fully explicit and implicit representations of the mass +balance. The fully explicit decomposition of equation can be written as + +.. math:: + + \label{ZEqnNum395184} + \frac{R_{j}^{n+1} C_{j}^{n+1} -R_{j}^{n} C_{j}^{n} }{\Delta t} =\frac{1}{\Delta x_{j} } \left[\frac{D_{p1}^{n} }{\Delta x_{p1}^{} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{n} }{\Delta x_{m1}^{} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+S_{j}^{n} , + +where *j* refers to the cell in the vertically discretized soil column +(increasing downward), *n* refers to the current time step, +*:math:`\Delta`\ t* is the time step (s), *p1* is *j+½*, *m1* is *j-½*, +and :math:`S_{j}^{n}` is the net source at time step *n* and position +*j*, i.e., +:math:`S_{j}^{n} =P\left(j,n\right)-E\left(j,n\right)-A\left(j,n\right)-O\left(j,n\right)`. +The diffusivity coefficients are calculated as harmonic means of values +from the adjacent cells. Equation is solved for gaseous and aqueous +concentrations above and below the water table, respectively. The *R* +term ensure the total mass balance in both phases is properly accounted +for. An analogous relationship can be generated for the fully implicit +case by replacing *n* by *n+1* on the *C* and *S* terms of equation . +Using an average of the fully implicit and fully explicit relationships +gives: + +.. math:: + + \label{ZEqnNum463314} + \begin{array}{l} {-\frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1}^{} } C_{j-1}^{n+1} +\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(\frac{D_{p1}^{} }{\Delta x_{p1}^{} } +\frac{D_{m1}^{} }{\Delta x_{m1}^{} } \right)\right]C_{j}^{n+1} -\frac{1}{2\Delta x_{j} } \frac{D_{p1}^{} }{\Delta x_{p1}^{} } C_{j+1}^{n+1} =} \\ {\frac{R_{j}^{n} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1}^{} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1}^{} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right]} \end{array}, + +Equation is solved with a standard tridiagonal solver, i.e.: + +.. math:: + + \label{19.17)} + aC_{j-1}^{n+1} +bC_{j}^{n+1} +cC_{j+1}^{n+1} =r, + +with coefficients specified in equation . + +Two methane balance checks are performed at each timestep to insure that +the diffusion solution and the time-varying aggregation over inundated +and non-inundated areas strictly conserves methane molecules (except for +production minus consumption) and carbon atoms. + +19.7.6 Interface between water table and unsaturated zone +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We assume Henry’s Law equilibrium at the interface between the saturated +and unsaturated zone and constant flux from the soil element below the +interface to the center of the soil element above the interface. In this +case, the coefficients are the same as described above, except for the +soil element above the interface: + +.. math:: \frac{D_{p1} }{\Delta x_{p1} } =\left[K_{H} \frac{\Delta x_{j} }{2D_{j} } +\frac{\Delta x_{j+1} }{2D_{j+1} } \right]^{-1} + +.. math:: b=\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(K_{H} \frac{D_{p1}^{} }{\Delta x_{p1} } +\frac{D_{m1}^{} }{\Delta x_{m1} } \right)\right] + +.. math:: + + \label{19.18)} + r=\frac{R_{j}^{n} }{\Delta t} C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -K_{H} C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] + +and the soil element below the interface: + +.. math:: \frac{D_{m1} }{\Delta x_{m1} } =\left[K_{H} \frac{\Delta x_{j-1} }{2D_{j-1} } +\frac{\Delta x_{j} }{2D_{j} } \right]^{-1} + +.. math:: a=-K_{H} \frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1} } + +.. math:: + + \label{19.19)} + r=\frac{R_{j}^{n} }{\Delta t} +C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -K_{H} C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] + +Inundated Fraction Prediction +---------------------------------- + +We developed a simplified dynamic representation of spatial inundation +based on recent work by Prigent et al. (2007), who described a +multi-satellite approach to estimate the global monthly inundated +fraction (*F\ :math:`{}_{i}`*) over an equal area grid +(0.25:math:`\circ`\ :math:`\times`\ 0.25\ :math:`\circ` at the equator) +from 1993 - 2000. They suggested that the IGBP estimate for inundation +could be used as a measure of sensitivity of their detection approach at +low inundation. We therefore used the sum of their satellite-derived +*F\ :math:`{}_{i}`* and the constant IGBP estimate when it was less than +10% to perform a simple inversion for the inundated fraction for methane +production (*f\ :math:`{}_{s}`*). The method optimized three parameters +(*p\ :math:`{}_{1}`*, *p\ :math:`{}_{2}`*, *p\ :math:`{}_{3}`*) for each +grid cell in a simple model based on simulated water table depth +(*z\ :math:`{}_{w}`*) and surface runoff (*Q\ :math:`{}_{r}`* (mm +s\ :math:`{}^{-1}`)): + +.. math:: + + \label{19.20)} + f_{s} =P_{1} e^{{\raise0.7ex\hbox{$ -z_{w} $}\!\mathord{\left/ {\vphantom {-z_{w} p_{2} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ p_{2} $}} } +p_{3} Q_{r} . + +These parameters were evaluated at the +0.5\ **:math:`\boldsymbol{{}^\circ}`** resolution, and aggregated for +coarser simulations. We expect that ongoing work in the hydrology +submodel of CLM will alleviate the need for this crude simplification of +inundated fraction in future model versions. + +Seasonal Inundation +------------------------ + +We have developed a simplified scaling factor to mimic the impact of +seasonal inundation on CH\ :math:`{}_{4}` production (see appendix B in +Riley et al. (2011a) for a discussion of this simplified expression): + +.. math:: + + \label{19.21)} + S=\frac{\beta \left(f-\bar{f}\right)+\bar{f}}{f} ,S\le 1. + +Here, *f* is the instantaneous inundated fraction, :math:`\bar{f}` is +the annual average inundated fraction (evaluated for the previous +calendar year) weighted by heterotrophic respiration, and +*:math:`\beta`* is the anoxia factor that relates the fully anoxic +decomposition rate to the fully oxygen-unlimited decomposition rate, all +other conditions being equal. + +.. |image| image:: image1 diff --git a/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst b/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst new file mode 100644 index 0000000000..0e29f00078 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst @@ -0,0 +1,782 @@ + +Surface Characterization and Model Input Requirements +======================================================== + +Surface Characterization +----------------------------- + +Surface Heterogeneity and Data Structure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Spatial land surface heterogeneity in CLM is represented as a nested +subgrid hierarchy in which grid cells are composed of multiple land +units, snow/soil columns, and PFTs (Figure 2.1). Each grid cell can have +a different number of land units, each land unit can have a different +number of columns, and each column can have multiple PFTs. The first +subgrid level, the land unit, is intended to capture the broadest +spatial patterns of subgrid heterogeneity. The current land units are +glacier, lake, urban, vegetated, and crop (when the crop model option is +turned on). The land unit level can be used to further delineate these +patterns. For example, the urban land unit is divided into density +classes representing the tall building district, high density, and +medium density urban areas. + +The second subgrid level, the column, is intended to capture potential +variability in the soil and snow state variables within a single land +unit. For example, the vegetated land unit could contain several columns +with independently evolving vertical profiles of soil water and +temperature. Similarly, the managed vegetation land unit could be +divided into two columns, irrigated and non-irrigated. The snow/soil +column is represented by fifteen layers for soil and up to five layers +for snow, depending on snow depth. The central characteristic of the +column subgrid level is that this is where the state variables for water +and energy in the soil and snow are defined, as well as the fluxes of +these components within the soil and snow. Regardless of the number and +type of PFTs occupying space on the column, the column physics operates +with a single set of upper boundary fluxes, as well as a single set of +transpiration fluxes from multiple soil levels. These boundary fluxes +are weighted averages over all PFTs. Currently, for glacier, lake, and +vegetated land units, a single column is assigned to each land unit. The +crop land unit is split into irrigated and unirrigated columns with a +single crop occupying each column. The urban land units have five +columns (roof, sunlit walls and shaded walls, and pervious and +impervious canyon floor) (Oleson et al. 2010b). + +Figure 2.1. Configuration of the CLM subgrid hierarchy. + +Note that the Crop land unit is only used when the model is run with the +crop model active. Abbreviations: TBD – Tall Building District; HD – +High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – +Crop, V – Vegetated, PFT – Plant Functional Type, I – Irrigated, U – +Unirrigated . + +.. image:: image1.png + +The third subgrid level is referred to as the PFT level, but it also +includes the treatment for bare ground. It is intended to capture the +biogeophysical and biogeochemical differences between broad categories +of plants in terms of their functional characteristics. On the vegetated +land unit, up to 16 possible PFTs that differ in physiology and +structure may coexist on a single column. All fluxes to and from the +surface are defined at the PFT level, as are the vegetation state +variables (e.g. vegetation temperature and canopy water storage). On the +crop land unit, several different crop types can be represented on each +crop land unit column (see Chapter 20 for details). + +In addition to state and flux variable data structures for conserved +components at each subgrid level (e.g., energy, water, carbon), each +subgrid level also has a physical state data structure for handling +quantities that are not involved in conservation checks (diagnostic +variables). For example, the urban canopy air temperature and humidity +are defined through physical state variables at the land unit level, the +number of snow layers and the soil roughness lengths are defined as +physical state variables at the column level, and the leaf area index +and the fraction of canopy that is wet are defined as physical state +variables at the PFT level. + +The standard configuration of the model subgrid hierarchy is illustrated +in Figure 2.1. Here, only four PFTs are shown associated with the single +column beneath the vegetated land unit but up to sixteen are possible. +The crop land unit is present only when the crop model is active. + +Note that the biogeophysical processes related to soil and snow require +PFT level properties to be aggregated to the column level. For example, +the net heat flux into the ground is required as a boundary condition +for the solution of snow/soil temperatures (Chapter 6). This column +level property must be determined by aggregating the net heat flux from +all PFTs sharing the column. This is generally accomplished in the model +by computing a weighted sum of the desired quantity over all PFTs whose +weighting depends on the PFT area relative to all PFTs, unless otherwise +noted in the text. + +Vegetation Composition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vegetated surfaces are comprised of up to 15 possible plant functional +types (PFTs) plus bare ground (Table 2.1). An additional PFT is +added if the irrigation model is active and six additional PFTs are +added if the crop model is active (Chapter 20). These plant types differ +in leaf and stem optical properties that determine reflection, +transmittance, and absorption of solar radiation (Table 3.1), root +distribution parameters that control the uptake of water from the soil +(Table 8.3), aerodynamic parameters that determine resistance to heat, +moisture, and momentum transfer (Table 5.1), and photosynthetic +parameters that determine stomatal resistance, photosynthesis, and +transpiration (Tables 8.1, 8.2). The composition and abundance of PFTs +within a grid cell can either be prescribed as time-invariant fields +(e.g., using the present day dataset described in section 21.3.3) or can +evolve with time if the model is run in transient landcover mode +(Chapter 21). + +Table 2.1. Plant functional types + ++--------------------------------------------------------------+-------------------+ +| Plant functional type | Acronym | ++==============================================================+===================+ +| Needleleaf evergreen tree – temperate | NET Temperate | ++--------------------------------------------------------------+-------------------+ +| Needleleaf evergreen tree - boreal | NET Boreal | ++--------------------------------------------------------------+-------------------+ +| Needleleaf deciduous tree – boreal | NDT Boreal | ++--------------------------------------------------------------+-------------------+ +| Broadleaf evergreen tree – tropical | BET Tropical | ++--------------------------------------------------------------+-------------------+ +| Broadleaf evergreen tree – temperate | BET Temperate | ++--------------------------------------------------------------+-------------------+ +| Broadleaf deciduous tree – tropical | BDT Tropical | ++--------------------------------------------------------------+-------------------+ +| Broadleaf deciduous tree – temperate | BDT Temperate | ++--------------------------------------------------------------+-------------------+ +| Broadleaf deciduous tree – boreal | BDT Boreal | ++--------------------------------------------------------------+-------------------+ +| Broadleaf evergreen shrub - temperate | BES Temperate | ++--------------------------------------------------------------+-------------------+ +| Broadleaf deciduous shrub – temperate | BDS Temperate | ++--------------------------------------------------------------+-------------------+ +| Broadleaf deciduous shrub – boreal | BDS Boreal | ++--------------------------------------------------------------+-------------------+ +| C\ :math:`{}_{3}` arctic grass | - | ++--------------------------------------------------------------+-------------------+ +| C\ :math:`{}_{3}` grass | - | ++--------------------------------------------------------------+-------------------+ +| C\ :math:`{}_{4}` grass | - | ++--------------------------------------------------------------+-------------------+ +| C\ :math:`{}_{3}` Unmanaged Rainfed Crop | Crop R | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{1}`\ C\ :math:`{}_{3}` Unmanaged Irrigated Crop | Crop I | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{2}`\ Rainfed Corn | Corn R | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{2}`\ Irrigated Corn | Corn I | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{2}`\ Rainfed Temperate Cereals | Temp Cereal R | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{2}`\ Irrigated Temperate Cereals | Temp Cereal I | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{3}`\ Rainfed Winter Cereals | Winter Cereal R | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{3}`\ Irrigated Winter Cereals | Winter Cereal I | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{2}`\ Rainfed Soybean | Soybean R | ++--------------------------------------------------------------+-------------------+ +| :math:`{}^{2}`\ Irrigated Soybean | Soybean I | ++--------------------------------------------------------------+-------------------+ + +:math:`{}^{1}`\ Only used if irrigation is active (Chapter 20). +:math:`{}^{2}`\ Only used if crop model is active (Chapter 20). +:math:`{}^{3}`\ Reserved for future implementations of crop model +(Chapter 20). + +Vegetation Structure +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vegetation structure is defined by leaf and stem area indices +(:math:`L,\, S`) and canopy top and bottom heights +(:math:`z_{top}` ,\ :math:`z_{bot}` ) (Table 2.2). Separate leaf and +stem area indices and canopy heights are prescribed or calculated for +each PFT. Daily leaf and stem area indices are obtained from gridded +datasets of monthly values (section 2.2.3). Canopy top and bottom +heights are also obtained from gridded datasets. However, these are +currently invariant in space and time and were obtained from +PFT-specific values (Bonan et al. 2002a). When the biogeochemistry model +is active, vegetation state (LAI, SAI, canopy top and bottom heights) +are calculated prognostically (see Chapter 14). + +Table 2.2. Prescribed plant functional type heights + ++-----------------------------------+------------------------+------------------------+ +| Plant functional type | :math:`z_{top}` (m) | :math:`z_{bot}` (m) | ++===================================+========================+========================+ +| NET Temperate | 17 | 8.5 | ++-----------------------------------+------------------------+------------------------+ +| NET Boreal | 17 | 8.5 | ++-----------------------------------+------------------------+------------------------+ +| NDT Boreal | 14 | 7 | ++-----------------------------------+------------------------+------------------------+ +| BET Tropical | 35 | 1 | ++-----------------------------------+------------------------+------------------------+ +| BET temperate | 35 | 1 | ++-----------------------------------+------------------------+------------------------+ +| BDT tropical | 18 | 10 | ++-----------------------------------+------------------------+------------------------+ +| BDT temperate | 20 | 11.5 | ++-----------------------------------+------------------------+------------------------+ +| BDT boreal | 20 | 11.5 | ++-----------------------------------+------------------------+------------------------+ +| BES temperate | 0.5 | 0.1 | ++-----------------------------------+------------------------+------------------------+ +| BDS temperate | 0.5 | 0.1 | ++-----------------------------------+------------------------+------------------------+ +| BDS boreal | 0.5 | 0.1 | ++-----------------------------------+------------------------+------------------------+ +| C\ :math:`{}_{3}` arctic grass | 0.5 | 0.01 | ++-----------------------------------+------------------------+------------------------+ +| C\ :math:`{}_{3}` grass | 0.5 | 0.01 | ++-----------------------------------+------------------------+------------------------+ +| C\ :math:`{}_{4}` grass | 0.5 | 0.01 | ++-----------------------------------+------------------------+------------------------+ +| Crop R | 0.5 | 0.01 | ++-----------------------------------+------------------------+------------------------+ +| Crop I | 0.5 | 0.01 | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Corn R | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Corn I | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Temp Cereal R | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Temp Cereal I | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Winter Cereal R | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Winter Cereal I | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Soybean R | - | - | ++-----------------------------------+------------------------+------------------------+ +| :math:`{}^{1}`\ Soybean I | - | - | ++-----------------------------------+------------------------+------------------------+ + +:math:`{}^{1}`\ Determined by the crop model (Chapter 20) + +Phenology and vegetation burial by snow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the biogeochemistry model is inactive, leaf and stem area indices +(m:math:`{}^{2}` leaf area m\ :math:`{}^{-2}` ground area) are updated +daily by linearly interpolating between monthly values. Monthly PFT leaf +area index values are developed from the 1-km MODIS-derived monthly grid +cell average leaf area index of Myneni et al. (2002), as described in +Lawrence and Chase (2007). Stem area index is calculated from the +monthly PFT leaf area index using the methods of Zeng et al. (2002). The +leaf and stem area indices are adjusted for vertical burying by snow +(Wang and Zeng 2009) as + +.. math:: + :label: 2.1 + + A=A^{*} ( 1-f_{veg}^{sno} ) + +where :math:`A^{\*}` is the leaf or stem area before adjustment for +snow, :math:`A` is the remaining exposed leaf or stem area, +:math:`f_{veg}^{sno}` is the vertical fraction of vegetation covered by snow + +.. math:: + :label: 2.2 + + {f_{veg}^{sno} = \frac{z_{sno} -z_{bot} }{z_{top} -z_{bot} } \qquad {\rm for\; tree\; and\; shrub}} \\ + {f_{veg}^{sno} = \frac{\min \left(z_{sno} ,\, z_{c} \right)}{z_{c} } \qquad {\rm for\; grass\; and\; crop}} + +where :math:`z_{sno} -z_{bot} \ge 0,{\rm \; }0\le f_{veg}^{sno} \le 1`, +:math:`z_{sno}` is the depth of snow (m) (section 7.2), and +:math:`z_{c} =0.2` is the snow depth when short vegetation is assumed to +be completely buried by snow (m). For numerical reasons, exposed leaf +and stem area are set to zero if less than 0.05. If the sum of exposed +leaf and stem area is zero, then the surface is treated as snow-covered +ground. + +Model Input Requirements +---------------------------- + +Atmospheric Coupling +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The current state of the atmosphere (Table 2.3) at a given time step is +used to force the land model. This atmospheric state is provided by an +atmospheric model in coupled mode or from an observed dataset in offline +mode (Chapter 26). The land model then initiates a full set of +calculations for surface energy, constituent, momentum, and radiative +fluxes. The land model calculations are implemented in two steps. The +land model proceeds with the calculation of surface energy, constituent, +momentum, and radiative fluxes using the snow and soil hydrologic states +from the previous time step. The land model then updates the soil and +snow hydrology calculations based on these fluxes. These fields are +passed to the atmosphere (Table 2.4). The albedos sent to the atmosphere +are for the solar zenith angle at the next time step but with surface +conditions from the current time step. + +Table 2.3. Atmospheric input to land model + ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Field | variable name | units | ++======================================================+================================================+=================================================+ +| :math:`{}^{1}`\ Reference height | :math:`z'_{atm}` | m | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Zonal wind at :math:`z_{atm}` | :math:`u_{atm}` | m s\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Meridional wind at :math:`z_{atm}` | :math:`v_{atm}` | m s\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Potential temperature | :math:`\overline{\theta _{atm} }` | K | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Specific humidity at :math:`z_{atm}` | :math:`q_{atm}` | kg kg\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Pressure at :math:`z_{atm}` | :math:`P_{atm}` | Pa | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Temperature at :math:`z_{atm}` | :math:`T_{atm}` | K | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Incident longwave radiation | :math:`L_{atm} \, \downarrow` | W m\ :math:`{}^{-2}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| :math:`{}^{2}`\ Liquid precipitation | :math:`q_{rain}` | mm s\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| :math:`{}^{2}`\ Solid precipitation | :math:`q_{sno}` | mm s\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Incident direct beam visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}^{\mu }` | W m\ :math:`{}^{-2}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Incident direct beam near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}^{\mu }` | W m\ :math:`{}^{-2}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Incident diffuse visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}` | W m\ :math:`{}^{-2}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Incident diffuse near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}` | W m\ :math:`{}^{-2}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| Carbon dioxide (CO:math:`{}_{2}`) concentration | :math:`c_{a}` | ppmv | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| :math:`{}^{3}`\ Aerosol deposition rate | :math:`D_{sp}` | kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| :math:`{}^{4}`\ Nitrogen deposition rate | :math:`NF_{ndep\_ s{\it min}n}` | g (N) m\ :math:`{}^{-2}` yr\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +| :math:`{}^{5}`\ Lightning frequency | :math:`I_{l}` | flash km\ :math:`{}^{-2}` hr\ :math:`{}^{-1}` | ++------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + +:math:`{}^{1}`\ The atmospheric reference height received from the +atmospheric model :math:`z'_{atm}` is assumed to be the height above +the surface as defined by the roughness length :math:`z_{0}` plus +displacement height :math:`d`. Thus, the reference height used for flux +computations (Chapter 5) is :math:`z_{atm} =z'_{atm} +z_{0} +d`. The +reference heights for temperature, wind, and specific humidity +(:math:`z_{atm,\, h}` , :math:`z_{atm,\, {\it m}}` , +:math:`z_{atm,\, w}` ) are required. These are set equal +to\ :math:`z_{atm}` . + +:math:`{}^{2}`\ The placeCAM provides convective and large-scale liquid +and solid precipitation, which are added to yield total liquid +precipitation :math:`q_{rain}` and solid precipitation +:math:`q_{sno}` . + +:math:`{}^{3}`\ There are 14 aerosol deposition rates required depending +on species and affinity for bonding with water; 8 of these are dust +deposition rates (dry and wet rates for 4 dust size bins, +:math:`D_{dst,\, dry1} ,\, D_{dst,\, dry2} ,\, D_{dst,\, dry3} ,\, D_{dst,\, dry4}` , +:math:`D_{dst,\, \, wet1} ,D_{dst,\, wet2} ,\, D_{dst,wet3} ,\, D_{dst,\, wet4}` ), +3 are black carbon deposition rates (dry and wet hydrophilic and dry +hydrophobic rates, +:math:`D_{bc,\, dryhphil} ,\, D_{bc,\, wethphil} ,\, D_{bc,\, dryhphob}` ), +and 3 are organic carbon deposition rates (dry and wet hydrophilic and +dry hydrophobic rates, +:math:`D_{oc,\, dryhphil} ,\, D_{oc,\, wethphil} ,\, D_{oc,\, dryhphob}` ). +These fluxes are computed interactively by the atmospheric model (when +prognostic aerosol representation is active) or are prescribed from a +time-varying (annual cycle or transient), globally-gridded deposition +file defined in the namelist (see the CLM4.5 User’s Guide). Aerosol +deposition rates were calculated in a transient 1850-2009 CAM simulation +(at a resolution of 1.9x2.5x26L) with interactive chemistry (troposphere +and stratosphere) driven by CCSM3 20\ :math:`{}^{th}` century +sea-surface temperatures and emissions (Lamarque et al. 2010) for +short-lived gases and aerosols; observed concentrations were specified +for methane, N\ :math:`{}_{2}`\ O, the ozone-depleting substances (CFCs) +,and CO\ :math:`{}_{2}`. The fluxes are used by the snow-related +parameterizations (Chapters 3 and 7). + +:math:`{}^{4}`\ The nitrogen deposition rate is required by the +biogeochemistry model when active and represents the total deposition of +mineral nitrogen onto the land surface, combining deposition of +NO\ :math:`{}_{y}` and NH\ :math:`{}_{x}`. The rate is supplied either +as a time-invariant spatially-varying annual mean rate or time-varying +for a transient simulation. Nitrogen deposition rates were calculated +from the same CAM chemistry simulation that generated the aerosol +deposition rates. + +:math:`{}^{5}`\ Climatological 3-hourly lightning frequency at +:math:`\sim`\ 1.8\ :math:`{}^{o}` resolution is provided, which was +calculated via bilinear interpolation from 1995-2011 NASA LIS/OTD grid +product v2.2 (http://ghrc.msfc.nasa.gov) 2-hourly, 2.5\ :math:`{}^{o}` +lightning frequency data. In future versions of the model, lightning +data may be obtained directly from the atmosphere model. + +Density of air (:math:`\rho _{atm}` ) (kg m\ :math:`{}^{-3}`) is also +required but is calculated directly from +:math:`\rho _{atm} =\frac{P_{atm} -0.378e_{atm} }{R_{da} T_{atm} }` +where :math:`P_{atm}` is atmospheric pressure (Pa), :math:`e_{atm}` is +atmospheric vapor pressure (Pa), :math:`R_{da}` is the gas constant for +dry air (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), and +:math:`T_{atm}` is the atmospheric temperature (K). The atmospheric +vapor pressure :math:`e_{atm}` is derived from atmospheric specific +humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`) as +:math:`e_{atm} =\frac{q_{atm} P_{atm} }{0.622+0.378q_{atm} }` . + +The O\ :math:`{}_{2}` partial pressure (Pa) is required but is +calculated from molar ratio and the atmospheric pressure +:math:`P_{atm}` as :math:`o_{i} =0.209P_{atm}` . + +Table 2.4. Land model output to atmospheric model + ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Field | Variable name | units | ++=======================================+================================================+==============================================================+ +| :math:`{}^{1}`\ Latent heat flux | :math:`\lambda _{vap} E_{v} +\lambda E_{g}` | W m\ :math:`{}^{-2}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Sensible heat flux | :math:`H_{v} +H_{g}` | W m\ :math:`{}^{-2}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Water vapor flux | :math:`E_{v} +E_{g}` | mm s\ :math:`{}^{-1}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Zonal momentum flux | :math:`\tau _{x}` | kg m\ :math:`{}^{-1}` s\ :math:`{}^{-2}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Meridional momentum flux | :math:`\tau _{y}` | kg m\ :math:`{}^{-1}` s\ :math:`{}^{-2}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Emitted longwave radiation | :math:`L\, \uparrow` | W m\ :math:`{}^{-2}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Direct beam visible albedo | :math:`I\, \uparrow _{vis}^{\mu }` | - | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Direct beam near-infrared albedo | :math:`I\, \uparrow _{nir}^{\mu }` | - | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Diffuse visible albedo | :math:`I\, \uparrow _{vis}` | - | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Diffuse near-infrared albedo | :math:`I\, \uparrow _{nir}` | - | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Absorbed solar radiation | :math:`\vec{S}` | W m\ :math:`{}^{-2}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Radiative temperature | :math:`T_{rad}` | K | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Temperature at 2 meter height | :math:`T_{2m}` | K | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Specific humidity at 2 meter height | :math:`q_{2m}` | kg kg\ :math:`{}^{-1}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Snow water equivalent | :math:`W_{sno}` | m | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Aerodynamic resistance | :math:`r_{am}` | s m\ :math:`{}^{-1}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Friction velocity | :math:`u_{*}` | m s\ :math:`{}^{-1}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| :math:`{}^{2}`\ Dust flux | :math:`F_{j}` | kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +| Net ecosystem exchange | NEE | kgCO\ :math:`{}_{2}` m\ :math:`{}^{-2}` s\ :math:`{}^{-1}` | ++---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + +:math:`{}^{1}`\ :math:`\lambda _{vap}` is the latent heat of +vaporization (J kg\ :math:`{}^{-1}`) (Table 2.6) and :math:`\lambda` is +either the latent heat of vaporization :math:`\lambda _{vap}` or latent +heat of sublimation :math:`\lambda _{sub}` (J kg\ :math:`{}^{-1}`) +(Table 2.6) depending on the liquid water and ice content of the top +snow/soil layer (section 5.4). + +:math:`{}^{2}`\ There are :math:`j=1,\ldots ,4` dust transport bins. + +Initialization +^^^^^^^^^^^^^^^^^^^^ + +Initialization of the land model (i.e., providing the model with initial +temperature and moisture states) depends on the type of run (startup or +restart) (see the CLM4.5 User’s Guide). A startup run starts the model +from either initial conditions that are set internally in the Fortran +code (referred to as arbitrary initial conditions) or from an initial +conditions dataset that enables the model to start from a spun up state +(i.e., where the land is in equilibrium with the simulated climate). In +restart runs, the model is continued from a previous simulation and +initialized from a restart file that ensures that the output is +bit-for-bit the same as if the previous simulation had not stopped. The +fields that are required from the restart or initial conditions files +can be obtained by examining the code. Arbitrary initial conditions are +specified as follows. + +Vegetated and glacier land units have fifteen vertical layers, while +lakes have ten. For soil points, temperature calculations are done over +all layers, :math:`N_{levgrnd} =15`, while hydrology calculations are +done over the top ten layers, :math:`N_{levsoi} =10`, the bottom five +layers being specified as bedrock. Soil points are initialized with +surface ground temperature :math:`T_{g}` and soil layer temperature +:math:`T_{i}` , for :math:`i=1,\ldots ,N_{levgrnd}` , of 274 K, +vegetation temperature :math:`T_{v}` of 283 K, no snow or canopy water +(:math:`W_{sno} =0`, :math:`W_{can} =0`), and volumetric soil water +content :math:`\theta _{i} =0.15` mm\ :math:`{}^{3}` mm\ :math:`{}^{-3}` +for layers :math:`i=1,\ldots ,N_{levsoi}` and :math:`\theta _{i} =0.0` +mm\ :math:`{}^{3}` mm\ :math:`{}^{-3}` for layers +:math:`i=N_{levsoi} +1,\ldots ,N_{levgrnd}` . placeLake temperatures +(:math:`T_{g}` and :math:`T_{i}` ) are initialized at 277 K and +:math:`W_{sno} =0`. + +Glacier temperatures (:math:`T_{g} =T_{snl+1}` and :math:`T_{i}` for +:math:`i=snl+1,\ldots ,N_{levgrnd}` where :math:`snl` is the negative +of the number of snow layers, i.e., :math:`snl` ranges from –5 to 0) are +initialized to 250 K with a snow water equivalent :math:`W_{sno} =1000` +mm, snow depth :math:`z_{sno} =\frac{W_{sno} }{\rho _{sno} }` (m) where +:math:`\rho _{sno} =250` kg m\ :math:`{}^{-3}` is an initial estimate +for the bulk density of snow, and :math:`\theta _{i}` \ =1.0 for +:math:`i=1,\ldots ,N_{levgrnd}` . The snow layer structure (e.g., number +of snow layers :math:`snl` and layer thickness) is initialized based on +the snow depth (section 6.1). The snow liquid water and ice contents (kg +m\ :math:`{}^{-2}`) are initialized as :math:`w_{liq,\, i} =0` and +:math:`w_{ice,\, i} =\Delta z_{i} \rho _{sno}` , respectively, where +:math:`i=snl+1,\ldots ,0` are the snow layers, and :math:`\Delta z_{i}` +is the thickness of snow layer :math:`i` (m). The soil liquid water and +ice contents are initialized as :math:`w_{liq,\, i} =0` and +:math:`w_{ice,\, i} =\Delta z_{i} \rho _{ice} \theta _{i}` for +:math:`T_{i} \le T_{f}` , and +:math:`w_{liq,\, i} =\Delta z_{i} \rho _{liq} \theta _{i}` and +:math:`w_{ice,\, i} =0` for :math:`T_{i} >T_{f}` , where +:math:`\rho _{ice}` and :math:`\rho _{liq}` are the densities of ice +and liquid water (kg m\ :math:`{}^{-3}`) (Table 2.6), and :math:`T_{f}` +is the freezing temperature of water (K) (Table 2.6). All vegetated and +glacier land units are initialized with water stored in the unconfined +aquifer and unsaturated soil :math:`W_{a} =4000` mm and water table +depth :math:`z_{\nabla }` at five meters below the soil column. + +Surface Data +^^^^^^^^^^^^^^^^^^ + +Required surface data for each land grid cell are listed in Table 2.5 +and include the glacier, lake, and urban fractions of the grid cell +(vegetated and crop occupy the remainder), the fractional cover of each +plant functional type (PFT), monthly leaf and stem area index and canopy +top and bottom heights for each PFT, soil color, soil texture, soil +organic matter density, maximum fractional saturated area, slope, +elevation, biogenic volatile organic compounds (BVOCs) emissions +factors, population density, gross domestic production, peat area +fraction, and peak month of agricultural burning. Optional surface data +include crop irrigation and managed crops. All fields are aggregated to +the model’s grid from high-resolution input datasets (Table 2.5) that +are obtained from a variety of sources described below. + +Table 2.5. Surface data required for CLM and their base spatial +resolution + ++--------------------------------------------+---------------------------+ +| Surface Field | Resolution | ++============================================+===========================+ +| Percent glacier | 0.05\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Percent lake and lake depth | 0.05\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Percent urban | 0.05\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Percent plant functional types (PFTs) | 0.05\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Monthly leaf and stem area index | 0.5\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Canopy height (top, bottom) | 0.5\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Soil color | 0.5\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Percent sand, percent clay | 0.083\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Soil organic matter density | 0.083\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Maximum fractional saturated area | 0.125\ :math:`\circ` | ++--------------------------------------------+---------------------------+ +| Elevation | 1km | ++--------------------------------------------+---------------------------+ +| Slope | 1km | ++--------------------------------------------+---------------------------+ +| Biogenic Volatile Organic Compounds | 0.5\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Crop Irrigation | 0.083\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Managed crops | 0.5\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Population density | 0.5\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Gross domestic production | 0.5\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Peat area fraction | 0.5\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ +| Peak month of agricultural waste burning | 0.5\ :math:`{}^\circ` | ++--------------------------------------------+---------------------------+ + +At the base spatial resolution of 0.05\ :math:`\circ`, the percentage of +each PFT is defined with respect to the vegetated portion of the grid +cell and the sum of the PFTs is 100%. The percent lake, wetland, +glacier, and urban at their base resolution are specified with respect +to the entire grid cell. The surface dataset creation routines re-adjust +the PFT percentages to ensure that the sum of all land cover types in +the grid cell sum to 100%. A minimum threshold of 0.1% of the grid cell +by area is required for urban areas. + +The percentage glacier mask was derived from vector data of global +glacier and ice sheet spatial coverage. Vector data for glaciers (ice +caps, icefields and mountain glaciers) were taken from the first +globally complete glacier inventory, the Randolph Glacier Inventory +version 1.0 (RGIv1.0: Arendt et al. 2012). Vector data for the Greenland +Ice Sheet were provided by Frank Paul and Tobias Bolch (University of +Zurich: Rastner et al. 2012). Antarctic Ice Sheet data were provided by +Andrew Bliss (University of Alaska) and were extracted from the +Scientific Committee on Antarctic Research (SCAR) Antarctic Digital +Database version 5.0. Floating ice is only provided for the Antarctic +and does not include the small area of Arctic ice shelves. High spatial +resolution vector data were then processed to determine the area of +glacier, ice sheet and floating ice within 30-second grid cells +globally. The 30-second glacier, ice sheet and Antarctic ice shelf masks +were subsequently draped over equivalent-resolution GLOBE topography +(Global Land One-km Base Elevation Project, Hastings et al. 1999) to +extract approximate ice-covered elevations of ice-covered regions. Grid +cells flagged as land-ice in the mask but ocean in GLOBE (typically, +around ice sheets at high latitudes) were designated land-ice with an +elevation of 0 meters. Finally, the high-resolution mask/topography +datasets were aggregated and processed into three 3-minute datasets: +3-minute fractional areal land ice coverage (including both glaciers and +ice sheets); 3-minute distributions of areal glacier fractional coverage +by elevation and areal ice sheet fractional coverage by elevation. Ice +fractions were binned at 100 meter intervals, with bin edges defined +from 0 to 6000 meters (plus one top bin encompassing all remaining +high-elevation ice, primarily in the Himalaya). These distributions by +elevation are needed when running CLM4 with multiple glacier elevation +classes. + +Percent lake and lake depth are area-averaged from the 90-second +resolution data of Kourzeneva (2009, 2010) to the 0.05\ :math:`{}^\circ` +resolution using the MODIS land-mask. Percent urban is derived from +LandScan 2004, a population density dataset derived from census data, +nighttime lights satellite observations, road proximity and slope +(Dobson et al. 2000) as described by Jackson et al. (2010) at 1km +resolution and aggregated to 0.05\ :math:`{}^\circ`. A number of urban +radiative, thermal, and morphological fields are also required and are +obtained from Jackson et al. (2010). Their description can be found in +Table 3 of the Community Land Model Urban (CLMU) technical note (Oleson +et al. 2010b). + +Percent PFTs are derived from MODIS satellite data as described in +Lawrence and Chase (2007) (section 21.3.3). Prescribed PFT leaf area +index is derived from the MODIS satellite data of Myneni et al. (2002) +using the de-aggregation methods described in Lawrence and Chase (2007) +(section 2.2.3). Prescribed PFT stem area index is derived from PFT leaf +area index phenology combined with the methods of Zeng et al. (2002). +Prescribed canopy top and bottom heights are from Bonan (1996) as +described in Bonan et al. (2002b). If the biogeochemistry model is +active, it supplies the leaf and stem area index and canopy top and +bottom heights dynamically, and the prescribed values are ignored. + +Soil color determines dry and saturated soil albedo (section 3.2). Soil +colors are from Lawrence and Chase (2007) (section 3.2). + +The soil texture and organic matter content determine soil thermal and +hydrologic properties (sections 6.3 and 7.4.1). The International +Geosphere-Biosphere Programme (IGBP) soil dataset (Global Soil Data Task +2000) of 4931 soil mapping units and their sand and clay content for +each soil layer were used to create a mineral soil texture dataset +(Bonan et al. 2002b). Soil organic matter data is merged from two +sources. The majority of the globe is from ISRIC-WISE (Batjes, 2006). +The high latitudes come from the 0.25\ :math:`{}^\circ` version of the +Northern Circumpolar Soil Carbon Database (Hugelius et al. 2012). Both +datasets report carbon down to 1m depth. Carbon is partitioned across +the top seven CLM4 layers (:math:`\sim`\ 1m depth) as in Lawrence and +Slater (2008). + +The maximum fractional saturated area (:math:`f_{\max }` ) is used in +determining surface runoff and infiltration (section 7.3). Maximum +fractional saturated area at 0.125\ :math:`{}^{o}` resolution is +calculated from 1-km compound topographic indices (CTIs) based on the +USGS HYDRO1K dataset (Verdin and Greenlee 1996) following the algorithm +in Niu et al. (2005). :math:`f_{\max }` is the ratio between the number +of 1-km pixels with CTIs equal to or larger than the mean CTI and the +total number of pixels in a 0.125\ :math:`{}^\circ` grid cell. See +section 7.3.1 and Li et al. (2013b) for further details. Slope and +elevation are also obtained from the USGS HYDRO1K 1-km dataset (Verdin +and Greenlee 1996). Slope is used in the River Transport Model (Chapter +11) and in the surface water parameterization (section 7.3.2), and +elevation is used to calculate the grid cell standard deviation of +topography for the snow cover fraction parameterization (section 7.2.1). + +Biogenic Volatile Organic Compounds emissions factors are from the Model +of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1; +Guenther et al. 2012). + +The default list of PFTs includes an unmanaged crop treated as a second +C3 grass (Table 2.1). The unmanaged crop has grid cell fractional cover +assigned from MODIS satellite data (Lawrence and Chase 2007). A managed +crop option uses grid cell fractional cover from the present-day crop +dataset of Ramankutty and Foley (1998) (CLM4CNcrop). Managed crops are +assigned in the proportions given by Ramankutty and Foley (1998) without +exceeding the area previously assigned to the unmanaged crop. The +unmanaged crop continues to occupy any of its original area that remains +and continues to be handled just by the CN part of CLM4CNcrop. The +managed crop types (corn, soybean, and temperate cereals) were chosen +based on the availability of corresponding algorithms in AgroIBIS +(Kucharik et al. 2000; Kucharik and Brye 2003). Temperate cereals +include wheat, barley, and rye here. All temperate cereals are treated +as summer crops (like spring wheat, for example) at this time. Winter +cereals (such as winter wheat) may be introduced in a future version of +the model. + +To allow crops to coexist with natural vegetation in a grid cell and be +treated by separate models (i.e., CLM4.5BGCcrop versus the Dynamic +Vegetation version (CLM4.5BGCDV)), we separate the vegetated land unit +into a naturally vegetated land unit and a human managed land unit. PFTs +in the naturally vegetated land unit share one soil column and compete +for water (default CLM setting). PFTs in the human managed land unit do +not share soil columns and thus permit for differences in land +management between crops. + +CLM includes the option to irrigate cropland areas that are equipped for +irrigation. The application of irrigation responds dynamically to +climate (see Chapter 20). In CLM, irrigation is implemented for the C3 +generic crop only. When irrigation is enabled, the cropland area of each +grid cell is divided into an irrigated and unirrigated fraction +according to a dataset of areas equipped for irrigation (Siebert et al. +2005). The area of irrigated cropland in each grid cell is given by the +smaller of the grid cell’s total cropland area, according to the default +CLM4 dataset, and the grid cell’s area equipped for irrigation. The +remainder of the grid cell’s cropland area (if any) is then assigned to +unirrigated cropland. Irrigated and unirrigated crops are placed on +separate soil columns, so that irrigation is only applied to the soil +beneath irrigated crops. + +Several input datasets are required for the fire model (Li et al. 2013a) +including population density, gross domestic production, peat area +fraction, and peak month of agricultural waste burning. Population +density at 0.5\ :math:`{}^{o}` resolution for 1850-2100 combines 5-min +resolution decadal population density data for 1850–1980 from the +Database of the Global Environment version 3.1 (HYDEv3.1) with +0.5\ :math:`{}^{o}` resolution population density data for 1990, 1995, +2000, and 2005 from the Gridded Population of the World version 3 +dataset (GPWv3) (CIESIN, 2005). Gross Domestic Production (GDP) per +capita in 2000 at 0.5\ :math:`{}^{o}` is from Van Vuuren et al. (2006), +which is the base-year GDP data for IPCC-SRES and derived from +country-level World Bank’s World Development Indicators (WDI) measured +in constant 1995 US$ (World Bank, 2004) and the UN Statistics Database +(UNSTAT, 2005). The peatland area fraction at 0.5\ :math:`{}^{o}` +resolution is derived from three vector datasets: peatland data in +Indonesia and Malaysian Borneo (Olson et al. 2001); peatland data in +Canada (Tarnocai et al. 2011); and bog, fen and mire data in boreal +regions (north of 45\ :math:`{}^{o}`\ N) outside Canada provided by the +Global Lakes and Wetlands Database (GLWD) (Lehner and Döll, 2004). The +climatological peak month for agricultural waste burning is from van der +Werf et al. (2010). + +Adjustable Parameters and Physical Constants +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Values of certain adjustable parameters inherent in the biogeophysical +or biogeochemical parameterizations have either been obtained from the +literature or calibrated based on comparisons with observations. These +are described in the text. Physical constants, generally shared by all +of the components in the coupled modeling system, are presented in Table +2.6. + +.. csv-table:: Table 2.6. Physical constants + :header: "description", "name", "value", "units" + :widths: 40, 20, 20, 20 + + "Pi", :math:`\pi`, 3.14159265358979323846, "\-" + "Acceleration of gravity", :math:`g`, 9.80616, m s\ :math:`{}^{-2}` + "Standard pressure", :math:`P_{std}`, 101325, "Pa" + "Stefan-Boltzmann constant", :math:`\sigma`, 5.67 :math:`\times 10^{-8}`, W m :math:`{}^{-2}` K :math:`{}^{-4}` + "Boltzmann constant", :math:`\kappa`, 1.38065 :math:`\times 10^{-23}`, J K :math:`{}^{-1}` molecule :math:`{}^{-1}` + "Avogadro’s number", :math:`N_{A}`, 6.02214 :math:`\times 10^{26}`, molecule kmol\ :math:`{}^{-1}` + "Universal gas constant", :math:`R_{gas}`, :math:`N_{A} \kappa`, J K :math:`{}^{-1}` kmol :math:`{}^{-1}` + "Molecular weight of dry air", :math:`MW_{da}`, 28.966, kg kmol :math:`{}^{-1}` + "Dry air gas constant", :math:`R_{da}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{da} }} \right. \kern-\nulldelimiterspace} MW_{da} }`, J K :math:`{}^{-1}` kg :math:`{}^{-1}` + "Molecular weight of water vapor", :math:`MW_{wv}`, 18.016, kg kmol :math:`{}^{-1}` + "Water vapor gas constant", :math:`R_{wv}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{wv} }} \right. \kern-\nulldelimiterspace} MW_{wv} }`, J K :math:`{}^{-1}` kg :math:`{}^{-1}` + "Von Karman constant", :math:`k`, 0.4, "\-" + "Freezing temperature of fresh water", :math:`T_{f}`, 273.5, K + "Density of liquid water", :math:`\rho _{liq}`, 1000, kg m :math:`{}^{-3}` + "Density of ice", :math:`\rho _{ice}`, 917, kg m :math:`{}^{-3}` + "Specific heat capacity of dry air", :math:`C_{p}`, 1.00464 :math:`\times 10^{3}`, J kg :math:`{}^{-1}` K :math:`{}^{-1}` + "Specific heat capacity of water", :math:`C_{liq}`, 4.188 :math:`\times 10^{3}`, J kg :math:`{}^{-1}` K :math:`{}^{-1}` + "Specific heat capacity of ice", :math:`C_{ice}`, 2.11727 :math:`\times 10^{3}`, J kg :math:`{}^{-1}` K :math:`{}^{-1}` + "Latent heat of vaporization", :math:`\lambda _{vap}`, 2.501 :math:`\times 10^{6}`, J kg :math:`{}^{-1}` + "Latent heat of fusion", :math:`L_{f}`, 3.337 :math:`\times 10^{5}`, J kg :math:`{}^{-1}` + "Latent heat of sublimation", :math:`\lambda _{sub}`, :math:`\lambda _{vap} +L_{f}`, J kg :math:`{}^{-1}` + :math:`{}^{1}` "Thermal conductivity of water", :math:`\lambda _{liq}`, 0.57, W m :math:`{}^{-1}` K :math:`{}^{-1}` + :math:`{}^{1}` "Thermal conductivity of ice", :math:`\lambda _{ice}`, 2.29, W m :math:`{}^{-1}` K :math:`{}^{-1}` + :math:`{}^{1}` "Thermal conductivity of air", :math:`\lambda _{air}`, 0.023 W m :math:`{}^{-1}` K :math:`{}^{-1}` + "Radius of the earth", :math:`R_{e}`, 6.37122, :math:`\times 10^{6}` m + +:math:`{}^{1}`\ Not shared by other components of the coupled modeling system. + diff --git a/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst b/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst new file mode 100644 index 0000000000..2c378b3aec --- /dev/null +++ b/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst @@ -0,0 +1,722 @@ +**** + +Crops and Irrigation +======================== + +Summary of CLM4.5 updates relative to the CLM4.0 +----------------------------------------------------- + +We describe here the complete crop and irrigation parameterizations that +appear in CLM4.5. Corresponding information for CLM4.0 appeared on the +CLM4.0 web site in a pdf document independent of the CLM4.0 Technical +Note (Oleson et al. 2010a). The CLM4.0 crop model description also +appeared in Levis et al. (2012). + +CLM4.5 includes the following updates to the CROP option, where CROP +refers to the interactive crop management model: + +- Interactive irrigation + +- Interactive fertilization + +- Biological nitrogen fixation for soybeans + +- Modified C:N ratios for crops + +- Nitrogen retranslocation for crops + +- Separate reproductive pool + +These updates appear in detail in section 20.4. Most also appear in +Drewniak et al. (2013). + +The crop model +------------------- + +20.2.1 Introduction +^^^^^^^^^^^^^^^^^^^ + +Groups developing Earth System Models generally account for the human +footprint on the landscape in simulations of historical and future +climates. Traditionally we have represented this footprint with natural +vegetation types and particularly grasses because they resemble many +common crops. Most modeling efforts have not incorporated more explicit +representations of land management such as crop type, planting, +harvesting, tillage, fertilization, and irrigation, because global scale +datasets of these factors have lagged behind vegetation mapping. As this +begins to change, we increasingly find models that will simulate the +biogeophysical and biogeochemical effects not only of natural but also +human-managed land cover. + +AgroIBIS is a state-of-the-art land surface model with options to +simulate dynamic vegetation (Kucharik et al. ** 2000) and interactive +crop management (Kucharik and Brye 2003). The interactive crop +management parameterizations from AgroIBIS (March 2003 version) were +coupled as a proof-of-concept to the Community Land Model version 3 +[CLM3.0, Oleson et al. ** (2004)] (not published), then coupled to the +CLM3.5 (Levis et al. 2009) and later released to the community with +CLM4CN (Levis et al. 2012). + +With interactive crop management and, therefore, a more accurate +representation of agricultural landscapes, we hope to improve the CLM’s +simulated biogeophysics and biogeochemistry. These advances may improve +fully coupled simulations with the Community Earth System Model (CESM), +while helping human societies answer questions about changing food, +energy, and water resources in response to climate, environmental, land +use, and land management change (e.g., Kucharik and Brye 2003; Lobell et +al. ** 2006). + +20.2.2 Crop plant functional types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CLM’s default list of plant functional types (pfts) includes an +unmanaged crop (Table 2.1) treated as a second C3 grass. The unmanaged +crop has grid cell coverage assigned from satellite data, as do all +natural pfts when CLM’s dynamic vegetation model (CNDV; Castillo et al. +2012) is not active. + +The new crop pfts used in the CLM get grid cell coverage from the +present-day crop dataset of Portmann et al. (2010). We assign these +managed crops in the proportions given by Portmann et al. (2010) without +exceeding the area previously assigned to the unmanaged crop. The +unmanaged crop continues to occupy any of its original area that remains +and continues to be handled just by the carbon/nitrogen cycling part of +the CLM (i.e., CN). The managed crop types (corn, soybean, and temperate +cereals) were chosen based on the availability of corresponding +algorithms in AgroIBIS. Temperate cereals include wheat, barley, and rye +here. We treat all temperate cereals as summer crops (like spring wheat, +for example) at this time. We may introduce winter cereals (such as +winter wheat) in a future version of the model. + +To allow crops to coexist with natural vegetation in a grid cell and be +treated by separate models (i.e., CLM4.5CNcrop versus CLM4.5CNDV), we +separate the vegetated land unit into a naturally vegetated land unit +and a human managed land unit. Plant functional types in the naturally +vegetated land unit share one soil column and compete for water (default +CLM setting). Managed crop PFTs in the human managed land unit do not +share soil columns and thus permit for differences in land management +between crops. + +20.2.3 Phenology +^^^^^^^^^^^^^^^^ + +CLM4.5CN includes evergreen, seasonally deciduous (responding to changes +in day length), and stress deciduous (responding to changes in +temperature and/or soil moisture) phenology algorithms (Chapter 14). In +CLM4.5CNcrop we have added the AgroIBIS crop phenology algorithm, +consisting of three distinct phases. + +Phase 1 starts at planting and ends with leaf emergence, phase 2 +continues from leaf emergence to the beginning of grain fill, and phase +3 starts from the beginning of grain fill and ends with physiological +maturity and harvest. + +20.2.3.1 Planting +''''''''''''''''' + +Corn and temperate cereals must meet the following requirements between +April 1\ :math:`{}^{st}` and June 14\ :math:`{}^{th}` for planting in +the northern hemisphere (NH): + +.. math:: + + \label{ZEqnNum568682} + \begin{array}{l} {T_{10d} >T_{p} } \\ {T_{10d}^{\min } >T_{p}^{\min } } \\ {GDD_{8} \ge GDD_{\min } } \end{array} + +where *T*\ :math:`{}_{10}`\ *:math:`{}_{d}`* is the 10-day running mean +of *T*\ :math:`{}_{2}`\ *:math:`{}_{m}`*, (the simulated 2-m air +temperature at every model time step) and :math:`T_{10d}^{\min }` is +the 10-day running mean of :math:`T_{2m}^{\min }` (the daily minimum of +*T*\ :math:`{}_{2}`\ *:math:`{}_{m}`*). *T\ :math:`{}_{p}`* and +:math:`T_{p}^{\min }` are crop-specific coldest planting temperatures +(Table 20.1), *GDD*\ :math:`{}_{8}` is the 20-year running mean growing +degree-days (units are degree-days or :math:`{}^\circ`\ days) tracked +from April through September (NH) base 8\ :math:`{}^\circ`\ C with +maximum daily increments of 30\ :math:`{}^\circ`\ days (see Eq. ), and +*GDD*\ :math:`{}_{min }`\ is the minimum growing degree day requirement +(Table 20.1). Soy must meet the same requirements but between May +1\ :math:`{}^{st}` and June 14\ :math:`{}^{th}` for planting. If the +requirements in Eq. are not met by June 14\ :math:`{}^{th}`, then corn, +soybean, and temperate cereals are still planted on June +15\ :math:`{}^{th}` as long as *GDD*\ :math:`{}_{8}`\ :math:`>`\ 0. In +the southern hemisphere (SH) the NH requirements apply 6 months later. + +*GDD*\ :math:`{}_{8}` does not change as quickly as +*T*\ :math:`{}_{10}`\ *:math:`{}_{d}`* and :math:`T_{10d}^{\min }` , so +it determines whether the crop can be planted in a grid cell, while the +two faster-changing variables determine when the crop may be planted. + +At planting, each crop is assigned 1 g leaf C m\ :math:`{}^{-2}` pft +column area to be transferred to the leaves upon leaf emergence. An +equivalent amount of seed leaf N is assigned given the pft’s C to N +ratio for leaves (*CN\ :math:`{}_{leaf}`*). (This differs from AgroIBIS, +which uses a seed leaf area index instead of seed C.) + +At planting, the model updates the average growing degree-days necessary +for the crop to reach vegetative and physiological maturity, +*GDD*\ :math:`{}_{mat}`, according to the following AgroIBIS rules: + +.. math:: + + \label{20.2)} + \begin{array}{l} {GDD_{{\rm mat}}^{{\rm corn}} =0.85GDD_{{\rm 8}} {\rm \; \; \; and\; \; \; 950}` 0, and *:math:`\beta`\ :math:`{}_{t}`* :math:`<` 1, +i.e., water is limiting for photosynthesis (see section 8.4). + +If irrigation is required, the model computes the deficit between the +current soil moisture content and a target soil moisture content; this +deficit is the amount of water that will be added through irrigation. +The target soil moisture content in each soil layer *i* +(*w\ :math:`{}_{target,i}`*, kg m\ :math:`{}^{-2}`) is a weighted +average of the minimum soil moisture content that results in no water +stress in that layer (*w\ :math:`{}_{o,i}`*, kg m\ :math:`{}^{-2}`) and +the soil moisture content at saturation in that layer +(*w\ :math:`{}_{sat,i}`*, kg m\ :math:`{}^{-2}`): + +.. math:: + + \label{20.7)} + w_{target,i} =(1-0.7)\cdot w_{o,i} +0.7\cdot w_{sat,i} + +*w\ :math:`{}_{o,i}`* is determined by inverting equation 8.19 in Oleson +et al. (2010a) to solve for the value of *s\ :math:`{}_{i}`* (soil +wetness) that makes *:math:`\Psi`\ :math:`{}_{i}`* = +*:math:`\Psi`\ :math:`{}_{o}`* (where *:math:`\Psi`\ :math:`{}_{i}`* is +the soil water matric potential and *:math:`\Psi`\ :math:`{}_{o}`* is +the soil water potential when stomata are fully open), and then +converting this value to units of kg m\ :math:`{}^{-2}`. +*w\ :math:`{}_{sat,i}`* is calculated simply by converting effective +porosity (section 7.4) to units of kg m\ :math:`{}^{-2}`. The value 0.7 +was determined empirically, in order to give global, annual irrigation +amounts that approximately match observed gross irrigation water use +around the year 2000 (i.e., total water withdrawals for irrigation: +:math:`\sim` 2500 – 3000 km\ :math:`{}^{3}` year\ :math:`{}^{-1}` +(Shiklomanov 2000)). The total water deficit (*w\ :math:`{}_{deficit}`*, +kg m\ :math:`{}^{-2}`) of the column is then determined by: + +.. math:: + + \label{20.8)} + w_{deficit} =\sum _{i}\max \left(w_{target,i} -w_{liq,i} ,0\right) + +where *w\ :math:`{}_{liq,i}`* (kg m\ :math:`{}^{-2}`) is the current +soil water content of layer *i* (Chapter 7). The max function means that +a surplus in one layer cannot make up for a deficit in another layer. +The sum is taken only over soil layers that contain roots. In addition, +if the temperature of any soil layer is below freezing, then the sum +only includes layers above the top-most frozen soil layer. + +The amount of water added to this column through irrigation is then +equal to *w\ :math:`{}_{deficit}`*. This irrigation is applied at a +constant rate over the following four hours. Irrigation water is applied +directly to the ground surface, bypassing canopy interception (i.e., +added to *q\ :math:`{}_{grnd,liq}`*: section 7.1). Added irrigation is +removed from total liquid runoff (*R\ :math:`{}_{liq}`*: Chapter 11), +simulating removal from nearby rivers. + +The details about what is new in CLM4.5 +-------------------------------------------- + +20.4.1 Interactive irrigation for corn, temperate cereals, and soybean +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CLM4.0 included interactive irrigation only for the generic C3 crops, +i.e. plant functional types (pfts) 15 (rainfed) and 16 (irrigated) in +the CLM list of pfts and not for the additional crops of the interactive +crop management model (CROP). Irrigation and CROP were mutually +exclusive in CLM4.0. + +In CLM4.5 we have reversed this situation. Now the irrigation model can +be used only while running with CROP. To accomplish this we downloaded +data of percent irrigated and percent rainfed corn, soybean, and +temperate cereals (wheat, barley, and rye) (Portmann et al. 2010), +available online from + +*ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* + +We embedded this data in CLM’s high-resolution pft data for use with the +tool mksurfdat to generate surface datasets at any desired resolution. +Now this data includes percent cover for 24 pfts: + +1-16 as in the standard list of pfts, plus six more: + +17 corn + +18 irrigated\_corn + +19 spring\_temperate\_cereal + +20 irrigated\_spring\_temperate\_cereal + +21 winter\_temperate\_cereal + +22 irrigated\_winter\_temperate\_cereal + +23 soybean + +24 irrigated\_soybean + +We intend surface datasets with 24 pfts only for CROP simulations with +or without irrigation. In simulations without irrigation, the rainfed +and irrigated crops merge into just rainfed crops at run time. Surface +datasets with 16 pfts can be used for all other CLM simulations. + +20.4.2 Interactive fertilization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CLM adds nitrogen directly to the soil mineral nitrogen pool to meet +crop nitrogen demands. CLM’s separate crop land unit ensures that +natural vegetation will not access the fertilizer applied to crops. +Fertilizer amounts are obtained from the Agro-IBIS model (Kucharik and +Brye 2003), but can be modified in CLM’s pft-physiology input dataset. +Fertilizer is reported in g N/m\ :math:`{}^{2}` by plant functional +type. Total nitrogen fertilizer amounts are 150 g N/m\ :math:`{}^{2}` +for maize, 80 g N/m\ :math:`{}^{2}` for temperate cereals, and 25 g +N/m\ :math:`{}^{2}` for soybean, representative of central U.S. annual +fertilizer application amounts. Since CLM’s denitrification rate is high +and results in a 50% loss of the unused available nitrogen each day, +fertilizer is applied slowly to minimize the loss and maximize plant +uptake. Fertilizer application begins during the emergence phase of crop +development and continues for 20 days, which helps reduce large losses +of nitrogen from leaching and denitrification during the early stage of +crop development. The 20-day period is chosen as an optimization to +limit fertilizer application to the emergence stage. A fertilizer +counter in seconds, *f*, is set as soon as the onset growth for crops +initiates: + +*f* = *n* \* 86400 [20.9)] + +where *n* is set to 20 fertilizer application days. When the crop enters +phase 2 (leaf emergence to the beginning of grain fill) of its growth +cycle, fertilizer application begins by initializing fertilizer amount +to the total fertilizer divided by the initialized *f*. Fertilizer is +applied and *f* is decremented each time step until a zero balance on +the counter is reached. + +The crop fertilization scheme was developed in versions of the CLM prior +to CLM4.5. In CLM4.5, crops with fertilization may be simulated over +productive. + +20.4.3 Biological nitrogen fixation for soybeans +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Nitrogen fixation by soybeans is similar to that in the SWAT model +(Neitsch et al. 2005) and depends on soil moisture, nitrogen +availability, and growth stage. Soybean fixation is calculated only for +unmet nitrogen demand; if soil nitrogen meets soybean demand, there will +be no fixation during the time step. Soybean fixation is determined by + +.. math:: + + \label{20.10)} + N_{fix} \; =\; N_{plant\_ ndemand} \; *\; min\; \left(\; 1,\; fxw,\; fxn\; \right)*\; fxg + +where *N\ :math:`{}_{plant\_demand}`* is the balance of nitrogen needed +to reach potential growth that cannot be supplied from the soil mineral +nitrogen pool, *fxw* is the soil water factor, *fxn* is the soil +nitrogen factor, and *fxg* is the growth stage factor calculated by + +.. math:: + + \label{20.11)} + fxw=\frac{wf}{0.85} + +.. math:: + + \label{20.12)} + fxn=\; \left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }sminn\le 10} \\ {1.5-0.005\left(sminn\times 10\right)\qquad {\rm for\; 10\; <\; }sminn{\rm \; }\ge 30} \\ {1\qquad \qquad \qquad \qquad {\rm for\; }sminn>30} \end{array}\right\} + +.. math:: + + \label{20.13)} + fxg=\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad \qquad {\rm for\; }GDD_{T_{2m} } \le 0.15} \\ {6.67\times GDD_{T_{2m} } -1\qquad \qquad \qquad {\rm for\; }0.150.75} \end{array}\right\} + +where *wf* is the soil water content as a fraction of the water holding +capacity for the top 0.05 m, *sminn* is the total nitrogen in the soil +pool (g/m:math:`{}^{2}`), and :math:`{GDD}_{T_{2m}}` is the fraction of +growing degree-days accumulated during the growing season. +:math:`N\mathrm{fix}` is added directly to the soil mineral nitrogen +pool for use that time step. Nitrogen fixation occurs after the plant +has accumulated 15%\ *GDD\ :math:`{}_{mat}`* and before +75%\ *GDD\ :math:`{}_{mat}`*, so before grain fill begins. + +20.4.4 Modified C:N ratios for crops +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Typically, C:N ratios in plant tissue vary throughout the growing season +and tend to be lower during early growth stages and higher in later +growth stages. In order to account for this change, two sets of C:N +ratios are established in CLM for the leaf, stem, and fine root of +crops. This modified C:N ratio approach accounts for the nitrogen +retranslocation that occurs during phase 3 of crop growth. Leaf and stem +(and root for temperate cereals) C:N ratios for phases 1 and 2 are lower +than measurements (Table 20.3) to allow excess nitrogen storage in plant +tissue. During grain fill (phase 3) of the crop growth cycle, the +nitrogen in the plant tissues is moved to a storage pool to fulfill +nitrogen demands of organ (reproductive pool) development, such that the +resulting C:N ratio of the plant tissue is reflective of measurements at +harvest. All C:N ratios were determined by calibration process, through +comparisons of model output versus observations of plant carbon +throughout the growth season. + +20.4.5 Nitrogen retranslocation for crops +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Nitrogen retranslocation in crops occurs when nitrogen that was used for +tissue growth of leaves, stems, and fine roots during the early growth +season is remobilized and used for grain development (Pollmer et al. +1979; Crawford et al. 1982; Simpson et al. 1983; Ta and Weiland 1992; +Barbottin et al. 2005; Gallais et al. 2006, 2007). Nitrogen allocation +for crops follows that of natural vegetation, is supplied in CLM by the +soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, +roots, and organs. Nitrogen demand during organ development is fulfilled +through retranslocation from leaves, stems, and roots. Nitrogen +retranslocation is initiated at the beginning of the grain fill stage +for corn and temperate cereals, but not until after LAI decline in +soybean. Nitrogen stored in the leaf and stem is moved into a storage +retranslocation pool. For temperate cereals, nitrogen in roots is also +released into the retranslocation storage pool. The quantity of nitrogen +mobilized depends on the C:N ratio of the plant tissue, and is +calculated as + +.. math:: + + \label{20.14)} + leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } + +.. math:: + + \label{20.15)} + stemn\_ to\_ retransn=\frac{c_{stem} }{CN_{stem} } -\frac{c_{stem} }{CN_{stem}^{f} } + +.. math:: + + \label{20.16)} + frootn\_ to\_ retransn=\frac{c_{froot} }{CN_{froot} } -\frac{c_{froot} }{CN_{froot}^{f} } + +where *C\ :math:`{}_{leaf}`*, *C\ :math:`{}_{stem}`*, and +*C\ :math:`{}_{froot}`* is the carbon in the plant leaf, stem, and fine +root, respectively, *CN\ :math:`{}_{leaf}`*, *CN\ :math:`{}_{stem}`*, +and *CN\ :math:`{}_{froot}`* is the pre-grain fill C:N ratio of the +leaf, stem, and fine root respectively, and :math:`CN^f_{leaf}`, +:math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N +ratio of the leaf, stem, and fine root respectively (Table 20.3). Since +C:N measurements are taken from mature crops, pre-grain development C:N +ratios for leaves, stems, and roots are optimized to allow maximum +nitrogen accumulation for later use during organ development. Post-grain +fill C:N ratios are assigned the same as crop residue. Once excess +nitrogen is moved into the retranslocated pool, during the remainder of +the growing season the retranslocated pool is used first to meet plant +nitrogen demand by assigning the available nitrogen from the +retranslocated pool equal to the plant nitrogen demand. Once the +retranslocation pool is depleted, soil mineral nitrogen pool is used to +fulfill plant nitrogen demands. + +Table 20.3. Pre- and post-grain fill C:N ratios for crop leaf, stem, +fine root, and reproductive pools. + ++----------------------------+--------+---------------------+-----------+ +| Pre-grain fill stage | Corn | Temperate Cereals | Soybean | ++============================+========+=====================+===========+ +| *CN\ :math:`{}_{leaf}`* | 10 | 15 | 25 | ++----------------------------+--------+---------------------+-----------+ +| *CN\ :math:`{}_{stem}`* | 50 | 50 | 50 | ++----------------------------+--------+---------------------+-----------+ +| *CN\ :math:`{}_{froot}`* | 42 | 30 | 42 | ++----------------------------+--------+---------------------+-----------+ +| Post-grain fill stage | | | | ++----------------------------+--------+---------------------+-----------+ +| :math:`CN_{leaf}^{f}` | 65 | 65 | 65 | ++----------------------------+--------+---------------------+-----------+ +| :math:`CN_{stem}^{f}` | 120 | 100 | 130 | ++----------------------------+--------+---------------------+-----------+ +| :math:`CN_{froot}^{f}` | 42 | 40 | 42 | ++----------------------------+--------+---------------------+-----------+ +| :math:`CN_{repr}^{f}` | 50 | 40 | 60 | ++----------------------------+--------+---------------------+-----------+ + +**** + +20.4.6 Separate reproductive pool +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +One notable difference between natural vegetation and crops is the +presence of a reproductive carbon pool (and nitrogen pool). Accounting +for the reproductive pool helps determine whether crops are performing +reasonably, through yield calculations, seasonal GPP and NEE changes, +etc. The reproductive pool is maintained similarly to the leaf, stem, +and fine root pools, but allocation of carbon and nitrogen does not +begin until the grain fill stage of crop development. Eq. shows the +carbon and nitrogen allocation coefficients to the reproductive pool. In +the CLM4.0, allocation of carbon to the reproductive pool was calculated +but merged with the stem pool. In the model, as allocation declines +during the grain fill stage of growth, increasing amounts of carbon and +nitrogen are available for grain development. diff --git a/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst b/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst new file mode 100644 index 0000000000..956e1aca1a --- /dev/null +++ b/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst @@ -0,0 +1,359 @@ +.. math:: 1 + +Transient Landcover Change +============================== + +CLM includes a treatment of mass and energy fluxes associated with +prescribed temporal change in land cover. Using an annual time series of +the spatial distribution of PFTs and wood harvest, CLM diagnoses the +change in area for PFTs at each model time step and then performs mass +and energy balance accounting necessary to represent the expansion and +contraction of PFT area. This implementation currently only pertains to +the case where all PFTs for a particular grid cell coexist on a single +soil/snow column. In this case, the only biogeophysical state variable +affected is canopy water (:math:`W_{can}` ). The biogeochemical impacts +of land use and land cover change are simulated through changes in CLM +carbon pools and fluxes as shown in Figure 21.1 and described further in +Chapter 13. Other implementations are possible, such as changing the +area of soil/snow columns or land unit area, however these require +additional consideration of conservation of mass and energy among the +soil/snow columns and land units which will be implemented in future +versions of CLM. + +Annual Transient Land Cover Data and Time Interpolation +------------------------------------------------------------ + +The changes in area over time associated with individual PFTs are +prescribed through a forcing dataset, referred to here as the *dynpft* +dataset. The *dynpft* dataset consists of an annual time series of +global grids, where each annual time slice describes the fractional area +occupied by all PFTs and the annual wood harvest within each grid cell. +Changes in area and wood harvest for each PFT within a grid cell at each +model time step are inferred from a time-interpolation of the area +information for the PFT from the two bracketing annual time slices in +the *dynpft* dataset. + +As a special case, when the time dimension of the *dynpft* dataset +starts at a later year than the current model time step, the first time +slice from the *dynpft* dataset is used to represent the current time +step PFT fractional area distributions. Similarly, when the time +dimension of the *dynpft* dataset stops at an earlier year than the +current model time step, the last time slice of the *dynpft* dataset is +used. Thus, the simulation will have invariant representations of PFT +distributions through time for the periods prior to and following the +time duration of the *dynpft* dataset, with transient PFT distributions +during the period covered by the *dynpft* dataset. + +The following equations capture this logic, where :math:`year_{cur}` is +the calendar year for the current timestep, +:math:`dynpft\_ year\eqref{GrindEQ__1_}` and +:math:`dynpft\_ year(nyears)`\ are the first and last calendar years in +the *dynpft* dataset, respectively, :math:`nyears` is the number of +years in the *dynpft* dataset, :math:`nt_{1}` and :math:`nt_{2}` +:math:`{}_{ }`\ are the two bracketing years used in the interpolation +algorithm, and :math:`n` is the index value for the +:math:`dynpft\_ year` array corresponding to +:math:`dynpft\_ year(n)=year_{cur}` : + +.. math:: + + \label{21.1)} + nt_{1} =\left\{\begin{array}{l} {1\qquad {\rm for}\qquad year_{cur} 0` and decreases for +:math:`\Delta w_{p} <0`. + +Mass and Energy Conservation +--------------------------------- + +Mass conservation is maintained across a PFT weight transition by +summing up all the water state variables to get the total vegetated land +unit water content before (:math:`W_{tot,1}` ) and after +(:math:`W_{tot,2}` ) new PFT weights are calculated. For example, +:math:`W_{tot,1}` is + +.. math:: + + \label{21.6)} + W_{tot,1} =W_{a} +W_{sno} +\sum _{i=1}^{N_{levgrnd} }\left(w_{liq,i} +w_{ice,i} \right) +\sum _{j=1}^{npft}\left(W_{can,j} wt_{j,1} \right) + +where :math:`W_{a}` is the aquifer water, :math:`W_{sno}` is the snow +water, :math:`w_{liq,i}` and :math:`w_{ice,i}` \ are the liquid and ice +soil water contents, :math:`W_{can,j}` \ is the canopy water content for +PFT :math:`j`, and :math:`wt_{j,1}` is the PFT weight for PFT +:math:`j`. For the situation where only PFT weights are changing and all +other land unit fractions are constant, any difference between +:math:`W_{tot,1}` and :math:`W_{tot,2}` \ can only be due to +differences in the total canopy water before and after the PFT weight +change. To ensure water conservation, the typically very small +difference between :math:`W_{tot,2}` \ and :math:`W_{tot,1}` is +subtracted from the grid cell runoff + +.. math:: + + \label{21.7)} + R_{liq} =R_{liq} +W_{tot,2} -W_{tot,1} . + +Total energy is unperturbed in this case and therefore an energy +conservation treatment is not required. As noted above, other +implementations are possible and will be desirable in the future, such +as changing the area of soil/snow columns or land unit area, for example +in a situation in which crops are implemented on a separate soil column. +These would require additional consideration of conservation of mass and +energy among the soil/snow columns and land units. + +Annual Transient Land Cover Dataset Development +---------------------------------------------------- + +This section describes the development of the d\ *ynpft* dataset. +Development of this dataset requires adapting for use with the CLM a +harmonized dataset of land cover change for the historical period and +for different representations of the scenario period. + +21.3.1 UNH Transient Land Use and Land Cover Change Dataset +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To coordinate the processing and consistency of land use and land cover +change data between the historical period (1850-2005) and the four IPCC +representative concentration pathways (RCPs) derived from integrated +assessment models (IAM), the University of New Hampshire +(stocktickerUNH) research group (Louise Chini, George Hurtt, Steve +Frolking; luh.unh.edu) produced a harmonized transient dataset for use +in climate change simulations. The historical component of the transient +land use and land cover change dataset is Version 1 of the Land-Use +History A product (LUHa.v1) covering the period 1850-2005. The RCP +transient land use and land cover change components (2005-2100) are +referred to as the Future Land-Use Harmonization A products. Version 1 +(LUHa.v1\_future.v1) is used for the AIM, MESSAGE, and MiniCAM IAMs; +Version 1.1 (LUHa.v1\_future.v1.1) is used for the IMAGE IAM. The land +cover information is provided at 0.5 degree grid resolution and includes +fractional grid cell coverage by crops, pasture, and primary and +secondary natural vegetation. + +The crop fraction of the grid cell represents the area of the grid cell +used to grow any type of crop. Similarly, pasture represents the +fraction of a grid cell used for grazing livestock. The remaining area +in a half degree grid cell is partitioned into primary and secondary +vegetation. Primary vegetation represents the fractional area of a grid +cell with vegetation undisturbed by human activities. Secondary +vegetation represents vegetated areas that have recovered from some +human disturbance; this could include re-vegetation of pasture and crop +areas as well as primary vegetation areas that have been logged. + +The stocktickerUNH dataset provides a transition matrix that describes +the annual fraction of land that is transformed from one category to +another (e.g. primary land to crop, pasture to crop, etc.; Hurtt et al. +2006). Included in these transitions is the conversion of secondary land +to secondary land, representing the logging on land recovering from an +earlier disturbance. These transitions provide information on all +changes in land cover through the sum of all transitions in a given +year. Harmonized prescriptions of CMIP5 wood harvest statistics also are +provided by (Hurtt et al. 2011) for the historical and RCP time series. +The wood harvest is prescribed spatially on the same 0.5 degree grid as +the land use class transitions for each year. + +To ensure consistency with the various land use classes wood harvest is +prescribed as both the area of land harvested and the amount of carbon +extracted in the grid cell for a particular year. To account for the +differences in standing amount of wood carbon as well as the differences +in harvest intensity associated with the different land units, the +harvest area and carbon amounts are prescribed for the five classes of: +PlaceNamePrimary PlaceTypeForest, PlaceNamePrimary PlaceTypeNon-Forest, +PlaceNameSecondary PlaceNameMature PlaceTypeForest, PlaceNameSecondary +PlaceNameYoung PlaceTypeForest, and PlaceNameplaceSecondary +PlaceTypeNon-Forest. + +21.3.2 Representing Land Use and Land Cover Change in CLM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CLM represents the land surface as a hierarchy of sub-grid types: +glacier; lake; wetland; urban; and vegetated land. The vegetated land is +further divided into a mosaic of PFTs. To represent the UNH transient +land use and land cover change dataset in CLM, the annual fractional +composition of crop, pasture, primary vegetation, and secondary +vegetation land units specified in the UNH dataset needs to be +faithfully represented with a corresponding PFT mosaic in CLM using the +methods described in Lawrence et al (2012). This method translated each +of the UNH land units into fractional PFT values based on current day +and potential vegetation CLM land surface parameters for that grid cell +and for that year, as shown in Figure 21.2. + +The methodology for creating the transient PFT dataset is based on four +steps which are applied across the time series. First, crop PFT +composition is directly specified from the crop land unit fractional +area. Second, pasture PFTs are assigned based on grass PFTs found in the +potential vegetation and current day CLM land surface parameters scaled +by the area of pasture. Third, potential vegetation PFTs are assigned to +the grid cell scaled by the fractional area of the primary land unit. +Last, current day non-crop and non-pasture PFTs are assigned to the grid +cell scaled by the fractional area of the secondary land unit. The +annual tree harvest values also are calculated from the harvest +information of the UNH dataset used in conjunction with transient tree +PFT values. Separate datasets representing the extent of water, wetland, +ice and urban land cover are used to compile the final land cover +present in each CLM grid cell. These additional non-vegetated land cover +fractions are held constant throughout the time series. All datasets are +resolved at the half degree grid resolution. + +21.3.3 Present Day PFT Dataset +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The present day dataset is based on the methodology of Lawrence and +Chase (2007) and uses a variety of satellite products to develop present +day PFT distributions with matching leaf area index values. The dataset +initially derives fractions of bare ground and tree cover from the +Moderate Resolution Imaging Spectroradiometer (MODIS) vegetation +continuous fields product (Hansen et al. 2003). To further distinguish +tree types, the tree fraction is divided into broadleaf/needleleaf and +evergreen/deciduous types based on the Advanced Very High Resolution +Radiometer (AVHRR) continuous fields tree cover (DeFries et al. 2000). +The remaining grid cell area is assumed to be herbaceous grasses and +shrubs, including crops. The area of crop is initially determined from +Ramankutty et al. (2008) circa 2000 global crop land areas, and the +remaining grass and shrub fractions are derived from the MODIS land +cover (Friedl et al. 2002). Further subdivisions of grass, shrub and +tree PFTs into tropical, temperate and boreal types were based on the +physiology and climate rules from Nemani and Running (1996), and for +C3/C4 photosynthetic pathways based on MODIS derived leaf area index +values and the mapping methods of Still et al. (2003). In contrast to +Lawrence and Chase (2007), the understory grasses of forested areas have +been replaced with trees for the dataset. Some advantages of this +dataset are that it reproduces the physical properties as observed by +the MODIS land surface data (e.g. grid cell albedo and leaf area index +values) while maintaining the multiple PFT representation. + +21.3.4 Potential PFT Distribution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Essential to any reconstruction of past vegetation distributions is the +need to know the potential vegetation that would be there prior to human +activities. Many researchers have worked to estimate potential +vegetation types at regional and global scales from remnant vegetation +and other field data or from bioclimatic models. The CLM potential PFT +distribution is derived from Ramankutty et al. (2008) at 5 arc-minute +resolution. However, this product is based on a biome type +classification system that is not directly compatible with the CLM PFT +distributions. + +The CLM potential vegetation is described by Lawrence and Chase (2010). +This reconstruction describes potential PFT distributions extrapolated +from the current day PFT composition of remnant natural biomes as mapped +by Ramankutty et al. (2008). The current day remnant natural PFT +parameters were taken from the Lawrence and Chase (2007) dataset with +the same forest understory changes as described above to ensure +consistency between the two datasets. The current day remnant natural +PFT biome compositions were spatially extrapolated to the potential +vegetation biome distributions provided by Ramankutty et al. (2008) +using inverse distance weighted methods. The resulting product is a CLM +PFT distribution that may have existed prior to human disturbance under +current day climate conditions. + +21.3.5 Transient Land Cover Change Dataset +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For each year from 1850 to 2005 and to 2100 for each of the four RCPs, +PFT distributions and wood harvest are adjusted based on the +stocktickerUNH dataset. Initially the grid cell is checked to adjust the +crop area based on the stocktickerUNH crop area. If the crop area +exceeds the available land area (i.e. the grid cell area minus the area +assigned to glacier, wetlands, lake and urban areas) then all the +available area is allocated to crops and no other PFTs are added. After +the crop area is assigned, any remaining area is considered available +for pasture. + +As the pasture data from the stocktickerUNH dataset represents grazing, +pasture areas are assigned in the present day based on the availability +of grasses (C3, C4 and boreal C3 PFTs) and shrubs relative to the bare +soil fraction. If the grazing area exceeds the total vegetated area from +both the potential and current day PFT data, then the grazed area is +limited to the larger of the potential or current day vegetated area. +This is done to prevent representing sparsely vegetated grazing areas as +100% vegetated pastures. Once the grazing area is less than or equal to +the total vegetated area, then grazing areas are assigned to the C3 and +C4 grass areas based on their potential vegetation and current day +fractions. In areas where the grazing area cannot be met through the +current day or potential vegetation grass fraction alone, the current +day tree PFTs are converted to grass PFTs, with the remaining shrub PFTs +included as being grazed. + +Once crop and pasture areas are assigned to a grid cell, the remaining +area is assigned to primary and secondary natural vegetation. Primary +vegetation is assumed to be undisturbed and reflects the potential +vegetation PFT distributions. In the secondary region, the PFT +distributions are based on the current day non-crop and non-pasture PFTs +in the grid cell. This process ensures that the PFT distributions are +kept consistent with the original current day and potential vegetation +CLM parameters, while remaining faithful to the stocktickerUNH assigned +areas. + +21.3.6 Forest Harvest Dataset Changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Discussions following the initial analysis of CCSM4 land cover change +experiments found there were very high wood harvest areas compared to +wood harvest carbon in the RCP 6.0 and RCP 8.5 time series. The high +wood harvest areas were traced to using gridded spatially explicit wood +harvest targets from the MESSAGE and AIM groups for these two time +series, rather than using regional targets with spatial downscaling in +GLM as done with the other three time periods. As a result of these +discussions new amended wood harvest targets were generated with +regional targets through GLM for the RCP 6.0 and RCP 8.5 time series as +described in Lawrence et al. (2012). + +Figure 21.1. Schematic of land cover change impacts on CLM carbon pools +and fluxes. + +|image| + +Figure 21.2. Schematic of translation of annual UNH land units to CLM4 +plant functional types. + +|image| + +.. |image| image:: image1 +.. |image| image:: image2 diff --git a/doc/source/tech_note/CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst b/doc/source/tech_note/CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst new file mode 100644 index 0000000000..b90f8b4a16 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst @@ -0,0 +1,155 @@ +.. math:: 1 + +Dynamic Global Vegetation Model +=================================== + +In CLM the user may choose to run the CN model as a dgvm (dynamic global +vegetation model) (CNDV). Note that CN must be active to run the dgvm in +CLM. In this section, a general description of the dgvm processes and +how they integrate with CN are provided. Further details are available +in the CLM3DGVM Technical Note (Levis et al. 2004). The focus here is on +the differences relative to the corresponding processes in the CLM3DGVM. + +As with the CLM3DGVM, CNDV can simulate biogeographical changes only for +natural vegetation. Although the vegetated land unit may be separated +into naturally vegetated and human managed land units to permit a +coexistence of natural and human managed vegetation, CNDV only works if +the human managed land units are fixed. CLM’s transient land cover and +land use change capability (see Chapter 21), which permits transitions +between natural and human managed plant functional types (PFTs), is +incompatible with the CNDV option at this time. + +CNDV was implemented by introducing CLM3DGVM code to the hourly CN +framework only to the extent necessary to simulate annual biogeography +updates. This includes the annual processes of light competition, +establishment, and survival [see sections 2.7 and 2.10, Levis et al. +(2004)] as they pertain to the calculations of PFT cover (FPC) and +population (P) but not processes related to carbon pools, leaf area +index (LAI), or canopy height. In CNDV we added complexity to the gap +mortality calculation with annual heat stress and growth efficiency +considerations from the corresponding CLM3DGVM algorithm [section 2.8, +Levis et al. (2004)]. All other ecosystem processes (allocation, +phenology, fire, etc.) are handled by CN modules. Unlike in the +CLM3DGVM, in CNDV, annual biogeography updates are interpolated to +hourly intervals. + +Establishment and survival +------------------------------- + +The PFT distribution in the vegetated land unit is typically prescribed +in CLM (see section 2.1.2) except for the case when CNDV is active. In +CNDV the model begins with no PFT information per grid cell and +evaluates whether or not a PFT may establish or survive according to the +PFT’s bioclimatic limits (Table 22.1). Shrub PFTs are treated as trees +at establishment. + +CNDV omits the CLM3DGVM’s annual introduction of saplings when a PFT can +establish. The CLM3DGVM merged sapling carbon pools with a PFT’s +existing carbon. The resultant leaf carbon (annual maximum value) would +update the FPC, i.e. the foliar projective cover or fraction of the +vegetated land unit occupied by the PFT [section 2.10, Levis et al. +(2004)]. Instead, CNDV updates the FPC using the PFT’s annual maximum +leaf carbon without an addition from saplings. For newly established +PFTs, CNDV assigns seed leaf carbon equal to 1 g C m\ :math:`{}^{-2}` of +land unit area and seed FPC equal to 0.05 for grasses and 0.000844 for +trees (values determined from CLM3DGVM simulations). The addition of +establishing individuals to *P*, a PFT’s population, is handled as in +the CLM3DGVM. + +*FPC* changes annually as in the CLM3DGVM but now is interpolated to an +hourly increment using the algorithms designed to conserve energy and +mass in the CLM’s dynamic land use option. + +Light competition +---------------------- + +In CNDV’s order of annual processes, light competition is invoked before +establishment and survival. However, light competition does not affect a +simulation starting from bare ground until the vegetation fills the land +unit (a few years at least). + +Light competition starts with a calculation updating *FPC*. For +reference, this update was included at the end of allocation in the +CLM3DGVM [section 2.6, Levis et al. (2004)]. + +Due to their height advantage, trees will cover up to 95% of the land +unit when their productivity permits, as in the CLM3DGVM, regardless of +grass and shrub productivity. Grasses get second priority, as in the +CLM3DGVM, even with shrubs included now. Shrubs, then, have access to +the remaining space and follow the tree algorithm for self thinning +[section 2.7, Levis et al. (2004)]. As a result, trees typically +dominate in the most productive regions, grasses in less productive +regions, and shrubs in the least productive non-desert regions (Zeng et +al. 2008). + +CN processes modified for the CNDV coupling +------------------------------------------------ + +Gap mortality and mortality from fire: Constant annual mortality rate of +0.02 is changed for trees and shrubs to an annual rate calculated as in +the CLM3DGVM accounting for background and stress mortality [section +2.8, Levis et al. (2004)]. The CN module converts the annual rate to +hourly. + +The CLM3DGVM used the concepts of average plant individual and PFT +population, *P*. CNDV retains these concepts in the light competition, +establishment, and survival calculations. In CNDV we account for the +individuals removed hourly from *P* in response to CN’s fire and gap +mortality, while the carbon pools per individual and FPC remain +constant. Ultimately, *P* updates should only affect the annual +processes of light competition, establishment, and survival, so the *P* +update may be moved to the end of the year in a future version of CNDV. + +Vegetation Structure Update: CN stocking is a constant, while in CNDV +stocking changes as P and FPC change. This affects the top-of-canopy +height calculation. CN specific leaf area and stem diameter calculations +are kept, while the height calculation is replaced with the CLM3DGVM’s +[section 2.6, Levis et al. (2004)]. CN stem area index (SAI) is kept. + +Allocation: CN calculates a PFT’s fraction of currently allocated carbon +relative to the total allocation instead of obtaining a constant value +from CLM’s PFT-physiology file. In CNDV, we returned to the constant +values in the old PFT-physiology file to get a reasonable simulation of +PFTs. For CNDV to use the calculated fraction, we will need to change +the algorithm for PFTs in early stages of growth. + +Table 22.1. Plant functional type (PFT) biogeography rules with respect +to climate. + +Adapted from Table 1 of Levis et al. (2004) to include shrub PFTs. +:math:`T_{c,\min }` , coldest minimum monthly air temperature for +survival of previously established PFTs; :math:`T_{c,\max }` , warmest +minimum monthly air temperature for establishment of new PFTs; +:math:`GDD_{\min }` , minimum annual growing degree-days above +5\ :math:`{}^\circ`\ C for establishment of new PFTs. Levis et al. +(2004) include an explanation of these variables and their use. + ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| | Survival | | | | ++=============================================+==============================================+==============================================+=========================+========+ +| | *T*\ :math:`{}_{c,min}` (:math:`\circ`\ C) | *T*\ :math:`{}_{c,max}` (:math:`\circ`\ C) | GDD\ :math:`{}_{min}` | | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Tropical broadleaf evergreen tree (BET) | | 15.5 | No limit | 0 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Tropical broadleaf deciduous tree (BDT) | | 15.5 | No limit | 0 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Temperate needleleaf evergreen tree (NET) | | -2.0 | 22.0 | 900 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Temperate broadleaf evergreen tree (BET) | | 3.0 | 18.8 | 1200 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Temperate broadleaf deciduous tree (BDT) | | -17.0 | 15.5 | 1200 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Boreal needleleaf evergreen tree (NET) | | -32.5 | -2.0 | 600 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Boreal deciduous tree | | No limit | -2.0 | 350 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Temperate broadleaf deciduous shrub (BDS) | | -17.0 | No limit | 1200 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| Boreal broadleaf deciduous shrub (BDS) | | No limit | -2.0 | 350 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| C\ :math:`{}_{4}` | | 15.5 | No limit | 0 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| C\ :math:`{}_{3}` | | -17.0 | 15.5 | 0 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ +| C\ :math:`{}_{3}` arctic | | No limit | -17.0 | 0 | ++---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ diff --git a/doc/source/tech_note/CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst b/doc/source/tech_note/CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst new file mode 100644 index 0000000000..d19c09ca0b --- /dev/null +++ b/doc/source/tech_note/CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst @@ -0,0 +1,66 @@ +.. math:: 2 + +.. math:: 1 + +Biogenic Volatile Organic Compounds (BVOCs) +=============================================== + +This chapter briefly describes the biogenic volatile organic compound +(BVOC) emissions model implemented in CLM. The CLM3 version (Levis et +al. 2003; Oleson et al. 2004) was based on Guenther et al. (1995). Heald +et al. (2008) updated this scheme in CLM4 based on Guenther et al. +(2006). The current version in CLM4.5 is based on MEGAN2.1 discussed in +detail in Guenther et al. (2012). This update of MEGAN incorporates four +main features: expansion to 147 chemical compounds the treatment of the +light-dependent fraction (LDF) for each compound inclusion of the +inhibition of isoprene emission by atmospheric CO\ :math:`{}_{2}` and +emission factors mapped to the specific PFTs of the CLM. + +MEGAN2.1 now describes the emissions of speciated monoterpenes, +sesquiterpenes, oxygenated VOC as well as isoprene. A flexible scheme +has been implemented in the CLM to specify a subset of emissions. This +allows for additional flexibility in grouping chemical compounds to form +the lumped species frequently used in atmospheric chemistry. The mapping +or grouping are therefore defined through a namelist parameter in +drv\_flds\_in, e.g. megan\_specifier = ’ISOP = isoprene’, ’BIGALK = +pentane + hexane + heptane + tricyclene’. + +Terrestrial BVOC emissions from plants to the atmosphere are expressed +as a flux, ** :math:`F_{i}` (:math:`\mu` \ g C m\ :math:`{}^{-2}` +ground area h\ :math:`{}^{-1}`), for emission of chemical compound +:math:`i` + +.. math:: + + \label{ZEqnNum964222} + F_{i} =\gamma _{i} \rho \sum _{j}\varepsilon _{i,j} \left(wt\right)_{j} + +where :math:`\gamma _{i}` is the emission activity factor accounting +for responses to meteorological and phenological conditions, +:math:`\rho` is the canopy loss and production factor also known as +escape efficiency (set to 1), and :math:`\varepsilon _{i,\, j}` +(:math:`\mu` \ g C m\ :math:`{}^{-2}` ground area h\ :math:`{}^{-1}`) is +the emission factor at standard conditions of light, temperature, and +leaf area for plant functional type *j* with fractional coverage +:math:`\left(wt\right)_{j}` (Guenther et al. 2012). The emission +activity factor :math:`\gamma _{i}` depends on plant functional type, +temperature, LAI, leaf age, and soil moisture (Guenther et al. 2012). +For isoprene only, the effect of CO\ :math:`{}_{2}` inhibition is now +included as described by Heald et al. (2009). Previously, only isoprene +was treated as a light-dependent emission. In MEGAN2.1, each chemical +compound is assigned a LDF (ranging from 1.0 for isoprene to 0.2 for +some monoterpenes, VOCs and acetone). The activity factor for the light +response of emissions is therefore estimated as: + +.. math:: + + \label{23.2)} + \gamma _{P,\, i} =\left(1-LDF_{i} \right)+\gamma _{P\_ LDF} LDF_{i} + +where the LDF activity factor (:math:`\gamma _{P\_ LDF}` ) is specified +as a function of PAR as in previous versions of MEGAN. + +The values for each emission factor :math:`\varepsilon _{i,\, j}` are +now available for each of the 15 plant functional types in the CLM and +each chemical compound. This information is distributed through an +external file, allowing for more frequent and easier updates. diff --git a/doc/source/tech_note/CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst b/doc/source/tech_note/CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst new file mode 100644 index 0000000000..ae371ca838 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst @@ -0,0 +1,212 @@ +.. math:: 1 + +.. math:: 1 + +Dust Model +============== + +Atmospheric dust is mobilized from the land by wind in the CLM. The most +important factors determining soil erodibility and dust emission include +the wind friction speed, the vegetation cover, and the soil moisture. +The CLM dust mobilization scheme (Mahowald et al. ** 2006) accounts for +these factors based on the DEAD (Dust Entrainment and Deposition) model +of Zender et al. (2003). Please refer to the Zender et al. ** (2003) +article for additional information regarding the equations presented in +this section. + +The total vertical mass flux of dust, :math:`F_{j}` (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), from the ground into transport +bin :math:`j` is given by + +.. math:: + + \label{ZEqnNum146272} + F_{j} =TSf_{m} \alpha Q_{s} \sum _{i=1}^{I}M_{i,j} + +where :math:`T` is a global factor that compensates for the DEAD model’s +sensitivity to horizontal and temporal resolution and equals 5 x +10\ :math:`{}^{-4}` in the CLM instead of 7 x 10\ :math:`{}^{-4}` in +Zender et al. (2003). :math:`S` is the source erodibility factor set to +1 in the CLM and serves as a place holder at this time. + +The grid cell fraction of exposed bare soil suitable for dust +mobilization :math:`f_{m}` is given by + +.. math:: + + \label{24.2)} + f_{m} =\left(1-f_{lake} -f_{wetl} \right)\left(1-f_{sno} \right)\left(1-f_{v} \right)\frac{w_{liq,1} }{w_{liq,1} +w_{ice,1} } + +where ** :math:`f_{lake}` and ** :math:`f_{wetl}` and :math:`f_{sno}` +are the CLM grid cell fractions of lake and wetland (section 2.2.3) and +snow cover (section 7.2.1), all ranging from zero to one. Not mentioned +by Zender et al. (2003), :math:`w_{liq,\, 1}` and +:math:`{}_{w_{ice,\, 1} }` are the CLM top soil layer liquid water and +ice contents (mm) entered as a ratio expressing the decreasing ability +of dust to mobilize from increasingly frozen soil. The grid cell +fraction of vegetation cover,\ :math:`{}_{f_{v} }`, is defined as + +.. math:: + + \label{ZEqnNum242183} + 0\le f_{v} =\frac{L+S}{\left(L+S\right)_{t} } \le 1{\rm \; \; \; \; where\; }\left(L+S\right)_{t} =0.3{\rm \; m}^{2} {\rm m}^{-2} + +where equation applies only for dust mobilization and is not related to +the plant functional type fractions prescribed from the CLM input data +or simulated by the CLM dynamic vegetation model (Chapter 22). :math:`L` +and :math:`S` are the CLM leaf and stem area index values +(m:math:`{}^{2}` m\ :math:`{}^{-2}`) averaged at the land unit level so +as to include all the pfts and the bare ground present in a vegetated +land unit. ** :math:`L` and :math:`S` may be prescribed from the CLM +input data (section 2.1.4) or simulated by the CLM biogeochemistry model +(Chapter 13). + +The sandblasting mass efficiency :math:`\alpha` (m:math:`{}^{-1}`) is +calculated as + +.. math:: + + \label{24.4)} + \alpha =100e^{\left(13.4M_{clay} -6.0\right)\ln 10} {\rm \; \; }\left\{\begin{array}{l} {M_{clay} =\% clay\times 0.01{\rm \; \; \; 0}\le \% clay\le 20} \\ {M_{clay} =20\times 0.01{\rm \; \; \; \; \; \; \; \; 20<\% }clay\le 100} \end{array}\right. + +where :math:`M_{clay}` \ *:math:`{}_{ }`*\ is the mass fraction of clay +particles in the soil and %clay is determined from the surface dataset +(section 2.2.3). :math:`M_{clay} =0` corresponds to sand and +:math:`M_{clay} =0.2` to sandy loam. + +:math:`Q_{s}` is the total horizontally saltating mass flux (kg +m\ :math:`{}^{-1}` s\ :math:`{}^{-1}`) of “large†particles (Table +24.1), also referred to as the vertically integrated streamwise mass +flux + +.. math:: + + \label{ZEqnNum832592} + Q_{s} =\left\{\begin{array}{l} {\frac{c_{s} \rho _{atm} u_{*s}^{3} }{g} \left(1-\frac{u_{*t} }{u_{*s} } \right)\left(1+\frac{u_{*t} }{u_{*s} } \right)^{2} {\rm \; }\qquad {\rm for\; }u_{*t} w_{t} } \end{array}\right. + +where + +.. math:: + + \label{24.8)} + w_{t} =a\left(0.17M_{clay} +0.14M_{clay}^{2} \right){\rm \; \; \; \; \; \; 0}\le M_{clay} =\% clay\times 0.01\le 1 + +and + +.. math:: + + \label{24.9)} + w=\frac{\theta _{1} \rho _{liq} }{\rho _{d,1} } + +where :math:`a=M_{clay}^{-1}` for tuning purposes, +:math:`\theta _{1}` is the volumetric soil moisture in the top soil +layer (m:math:`{}^{3 }`\ m\ :math:`{}^{-3}`) (section 7.4), +:math:`\rho _{liq}` is the density of liquid water (kg +m\ :math:`{}^{-3}`) (Table 2.6), and :math:`\rho _{d,\, 1}` is the bulk +density of soil in the top soil layer (kg m\ :math:`{}^{-3}`) defined as +in section 6.3 rather than as in Zender et al. ** (2003). +:math:`Re_{*t}^{f}` from equation is the threshold friction Reynolds +factor + +.. math:: + + \label{24.10)} + Re_{*t}^{f} =\left\{\begin{array}{l} {\frac{0.1291^{2} }{-1+1.928Re_{*t} } {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; 0.03}\le Re_{*t} \le 10} \\ {0.12^{2} \left(1-0.0858e^{-0.0617(Re_{*t} -10)} \right)^{2} {\rm \; for\; }Re_{*t} >10} \end{array}\right. + +and :math:`Re_{*t}` is the threshold friction Reynolds number +approximation for optimally sized particles + +.. math:: + + \label{24.11)} + Re_{*t} =0.38+1331\left(100D_{osp} \right)^{1.56} + +In equation , :math:`u_{*s}` ** is defined as the wind friction speed +(m s\ :math:`{}^{-1}`) accounting for the Owen effect (Owen 1964) + +.. math:: + + \label{24.12)} + u_{*s} =\left\{\begin{array}{l} {u_{*} {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }U_{10} ` 1.0 would indicate a preference for the +heavier isotope. Currently, in all cases where Eq. is used to calculate +a :math:`{}^{13}`\ C flux, *f\ :math:`{}_{frac}`* is set to 1.0. + +For :math:`{}^{1}`\ :math:`{}^{4}`\ C, no fractionation is used in +either the initial photosynthetic step, nor in subsequent fluxes from +upstream to downstream pools; as discussed below, this is because +observations of :math:`{}^{1}`\ :math:`{}^{4}`\ C are typically +described in units that implicitly correct out the fractionation of +:math:`{}^{1}`\ :math:`{}^{4}`\ C by referencing them to +:math:`{}^{1}`\ :math:`{}^{3}`\ C ratios. + +Isotope Symbols, Units, and Reference Standards +---------------------------------------------------- + +Carbon has two primary stable isotopes, :math:`{}^{12}`\ C and +:math:`{}^{13}`\ C. :math:`{}^{12}`\ C is the most abundant, comprising +about 99% of all carbon. The isotope ratio of a compound, +*R\ :math:`{}_{A}`*, is the mass ratio of the rare isotope to the +abundant isotope + +.. math:: + + \label{25.2)} + R_{A} =\frac{{}^{13} C_{A} }{{}^{12} C_{A} } . + +Carbon isotope ratios are often expressed using delta notation, +:math:`\deltaup`. The :math:`\deltaup`\ :math:`{}^{13}`\ C value of a +compound A, :math:`\deltaup`\ :math:`{}^{13}`\ C\ :math:`{}_{A}`, is the +difference between the isotope ratio of the compound, +*R\ :math:`{}_{A}`*, and that of the Pee Dee Belemnite standard, +*R\ :math:`{}_{PDB}`*, in parts per thousand + +.. math:: + + \label{25.3)} + \delta ^{13} C_{A} =\left(\frac{R_{A} }{R_{PDB} } -1\right)\times 1000 + +where *R\ :math:`{}_{PDB}`* = 0.0112372, and units of :math:`\deltaup` +are per mil (‰). + +Isotopic fractionation can be expressed in several ways. One expression +of the fractionation factor is with alpha (:math:`\alphaup`) notation. +For example, the equilibrium fractionation between two reservoirs A and +B can be written as: + +.. math:: + + \label{25.4)} + \alpha _{A-B} =\frac{R_{A} }{R_{B} } =\frac{\delta _{A} +1000}{\delta _{B} +1000} . + +This can also be expressed using epsilon notation +(:math:`\varepsilonup`), where + +.. math:: + + \label{25.5)} + \alpha _{A-B} =\frac{\varepsilon _{A-B} }{1000} +1 + +In other words, if :math:`{\varepsilon }_{A-B}=4.4\mathrm{\textrm{‰}}`, +then :math:`\alphaup`\ :math:`{}_{A-B}`\ =1.0044. + +In addition to the stable isotopes :math:`{}^{1}`\ :math:`{}^{2}`\ C and +:math:`{}^{1}`\ :math:`{}^{3}`\ C, the unstable isotope +:math:`{}^{1}`\ :math:`{}^{4}`\ C is included in CLM. +:math:`{}^{1}`\ :math:`{}^{4}`\ C can also be described using the delta +notation: + +.. math:: + + \label{25.6)} + \delta ^{14} C=\left(\frac{A_{s} }{A_{abs} } -1\right)\times 1000 + +However, observations of :math:`{}^{1}`\ :math:`{}^{4}`\ C are typically +fractionation-corrected using the following notation: + +.. math:: + + \label{25.7)} + \Delta {}^{14} C=1000\times \left(\left(1+\frac{\delta {}^{14} C}{1000} \right)\frac{0.975^{2} }{\left(1+\frac{\delta {}^{13} C}{1000} \right)^{2} } -1\right) + +where :math:`\deltaup`\ :math:`{}^{14}`\ C is the measured isotopic +fraction and :math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C corrects for +mass-dependent isotopic fractionation processes (assumed to be 0.975 for +fractionation of :math:`{}^{13}`\ C by photosynthesis). CLM assumes a +background preindustrial atmospheric :math:`{}^{14}`\ C /C ratio of +10\ :math:`{}^{-12}`, which is used for A\ :math:`{}_{abs}`. For the +reference standard A\ :math:`{}_{abs}`, which is a plant tissue and has +a :math:`\deltaup`\ :math:`{}^{13}`\ C value is :math:`\mathrm{-}`\ 25 ‰ +due to photosynthetic discrimination, +:math:`\deltaup`\ :math:`{}^{14}`\ C = +:math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C. For CLM, in order to use +the :math:`{}^{14}`\ C model independently of the :math:`{}^{13}`\ C +model, for the :math:`{}^{14}`\ C calculations, this fractionation is +set to zero, such that the 0.975 term becomes 1, the +:math:`\deltaup`\ :math:`{}^{13}`\ C term (for the calculation of +:math:`\deltaup`\ :math:`{}^{14}`\ C only) becomes 0, and thus +:math:`\deltaup`\ :math:`{}^{14}`\ C = +:math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C. + +Carbon Isotope Discrimination During Photosynthesis +-------------------------------------------------------- + +Photosynthesis is modeled in CLM as a two-step process: diffusion of +CO\ :math:`{}_{2}` into the stomatal cavity, followed by enzymatic +fixation (Chapter 8). Each step is associated with a kinetic isotope +effect. The kinetic isotope effect during diffusion of +CO\ :math:`{}_{2}` through the stomatal opening is 4.4‰. The kinetic +isotope effect during fixation of CO\ :math:`{}_{2}` with Rubisco is +:math:`\sim`\ 30‰; however, since about 5-10% of carbon in C3 plants +reacts with phosphoenolpyruvate carboxylase (PEPC) (Melzer and O’Leary, +1987), the net kinetic isotope effect during fixation is +:math:`\sim`\ 27‰ for C3 plants. In C4 plant photosynthesis, only the +diffusion effect is important. The fractionation factor equations for C3 +and C4 plants are given below: + +For C4 plants, + +.. math:: + + \label{25.8)} + \alpha _{psn} =1+\frac{4.4}{1000} + +For C3 plants, + +.. math:: + + \label{25.9)} + \alpha _{psn} =1+\frac{4.4+22.6\frac{c_{i}^{*} }{pCO_{2} } }{1000} + +where :math:`{\alpha }_{psn}` is the fractionation factor, and +:math:`c^*_i` and pCO\ :math:`{}_{2}` are the revised intracellular and +atmospheric CO\ :math:`{}_{2}` partial pressure, respectively. + +As can be seen from the above equation, kinetic isotope effect during +fixation of CO\ :math:`{}_{2}` is dependent on the intracellular +CO\ :math:`{}_{2}` concentration, which in turn depends on the net +carbon assimilation. That is calculated during the photosynthesis +calculation as follows: + +.. math:: + + \label{25.10)} + c_{i} =pCO_{2} -a_{n} p\frac{\left(1.4g_{s} \right)+\left(1.6g_{b} \right)}{g_{b} g_{s} } + +and + +.. math:: + + \label{25.11)} + c_{i}^{*} =pCO_{2} -a_{n} \left(1-d\right)p\frac{\left(1.4g_{s} \right)+\left(1.6g_{b} \right)}{g_{b} g_{s} } + +where :math:`a_n` is net carbon assimilation during photosynthesis, +:math:`d` is downscaling factor due to nitrogen limitation, :math:`p` is +atmospheric pressure, :math:`g_b` is leaf boundary layer conductance, +and :math:`g_s` is leaf stomatal conductance. + +The fractionation factor :math:`{\alpha }_{psn}` and net assimilation +:math:`a_n` are calculated during the radiation time-step in +CanopyFluxesMod.F90, whereas the downscaling factor :math:`d` is not +calculated until after the nitrogen limitation is computed in +CNAllocationMod.F90. That results in a difference between the actual +photosynthesis, which is downscaled by :math:`d`, and the potential +photosynthesis. In order to overcome this mismatch, downscaling due to +nitrogen limitation is factored in the calculation of the kinetic +isotope effect during fixation by defining a downscaled version of +intracellular CO\ :math:`{}_{2}` (:math:`c^*_i`), as a first order +approximation. However, since nitrogen down-regulation is calculated +after the photosynthesis calculation, down-regulation coefficient +calculated in the previous time step needs to be used. + +Isotopic fractionation code is compatible with multi-layered canopy +parameterization; i.e., it is possible to calculate varying +discrimination rates for each layer of a multi-layered canopy. However, +as with the rest of the photosynthesis model, the number of canopy +layers is currently set to one by default. + +:math:`{}^{14}`\ C radioactive decay and historical atmospheric :math:`{}^{14}`\ C concentrations +------------------------------------------------------------------------------------------------------ + +In the preindustrial biosphere, radioactive decay of :math:`{}^{14}`\ C +in carbon pools allows dating of long-term age since photosynthetic +uptake; while over the 20\ :math:`{}^{th}` century, radiocarbon in the +atmosphere was first diluted by radiocarbon-free fossil fuels and then +enriched by aboveground thermonuclear testing to approximately double +its long-term mean concentration. CLM includes both of these processes +to allow comparison of carbon that may vary on multiple timescales with +observed values. + +For radioactive decay, at each timestep all :math:`{}^{14}`\ C pools are +reduced at a rate of –log/:math:`\tau`, where :math:`\tau` is the +half-life (Libby half-life value of 5568 years). In order to rapidly +equilibrate the long-lived pools during accelerated decomposition +spinup, the radioactive decay of the accelerated pools is also +accelerated by the same degree as the decomposition, such that the +:math:`{}^{14}`\ C value of these pools is in equilibrium when taken out +of the spinup mode. + +For variation of atmospheric :math:`{}^{14}`\ C over the historical +period, :math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C values can be set to +either fixed concentration (:math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C += 0‰) or time-varying concentrations read in from a file. A default file +is provided that is based on a spline fit through several observational +datasets spanning the 20\ :math:`{}^{th}` century: (Levin and Kromer, +2004; Manning and Melhuish, 1994; Nydal and Lövseth, 1996; Turnbull et +al. 2007). This is shown in Figure 25.1. + +Figure 25.1. Atmospheric :math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C +used to drive :math:`{}^{14}`\ C model over the historical period. + +|image| + +.. |image| image:: image1 diff --git a/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst b/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst new file mode 100644 index 0000000000..9bf3495e0c --- /dev/null +++ b/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst @@ -0,0 +1,210 @@ +.. math:: 1 + +Offline Mode +================ + +In offline mode (uncoupled to an atmospheric model), the atmospheric +forcing required by CLM (Table 2.3) is supplied by observed datasets. +The standard forcing provided with the model is a 110-year (1901-2010) +dataset (CRUNCEP; Viovy 2011) that is a combination of two existing +datasets; the CRU TS3.2 0.5\ :math:`{}^\circ` X 0.5\ :math:`{}^\circ` +monthly data covering the period 1901 to 2002 (Mitchell and Jones 2005) +and the NCEP reanalysis 2.5\ :math:`{}^\circ` X 2.5\ :math:`{}^\circ` +6-hourly data covering the period 1948 to 2010. The CRUNCEP dataset has +been used to force CLM for studies of vegetation growth, +evapotranspiration, and gross primary production (Mao et al. 2012, Mao +et al. 2013, Shi et al. 2013) and for the TRENDY (trends in net +land-atmosphere carbon exchange over the period 1980-2010) project (Piao +et al. 2012). Version 4 is used here (Viovy 2011). Alternative forcing +datasets can also be used (e.g., the Qian et al. (2006) dataset used for +previous versions of CLM is still available). + +Here, the CRUNCEP dataset, which does not include data over oceans, +lakes, and Antarctica is modified. This missing data is filled with Qian +et al. (2006) data from 1948 that is interpolated by the data atmosphere +model to the 0.5\ :math:`{}^\circ` CRUNCEP grid. This allows the model +to be run over Antarctica and ensures data is available along coastlines +regardless of model resolution. + +The forcing data is ingested into a data atmosphere model in three +“streamsâ€; precipitation (:math:`P`) (mm s\ :math:`{}^{-1}`), solar +radiation (:math:`S_{atm}` ) (W m\ :math:`{}^{-2}`), and four other +fields [atmospheric pressure :math:`P_{atm}` (Pa), atmospheric specific +humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`), atmospheric +temperature :math:`T_{atm}` (K), and atmospheric wind :math:`W_{atm}` +(m s\ :math:`{}^{-1}`)]. These are separate streams because they are +handled differently according to the type of field. In the CRUNCEP +dataset, the precipitation stream is provided at six hour intervals and +the data atmosphere model prescribes the same precipitation rate for +each model time step within the six hour period. The four fields that +are grouped together in another stream (pressure, humidity, temperature, +and wind) are provided at six hour intervals and the data atmosphere +model linearly interpolates these fields to the time step of the model. + +The total solar radiation is also provided at six hour intervals. The +data is fit to the model time step using a diurnal function that depends +on the cosine of the solar zenith angle :math:`\mu` to provide a +smoother diurnal cycle of solar radiation and to ensure that all of the +solar radiation supplied by the six-hourly forcing data is actually +used. The solar radiation at model time step :math:`t_{M}` is + +.. math:: + + \label{ZEqnNum160435} + \begin{array}{l} {S_{atm} \left(t_{M} \right)=\frac{\frac{\Delta t_{FD} }{\Delta t_{M} } S_{atm} \left(t_{FD} \right)\mu \left(t_{M} \right)}{\sum _{i=1}^{\frac{\Delta t_{FD} }{\Delta t_{M} } }\mu \left(t_{M_{i} } \right) } \qquad {\rm for\; }\mu \left(t_{M} \right)>0.001} \\ {S_{atm} \left(t_{M} \right)=0\qquad {\rm for\; }\mu \left(t_{M} \right)\le 0.001} \end{array} + +where :math:`\Delta t_{FD}` is the time step of the forcing data (6 +hours :math:`\times` 3600 seconds hour\ :math:`{}^{-1}` = 21600 +seconds), :math:`\Delta t_{M}` is the model time step (seconds), +:math:`S_{atm} \left(t_{FD} \right)` is the six-hourly solar radiation +from the forcing data (W m\ :math:`{}^{-2}`), and +:math:`\mu \left(t_{M} \right)` is the cosine of the solar zenith angle +at model time step :math:`t_{M}` (section 3.3). The term in the +denominator of equation is the sum of the cosine of the solar zenith +angle for each model time step falling within the six hour period. For +numerical purposes, :math:`\mu \left(t_{M_{i} } \right)\ge 0.001`. + +The total incident solar radiation :math:`S_{atm}` at the model time +step :math:`t_{M}` is then split into near-infrared and visible +radiation and partitioned into direct and diffuse according to factors +derived from one year’s worth of hourly CAM output from CAM version +cam3\_5\_55 as + +.. math:: + + \label{26.2)} + S_{atm} \, \downarrow _{vis}^{\mu } =R_{vis} \left(\alpha S_{atm} \right) + +.. math:: + + \label{26.3)} + S_{atm} \, \downarrow _{nir}^{\mu } =R_{nir} \left[\left(1-\alpha \right)S_{atm} \right] + +.. math:: + + \label{26.4)} + S_{atm} \, \downarrow _{vis} =\left(1-R_{vis} \right)\left(\alpha S_{atm} \right) + +.. math:: + + \label{26.5)} + S_{atm} \, \downarrow _{nir} =\left(1-R_{nir} \right)\left[\left(1-\alpha \right)S_{atm} \right]. + +where :math:`\alpha` , the ratio of visible to total incident solar +radiation, is assumed to be + +.. math:: + + \label{26.6)} + \alpha =\frac{S_{atm} \, \downarrow _{vis}^{\mu } +S_{atm} \, \downarrow _{vis}^{} }{S_{atm} } =0.5. + +The ratio of direct to total incident radiation in the visible +:math:`R_{vis}` is + +.. math:: + + \label{26.7)} + R_{vis} =a_{0} +a_{1} \times \alpha S_{atm} +a_{2} \times \left(\alpha S_{atm} \right)^{2} +a_{3} \times \left(\alpha S_{atm} \right)^{3} \qquad 0.01\le R_{vis} \le 0.99 + +and in the near-infrared :math:`R_{nir}` is + +.. math:: + + \label{26.8)} + R_{nir} =b_{0} +b_{1} \times \left(1-\alpha \right)S_{atm} +b_{2} \times \left[\left(1-\alpha \right)S_{atm} \right]^{2} +b_{3} \times \left[\left(1-\alpha \right)S_{atm} \right]^{3} \qquad 0.01\le R_{nir} \le 0.99 + +where +:math:`a_{0} =0.17639,\, a_{1} =0.00380,\, a_{2} =-9.0039\times 10^{-6} ,\, a_{3} =8.1351\times 10^{-9}` +and +:math:`b_{0} =0.29548,b_{1} =0.00504,b_{2} =-1.4957\times 10^{-5} ,b_{3} =1.4881\times 10^{-8}` +are coefficients from polynomial fits to the placeCAM data. + +The additional atmospheric forcing variables required by Table 2.3 are +derived as follows. The atmospheric reference height :math:`z'_{atm}` +(m) is set to 30 m. The directional wind components are derived as +:math:`u_{atm} =v_{atm} ={W_{atm} \mathord{\left/ {\vphantom {W_{atm} \sqrt{2} }} \right. \kern-\nulldelimiterspace} \sqrt{2} }` . +The potential temperature :math:`\overline{\theta _{atm} }` (K) is set +to the atmospheric temperature :math:`T_{atm}` . The atmospheric +longwave radiation :math:`L_{atm} \, \downarrow` (W m\ :math:`{}^{-2}`) +is derived from the atmospheric vapor pressure :math:`e_{atm}` and +temperature :math:`T_{atm}` (Idso 1981) as + +.. math:: + + \label{26.9)} + L_{atm} \, \downarrow =\left[0.70+5.95\times 10^{-5} \times 0.01e_{atm} \exp \left(\frac{1500}{T_{atm} } \right)\right]\sigma T_{atm}^{4} + +where + +.. math:: + + \label{26.10)} + e_{atm} =\frac{P_{atm} q_{atm} }{0.622+0.378q_{atm} } + +and :math:`\sigma` is the Stefan-Boltzmann constant (W +m\ :math:`{}^{-2}` K\ :math:`{}^{-4}`) (Table 2.6). The fraction of +precipitation :math:`P` (mm s\ :math:`{}^{-1}`) falling as rain and/or +snow is + +.. math:: + + \label{ZEqnNum336485} + q_{rain} =P\left(f_{P} \right), + +.. math:: + + \label{26.12)} + q_{snow} =P\left(1-f_{P} \right) + +where + +.. math:: + + \label{26.13)} + f_{P} =0<0.5\left(T_{atm} -T_{f} \right)<1. + +The aerosol deposition rates :math:`D_{sp}` (14 rates as described in +Table 2.3) are provided by a time-varying, globally-gridded aerosol +deposition file developed by Lamarque et al. (2010). + +If the user wishes to provide atmospheric forcing data from another +source, the data format outlined above will need to be followed with the +following exceptions. The data atmosphere model will accept a +user-supplied relative humidity :math:`RH` (%) and derive specific +humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`) from + +.. math:: + + \label{26.14)} + q_{atm} =\frac{0.622e_{atm} }{P_{atm} -0.378e_{atm} } + +where the atmospheric vapor pressure :math:`e_{atm}` (Pa) is derived +from the water (:math:`T_{atm} >T_{f}` ) or ice +(:math:`T_{atm} \le T_{f}` ) saturation vapor pressure +:math:`e_{sat}^{T_{atm} }` as +:math:`e_{atm} =\frac{RH}{100} e_{sat}^{T_{atm} }` where :math:`T_{f}` +is the freezing temperature of water (K) (Table 2.6), and +:math:`P_{atm}` is the pressure at height :math:`z_{atm}` (Pa). The +data atmosphere model will also accept a user-supplied dew point +temperature :math:`T_{dew}` (K) and derive specific humidity +:math:`q_{atm}` from + +.. math:: + + \label{26.15)} + q_{atm} =\frac{0.622e_{sat}^{T_{dew} } }{P_{atm} -0.378e_{sat}^{T_{dew} } } . + +Here, :math:`e_{sat}^{T}` , the saturation vapor pressure as a function +of temperature, is derived from Lowe’s (1977) polynomials. If not +provided by the user, the atmospheric pressure :math:`P_{atm}` (Pa) is +set equal to the standard atmospheric pressure :math:`P_{std} =101325` +Pa, and surface pressure :math:`P_{srf}` (Pa) is set equal +to\ :math:`P_{atm}` . + +The user may provide the total direct and diffuse solar radiation, +:math:`S_{atm} \, \downarrow ^{\mu }` and +:math:`S_{atm} \, \downarrow` . These will be time-interpolated using +the procedure described above and then each term equally apportioned +into the visible and near-infrared wavebands (e.g., +:math:`S_{atm} \, \downarrow _{vis}^{\mu } =0.5S_{atm} \, \downarrow ^{\mu }` , +:math:`S_{atm} \, \downarrow _{nir}^{\mu } =0.5S_{atm} \, \downarrow ^{\mu }` ). diff --git a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst new file mode 100644 index 0000000000..fb30a23e60 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst @@ -0,0 +1,1377 @@ +.. math:: 1 + +.. math:: 1 + +References +============== + +Aber, J.D., Melillo, J.M. and McClaugherty, C.A., 1990. Predicting +long-term patterns of mass loss, nitrogen dynamics, and soil organic +matter formation from initial fime litter chemistry in temperate forest +ecosystems. Canadian Journal of Botany, 68: 2201-2208. + +Aber, J.D., Goodale, C.L., Ollinger, S.V., Smith, M.-L., Magill, A.H., +Martin, M.E., Hallett, R.A., and Stoddard, J.L. 2003. Is nitrogen +deposition altering the nitrogen status of northeastern forests? +BioScience 53:375-389. + +Allen, C.B., Will, R.E., and Jacobson, M.A. 2005. Production efficiency +and radiation use efficiency of four tree species receiving irrigation +and fertilization. Forest Science 51:556-569. + +Anderson, E.A. 1976. A point energy and mass balance model of a snow +cover. NOAA Technical Report NWS 19, Office of Hydrology, National +Weather Service, Silver Spring, MD. + +André, J.-C., Goutorbe, J.-P., and Perrier, A. 1986. HAPEX-MOBILHY: A +hydrologic atmosphere experiment for the study of water budget and +evaporation flux at the climatic scale. Bull. Amer. Meteor. Soc. +67:138-144. + +Andrén, O. and Paustian, K., 1987. Barley straw decomposition in the +field: a comparison of models. Ecology 68:1190-1200. + +Arah, J.R.M. and Stephen, K.D., 1998. A model of the processes leading +to methane emission from peatland. Atmos. Environ. 32:3257-3264. + +Arah, J. and Vinten, A., 1995. Simplified models of anoxia and +denitrification in aggregated and simple-structured soils. European +Journal of Soil Science 46:507-517. + +Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global +Glacier Outlines Version: 1.0, Global Land Ice Measurements from Space, +Boulder Colorado, USA. Digital Media. + +Arora, V.K. and Boer, G.J. 2005. Fire as an interactive component of +dynamic vegetation models. J. Geophys. Res. 110:G02008. +DOI:10.1029/2005JG000042. + +Arya, S.P. 2001. Introduction to Meteorology. Academic Press, San Diego, +CA. + +Asner, G.P., Wessman, C.A., Schimel, D.S., and Archer, S. 1998. +Variability in leaf and litter optical properties: implications for BRDF +model inversions using AVHRR, MODIS, and MISR. Remote Sens. Environ. +63:243-257. + +Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation +patterns in spruce and pine trees following irrigation and +fertilization. Tree Phys. 2:189-204. + +Baird, A.J., Beckwith, C.W., Waldron, S. and Waddington, J.M., 2004. +Ebullition of methane-containing gas bubbles from near-surface Sphagnum +peat. Geophys. Res. Lett. 31. DOI:10.1029/2004GL021157. + +Baldocchi, D., et al. 2001. FLUXNET: A new tool to study the temporal +and spatial variability of ecosystem-scale carbon dioxide, water vapor, +and energy flux densities. Bull. Amer. Meteor. Soc. 82:2415-2433. + +Barbottin, A., Lecomte, C., Bouchard, C., and Jeuffroy, M.-H. 2005. +Nitrogen remobilization during grain filling in wheat: Genotypic and +environmental effects. Crop Sci. 45:1141-1150. + +Batjes, N.H., 2006. ISRIC-WISE derived soil properties on a 5 by 5 +arc-minutes global grid. Report 2006/02 (available through : +http://www.isric.org) + +Berger, A.L. 1978a. Long-term variations of daily insolation and +quaternary climatic changes. J. Atmos. Sci. 35:2362-2367. + +Berger, A.L. 1978b. A simple algorithm to compute long-term variations +of daily or monthly insolation. Contribution de l’Institut d’Astronomie +et de Géophysique, Université Catholique de Louvain, Louvain-la-Neuve, +No. 18. + +Berger, A., Loutre, M.-F., and Tricot, C. 1993. Insolation and Earth’s +orbital periods. J. Geophys. Res. 98:10341-10362. + +Berkowitz, B., and Balberg, I. 1992. Percolation approach to the problem +of hydraulic conductivity in porous media. Transport in Porous Media +9:275–286. + +Beven, K.J., and Kirkby, M.J. 1979. A physically based variable +contributing area model of basin hydrology. Hydrol. Sci. Bull. 24:43-69. + +Bohren, C. F., and Huffman, D. R. 1983. Absorption and scattering of +light by small particles. John Wiley & Sons, New York, NY. + +Bonan, G.B. 1996. A land surface model (LSM version 1.0) for ecological, +hydrological, and atmospheric studies: Technical description and user’s +guide. NCAR Technical Note NCAR/TN-417+STR, National Center for +Atmospheric Research, Boulder, CO, 150 pp. + +Bonan, G.B. 1998. The land surface climatology of the NCAR Land Surface +Model coupled to the NCAR Community Climate Model. J. Climate +11:1307-1326. + +Bonan, G.B. 2002. Ecological Climatology: Concepts and Applications. +Cambridge University Press. + +Bonan, G.B., Oleson, K.W., Vertenstein, M., Levis, S., Zeng, X., Dai, +Y., Dickinson, R.E., and Yang, Z.-L. 2002a. The land surface climatology +of the Community Land Model coupled to the NCAR Community Climate Model. +J. Climate 15: 3123-3149. + +Bonan, G.B., Levis, S., Kergoat, L., and Oleson, K.W. 2002b. Landscapes +as patches of plant functional types: An integrating concept for climate +and ecosystem models. Global Biogeochem. Cycles 16: 5.1-5.23. + +Bonan, G.B., and Levis, S. 2006. Evaluating aspects of the Community +Land and Atmosphere Models (CLM3 and CAM3) using a dynamic global +vegetation model. J. Climate 19:2290-2301. + +Bonan, G.B., Lawrence P.J., Oleson K.W., Levis S., Jung M., Reichstein +M., Lawrence, D.M., and Swenson, S.C. 2011. Improving canopy processes +in the Community Land Model (CLM4) using global flux fields empirically +inferred from FLUXNET data. J. Geophys. Res. 116, G02014. +DOI:10.1029/2010JG001593. + +Bonan, G. B., Oleson, K.W., Fisher, R.A., Lasslop, G., and Reichstein, +M. 2012. Reconciling leaf physiological traits and canopy flux data: Use +of the TRY and FLUXNET databases in the Community Land Model version 4, +J. Geophys. Res., 117, G02026. DOI:10.1029/2011JG001913. + +Branstetter, M.L., and Famiglietti, J.S. 1999. Testing the sensitivity +of GCM-simulated runoff to climate model resolution using a parallel +river transport algorithm. Preprints, 14\ :math:`{}^{th}` Conference on +Hydrology, Dallas, TX, Amer. Meteor. Soc., 391-392. + +Branstetter, M.L. 2001. Development of a parallel river transport +algorithm and applications to climate studies. Ph.D. dissertation, +University of Texas at Austin. + +Brun, E. 1989. Investigation of wet-snow metamorphism in respect of +liquid water content. Ann. Glaciol. 13:22-26. + +Bugmann, H., and Solomon, A.M. 2000. Explaining forest composition and +biomass across multiple biogeographical regions. Ecol. Appl. 10:95-114. + +Busing, R.T. 2005. Tree mortality, canopy turnover, and woody detritus +in old cove forests of the southern Appalachians. Ecology 86:73-84. + +Campbell, G.S., and Norman, J.M. 1998. An Introduction to Environmental +Biophysics (2:math:`{}^{nd}` edition). Springer-Verlag, New York. + +Castillo, G., Kendra, C., Levis, S., and Thornton, P. 2012. Evaluation +of the new CNDV option of the Community Land Model: effects of dynamic +vegetation and interactive nitrogen on CLM4 means and variability. J. +Climate 25:3702–3714. + +Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and +methane emissions from natural wetlands: Application of a process-based +model. J. Geophys. Res. 101(D9):14,399-14,414. + +Churkina, G. et al., 2003. Analyzing the ecosystem carbon dynamics of +four European coniferous forests using a biogeochemistry model. +Ecosystems, 6: 168-184. + +CIESIN: Gridded population of the world version 3 (GPWv3), 2005. +Population density grids, Technical report, Socioeconomic Data and +Applications Center (SEDAC), Columbia University, Palisades, New York, +USA. + +Clapp, R.B., and Hornberger, G.M. 1978. Empirical equations for some +soil hydraulic properties. Water Resour. Res. 14:601-604. + +Clauser, C., and Huenges, E. 1995. Thermal conductivity of rocks and +minerals. pp. 105-126. In: T. J. Ahrens (editor) Rock Physics and Phase +Relations: A Handbook of Physical Constants. Washington, D.C. + +Cleveland, C.C., Townsend, A.R., Schimel, D.S., Fisher, H., Howarth, +R.W., Hedin, L.O., Perakis, S.S., Latty, E.F., Von Fischer, J.C., +Elseroad, A., and Wasson, M.F. 1999. Global patterns of terrestrial +biological nitrogen (N2) fixation in natural ecosystems. Global +Biogeochem. Cycles 13:623-645. + +Collatz, G.J., Ball, J.T., Grivet, C., and Berry, J.A. 1991. +Physiological and environmental regulation of stomatal conductance, +photosynthesis, and transpiration: A model that includes a laminar +boundary layer. Agric. For. Meteor. 54:107-136. + +Collatz, G.J., Ribas-Carbo, M., and Berry, J.A. 1992. Coupled +photosynthesis-stomatal conductance model for leaves of +C\ :math:`{}_{4}` plants. Aust. J. Plant Physiol. 19:519-538. + +Colmer, T.D., 2003. Long-distance transport of gases in plants: a +perspective on internal aeration and radial oxygen loss from roots. +Plant Cell and Environment 26:17-36. + +Conway, H., Gades, A., and Raymond, C.F. 1996. Albedo of dirty snow +during conditions of melt. Water Resour. Res. 32:1713-1718. + +Cosby, B.J., Hornberger, G.M., Clapp, R.B., and Ginn, T.R. 1984. A +statistical exploration of the relationships of soil moisture +characteristics to the physical properties of soils. Water Resour. Res. +20:682-690. + +Crawford, T. W., Rendig, V. V., and Broadent, F. E. 1982. Sources, +fluxes, and sinks of nitrogen during early reproductive growth of maize +(Zea mays L.). Plant Physiol. 70:1645-1660. + +Dai, Y., and Zeng, Q. 1997. A land surface model (IAP94) for climate +studies. Part I: formulation and validation in off-line experiments. +Adv. Atmos. Sci. 14:433-460. + +Dai, Y., et al. 2001. Common Land Model: Technical documentation and +user’s guide [Available online at +http://climate.eas.gatech.edu/dai/clmdoc.pdf]. + +Dai, Y., Zeng, X., Dickinson, R.E., Baker, I., Bonan, G.B., Bosilovich, +M.G., Denning, A.S., Dirmeyer, P.A., Houser, P.R., Niu, G., Oleson, +K.W., Schlosser, C.A., and Yang, Z.-L. 2003. The Common Land Model. +Bull. Amer. Meteor. Soc. 84:1013-1023. + +Dai, Y., Dickinson, R.E., and Wang, Y.-P. 2004. A two-big-leaf model for +canopy temperature, photosynthesis, and stomatal conductance. J. Climate +17:2281-2299. + +Dai, A., and Trenberth, K.E. 2002. Estimates of freshwater discharge +from continents: Latitudinal and seasonal variations. J. Hydrometeor. +3:660-687. + +DeFries, R.S., Hansen, M.C., Townshend, J.R.G., Janetos, A.C., and +Loveland, T.R. 2000. A new global 1-km dataset of percentage tree cover +derived from remote sensing. Global Change Biol. 6:247-254. + +Degens, B. and Sparling, G., 1996. Changes in aggregation do not +correspond with changes in labile organic C fractions in soil amended +with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): +453-462. + +de Vries, D.A. 1963. Thermal Properties of Soils. In: W.R. van Wijk +(editor) Physics of the Plant Environment. North-Holland, Amsterdam. + +Dickinson, R.E. 1983. Land surface processes and climate-surface albedos +and energy balance. Adv. Geophys. 25:305-353. + +Dickinson, R.E., Henderson-Sellers, A., and Kennedy, P.J. 1993. +Biosphere-Atmosphere Transfer Scheme (BATS) version 1e as coupled to the +NCAR Community Climate Model. NCAR Technical Note NCAR/TN-387+STR. +National Center for Atmospheric Research, Boulder, CO. + +Dickinson, R.E., Oleson, K.W., Bonan, G., Hoffman, F., Thornton, P., +Vertenstein, M., Yang, Z.-L., and Zeng, X. 2006. The Community Land +Model and its climate statistics as a component of the Community Climate +System Model. J. Climate 19:2302-2324. + +Dingman, S.L. 2002. Physical Hydrology. Second Edition. Prentice Hall, +NJ. + +Dirmeyer, P.A., Dolman, A.J., and Sato, N. 1999. The pilot phase of the +Global Soil Wetness Project. Bull. Amer. Meteor. Soc. 80:851-878. + +Dobson, J.E., Bright, E.A., Coleman, P.R., Durfee, R.C., and Worley, +B.A. 2000. LandScan: A global population database for estimating +populations at risk. Photogramm. Eng. Rem. Sens. 66:849-857. + +Dorman, J.L., and Sellers, P.J. 1989. A global climatology of albedo, +roughness length and stomatal resistance for atmospheric general +circulation models as represented by the simple biosphere model (SiB). +J. Appl. Meteor. 28:833-855. + +Dougherty, R.L., Bradford, J.A., Coyne, P.I., and Sims, P.L. 1994. +Applying an empirical model of stomatal conductance to three C4 grasses. +Agric. For. Meteor. 67:269-290. + +Drewniak, B., Song, J., Prell, J., Kotamarthi, V.R., and Jacob, R. 2013. +Modeling agriculture in the Community Land Model. Geosci. Model Dev. +6:495-515. DOI:10.5194/gmd-6-495-2013. + +Dunfield, P., Knowles, R., Dumont, R. and Moore, T.R., 1993. Methane +Production and Consumption in Temperate and Sub-Arctic Peat Soils - +Response to Temperature and Ph. Soil Biology & Biochemistry 25:321-326. + +Entekhabi, D., and Eagleson, P.S. 1989. Land surface hydrology +parameterization for atmospheric general circulation models including +subgrid scale spatial variability. J. Climate 2:816-831. + +Fang, X. and Stefan, H.G., 1996. Long-term lake water temperature and +ice cover simulations/measurements. Cold Regions Science and Technology +24:289-304. + +Farouki, O.T. 1981. The thermal properties of soils in cold regions. +Cold Regions Sci. and Tech. 5:67-75. + +Farquhar, G.D., von Caemmerer, S., and Berry, J.A. 1980. A biochemical +model of photosynthetic CO\ :math:`{}_{2}` assimilation in leaves of +C\ :math:`{}_{3}` species. Planta 149:78-90. + +Farquhar, G.D., and von Caemmerer, S. 1982. Modeling of photosynthetic +response to environmental conditions. pp. 549-587. In: O.L. Lange, P.S. +Nobel, C.B. Osmond, and H. Zeigler (editors) Encyclopedia of Plant +Physiology. Vol. 12B. Physiological Plant Ecology. II. Water Relations +and Carbon Assimilation. Springer-Verlag, New York. + +Ferrari, J.B., 1999. Fine-scale patterns of leaf litterfall and nitrogen +cycling in an old-growth forest. Canadian Journal of Forest Research, +29: 291-302. + +Firestone, M.K. and Davidson, E.A. 1989. Exchange of Trace Gases between +Terrestrial Ecosystems and the Atmosphere. In: M.O. Andreae and D.S. +Schimel (Editors). John Wiley and Sons, pp. 7-21. + +Flanner, M.G., and Zender. C.S. 2005. Snowpack radiative heating: +Influence on Tibetan Plateau climate. Geophys. Res. Lett. 32:L06501. +DOI:10.1029/2004GL022076. + +Flanner, M.G., and Zender, C.S. 2006. Linking snowpack microphysics and +albedo evolution. J. Geophys. Res. 111:D12208. DOI:10.1029/2005JD006834. + +Flanner, M.G., Zender, C.S., Randerson, J.T., and Rasch, P.J. 2007. +Present day climate forcing and response from black carbon in snow. J. +Geophys. Res. 112:D11202. DOI:10.1029/2006JD008003. + +Flatau, P.J., Walko, R.L., and Cotton, W.R. 1992. Polynomial fits to +saturation vapor pressure. J. Appl. Meteor. 31:1507-1513. + +Friedl, M.A., McIver, D.K., Hodges, J.C.F., Zhang, X.Y., Muchoney, D., +Strahler, A.H., Woodcock, C.E., Gopal, S., Schneider, A., Cooper, A., +Baccini, A., Gao, F., and Schaaf, C. 2002. Global land cover mapping +from MODIS: algorithms and early results. Remote Sens. Environ. +83:287-302. + +Frolking, S., et al. 2001. Modeling Northern Peatland Decomposition and +Peat Accumulation. Ecosystems. 4:479-498. + +Gallais, A., Coque, M. Quillere, I., Prioul, J., and Hirel, B. 2006. +Modeling postsilking nitrogen fluxes in maize (Zea mays) using +15N-labeling field experiments. New Phytologist 172:696-707. + +Gallais, A., Coque, M., Gouis, J. L., Prioul, J. L., Hirel, B., and +Quillere, I. 2007. Estimating the proportion of nitrogen remobilization +and of postsilking nitrogen uptake allocated to maize kernels by +Nitrogen-15 labeling. Crop Sci. 47:685-693. + +Galloway, J.N., et al. 2004. Nitrogen cycles: past, present, and future. +Biogeochem. 70:153-226. + +Garcia, R.L., Kanemasu, E.T., Blad, B.L., Bauer, A., Hatfield, J.L., +Major, D.A., Reginato, R.J., and Hubbard, K.G. 1988. Interception and +use efficiency of light in winter wheat under different nitrogen +regimes. Agric. For. Meteor. 44:175-186. + +Gash, J.H.C., Nobre, C.A., Roberts, J.M., and Victoria, R.L. 1996. An +overview of ABRACOS. pp. 1-14. In: J.H.C. Gash, C.A. Nobre, J.M. +Roberts, and R.L. Victoria (editors) Amazonian Deforestation and +Climate. John Wiley and Sons, Chichester, England. + +Gholz, H.L., Perry, C.S., Cropper, W.P., Jr. and Hendry, L.C., 1985. +Litterfall, decomposition, and nitrogen and phosphorous dynamics in a +chronosequence of slash pine (*Pinus elliottii*) plantations. Forest +Science, 31: 463-478. + +Giglio, L., Csiszar, I., and Justice, C.O. 2006. Global distribution and +seasonality of active fires as observed with the Terra and Aqua Moderate +Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. +111:G02016. DOI:10.1029/2005JG000142. + +Global Soil Data Task 2000. Global soil data products CD-ROM (IGBP-DIS). +International Geosphere-Biosphere Programme-Data and Information +Available Services [Available online at http://www.daac.ornl.gov]. + +Gomes, E.P.C., Mantovani, W., and Kageyama, P.Y. 2003. Mortality and +recruitment of trees in a secondary montane rain forest in southeastern +Brazil. Brazilian Journal of Biology 63:47-60. + +Gosz, J.R., Likens, G.E., and Bormann, F.H. 1973. Nutrient release from +decomposing leaf and branch litter in the Hubbard Brook Forest, New +Hampshire. Ecological Monographs 43:173-191. + +Gotangco Castillo C., Levis S., and Thornton P. 2012. Evaluation of the +new CNDV option of the Community Land Model: Effects of dynamic +vegetation and interactive nitrogen on CLM4 means and variability. J. +Climate 25:3702-3714. DOI:10.1175/JCLID-11-00372.1. + +Graham, S.T., Famiglietti, J.S., and Maidment, D.R. 1999. Five-minute, +1/2º, and 1º data sets of continental watersheds and river networks for +use in regional and global hydrologic and climate system modeling +studies. Water Resour. Res. 35:583-587. + +Grenfell, T.C., and Warren, S.G. 1999. Representation of a nonspherical +ice particle by a collection of independent spheres for scattering and +absorption of radiation. J. Geophys. Res. 104(D24):37697-37709. + +del Grosso, S.J., et al. 2000. General model for N2O and N2 gas +emissions from soils due to dentrification. Global Biogeochem. Cycles +14:1045-1060. + +Guenther, A., Hewitt, C.N., Erickson, D., Fall, R., Geron, C., Graedel, +T., Harley, P., Klinger, L., Lerdau, M., McKay, W.A., Pierce, T., +Scholes, B., Steinbrecher, R., Tallamraju, R., Taylor, J., and +Zimmerman, P. 1995. A global model of natural volatile organic compound +emissions. J. Geophys. Res. 100:8873-8892. + +Guenther, A., Karl, T., Harley, P., Wiedinmyer, C., Palmer. P.I., and +Geron, C. 2006. Estimates of global terrestrial isoprene emissions using +MEGAN (Model of Emissions of Gases and Aerosols from Nature). Atmos. +Chem. Phys. 6:3181–3210. + +Guenther, A. B., Jiang, X., Heald, C. L., Sakulyanontvittaya, T., Duhl, +T., Emmons, L. K., & Wang, X., 2012. The Model of Emissions of Gases and +Aerosols from Nature version 2.1 (MEGAN2.1): an extended and updated +framework for modeling biogenic emissions, Geosci. Model Dev., 5, +1471–1492. DOI:10.5194. + +Hack, J.J., Caron, J.M., Yeager, S.G., Oleson, K.W., Holland, M.M., +Truesdale, J.E., and Rasch, P.J. 2006. Simulation of the global +hydrological cycle in the CCSM Community Atmosphere Model version 3 +(CAM3): mean features. J. Climate 19:2199-2221. + +Hansen, M., DeFries, R.S., Townshend, J.R.G., Carroll, M., Dimiceli, C., +and Sohlberg, R.A. 2003. Global percent tree cover at a spatial +resolution of 500 meters: first results of the MODIS vegetation +continuous fields algorithm. Earth Interactions 7:1-15. + +Hastings, D.A., Dunbar, P.K., Elphingstone, G.M., Bootz, M., Murakami, +H., Maruyama, H., Masaharu, H., Holland, P., Payne, J., Bryant, N.A., +Logan, T.L., Muller, J.-P., Schreier, G., and MacDonald, J.S., eds., +1999. The Global Land One-kilometer Base Elevation (GLOBE) Digital +Elevation Model, Version 1.0. National Oceanic and Atmospheric +Administration, National Geophysical Data Center, 325 Broadway, Boulder, +Colorado 80305-3328, U.S.A. + +Heald, C.L., Henze, D.K., Horowitz, L.W., Feddema, J., Lamarque, J.-F., +Guenther, A., Hess, P.G., Vitt, F., Seinfeld, J.H., Goldstein, A.H., and +Fung, I. 2008. Predicted change in global secondary organic aerosol +concentrations in response to future climate, emissions, and land use +change. J. Geophys. Res. 113:D05211. DOI:10.1029/2007JD009092. + +Heald, C.L., Wilkinson, M.J., Monson, R.K., Alo, C.A., Wang, G.L., and +Guenther, A. 2009. Response of isoprene emission to ambient +CO\ :math:`{}_{2}` changes and implications for global budgets. Global +Change Biol. 15:1127-1140. DOI:10.1111/j.1365-2486.2008.01802.x + +Henderson-Sellers, B. 1985. New formulation of eddy diffusion +thermocline models. Appl. Math. Modelling 9:441-446. + +Henderson-Sellers, B. 1986. Calculating the surface energy balance for +lake and reservoir modeling: A review. Rev. Geophys. 24:625-649. + +Henderson-Sellers, A., Yang, Z.-L., and Dickinson, R.E. 1993. The +project for intercomparison of land-surface parameterization schemes. +Bull. Amer. Meteor. Soc. 74: 1335-1349. + +Hostetler, S.W., and Bartlein, P.J. 1990. Simulation of lake evaporation +with application to modeling lake level variations of Harney-Malheur +Lake, Oregon. Water Resour. Res. 26:2603-2612. + +Hostetler, S.W., Bates, G.T., and Giorgi, F. 1993. Interactive coupling +of a lake thermal model with a regional climate model. J. Geophys. Res. +98:5045-5057. + +Hostetler, S.W., Giorgi, F., Bates, G.T., and Bartlein, P.J. 1994. +Lake-atmosphere feedbacks associated with paleolakes Bonneville and +Lahontan. Science 263:665-668. + +Hou, Z., Huang, M., Leung, L.R., Lin, G., and Ricciuto, D.M. 2012. +Sensitivity of surface flux simulations to hydrologic parameters based +on an uncertainty quantification framework applied to the Community Land +Model. J. Geophys. Res. 117:D15108. + +Huang, M., and Liang, X. 2006. On the assessment of the impact of +reducing parameters and identification of parameter uncertainties for a +hydrologic model with applications to ungauged basins. J. Hydrol. +320:37-61. + +Hugelius, G., C. Tarnocai, G. Broll, J.G. Canadell, P. Kuhry, adn D.K. +Swanson, 2012. The Northern Circumpolar Soil Carbon Database: spatially +distributed datasets of soil coverage and soil carbon storage in the +northern permafrost regions. Earth Syst. Sci. Data Discuss., 5, 707-733 +(available online at (http://dev1.geo.su.se/bbcc/dev/ncscd/). + +Hunt, H.W., Ingham, E.R., Coleman, D.C., Elliott, E.T., and Reid, C.P.P. +1988. Nitrogen limitation of production and decomposition in prairie, +mountain meadow, and pine forest. Ecology 69:1009-1016. + +Hunt, E.R., Jr. and Running, S.W., 1992. Simulated dry matter yields for +aspen and spruce stands in the north american boreal forest. Canadian +Journal of Remote Sensing, 18: 126-133. + +Hunt, E.R., Jr. et al., 1996. Global net carbon exchange and +intra-annual atmospheric CO\ :math:`{}_{2}` concentrations predicted by +an ecosystem process model and three-dimensional atmospheric transport +model. Global Biogeochemical Cycles, 10: 431-456. + +Hurtt, G.C., Frolking, S., Fearon, M.G., Moore, B., Shevliakova, E., +Malyshev, S., Pacala, S.W., and Houghton, R.A. 2006. The underpinnings +of land-use history: three centuries of global gridded land-use +transitions, wood-harvest activity, and resulting secondary lands. +Global Change Biol. 12:1208-1229. + +Hurtt, G.C., et al. 2011. Harmonization of land-use scenarios for the +period 1500-2100: 600 years of global gridded annual land-use +transitions, wood harvest, and resulting secondary lands. Climatic +Change 109:117-161. DOI:10.1007/s10584-011-0153-2. + +Idso, S.B. 1981. A set of equations for full spectrum and 8- to +14-\ :math:`\mu` \ m and 10.5- to 12.5-\ :math:`\mu` \ m thermal +radiation from cloudless skies. Water Resour. Res. 17:295-304. + +Iiyama, I. and Hasegawa, S., 2005. Gas diffusion coefficient of +undisturbed peat soils. Soil Science and Plant Nutrition 51:431-435. + +Jackson, R. B., Canadell, J., Ehleringer, J. R., Mooney, H. A., Sala, O. +E., and Schulze, E. D. 1996. A global analysis of root distributions for +terrestrial biomes Oecologia 108:389–411. DOI:10.1007/BF00333714. + +Jackson, T.L., Feddema, J.J., Oleson, K.W., Bonan, G.B., and Bauer, J.T. +2010. Parameterization of urban characteristics for global climate +modeling. Annals of the Association of American Geographers. +100:848-865. + +Jenkinson, D. and Coleman, K. 2008. The turnover of organic carbon in +subsoils. Part 2. Modelling carbon turnover. European Journal of Soil +Science 59:400-413. + +Jordan, R. 1991. A One-dimensional Temperature Model for a Snow Cover: +Technical Documentation for SNTHERM.89. U.S. Army Cold Regions Research +and Engineering Laboratory, Special Report 91-16. + +Kattge, J., and Knorr, W. 2007. Temperature acclimation in a biochemical +model of photosynthesis: a reanalysis of data from 36 species. Plant +Cell Environ. 30:1176-1190. DOI: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 Biol. +15:976–991. + +Keller, M., Palace, M., Asner, G.P., Pereira, R., Jr. and Silva, J.N.M., +2004. Coarse woody debris in undisturbed and logged forests in the +eastern Brazilian Amazon. Global Change Biology, 10: 784-795. + +Kellner, E., Baird, A.J., Oosterwoud, M., Harrison, K. and Waddington, +J.M., 2006. Effect of temperature and atmospheric pressure on methane +(CH4) ebullition from near-surface peats. Geophys. Res. Lett. 33. +DOI:10.1029/2006GL027509. + +Kimball, J.S., Thornton, P.E., White, M.A. and Running, S.W. 1997. +Simulating forest productivity and surface-atmosphere exchange in the +BOREAS study region. Tree Physiology 17:589-599. + +Kohyama, T., Suzuki, E., Partomihardjo, T., and Yamada, T. 2001. Dynamic +steady state of patch-mosaic tree size structure of a mixed diptocarp +forest regulated by local crowding. Ecological Research 16:85-98. + +Kourzeneva, E., 2009. Global dataset for the parameterization of lakes +in Numerical Weather Prediction and Climate modeling. ALADIN Newsletter, +No 37, July-December, 2009, F. Bouttier and C. Fischer, Eds., +Meteo-France, Toulouse, France, 46-53. + +Kourzeneva, E., 2010: External data for lake parameterization in +Numerical Weather Prediction and climate modeling. Boreal Environment +Research, 15, 165-177. + +Kourzeneva, E., Asensio, H., Martin, E. and Faroux, S., 2012. Global +gridded dataset of lake coverage and lake depth for use in numerical +weather prediction and climate modelling. Tellus A 64. + +Koven, C., et al. 2009. On the formation of high-latitude soil carbon +stocks: The effects of cryoturbation and insulation by organic matter in +a land surface model. Geophys. Res. Lett. 36: L21501. + +Koven, C.D., et al. 2011. Permafrost carbon-climate feedbacks accelerate +global warming. Proceedings of the National Academy of Sciences +108:14769-14774. + +Koven, C.D. et al. 2013. The effect of vertically-resolved soil +biogeochemistry and alternate soil C and N models on C dynamics of CLM4. +Biogeosciences Discussions 10:7201-7256. + +Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., +Lenters, J.D., Young-Molling, C., and Ramankutty, N. 2000. Testing the +performance of a dynamic global ecosystem model: water balance, carbon +balance, and vegetation structure. Global Biogeochem. Cycles 14: +795–825. + +Kucharik, C.J., and Brye, K.R. 2003. Integrated BIosphere Simulator +(IBIS) yield and nitrate loss predictions for Wisconsin maize receiving +varied amounts of nitrogen fertilizer. Journal of Environmental Quality +32: 247–268. + +Ladd, J.N., Jocteur-Monrozier, L. and Amato, M., 1992. Carbon turnover +and nitrogen transformations in an alfisol and vertisol amended with +[U-:math:`{}^{14}`\ C] glucose and [:math:`{}^{15}`\ N] ammonium +sulfate. Soil Biology and Biochemistry, 24: 359-371. + +Lamarque, J.-F., et al. 2010. Historical (1850-2000) gridded +anthropogenic and biomass burning emissions of reactive gases and +aerosols: methodology and application. Atmos. Chem. Phys. Discuss. +10:4963-5019. DOI:10.5194/acpd-10-4963-2010. + +Larcher, W. 1995. Physiological Plant Ecology, Springer-Verlag, Berlin +Heidelberg. + +Lavigne, M.B., and Ryan, M.G. 1997. Growth and maintenance respiration +rates of aspen, black spruce, and jack pine stems at northern and +southern BOREAS sites. Tree Phys. 17:543-551. + +Law, B.E., Sun, O.J., Campbell, J., Van Tuyl, S. and Thornton, P.E. +2003. Changes in carbon storage and fluxes in a chronosequence of +ponderosa pine. Global Change Biology, 9: 510-514. + +Lawrence, D.M., Thornton, P.E., Oleson, K.W., and Bonan, G.B. 2007. The +partitioning of evapotranspiration into transpiration, soil evaporation, +and canopy evaporation in a GCM: Impacts on land-atmosphere interaction. +J. Hydrometeor. 8:862-880. + +Lawrence, D.M., and Slater, A.G. 2008. Incorporating organic soil into a +global climate model. Clim. Dyn. 30. DOI:10.1007/s00382-007-0278-1. + +Lawrence, D.M., Slater, A.G., Romanovsky, V.E., and Nicolsky, D.J. 2008. +The sensitivity of a model projection of near-surface permafrost +degradation to soil column depth and inclusion of soil organic matter. +J. Geophys. Res. 113:F02011. DOI:10.1029/2007JF000883. + +Lawrence, D.M., K.W. Oleson, M.G. Flanner, P.E. Thornton, S.C. Swenson, +P.J. Lawrence, X. Zeng, Z.-L. Yang, S. Levis, K. Sakaguchi, G.B. Bonan, +and A.G. Slater, 2011. Parameterization improvements and functional and +structural advances in version 4 of the Community Land Model. J. Adv. +Model. Earth Sys. 3. DOI:10.1029/2011MS000045. + +Lawrence, P.J., and Chase, T.N. 2007. Representing a MODIS consistent +land surface in the Community Land Model (CLM 3.0). J. Geophys. Res. +112:G01023. DOI:10.1029/2006JG000168. + +Lawrence, P.J., and Chase, T.N. 2010. Investigating the climate impacts +of global land cover change in the Community Climate System Model. Int. +J. Climatol. 30:2066-2087. DOI:10.1002/joc.2061. + +Lawrence, P.J., et al. 2012. Simulating the biogeochemical and +biogeophysical impacts of transient land cover change and wood harvest +in the Community Climate System Model (CCSM4) from 1850 to 2100. J. +Climate 25:3071-3095. DOI:10.1175/JCLI-D-11-00256.1. + +Lehner, B. and Döll, P., 2004. Development and validation of a global +database of lakes, reservoirs and wetlands, J. Hydrol., 296, 1–22. + +Le Page, Y., van der Werf, G.R., Morton, D.C., and Pereira, J.M.C. 2010. +Modeling fire-driven deforestation potential in Amazonia under current +and projected climate conditions. J. Geophys. Res. 115:G03012. +DOI:10.1029/2009JG001190. + +Lerman, A., 1979. Geochemical processes: Water and sediment +environments. John Wiley and Sons, New York, N.Y. + +Letts, M.G., Roulet, N.T., Comer, N.T., Skarupa, M.R., and Verseghy, +D.L. 2000. Parametrization of peatland hydraulic properties for the +Canadian Land Surface Scheme. Atmos.-Ocean 38:141-160. + +Levin, I. and Kromer, B. 2004. The tropospheric 14CO2 level in +mid-latitudes of the Northern Hemisphere (1959-2003) Radiocarbon 46:1. + +Levis, S., Wiedinmyer, C., Bonan, G.B., and Guenther, A. 2003. +Simulating biogenic volatile organic compound emissions in the Community +Climate System Model. J. Geophys. Res. 108:4659. +DOI:10.1029/2002JD003203. + +Levis, S., Bonan, G.B., Vertenstein, M., and Oleson, K.W. 2004. The +community land model’s dynamic global vegetation model (CLM-DGVM): +technical description and user’s guide. NCAR Technical Note +NCAR/TN-459+STR. National Center for Atmospheric Research, Boulder, +Colorado. 50 pp. + +Levis, S., Thornton, P., Bonan, G., and Kucharik, C. 2009. Modeling land +use and land management with the Community Land Model. iLeaps +newsletter, No. 7. + +Levis, S., Bonan, G., Kluzek, E., Thornton, P., Jones, A., Sacks, W., +and Kucharik, C 2012. Interactive crop management in the Community Earth +System Model (CESM1): Seasonal influences on land-atmosphere fluxes. J. +Climate 25: 4839-4859. DOI:10.1175/JCLI-D-11-00446.1. + +Li, C., Aber, J., Stange, F., Butterbach-Bahl, K. and Papen, H. 2000. A +process-oriented model of N2O and NO emissions from forest soils: 1. +Model development. J. Geophys. Res. 105(D4):4369-4384. + +Li, F., Zeng, X.-D., and Levis, S. 2012a. A process-based fire +parameterization of intermediate complexity in a Dynamic Global +Vegetation Model. Biogeosciences 9:2761-2780. + +Li, F., Zeng, X. D., and Levis, S. 2012b. Corrigendum to “A +process-based fire parameterization of intermediate complexity in a +Dynamic Global Vegetation Model†published in Biogeosciences, 9, +2761–2780, 2012â€. Biogeosciences 9: 4771-4772. + +Li, F., Levis, S., and Ward, D. S. 2013a. Quantifying the role of fire +in the Earth system – Part 1: Improved global fire modeling in the +Community Earth System Model (CESM1). Biogeosciences 10:2293-2314. + +Li, H.-Y., Huang, M., Tesfa, T., Ke, Y., Sun, Y., Liu, Y., and Leung, L. +R. 2013b. A subbasin-based framework to represent land surface processes +in an Earth System Model, Geosci. Model Dev. Discuss. 6:2699-2730. +DOI:10.5194/gmdd-6-2699-2013. + +Li, H., Huang, M., Wigmosta, M.S., Ke, Y., Coleman, A.M., Leung, L.R., +Wang, A., and Ricciuto, D.M. 2011. Evaluating runoff simulations from +the Community Land Model 4.0 using observations from flux towers and a +mountainous watershed. J. Geophys. Res. 116:D24120. +DOI:10.1029/2011JD016276. + +Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A +simple hydrologically based model of land surface water and energy +fluxes for GSMs. J. Geophys. Res. 99(D7):14,415–14,428. + +Lipscomb, W., and Sacks, W. 2012. The CESM land ice model documentation +and user’s guide. 46 pp. [Available online at +http://www.cesm.ucar.edu/models/cesm1.1/cism/]. + +Lloyd, J. and Taylor, J.A., 1994. On the temperature dependence of soil +respiration. Functional Ecology, 8: 315-323. + +Lloyd, J., et al. 2010. Optimisation of photosynthetic carbon gain and +within-canopy gradients of associated foliar traits for Amazon forest +trees. Biogeosci. 7:1833-1859. DOI:10.5194/bg-7-1833-2010. + +Lobell, D.B., Bala, G., and Duffy, P.B. 2006. Biogeophysical impacts of +cropland management changes on climate. Geophys. Res. Lett. 33:L06708. +DOI:10.1029/2005GL025492. + +Loveland, T.R., Reed, B.C., Brown, J.F., Ohlen, D.O., Zhu, Z., Yang, L., +and Merchant, J.W. 2000. Development of a global land cover +characteristics database and IGBP DISCover from 1 km AVHRR data. Int. J. +Remote Sens. 21:1303-1330. + +Lowe, P.R. 1977. An approximating polynomial for the computation of +saturation vapor pressure. J. Appl. Meteor. 16:100-103. + +Luo, Y., Hui, D., and Zhang, D. 2006. Elevated CO2 stimulates net +accumulations of carbon and nitrogen in land ecosystems: a +meta-analysis. Ecology 87:53-63. + +Magill, A.H. et al., 1997. Biogeochemical response of forest ecosystems +to simulated chronic nitrogen deposition. Ecological Applications, 7: +402-415. + +Mahowald, N.M., Muhs, D.R., Levis, S., Rasch, P.J., Yoshioka, M., +Zender, C.S., and Luo, C. 2006. Change in atmospheric mineral aerosols +in response to climate: last glacial period, pre-industrial, modern and +doubled CO\ :math:`{}_{2}` climates. J. Geophys. Res\ *.* 111:D10202. +DOI:10.1029/2005JD006653. + +Makela, A. 2002. Derivation of stem taper from the pipe model theory in +a carbon balance framework. Tree Phys. 22:891-905. + +Manning, M.R. and Melhuish, W.H. 1994. Trends: A Compendium of Data on +Global Change. Carbon Dioxide Information Analysis Center,. Oak Ridge +National Laboratory, U.S. Department of Energy, Oak Ridge, Tenn., U.S.A. + +Mao, J., Thornton, P.E., Shi, X., Zhao, M., and Post, W.M. 2012. Remote +sensing evaluation of CLM4 GPP for the period 2000 to 2009. J. Climate +25:5327-5342. + +Mao, J., Shi, X., Thornton, P.E., Hoffman, F.M., Zhu, Z., and Ranga B. +Myneni, R.B. 2013. Global latitudinal-asymmetric vegetation growth +trends and their driving mechanisms: 1982-2009. Remote Sensing +5:1484-1497. + +Martin, J.P., Haider, K. and Kassim, G., 1980. Biodegradation and +stabilization after 2 years of specific crop, lignin, and polysaccharide +carbons in soils. Soil Science Society of America Journal 44:1250-1255. + +Mary, B., Fresneau, C., Morel, J.L. and Mariotti, A., 1993. C and N +cycling during decomposition of root mucilage, roots and glucose in +soil. Soil Biology and Biochemistry 25:1005-1014. + +McGuire, A.D., Melillo, J.M., Joyce, L.A., Kicklighter, D.W., Grace, +A.L., Moore III, B., and Vorosmarty, C.J. 1992. Interactions between +carbon and nitrogen dynamics in estimating net primary productivity for +potential vegetation in North America. Global Biogeochem. Cycles +6:101-124. + +Melzer, E., and O’Leary, M.H. 1987. Anapleurotic CO2 Fixation by +Phosphoenolpyruvate Carboxylase in C3 Plants. Plant. Physiol. 84:58. + +Miller, J.R., Russell, G.L., and Caliri, G. 1994. Continental-scale +river flow in climate models. J. Climate 7:914-928. + +Millington, R. and Quirk, J.P., 1961. Permeability of Porous Solids. +Transactions of the Faraday Society 57:1200-1207. + +Mironov, D. et al., 2010. Implementation of the lake parameterisation +scheme FLake into the numerical weather prediction model COSMO. Boreal +Environment Research 15:218-230. + +Mitchell, T.D., and Jones, P.D. 2005. An improved method of constructing +a database of monthly climate observations and associated +high-resolution grids. Int. J. Climatol. 25:693-712. + +Moldrup, P. et al. 2003. Modeling diffusion and reaction in soils: X. A +unifying model for solute and gas diffusivity in unsaturated soil. Soil +Science 168:321-337. + +Myneni, R.B., et al. 2002. Global products of vegetation leaf area and +fraction absorbed PAR from year one of MODIS data. Remote Sens. Environ. +83:214-231. + +Neff, J.C., Harden, J.W. and Gleixner, G. 2005. Fire effects on soil +organic matter content, composition, and nutrients in boreal interior +Alaska. Canadian Journal of Forest Research-Revue Canadienne De +Recherche Forestiere 35:2178-2187. + +Neitsch, S.L., Arnold, J.G., Kiniry, J.R., and Williams J.R. 2005. Soil +and Water Assessment Tool, Theoretical Documentation: Version 2005. +Temple, TX. USDA Agricultural Research Service and Texas A&M Blackland +Research Center. + +Nemani, R.R., and Running, S.W. 1996. Implementation of a hierarchical +global vegetation classification in ecosystem function models. J. Veg. +Sci. 7:337-346. + +Niinemets, U., Kull, O., and Tenhunen, J.D. 1998. An analysis of light +effects on foliar morphology, physiology, and light interception in +temperate deciduous woody species of contrasting shade tolerance. Tree +Phys. 18:681-696. + +Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A +simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global +climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. + +Niu, G.-Y., and Yang, Z.-L. 2006. Effects of frozen soil on snowmelt +runoff and soil water storage at a continental scale. J. Hydrometeor. +7:937-952. + +Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., Gulden, L.E., and Su, H. 2007. +Development of a simple groundwater model for use in climate models and +evaluation with Gravity Recovery and Climate Experiment data. J. +Geophys. Res. 112:D07103. DOI:10.1029/2006JD007522. + +Niu, G.-Y., and Yang, Z.-L. 2007. An observation-based formulation of +snow cover fraction and its evaluation over large North American river +basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674. + +Nydal, R. and Lövseth, K. 1996. Carbon-14 Measurements In Atmospheric +CO2 From Northern And Southern Hemisphere Sites, 1962-1993, Carbon +Dioxide Information Analysis Center. + +Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and +nitrogen in the canopy of an annual herb, Xanthium canadense. Oecologia, +143: 517-526. + +Oke, T. 1987. Boundary Layer Climates (2:math:`{}^{nd}` edition). +Routledge, London and New York. + +Oleson, K.W., and Bonan, G.B. 2000. The effects of remotely-sensed plant +functional type and leaf area index on simulations of boreal forest +surface fluxes by the NCAR land surface model. J. Hydrometeor. +1:431-446. + +Oleson, K.W., Dai, Y., Bonan, G., Bosilovich, M., Dickinson, R., +Dirmeyer, P., Hoffman, F., Houser, P., Levis, S., Niu, G.-Y., Thornton, +P., Vertenstein, M., Yang, Z.-L., and Zeng. X. 2004. Technical +description of the Community Land Model (CLM). NCAR Technical Note +NCAR/TN-461+STR. National Center for Atmospheric Research, Boulder, +Colorado. 173 pp. + +Oleson, K.W., Niu, G.-Y., Yang, Z.-L., Lawrence, D.M., Thornton, P.E., +Lawrence, P.J., Stöckli, R., Dickinson, R.E., Bonan, G.B., Levis, S., +Dai, A., and Qian, T. 2008a. Improvements to the Community Land Model +and their impact on the hydrological cycle. J. Geophys. Res. 113:G01021. +DOI:10.1029/2007JG000563. + +Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Grimmond, +C.S.B. 2008b. An urban parameterization for a global climate model. 1. +Formulation and evaluation for two cities. J. Appl. Meteor. Clim. +47:1038-1060. + +Oleson, K.W., Bonan, G.B., Feddema, J., and Vertenstein, M. 2008c. An +urban parameterization for a global climate model. 2. Sensitivity to +input parameters and the simulated urban heat island in offline +simulations. J. Appl. Meteor. Clim. 47:1061-1076. + +Oleson, K.W., et al. 2010a. Technical description of version 4.0 of the +Community Land model (CLM). NCAR Technical Note NCAR/TN-478+STR, +National Center for Atmospheric Research, Boulder, CO, 257 pp. + +Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Kluzek, E. +2010b. Technical description of an urban parameterization for the +Community Land Model (CLMU). NCAR Technical Note NCAR/TN-480+STR, +National Center for Atmospheric Research, Boulder, CO, 169 pp. + +Olson, J.S., 1963. Energy storage and the balance of producers and +decomposers in ecological systems. Ecology 44:322-331. + +Olson, D.M., Dinerstein, E., Wikramanayake, E.D., Burgess, N.D., Powell, +G.V.N., Underwood, E.C., D’Amico, J.A., Itoua, I., Strand, H. E., +Morrison, J. C., Loucks, C. J., Allnutt, T. F., Ricketts, T. H., Kura, +Y., Lamoreux, J. F., Wettengel, W. W., Heda, P., and Kassem, K. R., +2001. Terrestrial ecoregions of the world a new map of life on earth, +Bioscience, 51, 933–938. + +Orchard, V.A. and Cook, F.J., 1983. Relationship between soil +respiration and soil moisture. Soil Biology and Biochemistry, 15: +447-453. + +Owen, P.R. 1964. Saltation of uniform grains in air. J. Fluid Mech\ *.* +20:225-242. + +Ozdogan, M., Rodell, M., Beaudoing, H.K., and Toll, D.L. 2010. +Simulating the effects of irrigation over the United States in a land +surface model based on satellite-derived agricultural data. Journal of +Hydrometeorology 11:171-184. + +Page, S.E., Siegert, F., Rieley, J.O., Boehm, H-D.V., Jaya, A., and +Limin, S. 2002. The amount of carbon released from peat and forest fires +in Indonesia in 1997. Nature 420:61-65. + +Panofsky, H.A., and Dutton, J.A. 1984. Atmospheric Turbulence: Models +and Methods for Engineering Applications. John Wiley and Sons, New York. + +Parton, W., Stewart, J. and Cole, C., 1988. Dynamics of C, N, P And S in +Grassland Soils - A Model. Biogeochemistry 5:109-131. + +Parton, W.J., et al. 1993. Observations and modeling of biomass and soil +organic matter dynamics for the grassland biome worlwide. Global +Biogeochemical Cycles 7:785-809. + +Parton, W. et al. 1996. Generalized model for N2 and N2O production from +nitrification and denitrification. Global Biogeochemical Cycles +10:401-412. + +Parton, W.J. et al. 2001. Generalized model for NOx and N2O emissions +from soils. J. Geophys. Res. 106(D15):17403-17419. + +Paterson, W.S.B., 1994. The Physics of Glaciers. Elsevier Science Inc., +New York, 480 pp. + +Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions +of boreal and arctic wetlands. Global Biogeochemical Cycles, 24(GB4009). + +Philip, J.R. 1957. Evaporation, and moisture and heat fields in the +soil. J. Meteor. 14:354-366. + +Piao, S.L., et al. 2012. The carbon budget of terrestrial ecosystems in +East Asia over the last two decades. Biogeosciences 9:3571-3586. + +Pivovarov, A.A., 1972. Thermal Conditions in Freezing Lakes and +Reservoirs. John Wiley, New York. + +Pollmer, W.G., Eberhard, D., Klein, D., and Dhillon, B.S. 1979. Genetic +control of nitrogen uptake and translocation in maize. Crop Sci. +19:82-86. + +Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global +monthly irrigated and rainfed crop areas around the year 2000: A new +high-resolution data set for agricultural and hydrological modeling. +Global Biogeochem. Cycles. 24, GB1011. DOI:10.1029/2008GB003435. + +Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P. 1992. +Numerical Recipes in FORTRAN: The Art of Scientific Computing. Cambridge +University Press, New York. + +Prigent, C., Papa, F., Aires, F., Rossow, W.B. and Matthews, E. 2007. +Global inundation dynamics inferred from multiple satellite +observations, 1993-2000. J. Geophys. Res. 112(D12). + +Pritchard, M.S., Bush, A.B.G., and Marshall, S.J. 2008. Neglecting +ice-atmosphere interactions underestimates ice sheet melt in +millennial-scale deglaciation simulations. Geophys. Res. Lett. ** +35:L01503. DOI:10.1029/2007GL031738. + +Qian, T., Dai, A., Trenberth, K.E., and Oleson, K.W. 2006. Simulation of +global land surface conditions from 1948 to 2004: Part I: Forcing data +and evaluations. J. Hydrometeor. 7:953-975. + +Ramankutty, N., and Foley, J. A., 1998. Characterizing patterns of +global land use: An analysis of global croplands data. Global +Biogeochemical Cycles, 12, 667-685. + +Ramankutty, N., Evan, A., Monfreda, C., and Foley, J.A. 2008. Farming +the Planet. Part 1: The Geographic Distribution of Global Agricultural +Lands in the Year 2000. Global Biogeochem. Cycles. 22:GB1003. +DOI:10.1029/2007GB002952. + +Randlett, D.L., Zak, D.R., Pregitzer, K.S., and Curtis, P.S. 1996. +Elevated atmospheric carbon dioxide and leaf litter chemistry: +Influences on microbial respiration and net nitrogen mineralization. +Soil Sci. Soc. Am. J. 60:1571-1577. + +Rastetter, E.B., Ryan, M.G., Shaver, G.R., Melillo, J.M., Nadelhoffer, +K.J., Hobbie, J.E., and Aber, J.D. 1991. A general biogeochemical model +describing the responses of the C and N cycles in terrestrial ecosystems +to changes in CO2, climate and N deposition. Tree Phys. 9:101-126. + +Rastner, P., Bolch, T., Mölg, N., Machguth, H., and Paul, F., 2012. The +first complete glacier inventory for the whole of Greenland, The +Cryosphere Discuss., 6, 2399-2436, 10.5194/tcd-6-2399-2012. + +Riley, W. J., Z. M. Subin, D. M. Lawrence, S. C. Swenson, M. S. Torn, L. +Meng, N. Mahowald, and P. Hess, 2011a. Barriers to predicting global +terrestrial methane fluxes: Analyses using a methane biogeochemistry +model integrated in CESM. Biogeosciences, 8, 1925–1953. +DOI:10.5194/bg-8-1925-2011. + +Riley, W.J. et al. 2011b. CLM4Me, a Methane Biogeochemistry Model +Integrated in CESM, Land and Biogeochemistry Model Working Group +Meeting, Boulder, CO. + +Ryan, M. G. 1991. A simple method for estimating gross carbon budgets +for vegetation in forest ecosystems. Tree Phys. 9:255-266. + +Running, S.W. and Coughlan, J.C., 1988. A general model of forest +ecosystem processes for regional applications. I. Hydrological balance, +canopy gas exchange and primary production processes. Ecological +Modelling, 42: 125-154. + +Running, S.W. et al., 1989. Mapping regional forest evapotranspiration +and photosynthesis by coupling satellite data with ecosystem simlation. +Ecology, 70: 1090-1101. + +Running, S.W. and Gower, S.T., 1991. FOREST BGC, A general model of +forest ecosystem processes for regional applications. II. Dynamic carbon +allocation and nitrogen budgets. Tree Physiology, 9: 147-160. + +Running, S.W. and Hunt, E.R., Jr., 1993. Generalization of a forest +ecosystem process model for other biomes, BIOME-BGC, and an +applicationfor global-scale models. In: J.R. Ehleringer and C. Field +(Editors), Scaling Physiological Processes: Leaf to Globe. Academic +Press, San Diego, CA, pp. 141-158. + +Sacks, W. J., Cook, B. I., Buenning, N., Levis, S., and Helkowski, J. H. +2009. Effects of global irrigation on the near-surface climate. Climate +Dyn., 33, 159–175. DOI:10.1007/s00382-008-0445-z. + +Saggar, S., Tate, K.R., Feltham, C.W., Childs, C.W. and Parshotam, A., +1994. Carbon turnover in a range of allophanic soils amended with +:math:`{}^{14}`\ C-labelled glucose. Soil Biology and Biochemistry, 26: +1263-1271. + +Sakaguchi, K., and Zeng, X. 2009. Effects of soil wetness, plant litter, +and under-canopy atmospheric stability on ground evaporation in the +Community Land Model (CLM3.5). J. Geophys. Res. 114:D01107. +DOI:10.1029/2008JD010834. + +Schaaf, C.B., Gao, F., Strahler, A.H., Lucht, W., Li, X., Tsang, T., +Strugnell, N.C., Zhang, X., Jin, Y., and Muller, J.-P. 2002. First +operational BRDF, albedo nadir reflectance products from MODIS. Remote +Sens. Environ. 83:135-148. + +Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. +Academic Press, London, 588 pp. + +Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity +in soils and cultures to water stress. Applied and Environmental +Microbiology 62:3203-3209. + +Segers, R., 1998. Methane production and methane consumption: a review +of processes underlying wetland methane fluxes. Biogeochemistry +41:23-51. + +Sellers, P.J. 1985. Canopy reflectance, photosynthesis and +transpiration. Int. J. Remote Sens. 6:1335-1372. + +Sellers, P.J., Mintz, Y., Sud, Y.C., and Dalcher, A. 1986. A simple +biosphere model (SiB) for use within general circulation models. J. +Atmos. Sci. 43:505-531. + +Sellers, P.J., Hall, F.G., Asrar, G., Strebel, D.E., and Murphy, R.E. +1988. The First ISLSCP Field Experiment (FIFE). Bull. Amer. Meteor. Soc. +69:22-27. + +Sellers, P.J., Berry, J.A., Collatz, G.J., Field, C.B., and Hall, F.G. +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. + +Sellers, P.J., et al. 1995. The Boreal Ecosystem-Atmosphere Study +(BOREAS): An overview and early results from the 1994 field year. Bull. +Amer. Meteor. Soc. 76:1549-1577. + +Sellers, P.J., Randall, D.A., Collatz, G.J., Berry, J.A., Field, C.B., +Dazlich, D.A., Zhang, C., Collelo, G.D., and Bounoua, L. 1996. A revised +land surface parameterization (SiB2) for atmospheric GCMs. Part I: Model +formulation. J. Climate 9:676-705. + +Shi, X., Mao, J., Thornton, P.E., and Huang, M. 2013. Spatiotemporal +patterns of evapotranspiration in response to multiple environmental +factors simulated by the Community Land Model. Environ. Res. Lett. +8:024012. + +Shiklomanov, I.A. 2000. Appraisal and assessment of world water +resources. Water International 25:11-32. + +Siebert, S., Döll, P., Hoogeveen, J., Faures, J.M., Frenken, K., Feick, +S., 2005. Development and validation of the global map of irrigation +areas. Hydrol Earth Syst Sc 9:535–547 + +Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen +redistribution during grain growth in wheat (Triticum avestivum L.). +Plant Physiol. 71:7-14. + +Smith, A.M.S., Wooster, M.J., Drake, N.A., Dipotso, F.M. and Perry, +G.L.W., 2005. Fire in African savanna: Testing the impact of incomplete +combustion on pyrogenic emissions estimates. Ecological Applications, +15: 1074-1082. + +Sollins, P., 1982. Input and decay of coarse woody debris in coniferous +stands in western Oregon and Washington. Canadian Journal of Forest +Research, 12: 18-28. + +Son, Y. and Gower, S.T., 1991. Aboveground nitrogen and phosphorus use +by five plantation-grown trees with different leaf longevities. +Biogeochemistry, 14: 167-191. + +Sørensen, L.H., 1981. Carbon-nitrogen relationships during the +humification of cellulose in soils containing different amounts of clay. +Soil Biology and Biochemistry, 13: 313-321. + +Sprugel, D.G., Ryan, M.G., Brooks, J.R., Vogt, K.A., and Martin, T.A. +1995. Respiration from the organ level to stand level. pp. 255-299. In: +W. K. Smith and T. M. Hinkley (editors) Resource Physiology of Conifers. +Academic Press, San Diego,CA. + +Stauffer, D., and Aharony, A. 1994. Introduction to Percolation Theory. +Taylor and Francis, London. + +Still, C.J., Berry, J.A., Collatz, G.J., and DeFries, R.S. 2003. Global +distribution of C3 and C4 vegetation: carbon cycle implications. Global +Biogeochem. Cycles 17:1006. DOI:10.1029/2001GB001807. + +Stöckli, R., Lawrence, D.M., Niu, G.-Y., Oleson, K.W., Thornton, P.E., +Yang, Z.-L., Bonan, G.B., Denning, A.S., and Running, S.W. 2008. Use of +FLUXNET in the Community Land Model development. J. Geophys. Res. +113:G01025. DOI:10.1029/2007JG000562. + +Strack, M., Kellner, E. and Waddington, J.M., 2006. Effect of entrapped +gas on peatland surface level fluctuations. Hydrological Processes +20:3611-3622. + +Strahler, A.H., Muchoney, D., Borak, J., Friedl, M., Gopal, S., Lambin, +E., and Moody. A. 1999. MODIS Land Cover Product: Algorithm Theoretical +Basis Document (Version 5.0). Boston University, Boston. + +Stull, R.B. 1988. An Introduction to Boundary Layer Meteorology. Kluwer +Academic Publishers, Dordrecht. + +Subin, Z.M., Riley, W.J. and Mironov, D. 2012a. Improved lake model for +climate simulations, J. Adv. Model. Earth Syst., 4, M02001. +DOI:10.1029/2011MS000072. + +Subin, Z.M., Murphy, L.N., Li, F., Bonfils, C. and Riley, W.J., 2012b. +Boreal lakes moderate seasonal and diurnal temperature variation and +perturb atmospheric circulation: analyses in the Community Earth System +Model 1 (CESM1). Tellus A, North America, 64. + +Sun, Y., Gu, L., and Dickinson, R. E. 2012. A numerical issue in +calculating the coupled carbon and water fluxes in a climate model, J. +Geophys. Res., 117, D22103. DOI:10.1029/2012JD018059. + +Swenson, S.C., Lawrence, D.M., and Lee, H. 2012. Improved Simulation of +the Terrestrial Hydrological Cycle in Permafrost Regions by the +Community Land Model. JAMES, 4, M08002. DOI:10.1029/2012MS000165. + +Swenson, S.C. and Lawrence, D.M. 2012. A New Fractional Snow Covered +Area Parameterization for the Community Land Model and its Effect on the +Surface Energy Balance. JGR, 117, D21107. DOI:10.1029/2012JD018178. + +Ta, C.T. and Weiland, R.T. 1992. Nitrogen partitioning in maize during +ear development. Crop Sci. 32:443-451. + +Tang, J.Y. and Riley, W.J. 2013. A new top boundary condition for +modeling surface diffusive exchange of a generic volatile tracer: +Theoretical analysis and application to soil evaporation. Hydrol. Earth +Syst. Sci. 17:873-893. + +Tarnocai, C., Kettles, I. M., and Lacelle, B., 2011. Peatlands of +Canada, Geological Survey of Canada, Open File 6561, CD-ROM. +DOI:10.495/288786. + +Taylor, B.R., Parkinson, D. and Parsons, W.F.J., 1989. Nitrogen and +lignin content as predictors of litter decay rates: A microcosm test. +Ecology, 70: 97-104. + +Thonicke, K., Venevsky, S., Sitch, S., and Cramer, W. 2001. The role of +fire disturbance for global vegetation dynamics: coupling fire into a +Dynamic Global Vegetation Model. Global Ecology and Biogeography +10:661-667. + +Thornton, P.E., 1998. Regional ecosystem simulation: combining surface- +and satellite-based observations to study linkages between terrestrial +energy and mass budgets. Ph.D. Thesis, The University of Montana, +Missoula, 280 pp. + +Thornton, P.E., Law, B.E., Gholz, H.L., Clark, K.L., Falge, E., +Ellsworth, D.S., Goldstein, A.H., Monson, R.K., Hollinger, D., Falk, M., +Chen, J., and Sparks, J.P. 2002. Modeling and measuring the effects of +disturbance history and climate on carbon and water budgets in evergreen +needleleaf forests. Agric. For. Meteor. 113:185-222. + +Thornton, P.E., and Rosenbloom, N.A. 2005. Ecosystem model spin-up: +estimating steady state conditions in a coupled terrestrial carbon and +nitrogen cycle model. Ecological Modelling 189:25-48. + +Thornton, P.E., and Zimmermann, N.E. 2007. An improved canopy +integration scheme for a land surface model with prognostic canopy +structure. J. Climate 20:3902-3923. + +Thornton, P.E., Lamarque, J.-F., Rosenbloom, N.A., and Mahowald, N.M. +2007. Influence of carbon-nitrogen cycle coupling on land model response +to CO\ :math:`{}_{2}` fertilization and climate variability. Global +Biogeochem. Cycles 21:GB4018. + +Thornton, P.E., Doney, S.C., Lindsay, K., Moore, J.K., Mahowald, N., +Randerson, J.T., Fung, I., Lamarque, J.F., Feddema, J.J., and Lee, Y.H. +2009. Carbon-nitrogen interactions regulate climate-carbon cycle +feedbacks: results from an atmosphere-ocean general circulation model. +Biogeosci. 6:2099-2120. + +Tian, H. et al. 2010. Spatial and temporal patterns of CH4 and N2O +fluxes in terrestrial ecosystems of North America during 1979-2008: +application of a global biogeochemistry model. Biogeosciences +7:2673-2694. + +Toon, O.B., McKay, C.P., Ackerman, T.P., and Santhanam, K. 1989. Rapid +calculation of radiative heating rates and photodissociation rates in +inhomogeneous multiple scattering atmospheres. J. Geophys. Res. +94(D13):16,287-16,301. + +Turetsky, M.R., Wieder, R.K., Halsey, L.A., and Vitt, D.H. 2002. Current +disturbance and the diminishing peatland carbon sink. Geophys. Res. +Lett. 29:1526. DOI:10.1029/2001GL014000. + +Turetsky, M.R., Amiro, B.D., Bosch, E., andBhatti, J.S. 2004. Historical +burn area in western Canadian peatlands and its relationship to fire +weather indices. Global Biogeochem. Cycles 18:GB4014. +DOI:10.1029/2004GB002222. + +Turnbull, J.C. et al. 2007. A new high precision (CO2)-C-14 time series +for North American continental air. Journal of Geophysical +Research-Atmospheres 112(D11). + +Tye, A.M., et al. 2005. The fate of N-15 added to high Arctic tundra to +mimic increased inputs of atmospheric nitrogen released from a melting +snowpack. Global Change Biology 11:1640-1654. + +Unland, H.E., Houser, P.R., Shuttleworth, W.J., and Yang, Z.-L. 1996. +Surface flux measurement and modeling at a semi-arid Sonoran Desert +site. Agric. For. Meteor. 82:119-153. + +UNSTAT, 2005. National Accounts Main Aggregates Database, United Nations +Statistics Division. + +Vallano, D.M. and Sparks, J.P. 2007. Quantifying foliar uptake of +gaseous itrogen dioxide using enriched foliar +:math:`\deltaup`\ :math:`{}^{15 }`\ N values. New Phytologist +177:946-955. + +van der Werf, G.R., Randerson, J.T., Giglio, L., Collatz, G.J., Mu, M., +Kasibhatla, S.P., Morton, D.C., DeFries, R.S., Jin, Y., van Leeuwen, +T.T. 2010. Global fire emissions and the contribution of deforestation, +savanna, forest, agricultural, and peat fires (1997-2009) Atmos. Chem. +Phys. 10:11707-11735. + +van Veen, J.A., Ladd, J.N. and Frissel, M.J., 1984. Modelling C and N +turnover through the microbial biomass in soil. Plant and Soil, 76: +257-274. + +Van Vuuren, D.P., Lucas, P.S., and Hilderink, H.B.M., 2006. Downscaling +drivers of global environmental change: enabling use of global SRES +scenarios at the national and grid levels, Report 550025001, Netherlands +Environmental Assessment Agency, 45 pp. + +Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: +effects of size, competition and site fertility on growth allocation and +production. Tree Phys. 25:17-30. + +Verdin, K. L., and S. K. Greenlee, 1996. Development of continental +scale digital elevation models and extraction of hydrographic features, +paper presented at the Third International Conference/Workshop on +Integrating GIS and Environmental Modeling, Santa Fe, New Mexico, 21–26 +January, Natl. Cent. for Geogr. Inf. and Anal., Santa Barbara, Calif. + +Viovy, N. 2011. CRUNCEP dataset. [Description available at +http://dods.extra.cea.fr/data/p529viov/cruncep/readme.htm. Data +available at +http://dods.extra.cea.fr/store/p529viov/cruncep/V4\_1901\_2011/]. + +Vitousek, P.M., and Howarth, R.W. 1991. Nitrogen limitation on land and +in the sea: How can it occur? Biogeochem. 13:87-115. + +Walter, B.P., Heimann, M. and Matthews, E., 2001. Modeling modern +methane emissions from natural wetlands 1. Model description and +results. J. Geophys. Res. 106(D24):34189-34206. + +Wania, R., Ross, I. and Prentice, I.C. 2009. Integrating peatlands and +permafrost into a dynamic global vegetation model: 2. Evaluation and +sensitivity of vegetation and carbon cycle processes. Global Biogeochem. +Cycles 23. + +Wania, R., Ross, I. and Prentice, I.C. 2010. Implementation and +evaluation of a new methane model within a dynamic global vegetation +model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions +3:1-59. + +Wang, A., and Zeng, X. 2009. Improving the treatment of vertical snow +burial fraction over short vegetation in the NCAR CLM3. Adv. Atmos. Sci. +26:877-886. DOI:10.1007/s00376-009-8098-3. + +White, M.A., Thornton, P.E., and Running, S.W. 1997. A continental +phenology model for monitoring vegetation responses to interannual +climatic variability. Global Biogeochem. Cycles 11:217-234. + +White, M.A., Thornton, P.E., Running, S.W., and Nemani, R.R. 2000. +Parameterization and sensitivity analysis of the Biome-BGC terrestrial +ecosystem model: net primary production controls. Earth Interactions +4:1-85. + +Wiscombe, W.J., and Warren, S.G. 1980. A model for the spectral albedo +of snow. I. Pure snow. J. Atmos. Sci. 37:2712-2733. + +Wood, E.F., Lettenmaier, D.P., and Zartarian, V.G. 1992. A land-surface +hydrology parameterization with subgrid variability for general +circulation models. J. Geophys. Res. 97(D3):2717–2728. +DOI:10.1029/91JD01786. + +World Bank, 2004. World development indicators 2004, Oxford University +Press, New York, 416 pp. + +Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and +temperature model. Unpublished manuscript. + +Zender, C.S., Bian, H., and Newman, D. 2003. Mineral dust entrainment +and deposition (DEAD) model: Description and 1990s dust climatology. ** +J. Geophys. Res\ *.* 108(D14):4416. DOI:10.1029/2002JD002775. + +Zeng, X., and Dickinson, R.E. 1998. Effect of surface sublayer on +surface skin temperature and fluxes. J.Climate 11:537-550. + +Zeng, X., Zhao, M., and Dickinson, R.E. 1998. Intercomparison of bulk +aerodynamic algorithms for the computation of sea surface fluxes using +the TOGA COARE and TAO data. J. Climate 11:2628-2644. + +Zeng, X. 2001. Global vegetation root distribution for land modeling. J. +Hydrometeor. 2:525-530. + +Zeng, X., Shaikh, M., Dai, Y., Dickinson, R.E., and Myneni, R. 2002. +Coupling of the Common Land Model to the NCAR Community Climate Model. +J. Climate 15:1832-1854. + +Zeng, X., Dickinson, R.E., Barlage, M., Dai, Y., Wang, G., and Oleson, +K. 2005. Treatment of under-canopy turbulence in land models. J. Climate +18:5086-5094. + +Zeng, X., and Wang, A. 2007. Consistent parameterization of roughness +length and displacement height for sparse and dense canopies in land +models. J. Hydrometeor. 8:730-737. + +Zeng, X., and Decker, M. 2009. Improving the numerical solution of soil +moisture-based Richards equation for land models with a deep or shallow +water table. J. Hydrometeor. 10:308-319. + +Zeng, X., Zeng, X., and Barlage, M. 2008. Growing temperate shrubs over +arid and semiarid regions in the Community Land Model - Dynamic Global +Vegetation Model. Global Biogeochem. Cycles 22:GB3003. +DOI:10.1029/2007GB003014. + +Zhang, Y., Li, C.S., Trettin, C.C., Li, H. and Sun, G., 2002. An +integrated model of soil, hydrology, and vegetation for carbon dynamics +in wetland ecosystems. Global Biogeochemical Cycles 16. +DOI:10.1029/2001GB001838. + +Zhuang, Q., et al. 2004. Methane fluxes between terrestrial ecosystems +and the atmosphere at northern high latitudes during the past century: A +retrospective analysis with a process-based biogeochemistry model. +Global Biogeochemical Cycles 18. DOI:10.1029/2004GB002239. + +Zilitinkevich, S.S. 1970. Dynamics of the Atmospheric Boundary Layer. +Leningrad Gidrometeor. diff --git a/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst b/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst new file mode 100644 index 0000000000..cc47ceedf1 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst @@ -0,0 +1,1137 @@ +Surface Albedos +================== + +Canopy Radiative Transfer +----------------------------- + +Radiative transfer within vegetative canopies is calculated from the +two-stream approximation of Dickinson (1983) and Sellers (1985) as +described by Bonan (1996) + +.. math:: + :label: 3.1 + + -\bar{\mu }\frac{dI\, \uparrow }{d\left(L+S\right)} +\left[1-\left(1-\beta \right)\omega \right]I\, \uparrow -\omega \beta I\, \downarrow =\omega \bar{\mu }K\beta _{0} e^{-K\left(L+S\right)} + +.. math:: + :label: 3.2 + + \bar{\mu }\frac{dI\, \downarrow }{d\left(L+S\right)} +\left[1-\left(1-\beta \right)\omega \right]I\, \downarrow -\omega \beta I\, \uparrow =\omega \bar{\mu }K\left(1-\beta _{0} \right)e^{-K\left(L+S\right)} + +where :math:`I\, \uparrow` and :math:`I\, \downarrow` are the upward +and downward diffuse radiative fluxes per unit incident flux, +:math:`K={G\left(\mu \right)\mathord{\left/ {\vphantom {G\left(\mu \right) \mu }} \right. \kern-\nulldelimiterspace} \mu }` +is the optical depth of direct beam per unit leaf and stem area, +:math:`\mu` is the cosine of the zenith angle of the incident beam, +:math:`G\left(\mu \right)` is the relative projected area of leaf and +stem elements in the direction :math:`\cos ^{-1} \mu` , +:math:`\bar{\mu }` is the average inverse diffuse optical depth per unit +leaf and stem area, :math:`\omega` is a scattering coefficient, +:math:`\beta` and :math:`\beta _{0}` are upscatter parameters for +diffuse and direct beam radiation, respectively, :math:`L` is the +exposed leaf area index (section 2.1.4), and :math:`S` is the exposed +stem area index (section 2.1.4). Given the direct beam albedo +:math:`\alpha _{g,\, \Lambda }^{\mu }` and diffuse albedo +:math:`\alpha _{g,\, \Lambda }` of the ground (section 3.2), these +equations are solved to calculate the fluxes, per unit incident flux, +absorbed by the vegetation, reflected by the vegetation, and transmitted +through the vegetation for direct and diffuse radiation and for visible +(:math:`<` 0.7\ :math:`\mu {\rm m}`) and near-infrared +(:math:`ge` 0.7\ :math:`\mu {\rm m}`) wavebands. The absorbed +radiation is partitioned to sunlit and shaded fractions of the canopy. +The optical parameters :math:`G\left(\mu \right)`, :math:`\bar{\mu }`, +:math:`\omega`, :math:`\beta`, and :math:`\beta _{0}` are calculated +based on work in Sellers (1985) as follows. + +The relative projected area of leaves and stems in the direction +:math:`\cos ^{-1} \mu` is + +.. math:: + :label: 3.3 + + G\left(\mu \right)=\phi _{1} +\phi _{2} \mu + +where :math:`\phi _{1} ={\rm 0.5}-0.633\chi _{L} -0.33\chi _{L}^{2}` +and :math:`\phi _{2} =0.877\left(1-2\phi _{1} \right)` for +:math:`-0.4\le \chi _{L} \le 0.6`. :math:`\chi _{L}` is the departure +of leaf angles from a random distribution and equals +1 for horizontal +leaves, 0 for random leaves, and –1 for vertical leaves. + +The average inverse diffuse optical depth per unit leaf and stem area is + +.. math:: + :label: 3.4 + + \bar{\mu }=\int _{0}^{1}\frac{\mu '}{G\left(\mu '\right)} d\mu '=\frac{1}{\phi _{2} } \left[1-\frac{\phi _{1} }{\phi _{2} } \ln \left(\frac{\phi _{1} +\phi _{2} }{\phi _{1} } \right)\right] + +where :math:`\mu '` is the direction of the scattered flux. + +The optical parameters :math:`\omega` , :math:`\beta` , and +:math:`\beta _{0}` , which vary with wavelength (:math:`\Lambda` ), are +weighted combinations of values for vegetation and snow. The model +determines that snow is on the canopy if :math:`T_{v} \le T_{f}` , where +:math:`T_{v}` is the vegetation temperature (K) (Chapter 5) and +:math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). In +this case, the optical parameters are + +.. math:: + :label: 3.5 + + \omega _{\Lambda } =\omega _{\Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} f_{wet} + +.. math:: + :label: 3.6 + + \omega _{\Lambda } \beta _{\Lambda } =\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} \beta _{\Lambda }^{sno} f_{wet} + +.. math:: + :label: 3.7 + + \omega _{\Lambda } \beta _{0,\, \Lambda } =\omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} \beta _{0,\, \Lambda }^{sno} f_{wet} + +where :math:`f_{wet}` is the wetted fraction of the canopy (section +7.1). The snow and vegetation weights are applied to the products +:math:`\omega _{\Lambda } \beta _{\Lambda }` and +:math:`\omega _{\Lambda } \beta _{0,\, \Lambda }` because these +products are used in the two-stream equations. If there is no snow on +the canopy, + +.. math:: + :label: 3.8 + + \omega _{\Lambda } =\omega _{\Lambda }^{veg} + +.. math:: + :label: 3.9 + + \omega _{\Lambda } \beta _{\Lambda } =\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} + +.. math:: + :label: 3.10 + + \omega _{\Lambda } \beta _{0,\, \Lambda } =\omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} . + +For vegetation, +:math:`\omega _{\Lambda }^{veg} =\alpha _{\Lambda } +\tau _{\Lambda }` . +:math:`\alpha _{\Lambda }` is a weighted combination of the leaf and +stem reflectances +(:math:`\alpha _{\Lambda }^{leaf} ,\alpha _{\Lambda }^{stem}` ) + +.. math:: + :label: 3.11 + + \alpha _{\Lambda } =\alpha _{\Lambda }^{leaf} w_{leaf} +\alpha _{\Lambda }^{stem} w_{stem} + +where +:math:`w_{leaf} ={L\mathord{\left/ {\vphantom {L \left(L+S\right)}} \right. \kern-\nulldelimiterspace} \left(L+S\right)}` +and +:math:`w_{stem} ={S\mathord{\left/ {\vphantom {S \left(L+S\right)}} \right. \kern-\nulldelimiterspace} \left(L+S\right)}` . +:math:`\tau _{\Lambda }` is a weighted combination of the leaf and stem transmittances (:math:`\tau _{\Lambda }^{leaf}, \tau _{\Lambda }^{stem}`) + +.. math:: + :label: 3.12 + + \tau _{\Lambda } =\tau _{\Lambda }^{leaf} w_{leaf} +\tau _{\Lambda }^{stem} w_{stem} . + +The upscatter for diffuse radiation is + +.. math:: + :label: ZEqnNum472968 + + \omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} =\frac{1}{2} \left[\alpha _{\Lambda } +\tau _{\Lambda } +\left(\alpha _{\Lambda } -\tau _{\Lambda } \right)\cos ^{2} \bar{\theta }\right] + +where :math:`\bar{\theta }` is the mean leaf inclination angle relative +to the horizontal plane (i.e., the angle between leaf normal and local +vertical) (Sellers 1985). Here, :math:`\cos \bar{\theta }` is +approximated by + +.. math:: + :label: ZEqnNum720349 + + \cos \bar{\theta }=\frac{1+\chi _{L} }{2} + +Using this approximation, for vertical leaves (:math:`\chi _{L} =-1`, +:math:`\bar{\theta }=90^{{\rm o}}` ), +:math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} =0.5\left(\alpha _{\Lambda } +\tau _{\Lambda } \right)`, +and for horizontal leaves (:math:`\chi _{L} =1`, +:math:`\bar{\theta }=0^{{\rm o}}` ) , +:math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} =\alpha _{\Lambda }` , +which agree with both Dickinson (1983) and Sellers (1985). For random +(spherically distributed) leaves (:math:`\chi _{L} =0`, +:math:`\bar{\theta }=60^{{\rm o}}` ), the approximation yields +:math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} ={5\mathord{\left/ {\vphantom {5 8}} \right. \kern-\nulldelimiterspace} 8} \alpha _{\Lambda } +{3\mathord{\left/ {\vphantom {3 8}} \right. \kern-\nulldelimiterspace} 8} \tau _{\Lambda }` +whereas the approximate solution of Dickinson (1983) is +:math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} ={2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} \alpha _{\Lambda } +{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} \tau _{\Lambda }` . +This discrepancy arises from the fact that a spherical leaf angle +distribution has a true mean leaf inclination +:math:`\bar{\theta }\approx 57` (Campbell and Norman 1998) in equation , +while :math:`\bar{\theta }=60` in equation . The upscatter for direct +beam radiation is + +.. math:: + :label: 3.15 + + \omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} =\frac{1+\bar{\mu }K}{\bar{\mu }K} a_{s} \left(\mu \right)_{\Lambda } + +where the single scattering albedo is + +.. math:: + :label: 3.16 + + \begin{array}{rcl} {a_{s} \left(\mu \right)_{\Lambda } } & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \int _{0}^{1}\frac{\mu 'G\left(\mu \right)}{\mu G\left(\mu '\right)+\mu 'G\left(\mu \right)} d\mu '} \\ {} & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \frac{G\left(\mu \right)}{\mu \phi _{2} +G\left(\mu \right)} \left[1-\frac{\mu \phi _{1} }{\mu \phi _{2} +G\left(\mu \right)} \ln \left(\frac{\mu \phi _{1} +\mu \phi _{2} +G\left(\mu \right)}{\mu \phi _{1} } \right)\right].} \end{array} + +The upward diffuse fluxes per unit incident direct beam and diffuse flux +(i.e., the surface albedos) are + +.. math:: + :label: 3.17 + + I\, \uparrow _{\Lambda }^{\mu } =\frac{h_{1} }{\sigma } +h_{2} +h_{3} + +.. math:: + :label: 3.18 + + I\, \uparrow _{\Lambda } =h_{7} +h_{8} . + +The downward diffuse fluxes per unit incident direct beam and diffuse +radiation, respectively, are + +.. math:: + :label: 3.19 + + I\, \downarrow _{\Lambda }^{\mu } =\frac{h_{4} }{\sigma } e^{-K\left(L+S\right)} +h_{5} s_{1} +\frac{h_{6} }{s_{1} } + +.. math:: + :label: 3.20 + + I\, \downarrow _{\Lambda } =h_{9} s_{1} +\frac{h_{10} }{s_{1} } . + +With reference to Figure 4.1, the direct beam flux transmitted through +the canopy, per unit incident flux, is :math:`e^{-K\left(L+S\right)}` , +and the direct beam and diffuse fluxes absorbed by the vegetation, per +unit incident flux, are + +.. math:: + :label: 3.21 + + \vec{I}_{\Lambda }^{\mu } =1-I\, \uparrow _{\Lambda }^{\mu } -\left(1-\alpha _{g,\, \Lambda } \right)I\, \downarrow _{\Lambda }^{\mu } -\left(1-\alpha _{g,\, \Lambda }^{\mu } \right)e^{-K\left(L+S\right)} + +.. math:: + :label: 3.22 + + \vec{I}_{\Lambda } =1-I\, \uparrow _{\Lambda } -\left(1-\alpha _{g,\, \Lambda } \right)I\, \downarrow _{\Lambda } . + +These fluxes are partitioned to the sunlit and shaded canopy using an +analytical solution to the two-stream approximation for sunlit and +shaded leaves (Dai et al. 2004), as described by Bonan et al. (2011). +The absorption of direct beam radiation by sunlit leaves is + +.. math:: + :label: 3.23 + + \vec{I}_{sun,\Lambda }^{\mu } =\left(1-\omega _{\Lambda } \right)\left[1-s_{2} +\frac{1}{\bar{\mu }} \left(a_{1} +a_{2} \right)\right] + +and for shaded leaves is + +.. math:: + :label: 3.24 + + \vec{I}_{sha,\Lambda }^{\mu } =\vec{I}_{\Lambda }^{\mu } -\vec{I}_{sun,\Lambda }^{\mu } + +with + +.. math:: + :label: 3.25 + + a_{1} =\frac{h_{1} }{\sigma } \left[\frac{1-s_{2}^{2} }{2K} \right]+h_{2} \left[\frac{1-s_{2} s_{1} }{K+h} \right]+h_{3} \left[\frac{1-{s_{2} \mathord{\left/ {\vphantom {s_{2} s_{1} }} \right. \kern-\nulldelimiterspace} s_{1} } }{K-h} \right] + +.. math:: + :label: 3.26 + + a_{2} =\frac{h_{4} }{\sigma } \left[\frac{1-s_{2}^{2} }{2K} \right]+h_{5} \left[\frac{1-s_{2} s_{1} }{K+h} \right]+h_{6} \left[\frac{1-{s_{2} \mathord{\left/ {\vphantom {s_{2} s_{1} }} \right. \kern-\nulldelimiterspace} s_{1} } }{K-h} \right]. + +For diffuse radiation, the absorbed radiation for sunlit leaves is + +.. math:: + :label: 3.27 + + \vec{I}_{sun,\Lambda }^{} =\left[\frac{1-\omega _{\Lambda } }{\bar{\mu }} \right]\left(a_{1} +a_{2} \right) + +and for shaded leaves is + +.. math:: + :label: 3.28 + + \vec{I}_{sha,\Lambda }^{} =\vec{I}_{\Lambda }^{} -\vec{I}_{sun,\Lambda }^{} + +with + +.. math:: + :label: 3.29 + + a_{1} =h_{7} \left[\frac{1-s_{2} s_{1} }{K+h} \right]+h_{8} \left[\frac{1-{s_{2} \mathord{\left/ {\vphantom {s_{2} s_{1} }} \right. \kern-\nulldelimiterspace} s_{1} } }{K-h} \right] + +.. math:: + :label: 3.30 + + a_{2} =h_{9} \left[\frac{1-s_{2} s_{1} }{K+h} \right]+h_{10} \left[\frac{1-{s_{2} \mathord{\left/ {\vphantom {s_{2} s_{1} }} \right. \kern-\nulldelimiterspace} s_{1} } }{K-h} \right]. + +The parameters :math:`h_{1}` –:math:`h_{10}` , :math:`\sigma` , +:math:`h`, :math:`s_{1}` , and :math:`s_{2}` are from Sellers (1985) +[note the error in :math:`h_{4}` in Sellers (1985)]: + +.. math:: + :label: 3.31 + + b=1-\omega _{\Lambda } +\omega _{\Lambda } \beta _{\Lambda } + +.. math:: + :label: 3.32 + + c=\omega _{\Lambda } \beta _{\Lambda } + +.. math:: + :label: 3.33 + + d=\omega _{\Lambda } \bar{\mu }K\beta _{0,\, \Lambda } + +.. math:: + :label: 3.34 + + f=\omega _{\Lambda } \bar{\mu }K\left(1-\beta _{0,\, \Lambda } \right) + +.. math:: + :label: 3.35 + + h=\frac{\sqrt{b^{2} -c^{2} } }{\bar{\mu }} + +.. math:: + :label: 3.36 + + \sigma =\left(\bar{\mu }K\right)^{2} +c^{2} -b^{2} + +.. math:: + :label: 3.37 + + u_{1} =b-{c\mathord{\left/ {\vphantom {c \alpha _{g,\, \Lambda }^{\mu } }} \right. \kern-\nulldelimiterspace} \alpha _{g,\, \Lambda }^{\mu } } {\rm \; or\; }u_{1} =b-{c\mathord{\left/ {\vphantom {c \alpha _{g,\, \Lambda } }} \right. \kern-\nulldelimiterspace} \alpha _{g,\, \Lambda } } + +.. math:: + :label: 3.38 + + u_{2} =b-c\alpha _{g,\, \Lambda }^{\mu } {\rm \; or\; }u_{2} =b-c\alpha _{g,\, \Lambda } + +.. math:: + :label: 3.39 + + u_{3} =f+c\alpha _{g,\, \Lambda }^{\mu } {\rm \; or\; }u_{3} =f+c\alpha _{g,\, \Lambda } + +.. math:: + :label: 3.40 + + s_{1} =\exp \left\{-\min \left[h\left(L+S\right),40\right]\right\} + +.. math:: + :label: 3.41 + + s_{2} =\exp \left\{-\min \left[K\left(L+S\right),40\right]\right\} + +.. math:: + :label: 3.42 + + p_{1} =b+\bar{\mu }h + +.. math:: + :label: 3.43 + + p_{2} =b-\bar{\mu }h + +.. math:: + :label: 3.44 + + p_{3} =b+\bar{\mu }K + +.. math:: + :label: 3.45 + + p_{4} =b-\bar{\mu }K + +.. math:: + :label: 3.46 + + d_{1} =\frac{p_{1} \left(u_{1} -\bar{\mu }h\right)}{s_{1} } -p_{2} \left(u_{1} +\bar{\mu }h\right)s_{1} + +.. math:: + :label: 3.47 + + d_{2} =\frac{u_{2} +\bar{\mu }h}{s_{1} } -\left(u_{2} -\bar{\mu }h\right)s_{1} + +.. math:: + :label: 3.48 + + h_{1} =-dp_{4} -cf + +.. math:: + :label: 3.49 + + h_{2} =\frac{1}{d_{1} } \left[\left(d-\frac{h_{1} }{\sigma } p_{3} \right)\frac{\left(u_{1} -\bar{\mu }h\right)}{s_{1} } -p_{2} \left(d-c-\frac{h_{1} }{\sigma } \left(u_{1} +\bar{\mu }K\right)\right)s_{2} \right] + +.. math:: + :label: 3.50 + + h_{3} =\frac{-1}{d_{1} } \left[\left(d-\frac{h_{1} }{\sigma } p_{3} \right)\left(u_{1} +\bar{\mu }h\right)s_{1} -p_{1} \left(d-c-\frac{h_{1} }{\sigma } \left(u_{1} +\bar{\mu }K\right)\right)s_{2} \right] + +.. math:: + :label: 3.51 + + h_{4} =-fp_{3} -cd + +.. math:: + :label: 3.52 + + h_{5} =\frac{-1}{d_{2} } \left[\left(\frac{h_{4} \left(u_{2} +\bar{\mu }h\right)}{\sigma s_{1} } \right)+\left(u_{3} -\frac{h_{4} }{\sigma } \left(u_{2} -\bar{\mu }K\right)\right)s_{2} \right] + +.. math:: + :label: 3.53 + + h_{6} =\frac{1}{d_{2} } \left[\frac{h_{4} }{\sigma } \left(u_{2} -\bar{\mu }h\right)s_{1} +\left(u_{3} -\frac{h_{4} }{\sigma } \left(u_{2} -\bar{\mu }K\right)\right)s_{2} \right] + +.. math:: + :label: 3.54 + + h_{7} =\frac{c\left(u_{1} -\bar{\mu }h\right)}{d_{1} s_{1} } + +.. math:: + :label: 3.55 + + h_{8} =\frac{-c\left(u_{1} +\bar{\mu }h\right)s_{1} }{d_{1} } + +.. math:: + :label: 3.56 + + h_{9} =\frac{u_{2} +\bar{\mu }h}{d_{2} s_{1} } + +.. math:: + :label: 3.57 + + h_{10} =\frac{-s_{1} \left(u_{2} -\bar{\mu }h\right)}{d_{2} } . + +Plant functional type optical properties (Table 3.1) for trees and +shrubs are from Dorman and Sellers (1989). Leaf and stem optical +properties (placeVIS and NIR reflectance and transmittance) were derived +for grasslands and crops from full optical range spectra of measured +optical properties (Asner et al. 1998). Optical properties for +intercepted snow (Table 3.2) are from Sellers et al. (1986). + +Table 3.1. Plant functional type optical properties + ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Plant Functional Type | :math:`\chi _{L}` | :math:`\alpha _{vis}^{leaf}` | :math:`\alpha _{nir}^{leaf}` | :math:`\alpha _{vis}^{stem}` | :math:`\alpha _{nir}^{stem}` | :math:`\tau _{vis}^{leaf}` | :math:`\tau _{nir}^{leaf}` | :math:`\tau _{vis}^{stem}` | :math:`\tau _{nir}^{stem}` | ++==================================+======================+=================================+=================================+=================================+=================================+===============================+===============================+===============================+===============================+ +| NET Temperate | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| NET Boreal | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| NDT Boreal | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BET Tropical | 0.10 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BET temperate | 0.10 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BDT tropical | 0.01 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BDT temperate | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BDT boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BES temperate | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BDS temperate | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| BDS boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| C\ :math:`{}_{3}` arctic grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| C\ :math:`{}_{3}` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| C\ :math:`{}_{4}` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Crop R | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Crop I | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Corn R | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Corn I | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Temp Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Temp Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Winter Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Winter Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Soybean R | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ +| Soybean I | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | ++----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + +Table 3.2. Intercepted snow optical properties + ++-----------------------------+-------+-------+ +| Parameter | vis | nir | ++-----------------------------+-------+-------+ +| :math:`\omega ^{sno}` | 0.8 | 0.4 | ++-----------------------------+-------+-------+ +| :math:`\beta ^{sno}` | 0.5 | 0.5 | ++-----------------------------+-------+-------+ +| :math:`\beta _{0}^{sno}` | 0.5 | 0.5 | ++-----------------------------+-------+-------+ + +Ground Albedos +------------------ + +The overall direct beam :math:`\alpha _{g,\, \Lambda }^{\mu }` and +diffuse :math:`\alpha _{g,\, \Lambda }` ground albedos are weighted +combinations of “soil†and snow albedos + +.. math:: + :label: 3.58 + + \alpha _{g,\, \Lambda }^{\mu } =\alpha _{soi,\, \Lambda }^{\mu } \left(1-f_{sno} \right)+\alpha _{sno,\, \Lambda }^{\mu } f_{sno} + +.. math:: + :label: 3.59 + + \alpha _{g,\, \Lambda } =\alpha _{soi,\, \Lambda } \left(1-f_{sno} \right)+\alpha _{sno,\, \Lambda } f_{sno} + +where :math:`f_{sno}` is the fraction of the ground covered with snow +(section 7.2.1). + +:math:`\alpha _{soi,\, \Lambda }^{\mu }` and +:math:`\alpha _{soi,\, \Lambda }` vary with glacier, lake, wetland, and +soil surfaces. Glacier albedos are from Paterson (1994) + +.. math:: \alpha _{soi,\, vis}^{\mu } =\alpha _{soi,\, vis} =0.6 + +.. math:: \alpha _{soi,\, nir}^{\mu } =\alpha _{soi,\, nir} =0.4. + +Unfrozen lake and wetland albedos depend on the cosine of the solar +zenith angle :math:`\mu` + +.. math:: + :label: 3.60 + + \alpha _{soi,\, \Lambda }^{\mu } =\alpha _{soi,\, \Lambda } =0.05\left(\mu +0.15\right)^{-1} . + +Frozen lake and wetland albedos are from NCAR LSM (Bonan 1996) + +.. math:: \alpha _{soi,\, vis}^{\mu } =\alpha _{soi,\, vis} =0.60 + +.. math:: \alpha _{soi,\, nir}^{\mu } =\alpha _{soi,\, nir} =0.40. + +As in NCAR LSM (Bonan 1996), soil albedos vary with color class + +.. math:: + :label: 3.61 + + \alpha _{soi,\, \Lambda }^{\mu } =\alpha _{soi,\, \Lambda } =\left(\alpha _{sat,\, \Lambda } +\Delta \right)\le \alpha _{dry,\, \Lambda } + +where :math:`\Delta` depends on the volumetric water content of the +first soil layer :math:`\theta _{1}` (section 7.4) as +:math:`\Delta =0.11-0.40\theta _{1} >0`, and +:math:`\alpha _{sat,\, \Lambda }` and +:math:`\alpha _{dry,\, \Lambda }` are albedos for saturated and dry +soil color classes (Table 3.3). + +CLM soil colors are prescribed so that they best reproduce observed +MODIS local solar noon surface albedo values at the CLM grid cell +following the methods of Lawrence and Chase (2007). The soil colors are +fitted over the range of 20 soil classes shown in Table 3.3 and compared +to the MODIS monthly local solar noon all-sky surface albedo as +described in Strahler et al. (1999) and Schaaf et al. (2002). The CLM +two-stream radiation model was used to calculate the model equivalent +surface albedo using climatological monthly soil moisture along with the +vegetation parameters of PFT fraction, LAI, and SAI. The soil color that +produced the closest all-sky albedo in the two-stream radiation model +was selected as the best fit for the month. The fitted monthly soil +colors were averaged over all snow-free months to specify a +representative soil color for the grid cell. In cases where there was no +snow-free surface albedo for the year, the soil color derived from +snow-affected albedo was used to give a representative soil color that +included the effects of the minimum permanent snow cover. + +Table 3.3. Dry and saturated soil albedos + ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| Color Class | vis | nir | vis | nir | Color Class | vis | nir | vis | nir | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 1 | 0.36 | 0.61 | 0.25 | 0.50 | 11 | 0.24 | 0.37 | 0.13 | 0.26 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 2 | 0.34 | 0.57 | 0.23 | 0.46 | 12 | 0.23 | 0.35 | 0.12 | 0.24 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 3 | 0.32 | 0.53 | 0.21 | 0.42 | 13 | 0.22 | 0.33 | 0.11 | 0.22 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 4 | 0.31 | 0.51 | 0.20 | 0.40 | 14 | 0.20 | 0.31 | 0.10 | 0.20 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 5 | 0.30 | 0.49 | 0.19 | 0.38 | 15 | 0.18 | 0.29 | 0.09 | 0.18 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 6 | 0.29 | 0.48 | 0.18 | 0.36 | 16 | 0.16 | 0.27 | 0.08 | 0.16 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 7 | 0.28 | 0.45 | 0.17 | 0.34 | 17 | 0.14 | 0.25 | 0.07 | 0.14 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 8 | 0.27 | 0.43 | 0.16 | 0.32 | 18 | 0.12 | 0.23 | 0.06 | 0.12 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 9 | 0.26 | 0.41 | 0.15 | 0.30 | 19 | 0.10 | 0.21 | 0.05 | 0.10 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +| 10 | 0.25 | 0.39 | 0.14 | 0.28 | 20 | 0.08 | 0.16 | 0.04 | 0.08 | ++---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + +Snow Albedo +^^^^^^^^^^^^^^^^^ + +Snow albedo and solar absorption within each snow layer are simulated +with the Snow, Ice, and Aerosol Radiative Model (SNICAR), which +incorporates a two-stream radiative transfer solution from Toon et al. +(1989). Albedo and the vertical absorption profile depend on solar +zenith angle, albedo of the substrate underlying snow, mass +concentrations of atmospheric-deposited aerosols (black carbon, mineral +dust, and organic carbon), and ice effective grain size +(:math:`r_{e}`), which is simulated with a snow aging routine +described in section 3.2.3. Representation of impurity mass +concentrations within the snowpack is described in section 7.2.4. +Implementation of SNICAR in CLM is also described somewhat by Flanner +and Zender (2005) and Flanner et al. (2007). + +The two-stream solution requires the following bulk optical properties +for each snow layer and spectral band: extinction optical depth +(:math:`\tau`), single-scatter albedo (:math:`\omega`), and +scattering asymmetry parameter (*g*). The snow layers used for radiative +calculations are identical to snow layers applied elsewhere in CLM, +except for the case when snow mass is greater than zero but no snow +layers exist. When this occurs, a single radiative layer is specified to +have the column snow mass and an effective grain size of freshly-fallen +snow (section 3.2.3). The bulk optical properties are weighted functions +of each constituent *k*, computed for each snow layer and spectral band +as + +.. math:: + :label: 3.62 + + \tau =\sum _{1}^{k}\tau _{k} + +.. math:: + :label: 3.63 + + \omega =\frac{\sum _{1}^{k}\omega _{k} \tau _{k} }{\sum _{1}^{k}\tau _{k} } + +.. math:: + :label: 3.64 + + g=\frac{\sum _{1}^{k}g_{k} \omega _{k} \tau _{k} }{\sum _{1}^{k}\omega _{k} \tau _{k} } + +For each constituent (ice, two black carbon species, two organic carbon +species, and four dust species), :math:`\omega`, *g*, and +the mass extinction cross-section :math:`\psi` (:math:`\text{m}^{2} \text{kg}^{-1}`) +are computed offline with Mie Theory, e.g., +applying the computational technique from Bohren and Huffman (1983). The +extinction optical depth for each constituent depends on its mass +extinction cross-section and layer mass, :math:`w _{k} (\text{kg m} ^{-2}`) as + +.. math:: + :label: 3.65 + + \tau _{k} =\psi _{k} w_{k} + +The two-stream solution (Toon et al. 1989) applies a tri-diagonal matrix +solution to produce upward and downward radiative fluxes at each layer +interface, from which net radiation, layer absorption, and surface +albedo are easily derived. Solar fluxes are computed in five spectral +bands, listed in Table 3.4. Because snow albedo varies strongly across +the solar spectrum, it was determined that four bands were needed to +accurately represent the near-infrared (NIR) characteristics of snow, +whereas only one band was needed for the visible spectrum. Boundaries of +the NIR bands were selected to capture broad radiative features and +maximize accuracy and computational efficiency. We partition NIR +(0.7-5.0 :math:`\mu` m) surface downwelling flux from CLM +according to the weights listed in Table 3.4, which are unique for +diffuse and direct incident flux. These fixed weights were determined +with offline hyperspectral radiative transfer calculations for an +atmosphere typical of mid-latitude winter (Flanner et al. 2007). The +tri-diagonal solution includes intermediate terms that allow for easy +interchange of two-stream techniques. We apply the Eddington solution +for the visible band (following Wiscombe and Warren 1980) and the +hemispheric mean solution (Toon et al. 1989) for NIR bands. These +choices were made because the Eddington scheme works well for highly +scattering media, but can produce negative albedo for absorptive NIR +bands with diffuse incident flux. Delta scalings are applied to +:math:`\tau`, :math:`\omega`, and :math:`g` (Wiscombe and Warren 1980) in +all spectral bands, producing effective values (denoted with \*) that +are applied in the two-stream solution + +.. math:: + :label: 3.66 + + \tau ^{*} =\left(1-\omega g^{2} \right)\tau + +.. math:: + :label: 3.67 + + \omega ^{*} =\frac{\left(1-g^{2} \right)\omega }{1-g^{2} \omega } + +.. math:: + :label: 3.68 + + g^{*} =\frac{g}{1+g} + +Table 3.4. Spectral bands and weights used for snow radiative transfer + ++---------------------------------------------------------+----------------------+------------------+ +| Spectral band | Direct-beam weight | Diffuse weight | ++=========================================================+======================+==================+ +| Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | | | ++---------------------------------------------------------+----------------------+------------------+ +| Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | ++---------------------------------------------------------+----------------------+------------------+ +| Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.181 | 0.202 | ++---------------------------------------------------------+----------------------+------------------+ +| Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.121 | 0.109 | ++---------------------------------------------------------+----------------------+------------------+ +| Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.204 | 0.103 | ++---------------------------------------------------------+----------------------+------------------+ + +Under direct-beam conditions, singularities in the radiative +approximation are occasionally approached in spectral bands 4 and 5 that +produce unrealistic conditions (negative energy absorption in a layer, +negative albedo, or total absorbed flux greater than incident flux). +When any of these three conditions occur, the Eddington approximation is +attempted instead, and if both approximations fail, the cosine of the +solar zenith angle is adjusted by 0.02 (conserving incident flux) and a +warning message is produced. This situation occurs in only about 1 in +10 :math:`{}^{6}` computations of snow albedo. After looping over the +five spectral bands, absorption fluxes and albedo are averaged back into +the bulk NIR band used by the rest of CLM. + +Soil albedo (or underlying substrate albedo), which is defined for +visible and NIR bands, is a required boundary condition for the snow +radiative transfer calculation. Currently, the bulk NIR soil albedo is +applied to all four NIR snow bands. With ground albedo as a lower +boundary condition, SNICAR simulates solar absorption in all snow layers +as well as the underlying soil or ground. With a thin snowpack, +penetrating solar radiation to the underlying soil can be quite large +and heat cannot be released from the soil to the atmosphere in this +situation. Thus, solar radiation penetration is limited to snowpacks +with total snow depth greater than or equal to 0.1 m +(:math:`z_{sno} \ge 0.1`) to prevent unrealistic soil warming within a +single timestep. + +The radiative transfer calculation is performed twice for each column +containing a mass of snow greater than +:math:`1 \times 10^{-30} \text{kg m}^{-2}` (excluding lake and urban columns); once each for +direct-beam and diffuse incident flux. Absorption in each layer +:math:`i` of pure snow is initially recorded as absorbed flux per unit +incident flux on the ground (:math:`S_{sno,\, i}` ), as albedos must be +calculated for the next timestep with unknown incident flux. The snow +absorption fluxes that are used for column temperature calculations are + +.. math:: + :label: ZEqnNum275338 + + S_{g,\, i} =S_{sno,\, i} \left(1-\alpha _{sno} \right) + +This weighting is performed for direct-beam and diffuse, visible and NIR +fluxes. After the ground-incident fluxes (transmitted through the +vegetation canopy) have been calculated for the current time step +(sections 3.1 and 4.1), the layer absorption factors + +(:math:`S_{g,\, i}`) are multiplied by the ground-incident fluxes to +produce solar absorption (W m\ :math:`{}^{-2}`) in each snow layer and +the underlying ground. + +Snowpack Optical Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ice optical properties for the five spectral bands are derived offline +and stored in a namelist-defined lookup table for online retrieval (see +CLM4.5 User’s Guide). Mie properties are first computed at fine spectral +resolution (470 bands), and are then weighted into the five bands +applied by CLM according to incident solar flux, +:math:`I^{\downarrow } (\lambda )`. For example, the broadband +mass-extinction cross section (:math:`\bar{\psi }`) over wavelength +interval :math:`\lambda _{1}` to :math:`\lambda _{2}` is + +.. math:: + :label: 3.70 + + \bar{\psi }=\frac{\int _{\lambda _{1} }^{\lambda _{2} }\psi \left(\lambda \right) I^{\downarrow } \left(\lambda \right){\rm d}\lambda }{\int _{\lambda _{1} }^{\lambda _{2} }I^{\downarrow } \left(\lambda \right){\rm d}\lambda } + +Broadband single-scatter albedo (:math:`\bar{\omega }`) is additionally +weighted by the diffuse albedo for a semi-infinite snowpack (:math:`\alpha _{sno}`) + +.. math:: + :label: 3.71 + + \bar{\omega }=\frac{\int _{\lambda _{1} }^{\lambda _{2} }\omega (\lambda )I^{\downarrow } ( \lambda )\alpha _{sno} (\lambda ){\rm d}\lambda }{\int _{\lambda _{1} }^{\lambda _{2} }I^{\downarrow } ( \lambda )\alpha _{sno} (\lambda ){\rm d}\lambda } + +Inclusion of this additional albedo weight was found to improve accuracy +of the five-band albedo solutions (relative to 470-band solutions) +because of the strong dependence of optically-thick snowpack albedo on +ice grain single-scatter albedo (Flanner et al. 2007). The lookup tables +contain optical properties for lognormal distributions of ice particles +over the range of effective radii: 30\ :math:`\mu`\ m +:math:`< r _{e} < \text{1500} \mu \text{m}`, at 1 :math:`\mu` m resolution. Single-scatter albedos for the end-members of this size +range are listed in Table 3.5. + +Optical properties for black carbon are described in Flanner et al. +(2007). Single-scatter albedo, mass extinction cross-section, and +asymmetry parameter values for all snowpack species, in the five +spectral bands used, are listed in Tables 3.5, 3.6, and 3.7. These +properties were also derived with Mie Theory, using various published +sources of indices of refraction and assumptions about particle size +distribution. Weighting into the five CLM spectral bands was determined +only with incident solar flux, as in equation . + +Table 3.5. Single-scatter albedo values used for snowpack impurities and ice + ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | ++================================================================+==========+==========+==========+==========+==========+ +| Hydrophilic black carbon | 0.516 | 0.434 | 0.346 | 0.276 | 0.139 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophobic black carbon | 0.288 | 0.187 | 0.123 | 0.089 | 0.040 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophilic organic carbon | 0.997 | 0.994 | 0.990 | 0.987 | 0.951 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophobic organic carbon | 0.963 | 0.921 | 0.860 | 0.814 | 0.744 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 1 | 0.979 | 0.994 | 0.993 | 0.993 | 0.953 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 2 | 0.944 | 0.984 | 0.989 | 0.992 | 0.983 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 3 | 0.904 | 0.965 | 0.969 | 0.973 | 0.978 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 4 | 0.850 | 0.940 | 0.948 | 0.953 | 0.955 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 0.9999 | 0.9999 | 0.9992 | 0.9938 | 0.9413 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 0.9998 | 0.9960 | 0.9680 | 0.8730 | 0.5500 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ + +Table 3.6. Mass extinction values (:math:`\text{m}^{2} \text{kg}^{-1}`) used for snowpack impurities and ice. + ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | ++================================================================+==========+==========+==========+==========+==========+ +| Hydrophilic black carbon | 25369 | 12520 | 7739 | 5744 | 3527 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophobic black carbon | 11398 | 5923 | 4040 | 3262 | 2224 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophilic organic carbon | 37774 | 22112 | 14719 | 10940 | 5441 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophobic organic carbon | 3289 | 1486 | 872 | 606 | 248 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 1 | 2687 | 2420 | 1628 | 1138 | 466 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 2 | 841 | 987 | 1184 | 1267 | 993 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 3 | 388 | 419 | 400 | 397 | 503 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 4 | 197 | 203 | 208 | 205 | 229 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 55.7 | 56.1 | 56.3 | 56.6 | 57.3 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 1.09 | 1.09 | 1.09 | 1.09 | 1.1 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ + +Table 3.7. Asymmetry scattering parameters used for snowpack impurities and ice. + ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | ++================================================================+==========+==========+==========+==========+==========+ +| Hydrophilic black carbon | 0.52 | 0.34 | 0.24 | 0.19 | 0.10 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophobic black carbon | 0.35 | 0.21 | 0.15 | 0.11 | 0.06 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophilic organic carbon | 0.77 | 0.75 | 0.72 | 0.70 | 0.64 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Hydrophobic organic carbon | 0.62 | 0.57 | 0.54 | 0.51 | 0.44 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 1 | 0.69 | 0.72 | 0.67 | 0.61 | 0.44 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 2 | 0.70 | 0.65 | 0.70 | 0.72 | 0.70 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 3 | 0.79 | 0.75 | 0.68 | 0.63 | 0.67 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Dust 4 | 0.83 | 0.79 | 0.77 | 0.76 | 0.73 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Ice (:math:`r _{e}` = 30\ :math:`\mu`\ m) | 0.88 | 0.88 | 0.88 | 0.88 | 0.90 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ +| Ice (:math:`r _{e}` = 1500\ :math:`\mu`\ m) | 0.89 | 0.90 | 0.90 | 0.92 | 0.97 | ++----------------------------------------------------------------+----------+----------+----------+----------+----------+ + +Snow Aging +^^^^^^^^^^^^^^^^ + +Snow aging is represented as evolution of the ice effective grain size +(:math:`r_{e}`). Previous studies have shown that use of spheres +which conserve the surface area-to-volume ratio (or specific surface +area) of ice media composed of more complex shapes produces relatively +small errors in simulated hemispheric fluxes (e.g., Grenfell and Warren +1999). Effective radius is the surface area-weighted mean radius of an +ensemble of spherical particles and is directly related to specific +surface area (*SSA*) as +:math:`r_{e} ={3\mathord{\left/ {\vphantom {3 \left(\rho _{ice} SSA\right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{ice} SSA\right)}` , +where :math:`\rho_{ice}` is the density of ice. Hence, +:math:`r_{e}` is a simple and practical metric for relating the +snowpack microphysical state to dry snow radiative characteristics. + +Wet snow processes can also drive rapid changes in albedo. The presence +of liquid water induces rapid coarsening of the surrounding ice grains +(e.g., Brun 1989), and liquid water tends to refreeze into large ice +clumps that darken the bulk snowpack. The presence of small liquid +drops, by itself, does not significantly darken snowpack, as ice and +water have very similar indices of refraction throughout the solar +spectrum. Pooled or ponded water, however, can significantly darken +snowpack by greatly reducing the number of refraction events per unit +mass. This influence is not currently accounted for. + +The net change in effective grain size occurring each time step is +represented in each snow layer as a summation of changes caused by dry +snow metamorphism (:math:`dr_{e,dry}`), liquid water-induced +metamorphism (:math:`dr_{e,wet}`), refreezing of liquid water, and +addition of freshly-fallen snow. The mass of each snow layer is +partitioned into fractions of snow carrying over from the previous time +step (:math:`f_{old}`), freshly-fallen snow +(:math:`f_{new}`), and refrozen liquid water +(:math:`f_{rfz}`), such that snow :math:`r_{e}` is updated +each time step *t* as + +.. math:: + :label: 3.72 + + r_{e} \left(t\right)=\left[r_{e} \left(t-1\right)+dr_{e,\, dry} +dr_{e,\, wet} \right]f_{old} +r_{e,\, 0} f_{new} +r_{e,\, rfz} f_{rfrz} + +Here, the effective radius of freshly-fallen snow +(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface +area of 60 :math:`\text{m}^{2} \text{kg}^{-1}`), and the effective +radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. + +Dry snow aging is based on a microphysical model described by Flanner +and Zender (2006). This model simulates diffusive vapor flux amongst +collections of ice crystals with various size and inter-particle +spacing. Specific surface area and effective radius are prognosed for +any combination of snow temperature, temperature gradient, density, and +initial size distribution. The combination of warm snow, large +temperature gradient, and low density produces the most rapid snow +aging, whereas aging proceeds slowly in cold snow, regardless of +temperature gradient and density. Because this model is currently too +computationally expensive for inclusion in climate models, we fit +parametric curves to model output over a wide range of snow conditions +and apply these parameters in CLM. The functional form of the parametric +equation is + +.. math:: + :label: 3.73 + + \frac{dr_{e,\, dry} }{dt} =\left(\frac{dr_{e} }{dt} \right)_{0} \left(\frac{\eta }{\left(r_{e} -r_{e,\, 0} \right)+\eta } \right)^{{1\mathord{\left/ {\vphantom {1 \kappa }} \right. \kern-\nulldelimiterspace} \kappa } } + +The parameters :math:`{(\frac{dr_{e}}{dt}})_{0}`, +:math:`\eta`, and :math:`\kappa` are retrieved interactively from a +lookup table with dimensions corresponding to snow temperature, +temperature gradient, and density. The domain covered by this lookup +table includes temperature ranging from 223 to 273 K, temperature +gradient ranging from 0 to 300 K m\ :math:`{}^{-1}`, and density ranging +from 50 to 400 kg m\ :math:`{}^{-3}`. Temperature gradient is calculated +at the midpoint of each snow layer *n*, using mid-layer temperatures +(:math:`T_{n}`) and snow layer thicknesses (:math:`dz_{n}`), as + +.. math:: + :label: 3.74 + + \left(\frac{dT}{dz} \right)_{n} =\frac{1}{dz_{n} } abs\left[\frac{T_{n-1} dz_{n} +T_{n} dz_{n-1} }{dz_{n} +dz_{n-1} } +\frac{T_{n+1} dz_{n} +T_{n} dz_{n+1} }{dz_{n} +dz_{n+1} } \right] + +For the bottom snow layer (:math:`n=0`), +:math:`T_{n+1}` is taken as the temperature of the +top soil layer, and for the top snow layer it is assumed that +:math:`T_{n-1}` = :math:`T_{n}`. + +The contribution of liquid water to enhanced metamorphism is based on +parametric equations published by Brun (1989), who measured grain +growth rates under different liquid water contents. This relationship, +expressed in terms of :math:`r_{e} (\mu \text{m})` and +subtracting an offset due to dry aging, depends on the mass liquid water +fraction :math:`f_{liq}` as + +.. math:: + :label: 3.75 + + \frac{dr_{e} }{dt} =\frac{10^{18} C_{1} f_{liq} ^{3} }{4\pi r_{e} ^{2} } + +The constant *C*\ :math:`{}_{1}` is +4.22\ :math:`\times`\ 10\ :math:`{}^{-13}`, and: +:math:`f_{liq} =w_{liq} /(w_{liq} +w_{ice} )`\ (section 7.2). + +In cases where snow mass is greater than zero, but a snow layer has not +yet been defined, :math:`r_{e}` is set to :math:`r_{e,0}`. When snow layers are combined or +divided, :math:`r_{e}` is calculated as a mass-weighted mean of +the two layers, following computations of other state variables (section +7.2.7). Finally, the allowable range of :math:`r_{e}`, +corresponding to the range over which Mie optical properties have been +defined, is 30-1500\ :math:`\mu` m. + +Solar Zenith Angle +---------------------- + +The CLM uses the same formulation for solar zenith angle as the +Community Atmosphere Model. The cosine of the solar zenith angle +:math:`\mu` is + +.. math:: + :label: 3.76 + + \mu =\sin \phi \sin \delta -\cos \phi \cos \delta \cos h + +where :math:`h` is the solar hour angle (radians) (24 hour periodicity), +:math:`\delta` is the solar declination angle (radians), and +:math:`\phi` is latitude (radians) (positive in Northern Hemisphere). +The solar hour angle :math:`h` (radians) is + +.. math:: + :label: 3.77 + + h=2\pi d+\theta + +where :math:`d` is calendar day (:math:`d=0.0` at 0Z on January 1), and +:math:`\theta` is longitude (radians) (positive east of the +CityplaceGreenwich meridian). + +The solar declination angle :math:`\delta` is calculated as in Berger +(1978a,b) and is valid for one million years past or hence, relative to +1950 A.D. The orbital parameters may be specified directly or the +orbital parameters are calculated for the desired year. The required +orbital parameters to be input by the user are the obliquity of the +Earth :math:`\varepsilon` (degrees, +:math:`-90^{\circ } <\varepsilon <90^{\circ }` ), Earth’s eccentricity +:math:`e` (:math:`0.00} \\ {\tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]+\pi \qquad {\rm for\; }e^{\cos } <{\rm -1}\times {\rm 10}^{{\rm -8}} } \\ {\tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]+2\pi \qquad {\rm for\; }e^{\cos } >{\rm 1}\times {\rm 10}^{{\rm -8}} {\rm \; and\; }e^{\sin } <0} \\ {\tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]\qquad {\rm for\; }e^{\cos } >{\rm 1}\times {\rm 10}^{{\rm -8}} {\rm \; and\; }e^{\sin } \ge 0} \end{array}\right\}. + +The numerical solution for the longitude of the perihelion +:math:`\tilde{\omega }` is constrained to be between 0 and 360 degrees +(measured from the autumn equinox). A constant 180 degrees is then added +to :math:`\tilde{\omega }` because the Sun is considered as revolving +around the Earth (geocentric coordinate system) (Berger et al. 1993). + +Table 3.8. Orbital parameters + ++--------------------------------------+-------------+ +| Parameter | | ++======================================+=============+ +| :math:`\varepsilon *` | 23.320556 | ++--------------------------------------+-------------+ +| :math:`\tilde{\psi }` (arcseconds) | 50.439273 | ++--------------------------------------+-------------+ +| :math:`\zeta` (degrees) | 3.392506 | ++--------------------------------------+-------------+ diff --git a/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst b/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst new file mode 100644 index 0000000000..45d03e83f8 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst @@ -0,0 +1,289 @@ +Radiative Fluxes +=================== + +The net radiation at the surface is +:math:`\left(\vec{S}_{v} +\vec{S}_{g} \right)-\left(\vec{L}_{v} +\vec{L}_{g} \right)`, +where :math:`\vec{S}` is the net solar flux absorbed by the vegetation +(“vâ€) and the ground (“gâ€) and :math:`\vec{L}` is the net longwave flux +(positive toward the atmosphere) (W m\ :math:`{}^{-2}`). + +Solar Fluxes +---------------- + +Figure 4.1 illustrates the direct beam and diffuse fluxes in the canopy. +:math:`I\, \uparrow _{\Lambda }^{\mu }` and +:math:`I\, \uparrow _{\Lambda }` are the upward diffuse fluxes, per +unit incident direct beam and diffuse flux (section 3.1). +:math:`I\, \downarrow _{\Lambda }^{\mu }` and +:math:`I\, \downarrow _{\Lambda }` \ are the downward diffuse fluxes +below the vegetation per unit incident direct beam and diffuse radiation +(section 3.1). The direct beam flux transmitted through the canopy, per +unit incident flux, is :math:`e^{-K\left(L+S\right)}` . +:math:`\vec{I}_{\Lambda }^{\mu }` and :math:`\vec{I}_{\Lambda }^{}` +are the fluxes absorbed by the vegetation, per unit incident direct beam +and diffuse radiation (section 3.1). +:math:`\alpha _{g,\, \Lambda }^{\mu }` and +:math:`\alpha _{g,\, \Lambda }` are the direct beam and diffuse ground +albedos (section 3.2). :math:`L` and :math:`S` are the exposed leaf area +index and stem area index (section 2.1.4). :math:`K` is the optical +depth of direct beam per unit leaf and stem area (section 3.1). + +Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse +solar radiation, and (c) longwave radiation absorbed, transmitted, and +reflected by vegetation and ground. + +For clarity, terms involving :math:`T^{n+1} -T^{n}` are not shown in +(c). + +.. image:: image1.png + +The total solar radiation absorbed by the vegetation and ground is + +.. math:: + :label: 4.1 + + \vec{S}_{v} =\sum _{\Lambda }S_{atm} \, \downarrow _{\Lambda }^{\mu } \overrightarrow{I}_{\Lambda }^{\mu } +S_{atm} \, \downarrow _{\Lambda } \overrightarrow{I}_{\Lambda } + +.. math:: + :label: 4.2 + + \begin{array}{l} {\vec{S}_{g} =\sum _{\Lambda }S_{atm} \, \downarrow _{\Lambda }^{\mu } e^{-K\left(L+S\right)} \left(1-\alpha _{g,\, \Lambda }^{\mu } \right) +} \\ {\qquad \left(S_{atm} \, \downarrow _{\Lambda }^{\mu } I\downarrow _{\Lambda }^{\mu } +S_{atm} \downarrow _{\Lambda } I\downarrow _{\Lambda } \right)\left(1-\alpha _{g,\, \Lambda } \right)} \end{array} + +where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and +:math:`S_{atm} \, \downarrow _{\Lambda }` are the incident direct beam +and diffuse solar fluxes (W m\ :math:`{}^{-2}`). For non-vegetated +surfaces, :math:`e^{-K\left(L+S\right)} =1`, +:math:`\overrightarrow{I}_{\Lambda }^{\mu } =\overrightarrow{I}_{\Lambda } =0`, +:math:`I\, \downarrow _{\Lambda }^{\mu } =0`, and +:math:`I\, \downarrow _{\Lambda } =1`, so that + +.. math:: + :label: 4.3 + + \begin{array}{l} {\vec{S}_{g} =\sum _{\Lambda }S_{atm} \, \downarrow _{\Lambda }^{\mu } \left(1-\alpha _{g,\, \Lambda }^{\mu } \right) +S_{atm} \, \downarrow _{\Lambda } \left(1-\alpha _{g,\, \Lambda } \right)} \\ {\vec{S}_{v} =0} \end{array}. + +Solar radiation is conserved as + +.. math:: + :label: 4.4 + + \sum _{\Lambda }\left(S_{atm} \, \downarrow _{\Lambda }^{\mu } +S_{atm} \, \downarrow _{\Lambda } \right)=\left(\vec{S}_{v} +\vec{S}_{g} \right) +\sum _{\Lambda }\left(S_{atm} \, \downarrow _{\Lambda }^{\mu } I\uparrow _{\Lambda }^{\mu } +S_{atm} \, \downarrow _{\Lambda } I\uparrow _{\Lambda } \right) + +where the latter term in parentheses is reflected solar radiation. + +Photosynthesis and transpiration depend non-linearly on solar radiation, +via the light response of stomata. The canopy is treated as two leaves +(sunlit and shaded) and the solar radiation in the visible waveband +(:math:`<` 0.7 µm) absorbed by the vegetation is apportioned to the +sunlit and shaded leaves (section 3.1). The absorbed photosynthetically +active (visible waveband) radiation averaged over the sunlit canopy (per +unit plant area) is + +.. math:: + :label: 4.5 + + \phi ^{sun} ={\left(\vec{I}_{sun,vis}^{\mu } S_{atm} \downarrow _{vis}^{\mu } +\vec{I}_{sun,vis}^{} S_{atm} \downarrow _{vis}^{} \right)\mathord{\left/ {\vphantom {\left(\vec{I}_{sun,vis}^{\mu } S_{atm} \downarrow _{vis}^{\mu } +\vec{I}_{sun,vis}^{} S_{atm} \downarrow _{vis}^{} \right) L^{sun} }} \right. \kern-\nulldelimiterspace} L^{sun} } + +and the absorbed radiation for the average shaded leaf (per unit plant +area) is + +.. math:: + :label: 4.6 + + \phi ^{sha} ={\left(\vec{I}_{sha,vis}^{\mu } S_{atm} \downarrow _{vis}^{\mu } +\vec{I}_{sha,vis}^{} S_{atm} \downarrow _{vis}^{} \right)\mathord{\left/ {\vphantom {\left(\vec{I}_{sha,vis}^{\mu } S_{atm} \downarrow _{vis}^{\mu } +\vec{I}_{sha,vis}^{} S_{atm} \downarrow _{vis}^{} \right) L^{sha} }} \right. \kern-\nulldelimiterspace} L^{sha} } + +with :math:`L^{sun}` and :math:`L^{sha}` the sunlit and shaded plant +area index, respectively. The sunlit plant area index is + +.. math:: + :label: 4.7 + + L^{sun} =\frac{1-e^{-K(L+S)} }{K} + +and the shaded leaf area index is :math:`L^{sha} =(L+S)-L^{sun}` . In +calculating :math:`L^{sun}` , + +.. math:: + :label: 4.8 + + K=\frac{G\left(\mu \right)}{\mu } + +where :math:`G\left(\mu \right)` and :math:`\mu` are parameters in the +two-stream approximation (section 3.1). + +The model uses the two-stream approximation to calculate radiative +transfer of direct and diffuse radiation through a canopy that is +differentiated into leaves that are sunlit and those that are shaded +(section 3.1). The two-stream equations are integrated over all plant +area (leaf and stem area) in the canopy. The model has an optional +(though not supported) multi-layer canopy, as described by Bonan et al. +(2012). The multi-layer model is only intended to address the +non-linearity of light profiles, photosynthesis, and stomatal +conductance in the plant canopy. + +In the multi-layer canopy, canopy-integrated radiative fluxes are +calculated from the two-stream approximation. The model additionally +derives the light profile with depth in the canopy by taking the +derivatives of the absorbed radiative fluxes with respect to plant area +index (:math:`L'=L+S`) and evaluating them incrementally through the +canopy with cumulative plant area index (:math:`x`). The terms +:math:`{d\vec{I}_{sun,\Lambda }^{\mu } (x)\mathord{\left/ {\vphantom {d\vec{I}_{sun,\Lambda }^{\mu } (x) dL'}} \right. \kern-\nulldelimiterspace} dL'}` +and +:math:`{d\vec{I}_{sun,\Lambda }^{} (x)\mathord{\left/ {\vphantom {d\vec{I}_{sun,\Lambda }^{} (x) dL'}} \right. \kern-\nulldelimiterspace} dL'}` +are the direct beam and diffuse solar radiation, respectively, absorbed +by the sunlit fraction of the canopy (per unit plant area) at a depth +defined by the cumulative plant area index :math:`x`; +:math:`{d\vec{I}_{sha,\Lambda }^{\mu } (x)\mathord{\left/ {\vphantom {d\vec{I}_{sha,\Lambda }^{\mu } (x) dL'}} \right. \kern-\nulldelimiterspace} dL'}` \ and +:math:`{d\vec{I}_{sha,\Lambda }^{} (x)\mathord{\left/ {\vphantom {d\vec{I}_{sha,\Lambda }^{} (x) dL'}} \right. \kern-\nulldelimiterspace} dL'}` +are the corresponding fluxes for the shaded fraction of the canopy at +depth :math:`x`. These fluxes are normalized by the sunlit or shaded +fraction at depth :math:`x`, defined by +:math:`f_{sun} =\exp \left(-Kx\right)`, to give fluxes per unit sunlit +or shaded plant area at depth :math:`x`. + +Longwave Fluxes +------------------- + +The net longwave radiation (W m\ :math:`{}^{-2}`) (positive toward the +atmosphere) at the surface is + +.. math:: + :label: 4.9 + + \vec{L}=L\, \uparrow -L_{atm} \, \downarrow + +where :math:`L\, \uparrow` is the upward longwave radiation from the +surface and :math:`L_{atm} \, \downarrow` is the downward atmospheric +longwave radiation (W m\ :math:`{}^{-2}`). The radiative temperature +:math:`T_{rad}` (K) is defined from the upward longwave radiation as + +.. math:: + :label: 4.10 + + T_{rad} =\left(\frac{L\, \uparrow }{\sigma } \right)^{{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } + +where :math:`\sigma` is the Stefan-Boltzmann constant (W +m\ :math:`{}^{-2}` K\ :math:`{}^{-4}`) (Table 2.6). With reference to +Figure 4.1, the upward longwave radiation from the surface to the +atmosphere is + +.. math:: + :label: 4.11 + + \begin{array}{l} {L\, \uparrow =\delta _{veg} L_{vg} \, \uparrow +\left(1-\delta _{veg} \right)\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +} \\ {\qquad \left(1-\delta _{veg} \right)\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right)} \end{array} + +where :math:`L_{vg} \, \uparrow` is the upward longwave radiation from +the vegetation/soil system for exposed leaf and stem area +:math:`L+S\ge 0.05`, :math:`\delta _{veg}` is a step function and is +zero for :math:`L+S<0.05` and one otherwise, :math:`\varepsilon _{g}` +is the ground emissivity, and :math:`T_{g}^{n+1}` and +:math:`T_{g}^{n}` are the snow/soil surface temperatures at the current +and previous time steps, respectively (Chapter 6). + +For non-vegetated surfaces, the above equation reduces to + +.. math:: + :label: 4.12 + + L\, \uparrow =\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) + +where the first term is the atmospheric longwave radiation reflected by +the ground, the second term is the longwave radiation emitted by the +ground, and the last term is the increase (decrease) in longwave +radiation emitted by the ground due to an increase (decrease) in ground +temperature. + +For vegetated surfaces, the upward longwave radiation from the surface +reduces to + +.. math:: + :label: 4.13 + + L\, \uparrow =L_{vg} \, \uparrow +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) + +where + +.. math:: + :label: 4.14 + + \begin{array}{l} {L_{vg} \, \uparrow =\left(1-\varepsilon _{g} \right)\left(1-\varepsilon _{v} \right)\left(1-\varepsilon _{v} \right)L_{atm} \, \downarrow } \\ {\qquad \qquad +\varepsilon _{v} \left[1+\left(1-\varepsilon _{g} \right)\left(1-\varepsilon _{v} \right)\right]\sigma \left(T_{v}^{n} \right)^{3} \left[T_{v}^{n} +4\left(T_{v}^{n+1} -T_{v}^{n} \right)\right]} \\ {\qquad \qquad +\varepsilon _{g} \left(1-\varepsilon _{v} \right)\sigma \left(T_{g}^{n} \right)^{4} } \\ {\qquad =\left(1-\varepsilon _{g} \right)\left(1-\varepsilon _{v} \right)\left(1-\varepsilon _{v} \right)L_{atm} \, \downarrow } \\ {\qquad \qquad +\varepsilon _{v} \sigma \left(T_{v}^{n} \right)^{4} } \\ {\qquad \qquad +\varepsilon _{v} \left(1-\varepsilon _{g} \right)\left(1-\varepsilon _{v} \right)\sigma \left(T_{v}^{n} \right)^{4} } \\ {\qquad \qquad +4\varepsilon _{v} \sigma \left(T_{v}^{n} \right)^{3} \left(T_{v}^{n+1} -T_{v}^{n} \right)} \\ {\qquad \qquad +4\varepsilon _{v} \left(1-\varepsilon _{g} \right)\left(1-\varepsilon _{v} \right)\sigma \left(T_{v}^{n} \right)^{3} \left(T_{v}^{n+1} -T_{v}^{n} \right)} \\ {\qquad \qquad +\varepsilon _{g} \left(1-\varepsilon _{v} \right)\sigma \left(T_{g}^{n} \right)^{4} } \end{array} + +where :math:`\varepsilon _{v}` is the vegetation emissivity and +:math:`T_{v}^{n+1}` and :math:`T_{v}^{n}` are the vegetation +temperatures at the current and previous time steps, respectively +(Chapter 5). The first term in the equation above is the atmospheric +longwave radiation that is transmitted through the canopy, reflected by +the ground, and transmitted through the canopy to the atmosphere. The +second term is the longwave radiation emitted by the canopy directly to +the atmosphere. The third term is the longwave radiation emitted +downward from the canopy, reflected by the ground, and transmitted +through the canopy to the atmosphere. The fourth term is the increase +(decrease) in longwave radiation due to an increase (decrease) in canopy +temperature that is emitted by the canopy directly to the atmosphere. +The fifth term is the increase (decrease) in longwave radiation due to +an increase (decrease) in canopy temperature that is emitted downward +from the canopy, reflected from the ground, and transmitted through the +canopy to the atmosphere. The last term is the longwave radiation +emitted by the ground and transmitted through the canopy to the +atmosphere. + +The upward longwave radiation from the ground is + +.. math:: + :label: 4.15 + + L_{g} \, \uparrow =\left(1-\varepsilon _{g} \right)L_{v} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} + +where :math:`L_{v} \, \downarrow` is the downward longwave radiation +below the vegetation + +.. math:: + :label: 4.16 + + L_{v} \, \downarrow =\left(1-\varepsilon _{v} \right)L_{atm} \, \downarrow +\varepsilon _{v} \sigma \left(T_{v}^{n} \right)^{4} +4\varepsilon _{v} \sigma \left(T_{v}^{n} \right)^{3} \left(T_{v}^{n+1} -T_{v}^{n} \right). + +The net longwave radiation flux for the ground is (positive toward the +atmosphere) + +.. math:: + :label: 4.17 + + \vec{L}_{g} =\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} -\delta _{veg} \varepsilon _{g} L_{v} \, \downarrow -\left(1-\delta _{veg} \right)\varepsilon _{g} L_{atm} \, \downarrow . + +The above expression for :math:`\vec{L}_{g}` is the net longwave +radiation forcing that is used in the soil temperature calculation +(Chapter 6). Once updated soil temperatures have been obtained, the term +:math:`4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right)` +is added to :math:`\vec{L}_{g}` to calculate the ground heat flux +(section 5.4) + +The net longwave radiation flux for vegetation is (positive toward the +atmosphere) + +.. math:: + :label: 4.18 + + \vec{L}_{v} =\left[2-\varepsilon _{v} \left(1-\varepsilon _{g} \right)\right]\varepsilon _{v} \sigma \left(T_{v} \right)^{4} -\varepsilon _{v} \varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} -\varepsilon _{v} \left[1+\left(1-\varepsilon _{g} \right)\left(1-\varepsilon _{v} \right)\right]L_{atm} \, \downarrow . + +These equations assume that absorptivity equals emissivity. The +emissivity of the ground is + +.. math:: + :label: 4.19 + + \varepsilon _{g} =\varepsilon _{soi} \left(1-f_{sno} \right)+\varepsilon _{sno} f_{sno} + +where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, and +0.96 for wetland, :math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` +is the fraction of ground covered by snow (section 7.2.1). The +vegetation emissivity is + +.. math:: + :label: 4.20 + + \varepsilon _{v} =1-e^{-{\left(L+S\right)\mathord{\left/ {\vphantom {\left(L+S\right) \bar{\mu }}} \right. \kern-\nulldelimiterspace} \bar{\mu }} } + +where :math:`L` and :math:`S` are the leaf and stem area indices +(section 2.1.4) and :math:`\bar{\mu }=1` is the average inverse optical +depth for longwave radiation. + diff --git a/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst b/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst new file mode 100644 index 0000000000..336fde1b9f --- /dev/null +++ b/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst @@ -0,0 +1,1773 @@ +Momentum, Sensible Heat, and Latent Heat Fluxes +================================================== + +The zonal :math:`\tau _{x}` and meridional :math:`\tau _{y}` momentum +fluxes (kg m\ :math:`{}^{-1}` s\ :math:`{}^{-2}`), sensible heat flux +:math:`H` (W m\ :math:`{}^{-2}`), and water vapor flux :math:`E` (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) between the atmosphere at +reference height :math:`z_{atm,\, x}` (m) [where :math:`x` is height +for wind (momentum) (:math:`m`), temperature (sensible heat) +(:math:`h`), and humidity (water vapor) (:math:`w`); with zonal and +meridional winds :math:`u_{atm}` and :math:`v_{atm}` (m +s\ :math:`{}^{-1}`), potential temperature :math:`\theta _{atm}` (K), +and specific humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`)] and the +surface [with :math:`u_{s}` , :math:`v_{s}` , :math:`\theta _{s}` , and +:math:`q_{s}` ] are + +.. math:: + :label: 5.1 + + \tau _{x} =-\rho _{atm} \frac{\left(u_{atm} -u_{s} \right)}{r_{am} } + +.. math:: + :label: 5.2 + + \tau _{y} =-\rho _{atm} \frac{\left(v_{atm} -v_{s} \right)}{r_{am} } + +.. math:: + :label: 5.3 + + H=-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -\theta _{s} \right)}{r_{ah} } + +.. math:: + :label: 5.4 + + E=-\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } . + +These fluxes are derived in the next section from Monin-Obukhov +similarity theory developed for the surface layer (i.e., the nearly +constant flux layer above the surface sublayer). In this derivation, +:math:`u_{s}` and :math:`v_{s}` are defined to equal zero at height +:math:`z_{0m} +d` (the apparent sink for momentum) so that +:math:`r_{am}` is the aerodynamic resistance (s m\ :math:`{}^{-1}`) for +momentum between the atmosphere at height :math:`z_{atm,\, m}` and the +surface at height :math:`z_{0m} +d`. Thus, the momentum fluxes become + +.. math:: + :label: + + \tau _{x} =-\rho _{atm} \frac{u_{atm} }{r_{am} } + +.. math:: + :label: + + \tau _{y} =-\rho _{atm} \frac{v_{atm} }{r_{am} } . + +Likewise, :math:`\theta _{s}` and :math:`q_{s}` are defined at +heights :math:`z_{0h} +d` and :math:`z_{0w} +d` (the apparent sinks for +heat and water vapor, respectively + +:math:`r_{aw}` are the aerodynamic resistances (s m\ :math:`{}^{-1}`) +to sensible heat and water vapor transfer between the atmosphere at +heights :math:`z_{atm,\, h}` and :math:`z_{atm,\, w}` and the surface +at heights :math:`z_{0h} +d` and :math:`z_{0w} +d`, respectively. The +specific heat capacity of air :math:`C_{p}` (J kg\ :math:`{}^{-1}` +K\ :math:`{}^{-1}`) is a constant (Table 2.6). The atmospheric potential +temperature used here is + +.. math:: + :label: 5.7 + + \theta _{atm} =T_{atm} +\Gamma _{d} z_{atm,\, h} + +where :math:`T_{atm}` is the air temperature (K) at height +:math:`z_{atm,\, h}` and :math:`\Gamma _{d} =0.0098` K +m\ :math:`{}^{-1}` is the negative of the dry adiabatic lapse rate [this +expression is first-order equivalent to +:math:`\theta _{atm} =T_{atm} \left({P_{srf} \mathord{\left/ {\vphantom {P_{srf} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } \right)^{{R_{da} \mathord{\left/ {\vphantom {R_{da} C_{p} }} \right. \kern-\nulldelimiterspace} C_{p} } }` +(Stull 1988), where :math:`P_{srf}` is the surface pressure (Pa), +:math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`R_{da}` +is the gas constant for dry air (J kg\ :math:`{}^{-1}` +K\ :math:`{}^{-1}`) (Table 2.6)]. By definition, +:math:`\theta _{s} =T_{s}` . The density of moist air (kg +m\ :math:`{}^{-3}`) is + +.. math:: + :label: 5.8 + + \rho _{atm} =\frac{P_{atm} -0.378e_{atm} }{R_{da} T_{atm} } + +where the atmospheric vapor pressure :math:`e_{atm}` (Pa) is derived +from the atmospheric specific humidity :math:`q_{atm}` + +.. math:: + :label: 5.9 + + e_{atm} =\frac{q_{atm} P_{atm} }{0.622+0.378q_{atm} } . + +Monin-Obukhov Similarity Theory +----------------------------------- + +The surface vertical kinematic fluxes of momentum +:math:`\overline{u'w'}` and :math:`\overline{v'w'}` (:math:`\text{m}^{2} \text{s}^{-2}`), sensible heat :math:`\overline{\theta 'w'}` +(:math:`\text{K m} \text{s}^{-1}`), and latent heat :math:`\overline{q'w'}` (:math:`\text{kg kg }^{-1}` m s\ :math:`{}^{-1}`), where :math:`u'`, :math:`v'`, +:math:`w'`, :math:`\theta '`, and :math:`q'` are zonal horizontal wind, +meridional horizontal wind, vertical velocity, potential temperature, +and specific humidity turbulent fluctuations about the mean, are defined +from Monin-Obukhov similarity applied to the surface layer. This theory +states that when scaled appropriately, the dimensionless mean horizontal +wind speed, mean potential temperature, and mean specific humidity +profile gradients depend on unique functions of +:math:`\zeta =\frac{z-d}{L}` (Zeng et al. 1998) as + +.. math:: + :label: 5.10 + + \frac{k\left(z-d\right)}{u_{*} } \frac{\partial \left|{\it u}\right|}{\partial z} =\phi _{m} \left(\zeta \right) + +.. math:: + :label: 5.11 + + \frac{k\left(z-d\right)}{\theta _{*} } \frac{\partial \theta }{\partial z} =\phi _{h} \left(\zeta \right) + +.. math:: + :label: 5.12 + + \frac{k\left(z-d\right)}{q_{*} } \frac{\partial q}{\partial z} =\phi _{w} \left(\zeta \right) + +where :math:`z` is height in the surface layer (m), :math:`d` is the +displacement height (m), :math:`L` is the Monin-Obukhov length scale (m) +that accounts for buoyancy effects resulting from vertical density +gradients (i.e., the atmospheric stability), k is the von Karman +constant (Table 2.6), and :math:`\left|{\it u}\right|` is the +atmospheric wind speed (m s\ :math:`{}^{-1}`). :math:`\phi _{m}` , +:math:`\phi _{h}` , and :math:`\phi _{w}` are universal (over any +surface) similarity functions of :math:`\zeta` that relate the constant +fluxes of momentum, sensible heat, and latent heat to the mean profile +gradients of :math:`\left|{\it u}\right|`, :math:`\theta` , and +:math:`q` in the surface layer. In neutral conditions, +:math:`\phi _{m} =\phi _{h} =\phi _{w} =1`. The velocity (i.e., friction +velocity) :math:`u_{\*}` (m s\ :math:`{}^{-1}`), temperature +:math:`\theta _{\*}` (K), and moisture :math:`q_{\*}` (kg +kg\ :math:`{}^{-1}`) scales are + +.. math:: + :label: 5.13 + + u_{*}^{2} =\sqrt{\left(\overline{u'w'}\right)^{2} +\left(\overline{v'w'}\right)^{2} } =\frac{\left|{\it \tau }\right|}{\rho _{atm} } + +.. math:: + :label: 5.14 + + \theta _{*} u_{*} =-\overline{\theta 'w'}=-\frac{H}{\rho _{atm} C_{p} } + +.. math:: + :label: 5.15 + + q_{*} u_{*} =-\overline{q'w'}=-\frac{E}{\rho _{atm} } + +where :math:`\left|{\it \tau }\right|` is the shearing stress (kg +m\ :math:`{}^{-1}` s\ :math:`{}^{-2}`), with zonal and meridional +components :math:`\overline{u'w'}=-\frac{\tau _{x} }{\rho _{atm} }` and +:math:`\overline{v'w'}=-\frac{\tau _{y} }{\rho _{atm} }` , respectively, +:math:`H` is the sensible heat flux (W m\ :math:`{}^{-2}`) and :math:`E` +is the water vapor flux (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`). + +The dimensionless length scale :math:`L` is the Monin-Obukhov length +defined as + +.. math:: + :label: 5.16 + + L=-\frac{u_{*}^{3} }{k\left(\frac{g}{\overline{\theta _{v,\, atm} }} \right)\theta '_{v} w'} =\frac{u_{*}^{2} \overline{\theta _{v,\, atm} }}{kg\theta _{v*} } + +where :math:`g` is the acceleration of gravity (m s\ :math:`{}^{-2}`) +(Table 2.6), and +:math:`\overline{\theta _{v,\, atm} }=\overline{\theta _{atm} }\left(1+0.61q_{atm} \right)` +is the reference virtual potential temperature. :math:`L>0` indicates +stable conditions. :math:`L<0` indicates unstable conditions. +:math:`L=\infty` for neutral conditions. The temperature scale +:math:`\theta _{v*}` is defined as + +.. math:: + :label: ZEqnNum632600 + + \theta _{v*} u_{*} =\left[\theta _{*} \left(1+0.61q_{atm} \right)+0.61\overline{\theta _{atm} }q_{*} \right]u_{*} + +where :math:`\overline{\theta _{atm} }` is the atmospheric potential +temperature. + +Following Panofsky and Dutton (1984), the differential equations for +:math:`\phi _{m} \left(\zeta \right)`, +:math:`\phi _{h} \left(\zeta \right)`, and +:math:`\phi _{w} \left(\zeta \right)` can be integrated formally without +commitment to their exact forms. Integration between two arbitrary +heights in the surface layer :math:`z_{2}` and :math:`z_{1}` +(:math:`z_{2} >z_{1}` ) with horizontal winds +:math:`\left|{\it u}\right|_{1}` and :math:`\left|{\it u}\right|_{2}` , +potential temperatures :math:`\theta _{1}` and :math:`\theta _{2}` , +and specific humidities :math:`q_{1}` and :math:`q_{2}` results in + +.. math:: + :label: 5.18 + + \left|{\it u}\right|_{2} -\left|{\it u}\right|_{1} =\frac{u_{*} }{k} \left[\ln \left(\frac{z_{2} -d}{z_{1} -d} \right)-\psi _{m} \left(\frac{z_{2} -d}{L} \right)+\psi _{m} \left(\frac{z_{1} -d}{L} \right)\right] + +.. math:: + :label: 5.19 + + \theta _{2} -\theta _{1} =\frac{\theta _{*} }{k} \left[\ln \left(\frac{z_{2} -d}{z_{1} -d} \right)-\psi _{h} \left(\frac{z_{2} -d}{L} \right)+\psi _{h} \left(\frac{z_{1} -d}{L} \right)\right] + +.. math:: + :label: 5.20 + + q_{2} -q_{1} =\frac{q_{*} }{k} \left[\ln \left(\frac{z_{2} -d}{z_{1} -d} \right)-\psi _{w} \left(\frac{z_{2} -d}{L} \right)+\psi _{w} \left(\frac{z_{1} -d}{L} \right)\right]. + +The functions :math:`\psi _{m} \left(\zeta \right)`, +:math:`\psi _{h} \left(\zeta \right)`, and +:math:`\psi _{w} \left(\zeta \right)` are defined as + +.. math:: + :label: 5.21 + + \psi _{m} \left(\zeta \right)=\int _{{z_{0m} \mathord{\left/ {\vphantom {z_{0m} L}} \right. \kern-\nulldelimiterspace} L} }^{\zeta }\frac{\left[1-\phi _{m} \left(x\right)\right]}{x} \, dx + +.. math:: + :label: 5.22 + + \psi _{h} \left(\zeta \right)=\int _{{z_{0h} \mathord{\left/ {\vphantom {z_{0h} L}} \right. \kern-\nulldelimiterspace} L} }^{\zeta }\frac{\left[1-\phi _{h} \left(x\right)\right]}{x} \, dx + +.. math:: + :label: 5.23 + + \psi _{w} \left(\zeta \right)=\int _{{z_{0w} \mathord{\left/ {\vphantom {z_{0w} L}} \right. \kern-\nulldelimiterspace} L} }^{\zeta }\frac{\left[1-\phi _{w} \left(x\right)\right]}{x} \, dx + +where :math:`z_{0m}` , :math:`z_{0h}` , and :math:`z_{0w}` are the +roughness lengths (m) for momentum, sensible heat, and water vapor, +respectively. + +Defining the surface values + +.. math:: \left|{\it u}\right|_{1} =0{\rm \; at\; }z_{1} =z_{0m} +d, + +.. math:: \theta _{1} =\theta _{s} {\rm \; at\; }z_{1} =z_{0h} +d,{\rm \; and} + +.. math:: q_{1} =q_{s} {\rm \; at\; }z_{1} =z_{0w} +d, + +and the atmospheric values at :math:`z_{2} =z_{atm,\, x}` + +.. math:: + :label: ZEqnNum228149 + + \left|{\it u}\right|_{2} =V_{a} {\rm =\; }\sqrt{u_{atm}^{2} +v_{atm}^{2} +U_{c}^{2} } \ge 1, + +.. math:: \theta _{2} =\theta _{atm} {\rm ,\; and} + +.. math:: q_{2} =q_{atm} {\rm ,\; } + +the integral forms of the flux-gradient relations are + +.. math:: + :label: 5.25 + + V_{a} =\frac{u_{*} }{k} \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right] + +.. math:: + :label: 5.26 + + \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left[\ln \left(\frac{z_{atm,\, h} -d}{z_{0h} } \right)-\psi _{h} \left(\frac{z_{atm,\, h} -d}{L} \right)+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right] + +.. math:: + :label: 5.27 + + q_{atm} -q_{s} =\frac{q_{*} }{k} \left[\ln \left(\frac{z_{atm,\, w} -d}{z_{0w} } \right)-\psi _{w} \left(\frac{z_{atm,\, w} -d}{L} \right)+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right]. + +The constraint :math:`V_{a} \ge 1` is required simply for numerical +reasons to prevent :math:`H` and :math:`E` from becoming small with +small wind speeds. The convective velocity :math:`U_{c}` accounts for +the contribution of large eddies in the convective boundary layer to +surface fluxes as follows + +.. math:: + :label: 5.28 + + {U_{c} = 0\ \qquad \zeta \ge {\rm 0} {\rm (stable)}} \\ + {U_{c} = \beta w_{\*} \qquad \zeta <0 {\rm (unstable})} + +where :math:`w_{\*}` is the convective velocity scale + +.. math:: + :label: 5.29 + + w_{\*} =\left(\frac{-gu_{\*} \theta _{v*} z_{i} }{\overline{\theta _{v,\, atm} }} \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } , + +:math:`z_{i} =1000` is the convective boundary layer height (m), and :math:`\beta =1`. + +The momentum flux gradient relations are (Zeng et al. 1998) + +.. math:: + :label: 5.30 + + \begin{array}{l} {\phi _{m} \left(\zeta \right)=0.7k^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } \qquad {\rm for\; }\zeta <-1.574{\rm \; (very\; unstable)}} \\ {\phi _{m} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } \qquad {\rm for\; -1.574}\le \zeta <0{\rm \; (unstable)}} \\ {\phi _{m} \left(\zeta \right)=1+5\zeta \qquad {\rm for\; }0\le \zeta \le 1{\rm \; (stable)}} \\ {\phi _{m} \left(\zeta \right)=5+\zeta \qquad {\rm for\; }\zeta {\rm >1\; (very\; stable).}} \end{array} + +The sensible and latent heat flux gradient relations are (Zeng et al. +1998) + +.. math:: + :label: 5.31 + + \begin{array}{l} {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=0.9k^{{4\mathord{\left/ {\vphantom {4 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } \qquad {\rm for\; }\zeta <-0.465{\rm \; (very\; unstable)}} \\ {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 2}} \right. \kern-\nulldelimiterspace} 2} } \qquad {\rm for\; -0.465}\le \zeta <0{\rm \; (unstable)}} \\ {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=1+5\zeta \qquad {\rm for\; }0\le \zeta \le 1{\rm \; (stable)}} \\ {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=5+\zeta \qquad {\rm for\; }\zeta {\rm >1\; (very\; stable).}} \end{array} + +To ensure continuous functions of +:math:`\phi _{m} \left(\zeta \right)`, +:math:`\phi _{h} \left(\zeta \right)`, and +:math:`\phi _{w} \left(\zeta \right)`, the simplest approach (i.e., +without considering any transition regimes) is to match the relations +for very unstable and unstable conditions at :math:`\zeta _{m} =-1.574` +for :math:`\phi _{m} \left(\zeta \right)` and +:math:`\zeta _{h} =\zeta _{w} =-0.465` for +:math:`\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)` +(Zeng et al. 1998). The flux gradient relations can be integrated to +yield wind profiles for the following conditions: + +Very unstable :math:`\left(\zeta <-1.574\right)` + +.. math:: + :label: ZEqnNum566843 + + V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{\zeta _{m} L}{z_{0m} } -\psi _{m} \left(\zeta _{m} \right)\right]+1.14\left[\left(-\zeta \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } -\left(-\zeta _{m} \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } \right]+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right\} + +Unstable :math:`\left(-1.574\le \zeta <0\right)` + +.. math:: + :label: ZEqnNum309568 + + V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, m} -d}{z_{0m} } -\psi _{m} \left(\zeta \right)\right]+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right\} + +Stable :math:`\left(0\le \zeta \le 1\right)` + +.. math:: + :label: ZEqnNum973766 + + V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, m} -d}{z_{0m} } +5\zeta \right]-5\frac{z_{0m} }{L} \right\} + +Very stable :math:`\left(\zeta >1\right)` + +.. math:: + :label: ZEqnNum310559 + + V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{L}{z_{0m} } +5\right]+\left[5\ln \zeta +\zeta -1\right]-5\frac{z_{0m} }{L} \right\} + +where + +.. math:: + :label: 5.36 + + \psi _{m} \left(\zeta \right)=2\ln \left(\frac{1+x}{2} \right)+\ln \left(\frac{1+x^{2} }{2} \right)-2\tan ^{-1} x+\frac{\pi }{2} + +and + +:math:`x=\left(1-16\zeta \right)^{{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} }` . + +The potential temperature profiles are: + +Very unstable :math:`\left(\zeta <-0.465\right)` + +.. math:: + :label: ZEqnNum382106 + + \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{\zeta _{h} L}{z_{0h} } -\psi _{h} \left(\zeta _{h} \right)\right]+0.8\left[\left(-\zeta _{h} \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } -\left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } \right]+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right\} + +Unstable :math:`\left(-0.465\le \zeta <0\right)` + +.. math:: + :label: ZEqnNum767002 + + \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{z_{atm,\, h} -d}{z_{0h} } -\psi _{h} \left(\zeta \right)\right]+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right\} + + +Stable :math:`\left(0\le \zeta \le 1\right)` + +.. math:: + :label: ZEqnNum556410 + + \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{z_{atm,\, h} -d}{z_{0h} } +5\zeta \right]-5\frac{z_{0h} }{L} \right\} + +Very stable :math:`\left(\zeta >1\right)` + +.. math:: + :label: ZEqnNum846197 + + \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{L}{z_{0h} } +5\right]+\left[5\ln \zeta +\zeta -1\right]-5\frac{z_{0h} }{L} \right\}. + +The specific humidity profiles are: + +Very unstable :math:`\left(\zeta <-0.465\right)` + +.. math:: + :label: ZEqnNum299834 + + q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{\zeta _{w} L}{z_{0w} } -\psi _{w} \left(\zeta _{w} \right)\right]+0.8\left[\left(-\zeta _{w} \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } -\left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } \right]+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right\} + +Unstable :math:`\left(-0.465\le \zeta <0\right)` + +.. math:: + + \label{ZEqnNum142122} + q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, w} -d}{z_{0w} } -\psi _{w} \left(\zeta \right)\right]+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right\} + +Stable :math:`\left(0\le \zeta \le 1\right)` + +.. math:: + :label: ZEqnNum350694 + + q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, w} -d}{z_{0w} } +5\zeta \right]-5\frac{z_{0w} }{L} \right\} + +Very stable :math:`\left(\zeta >1\right)` + +.. math:: + :label: ZEqnNum211437 + + q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{L}{z_{0w} } +5\right]+\left[5\ln \zeta +\zeta -1\right]-5\frac{z_{0w} }{L} \right\} + +where + +.. math:: + :label: 5.45 + + \psi _{h} \left(\zeta \right)=\psi _{w} \left(\zeta \right)=2\ln \left(\frac{1+x^{2} }{2} \right). + +Using the definitions of :math:`u_{*}` , :math:`\theta _{*}` , and +:math:`q_{*}` , an iterative solution of these equations can be used to +calculate the surface momentum, sensible heat, and water vapor flux +using atmospheric and surface values for :math:`\left|{\it u}\right|`, +:math:`\theta` , and :math:`q` except that :math:`L` depends on +:math:`u_{*}` , :math:`\theta _{*}` , and :math:`q_{*}` . However, the +bulk CityplaceRichardson number + +.. math:: + :label: ZEqnNum750428} + + R_{iB} =\frac{\theta _{v,\, atm} -\theta _{v,\, s} }{\overline{\theta _{v,\, atm} }} \frac{g\left(z_{atm,\, m} -d\right)}{V_{a}^{2} } + + +is related to :math:`\zeta` (Arya 2001) as + +.. math:: + :label: 5.47 + + R_{iB} =\zeta \left[\ln \left(\frac{z_{atm,\, h} -d}{z_{0h} } \right)-\psi _{h} \left(\zeta \right)\right]\left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\zeta \right)\right]^{-2} . + +Using +:math:`\phi _{h} =\phi _{m}^{2} =\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 2}} \right. \kern-\nulldelimiterspace} 2} }` +for unstable conditions and :math:`\phi _{h} =\phi _{m} =1+5\zeta` for +stable conditions to determine :math:`\psi _{m} \left(\zeta \right)` and +:math:`\psi _{h} \left(\zeta \right)`, the inverse relationship +:math:`\zeta =f\left(R_{iB} \right)` can be solved to obtain a first +guess for :math:`\zeta` and thus :math:`L` from + +.. math:: + + \label{ZEqnNum979946} + \begin{array}{l} {\zeta =\frac{R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)}{1-5\min \left(R_{iB} ,0.19\right)} \qquad 0.01\le \zeta \le 2\qquad {\rm for\; }R_{iB} \ge 0{\rm \; (neutral\; or\; stable)}} \\ {\zeta =R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)\qquad -100\le \zeta \le -0.01\qquad {\rm for\; }R_{iB} <0{\rm \; (unstable)}} \end{array}. + +Upon iteration (section 5.3.2), the following is used to determine +:math:`\zeta` and thus :math:`L` + +.. math:: + + \label{ZEqnNum153243} + \zeta =\frac{\left(z_{atm,\, m} -d\right)kg\theta _{v*} }{u_{*}^{2} \overline{\theta _{v,\, atm} }} + +where + +.. math:: \begin{array}{l} {0.01\le \zeta \le 2\qquad {\rm for\; }\zeta \ge 0{\rm \; (neutral\; or\; stable)}} \\ {{\rm -100}\le \zeta \le {\rm -0.01}\qquad {\rm for\; }\zeta <0{\rm \; (unstable)}} \end{array}. + +The difference in virtual potential air temperature between the +reference height and the surface is + +.. math:: + :label: ZEqnNum516498 + + \theta _{v,\, atm} -\theta _{v,\, s} =\left(\theta _{atm} -\theta _{s} \right)\left(1+0.61q_{atm} \right)+0.61\overline{\theta _{atm} }\left(q_{atm} -q_{s} \right). + +The momentum, sensible heat, and water vapor fluxes between the surface +and the atmosphere can also be written in the form + +.. math:: + :label: ZEqnNum567382 + + \tau _{x} =-\rho _{atm} \frac{\left(u_{atm} -u_{s} \right)}{r_{am} } + +.. math:: + :label: ZEqnNum615113 + + \tau _{y} =-\rho _{atm} \frac{\left(v_{atm} -v_{s} \right)}{r_{am} } + +.. math:: + :label: ZEqnNum588623 + + H=-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -\theta _{s} \right)}{r_{ah} } + +.. math:: + :label: ZEqnNum154565 + + E=-\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } + +where the aerodynamic resistances (s m\ :math:`{}^{-1}`) are + +.. math:: + :label: ZEqnNum660763 + + r_{am} =\frac{V_{a} }{u_{*}^{2} } =\frac{1}{k^{2} V_{a} } \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right]^{2} + +.. math:: + :label: ZEqnNum193138 + + \begin{array}{l} {r_{ah} =\frac{\theta _{atm} -\theta _{s} }{\theta _{*} u_{*} } =\frac{1}{k^{2} V_{a} } \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right]} \\ {\qquad \left[\ln \left(\frac{z_{atm,\, h} -d}{z_{0h} } \right)-\psi _{h} \left(\frac{z_{atm,\, h} -d}{L} \right)+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right]} \end{array} + +.. math:: + :label: ZEqnNum382229 + + \begin{array}{l} {r_{aw} =\frac{q_{atm} -q_{s} }{q_{*} u_{*} } =\frac{1}{k^{2} V_{a} } \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right]} \\ {\qquad \left[\ln \left(\frac{z_{atm,\, {\it w}} -d}{z_{0w} } \right)-\psi _{w} \left(\frac{z_{atm,\, w} -d}{L} \right)+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right]} \end{array}. + +A 2-m height “screen†temperature is useful for comparison with +observations + +.. math:: + :label: ZEqnNum664652 + + T_{2m} =\theta _{s} +\frac{\theta _{*} }{k} \left[\ln \left(\frac{2+z_{0h} }{z_{0h} } \right)-\psi _{h} \left(\frac{2+z_{0h} }{L} \right)+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right] + +where for convenience, “2-m†is defined as 2 m above the apparent sink +for sensible heat (:math:`z_{0h} +d`). Similarly, a 2-m height specific +humidity is defined as + +.. math:: + :label: ZEqnNum735237 + + q_{2m} =q_{s} +\frac{q_{*} }{k} \left[\ln \left(\frac{2+z_{0w} }{z_{0w} } \right)-\psi _{w} \left(\frac{2+z_{0w} }{L} \right)+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right]. + +Relative humidity is + +.. math:: + :label: ZEqnNum299365 + + RH_{2m} =\min \left(100,\, \frac{q_{2m} }{q_{sat}^{T_{2m} } } \times 100\right) + +where :math:`q_{sat}^{T_{2m} }` is the saturated specific humidity at +the 2-m temperature :math:`T_{2m}` (section 5.5). + +A 10-m wind speed is calculated as (note that this is not consistent +with the 10-m wind speed calculated for the dust model as described in +Chapter 24) + +.. math:: + :label: 5.61 + + u_{10m} =\left\{\begin{array}{l} {V_{a} \qquad z_{atm,\, m} \le 10} \\ {V_{a} -\frac{u_{*} }{k} \left[\ln \left(\frac{z_{atm,\, m} -d}{10+z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{10+z_{0m} }{L} \right)\right]\qquad z_{atm,\, m} >10} \end{array}\right\} + +Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces +-------------------------------------------------------------- + +Surfaces are considered non-vegetated for the surface flux calculations +if leaf plus stem area index :math:`L+S<0.05` (section 2.1.4). By +definition, this includes bare soil, wetlands, and glaciers. The +solution for lakes is described in Chapter 9. For these surfaces, the +surface may be exposed to the atmosphere, snow covered, and/or surface +water covered, so that the sensible heat flux :math:`H_{g}` (W +m\ :math:`{}^{-2}`) is, with reference to Figure 5.1, + +.. math:: + :label: ZEqnNum726771 + + H_{g} =\left(1-f_{sno} -f_{h2osfc} \right)H_{soil} +f_{sno} H_{snow} +f_{h2osfc} H_{h2osfc} + +where :math:`\left(1-f_{sno} -f_{h2osfc} \right)`, :math:`f_{sno}` , and +:math:`f_{h2osfc}` are the exposed, snow covered, and surface water +covered fractions of the grid cell. The individual fluxes based on the +temperatures of the soil :math:`T_{1}` , snow :math:`T_{snl+1}` , and +surface water :math:`T_{h2osfc}` are + +.. math:: + :label: 5.63 + + H_{soil} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{1} \right)}{r_{ah} } + +.. math:: + :label: 5.64 + + H_{sno} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{snl+1} \right)}{r_{ah} } + +.. math:: + :label: 5.65 + + H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{h2osfc} \right)}{r_{ah} } + +where :math:`\rho _{atm}` is the density of atmospheric air (kg +m\ :math:`{}^{-3}`), :math:`C_{p}` is the specific heat capacity of air +(J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), +:math:`\theta _{atm}` is the atmospheric potential temperature (K), and +:math:`r_{ah}` is the aerodynamic resistance to sensible heat transfer +(s m\ :math:`{}^{-1}`). + +The water vapor flux :math:`E_{g}` (kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`) is, with reference to Figure 5.2, + +.. math:: + :label: ZEqnNum419297 + + E_{g} =\left(1-f_{sno} -f_{h2osfc} \right)E_{soil} +f_{sno} E_{snow} +f_{h2osfc} E_{h2osfc} + +.. math:: + :label: 5.67 + + E_{soil} =-\frac{\beta _{soi} \rho _{atm} \left(q_{atm} -q_{soil} \right)}{r_{aw} } + +.. math:: + :label: 5.68 + + E_{sno} =-\frac{\rho _{atm} \left(q_{atm} -q_{sno} \right)}{r_{aw} } + +.. math:: + :label: 5.69 + + E_{h2osfc} =-\frac{\rho _{atm} \left(q_{atm} -q_{h2osfc} \right)}{r_{aw} } + +where :math:`\beta _{soi}` is an empirical function of soil water +(Sakaguchi and Zeng 2009), :math:`q_{atm}` is the atmospheric specific +humidity (kg kg\ :math:`{}^{-1}`), :math:`q_{soil}` , :math:`q_{sno}` , +and :math:`q_{h2osfc}` are the specific humidities (kg +kg\ :math:`{}^{-1}`) of the soil, snow, and surface water, respectively, +and :math:`r_{aw}` is the aerodynamic resistance to water vapor +transfer (s m\ :math:`{}^{-1}`). The specific humidities of the snow +:math:`q_{sno}` and surface water :math:`q_{h2osfc}` are assumed to be +at the saturation specific humidity of their respective temperatures + +.. math:: + :label: 5.70) + + q_{sno} =q_{sat}^{T_{snl+1} } + +.. math:: + :label: 5.71) + + q_{h2osfc} =q_{sat}^{T_{h2osfc} } + +The specific humidity of the soil surface :math:`q_{soil}` is assumed +to be proportional to the saturation specific humidity + +.. math:: + :label: 5.72) + + q_{soil} =\alpha _{soil} q_{sat}^{T_{1} } + +where :math:`q_{sat}^{T_{1} }` is the saturated specific humidity at +the soil surface temperature :math:`T_{1}` (section 5.5). The factor +:math:`\alpha _{soil}` is a function of the surface soil water matric +potential :math:`\psi` as in Philip (1957) + +.. math:: + :label: 5.73) + + \alpha _{soil} =\exp \left(\frac{\psi _{1} g}{1\times 10^{3} R_{wv} T_{1} } \right) + +where :math:`R_{wv}` is the gas constant for water vapor (J +kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), :math:`g` is the +gravitational acceleration (m s\ :math:`{}^{-2}`) (Table 2.6), and +:math:`\psi _{1}` is the soil water matric potential of the top soil +layer (mm). The soil water matric potential :math:`\psi _{1}` is + +.. math:: + :label: 5.74) + + \psi _{1} =\psi _{sat,\, 1} s_{1}^{-B_{1} } \ge -1\times 10^{8} + +where :math:`\psi _{sat,\, 1}` is the saturated matric potential (mm) +(section 7.4.1), :math:`B_{1}` is the Clapp and Hornberger (1978) +parameter (section 7.4.1), and :math:`s_{1}` is the wetness of the top +soil layer with respect to saturation. The surface wetness +:math:`s_{1}` is a function of the liquid water and ice content + +.. math:: + :label: 5.75) + + s_{1} =\frac{1}{\Delta z_{1} \theta _{sat,\, 1} } \left[\frac{w_{liq,\, 1} }{\rho _{liq} } +\frac{w_{ice,\, 1} }{\rho _{ice} } \right]\qquad 0.01\le s_{1} \le 1.0 + +where :math:`\Delta z_{1}` is the thickness of the top soil layer (m), +:math:`\rho _{liq}` and :math:`\rho _{ice}` are the density of liquid +water and ice (kg m\ :math:`{}^{-3}`) (Table 2.6), :math:`w_{liq,\, 1}` +and :math:`w_{ice,\, 1}` are the mass of liquid water and ice of the +top soil layer (:math:`\text{kg} \text{m}^{-2}`) (Chapter 7), and +:math:`\theta _{sat,\, 1}` is the saturated volumetric water content +(i.e., porosity) of the top soil layer (:math:`\text{mm}^{3}` :math:`\text{mm}^{-3}`) (section 7.4.1). If +:math:`q_{sat}^{T_{1} } >q_{atm}` and :math:`q_{atm} >q_{soil}` , then +:math:`q_{soil} =q_{atm}` and :math:`\frac{dq_{soil} }{dT} =0`. This +prevents large increases (decreases) in :math:`q_{soil}` for small +increases (decreases) in soil moisture in very dry soils. + +The function :math:`\beta _{soi}` ranges from 0 to 1 and is intended to +represent the molecular diffusion process from the soil pore to the +surface within the dry part of the soil (Sakaguchi and Zeng 2009) as + +.. math:: + :label: 5.76) + + \beta _{soi} =\left\{\begin{array}{l} {1\qquad \theta _{1} \ge \theta _{fc,\, 1} {\rm \; or\; }q_{atm} -q_{soil} >0} \\ {0.25\left(1-f_{sno} -f_{h2osfc} \right)\left[1-\cos \left(\pi \frac{\theta _{1} }{\theta _{fc,\, 1} } \right)\right]^{2} +f_{sno} +f_{h2osfc} \qquad \theta _{1} <\theta _{fc,\, 1} } \end{array}\right\}. + +where :math:`\theta _{fc,\, 1}` is the field capacity of the top soil +layer and +:math:`0.01{\le \theta _{1} \mathord{\left/ {\vphantom {\le \theta _{1} \theta _{fc,\, 1} \le 1}} \right. \kern-\nulldelimiterspace} \theta _{fc,\, 1} \le 1}` . +The volumetric water content of the top soil layer (:math:`\text{mm}^{3}` :math:`\text{mm}^{-3}`) is + +.. math:: + :label: 5.77) + + \theta _{1} =\frac{1}{\Delta z_{1} } \left[\frac{w_{liq,\, 1} }{\rho _{liq} } +\frac{w_{ice,\, 1} }{\rho _{ice} } \right]. + +The volumetric water content at field capacity is derived by assuming a +hydraulic conductivity of 0.1 mm day\ :math:`{}^{-1}` and inverting the +hydraulic conductivity function (section 7.4.1) as + +.. math:: + :label: 5.78) + + \theta _{fc,\, 1} =\theta _{sat,\, 1} \left[\frac{0.1}{86400k_{sat,\, 1} } \right]^{\frac{1}{2B_{i} +3} } + +where :math:`k_{sat,\, 1}` is the saturated hydraulic conductivity of +the top soil layer (mm s\ :math:`{}^{-1}`) (section 7.4.1) and the +exponent :math:`B_{1}` is a function of soil texture (section 7.4.1). + +The roughness lengths used to calculate :math:`r_{am}` , +:math:`r_{ah}` , and :math:`r_{aw}` are :math:`z_{0m} =z_{0m,\, g}` , +:math:`z_{0h} =z_{0h,\, g}` , and :math:`z_{0w} =z_{0w,\, g}` . The +displacement height :math:`d=0`. The momentum roughness length is +:math:`z_{0m,\, g} =0.01` for soil, glaciers, and wetland, and +:math:`z_{0m,\, g} =0.0024` for snow-covered surfaces +(:math:`f_{sno} >0`). In general, :math:`z_{0m}` is different from +:math:`z_{0h}` because the transfer of momentum is affected by pressure +fluctuations in the turbulent waves behind the roughness elements, while +for heat and water vapor transfer no such dynamical mechanism exists. +Rather, heat and water vapor must be transferred by molecular diffusion +across the interfacial sublayer. The following relation from +Zilitinkevich (1970) is adopted by Zeng and Dickinson (1998) + +.. math:: + :label: ZEqnNum844212 + + z_{0h,\, g} =z_{0w,\, g} =z_{0m,\, g} e^{-a\left({u_{*} z_{0m,\, g} \mathord{\left/ {\vphantom {u_{*} z_{0m,\, g} \upsilon }} \right. \kern-\nulldelimiterspace} \upsilon } \right)^{0.45} } + +where the quantity +:math:`{u_{*} z_{0m,\, g} \mathord{\left/ {\vphantom {u_{*} z_{0m,\, g} \upsilon }} \right. \kern-\nulldelimiterspace} \upsilon }` +is the roughness Reynolds number (and may be interpreted as the Reynolds +number of the smallest turbulent eddy in the flow) with the kinematic +viscosity of air :math:`\upsilon =1.5\times 10^{-5}` m\ :math:`{}^{2}` +s\ :math:`{}^{-1}` and :math:`a=0.13`. + +The numerical solution for the fluxes of momentum, sensible heat, and +water vapor flux from non-vegetated surfaces proceeds as follows: + +#. An initial guess for the wind speed :math:`V_{a}` is obtained from + eq. assuming an initial convective velocity :math:`U_{c} =0` m + s\ :math:`{}^{-1}` for stable conditions + (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from + eq. ) and :math:`U_{c} =0.5` for unstable conditions + (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). + +#. An initial guess for the Monin-Obukhov length :math:`L` is obtained + from the bulk Richardson number using eqs. and . + +#. The following system of equations is iterated three times: + +#. Friction velocity :math:`u_{*}` (eqs. , , , ) + +#. Potential temperature scale :math:`\theta _{*}` (eqs. , , , ) + +#. Humidity scale :math:`q_{*}` (eqs. , , , ) + +#. Roughness lengths for sensible :math:`z_{0h,\, g}` and latent heat + :math:`z_{0w,\, g}` (eq. ) + +#. Virtual potential temperature scale :math:`\theta _{v*}` (eq. ) + +#. Wind speed including the convective velocity, :math:`V_{a}` (eq. ) + +#. Monin-Obukhov length :math:`L` (eq. ) + +#. Aerodynamic resistances :math:`r_{am}` , :math:`r_{ah}` , and + :math:`r_{aw}` (eqs. , , ) + +#. Momentum fluxes :math:`\tau _{x}` , :math:`\tau _{y}` (eqs. , ) + +#. Sensible heat flux :math:`H_{g}` (eq. ) + +#. Water vapor flux :math:`E_{g}` (eq. ) + +#. 2-m height air temperature :math:`T_{2m}` and specific humidity + :math:`q_{2m}` (eqs. , ) + +The partial derivatives of the soil surface fluxes with respect to +ground temperature, which are needed for the soil temperature +calculations (section 6.1) and to update the soil surface fluxes +(section 5.4), are + +.. math:: + :label: ZEqnNum806472 + + \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r_{ah} } + +.. math:: + :label: ZEqnNum497230 + + \frac{\partial E_{g} }{\partial T_{g} } =\frac{\beta _{soi} \rho _{atm} }{r_{aw} } \frac{dq_{g} }{dT_{g} } + +where + +.. math:: + :label: 5.82) + + \frac{dq_{g} }{dT_{g} } =\left(1-f_{sno} -f_{h2osfc} \right)\alpha _{soil} \frac{dq_{sat}^{T_{soil} } }{dT_{soil} } +f_{sno} \frac{dq_{sat}^{T_{sno} } }{dT_{sno} } +f_{h2osfc} \frac{dq_{sat}^{T_{h2osfc} } }{dT_{h2osfc} } . + +The partial derivatives +:math:`\frac{\partial r_{ah} }{\partial T_{g} }` and +:math:`\frac{\partial r_{aw} }{\partial T_{g} }` , which cannot be +determined analytically, are ignored for +:math:`\frac{\partial H_{g} }{\partial T_{g} }` and +:math:`\frac{\partial E_{g} }{\partial T_{g} }` . + +Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces +-------------------------------------------------------------------------- + +In the case of a vegetated surface, the sensible heat :math:`H` and +water vapor flux :math:`E` are partitioned into vegetation and ground +fluxes that depend on vegetation :math:`T_{v}` and ground +:math:`T_{g}` temperatures in addition to surface temperature +:math:`T_{s}` and specific humidity :math:`q_{s}` . Because of the +coupling between vegetation temperature and fluxes, Newton-Raphson +iteration is used to solve for the vegetation temperature and the +sensible heat and water vapor fluxes from vegetation simultaneously +using the ground temperature from the previous time step. In section +5.3.1, the equations used in the iteration scheme are derived. Details +on the numerical scheme are provided in section 5.3.2. + +Theory +^^^^^^^^^^^^ + +The air within the canopy is assumed to have negligible capacity to +store heat so that the sensible heat flux :math:`H` between the surface +at height :math:`z_{0h} +d` and the atmosphere at height +:math:`z_{atm,\, h}` must be balanced by the sum of the sensible heat +from the vegetation :math:`H_{v}` and the ground :math:`H_{g}` + +.. math:: + :label: ZEqnNum550014 + + H=H_{v} +H_{g} + +where, with reference to Figure 5.1, + +.. math:: + :label: 5.84) + + H=-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{s} \right)}{r_{ah} } + +.. math:: + :label: ZEqnNum675188 + + H_{v} =-\rho _{atm} C_{p} \left(T_{s} -T_{v} \right)\frac{\left(L+S\right)}{r_{b} } + +.. math:: + :label: ZEqnNum293573 + + H_{g} =\left(1-f_{sno} -f_{h2osfc} \right)H_{soil} +f_{sno} H_{snow} +f_{h2osfc} H_{h2osfc} + +.. math:: + :label: 5.87) + + H_{soil} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{1} \right)}{r_{ah} ^{{'} } } + +.. math:: + :label: 5.88) + + H_{sno} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{snl+1} \right)}{r_{ah} ^{{'} } } + +.. math:: + :label: 5.89) + + H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{h2osfc} \right)}{r_{ah} ^{{'} } } + +where :math:`\rho _{atm}` is the density of atmospheric air (kg +m\ :math:`{}^{-3}`), :math:`C_{p}` is the specific heat capacity of air +(J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), +:math:`\theta _{atm}` is the atmospheric potential temperature (K), and +:math:`r_{ah}` is the aerodynamic resistance to sensible heat transfer +(s m\ :math:`{}^{-1}`). + +Here, :math:`T_{s}` is the surface temperature at height +:math:`z_{0h} +d`, also referred to as the canopy air temperature. +:math:`L` and :math:`S` are the exposed leaf and stem area indices +(section 2.1.4), :math:`r_{b}` is the leaf boundary layer resistance (s +m\ :math:`{}^{-1}`), and :math:`r_{ah} ^{{'} }` is the aerodynamic +resistance (s m\ :math:`{}^{-1}`) to heat transfer between the ground at +height :math:`z_{0h} ^{{'} }` and the canopy air at height +:math:`z_{0h} +d`. + +Figure 5.1. Schematic diagram of sensible heat fluxes for (a) +non-vegetated surfaces and (b) vegetated surfaces. + +.. image:: image1.png + +Figure 5.2. Schematic diagram of water vapor fluxes for (a) +non-vegetated surfaces and (b) vegetated surfaces. + +.. image:: image2.png + +Equations - can be solved for the canopy air temperature :math:`T_{s}` + +.. math:: + :label: ZEqnNum103571 + + T_{s} =\frac{c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} +c_{v}^{h} T_{v} }{c_{a}^{h} +c_{g}^{h} +c_{v}^{h} } + +where + +.. math:: + :label: ZEqnNum298904 + + c_{a}^{h} =\frac{1}{r_{ah} } + +.. math:: + :label: ZEqnNum991533 + + c_{g}^{h} =\frac{1}{r_{ah} ^{{'} } } + +.. math:: + :label: ZEqnNum284616 + + c_{v}^{h} =\frac{\left(L+S\right)}{r_{b} } + +are the sensible heat conductances from the canopy air to the +atmosphere, the ground to canopy air, and leaf surface to canopy air, +respectively (m s\ :math:`{}^{-1}`). + +When the expression for :math:`T_{s}` is substituted into equation , +the sensible heat flux from vegetation :math:`H_{v}` is a function of +:math:`\theta _{atm}` , :math:`T_{g}` , and :math:`T_{v}` + +.. math:: + :label: ZEqnNum362496 + + H_{v} =-\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} -\left(c_{a}^{h} +c_{g}^{h} \right)T_{v} \right]\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . + +Similarly, the expression for :math:`T_{s}` can be substituted into +equation to obtain the sensible heat flux from ground :math:`H_{g}` + +.. math:: + :label: ZEqnNum527667 + + H_{g} =-\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{v}^{h} T_{v} -\left(c_{a}^{h} +c_{v}^{h} \right)T_{g} \right]\frac{c_{g}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . + +The air within the canopy is assumed to have negligible capacity to +store water vapor so that the water vapor flux :math:`E` between the +surface at height :math:`z_{0w} +d` and the atmosphere at height +:math:`z_{atm,\, w}` must be balanced by the sum of the water vapor +flux from the vegetation :math:`E_{v}` and the ground :math:`E_{g}` + +.. math:: + :label: ZEqnNum365017 + + E=E_{v} +E_{g} + +where, with reference to Figure 5.2, + +.. math:: + :label: 5.97) + + E=-\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } + +.. math:: + :label: ZEqnNum351492 + + E_{v} =-\rho _{atm} \frac{\left(q_{s} -q_{sat}^{T_{v} } \right)}{r_{total} } + +.. math:: + :label: ZEqnNum145330 + + E_{g} =\left(1-f_{sno} -f_{h2osfc} \right)E_{soil} +f_{sno} E_{snow} +f_{h2osfc} E_{h2osfc} + +.. math:: + :label: 5.100) + + E_{soil} =-\rho _{atm} \frac{\beta _{soi} \left(q_{s} -q_{soil} \right)}{r_{aw} ^{{'} } +r_{litter} } + +.. math:: + :label: 5.101) + + E_{sno} =-\rho _{atm} \frac{\left(q_{s} -q_{sno} \right)}{r_{aw} ^{{'} } +r_{litter} } + +.. math:: + :label: 5.102) + + E_{h2osfc} =-\rho _{atm} \frac{\left(q_{s} -q_{h2osfc} \right)}{r_{aw} ^{{'} } +r_{litter} } + +where :math:`q_{atm}` is the atmospheric specific humidity (kg +kg\ :math:`{}^{-1}`), :math:`r_{aw}` is the aerodynamic resistance to +water vapor transfer (s m\ :math:`{}^{-1}`), :math:`q_{sat}^{T_{v} }` +(kg kg\ :math:`{}^{-1}`) is the saturation water vapor specific humidity +at the vegetation temperature (section 5.5), :math:`q_{g}` , +:math:`q_{sno}` , and :math:`q_{h2osfc}` are the specific humidities +of the soil, snow, and surface water (section 5.2), +:math:`r_{aw} ^{{'} }` is the aerodynamic resistance (s +m\ :math:`{}^{-1}`) to water vapor transfer between the ground at height +:math:`z_{0w} ^{{'} }` and the canopy air at height :math:`z_{0w} +d`, +:math:`\beta _{soi}` is an empirical function of soil water (section +5.2), and :math:`r_{litter}` is a resistance for the plant litter layer +(s m\ :math:`{}^{-1}`). :math:`r_{total}` is the total resistance to +water vapor transfer from the canopy to the canopy air and includes +contributions from leaf boundary layer and sunlit and shaded stomatal +resistances :math:`r_{b}` , :math:`r_{s}^{sun}` , and +:math:`r_{s}^{sha}` (Figure 5.2). The water vapor flux from vegetation +is the sum of water vapor flux from wetted leaf and stem area +:math:`E_{v}^{w}` (evaporation of water intercepted by the canopy) and +transpiration from dry leaf surfaces :math:`E_{v}^{t}` + +.. math:: + :label: 5.103) + + E_{v} =E_{v}^{w} +E_{v}^{t} . + +Equations - can be solved for the canopy specific humidity +:math:`q_{s}` + +.. math:: + :label: ZEqnNum362168 + + q_{s} =\frac{c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} +c_{v}^{w} q_{sat}^{T_{v} } }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } + +where + +.. math:: + :label: ZEqnNum533553 + + c_{a}^{w} =\frac{1}{r_{aw} } + +.. math:: + :label: ZEqnNum544982 + + c_{v}^{w} =\frac{\left(L+S\right)}{r_{b} } r'' + +.. math:: + :label: ZEqnNum888691 + + c_{g}^{w} =\frac{\beta _{soi} }{r_{aw} ^{{'} } +r_{litter} } + +are the water vapor conductances from the canopy air to the atmosphere, +the leaf to canopy air, and ground to canopy air, respectively. The term +:math:`r''` is determined from contributions by wet leaves and +transpiration and limited by available water and potential evaporation +as + +.. math:: + :label: ZEqnNum166006 + + r''=\left\{\begin{array}{l} {\min \left(f_{wet} +r_{dry} ^{{'} {'} } ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} >0} \\ {\min \left(f_{wet} ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} \le 0} \\ {1\qquad E_{v}^{w,\, pot} \le 0} \end{array}\right\} + +where :math:`f_{wet}` is the fraction of leaves and stems that are wet +(section 7.1), :math:`W_{can}` is canopy water (kg m\ :math:`{}^{-2}`) +(section 7.1), :math:`\Delta t` is the time step (s), and +:math:`\beta _{t}` is a soil moisture function limiting transpiration +(Chapter 8). The potential evaporation from wet foliage per unit wetted +area is + +.. math:: + :label: 5.109) + + E_{v}^{w,\, pot} =-\frac{\rho _{atm} \left(q_{s} -q_{sat}^{T_{v} } \right)}{r_{b} } . + +The term :math:`r_{dry} ^{{'} {'} }` is + +.. math:: + :label: 5.110) + + r_{dry} ^{{'} {'} } =\frac{f_{dry} r_{b} }{L} \left(\frac{L^{sun} }{r_{b} +r_{s}^{sun} } +\frac{L^{sha} }{r_{b} +r_{s}^{sha} } \right) + +where :math:`f_{dry}` is the fraction of leaves that are dry (section +7.1), :math:`L^{sun}` and :math:`L^{sha}` are the sunlit and shaded +leaf area indices (section 4.1), and :math:`r_{s}^{sun}` and +:math:`r_{s}^{sha}` are the sunlit and shaded stomatal resistances (s +m\ :math:`{}^{-1}`) (Chapter 8). + +When the expression for :math:`q_{s}` is substituted into equation , +the water vapor flux from vegetation :math:`E_{v}` is a function of +:math:`q_{atm}` , :math:`q_{g}` , and :math:`q_{sat}^{T_{v} }` + +.. math:: + :label: ZEqnNum256012 + + E_{v} =-\rho _{atm} \left[c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} -\left(c_{a}^{w} +c_{g}^{w} \right)q_{sat}^{T_{v} } \right]\frac{c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } . + +Similarly, the expression for :math:`q_{s}` can be substituted into +equation to obtain the water vapor flux from the ground beneath the +canopy :math:`E_{g}` + +.. math:: + :label: ZEqnNum243941 + + E_{g} =-\rho _{atm} \left[c_{a}^{w} q_{atm} +c_{v}^{w} q_{sat}^{T_{v} } -\left(c_{a}^{w} +c_{v}^{w} \right)q_{g} \right]\frac{c_{g}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } . + +The aerodynamic resistances to heat (moisture) transfer between the +ground at height :math:`z_{0h} ^{{'} }` (:math:`z_{0w} ^{{'} }` ) and +the canopy air at height :math:`z_{0h} +d` (:math:`z_{0w} +d`) are + +.. math:: + :label: ZEqnNum496775 + + r_{ah} ^{{'} } =r_{aw} ^{{'} } =\frac{1}{C_{s} U_{av} } + +where + +.. math:: + :label: ZEqnNum781547 + + U_{av} =V_{a} \sqrt{\frac{1}{r_{am} V_{a} } } =u_{*} + +is the magnitude of the wind velocity incident on the leaves +(equivalent here to friction velocity) (m s\ :math:`{}^{-1}`) and +:math:`C_{s}` is the turbulent transfer coefficient between the +underlying soil and the canopy air. :math:`C_{s}` is obtained by +interpolation between values for dense canopy and bare soil (Zeng et al. +2005) + +.. math:: + :label: 5.115) + + C_{s} =C_{s,\, bare} W+C_{s,\, dense} (1-W) + +where the weight :math:`W` is + +.. math:: + :label: 5.116) + + W=e^{-\left(L+S\right)} . + +The dense canopy turbulent transfer coefficient in Zeng et al. (2005) +is modified from its original value of 0.004 (Dickinson et al. 1993) by +Sakaguchi and Zeng (2009) to account for stability as + +.. math:: + :label: 5.117) + + C_{s,\, dense} =\left\{\begin{array}{l} {0.004\qquad T_{s} -T_{g} \le 0} \\ {\frac{0.004}{1+\gamma \min \left(S,10\right)} \qquad T_{s} -T_{g} >0} \end{array}\right\} + +where :math:`\gamma =0.5` and :math:`S` is a stability parameter +determined from + +.. math:: + :label: 5.118) + + S=\frac{gz_{top} \left(T_{s} -T_{g} \right)}{T_{s} u_{*}^{2} } + +where :math:`g` is the gravitational acceleration (m +s\ :math:`{}^{-2}`) (Table 2.6), and :math:`z_{top}` is canopy top +height (m) (Table 2.2). The bare soil turbulent transfer coefficient is + +.. math:: + :label: 5.119) + + C_{s,\, bare} =\frac{k}{a} \left(\frac{z_{0m,\, g} U_{av} }{\upsilon } \right)^{-0.45} + +where the kinematic viscosity of air +:math:`\upsilon =1.5\times 10^{-5}` m\ :math:`{}^{2}` +s\ :math:`{}^{-1}` and :math:`a=0.13`. + +The litter resistance :math:`r_{litter}` (Sakaguchi and Zeng 2009) (s +m\ :math:`{}^{-1}`) is + +.. math:: + :label: 5.120) + + r_{litter} =\frac{1}{0.004u_{*} } \left(1-e^{-L_{litter}^{eff} } \right) + +where the effective litter area index :math:`L_{litter}^{eff}` +(:math:`\text{m}^{2}` :math:`\text{m}^{-2}`) is the fraction of plant litter +area index :math:`L_{litter}` (currently set to 0.5 :math:`\text{m}^{2}` +:math:`\text{m}^{-2}`) that is not covered by snow + +.. math:: + :label: 5.121) + + L_{litter}^{eff} =L_{litter} \left[1-\min \left(f_{litter}^{snow} ,\, 1\right)\right]. + +The effective snow cover of the litter layer is + +.. math:: + :label: 5.122) + + f_{litter}^{snow} =\frac{z_{sno} }{\Delta z_{litter} } + +where :math:`\Delta z_{litter} =0.05`\ m is assumed as a typical depth +for the litter layer, and :math:`z_{sno}` is the depth of snow (section +7.2) (m). + +The leaf boundary layer resistance :math:`r_{b}` is + +.. math:: + :label: ZEqnNum181758 + + r_{b} =\frac{1}{C_{v} } \left({U_{av} \mathord{\left/ {\vphantom {U_{av} d_{leaf} }} \right. \kern-\nulldelimiterspace} d_{leaf} } \right)^{{-1\mathord{\left/ {\vphantom {-1 2}} \right. \kern-\nulldelimiterspace} 2} } + +where :math:`C_{v} =0.01` m s\ :math:`{}^{-1/2}` is the turbulent +transfer coefficient between the canopy surface and canopy air, and +:math:`d_{leaf}` is the characteristic dimension of the leaves in the +direction of wind flow (Table 5.1). + +The partial derivatives of the fluxes from the soil beneath the canopy +with respect to ground temperature, which are needed for the soil +temperature calculations (section 6.1) and to update the soil surface +fluxes (section 5.4), are + +.. math:: + :label: ZEqnNum774729 + + \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r'_{ah} } \frac{c_{a}^{h} +c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } + +.. math:: + :label: ZEqnNum562232 + + \frac{\partial E_{g} }{\partial T_{g} } =\frac{\beta _{soi} \rho _{atm} }{r'_{aw} +r_{litter} } \frac{c_{a}^{w} +c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{g} }{dT_{g} } . + +The partial derivatives +:math:`\frac{\partial r'_{ah} }{\partial T_{g} }` and +:math:`\frac{\partial r'_{aw} }{\partial T_{g} }` , which cannot be +determined analytically, are ignored for +:math:`\frac{\partial H_{g} }{\partial T_{g} }` and +:math:`\frac{\partial E_{g} }{\partial T_{g} }` . + +The roughness lengths used to calculate :math:`r_{am}` , +:math:`r_{ah}` , and :math:`r_{aw}` from equations , , and are +:math:`z_{0m} =z_{0m,\, v}` , :math:`z_{0h} =z_{0h,\, v}` , and +:math:`z_{0w} =z_{0w,\, v}` . The vegetation displacement height +:math:`d` and the roughness lengths are a function of plant height and +adjusted for canopy density following Zeng and Wang (2007) + +.. math:: + :label: 5.126) + + z_{0m,\, v} =z_{0h,\, v} =z_{0w,\, v} =\exp \left[V\ln \left(z_{top} R_{z0m} \right)+\left(1-V\right)\ln \left(z_{0m,\, g} \right)\right] + +.. math:: + :label: 5.127) + + d=z_{top} R_{d} V + +where :math:`z_{top}` is canopy top height (m) (Table 2.2), +:math:`R_{z0m}` and :math:`R_{d}` are the ratio of momentum roughness +length and displacement height to canopy top height, respectively (Table +5.1), and :math:`z_{0m,\, g}` is the ground momentum roughness length +(m) (section 5.2). The fractional weight :math:`V` is determined from + +.. math:: + :label: 5.128) + + V=\frac{1-\exp \left\{-\beta \min \left[L+S,\, \left(L+S\right)_{cr} \right]\right\}}{1-\exp \left[-\beta \left(L+S\right)_{cr} \right]} + +where :math:`\beta =1` and :math:`\left(L+S\right)_{cr} =2` (:math:`\text{m}^{2}` m\ :math:`{}^{-2}`) is a critical value of exposed leaf +plus stem area for which :math:`z_{0m}` reaches its maximum. + +Table 5.1. Plant functional type aerodynamic parameters + ++----------------------------------+--------------------+------------------+-------------------------+ +| Plant functional type | :math:`R_{z0m}` | :math:`R_{d}` | :math:`d_{leaf}` (m) | ++==================================+====================+==================+=========================+ +| NET Temperate | 0.055 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| NET Boreal | 0.055 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| NDT Boreal | 0.055 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BET Tropical | 0.075 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BET temperate | 0.075 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BDT tropical | 0.055 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BDT temperate | 0.055 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BDT boreal | 0.055 | 0.67 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BES temperate | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BDS temperate | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| BDS boreal | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| C\ :math:`{}_{3}` arctic grass | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| C\ :math:`{}_{3}` grass | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| C\ :math:`{}_{4}` grass | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Crop R | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Crop I | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Corn R | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Corn I | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Temp Cereal R | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Temp Cereal I | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Winter Cereal R | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Winter Cereal I | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Soybean R | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ +| Soybean I | 0.120 | 0.68 | 0.04 | ++----------------------------------+--------------------+------------------+-------------------------+ + +Numerical Implementation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Canopy energy conservation gives + +.. math:: + :label: 5.129) + + -\overrightarrow{S}_{v} +\overrightarrow{L}_{v} \left(T_{v} \right)+H_{v} \left(T_{v} \right)+\lambda E_{v} \left(T_{v} \right)=0 + +where :math:`\overrightarrow{S}_{v}` is the solar radiation absorbed by +the vegetation (section 4.1), :math:`\overrightarrow{L}_{v}` is the net +longwave radiation absorbed by vegetation (section 4.2), and +:math:`H_{v}` and :math:`\lambda E_{v}` are the sensible and latent +heat fluxes from vegetation, respectively. The term :math:`\lambda` is +taken to be the latent heat of vaporization :math:`\lambda _{vap}` +(Table 2.6). + +:math:`\overrightarrow{L}_{v}` , :math:`H_{v}` , and +:math:`\lambda E_{v}` depend on the vegetation temperature +:math:`T_{v}` . The Newton-Raphson method for finding roots of +non-linear systems of equations can be applied to iteratively solve for +:math:`T_{v}` as + +.. math:: + :label: ZEqnNum247755 + + \Delta T_{v} =\frac{\overrightarrow{S}_{v} -\overrightarrow{L}_{v} -H_{v} -\lambda E_{v} }{\frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } +\frac{\partial H_{v} }{\partial T_{v} } +\frac{\partial \lambda E_{v} }{\partial T_{v} } } + +where :math:`\Delta T_{v} =T_{v}^{n+1} -T_{v}^{n}` and the subscript +“n†indicates the iteration. + +The partial derivatives are + +.. math:: + :label: 5.131) + + \frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } =4\varepsilon _{v} \sigma \left[2-\varepsilon _{v} \left(1-\varepsilon _{g} \right)\right]T_{v}^{3} + +.. math:: + :label: 5.132) + + \frac{\partial H_{v} }{\partial T_{v} } =\rho _{atm} C_{p} \left(c_{a}^{h} +c_{g}^{h} \right)\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } + +.. math:: + :label: 5.133) + + \frac{\partial \lambda E_{v} }{\partial T_{v} } =\lambda \rho _{atm} \left(c_{a}^{w} +c_{g}^{w} \right)\frac{c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{sat}^{T_{v} } }{dT_{v} } . + +The partial derivatives +:math:`\frac{\partial r_{ah} }{\partial T_{v} }` and +:math:`\frac{\partial r_{aw} }{\partial T_{v} }` , which cannot be +determined analytically, are ignored for +:math:`\frac{\partial H_{v} }{\partial T_{v} }` and +:math:`\frac{\partial \lambda E_{v} }{\partial T_{v} }` . However, if +:math:`\zeta` changes sign more than four times during the temperature +iteration, :math:`\zeta =-0.01`. This helps prevent “flip-flopping†+between stable and unstable conditions. The total water vapor flux +:math:`E_{v}` , transpiration flux :math:`E_{v}^{t}` , and sensible heat +flux :math:`H_{v}` are updated for changes in leaf temperature as + +.. math:: + :label: ZEqnNum420059 + + E_{v} =-\rho _{atm} \left[c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} -\left(c_{a}^{w} +c_{g}^{w} \right)\left(q_{sat}^{T_{v} } +\frac{dq_{sat}^{T_{v} } }{dT_{v} } \Delta T_{v} \right)\right]\frac{c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } + +.. math:: + :label: ZEqnNum554100 + + E_{v}^{t} =-r_{dry} ^{{'} {'} } \rho _{atm} \left[c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} -\left(c_{a}^{w} +c_{g}^{w} \right)\left(q_{sat}^{T_{v} } +\frac{dq_{sat}^{T_{v} } }{dT_{v} } \Delta T_{v} \right)\right]\frac{c_{v}^{h} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } + +.. math:: + :label: ZEqnNum839021 + + H_{v} =-\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} -\left(c_{a}^{h} +c_{g}^{h} \right)\left(T_{v} +\Delta T_{v} \right)\right]\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . + +The numerical solution for vegetation temperature and the fluxes of +momentum, sensible heat, and water vapor flux from vegetated surfaces +proceeds as follows: + +#. Initial values for canopy air temperature and specific humidity are + obtained from + + .. math:: + :label: 5.137) + + T_{s} =\frac{T_{g} +\theta _{atm} }{2} + + .. math:: + :label: 5.138) + + q_{s} =\frac{q_{g} +q_{atm} }{2} . + +#. An initial guess for the wind speed :math:`V_{a}` is obtained from + eq. assuming an initial convective velocity :math:`U_{c} =0` m + s\ :math:`{}^{-1}` for stable conditions + (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from + eq. ) and :math:`U_{c} =0.5` for unstable conditions + (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). + +#. An initial guess for the Monin-Obukhov length :math:`L` is obtained + from the bulk Richardson number using equation and . + +#. Iteration proceeds on the following system of equations: + +#. Friction velocity :math:`u_{*}` (eqs. , , , ) + +#. Ratio :math:`\frac{\theta _{*} }{\theta _{atm} -\theta _{s} }` (eqs. + , , , ) + +#. Ratio :math:`\frac{q_{*} }{q_{atm} -q_{s} }` (eqs. , , , ) + +#. Aerodynamic resistances :math:`r_{am}` , :math:`r_{ah}` , and + :math:`r_{aw}` (eqs. , , ) + +#. Magnitude of the wind velocity incident on the leaves :math:`U_{av}` + (eq. ) + +#. Leaf boundary layer resistance :math:`r_{b}` (eq. ) + +#. Aerodynamic resistances :math:`r_{ah} ^{{'} }` and + :math:`r_{aw} ^{{'} }` (eq. ) + +#. Sunlit and shaded stomatal resistances :math:`r_{s}^{sun}` and + :math:`r_{s}^{sha}` (Chapter 8) + +#. Sensible heat conductances :math:`c_{a}^{h}` , :math:`c_{g}^{h}` , + and :math:`c_{v}^{h}` (eqs. , , ) + +#. Latent heat conductances :math:`c_{a}^{w}` , :math:`c_{v}^{w}` , and + :math:`c_{g}^{w}` (eqs. , , ) + +#. Sensible heat flux from vegetation :math:`H_{v}` (eq. ) + +#. Latent heat flux from vegetation :math:`\lambda E_{v}` (eq. ) + +#. If the latent heat flux has changed sign from the latent heat flux + computed at the previous iteration + (:math:`\lambda E_{v} ^{n+1} \times \lambda E_{v} ^{n} <0`), the + latent heat flux is constrained to be 10% of the computed value. The + difference between the constrained and computed value + (:math:`\Delta _{1} =0.1\lambda E_{v} ^{n+1} -\lambda E_{v} ^{n+1}` ) + is added to the sensible heat flux later. + +#. Change in vegetation temperature :math:`\Delta T_{v}` (eq. ) and + update the vegetation temperature as + :math:`T_{v}^{n+1} =T_{v}^{n} +\Delta T_{v}` . :math:`T_{v}` is + constrained to change by no more than 1ºK in one iteration. If this + limit is exceeded, the energy error is + + .. math:: + :label: 5.139) + + \Delta _{2} =\overrightarrow{S}_{v} -\overrightarrow{L}_{v} -\frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } \Delta T_{v} -H_{v} -\frac{\partial H_{v} }{\partial T_{v} } \Delta T_{v} -\lambda E_{v} -\frac{\partial \lambda E_{v} }{\partial T_{v} } \Delta T_{v} + +where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error +:math:`\Delta _{2}` is added to the sensible heat flux later. + +#. Water vapor flux :math:`E_{v}` (eq. ) + +#. Transpiration :math:`E_{v}^{t}` (eq. if :math:`\beta _{t} >0`, + otherwise :math:`E_{v}^{t} =0`) + +#. The water vapor flux :math:`E_{v}` is constrained to be less than or + equal to the sum of transpiration :math:`E_{v}^{t}` and the water + available from wetted leaves and stems + :math:`{W_{can} \mathord{\left/ {\vphantom {W_{can} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` . + The energy error due to this constraint is + + .. math:: + :label: 5.140) + + \Delta _{3} =\max \left(0,\, E_{v} -E_{v}^{t} -\frac{W_{can} }{\Delta t} \right). + +The error :math:`\lambda \Delta _{3}` is added to the sensible heat +flux later. + +#. Sensible heat flux :math:`H_{v}` (eq. ). The three energy error + terms, :math:`\Delta _{1}` , :math:`\Delta _{2}` , and + :math:`\lambda \Delta _{3}` are also added to the sensible heat + flux. + +#. The saturated vapor pressure :math:`e_{i}` (Chapter 8), saturated + specific humidity :math:`q_{sat}^{T_{v} }` and its derivative + :math:`\frac{dq_{sat}^{T_{v} } }{dT_{v} }` at the leaf surface + (section 5.5), are re-evaluated based on the new :math:`T_{v}` . + +#. Canopy air temperature :math:`T_{s}` (eq. ) + +#. Canopy air specific humidity :math:`q_{s}` (eq. ) + +#. Temperature difference :math:`\theta _{atm} -\theta _{s}` + +#. Specific humidity difference :math:`q_{atm} -q_{s}` + +#. Potential temperature scale + :math:`\theta _{*} =\frac{\theta _{*} }{\theta _{atm} -\theta _{s} } \left(\theta _{atm} -\theta _{s} \right)` + where :math:`\frac{\theta _{*} }{\theta _{atm} -\theta _{s} }` was + calculated earlier in the iteration + +#. Humidity scale + :math:`q_{*} =\frac{q_{*} }{q_{atm} -q_{s} } \left(q_{atm} -q_{s} \right)` + where :math:`\frac{q_{*} }{q_{atm} -q_{s} }` was calculated earlier + in the iteration + +#. Virtual potential temperature scale :math:`\theta _{v*}` (eq. ) + +#. Wind speed including the convective velocity, :math:`V_{a}` (eq. ) + +#. Monin-Obukhov length :math:`L` (eq. ) + +#. The iteration is stopped after two or more steps if + :math:`\tilde{\Delta }T_{v} <0.01` and + :math:`\left|\lambda E_{v}^{n+1} -\lambda E_{v}^{n} \right|<0.1` + where + :math:`\tilde{\Delta }T_{v} =\max \left(\left|T_{v}^{n+1} -T_{v}^{n} \right|,\, \left|T_{v}^{n} -T_{v}^{n-1} \right|\right)`, + or after forty iterations have been carried out. + +#. Momentum fluxes :math:`\tau _{x}` , :math:`\tau _{y}` (eqs. , ) + +#. Sensible heat flux from ground :math:`H_{g}` (eq. ) + +#. Water vapor flux from ground :math:`E_{g}` (eq. ) + +#. 2-m height air temperature :math:`T_{2m}` , specific humidity + :math:`q_{2m}` , relative humidity :math:`RH_{2m}` \ (eqs. , , ) + +Update of Ground Sensible and Latent Heat Fluxes +---------------------------------------------------- + +The sensible and water vapor heat fluxes derived above for bare soil and +soil beneath canopy are based on the ground surface temperature from the +previous time step :math:`T_{g}^{n}` and are used as the surface +forcing for the solution of the soil temperature equations (section +6.1). This solution yields a new ground surface temperature +:math:`T_{g}^{n+1}` . The ground sensible and water vapor fluxes are +then updated for :math:`T_{g}^{n+1}` as + +.. math:: + :label: 5.141) + + H'_{g} =H_{g} +\left(T_{g}^{n+1} -T_{g}^{n} \right)\frac{\partial H_{g} }{\partial T_{g} } + +.. math:: + :label: 5.142) + + E'_{g} =E_{g} +\left(T_{g}^{n+1} -T_{g}^{n} \right)\frac{\partial E_{g} }{\partial T_{g} } + +where :math:`H_{g}` and :math:`E_{g}` are the sensible heat and water +vapor fluxes derived from equations and for non-vegetated surfaces and +equations and for vegetated surfaces using :math:`T_{g}^{n}` . One +further adjustment is made to :math:`H'_{g}` and :math:`E'_{g}` . If +the soil moisture in the top snow/soil layer is not sufficient to +support the updated ground evaporation, i.e., if :math:`E'_{g} >0` and +:math:`f_{evap} <1` where + +.. math:: + :label: 5.143) + + f_{evap} =\frac{{\left(w_{ice,\; snl+1} +w_{liq,\, snl+1} \right)\mathord{\left/ {\vphantom {\left(w_{ice,\; snl+1} +w_{liq,\, snl+1} \right) \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} }{\sum _{j=1}^{npft}\left(E'_{g} \right)_{j} \left(wt\right)_{j} } \le 1, + +an adjustment is made to reduce the ground evaporation accordingly as + +.. math:: + :label: 5.144) + + E''_{g} =f_{evap} E'_{g} . + +The term +:math:`\sum _{j=1}^{npft}\left(E'_{g} \right)_{j} \left(wt\right)_{j}` +is the sum of :math:`E'_{g}` over all evaporating PFTs where +:math:`\left(E'_{g} \right)_{j}` is the ground evaporation from the +:math:`j^{th}` PFT on the column, :math:`\left(wt\right)_{j}` is the +relative area of the :math:`j^{th}` PFT with respect to the column, and +:math:`npft` is the number of PFTs on the column. +:math:`w_{ice,\, snl+1}` and :math:`w_{liq,\, snl+1}` are the ice and +liquid water contents (kg m\ :math:`{}^{-2}`) of the top snow/soil layer +(Chapter 7). Any resulting energy deficit is assigned to sensible heat +as + +.. math:: + :label: 5.145) + + H''_{g} =H_{g} +\lambda \left(E'_{g} -E''_{g} \right). + +The ground water vapor flux :math:`E''_{g}` is partitioned into +evaporation of liquid water from snow/soil :math:`q_{seva}` (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), sublimation from snow/soil ice +:math:`q_{subl}` (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), liquid dew +on snow/soil :math:`q_{sdew}` (kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`), or frost on snow/soil :math:`q_{frost}` (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) as + +.. math:: + :label: 5.146) + + q_{seva} =\max \left(E''_{sno} \frac{w_{liq,\, snl+1} }{w_{ice,\; snl+1} +w_{liq,\, snl+1} } ,0\right)\qquad E''_{sno} \ge 0,\, w_{ice,\; snl+1} +w_{liq,\, snl+1} >0 + +.. math:: + :label: 5.147) + + q_{subl} =E''_{sno} -q_{seva} \qquad E''_{sno} \ge 0 + +.. math:: + :label: 5.148) + + q_{sdew} =\left|E''_{sno} \right|\qquad E''_{sno} <0{\rm \; and\; }T_{g} \ge T_{f} + +.. math:: + :label: 5.149) + + q_{frost} =\left|E''_{sno} \right|\qquad E''_{sno} <0{\rm \; and\; }T_{g} 0} \\ {\lambda _{vap} \qquad {\rm otherwise}} \end{array}\right\} + +where :math:`\lambda _{sub}` and :math:`\lambda _{vap}` are the latent +heat of sublimation and vaporization, respectively (J +kg\ :math:`{}^{-1}`) (Table 2.6). When converting vegetation water vapor +flux to an energy flux, :math:`\lambda _{vap}` is used. + +The system balances energy as + +.. math:: + :label: 5.154) + + \overrightarrow{S}_{g} +\overrightarrow{S}_{v} +L_{atm} \, \downarrow -L\, \uparrow -H_{v} -H_{g} -\lambda _{vap} E_{v} -\lambda E_{g} -G=0. + +Saturation Vapor Pressure +----------------------------- + +Saturation vapor pressure :math:`e_{sat}^{T}` (Pa) and its derivative +:math:`\frac{de_{sat}^{T} }{dT}` , as a function of temperature +:math:`T` (ºC), are calculated from the eighth-order polynomial fits of +Flatau et al. (1992) + +.. math:: + :label: 5.155) + + e_{sat}^{T} =100\left[a_{0} +a_{1} T+\cdots +a_{n} T^{n} \right] + +.. math:: + :label: 5.156) + + \frac{de_{sat}^{T} }{dT} =100\left[b_{0} +b_{1} T+\cdots +b_{n} T^{n} \right] + +where the coefficients for ice are valid for +:math:`-75\, ^{\circ } {\rm C}\le T<0\, ^{\circ } {\rm C}` and the +coefficients for water are valid for +:math:`0\, ^{\circ } {\rm C}\le T\le 100\, ^{\circ } {\rm C}` (Table 5.2 +and 5.3). The saturated water vapor specific humidity +:math:`q_{sat}^{T}` and its derivative +:math:`\frac{dq_{sat}^{T} }{dT}` are + +.. math:: + :label: 5.157) + + q_{sat}^{T} =\frac{0.622e_{sat}^{T} }{P_{atm} -0.378e_{sat}^{T} } + +.. math:: + :label: 5.158) + + \frac{dq_{sat}^{T} }{dT} =\frac{0.622P_{atm} }{\left(P_{atm} -0.378e_{sat}^{T} \right)^{2} } \frac{de_{sat}^{T} }{dT} . + +Table 5.2. Coefficients for :math:`e_{sat}^{T}` + ++------------------+------------------------------------------+----------------------------------------+ +| | water | ice | ++==================+==========================================+========================================+ +| :math:`a_{0}` | 6.11213476 | 6.11123516 | ++------------------+------------------------------------------+----------------------------------------+ +| :math:`a_{1}` | 4.44007856 :math:`\times 10^{-1}` | 5.03109514\ :math:`\times 10^{-1}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{2}` | 1.43064234 :math:`\times 10^{-2}` | 1.88369801\ :math:`\times 10^{-2}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{3}` | 2.64461437 :math:`\times 10^{-4}` | 4.20547422\ :math:`\times 10^{-4}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{4}` | 3.05903558 :math:`\times 10^{-6}` | 6.14396778\ :math:`\times 10^{-6}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{5}` | 1.96237241 :math:`\times 10^{-8}` | 6.02780717\ :math:`\times 10^{-8}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{6}` | 8.92344772 :math:`\times 10^{-11}` | 3.87940929\ :math:`\times 10^{-10}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{7}` | -3.73208410 :math:`\times 10^{-13}` | 1.49436277\ :math:`\times 10^{-12}` | ++------------------+-------------------------------------------+---------------------------------------+ +| :math:`a_{8}` | 2.09339997 :math:`\times 10^{-16}` | 2.62655803\ :math:`\times 10^{-15}` | ++------------------+------------------------------------------+----------------------------------------+ + +Table 5.3. Coefficients for :math:`\frac{de_{sat}^{T} }{dT}` + ++------------------+----------------------------------------+----------------------------------------+ +| | water | ice | ++==================+========================================+========================================+ +| :math:`b_{0}` | 4.44017302\ :math:`\times 10^{-1}` | 5.03277922\ :math:`\times 10^{-1}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{1}` | 2.86064092\ :math:`\times 10^{-2}` | 3.77289173\ :math:`\times 10^{-2}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{2}` | 7.94683137\ :math:`\times 10^{-4}` | 1.26801703\ :math:`\times 10^{-3}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{3}` | 1.21211669\ :math:`\times 10^{-5}` | 2.49468427\ :math:`\times 10^{-5}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{4}` | 1.03354611\ :math:`\times 10^{-7}` | 3.13703411\ :math:`\times 10^{-7}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{5}` | 4.04125005\ :math:`\times 10^{-10}` | 2.57180651\ :math:`\times 10^{-9}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{6}` | -7.88037859 :math:`\times 10^{-13}` | 1.33268878\ :math:`\times 10^{-11}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{7}` | -1.14596802 :math:`\times 10^{-14}` | 3.94116744\ :math:`\times 10^{-14}` | ++------------------+----------------------------------------+----------------------------------------+ +| :math:`b_{8}` | 3.81294516\ :math:`\times 10^{-17}` | 4.98070196\ :math:`\times 10^{-17}` | ++------------------+----------------------------------------+----------------------------------------+ + diff --git a/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst b/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst new file mode 100644 index 0000000000..d39a780958 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst @@ -0,0 +1,928 @@ +Soil and Snow Temperatures +============================= + +The first law of heat conduction is + +.. math:: + :label: 6.1) + + F=-\lambda \nabla T + +where :math:`F` is the amount of heat conducted across a unit +cross-sectional area in unit time (W m\ :math:`{}^{-2}`), +:math:`\lambda` is thermal conductivity (W m\ :math:`{}^{-1}` +K\ :math:`{}^{-1}`), and :math:`\nabla T` is the spatial gradient of +temperature (K m\ :math:`{}^{-1}`). In one-dimensional form + +.. math:: + :label: ZEqnNum105915 + + F_{z} =-\lambda \frac{\partial T}{\partial z} + +where :math:`z` is in the vertical direction (m) and is positive +downward and :math:`F_{z}` is positive upward. To account for +non-steady or transient conditions, the principle of energy conservation +in the form of the continuity equation is invoked as + +.. math:: + :label: ZEqnNum376834 + + c\frac{\partial T}{\partial t} =-\frac{\partial F_{z} }{\partial z} + +where :math:`c` is the volumetric snow/soil heat capacity (J +m\ :math:`{}^{-3}` K\ :math:`{}^{-1}`) and :math:`t` is time (s). +Combining equations and yields the second law of heat conduction in +one-dimensional form + +.. math:: + :label: 6.4) + + c\frac{\partial T}{\partial t} =\frac{\partial }{\partial z} \left[\lambda \frac{\partial T}{\partial z} \right]. + +This equation is solved numerically to calculate the soil, snow, and +surface water temperatures for a fifteen-layer soil column with up to +five overlying layers of snow and a single surface water layer with the +boundary conditions of :math:`h` as the heat flux into the top soil, +snow, and surface water layers from the overlying atmosphere (section +6.1) and zero heat flux at the bottom of the soil column. The +temperature profile is calculated first without phase change and then +readjusted for phase change (section 6.2). + +Numerical Solution +---------------------- + +The soil column is discretized into fifteen layers (Table 6.1) where the +depth of soil layer :math:`i`, or node depth, :math:`z_{i}` (m), is + +.. math:: + :label: ZEqnNum185766 + + z_{i} =f_{s} \left\{\exp \left[0.5\left(i-0.5\right)\right]-1\right\} + +where :math:`f_{s} =0.025` is a scaling factor. The thickness of each +layer :math:`\Delta z_{i}` (m) is + +.. math:: + :label: 6.6) + + \Delta z_{i} =\left\{\begin{array}{l} {0.5\left(z_{1} +z_{2} \right)\qquad i=1} \\ {0.5\left(z_{i+1} -z_{i-1} \right)\qquad i=2,3,\ldots ,N_{levgrnd} -1} \\ {z_{N} -z_{N-1} \qquad i=N_{levgrnd} } \end{array}\right\} + +where :math:`N_{levgrnd} =15` is the number of soil layers. The depths +at the layer interfaces :math:`z_{h,\, i}` (m) are + +.. math:: + :label: 6.7) + + z_{h,\, i} =\left\{\begin{array}{l} {0.5\left(z_{i} +z_{i+1} \right)\qquad i=1,2,\ldots ,N_{levgrnd} -1} \\ {z_{N_{levgrnd} } +0.5\Delta z_{N_{levgrnd} } \qquad i=N_{levgrnd} } \end{array}\right\}. + +The exponential form of equation is to obtain more soil layers near the +soil surface where the soil water gradient is generally strong (section +7.4). + +Table 6.1. Soil layer structure. + +Layer node depth (:math:`z_{i}` ), thickness (:math:`\Delta z_{i}` ), +and depth at layer interface (:math:`z_{h,\, i}` ) for fifteen-layer +soil column. All in meters. + ++---------------+------------------+-------------------------+-----------------------+ +| Layer | :math:`z_{i}` | :math:`\Delta z_{i}` | :math:`z_{h,\, i}` | ++===============+==================+=========================+=======================+ +| 1 (top) | 0.0071 | 0.0175 | 0.0175 | ++---------------+------------------+-------------------------+-----------------------+ +| 2 | 0.0279 | 0.0276 | 0.0451 | ++---------------+------------------+-------------------------+-----------------------+ +| 3 | 0.0623 | 0.0455 | 0.0906 | ++---------------+------------------+-------------------------+-----------------------+ +| 4 | 0.1189 | 0.0750 | 0.1655 | ++---------------+------------------+-------------------------+-----------------------+ +| 5 | 0.2122 | 0.1236 | 0.2891 | ++---------------+------------------+-------------------------+-----------------------+ +| 6 | 0.3661 | 0.2038 | 0.4929 | ++---------------+------------------+-------------------------+-----------------------+ +| 7 | 0.6198 | 0.3360 | 0.8289 | ++---------------+------------------+-------------------------+-----------------------+ +| 8 | 1.0380 | 0.5539 | 1.3828 | ++---------------+------------------+-------------------------+-----------------------+ +| 9 | 1.7276 | 0.9133 | 2.2961 | ++---------------+------------------+-------------------------+-----------------------+ +| 10 | 2.8646 | 1.5058 | 3.8019 | ++---------------+------------------+-------------------------+-----------------------+ +| 11 | 4.7392 | 2.4826 | 6.2845 | ++---------------+------------------+-------------------------+-----------------------+ +| 12 | 7.8298 | 4.0931 | 10.3775 | ++---------------+------------------+-------------------------+-----------------------+ +| 13 | 12.9253 | 6.7484 | 17.1259 | ++---------------+------------------+-------------------------+-----------------------+ +| 14 | 21.3265 | 11.1262 | 28.2520 | ++---------------+------------------+-------------------------+-----------------------+ +| 15 (bottom) | 35.1776 | 13.8512 | 42.1032 | ++---------------+------------------+-------------------------+-----------------------+ + +The overlying snow pack is modeled with up to five layers depending on +the total snow depth. The layers from top to bottom are indexed in the +Fortran code as :math:`i=-4,-3,-2,-1,0`, which permits the accumulation +or ablation of snow at the top of the snow pack without renumbering the +layers. Layer :math:`i=0` is the snow layer next to the soil surface and +layer :math:`i=snl+1` is the top layer, where the variable :math:`snl` +is the negative of the number of snow layers. The number of snow layers +and the thickness of each layer is a function of snow depth +:math:`z_{sno}` (m) as follows. + +.. math:: \left\{\begin{array}{l} {snl=-1} \\ {\Delta z_{0} =z_{sno} \qquad {\rm for\; 0.01}\le {\rm z}_{{\rm sno}} \le 0.03} \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-2} \\ {\Delta z_{-1} ={z_{sno} \mathord{\left/ {\vphantom {z_{sno} 2}} \right. \kern-\nulldelimiterspace} 2} \qquad {\rm for\; 0.03}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.04} \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-2} \\ {\Delta z_{-1} =0.02\qquad {\rm for\; 0.04}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.07} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-3} \\ {\Delta z_{-2} =0.02} \\ {\Delta z_{-1} ={\left(z_{sno} -0.02\right)\mathord{\left/ {\vphantom {\left(z_{sno} -0.02\right) 2}} \right. \kern-\nulldelimiterspace} 2} \qquad {\rm for\; 0.07}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.12} \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-3} \\ {\Delta z_{-2} =0.02} \\ {\Delta z_{-1} =0.05\qquad {\rm for\; 0.12}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.18} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-2} -\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-4} \\ {\Delta z_{-3} =0.02} \\ {\Delta z_{-2} =0.05\qquad {\rm for\; 0.18}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.29} \\ {\Delta z_{-1} ={\left(z_{sno} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-4} \\ {\Delta z_{-3} =0.02} \\ {\Delta z_{-2} =0.05\qquad {\rm for\; 0.29}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.41} \\ {\Delta z_{-1} =0.11} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-5} \\ {\Delta z_{-4} =0.02} \\ {\Delta z_{-3} =0.05\qquad {\rm for\; 0.41}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.64} \\ {\Delta z_{-2} =0.11} \\ {\Delta z_{-1} ={\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, + +.. math:: \left\{\begin{array}{l} {snl=-5} \\ {\Delta z_{-4} =0.02} \\ {\Delta z_{-3} =0.05\qquad {\rm for\; 0.64}\, {\rm <}\, {\rm z}_{{\rm sno}} } \\ {\Delta z_{-2} =0.11} \\ {\Delta z_{-1} =0.23} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} } \end{array}\right\}. + +The node depths, which are located at the midpoint of the snow layers, +and the layer interfaces are both referenced from the soil surface and +are defined as negative values + +.. math:: + :label: 6.8) + + z_{i} =z_{h,\, i} -0.5\Delta z_{i} \qquad i=snl+1,\ldots ,0 + +.. math:: + :label: 6.9) + + z_{h,\, i} =z_{h,\, i+1} -\Delta z_{i+1} \qquad i=snl,\ldots ,-1. + +Note that :math:`z_{h,\, 0}` , the interface between the bottom snow +layer and the top soil layer, is zero. Thermal properties (i.e., +temperature :math:`T_{i}` [K]; thermal conductivity +:math:`\lambda _{i}` [W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`]; +volumetric heat capacity :math:`c_{i}` [J m\ :math:`{}^{-3}` +K\ :math:`{}^{-1}`]) are defined for soil layers at the node depths +(Figure 6.1) and for snow layers at the layer midpoints. When present, +snow occupies a fraction of a grid cell’s area, therefore snow depth +represents the thickness of the snowpack averaged over only the snow +covered area. The grid cell average snow depth is related to the depth +of the snow covered area as :math:`\bar{z}_{sno} =f_{sno} z_{sno}` . By +default, the grid cell average snow depth is written to the history +file. + +The heat flux :math:`F_{i}` (W m\ :math:`{}^{-2}`) from layer :math:`i` +to layer :math:`i+1` is + +.. math:: + :label: ZEqnNum443713 + + F_{i} =-\lambda \left[z_{h,\, i} \right]\left(\frac{T_{i} -T_{i+1} }{z_{i+1} -z_{i} } \right) + +where the thermal conductivity at the interface +:math:`\lambda \left[z_{h,\, i} \right]` is + +.. math:: + :label: ZEqnNum604125 + + \lambda \left[z_{h,\, i} \right]=\left\{\begin{array}{l} {\frac{\lambda _{i} \lambda _{i+1} \left(z_{i+1} -z_{i} \right)}{\lambda _{i} \left(z_{i+1} -z_{h,\, i} \right)+\lambda _{i+1} \left(z_{h,\, i} -z_{i} \right)} \qquad i=snl+1,\ldots ,N_{levgrnd} -1} \\ {0\qquad i=N_{levgrnd} } \end{array}\right\}. + +These equations are derived, with reference to Figure 6.1, assuming +that the heat flux from :math:`i` (depth :math:`z_{i}` ) to the +interface between :math:`i` and :math:`i+1` (depth :math:`z_{h,\, i}` ) +equals the heat flux from the interface to :math:`i+1` (depth +:math:`z_{i+1}` ), i.e., + +.. math:: + :label: ZEqnNum726244 + + -\lambda _{i} \frac{T_{i} -T_{m} }{z_{h,\, i} -z_{i} } =-\lambda _{i+1} \frac{T_{m} -T_{i+1} }{z_{i+1} -z_{h,\, i} } + +where :math:`T_{m}` is the temperature at the interface of layers +:math:`i` and :math:`i+1`. + +Figure 6.1. Schematic diagram of numerical scheme used to solve for soil +temperature. + +Shown are three soil layers, :math:`i-1`, :math:`i`, and :math:`i+1`. +The thermal conductivity :math:`\lambda` , specific heat capacity +:math:`c`, and temperature :math:`T` are defined at the layer node depth +:math:`z`. :math:`T_{m}` is the interface temperature. The thermal +conductivity :math:`\lambda \left[z_{h} \right]` is defined at the +interface of two layers + +:math:`z_{h}` . The layer thickness is :math:`\Delta z`. The heat fluxes +:math:`F_{i-1}` and :math:`F_{i}` are defined as positive upwards. + +.. image:: image1.png + + +The energy balance for the :math:`i^{th}` layer is + +.. math:: + :label: 6.13) + + \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=-F_{i-1} +F_{i} + +where the superscripts :math:`n` and :math:`n+1` indicate values at the +beginning and end of the time step, respectively, and :math:`\Delta t` +is the time step (s). This equation is solved using the Crank-Nicholson +method, which combines the explicit method with fluxes evaluated at +:math:`n` (:math:`F_{i-1}^{n} ,F_{i}^{n}` ) and the implicit method with +fluxes evaluated at :math:`n+1` (:math:`F_{i-1}^{n+1} ,F_{i}^{n+1}` ) + +.. math:: + :label: 6.14) + + \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=\alpha \left(-F_{i-1}^{n} +F_{i}^{n} \right)+\left(1-\alpha \right)\left(-F_{i-1}^{n+1} +F_{i}^{n+1} \right) + +where :math:`\alpha =0.5`, resulting in a tridiagonal system of +equations + +.. math:: + :label: 6.15) + + r_{i} =a_{i} T_{i-1}^{n+1} +b_{i} T_{i}^{n+1} +c_{i} T_{i+1}^{n+1} + +where :math:`a_{i}` , :math:`b_{i}` , and :math:`c_{i}` are the +subdiagonal, diagonal, and superdiagonal elements in the tridiagonal +matrix and :math:`r_{i}` is a column vector of constants. When surface +water is present, the equation for the top soil layer has an additional +term representing the surface water temperature; this results in a four +element band-diagonal system of equations. + +For the top soil layer :math:`i=1` , top snow layer :math:`i=snl+1`, or +surface water layer, the heat flux from the overlying atmosphere +:math:`h` (W m\ :math:`{}^{-2}`, defined as positive into the surface) +is + +.. math:: + :label: 6.16) + + h^{n+1} =-\alpha F_{i-1}^{n} -\left(1-\alpha \right)F_{i-1}^{n+1} . + +The energy balance for these layers is then + +.. math:: + :label: 6.17) + + \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=h^{n+1} +\alpha F_{i}^{n} +\left(1-\alpha \right)F_{i}^{n+1} . + +The heat flux :math:`h` at :math:`n+1` may be approximated as follows + +.. math:: + :label: 6.18) + + h^{n+1} =h^{n} +\frac{\partial h}{\partial T_{i} } \left(T_{i}^{n+1} -T_{i}^{n} \right). + +The resulting equations are then + +.. math:: + :label: ZEqnNum219926 + + \begin{array}{rcl} {\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)} & {=} & {h^{n} +\frac{\partial h}{\partial T_{i} } \left(T_{i}^{n+1} -T_{i} \right)} \\ {} & {} & {-\alpha \frac{\lambda \left[z_{h,\, i} \right]\left(T_{i}^{n} -T_{i+1}^{n} \right)}{z_{i+1} -z_{i} } -\left(1-\alpha \right)\frac{\lambda \left[z_{h,\, i} \right]\left(T_{i}^{n+1} -T_{i+1}^{n+1} \right)}{z_{i+1} -z_{i} } } \end{array} + +For the top snow layer, :math:`i=snl+1`, the coefficients are + +.. math:: + :label: 6.20) + + a_{i} =0 + +.. math:: + :label: 6.21) + + b_{i} =1+\frac{\Delta t}{c_{i} \Delta z_{i} } \left[\left(1-\alpha \right)\frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } -\frac{\partial h}{\partial T_{i} } \right] + +.. math:: + :label: 6.22) + + c_{i} =-\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } + +.. math:: + :label: 6.23) + + r_{i} =T_{i}^{n} +\frac{\Delta t}{c_{i} \Delta z_{i} } \left[h_{sno} ^{n} -\frac{\partial h}{\partial T_{i} } T_{i}^{n} +\alpha F_{i} \right] + +where + +.. math:: + :label: ZEqnNum455578 + + F_{i} =-\lambda \left[z_{h,\, i} \right]\left(\frac{T_{i}^{n} -T_{i+1}^{n} }{z_{i+1} -z_{i} } \right). + +The heat flux into the snow surface from the overlying atmosphere +:math:`h` is + +.. math:: + :label: 6.25) + + h=\overrightarrow{S}_{sno} -\overrightarrow{L}_{sno} -H_{sno} -\lambda E_{sno} + +where :math:`\overrightarrow{S}_{sno}` is the solar radiation absorbed +by the top snow layer (section 3.2.1), :math:`\overrightarrow{L}_{sno}` +is the longwave radiation absorbed by the snow (positive toward the +atmosphere) (section 4.2), :math:`H_{sno}` is the sensible heat flux +from the snow (Chapter 5), and :math:`\lambda E_{sno}` is the latent +heat flux from the snow (Chapter 5). The partial derivative of the heat +flux :math:`h` with respect to temperature is + +.. math:: + :label: 6.26) + + \frac{\partial h}{\partial T_{} } =-\frac{\partial \overrightarrow{L}_{} }{\partial T_{} } -\frac{\partial H_{} }{\partial T_{} } -\frac{\partial \lambda E_{} }{\partial T_{} } + +where the partial derivative of the net longwave radiation is + +.. math:: + :label: 6.27) + + \frac{\partial \overrightarrow{L}_{} }{\partial T_{} } =4\varepsilon _{g} \sigma \left(T_{}^{n} \right)^{3} + +and the partial derivatives of the sensible and latent heat fluxes are +given by equations and for non-vegetated surfaces, and by equations and +for vegetated surfaces. :math:`\sigma` is the Stefan-Boltzmann constant +(W m\ :math:`{}^{-2}` K\ :math:`{}^{-4}`) (Table 2.6) and +:math:`\varepsilon _{g}` is the ground emissivity (section 4.2). For +purposes of computing :math:`h` and +:math:`\frac{\partial h}{\partial T_{g} }` , the term :math:`\lambda` +is arbitrarily assumed to be + +.. math:: + :label: 6.28) + + \lambda =\left\{\begin{array}{l} {\lambda _{sub} \qquad {\rm if\; }w_{liq,\, snl+1} =0{\rm \; and\; }w_{ice,\, snl+1} >0} \\ {\lambda _{vap} \qquad {\rm otherwise}} \end{array}\right\} + +where :math:`\lambda _{sub}` and :math:`\lambda _{vap}` are the +latent heat of sublimation and vaporization, respectively (J +kg\ :math:`{}^{-1}`) (Table 2.6), and :math:`w_{liq,\, snl+1}` and +:math:`w_{ice,\, snl+1}` are the liquid water and ice contents of the +top snow/soil layer, respectively (kg m\ :math:`{}^{-2}`) (Chapter 7). + +For the top soil layer, :math:`i=1`, the coefficients are + +.. math:: + :label: 6.29) + + a_{i} =-f_{sno} \left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } + +.. math:: + :label: 6.30) + + b_{i} =1+\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \left[f_{sno} \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } +\frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \right]-\left(1-f_{sno} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} + +.. math:: + :label: 6.31) + + c_{i} =-\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } + +.. math:: + :label: 6.32) + + r_{i} =T_{i}^{n} +\frac{\Delta t}{c_{i} \Delta z_{i} } \left[\left(1-f_{sno} \right)\left(h_{soil} ^{n} -\frac{\partial h}{\partial T_{} } T_{i}^{n} \right)+\alpha \left(F_{i} -f_{sno} F_{i-1} \right)\right] + +The heat flux into the soil surface from the overlying atmosphere +:math:`h` is + +.. math:: + :label: 6.33) + + h=\overrightarrow{S}_{soil} -\overrightarrow{L}_{soil} -H_{soil} -\lambda E_{soil} + +It can be seen that when no snow is present (:math:`f_{sno} =0`), the +expressions for the coefficients of the top soil layer have the same +form as those for the top snow layer. + +The surface snow/soil layer temperature computed in this way is the +layer-averaged temperature and hence has somewhat reduced diurnal +amplitude compared with surface temperature. An accurate surface +temperature is provided that compensates for this effect and numerical +error by tuning the heat capacity of the top layer (through adjustment +of the layer thickness) to give an exact match to the analytic solution +for diurnal heating. The top layer thickness for :math:`i=snl+1` is +given by + +.. math:: + :label: 6.34) + + \Delta z_{i*} =0.5\left[z_{i} -z_{h,\, i-1} +c_{a} \left(z_{i+1} -z_{h,\, i-1} \right)\right] + +where :math:`c_{a}` is a tunable parameter, varying from 0 to 1, and is +taken as 0.34 by comparing the numerical solution with the analytic +solution (Z.-L. Yang 1998, unpublished manuscript). +:math:`\Delta z_{i*}` is used in place of :math:`\Delta z_{i}` for +:math:`i=snl+1` in equations -. The top snow/soil layer temperature +computed in this way is the ground surface temperature +:math:`T_{g}^{n+1}` . + +The boundary condition at the bottom of the snow/soil column is zero +heat flux, :math:`F_{i} =0`, resulting in, for :math:`i=N_{levgrnd}` , + +.. math:: + :label: 6.35) + + \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=\alpha \frac{\lambda \left[z_{h,\, i-1} \right]\left(T_{i-1}^{n} -T_{i}^{n} \right)}{z_{i} -z_{i-1} } +\left(1-\alpha \right)\frac{\lambda \left[z_{h,\, i-1} \right]\left(T_{i-1}^{n+1} -T_{i}^{n+1} \right)}{z_{i} -z_{i-1} } + +.. math:: + :label: 6.36) + + a_{i} =-\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } + +.. math:: + :label: 6.37) + + b_{i} =1+\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } + +.. math:: + :label: 6.38) + + c_{i} =0 + +.. math:: + :label: 6.39) + + r_{i} =T_{i}^{n} -\alpha \frac{\Delta t}{c_{i} \Delta z_{i} } F_{i-1} + +where + +.. math:: + :label: ZEqnNum768674 + + F_{i-1} =-\frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \left(T_{i-1}^{n} -T_{i}^{n} \right). + +For the interior snow/soil layers, :math:`snl+1T_{f} {\rm \; and\; }w_{ice,\, i} >0\qquad i=snl+1,\ldots ,N_{levgrnd} \qquad {\rm melting}} \\ {T_{i}^{n+1} 0\qquad i=snl+1,\ldots ,0\qquad {\rm freezing}} \\ {T_{i}^{n+1} w_{liq,\, \max ,\, i} \qquad i=1,\ldots ,N_{levgrnd} \qquad {\rm freezing}} \end{array} + +where :math:`T_{i}^{n+1}` is the soil layer temperature after solution +of the tridiagonal equation set, :math:`w_{ice,\, i}` and +:math:`w_{liq,\, i}` are the mass of ice and liquid water (kg +m\ :math:`{}^{-2}`) in each snow/soil layer, respectively, and +:math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). For +the freezing process in soil layers, the concept of supercooled soil +water from Niu and Yang (2006) is adopted. The supercooled soil water is +the liquid water that coexists with ice over a wide range of +temperatures below freezing and is implemented through a freezing point +depression equation + +.. math:: + :label: ZEqnNum547401 + + w_{liq,\, \max ,\, i} =\Delta z_{i} \theta _{sat,\, i} \left[\frac{10^{3} L_{f} \left(T_{f} -T_{i} \right)}{gT_{i} \psi _{sat,\, i} } \right]^{{-1\mathord{\left/ {\vphantom {-1 B_{i} }} \right. \kern-\nulldelimiterspace} B_{i} } } \qquad T_{i} 0`) +but there are no explicit snow layers (:math:`snl=0`) (i.e., there is +not enough snow present to meet the minimum snow depth requirement of +0.01 m), snow melt will take place for soil layer :math:`i=1` if the +soil layer temperature is greater than the freezing temperature +(:math:`T_{1}^{n+1} >T_{f}` ). + +The rate of phase change is assessed from the energy excess (or deficit) +needed to change :math:`T_{i}` to freezing temperature, :math:`T_{f}` . +The excess or deficit of energy :math:`H_{i}` (W m\ :math:`{}^{-2}`) is +determined as follows + +.. math:: + :label: 6.55) + + H_{i} =\left\{\begin{array}{l} {\frac{\partial h}{\partial T} \left(T_{f} -T_{i}^{n} \right)-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\qquad \quad \quad \quad i=snl+1} \\ {\left(1-f_{sno} -f_{h2osfc} \right)\frac{\partial h}{\partial T} \left(T_{f} -T_{i}^{n} \right)-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\quad {\kern 1pt} {\kern 1pt} {\kern 1pt} {\kern 1pt} i=1} \\ {-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\qquad \quad \quad \quad i\ne \left\{1,snl+1\right\}} \end{array}\right\}. + +If the melting criteria is met (equation ) and +:math:`H_{m} =\frac{H_{i} \Delta t}{L_{f} } >0`, then the ice mass is +readjusted as + +.. math:: + :label: ZEqnNum547839 + + w_{ice,\, i}^{n+1} =w_{ice,\, i}^{n} -H_{m} \ge 0\qquad i=snl+1,\ldots ,N_{levgrnd} . + +If the freezing criteria is met (equation ) and :math:`H_{m} <0`, then +the ice mass is readjusted for :math:`i=snl+1,\ldots ,0` as + +.. math:: + :label: 6.57) + + w_{ice,\, i}^{n+1} =\min \left(w_{liq,\, i}^{n} +w_{ice,\, i}^{n} ,w_{ice,\, i}^{n} -H_{m} \right) + +and for :math:`i=1,\ldots ,N_{levgrnd}` as + +.. math:: + :label: 6.58) + + w_{ice,\, i}^{n+1} =\left\{\begin{array}{l} {\min \left(w_{liq,\, i}^{n} +w_{ice,\, i}^{n} -w_{liq,\, \max ,\, i}^{n} ,\, w_{ice,\, i}^{n} -H_{m} \right)\qquad w_{liq,\, i}^{n} +w_{ice,\, i}^{n} \ge w_{liq,\, \max ,\, i}^{n} {\rm \; }} \\ {{\rm 0}\qquad w_{liq,\, i}^{n} +w_{ice,\, i}^{n} 0`) as + +.. math:: + :label: ZEqnNum190862 + + T_{i}^{n+1} =\left\{\begin{array}{l} {T_{f} +{\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \mathord{\left/ {\vphantom {\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \left(1-\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)}} \right. \kern-\nulldelimiterspace} \left(1-\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)} \qquad \quad \quad \quad \quad \quad \, i=snl+1} \\ {T_{f} +{\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \mathord{\left/ {\vphantom {\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \left(1-\left(1-f_{sno} -f_{h2osfc} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)}} \right. \kern-\nulldelimiterspace} \left(1-\left(1-f_{sno} -f_{h2osfc} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)} \qquad i=1} \\ {T_{f} +\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \qquad \quad \quad \quad \quad \quad \, i\ne \left\{1,snl+1\right\}} \end{array}\right\}. + +For the special case when snow is present (:math:`W_{sno} >0`), there +are no explicit snow layers (:math:`snl=0`), and +:math:`\frac{H_{1} \Delta t}{L_{f} } >0` (melting), the snow mass +:math:`W_{sno}` (kg m\ :math:`{}^{-2}`) is reduced according to + +.. math:: + :label: 6.62) + + W_{sno}^{n+1} =W_{sno}^{n} -\frac{H_{1} \Delta t}{L_{f} } \ge 0. + +The snow depth is reduced proportionally + +.. math:: + :label: 6.63) + + z_{sno}^{n+1} =\frac{W_{sno}^{n+1} }{W_{sno}^{n} } z_{sno}^{n} . + +Again, because part of the energy may not be consumed in melting, the +energy for the surface soil layer :math:`i=1` is recalculated as + +.. math:: + :label: 6.64) + + H_{1*} =H_{1} -\frac{L_{f} \left(W_{sno}^{n} -W_{sno}^{n+1} \right)}{\Delta t} . + +If there is excess energy (:math:`H_{1*} >0`), this energy becomes +available to the top soil layer as + +.. math:: + :label: ZEqnNum985120 + + H_{1} =H_{1*} . + +The ice mass, liquid water content, and temperature of the top soil +layer are then determined from equations , , and using the recalculated +energy from equation . Snow melt :math:`M_{1S}` (kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`) and phase change energy :math:`E_{p,\, 1S}` (W +m\ :math:`{}^{-2}`) for this special case are + +.. math:: + :label: 6.66) + + M_{1S} =\frac{W_{sno}^{n} -W_{sno}^{n+1} }{\Delta t} \ge 0 + +.. math:: + :label: 6.67) + + E_{p,\, 1S} =L_{f} M_{1S} . + +The total energy of phase change :math:`E_{p}` (W m\ :math:`{}^{-2}`) +for the snow/soil column is + +.. math:: + :label: 6.68) + + E_{p} =E_{p,\, 1S} +\sum _{i=snl+1}^{N_{levgrnd} }E_{p,i} + +where + +.. math:: + :label: 6.69) + + E_{p,\, i} =L_{f} \frac{\left(w_{ice,\, i}^{n} -w_{ice,\, i}^{n+1} \right)}{\Delta t} . + +The total snow melt :math:`M` (kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`) is + +.. math:: + :label: 6.70) + + M=M_{1S} +\sum _{i=snl+1}^{i=0}M_{i} + +where + +.. math:: + :label: 6.71) + + M_{i} =\frac{\left(w_{ice,\, i}^{n} -w_{ice,\, i}^{n+1} \right)}{\Delta t} \ge 0. + +The solution for snow/soil temperatures conserves energy as + +.. math:: + :label: 6.72) + + G-E_{p} -\sum _{i=snl+1}^{i=N_{levgrnd} }\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=0 + +where :math:`G` is the ground heat flux (section 5.4). + +Surface Water +^^^^^^^^^^^^^^^^^^^ + +Phase change of surface water takes place when the surface water +temperature, :math:`T_{h2osfc}` , becomes less than :math:`T_{f}` . The +energy available for freezing is + +.. math:: + :label: 6.73) + + H_{h2osfc} =\frac{\partial h}{\partial T} \left(T_{f} -T_{h2osfc}^{n} \right)-\frac{c_{h2osfc} \Delta z_{h2osfc} }{\Delta t} \left(T_{f} -T_{h2osfc}^{n} \right) + +where :math:`c_{h2osfc}` is the volumetric heat capacity of water, and +:math:`\Delta z_{h2osfc}` is the depth of the surface water layer. If +:math:`H_{m} =\frac{H_{h2osfc} \Delta t}{L_{f} } >0` then :math:`H_{m}` +is removed from surface water and added to the snow column as ice + +.. math:: + :label: 6.74) + + H^{n+1} _{h2osfc} =H^{n} _{h2osfc} -H_{m} + +.. math:: + :label: 6.75) + + w_{ice,\, 0}^{n+1} =w_{ice,\, 0}^{n} +H_{m} + +The snow depth is adjusted to account for the additional ice mass + +.. math:: + :label: 6.76) + + \Delta z_{sno} =\frac{H_{m} }{\rho _{ice} } + +If :math:`H_{m}` \ is greater than :math:`W_{sfc}` , the excess heat +:math:`\frac{L_{f} \left(H_{m} -W_{sfc} \right)}{\Delta t}` is used to +cool the snow layer. + +Soil and Snow Thermal Properties +------------------------------------ + +The thermal and hydraulic (section 6.3 and 7.4.1) properties of the soil +are assumed to be a weighted combination of the mineral and organic +properties of the soil (Lawrence and Slater 2008). The soil layer +organic matter fraction :math:`f_{om,i}` is + +.. math:: + :label: 6.77) + + f_{om,i} =\rho _{om,i} /\rho _{om,\max } . + +Soil thermal conductivity :math:`\lambda _{i}` (W m\ :math:`{}^{-1}` +K\ :math:`{}^{-1}`) is from Farouki (1981) + +.. math:: + :label: 6.78) + + \begin{array}{l} {\lambda _{i} =\left\{\begin{array}{l} {K_{e,\, i} \lambda _{sat,\, i} +\left(1-K_{e,\, i} \right)\lambda _{dry,\, i} \qquad S_{r,\, i} >1\times 10^{-7} } \\ {\lambda _{dry,\, i} \qquad S_{r,\, i} \le 1\times 10^{-7} } \end{array}\right\}\qquad i=1,\ldots ,N_{levsoi} } \\ {\lambda _{i} =\lambda _{bedrock} \qquad i=N_{levsoi} +1,\ldots N_{levgrnd} } \end{array} + +where :math:`\lambda _{sat,\, i}` is the saturated thermal +conductivity, :math:`\lambda _{dry,\, i}` is the dry thermal +conductivity, :math:`K_{e,\, i}` is the Kersten number, +:math:`S_{r,\, i}` is the wetness of the soil with respect to +saturation, and :math:`\lambda _{bedrock} =3` W m\ :math:`{}^{-1}` +K\ :math:`{}^{-1}` is the thermal conductivity assumed for the deep +ground layers (typical of saturated granitic rock; Clauser and Huenges, +1995). For glaciers and wetlands, + +.. math:: + :label: 6.79) + + \lambda _{i} =\left\{\begin{array}{l} {\lambda _{liq,\, i} \qquad T_{i} \ge T_{f} } \\ {\lambda _{ice,\, i} \qquad T_{i} 0`) but +there are no explicit snow layers (:math:`snl=0`), the heat capacity of +the top layer is a blend of ice and soil heat capacity + +.. math:: + :label: 6.93) + + c_{1} =c_{1}^{\*} +\frac{C_{ice} W_{sno} }{\Delta z_{1} } + +where :math:`c_{1}^{\*}` is calculated from equation or . + +.. todo:: fill in the above - should be calculated form equation (6.89) or (6.92) + diff --git a/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst b/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst new file mode 100644 index 0000000000..47359c6b77 --- /dev/null +++ b/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst @@ -0,0 +1,2167 @@ +Hydrology +============ + +The model parameterizes interception, throughfall, canopy drip, snow +accumulation and melt, water transfer between snow layers, infiltration, +evaporation, surface runoff, sub-surface drainage, redistribution within +the soil column, and groundwater discharge and recharge to simulate +changes in canopy water :math:`\Delta W_{can}` , surface water +:math:`\Delta W_{sfc}` , snow water :math:`\Delta W_{sno}` , soil water +:math:`\Delta w_{liq,\, i}` , and soil ice :math:`\Delta w_{ice,\, i}` , +and water in the unconfined aquifer :math:`\Delta W_{a}` (all in kg +m\ :math:`{}^{-2}` or mm of H\ :math:`{}_{2}`\ O) (Figure 7.1). + +The total water balance of the system is + +.. math:: + :label: 7.1) + + \begin{array}{l} {\Delta W_{can} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} + +where :math:`q_{rain}` is the liquid part of precipitation, +:math:`q_{sno}` is the solid part of precipitation, :math:`E_{v}` is +ET from vegetation (Chapter 5), :math:`E_{g}` is ground evaporation +(Chapter 5), :math:`q_{over}` is surface runoff (section 7.3), +:math:`q_{h2osfc}` is runoff from surface water storage (section 7.3), +:math:`q_{drai}` is sub-surface drainage (section 7.6), +:math:`q_{rgwl}` and :math:`q_{snwcp,ice}` are liquid and solid runoff +from glaciers, wetlands, and lakes, and runoff from other surface types +due to snow capping (section 7.7) (all in kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`), :math:`N_{levsoi}` is the number of soil layers +(note that hydrology calculations are only done over soil layers 1 to +:math:`N_{levsoi}` ; ground levels :math:`N_{levsoi} +1`\ to +:math:`N_{levgrnd}` are currently hydrologically inactive; Lawrence et +al. 2008) and :math:`\Delta t` is the time step (s). + +Figure 7.1. Hydrologic processes represented in CLM. + +.. image:: image1.png + +Canopy Water +---------------- + +Precipitation is either intercepted by the canopy, falls directly to the +snow/soil surface (throughfall), or drips off the vegetation (canopy +drip). Interception by vegetation :math:`q_{intr}` (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) does not distinguish between +liquid and solid phases + +.. math:: + :label: 7.2) + + q_{intr} =\alpha \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + +where :math:`L` and :math:`S` are the exposed leaf and stem area index, +respectively (section 2.1.4), and :math:`\alpha =0.25` scales +interception from point to grid cell (Lawrence et al. 2007). Throughfall +(kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), however, is divided into +liquid and solid phases reaching the ground (soil or snow surface) as + +.. math:: + :label: 7.3) + + q_{thru,\, liq} =q_{rain} \left[1-\alpha \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right] + +.. math:: + :label: 7.4) + + q_{thru,\, ice} =q_{sno} \left[1-\alpha \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right]. + +Similarly, the canopy drip is + +.. math:: + :label: 7.5) + + q_{drip,\, liq} =\frac{W_{can}^{intr} -W_{can,\, \max } }{\Delta t} \frac{q_{rain} }{q_{rain} +q_{sno} } \ge 0 + +.. math:: + :label: 7.6) + + q_{drip,\, ice} =\frac{W_{can}^{intr} -W_{can,\, \max } }{\Delta t} \frac{q_{sno} }{q_{rain} +q_{sno} } \ge 0 + +where + +.. math:: + :label: 7.7) + + W_{can}^{intr} =W_{can}^{n} +q_{intr} \Delta t\ge 0 + +is the canopy water after accounting for interception, +:math:`W_{can}^{n}` is the canopy water from the previous time step, +and :math:`W_{can,\, \max }` (kg m\ :math:`{}^{-2}`) is the maximum +amount of water the canopy can hold + +.. math:: + :label: 7.8) + + W_{can,\, \max } =p\left(L+S\right). + +The maximum storage of solid water is assumed to be the same as that of +liquid water, :math:`p=0.1` kg m\ :math:`{}^{-2}` (Dickinson et al. +1993). The canopy water is updated as + +.. math:: + :label: 7.9) + + W_{can}^{n+1} =W_{can}^{n} +q_{intr} \Delta t-\left(q_{drip,\, liq} +q_{drip,\, ice} \right)\Delta t-E_{v}^{w} \Delta t\ge 0. + +where :math:`E_{v}^{w}` is the flux of water vapor from stem and leaf +surfaces (Chapter 5). The total rate of liquid and solid precipitation +reaching the ground is then + +.. math:: + :label: ZEqnNum946822 + + q_{grnd,liq} =q_{thru,\, liq} +q_{drip,\, liq} + +.. math:: + :label: ZEqnNum339590 + + q_{grnd,ice} =q_{thru,\, ice} +q_{drip,\, ice} . + +Solid precipitation reaching the soil or snow surface, +:math:`q_{grnd,\, ice} \Delta t`, is added immediately to the snow pack +(section 7.2). The liquid part, :math:`q_{grnd,\, liq} \Delta t` is +added after surface fluxes (Chapter 5) and snow/soil temperatures +(Chapter 6) have been determined. + +The wetted fraction of the canopy (stems plus leaves), which is required +for the surface albedo (section 3.1) and surface flux (Chapter 5) +calculations is (Dickinson et al. 1993) + +.. math:: + :label: 7.12) + + f_{wet} =\left\{\begin{array}{l} {\left[\frac{W_{can} }{p\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \le 1\qquad L+S>0} \\ {0\qquad L+S=0} \end{array}\right\} + +while the fraction of the canopy that is dry and transpiring is + +.. math:: + :label: 7.13) + + f_{dry} =\left\{\begin{array}{l} {\frac{\left(1-f_{wet} \right)L}{L+S} \qquad L+S>0} \\ {0\qquad L+S=0} \end{array}\right\}. + +Snow +-------- + +The parameterizations for snow are based primarily on Anderson (1976), +country-regionplaceJordan (1991), and Dai and Zeng (1997). The snowpack +can have up to five layers. These layers are indexed in the Fortran code +as :math:`i=-4,-3,-2,-1,0` where layer :math:`i=0` is the snow layer +next to the top soil layer and layer :math:`i=-4` is the top layer of a +five-layer snow pack. Since the number of snow layers varies according +to the snow depth, we use the notation :math:`snl+1` to describe the top +layer of snow for the variable layer snow pack, where :math:`snl` is the +negative of the number of snow layers. Refer to Figure 7.2 for an +example of the snow layer structure for a three layer snow pack. + +Figure 7.2. Example of three layer snow pack (:math:`snl=-3`). + +Shown are three snow layers, :math:`i=-2`, :math:`i=-1`, and +:math:`i=0`. The layer node depth is :math:`z`, the layer interface is +:math:`z_{h}` , and the layer thickness is :math:`\Delta z`. + +.. image:: image2.png + +The state variables for snow are the mass of water :math:`w_{liq,i}` +(kg m\ :math:`{}^{-2}`), mass of ice :math:`w_{ice,i}` (kg +m\ :math:`{}^{-2}`), layer thickness :math:`\Delta z_{i}` (m), and +temperature :math:`T_{i}` (Chapter 6). The water vapor phase is +neglected. Snow can also exist in the model without being represented by +explicit snow layers. This occurs when the snowpack is less than a +specified minimum snow depth (:math:`z_{sno} <0.01` m). In this case, +the state variable is the mass of snow :math:`W_{sno}` (kg +m\ :math:`{}^{-2}`). + +Section 7.2.1 describes the calculation of fractional snow covered area, +which is used in the surface albedo calculation (Chapter 3) and the +surface flux calculations (Chapter 5). The following two sections (7.2.2 +and 7.2.3) describe the ice and water content of the snow pack assuming +that at least one snow layer exists. Section 7.2.4 describes how black +and organic carbon and mineral dust particles are represented within +snow, including meltwater flushing. See section 7.2.5 for a description +of how a snow layer is initialized. + +Snow Covered Area Fraction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The fraction of the ground covered by snow, :math:`f_{sno}` , is based +on the method of Swenson and Lawrence (2012). Because the processes +governing snowfall and snowmelt differ, changes in :math:`f_{sno}` are +calculated separately for accumulation and depletion. When snowfall +occurs, :math:`f_{sno}` is updated as + +.. math:: + :label: 7.14) + + f^{n+1} _{sno} =1-\left(\left(1-\tanh (k_{accum} q_{sno} \Delta t)\right)\left(1-f^{n} _{sno} \right)\right) + +where :math:`k_{accum}` is a constant whose default value is 0.1, +:math:`q_{sno} \Delta t` is the amount of new snow, +:math:`f^{n+1} _{sno}` is the updated snow covered fraction (SCF), and +:math:`f^{n} _{sno}` is the SCF from the previous time step. + +When snow melt occurs, :math:`f_{sno}` is calculated from the depletion +curve + +.. math:: + :label: 7.15) + + f_{sno} =1-\left(\frac{\cos ^{-1} \left(2R_{sno} -1\right)}{\pi } \right)^{N_{melt} } + +where :math:`R_{sno}` is the ratio of :math:`W_{sno}` to the maximum +accumulated snow :math:`W_{\max }` , and :math:`N_{melt}` is a +parameter that depends on the topographic variability within the grid +cell. Whenever :math:`W_{sno}` reaches zero, :math:`W_{\max }` is +reset to zero. The depletion curve shape parameter is defined as + +.. math:: + :label: 7.16) + + N_{melt} =\frac{200}{\min \left(10,\sigma _{topo} \right)} + +The standard deviation of the elevation within a grid cell, +:math:`\sigma _{topo}` , is calculated from a high resolution DEM (a +1km DEM is used for CLM). + +Ice Content +^^^^^^^^^^^^^^^^^ + +The conservation equation for mass of ice in snow layers is + +.. math:: + :label: 7.17) + + \frac{\partial w_{ice,\, i} }{\partial t} =\left\{\begin{array}{l} {f_{sno} q_{ice,\, i-1} -\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} \qquad i=snl+1} \\ {-\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} \qquad i=snl+2,\ldots ,0} \end{array}\right\} + +where :math:`q_{ice,\, i-1}` is the rate of ice accumulation from +precipitation or frost or the rate of ice loss from sublimation (kg +m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) in the top layer and +:math:`{\left(\Delta w_{ice,\, i} \right)_{p} \mathord{\left/ {\vphantom {\left(\Delta w_{ice,\, i} \right)_{p} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` +is the change in ice due to phase change (melting rate) (section 6.2). +The term :math:`q_{ice,\, i-1}` is computed in two steps as + +.. math:: + :label: 7.18) + + q_{ice,\, i-1} =q_{grnd,\, ice} +\left(q_{frost} -q_{subl} \right) + +where :math:`q_{grnd,\, ice}` is the rate of solid precipitation +reaching the ground (section 7.1) and :math:`q_{frost}` and +:math:`q_{subl}` are gains due to frost and losses due to sublimation, +respectively (section 5.4). In the first step, immediately after +:math:`q_{grnd,\, ice}` has been determined after accounting for +interception (section 7.1), a new snow depth :math:`z_{sno}` (m) is +calculated from + +.. math:: + :label: 7.19) + + z_{sno}^{n+1} =z_{sno}^{n} +\Delta z_{sno} + +where + +.. math:: + :label: 7.20) + + \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } + +and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg +m\ :math:`{}^{-3}`) (CityplaceAnderson 1976) + +.. math:: + :label: 7.21) + + \rho _{sno} =\left\{\begin{array}{l} {50+1.7\left(17\right)^{1.5} \qquad T_{atm} >T_{f} +2} \\ {50+1.7\left(T_{atm} -T_{f} +15\right)^{1.5} \qquad T_{f} -15T_{f}` ). In this case, the incoming solid precipitation +is assigned to the runoff term :math:`q_{rgwl}` (section 7.7). + +In the second step, after surface fluxes and snow/soil temperatures have +been determined (Chapters 5 and 6), :math:`w_{ice,\, snl+1}` is updated +for frost or sublimation as + +.. math:: + :label: ZEqnNum863244 + + w_{ice,\, snl+1}^{n+1} =w_{ice,\, snl+1}^{n} +f_{sno} \left(q_{frost} -q_{subl} \right)\Delta t. + +If :math:`w_{ice,\, snl+1}^{n+1} <0` upon solution of equation , the ice +content is reset to zero and the liquid water content +:math:`w_{liq,\, snl+1}` is reduced by the amount required to bring +:math:`w_{ice,\, snl+1}^{n+1}` up to zero. + +The snow water equivalent :math:`W_{sno}` is capped to not exceed 1000 +kg m\ :math:`{}^{-2}`. If the addition of :math:`q_{frost}` were to +result in :math:`W_{sno} >1000` kg m\ :math:`{}^{-2}`, the frost term +:math:`q_{frost}` is instead added to the ice runoff term +:math:`q_{snwcp,\, ice}` (section 7.7). + +Water Content +^^^^^^^^^^^^^^^^^^^ + +The conservation equation for mass of water in snow layers is + +.. math:: + :label: 7.26) + + \frac{\partial w_{liq,\, i} }{\partial t} =\left(q_{liq,\, i-1} -q_{liq,\, i} \right)+\frac{\left(\Delta w_{liq,\, i} \right)_{p} }{\Delta t} + +where :math:`q_{liq,\, i-1}` is the flow of liquid water into layer +:math:`i` from the layer above, :math:`q_{liq,\, i}` is the flow of +water out of layer :math:`i` to the layer below, +:math:`{\left(\Delta w_{liq,\, i} \right)_{p} \mathord{\left/ {\vphantom {\left(\Delta w_{liq,\, i} \right)_{p} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` +is the change in liquid water due to phase change (melting rate) +(section 6.2). For the top snow layer only, + +.. math:: + :label: 7.27) + + q_{liq,\, i-1} =f_{sno} \left(q_{grnd,\, liq} +\left(q_{sdew} -q_{seva} \right)\right) + +where :math:`q_{grnd,\, liq}` is the rate of liquid precipitation +reaching the snow (section 7.1), :math:`q_{seva}` is the evaporation of +liquid water and :math:`q_{sdew}` is the liquid dew (section 5.4). +After surface fluxes and snow/soil temperatures have been determined +(Chapters 5 and 6), :math:`w_{liq,\, snl+1}` is updated for the liquid +precipitation reaching the ground and dew or evaporation as + +.. math:: + :label: 7.28) + + w_{liq,\, snl+1}^{n+1} =w_{liq,\, snl+1}^{n} +f_{sno} \left(q_{grnd,\, liq} +q_{sdew} -q_{seva} \right)\Delta t. + +When the liquid water within a snow layer exceeds the layer’s holding +capacity, the excess water is added to the underlying layer, limited by +the effective porosity (:math:`1-\theta _{ice}` ) of the layer. The flow +of water is assumed to be zero (:math:`q_{liq,\, i} =0`) if the +effective porosity of either of the two layers +(:math:`1-\theta _{ice,\, i} {\rm \; and\; }1-\theta _{ice,\, i+1}` ) is +less than :math:`\theta _{imp} =0.05`, the water impermeable volumetric +water content. Thus, water flow between layers, :math:`q_{liq,\, i}` , +for layers :math:`i=snl+1,\ldots ,0`, is initially calculated as + +.. math:: + :label: ZEqnNum767577 + + q_{liq,\, i} =\frac{\rho _{liq} \left[\theta _{liq,\, i} -S_{r} \left(1-\theta _{ice,\, i} \right)\right]f_{sno} \Delta z_{i} }{\Delta t} \ge 0 + +where the volumetric liquid water :math:`\theta _{liq,\, i}` and ice +:math:`\theta _{ice,\, i}` contents are + +.. math:: + :label: 7.30) + + \theta _{ice,\, i} =\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } \le 1 + +.. math:: + :label: 7.31) + + \theta _{liq,\, i} =\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \le 1-\theta _{ice,\, i} , + +and :math:`S_{r} =0.033` is the irreducible water saturation (snow +holds a certain amount of liquid water due to capillary retention after +drainage has ceased (Anderson 1976)). The water holding capacity of the +underlying layer limits the flow of water :math:`q_{liq,\, i}` +calculated in equation , unless the underlying layer is the surface soil +layer, as + +.. math:: + :label: 7.32) + + q_{liq,\, i} \le \frac{\rho _{liq} \left[1-\theta _{ice,\, i+1} -\theta _{liq,\, i+1} \right]\Delta z_{i+1} }{\Delta t} \qquad i=snl+1,\ldots ,-1. + +The liquid water content :math:`w_{liq,\, i}` is updated as + +.. math:: + :label: ZEqnNum265203 + + w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\left(q_{i-1} -q_{i} \right)\Delta t. + +Equations - are solved sequentially from top (:math:`i=snl+1`) to +bottom (:math:`i=0`) snow layer in each time step. The total flow of +liquid water reaching the soil surface is then :math:`q_{liq,\, 0}` +which is used in the calculation of surface runoff and infiltration +(section 7.3). + +Black and organic carbon and mineral dust within snow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Particles within snow originate from atmospheric aerosol deposition +(:math:`D_{sp}` in Table 2.3 (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) +and influence snow radiative transfer (sections 3.2.1, 3.2.2, and +3.3.3). Particle masses and mixing ratios are represented with a simple +mass-conserving scheme. The model maintains masses of the following +eight particle species within each snow layer: hydrophilic black carbon, +hydrophobic black carbon, hydrophilic organic carbon, hydrophobic +organic carbon, and four species of mineral dust with the following +particle sizes: 0.1-1.0, 1.0-2.5, 2.5-5.0, and 5.0-10.0 :math:`\mu m`. +Each of these species has unique optical properties (Table 3.5) and +meltwater removal efficiencies (Table 7.1). + +The black carbon and organic carbon deposition rates described in Table +2.3 are combined into four categories as follows + +.. math:: + :label: 7.34) + + D_{bc,\, hphil} =D_{bc,\, dryhphil} +D_{bc,\, wethphil} + +.. math:: + :label: 7.35) + + D_{bc,\, hphob} =D_{bc,\, dryhphob} + +.. math:: + :label: 7.36) + + D_{oc,\, hphil} =D_{oc,\, dryhphil} +D_{oc,\, wethphil} + +.. math:: + :label: 7.37) + + D_{oc,\, hphob} =D_{oc,\, dryhphob} + +Deposited particles are assumed to be instantly mixed (homogeneously) +within the surface snow layer and are added after the inter-layer water +fluxes are computed (section 7.2.3) so that some aerosol is in the top +layer after deposition and is not immediately washed out before +radiative calculations are done. Particle masses are then redistributed +each time step based on meltwater drainage through the snow column +(section 7.2.3) and snow layer combination and subdivision (section +7.2.7). The change in mass of each of the particle species +:math:`\Delta m_{sp,\, i}` (kg m\ :math:`{}^{-2}`) is + +.. math:: + :label: 7.38) + + \Delta m_{sp,\, i} =\left[k_{sp} \left(q_{liq,\, i-1} c_{sp,\, i-1} -q_{liq,\, i} c_{i} \right)+D_{sp} \right]\Delta t + +where :math:`k_{sp}` is the meltwater scavenging efficiency that is +unique for each species (Table 7.1), :math:`q_{liq,\, i-1}` is the flow +of liquid water into layer :math:`i` from the layer above, +:math:`q_{liq,\, i}` is the flow of water out of layer :math:`i` into +the layer below (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) (section +7.2.3), :math:`c_{sp,\, i-1}` and :math:`c_{sp,\, i}` are the particle +mass mixing ratios in layers :math:`i-1` and :math:`i` (kg +kg\ :math:`{}^{-1}`), :math:`D_{sp}` is the atmospheric deposition rate +(zero for all layers except layer :math:`snl+1`), and :math:`\Delta t` +is the model time step (s). The particle mass mixing ratio is + +.. math:: + :label: 7.39) + + c_{i} =\frac{m_{sp,\, i} }{w_{liq,\, i} +w_{ice,\, i} } . + +Values of :math:`k_{sp}` are partially derived from experiments +published by Conway et al. (1996). Particles masses are re-distributed +proportionately with snow mass when layers are combined or divided, thus +conserving particle mass within the snow column. The mass of particles +carried out with meltwater through the bottom snow layer is assumed to +be permanently lost from the snowpack, and is not maintained within the +model. + +Table 7.1. Meltwater scavenging efficiency for particles within snow + ++------------------------------------------+-------------------+ +| Species | :math:`k_{sp}` | ++==========================================+===================+ +| Hydrophilic black carbon | 0.20 | ++------------------------------------------+-------------------+ +| Hydrophobic black carbon | 0.03 | ++------------------------------------------+-------------------+ +| Hydrophilic organic carbon | 0.20 | ++------------------------------------------+-------------------+ +| Hydrophobic organic carbon | 0.03 | ++------------------------------------------+-------------------+ +| Dust species 1 (0.1-1.0 :math:`\mu m`) | 0.02 | ++------------------------------------------+-------------------+ +| Dust species 2 (1.0-2.5 :math:`\mu m`) | 0.02 | ++------------------------------------------+-------------------+ +| Dust species 3 (2.5-5.0 :math:`\mu m`) | 0.01 | ++------------------------------------------+-------------------+ +| Dust species 4 (5.0-10.0 :math:`\mu m`) | 0.01 | ++------------------------------------------+-------------------+ + +Initialization of snow layer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If there are no existing snow layers (:math:`snl+1=1`) but +:math:`z_{sno} \ge 0.01` m after accounting for solid precipitation +:math:`q_{sno}` , then a snow layer is initialized (:math:`snl=-1`) as +follows + +.. math:: + :label: 7.40) + + \begin{array}{l} {\Delta z_{0} =z_{sno} } \\ {z_{o} =-0.5\Delta z_{0} } \\ {z_{h,\, -1} =-\Delta z_{0} } \\ {T_{0} =\min \left(T_{f} ,T_{atm} \right)} \\ {w_{ice,\, 0} =W_{sno} } \\ {w_{liq,\, 0} =0} \end{array}. + +Snow Compaction +^^^^^^^^^^^^^^^^^^^^^ + +Snow compaction is initiated after the soil hydrology calculations +[surface runoff (section 7.3), infiltration (section 7.3), soil water +(section 7.4), groundwater-soilwater interactions (section 7.6)] are +complete. Compaction of snow includes three types of processes: +destructive metamorphism of new snow (crystal breakdown due to wind or +thermodynamic stress); snow load or overburden (pressure); and melting +(changes in snow structure due to melt-freeze cycles plus changes in +crystals due to liquid water). The total fractional compaction rate for +each snow layer :math:`C_{R,\, i}` (:math:`\text{s}^{-1}`) is the sum of the +three compaction processes + +.. math:: + :label: 7.41) + + C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} . + +Compaction is not allowed if the layer is saturated + +.. math:: + :label: 7.42) + + 1-\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } +\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \right)\le 0.001 + +or if the ice content is below a minimum value +(:math:`w_{ice,\, i} \le 0.1`). + +Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` +(:math:`{\text s^{-1}}`) is temperature dependent (CityplaceAnderson 1976) + +.. math:: + :label: 7.43) + + C_{R1,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{metamorphism} =-c_{3} c_{1} c_{2} \exp \left[-c_{4} \left(T_{f} -T_{i} \right)\right] + +where :math:`c_{3} =2.777\times 10^{-6}` (:math:`\text{s}^{-1}`) is the +fractional compaction rate for :math:`T_{i} =T_{f}`, :math:`c_{4} =0.04` :math:`\text{K}^{-1}`, and + +.. math:: + :label: 7.44) + + c_{1} & = 1\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{1} & = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -100\right)\right]\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{2} & = 2\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } >0.01 \\ + c_{2} & = 1\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } \le 0.01 + +where +:math:`{w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` +and +:math:`{w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` +are the bulk densities of liquid water and ice (kg m\ :math:`{}^{-3}`). + +The compaction rate as a result of overburden :math:`C_{R2,\; i}` +(:math:`\text{s}^{-1}`) is a linear function of the snow load pressure +:math:`P_{s,\, i}` (:math:`\text{k} \text{g} \text{m}^{-2}`) (CityplaceAnderson 1976) + +.. math:: + :label: 7.45) + + C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } + +where :math:`\eta` is a viscosity coefficient (:math:`\text{kg} \text{s} \text{m}^{-2}`) +that varies with density and temperature as + +.. math:: + :label: 7.46) + + \eta =\eta _{0} \exp \left[c_{5} \left(T_{f} -T_{i} \right)+c_{6} \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \right] + +where :math:`\eta _{0} =9\times 10^{5}` kg s m\ :math:`{}^{-2}`, and +:math:`c_{5} =0.08` K\ :math:`{}^{-1}`, :math:`c_{6} =0.023` +m\ :math:`{}^{3}` kg\ :math:`{}^{-1}` are constants. The snow load +pressure :math:`P_{s,\, i}` is calculated for each layer as the sum of +the ice :math:`w_{ice,\, i}` and liquid water contents +:math:`w_{liq,\, i}` of the layers above plus half the ice and liquid +water contents of the layer being compacted + +.. math:: + :label: 7.47) + + P_{s,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{2} +\sum _{j=snl+1}^{j=i-1}\left(w_{ice,\, j} +w_{liq,\, j} \right) . + +The compaction rate due to melting :math:`C_{R3,\; i}` +(:math:`\text{s}^{-1}`) is taken to be the ratio of the change in snow ice +mass after the melting to the mass before melting + +.. math:: + :label: 7.48) + + C_{R3,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} =-\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) + +and melting is identified during the phase change calculations (section +6.2). Because snow depth is defined as the average depth of the snow +covered area, the snow depth must also be updated for changes in +:math:`f_{sno}` . + +.. math:: + :label: 7.49) + + C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) + +The snow layer thickness after compaction is then + +.. math:: + :label: 7.50) + + \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). + +Snow Layer Combination and Subdivision +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After the determination of snow temperature including phase change +(Chapter 6), snow hydrology (sections 7.2.2, 7.2.3, and 7.2.4), and the +compaction calculations , the number of snow layers is adjusted by +either combining or subdividing layers. The combination and subdivision +of snow layers is based on Jordan (1991). + +7.2.7.1 Combination +''''''''''''''''''' + +If a snow layer has nearly melted or if its thickness +:math:`\Delta z_{i}` is less than the prescribed minimum thickness +:math:`\Delta z_{\min }` (Table 7.2), the layer is combined with a +neighboring layer. The overlying or underlying layer is selected as the +neighboring layer according to the following rules + +#. If the top layer is being removed, it is combined with the underlying + layer + +#. If the underlying layer is not snow (i.e., it is the top soil layer), + the layer is combined with the overlying layer + +#. If the layer is nearly completely melted, the layer is combined with + the underlying layer + +#. If none of the above rules apply, the layer is combined with the + thinnest neighboring layer. + +A first pass is made through all snow layers to determine if any layer +is nearly melted (:math:`w_{ice,\, i} \le 0.1`). If so, the remaining +liquid water and ice content of layer :math:`i` is combined with the +underlying neighbor :math:`i+1` as + +.. math:: + :label: 7.51) + + w_{liq,\, i+1} =w_{liq,\, i+1} +w_{liq,\, i} + +.. math:: + :label: 7.52) + + w_{ice,\, i+1} =w_{ice,\, i+1} +w_{ice,\, i} . + +This includes the snow layer directly above the top soil layer. In this +case, the liquid water and ice content of the melted snow layer is added +to the contents of the top soil layer. The layer properties, +:math:`T_{i}` , :math:`w_{ice,\, i}` , :math:`w_{liq,\, i}` , +:math:`\Delta z_{i}` , are then re-indexed so that the layers above the +eliminated layer are shifted down by one and the number of snow layers +is decremented accordingly. + +At this point, if there are no explicit snow layers remaining +(:math:`snl=0`), the snow water equivalent :math:`W_{sno}` and snow +depth :math:`z_{sno}` are set to zero, otherwise, :math:`W_{sno}` and +:math:`z_{sno}` are re-calculated as + +.. math:: + :label: 7.53) + + W_{sno} =\sum _{i=snl+1}^{i=0}\left(w_{ice,\, i} +w_{liq,\, i} \right) + +.. math:: + :label: 7.54) + + z_{sno} =\sum _{i=snl+1}^{i=0}\Delta z_{i} . + +If the snow depth :math:`0`\ 1 | 0.03 | 0.02 | ++--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ +| 2 | 0.015 | 2 | :math:`>`\ 2 | 0.07 | 0.05 | ++--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ +| 3 | 0.025 | 3 | :math:`>`\ 3 | 0.18 | 0.11 | ++--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ +| 4 | 0.055 | 4 | :math:`>`\ 4 | 0.41 | 0.23 | ++--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ +| 5 (bottom) | 0.115 | 5 | - | - | - | ++--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ + +The maximum snow layer thickness, :math:`\Delta z_{\max }` , depends on +the number of layers, :math:`N_{l}` and :math:`N_{u}` (section +7.2.7.2). + +7.2.7.2 Subdivision +''''''''''''''''''' + +The snow layers are subdivided when the layer thickness exceeds the +prescribed maximum thickness :math:`\Delta z_{\max }` with lower and +upper bounds that depend on the number of snow layers (Table 7.2). For +example, if there is only one layer, then the maximum thickness of that +layer is 0.03 m, however, if there is more than one layer, then the +maximum thickness of the top layer is 0.02 m. Layers are checked +sequentially from top to bottom for this limit. If there is only one +snow layer and its thickness is greater than 0.03 m (Table 7.2), the +layer is subdivided into two layers of equal thickness, liquid water and +ice contents, and temperature. If there is an existing layer below the +layer to be subdivided, the thickness :math:`\Delta z_{i}` , liquid +water and ice contents, :math:`w_{liq,\; i}` and :math:`w_{ice,\; i}` , +and temperature :math:`T_{i}` of the excess snow are combined with the +underlying layer according to equations -. If there is no underlying +layer after adjusting the layer for the excess snow, the layer is +subdivided into two layers of equal thickness, liquid water and ice +contents. The vertical snow temperature profile is maintained by +calculating the slope between the layer above the splitting layer +(:math:`T_{1}` ) and the splitting layer (:math:`T_{2}` ) and +constraining the new temperatures (:math:`T_{2}^{n+1}` , +:math:`T_{3}^{n+1}` ) to lie along this slope. The temperature of the +lower layer is first evaluated from + +.. math:: + :label: 7.62) + + T'_{3} =T_{2}^{n} -\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right), + +then adjusted as, + +.. math:: + :label: 7.63) + + \begin{array}{l} {T_{3}^{n+1} =T_{2}^{n} \qquad T'_{3} \ge T_{f} } \\ {T_{2}^{n+1} =T_{2}^{n} +\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right)\qquad T'_{3} f_{c} } \\ {f_{connected} =0\qquad \qquad \qquad for\, f_{h2osfc} \le f_{c} } \end{array} + +where :math:`f_{c}` is a threshold below which no single connected +inundated area spans the grid cell and :math:`\mu` is a scaling +exponent. Default values of :math:`f_{c}` and :math:`\mu` \ are 0.4 and +0.14, respectively. When the inundated fraction of the grid cell +surpasses :math:`f_{c}` , the surface water store acts as a linear +reservoir + +.. math:: + :label: 7.70) + + qout,h2osfc=kh2osfcf_{connected} (Wsfc-Wc)\frac{1}{\Delta t} + +where :math:`qout,h2osfc` is the surface water runoff, :math:`kh2osfc` +is a constant, :math:`Wc` is the amount of surface water present when +:math:`f_{h2osfc} =f_{c}` , and :math:`\Delta t` is the model time step. +The linear storage coefficent :math:`kh2osfc=\sin \left(\beta \right)` +is a function of grid cell mean topographic slope where :math:`\beta` +is the slope in radians. + +Infiltration +^^^^^^^^^^^^^^^^^^ + +The surface moisture flux remaining after surface runoff has been +removed, + +.. math:: + :label: 7.71) + + qin,surface=(1-f_{sat} )q_{liq,\, 0} + +is divided into inputs to surface water (:math:`q_{in,\, h2osfc}` ) and +the soil :math:`q_{in,soil}` . If :math:`q_{in,soil}` exceeds the +maximum soil infiltration capacity (kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}`), + +.. math:: + :label: ZEqnNum569150 + + q_{infl,\, \max } =(1-fsat){\rm \Theta }iceksat + +where :math:`{\rm \Theta }ice` is an ice impedance factor (section +7.4), infiltration excess (Hortonian) runoff is generated + +.. math:: + :label: 7.73) + + q_{infl,\, excess} =\max \left(q_{in,soil} -\left(1-f_{h2osfc} \right)q_{\inf l,\max } ,0\right) + +and transferred from :math:`q_{in,soil}` to :math:`q_{in,h2osfc}` . +After evaporative losses have been removed, these moisture fluxes are + +.. math:: + :label: 7.74) + + q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} +q_{infl,excess} -q_{evap,h2osfc} + +and + +.. math:: + :label: 7.75) + + qin,soil=(1-f_{h2osfc} )q_{in,surface} -q_{\inf l,excess} -(1-f_{sno} -f_{h2osfc} )qevap,soil. + +The balance of surface water is then calculated as + +.. math:: + :label: 7.76) + + \Delta W_{sfc} =\left(qin,h2osfc-qout,h2osfc-qdrain,h2osfc\right)\Delta t. + +Bottom drainage from the surface water store + +.. math:: + :label: 7.77) + + qdrain,h2osfc=\min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) + +is then added to :math:`q_{in,soil}` giving the total infiltration +into the surface soil layer + +.. math:: + :label: 7.78) + + q_{infl} =q_{in,soil} +q_{drain,h2osfc} + +Infiltration :math:`q_{infl}` and explicit surface runoff +:math:`q_{over}` are not allowed for glaciers. + +Soil Water +-------------- + +Soil water is predicted from a multi-layer model, in which the vertical +soil moisture transport is governed by infiltration, surface and +sub-surface runoff, gradient diffusion, gravity, canopy transpiration +through root extraction, and interactions with groundwater (Figure 7.1). +The following derivation generally follows that of Z.-L. Yang (1998, +unpublished manuscript) with modifications by Zeng and Decker (2009). + +For one-dimensional vertical water flow in soils, the conservation of +mass is stated as + +.. math:: + :label: ZEqnNum790844 + + \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q + +where :math:`\theta` is the volumetric soil water content +(mm:math:`{}^{3}` of water mm\ :math:`{}^{-3}` of soil), :math:`t` is +time (s), :math:`z` is height above some datum in the soil column (mm) +(positive upwards), :math:`q` is soil water flux (kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}` or mm s\ :math:`{}^{-1}`) (positive upwards), and +:math:`Q` is a soil moisture sink term (mm of water mm\ :math:`{}^{-1}` +of soil s\ :math:`{}^{-1}`) (ET loss). This equation is solved +numerically by dividing the soil column into multiple layers in the +vertical and integrating downward over each layer with an upper boundary +condition of the infiltration flux into the top soil layer +:math:`q_{infl}` and a lower boundary condition that depends on the +depth of the water table. + +The soil water flux :math:`q` in equation can be described by Darcy’s +law + +.. math:: + :label: 7.80) + + q=-k\frac{\partial \psi _{h} }{\partial z} + +where :math:`k` is the hydraulic conductivity (mm s\ :math:`{}^{-1}`), +and :math:`\psi _{h}` is the hydraulic potential (mm). The hydraulic +potential is + +.. math:: + :label: 7.81) + + \psi _{h} =\psi _{m} +\psi _{z} + +where :math:`\psi _{m}` is the soil matric potential (mm) (which is +related to the adsorptive and capillary forces within the soil matrix), +and :math:`\psi _{z}` is the gravitational potential (mm) (the vertical +distance from an arbitrary reference elevation to a point in the soil). +If the reference elevation is the soil surface, then +:math:`\psi _{z} =z`. Letting :math:`\psi =\psi _{m}` , Darcy’s law +becomes + +.. math:: + :label: ZEqnNum186573 + + q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]. + +Darcy’s equation can be further manipulated to yield + +.. math:: + :label: 7.83) + + q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]=-k\left(\frac{\partial \psi }{\partial z} +1\right)=-k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right). + +Substitution of this equation into equation , with :math:`Q=0`, yields +the Richards equation + +.. math:: + :label: ZEqnNum670361 + + \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } \right)+1\right]. + +Zeng and Decker (2009) note that this :math:`\theta` -based form of the +Richards equation cannot maintain the hydrostatic equilibrium soil +moisture distribution because of the truncation errors of the +finite-difference numerical scheme. They show that this deficiency can +be overcome by subtracting the equilibrium state from equation as + +.. math:: + :label: ZEqnNum936839 + + q=-k\left[\frac{\partial \left(\psi +z-C\right)}{\partial z} \right] + +where :math:`C` is a constant hydraulic potential above the water table +:math:`z_{\nabla }` + +.. math:: + :label: ZEqnNum126975 + + C=\psi _{E} +z=\psi _{sat} \left[\frac{\theta _{E} \left(z\right)}{\theta _{sat} } \right]^{-B} +z=\psi _{sat} +z_{\nabla } + +so that + +.. math:: + :label: ZEqnNum537733 + + q=-k\left[\frac{\partial \left(\psi -\psi _{E} \right)}{\partial z} \right] + +where :math:`\psi _{E}` \ is the equilibrium soil matric potential +(mm). Substitution of equations and into equation yields Zeng and +Decker’s (2009) modified Richards equation + +.. math:: + :label: 7.88) + + \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \left(\psi -\psi _{E} \right)}{\partial z} \right)\right]-Q + +where the soil moisture sink term :math:`Q` is now included. + +Hydraulic Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The hydraulic conductivity :math:`k_{i}` (mm s\ :math:`{}^{-1}`) and +the soil matric potential :math:`\psi _{i}` (mm) for layer :math:`i` +vary with volumetric soil water :math:`\theta _{i}` and soil texture. +As with the soil thermal properties (section 6.3) the hydraulic +properties of the soil are assumed to be a weighted combination of the +mineral properties, which are determined according to sand and clay +contents based on work by Clapp and Hornberger (1978) and Cosby et al. +(1984), and organic properties of the soil (Lawrence and Slater 2008). + +The hydraulic conductivity is defined at the depth of the interface of +two adjacent layers :math:`z_{h,\, i}` (Figure 7.3) and is a function +of the saturated hydraulic conductivity +:math:`k_{sat} \left[z_{h,\, i} \right]`, the liquid volumetric soil +moisture of the two layers :math:`\theta _{i}` and +:math:`\theta _{i+1}` and an ice impedance factor +:math:`\Theta _{ice}` + +.. math:: + :label: ZEqnNum398074 + + k\left[z_{h,\, i} \right]=\left\{\begin{array}{l} {\Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +3} \qquad 1\le i\le N_{levsoi} -1} \\ {\Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{2B_{i} +3} \qquad i=N_{levsoi} } \end{array}\right\}. + +The ice impedance factor is a function of ice content, and is meant to +quantify the increased tortuosity of the water flow when part of the +pore space is filled with ice. Swenson et al. (2012) used a power law +form :math:`\Theta _{ice} =10^{-\Omega F_{ice} }` where +:math:`\Omega =6`\ and +:math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the +ice-filled fraction of the pore space. + +Because the hydraulic properties of mineral and organic soil may differ +significantly, the bulk hydraulic properties of each soil layer are +computed as weighted averages of the properties of the mineral and +organic components. The water content at saturation (i.e. porosity) is + +.. math:: + :label: 7.90) + + \theta _{sat,i} =(1-f_{om,i} )\theta _{sat,\min ,i} +f_{om,i} \theta _{sat,om} + +where :math:`f_{om,i}` is the soil organic matter fraction, +:math:`\theta _{sat,om} =0.9` (Farouki 1981; Letts et al. 2000) is the +porosity of organic matter and the porosity of the mineral soil +:math:`\theta _{sat,\min ,i}` is + +.. math:: + :label: 7.91) + + \theta _{sai,\min ,i} =0.489-0.00126(\% sand)_{i} . + +The exponent “:math:`B`†is + +.. math:: + :label: 7.92) + + B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} + +where :math:`B_{om} =2.7`\ (Letts et al. 2000) and + +.. math:: + :label: 7.93) + + B_{\min ,i} =2.91+0.159(\% clay)_{i} . + +The soil matric potential (mm) is defined at the node depth +:math:`z_{i}` of each layer :math:`i` (Figure 7.3) + +.. math:: + :label: ZEqnNum316201 + + \psi _{i} =\psi _{sat,\, i} \left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta _{i} }{\theta _{sat,\, i} } \le 1 + +where the saturated soil matric potential (mm) is + +.. math:: + :label: 7.95) + + \psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om} + +where :math:`\psi _{sat,om} =-10.3`\ mm (Letts et al. 2000) is the +saturated organic matter matric potential and the saturated mineral soil +matric potential :math:`\psi _{sat,\min ,i}` \ is + +.. math:: + :label: 7.96) + + \psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } . + +The saturated hydraulic conductivity, +:math:`k_{sat} \left[z_{h,\, i} \right]` (mm s\ :math:`{}^{-1}`), for +organic soils (:math:`k_{sat,\, om}` ) may be two to three orders of +magnitude larger than that of mineral soils (:math:`k_{sat,\, \min }` ). +Bulk soil layer values of :math:`k_{sat}` \ calculated as weighted +averages based on :math:`f_{om}` may therefore be determined primarily +by the organic soil properties even for values of :math:`f_{om}` as low +as 1 %. To better represent the influence of organic soil material on +the grid cell average saturated hydraulic conductivity, the soil organic +matter fraction is further subdivided into “connected†and “unconnected†+fractions using a result from percolation theory (Stauffer and Aharony +1994, Berkowitz and Balberg 1992). Assuming that the organic and mineral +fractions are randomly distributed throughout a soil layer, percolation +theory predicts that above a threshold value +:math:`f_{om} =f_{threshold}` , connected flow pathways consisting of +organic material only exist and span the soil space. Flow through these +pathways interacts only with organic material, and thus can be described +by :math:`k_{sat,\, om}` . This fraction of the grid cell is given by + +.. math:: + :label: 7.97) + + \begin{array}{l} {f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta _{perc} } f_{om} {\rm \; }\qquad f_{om} \ge f_{threshold} } \\ {f_{perc} =0\qquad f_{om} 0} \\ {\left(r_{e,\, i} \right)_{j} =0\qquad \left(\beta _{t} \right)_{j} =0} \end{array} + +and :math:`\left(r_{i} \right)_{j}` is the fraction of roots in layer +:math:`i` (Chapter 8), :math:`\left(w_{i} \right)_{j}` is a soil +dryness or plant wilting factor for layer :math:`i` (Chapter 8), and +:math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total +soil column for the :math:`j^{th}` PFT (Chapter 8). + +The soil water fluxes in equation , which are a function of +:math:`\theta _{liq,\, i}` and :math:`\theta _{liq,\, i+1}` because of +their dependence on hydraulic conductivity and soil matric potential, +can be linearized about :math:`\theta` using a Taylor series expansion +as + +.. math:: + :label: 7.108) + + q_{i}^{n+1} =q_{i}^{n} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } \Delta \theta _{liq,\, i+1} + +.. math:: + :label: 7.109) + + q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } \Delta \theta _{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} . + +Substitution of these expressions for :math:`q_{i}^{n+1}` and +:math:`q_{i-1}^{n+1}` into equation results in a general tridiagonal +equation set of the form + +.. math:: + :label: 7.110) + + r_{i} =a_{i} \Delta \theta _{liq,\, i-1} +b_{i} \Delta \theta _{liq,\, i} +c_{i} \Delta \theta _{liq,\, i+1} + +where + +.. math:: + :label: ZEqnNum557934 + + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + +.. math:: + :label: 7.112) + + b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.113) + + c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + +.. math:: + :label: ZEqnNum981892 + + r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . + +The tridiagonal equation set is solved over +:math:`i=1,\ldots ,N_{levsoi} +1` where the layer +:math:`i=N_{levsoi} +1` is a virtual layer representing the aquifer. + +The finite-difference forms of the fluxes and partial derivatives in +equations - can be obtained from equation as + +.. math:: + :label: 7.115) + + q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + +.. math:: + :label: 7.116) + + q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] + +.. math:: + :label: 7.117) + + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + +.. math:: + :label: 7.118) + + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + +.. math:: + :label: 7.119) + + \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] + +.. math:: + :label: 7.120) + + \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right]. + +The derivatives of the soil matric potential at the node depth are +derived from equation + +.. math:: + :label: 7.121) + + \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta _{\, \, i-1} } + +.. math:: + :label: 7.122) + + \frac{\partial \psi _{i} }{\partial \theta _{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta _{i} } + +.. math:: + :label: 7.123) + + \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta _{\, i+1} } + +with the constraint +:math:`0.01\, \theta _{sat,\, i} \le \theta _{\, i} \le \theta _{sat,\, i}` . + +The derivatives of the hydraulic conductivity at the layer interface are +derived from equation + +.. math:: + :label: 7.124) + + \begin{array}{l} {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } =\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } =\left(1-\frac{f_{frz,\, i-1} +f_{frz,\, i} }{2} \right)\left(2B_{i-1} +3\right)k_{sat} \left[z_{h,\, i-1} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right]^{2B_{i-1} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right)} \end{array} + +.. math:: + :label: 7.125) + + \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } =\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } =\left(1-\frac{f_{frz,\, i} +f_{frz,\, i+1} }{2} \right)\left(2B_{i} +3\right)k_{sat} \left[z_{h,\, i} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right)} \end{array}. + +7.4.2.1 Equilibrium soil matric potential and volumetric moisture +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The equilibrium soil matric potential :math:`\psi _{E}` can be derived +from equation as + +.. math:: + :label: ZEqnNum899028 + + \psi _{E} =\psi _{sat} \left(\frac{\theta _{E} \left(z\right)}{\theta _{sat} } \right)^{-B} + +and the equilibrium volumetric water content +:math:`\theta _{E} \left(z\right)` at depth :math:`z` can also be +derived as + +.. math:: + :label: 7.127) + + \theta _{E} \left(z\right)=\theta _{sat} \left(\frac{\psi _{sat} +z_{\nabla } -z}{\psi _{sat} } \right)^{-\frac{1}{B} } . + +Here, the soil matric potentials, the water table depth +:math:`z_{\nabla }` and the soil depths have units of mm. For the +finite-difference scheme, a layer-average equilibrium volumetric water +content is used in equation and can be obtained from + +.. math:: + :label: 7.128) + + \overline{\theta _{E,\, i} }=\int _{z_{h,\, i-1} }^{z_{h,\, i} }\frac{\theta _{E} \left(z\right)}{z_{h,\, i} -z_{h,\, i-1} } \, dz + +which when integrated yields + +.. math:: + :label: ZEqnNum445442 + + \overline{\theta _{E,\, i} }=\frac{\theta _{sat,\, i} \psi _{sat,\, i} }{\left(z_{h,\, i} -z_{h,\, i-1} \right)\left(1-\frac{1}{B_{i} } \right)} \left[\left(\frac{\psi _{sat,\, i} -z_{\nabla } +z_{h,\, i} }{\psi _{sat,\, i} } \right)^{1-\frac{1}{B_{i} } } -\left(\frac{\psi _{sat,\, i} -z_{\nabla } +z_{h,\, i-1} }{\psi _{sat,\, i} } \right)^{1-\frac{1}{B_{i} } } \right]. + +Equation is valid when the water table :math:`z_{\nabla }` is deeper +than both interface depths :math:`z_{h,\, i-1}` and +:math:`z_{h,\, i}` . Since the water table can be within the soil +column, the equation is modified if the water table is within soil layer +:math:`i` (:math:`z_{h,\, i-1} z_{h,\, N_{levsoi} }` ), an equilibrium volumetric +soil moisture is calculated for a virtual layer :math:`i=N_{levsoi} +1` +as + +.. math:: + :label: ZEqnNum235293 + + \overline{\theta _{E,\, i=N_{levsoi+1} } }=\frac{\theta _{sat,i-1} \psi _{sat,\, i-1} }{\left(z_{\nabla } -z_{h,\, i-1} \right)\left(1-\frac{1}{B_{i-1} } \right)} \left[1-\left(\frac{\psi _{sat,\, i-1} -z_{\nabla } +z_{h,\, i-1} }{\psi _{sat,\, i-1} } \right)^{1-\frac{1}{B_{i-1} } } \right] + +The equilibrium volumetric soil moisture is constrained by + +.. math:: + :label: 7.133) + + 0\le \overline{\theta _{E,\, i} }\le \theta _{sat,\, i} + +The equilibrium soil matric potential is then + +.. math:: + :label: ZEqnNum533842 + + \psi _{E,\, i} =\psi _{sat,\, i} \left(\frac{\overline{\theta _{E,\, i} }}{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad \frac{\overline{\theta _{E,\, i} }}{\theta _{sat,\, i} } \ge 0.01 + +7.4.2.2 Equation set for layer :math:`i=1` +'''''''''''''''''''''''''''''''''''''''''' + +For the top soil layer (:math:`i=1`), the boundary condition is the +infiltration rate (section 7.3), +:math:`q_{i-1}^{n+1} =-q_{infl}^{n+1}` , and the water balance equation +is + +.. math:: + :label: 7.135) + + \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =q_{infl}^{n+1} +q_{i}^{n+1} -e_{i} . + +After grouping like terms, the coefficients of the tridiagonal set of +equations for :math:`i=1` are + +.. math:: + :label: 7.136) + + a_{i} =0 + +.. math:: + :label: 7.137) + + b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.138) + + c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + +.. math:: + :label: 7.139) + + r_{i} =q_{infl}^{n+1} -q_{i}^{n} +e_{i} . + +7.4.2.3 Equation set for layers :math:`i=2,\ldots ,N_{levsoi} -1` +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The coefficients of the tridiagonal set of equations for +:math:`i=2,\ldots ,N_{levsoi} -1` are + +.. math:: + :label: 7.140) + + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + +.. math:: + :label: 7.141) + + b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.142) + + c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + +.. math:: + :label: 7.143) + + r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . + +7.4.2.4 Equation set for layers :math:`i=N_{levsoi} ,\ldots N_{levsoi} +1` +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +For the lowest soil layer (:math:`i=N_{levsoi}` ), the bottom boundary +condition depends on the depth of the water table. If the water table is +within the soil column (:math:`z_{\nabla } \le z_{h,\, N_{levsoi} }` ), +a zero-flux bottom boundary condition is applied (:math:`q_{i}^{n} =0`) +and the coefficients of the tridiagonal set of equations for +:math:`i=N_{levsoi}` are + +.. math:: + :label: 7.144) + + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + +.. math:: + :label: 7.145) + + b_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.146) + + c_{i} =0 + +.. math:: + :label: 7.147) + + r_{i} =q_{i-1}^{n} +e_{i} . + +The coefficients for the aquifer layer :math:`i=N_{levsoi} +1` are then + +.. math:: + :label: 7.148) + + a_{i} =0 + +.. math:: + :label: 7.149) + + b_{i} =-\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.150) + + c_{i} =0 + +.. math:: + :label: 7.151) + + r_{i} =0. + +If the water table is below the soil column +(:math:`z_{\nabla } >z_{h,\, N_{levsoi} }` ), the coefficients for +:math:`i=N_{levsoi}` are + +.. math:: + :label: 7.152) + + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + +.. math:: + :label: 7.153) + + b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.154) + + c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + +.. math:: + :label: 7.155) + + r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . + +The :math:`i=N_{levsoi} +1` terms are evaluated using + +.. math:: + :label: 7.156) + + \psi _{N_{levsoi} +1} =\psi _{sat,\, N_{levsoi} } \left[s_{N_{levsoi} +1} \right]^{-B_{N_{levsoi} } } \ge -1\times 10^{8} + +.. math:: + :label: 7.157) + + z_{N_{levsoi} +1} =0.5\left(z_{\nabla } +z_{N_{levsoi} } \right) + +where + +.. math:: + :label: 7.158) + + s_{N_{levsoi} +1} =0.5\left(\frac{\theta _{sat,\, N_{levsoi} } +\theta _{N_{levsoi} } }{\theta _{sat,\, N_{levsoi} } } \right)\qquad 0.01\le s_{N_{levsoi} +1} \le 1, + + :math:`\psi _{E,\, N_{levsoi} +1}` is evaluated from equations and , +and + +.. math:: + :label: 7.159) + + \frac{\partial \psi _{N_{levsoi} +1} }{\partial \theta _{liq,\, N_{levsoi} +1} } =-B_{N_{levsoi} } \frac{\psi _{N_{levsoi} +1} }{s_{\, N_{levsoi} } \theta _{sat,\, N_{levsoi} } } . + +The coefficients for the aquifer layer :math:`i=N_{levsoi} +1` are then + +.. math:: + :label: 7.160) + + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + +.. math:: + :label: 7.161) + + b_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + +.. math:: + :label: 7.162) + + c_{i} =0 + +.. math:: + :label: 7.163) + + r_{i} =q_{i-1}^{n} . + +Upon solution of the tridiagonal equation set (Press et al. 1992), the +liquid water contents are updated as follows + +.. math:: + :label: 7.164) + + w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta _{liq,\, i} \Delta z_{i} \qquad i=1,\ldots ,N_{levsoi} . + +The volumetric water content is + +.. math:: + :label: 7.165) + + \theta _{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } . + +Frozen Soils and Perched Water Table +---------------------------------------- + +When soils freeze, the power-law form of the ice impedance factor +(section 7.4.1) can greatly decrease the hydraulic conductivity of the +soil, leading to nearly impermeable soil layers. When unfrozen soil +layers are present above relatively ice-rich frozen layers, the +possibility exists for perched saturated zones. Lateral drainage from +perched saturated regions is parameterized as a function of the +thickness of the saturated zone + +.. math:: + :label: 7.166) + + q_{drai,perch} =k_{drai,\, perch} \left(z_{frost} -z_{\nabla ,perch} \right) + +where :math:`k_{drai,\, perch}` depends on topographic slope and soil +hydraulic conductivity, + +.. math:: + :label: 7.167) + + k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta _{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right) + +where :math:`\Theta _{ice}` is an ice impedance factor determined from +the ice content of the soil layers interacting with the water table +(section 7.6), :math:`\beta` is the mean grid cell topographic slope in +radians, :math:`z_{frost}` \ is the depth to the frost table, and +:math:`z_{\nabla ,perch}` is the depth to the perched saturated zone. +The frost table :math:`z_{frost}` is defined as the shallowest frozen +layer having an unfrozen layer above it, while the perched water table +:math:`z_{\nabla ,perch}` is defined as the depth at which the +volumetric water content drops below a specified threshold. The default +threshold is set to 0.9. Drainage from the perched saturated zone +:math:`q_{drai,perch}` is removed from layers :math:`N_{perch}` +through :math:`N_{frost}` , which are the layers containing +:math:`z_{\nabla ,perch}` and, :math:`z_{frost}` \ respectively. + +Groundwater-Soil Water Interactions +--------------------------------------- + +Drainage or sub-surface runoff is based on the SIMTOP scheme (Niu et al. +2005) with a modification to account for reduced drainage in frozen +soils. In the work of Niu et al. (2005), the drainage :math:`q_{drai}` +(kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) was formulated as + +.. math:: + :label: ZEqnNum924767 + + q_{drai} =q_{drai,\, \max } \exp \left(-f_{drai} z_{\nabla } \right). + +Here, the water table depth :math:`z_{\nabla }` has units of meters. To +restrict drainage in frozen soils, Niu et al. (2005) added the following +condition + +.. math:: + :label: 7.169) + + q_{drai} =0\qquad {\rm for\; \; }w_{ice,\, N_{levsoi} } >w_{liq,\, N_{levsoi} } . + +In preliminary testing it was found that a more gradual restriction of +drainage was required so that the water table depth remained dynamic +under partially frozen conditions. The following modification is made to +equation + +.. math:: + :label: ZEqnNum150955 + + q_{drai} =\Theta _{ice} q_{drai,\, \max } \exp \left(-f_{drai} z_{\nabla } \right) + +where :math:`\Theta _{ice}` is an ice impedance factor determined from +the ice content of the soil layers interacting with the water table + +.. math:: + :label: 7.171) + + \Theta _{ice} =10^{-\Omega \left(\frac{\sum _{i=jwt}^{i=N_{levsoi} }F_{ice,i} \Delta z_{i} }{\sum _{i=jwt}^{i=N_{levsoi} }\Delta z_{i} } \right)} + +where :math:`\Omega =6`\ is an adjustable parameter, :math:`jwt` is the +index of the layer directly above the water table, +:math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the +ice-filled fraction of the pore space of soil layer :math:`i` (kg +m\ :math:`{}^{-2}`), and :math:`\Delta z_{i}` is the layer thickness +(mm). This expression is functionally the same as that used to determine +the ice impedance factor in section 7.4. In equation , the decay factor +:math:`f_{drai} =2.5` m\ :math:`{}^{-1}` and the maximum drainage when +the water table depth is at the surface +:math:`q_{drai,\, \max } =10\sin (\beta )` kg m\ :math:`{}^{-2}` +s\ :math:`{}^{-1}` , where :math:`\beta` is the mean grid cell +topographic slope in radians, were determined for global simulations +through sensitivity analysis and comparison with observed runoff. + +Determination of water table depth :math:`z_{\nabla }` is based on work +by Niu et al. (2007). In this approach, a groundwater component is added +in the form of an unconfined aquifer lying below the soil column (Figure +7.1). The groundwater solution is dependent on whether the water table +is within or below the soil column. The water stored in the unconfined +aquifer :math:`W_{a}` has a prescribed maximum value (5000 mm). When +the water table is within the soil column, :math:`W_{a}` is constant +because there is no water exchange between the soil column and the +underlying aquifer. In this case, recharge to the water table is +diagnosed by applying Darcy’s law across the water table + +.. math:: + :label: 7.172) + + q_{rech\arg e} =-k_{aq} \frac{\left(\Psi _{\nabla } -\Psi _{jwt} \right)}{\left(z_{\nabla } -z_{jwt} \right)} + +where :math:`\Psi _{\nabla } =0` is the matric potential at the water +table and\ :math:`k_{aq} =\Theta _{ice,jwt+1} k\left[z_{jwt+1} \right]` +is the hydraulic conductivity of the layer containing the water table. +Change in the water table is then calculated as the difference between +recharge and drainage, scaled by the specific yield of the layer +containing the water table + +.. math:: + :label: ZEqnNum287831 + + \Delta z_{\nabla } =\frac{\left(q_{rech\arg e} -q_{drai} \right)}{S_{y} } \Delta t. + +The specific yield, :math:`S_{y}` , which depends on the soil +properties and the water table location, is derived by taking the +difference between two equilibrium soil moisture profiles whose water +tables differ by an infinitesimal amount + +.. math:: + :label: 7.174) + + S_{y} =\theta _{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right) + +where B is the Clapp-Hornberger exponent. Because :math:`S_{y}` is a +function of the soil properties, it results in water table dynamics that +are consistent with the soil water fluxes described in section 7.4. + +For the case when the water table is below the soil column, the change +in water stored in the unconfined aquifer :math:`W_{a}` (mm) is updated +as + +.. math:: + :label: 7.174) + + \Delta W_{a}^{} =\left(q_{recharge} -q_{drai} \right)\Delta t + +and the water table is updated using equation with the specific yield of +layer :math:`N_{levsoi}` . + +The recharge rate is defined as positive when water enters the aquifer + +.. math:: + :label: 7.174) + + q_{recharge} =\frac{\Delta \theta _{liq,\, N_{levsoi} +1} \Delta z_{N_{levsoi} +1} }{\Delta t} + +where +:math:`\Delta \theta _{liq,\, N_{levsoi} +1} =\theta _{liq,\, N_{levsoi} +1}^{n+1} -\theta _{liq,\, N_{levsoi} +1}^{n}` +is the change in liquid water content for layer :math:`i=N_{levsoi} +1` +calculated from the solution of the soil water equations (section 7.4), +and :math:`\Delta z_{N_{levsoi} +1}` (mm) is + +.. math:: + :label: 7.174) + + \Delta z_{N_{levsoi} +1} =z_{\nabla }^{n} -z_{h,\, N_{levsoi} } . + +After the above calculations, two numerical adjustments are implemented +to keep the liquid water content of each soil layer +(:math:`w_{liq,\, i}` ) within physical constraints of +:math:`w_{liq}^{\min } \le w_{liq,\, i} \le \left(\theta _{sat,\, i} -\theta _{ice,\, i} \right)\Delta z_{i}` +where :math:`w_{liq}^{\min } =0.01` (mm). First, beginning with the +bottom soil layer :math:`i=N_{levsoi}` , any excess liquid water in each +soil layer +(:math:`w_{liq,\, i}^{excess} =w_{liq,\, i} -\left(\theta _{sat,\, i} -\theta _{ice,\, i} \right)\Delta z_{i} \ge 0`) +is successively added to the layer above. Any excess liquid water that +remains after saturating the entire soil column (plus a maximum surface +ponding depth :math:`w_{liq}^{pond} =10` kg m\ :math:`{}^{-2}`), is +added to drainage :math:`q_{drai}` . Second, to prevent negative +:math:`w_{liq,\, i}` , each layer is successively brought up to +:math:`w_{liq,\, i} =w_{liq}^{\min }` by taking the required amount of +water from the layer below. If this results in +:math:`w_{liq,\, N_{levsoi} } T_{f} -2{\rm \; and\; }\theta _{liq,\, i} >0} \\ {0\qquad \qquad \qquad \qquad {\rm for\; }T_{i} \le T_{f} -2{\rm \; or\; }\theta _{liq,\, i} \le 0} \end{array}\right\} + +where :math:`\psi _{i}` is the soil water matric potential (mm) and +:math:`\psi _{c}` and :math:`\psi _{o}` are the soil water potential +(mm) when stomata are fully closed or fully open (respectively) (Table +8.1). The term in brackets scales :math:`w_{i}` by the ratio of the +effective porosity (accounting for the ice fraction; +:math:`\theta _{sat} -\theta _{ice}` ) relative to the total porosity. + +Here, the soil water matric potential :math:`\psi _{i}` \ is defined as + +.. math:: + :label: 8.28) + + \psi _{i} =\psi _{sat,i} \, s_{i}^{-B_{i} } \ge \psi _{c} + +where :math:`s_{i}` is the soil wetness for layer :math:`i` with +respect to the effective porosity and :math:`\psi _{sat,i}` and +:math:`B_{i}` are the saturated soil matric potential (mm) and the +Clapp and Hornberger (1978) parameter (section 7.4.1). The soil wetness +:math:`s_{i}` is + +.. math:: + :label: 8.29) + + s_{i} =\frac{\theta _{liq,\, i} }{\theta _{sat,\, i} -\theta _{ice,\, i} } \ge 0.01 + +where +:math:`\theta _{ice,\, i} ={w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(\rho _{ice} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{ice} \Delta z_{i} \right)} \le \theta _{sat,\, i}` \ and +:math:`\theta _{liq,\, i} ={w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(\rho _{liq} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{liq} \Delta z_{i} \right)} \le \theta _{sat,\, i} -\theta _{ice,\, i}` . +:math:`w_{ice,\, i}` and :math:`w_{liq,\, i}` are the ice and liquid +water contents (kg m\ :math:`{}^{-2}`) (Chapter 7), +:math:`\theta _{sat,\, i}` is the saturated volumetric water content +(section 7.4.1), :math:`\rho _{ice}` and :math:`\rho _{liq}` are the +densities of ice and liquid water (kg m\ :math:`{}^{-3}`) (Table 2.6), +and :math:`\Delta z_{i}` is the soil layer thickness (m) (section 6.1). + +The root fraction :math:`r_{i}` in each soil layer depends on the plant +functional type + +.. math:: + :label: 8.30) + + r_{i} =\left\{\begin{array}{l} {0.5\left[\begin{array}{l} {\exp \left(-r_{a} z_{h,\, i-1} \right)+\exp \left(-r_{b} z_{h,\, i-1} \right)-} \\ {\exp \left(-r_{a} z_{h,\, i} \right)-\exp \left(-r_{b} z_{h,\, i} \right)} \end{array}\right]\qquad {\rm for\; }1\le iT_{f} } \end{array}\right\}. + +The sensible heat flux (W m\ :math:`{}^{-2}`) is + +.. math:: + :label: ZEqnNum720553 + + H_{g} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{g} \right)}{r_{ah} } + +where :math:`\rho _{atm}` is the density of moist air (kg +m\ :math:`{}^{-3}`) (Chapter 5), :math:`C_{p}` is the specific heat +capacity of air (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), +:math:`\theta _{atm}` is the atmospheric potential temperature (K) +(Chapter 5), :math:`T_{g}` is the lake surface temperature (K) (at an +infinitesimal interface just above the top resolved model layer: snow, +ice, or water), and :math:`r_{ah}` is the aerodynamic resistance to +sensible heat transfer (s m\ :math:`{}^{-1}`) (section 5.1). + +The water vapor flux (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is + +.. math:: + :label: 9.10) + + E_{g} =-\frac{\rho _{atm} \left(q_{atm} -q_{sat}^{T_{g} } \right)}{r_{aw} } + +where :math:`q_{atm}` is the atmospheric specific humidity (kg +kg\ :math:`{}^{-1}`) (section 2.2.1), :math:`q_{sat}^{T_{g} }` \ is the +saturated specific humidity (kg kg\ :math:`{}^{-1}`) (section 5.5) at +the lake surface temperature :math:`T_{g}` , and :math:`r_{aw}` is the +aerodynamic resistance to water vapor transfer (s m\ :math:`{}^{-1}`) +(section 5.1). + +The zonal and meridional momentum fluxes are + +.. math:: + :label: 9.11) + + \tau _{x} =-\rho _{atm} \frac{u_{atm} }{r_{atm} } + +.. math:: + :label: 9.12) + + \tau _{y} =-\rho _{atm} \frac{v_{atm} }{r_{atm} } + +where :math:`u_{atm}` and :math:`v_{atm}` are the zonal and +meridional atmospheric winds (m s\ :math:`{}^{-1}`) (section 2.2.1), and +:math:`r_{am}` is the aerodynamic resistance for momentum (s +m\ :math:`{}^{-1}`) (section 5.1). + +The heat flux into the lake surface :math:`G` (W m\ :math:`{}^{-2}`) is + +.. math:: + :label: ZEqnNum122376 + + G=\frac{2\lambda _{T} }{\Delta z_{T} } \left(T_{g} -T_{T} \right) + +where :math:`\lambda _{T}` is the thermal conductivity (W +m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), :math:`\Delta z_{T}` is the +thickness (m), and :math:`T_{T}` is the temperature (K) of the top +resolved lake layer (snow, ice, or water). The top thermal conductivity +:math:`\lambda _{T}` of unfrozen lakes ( :math:`T_{g} >T_{f}` ) +includes conductivities due to molecular ( :math:`\lambda _{liq}` ) and +eddy (:math:`\lambda _{K}` ) diffusivities (section 9.5.4), as evaluated +in the top lake layer at the previous timestep, where +:math:`\lambda _{liq}` is the thermal conductivity of water (Table +2.6). For frozen lakes without resolved snow layers, +:math:`\lambda _{T} =\lambda _{ice}` . When resolved snow layers are +present, :math:`\lambda _{T}` \ is calculated based on the water +content, ice content, and thickness of the top snow layer, as for +non-vegetated surfaces. + +The absorbed solar radiation :math:`\vec{S}_{g}` is + +.. math:: + :label: 9.14) + + \vec{S}_{g} =\sum _{\Lambda }S_{atm} \, \downarrow _{\Lambda }^{\mu } \left(1-\alpha _{g,\, \Lambda }^{\mu } \right) +S_{atm} \, \downarrow _{\Lambda } \left(1-\alpha _{g,\, \Lambda } \right) + +where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and +:math:`S_{atm} \, \downarrow _{\Lambda }` are the incident direct beam +and diffuse solar fluxes (W m\ :math:`{}^{-2}`) and :math:`\Lambda` +denotes the visible (:math:`<` 0.7\ :math:`\mu {\rm m}`) and +near-infrared (:math:`\ge` 0.7\ :math:`\mu {\rm m}`) wavebands (section +2.2.1), and :math:`\alpha _{g,\, \Lambda }^{\mu }` and +:math:`\alpha _{g,\, \mu }` are the direct beam and diffuse lake +albedos (section 9.3). + +The net emitted longwave radiation is + +.. math:: + :label: 9.15) + + \vec{L}_{g} =L_{g} \, \uparrow -L_{atm} \, \downarrow + +where :math:`L_{g} \, \uparrow` is the upward longwave radiation from +the surface, :math:`L_{atm} \, \downarrow` is the downward atmospheric +longwave radiation (section 2.2.1). The upward longwave radiation from +the surface is + +.. math:: + :label: 9.16) + + L\, \uparrow =\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) + +where :math:`\varepsilon _{g} =0.97` is the lake surface emissivity, +:math:`\sigma` is the Stefan-Boltzmann constant (W m\ :math:`{}^{-2}` +K\ :math:`{}^{-4}`) (Table 2.6), and :math:`T_{g}^{n+1} -T_{g}^{n}` is +the difference in lake surface temperature between Newton-Raphson +iterations (see below). + +The sensible heat :math:`H_{g}` , the water vapor flux :math:`E_{g}` +through its dependence on the saturated specific humidity, the net +longwave radiation :math:`\vec{L}_{g}` , and the ground heat flux +:math:`G`, all depend on the lake surface temperature :math:`T_{g}` . +Newton-Raphson iteration is applied to solve for :math:`T_{g}` and the +surface fluxes as + +.. math:: + :label: ZEqnNum858039 + + \Delta T_{g} =\frac{\beta \overrightarrow{S}_{g} -\overrightarrow{L}_{g} -H_{g} -\lambda E_{g} -G}{\frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } +\frac{\partial H_{g} }{\partial T_{g} } +\frac{\partial \lambda E_{g} }{\partial T_{g} } +\frac{\partial G}{\partial T_{g} } } + +where :math:`\Delta T_{g} =T_{g}^{n+1} -T_{g}^{n}` and the subscript +“n†indicates the iteration. Therefore, the surface temperature +:math:`T_{g}^{n+1}` can be written as + +.. math:: + :label: ZEqnNum878786 + + T_{g}^{n+1} =\frac{\beta \overrightarrow{S}_{g} -\overrightarrow{L}_{g} -H_{g} -\lambda E_{g} -G+T_{g}^{n} \left(\frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } +\frac{\partial H_{g} }{\partial T_{g} } +\frac{\partial \lambda E_{g} }{\partial T_{g} } +\frac{\partial G}{\partial T_{g} } \right)}{\frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } +\frac{\partial H_{g} }{\partial T_{g} } +\frac{\partial \lambda E_{g} }{\partial T_{g} } +\frac{\partial G}{\partial T_{g} } } + +where the partial derivatives are + +.. math:: + :label: 9.19) + + \frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } =4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} , + +.. math:: + :label: 9.20) + + \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r_{ah} } , + +.. math:: + :label: 9.21) + + \frac{\partial \lambda E_{g} }{\partial T_{g} } =\frac{\lambda \rho _{atm} }{r_{aw} } \frac{dq_{sat}^{T_{g} } }{dT_{g} } , + +.. math:: + :label: 9.22) + + \frac{\partial G}{\partial T_{g} } =\frac{2\lambda _{T} }{\Delta z_{T} } . + +The fluxes of momentum, sensible heat, and water vapor are solved for +simultaneously with lake surface temperature as follows. The +stability-related equations are the same as for non-vegetated surfaces +(section 5.2), except that the surface roughnesses are here (weakly +varying) functions of the friction velocity :math:`u_{\*}` . To begin, +*z* :math:`{}_{0}`\ :math:`{}_{m}` is set based on the value +calculated for the last timestep (for :math:`T_{g} >T_{f}` ) or based on +the values in section 9.4.2 (otherwise), and the scalar roughness +lengths are set based on the relationships in section 9.4.2. + +#. An initial guess for the wind speed :math:`V_{a}` including the + convective velocity :math:`U_{c}` is obtained from eq. assuming an + initial convective velocity :math:`U_{c} =0` m s\ :math:`{}^{-1}` for + stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` + as evaluated from eq. ) and :math:`U_{c} =0.5` for unstable + conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). + +#. An initial guess for the Monin-Obukhov length :math:`L` is obtained + from the bulk Richardson number using equations and . + +#. The following system of equations is iterated four times: + +#. Heat of vaporization / sublimation :math:`\lambda` \ (eq. ) + +#. Thermal conductivity :math:`\lambda _{T}` \ (above) + +#. Friction velocity :math:`u_{\*}` (eqs. , , , ) + +#. Potential temperature scale :math:`\theta _{\*}` (eqs. , , , ) + +#. Humidity scale :math:`q_{\*}` (eqs. , , , ) + +#. Aerodynamic resistances :math:`r_{am}` , :math:`r_{ah}` , and + :math:`r_{aw}` (eqs. , , ) + +#. Lake surface temperature :math:`T_{g}^{n+1}` (eq.) + +#. Heat of vaporization / sublimation :math:`\lambda` (eq. ) + +#. Sensible heat flux :math:`H_{g}` is updated for :math:`T_{g}^{n+1}` + (eq.) + +#. Water vapor flux :math:`E_{g}` is updated for :math:`T_{g}^{n+1}` + as + + .. math:: + :label: ZEqnNum331835 + + E_{g} =-\frac{\rho _{atm} }{r_{aw} } \left[q_{atm} -q_{sat}^{T_{g} } -\frac{\partial q_{sat}^{T_{g} } }{\partial T_{g} } \left(T_{g}^{n+1} -T_{g}^{n} \right)\right] + +where the last term on the right side of equation is the change in +saturated specific humidity due to the change in :math:`T_{g}` between +iterations. + +#. Saturated specific humidity :math:`q_{sat}^{T_{g} }` and its + derivative :math:`\frac{dq_{sat}^{T_{g} } }{dT_{g} }` are updated + for :math:`T_{g}^{n+1}` (section 5.1). + +#. Virtual potential temperature scale :math:`\theta _{v\*}` (eq. ) + +#. Wind speed including the convective velocity, :math:`V_{a}` (eq. ) + +#. Monin-Obukhov length :math:`L` (eq. ). + +#. Roughness lengths (eq. , ). + +Once the four iterations for lake surface temperature have been yielded +a tentative solution :math:`T_{g} ^{{'} }` , several restrictions +are imposed in order to maintain consistency with the top lake model +layer temperature :math:`T_{T}` \ (Subin et al. 2012a). + +.. math:: + :label: ZEqnNum180534 + + \begin{array}{l} {{\rm 1)\; }T_{T} \le T_{f} T_{g} ^{{'} } >T_{m} \Rightarrow T_{g} =T_{T} ,} \\ {{\rm 3)\; }T_{m} >T_{g} ^{{'} } >T_{T} >T_{f} \Rightarrow T_{g} =T_{T} } \end{array} + +where :math:`T_{m}` \ is the temperature of maximum liquid water +density, 3.85\ :math:`{}^\circ`\ C (Hostetler and Bartlein 1990). The +first condition requires that, if there is any snow or ice present, the +surface temperature is restricted to be less than or equal to freezing. +The second and third conditions maintain convective stability in the top +lake layer. + +If eq. XXX is applied, the turbulent fluxes :math:`H_{g}` and +:math:`E_{g}` are re-evaluated. The emitted longwave radiation and +the momentum fluxes are re-evaluated in any case. The final ground heat +flux :math:`G` is calculated from the residual of the energy balance eq. +XXX in order to precisely conserve energy. XXX This ground heat flux +is taken as a prescribed flux boundary condition for the lake +temperature solution (section 9.5.3). An energy balance check is +included at each timestep to insure that eq. XXX is obeyed to within +0.1 W m\ :math:`{}^{-2}`. + +Lake Temperature +-------------------- + +Introduction +^^^^^^^^^^^^^^^^^^ + +The (optional-) snow, lake body (water and/or ice), soil, and bedrock +system is unified for the lake temperature solution. The governing +equation, similar to that for the snow-soil-bedrock system for vegetated +land units (Chapter 6), is + +.. math:: + :label: ZEqnNum239244 + + \tilde{c}_{v} \frac{\partial T}{\partial t} =\frac{\partial }{\partial z} \left(\tau \frac{\partial T}{\partial z} \right)-\frac{d\phi }{dz} + +where :math:`\tilde{c}_{v}` is the volumetric heat capacity (J +m\ :math:`{}^{-3}` K\ :math:`{}^{-1}`), :math:`t` is time (s), *T* is +the temperature (K), :math:`\tau` is the thermal conductivity (W +m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), and :math:`\phi` is the solar +radiation (W m\ :math:`{}^{-2}`) penetrating to depth *z* (m). The +system is discretized into *N* layers, where + +.. math:: + :label: 9.26) + + N=n_{sno} +N_{levlak} +N_{levgrnd} , + + :math:`n_{sno}` is the number of actively modeled snow layers at the +current timestep (section 7.2), and :math:`N_{levgrnd}` \ is as for +vegetated land units (Chapter 6). Energy is conserved as + +.. math:: + :label: ZEqnNum317718 + + \frac{d}{dt} \sum _{j=1}^{N}\left[\tilde{c}_{v,j} (t)\left(T_{j} -T_{f} \right)+L_{j} (t)\right] \Delta z_{j} =G+\left(1-\beta \right)\vec{S}_{g} + +where :math:`\tilde{c}_{v,j} (t)`\ is the volumetric heat capacity of +the *j*\ th layer (section 9.5.5), :math:`L_{j} (t)`\ is the latent heat +of fusion per unit volume of the *j*\ th layer (proportional to the mass +of liquid water present), and the right-hand side represents the net +influx of energy to the lake system. Note that +:math:`\tilde{c}_{v,j} (t)` can only change due to phase change (except +for changing snow layer mass, which, apart from energy required to melt +snow, represents an untracked energy flux in the land model, along with +advected energy associated with water flows in general), and this is +restricted to occur at :math:`T_{j} =T_{f}` \ in the snow-lake-soil +system, allowing eq. to be precisely enforced and justifying the +exclusion of :math:`c_{v,j}` from the time derivative in eq. . + +Overview of Changes from CLM4 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Thermal conductivities include additional eddy diffusivity, beyond the +Hostetler and Bartlein (1990) formulation, due to unresolved processes +(Fang and Stefan 1996; Subin et al. 2012a). Lake water is now allowed to +freeze by an arbitrary fraction for each layer, which releases latent +heat and changes thermal properties. Convective mixing occurs for all +lakes, even if frozen. Soil and bedrock are included beneath the lake. +The full snow model is used if the snow thickness exceeds a threshold; +if there are resolved snow layers, radiation transfer is predicted by +the snow-optics submodel (Chapter 3), and the remaining radiation +penetrating the bottom snow layer is absorbed in the top layer of lake +ice; conversely, if there are no snow layers, the solar radiation +penetrating the bottom lake layer is absorbed in the top soil layer. The +lakes have variable depth, and all physics is assumed valid for +arbitrary depth, except for a depth-dependent enhanced mixing (section +9.5.4). Finally, a previous sign error in the calculation of eddy +diffusivity (specifically, the Brunt-Väisälä frequency term; eq. ) was +corrected. + +Boundary Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The top boundary condition, imposed at the top modeled layer +:math:`i=j_{top}` , where :math:`j_{top} =-n_{sno} +1`, is the +downwards surface flux *G* defined by the energy flux residual during +the surface temperature solution (section 9.4.3). The bottom boundary +condition, imposed at :math:`i=N_{levlak} +N_{levgrnd}` , is zero flux. +The 2-m windspeed :math:`u_{2}` \ (m s\ :math:`{}^{-1}`) is used in the +calculation of eddy diffusivity: + +.. math:: + :label: ZEqnNum997977 + + u_{2} =\frac{u_{*} }{k} \ln \left(\frac{2}{z_{0m} } \right)\ge 0.1. + +where :math:`u_{*}` \ is the friction velocity calculated in section +9.4.3 and *k* is the von Karman constant (Table 2.6). + +Eddy Diffusivity and Thermal Conductivities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The total eddy diffusivity :math:`K_{W}` (:math:`\text{m}^{2}\,\text{s}^{-1}`) for liquid water in the lake body is given by (Subin et al. 2012a) + +.. math:: + :label: 9.29) + + K_{W} = m_{d} \left(\kappa _{e} +K_{ed} +\kappa _{m} \right) + +where :math:`\kappa _{e}` is due to wind-driven eddies (Hostetler and +Bartlein 1990), :math:`K_{ed}` is a modest enhanced diffusivity +intended to represent unresolved mixing processes (Fang and Stefan +1996), +:math:`\kappa _{m} =\frac{\lambda _{liq} }{c_{liq} \rho _{liq} }` \ is +the molecular diffusivity of water (given by the ratio of its thermal +conductivity (W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) to the product of +its heat capacity (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) and density +(kg m\ :math:`{}^{-3}`), values given in Table 2.6), and :math:`m_{d}` +(unitless) is a factor which increases the overall diffusivity for large +lakes, intended to represent 3-dimensional mixing processes such as +caused by horizontal temperature gradients. As currently implemented, + +.. math:: + :label: 9.30) + + m_{d} =\left\{\begin{array}{l} {1,\qquad d<25{\rm m}} \\ {10,\qquad d\ge 25{\rm m}} \end{array}\right\} + +where *d* is the lake depth. + +The wind-driven eddy diffusion coefficient :math:`\kappa _{e,\, i}` +( :math:`\text{m}^{2}\,\text{s}^{-1}` ) for layers :math:`1\le i\le N_{levlak}` is + +.. math:: + :label: 9.31) + + \kappa _{e,\, i} =\left\{\begin{array}{l} {\frac{kw^{*} z_{i} }{P_{0} \left(1+37Ri^{2} \right)} \exp \left(-k^{*} z_{i} \right)\qquad T_{g} >T_{f} } \\ {0\qquad T_{g} \le T_{f} } \end{array}\right\} + +where :math:`P_{0} =1` is the neutral value of the turbulent Prandtl +number, :math:`z_{i}` is the node depth (m), the surface friction +velocity (m s\ :math:`{}^{-1}`) is :math:`w^{*} =0.0012u_{2}` , and +:math:`k^{*}` varies with latitude :math:`\phi` as +:math:`k^{*} =6.6u_{2}^{-1.84} \sqrt{\left|\sin \phi \right|}` . For the +bottom layer, +:math:`\kappa _{e,\, N_{levlak} } =\kappa _{e,N_{levlak} -1\, }` . As in +Hostetler and Bartlein (1990), the 2-m wind speed :math:`u_{2}` (m +s\ :math:`{}^{-1}`) (eq. ) is used to evaluate :math:`w^{*}` and +:math:`k^{*}` rather than the 10-m wind used by Henderson-Sellers +(1985). + +The CityplaceRichardson number is + +.. math:: + :label: 9.32) + + R_{i} =\frac{-1+\sqrt{1+\frac{40N^{2} k^{2} z_{i}^{2} }{w^{*^{2} } \exp \left(-2k^{*} z_{i} \right)} } }{20} + +where + +.. math:: + :label: ZEqnNum230908 + + N^{2} =\frac{g}{\rho _{i} } \frac{\partial \rho }{\partial z} + +and :math:`g` is the acceleration due to gravity (m s\ :math:`{}^{-2}`) +(Table 2.6), :math:`\rho _{i}` is the density of water (kg +m\ :math:`{}^{-3}`), and :math:`\frac{\partial \rho }{\partial z}` is +approximated as +:math:`\frac{\rho _{i+1} -\rho _{i} }{z_{i+1} -z_{i} }` . Note that +because here, *z* is increasing downwards (unlike in Hostetler and +Bartlein (1990)), eq. contains no negative sign; this is a correction +from CLM4. The density of water is (Hostetler and Bartlein 1990) + +.. math:: + :label: 9.34) + + \rho _{i} =1000\left(1-1.9549\times 10^{-5} \left|T_{i} -277\right|^{1.68} \right). + +The enhanced diffusivity :math:`K_{ed}` is given by (Fang and Stefan +1996) + +.. math:: + :label: ZEqnNum809542 + + K_{ed} =1.04\times 10^{-8} \left(N^{2} \right)^{-0.43} ,N^{2} \ge 7.5\times 10^{-5} {\rm s}^{2} + +where :math:`N^{2}` \ is calculated as in eq. except for the minimum +value imposed in . + +The thermal conductivity for the liquid water portion of lake body layer +*i*, :math:`\tau _{liq,i}` (W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) is +given by + +.. math:: + :label: 9.36) + + \tau _{liq,i} =K_{W} c_{liq} \rho _{liq} . + +The thermal conductivity of the ice portion of lake body layer *i*, +:math:`\tau _{ice,eff}` \ (W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), is +constant among layers, and is given by + +.. math:: + :label: 9.37) + + \tau _{ice,eff} =\tau _{ice} \frac{\rho _{ice} }{\rho _{liq} } + +where :math:`\tau _{ice}` \ (Table 2.6) is the nominal thermal +conductivity of ice: :math:`\tau _{ice,eff}` \ is adjusted for the fact +that the nominal model layer thicknesses remain constant even while the +physical ice thickness exceeds the water thickness. + +The overall thermal conductivity :math:`\tau _{i}` for layer *i* with +ice mass-fraction :math:`I_{i}` is the harmonic mean of the liquid +and water fractions, assuming that they will be physically vertically +stacked, and is given by + +.. math:: + :label: 9.38) + + \tau _{i} =\frac{\tau _{ice,eff} \tau _{liq,i} }{\tau _{liq,i} I_{i} +\tau _{ice} \left(1-I_{i} \right)} . + +The thermal conductivity of snow, soil, and bedrock layers above and +below the lake, respectively, are computed identically to those for +vegetated land units (Chapter 6), except for the adjustment of thermal +conductivity for frost heave or excess ice (Subin et al., 2012a, +Supporting Information). + +Radiation Penetration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If there are no resolved snow layers, the surface absorption fraction :math:`\beta` is set according to the near-infrared fraction simulated +by the atmospheric model. This is apportioned to the surface energy +budget (section 9.4.2), and thus no additional radiation is absorbed in +the top :math:`z_{a}` (currently 0.6 m) of unfrozen lakes, for which +the light extinction coefficient :math:`\eta` ( :math:`\text{m}^{-1}` ) +varies between lake columns (eq. ). For frozen lakes +(:math:`T_{g} \le T_{f}` ), the remaining :math:`\left(1-\beta \right)\vec{S}_{g}` fraction of surface absorbed +radiation that is not apportioned to the surface energy budget is +absorbed in the top lake body layer. This is a simplification, as lake +ice is partially transparent. If there are resolved snow layers, then +the snow optics submodel (Chapter 3) is used to calculate the snow layer +absorption (except for the absorption predicted for the top layer by the +snow optics submodel, which is assigned to the surface energy budget), +with the remainder penetrating snow layers absorbed in the top lake body +ice layer. + +For unfrozen lakes, the solar radiation remaining at depth +:math:`z>z_{a}` in the lake body is given by + +.. math:: + :label: 9.39) + + \phi =\left(1-\beta \vec{S}_{g} \right)\exp \left\{-\eta \left(z-z_{a} \right)\right\} . + +For all lake body layers, the flux absorbed by the layer *i*, +:math:`\phi _{i}` , is + +.. math:: + :label: 9.40) + + \phi _{i} =\left(1-\beta \vec{S}_{g} \right)\left[\exp \left\{-\eta \left(z_{i} -\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}-\exp \left\{-\eta \left(z_{i} +\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}\right] . + +The argument of each exponent is constrained to be non-negative (so +:math:`\phi _{i}` = 0 for layers contained within :math:`\text{z}_{a}`). +The remaining flux exiting the bottom of layer :math:`i=N_{levlak}` is +absorbed in the top soil layer. + +The light extinction coefficient :math:`\eta` ( :math:`\text{m}^{-1}` ), if +not provided as external data, is a function of depth *d* (m) (Subin et +al. 2012a): + +.. math:: + :label: ZEqnNum284649 + + \eta =1.1925d^{-0.424} . + +Heat Capacities +^^^^^^^^^^^^^^^^^^^^^ + +The vertically-integrated heat capacity for each lake layer, +:math:`\text{c}_{v,i}\,\text{J\,m}^{-2}`) is +determined by the mass-weighted average over the heat capacities for the +water and ice fractions: + +.. math:: + :label: 9.42) + + c_{v,i} =\Delta z_{i} \rho _{liq} \left[c_{liq} \left(1-I_{i} \right)+c_{ice} I_{i} \right] . + +Note that the density of water is used for both ice and water fractions, +as the thickness of the layer is fixed. + +The total heat capacity :math:`c_{v,i}` for each soil, snow, and +bedrock layer (J m\ :math:`{}^{-2}`) is determined as for vegetated land +units (Chapter 6), as the sum of the heat capacities for the water, ice, +and mineral constituents. + +Crank-Nicholson Solution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The solution method for thermal diffusion is similar to that used for +soil (Chapter 6), except that the lake body layers are sandwiched +between the snow and soil layers (section 9.5.1), and radiation flux is +absorbed throughout the lake layers. Before solution, layer temperatures +:math:`T_{i}` (K), thermal conductivities :math:`\tau _{i}` (W +m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), heat capacities :math:`c_{v,i}` +(J m\ :math:`{}^{-2}`), and layer and interface depths from all +components are transformed into a uniform set of vectors with length +:math:`N=n_{sno} +N_{levlak} +N_{levgrnd}` and consistent units to +simplify the solution. Thermal conductivities at layer interfaces are +calculated as the harmonic mean of the conductivities of the neighboring +layers: + +.. math:: + :label: 9.43) + + \lambda _{i} =\frac{\tau _{i} \tau _{i+1} \left(z_{i+1} -z_{i} \right)}{\tau _{i} \left(z_{i+1} -\hat{z}_{i} \right)+\tau _{i+1} \left(\hat{z}_{i} -z_{i} \right)} , + +where :math:`\lambda _{i}` is the conductivity at the interface between +layer *i* and layer *i +* 1, :math:`z_{i}` is the depth of the node of +layer *i*, and :math:`\hat{z}_{i}` is the depth of the interface below +layer *i*. Care is taken at the boundaries between snow and lake and +between lake and soil. The governing equation is discretized for each +layer as + +.. math:: + :label: ZEqnNum991615 + + \frac{c_{v,i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=F_{i-1} -F_{i} +\phi _{i} + +where superscripts *n* + 1 and *n* denote values at the end and +beginning of the timestep :math:`\Delta t`, respectively, :math:`F_{i}` +(W m\ :math:`{}^{-2}`) is the downward heat flux at the bottom of layer +*i*, and :math:`\phi _{i}` is the solar radiation absorbed in layer +*i*. + +Eq. is solved using the semi-implicit Crank-Nicholson Method, resulting +in a tridiagonal system of equations: + +.. math:: + :label: 9.45) + + \begin{array}{l} {r_{i} =a_{i} T_{i-1}^{n+1} +b_{i} T_{i}^{n+1} +cT_{i+1}^{n+1} ,} \\ {a_{i} =-0.5\frac{\Delta t}{c_{v,i} } \frac{\partial F_{i-1} }{\partial T_{i-1}^{n} } ,} \\ {b_{i} =1+0.5\frac{\Delta t}{c_{v,i} } \left(\frac{\partial F_{i-1} }{\partial T_{i-1}^{n} } +\frac{\partial F_{i} }{\partial T_{i}^{n} } \right),} \\ {c_{i} =-0.5\frac{\Delta t}{c_{v,i} } \frac{\partial F_{i} }{\partial T_{i}^{n} } ,} \\ {r_{i} =T_{i}^{n} +0.5\frac{\Delta t}{c_{v,i} } \left(F_{i-1} -F_{i} \right)+\frac{\Delta t}{c_{v,i} } \phi _{i} .} \end{array} + +The fluxes :math:`F_{i}` are defined as follows: for the top layer, +:math:`F_{j_{top} -1} =2G;a_{j_{top} } =0`, where *G* is defined as in +section 9.4.3 (the factor of 2 merely cancels out the Crank-Nicholson +0.5 in the equation for :math:`r_{j_{top} }` ). For the bottom layer, +:math:`F_{N_{levlak} +N_{levgrnd} } =0`. For all other layers: + +.. math:: + :label: 9.46) + + F_{i} =\lambda _{i} \frac{T_{i} ^{n} -T_{i+1}^{n} }{z_{n+1} -z_{n} } . + +Phase Change +^^^^^^^^^^^^^^^^^^ + +Phase change in the lake, snow, and soil is done similarly to that done +for the soil and snow for vegetated land units (Chapter 6), except +without the allowance for freezing point depression in soil underlying +lakes. After the heat diffusion is calculated, phase change occurs in a +given layer if the temperature is below freezing and liquid water +remains, or if the temperature is above freezing and ice remains. + +If melting occurs, the available energy for melting, :math:`Q_{avail}` +(J m\ :math:`{}^{-2}`), is computed as + +.. math:: + :label: ZEqnNum598199 + + Q_{avail} =\left(T_{i} -T_{f} \right)c_{v,i} + +where :math:`T_{i}` is the temperature of the layer after thermal +diffusion (section 9.5.7), and :math:`c_{v,i}` \ is as calculated in +section 9.5.6. The mass of melt in the layer *M* (kg m\ :math:`{}^{-2}`) +is given by + +.. math:: + :label: 9.48) + + M=\min \left\{M_{ice} ,\frac{Q_{avail} }{H_{fus} } \right\} + +where :math:`H_{fus}` (J kg\ :math:`{}^{-1}`) is the latent heat of +fusion of water (Table 2.6), and :math:`M_{ice}` is the mass of ice in +the layer: :math:`I_{i} \rho _{liq} \Delta z_{i}` for a lake body +layer, or simply the soil / snow ice content state variable +(:math:`w_{ice}` ) for a soil / snow layer. The heat remainder, +:math:`Q_{rem}` \ is given by + +.. math:: + :label: ZEqnNum889387 + + Q_{rem} =Q_{avail} -MH_{fus} . + +Finally, the mass of ice in the layer :math:`M_{ice}` is adjusted +downwards by :math:`M`, and the temperature :math:`T_{i}` of the +layer is adjusted to + +.. math:: + :label: ZEqnNum926437 + + T_{i} =T_{f} +\frac{Q_{rem} }{c'_{v,i} } + +where :math:`c'_{v,i} =c_{v,i} +M\left(c_{liq} -c_{ice} \right)`. + +If freezing occurs, :math:`Q_{avail}` is again given by but will be +negative. The melt :math:`M`, also negative, is given by + +.. math:: + :label: 9.51) + + M=\max \left\{-M_{liq} ,\frac{Q_{avail} }{H_{fus} } \right\} + +where :math:`M_{liq}` is the mass of water in the layer: +:math:`\left(1-I_{i} \right)\rho _{liq} \Delta z_{i}` for a lake body +layer, or the soil / snow water content state variable +(:math:`w_{liq}` ). The heat remainder :math:`Q_{rem}` is given by eq. +and will be negative or zero. Finally, :math:`M_{liq}` is adjusted +downwards by :math:`-M` and the temperature is reset according to eq. . + +In the presence of nonzero snow water :math:`W_{sno}` without resolved +snow layers over + +an unfrozen top lake layer, the available energy in the top lake layer +:math:`\left(T_{1} -T_{f} \right)c_{v,1}` is used to melt the snow. +Similar to above, :math:`W_{sno}` is either completely melted and the +remainder of heat returned to the top lake layer, or the available heat +is exhausted and the top lake layer is set to freezing. The snow +thickness is adjusted downwards in proportion to the amount of melt, +maintaining constant density. + +Convection +^^^^^^^^^^^^^^^^ + +Convective mixing is based on Hostetler et al.’s (1993, 1994) coupled +lake-atmosphere model, adjusting the lake temperature after diffusion +and phase change to maintain a stable density profile. Unfrozen lakes +overturn when :math:`\rho _{i} >\rho _{i+1}` , in which case the layer +thickness weighted average temperature for layers 1 to :math:`i+1` is +applied to layers 1 to :math:`i+1` and the densities are updated. This +scheme is applied iteratively to layers :math:`1\le i 0`, then :math:`T_{froz} =T_{f}` , and :math:`T_{unfr}` +is given by + +.. math:: + :label: 9.54) + + T_{unfr} =\frac{Q}{\rho _{liq} Z_{i+1} \left[\left(1-I_{av} \right)c_{liq} \right]} +T_{f} . + +If :math:`Q < 0`, then :math:`T_{unfr} =T_{f}` , and :math:`T_{froz}` +is given by + +.. math:: + :label: 9.55) + + T_{froz} =\frac{Q}{\rho _{liq} Z_{i+1} \left[I_{av} c_{ice} \right]} +T_{f} . + +The ice is lumped together at the top. For each lake layer *j* from 1 +to *i* + 1, the ice fraction and temperature are set as follows, where +:math:`Z_{j} =\sum _{m=1}^{j}\Delta z_{m}` : + +#. If :math:`Z_{j} \le Z_{i+1} I_{av}` , then :math:`I_{j} =1` and + :math:`T_{j} =T_{froz}` . + +#. Otherwise, if :math:`Z_{j-1} 1000{\rm m}`, +in which case additional precipitation and frost deposition is added to +:math:`q_{snwcp,\, ice}` . + +If there are resolved snow layers, the generalized “evaporation†+:math:`E_{g}` (i.e., evaporation, dew, frost, and sublimation) is +treated as over other land units, except that the allowed evaporation +from the ground is unlimited (though the top snow layer cannot lose more +water mass than it contains). If there are no resolved snow layers but +:math:`W_{sno} >0` and :math:`E_{g} >0`, sublimation +:math:`q_{sub,sno}` \ (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) will be +given by + +.. math:: + :label: 9.60) + + q_{sub,sno} =\min \left\{E_{g} ,\frac{W_{sno} }{\Delta t} \right\} . + +If :math:`E_{g} <0,T_{g} \le T_{f}` , and there are no resolved snow +layers or the top snow layer is not unfrozen, then the rate of frost +production :math:`q_{frost} =\left|E_{g} \right|`. If :math:`E_{g} <0` +but the top snow layer has completely thawed during the Phase Change +step of the Lake Temperature solution (section 9.5.8), then frost (or +dew) is not allowed to accumulate (:math:`q_{frost} =0`), to insure that +the layer is eliminated by the Snow Hydrology (section 7.2) code. (If +:math:`T_{g} >T_{f}` , then no snow is present (section 9.4.3), and +evaporation or dew deposition is balanced by :math:`q_{rgwl}` .) The +snowpack is updated for frost and sublimation: + +.. math:: + :label: 9.61) + + W_{sno} =W_{sno} +\Delta t\left(q_{frost} -q_{sub,sno} \right) . + +If there are resolved snow layers, then this update occurs using the +Snow Hydrology submodel (section 7.2). Otherwise, the snow ice mass is +updated directly, and :math:`z_{sno}` is adjusted by the same +proportion as the snow ice (i.e., maintaining the same density), unless +there was no snow before adding the frost, in which case the density is +assumed to be 250 kg m\ :math:`{}^{-3}`. + +Soil Hydrology +^^^^^^^^^^^^^^^^^^^^ + +The combined water and ice soil volume fraction in a soil layer +:math:`\theta _{i}` is given by + +.. math:: + :label: 9.62) + + \theta _{i} =\frac{1}{\Delta z_{i} } \left(\frac{w_{ice,i} }{\rho _{ice} } +\frac{w_{liq,i} }{\rho _{liq} } \right) . + +If :math:`\theta _{i} <\theta _{sat,i}` , the pore volume fraction at +saturation (as may occur when ice melts), then the liquid water mass is +adjusted to + +.. math:: + :label: 9.63) + + w_{liq,i} =\left(\theta _{sat,i} \Delta z_{i} -\frac{w_{ice,i} }{\rho _{ice} } \right)\rho _{liq} . + +Otherwise, if excess ice is melting and +:math:`w_{liq,i} >\theta _{sat,i} \rho _{liq} \Delta z_{i}` , then the +water in the layer is reset to + +.. math:: + :label: 9.64) + + w_{liq,i} = \theta _{sat,i} \rho _{liq} \Delta z_{i} + +This allows excess ice to be initialized (and begin to be lost only +after the pore ice is melted, which is realistic if the excess ice is +found in heterogeneous chunks) but irreversibly lost when melt occurs. + +Modifications to Snow Layer Logic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A thickness difference :math:`z_{lsa} =s_{\min } -\tilde{s}_{\min }` +adjusts the minimum resolved snow layer thickness for lake columns as +compared to non-lake columns. The value of :math:`z_{lsa}` is chosen to +satisfy the CFL condition for the model timestep. By default, +:math:`\tilde{s}_{\min }` \ = 1 cm and :math:`s_{\min }` \ = 4 cm. See +Subin et al. (2012a; including Supporting Information) for further +discussion. + +The rules for combining and sub-dividing snow layers (section 7.2.7) are +adjusted for lakes to maintain minimum thicknesses of :math:`s_{\min }` +and to increase all target layer thicknesses by :math:`z_{lsa}` . The +rules for combining layers are modified by simply increasing layer +thickness thresholds by :math:`z_{lsa}` . The rules for dividing snow +layers are contained in a separate subroutine that is modified for +lakes, and is a function of the number of layers and the layer +thicknesses. There are two types of operations: (a) subdividing layers +in half, and (b) shifting some volume from higher layers to lower layers +(without increasing the layer number). For subdivisions of type (a), the +thickness thresholds triggering subdivision are increased by +:math:`2z_{lsa}` for lakes. For shifts of type (b), the thickness +thresholds triggering the shifts are increased by :math:`z_{lsa}` . At +the end of the modified subroutine, a snow ice and liquid balance check +are performed. + +In rare instances, resolved snow layers may be present over an unfrozen +top lake body layer. In this case, the snow layers may be eliminated if +enough heat is present in the top layer to melt the snow: see Subin et +al. (2012a, Supporting Information). From 13fbf29398b215ebbaab54b3e87ce7f3f9bcf6ab Mon Sep 17 00:00:00 2001 From: mvertens Date: Mon, 27 Mar 2017 11:30:21 -0600 Subject: [PATCH 003/255] first pass at complete tech note --- doc/source/conf.py | 2 +- doc/source/index.rst | 1 + .../CLM45_Tech_Note_Chpt_1_Introduction.rst | 432 ++++++------------ .../CLM45_Tech_Note_Chpt_11_RTM.rst | 20 +- .../CLM45_Tech_Note_Chpt_12_Urban.rst | 6 +- ...Note_Chpt_13_CN_Allocation_Respiration.rst | 40 +- ...Tech_Note_Chpt_14_Vegetation_Phenology.rst | 350 +++++++------- .../CLM45_Tech_Note_Chpt_15_Decomposition.rst | 353 +++++++------- ...h_Note_Chpt_16_External_Nitrogen_Cycle.rst | 183 ++++---- ...LM45_Tech_Note_Chpt_17_Plant_Mortality.rst | 186 ++++---- .../CLM45_Tech_Note_Chpt_18_Fire.rst | 287 ++++++------ .../CLM45_Tech_Note_Chpt_19_Methane.rst | 323 ++++++------- .../CLM45_Tech_Note_Chpt_2_Ecosystem.rst | 277 ++++++----- ...LM45_Tech_Note_Chpt_20_Crop_Irrigation.rst | 294 ++++++------ ..._Tech_Note_Chpt_21_Transient_Landcover.rst | 25 +- .../CLM45_Tech_Note_Chpt_22_DGVM.rst | 12 +- .../CLM45_Tech_Note_Chpt_23_BVOCs.rst | 19 +- .../CLM45_Tech_Note_Chpt_24_Dust.rst | 83 ++-- .../CLM45_Tech_Note_Chpt_25_Isotopes.rst | 163 +++---- .../CLM45_Tech_Note_Chpt_26_Offline.rst | 54 ++- .../CLM45_Tech_Note_Chpt_27_References.rst | 14 +- ...CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst | 61 +-- ...LM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst | 14 +- .../CLM45_Tech_Note_Chpt_5_Fluxes.rst | 168 +++---- ...ech_Note_Chpt_6_Soil_Snow_Temperatures.rst | 102 ++--- .../CLM45_Tech_Note_Chpt_7_Hydrology.rst | 146 +++--- .../CLM45_Tech_Note_Chpt_8_Photosynthesis.rst | 202 ++++---- .../CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst | 149 +++--- doc/source/tech_note/index.rst | 43 ++ .../overview/scientific_validation.rst | 2 +- 30 files changed, 1836 insertions(+), 2175 deletions(-) create mode 100644 doc/source/tech_note/index.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index bdf2be569c..dc9a7b7ea8 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -34,7 +34,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.mathjax', + 'sphinx.ext.imgmath', 'sphinx.ext.githubpages'] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/index.rst b/doc/source/index.rst index a5ec1eb158..cc7ec3c27c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,6 +17,7 @@ Table of contents :maxdepth: 1 users_guide/index.rst + tech_note/index.rst Indices and tables ================== diff --git a/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst b/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst index 1bcd54fca7..bb9b012bdc 100644 --- a/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst +++ b/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst @@ -1,17 +1,9 @@ -.. math:: 188 - **NCAR/TN-503+STR** **NCAR Technical Note** -**\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** - -**** - **July 2013** -**** - **Technical Description of version 4.5 of the Community Land Model (CLM)** @@ -19,16 +11,12 @@ **Keith W. Oleson, David M. Lawrence** -**** - ***Lead Authors*** **Gordon B. Bonan, Beth Drewniak, Maoyi Huang, Charles D. Koven, Samuel Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, Peter E. Thornton** -**** - ***Contributing Authors*** **Anil Bozbiyik, Rosie Fisher, Colette L. Heald, Erik Kluzek, @@ -36,16 +24,9 @@ Jean-Francois Lamarque, Peter J. Lawrence, L. Ruby Leung, William Lipscomb, Stefan Muszala, Daniel M. Ricciuto, William Sacks, Ying Sun, Jinyun Tang, Zong-Liang Yang** -**** - -**** - -**** - **NCAR Earth System Laboratory** -**Climate and Global Dynamics -Division\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** +**Climate and Global Dynamics Division** **NATIONAL CENTER FOR ATMOSPHERIC RESEARCH** @@ -57,13 +38,9 @@ Division\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ **ISSN Electronic Edition 2153-2400** -**** - **NCAR TECHNICAL NOTES** -http://library.ucar.edu/research/publish-technote\ **** - -**** +http://library.ucar.edu/research/publish-technote The Technical Notes series provides an outlet for a variety of NCAR Manuscripts that contribute in specialized ways to the body of @@ -75,35 +52,23 @@ include: **EDD – Engineering, Design, or Development Reports** -Equipment descriptions, test results, instrumentation, - -and operating and maintenance manuals. +Equipment descriptions, test results, instrumentation, and operating and maintenance manuals. **IA – Instructional Aids** -** Instruction manuals, bibliographies, film supplements, - -and other research or instructional aids. +Instruction manuals, bibliographies, film supplements, and other research or instructional aids. **PPR – Program Progress Reports** -** Field program reports, interim and working reports, - -survey reports, and plans for experiments. +Field program reports, interim and working reports, survey reports, and plans for experiments. **PROC – Proceedings** -** Documentation or symposia, colloquia, conferences, - -workshops, and lectures. (Distribution maybe limited to - -attendees). +Documentation or symposia, colloquia, conferences, workshops, and lectures. (Distribution maybe limited to attendees). **STR – Scientific and Technical Reports** -Data compilations, theoretical and numerical - -investigations, and experimental results. +Data compilations, theoretical and numerical investigations, and experimental results. The National Center for Atmospheric Research (NCAR) is operated by the nonprofit University Corporation for Atmospheric Research (UCAR) under @@ -113,61 +78,35 @@ are those of the author(s) and do not necessarily reflect the views of the National Science Foundation. National Center for Atmospheric Research - -P. O. Box 3000 - -Boulder, Colorado 80307-300 - -**** - -ii +P. O. Box 3000, Boulder, Colorado 80307-300 **NCAR/TN-503+STR** **NCAR Technical Note** -**\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** - -**** - **July 2013** -**** +**Technical Description of version 4.5 of the Community Land Model (CLM)** -**Technical Description of version 4.5 of the Community Land Model -(CLM)** - -***Coordinating Lead Authors*** +**Coordinating Lead Authors** **Keith W. Oleson, David M. Lawrence** -**** - -***Lead Authors*** +**Lead Authors** **Gordon B. Bonan, Beth Drewniak, Maoyi Huang, Charles D. Koven, Samuel -Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, -Peter E. Thornton** - -**** +Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, Peter E. Thornton** -***Contributing Authors*** +**Contributing Authors** **Anil Bozbiyik, Rosie Fisher, Colette L. Heald, Erik Kluzek, Jean-Francois Lamarque, Peter J. Lawrence, L. Ruby Leung, William Lipscomb, Stefan Muszala, Daniel M. Ricciuto, William Sacks, Ying Sun, Jinyun Tang, Zong-Liang Yang** -**** - -**** - -**** - **NCAR Earth System Laboratory** -**Climate and Global Dynamics -Division\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_** +**Climate and Global Dynamics Division** **NATIONAL CENTER FOR ATMOSPHERIC RESEARCH** @@ -179,219 +118,127 @@ Division\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ **ISSN Electronic Edition 2153-2400** -xi - -**TABLE OF CONTENTS** - -**** - -**1. Introduction 11.1 Model History 11.1.1 Inception of CLM 11.1.2 CLM2 -31.1.3 CLM3 51.1.4 CLM3.5 61.1.5 CLM4 71.1.6 CLM4.5 81.2 Biogeophysical -and Biogeochemical Processes 112. Surface Characterization and Model -Input Requirements 142.1 Surface Characterization 142.1.1 Surface -Heterogeneity and Data Structure 142.1.2 Vegetation Composition 172.1.3 -Vegetation Structure 192.1.4 Phenology and vegetation burial by snow -212.2 Model Input Requirements 212.2.1 Atmospheric Coupling 212.2.2 -Initialization 272.2.3 Surface Data 282.2.4 Adjustable Parameters and -Physical Constants 353. Surface Albedos 373.1 Canopy Radiative Transfer -373.2 Ground Albedos 463.2.1 Snow Albedo 483.2.2 Snowpack Optical -Properties 523.2.3 Snow Aging 563.3 Solar Zenith Angle 594. Radiative -Fluxes 634.1 Solar Fluxes 634.2 Longwave Fluxes 675. Momentum, Sensible -Heat, and Latent Heat Fluxes 715.1 Monin-Obukhov Similarity Theory 735.2 -Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces 825.3 -Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces -885.3.1 Theory 885.3.2 Numerical Implementation 1025.4 Update of Ground -Sensible and Latent Heat Fluxes 1075.5 Saturation Vapor Pressure 1106. -Soil and Snow Temperatures 1136.1 Numerical Solution 1146.2 Phase Change -1256.2.1 Soil and Snow Layers 1256.2.2 Surface Water 1296.3 Soil and -Snow Thermal Properties 1307. Hydrology 1347.1 Canopy Water 1357.2 Snow -1377.2.1 Snow Covered Area Fraction 1397.2.2 Ice Content 1407.2.3 Water -Content 1427.2.4 Black and organic carbon and mineral dust within snow -1437.2.5 Initialization of snow layer 1467.2.6 Snow Compaction 1467.2.7 -Snow Layer Combination and Subdivision 1497.2.7.1 Combination 1497.2.7.2 -Subdivision 1527.3 Surface Runoff, Surface Water Storage, and -Infiltration 1537.3.1 Surface Runoff 1537.3.2 Surface Water Storage -1557.3.3 Infiltration 1567.4 Soil Water 1587.4.1 Hydraulic Properties -1607.4.2 Numerical Solution 1637.4.2.1 Equilibrium soil matric potential -and volumetric moisture 1697.4.2.2 Equation set for layer i=1 1717.4.2.3 -Equation set for layers i=2,…,N\ :sub:`levsoi` -1 1717.4.2.4 Equation -set for layers i=N\ :sub:`levsoi` ,…N\ :sub:`levsoi` +1 1727.5 Frozen -Soils and Perched Water Table 1747.6 Groundwater-Soil Water Interactions -1757.7 Runoff from glaciers and snow-capped surfaces 1787.8 The Variable -Infiltration Capacity parameterizations as a hydrologic option 1798. -Stomatal Resistance and Photosynthesis 1838.1 Stomatal resistance 1838.2 -Photosynthesis 1868.3 Vcmax25 and canopy scaling 1918.4 Soil water -stress 1938.5 Numerical implementation 1979. Lake Model 2009.1 -Discretization 2019.2 External Data 2029.3 Surface Albedo 2029.4 Surface -Fluxes and Surface Temperature 2039.4.1 Overview of Changes from CLM4 -2039.4.2 Surface Properties 2039.4.3 Surface Flux Solution 2059.5 Lake -Temperature 2119.5.1 Introduction 2119.5.2 Overview of Changes from CLM4 -2129.5.3 Boundary Conditions 2139.5.4 Eddy Diffusivity and Thermal -Conductivities 2139.5.5 Radiation Penetration 2169.5.6 Heat Capacities -2179.5.7 Crank-Nicholson Solution 2179.5.8 Phase Change 2199.5.9 -Convection 2209.5.10 Energy Conservation 2239.6 Lake Hydrology 2239.6.1 -Overview 2239.6.2 Water Balance 2249.6.3 Precipitation, Evaporation, and -Runoff 2259.6.4 Soil Hydrology 2269.6.5 Modifications to Snow Layer -Logic 22710. Glaciers 22910.1 Overview 22910.2 Multiple elevation class -scheme 23110.3 Computation of the surface mass balance 23211. River -Transport Model (RTM) 23512. Urban Model (CLMU) 23913. Carbon and -Nitrogen Pools, Allocation, and Respiration 24413.1 Introduction 24413.2 -Carbon Allocation for Maintenance Respiration Costs 24613.3 Carbon and -Nitrogen Stoichiometry of New Growth 24813.4 Deployment of -retranslocated nitrogen 25213.5 Plant nitrogen uptake from soil mineral -nitrogen pool 25313.6 Final carbon and nitrogen allocation 25313.7 -Autotrophic Respiration 25613.7.1 Maintenance Respiration 25613.7.2 -Growth Respiration 25714. Vegetation Phenology 25914.1 General Phenology -Flux Parameterization 25914.1.1 Onset Periods 26014.1.2 Offset Periods -26214.1.3 Background Onset Growth 26414.1.4 Background Litterfall -26514.1.5 Livewood Turnover 26614.2 Evergreen Phenology 26714.3 -Seasonal-Deciduous Phenology 26814.3.1 Seasonal-Deciduous Onset Trigger -26814.3.2 Seasonal-Deciduous Offset Trigger 27114.4 Stress-Deciduous -Phenology 27114.4.1 Stress-Deciduous Onset Triggers 27114.4.2 -Stress-Deciduous Offset Triggers 27314.4.3 Stress-Deciduous: Long -Growing Season 27414.5 Litterfall Fluxes Merged to the Column Level -27615. Decomposition 27815.1 CLM-CN Pool Structure, Rate Constants and -Parameters 28115.2 Century-based Pool Structure, Rate Constants and -Parameters 28515.3 Environmental modifiers on decomposition rate 28615.4 -N-limitation of Decomposition Fluxes 28915.5 N Competition between plant -uptake and soil immobilization fluxes 29215.6 Final Decomposition Fluxes -29315.7 Vertical Distribution and Transport of Decomposing C and N pools -29515.8 Model Equilibration 29616. External Nitrogen Cycle 29816.1 -Atmospheric Nitrogen Deposition 29816.2 Biological Nitrogen Fixation -29916.3 Nitrification and Denitrification Losses of Nitrogen 30116.3.1 -CLM-CN formulation 30116.3.2 Century-based formulation 30416.4 Leaching -Losses of Nitrogen 30516.5 Losses of Nitrogen Due to Fire 30717. Plant -Mortality 30817.1 Mortality Fluxes Leaving Vegetation Pools 30817.2 -Mortality Fluxes Merged to the Column Level 31118. Fire 31618.1 Non-peat -fires outside cropland and tropical closed forest 31618.1.1 Fire counts -31618.1.2 Average spread area of a fire 32018.1.3 Fire impact 32318.2 -Agricultural fires 32518.3 Deforestation fires 32618.4 Peat fires 32919. -Methane Model 33219.1 Methane Model Structure and Flow 33219.2 Governing -Mass-Balance Relationship 33319.3 CH4 Production 33419.4 Ebullition -33819.5 Aerenchyma Transport 33819.6 CH4 Oxidation 34019.7 Reactive -Transport Solution 34019.7.1 Competition for CH4 and O2 34119.7.2 CH4 -and O2 Source Terms 34119.7.3 Aqueous and Gaseous Diffusion 34219.7.4 -Boundary Conditions 34319.7.5 Crank-Nicholson Solution 34419.7.6 -Interface between water table and unsaturated zone 34519.8 Inundated -Fraction Prediction 34619.9 Seasonal Inundation 34720. Crops and -Irrigation 34820.1 Summary of CLM4.5 updates relative to the CLM4.0 -34820.2 The crop model 34820.2.1 Introduction 34820.2.2 Crop plant -functional types 34920.2.3 Phenology 35020.2.3.1 Planting 35120.2.3.2 -Leaf emergence 35220.2.3.3 Grain fill 35320.2.3.4 Harvest 35320.2.4 -Allocation 35320.2.4.1 Leaf emergence to grain fill 35420.2.4.2 Grain -fill to harvest 35420.2.5 General comments 35520.3 The irrigation model -36020.4 The details about what is new in CLM4.5 36120.4.1 Interactive -irrigation for corn, temperate cereals, and soybean 36120.4.2 -Interactive fertilization 36320.4.3 Biological nitrogen fixation for -soybeans 36420.4.4 Modified C:N ratios for crops 36520.4.5 Nitrogen -retranslocation for crops 36520.4.6 Separate reproductive pool 36721. -Transient Landcover Change 36921.1 Annual Transient Land Cover Data and -Time Interpolation 36921.2 Mass and Energy Conservation 37121.3 Annual -Transient Land Cover Dataset Development 37221.3.1 UNH Transient Land -Use and Land Cover Change Dataset 37221.3.2 Representing Land Use and -Land Cover Change in CLM 37421.3.3 Present Day PFT Dataset 37521.3.4 -Potential PFT Distribution 37621.3.5 Transient Land Cover Change Dataset -37721.3.6 Forest Harvest Dataset Changes 37822. Dynamic Global -Vegetation Model 38122.1 Establishment and survival 38222.2 Light -competition 38322.3 CN processes modified for the CNDV coupling 38323. -Biogenic Volatile Organic Compounds (BVOCs) 38624. Dust Model 38825. -Carbon Isotopes 39325.1 General Form for Calculating 13C and 14C Flux -39325.2 Isotope Symbols, Units, and Reference Standards 39425.3 Carbon -Isotope Discrimination During Photosynthesis 39625.4 14C radioactive -decay and historical atmospheric 14C concentrations 39826. Offline Mode -40027. References 405** - **LIST OF FIGURES** -Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes -simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). -13Figure 2.1. Configuration of the CLM subgrid hierarchy. 15Figure 4.1. -Schematic diagram of (a) direct beam radiation, (b) diffuse solar -radiation, and (c) longwave radiation absorbed, transmitted, and -reflected by vegetation and ground. 64Figure 5.1. Schematic diagram of -sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated -surfaces. 91Figure 5.2. Schematic diagram of water vapor fluxes for (a) -non-vegetated surfaces and (b) vegetated surfaces. 92Figure 6.1. -Schematic diagram of numerical scheme used to solve for soil -temperature. 119Figure 7.1. Hydrologic processes represented in CLM. -135Figure 7.2. Example of three layer snow pack (snl=-3). 137Figure 7.3. -Schematic diagram of numerical scheme used to solve for soil water -fluxes. 165Figure 12.1. Schematic representation of the urban land unit. -242Figure 12.2. Schematic of urban and atmospheric model coupling. -243Figure 13.1. Vegetation fluxes and pools. 245Figure 13.2: Carbon and -nitrogen pools. 246Figure 14.1. Example of annual phenology cycle for -seasonal deciduous. 260Figure 14.2. Example fluxes and pools sizes for -an onset growth period of 15 days, with initial transfer pool size of -100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool -(e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its -associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). -262Figure 14.3. Example fluxes and pool sizes for an offset (litterfall) -period of 15 days, with initial display pool size of 100 gC m-2 and a -timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon -content of display pool and litter pool through the litterfall period, -ignoring the losses from litter pool due to decomposition during this -period. 264Figure 15.1. Schematic of decomposition model in CLM. -279Figure 15.2. Pool structure, transitions, respired fractions (numbers -at end of arrows), and turnover times (numbers in boxes) for the 2 -alternate soil decomposition models included in CLM. 281Figure 16.1. -Biological nitrogen fixation as a function of annual net primary -production. 300Figure 19.1. Schematic representation of biological and -physical processes integrated in CLM that affect the net CH4 surface -flux. (left) Fully inundated portion of a CLM gridcell and (right) -variably saturated portion of a gridcell. 334Figure 21.1. Schematic of -land cover change impacts on CLM carbon pools and fluxes. 379Figure -21.2. Schematic of translation of annual UNH land units to CLM4 plant -functional types. 380Figure 25.1. Atmospheric -:math:`\mathrm{\Delta}`\ 14C used to drive 14C model over the historical -period. 399\ **** +- Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). + +- Figure 2.1. Configuration of the CLM subgrid hierarchy. + +- Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. + +- Figure 5.1. Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. + +- Figure 5.2. Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. + +- Figure 6.1. Schematic diagram of numerical scheme used to solve for soil temperature. + +- Figure 7.1. Hydrologic processes represented in CLM. + +- Figure 7.2. Example of three layer snow pack (snl=-3). + +- Figure 7.3. Schematic diagram of numerical scheme used to solve for soil water fluxes. + +- Figure 12.1. Schematic representation of the urban land unit. + +- Figure 12.2. Schematic of urban and atmospheric model coupling. + +- Figure 13.1. Vegetation fluxes and pools. + +- Figure 13.2: Carbon and nitrogen pools. + +- Figure 14.1. Example of annual phenology cycle for seasonal deciduous. + +- Figure 14.2. Example fluxes and pools sizes for an onset growth period of 15 days, with initial transfer pool size of 100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool (e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). + +- Figure 14.3. Example fluxes and pool sizes for an offset (litterfall) period of 15 days, with initial display pool size of 100 gC m-2 and a timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon content of display pool and litter pool through the litterfall period, ignoring the losses from litter pool due to decomposition during this period. + +- Figure 15.1. Schematic of decomposition model in CLM. + +- Figure 15.2. Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. + +- Figure 16.1. Biological nitrogen fixation as a function of annual net primary production. 300Figure 19.1. Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. + +- Figure 21.1. Schematic of land cover change impacts on CLM carbon pools and fluxes. + +- Figure 21.2. Schematic of translation of annual UNH land units to CLM4 plant functional types. + +- Figure 25.1. Atmospheric :math:`\mathrm{\Delta}` 14C used to drive 14C model over the historical period. **LIST OF TABLES** -Table 2.1. Plant functional types 18Table 2.2. Prescribed plant -functional type heights 20Table 2.3. Atmospheric input to land model -23Table 2.4. Land model output to atmospheric model 26Table 2.5. Surface -data required for CLM4.5 and their base spatial resolution 29Table 2.6. -Physical constants 36Table 3.1. Plant functional type optical properties -44Table 3.2. Intercepted snow optical properties 46Table 3.3. Dry and -saturated soil albedos 48Table 3.4. Spectral bands and weights used for -snow radiative transfer 51Table 3.5. Single-scatter albedo values used -for snowpack impurities and ice 54Table 3.6. Mass extinction values (m2 -kg-1) used for snowpack impurities and ice. 55Table 3.7. Asymmetry -scattering parameters used for snowpack impurities and ice. 56Table 3.8. -Orbital parameters 62Table 5.1. Plant functional type aerodynamic -parameters 101Table 5.2. Coefficients for e\ :sub:`sat`\ :sup:`T` -111Table 5.3. Coefficients for 112Table 6.1. Soil layer structure. -115Table 7.1. Meltwater scavenging efficiency for particles within snow -146Table 7.2. Minimum and maximum thickness of snow layers (m) 152Table -8.1. Plant functional type (PFT) photosynthetic parameters. 185Table -8.2. Temperature dependence parameters for C3 photosynthesis. 190Table -8.3. Plant functional type root distribution parameters. 196Table 13.1. -Allocation and carbon:nitrogen ratio parameters 250Table 15.1. -Decomposition rate constants for litter and SOM pools, C:N ratios, and -acceleration parameters (see section 15.8 for explanation) for the -CLM-CN decomposition pool structure. 283Table 15.2. Respiration -fractions for litter and SOM pools 284Table 15.3. Respiration fractions -for litter and SOM pools for Century-based structure 285Table 15.4. -Turnover times, C:N ratios, and acceleration parameters (see section -15.8 for explanation) for the Century-based decomposition cascade. -286Table 18.1. PFT-specific combustion completeness and fire mortality -factors. 331Table 19.1. Parameter descriptions and sensitivity analysis -ranges applied in the methane model. 337Table 19.2. Temperature -dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. -342Table 20.1. Crop plant functional types (pfts) in CLM4.5CNcrop and -their parameters relating to phenology and morphology. Numbers in the -first column correspond to the list of pfts in Table 2.1. 357Table 20.2. -Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. -Numbers in the first column correspond to the list of pfts in Table 2.1. -359Table 20.3. Pre- and post-grain fill C:N ratios for crop leaf, stem, -fine root, and reproductive pools. 367Table 22.1. Plant functional type -(PFT) biogeography rules with respect to climate. 385Table 24.1. Mass -fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric -standard deviation :sub:`g, i` , per dust source mode i 392Table 24.2. -Minimum and maximum particle diameters in each dust transport bin j -392\ **** - -ACKNOWLEDGEMENTS +- Table 2.1. Plant functional types + +- Table 2.2. Prescribed plant functional type heights + +- Table 2.3. Atmospheric input to land model + +- Table 2.4. Land model output to atmospheric model + +- Table 2.5. Surface data required for CLM4.5 and their base spatial resolution + +- Table 2.6. Physical constants + +- Table 3.1. Plant functional type optical properties + +- Table 3.2. Intercepted snow optical properties + +- Table 3.3. Dry and saturated soil albedos + +- Table 3.4. Spectral bands and weights used for snow radiative transfer + +- Table 3.5. Single-scatter albedo values used for snowpack impurities and ice + +- Table 3.6. Mass extinction values (m2 kg-1) used for snowpack impurities and ice. + +- Table 3.7. Asymmetry scattering parameters used for snowpack impurities and ice. + +- Table 3.8. Orbital parameters + +- Table 5.1. Plant functional type aerodynamic parameters + +- Table 5.2. Coefficients for e\ :sub:`sat`\ :sup:`T` + +- Table 5.3. Coefficients for 112Table 6.1. Soil layer structure. + +- Table 7.1. Meltwater scavenging efficiency for particles within snow + +- Table 7.2. Minimum and maximum thickness of snow layers (m) + +- Table 8.1. Plant functional type (PFT) photosynthetic parameters. + +- Table 8.2. Temperature dependence parameters for C3 photosynthesis. + +- Table8.3. Plant functional type root distribution parameters. + +- Table 13.1. Allocation and carbon:nitrogen ratio parameters + +- Table 15.1. Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. + +- Table 15.2. Respiration fractions for litter and SOM pools + +- Table 15.3. Respiration fractions for litter and SOM pools for Century-based structure + +- Table 15.4.Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. + +- Table 18.1. PFT-specific combustion completeness and fire mortality factors. + +- Table 19.1. Parameter descriptions and sensitivity analysis ranges applied in the methane model. + +- Table 19.2. Temperature dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. + +- Table 20.1. Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in Table 2.1. + +- Table 20.2. Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in Table 2.1. + +- Table 20.3. Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. + +- Table 22.1. Plant functional type (PFT) biogeography rules with respect to climate. + +- Table 24.1. Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i + +- Table 24.2. Minimum and maximum particle diameters in each dust transport bin j + +**ACKNOWLEDGEMENTS** The authors would like to acknowledge the substantial contributions of the following members of the Land Model and Biogeochemistry Working @@ -426,12 +273,9 @@ National Laboratory); A. Bozbiyik (Bern University); C. Heald National Laboratory); Ying Sun and Z.-L. Yang (University of Texas at Austin) -.. math:: 188 - -.. math:: 7 - -Introduction -=============== +================= + 1. Introduction +================= The purpose of this technical note is to describe the biogeophysical and biogeochemical parameterizations and numerical implementation of version @@ -690,7 +534,11 @@ problems or biases. The main modifications include updates to canopy processes including a revised canopy radiation scheme and canopy scaling of leaf processes, co-limitations on photosynthesis, revisions to photosynthetic parameters -(Bonan et al. 2011), **** temperature acclimation of photosynthesis, and +(Bonan et al. 2011), + +.. todo:: had three stars here - need to resolve this + +temperature acclimation of photosynthesis, and improved stability of the iterative solution in the photosynthesis and stomatal conductance model (Sun et al. 2012). Hydrology updates include modifications such that hydraulic properties of frozen soils are @@ -827,6 +675,4 @@ processes simulated include (Figure 1.1): Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). -**|image|** - -.. |image| image:: image1 +.. image:: image1.png diff --git a/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst b/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst index 2f1fd04e7b..032589055f 100644 --- a/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst +++ b/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst @@ -20,7 +20,7 @@ ocean separately. The RTM uses a linear transport scheme to route water from each grid cell to its downstream neighboring grid cell. The change in storage :math:`S` of river water, whether it be liquid or ice, within a RTM grid -cell (m\ :math:`{}^{3}` s\ :math:`{}^{-1}`) is +cell (m\ :sup:`3` s\ :sup:`-1`) is .. math:: :label: ZEqnNum723341 @@ -28,11 +28,11 @@ cell (m\ :math:`{}^{3}` s\ :math:`{}^{-1}`) is \frac{dS}{dt} =\sum F_{in} -F_{out} +R where :math:`\sum F_{in}` is the sum of inflows of water from -neighboring upstream grid cells (m\ :math:`{}^{3}` s\ :math:`{}^{-1}`), +neighboring upstream grid cells (m\ :sup:`3` s\ :sup:`-1`), :math:`F_{out}` is the flux of water leaving the grid cell in the -downstream direction (m :math:`{}^{3}` s\ :math:`{}^{-1}`), and :math:`R` +downstream direction (m :sup:`3` s\ :sup:`-1`), and :math:`R` is the total runoff generated by the land model grid cell -(m\ :math:`{}^{3}` s\ :math:`{}^{-1}`). Downstream water flow direction in +(m\ :sup:`3` s\ :sup:`-1`). Downstream water flow direction in each grid cell is determined as one of eight compass points (north, northeast, east, southeast, south, southwest, west, and northwest) based on the steepest downhill slope as determined from a digital elevation @@ -45,9 +45,9 @@ model (Graham et al. 1999). The flux of water leaving the grid cell F_{out} =\frac{v}{d} S where :math:`v` is the effective water flow velocity (m -s\ :math:`{}^{-1}`), :math:`d` is the distance between centers of +s\ :sup:`-1`), :math:`d` is the distance between centers of neighboring grid cells (m), and :math:`S` is the volume of river water -stored within the grid cell (m\ :math:`{}^{3}`). The effective water flow +stored within the grid cell (m\ :sup:`3`). The effective water flow velocity can be estimated from Manning’s equation, which is a function of surface water slope, the hydraulic radius of the river channel, and a channel roughness coefficient (Dingman, 2002). However, hydraulic radius @@ -94,7 +94,7 @@ The RTM is generally run at a time step greater than that of the CLM because of computational constraints. The total runoff from the land model at each time step is accumulated until the RTM is invoked. The total liquid water runoff at the land model resolution (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is +m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 11.6) @@ -104,7 +104,7 @@ m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is where :math:`q_{over}` is surface runoff (section 7.3), :math:`q_{drai}` is sub-surface drainage (section 7.6), and :math:`q_{rgwl}` is liquid runoff from glaciers, wetlands, and lakes -(all in kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) (sections 7.7 and +(all in kg m\ :sup:`-2` s\ :sup:`-1`) (sections 7.7 and 9.6.3). The total ice water runoff, also at the land model resolution is .. math:: @@ -115,9 +115,9 @@ where :math:`q_{over}` is surface runoff (section 7.3), where :math:`q_{snwcp,ice}` is the ice runoff from snow-capped surfaces (section 7.7). The runoff at the land model resolution is interpolated to the resolution of RTM and converted to units of -m\ :math:`{}^{3}` s\ :math:`{}^{-1}` for use in equation by multiplying +m\ :sup:`3` s\ :sup:`-1` for use in equation by multiplying by :math:`1\times 10^{-3} A` where :math:`A` is the area -(m\ :math:`{}^{2}`) of the RTM grid cell. +(m\ :sup:`2`) of the RTM grid cell. The RTM grid cells that are at river mouths, hence providing freshwater flux to the ocean, are identified by examining each RTM ocean grid cell diff --git a/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst b/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst index f4e74d3731..7e78b328d2 100644 --- a/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst +++ b/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst @@ -83,9 +83,9 @@ LD)], was derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity, and slope (Dobson et al. 2000). The urban extent data for TBD, HD, and MD classes are aggregated from the original 1 km resolution -to both a 0.05\ :math:`{}^\circ` by 0.05\ :math:`{}^\circ` global grid -for high-resolution studies or a 0.5\ :math:`{}^\circ` by -0.5\ :math:`{}^\circ` grid. For the current implementation, the LD class +to both a 0.05\ :sup:`o` by 0.05\ :sup:`o` global grid +for high-resolution studies or a 0.5\ :sup:`o` by +0.5\ :sup:`o` grid. For the current implementation, the LD class is not used because it is highly rural and better modeled as a vegetated/soil surface. Although the TBD, HD, and MD classes are represented as individual urban landunits, urban model history output is diff --git a/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst b/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst index c4a4ab2345..a4173834b5 100644 --- a/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst +++ b/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst @@ -64,14 +64,14 @@ storage pools from which new growth will be displayed in subsequent time steps. The total maintenance respiration demand (:math:`CF_{mr}`, gC -m\ :sup:`-2` s\ :math:`{}^{-1}`) is calculated as a function of +m\ :sup:`-2` s\ :sup:`-1`) is calculated as a function of tissue mass and nitrogen concentration, and temperature (section 13.7). The carbon supply to support this demand is composed of fluxes allocated from carbon assimilated in the current timestep -(:math:`CF_{GPP,mr}`, gC m\ :sup:`-2` s\ :math:`{}^{-1}`) +(:math:`CF_{GPP,mr}`, gC m\ :sup:`-2` s\ :sup:`-1`) and from a storage pool that is drawn down when total demand exceeds photosynthesis ( :math:`CF_{xs,mr}`, gC m\ :sup:`-2` -s\ :math:`{}^{-1}`): +s\ :sup:`-1`): .. math:: :label: 13.1) @@ -105,7 +105,7 @@ and plant type are not suitable to sustained growth, the deficit in this pool increases until the available carbon is being allocated mostly to alleviate the deficit, and new growth approaches zero. The allocation flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC -m\ :sup:`-2` s\ :math:`{}^{-1}`) is given as +m\ :sup:`-2` s\ :sup:`-1`) is given as .. math:: :label: 13.4) @@ -131,7 +131,7 @@ Carbon and Nitrogen Stoichiometry of New Growth After accounting for the carbon cost of maintenance respiration, the remaining carbon flux from photosynthesis which can be allocated to new -growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :math:`{}^{-1}`) is +growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 13.6) @@ -197,11 +197,11 @@ Table 13.1. Allocation and carbon:nitrogen ratio parameters +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ | BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :math:`{}_{3}` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +| C\ :sub:`3` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :math:`{}_{3}` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +| C\ :sub:`3` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :math:`{}_{4}` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +| C\ :sub:`4` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ | Crop R | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ @@ -237,10 +237,10 @@ where all C:N parameters are defined as constants for a given PFT (Table Given values for the parameters in and , total carbon and nitrogen allocation to new growth ( :math:`CF_{alloc}`, gC -m\ :sup:`-2` s\ :math:`{}^{-1}`, and :math:`NF_{alloc}`, gN -m\ :sup:`-2` s\ :math:`{}^{-1}`, respectively) can be expressed as +m\ :sup:`-2` s\ :sup:`-1`, and :math:`NF_{alloc}`, gN +m\ :sup:`-2` s\ :sup:`-1`, respectively) can be expressed as functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC -m\ :sup:`-2` s\ :math:`{}^{-1}`): +m\ :sup:`-2` s\ :sup:`-1`): .. math:: :label: ZEqnNum555154 @@ -263,7 +263,7 @@ Since the C:N stoichiometry for new growth allocation is defined, from Eq. , as :math:`C_{allom}`/ :math:`N_{allom}`, the total carbon available for new growth allocation (:math:`CF_{avail\_alloc}`) can be used to calculate the total plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, -gN m\ :sup:`-2` s\ :math:`{}^{-1}`) as: +gN m\ :sup:`-2` s\ :sup:`-1`) as: .. math:: :label: 13.13) @@ -282,16 +282,16 @@ Son and Gower, 1991). CLM includes one pool of retranslocated nitrogen (:math:`NS_{retrans}`, gN m\ :sup:`-2`), and the availability of nitrogen from this pool to support new growth (:math:`NF_{avail\_retrans}`, gN m\ :sup:`-2` -s\ :math:`{}^{-1}`) is proportional to the plant nitrogen demand, as: +s\ :sup:`-1`) is proportional to the plant nitrogen demand, as: .. math:: :label: 13.14) NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) -where :math:`NF_{retrans\_ann}` (gN m\ :sup:`-2` y\ :math:`{}^{-1}`) is the previous year’s annual sum of retranslocated +where :math:`NF_{retrans\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of retranslocated nitrogen extracted from senescing tissues, -:math:`NF_{plant\_demand\_ann}` (gN m\ :sup:`-2` y\ :math:`{}^{-1}`) is the previous year’s annual sum of +:math:`NF_{plant\_demand\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of :math:`NF_{plant\_demand}`, and :math:`\Delta`\ *t* (s) is the model’s biogeochemistry time step. This formulation produces an annual cycle in the extraction of nitrogen from :math:`NS_{retrans}` @@ -307,7 +307,7 @@ simulation, before :math:`NF_{plant\_demand\_ann}` and The actual flux of nitrogen from the retranslocated N pool into allocation of new growth (:math:`NF_{retrans,alloc}`, gN -m\ :sup:`-2` s\ :math:`{}^{-1}`) is never greater than the plant +m\ :sup:`-2` s\ :sup:`-1`) is never greater than the plant demand for new nitrogen: .. math:: @@ -321,7 +321,7 @@ Plant nitrogen uptake from soil mineral nitrogen pool The total plant nitrogen demand is reduced by the nitrogen flux from :math:`NS_{retrans}` to give the plant demand for mineral nitrogen from the soil (:math:`NF_{plant\_demand\_soil}`, gN -m\ :sup:`-2` s\ :math:`{}^{-1}`): +m\ :sup:`-2` s\ :sup:`-1`): .. math:: :label: ZEqnNum491412 @@ -368,7 +368,7 @@ The downregulation of photosynthesis can then be calculated as: f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . Total allocation to new leaf carbon -(:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :math:`{}^{-1}`) is calculated as: +(:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as: .. math:: :label: 13.21) @@ -550,8 +550,8 @@ following the empirical relationship reported by Ryan (1991): where :math:`MR_{base}` (= 2.525e\ :sup:`-6` gC gN\ :sup:`-1` s\ :sup:`-1`) is the base rate of maintenance respiration per unit nitrogen content, :math:`MR_{q10}` (= 2.0) is the temperature sensitivity for maintenance respiration, -:math:`T_{2m}` (:math:`{}^\circ`\ C) is the air temperature at 2m -height, :math:`Ts_{j}`* (:math:`{}^\circ`\ C) is the soil +:math:`T_{2m}` (:sup:`o`\ C) is the air temperature at 2m +height, :math:`Ts_{j}`* (:sup:`o`\ C) is the soil temperature at level *j*, and :math:`rootfr_{j}` is the fraction of fine roots distributed in soil level *j*. diff --git a/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst b/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst index 65a0cf17a7..305e532552 100644 --- a/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst +++ b/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst @@ -1,5 +1,3 @@ -.. math:: 10 - Vegetation Phenology ======================== @@ -33,7 +31,7 @@ storage over the course of a single growing season. Figure 14.1. Example of annual phenology cycle for seasonal deciduous. -|image| +.. image:: image1.png 14.1.1 Onset Periods ^^^^^^^^^^^^^^^^^^^^ @@ -43,78 +41,77 @@ growth periods (Figure 14.1). Carbon fluxes from the transfer pools into displayed growth are calculated during these periods as: .. math:: + :label: 14.1) - \label{14.1)} CF_{leaf\_ xfer,leaf} =r_{xfer\_ on} CS_{leaf\_ xfer} .. math:: + :label: 14.2) - \label{14.2)} CF_{froot\_ xfer,froot} =r_{xfer\_ on} CS_{froot\_ xfer} .. math:: + :label: 14.3) - \label{14.3)} CF_{livestem\_ xfer,livestem} =r_{xfer\_ on} CS_{livestem\_ xfer} .. math:: + :label: 14.4) - \label{14.4)} CF_{deadstem\_ xfer,deadstem} =r_{xfer\_ on} CS_{deadstem\_ xfer} .. math:: + :label: 14.5) - \label{14.5)} CF_{livecroot\_ xfer,livecroot} =r_{xfer\_ on} CS_{livecroot\_ xfer} .. math:: + :label: 14.6) - \label{14.6)} CF_{deadcroot\_ xfer,deadcroot} =r_{xfer\_ on} CS_{deadcroot\_ xfer} , with corresponding nitrogen fluxes: .. math:: + :label: 14.7) - \label{14.7)} NF_{leaf\_ xfer,leaf} =r_{xfer\_ on} NS_{leaf\_ xfer} .. math:: + :label: 14.8) - \label{14.8)} NF_{froot\_ xfer,froot} =r_{xfer\_ on} NS_{froot\_ xfer} .. math:: + :label: 14.9) - \label{14.9)} NF_{livestem\_ xfer,livestem} =r_{xfer\_ on} NS_{livestem\_ xfer} .. math:: + :label: 14.10) - \label{14.10)} NF_{deadstem\_ xfer,deadstem} =r_{xfer\_ on} NS_{deadstem\_ xfer} .. math:: + :label: 14.11) - \label{14.11)} NF_{livecroot\_ xfer,livecroot} =r_{xfer\_ on} NS_{livecroot\_ xfer} .. math:: + :label: 14.12) - \label{14.12)} NF_{deadcroot\_ xfer,deadcroot} =r_{xfer\_ on} NS_{deadcroot\_ xfer} , where CF is the carbon flux, CS is stored carbon, NF is the nitrogen -flux, NS is stored nitrogen, *r\ :math:`{}_{xfer\_on}`* -(s:math:`{}^{-1}`) is a time-varying rate coefficient controlling flux +flux, NS is stored nitrogen, :math:`{r}_{xfer\_on}` (s\ :sup:`-1`) is a time-varying rate coefficient controlling flux out of the transfer pool: .. math:: + :label: ZEqnNum852972 - \label{ZEqnNum852972} r_{xfer\_ on} =\left\{\begin{array}{l} {{2\mathord{\left/ {\vphantom {2 t_{onset} }} \right. \kern-\nulldelimiterspace} t_{onset} } \qquad {\rm for\; }t_{onset} \ne \Delta t} \\ {{1\mathord{\left/ {\vphantom {1 \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \qquad {\rm for\; }t_{onset} =\Delta t} \end{array}\right. -and *t\ :math:`{}_{onset}`* (s) is the number of seconds remaining in +and *t*\ :sub:`onset` (s) is the number of seconds remaining in the current phenology onset growth period (Figure 14.1). The form of Eq. produces a flux from the transfer pool which declines linearly over the onset growth period, approaching zero flux in the final timestep. @@ -129,47 +126,44 @@ Carbon fluxes from display pools into litter are calculated during these periods as: .. math:: + :label: 14.14) - \label{14.14)} CF_{leaf,litter}^{n} =\left\{\begin{array}{l} {CF_{leaf,litter}^{n-1} +r_{xfer\_ off} \left(CS_{leaf} -CF_{leaf,litter}^{n-1} {\kern 1pt} t_{offset} \right)\qquad {\rm for\; }t_{offset} \ne \Delta t} \\ {\left({CS_{leaf} \mathord{\left/ {\vphantom {CS_{leaf} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \right)+CF_{alloc,leaf} \qquad \qquad \qquad \qquad {\rm for\; }t_{offset} =\Delta t} \end{array}\right. .. math:: + :label: 14.15) - \label{14.15)} CF_{froot,litter}^{n} =\left\{\begin{array}{l} {CF_{froot,litter}^{n-1} +r_{xfer\_ off} \left(CS_{froot} -CF_{froot,litter}^{n-1} {\kern 1pt} t_{offset} \right)\qquad {\rm for\; }t_{offset} \ne \Delta t} \\ {\left({CS_{froot} \mathord{\left/ {\vphantom {CS_{froot} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \right)+CF_{alloc,\, froot} \qquad \qquad \qquad {\rm for\; }t_{offset} =\Delta t} \end{array}\right. .. math:: + :label: 14.16) - \label{14.16)} r_{xfer\_ off} =\frac{2\Delta t}{t_{offset} ^{2} } where superscripts *n* and *n-1* refer to fluxes on the current and -previous timesteps, respectively. The rate coefficient -*r\ :math:`{}_{xfer\_off}`* varies with time to produce a linearly +previous timesteps, respectively. The rate coefficient :math:`{r}_{xfer\_off}` varies with time to produce a linearly increasing litterfall rate throughout the offset period, and the special case for fluxes in the final litterfall timestep -(*t\ :math:`{}_{offset}`* = *:math:`\Delta`\ t*) ensures that all of the +(:math:`{t}_{offset}` = :math:`\Delta t`\ ) ensures that all of the displayed growth is sent to the litter pools for deciduous plant types. -Corresponding nitrogen fluxes during litterfall take into account -retranslocation of nitrogen out of the displayed leaf pool prior to -litterfall (*NF\ :math:`{}_{leaf,retrans}`*, gN m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`). Retranslocation of nitrogen out of fine roots is +Corresponding nitrogen fluxes during litterfall take into account retranslocation of nitrogen out of the displayed leaf pool prior to +litterfall (:math:`{NF}_{leaf,retrans}`, gN m\ :sup:`-2` s\ :sup:`-1`). Retranslocation of nitrogen out of fine roots is assumed to be negligible. The fluxes are: .. math:: + :label: 14.17) - \label{14.17)} NF_{leaf,litter} ={CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf\_ litter} }} \right. \kern-\nulldelimiterspace} CN_{leaf\_ litter} } .. math:: + :label: 14.18) - \label{14.18)} NF_{froot,litter} ={CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{froot} }} \right. \kern-\nulldelimiterspace} CN_{froot} } .. math:: + :label: 14.19) - \label{14.19)} NF_{leaf,retrans} =\left({CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf} }} \right. \kern-\nulldelimiterspace} CN_{leaf} } \right)-NF_{leaf,litter} . where CN is C:N. @@ -182,7 +176,7 @@ case when stress signals are absent, and the vegetation shifts from a deciduous habit to an evergreen habit, until the next occurrence of an offset stress trigger . In that case, the regular onset flux mechanism is switched off and a background onset growth algorithm is invoked -(*r\ :math:`{}_{bgtr}`* :math:`>` 0). During this period, small fluxes +(:math:`{r}_{bgtr} > 0`). During this period, small fluxes of carbon and nitrogen from the storage pools into the associated transfer pools are calculated on each time step, and the entire contents of the transfer pool are added to the associated displayed growth pool @@ -190,65 +184,65 @@ on each time step. The carbon fluxes from transfer to display pools under these conditions are: .. math:: + :label: 14.20) - \label{14.20)} CF_{leaf\_ xfer,leaf} ={CS_{leaf\_ xfer} \mathord{\left/ {\vphantom {CS_{leaf\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.21) - \label{14.21)} CF_{froot\_ xfer,froot} ={CS_{froot\_ xfer} \mathord{\left/ {\vphantom {CS_{froot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.22) - \label{14.22)} CF_{livestem\_ xfer,livestem} ={CS_{livestem\_ xfer} \mathord{\left/ {\vphantom {CS_{livestem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.23) - \label{14.23)} CF_{deadstem\_ xfer,deadstem} ={CS_{deadstem\_ xfer} \mathord{\left/ {\vphantom {CS_{deadstem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.24) - \label{14.24)} CF_{livecroot\_ xfer,livecroot} ={CS_{livecroot\_ xfer} \mathord{\left/ {\vphantom {CS_{livecroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.25) - \label{14.25)} CF_{deadcroot\_ xfer,deadcroot} ={CS_{deadcroot\_ xfer} \mathord{\left/ {\vphantom {CS_{deadcroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} , and the corresponding nitrogen fluxes are: .. math:: + :label: 14.26) - \label{14.26)} NF_{leaf\_ xfer,leaf} ={NS_{leaf\_ xfer} \mathord{\left/ {\vphantom {NS_{leaf\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.27) - \label{14.27)} NF_{froot\_ xfer,froot} ={NS_{froot\_ xfer} \mathord{\left/ {\vphantom {NS_{froot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.28) - \label{14.28)} NF_{livestem\_ xfer,livestem} ={NS_{livestem\_ xfer} \mathord{\left/ {\vphantom {NS_{livestem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.29) - \label{14.29)} NF_{deadstem\_ xfer,deadstem} ={NS_{deadstem\_ xfer} \mathord{\left/ {\vphantom {NS_{deadstem\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.30) - \label{14.30)} NF_{livecroot\_ xfer,livecroot} ={NS_{livecroot\_ xfer} \mathord{\left/ {\vphantom {NS_{livecroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.31) - \label{14.31)} NF_{deadcroot\_ xfer,deadcroot} ={NS_{deadcroot\_ xfer} \mathord{\left/ {\vphantom {NS_{deadcroot\_ xfer} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} . 14.1.4 Background Litterfall @@ -261,34 +255,33 @@ referred to as background litterfall. For evergreen types the background litterfall is the only litterfall flux. For stress-deciduous types either the offset period litterfall or the background litterfall mechanism may be active, but not both at once. Given a specification of -the background litterfall rate (*r\ :math:`{}_{bglf}`*, -s\ :math:`{}^{-1}`), litterfall carbon fluxes are calculated as +the background litterfall rate (:math:`{r}_{bglf}`, s\ :sup:`-1`), litterfall carbon fluxes are calculated as .. math:: + :label: 14.32) - \label{14.32)} CF_{leaf,litter} =r_{bglf} CS_{leaf} .. math:: + :label: 14.33) - \label{14.33)} CS_{froot,litter} =r_{bglf} CS_{froot} , with corresponding nitrogen litterfall and retranslocation fluxes: .. math:: + :label: 14.34) - \label{14.34)} NF_{leaf,litter} ={CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf\_ litter} }} \right. \kern-\nulldelimiterspace} CN_{leaf\_ litter} } .. math:: + :label: 14.35) - \label{14.35)} NF_{froot,litter} ={CF_{froot,litter} \mathord{\left/ {\vphantom {CF_{froot,litter} CN_{froot} }} \right. \kern-\nulldelimiterspace} CN_{froot} } .. math:: + :label: 14.36) - \label{14.36)} NF_{leaf,retrans} =\left({CF_{leaf,litter} \mathord{\left/ {\vphantom {CF_{leaf,litter} CN_{leaf} }} \right. \kern-\nulldelimiterspace} CN_{leaf} } \right)-NF_{leaf,litter} . 14.1.5 Livewood Turnover @@ -305,48 +298,48 @@ effect the transfer of live wood to dead wood pools, which also takes into account the different nitrogen concentrations typical of these tissue types. -A live wood turnover rate (*r\ :math:`{}_{lwt}`*, s\ :math:`{}^{-1}`) is +A live wood turnover rate (:math:`{r}_{lwt}`, s\ :sup:`-1`) is defined as .. math:: + :label: 14.37) - \label{14.37)} r_{lwt} ={p_{lwt} \mathord{\left/ {\vphantom {p_{lwt} \left(365\cdot 86400\right)}} \right. \kern-\nulldelimiterspace} \left(365\cdot 86400\right)} -where *p\ :math:`{}_{lwt}`* = 0.7 is the assumed annual live wood +where :math:`{p}_{lwt} = 0.7` is the assumed annual live wood turnover fraction. Carbon fluxes from live to dead wood pools are: .. math:: + :label: 14.38) - \label{14.38)} CF_{livestem,deadstem} =CS_{livestem} r_{lwt} .. math:: + :label: 14.39) - \label{14.39)} CF_{livecroot,deadcroot} =CS_{livecroot} r_{lwt} , and the associated nitrogen fluxes, including retranslocation of nitrogen out of live wood during turnover, are: .. math:: + :label: 14.40) - \label{14.40)} NF_{livestem,deadstem} ={CF_{livestem,deadstem} \mathord{\left/ {\vphantom {CF_{livestem,deadstem} CN_{dw} }} \right. \kern-\nulldelimiterspace} CN_{dw} } .. math:: + :label: 14.41) - \label{14.41)} NF_{livestem,retrans} =\left({CF_{livestem,deadstem} \mathord{\left/ {\vphantom {CF_{livestem,deadstem} CN_{lw} }} \right. \kern-\nulldelimiterspace} CN_{lw} } \right)-NF_{livestem,deadstem} .. math:: + :label: 14.42) - \label{14.42)} NF_{livecroot,deadcroot} ={CF_{livecroot,deadcroot} \mathord{\left/ {\vphantom {CF_{livecroot,deadcroot} CN_{dw} }} \right. \kern-\nulldelimiterspace} CN_{dw} } .. math:: + :label: 14.43) - \label{14.43)} NF_{livecroot,retrans} =\left({CF_{livecroot,deadcroot} \mathord{\left/ {\vphantom {CF_{livecroot,deadcroot} CN_{lw} }} \right. \kern-\nulldelimiterspace} CN_{lw} } \right)-NF_{livecroot,deadcroot} . Evergreen Phenology @@ -355,7 +348,7 @@ Evergreen Phenology The evergreen phenology algorithm is by far the simplest of the three possible types. It is assumed for all evergreen types that all carbon and nitrogen allocated for new growth in the current timestep goes -immediately to the displayed growth pools (i.e. *f\ :math:`{}_{cur}`* = +immediately to the displayed growth pools (i.e. f\ :math:`{f}_{cur} = 1.0` (Chapter 13)). As such, there is never an accumulation of carbon or nitrogen in the storage or transfer pools, and so the onset growth and background onset growth mechanisms are never invoked for this type. @@ -366,13 +359,12 @@ roots. This is an obvious area for potential improvements in the model, since it is known, at least for evergreen needleleaf trees in the temperate and boreal zones, that there are distinct periods of higher and lower leaf litterfall (Ferrari, 1999; Gholz et al., 1985). The rate -of background litterfall (*r\ :math:`{}_{bglf}`*, section 14.1.4) -depends on the specified leaf longevity -(*:math:`\tau`\ :math:`{}_{leaf}`*, y), as +of background litterfall (:math:`{r}_{bglf}`, section 14.1.4) +depends on the specified leaf longevity (:math:`\tau_{leaf}`\ , y), as .. math:: + :label: 14.44) - \label{14.44)} r_{bglf} =\frac{1}{\tau _{leaf} \cdot 365\cdot 86400} . Seasonal-Deciduous Phenology @@ -394,16 +386,15 @@ of one onset period and one offset period each year. The algorithms for initiation of onset and offset periods use the winter and summer solstices as coordination signals. The period between winter -and summer solstice is identified as *dayl\ :math:`{}_{n}`* :math:`>` -*dayl\ :math:`{}_{n-1}`*, and the period between summer and winter -solstice is identified as *dayl\ :math:`{}_{n}`* :math:`<` -*dayl\ :math:`{}_{n-1}`*, where *dayl\ :math:`{}_{n}`* and -*dayl\ :math:`{}_{n-1}`* are the daylength (s) calculated for the +and summer solstice is identified as :math:`{dayl}_{n} > {dayl}_{n-1}`, +and the period between summer and winter +solstice is identified as :math:`{dayl}_{n} < {dayl}_{n-1}`, +where :math:`{dayl}_{n}` and :math:`{dayl}_{n-1}` are the day length(s) calculated for the current and previous timesteps, respectively, using .. math:: + :label: 14.45) - \label{14.45)} dayl=2\cdot 13750.9871\cdot acos\left(\frac{-\sin (lat)\sin (decl)}{\cos (lat)\cos (decl)} \right), where *lat* and *decl* are the latitude and solar declination (radians), @@ -415,124 +406,120 @@ radian of hour-angle. The onset trigger for the seasonal-deciduous phenology algorithm is based on an accumulated growing-degree-day approach (White et al., -1997). The growing-degree-day summation (*GDD\ :math:`{}_{sum}`*) is -initiated (*GDD\ :math:`{}_{sum}`* = 0) when the phenological state is +1997). The growing-degree-day summation (:math:`{GDD}_{sum}`) is +initiated ( :math:`{GDD}_{sum} = 0`) when the phenological state is dormant and the model timestep crosses the winter solstice. Once these -conditions are met, *GDD\ :math:`{}_{sum}`* is updated on each timestep -as +conditions are met, :math:`{GDD}_{sum}` is updated on each timestep as .. math:: + :label: ZEqnNum510730 - \label{ZEqnNum510730} GDD_{sum}^{n} =\left\{\begin{array}{l} {GDD_{sum}^{n-1} +\left(T_{s,3} -TKFRZ\right)f_{day} \qquad {\rm for\; }T_{s,3} >TKFRZ} \\ {GDD_{sum}^{n-1} \qquad \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \end{array}\right. -where *T\ :math:`{}_{s,3}`* (K) is the temperature of the third soil -layer, and +where :math:`{T}_{s,3}` (K) is the temperature of the third soil layer, and :math:`f_{day} ={\Delta t\mathord{\left/ {\vphantom {\Delta t 86400}} \right. \kern-\nulldelimiterspace} 86400}` . The onset period is initiated if :math:`GDD_{sum} >GDD_{sum\_ crit}` , where .. math:: + :label: ZEqnNum598907 - \label{ZEqnNum598907} GDD_{sum\_ crit} =\exp \left(4.8+0.13{\kern 1pt} \left(T_{2m,ann\_ avg} -TKFRZ\right)\right) -and where *T\ :math:`{}_{2m,ann\_avg}`* (K) is the annual average of -the 2m air temperature, and TKFRZ is the freezing point of water (273.15 -K). The following control variables are set when a new onset growth +and where :math:`{T}_{2m,ann\_avg}` (K) is the annual average of +the 2m air temperature, and TKFRZ is the freezing point of water (273.15 K). The following control variables are set when a new onset growth period is initiated: .. math:: + :label: 14.48) - \label{14.48)} GDD_{sum} =0 .. math:: + :label: 14.49) - \label{14.49)} t_{onset} =86400\cdot n_{days\_ on} , -where *n\ :math:`{}_{days\_on}`* is set to a constant value of 30 days. +where :math:`{n}_{days\_on}` is set to a constant value of 30 days. Fluxes from storage into transfer pools occur in the timestep when a new onset growth period is initiated. Carbon fluxes are: .. math:: + :label: ZEqnNum904388 - \label{ZEqnNum904388} CF_{leaf\_ stor,leaf\_ xfer} ={f_{stor,xfer} CS_{leaf\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{leaf\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.51) - \label{14.51)} CF_{froot\_ stor,froot\_ xfer} ={f_{stor,xfer} CS_{froot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{froot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.52) - \label{14.52)} CF_{livestem\_ stor,livestem\_ xfer} ={f_{stor,xfer} CS_{livestem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{livestem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.53) - \label{14.53)} CF_{deadstem\_ stor,deadstem\_ xfer} ={f_{stor,xfer} CS_{deadstem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{deadstem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.54) - \label{14.54)} CF_{livecroot\_ stor,livecroot\_ xfer} ={f_{stor,xfer} CS_{livecroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{livecroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.55) - \label{14.55)} CF_{deadcroot\_ stor,deadcroot\_ xfer} ={f_{stor,xfer} CS_{deadcroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{deadcroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: ZEqnNum195642 - \label{ZEqnNum195642} CF_{gresp\_ stor,gresp\_ xfer} ={f_{stor,xfer} CS_{gresp\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} CS_{gresp\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} and the associated nitrogen fluxes are: .. math:: + :label: ZEqnNum812152 - \label{ZEqnNum812152} NF_{leaf\_ stor,leaf\_ xfer} ={f_{stor,xfer} NS_{leaf\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{leaf\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.58) - \label{14.58)} NF_{froot\_ stor,froot\_ xfer} ={f_{stor,xfer} NS_{froot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{froot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.59) - \label{14.59)} NF_{livestem\_ stor,livestem\_ xfer} ={f_{stor,xfer} NS_{livestem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{livestem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.60) - \label{14.60)} NF_{deadstem\_ stor,deadstem\_ xfer} ={f_{stor,xfer} NS_{deadstem\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{deadstem\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 14.61) - \label{14.61)} NF_{livecroot\_ stor,livecroot\_ xfer} ={f_{stor,xfer} NS_{livecroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{livecroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: ZEqnNum605338 - \label{ZEqnNum605338} NF_{deadcroot\_ stor,deadcroot\_ xfer} ={f_{stor,xfer} NS_{deadcroot\_ stor} \mathord{\left/ {\vphantom {f_{stor,xfer} NS_{deadcroot\_ stor} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} -where *f\ :math:`{}_{stor,xfer}`* is the fraction of current storage +where :math:`{f}_{stor,xfer}` is the fraction of current storage pool moved into the transfer pool for display over the incipient onset period. This fraction is set to 0.5, based on the observation that seasonal deciduous trees are capable of replacing their canopies from storage reserves in the event of a severe early-season disturbance such as frost damage or defoliation due to insect herbivory. -If the onset criterion (*GDD\ :math:`{}_{sum}`* :math:`>` -*GDD\ :math:`{}_{sum\_crit}`*) is not met before the summer solstice, -then *GDD\ :math:`{}_{sum}`* is set to 0.0 and the growing-degree-day +If the onset criterion (:math:`{GDD}_{sum} > {GDD}_{sum\_crit}`) is not met before the summer solstice, +then :math:`{GDD}_{sum}` is set to 0.0 and the growing-degree-day accumulation will not start again until the following winter solstice. This mechanism prevents the initiation of very short growing seasons late in the summer in cold climates. The onset counter is decremented on @@ -540,8 +527,8 @@ each time step after initiation of the onset period, until it reaches zero, signaling the end of the onset period: .. math:: + :label: 14.63) - \label{14.63)} t_{onfset}^{n} =t_{onfset}^{n-1} -\Delta t 14.3.2 Seasonal-Deciduous Offset Trigger @@ -551,14 +538,14 @@ After the completion of an onset period, and once past the summer solstice, the offset (litterfall) period is triggered when daylength is shorter than 39300 s. The offset counter is set at the initiation of the offset period: :math:`t_{offset} =86400\cdot n_{days\_ off}` , where -*n\ :math:`{}_{days\_off}`* is set to a constant value of 15 days. The +:math:`{n}_{days\_off}` is set to a constant value of 15 days. The offset counter is decremented on each time step after initiation of the offset period, until it reaches zero, signaling the end of the offset period: .. math:: + :label: 14.64) - \label{14.64)} t_{offset}^{n} =t_{offset}^{n-1} -\Delta t Stress-Deciduous Phenology @@ -581,22 +568,21 @@ the next stress trigger. In climates that are warm year-round, onset triggering depends on soil water availability. At the beginning of a dormant period (end of previous offset period), an accumulated soil water index -(*SWI\ :math:`{}_{sum}`*, d) is initialized (*SWI\ :math:`{}_{sum}`* = -0), with subsequent accumulation calculated as: +(:math:`{SWI}_{sum}`, d) is initialized (:math:`{SWI}_{sum} = 0`), with subsequent accumulation calculated as: .. math:: + :label: ZEqnNum503826 - \label{ZEqnNum503826} SWI_{sum}^{n} =\left\{\begin{array}{l} {SWI_{sum}^{n-1} +f_{day} \qquad {\rm for\; }\Psi _{s,3} \ge \Psi _{onset} } \\ {SWI_{sum}^{n-1} \qquad \qquad {\rm for\; }\Psi _{s,3} <\Psi _{onset} } \end{array}\right. -where :math:`\Psi`\ *:math:`{}_{s,3}`* is the soil water potential (MPa) -in the third soil layer and :math:`\Psi`\ *:math:`{}_{onset}`* = -2 MPa +where :math:`\Psi`\ :sub:`s,3` is the soil water potential (MPa) +in the third soil layer and :math:`{\Psi}_{onset} = -2 MPa` is the onset soil water potential threshold. Onset triggering is -possible once *SWI\ :math:`{}_{sum}`* :math:`>` 15. If the cold climate +possible once :math:`{SWI}_{sum} > 15`. If the cold climate growing degree-day accumulator is not active at the time when this threshold is reached (see below), and if the daylength is greater than 6 hours, then onset is triggered. Except as noted below, -*SWI\ :math:`{}_{sum}`* continues to accumulate according to Eq. during +:math:`{SWI}_{sum}` continues to accumulate according to Eq. during the dormant period if the daylength criterion prevents onset triggering, and onset is then triggered at the timestep when daylength exceeds 6 hours. @@ -604,37 +590,32 @@ hours. In climates with a cold season, onset triggering depends on both accumulated soil temperature summation and adequate soil moisture. At the beginning of a dormant period a freezing day accumulator -(*FD\ :math:`{}_{sum}`*, d) is initialized (*FD\ :math:`{}_{sum}`* = 0), +(:math:`{FD}_{sum}`, d) is initialized (:math:`{FD}_{sum} = 0`), with subsequent accumulation calculated as: .. math:: + :label: 14.66) - \label{14.66)} FD_{sum}^{n} =\left\{\begin{array}{l} {FD_{sum}^{n-1} +f_{day} \qquad {\rm for\; }T_{s,3} >TKFRZ} \\ {FD_{sum}^{n-1} \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \end{array}\right. . -If *FD\ :math:`{}_{sum}`* :math:`>` 15 during the dormant period, then a +If :math:`{FD}_{sum} > 15` during the dormant period, then a cold-climate onset triggering criterion is introduced, following exactly -the growing degree-day summation (*GDD\ :math:`{}_{sum}`*) logic of Eqs. -and . At that time *SWI\ :math:`{}_{sum}`* is reset -(*SWI\ :math:`{}_{sum}`* = 0). Onset triggering under these conditions +the growing degree-day summation (:math:`{GDD}_{sum}`) logic of Eqs. +and . At that time :math:`{SWI}_{sum}` is reset +(:math:`{SWI}_{sum} = 0`). Onset triggering under these conditions depends on meeting all three of the following criteria: -*SWI\ :math:`{}_{sum}`* :math:`>` 15, *GDD\ :math:`{}_{sum}`* :math:`>` -*GDD\ :math:`{}_{sum\_crit}`*, and daylength greater than 6 hrs. +:math:`{SWI}_{sum} > 15`, :math:`{GDD}_{sum} > {GDD}_{sum\_crit}`, and daylength greater than 6 hrs. The following control variables are set when a new onset growth period -is initiated: *SWI\ :math:`{}_{sum}`* = 0, *FD\ :math:`{}_{sum}`* = 0, -*GDD\ :math:`{}_{sum}`* = 0, *n\ :math:`{}_{days\_active}`* = 0, and -:math:`t_{onset} =86400\cdot n_{days\_ on}` , where -*n\ :math:`{}_{days\_on}`* is set to a constant value of 30 days. Fluxes -from storage into transfer pools occur in the timestep when a new onset -growth period is initiated, and are handled identically to Eqs. - for -carbon fluxes, and to Eqs. - for nitrogen fluxes. The onset counter is -decremented on each time step after initiation of the onset period, +is initiated: :math:`{SWI}_{sum} = 0`, :math:`{FD}_{sum} = 0`, :math:`{GDD}_{sum} = 0`, :math:`{n}_{days\_active} = 0`, and +:math:`t_{onset} = 86400\cdot n_{days\_ on}` , where :math:`{n}_{days\_on}` is set to a constant value of 30 days. Fluxes +from storage into transfer pools occur in the timestep when a new onset growth period is initiated, and are handled identically to Eqs. - for +carbon fluxes, and to Eqs. - for nitrogen fluxes. The onset counter is decremented on each time step after initiation of the onset period, until it reaches zero, signaling the end of the onset period: .. math:: + :label: 14.67) - \label{14.67)} t_{onfset}^{n} =t_{onfset}^{n-1} -\Delta t 14.4.2 Stress-Deciduous Offset Triggers @@ -646,44 +627,43 @@ period of dry soil, sustained period of cold temperature, or daylength shorter than 6 hours. Offset triggering due to dry soil or cold temperature conditions is only allowed once the most recent onset period is complete. Dry soil condition is evaluated with an offset soil water -index accumulator (*OSWI\ :math:`{}_{sum}`*, d). To test for a sustained +index accumulator (:math:`{OSWI}_{sum}`, d). To test for a sustained period of dry soils, this control variable can increase or decrease, as follows: .. math:: + :label: 14.68) - \label{14.68)} OSWI_{sum}^{n} =\left\{\begin{array}{l} {OSWI_{sum}^{n-1} +f_{day} \qquad \qquad \qquad {\rm for\; }\Psi _{s,3} \le \Psi _{offset} } \\ {{\rm max}\left(OSWI_{sum}^{n-1} -f_{day} ,0\right)\qquad {\rm for\; }\Psi _{s,3} >\Psi _{onset} } \end{array}\right. -where :math:`\Psi`\ *:math:`{}_{offset}`* = -2 MPa is the offset soil +where :math:`{\Psi}_{offset} = -2 MPa` is the offset soil water potential threshold. An offset period is triggered if the previous -onset period is complete and *OSWI\ :math:`{}_{sum}`* -:math:`\mathrm{\ge}` *OSWI\ :math:`{}_{sum\_crit}`*, where -*OSWI\ :math:`{}_{sum\_crit}`* = 15. +onset period is complete and :math:`{OSWI}_{sum}` +:math:`\mathrm{\ge}` :math:`{OSWI}_{sum\_crit}`, where :math:`{OSWI}_{sum\_crit} = 15`. The cold temperature trigger is calculated with an offset freezing day -accumulator (*OFD\ :math:`{}_{sum}`*, d). To test for a sustained period +accumulator (:math:`{OFD}_{sum}`, d). To test for a sustained period of cold temperature, this variable can increase or decrease, as follows: .. math:: + :label: 14.69) - \label{14.69)} OFD_{sum}^{n} =\left\{\begin{array}{l} {OFD_{sum}^{n-1} +f_{day} \qquad \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \\ {{\rm max}\left(OFD_{sum}^{n-1} -f_{day} ,0\right)\qquad \qquad {\rm for\; }T_{s,3} >TKFRZ} \end{array}\right. An offset period is triggered if the previous onset period is complete -and *OFD\ :math:`{}_{sum}`* :math:`>` *OFD\ :math:`{}_{sum\_crit}`*, -where *OFD\ :math:`{}_{sum\_crit}`* = 15. +and :math:`{OFD}_{sum} > {OFD}_{sum\_crit}`, +where :math:`{OFD}_{sum\_crit} = 15`. The offset counter is set at the initiation of the offset period: :math:`t_{offset} =86400\cdot n_{days\_ off}` , where -*n\ :math:`{}_{days\_off}`* is set to a constant value of 15 days. The +:math:`{n}_{days\_off}` is set to a constant value of 15 days. The offset counter is decremented on each time step after initiation of the offset period, until it reaches zero, signaling the end of the offset period: .. math:: + :label: 14.70) - \label{14.70)} t_{offset}^{n} =t_{offset}^{n-1} -\Delta t 14.4.3 Stress-Deciduous: Long Growing Season @@ -695,99 +675,94 @@ shifts toward the evergreen behavior. This can happen in cases where a stress-deciduous vegetation type is assigned in a climate where suitably strong stresses occur less frequently than once per year. This condition is evaluated by tracking the number of days since the beginning of the -most recent onset period (*n\ :math:`{}_{days\_active}`*, d). At the end -of an offset period *n\ :math:`{}_{days\_active}`* is reset to 0. A long +most recent onset period (:math:`{n}_{days\_active}`, d). At the end +of an offset period :math:`{n}_{days\_active}` is reset to 0. A long growing season control variable (*LGS*, range 0 to 1) is calculated as: .. math:: + :label: 14.71) - \label{14.71)} LGS=\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }n_{days\_ active} <365} \\ {\left({n_{days\_ active} \mathord{\left/ {\vphantom {n_{days\_ active} 365}} \right. \kern-\nulldelimiterspace} 365} \right)-1\qquad {\rm for\; }365\le n_{days\_ active} <730} \\ {1\qquad \qquad \qquad {\rm for\; }n_{days\_ active} \ge 730} \end{array}\right. . -The rate coefficient for background litterfall (*r\ :math:`{}_{bglf}`*, -s\ :math:`{}^{-1}`) is calculated as a function of *LGS*: +The rate coefficient for background litterfall (:math:`{r}_{bglf}`, s\ :sup:`-1`) is calculated as a function of *LGS*: .. math:: + :label: 14.72) - \label{14.72)} r_{bglf} =\frac{LGS}{\tau _{leaf} \cdot 365\cdot 86400} -where *:math:`\tau`\ :math:`{}_{leaf}`* is the leaf longevity. The -result is a shift to continuous litterfall as -*n\ :math:`{}_{days\_active}`* increases from 365 to 730. When a new -offset period is triggered *r\ :math:`{}_{bglf}`* is set to 0. +where :math:`{\tau}_{leaf}` is the leaf longevity. The result is a shift to continuous litterfall as +:math:`{n}_{days\_active}` increases from 365 to 730. When a new offset period is triggered :math:`{r}_{bglf}` is set to 0. -The rate coefficient for background onset growth from the transfer pools -(*r\ :math:`{}_{bgtr}`*, s\ :math:`{}^{-1}`) also depends on *LGS*, as: +The rate coefficient for background onset growth from the transfer pools ( :math:`{r}_{bgtr}`, s\ :sup:`-1`) also depends on *LGS*, as: .. math:: + :label: 14.73) - \label{14.73)} r_{bgtr} =\frac{LGS}{365\cdot 86400} . -On each timestep with *r\ :math:`{}_{bgtr}`* :math:`\neq` 0, carbon -fluxes from storage to transfer pools are calculated as: +On each timestep with :math:`{r}_{bgtr}` :math:`\neq` 0, carbon fluxes from storage to transfer pools are calculated as: .. math:: + :label: 14.74) - \label{14.74)} CF_{leaf\_ stor,leaf\_ xfer} =CS_{leaf\_ stor} r_{bgtr} .. math:: + :label: 14.75) - \label{14.75)} CF_{froot\_ stor,froot\_ xfer} =CS_{froot\_ stor} r_{bgtr} .. math:: + :label: 14.76) - \label{14.76)} CF_{livestem\_ stor,livestem\_ xfer} =CS_{livestem\_ stor} r_{bgtr} .. math:: + :label: 14.77) - \label{14.77)} CF_{deadstem\_ stor,deadstem\_ xfer} =CS_{deadstem\_ stor} r_{bgtr} .. math:: + :label: 14.78) - \label{14.78)} CF_{livecroot\_ stor,livecroot\_ xfer} =CS_{livecroot\_ stor} r_{bgtr} .. math:: + :label: 14.79) - \label{14.79)} CF_{deadcroot\_ stor,deadcroot\_ xfer} =CS_{deadcroot\_ stor} r_{bgtr} , with corresponding nitrogen fluxes: .. math:: + :label: 14.80) - \label{14.80)} NF_{leaf\_ stor,leaf\_ xfer} =NS_{leaf\_ stor} r_{bgtr} .. math:: + :label: 14.81) - \label{14.81)} NF_{froot\_ stor,froot\_ xfer} =NS_{froot\_ stor} r_{bgtr} .. math:: + :label: 14.82) - \label{14.82)} NF_{livestem\_ stor,livestem\_ xfer} =NS_{livestem\_ stor} r_{bgtr} .. math:: + :label: 14.83) - \label{14.83)} NF_{deadstem\_ stor,deadstem\_ xfer} =NS_{deadstem\_ stor} r_{bgtr} .. math:: + :label: 14.84) - \label{14.84)} NF_{livecroot\_ stor,livecroot\_ xfer} =NS_{livecroot\_ stor} r_{bgtr} .. math:: + :label: 14.85) - \label{14.85)} NF_{deadcroot\_ stor,deadcroot\_ xfer} =NS_{deadcroot\_ stor} r_{bgtr} . The result, in conjunction with the treatment of background onset @@ -795,7 +770,7 @@ growth, is a shift to continuous transfer from storage to display pools at a rate that would result in complete turnover of the storage pools in one year at steady state, once *LGS* reaches 1 (i.e. after two years without stress-deciduous offset conditions). If and when conditions -cause stress-deciduous triggering again, *r\ :math:`{}_{bgtr}`* is rest +cause stress-deciduous triggering again, :math:`{r}_{bgtr}` is rest to 0. Litterfall Fluxes Merged to the Column Level @@ -813,75 +788,74 @@ calculated using a weighted average of the fluxes originating at the PFT level. Carbon fluxes are calculated as: .. math:: + :label: 14.86) - \label{14.86)} CF_{leaf,lit1} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{lab\_ leaf,p} wcol_{p} .. math:: + :label: 14.87) - \label{14.87)} CF_{leaf,lit2} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{cel\_ leaf,p} wcol_{p} .. math:: + :label: 14.88) - \label{14.88)} CF_{leaf,lit3} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{lig\_ leaf,p} wcol_{p} .. math:: + :label: 14.89) - \label{14.89)} CF_{froot,lit1} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{lab\_ froot,p} wcol_{p} .. math:: + :label: 14.90) - \label{14.90)} CF_{froot,lit2} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{cel\_ froot,p} wcol_{p} .. math:: + :label: 14.91) - \label{14.91)} CF_{froot,lit3} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{lig\_ froot,p} wcol_{p} , -where *f\ :math:`{}_{lab\_leaf,p}`*, *f\ :math:`{}_{cel\_leaf,p}`*, and -*f\ :math:`{}_{lig\_leaf,p}`* are the labile, cellulose/hemicellulose, +where :math:`{f}_{lab\_leaf,p}`, :math:`{f}_{cel\_leaf,p}`, and +:math:`{f}_{lig\_leaf,p}` are the labile, cellulose/hemicellulose, and lignin fractions of leaf litter for PFT *p*, -*f\ :math:`{}_{lab\_froot,p}`*, *f\ :math:`{}_{cel\_froot,p}`*, and -*f\ :math:`{}_{lig\_froot,p}`* are the labile, cellulose/hemicellulose, +:math:`{f}_{lab\_froot,p}`, :math:`{f}_{cel\_froot,p}`, and +:math:`{f}_{lig\_froot,p}` are the labile, cellulose/hemicellulose, and lignin fractions of fine root litter for PFT *p*, -*wtcol\ :math:`{}_{p}`* is the weight relative to the column for PFT +:math:`{wtcol}_{p}` is the weight relative to the column for PFT *p*, and *p* is an index through the plant functional types occurring on a column. Nitrogen fluxes to the litter pools are assumed to follow the C:N of the senescent tissue, and so are distributed using the same fractions used for carbon fluxes: .. math:: + :label: 14.92) - \label{14.92)} NF_{leaf,lit1} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{lab\_ leaf,p} wcol_{p} .. math:: + :label: 14.93) - \label{14.93)} NF_{leaf,lit2} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{cel\_ leaf,p} wcol_{p} .. math:: + :label: 14.94) - \label{14.94)} NF_{leaf,lit3} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{lig\_ leaf,p} wcol_{p} .. math:: + :label: 14.95) - \label{14.95)} NF_{froot,lit1} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{lab\_ froot,p} wcol_{p} .. math:: + :label: 14.96) - \label{14.96)} NF_{froot,lit2} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{cel\_ froot,p} wcol_{p} .. math:: + :label: 14.97) - \label{14.97)} NF_{froot,lit3} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{lig\_ froot,p} wcol_{p} . -.. |image| image:: image1 diff --git a/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst b/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst index eefab609fb..89e12a7b94 100644 --- a/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst +++ b/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst @@ -3,16 +3,16 @@ Decomposition Decomposition of fresh litter material into progressively more recalcitrant forms of soil organic matter is represented in CLM is -defined as a cascade of *k\ :math:`{}_{tras}`* transformations between -*m\ :math:`{}_{pool}`* decomposing coarse woody debris (CWD), litter, +defined as a cascade of :math:`{k}_{tras}` transformations between +:math:`{m}_{pool}` decomposing coarse woody debris (CWD), litter, and soil organic matter (SOM) pools, each defined at -*n\ :math:`{}_{lev}`* vertical levels. CLM allows the user to define, at +:math:`{n}_{lev}` vertical levels. CLM allows the user to define, at compile time, between 2 contrasting hypotheses of decomposition as embodied by two separate decomposition submodels: the CLM-CN pool structure used in CLM4.0, or a second pool structure, characterized by slower decomposition rates, based on the Century model (Parton et al. 1988). In addition, the user can choose, at compile time, whether to -allow *n\ :math:`{}_{lev}`* to equal 1, as in CLM4.0, or to equal the +allow :math:`{n}_{lev}` to equal 1, as in CLM4.0, or to equal the number of soil levels used for the soil hydrology (default 10). Figure 15.1. Schematic of decomposition model in CLM. @@ -21,41 +21,40 @@ Model is structured to allow different representations of the soil C and N decomposition cascade, as well as a vertically-explicit treatment of soil biogeochemistry. -|image| +.. image:: image1.png For the single-level model structure, the fundamental equation for carbon balance of the decomposing pools is: .. math:: + :label: 15.1) - \label{15.1)} \frac{\partial C_{i} }{\partial t} =R_{i} +\sum _{j\ne i}\left(i-r_{j} \right)T_{ji} k_{j} C_{j} -k_{i} C_{i} -where *C\ :math:`{}_{i}`* is the carbon content of pool *i*, -*R\ :math:`{}_{i}`* are the carbon inputs from plant tissues directly to -pool *i* (only non-zero for CWD and litter pools), *k\ :math:`{}_{i}`* -is the decay constant of pool *i*; *T\ :math:`{}_{ji}`* is the fraction +where :math:`{C}_{i}` is the carbon content of pool *i*, +:math:`{R}_{i}` are the carbon inputs from plant tissues directly to +pool *i* (only non-zero for CWD and litter pools), :math:`{k}_{i}` +is the decay constant of pool *i*; :math:`{T}_{ji}` is the fraction of carbon directed from pool *j* to pool *i* with fraction -*r\ :math:`{}_{j}`* lost as a respiration flux along the way. +:math:`{r}_{j}` lost as a respiration flux along the way. Adding the vertical dimension to the decomposing pools changes the balance equation to the following: .. math:: + :label: 15.2) - \label{15.2)} \begin{array}{l} {\frac{\partial C_{i} (z)}{\partial t} =R_{i} (z)+\sum _{i\ne j}\left(1-r_{j} \right)T_{ji} k_{j} (z)C_{j} (z) -k_{i} (z)C_{i} (z)} \\ {+\frac{\partial }{\partial z} \left(D(z)\frac{\partial C_{i} }{\partial z} \right)+\frac{\partial }{\partial z} \left(A(z)C_{i} \right)} \end{array} -where *C\ :math:`{}_{i}`\ (z)* is now defined at each model level, and -in volumetric (gC m\ :math:`{}^{-3}`) rather than areal (gC -m\ :math:`{}^{-2}`) units, along with *R\ :math:`{}_{i}`\ (z)* and -*k\ :math:`{}_{j}`\ (z)*. In addition, vertical transport is handled by +where :math:`{C}_{i}`\ (z) is now defined at each model level, and +in volumetric (gC m\ :sup:`-3`) rather than areal (gC m\ :sup:`-2`) units, along with :math:`{R}_{i}`\ (z) and +:math:`{k}_{j}`\ (z). In addition, vertical transport is handled by the last two terms, for diffusive and advective transport. In the base model, advective transport is set to zero, leaving only a diffusive flux with diffusivity *D(z)* defined for all decomposing carbon and nitrogen pools. Further discussion of the vertical distribution of carbon inputs -*R\ :math:`{}_{i}`\ (z)*, vertical turnover times -*k\ :math:`{}_{j}`\ (z)*, and vertical transport *D(z)* is below. +:math:`{R}_{i}`\ (z), vertical turnover times +:math:`{k}_{j}`\ (z), and vertical transport *D(z)* is below. Discussion of the vertical model and analysis of both decomposition structures is in Koven et al (2013). @@ -63,7 +62,7 @@ Figure 15.2. Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. -|image| +.. image:: image2.png CLM-CN Pool Structure, Rate Constants and Parameters --------------------------------------------------------- @@ -100,52 +99,52 @@ for the CLM-CN decomposition pool structure. +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ | | Biome-BGC | CLM-CN | | | +==========================+================================================+===============================================+===============+=========================================+ -| | *k\ :math:`{}_{disc1 }`*\ (d:math:`{}^{-1}`) | *k\ :math:`{}_{disc2}`* (hr:math:`{}^{-1}`) | *C:N ratio* | *Acceleration term (a:math:`{}_{i}`)* | +| | :math:`{k}_{disc1}`\ (d\ :sup:`-1`) | :math:`{k}_{disc2}` (hr\ :sup:`-1`) | *C:N ratio* | Acceleration term (:math:`{a}_{i}`) | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{Lit1}`* | 0.7 | 0.04892 | - | 1 | +| :math:`{k}_{Lit1}` | 0.7 | 0.04892 | - | 1 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{Lit2}`* | 0.07 | 0.00302 | - | 1 | +| :math:`{k}_{Lit2}` | 0.07 | 0.00302 | - | 1 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{Lit3}`* | 0.014 | 0.00059 | - | 1 | +| :math:`{k}_{Lit3}` | 0.014 | 0.00059 | - | 1 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{SOM1}`* | 0.07 | 0.00302 | 12 | 1 | +| :math:`{k}_{SOM1}` | 0.07 | 0.00302 | 12 | 1 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{SOM2}`* | 0.014 | 0.00059 | 12 | 1 | +| :math:`{k}_{SOM2}` | 0.014 | 0.00059 | 12 | 1 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{SOM3}`* | 0.0014 | 0.00006 | 10 | 5 | +| :math:`{k}_{SOM3}` | 0.0014 | 0.00006 | 10 | 5 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{SOM4}`* | 0.0001 | 0.000004 | 10 | 70 | +| :math:`{k}_{SOM4}` | 0.0001 | 0.000004 | 10 | 70 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| *k\ :math:`{}_{CWD}`* | 0.001 | 0.00004 | - | 1 | +| :math:`{k}_{CWD}` | 0.001 | 0.00004 | - | 1 | +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ The first column of Table 15.1 gives the rates as used for the Biome-BGC model, which uses a discrete-time model with a daily timestep. The second column of Table 15.1 shows the rates transformed for a one-hour discrete timestep typical of CLM-CN. The transformation is based on the -conversion of the initial discrete-time value (*k\ :math:`{}_{disc1}`*) -first to a continuous time value (*k\ :math:`{}_{cont}`*), then to the +conversion of the initial discrete-time value (:math:`{k}_{disc1}`) +first to a continuous time value (:math:`{k}_{cont}`), then to the new discrete-time value with a different timestep -(*k\ :math:`{}_{disc2}`*) , following Olson (1963): +(:math:`{k}_{disc2}`) , following Olson (1963): .. math:: + :label: ZEqnNum608251 - \label{ZEqnNum608251} k_{cont} =-\log \left(1-k_{disc1} \right) .. math:: + :label: ZEqnNum772630 - \label{ZEqnNum772630} k_{disc2} =1-\exp \left(-k_{cont} \frac{\Delta t_{2} }{\Delta t_{1} } \right) -where :math:`\Delta`\ *t\ :math:`{}_{1}`* (s) and -:math:`\Delta`\ *t\ :math:`{}_{2}`* (s) are the time steps of the +where :math:`\Delta`\ :math:`{t}_{1}` (s) and +:math:`\Delta`\ t\ :sub:`2` (s) are the time steps of the initial and new discrete-time models, respectively. Respiration fractions are parameterized for decomposition fluxes out of each litter and SOM pool. The respiration fraction (*rf*, unitless) is the fraction of the decomposition carbon flux leaving one of the litter -or SOM pools that is released as CO\ :math:`{}_{2}` due to heterotrophic +or SOM pools that is released as CO\ :sub:`2` due to heterotrophic respiration. Respiration fractions and exponential decay rates are estimated simultaneously from the results of microcosm decomposition experiments (Thornton, 1998). The same values are used in CLM-CN and @@ -156,24 +155,24 @@ Table 15.2. Respiration fractions for litter and SOM pools +---------------------------+-----------------------+ | Pool | *rf* | +===========================+=======================+ -| *rf\ :math:`{}_{Lit1}`* | 0.39 | +| :math:`{rf}_{Lit1}` | 0.39 | +---------------------------+-----------------------+ -| *rf\ :math:`{}_{Lit2}`* | 0.55 | +| :math:`{rf}_{Lit2}` | 0.55 | +---------------------------+-----------------------+ -| *rf\ :math:`{}_{Lit3}`* | 0.29 | +| :math:`{rf}_{Lit3}` | 0.29 | +---------------------------+-----------------------+ -| *rf\ :math:`{}_{SOM1}`* | 0.28 | +| :math:`{rf}_{SOM1}` | 0.28 | +---------------------------+-----------------------+ -| *rf\ :math:`{}_{SOM2}`* | 0.46 | +| :math:`{rf}_{SOM2}` | 0.46 | +---------------------------+-----------------------+ -| *rf\ :math:`{}_{SOM3}`* | 0.55 | +| :math:`{rf}_{SOM3}` | 0.55 | +---------------------------+-----------------------+ -| *rf\ :math:`{}_{SOM4}`* | 1.0\ :math:`{}^{a}` | +| :math:`{rf}_{SOM4}` | :math:`{1.0}^{a}` | +---------------------------+-----------------------+ -:math:`{}^{a}` The respiration fraction for pool SOM4 is 1.0 by +:sup:`a`:math:`{}^{a}` The respiration fraction for pool SOM4 is 1.0 by definition: since there is no pool downstream of SOM4, the entire carbon -flux leaving this pool is assumed to be respired as CO\ :math:`{}_{2}`. +flux leaving this pool is assumed to be respired as CO\ :sub:`2`. Century-based Pool Structure, Rate Constants and Parameters ---------------------------------------------------------------- @@ -190,7 +189,7 @@ section 15.8 for explanation) for the Century-based decomposition cascade. +------------+------------------------+-------------+-------------------------------------------+ -| | Turnover time (year) | C:N ratio | Acceleration term (*a\ :math:`{}_{i}`*) | +| | Turnover time (year) | C:N ratio | Acceleration term (:math:`{a}_{i}`) | +============+========================+=============+===========================================+ | CWD | 4.1 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ @@ -207,26 +206,24 @@ cascade. | SOM 3 | 270 | 11 | 675 | +------------+------------------------+-------------+-------------------------------------------+ -Likewise, values for the respiration fraction of Century-based structure -are in Table 15.4. +Likewise, values for the respiration fraction of Century-based structure are in Table 15.4. -Table 15.4. Respiration fractions for litter and SOM pools for -Century-based structure +Table 15.4. Respiration fractions for litter and SOM pools for Century-based structure +---------------------------+----------+ | Pool | *rf* | +===========================+==========+ -| *rf\ :math:`{}_{Lit1}`* | 0.55 | +| :math:`{rf}_{Lit1}` | 0.55 | +---------------------------+----------+ -| *rf\ :math:`{}_{Lit2}`* | 0.5 | +| :math:`{rf}_{Lit2}` | 0.5 | +---------------------------+----------+ -| *rf\ :math:`{}_{Lit3}`* | 0.5 | +| :math:`{rf}_{Lit3}` | 0.5 | +---------------------------+----------+ -| *rf\ :math:`{}_{SOM1}`* | f(txt) | +| :math:`{rf}_{SOM1}` | f(txt) | +---------------------------+----------+ -| *rf\ :math:`{}_{SOM2}`* | 0.55 | +| :math:`{rf}_{SOM2}` | 0.55 | +---------------------------+----------+ -| *rf\ :math:`{}_{SOM3}`* | 0.55 | +| :math:`{rf}_{SOM3}` | 0.55 | +---------------------------+----------+ Environmental modifiers on decomposition rate @@ -234,48 +231,46 @@ Environmental modifiers on decomposition rate These base rates are modified on each timestep by functions of the current soil environment. For the single-level model, there are two rate -modifiers, temperature (*r\ :math:`{}_{tsoil}`*, unitless) and moisture -(*r\ :math:`{}_{water}`*, unitless), both of which are calculated using +modifiers, temperature (:math:`{r}_{tsoil}`, unitless) and moisture +(:math:`{r}_{water}`, unitless), both of which are calculated using the average environmental conditions of the top five model levels (top 29 cm of soil column). For the vertically-resolved model, two additional environmental modifiers are calculated beyond the temperature and -moisture limitations: an oxygen scalar (*r\ :math:`{}_{oxygen}`*, -unitless), and a depth scalar (*r\ :math:`{}_{depth}`*, unitless). +moisture limitations: an oxygen scalar (:math:`{r}_{oxygen}`, +unitless), and a depth scalar (:math:`{r}_{depth}`, unitless). -The Temperature scalar *r\ :math:`{}_{tsoil}`* is calculated in CLM -using a *Q\ :math:`{}_{10}`* approach, with *Q\ :math:`{}_{10}`\ =1.5:* +The Temperature scalar :math:`{r}_{tsoil}` is calculated in CLM +using a :math:`{Q}_{10}` approach, with :math:`{Q}_{10} = 1.5`. .. math:: + :label: 15.5) - \label{15.5)} r_{tsoil} =Q_{10} ^{\left(\frac{T_{soil,\, j} -T_{ref} }{10} \right)} -where *j* is the soil layer index, *T\ :math:`{}_{soil,j}`* (K) is the -temperature of soil level *j*. The reference temperature -*T\ :math:`{}_{ref}`* = 25C. +where *j* is the soil layer index, :math:`{T}_{soil,j}` (K) is the +temperature of soil level *j*. The reference temperature :math:`{T}_{ref}` = 25C. -The rate scalar for soil water potential (*r\ :math:`{}_{water}`*, +The rate scalar for soil water potential (:math:`{r}_{water}`, unitless) is calculated using a relationship from Andrén and Paustian (1987) and supported by additional data in Orchard and Cook (1983): .. math:: + :label: 15.6) - \label{15.6)} r_{water} =\sum _{j=1}^{5}\left\{\begin{array}{l} {0\qquad {\rm for\; }\Psi _{j} <\Psi _{\min } } \\ {\frac{\log \left({\Psi _{\min } \mathord{\left/ {\vphantom {\Psi _{\min } \Psi _{j} }} \right. \kern-\nulldelimiterspace} \Psi _{j} } \right)}{\log \left({\Psi _{\min } \mathord{\left/ {\vphantom {\Psi _{\min } \Psi _{\max } }} \right. \kern-\nulldelimiterspace} \Psi _{\max } } \right)} w_{soil,\, j} \qquad {\rm for\; }\Psi _{\min } \le \Psi _{j} \le \Psi _{\max } } \\ {1\qquad {\rm for\; }\Psi _{j} >\Psi _{\max } \qquad \qquad } \end{array}\right\} -where :math:`\Psi`\ *:math:`{}_{j}`* is the soil water potential in -layer *j*, :math:`\Psi`\ *:math:`{}_{min}`* is a lower limit for soil +where :math:`{\Psi}_{j}` is the soil water potential in +layer *j*, :math:`{\Psi}_{min}` is a lower limit for soil water potential control on decomposition rate (set to -10 MPa). -:math:`\Psi`\ *:math:`{}_{sat,j}`* (MPa) is the saturated soil water -potential, calculated using the multivariate regression model from Cosby -et al. (1984): +:math:`{\Psi}_{sat,j}` (MPa) is the saturated soil water +potential, calculated using the multivariate regression model from Cosby et al. (1984): .. math:: + :label: 15.7) - \label{15.7)} \Psi _{sat,\, j} =-\left(9.8e-5\right)\exp \left(\left(1.54-0.0095P_{sand,\, j} +0.0063\left(100-P_{sand,\, j} -P_{clay,\, j} \right)\right)\log \left(10\right)\right) -where *P\ :math:`{}_{sand,j}`* and *P\ :math:`{}_{clay,j}`* are the +where :math:`{P}_{sand,j}` and :math:`{P}_{clay,j}` are the volume percentages of sand and clay in soil layer *j*. For frozen soils, the bulk of the rapid dropoff in decomposition with @@ -284,32 +279,32 @@ potential is limited by temperature in the supercooled water formulation of Niu and Yang (2006), .. math:: + :label: 15.8) - \label{15.8)} \psi \left(T\right)=-\frac{L_{f} \left(T-T_{f} \right)}{10^{3} T} An additional frozen decomposition limitation can be specified using a -‘frozen Q\ :math:`{}_{10}`’ following Koven et al. (2011), however the -default value of this is the same as the unfrozen Q\ :math:`{}_{10}` +‘frozen Q\ :sub:`10` following Koven et al. (2011), however the +default value of this is the same as the unfrozen Q\ :sub:`10` value, and therefore the basic hypothesis is that frozen respiration is limited by liquid water availability, and can be modeled following the same approach as thawed but dry soils. -An additional rate scalar, *r\ :math:`{}_{oxygen}`* is enabled when the -CH\ :math:`{}_{4}` submodel is used (set equal to 1 for the single layer -model or when the CH\ :math:`{}_{4}` submodel is disabled). This limits +An additional rate scalar, :math:`{r}_{oxygen}` is enabled when the +CH\ :sub:`4` submodel is used (set equal to 1 for the single layer +model or when the CH\ :sub:`4` submodel is disabled). This limits decomposition when there is insufficient molecular oxygen to satisfy -stoichiometric demand (1 mol O\ :math:`{}_{2}` consumed per mol -CO\ :math:`{}_{2}` produced) from heterotrophic decomposers, and supply +stoichiometric demand (1 mol O\ :sub:`2` consumed per mol +CO\ :sub:`2` produced) from heterotrophic decomposers, and supply from diffusion through soil layers (unsaturated and saturated) or -aerenchyma (Chapter 19). A minimum value of *r\ :math:`{}_{oxygen}`* is +aerenchyma (Chapter 19). A minimum value of :math:`{r}_{oxygen}` is set at 0.2, with the assumption that oxygen within organic tissues can supply the necessary stoichiometric demand at this rate. This value lies between estimates of 0.025–0.1 (Frolking et al. 2001), and 0.35 (Wania et al. 2009); the large range of these estimates poses a large unresolved uncertainty. -Lastly, a possible explicit depth dependence, *r\ :math:`{}_{depth}`*, +Lastly, a possible explicit depth dependence, :math:`{r}_{depth}`, (set equal to 1 for the single layer model) can be applied to soil C decomposition rates to account for processes other than temperature, moisture, and anoxia that can limit decomposition. This depth dependence @@ -322,19 +317,17 @@ includes these unresolved depth controls via an exponential decrease in the soil turnover time with depth: .. math:: + :label: 15.9) - \label{15.9)} r_{depth} =\exp \left(-\frac{z}{z_{\tau } } \right) -where *z\ :math:`{}_{\tau}`* is the e-folding depth for decomposition, -set by default to 0.5m. +where :math:`{z}_{\tau}` is the e-folding depth for decomposition, set by default to 0.5m. -The combined decomposition rate scalar (*r\ :math:`{}_{total}`*, -unitless) is: +The combined decomposition rate scalar (:math:`{r}_{total}`,unitless) is: .. math:: + :label: 15.10) - \label{15.10)} r_{total} =r_{tsoil} r_{water} r_{oxygen} r_{depth} . N-limitation of Decomposition Fluxes @@ -347,35 +340,34 @@ nitrogen supply. The general case is described here first, referring to a generic decomposition flux from an “upstream†pool (*u*) to a “downstream†pool (*d*), with an intervening loss due to respiration. The potential carbon flux out of the upstream pool -(*CF\ :math:`{}_{pot,u}`*, gC m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is: +(:math:`{CF}_{pot,u}`, gC m\ :sup:`-2` s\ :sup:`-1`) is: .. math:: + :label: 15.11) - \label{15.11)} CF_{pot,\, u} =CS_{u} k_{u} -where *CS\ :math:`{}_{u}`* (gC m\ :math:`{}^{-2}`) is the initial mass -in the upstream pool and *k\ :math:`{}_{u}`* is the decay rate constant -(s:math:`{}^{-1}`) for the upstream pool, adjusted for temperature and +where :math:`{CS}_{u}` (gC m\ :sup:`-2`) is the initial mass +in the upstream pool and :math:`{k}_{u}` is the decay rate constant +(s:sup:`-1`) for the upstream pool, adjusted for temperature and moisture conditions. Depending on the C:N ratios of the upstream and downstream pools and the amount of carbon lost in the transformation due to respiration (the respiration fraction), the execution of this potential carbon flux can generate either a source or a sink of new mineral nitrogen -(*NF\ :math:`{}_{pot\_min,u}`\ :math:`{}_{\rightarrow}`\ :math:`{}_{d}`*, -gN m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`). The governing equation +(:math:`{NF}_{pot\_min,u}`\ :math:`{}_{\rightarrow}`\ :math:`{}_{d}`, gN m\ :sup:`-2` s\ :sup:`-1`). The governing equation (Thornton and Rosenbloom, 2005) is: .. math:: + :label: 15.12) - \label{15.12)} NF_{pot\_ min,\, u\to d} =\frac{CF_{pot,\, u} \left(1-rf_{u} -\frac{CN_{d} }{CN_{u} } \right)}{CN_{d} } -where *rf\ :math:`{}_{u}`* is the respiration fraction for fluxes -leaving the upstream pool, *CN\ :math:`{}_{u}`* and *CN\ :math:`{}_{d}`* +where :math:`{rf}_{u}` is the respiration fraction for fluxes +leaving the upstream pool, :math:`{CN}_{u}` and :math:`{CN}_{d}` are the C:N ratios for upstream and downstream pools, respectively. Negative values of -*NF\ :math:`{}_{pot\_min,u}`\ :math:`{}_{\rightarrow}`\ :math:`{}_{d}`* +:math:`{NF}_{pot\_min,u}`\ :math:`{}_{\rightarrow}`\ :math:`{}_{d}` indicate that the decomposition flux results in a source of new mineral nitrogen, while positive values indicate that the potential decomposition flux results in a sink (demand) for mineral nitrogen. @@ -385,38 +377,38 @@ individual pools in the decomposition cascade, for the example of the CLM-CN pool structure, are given as: .. math:: + :label: 15.13) - \label{15.13)} CF_{pot,\, Lit1} ={CS_{Lit1} k_{Lit1} r_{total} \mathord{\left/ {\vphantom {CS_{Lit1} k_{Lit1} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 15.14) - \label{15.14)} CF_{pot,\, Lit2} ={CS_{Lit2} k_{Lit2} r_{total} \mathord{\left/ {\vphantom {CS_{Lit2} k_{Lit2} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 15.15) - \label{15.15)} CF_{pot,\, Lit3} ={CS_{Lit3} k_{Lit3} r_{total} \mathord{\left/ {\vphantom {CS_{Lit3} k_{Lit3} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 15.16) - \label{15.16)} CF_{pot,\, SOM1} ={CS_{SOM1} k_{SOM1} r_{total} \mathord{\left/ {\vphantom {CS_{SOM1} k_{SOM1} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 15.17) - \label{15.17)} CF_{pot,\, SOM2} ={CS_{SOM2} k_{SOM2} r_{total} \mathord{\left/ {\vphantom {CS_{SOM2} k_{SOM2} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 15.18) - \label{15.18)} CF_{pot,\, SOM3} ={CS_{SOM3} k_{SOM3} r_{total} \mathord{\left/ {\vphantom {CS_{SOM3} k_{SOM3} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: + :label: 15.19) - \label{15.19)} CF_{pot,\, SOM4} ={CS_{SOM4} k_{SOM4} r_{total} \mathord{\left/ {\vphantom {CS_{SOM4} k_{SOM4} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} where the factor (1/:math:`\Delta`\ *t*) is included because the rate @@ -427,43 +419,43 @@ again for the example of the CLM-CN pool structure (the CENTURY structure will be similar but without the different terminal step): .. math:: + :label: ZEqnNum934998 - \label{ZEqnNum934998} NF_{pot\_ min,\, Lit1\to SOM1} ={CF_{pot,\, Lit1} \left(1-rf_{Lit1} -\frac{CN_{SOM1} }{CN_{Lit1} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit1} \left(1-rf_{Lit1} -\frac{CN_{SOM1} }{CN_{Lit1} } \right) CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } .. math:: + :label: 15.21) - \label{15.21)} NF_{pot\_ min,\, Lit2\to SOM2} ={CF_{pot,\, Lit2} \left(1-rf_{Lit2} -\frac{CN_{SOM2} }{CN_{Lit2} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit2} \left(1-rf_{Lit2} -\frac{CN_{SOM2} }{CN_{Lit2} } \right) CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: + :label: 15.22) - \label{15.22)} NF_{pot\_ min,\, Lit3\to SOM3} ={CF_{pot,\, Lit3} \left(1-rf_{Lit3} -\frac{CN_{SOM3} }{CN_{Lit3} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit3} \left(1-rf_{Lit3} -\frac{CN_{SOM3} }{CN_{Lit3} } \right) CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } .. math:: + :label: 15.23) - \label{15.23)} NF_{pot\_ min,\, SOM1\to SOM2} ={CF_{pot,\, SOM1} \left(1-rf_{SOM1} -\frac{CN_{SOM2} }{CN_{SOM1} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM1} \left(1-rf_{SOM1} -\frac{CN_{SOM2} }{CN_{SOM1} } \right) CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: + :label: 15.24) - \label{15.24)} NF_{pot\_ min,\, SOM2\to SOM3} ={CF_{pot,\, SOM2} \left(1-rf_{SOM2} -\frac{CN_{SOM3} }{CN_{SOM2} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM2} \left(1-rf_{SOM2} -\frac{CN_{SOM3} }{CN_{SOM2} } \right) CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } .. math:: + :label: 15.25) - \label{15.25)} NF_{pot\_ min,\, SOM3\to SOM4} ={CF_{pot,\, SOM3} \left(1-rf_{SOM3} -\frac{CN_{SOM4} }{CN_{SOM3} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM3} \left(1-rf_{SOM3} -\frac{CN_{SOM4} }{CN_{SOM3} } \right) CN_{SOM4} }} \right. \kern-\nulldelimiterspace} CN_{SOM4} } .. math:: + :label: ZEqnNum473594 - \label{ZEqnNum473594} NF_{pot\_ min,\, SOM4} =-{CF_{pot,\, SOM4} \mathord{\left/ {\vphantom {CF_{pot,\, SOM4} CN_{SOM4} }} \right. \kern-\nulldelimiterspace} CN_{SOM4} } where the special form of Eq. arises because there is no SOM pool downstream of SOM4 in the converging cascade: all carbon fluxes leaving -that pool are assumed to be in the form of respired CO\ :math:`{}_{2}`, +that pool are assumed to be in the form of respired CO\ :sub:`2`, and all nitrogen fluxes leaving that pool are assumed to be sources of new mineral nitrogen. @@ -476,11 +468,9 @@ nitrogen, the total immobilization demand, and the total demand for soil mineral nitrogen to support new plant growth. The potential mineral nitrogen fluxes from Eqs. - are evaluated, summing all the positive fluxes to generate the total potential nitrogen immobilization flux -(*NF\ :math:`{}_{immob\_demand}`*, gN m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`), and summing absolute values of all the negative +(:math:`{NF}_{immob\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`), and summing absolute values of all the negative fluxes to generate the total nitrogen mineralization flux -(*NF\ :math:`{}_{gross\_nmin}`*, gN m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`). Since *NF\ :math:`{}_{griss\_nmin}`* is a source of +(:math:`{NF}_{gross\_nmin}`, gN m\ :sup:`-2` s\ :sup:`-1`). Since :math:`{NF}_{griss\_nmin}` is a source of new mineral nitrogen to the soil mineral nitrogen pool it is not limited by the availability of soil mineral nitrogen, and is therefore an actual as opposed to a potential flux. @@ -488,42 +478,39 @@ as opposed to a potential flux. N Competition between plant uptake and soil immobilization fluxes ---------------------------------------------------------------------- -Once *NF\ :math:`{}_{immob\_demand }`* is known, the competition between +Once :math:`{NF}_{immob\_demand }` is known, the competition between plant and microbial nitrogen demand can be resolved. Mineral nitrogen in -the soil pool (*NS\ :math:`{}_{sminn}`*, gN m\ :math:`{}^{-2}`) at the +the soil pool (:math:`{NS}_{sminn}`, gN m\ :sup:`-2`) at the beginning of the timestep is considered the available supply. Total -demand for mineral nitrogen from this pool -(*NF\ :math:`{}_{total\_demand}`*, gN m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) is: +demand for mineral nitrogen from this pool (:math:`{NF}_{total\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`) is: .. math:: + :label: 15.27) - \label{15.27)} NF_{total\_ demand} =NF_{immob\_ demand} +NF_{plant\_ demand\_ soil} -If *NF\ :math:`{}_{total\_demand}`*\ :math:`\Delta`\ *t* :math:`<` -*NS\ :math:`{}_{sminn}`*, then the available pool is large enough to +If :math:`{NF}_{total\_demand}`\ :math:`\Delta`\ *t* :math:`<` +:math:`{NS}_{sminn}`, then the available pool is large enough to meet both plant and microbial demand, and neither plant growth nor immobilization steps in the decomposition cascade are limited by nitrogen availability in the timestep. In that case, the signaling -variables *f\ :math:`{}_{plant\_demand}`* and -*f\ :math:`{}_{immob\_demand}`* are both set to 1.0, where -*f\ :math:`{}_{plant\_demand}`* is defined and used in section 15.4, and -*f\ :math:`{}_{immob\_demand}`* is the fraction of potential -immobilization demand that can be met given current supply of mineral -nitrogen. - -If *NF\ :math:`{}_{total\_demand}`*\ :math:`\Delta`\ *t* -:math:`\mathrm{\ge}` *NS\ :math:`{}_{sminn}`*, then there is not enough +variables :math:`{f}_{plant\_demand}` and +:math:`{f}_{immob\_demand}` are both set to 1.0, where +:math:`{f}_{plant\_demand}` is defined and used in section 15.4, and +:math:`{f}_{immob\_demand}` is the fraction of potential +immobilization demand that can be met given current supply of mineral nitrogen. + +If :math:`{NF}_{total\_demand}`\ :math:`\Delta`\ *t* +:math:`\mathrm{\ge}` :math:`{NS}_{sminn}`, then there is not enough mineral nitrogen to meet the combined demands for plant growth and heterotrophic immobilization, and both of these processes proceed at lower-than-potential rates, defined by the fractions -*f\ :math:`{}_{plant\_demand}`* and *f\ :math:`{}_{immob\_demand}`*, +:math:`{f}_{plant\_demand}` and :math:`{f}_{immob\_demand}`, where: .. math:: + :label: 15.28) - \label{15.28)} f_{plant\_ demand} =f_{immob\_ demand} =\frac{NS_{sminn} }{\Delta t\, NF_{total\_ demand} } This treatment of competition for nitrogen as a limiting resource is @@ -536,116 +523,116 @@ fraction of the available resource. Final Decomposition Fluxes ------------------------------- -With *f\ :math:`{}_{immob\_demand}`* known, final decomposition fluxes +With :math:`{f}_{immob\_demand}` known, final decomposition fluxes can be calculated. Actual carbon fluxes leaving the individual litter and SOM pools, again for the example of the CLM-CN pool structure (the CENTURY structure will be similar but, again without the different terminal step), are calculated as: .. math:: + :label: 15.29) - \label{15.29)} CF_{Lit1} =\left\{\begin{array}{l} {CF_{pot,\, Lit1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {CF_{pot,\, Lit1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} .. math:: + :label: 15.30) - \label{15.30)} CF_{Lit2} =\left\{\begin{array}{l} {CF_{pot,\, Lit2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {CF_{pot,\, Lit2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} .. math:: + :label: 15.31) - \label{15.31)} CF_{Lit3} =\left\{\begin{array}{l} {CF_{pot,\, Lit3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {CF_{pot,\, Lit3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} .. math:: + :label: 15.32) - \label{15.32)} CF_{SOM1} =\left\{\begin{array}{l} {CF_{pot,\, SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {CF_{pot,\, SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} .. math:: + :label: 15.33) - \label{15.33)} CF_{SOM2} =\left\{\begin{array}{l} {CF_{pot,\, SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {CF_{pot,\, SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} .. math:: + :label: 15.34) - \label{15.34)} CF_{SOM3} =\left\{\begin{array}{l} {CF_{pot,\, SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {CF_{pot,\, SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} .. math:: + :label: 15.35) - \label{15.35)} CF_{SOM4} =CF_{pot,\, SOM4} Heterotrophic respiration fluxes (losses of carbon as -CO\ :math:`{}_{2}` to the atmosphere) are: +CO\ :sub:`2` to the atmosphere) are: .. math:: + :label: 15.36) - \label{15.36)} CF_{Lit1,\, HR} =CF_{Lit1} rf_{Lit1} .. math:: + :label: 15.37) - \label{15.37)} CF_{Lit2,\, HR} =CF_{Lit2} rf_{Lit2} .. math:: + :label: 15.38) - \label{15.38)} CF_{Lit3,\, HR} =CF_{Lit3} rf_{Lit3} .. math:: + :label: 15.39) - \label{15.39)} CF_{SOM1,\, HR} =CF_{SOM1} rf_{SOM1} .. math:: + :label: 15.40) - \label{15.40)} CF_{SOM2,\, HR} =CF_{SOM2} rf_{SOM2} .. math:: + :label: 15.41) - \label{15.41)} CF_{SOM3,\, HR} =CF_{SOM3} rf_{SOM3} .. math:: + :label: 15.42) - \label{15.42)} CF_{SOM4,\, HR} =CF_{SOM4} rf_{SOM4} Transfers of carbon from upstream to downstream pools in the decomposition cascade are given as: .. math:: + :label: 15.43) - \label{15.43)} CF_{Lit1,\, SOM1} =CF_{Lit1} \left(1-rf_{Lit1} \right) .. math:: + :label: 15.44) - \label{15.44)} CF_{Lit2,\, SOM2} =CF_{Lit2} \left(1-rf_{Lit2} \right) .. math:: + :label: 15.45) - \label{15.45)} CF_{Lit3,\, SOM3} =CF_{Lit3} \left(1-rf_{Lit3} \right) .. math:: + :label: 15.46) - \label{15.46)} CF_{SOM1,\, SOM2} =CF_{SOM1} \left(1-rf_{SOM1} \right) .. math:: + :label: 15.47) - \label{15.47)} CF_{SOM2,\, SOM3} =CF_{SOM2} \left(1-rf_{SOM2} \right) .. math:: + :label: 15.48) - \label{15.48)} CF_{SOM3,\, SOM4} =CF_{SOM3} \left(1-rf_{SOM3} \right) In accounting for the fluxes of nitrogen between pools in the @@ -658,33 +645,33 @@ or from the downstream pool to the soil mineral nitrogen pool pools in the decomposition cascade are given as: .. math:: + :label: 15.49) - \label{15.49)} NF_{Lit1,\, SOM1} ={CF_{Lit1} \mathord{\left/ {\vphantom {CF_{Lit1} CN_{Lit1} }} \right. \kern-\nulldelimiterspace} CN_{Lit1} } .. math:: + :label: 15.50) - \label{15.50)} NF_{Lit2,\, SOM2} ={CF_{Lit2} \mathord{\left/ {\vphantom {CF_{Lit2} CN_{Lit2} }} \right. \kern-\nulldelimiterspace} CN_{Lit2} } .. math:: + :label: 15.51) - \label{15.51)} NF_{Lit3,\, SOM3} ={CF_{Lit3} \mathord{\left/ {\vphantom {CF_{Lit3} CN_{Lit3} }} \right. \kern-\nulldelimiterspace} CN_{Lit3} } .. math:: + :label: 15.52) - \label{15.52)} NF_{SOM1,\, SOM2} ={CF_{SOM1} \mathord{\left/ {\vphantom {CF_{SOM1} CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } .. math:: + :label: 15.53) - \label{15.53)} NF_{SOM2,\, SOM3} ={CF_{SOM2} \mathord{\left/ {\vphantom {CF_{SOM2} CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: + :label: 15.54) - \label{15.54)} NF_{SOM3,\, SOM4} ={CF_{SOM3} \mathord{\left/ {\vphantom {CF_{SOM3} CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } Corresponding fluxes to or from the soil mineral nitrogen pool depend on @@ -692,38 +679,38 @@ whether the decomposition step is an immobilization flux or a mineralization flux: .. math:: + :label: 15.55) - \label{15.55)} NF_{sminn,\, Lit1\to SOM1} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit1\to SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {NF_{pot\_ min,\, Lit1\to SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} .. math:: + :label: 15.56) - \label{15.56)} NF_{sminn,\, Lit2\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit2\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {NF_{pot\_ min,\, Lit2\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} .. math:: + :label: 15.57) - \label{15.57)} NF_{sminn,\, Lit3\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit3\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {NF_{pot\_ min,\, Lit3\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} .. math:: + :label: 15.58) - \label{15.58)} NF_{sminn,SOM1\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM1\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {NF_{pot\_ min,\, SOM1\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} .. math:: + :label: 15.59) - \label{15.59)} NF_{sminn,SOM2\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM2\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {NF_{pot\_ min,\, SOM2\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} .. math:: + :label: 15.60) - \label{15.60)} NF_{sminn,SOM3\to SOM4} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM3\to SOM4} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {NF_{pot\_ min,\, SOM3\to SOM4} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} .. math:: + :label: 15.61) - \label{15.61)} NF_{sminn,\, SOM4} =NF_{pot\_ min,\, SOM4} Vertical Distribution and Transport of Decomposing C and N pools @@ -753,8 +740,8 @@ parameterization based on that of Koven et al. (2009) is used: the diffusivity parameter is constant through the active layer, and decreases linearly from the base of the active layer to zero at a set depth (default 3m); the default permafrost diffusivity is 5 -cm\ :math:`{}^{2}`/yr. For non-permafrost soils, the default diffusivity -is 1 cm\ :math:`{}^{2}`/yr. +cm\ :sup:`2`/yr. For non-permafrost soils, the default diffusivity +is 1 cm\ :sup:`2`/yr. Model Equilibration ------------------------ @@ -769,23 +756,23 @@ decomposition†(Thornton and Rosenbloom, 2005) is used. The fundamental idea of this approach is to allow fluxes between the various pools (both turnover-defined and vertically-defined fluxes) adjust rapidly, while keeping the pool sizes themselves small so that they can fill quickly. -To do this, the base decomposition rate *k\ :math:`{}_{i}`* for each -pool *i* is accelerated by a term *a\ :math:`{}_{i}`* such that the slow +To do this, the base decomposition rate :math:`{k}_{i}` for each +pool *i* is accelerated by a term :math:`{a}_{i}` such that the slow pools are collapsed onto an approximately annual timescale (Koven et al. 2013). Accelerating the pools beyond this timescale distorts the seasonal and/or diurnal cycles of decomposition and N mineralization, thus leading to a substantially different ecosystem productivity than the full model. For the vertical model, the vertical transport terms are -also accelerated by the same term *a\ :math:`{}_{i}`*, as is the +also accelerated by the same term :math:`{a}_{i}`, as is the radioactive decay when :math:`{}^{14}`\ C is enabled, following the same principle of keeping fluxes between pools (or fluxes lost to decay) close to the full model while keeping the pools sizes small. When leaving the accelerated decomposition mode, the concentration of C and N in pools that had been accelerated are multiplied by the same term -*a\ :math:`{}_{i}`*, to bring the model into approximate equilibrium. +:math:`{a}_{i}`, to bring the model into approximate equilibrium. Note that in CLM, the model can also transition into accelerated decomposition mode from the standard mode (by dividing the pools by -*a\ :math:`{}_{i}`*), and that the transitions into and out of +:math:`{a}_{i}`), and that the transitions into and out of accelerated decomposition mode are handled automatically by CLM upon loading from restart files (which preserve information about the mode of the model when restart files were written). @@ -793,5 +780,3 @@ the model when restart files were written). The acceleration terms for the two decomposition cascades are shown in Tables 15.1 and 15.3. -.. |image| image:: image1 -.. |image| image:: image2 diff --git a/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst b/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst index b6dd7a2b1a..07bb1567f9 100644 --- a/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst @@ -1,7 +1,3 @@ -.. math:: 1 - -.. math:: 1 - External Nitrogen Cycle =========================== @@ -19,13 +15,12 @@ sinks in the external nitrogen cycle. CLM includes two separate treatments of the slow nitrogen cycle. The first is the original CLM-CN formulations, which includes a single soil mineral nitrogen pool to represent both -NO\ :math:`{}_{3}`\ :math:`{}^{-}` and -NH\ :math:`{}_{4}`\ :math:`{}^{+}`, and with nitrogen losses via +NO\ :sub:`3`\ :sup:`-` and NH\ :sub:`4`\ :sup:`+`, and with nitrogen losses via denitrification calculated as a constant fraction of mineralization plus a fixed first-order loss of unutilized mineral nitrogen at the end of every timestep. The second is based on the Century N-gas model; this -includes separate NH\ :math:`{}_{4}`\ :math:`{}^{+}` and -NO\ :math:`{}_{3}`\ :math:`{}^{-}`\ :math:`{}^{ }`\ pools, as well as +includes separate NH\ :sub:`4`\ :sup:`+` and +NO\ :sub:`3`\ :sup:`-` pools, as well as environmentally controlled nitrification and denitrification rates. Both are described below. @@ -34,42 +29,41 @@ Atmospheric Nitrogen Deposition CLM uses a single variable to represent the total deposition of mineral nitrogen onto the land surface, combining wet and dry deposition of -NO\ :math:`{}_{y}` and NH\ :math:`{}_{x}` as a single flux -(*NF\ :math:`{}_{ndep\_sminn}`*, gN m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`). This flux is intended to represent total reactive +NO\ :sub:`y` and NH\ :sub:`x` as a single flux +(:math:`{NF}_{ndep\_sminn}`, gN m\ :sup:`-2` s\ :sup:`-1`). This flux is intended to represent total reactive nitrogen deposited to the land surface which originates from the following natural and anthropogenic sources (Galloway et al. 2004): -formation of NO\ :math:`{}_{x}` during lightning, -NO\ :math:`{}_{x }`\ and NH\ :math:`{}_{3}` emission from wildfire, -NO\ :math:`{}_{x}` emission from natural soils, NH\ :math:`{}_{3}` +formation of NO\ :sub:`x` during lightning, +NO\ :math:`{}_{x }`\ and NH\ :sub:`3` emission from wildfire, +NO\ :sub:`x` emission from natural soils, NH\ :sub:`3` emission from natural soils, vegetation, and wild animals, -NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` emission during fossil fuel -combustion (both thermal and fuel NO\ :math:`{}_{x}` production), -NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` emission from other industrial -processes, NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` emission from fire -associated with deforestation, NO\ :math:`{}_{x}` and NH\ :math:`{}_{3}` -emission from agricultural burning, NO\ :math:`{}_{x}` emission from -agricultural soils, NH\ :math:`{}_{3}` emission from agricultural crops, -NH\ :math:`{}_{3}` emission from agricultural animal waste, and -NH\ :math:`{}_{3}` emission from human waste and waste water. The +NO\ :sub:`x` and NH\ :sub:`3` emission during fossil fuel +combustion (both thermal and fuel NO\ :sub:`x` production), +NO\ :sub:`x` and NH\ :sub:`3` emission from other industrial +processes, NO\ :sub:`x` and NH\ :sub:`3` emission from fire +associated with deforestation, NO\ :sub:`x` and NH\ :sub:`3` +emission from agricultural burning, NO\ :sub:`x` emission from +agricultural soils, NH\ :sub:`3` emission from agricultural crops, +NH\ :sub:`3` emission from agricultural animal waste, and +NH\ :sub:`3` emission from human waste and waste water. The deposition flux is provided as a spatially and (potentially) temporally varying dataset (see section 2.2.3 for a description of the default input dataset). In the CLM-CN mineral N pool model, the nitrogen deposition flux is assumed to enter the soil mineral nitrogen pool -(*NS\ :math:`{}_{sminn}`*) directly; while in the Century-based model, +(:math:`{NS}_{sminn}`) directly; while in the Century-based model, all of the nitrogen is assumed to enter the -NH\ :math:`{}_{4}`\ :math:`{}^{+}` pool. Real pathways for wet and dry +NH\ :sub:`4`\ :sup:`+` pool. Real pathways for wet and dry nitrogen deposition can be more complex than currently represented in the CLM-CN, including release from melting snowpack and direct foliar -uptake of deposited NO\ :math:`{}_{y}` (e.g. Tye et al. 2005; Vallano +uptake of deposited NO\ :sub:`y` (e.g. Tye et al. 2005; Vallano and Sparks, 2007). Biological Nitrogen Fixation --------------------------------- -The fixation of new reactive nitrogen from atmospheric N\ :math:`{}_{2}` +The fixation of new reactive nitrogen from atmospheric N\ :sub:`2` by soil microorganisms is an important component of both preindustrial and modern-day nitrogen budgets, but a mechanistic understanding of global-scale controls on biological nitrogen fixation (BNF) is still @@ -77,8 +71,7 @@ only poorly developed (Cleveland et al. 1999; Galloway et al. 2004). Cleveland et al. (1999) suggested empirical relationships that predict BNF as a function of either evapotranspiration rate or net primary productivity for natural vegetation. CLM assumes that BNF is a function -of net primary production (*CF\ :math:`{}_{ann\_NPP}`*, gC -m\ :math:`{}^{-2}` y\ :math:`{}^{-1}`). The rationale for choosing net +of net primary production (:math:`{CF}_{ann\_NPP}`, gC m\ :sup:`-2` y\ :sup:`-1`). The rationale for choosing net primary production over evapotranspiration as the predictor is that the two are well-correlated (Parton et al. 1993; Running et al. 1989), and the use of primary production also introduces a known dependence of BNF @@ -86,18 +79,17 @@ on the carbon supply to nitrogen fixing microorganisms (Cleveland et al. 1999). The expression used is: .. math:: + :label: ZEqnNum802819: - \label{ZEqnNum802819} NF_{nfix,sminn} ={1.8\left(1-\exp \left(-0.003{\kern 1pt} CF_{ann\_ NPP} \right)\right)\mathord{\left/ {\vphantom {1.8\left(1-\exp \left(-0.003{\kern 1pt} CF_{ann\_ NPP} \right)\right) \left(86400\cdot 365\right)}} \right. \kern-\nulldelimiterspace} \left(86400\cdot 365\right)} -where *NF\ :math:`{}_{nfix,sminn}`* (gN m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) is the rate of BNF. Eq. is plotted over a range of +where :math:`{NF}_{nfix,sminn}` (gN m\ :sup:`-2` s\ :sup:`-1`) is the rate of BNF. Eq. is plotted over a range of annual NPP in Figure 16.1. Figure 16.1. Biological nitrogen fixation as a function of annual net primary production. -|image| +.. image:: image1.png Because of the empirical nature of this NPP-BNF relationship, the timescale for calculating NPP and thus BNF is unconstrained. Using @@ -111,7 +103,7 @@ and BNF calculated from that using equation 16.1. As with Atmospheric N deposition, BNF N inputs are added directly to the mineral N pools. In the CLM-CN N model, this is the single mineral N pool; in the Century-based model, this is the -NH\ :math:`{}_{4}`\ :math:`{}^{+}` pool. +NH\ :sub:`4`\ :sup:`+` pool. Nitrification and Denitrification Losses of Nitrogen --------------------------------------------------------- @@ -129,8 +121,8 @@ acceptor supporting the metabolism of heterotrophs, but anaerobic conditions favor the activity of soil heterotrophs which use nitrate as an electron acceptor (e.g. *Pseudomonas* and *Clostridium*) supporting respiration. This process, known as denitrification, results in the -transformation of nitrate to gaseous N\ :math:`{}_{2}`, with smaller -associated production of NO\ :math:`{}_{x}` and N\ :math:`{}_{2}`\ O. It +transformation of nitrate to gaseous N\ :sub:`2`, with smaller +associated production of NO\ :sub:`x` and N\ :sub:`2`\ O. It is typically assumed that nitrogen fixation and denitrification were approximately balanced in the preindustrial biosphere (Galloway et al. 2004). It is likely that denitrification can occur within anaerobic @@ -155,46 +147,46 @@ Denitrification fluxes associated with gross mineralization in the decomposition cascade are calculated as follows: .. math:: + :label: 16.2) - \label{16.2)} NF_{denit,Lit1\to SOM1} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} >0} \\ {-NF_{pot\_ min,Lit1\to SOM1} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} \le 0} \end{array}\right. .. math:: + :label: 16.3) - \label{16.3)} NF_{denit,Lit2\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} >0} \\ {-NF_{pot\_ min,Lit2\to SOM2} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} \le 0} \end{array}\right. .. math:: + :label: 16.4) - \label{16.4)} NF_{denit,Lit3\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} >0} \\ {-NF_{pot\_ min,Lit3\to SOM3} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} \le 0} \end{array}\right. .. math:: + :label: 16.5) - \label{16.5)} NF_{denit,SOM1\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} >0} \\ {-NF_{pot\_ min,SOM1\to SOM2} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} \le 0} \end{array}\right. .. math:: + :label: 16.6) - \label{16.6)} NF_{denit,SOM2\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} >0} \\ {-NF_{pot\_ min,SOM2\to SOM3} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} \le 0} \end{array}\right. .. math:: + :label: 16.7) - \label{16.7)} NF_{denit,SOM3\to SOM4} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} >0} \\ {-NF_{pot\_ min,SOM3\to SOM4} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} \le 0} \end{array}\right. .. math:: + :label: 16.8) - \label{16.8)} NF_{denit,SOM4} =-NF_{pot\_ min,SOM4} -where *f\ :math:`{}_{denit}`* = 0.01 is the constant denitrification +where :math:`{f}_{denit} = 0.01` is the constant denitrification fraction of gross mineralization, and the denitrification fluxes are assumed to be leaving the soil mineral nitrogen pool -(*NS\ :math:`{}_{sminn}`*) and entering the atmosphere. The speciation +(:math:`{NS}_{sminn}`) and entering the atmosphere. The speciation of gaseous nitrogen fluxes entering the atmosphere (e.g. -N\ :math:`{}_{2}` vs. NO\ :math:`{}_{x}` or N\ :math:`{}_{2}`\ O) is not +N\ :sub:`2` vs. NO\ :sub:`x` or N\ :sub:`2`\ O) is not specified. Providing an explicit speciation of these nitrogen losses is another high-priority area for future model development. @@ -220,18 +212,18 @@ pool. The denitrification of excess soil mineral nitrogen is non-zero whenever the supply of mineral nitrogen exceeds the demand: .. math:: + :label: 16.9) - \label{16.9)} NF_{sminn,denit} =\left\{\begin{array}{l} {\left(\frac{NS_{sminn} }{\Delta t} \right)-NF_{total\_ demand} f_{dnx} \qquad {\rm for\; }NF_{total\_ demand} \Delta tB_{up} } \end{array} -where :math:`B_{ag}` (g C m\ :math:`{}^{--2}`) is the aboveground +where :math:`B_{ag}` (g C m\ :sup:`-2`) is the aboveground biomass of combined leaf, stem and aboveground litter (leaf litter and -woody debris) pools; :math:`B_{low}` \ =155 g C m\ :math:`{}^{--2 }`\ is +woody debris) pools; :math:`B_{low}` \ =155 g C m\ :sup:`-2` is the lower fuel threshold below which fire does not occur; -:math:`B_{up}` \ = 1050 g C m\ :math:`{}^{--2}` is the upper fuel +:math:`B_{up}` \ = 1050 g C m\ :sup:`-2` is the upper fuel threshold above which fire occurrence is not limited by fuel -availability. **** +availability. -Fuel combustibility :math:`f_{m}` is estimated by +Fuel combustibility :math:`f_{m}` is estimated by .. math:: + :label: 18.7) - \label{18.7)} f_{m} =f_{RH} f_{\theta } f_{T} -where\ :math:`f_{RH}` , **:math:`f_{\theta }` **, :math:`f_{T}` +where :math:`f_{RH}`, :math:`f_{\theta }`, :math:`f_{T}` represent the dependence of fuel combustibility on relative humidity *RH* (%), surface soil wetness :math:`\theta` , and surface air -temperature *T* (ºC), respectively.\ :math:`f_{RH}` is calculated by +temperature *T* (ºC), respectively. :math:`f_{RH}` is calculated by .. math:: + :label: 18.8) - \label{18.8)} f_{RH} =\left\{\begin{array}{cccc} {1} & {} & {} & {RH\le RH_{low} } \\ {\frac{RH_{up} -RH}{RH_{up} -RH_{low} } ,} & {} & {} & {RH_{low} 0.1` person km\ :math:`{}^{-2}`, we parameterize the +:math:`D_{p} >0.1` person km\ :sup:`-2`, we parameterize the fraction of anthropogenic and natural fires unsuppressed by human activities as .. math:: + :label: 18.10) - \label{18.10)} f_{se,o} =f_{d} f_{e} -where *f\ :math:`{}_{d}`* and *:math:`{}_{ }`\ f\ :math:`{}_{e}`* are +where :math:`{f}_{d}` and :math:`{f}_{e}` are the effects of the demographic and economic conditions on fire occurrence. The demographic influence on fire occurrence is .. math:: + :label: 18.11) - \label{18.11)} f_{d} =0.01+0.98\exp (-0.025D_{P} ). For shrub and grass PFTs, the economic influence on fire occurrence is parameterized as a function of Gross Domestic Product GDP (k 1995US$ -capita\ :math:`{}^{-1}`): +capita\ :sup:`-1`): .. math:: + :label: 18.12) - \label{18.12)} f_{e} =0.1+0.9\times \exp [-\pi (\frac{GDP}{8} )^{0.5} ] which captures 73% of the observed MODIS fire counts with variable GDP @@ -175,17 +166,17 @@ in regions where shrub and grass PFTs are dominant (fractional coverage of shrub and grass PFTs :math:`>` 50%). In regions outside tropical closed forests and dominated by trees (fractional coverage of tree PFTs :math:`>` 50%), we divide the MODIS fire counts into only two bins -(:math:`GDP\ge 20` k 1995US$ capita\ :math:`{}^{-1}`, and :math:`GDP<20` -k 1995US$ capita\ :math:`{}^{-1}`) and parameterize the economic +(:math:`GDP\ge 20` k 1995US$ capita\ :sup:`-1`, and :math:`GDP<20` +k 1995US$ capita\ :sup:`-1`) and parameterize the economic influence on fire occurrence for tree PFTs as .. math:: + :label: 18.13) - \label{18.13)} f_{e} =\left\{\begin{array}{cc} {0.39,} & {GDP\ge 20} \\ {1} & {GDP<20} \end{array}\right. to reproduce that the MODIS fire counts in tree-dominated regions of -GDP\ :math:`\ge 20` k 1995US$ capita\ :math:`{}^{-1}` is 39% of that in +GDP\ :math:`\ge 20` k 1995US$ capita\ :sup:`-1` is 39% of that in other **** tree-dominated regions. 18.1.2 Average spread area of a fire @@ -197,8 +188,8 @@ socioeconomic impact on the average burned area rather than separately on fire spread rate and fire duration： .. math:: + :label: 18.14) - \label{18.14)} a=a^{*} F_{se} where :math:`a^{*}` is the average burned area of a fire without @@ -212,47 +203,45 @@ formula for an ellipse, average burned area of a fire can be represented as: .. math:: + :label: 18.15) - \label{18.15)} a^{*} =\pi \frac{l}{2} \frac{w}{2} \times 10^{-6} =\frac{\pi u_{p}^{2} \tau ^{2} }{4L_{B} } (1+\frac{1}{H_{B} } )^{2} \times 10^{-6} -where :math:`u_{p}` \ (m s\ :math:`{}^{--1}`) is the fire spread rate in +where :math:`u_{p}` \ (m s\ :sup:`-1`) is the fire spread rate in the downwind direction; :math:`\tau` \ (s) is average fire duration;\ :math:`L_{B}` and :math:`H_{B}` are length-to-breadth ratio -and head-to-back ratio of the ellipse; 10\ :math:`{}^{-6 }`\ converts -m\ :math:`{}^{2}` to km\ :math:`{}^{2}`. +and head-to-back ratio of the ellipse; 10\ :sup:`-6` converts m\ :sup:`2` to km\ :sup:`2`. According to Arora and Boer (2005), .. math:: + :label: ZEqnNum696342 - \label{ZEqnNum696342} L_{B} =1.0+10.0[1-\exp (-0.06W)] -where :math:`W`\ (m s\ :math:`{}^{--1}`) is the wind speed. According to +where :math:`W`\ (m s\ :sup:`-1`) is the wind speed. According to the mathematical properties of the ellipse, the head-to-back ratio :math:`H_{B}` is .. math:: + :label: ZEqnNum179757 - \label{ZEqnNum179757} H_{B} =\frac{u_{p} }{u_{b} } =\frac{L_{B} +(L_{B} ^{2} -1)^{0.5} }{L_{B} -(L_{B} ^{2} -1)^{0.5} } . The fire spread rate in the downwind direction is represented as .. math:: + :label: 18.18) - \label{18.18)} u_{p} =u_{\max } C_{m} g(W) (Arora and Boer, 2005), where :math:`u_{\max }` (m -s\ :math:`{}^{--1}`) is the PFT-dependent average maximum fire spread +s\ :sup:`-1`) is the PFT-dependent average maximum fire spread rate in natural vegetation regions; :math:`C_{m}` and :math:`g(W)` represent the dependence of :math:`u_{p}` on fuel wetness and wind speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.55 m -s\ :math:`{}^{--1 }`\ for grass PFTs, 0.46 m s\ :math:`{}^{--1}` for -shrub PFTs, 0.43 m s\ :math:`{}^{--1}` for\ :math:`{}^{ }`\ needleleaf -tree PFTs, and 0.40 m s\ :math:`{}^{--1}` for other tree PFTs. +s\ :sup:`-1`\ for grass PFTs, 0.46 m s\ :sup:`-1` for +shrub PFTs, 0.43 m s\ :sup:`-1` for needleleaf tree PFTs, and 0.40 m s\ :sup:`-1` for other tree PFTs. :math:`C_{m} =C_{\beta } C_{RH}` is estimated by the dependence of :math:`u_{p}` \ on root zone soil wetness (:math:`C_{\beta }` ) and relative humidity (:math:`C_{RH}` ). Here,\ :math:`\beta` is a root @@ -264,8 +253,8 @@ and upper thresholds of root zone soil wetness, respectively. derived from the mathematical properties of the ellipse and Eqs and .. math:: + :label: 18.19) - \label{18.19)} g(W)=\frac{2L_{B} }{1+\frac{1}{H_{B} } } g(0). Since g(\ *W*)=1.0, and\ :math:`L_{B}` and :math:`H_{B}` are at their @@ -273,8 +262,8 @@ maxima\ :math:`L_{B} ^{\max } =11.0`\ and :math:`H_{B} ^{\max } =482.0` when :math:`W\to \infty` , g(0) can be derived as .. math:: + :label: 18.20) - \label{18.20)} g(0)=\frac{1+\frac{1}{H_{B} ^{\max } } }{2L_{B} ^{\max } } =0.05. In the absence of globally gridded data on barriers to fire (e.g. @@ -285,16 +274,16 @@ average fire duration is simply assumed equal to 1 which is the observed As with the socioeconomic influence on fire occurrence, we assume that the socioeconomic influence on fire spreading is negligible in regions -of\ :math:`D_{p} \le 0.1` person km\ :math:`{}^{-2}`, i.e., +of\ :math:`D_{p} \le 0.1` person km\ :sup:`-2`, i.e., :math:`F_{se} =1.0`. In regions of :math:`D_{p} >0.1` person -km\ :math:`{}^{-2}`, we parameterize such socioeconomic influence as: +km\ :sup:`-2`, we parameterize such socioeconomic influence as: .. math:: + :label: 18.21) - \label{18.21)} F_{se} =F_{d} F_{e} -where *F\ :math:`{}_{d}`* and\ *:math:`{}_{ }`\ F\ :math:`{}_{e}`* are +where :math:`{F}_{d}` and :math:`{F}_{e}` are effects of the demographic and economic conditions on the average spread area of a fire, and are identified by maximizing the explained variability of the GFED3 burned area fraction with both socioeconomic @@ -302,30 +291,30 @@ indices in grid cells with various dominant vegetation types. For shrub and grass PFTs, the demographic impact factor is .. math:: + :label: ZEqnNum900584 - \label{ZEqnNum900584} F_{d} =0.2+0.8\times \exp [-\pi (\frac{D_{p} }{450} )^{0.5} ] and the economic impact factor is .. math:: + :label: ZEqnNum213480 - \label{ZEqnNum213480} F_{e} =0.2+0.8\times \exp (-\pi \frac{GDP}{7} ). For tree PFTs outside tropical closed forests, the demographic and economic impact factors are given as .. math:: + :label: 18.24) - \label{18.24)} F_{d} =0.4+0.6\times \exp (-\pi \frac{D_{p} }{125} ) and .. math:: + :label: ZEqnNum543524 - \label{ZEqnNum543524} F_{e} =\left\{\begin{array}{cc} {0.62,} & {GDP>20} \\ {0.83,} & {8`\ *T\ :math:`{}_{f}`* if no agricultural fires occurred -earlier in the year; *f\ :math:`{}_{t}`* is set to 0 otherwise. Peak +*T*\ :math:`>`\ :math:`{T}_{f}` if no agricultural fires occurred +earlier in the year; :math:`{f}_{t}` is set to 0 otherwise. Peak month in this dataset correlates with the month after harvesting or the month before planting. In CLM we use this dataset the same way whether the CROP option is active or not, without regard to the CROP option’s @@ -473,59 +451,59 @@ these grid cells. Burned area is controlled by the deforestation rate and climate: .. math:: + :label: 18.34) - \label{18.34)} A_{b} =bf_{lu} f_{cli,d} A_{g} -where *b* (time step)\ :math:`{}^{-1 }`\ is a global constant; +where *b* (time step)\ :sup:`-1` is a global constant; :math:`f_{lu}` (fraction) represents the effect of decreasing fractional coverage of tree PFTs derived from land use data; and :math:`f_{cli,d}` (fraction) represents the effect of climate conditions on the burned area. -Constants *b* and\ :math:`{}^{ }`\ :math:`{}^{f_{lu} }` are calibrated +Constants *b* and :math:`{f}_{lu}` are calibrated based on observations and reanalysis datasets in the Amazon rainforest -(tropical closed forests within 15.5ºS\ :math:`\mathrm{-}`\ 10.5ºN, -30.5ºW\ :math:`\mathrm{-}`\ 91ºW). *b=*\ 0.035 d\ :math:`{}^{-1}` and +(tropical closed forests within 15.5ºS\ :math:`\text{-}`\ 10.5ºN, +30.5ºW\ :math:`\text{-}`\ 91ºW). *b=*\ 0.035 d\ :sup:`-1` and :math:`f_{lu}` is defined as .. math:: + :label: 18.35) - \label{18.35)} f_{lu} =\max (0.0005,0.19D-0.0011) -where :math:`D`\ (yr:math:`{}^{-1}`) is the annual loss of tree cover +where :math:`D`\ (yr:sup:`-1`) is the annual loss of tree cover based on CLM4’s land use and land cover change data. The effect of climate on deforestation fires is parameterized as: .. math:: + :label: ZEqnNum336915 - \label{ZEqnNum336915} \begin{array}{l} {f_{cli,d} =\max [0,\min (1,\frac{b_{2} -P_{60d} }{b_{2} } )]^{0.5} \max [0,\min (1,\frac{b_{3} -P_{10d} }{b_{3} } )]^{0.5} } \\ {\qquad \max [0,\min (1,\frac{0.25-P}{0.25} )]} \end{array} -where\ :math:`P`\ (mm d\ :math:`{}^{-1}`) is instantaneous -precipitation, while :math:`P_{60d}` (mm d\ :math:`{}^{-1}`) and -:math:`P_{10d}` (mm d\ :math:`{}^{-1}`) are 60-day and 10-day running +where\ :math:`P`\ (mm d\ :sup:`-1`) is instantaneous +precipitation, while :math:`P_{60d}` (mm d\ :sup:`-1`) and +:math:`P_{10d}` (mm d\ :sup:`-1`) are 60-day and 10-day running means of precipitation, respectively; :math:`b_{2}` (mm -d\ :math:`{}^{-1}`) and :math:`b_{3}` (mm d\ :math:`{}^{-1}`) are the +d\ :sup:`-1`) and :math:`b_{3}` (mm d\ :sup:`-1`) are the grid-cell dependent thresholds of :math:`P_{60d}` and :math:`P_{10d}` ; -0.25 mm d\ :math:`{}^{-1}` is the maximum precipitation rate for +0.25 mm d\ :sup:`-1` is the maximum precipitation rate for drizzle. Le Page et al. (2010) analyzed the relationship between large-scale deforestation fire counts and precipitation during -2003\ :math:`\mathrm{-}`\ 2006 in southern Amazonia where tropical +2003\ :math:`\text{-}`\ 2006 in southern Amazonia where tropical evergreen trees (BET Tropical) are dominant. Figure 2 in Le Page et al. (2010) showed that fires generally occurred if both :math:`P_{60d}` and -:math:`P_{10d}` were less than about 4.0 mm d\ :math:`{}^{-1}`, and +:math:`P_{10d}` were less than about 4.0 mm d\ :sup:`-1`, and fires occurred more frequently in a drier environment. Based on the -30-yr (1985:math:`\mathrm{-}`\ 2004) precipitation data in Qian et al. +30-yr (1985:math:`\text{-}`\ 2004) precipitation data in Qian et al. (2006), the climatological precipitation of dry months (P:math:`<`\ 4.0 -mm d\ :math:`{}^{-1}`) in a year over tropical deciduous tree (BDT +mm d\ :sup:`-1`) in a year over tropical deciduous tree (BDT Tropical) dominated regions is 46% of that over BET Tropical dominated regions, so we set the PFT-dependent thresholds of :math:`P_{60d}` and -:math:`P_{10d}` as 4.0 mm d\ :math:`{}^{-1}` for BET Tropical and 1.8 -mm d\ :math:`{}^{-1}` (= 4.0 mm d\ :math:`{}^{-1}` :math:`\times` 46%) -for BDT Tropical, and *b\ :math:`{}_{2}`* and *b\ :math:`{}_{3}`* are +:math:`P_{10d}` as 4.0 mm d\ :sup:`-1` for BET Tropical and 1.8 +mm d\ :sup:`-1` (= 4.0 mm d\ :sup:`-1` :math:`\times` 46%) +for BDT Tropical, and *b*\ :sub:`2` and *b*\ :sub:`3` are the average of thresholds of BET Tropical and BDT Tropical weighted by their coverage. @@ -536,7 +514,7 @@ to the fraction of conversion flux for tropical trees in the tree-reduced region (60%) assigned by CLM, to reach the maximum fire carbon emissions in a conversion region requires burning this region about twice when we set PFT-dependent combustion completeness factors to -about 0.3 for stem [the mean of 0.2\ :math:`\mathrm{-}`\ 0.4 used in van +about 0.3 for stem [the mean of 0.2\ :math:`{-}`\ 0.4 used in van der Werf (2010)]. Therefore, when the burned area calculated from Eq. is no more than twice the tree-reduced area, we assume no escaped fires outside the land-type conversion region, and the fire-related fraction @@ -550,43 +528,41 @@ section 18.1.3. Peat fires --------------- -The burned area due to peat fires is given as *A\ :math:`{}_{b}`*: +The burned area due to peat fires is given as :math:`{A}_{b}`: .. math:: + :label: 18.37) - \label{18.37)} A_{b} =cf_{cli,p} f_{peat} (1-f_{sat} )A_{g} -where *c* (time step)\ :math:`{}^{-1}` is a constant; :math:`f_{cli,p}` +where *c* (time step)\ :sup:`-1` is a constant; :math:`f_{cli,p}` represents the effect of climate on the burned area;\ :math:`f_{peat}` is the fractional coverage of peatland in the grid cell; and :math:`f_{sat}` is the fraction of the grid cell with a water table at -the surface or higher. *c*\ =1.0\ :math:`\times`\ 10\ :math:`{}^{-3}` -hr\ :math:`{}^{-1 }`\ for tropical peat fires and -*c*\ =4.2\ :math:`\times`\ 10\ :math:`{}^{-5}`\ :math:`{}^{ }`\ hr\ :math:`{}^{-1 }`\ for -boreal peat fires are derived using an inverse -method,\ :math:`{}^{ }`\ by matching simulations from an unreleased +the surface or higher. *c*\ =1.0\ :math:`\times`\ 10\ :sup:`-3` hr\ :sup:`-1` for tropical peat fires and +*c*\ =4.2\ :math:`\times`\ 10\ :sup:`-5` hr\ :sup:`-1` for boreal peat fires are derived using an inverse +method, by matching simulations from an unreleased CLM4.5 version driven by Qian et al. (2006) atmospheric forcing and climatological lightning data to earlier studies: about 2.4 Mha peatland was burned over Indonesia in 1997 (Page et al. 2002) and the average burned area of peat fires in Western Canada was 0.2 Mha -yr\ :math:`{}^{-1}` for 1980\ :math:`\mathrm{-}`\ 1999 (Turestky et al. +yr\ :sup:`-1` for 1980\ :math:`\math{-}`\ 1999 (Turestky et al. 2004). For tropical peat fires, :math:`f_{cli,p}` is set as a function of long-term precipitation :math:`P_{60d}` : .. math:: + :label: 18.38) - \label{18.38)} f_{cli,p} =\max [0,\min (1,\frac{4-P_{60d} }{4} )]^{2} . For boreal peat fires, :math:`f_{cli,p}` is set to .. math:: + :label: 18.39) - \label{18.39)} - f_{cli,p} =\exp (-\pi \frac{\theta _{17cm} }{0.3} )\cdot \max [0,\min (1,\frac{T_{17cm} -T_{f} }{10} )] + f_{cli,p} = \exp (-\pi \frac{\theta _{17cm} }{0.3} )\cdot \max [0,\min (1,\frac{T_{17cm} -T_{f} }{10} )] where :math:`\theta _{17cm}` and :math:`T_{17cm}` are the wetness and temperature of the top 17 cm of soil; :math:`T_{f}` \ =273.15 K is the @@ -595,13 +571,10 @@ freezing temperature. Peat fires lead to peat combustion and the combustion and mortality of vegetation in peatlands. For tropical peat fires, based on Page et al. (2002), about 6% of the peat carbon loss from stored carbon is caused by -33.9% of the peatland burned. Carbon emissions due to peat combustion (g -C m\ :math:`{}^{-2}` (time step)\ :math:`{}^{-1}`) are therefore set as +33.9% of the peatland burned. Carbon emissions due to peat combustion (g C m\ :sup:`-2` (time step)\ :sup:`-1`) are therefore set as the product of 6%/33.9%, by burned area fraction of peat fire ((time -step)\ :math:`{}^{-1}`), by soil organic carbon (g C -m\ :math:`{}^{-2}`). For boreal peat fires, the carbon emissions due to -peat combustion are set as 2.2 kg C -m\ :math:`{}^{-}`\ :math:`{}^{2 }`\ peat fire area (Turetsky et al. +step)\ :sup:`-1`), by soil organic carbon (g C m\ :sup:`-2`). For boreal peat fires, the carbon emissions due to +peat combustion are set as 2.2 kg C m\ :sup:`-2`\ peat fire area (Turetsky et al. 2002). Biomass combustion and vegetation mortality in post-fire peatlands are set the same as section 18.1.3 for non-crop PFTs and as section 18.2 for crops PFTs. @@ -610,7 +583,7 @@ Table 18.1. PFT-specific combustion completeness and fire mortality factors. +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| PFT | *CC*\ :math:`{}_{leaf}` | *CC*\ :math:`{}_{stem}` | *CC*\ :math:`{}_{root}` | *CC*\ :math:`{}_{ts}` | *M*\ :math:`{}_{leaf}` | *M*\ :math:`{}_{livestem}` | *M*\ :math:`{}_{deadstem}` | *M*\ :math:`{}_{root}` | *M*\ :math:`{}_{ts}` | *M*\ :math:`{}_{livestem}` | *:math:`\xi`*\ :math:`{}_{j}` | +| PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem` | :math:`\xi`\ :sub:`j` | +==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+ | NET Temperate | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ @@ -634,11 +607,11 @@ factors. +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ | BDS Boreal | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| C\ :math:`{}_{3}` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +| C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| C\ :math:`{}_{3}` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +| C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| C\ :math:`{}_{4}` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +| C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ | Crop 1 | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ diff --git a/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst b/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst index 980ed65268..7bdea2fefb 100644 --- a/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst +++ b/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst @@ -9,15 +9,15 @@ Zhuang et al. 2004). Although the model has similarities with these precursor models, a number of new process representations and parameterization have been integrated into CLM. -Mechanistically modeling net surface CH\ :math:`{}_{4}` emissions +Mechanistically modeling net surface CH\ :sub:`4` emissions requires representing a complex and interacting series of processes. We first (section 19.1) describe the overall model structure and flow of -information in the CH\ :math:`{}_{4}` model, then describe the methods -used to represent: CH\ :math:`{}_{4}` mass balance; CH\ :math:`{}_{4}` -production; ebullition; aerenchyma transport; CH\ :math:`{}_{4}` +information in the CH\ :sub:`4` model, then describe the methods +used to represent: CH\ :sub:`4` mass balance; CH\ :sub:`4` +production; ebullition; aerenchyma transport; CH\ :sub:`4` oxidation; reactive transport solution, including boundary conditions, numerical solution, water table interface, etc.; seasonal inundation -effects; and impact of seasonal inundation on CH\ :math:`{}_{4}` +effects; and impact of seasonal inundation on CH\ :sub:`4` production. Methane Model Structure and Flow @@ -26,97 +26,90 @@ Methane Model Structure and Flow The driver routine for the methane biogeochemistry calculations (ch4, in ch4Mod.F) controls the initialization of boundary conditions, inundation, and impact of redox conditions; calls to routines to -calculate CH\ :math:`{}_{4}` production, oxidation, transport through +calculate CH\ :sub:`4` production, oxidation, transport through aerenchyma, ebullition, and the overall mass balance (for unsaturated and saturated soils and, if desired, lakes); resolves changes to -CH\ :math:`{}_{4}` calculations associated with a changing inundated +CH\ :sub:`4` calculations associated with a changing inundated fraction; performs a mass balance check; and calculates the average -gridcell CH\ :math:`{}_{4}` production, oxidation, and exchanges with +gridcell CH\ :sub:`4` production, oxidation, and exchanges with the atmosphere. Governing Mass-Balance Relationship ---------------------------------------- -The model (Figure 19.1) accounts for CH\ :math:`{}_{4}` production in -the anaerobic fraction of soil (*P*, mol m\ :math:`{}^{-3}` -s\ :math:`{}^{-1}`), ebullition (*E*, mol m\ :math:`{}^{-3}` -s\ :math:`{}^{-1}`), aerenchyma transport (*A*, mol m\ :math:`{}^{-3}` -s\ :math:`{}^{-1}`), aqueous and gaseous diffusion (*F\ :math:`{}_{D}`*, -mol m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), and oxidation (*O*, mol -m\ :math:`{}^{-3}` s\ :math:`{}^{-1}`) via a transient reaction +The model (Figure 19.1) accounts for CH\ :sub:`4` production in +the anaerobic fraction of soil (*P*, mol m\ :sup:`-3` s\ :sup:`-1`), ebullition (*E*, mol m\ :sup:`-3` s\ :sup:`-1`), +aerenchyma transport (*A*, mol m\ :sup:`-3` s\ :sup:`-1`), aqueous and gaseous diffusion (:math:`{F}_{D}`, +mol m\ :sup:`-2` s\ :sup:`-1`), and oxidation (*O*, mol m\ :sup:`-3` s\ :sup:`-1`) via a transient reaction diffusion equation: .. math:: + :label: ZEqnNum628535 - \label{ZEqnNum628535} \frac{\partial \left(RC\right)}{\partial t} =\frac{\partial F_{D} }{\partial z} +P\left(z,t\right)-E\left(z,t\right)-A\left(z,t\right)-O\left(z,t\right) Here *z* (m) represents the vertical dimension, *t* (s) is time, and *R* accounts for gas in both the aqueous and gaseous -phases:\ :math:`R=\varepsilon _{a} +K_{H}^{} \varepsilon _{w}` , with -*:math:`\epsilon`\ :math:`{}_{a}`*, *:math:`\epsilon`\ :math:`{}_{w}`,* -and :math:`K_{H}^{}` (-) the air-filled porosity, water-filled +phases:\ :math:`R = \epsilon _{a} +K_{H} \epsilon _{w}`, with +:math:`\epsilon _{a}`, :math:`\epsilon _{w}`, and :math:`K_{H}` (-) the air-filled porosity, water-filled porosity, and partitioning coefficient for the species of interest, -respectively, and :math:`C` represents CH\ :math:`{}_{4}` or -O\ :math:`{}_{2}` concentration with respect to water volume (mol -m\ :math:`{}^{-3}`). +respectively, and :math:`C` represents CH\ :sub:`4` or O\ :sub:`2` concentration with respect to water volume (mol m\ :sup:`-3`). An analogous version of equation is concurrently solved for -O\ :math:`{}_{2}`, but with the following differences relative to -CH\ :math:`{}_{4}`: *P* = *E* = 0 (i.e., no production or ebullition), -and the oxidation sink includes the O\ :math:`{}_{2}` demanded by +O\ :sub:`2`, but with the following differences relative to +CH\ :sub:`4`: *P* = *E* = 0 (i.e., no production or ebullition), +and the oxidation sink includes the O\ :sub:`2` demanded by methanotrophs, heterotroph decomposers, nitrifiers, and autotrophic root respiration. As currently implemented, each gridcell contains an inundated and a non-inundated fraction. Therefore, equation is solved four times for each gridcell and time step: in the inundated and non-inundated -fractions, and for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}`. If desired, -the CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` mass balance equation is +fractions, and for CH\ :sub:`4` and O\ :sub:`2`. If desired, +the CH\ :sub:`4` and O\ :sub:`2` mass balance equation is solved again for lakes (Chapter 9). For non-inundated areas, the water table interface is defined at the deepest transition from greater than 95% saturated to less than 95% saturated that occurs above frozen soil layers. The inundated fraction is allowed to change at each time step, -and the total soil CH\ :math:`{}_{4}` quantity is conserved by evolving -CH\ :math:`{}_{4}` to the atmosphere when the inundated fraction +and the total soil CH\ :sub:`4` quantity is conserved by evolving +CH\ :sub:`4` to the atmosphere when the inundated fraction decreases, and averaging a portion of the non-inundated concentration into the inundated concentration when the inundated fraction increases. Figure 19.1. Schematic representation of biological and physical -processes integrated in CLM that affect the net CH\ :math:`{}_{4}` +processes integrated in CLM that affect the net CH\ :sub:`4` surface flux (Riley et al. 2011a). (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. -|image| +.. image:: image1.png -19.3 CH\ :math:`{}_{4}` Production +CH\ :sub:`4` Production ---------------------------------- Because CLM does not currently specifically represent wetland plant functional types or soil biogeochemical processes, we used gridcell-averaged decomposition rates as proxies. Thus, the upland (default) heterotrophic respiration is used to estimate the wetland -decomposition rate after first dividing off the O\ :math:`{}_{2}` -limitation. The O\ :math:`{}_{2}` consumption associated with anaerobic +decomposition rate after first dividing off the O\ :sub:`2` +limitation. The O\ :sub:`2` consumption associated with anaerobic decomposition is then set to the unlimited version so that it will be -reduced appropriately during O\ :math:`{}_{2}` competition. -CH\ :math:`{}_{4}` production at each soil level in the anaerobic +reduced appropriately during O\ :sub:`2` competition. +CH\ :sub:`4` production at each soil level in the anaerobic portion (i.e., below the water table) of the column is related to the gridcell estimate of heterotrophic respiration from soil and litter -(*R\ :math:`{}_{H}`*; mol C m\ :math:`{}^{-2}` -s\ :math:`{}^{-}`\ :math:`{}^{1}`) corrected for its soil temperature -(*T\ :math:`{}_{s}`*) dependence, soil temperature through a -*Q*\ :math:`{}_{10}` factor (:math:`f_{T}` ), pH (:math:`f_{pH}` ), -redox potential (:math:`f_{pE}` ), and a factor accounting for the +(R\ :sub:`H`; mol C m\ :sup:`-2` s\ :sub:`-1`) corrected for its soil temperature +(:math:`{T}_{s}`) dependence, soil temperature through a +:math:`{A}_{10}` factor (:math:`f_{T}`), pH (:math:`f_{pH}`), +redox potential (:math:`f_{pE}`), and a factor accounting for the seasonal inundation fraction (*S*, described below): .. math:: + :label: ZEqnNum109798 - \label{ZEqnNum109798} P=R_{H} f_{CH_{4} } f_{T} f_{pH} f_{pE} S. Here, :math:`f_{CH_{4} }` is the baseline ratio between -CO\ :math:`{}_{2}` and CH\ :math:`{}_{4}` production (all parameters +CO\ :sub:`2` and CH\ :sub:`4` production (all parameters values are given in Table 19.1). Currently, :math:`f_{CH_{4} }` is modified to account for our assumptions that methanogens may have a higher Q\ :math:`{}_{10}` than aerobic decomposers; are not N limited; @@ -126,27 +119,24 @@ When the single BGC soil level is used in CLM (Chapter 15), the temperature factor, :math:`f_{T}` , is set to 0 for temperatures equal to or below freezing, even though CLM allows heterotrophic respiration below freezing. However, if the vertically resolved BGC soil column is -used, CH\ :math:`{}_{4}` production continues below freezing because +used, CH\ :sub:`4` production continues below freezing because liquid water stress limits decomposition. The base temperature for the -*Q*\ :math:`{}_{10}` factor, *T\ :math:`{}_{B}`*, is 22 -:math:`{}^\circ`\ C and effectively modified the base -:math:`f_{CH_{4} }` value. +:math:`{Q}_{10}` factor, :math:`{T}_{B}`, is 22\ :sup:`o` C and effectively modified the base +:math:`f_{CH_{4}}` value. -For the single-layer BGC version, *R\ :math:`{}_{H}`* is distributed ** +For the single-layer BGC version, :math:`{R}_{H}` is distributed among soil levels by assuming that 50% is associated with the roots (using the CLM PFT-specific rooting distribution) and the rest is evenly divided among the top 0.28 m of soil (to be consistent with CLM’s soil decomposition algorithm). For the vertically resolved BGC version, the -prognosed distribution of *R\ :math:`{}_{H}`* is used to estimate -CH\ :math:`{}_{4}` production. +prognosed distribution of :math:`{R}_{H}` is used to estimate CH\ :sub:`4` production. The factor :math:`f_{pH}` is nominally set to 1, although a static -spatial map of *pH* can be used to determine this factor (Dunfield et -al. 1993) by applying: +spatial map of *pH* can be used to determine this factor (Dunfield et al. 1993) by applying: .. math:: + :label: 19.3) - \label{19.3)} f_{pH} =10^{-0.2235pH^{2} +2.7727pH-8.6} . The :math:`f_{pE}` factor assumes that alternative electron acceptors @@ -157,26 +147,26 @@ in the upland fraction of the gridcell. We consider both :math:`f_{pH}` and :math:`f_{pE}` to be poorly constrained in the model and identify these controllers as important areas for model improvement. -As a non-default option to account for CH\ :math:`{}_{4}` production in +As a non-default option to account for CH\ :sub:`4` production in anoxic microsites above the water table, we apply the Arah and Stephen (1998) estimate of anaerobic fraction: .. math:: + :label: 19.4) - \label{19.4)} \varphi =\frac{1}{1+\eta C_{O_{2} } } . -Here, *:math:`\varphi`* is the factor by which production is inhibited +Here, :math:`\phi` is the factor by which production is inhibited above the water table (compared to production as calculated in equation -, :math:`C_{O_{2} }` (mol m\ :math:`{}^{-3}`) is the bulk soil oxygen -concentration, and *:math:`\eta`* = 400 mol m\ :math:`{}^{-3}`. +, :math:`C_{O_{2}}` (mol m\ :sup:`-3`) is the bulk soil oxygen +concentration, and :math:`\eta` = 400 mol m\ :sup:`-3`. -The O\ :math:`{}_{2}` required to facilitate the vertically resolved +The O\ :sub:`2` required to facilitate the vertically resolved heterotrophic decomposition and root respiration is estimated assuming 1 -mol O\ :math:`{}_{2}` is required per mol CO\ :math:`{}_{2}` produced. -The model also calculates the O\ :math:`{}_{2}` required during -nitrification, and the total O\ :math:`{}_{2}` demand is used in the -O\ :math:`{}_{2}` mass balance solution. +mol O\ :sub:`2` is required per mol CO\ :sub:`2` produced. +The model also calculates the O\ :sub:`2` required during +nitrification, and the total O\ :sub:`2` demand is used in the +O\ :sub:`2` mass balance solution. Table 19.1. Parameter descriptions and sensitivity analysis ranges applied in the methane model. @@ -184,79 +174,74 @@ applied in the methane model. +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ | Mechanism | Parameter | Baseline Value | Range for Sensitivity Analysis | Units | Description | +==============+============================+==============================================+==================================================================================================+=============================================+============================================================================================+ -| Production | *Q\ :math:`{}_{10}`* | 2 | 1.5 – 4 | - | CH\ :math:`{}_{4}` production Q\ :math:`{}_{10}` | +| Production | :math:`{Q}_{10}` | 2 | 1.5 – 4 | - | CH\ :sub:`4` production :math:`{Q}_{10}` | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`f_{pH}` | 1 | On, off | - | Impact of pH on CH\ :math:`{}_{4}` production | +| | :math:`f_{pH}` | 1 | On, off | - | Impact of pH on CH\ :sub:`4` production | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`f_{pE}` | 1 | On, off | - | Impact of redox potential on CH\ :math:`{}_{4}` production | +| | :math:`f_{pE}` | 1 | On, off | - | Impact of redox potential on CH\ :sub:`4` production | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| ** | *S* | Varies | NA | - | Seasonal inundation factor | +| | *S* | Varies | NA | - | Seasonal inundation factor | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | *:math:`\beta`* | 0.2 | NA | - | Effect of anoxia on decomposition rate (used to calculate *S* only) | +| | :math:`\beta` | 0.2 | NA | - | Effect of anoxia on decomposition rate (used to calculate *S* only) | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`f_{CH_{4} }` | 0.2 | NA | - | Ratio between CH\ :math:`{}_{4}` and CO\ :math:`{}_{2}` production below the water table | +| | :math:`f_{CH_{4} }` | 0.2 | NA | - | Ratio between CH\ :sub:`4` and CO\ :sub:`2` production below the water table | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Ebullition | *C\ :math:`{}_{e,max}`* | 0.15 | NA | mol m\ :math:`{}^{-3}` | CH\ :math:`{}_{4}` concentration to start ebullition | +| Ebullition | :math:`{C}_{e,max}` | 0.15 | NA | mol m\ :sup:`-3` | CH\ :sub:`4` concentration to start ebullition | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| ** | *C\ :math:`{}_{e,min}`* | 0.15 | NA | - | CH\ :math:`{}_{4}` concentration to end ebullition | +| | :math:`{C}_{e,min}` | 0.15 | NA | - | CH\ :sub:`4` concentration to end ebullition | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Diffusion | :math:`f_{D_{0} }` \ ** | 1 | 1, 10 | m\ :math:`{}^{2}` s\ :math:`{}^{-1}` | Diffusion coefficient multiplier (Table 19.2) | +| Diffusion | :math:`f_{D_{0} }` | 1 | 1, 10 | m\ :sup:`2` s\ :sup:`-1` | Diffusion coefficient multiplier (Table 19.2) | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ | Aerenchyma | *p* | 0.3 | NA | - | Grass aerenchyma porosity | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| ** | *R* | 2.9\ :math:`\times`\ 10\ :math:`{}^{-3}` m | NA | m | Aerenchyma radius | +| | *R* | 2.9\ :math:`\times`\ 10\ :sup:`-3` m | NA | m | Aerenchyma radius | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| ** | *r\ :math:`{}_{L}`* | 3 | NA | - | Root length to depth ratio | +| | :math:`{r}_{L}` | 3 | NA | - | Root length to depth ratio | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | *F\ :math:`{}_{a}`* | 1 | 0.5 – 1.5 | - | Aerenchyma conductance multiplier | +| | :math:`{F}_{a}` | 1 | 0.5 – 1.5 | - | Aerenchyma conductance multiplier | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Oxidation | :math:`K_{CH_{4} }` | 5 x 10\ :math:`{}^{-3}` | 5\ :math:`\times`\ 10\ :math:`{}^{-4}`\ :math:`{}_{ }`- 5\ :math:`\times`\ 10\ :math:`{}^{-2}` | mol m\ :math:`{}^{-3}` | CH\ :math:`{}_{4}` half-saturation oxidation coefficient (wetlands) | +| Oxidation | :math:`K_{CH_{4} }` | 5 x 10\ :sup:`-3` | 5\ :math:`\times`\ 10\ :math:`{}^{-4}`\ :math:`{}_{ }`- 5\ :math:`\times`\ 10\ :sup:`-2` | mol m\ :sup:`-3` | CH\ :sub:`4` half-saturation oxidation coefficient (wetlands) | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| ** | :math:`K_{O_{2} }` \ ** | 2 x 10\ :math:`{}^{-2}` | 2\ :math:`\times`\ 10\ :math:`{}^{-3}` - 2\ :math:`\times`\ 10\ :math:`{}^{-1}` | mol m\ :math:`{}^{-3}` | O\ :math:`{}_{2}` half-saturation oxidation coefficient | +| | :math:`K_{O_{2} }` | 2 x 10\ :sup:`-2` | 2\ :math:`\times`\ 10\ :sup:`-3` - 2\ :math:`\times`\ 10\ :sup:`-1` | mol m\ :sup:`-3` | O\ :sub:`2` half-saturation oxidation coefficient | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`R_{o,\max }` \ ** | 1.25 x 10\ :math:`{}^{-5}` | 1.25\ :math:`\times`\ 10\ :math:`{}^{-6}` - 1.25\ :math:`\times`\ 10\ :math:`{}^{-4}` | mol m\ :math:`{}^{-3}` s\ :math:`{}^{-1}` | Maximum oxidation rate (wetlands) | +| | :math:`R_{o,\max }` | 1.25 x 10\ :math:`{}^{-5}` | 1.25\ :math:`\times`\ 10\ :math:`{}^{-6}` - 1.25\ :math:`\times`\ 10\ :math:`{}^{-4}` | mol m\ :sup:`-3` s\ :sup:`-1` | Maximum oxidation rate (wetlands) | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -.. math:: 8 - -.. math:: 17 - Ebullition --------------- -Briefly, the simulated aqueous CH\ :math:`{}_{4}` concentration in each +Briefly, the simulated aqueous CH\ :sub:`4` concentration in each soil level is used to estimate the expected equilibrium gaseous partial pressure (:math:`C_{e}` ), as a function of temperature and depth below the water table, by first estimating the Henry’s law partitioning -coefficient (:math:`k_{h}^{C}` ) by the method described in Wania et al. -(2010): +coefficient (:math:`k_{h}^{C}` ) by the method described in Wania et al. (2010): .. math:: + :label: 19.5) - \label{19.5)} \log \left(\frac{1}{k_{H} } \right)=\log k_{H}^{s} -\frac{1}{C_{H} } \left(\frac{1}{T} -\frac{1}{T^{s} } \right) .. math:: + :label: ZEqnNum493232 - \label{ZEqnNum493232} k_{h}^{C} =Tk_{H} R_{g} .. math:: + :label: 19.7) - \label{19.7)} C_{e} =\frac{C_{w} R_{g} T}{\theta _{s} k_{H}^{C} p} where :math:`C_{H}` \ is a constant, :math:`R_{g}` is the universal gas constant, :math:`k_{H}^{s}` is Henry’s law partitioning coefficient at standard temperature (:math:`T^{s}` ),\ :math:`C_{w}` \ is local -aqueous CH\ :math:`{}_{4}` concentration, and *p* is pressure. +aqueous CH\ :sub:`4` concentration, and *p* is pressure. The local pressure is calculated as the sum of the ambient pressure, water pressure down to the local depth, and pressure from surface -ponding (if applicable). When the CH\ :math:`{}_{4}` partial pressure +ponding (if applicable). When the CH\ :sub:`4` partial pressure exceeds 15% of the local pressure (Baird et al. 2004; Strack et al. -2006; Wania et al. 2010), bubbling occurs to remove CH\ :math:`{}_{4}` -to below this value, modified by the fraction of CH\ :math:`{}_{4}` in +2006; Wania et al. 2010), bubbling occurs to remove CH\ :sub:`4` +to below this value, modified by the fraction of CH\ :sub:`4` in the bubbles [taken as 57%; (Kellner et al. 2006; Wania et al. 2010)]. Bubbles are immediately added to the surface flux for saturated columns and are placed immediately above the water table interface in @@ -271,21 +256,19 @@ atmosphere and, if specified, by vertical advection with the transpiration stream. There is evidence that pressure driven flow can also occur, but we did not include that mechanism in the current model. -The diffusive transport through aerenchyma (*A*, mol m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) from each soil layer is represented in the model as: +The diffusive transport through aerenchyma (*A*, mol m\ :sup:`-2` s\ :sup:`-1`) from each soil layer is represented in the model as: .. math:: + :label: ZEqnNum158128 - \label{ZEqnNum158128} A=\frac{C\left(z\right)-C_{a} }{{\raise0.7ex\hbox{$ r_{L} z $}\!\mathord{\left/ {\vphantom {r_{L} z D}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ D $}} +r_{a} } pT\rho _{r} , - -where *D* is the free-air gas diffusion coefficient (m:math:`{}^{2}` -s\ :math:`{}^{-1}`); *C(z)* (mol m\ :math:`{}^{-3}`) is the gaseous + +where *D* is the free-air gas diffusion coefficient (m:sup:`2` s\ :sup:`-1`); *C(z)* (mol m\ :sup:`-3`) is the gaseous concentration at depth *z* (m); :math:`r_{L}` is the ratio of root length to depth; *p* is the porosity (-); *T* is specific aerenchyma -area (m:math:`{}^{2}` m\ :math:`{}^{-2}`); *r\ :math:`{}_{a}`* is the +area (m:sup:`2` m\ :sup:`-2`); :math:`{r}_{a}` is the aerodynamic resistance between the surface and the atmospheric reference -height (s m:math:`{}^{-1}`); and :math:`\rho _{r}` is the rooting +height (s m:sup:`-1`); and :math:`\rho _{r}` is the rooting density as a function of depth (-). The gaseous concentration is calculated with Henry’s law as described in equation . @@ -293,125 +276,121 @@ Based on the ranges reported in Colmer (2003), we have chosen baseline aerenchyma porosity values of 0.3 for grass and crop PFTs and 0.1 for tree and shrub PFTs. The aerenchyma area varies over the course of the growing season; we parameterize this dependency using the simulated leaf -area index *L* (m:math:`{}^{2}` m\ :math:`{}^{-2}`), as in Wania et al. +area index *L* (m:sup:`2` m\ :sup:`-2`), as in Wania et al. (2010): .. math:: + :label: 19.9) - \label{19.9)} T=\frac{f_{N} N_{a} L}{0.22} \pi R^{2} . Here :math:`N_{a}` is annual net primary production (NPP, mol -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`); *R* is the aerenchyma radius -(2.9:math:`\times`\ 10\ :math:`{}^{-3}` m); *f\ :math:`{}_{N}`* is the +m\ :sup:`-2` s\ :sup:`-1`); *R* is the aerenchyma radius +(2.9:math:`\times`\ 10\ :sup:`-3` m); :math:`{f}_{N}` is the belowground fraction of annual NPP; and the 0.22 factor represents the -amount of C per tiller. O\ :math:`{}_{2}` can also diffuse in from the +amount of C per tiller. O\ :sub:`2` can also diffuse in from the atmosphere to the soil layer via the reverse of the same pathway, with the same representation as Equation but with the gas diffusivity of oxygen. -CLM also simulates the direct emission of CH\ :math:`{}_{4}` from leaves +CLM also simulates the direct emission of CH\ :sub:`4` from leaves to the atmosphere via transpiration of dissolved methane. We calculate -this flux (:math:`F_{CH_{4} -T}` ; mol m\ :math:`{}^{-}`\ :math:`{}^{2}` -s\ :math:`{}^{-1}`) using the simulated soil water methane concentration -(:math:`C_{CH_{4} ,j}` (mol m\ :math:`{}^{-3}`)) in each soil layer *j* +this flux (:math:`F_{CH_{4} -T}` ; mol m\ :math:`{}^{-}`\ :sup:`2` +s\ :sup:`-1`) using the simulated soil water methane concentration +(:math:`C_{CH_{4} ,j}` (mol m\ :sup:`-3`)) in each soil layer *j* and the CLM predicted transpiration (:math:`F_{T}` ) for each PFT, assuming that no methane was oxidized inside the plant tissue: .. math:: + :label: 19.10) - \label{19.10)} F_{CH_{4} -T} =\sum _{j}\rho _{r,j} F_{T} C_{CH_{4} ,j} . -CH\ :math:`{}_{4}` Oxidation +CH\ :sub:`4` Oxidation --------------------------------- -CLM represents CH\ :math:`{}_{4}` oxidation with double Michaelis-Menten +CLM represents CH\ :sub:`4` oxidation with double Michaelis-Menten kinetics (Arah and Stephen 1998; Segers 1998), dependent on both the -gaseous CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` concentrations: +gaseous CH\ :sub:`4` and O\ :sub:`2` concentrations: .. math:: + :label: 19.11) - \label{19.11)} R_{oxic} =R_{o,\max } \left[\frac{C_{CH_{4} } }{K_{CH_{4} } +C_{CH_{4} } } \right]\left[\frac{C_{O_{2} } }{K_{O_{2} } +C_{O_{2} } } \right]Q_{10} F_{\vartheta } where :math:`K_{CH_{4} }` and :math:`K_{O_{2} }` \ are the half -saturation coefficients (mol m\ :math:`{}^{-3}`) with respect to -CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` concentrations, respectively; +saturation coefficients (mol m\ :sup:`-3`) with respect to +CH\ :sub:`4` and O\ :sub:`2` concentrations, respectively; :math:`R_{o,\max }` is the maximum oxidation rate (mol -m\ :math:`{}^{-3}` s\ :math:`{}^{-1}`); and *Q\ :math:`{}_{10}`* +m\ :sup:`-3` s\ :sup:`-1`); and :math:`{Q}_{10}` specifies the temperature dependence of the reaction with a base -temperature set to 12 :math:`{}^\circ`\ C. The soil moisture limitation -factor :math:`F_{\vartheta }` is applied above the water table to +temperature set to 12 :sup:`o` C. The soil moisture limitation +factor :math:`F_{\theta }` is applied above the water table to represent water stress for methanotrophs. Based on the data in Schnell -and King (1996), we take :math:`F_{\vartheta } =e^{{\raise0.7ex\hbox{` --P -:math:`}\!\mathord{\left/ {\vphantom {-P P_{c} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{` -P\ :sub:`c` :math:`}} }` , where *P* is the soil moisture potential and -*P\ :math:`{}_{c}`* = -2.4:math:`\times`\ 10\ :math:`{}^{5}` mm. +and King (1996), we take :math:`F_{\theta } = {e}^{-P/{P}_{c}}`, where *P* is the soil moisture potential and +:math:`{P}_{c} = -2.4 \times {10}^{5}` mm. Reactive Transport Solution -------------------------------- The solution to equation is solved in several sequential steps: resolve -competition for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` (section +competition for CH\ :sub:`4` and O\ :sub:`2` (section 19.7.1); add the ebullition flux into the layer directly above the water -table or into the atmosphere; calculate the overall CH\ :math:`{}_{4}` -or O\ :math:`{}_{2}` source term based on production, aerenchyma +table or into the atmosphere; calculate the overall CH\ :sub:`4` +or O\ :sub:`2` source term based on production, aerenchyma transport, ebullition, and oxidation; establish boundary conditions, including surface conductance to account for snow, ponding, and turbulent conductances and bottom flux condition (section 19.7.2); calculate diffusivity (section 19.7.3); and solve the resulting mass balance using a tridiagonal solver (section 19.7.5). -19.7.1 Competition for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` +Competition for CH\ :sub:`4` and O\ :sub:`2` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For each time step, the unlimited CH\ :math:`{}_{4}` and -O\ :math:`{}_{2}` demands in each model depth interval are computed. If +For each time step, the unlimited CH\ :sub:`4` and +O\ :sub:`2` demands in each model depth interval are computed. If the total demand over a time step for one of the species exceeds the amount available in a particular control volume, the demand from each process associated with the sink is scaled by the fraction required to ensure non-negative concentrations. Since the methanotrophs are limited -by both CH\ :math:`{}_{4}` and O\ :math:`{}_{2}`, the stricter +by both CH\ :sub:`4` and O\ :sub:`2`, the stricter limitation is applied to methanotroph oxidation, and then the limitations are scaled back for the other processes. The competition is designed so that the sinks must not exceed the available concentration over the time step, and if any limitation exists, the sinks must sum to this value. Because the sinks are calculated explicitly while the transport is semi-implicit, negative concentrations can occur after the -tridiagonal solution. When this condition occurs for O\ :math:`{}_{2}`, +tridiagonal solution. When this condition occurs for O\ :sub:`2`, the concentrations are reset to zero; if it occurs for -CH\ :math:`{}_{4}`, the surface flux is adjusted and the concentration +CH\ :sub:`4`, the surface flux is adjusted and the concentration is set to zero if the adjustment is not too large. -19.7.2 CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` Source Terms +19.7.2 CH\ :sub:`4` and O\ :sub:`2` Source Terms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The overall CH\ :math:`{}_{4}` net source term consists of production, +The overall CH\ :sub:`4` net source term consists of production, oxidation at the base of aerenchyma, transport through aerenchyma, methanotrophic oxidation, and ebullition (either to the control volume above the water table if unsaturated or directly to the atmosphere if -saturated). For O\ :math:`{}_{2}` below the top control volume, the net -source term consists of O\ :math:`{}_{2}` losses from methanotrophy, SOM -decomposition, and autotrophic respiration, and an O\ :math:`{}_{2}` +saturated). For O\ :sub:`2` below the top control volume, the net +source term consists of O\ :sub:`2` losses from methanotrophy, SOM +decomposition, and autotrophic respiration, and an O\ :sub:`2` source through aerenchyma. 19.7.3 Aqueous and Gaseous Diffusion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For gaseous diffusion, we adopted the temperature dependence of -molecular free-air diffusion coefficients (*D\ :math:`{}_{0}`* -(m:math:`{}^{2}` s\ :math:`{}^{-1}`)) as described by Lerman et al. -(1979) and applied by Wania et al. (2010) (Table 19.2). +molecular free-air diffusion coefficients (:math:`{D}_{0}` +(m:sup:`2` s\ :sup:`-1`)) as described by Lerman et al. (1979) and applied by Wania et al. (2010) (Table 19.2). Table 19.2. Temperature dependence of aqueous and gaseous diffusion -coefficients for CH\ :math:`{}_{4}` and O\ :math:`{}_{2}`. +coefficients for CH\ :sub:`4` and O\ :sub:`2`. +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ -| D\ :math:`{}_{0}` (m:math:`{}^{2}` s\ :math:`{}^{-1}`) | CH\ :math:`{}_{4}` | O\ :math:`{}_{2}` | +| :math:`{D}_{0}` (m\ :sup:`2` s\ :sup:`-1`) | CH\ :sub:`4` | O\ :sub:`2` | +==========================================================+==========================================================+========================================================+ -| Aqueous | 0.9798 + 0.02986\ *T* + 0.0004381\ *T*\ :math:`{}^{2}` | 1.172+ 0.03443\ *T* + 0.0005048\ *T*\ :math:`{}^{2}` | +| Aqueous | 0.9798 + 0.02986\ *T* + 0.0004381\ *T*\ :sup:`2` | 1.172+ 0.03443\ *T* + 0.0005048\ *T*\ :sup:`2` | +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ | Gaseous | 0.1875 + 0.0013\ *T* | 0.1759 + 0.0011\ *T* | +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ @@ -420,12 +399,12 @@ Gaseous diffusivity in soils also depends on the molecular diffusivity, soil structure, porosity, and organic matter content. Moldrup et al. (2003), using observations across a range of unsaturated mineral soils, showed that the relationship between effective diffusivity -(:math:`D_{e}` (m:math:`{}^{2}` s\ :math:`{}^{-1}`)) and soil +(:math:`D_{e}` (m:sup:`2` s\ :sup:`-1`)) and soil properties can be represented as: .. math:: + :label: ZEqnNum730978 - \label{ZEqnNum730978} D_{e} =D_{0} \theta _{a}^{2} \left(\frac{\theta _{a} }{\theta _{s} } \right)^{{\raise0.7ex\hbox{$ 3 $}\!\mathord{\left/ {\vphantom {3 b}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ b $}} } , where :math:`\theta _{a}` and :math:`\theta _{s}` are the air-filled @@ -436,26 +415,26 @@ Hasegawa (2005) have shown that the original Millington-Quirk closely in unsaturated peat soils: .. math:: + :label: ZEqnNum437147 - \label{ZEqnNum437147} D_{e} =D_{0} \frac{\theta _{a} ^{{\raise0.7ex\hbox{$ 10 $}\!\mathord{\left/ {\vphantom {10 3}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ 3 $}} } }{\theta _{s} ^{2} } In CLM, we applied equation for soils with zero organic matter content -and equation for soils with more than 130 kg m\ :math:`{}^{-3}` organic +and equation for soils with more than 130 kg m\ :sup:`-3` organic matter content. A linear interpolation between these two limits is -applied for soils with SOM content below 130 kg m\ :math:`{}^{-3}`. For +applied for soils with SOM content below 130 kg m\ :sup:`-3`. For aqueous diffusion in the saturated part of the soil column, we applied (Moldrup et al. 2003): .. math:: + :label: 19.14) - \label{19.14)} D_{e} =D_{0} \theta _{s} ^{2} . To simplify the solution, we assumed that gaseous diffusion dominates above the water table interface and aqueous diffusion below the water table interface. Descriptions, baseline values, and dimensions for -parameters specific to the CH\ :math:`{}_{4}` model are given in Table +parameters specific to the CH\ :sub:`4` model are given in Table 19.1. For freezing or frozen soils below the water table, diffusion is limited to the remaining liquid (CLM allows for some freezing point depression), and the diffusion coefficients are scaled by the @@ -465,7 +444,7 @@ equilibrium is assumed at the interface with the water table. 19.7.4 Boundary Conditions ^^^^^^^^^^^^^^^^^^^^^^^^^^ -We assume the CH\ :math:`{}_{4}` and O\ :math:`{}_{2}` surface fluxes +We assume the CH\ :sub:`4` and O\ :sub:`2` surface fluxes can be calculated from an effective conductance and a gaseous concentration gradient between the atmospheric concentration and either the gaseous concentration in the first soil layer (unsaturated soils) or @@ -481,7 +460,7 @@ with a series combination: :math:`\left[\frac{1}{w} +\frac{\Delta x_{1} }{D_{1} } \right]^{-1}` , and if the top layer is saturated, this term is replaced with :math:`\left[\frac{K_{H} }{w} +\frac{\frac{1}{2} \Delta x_{1} }{D_{1} } \right]^{-1}` , -where *K\ :math:`{}_{H}`* is the Henry’s law equilibrium constant. +where :math:`{K}_{H}` is the Henry’s law equilibrium constant. When snow is present, a resistance is added to account for diffusion through the snow based on the Millington-Quirk expression (equation ) @@ -492,7 +471,7 @@ ponding depth to diffusivity. The overall conductance is taken as the series combination of surface, snow, and ponding resistances. We assume a zero flux gradient at the bottom of the soil column. -19.7.5 Crank-Nicholson Solution +Crank-Nicholson Solution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Equation is solved using a Crank-Nicholson solution (Press et al. 1992), @@ -500,13 +479,13 @@ which combines fully explicit and implicit representations of the mass balance. The fully explicit decomposition of equation can be written as .. math:: + :label: ZEqnNum395184 - \label{ZEqnNum395184} \frac{R_{j}^{n+1} C_{j}^{n+1} -R_{j}^{n} C_{j}^{n} }{\Delta t} =\frac{1}{\Delta x_{j} } \left[\frac{D_{p1}^{n} }{\Delta x_{p1}^{} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{n} }{\Delta x_{m1}^{} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+S_{j}^{n} , where *j* refers to the cell in the vertically discretized soil column (increasing downward), *n* refers to the current time step, -*:math:`\Delta`\ t* is the time step (s), *p1* is *j+½*, *m1* is *j-½*, +:math:`\Delta`\ *t* is the time step (s), *p1* is *j+½*, *m1* is *j-½*, and :math:`S_{j}^{n}` is the net source at time step *n* and position *j*, i.e., :math:`S_{j}^{n} =P\left(j,n\right)-E\left(j,n\right)-A\left(j,n\right)-O\left(j,n\right)`. @@ -520,15 +499,15 @@ Using an average of the fully implicit and fully explicit relationships gives: .. math:: + :label: ZEqnNum463314 - \label{ZEqnNum463314} \begin{array}{l} {-\frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1}^{} } C_{j-1}^{n+1} +\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(\frac{D_{p1}^{} }{\Delta x_{p1}^{} } +\frac{D_{m1}^{} }{\Delta x_{m1}^{} } \right)\right]C_{j}^{n+1} -\frac{1}{2\Delta x_{j} } \frac{D_{p1}^{} }{\Delta x_{p1}^{} } C_{j+1}^{n+1} =} \\ {\frac{R_{j}^{n} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1}^{} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1}^{} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right]} \end{array}, Equation is solved with a standard tridiagonal solver, i.e.: .. math:: + :label: 19.17) - \label{19.17)} aC_{j-1}^{n+1} +bC_{j}^{n+1} +cC_{j+1}^{n+1} =r, with coefficients specified in equation . @@ -538,7 +517,7 @@ the diffusion solution and the time-varying aggregation over inundated and non-inundated areas strictly conserves methane molecules (except for production minus consumption) and carbon atoms. -19.7.6 Interface between water table and unsaturated zone +Interface between water table and unsaturated zone ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We assume Henry’s Law equilibrium at the interface between the saturated @@ -552,8 +531,8 @@ soil element above the interface: .. math:: b=\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(K_{H} \frac{D_{p1}^{} }{\Delta x_{p1} } +\frac{D_{m1}^{} }{\Delta x_{m1} } \right)\right] .. math:: + :label: 19.18) - \label{19.18)} r=\frac{R_{j}^{n} }{\Delta t} C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -K_{H} C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] and the soil element below the interface: @@ -563,8 +542,8 @@ and the soil element below the interface: .. math:: a=-K_{H} \frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1} } .. math:: + :label: 19.19) - \label{19.19)} r=\frac{R_{j}^{n} }{\Delta t} +C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -K_{H} C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] Inundated Fraction Prediction @@ -573,26 +552,25 @@ Inundated Fraction Prediction We developed a simplified dynamic representation of spatial inundation based on recent work by Prigent et al. (2007), who described a multi-satellite approach to estimate the global monthly inundated -fraction (*F\ :math:`{}_{i}`*) over an equal area grid +fraction (:math:`{F}_{i}`) over an equal area grid (0.25:math:`\circ`\ :math:`\times`\ 0.25\ :math:`\circ` at the equator) from 1993 - 2000. They suggested that the IGBP estimate for inundation could be used as a measure of sensitivity of their detection approach at low inundation. We therefore used the sum of their satellite-derived -*F\ :math:`{}_{i}`* and the constant IGBP estimate when it was less than +:math:`{F}_{i}` and the constant IGBP estimate when it was less than 10% to perform a simple inversion for the inundated fraction for methane -production (*f\ :math:`{}_{s}`*). The method optimized three parameters -(*p\ :math:`{}_{1}`*, *p\ :math:`{}_{2}`*, *p\ :math:`{}_{3}`*) for each +production (:math:`{f}_{s}`). The method optimized three parameters +(:math:`{p}_{1}`, *p*\ :sub:`2`, :math:`{p}_{3}`) for each grid cell in a simple model based on simulated water table depth -(*z\ :math:`{}_{w}`*) and surface runoff (*Q\ :math:`{}_{r}`* (mm -s\ :math:`{}^{-1}`)): +(:math:`{z}_{w}`) and surface runoff (:math:`{Q}_{r}` (mm s\ :sup:`-1`)): .. math:: + :label: 19.20) - \label{19.20)} f_{s} =P_{1} e^{{\raise0.7ex\hbox{$ -z_{w} $}\!\mathord{\left/ {\vphantom {-z_{w} p_{2} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ p_{2} $}} } +p_{3} Q_{r} . These parameters were evaluated at the -0.5\ **:math:`\boldsymbol{{}^\circ}`** resolution, and aggregated for +0.5\ :sup:`o` resolution, and aggregated for coarser simulations. We expect that ongoing work in the hydrology submodel of CLM will alleviate the need for this crude simplification of inundated fraction in future model versions. @@ -601,19 +579,18 @@ Seasonal Inundation ------------------------ We have developed a simplified scaling factor to mimic the impact of -seasonal inundation on CH\ :math:`{}_{4}` production (see appendix B in +seasonal inundation on CH\ :sub:`4` production (see appendix B in Riley et al. (2011a) for a discussion of this simplified expression): .. math:: + :label: 19.21) - \label{19.21)} S=\frac{\beta \left(f-\bar{f}\right)+\bar{f}}{f} ,S\le 1. Here, *f* is the instantaneous inundated fraction, :math:`\bar{f}` is the annual average inundated fraction (evaluated for the previous calendar year) weighted by heterotrophic respiration, and -*:math:`\beta`* is the anoxia factor that relates the fully anoxic +:math:`\beta` is the anoxia factor that relates the fully anoxic decomposition rate to the fully oxygen-unlimited decomposition rate, all other conditions being equal. -.. |image| image:: image1 diff --git a/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst b/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst index 0e29f00078..d19fdd3f5d 100644 --- a/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst +++ b/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst @@ -135,52 +135,46 @@ Table 2.1. Plant functional types +--------------------------------------------------------------+-------------------+ | Broadleaf deciduous shrub – boreal | BDS Boreal | +--------------------------------------------------------------+-------------------+ -| C\ :math:`{}_{3}` arctic grass | - | +| C\ :sub:`3` arctic grass | - | +--------------------------------------------------------------+-------------------+ -| C\ :math:`{}_{3}` grass | - | +| C\ :sub:`3` grass | - | +--------------------------------------------------------------+-------------------+ -| C\ :math:`{}_{4}` grass | - | +| C\ :sub:`4` grass | - | +--------------------------------------------------------------+-------------------+ -| C\ :math:`{}_{3}` Unmanaged Rainfed Crop | Crop R | +| C\ :sub:`3` Unmanaged Rainfed Crop | Crop R | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{1}`\ C\ :math:`{}_{3}` Unmanaged Irrigated Crop | Crop I | +| :sup:`1`\ C\ :sub:`3` Unmanaged Irrigated Crop | Crop I | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{2}`\ Rainfed Corn | Corn R | +| :sup:`2`\ Rainfed Corn | Corn R | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{2}`\ Irrigated Corn | Corn I | +| :sup:`2`\ Irrigated Corn | Corn I | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{2}`\ Rainfed Temperate Cereals | Temp Cereal R | +| :sup:`2`\ Rainfed Temperate Cereals | Temp Cereal R | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{2}`\ Irrigated Temperate Cereals | Temp Cereal I | +| :sup:`2`\ Irrigated Temperate Cereals | Temp Cereal I | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{3}`\ Rainfed Winter Cereals | Winter Cereal R | +| :sup:`3`\ Rainfed Winter Cereals | Winter Cereal R | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{3}`\ Irrigated Winter Cereals | Winter Cereal I | +| :sup:`3`\ Irrigated Winter Cereals | Winter Cereal I | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{2}`\ Rainfed Soybean | Soybean R | +| :sup:`2`\ Rainfed Soybean | Soybean R | +--------------------------------------------------------------+-------------------+ -| :math:`{}^{2}`\ Irrigated Soybean | Soybean I | +| :sup:`2`\ Irrigated Soybean | Soybean I | +--------------------------------------------------------------+-------------------+ -:math:`{}^{1}`\ Only used if irrigation is active (Chapter 20). -:math:`{}^{2}`\ Only used if crop model is active (Chapter 20). -:math:`{}^{3}`\ Reserved for future implementations of crop model -(Chapter 20). +:sup:`1`\ Only used if irrigation is active (Chapter 20). +:sup:`2`\ Only used if crop model is active (Chapter 20). +:sup:`3`\ Reserved for future implementations of crop model (Chapter 20). Vegetation Structure ^^^^^^^^^^^^^^^^^^^^^^^^^^ Vegetation structure is defined by leaf and stem area indices -(:math:`L,\, S`) and canopy top and bottom heights -(:math:`z_{top}` ,\ :math:`z_{bot}` ) (Table 2.2). Separate leaf and -stem area indices and canopy heights are prescribed or calculated for -each PFT. Daily leaf and stem area indices are obtained from gridded -datasets of monthly values (section 2.2.3). Canopy top and bottom -heights are also obtained from gridded datasets. However, these are -currently invariant in space and time and were obtained from -PFT-specific values (Bonan et al. 2002a). When the biogeochemistry model -is active, vegetation state (LAI, SAI, canopy top and bottom heights) -are calculated prognostically (see Chapter 14). +(:math:`L,\, S`) and canopy top and bottom heights (:math:`z_{top}`,\ :math:`z_{bot}` ) (Table 2.2). Separate leaf and +stem area indices and canopy heights are prescribed or calculated for each PFT. Daily leaf and stem area indices are obtained from gridded +datasets of monthly values (section 2.2.3). Canopy top and bottom heights are also obtained from gridded datasets. However, these are +currently invariant in space and time and were obtained from PFT-specific values (Bonan et al. 2002a). When the biogeochemistry model +is active, vegetation state (LAI, SAI, canopy top and bottom heights) are calculated prognostically (see Chapter 14). Table 2.2. Prescribed plant functional type heights @@ -219,30 +213,30 @@ Table 2.2. Prescribed plant functional type heights +-----------------------------------+------------------------+------------------------+ | Crop I | 0.5 | 0.01 | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Corn R | - | - | +| :sup:`1`\ Corn R | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Corn I | - | - | +| :sup:`1`\ Corn I | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Temp Cereal R | - | - | +| :sup:`1`\ Temp Cereal R | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Temp Cereal I | - | - | +| :sup:`1`\ Temp Cereal I | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Winter Cereal R | - | - | +| :sup:`1`\ Winter Cereal R | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Winter Cereal I | - | - | +| :sup:`1`\ Winter Cereal I | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Soybean R | - | - | +| :sup:`1`\ Soybean R | - | - | +-----------------------------------+------------------------+------------------------+ -| :math:`{}^{1}`\ Soybean I | - | - | +| :sup:`1`\ Soybean I | - | - | +-----------------------------------+------------------------+------------------------+ -:math:`{}^{1}`\ Determined by the crop model (Chapter 20) +:sup:`1`\ Determined by the crop model (Chapter 20) Phenology and vegetation burial by snow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the biogeochemistry model is inactive, leaf and stem area indices -(m:math:`{}^{2}` leaf area m\ :math:`{}^{-2}` ground area) are updated +(m\ :sup:`2` leaf area m\ :sup:`-2` ground area) are updated daily by linearly interpolating between monthly values. Monthly PFT leaf area index values are developed from the 1-km MODIS-derived monthly grid cell average leaf area index of Myneni et al. (2002), as described in @@ -266,12 +260,9 @@ snow, :math:`A` is the remaining exposed leaf or stem area, {f_{veg}^{sno} = \frac{z_{sno} -z_{bot} }{z_{top} -z_{bot} } \qquad {\rm for\; tree\; and\; shrub}} \\ {f_{veg}^{sno} = \frac{\min \left(z_{sno} ,\, z_{c} \right)}{z_{c} } \qquad {\rm for\; grass\; and\; crop}} -where :math:`z_{sno} -z_{bot} \ge 0,{\rm \; }0\le f_{veg}^{sno} \le 1`, -:math:`z_{sno}` is the depth of snow (m) (section 7.2), and -:math:`z_{c} =0.2` is the snow depth when short vegetation is assumed to -be completely buried by snow (m). For numerical reasons, exposed leaf -and stem area are set to zero if less than 0.05. If the sum of exposed -leaf and stem area is zero, then the surface is treated as snow-covered +where :math:`z_{sno} -z_{bot} \ge 0,{\rm \; }0\le f_{veg}^{sno} \le 1`, :math:`z_{sno}` is the depth of snow (m) (section 7.2), and +:math:`z_{c} = 0.2` is the snow depth when short vegetation is assumed to be completely buried by snow (m). For numerical reasons, exposed leaf +and stem area are set to zero if less than 0.05. If the sum of exposed leaf and stem area is zero, then the surface is treated as snow-covered ground. Model Input Requirements @@ -299,44 +290,44 @@ Table 2.3. Atmospheric input to land model +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Field | variable name | units | +======================================================+================================================+=================================================+ -| :math:`{}^{1}`\ Reference height | :math:`z'_{atm}` | m | +| :sup:`1`\ Reference height | :math:`z'_{atm}` | m | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Zonal wind at :math:`z_{atm}` | :math:`u_{atm}` | m s\ :math:`{}^{-1}` | +| Zonal wind at :math:`z_{atm}` | :math:`u_{atm}` | m s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Meridional wind at :math:`z_{atm}` | :math:`v_{atm}` | m s\ :math:`{}^{-1}` | +| Meridional wind at :math:`z_{atm}` | :math:`v_{atm}` | m s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Potential temperature | :math:`\overline{\theta _{atm} }` | K | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Specific humidity at :math:`z_{atm}` | :math:`q_{atm}` | kg kg\ :math:`{}^{-1}` | +| Specific humidity at :math:`z_{atm}` | :math:`q_{atm}` | kg kg\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Pressure at :math:`z_{atm}` | :math:`P_{atm}` | Pa | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Temperature at :math:`z_{atm}` | :math:`T_{atm}` | K | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident longwave radiation | :math:`L_{atm} \, \downarrow` | W m\ :math:`{}^{-2}` | +| Incident longwave radiation | :math:`L_{atm} \, \downarrow` | W m\ :sup:`-2` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :math:`{}^{2}`\ Liquid precipitation | :math:`q_{rain}` | mm s\ :math:`{}^{-1}` | +| :sup:`2`\ Liquid precipitation | :math:`q_{rain}` | mm s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :math:`{}^{2}`\ Solid precipitation | :math:`q_{sno}` | mm s\ :math:`{}^{-1}` | +| :sup:`2`\ Solid precipitation | :math:`q_{sno}` | mm s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident direct beam visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}^{\mu }` | W m\ :math:`{}^{-2}` | +| Incident direct beam visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}^{\mu }` | W m\ :sup:`-2` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident direct beam near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}^{\mu }` | W m\ :math:`{}^{-2}` | +| Incident direct beam near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}^{\mu }` | W m\ :sup:`-2` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident diffuse visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}` | W m\ :math:`{}^{-2}` | +| Incident diffuse visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}` | W m\ :sup:`-2` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident diffuse near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}` | W m\ :math:`{}^{-2}` | +| Incident diffuse near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}` | W m\ :sup:`-2` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Carbon dioxide (CO:math:`{}_{2}`) concentration | :math:`c_{a}` | ppmv | +| Carbon dioxide (CO:sub:`2`) concentration | :math:`c_{a}` | ppmv | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :math:`{}^{3}`\ Aerosol deposition rate | :math:`D_{sp}` | kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}` | +| :sup:`3`\ Aerosol deposition rate | :math:`D_{sp}` | kg m\ :sup:`-2` s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :math:`{}^{4}`\ Nitrogen deposition rate | :math:`NF_{ndep\_ s{\it min}n}` | g (N) m\ :math:`{}^{-2}` yr\ :math:`{}^{-1}` | +| :sup:`4`\ Nitrogen deposition rate | :math:`NF_{ndep\_ s{\it min}n}` | g (N) m\ :sup:`-2` yr\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :math:`{}^{5}`\ Lightning frequency | :math:`I_{l}` | flash km\ :math:`{}^{-2}` hr\ :math:`{}^{-1}` | +| :sup:`5`\ Lightning frequency | :math:`I_{l}` | flash km\ :sup:`-2` hr\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -:math:`{}^{1}`\ The atmospheric reference height received from the +:sup:`1`\ The atmospheric reference height received from the atmospheric model :math:`z'_{atm}` is assumed to be the height above the surface as defined by the roughness length :math:`z_{0}` plus displacement height :math:`d`. Thus, the reference height used for flux @@ -346,12 +337,12 @@ reference heights for temperature, wind, and specific humidity :math:`z_{atm,\, w}` ) are required. These are set equal to\ :math:`z_{atm}` . -:math:`{}^{2}`\ The placeCAM provides convective and large-scale liquid +:sup:`2`\ The placeCAM provides convective and large-scale liquid and solid precipitation, which are added to yield total liquid precipitation :math:`q_{rain}` and solid precipitation :math:`q_{sno}` . -:math:`{}^{3}`\ There are 14 aerosol deposition rates required depending +:sup:`3`\ There are 14 aerosol deposition rates required depending on species and affinity for bonding with water; 8 of these are dust deposition rates (dry and wet rates for 4 dust size bins, :math:`D_{dst,\, dry1} ,\, D_{dst,\, dry2} ,\, D_{dst,\, dry3} ,\, D_{dst,\, dry4}` , @@ -368,41 +359,41 @@ time-varying (annual cycle or transient), globally-gridded deposition file defined in the namelist (see the CLM4.5 User’s Guide). Aerosol deposition rates were calculated in a transient 1850-2009 CAM simulation (at a resolution of 1.9x2.5x26L) with interactive chemistry (troposphere -and stratosphere) driven by CCSM3 20\ :math:`{}^{th}` century +and stratosphere) driven by CCSM3 20\ :sup:`th` century sea-surface temperatures and emissions (Lamarque et al. 2010) for short-lived gases and aerosols; observed concentrations were specified -for methane, N\ :math:`{}_{2}`\ O, the ozone-depleting substances (CFCs) -,and CO\ :math:`{}_{2}`. The fluxes are used by the snow-related +for methane, N\ :sub:`2`\ O, the ozone-depleting substances (CFCs) +,and CO\ :sub:`2`. The fluxes are used by the snow-related parameterizations (Chapters 3 and 7). -:math:`{}^{4}`\ The nitrogen deposition rate is required by the +:sup:`4`\ The nitrogen deposition rate is required by the biogeochemistry model when active and represents the total deposition of mineral nitrogen onto the land surface, combining deposition of -NO\ :math:`{}_{y}` and NH\ :math:`{}_{x}`. The rate is supplied either +NO\ :sub:`y` and NH\ :sub:`x`. The rate is supplied either as a time-invariant spatially-varying annual mean rate or time-varying for a transient simulation. Nitrogen deposition rates were calculated from the same CAM chemistry simulation that generated the aerosol deposition rates. -:math:`{}^{5}`\ Climatological 3-hourly lightning frequency at -:math:`\sim`\ 1.8\ :math:`{}^{o}` resolution is provided, which was +:sup:`5`\ Climatological 3-hourly lightning frequency at +:math:`\sim`\ 1.8\ :sup:`o` resolution is provided, which was calculated via bilinear interpolation from 1995-2011 NASA LIS/OTD grid -product v2.2 (http://ghrc.msfc.nasa.gov) 2-hourly, 2.5\ :math:`{}^{o}` +product v2.2 (http://ghrc.msfc.nasa.gov) 2-hourly, 2.5\ :sup:`o` lightning frequency data. In future versions of the model, lightning data may be obtained directly from the atmosphere model. -Density of air (:math:`\rho _{atm}` ) (kg m\ :math:`{}^{-3}`) is also +Density of air (:math:`\rho _{atm}` ) (kg m\ :sup:`-3`) is also required but is calculated directly from :math:`\rho _{atm} =\frac{P_{atm} -0.378e_{atm} }{R_{da} T_{atm} }` where :math:`P_{atm}` is atmospheric pressure (Pa), :math:`e_{atm}` is atmospheric vapor pressure (Pa), :math:`R_{da}` is the gas constant for -dry air (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), and +dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), and :math:`T_{atm}` is the atmospheric temperature (K). The atmospheric vapor pressure :math:`e_{atm}` is derived from atmospheric specific -humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`) as +humidity :math:`q_{atm}` (kg kg\ :sup:`-1`) as :math:`e_{atm} =\frac{q_{atm} P_{atm} }{0.622+0.378q_{atm} }` . -The O\ :math:`{}_{2}` partial pressure (Pa) is required but is +The O\ :sub:`2` partial pressure (Pa) is required but is calculated from molar ratio and the atmospheric pressure :math:`P_{atm}` as :math:`o_{i} =0.209P_{atm}` . @@ -411,17 +402,17 @@ Table 2.4. Land model output to atmospheric model +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Field | Variable name | units | +=======================================+================================================+==============================================================+ -| :math:`{}^{1}`\ Latent heat flux | :math:`\lambda _{vap} E_{v} +\lambda E_{g}` | W m\ :math:`{}^{-2}` | +| :sup:`1`\ Latent heat flux | :math:`\lambda _{vap} E_{v} +\lambda E_{g}` | W m\ :sup:`-2` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Sensible heat flux | :math:`H_{v} +H_{g}` | W m\ :math:`{}^{-2}` | +| Sensible heat flux | :math:`H_{v} +H_{g}` | W m\ :sup:`-2` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Water vapor flux | :math:`E_{v} +E_{g}` | mm s\ :math:`{}^{-1}` | +| Water vapor flux | :math:`E_{v} +E_{g}` | mm s\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Zonal momentum flux | :math:`\tau _{x}` | kg m\ :math:`{}^{-1}` s\ :math:`{}^{-2}` | +| Zonal momentum flux | :math:`\tau _{x}` | kg m\ :sup:`-1` s\ :sup:`-2` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Meridional momentum flux | :math:`\tau _{y}` | kg m\ :math:`{}^{-1}` s\ :math:`{}^{-2}` | +| Meridional momentum flux | :math:`\tau _{y}` | kg m\ :sup:`-1` s\ :sup:`-2` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Emitted longwave radiation | :math:`L\, \uparrow` | W m\ :math:`{}^{-2}` | +| Emitted longwave radiation | :math:`L\, \uparrow` | W m\ :sup:`-2` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Direct beam visible albedo | :math:`I\, \uparrow _{vis}^{\mu }` | - | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ @@ -431,33 +422,33 @@ Table 2.4. Land model output to atmospheric model +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Diffuse near-infrared albedo | :math:`I\, \uparrow _{nir}` | - | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Absorbed solar radiation | :math:`\vec{S}` | W m\ :math:`{}^{-2}` | +| Absorbed solar radiation | :math:`\vec{S}` | W m\ :sup:`-2` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Radiative temperature | :math:`T_{rad}` | K | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Temperature at 2 meter height | :math:`T_{2m}` | K | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Specific humidity at 2 meter height | :math:`q_{2m}` | kg kg\ :math:`{}^{-1}` | +| Specific humidity at 2 meter height | :math:`q_{2m}` | kg kg\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Snow water equivalent | :math:`W_{sno}` | m | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Aerodynamic resistance | :math:`r_{am}` | s m\ :math:`{}^{-1}` | +| Aerodynamic resistance | :math:`r_{am}` | s m\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Friction velocity | :math:`u_{*}` | m s\ :math:`{}^{-1}` | +| Friction velocity | :math:`u_{*}` | m s\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| :math:`{}^{2}`\ Dust flux | :math:`F_{j}` | kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}` | +| :sup:`2`\ Dust flux | :math:`F_{j}` | kg m\ :sup:`-2` s\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Net ecosystem exchange | NEE | kgCO\ :math:`{}_{2}` m\ :math:`{}^{-2}` s\ :math:`{}^{-1}` | +| Net ecosystem exchange | NEE | kgCO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -:math:`{}^{1}`\ :math:`\lambda _{vap}` is the latent heat of -vaporization (J kg\ :math:`{}^{-1}`) (Table 2.6) and :math:`\lambda` is +:sup:`1`\ :math:`\lambda _{vap}` is the latent heat of +vaporization (J kg\ :sup:`-1`) (Table 2.6) and :math:`\lambda` is either the latent heat of vaporization :math:`\lambda _{vap}` or latent -heat of sublimation :math:`\lambda _{sub}` (J kg\ :math:`{}^{-1}`) +heat of sublimation :math:`\lambda _{sub}` (J kg\ :sup:`-1`) (Table 2.6) depending on the liquid water and ice content of the top snow/soil layer (section 5.4). -:math:`{}^{2}`\ There are :math:`j=1,\ldots ,4` dust transport bins. +:sup:`2`\ There are :math:`j=1,\ldots ,4` dust transport bins. Initialization ^^^^^^^^^^^^^^^^^^^^ @@ -485,9 +476,9 @@ surface ground temperature :math:`T_{g}` and soil layer temperature :math:`T_{i}` , for :math:`i=1,\ldots ,N_{levgrnd}` , of 274 K, vegetation temperature :math:`T_{v}` of 283 K, no snow or canopy water (:math:`W_{sno} =0`, :math:`W_{can} =0`), and volumetric soil water -content :math:`\theta _{i} =0.15` mm\ :math:`{}^{3}` mm\ :math:`{}^{-3}` +content :math:`\theta _{i} =0.15` mm\ :sup:`3` mm\ :sup:`-3` for layers :math:`i=1,\ldots ,N_{levsoi}` and :math:`\theta _{i} =0.0` -mm\ :math:`{}^{3}` mm\ :math:`{}^{-3}` for layers +mm\ :sup:`3` mm\ :sup:`-3` for layers :math:`i=N_{levsoi} +1,\ldots ,N_{levgrnd}` . placeLake temperatures (:math:`T_{g}` and :math:`T_{i}` ) are initialized at 277 K and :math:`W_{sno} =0`. @@ -497,12 +488,12 @@ Glacier temperatures (:math:`T_{g} =T_{snl+1}` and :math:`T_{i}` for of the number of snow layers, i.e., :math:`snl` ranges from –5 to 0) are initialized to 250 K with a snow water equivalent :math:`W_{sno} =1000` mm, snow depth :math:`z_{sno} =\frac{W_{sno} }{\rho _{sno} }` (m) where -:math:`\rho _{sno} =250` kg m\ :math:`{}^{-3}` is an initial estimate +:math:`\rho _{sno} =250` kg m\ :sup:`-3` is an initial estimate for the bulk density of snow, and :math:`\theta _{i}` \ =1.0 for :math:`i=1,\ldots ,N_{levgrnd}` . The snow layer structure (e.g., number of snow layers :math:`snl` and layer thickness) is initialized based on the snow depth (section 6.1). The snow liquid water and ice contents (kg -m\ :math:`{}^{-2}`) are initialized as :math:`w_{liq,\, i} =0` and +m\ :sup:`-2`) are initialized as :math:`w_{liq,\, i} =0` and :math:`w_{ice,\, i} =\Delta z_{i} \rho _{sno}` , respectively, where :math:`i=snl+1,\ldots ,0` are the snow layers, and :math:`\Delta z_{i}` is the thickness of snow layer :math:`i` (m). The soil liquid water and @@ -512,7 +503,7 @@ ice contents are initialized as :math:`w_{liq,\, i} =0` and :math:`w_{liq,\, i} =\Delta z_{i} \rho _{liq} \theta _{i}` and :math:`w_{ice,\, i} =0` for :math:`T_{i} >T_{f}` , where :math:`\rho _{ice}` and :math:`\rho _{liq}` are the densities of ice -and liquid water (kg m\ :math:`{}^{-3}`) (Table 2.6), and :math:`T_{f}` +and liquid water (kg m\ :sup:`-3`) (Table 2.6), and :math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). All vegetated and glacier land units are initialized with water stored in the unconfined aquifer and unsaturated soil :math:`W_{a} =4000` mm and water table @@ -540,46 +531,46 @@ resolution +--------------------------------------------+---------------------------+ | Surface Field | Resolution | +============================================+===========================+ -| Percent glacier | 0.05\ :math:`\circ` | +| Percent glacier | 0.05\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Percent lake and lake depth | 0.05\ :math:`\circ` | +| Percent lake and lake depth | 0.05\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Percent urban | 0.05\ :math:`\circ` | +| Percent urban | 0.05\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Percent plant functional types (PFTs) | 0.05\ :math:`\circ` | +| Percent plant functional types (PFTs) | 0.05\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Monthly leaf and stem area index | 0.5\ :math:`\circ` | +| Monthly leaf and stem area index | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Canopy height (top, bottom) | 0.5\ :math:`\circ` | +| Canopy height (top, bottom) | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Soil color | 0.5\ :math:`\circ` | +| Soil color | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Percent sand, percent clay | 0.083\ :math:`{}^\circ` | +| Percent sand, percent clay | 0.083\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Soil organic matter density | 0.083\ :math:`\circ` | +| Soil organic matter density | 0.083\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Maximum fractional saturated area | 0.125\ :math:`\circ` | +| Maximum fractional saturated area | 0.125\ :sup:`o` | +--------------------------------------------+---------------------------+ | Elevation | 1km | +--------------------------------------------+---------------------------+ | Slope | 1km | +--------------------------------------------+---------------------------+ -| Biogenic Volatile Organic Compounds | 0.5\ :math:`{}^\circ` | +| Biogenic Volatile Organic Compounds | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Crop Irrigation | 0.083\ :math:`{}^\circ` | +| Crop Irrigation | 0.083\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Managed crops | 0.5\ :math:`{}^\circ` | +| Managed crops | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Population density | 0.5\ :math:`{}^\circ` | +| Population density | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Gross domestic production | 0.5\ :math:`{}^\circ` | +| Gross domestic production | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Peat area fraction | 0.5\ :math:`{}^\circ` | +| Peat area fraction | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -| Peak month of agricultural waste burning | 0.5\ :math:`{}^\circ` | +| Peak month of agricultural waste burning | 0.5\ :sup:`o` | +--------------------------------------------+---------------------------+ -At the base spatial resolution of 0.05\ :math:`\circ`, the percentage of +At the base spatial resolution of 0.05\ :sup:`o`, the percentage of each PFT is defined with respect to the vegetated portion of the grid cell and the sum of the PFTs is 100%. The percent lake, wetland, glacier, and urban at their base resolution are specified with respect @@ -619,12 +610,12 @@ elevation are needed when running CLM4 with multiple glacier elevation classes. Percent lake and lake depth are area-averaged from the 90-second -resolution data of Kourzeneva (2009, 2010) to the 0.05\ :math:`{}^\circ` +resolution data of Kourzeneva (2009, 2010) to the 0.05\ :sup:`o` resolution using the MODIS land-mask. Percent urban is derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity and slope (Dobson et al. 2000) as described by Jackson et al. (2010) at 1km -resolution and aggregated to 0.05\ :math:`{}^\circ`. A number of urban +resolution and aggregated to 0.05\ :sup:`o`. A number of urban radiative, thermal, and morphological fields are also required and are obtained from Jackson et al. (2010). Their description can be found in Table 3 of the Community Land Model Urban (CLMU) technical note (Oleson @@ -651,7 +642,7 @@ Geosphere-Biosphere Programme (IGBP) soil dataset (Global Soil Data Task each soil layer were used to create a mineral soil texture dataset (Bonan et al. 2002b). Soil organic matter data is merged from two sources. The majority of the globe is from ISRIC-WISE (Batjes, 2006). -The high latitudes come from the 0.25\ :math:`{}^\circ` version of the +The high latitudes come from the 0.25\ :sup:`o` version of the Northern Circumpolar Soil Carbon Database (Hugelius et al. 2012). Both datasets report carbon down to 1m depth. Carbon is partitioned across the top seven CLM4 layers (:math:`\sim`\ 1m depth) as in Lawrence and @@ -659,12 +650,12 @@ Slater (2008). The maximum fractional saturated area (:math:`f_{\max }` ) is used in determining surface runoff and infiltration (section 7.3). Maximum -fractional saturated area at 0.125\ :math:`{}^{o}` resolution is +fractional saturated area at 0.125\ :sup:`o` resolution is calculated from 1-km compound topographic indices (CTIs) based on the USGS HYDRO1K dataset (Verdin and Greenlee 1996) following the algorithm in Niu et al. (2005). :math:`f_{\max }` is the ratio between the number of 1-km pixels with CTIs equal to or larger than the mean CTI and the -total number of pixels in a 0.125\ :math:`{}^\circ` grid cell. See +total number of pixels in a 0.125\ :sup:`o` grid cell. See section 7.3.1 and Li et al. (2013b) for further details. Slope and elevation are also obtained from the USGS HYDRO1K 1-km dataset (Verdin and Greenlee 1996). Slope is used in the River Transport Model (Chapter @@ -719,21 +710,21 @@ beneath irrigated crops. Several input datasets are required for the fire model (Li et al. 2013a) including population density, gross domestic production, peat area fraction, and peak month of agricultural waste burning. Population -density at 0.5\ :math:`{}^{o}` resolution for 1850-2100 combines 5-min +density at 0.5\ :sup:`o` resolution for 1850-2100 combines 5-min resolution decadal population density data for 1850–1980 from the Database of the Global Environment version 3.1 (HYDEv3.1) with -0.5\ :math:`{}^{o}` resolution population density data for 1990, 1995, +0.5\ :sup:`o` resolution population density data for 1990, 1995, 2000, and 2005 from the Gridded Population of the World version 3 dataset (GPWv3) (CIESIN, 2005). Gross Domestic Production (GDP) per -capita in 2000 at 0.5\ :math:`{}^{o}` is from Van Vuuren et al. (2006), +capita in 2000 at 0.5\ :sup:`o` is from Van Vuuren et al. (2006), which is the base-year GDP data for IPCC-SRES and derived from country-level World Bank’s World Development Indicators (WDI) measured in constant 1995 US$ (World Bank, 2004) and the UN Statistics Database -(UNSTAT, 2005). The peatland area fraction at 0.5\ :math:`{}^{o}` +(UNSTAT, 2005). The peatland area fraction at 0.5\ :sup:`o` resolution is derived from three vector datasets: peatland data in Indonesia and Malaysian Borneo (Olson et al. 2001); peatland data in Canada (Tarnocai et al. 2011); and bog, fen and mire data in boreal -regions (north of 45\ :math:`{}^{o}`\ N) outside Canada provided by the +regions (north of 45\ :sup:`o`\ N) outside Canada provided by the Global Lakes and Wetlands Database (GLWD) (Lehner and Döll, 2004). The climatological peak month for agricultural waste burning is from van der Werf et al. (2010). @@ -753,30 +744,30 @@ of the components in the coupled modeling system, are presented in Table :widths: 40, 20, 20, 20 "Pi", :math:`\pi`, 3.14159265358979323846, "\-" - "Acceleration of gravity", :math:`g`, 9.80616, m s\ :math:`{}^{-2}` + "Acceleration of gravity", :math:`g`, 9.80616, m s\ :sup:`-2` "Standard pressure", :math:`P_{std}`, 101325, "Pa" - "Stefan-Boltzmann constant", :math:`\sigma`, 5.67 :math:`\times 10^{-8}`, W m :math:`{}^{-2}` K :math:`{}^{-4}` - "Boltzmann constant", :math:`\kappa`, 1.38065 :math:`\times 10^{-23}`, J K :math:`{}^{-1}` molecule :math:`{}^{-1}` - "Avogadro’s number", :math:`N_{A}`, 6.02214 :math:`\times 10^{26}`, molecule kmol\ :math:`{}^{-1}` - "Universal gas constant", :math:`R_{gas}`, :math:`N_{A} \kappa`, J K :math:`{}^{-1}` kmol :math:`{}^{-1}` - "Molecular weight of dry air", :math:`MW_{da}`, 28.966, kg kmol :math:`{}^{-1}` - "Dry air gas constant", :math:`R_{da}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{da} }} \right. \kern-\nulldelimiterspace} MW_{da} }`, J K :math:`{}^{-1}` kg :math:`{}^{-1}` - "Molecular weight of water vapor", :math:`MW_{wv}`, 18.016, kg kmol :math:`{}^{-1}` - "Water vapor gas constant", :math:`R_{wv}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{wv} }} \right. \kern-\nulldelimiterspace} MW_{wv} }`, J K :math:`{}^{-1}` kg :math:`{}^{-1}` + "Stefan-Boltzmann constant", :math:`\sigma`, 5.67 :math:`\times 10^{-8}`, W m :sup:`-2` K :math:`{}^{-4}` + "Boltzmann constant", :math:`\kappa`, 1.38065 :math:`\times 10^{-23}`, J K :sup:`-1` molecule :sup:`-1` + "Avogadro’s number", :math:`N_{A}`, 6.02214 :math:`\times 10^{26}`, molecule kmol\ :sup:`-1` + "Universal gas constant", :math:`R_{gas}`, :math:`N_{A} \kappa`, J K :sup:`-1` kmol :sup:`-1` + "Molecular weight of dry air", :math:`MW_{da}`, 28.966, kg kmol :sup:`-1` + "Dry air gas constant", :math:`R_{da}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{da} }} \right. \kern-\nulldelimiterspace} MW_{da} }`, J K :sup:`-1` kg :sup:`-1` + "Molecular weight of water vapor", :math:`MW_{wv}`, 18.016, kg kmol :sup:`-1` + "Water vapor gas constant", :math:`R_{wv}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{wv} }} \right. \kern-\nulldelimiterspace} MW_{wv} }`, J K :sup:`-1` kg :sup:`-1` "Von Karman constant", :math:`k`, 0.4, "\-" "Freezing temperature of fresh water", :math:`T_{f}`, 273.5, K - "Density of liquid water", :math:`\rho _{liq}`, 1000, kg m :math:`{}^{-3}` - "Density of ice", :math:`\rho _{ice}`, 917, kg m :math:`{}^{-3}` - "Specific heat capacity of dry air", :math:`C_{p}`, 1.00464 :math:`\times 10^{3}`, J kg :math:`{}^{-1}` K :math:`{}^{-1}` - "Specific heat capacity of water", :math:`C_{liq}`, 4.188 :math:`\times 10^{3}`, J kg :math:`{}^{-1}` K :math:`{}^{-1}` - "Specific heat capacity of ice", :math:`C_{ice}`, 2.11727 :math:`\times 10^{3}`, J kg :math:`{}^{-1}` K :math:`{}^{-1}` - "Latent heat of vaporization", :math:`\lambda _{vap}`, 2.501 :math:`\times 10^{6}`, J kg :math:`{}^{-1}` - "Latent heat of fusion", :math:`L_{f}`, 3.337 :math:`\times 10^{5}`, J kg :math:`{}^{-1}` - "Latent heat of sublimation", :math:`\lambda _{sub}`, :math:`\lambda _{vap} +L_{f}`, J kg :math:`{}^{-1}` - :math:`{}^{1}` "Thermal conductivity of water", :math:`\lambda _{liq}`, 0.57, W m :math:`{}^{-1}` K :math:`{}^{-1}` - :math:`{}^{1}` "Thermal conductivity of ice", :math:`\lambda _{ice}`, 2.29, W m :math:`{}^{-1}` K :math:`{}^{-1}` - :math:`{}^{1}` "Thermal conductivity of air", :math:`\lambda _{air}`, 0.023 W m :math:`{}^{-1}` K :math:`{}^{-1}` + "Density of liquid water", :math:`\rho _{liq}`, 1000, kg m :sup:`-3` + "Density of ice", :math:`\rho _{ice}`, 917, kg m :sup:`-3` + "Specific heat capacity of dry air", :math:`C_{p}`, 1.00464 :math:`\times 10^{3}`, J kg :sup:`-1` K :sup:`-1` + "Specific heat capacity of water", :math:`C_{liq}`, 4.188 :math:`\times 10^{3}`, J kg :sup:`-1` K :sup:`-1` + "Specific heat capacity of ice", :math:`C_{ice}`, 2.11727 :math:`\times 10^{3}`, J kg :sup:`-1` K :sup:`-1` + "Latent heat of vaporization", :math:`\lambda _{vap}`, 2.501 :math:`\times 10^{6}`, J kg :sup:`-1` + "Latent heat of fusion", :math:`L_{f}`, 3.337 :math:`\times 10^{5}`, J kg :sup:`-1` + "Latent heat of sublimation", :math:`\lambda _{sub}`, :math:`\lambda _{vap} +L_{f}`, J kg :sup:`-1` + :sup:`1` "Thermal conductivity of water", :math:`\lambda _{liq}`, 0.57, W m :sup:`-1` K :sup:`-1` + :sup:`1` "Thermal conductivity of ice", :math:`\lambda _{ice}`, 2.29, W m :sup:`-1` K :sup:`-1` + :sup:`1` "Thermal conductivity of air", :math:`\lambda _{air}`, 0.023 W m :sup:`-1` K :sup:`-1` "Radius of the earth", :math:`R_{e}`, 6.37122, :math:`\times 10^{6}` m -:math:`{}^{1}`\ Not shared by other components of the coupled modeling system. +:sup:`1`\ Not shared by other components of the coupled modeling system. diff --git a/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst b/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst index 2c378b3aec..570028bc8b 100644 --- a/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst +++ b/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst @@ -1,5 +1,3 @@ -**** - Crops and Irrigation ======================== @@ -33,7 +31,7 @@ Drewniak et al. (2013). The crop model ------------------- -20.2.1 Introduction +Introduction ^^^^^^^^^^^^^^^^^^^ Groups developing Earth System Models generally account for the human @@ -49,11 +47,11 @@ biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. AgroIBIS is a state-of-the-art land surface model with options to -simulate dynamic vegetation (Kucharik et al. ** 2000) and interactive +simulate dynamic vegetation (Kucharik et al. 2000) and interactive crop management (Kucharik and Brye 2003). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 -[CLM3.0, Oleson et al. ** (2004)] (not published), then coupled to the +[CLM3.0, Oleson et al. (2004)] (not published), then coupled to the CLM3.5 (Levis et al. 2009) and later released to the community with CLM4CN (Levis et al. 2012). @@ -63,17 +61,15 @@ simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land -use, and land management change (e.g., Kucharik and Brye 2003; Lobell et -al. ** 2006). +use, and land management change (e.g., Kucharik and Brye 2003; Lobell et al. 2006). -20.2.2 Crop plant functional types +Crop plant functional types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CLM’s default list of plant functional types (pfts) includes an unmanaged crop (Table 2.1) treated as a second C3 grass. The unmanaged crop has grid cell coverage assigned from satellite data, as do all -natural pfts when CLM’s dynamic vegetation model (CNDV; Castillo et al. -2012) is not active. +natural pfts when CLM’s dynamic vegetation model (CNDV; Castillo et al. 2012) is not active. The new crop pfts used in the CLM get grid cell coverage from the present-day crop dataset of Portmann et al. (2010). We assign these @@ -97,7 +93,7 @@ CLM setting). Managed crop PFTs in the human managed land unit do not share soil columns and thus permit for differences in land management between crops. -20.2.3 Phenology +Phenology ^^^^^^^^^^^^^^^^ CLM4.5CN includes evergreen, seasonally deciduous (responding to changes @@ -111,104 +107,102 @@ continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. -20.2.3.1 Planting +Planting ''''''''''''''''' Corn and temperate cereals must meet the following requirements between -April 1\ :math:`{}^{st}` and June 14\ :math:`{}^{th}` for planting in -the northern hemisphere (NH): +April 1\ :sup:`st` and June 14\ :sup:`th` for planting in the northern hemisphere (NH): .. math:: + :label: ZEqnNum568682 - \label{ZEqnNum568682} - \begin{array}{l} {T_{10d} >T_{p} } \\ {T_{10d}^{\min } >T_{p}^{\min } } \\ {GDD_{8} \ge GDD_{\min } } \end{array} + \begin{array}{l} + {T_{10d} >T_{p} } \\ + {T_{10d}^{\min } >T_{p}^{\min } } \\ + {GDD_{8} \ge GDD_{\min } } + \end{array} -where *T*\ :math:`{}_{10}`\ *:math:`{}_{d}`* is the 10-day running mean -of *T*\ :math:`{}_{2}`\ *:math:`{}_{m}`*, (the simulated 2-m air -temperature at every model time step) and :math:`T_{10d}^{\min }` is +where :math:`{T}_{10d}` is the 10-day running mean of :math:`{T}_{2m}`, (the simulated 2-m air +temperature at every model time step) and :math:`T_{10d}^{\min}` is the 10-day running mean of :math:`T_{2m}^{\min }` (the daily minimum of -*T*\ :math:`{}_{2}`\ *:math:`{}_{m}`*). *T\ :math:`{}_{p}`* and -:math:`T_{p}^{\min }` are crop-specific coldest planting temperatures -(Table 20.1), *GDD*\ :math:`{}_{8}` is the 20-year running mean growing -degree-days (units are degree-days or :math:`{}^\circ`\ days) tracked -from April through September (NH) base 8\ :math:`{}^\circ`\ C with -maximum daily increments of 30\ :math:`{}^\circ`\ days (see Eq. ), and -*GDD*\ :math:`{}_{min }`\ is the minimum growing degree day requirement +:math:`{T}_{2m}`. :math:`{T}_{p}` and :math:`T_{p}^{\min }` are crop-specific coldest planting temperatures +(Table 20.1), :math:`{GDD}_{8}` is the 20-year running mean growing +degree-days (units are degree-days or :sup:`o` days) tracked +from April through September (NH) base 8\ :sup:`o` C with +maximum daily increments of 30\ :sup:`o` days (see Eq.XXX ), and +:math:`{GDD}_{min }`\ is the minimum growing degree day requirement (Table 20.1). Soy must meet the same requirements but between May -1\ :math:`{}^{st}` and June 14\ :math:`{}^{th}` for planting. If the -requirements in Eq. are not met by June 14\ :math:`{}^{th}`, then corn, +1\ :sup:`st` and June 14\ :sup:`th` for planting. If the +requirements in Eq. are not met by June 14\ :sup:`th`, then corn, soybean, and temperate cereals are still planted on June -15\ :math:`{}^{th}` as long as *GDD*\ :math:`{}_{8}`\ :math:`>`\ 0. In +15\ :sup:`th` as long as :math:`{GDD}_{8} > 0`. In the southern hemisphere (SH) the NH requirements apply 6 months later. -*GDD*\ :math:`{}_{8}` does not change as quickly as -*T*\ :math:`{}_{10}`\ *:math:`{}_{d}`* and :math:`T_{10d}^{\min }` , so +:math:`{GDD}_{8}` does not change as quickly as :math:`{T}_{10d}` and :math:`T_{10d}^{\min }`, so it determines whether the crop can be planted in a grid cell, while the two faster-changing variables determine when the crop may be planted. -At planting, each crop is assigned 1 g leaf C m\ :math:`{}^{-2}` pft +At planting, each crop is assigned 1 g leaf C m\ :sup:`-2` pft column area to be transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the pft’s C to N -ratio for leaves (*CN\ :math:`{}_{leaf}`*). (This differs from AgroIBIS, +ratio for leaves (:math:`{CN}_{leaf}`). (This differs from AgroIBIS, which uses a seed leaf area index instead of seed C.) At planting, the model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, -*GDD*\ :math:`{}_{mat}`, according to the following AgroIBIS rules: +:math:`{GDD}_{mat}`, according to the following AgroIBIS rules: .. math:: + :label: 20.2) - \label{20.2)} \begin{array}{l} {GDD_{{\rm mat}}^{{\rm corn}} =0.85GDD_{{\rm 8}} {\rm \; \; \; and\; \; \; 950}` 0, and *:math:`\beta`\ :math:`{}_{t}`* :math:`<` 1, -i.e., water is limiting for photosynthesis (see section 8.4). +leaf area :math:`>` 0, and :math:`\beta_{t} < 1`, i.e., water is limiting for photosynthesis (see section 8.4). If irrigation is required, the model computes the deficit between the current soil moisture content and a target soil moisture content; this deficit is the amount of water that will be added through irrigation. The target soil moisture content in each soil layer *i* -(*w\ :math:`{}_{target,i}`*, kg m\ :math:`{}^{-2}`) is a weighted +(:math:`{s}_{target,i}`, kg m\ :sup:`-2`) is a weighted average of the minimum soil moisture content that results in no water -stress in that layer (*w\ :math:`{}_{o,i}`*, kg m\ :math:`{}^{-2}`) and -the soil moisture content at saturation in that layer -(*w\ :math:`{}_{sat,i}`*, kg m\ :math:`{}^{-2}`): +stress in that layer (:math:`{s}_{o,i}`, kg m\ :sup:`-2`) and +the soil moisture content at saturation in that layer (:math:`{w}_{sat,i}`, kg m\ :sup:`-2`): .. math:: + :label: 20.7) - \label{20.7)} w_{target,i} =(1-0.7)\cdot w_{o,i} +0.7\cdot w_{sat,i} -*w\ :math:`{}_{o,i}`* is determined by inverting equation 8.19 in Oleson -et al. (2010a) to solve for the value of *s\ :math:`{}_{i}`* (soil -wetness) that makes *:math:`\Psi`\ :math:`{}_{i}`* = -*:math:`\Psi`\ :math:`{}_{o}`* (where *:math:`\Psi`\ :math:`{}_{i}`* is -the soil water matric potential and *:math:`\Psi`\ :math:`{}_{o}`* is +:math:`{w}_{o,i}` is determined by inverting equation 8.19 in Oleson +et al. (2010a) to solve for the value of :math:`{s}_{i}` (soil +wetness) that makes :math:`\Psi_{i} = \Psi_{o}` (where :math:`\Psi_{i}` is +the soil water matric potential and :math:`\Psi_{o}` is the soil water potential when stomata are fully open), and then -converting this value to units of kg m\ :math:`{}^{-2}`. -*w\ :math:`{}_{sat,i}`* is calculated simply by converting effective -porosity (section 7.4) to units of kg m\ :math:`{}^{-2}`. The value 0.7 +converting this value to units of kg m\ :sup:`-2`. +:math:`{w}_{sat,i}` is calculated simply by converting effective +porosity (section 7.4) to units of kg m\ :sup:`-2`. The value 0.7 was determined empirically, in order to give global, annual irrigation amounts that approximately match observed gross irrigation water use around the year 2000 (i.e., total water withdrawals for irrigation: -:math:`\sim` 2500 – 3000 km\ :math:`{}^{3}` year\ :math:`{}^{-1}` -(Shiklomanov 2000)). The total water deficit (*w\ :math:`{}_{deficit}`*, -kg m\ :math:`{}^{-2}`) of the column is then determined by: +:math:`\sim` 2500 – 3000 km\ :sup:`3` year\ :sup:`-1` +(Shiklomanov 2000)). The total water deficit (:math:`{w}_{deficit}`, +kg m\ :sup:`-2`) of the column is then determined by: .. math:: + :label: 20.8) - \label{20.8)} w_{deficit} =\sum _{i}\max \left(w_{target,i} -w_{liq,i} ,0\right) -where *w\ :math:`{}_{liq,i}`* (kg m\ :math:`{}^{-2}`) is the current +where :math:`{w}_{liq,i}` (kg m\ :sup:`-2`) is the current soil water content of layer *i* (Chapter 7). The max function means that a surplus in one layer cannot make up for a deficit in another layer. The sum is taken only over soil layers that contain roots. In addition, @@ -475,17 +471,17 @@ if the temperature of any soil layer is below freezing, then the sum only includes layers above the top-most frozen soil layer. The amount of water added to this column through irrigation is then -equal to *w\ :math:`{}_{deficit}`*. This irrigation is applied at a +equal to :math:`{w}_{deficit}`. This irrigation is applied at a constant rate over the following four hours. Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., -added to *q\ :math:`{}_{grnd,liq}`*: section 7.1). Added irrigation is -removed from total liquid runoff (*R\ :math:`{}_{liq}`*: Chapter 11), +added to :math:`{q}_{grnd,liq}`: section 7.1). Added irrigation is +removed from total liquid runoff ( :math:`{R}_{liq}`: Chapter 11), simulating removal from nearby rivers. The details about what is new in CLM4.5 -------------------------------------------- -20.4.1 Interactive irrigation for corn, temperate cereals, and soybean +Interactive irrigation for corn, temperate cereals, and soybean ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CLM4.0 included interactive irrigation only for the generic C3 crops, @@ -529,7 +525,7 @@ or without irrigation. In simulations without irrigation, the rainfed and irrigated crops merge into just rainfed crops at run time. Surface datasets with 16 pfts can be used for all other CLM simulations. -20.4.2 Interactive fertilization +Interactive fertilization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CLM adds nitrogen directly to the soil mineral nitrogen pool to meet @@ -537,10 +533,10 @@ crop nitrogen demands. CLM’s separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer amounts are obtained from the Agro-IBIS model (Kucharik and Brye 2003), but can be modified in CLM’s pft-physiology input dataset. -Fertilizer is reported in g N/m\ :math:`{}^{2}` by plant functional -type. Total nitrogen fertilizer amounts are 150 g N/m\ :math:`{}^{2}` -for maize, 80 g N/m\ :math:`{}^{2}` for temperate cereals, and 25 g -N/m\ :math:`{}^{2}` for soybean, representative of central U.S. annual +Fertilizer is reported in g N/m\ :sup:`2` by plant functional +type. Total nitrogen fertilizer amounts are 150 g N/m\ :sup:`2` +for maize, 80 g N/m\ :sup:`2` for temperate cereals, and 25 g +N/m\ :sup:`2` for soybean, representative of central U.S. annual fertilizer application amounts. Since CLM’s denitrification rate is high and results in a 50% loss of the unused available nitrogen each day, fertilizer is applied slowly to minimize the loss and maximize plant @@ -565,7 +561,7 @@ The crop fertilization scheme was developed in versions of the CLM prior to CLM4.5. In CLM4.5, crops with fertilization may be simulated over productive. -20.4.3 Biological nitrogen fixation for soybeans +Biological nitrogen fixation for soybeans ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Nitrogen fixation by soybeans is similar to that in the SWAT model @@ -575,40 +571,40 @@ unmet nitrogen demand; if soil nitrogen meets soybean demand, there will be no fixation during the time step. Soybean fixation is determined by .. math:: + :label: 20.10) - \label{20.10)} N_{fix} \; =\; N_{plant\_ ndemand} \; *\; min\; \left(\; 1,\; fxw,\; fxn\; \right)*\; fxg -where *N\ :math:`{}_{plant\_demand}`* is the balance of nitrogen needed +where :math:`{N}_{plant\_demand}` is the balance of nitrogen needed to reach potential growth that cannot be supplied from the soil mineral nitrogen pool, *fxw* is the soil water factor, *fxn* is the soil nitrogen factor, and *fxg* is the growth stage factor calculated by .. math:: + :label: 20.11) - \label{20.11)} fxw=\frac{wf}{0.85} .. math:: + :label: 20.12) - \label{20.12)} fxn=\; \left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }sminn\le 10} \\ {1.5-0.005\left(sminn\times 10\right)\qquad {\rm for\; 10\; <\; }sminn{\rm \; }\ge 30} \\ {1\qquad \qquad \qquad \qquad {\rm for\; }sminn>30} \end{array}\right\} .. math:: + :label: 20.13) - \label{20.13)} fxg=\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad \qquad {\rm for\; }GDD_{T_{2m} } \le 0.15} \\ {6.67\times GDD_{T_{2m} } -1\qquad \qquad \qquad {\rm for\; }0.150.75} \end{array}\right\} where *wf* is the soil water content as a fraction of the water holding capacity for the top 0.05 m, *sminn* is the total nitrogen in the soil -pool (g/m:math:`{}^{2}`), and :math:`{GDD}_{T_{2m}}` is the fraction of +pool (g/m:sup:`2`), and :math:`{GDD}_{T_{2m}}` is the fraction of growing degree-days accumulated during the growing season. :math:`N\mathrm{fix}` is added directly to the soil mineral nitrogen pool for use that time step. Nitrogen fixation occurs after the plant -has accumulated 15%\ *GDD\ :math:`{}_{mat}`* and before -75%\ *GDD\ :math:`{}_{mat}`*, so before grain fill begins. +has accumulated 15%\ :math:`{GDD}_{mat}` and before +75%\ :math:`{GDD}_{mat}`, so before grain fill begins. -20.4.4 Modified C:N ratios for crops +Modified C:N ratios for crops ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Typically, C:N ratios in plant tissue vary throughout the growing season @@ -627,7 +623,7 @@ harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growth season. -20.4.5 Nitrogen retranslocation for crops +Nitrogen retranslocation for crops ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Nitrogen retranslocation in crops occurs when nitrogen that was used for @@ -648,24 +644,22 @@ mobilized depends on the C:N ratio of the plant tissue, and is calculated as .. math:: + :label: 20.14) - \label{20.14)} leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } .. math:: + :label: 20.15) - \label{20.15)} stemn\_ to\_ retransn=\frac{c_{stem} }{CN_{stem} } -\frac{c_{stem} }{CN_{stem}^{f} } .. math:: + :label: 20.16) - \label{20.16)} frootn\_ to\_ retransn=\frac{c_{froot} }{CN_{froot} } -\frac{c_{froot} }{CN_{froot}^{f} } -where *C\ :math:`{}_{leaf}`*, *C\ :math:`{}_{stem}`*, and -*C\ :math:`{}_{froot}`* is the carbon in the plant leaf, stem, and fine -root, respectively, *CN\ :math:`{}_{leaf}`*, *CN\ :math:`{}_{stem}`*, -and *CN\ :math:`{}_{froot}`* is the pre-grain fill C:N ratio of the +where :math:`{C}_{leaf}`, :math:`{C}_{stem}`, and :math:`{C}_{froot}` is the carbon in the plant leaf, stem, and fine +root, respectively, :math:`{CN}_{leaf}`, :math:`{CN}_{stem}`, and :math:`{CN}_{froot}` is the pre-grain fill C:N ratio of the leaf, stem, and fine root respectively, and :math:`CN^f_{leaf}`, :math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively (Table 20.3). Since @@ -686,11 +680,11 @@ fine root, and reproductive pools. +----------------------------+--------+---------------------+-----------+ | Pre-grain fill stage | Corn | Temperate Cereals | Soybean | +============================+========+=====================+===========+ -| *CN\ :math:`{}_{leaf}`* | 10 | 15 | 25 | +| :math:`{CN}_{leaf}` | 10 | 15 | 25 | +----------------------------+--------+---------------------+-----------+ -| *CN\ :math:`{}_{stem}`* | 50 | 50 | 50 | +| :math:`{CN}_{stem}` | 50 | 50 | 50 | +----------------------------+--------+---------------------+-----------+ -| *CN\ :math:`{}_{froot}`* | 42 | 30 | 42 | +| :math:`{CN}_{froot}` | 42 | 30 | 42 | +----------------------------+--------+---------------------+-----------+ | Post-grain fill stage | | | | +----------------------------+--------+---------------------+-----------+ @@ -703,9 +697,7 @@ fine root, and reproductive pools. | :math:`CN_{repr}^{f}` | 50 | 40 | 60 | +----------------------------+--------+---------------------+-----------+ -**** - -20.4.6 Separate reproductive pool +Separate reproductive pool ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One notable difference between natural vegetation and crops is the diff --git a/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst b/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst index 956e1aca1a..661b1f2e6e 100644 --- a/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst +++ b/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst @@ -1,5 +1,3 @@ -.. math:: 1 - Transient Landcover Change ============================== @@ -56,13 +54,13 @@ algorithm, and :math:`n` is the index value for the :math:`dynpft\_ year(n)=year_{cur}` : .. math:: + :label: 21.1) - \label{21.1)} nt_{1} =\left\{\begin{array}{l} {1\qquad {\rm for}\qquad year_{cur} w_{t} } \end{array}\right. where .. math:: + :label: 24.8) - \label{24.8)} w_{t} =a\left(0.17M_{clay} +0.14M_{clay}^{2} \right){\rm \; \; \; \; \; \; 0}\le M_{clay} =\% clay\times 0.01\le 1 and .. math:: + :label: 24.9) - \label{24.9)} w=\frac{\theta _{1} \rho _{liq} }{\rho _{d,1} } where :math:`a=M_{clay}^{-1}` for tuning purposes, :math:`\theta _{1}` is the volumetric soil moisture in the top soil -layer (m:math:`{}^{3 }`\ m\ :math:`{}^{-3}`) (section 7.4), +layer (m:math:`{}^{3 }`\ m\ :sup:`-3`) (section 7.4), :math:`\rho _{liq}` is the density of liquid water (kg -m\ :math:`{}^{-3}`) (Table 2.6), and :math:`\rho _{d,\, 1}` is the bulk -density of soil in the top soil layer (kg m\ :math:`{}^{-3}`) defined as -in section 6.3 rather than as in Zender et al. ** (2003). +m\ :sup:`-3`) (Table 2.6), and :math:`\rho _{d,\, 1}` is the bulk +density of soil in the top soil layer (kg m\ :sup:`-3`) defined as +in section 6.3 rather than as in Zender et al. (2003). :math:`Re_{*t}^{f}` from equation is the threshold friction Reynolds factor .. math:: + :label: 24.10) - \label{24.10)} Re_{*t}^{f} =\left\{\begin{array}{l} {\frac{0.1291^{2} }{-1+1.928Re_{*t} } {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; 0.03}\le Re_{*t} \le 10} \\ {0.12^{2} \left(1-0.0858e^{-0.0617(Re_{*t} -10)} \right)^{2} {\rm \; for\; }Re_{*t} >10} \end{array}\right. and :math:`Re_{*t}` is the threshold friction Reynolds number approximation for optimally sized particles .. math:: + :label: 24.11) - \label{24.11)} Re_{*t} =0.38+1331\left(100D_{osp} \right)^{1.56} In equation , :math:`u_{*s}` ** is defined as the wind friction speed -(m s\ :math:`{}^{-1}`) accounting for the Owen effect (Owen 1964) +(m s\ :sup:`-1`) accounting for the Owen effect (Owen 1964) .. math:: + :label: 24.12) - \label{24.12)} - u_{*s} =\left\{\begin{array}{l} {u_{*} {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }U_{10} ` 1.0 would indicate a preference for the +If the :math:`{f}_{frac}` = 1.0 (no fractionation), then the fluxes +:math:`{CF}_{13C}` and :math:`{CF}_{totC}`* will be in simple +proportion to the masses :math:`{CS}_{13C\_up}` and +:math:`{CS}_{totC\_up}`. Values of :math:`{f}_{frac} < 1.0` indicate a discrimination against the heavier isotope +(:sup:`13`\ C) in the flux-generating process, while +:math:`{f}_{frac}` :math:`>` 1.0 would indicate a preference for the heavier isotope. Currently, in all cases where Eq. is used to calculate -a :math:`{}^{13}`\ C flux, *f\ :math:`{}_{frac}`* is set to 1.0. +a :sup:`13`\ C flux, :math:`{f}_{frac}` is set to 1.0. -For :math:`{}^{1}`\ :math:`{}^{4}`\ C, no fractionation is used in +For :sup:`1`\ :sup:`4`\ C, no fractionation is used in either the initial photosynthetic step, nor in subsequent fluxes from upstream to downstream pools; as discussed below, this is because -observations of :math:`{}^{1}`\ :math:`{}^{4}`\ C are typically +observations of :sup:`1`\ :sup:`4`\ C are typically described in units that implicitly correct out the fractionation of -:math:`{}^{1}`\ :math:`{}^{4}`\ C by referencing them to -:math:`{}^{1}`\ :math:`{}^{3}`\ C ratios. +:sup:`1`\ :sup:`4`\ C by referencing them to +:sup:`1`\ :sup:`3`\ C ratios. Isotope Symbols, Units, and Reference Standards ---------------------------------------------------- Carbon has two primary stable isotopes, :math:`{}^{12}`\ C and -:math:`{}^{13}`\ C. :math:`{}^{12}`\ C is the most abundant, comprising +:sup:`13`\ C. :math:`{}^{12}`\ C is the most abundant, comprising about 99% of all carbon. The isotope ratio of a compound, -*R\ :math:`{}_{A}`*, is the mass ratio of the rare isotope to the -abundant isotope +:math:`{R}_{A}`, is the mass ratio of the rare isotope to the abundant isotope .. math:: + :label: 25.2) - \label{25.2)} R_{A} =\frac{{}^{13} C_{A} }{{}^{12} C_{A} } . Carbon isotope ratios are often expressed using delta notation, -:math:`\deltaup`. The :math:`\deltaup`\ :math:`{}^{13}`\ C value of a -compound A, :math:`\deltaup`\ :math:`{}^{13}`\ C\ :math:`{}_{A}`, is the +:math:`\delta`. The :math:`\delta^{13}`\ C value of a +compound A, :math:`\delta^{13}`\ C\ :sub:`A`, is the difference between the isotope ratio of the compound, -*R\ :math:`{}_{A}`*, and that of the Pee Dee Belemnite standard, -*R\ :math:`{}_{PDB}`*, in parts per thousand +:math:`{R}_{A}`, and that of the Pee Dee Belemnite standard, :math:`{R}_{PDB}`, in parts per thousand .. math:: + :label: 25.3) - \label{25.3)} \delta ^{13} C_{A} =\left(\frac{R_{A} }{R_{PDB} } -1\right)\times 1000 -where *R\ :math:`{}_{PDB}`* = 0.0112372, and units of :math:`\deltaup` -are per mil (‰). +where :math:`{R}_{PDB}` = 0.0112372, and units of :math:`\delta` are per mil (‰). Isotopic fractionation can be expressed in several ways. One expression -of the fractionation factor is with alpha (:math:`\alphaup`) notation. +of the fractionation factor is with alpha (:math:`\alpha`) notation. For example, the equilibrium fractionation between two reservoirs A and B can be written as: .. math:: + :label: 25.4) - \label{25.4)} \alpha _{A-B} =\frac{R_{A} }{R_{B} } =\frac{\delta _{A} +1000}{\delta _{B} +1000} . -This can also be expressed using epsilon notation -(:math:`\varepsilonup`), where +This can also be expressed using epsilon notation (:math:`\epsilon`), where .. math:: + :label: 25.5) - \label{25.5)} \alpha _{A-B} =\frac{\varepsilon _{A-B} }{1000} +1 -In other words, if :math:`{\varepsilon }_{A-B}=4.4\mathrm{\textrm{‰}}`, -then :math:`\alphaup`\ :math:`{}_{A-B}`\ =1.0044. +In other words, if :math:`{\epsilon }_{A-B} = 4.4{\mathrm{‰}}`, then :math:`{\alpha}_{A-B} =1.0044`. -In addition to the stable isotopes :math:`{}^{1}`\ :math:`{}^{2}`\ C and -:math:`{}^{1}`\ :math:`{}^{3}`\ C, the unstable isotope -:math:`{}^{1}`\ :math:`{}^{4}`\ C is included in CLM. -:math:`{}^{1}`\ :math:`{}^{4}`\ C can also be described using the delta -notation: +In addition to the stable isotopes :sup:`1`\ :sup:`2`\ C and :sup:`1`\ :sup:`3`\ C, the unstable isotope +:sup:`1`\ :sup:`4`\ C is included in CLM. :sup:`1`\ :sup:`4`\ C can also be described using the delta notation: .. math:: + :label: 25.6) - \label{25.6)} \delta ^{14} C=\left(\frac{A_{s} }{A_{abs} } -1\right)\times 1000 -However, observations of :math:`{}^{1}`\ :math:`{}^{4}`\ C are typically +However, observations of :sup:`1`\ :sup:`4`\ C are typically fractionation-corrected using the following notation: .. math:: + :label: 25.7) - \label{25.7)} \Delta {}^{14} C=1000\times \left(\left(1+\frac{\delta {}^{14} C}{1000} \right)\frac{0.975^{2} }{\left(1+\frac{\delta {}^{13} C}{1000} \right)^{2} } -1\right) -where :math:`\deltaup`\ :math:`{}^{14}`\ C is the measured isotopic -fraction and :math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C corrects for +where :math:`\delta^{14}`\ C is the measured isotopic +fraction and :math:`\mathrm{\Delta}^{14}`\ C corrects for mass-dependent isotopic fractionation processes (assumed to be 0.975 for -fractionation of :math:`{}^{13}`\ C by photosynthesis). CLM assumes a -background preindustrial atmospheric :math:`{}^{14}`\ C /C ratio of -10\ :math:`{}^{-12}`, which is used for A\ :math:`{}_{abs}`. For the -reference standard A\ :math:`{}_{abs}`, which is a plant tissue and has -a :math:`\deltaup`\ :math:`{}^{13}`\ C value is :math:`\mathrm{-}`\ 25 ‰ -due to photosynthetic discrimination, -:math:`\deltaup`\ :math:`{}^{14}`\ C = -:math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C. For CLM, in order to use -the :math:`{}^{14}`\ C model independently of the :math:`{}^{13}`\ C -model, for the :math:`{}^{14}`\ C calculations, this fractionation is +fractionation of :sup:`13`\ C by photosynthesis). CLM assumes a +background preindustrial atmospheric :sup:`14`\ C /C ratio of 10\ :sup:`-12`, which is used for A\ :sub::`abs`. +For the reference standard A\ :math:`{}_{abs}`, which is a plant tissue and has +a :math:`\delta^{13}`\ C value is :math:`\mathrm{-}`\ 25 ‰ due to photosynthetic discrimination, +:math:`\delta`\ :sup:`14`\ C = :math:`\mathrm{\Delta}`\ :sup:`14`\ C. For CLM, in order to use +the :sup:`14`\ C model independently of the :sup:`13`\ C +model, for the :sup:`14`\ C calculations, this fractionation is set to zero, such that the 0.975 term becomes 1, the -:math:`\deltaup`\ :math:`{}^{13}`\ C term (for the calculation of -:math:`\deltaup`\ :math:`{}^{14}`\ C only) becomes 0, and thus -:math:`\deltaup`\ :math:`{}^{14}`\ C = -:math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C. +:math:`\delta^{13}`\ C term (for the calculation of +:math:`\delta^{14}`\ C only) becomes 0, and thus +:math:`\delta^{14}`\ C = :math:`\mathrm{\Delta}`\ :sup:`14`\ C. Carbon Isotope Discrimination During Photosynthesis -------------------------------------------------------- Photosynthesis is modeled in CLM as a two-step process: diffusion of -CO\ :math:`{}_{2}` into the stomatal cavity, followed by enzymatic +CO\ :sub:`2` into the stomatal cavity, followed by enzymatic fixation (Chapter 8). Each step is associated with a kinetic isotope effect. The kinetic isotope effect during diffusion of -CO\ :math:`{}_{2}` through the stomatal opening is 4.4‰. The kinetic -isotope effect during fixation of CO\ :math:`{}_{2}` with Rubisco is +CO\ :sub:`2` through the stomatal opening is 4.4‰. The kinetic +isotope effect during fixation of CO\ :sub:`2` with Rubisco is :math:`\sim`\ 30‰; however, since about 5-10% of carbon in C3 plants reacts with phosphoenolpyruvate carboxylase (PEPC) (Melzer and O’Leary, 1987), the net kinetic isotope effect during fixation is @@ -160,37 +145,37 @@ and C4 plants are given below: For C4 plants, .. math:: + :label: 25.8) - \label{25.8)} \alpha _{psn} =1+\frac{4.4}{1000} For C3 plants, .. math:: + :label: 25.9) - \label{25.9)} \alpha _{psn} =1+\frac{4.4+22.6\frac{c_{i}^{*} }{pCO_{2} } }{1000} where :math:`{\alpha }_{psn}` is the fractionation factor, and -:math:`c^*_i` and pCO\ :math:`{}_{2}` are the revised intracellular and -atmospheric CO\ :math:`{}_{2}` partial pressure, respectively. +:math:`c^*_i` and pCO\ :sub:`2` are the revised intracellular and +atmospheric CO\ :sub:`2` partial pressure, respectively. As can be seen from the above equation, kinetic isotope effect during -fixation of CO\ :math:`{}_{2}` is dependent on the intracellular -CO\ :math:`{}_{2}` concentration, which in turn depends on the net +fixation of CO\ :sub:`2` is dependent on the intracellular +CO\ :sub:`2` concentration, which in turn depends on the net carbon assimilation. That is calculated during the photosynthesis calculation as follows: .. math:: + :label: 25.10) - \label{25.10)} c_{i} =pCO_{2} -a_{n} p\frac{\left(1.4g_{s} \right)+\left(1.6g_{b} \right)}{g_{b} g_{s} } and .. math:: + :label: 25.11) - \label{25.11)} c_{i}^{*} =pCO_{2} -a_{n} \left(1-d\right)p\frac{\left(1.4g_{s} \right)+\left(1.6g_{b} \right)}{g_{b} g_{s} } where :math:`a_n` is net carbon assimilation during photosynthesis, @@ -207,7 +192,7 @@ photosynthesis, which is downscaled by :math:`d`, and the potential photosynthesis. In order to overcome this mismatch, downscaling due to nitrogen limitation is factored in the calculation of the kinetic isotope effect during fixation by defining a downscaled version of -intracellular CO\ :math:`{}_{2}` (:math:`c^*_i`), as a first order +intracellular CO\ :sub:`2` (:math:`c^*_i`), as a first order approximation. However, since nitrogen down-regulation is calculated after the photosynthesis calculation, down-regulation coefficient calculated in the previous time step needs to be used. @@ -218,10 +203,10 @@ discrimination rates for each layer of a multi-layered canopy. However, as with the rest of the photosynthesis model, the number of canopy layers is currently set to one by default. -:math:`{}^{14}`\ C radioactive decay and historical atmospheric :math:`{}^{14}`\ C concentrations +:sup:`14`\ C radioactive decay and historical atmospheric :sup:`14`\ C concentrations ------------------------------------------------------------------------------------------------------ -In the preindustrial biosphere, radioactive decay of :math:`{}^{14}`\ C +In the preindustrial biosphere, radioactive decay of :sup:`14`\ C in carbon pools allows dating of long-term age since photosynthetic uptake; while over the 20\ :math:`{}^{th}` century, radiocarbon in the atmosphere was first diluted by radiocarbon-free fossil fuels and then @@ -230,27 +215,25 @@ its long-term mean concentration. CLM includes both of these processes to allow comparison of carbon that may vary on multiple timescales with observed values. -For radioactive decay, at each timestep all :math:`{}^{14}`\ C pools are +For radioactive decay, at each timestep all :sup:`14`\ C pools are reduced at a rate of –log/:math:`\tau`, where :math:`\tau` is the half-life (Libby half-life value of 5568 years). In order to rapidly equilibrate the long-lived pools during accelerated decomposition spinup, the radioactive decay of the accelerated pools is also accelerated by the same degree as the decomposition, such that the -:math:`{}^{14}`\ C value of these pools is in equilibrium when taken out +:sup:`14`\ C value of these pools is in equilibrium when taken out of the spinup mode. -For variation of atmospheric :math:`{}^{14}`\ C over the historical -period, :math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C values can be set to -either fixed concentration (:math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C -= 0‰) or time-varying concentrations read in from a file. A default file +For variation of atmospheric :sup:`14`\ C over the historical +period, :math:`\mathrm{\Delta}`\ :sup:`14`\ C values can be set to +either fixed concentration (:math:`\mathrm{\Delta}`\ :sup:`14`\ C = 0‰) +or time-varying concentrations read in from a file. A default file is provided that is based on a spline fit through several observational datasets spanning the 20\ :math:`{}^{th}` century: (Levin and Kromer, 2004; Manning and Melhuish, 1994; Nydal and Lövseth, 1996; Turnbull et al. 2007). This is shown in Figure 25.1. -Figure 25.1. Atmospheric :math:`\mathrm{\Delta}`\ :math:`{}^{14}`\ C -used to drive :math:`{}^{14}`\ C model over the historical period. - -|image| +Figure 25.1. Atmospheric :math:`\mathrm{\Delta}`\ :sup:`14`\ C +used to drive :sup:`14`\ C model over the historical period. -.. |image| image:: image1 +.. image:: image1.png diff --git a/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst b/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst index 9bf3495e0c..c6a78b34d9 100644 --- a/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst +++ b/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst @@ -1,5 +1,3 @@ -.. math:: 1 - Offline Mode ================ @@ -27,12 +25,12 @@ to be run over Antarctica and ensures data is available along coastlines regardless of model resolution. The forcing data is ingested into a data atmosphere model in three -“streamsâ€; precipitation (:math:`P`) (mm s\ :math:`{}^{-1}`), solar -radiation (:math:`S_{atm}` ) (W m\ :math:`{}^{-2}`), and four other +“streamsâ€; precipitation (:math:`P`) (mm s\ :sup:`-1`), solar +radiation (:math:`S_{atm}` ) (W m\ :sup:`-2`), and four other fields [atmospheric pressure :math:`P_{atm}` (Pa), atmospheric specific -humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`), atmospheric +humidity :math:`q_{atm}` (kg kg\ :sup:`-1`), atmospheric temperature :math:`T_{atm}` (K), and atmospheric wind :math:`W_{atm}` -(m s\ :math:`{}^{-1}`)]. These are separate streams because they are +(m s\ :sup:`-1`)]. These are separate streams because they are handled differently according to the type of field. In the CRUNCEP dataset, the precipitation stream is provided at six hour intervals and the data atmosphere model prescribes the same precipitation rate for @@ -49,15 +47,15 @@ solar radiation supplied by the six-hourly forcing data is actually used. The solar radiation at model time step :math:`t_{M}` is .. math:: + :label: ZEqnNum160435 - \label{ZEqnNum160435} \begin{array}{l} {S_{atm} \left(t_{M} \right)=\frac{\frac{\Delta t_{FD} }{\Delta t_{M} } S_{atm} \left(t_{FD} \right)\mu \left(t_{M} \right)}{\sum _{i=1}^{\frac{\Delta t_{FD} }{\Delta t_{M} } }\mu \left(t_{M_{i} } \right) } \qquad {\rm for\; }\mu \left(t_{M} \right)>0.001} \\ {S_{atm} \left(t_{M} \right)=0\qquad {\rm for\; }\mu \left(t_{M} \right)\le 0.001} \end{array} where :math:`\Delta t_{FD}` is the time step of the forcing data (6 -hours :math:`\times` 3600 seconds hour\ :math:`{}^{-1}` = 21600 +hours :math:`\times` 3600 seconds hour\ :sup:`-1` = 21600 seconds), :math:`\Delta t_{M}` is the model time step (seconds), :math:`S_{atm} \left(t_{FD} \right)` is the six-hourly solar radiation -from the forcing data (W m\ :math:`{}^{-2}`), and +from the forcing data (W m\ :sup:`-2`), and :math:`\mu \left(t_{M} \right)` is the cosine of the solar zenith angle at model time step :math:`t_{M}` (section 3.3). The term in the denominator of equation is the sum of the cosine of the solar zenith @@ -71,46 +69,46 @@ derived from one year’s worth of hourly CAM output from CAM version cam3\_5\_55 as .. math:: + :label: 26.2) - \label{26.2)} S_{atm} \, \downarrow _{vis}^{\mu } =R_{vis} \left(\alpha S_{atm} \right) .. math:: + :label: 26.3) - \label{26.3)} S_{atm} \, \downarrow _{nir}^{\mu } =R_{nir} \left[\left(1-\alpha \right)S_{atm} \right] .. math:: + :label: 26.4) - \label{26.4)} S_{atm} \, \downarrow _{vis} =\left(1-R_{vis} \right)\left(\alpha S_{atm} \right) .. math:: + :label: 26.5) - \label{26.5)} S_{atm} \, \downarrow _{nir} =\left(1-R_{nir} \right)\left[\left(1-\alpha \right)S_{atm} \right]. where :math:`\alpha` , the ratio of visible to total incident solar radiation, is assumed to be .. math:: + :label: 26.6) - \label{26.6)} \alpha =\frac{S_{atm} \, \downarrow _{vis}^{\mu } +S_{atm} \, \downarrow _{vis}^{} }{S_{atm} } =0.5. The ratio of direct to total incident radiation in the visible :math:`R_{vis}` is .. math:: + :label: 26.7) - \label{26.7)} R_{vis} =a_{0} +a_{1} \times \alpha S_{atm} +a_{2} \times \left(\alpha S_{atm} \right)^{2} +a_{3} \times \left(\alpha S_{atm} \right)^{3} \qquad 0.01\le R_{vis} \le 0.99 and in the near-infrared :math:`R_{nir}` is .. math:: + :label: 26.8) - \label{26.8)} R_{nir} =b_{0} +b_{1} \times \left(1-\alpha \right)S_{atm} +b_{2} \times \left[\left(1-\alpha \right)S_{atm} \right]^{2} +b_{3} \times \left[\left(1-\alpha \right)S_{atm} \right]^{3} \qquad 0.01\le R_{nir} \le 0.99 where @@ -125,42 +123,42 @@ derived as follows. The atmospheric reference height :math:`z'_{atm}` :math:`u_{atm} =v_{atm} ={W_{atm} \mathord{\left/ {\vphantom {W_{atm} \sqrt{2} }} \right. \kern-\nulldelimiterspace} \sqrt{2} }` . The potential temperature :math:`\overline{\theta _{atm} }` (K) is set to the atmospheric temperature :math:`T_{atm}` . The atmospheric -longwave radiation :math:`L_{atm} \, \downarrow` (W m\ :math:`{}^{-2}`) +longwave radiation :math:`L_{atm} \, \downarrow` (W m\ :sup:`-2`) is derived from the atmospheric vapor pressure :math:`e_{atm}` and temperature :math:`T_{atm}` (Idso 1981) as .. math:: + :label: 26.9) - \label{26.9)} L_{atm} \, \downarrow =\left[0.70+5.95\times 10^{-5} \times 0.01e_{atm} \exp \left(\frac{1500}{T_{atm} } \right)\right]\sigma T_{atm}^{4} where .. math:: + :label: 26.10) - \label{26.10)} e_{atm} =\frac{P_{atm} q_{atm} }{0.622+0.378q_{atm} } and :math:`\sigma` is the Stefan-Boltzmann constant (W -m\ :math:`{}^{-2}` K\ :math:`{}^{-4}`) (Table 2.6). The fraction of -precipitation :math:`P` (mm s\ :math:`{}^{-1}`) falling as rain and/or +m\ :sup:`-2` K\ :math:`{}^{-4}`) (Table 2.6). The fraction of +precipitation :math:`P` (mm s\ :sup:`-1`) falling as rain and/or snow is .. math:: + :label: ZEqnNum336485 - \label{ZEqnNum336485} q_{rain} =P\left(f_{P} \right), .. math:: + :label: 26.12) - \label{26.12)} q_{snow} =P\left(1-f_{P} \right) where .. math:: + :label: 26.13) - \label{26.13)} f_{P} =0<0.5\left(T_{atm} -T_{f} \right)<1. The aerosol deposition rates :math:`D_{sp}` (14 rates as described in @@ -171,11 +169,11 @@ If the user wishes to provide atmospheric forcing data from another source, the data format outlined above will need to be followed with the following exceptions. The data atmosphere model will accept a user-supplied relative humidity :math:`RH` (%) and derive specific -humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`) from +humidity :math:`q_{atm}` (kg kg\ :sup:`-1`) from .. math:: + :label: 26.14) - \label{26.14)} q_{atm} =\frac{0.622e_{atm} }{P_{atm} -0.378e_{atm} } where the atmospheric vapor pressure :math:`e_{atm}` (Pa) is derived @@ -190,9 +188,9 @@ temperature :math:`T_{dew}` (K) and derive specific humidity :math:`q_{atm}` from .. math:: + :label: 26.15) - \label{26.15)} - q_{atm} =\frac{0.622e_{sat}^{T_{dew} } }{P_{atm} -0.378e_{sat}^{T_{dew} } } . + q_{atm} = \frac{0.622e_{sat}^{T_{dew} } }{P_{atm} -0.378e_{sat}^{T_{dew} } } . Here, :math:`e_{sat}^{T}` , the saturation vapor pressure as a function of temperature, is derived from Lowe’s (1977) polynomials. If not diff --git a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst index fb30a23e60..5b73e1a70a 100644 --- a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst +++ b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst @@ -1,7 +1,3 @@ -.. math:: 1 - -.. math:: 1 - References ============== @@ -293,7 +289,7 @@ Farouki, O.T. 1981. The thermal properties of soils in cold regions. Cold Regions Sci. and Tech. 5:67-75. Farquhar, G.D., von Caemmerer, S., and Berry, J.A. 1980. A biochemical -model of photosynthetic CO\ :math:`{}_{2}` assimilation in leaves of +model of photosynthetic CO\ :sub:`2` assimilation in leaves of C\ :math:`{}_{3}` species. Planta 149:78-90. Farquhar, G.D., and von Caemmerer, S. 1982. Modeling of photosynthetic @@ -438,7 +434,7 @@ change. J. Geophys. Res. 113:D05211. DOI:10.1029/2007JD009092. Heald, C.L., Wilkinson, M.J., Monson, R.K., Alo, C.A., Wang, G.L., and Guenther, A. 2009. Response of isoprene emission to ambient -CO\ :math:`{}_{2}` changes and implications for global budgets. Global +CO\ :sub:`2` changes and implications for global budgets. Global Change Biol. 15:1127-1140. DOI:10.1111/j.1365-2486.2008.01802.x Henderson-Sellers, B. 1985. New formulation of eddy diffusion @@ -488,7 +484,7 @@ aspen and spruce stands in the north american boreal forest. Canadian Journal of Remote Sensing, 18: 126-133. Hunt, E.R., Jr. et al., 1996. Global net carbon exchange and -intra-annual atmospheric CO\ :math:`{}_{2}` concentrations predicted by +intra-annual atmospheric CO\ :sub:`2` concentrations predicted by an ecosystem process model and three-dimensional atmospheric transport model. Global Biogeochemical Cycles, 10: 431-456. @@ -746,7 +742,7 @@ to simulated chronic nitrogen deposition. Ecological Applications, 7: Mahowald, N.M., Muhs, D.R., Levis, S., Rasch, P.J., Yoshioka, M., Zender, C.S., and Luo, C. 2006. Change in atmospheric mineral aerosols in response to climate: last glacial period, pre-industrial, modern and -doubled CO\ :math:`{}_{2}` climates. J. Geophys. Res\ *.* 111:D10202. +doubled CO\ :sub:`2` climates. J. Geophys. Res\ *.* 111:D10202. DOI:10.1029/2005JD006653. Makela, A. 2002. Derivation of stem taper from the pipe model theory in @@ -1206,7 +1202,7 @@ structure. J. Climate 20:3902-3923. Thornton, P.E., Lamarque, J.-F., Rosenbloom, N.A., and Mahowald, N.M. 2007. Influence of carbon-nitrogen cycle coupling on land model response -to CO\ :math:`{}_{2}` fertilization and climate variability. Global +to CO\ :sub:`2` fertilization and climate variability. Global Biogeochem. Cycles 21:GB4018. Thornton, P.E., Doney, S.C., Lindsay, K., Moore, J.K., Mahowald, N., diff --git a/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst b/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst index cc47ceedf1..e4320a9933 100644 --- a/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst +++ b/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst @@ -66,12 +66,9 @@ The average inverse diffuse optical depth per unit leaf and stem area is where :math:`\mu '` is the direction of the scattered flux. -The optical parameters :math:`\omega` , :math:`\beta` , and -:math:`\beta _{0}` , which vary with wavelength (:math:`\Lambda` ), are -weighted combinations of values for vegetation and snow. The model -determines that snow is on the canopy if :math:`T_{v} \le T_{f}` , where -:math:`T_{v}` is the vegetation temperature (K) (Chapter 5) and -:math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). In +The optical parameters :math:`\omega`, :math:`\beta`, and :math:`\beta _{0}`, which vary with wavelength (:math:`\Lambda` ), are +weighted combinations of values for vegetation and snow. The model determines that snow is on the canopy if :math:`T_{v} \le T_{f}` , where +:math:`T_{v}` is the vegetation temperature (K) (Chapter 5) and :math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). In this case, the optical parameters are .. math:: @@ -89,12 +86,9 @@ this case, the optical parameters are \omega _{\Lambda } \beta _{0,\, \Lambda } =\omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} \beta _{0,\, \Lambda }^{sno} f_{wet} -where :math:`f_{wet}` is the wetted fraction of the canopy (section -7.1). The snow and vegetation weights are applied to the products -:math:`\omega _{\Lambda } \beta _{\Lambda }` and -:math:`\omega _{\Lambda } \beta _{0,\, \Lambda }` because these -products are used in the two-stream equations. If there is no snow on -the canopy, +where :math:`f_{wet}` is the wetted fraction of the canopy (section 7.1). The snow and vegetation weights are applied to the products +:math:`\omega _{\Lambda } \beta _{\Lambda }` and :math:`\omega _{\Lambda } \beta _{0,\, \Lambda }` because these +products are used in the two-stream equations. If there is no snow on the canopy, .. math:: :label: 3.8 @@ -449,11 +443,11 @@ Table 3.1. Plant functional type optical properties +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ | BDS boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| C\ :math:`{}_{3}` arctic grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +| C\ :sub:`3` arctic grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| C\ :math:`{}_{3}` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +| C\ :sub:`3` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| C\ :math:`{}_{4}` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +| C\ :sub:`4` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ | Crop R | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ @@ -480,7 +474,7 @@ Table 3.2. Intercepted snow optical properties +-----------------------------+-------+-------+ | Parameter | vis | nir | -+-----------------------------+-------+-------+ ++=============================+=======+=======+ | :math:`\omega ^{sno}` | 0.8 | 0.4 | +-----------------------------+-------+-------+ | :math:`\beta ^{sno}` | 0.5 | 0.5 | @@ -491,8 +485,7 @@ Table 3.2. Intercepted snow optical properties Ground Albedos ------------------ -The overall direct beam :math:`\alpha _{g,\, \Lambda }^{\mu }` and -diffuse :math:`\alpha _{g,\, \Lambda }` ground albedos are weighted +The overall direct beam :math:`\alpha _{g,\, \Lambda }^{\mu }` and diffuse :math:`\alpha _{g,\, \Lambda }` ground albedos are weighted combinations of “soil†and snow albedos .. math:: @@ -505,8 +498,7 @@ combinations of “soil†and snow albedos \alpha _{g,\, \Lambda } =\alpha _{soi,\, \Lambda } \left(1-f_{sno} \right)+\alpha _{sno,\, \Lambda } f_{sno} -where :math:`f_{sno}` is the fraction of the ground covered with snow -(section 7.2.1). +where :math:`f_{sno}` is the fraction of the ground covered with snow (section 7.2.1). :math:`\alpha _{soi,\, \Lambda }^{\mu }` and :math:`\alpha _{soi,\, \Lambda }` vary with glacier, lake, wetland, and @@ -630,13 +622,10 @@ as g=\frac{\sum _{1}^{k}g_{k} \omega _{k} \tau _{k} }{\sum _{1}^{k}\omega _{k} \tau _{k} } -For each constituent (ice, two black carbon species, two organic carbon -species, and four dust species), :math:`\omega`, *g*, and -the mass extinction cross-section :math:`\psi` (:math:`\text{m}^{2} \text{kg}^{-1}`) -are computed offline with Mie Theory, e.g., -applying the computational technique from Bohren and Huffman (1983). The -extinction optical depth for each constituent depends on its mass -extinction cross-section and layer mass, :math:`w _{k} (\text{kg m} ^{-2}`) as +For each constituent (ice, two black carbon species, two organic carbon species, and four dust species), :math:`\omega`, *g*, and +the mass extinction cross-section :math:`\psi` (m\ :sup:`2` kg\ :sub:`-1`) +are computed offline with Mie Theory, e.g., applying the computational technique from Bohren and Huffman (1983). The +extinction optical depth for each constituent depends on its mass extinction cross-section and layer mass, :math:`w _{k}` (kg\ m\ :sup:`-1`) as .. math:: :label: 3.65 @@ -708,7 +697,7 @@ When any of these three conditions occur, the Eddington approximation is attempted instead, and if both approximations fail, the cosine of the solar zenith angle is adjusted by 0.02 (conserving incident flux) and a warning message is produced. This situation occurs in only about 1 in -10 :math:`{}^{6}` computations of snow albedo. After looping over the +10 :sup:`6` computations of snow albedo. After looping over the five spectral bands, absorption fluxes and albedo are averaged back into the bulk NIR band used by the rest of CLM. @@ -727,7 +716,7 @@ single timestep. The radiative transfer calculation is performed twice for each column containing a mass of snow greater than -:math:`1 \times 10^{-30} \text{kg m}^{-2}` (excluding lake and urban columns); once each for +:math:`1 \times 10^{-30}` kg\ m\ :sup:`-2` (excluding lake and urban columns); once each for direct-beam and diffuse incident flux. Absorption in each layer :math:`i` of pure snow is initially recorded as absorbed flux per unit incident flux on the ground (:math:`S_{sno,\, i}` ), as albedos must be @@ -745,7 +734,7 @@ vegetation canopy) have been calculated for the current time step (sections 3.1 and 4.1), the layer absorption factors (:math:`S_{g,\, i}`) are multiplied by the ground-incident fluxes to -produce solar absorption (W m\ :math:`{}^{-2}`) in each snow layer and +produce solar absorption (W m\ :sup:`-2`) in each snow layer and the underlying ground. Snowpack Optical Properties @@ -817,7 +806,7 @@ Table 3.5. Single-scatter albedo values used for snowpack impurities and ice | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 0.9998 | 0.9960 | 0.9680 | 0.8730 | 0.5500 | +----------------------------------------------------------------+----------+----------+----------+----------+----------+ -Table 3.6. Mass extinction values (:math:`\text{m}^{2} \text{kg}^{-1}`) used for snowpack impurities and ice. +Table 3.6. Mass extinction values (m\ :sup:`2` kg\ :sub:`-1`) used for snowpack impurities and ice. +----------------------------------------------------------------+----------+----------+----------+----------+----------+ | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | @@ -912,8 +901,7 @@ each time step *t* as r_{e} \left(t\right)=\left[r_{e} \left(t-1\right)+dr_{e,\, dry} +dr_{e,\, wet} \right]f_{old} +r_{e,\, 0} f_{new} +r_{e,\, rfz} f_{rfrz} Here, the effective radius of freshly-fallen snow -(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface -area of 60 :math:`\text{m}^{2} \text{kg}^{-1}`), and the effective +(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sub:`-1`), and the effective radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. Dry snow aging is based on a microphysical model described by Flanner @@ -940,8 +928,8 @@ The parameters :math:`{(\frac{dr_{e}}{dt}})_{0}`, lookup table with dimensions corresponding to snow temperature, temperature gradient, and density. The domain covered by this lookup table includes temperature ranging from 223 to 273 K, temperature -gradient ranging from 0 to 300 K m\ :math:`{}^{-1}`, and density ranging -from 50 to 400 kg m\ :math:`{}^{-3}`. Temperature gradient is calculated +gradient ranging from 0 to 300 K m\ :sup:`-1`, and density ranging +from 50 to 400 kg m\ :sup:`-3`. Temperature gradient is calculated at the midpoint of each snow layer *n*, using mid-layer temperatures (:math:`T_{n}`) and snow layer thicknesses (:math:`dz_{n}`), as @@ -967,8 +955,7 @@ fraction :math:`f_{liq}` as \frac{dr_{e} }{dt} =\frac{10^{18} C_{1} f_{liq} ^{3} }{4\pi r_{e} ^{2} } -The constant *C*\ :math:`{}_{1}` is -4.22\ :math:`\times`\ 10\ :math:`{}^{-13}`, and: +The constant *C*\ :sub:`1` is 4.22\ :math:`\times`\ 10\ :sup:`-13`, and: :math:`f_{liq} =w_{liq} /(w_{liq} +w_{ice} )`\ (section 7.2). In cases where snow mass is greater than zero, but a snow layer has not diff --git a/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst b/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst index 45d03e83f8..64506d1032 100644 --- a/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst +++ b/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst @@ -5,7 +5,7 @@ The net radiation at the surface is :math:`\left(\vec{S}_{v} +\vec{S}_{g} \right)-\left(\vec{L}_{v} +\vec{L}_{g} \right)`, where :math:`\vec{S}` is the net solar flux absorbed by the vegetation (“vâ€) and the ground (“gâ€) and :math:`\vec{L}` is the net longwave flux -(positive toward the atmosphere) (W m\ :math:`{}^{-2}`). +(positive toward the atmosphere) (W m\ :sup:`-2`). Solar Fluxes ---------------- @@ -51,7 +51,7 @@ The total solar radiation absorbed by the vegetation and ground is where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and :math:`S_{atm} \, \downarrow _{\Lambda }` are the incident direct beam -and diffuse solar fluxes (W m\ :math:`{}^{-2}`). For non-vegetated +and diffuse solar fluxes (W m\ :sup:`-2`). For non-vegetated surfaces, :math:`e^{-K\left(L+S\right)} =1`, :math:`\overrightarrow{I}_{\Lambda }^{\mu } =\overrightarrow{I}_{\Lambda } =0`, :math:`I\, \downarrow _{\Lambda }^{\mu } =0`, and @@ -144,7 +144,7 @@ or shaded plant area at depth :math:`x`. Longwave Fluxes ------------------- -The net longwave radiation (W m\ :math:`{}^{-2}`) (positive toward the +The net longwave radiation (W m\ :sup:`-2`) (positive toward the atmosphere) at the surface is .. math:: @@ -154,7 +154,7 @@ atmosphere) at the surface is where :math:`L\, \uparrow` is the upward longwave radiation from the surface and :math:`L_{atm} \, \downarrow` is the downward atmospheric -longwave radiation (W m\ :math:`{}^{-2}`). The radiative temperature +longwave radiation (W m\ :sup:`-2`). The radiative temperature :math:`T_{rad}` (K) is defined from the upward longwave radiation as .. math:: @@ -162,10 +162,8 @@ longwave radiation (W m\ :math:`{}^{-2}`). The radiative temperature T_{rad} =\left(\frac{L\, \uparrow }{\sigma } \right)^{{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } -where :math:`\sigma` is the Stefan-Boltzmann constant (W -m\ :math:`{}^{-2}` K\ :math:`{}^{-4}`) (Table 2.6). With reference to -Figure 4.1, the upward longwave radiation from the surface to the -atmosphere is +where :math:`\sigma` is the Stefan-Boltzmann constant (W\ m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6). With reference to +Figure 4.1, the upward longwave radiation from the surface to the atmosphere is .. math:: :label: 4.11 diff --git a/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst b/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst index 336fde1b9f..81c25ee0e8 100644 --- a/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst +++ b/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst @@ -2,15 +2,14 @@ Momentum, Sensible Heat, and Latent Heat Fluxes ================================================== The zonal :math:`\tau _{x}` and meridional :math:`\tau _{y}` momentum -fluxes (kg m\ :math:`{}^{-1}` s\ :math:`{}^{-2}`), sensible heat flux -:math:`H` (W m\ :math:`{}^{-2}`), and water vapor flux :math:`E` (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) between the atmosphere at +fluxes (kg m\ :sup:`-1` s\ :sup:`-2`), sensible heat flux +:math:`H` (W m\ :sup:`-2`), and water vapor flux :math:`E` (kg m\ :sup:`-2` s\ :sup:`-1`) between the atmosphere at reference height :math:`z_{atm,\, x}` (m) [where :math:`x` is height for wind (momentum) (:math:`m`), temperature (sensible heat) (:math:`h`), and humidity (water vapor) (:math:`w`); with zonal and meridional winds :math:`u_{atm}` and :math:`v_{atm}` (m -s\ :math:`{}^{-1}`), potential temperature :math:`\theta _{atm}` (K), -and specific humidity :math:`q_{atm}` (kg kg\ :math:`{}^{-1}`)] and the +s\ :sup:`-1`), potential temperature :math:`\theta _{atm}` (K), +and specific humidity :math:`q_{atm}` (kg kg\ :sup:`-1`)] and the surface [with :math:`u_{s}` , :math:`v_{s}` , :math:`\theta _{s}` , and :math:`q_{s}` ] are @@ -39,7 +38,7 @@ similarity theory developed for the surface layer (i.e., the nearly constant flux layer above the surface sublayer). In this derivation, :math:`u_{s}` and :math:`v_{s}` are defined to equal zero at height :math:`z_{0m} +d` (the apparent sink for momentum) so that -:math:`r_{am}` is the aerodynamic resistance (s m\ :math:`{}^{-1}`) for +:math:`r_{am}` is the aerodynamic resistance (s m\ :sup:`-1`) for momentum between the atmosphere at height :math:`z_{atm,\, m}` and the surface at height :math:`z_{0m} +d`. Thus, the momentum fluxes become @@ -57,12 +56,12 @@ Likewise, :math:`\theta _{s}` and :math:`q_{s}` are defined at heights :math:`z_{0h} +d` and :math:`z_{0w} +d` (the apparent sinks for heat and water vapor, respectively -:math:`r_{aw}` are the aerodynamic resistances (s m\ :math:`{}^{-1}`) +:math:`r_{aw}` are the aerodynamic resistances (s m\ :sup:`-1`) to sensible heat and water vapor transfer between the atmosphere at heights :math:`z_{atm,\, h}` and :math:`z_{atm,\, w}` and the surface at heights :math:`z_{0h} +d` and :math:`z_{0w} +d`, respectively. The -specific heat capacity of air :math:`C_{p}` (J kg\ :math:`{}^{-1}` -K\ :math:`{}^{-1}`) is a constant (Table 2.6). The atmospheric potential +specific heat capacity of air :math:`C_{p}` (J kg\ :sup:`-1` +K\ :sup:`-1`) is a constant (Table 2.6). The atmospheric potential temperature used here is .. math:: @@ -72,15 +71,13 @@ temperature used here is where :math:`T_{atm}` is the air temperature (K) at height :math:`z_{atm,\, h}` and :math:`\Gamma _{d} =0.0098` K -m\ :math:`{}^{-1}` is the negative of the dry adiabatic lapse rate [this +m\ :sup:`-1` is the negative of the dry adiabatic lapse rate [this expression is first-order equivalent to :math:`\theta _{atm} =T_{atm} \left({P_{srf} \mathord{\left/ {\vphantom {P_{srf} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } \right)^{{R_{da} \mathord{\left/ {\vphantom {R_{da} C_{p} }} \right. \kern-\nulldelimiterspace} C_{p} } }` (Stull 1988), where :math:`P_{srf}` is the surface pressure (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`R_{da}` -is the gas constant for dry air (J kg\ :math:`{}^{-1}` -K\ :math:`{}^{-1}`) (Table 2.6)]. By definition, -:math:`\theta _{s} =T_{s}` . The density of moist air (kg -m\ :math:`{}^{-3}`) is +is the gas constant for dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6)]. By definition, +:math:`\theta _{s} =T_{s}` . The density of moist air (kg m\ :sup:`-3`) is .. math:: :label: 5.8 @@ -99,8 +96,8 @@ Monin-Obukhov Similarity Theory ----------------------------------- The surface vertical kinematic fluxes of momentum -:math:`\overline{u'w'}` and :math:`\overline{v'w'}` (:math:`\text{m}^{2} \text{s}^{-2}`), sensible heat :math:`\overline{\theta 'w'}` -(:math:`\text{K m} \text{s}^{-1}`), and latent heat :math:`\overline{q'w'}` (:math:`\text{kg kg }^{-1}` m s\ :math:`{}^{-1}`), where :math:`u'`, :math:`v'`, +:math:`\overline{u'w'}` and :math:`\overline{v'w'}` (m\ :sup:`2` s\ :sub:`-2`), sensible heat :math:`\overline{\theta 'w'}` +(K m s :sup:`-1`), and latent heat :math:`\overline{q'w'}` (kg kg\ :sup:`-1` m s\ :sup:`-1`), where :math:`u'`, :math:`v'`, :math:`w'`, :math:`\theta '`, and :math:`q'` are zonal horizontal wind, meridional horizontal wind, vertical velocity, potential temperature, and specific humidity turbulent fluctuations about the mean, are defined @@ -130,16 +127,15 @@ displacement height (m), :math:`L` is the Monin-Obukhov length scale (m) that accounts for buoyancy effects resulting from vertical density gradients (i.e., the atmospheric stability), k is the von Karman constant (Table 2.6), and :math:`\left|{\it u}\right|` is the -atmospheric wind speed (m s\ :math:`{}^{-1}`). :math:`\phi _{m}` , +atmospheric wind speed (m s\ :sup:`-1`). :math:`\phi _{m}` , :math:`\phi _{h}` , and :math:`\phi _{w}` are universal (over any surface) similarity functions of :math:`\zeta` that relate the constant fluxes of momentum, sensible heat, and latent heat to the mean profile gradients of :math:`\left|{\it u}\right|`, :math:`\theta` , and :math:`q` in the surface layer. In neutral conditions, :math:`\phi _{m} =\phi _{h} =\phi _{w} =1`. The velocity (i.e., friction -velocity) :math:`u_{\*}` (m s\ :math:`{}^{-1}`), temperature -:math:`\theta _{\*}` (K), and moisture :math:`q_{\*}` (kg -kg\ :math:`{}^{-1}`) scales are +velocity) :math:`u_{\*}` (m s\ :sup:`-1`), temperature +:math:`\theta _{\*}` (K), and moisture :math:`q_{\*}` (kg kg\ :sup:`-1`) scales are .. math:: :label: 5.13 @@ -156,12 +152,11 @@ kg\ :math:`{}^{-1}`) scales are q_{*} u_{*} =-\overline{q'w'}=-\frac{E}{\rho _{atm} } -where :math:`\left|{\it \tau }\right|` is the shearing stress (kg -m\ :math:`{}^{-1}` s\ :math:`{}^{-2}`), with zonal and meridional +where :math:`\left|{\it \tau }\right|` is the shearing stress (kg m\ :sup:`-1` s\ :sup:`-2`), with zonal and meridional components :math:`\overline{u'w'}=-\frac{\tau _{x} }{\rho _{atm} }` and :math:`\overline{v'w'}=-\frac{\tau _{y} }{\rho _{atm} }` , respectively, -:math:`H` is the sensible heat flux (W m\ :math:`{}^{-2}`) and :math:`E` -is the water vapor flux (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`). +:math:`H` is the sensible heat flux (W m\ :sup:`-2`) and :math:`E` +is the water vapor flux (kg m\ :sup:`-2` s\ :sup:`-1`). The dimensionless length scale :math:`L` is the Monin-Obukhov length defined as @@ -171,7 +166,7 @@ defined as L=-\frac{u_{*}^{3} }{k\left(\frac{g}{\overline{\theta _{v,\, atm} }} \right)\theta '_{v} w'} =\frac{u_{*}^{2} \overline{\theta _{v,\, atm} }}{kg\theta _{v*} } -where :math:`g` is the acceleration of gravity (m s\ :math:`{}^{-2}`) +where :math:`g` is the acceleration of gravity (m s\ :sup:`-2`) (Table 2.6), and :math:`\overline{\theta _{v,\, atm} }=\overline{\theta _{atm} }\left(1+0.61q_{atm} \right)` is the reference virtual potential temperature. :math:`L>0` indicates @@ -504,7 +499,7 @@ and the atmosphere can also be written in the form E=-\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } -where the aerodynamic resistances (s m\ :math:`{}^{-1}`) are +where the aerodynamic resistances (s m\ :sup:`-1`) are .. math:: :label: ZEqnNum660763 @@ -566,7 +561,7 @@ definition, this includes bare soil, wetlands, and glaciers. The solution for lakes is described in Chapter 9. For these surfaces, the surface may be exposed to the atmosphere, snow covered, and/or surface water covered, so that the sensible heat flux :math:`H_{g}` (W -m\ :math:`{}^{-2}`) is, with reference to Figure 5.1, +m\ :sup:`-2`) is, with reference to Figure 5.1, .. math:: :label: ZEqnNum726771 @@ -594,15 +589,13 @@ surface water :math:`T_{h2osfc}` are H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{h2osfc} \right)}{r_{ah} } -where :math:`\rho _{atm}` is the density of atmospheric air (kg -m\ :math:`{}^{-3}`), :math:`C_{p}` is the specific heat capacity of air -(J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), +where :math:`\rho _{atm}` is the density of atmospheric air (kg m\ :sup:`-3`), :math:`C_{p}` is the specific heat capacity of air +(J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), :math:`\theta _{atm}` is the atmospheric potential temperature (K), and :math:`r_{ah}` is the aerodynamic resistance to sensible heat transfer -(s m\ :math:`{}^{-1}`). +(s m\ :sup:`-1`). -The water vapor flux :math:`E_{g}` (kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) is, with reference to Figure 5.2, +The water vapor flux :math:`E_{g}` (kg m\ :sup:`-2` s\ :sup:`-1`) is, with reference to Figure 5.2, .. math:: :label: ZEqnNum419297 @@ -624,14 +617,10 @@ s\ :math:`{}^{-1}`) is, with reference to Figure 5.2, E_{h2osfc} =-\frac{\rho _{atm} \left(q_{atm} -q_{h2osfc} \right)}{r_{aw} } -where :math:`\beta _{soi}` is an empirical function of soil water -(Sakaguchi and Zeng 2009), :math:`q_{atm}` is the atmospheric specific -humidity (kg kg\ :math:`{}^{-1}`), :math:`q_{soil}` , :math:`q_{sno}` , -and :math:`q_{h2osfc}` are the specific humidities (kg -kg\ :math:`{}^{-1}`) of the soil, snow, and surface water, respectively, -and :math:`r_{aw}` is the aerodynamic resistance to water vapor -transfer (s m\ :math:`{}^{-1}`). The specific humidities of the snow -:math:`q_{sno}` and surface water :math:`q_{h2osfc}` are assumed to be +where :math:`\beta _{soi}` is an empirical function of soil water (Sakaguchi and Zeng 2009), :math:`q_{atm}` is the atmospheric specific +humidity (kg kg\ :sup:`-1`), :math:`q_{soil}` , :math:`q_{sno}` , and :math:`q_{h2osfc}` are the specific humidities +(kg kg\ :sup:`-1`) of the soil, snow, and surface water, respectively, and :math:`r_{aw}` is the aerodynamic resistance to water vapor +transfer (s m\ :sup:`-1`). The specific humidities of the snow :math:`q_{sno}` and surface water :math:`q_{h2osfc}` are assumed to be at the saturation specific humidity of their respective temperatures .. math:: @@ -662,9 +651,8 @@ potential :math:`\psi` as in Philip (1957) \alpha _{soil} =\exp \left(\frac{\psi _{1} g}{1\times 10^{3} R_{wv} T_{1} } \right) -where :math:`R_{wv}` is the gas constant for water vapor (J -kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), :math:`g` is the -gravitational acceleration (m s\ :math:`{}^{-2}`) (Table 2.6), and +where :math:`R_{wv}` is the gas constant for water vapor (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), :math:`g` is the +gravitational acceleration (m s\ :sup:`-2`) (Table 2.6), and :math:`\psi _{1}` is the soil water matric potential of the top soil layer (mm). The soil water matric potential :math:`\psi _{1}` is @@ -686,11 +674,11 @@ soil layer with respect to saturation. The surface wetness where :math:`\Delta z_{1}` is the thickness of the top soil layer (m), :math:`\rho _{liq}` and :math:`\rho _{ice}` are the density of liquid -water and ice (kg m\ :math:`{}^{-3}`) (Table 2.6), :math:`w_{liq,\, 1}` +water and ice (kg m\ :sup:`-3`) (Table 2.6), :math:`w_{liq,\, 1}` and :math:`w_{ice,\, 1}` are the mass of liquid water and ice of the -top soil layer (:math:`\text{kg} \text{m}^{-2}`) (Chapter 7), and +top soil layer (kg m\ :sup:`-2`) (Chapter 7), and :math:`\theta _{sat,\, 1}` is the saturated volumetric water content -(i.e., porosity) of the top soil layer (:math:`\text{mm}^{3}` :math:`\text{mm}^{-3}`) (section 7.4.1). If +(i.e., porosity) of the top soil layer (mm\ :sup:`3` mm\ :sup:`-3`) (section 7.4.1). If :math:`q_{sat}^{T_{1} } >q_{atm}` and :math:`q_{atm} >q_{soil}` , then :math:`q_{soil} =q_{atm}` and :math:`\frac{dq_{soil} }{dT} =0`. This prevents large increases (decreases) in :math:`q_{soil}` for small @@ -708,7 +696,7 @@ surface within the dry part of the soil (Sakaguchi and Zeng 2009) as where :math:`\theta _{fc,\, 1}` is the field capacity of the top soil layer and :math:`0.01{\le \theta _{1} \mathord{\left/ {\vphantom {\le \theta _{1} \theta _{fc,\, 1} \le 1}} \right. \kern-\nulldelimiterspace} \theta _{fc,\, 1} \le 1}` . -The volumetric water content of the top soil layer (:math:`\text{mm}^{3}` :math:`\text{mm}^{-3}`) is +The volumetric water content of the top soil layer (mm\ :sup:`3` mm\ :sup:`-3`) is .. math:: :label: 5.77) @@ -716,7 +704,7 @@ The volumetric water content of the top soil layer (:math:`\text{mm}^{3}` :math: \theta _{1} =\frac{1}{\Delta z_{1} } \left[\frac{w_{liq,\, 1} }{\rho _{liq} } +\frac{w_{ice,\, 1} }{\rho _{ice} } \right]. The volumetric water content at field capacity is derived by assuming a -hydraulic conductivity of 0.1 mm day\ :math:`{}^{-1}` and inverting the +hydraulic conductivity of 0.1 mm day\ :sup:`-1` and inverting the hydraulic conductivity function (section 7.4.1) as .. math:: @@ -725,7 +713,7 @@ hydraulic conductivity function (section 7.4.1) as \theta _{fc,\, 1} =\theta _{sat,\, 1} \left[\frac{0.1}{86400k_{sat,\, 1} } \right]^{\frac{1}{2B_{i} +3} } where :math:`k_{sat,\, 1}` is the saturated hydraulic conductivity of -the top soil layer (mm s\ :math:`{}^{-1}`) (section 7.4.1) and the +the top soil layer (mm s\ :sup:`-1`) (section 7.4.1) and the exponent :math:`B_{1}` is a function of soil texture (section 7.4.1). The roughness lengths used to calculate :math:`r_{am}` , @@ -748,18 +736,16 @@ Zilitinkevich (1970) is adopted by Zeng and Dickinson (1998) z_{0h,\, g} =z_{0w,\, g} =z_{0m,\, g} e^{-a\left({u_{*} z_{0m,\, g} \mathord{\left/ {\vphantom {u_{*} z_{0m,\, g} \upsilon }} \right. \kern-\nulldelimiterspace} \upsilon } \right)^{0.45} } where the quantity -:math:`{u_{*} z_{0m,\, g} \mathord{\left/ {\vphantom {u_{*} z_{0m,\, g} \upsilon }} \right. \kern-\nulldelimiterspace} \upsilon }` -is the roughness Reynolds number (and may be interpreted as the Reynolds -number of the smallest turbulent eddy in the flow) with the kinematic -viscosity of air :math:`\upsilon =1.5\times 10^{-5}` m\ :math:`{}^{2}` -s\ :math:`{}^{-1}` and :math:`a=0.13`. +:math:`{u_{\*} z_{0m,\, g} \mathord{\left/ {\vphantom {u_{*} z_{0m,\, g} \upsilon }} \right. \kern-\nulldelimiterspace} \upsilon }` +is the roughness Reynolds number (and may be interpreted as the Reynolds number of the smallest turbulent eddy in the flow) with the kinematic +viscosity of air :math:`\upsilon =1.5\times 10^{-5}` m\ :sup:`2` s\ :sup:`-1` and :math:`a=0.13`. The numerical solution for the fluxes of momentum, sensible heat, and water vapor flux from non-vegetated surfaces proceeds as follows: #. An initial guess for the wind speed :math:`V_{a}` is obtained from eq. assuming an initial convective velocity :math:`U_{c} =0` m - s\ :math:`{}^{-1}` for stable conditions + s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from eq. ) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). @@ -886,19 +872,18 @@ where, with reference to Figure 5.1, H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{h2osfc} \right)}{r_{ah} ^{{'} } } -where :math:`\rho _{atm}` is the density of atmospheric air (kg -m\ :math:`{}^{-3}`), :math:`C_{p}` is the specific heat capacity of air -(J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), +where :math:`\rho _{atm}` is the density of atmospheric air (kg m\ :sup:`-3`), :math:`C_{p}` is the specific heat capacity of air +(J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), :math:`\theta _{atm}` is the atmospheric potential temperature (K), and :math:`r_{ah}` is the aerodynamic resistance to sensible heat transfer -(s m\ :math:`{}^{-1}`). +(s m\ :sup:`-1`). Here, :math:`T_{s}` is the surface temperature at height :math:`z_{0h} +d`, also referred to as the canopy air temperature. :math:`L` and :math:`S` are the exposed leaf and stem area indices (section 2.1.4), :math:`r_{b}` is the leaf boundary layer resistance (s -m\ :math:`{}^{-1}`), and :math:`r_{ah} ^{{'} }` is the aerodynamic -resistance (s m\ :math:`{}^{-1}`) to heat transfer between the ground at +m\ :sup:`-1`), and :math:`r_{ah} ^{{'} }` is the aerodynamic +resistance (s m\ :sup:`-1`) to heat transfer between the ground at height :math:`z_{0h} ^{{'} }` and the canopy air at height :math:`z_{0h} +d`. @@ -938,7 +923,7 @@ where are the sensible heat conductances from the canopy air to the atmosphere, the ground to canopy air, and leaf surface to canopy air, -respectively (m s\ :math:`{}^{-1}`). +respectively (m s\ :sup:`-1`). When the expression for :math:`T_{s}` is substituted into equation , the sensible heat flux from vegetation :math:`H_{v}` is a function of @@ -1000,19 +985,18 @@ where, with reference to Figure 5.2, E_{h2osfc} =-\rho _{atm} \frac{\left(q_{s} -q_{h2osfc} \right)}{r_{aw} ^{{'} } +r_{litter} } -where :math:`q_{atm}` is the atmospheric specific humidity (kg -kg\ :math:`{}^{-1}`), :math:`r_{aw}` is the aerodynamic resistance to -water vapor transfer (s m\ :math:`{}^{-1}`), :math:`q_{sat}^{T_{v} }` -(kg kg\ :math:`{}^{-1}`) is the saturation water vapor specific humidity +where :math:`q_{atm}` is the atmospheric specific humidity (kg kg\ :sup:`-1`), :math:`r_{aw}` is the aerodynamic resistance to +water vapor transfer (s m\ :sup:`-1`), :math:`q_{sat}^{T_{v} }` +(kg kg\ :sup:`-1`) is the saturation water vapor specific humidity at the vegetation temperature (section 5.5), :math:`q_{g}` , :math:`q_{sno}` , and :math:`q_{h2osfc}` are the specific humidities of the soil, snow, and surface water (section 5.2), :math:`r_{aw} ^{{'} }` is the aerodynamic resistance (s -m\ :math:`{}^{-1}`) to water vapor transfer between the ground at height +m\ :sup:`-1`) to water vapor transfer between the ground at height :math:`z_{0w} ^{{'} }` and the canopy air at height :math:`z_{0w} +d`, :math:`\beta _{soi}` is an empirical function of soil water (section 5.2), and :math:`r_{litter}` is a resistance for the plant litter layer -(s m\ :math:`{}^{-1}`). :math:`r_{total}` is the total resistance to +(s m\ :sup:`-1`). :math:`r_{total}` is the total resistance to water vapor transfer from the canopy to the canopy air and includes contributions from leaf boundary layer and sunlit and shaded stomatal resistances :math:`r_{b}` , :math:`r_{s}^{sun}` , and @@ -1063,7 +1047,7 @@ as r''=\left\{\begin{array}{l} {\min \left(f_{wet} +r_{dry} ^{{'} {'} } ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} >0} \\ {\min \left(f_{wet} ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} \le 0} \\ {1\qquad E_{v}^{w,\, pot} \le 0} \end{array}\right\} where :math:`f_{wet}` is the fraction of leaves and stems that are wet -(section 7.1), :math:`W_{can}` is canopy water (kg m\ :math:`{}^{-2}`) +(section 7.1), :math:`W_{can}` is canopy water (kg m\ :sup:`-2`) (section 7.1), :math:`\Delta t` is the time step (s), and :math:`\beta _{t}` is a soil moisture function limiting transpiration (Chapter 8). The potential evaporation from wet foliage per unit wetted @@ -1085,7 +1069,7 @@ where :math:`f_{dry}` is the fraction of leaves that are dry (section 7.1), :math:`L^{sun}` and :math:`L^{sha}` are the sunlit and shaded leaf area indices (section 4.1), and :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}` are the sunlit and shaded stomatal resistances (s -m\ :math:`{}^{-1}`) (Chapter 8). +m\ :sup:`-1`) (Chapter 8). When the expression for :math:`q_{s}` is substituted into equation , the water vapor flux from vegetation :math:`E_{v}` is a function of @@ -1122,7 +1106,7 @@ where U_{av} =V_{a} \sqrt{\frac{1}{r_{am} V_{a} } } =u_{*} is the magnitude of the wind velocity incident on the leaves -(equivalent here to friction velocity) (m s\ :math:`{}^{-1}`) and +(equivalent here to friction velocity) (m s\ :sup:`-1`) and :math:`C_{s}` is the turbulent transfer coefficient between the underlying soil and the canopy air. :math:`C_{s}` is obtained by interpolation between values for dense canopy and bare soil (Zeng et al. @@ -1158,7 +1142,7 @@ determined from S=\frac{gz_{top} \left(T_{s} -T_{g} \right)}{T_{s} u_{*}^{2} } where :math:`g` is the gravitational acceleration (m -s\ :math:`{}^{-2}`) (Table 2.6), and :math:`z_{top}` is canopy top +s\ :sup:`-2`) (Table 2.6), and :math:`z_{top}` is canopy top height (m) (Table 2.2). The bare soil turbulent transfer coefficient is .. math:: @@ -1167,21 +1151,19 @@ height (m) (Table 2.2). The bare soil turbulent transfer coefficient is C_{s,\, bare} =\frac{k}{a} \left(\frac{z_{0m,\, g} U_{av} }{\upsilon } \right)^{-0.45} where the kinematic viscosity of air -:math:`\upsilon =1.5\times 10^{-5}` m\ :math:`{}^{2}` -s\ :math:`{}^{-1}` and :math:`a=0.13`. +:math:`\upsilon =1.5\times 10^{-5}` m\ :sup:`2` +s\ :sup:`-1` and :math:`a=0.13`. The litter resistance :math:`r_{litter}` (Sakaguchi and Zeng 2009) (s -m\ :math:`{}^{-1}`) is +m\ :sup:`-1`) is .. math:: :label: 5.120) r_{litter} =\frac{1}{0.004u_{*} } \left(1-e^{-L_{litter}^{eff} } \right) -where the effective litter area index :math:`L_{litter}^{eff}` -(:math:`\text{m}^{2}` :math:`\text{m}^{-2}`) is the fraction of plant litter -area index :math:`L_{litter}` (currently set to 0.5 :math:`\text{m}^{2}` -:math:`\text{m}^{-2}`) that is not covered by snow +where the effective litter area index :math:`L_{litter}^{eff}` (m\ :sup:`2` m\ :sup:`-2`) is the fraction of plant litter +area index :math:`L_{litter}` (currently set to 0.5 m\ :sup:`2` m\ :sup:`-2`) that is not covered by snow .. math:: :label: 5.121) @@ -1206,7 +1188,7 @@ The leaf boundary layer resistance :math:`r_{b}` is r_{b} =\frac{1}{C_{v} } \left({U_{av} \mathord{\left/ {\vphantom {U_{av} d_{leaf} }} \right. \kern-\nulldelimiterspace} d_{leaf} } \right)^{{-1\mathord{\left/ {\vphantom {-1 2}} \right. \kern-\nulldelimiterspace} 2} } -where :math:`C_{v} =0.01` m s\ :math:`{}^{-1/2}` is the turbulent +where :math:`C_{v} =0.01` m\ s\ :sup:`-1/2` is the turbulent transfer coefficient between the canopy surface and canopy air, and :math:`d_{leaf}` is the characteristic dimension of the leaves in the direction of wind flow (Table 5.1). @@ -1261,7 +1243,7 @@ length and displacement height to canopy top height, respectively (Table V=\frac{1-\exp \left\{-\beta \min \left[L+S,\, \left(L+S\right)_{cr} \right]\right\}}{1-\exp \left[-\beta \left(L+S\right)_{cr} \right]} -where :math:`\beta =1` and :math:`\left(L+S\right)_{cr} =2` (:math:`\text{m}^{2}` m\ :math:`{}^{-2}`) is a critical value of exposed leaf +where :math:`\beta =1` and :math:`\left(L+S\right)_{cr} =2` (m\ :sup:`2` m\ :sup:`-2`) is a critical value of exposed leaf plus stem area for which :math:`z_{0m}` reaches its maximum. Table 5.1. Plant functional type aerodynamic parameters @@ -1291,11 +1273,11 @@ Table 5.1. Plant functional type aerodynamic parameters +----------------------------------+--------------------+------------------+-------------------------+ | BDS boreal | 0.120 | 0.68 | 0.04 | +----------------------------------+--------------------+------------------+-------------------------+ -| C\ :math:`{}_{3}` arctic grass | 0.120 | 0.68 | 0.04 | +| C\ :sub:`3` arctic grass | 0.120 | 0.68 | 0.04 | +----------------------------------+--------------------+------------------+-------------------------+ -| C\ :math:`{}_{3}` grass | 0.120 | 0.68 | 0.04 | +| C\ :sub:`3` grass | 0.120 | 0.68 | 0.04 | +----------------------------------+--------------------+------------------+-------------------------+ -| C\ :math:`{}_{4}` grass | 0.120 | 0.68 | 0.04 | +| C\ :sub:`4` grass | 0.120 | 0.68 | 0.04 | +----------------------------------+--------------------+------------------+-------------------------+ | Crop R | 0.120 | 0.68 | 0.04 | +----------------------------------+--------------------+------------------+-------------------------+ @@ -1413,7 +1395,7 @@ proceeds as follows: #. An initial guess for the wind speed :math:`V_{a}` is obtained from eq. assuming an initial convective velocity :math:`U_{c} =0` m - s\ :math:`{}^{-1}` for stable conditions + s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from eq. ) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). @@ -1594,7 +1576,7 @@ is the sum of :math:`E'_{g}` over all evaporating PFTs where relative area of the :math:`j^{th}` PFT with respect to the column, and :math:`npft` is the number of PFTs on the column. :math:`w_{ice,\, snl+1}` and :math:`w_{liq,\, snl+1}` are the ice and -liquid water contents (kg m\ :math:`{}^{-2}`) of the top snow/soil layer +liquid water contents (kg m\ :sup:`-2`) of the top snow/soil layer (Chapter 7). Any resulting energy deficit is assigned to sensible heat as @@ -1603,13 +1585,9 @@ as H''_{g} =H_{g} +\lambda \left(E'_{g} -E''_{g} \right). -The ground water vapor flux :math:`E''_{g}` is partitioned into -evaporation of liquid water from snow/soil :math:`q_{seva}` (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), sublimation from snow/soil ice -:math:`q_{subl}` (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), liquid dew -on snow/soil :math:`q_{sdew}` (kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`), or frost on snow/soil :math:`q_{frost}` (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) as +The ground water vapor flux :math:`E''_{g}` is partitioned into evaporation of liquid water from snow/soil :math:`q_{seva}` +(kg\ m\ :sup:`-2` s\ :sup:`-1`), sublimation from snow/soil ice :math:`q_{subl}` (kg m\ :sup:`-2` s\ :sup:`-1`), liquid dew +on snow/soil :math:`q_{sdew}` (kg m\ :sup:`-2` s\ :sup:`-1`), or frost on snow/soil :math:`q_{frost}` (kg m\ :sup:`-2` s\ :sup:`-1`) as .. math:: :label: 5.146) @@ -1677,7 +1655,7 @@ When converting ground water vapor flux to an energy flux, the term where :math:`\lambda _{sub}` and :math:`\lambda _{vap}` are the latent heat of sublimation and vaporization, respectively (J -kg\ :math:`{}^{-1}`) (Table 2.6). When converting vegetation water vapor +(kg\ :sup:`-1`) (Table 2.6). When converting vegetation water vapor flux to an energy flux, :math:`\lambda _{vap}` is used. The system balances energy as diff --git a/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst b/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst index d39a780958..83dc1e3579 100644 --- a/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst @@ -9,10 +9,10 @@ The first law of heat conduction is F=-\lambda \nabla T where :math:`F` is the amount of heat conducted across a unit -cross-sectional area in unit time (W m\ :math:`{}^{-2}`), -:math:`\lambda` is thermal conductivity (W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}`), and :math:`\nabla T` is the spatial gradient of -temperature (K m\ :math:`{}^{-1}`). In one-dimensional form +cross-sectional area in unit time (W m\ :sup:`-2`), +:math:`\lambda` is thermal conductivity (W m\ :sup:`-1` +K\ :sup:`-1`), and :math:`\nabla T` is the spatial gradient of +temperature (K m\ :sup:`-1`). In one-dimensional form .. math:: :label: ZEqnNum105915 @@ -30,7 +30,7 @@ in the form of the continuity equation is invoked as c\frac{\partial T}{\partial t} =-\frac{\partial F_{z} }{\partial z} where :math:`c` is the volumetric snow/soil heat capacity (J -m\ :math:`{}^{-3}` K\ :math:`{}^{-1}`) and :math:`t` is time (s). +m\ :sup:`-3` K\ :sup:`-1`) and :math:`t` is time (s). Combining equations and yields the second law of heat conduction in one-dimensional form @@ -164,9 +164,9 @@ are defined as negative values Note that :math:`z_{h,\, 0}` , the interface between the bottom snow layer and the top soil layer, is zero. Thermal properties (i.e., temperature :math:`T_{i}` [K]; thermal conductivity -:math:`\lambda _{i}` [W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`]; -volumetric heat capacity :math:`c_{i}` [J m\ :math:`{}^{-3}` -K\ :math:`{}^{-1}`]) are defined for soil layers at the node depths +:math:`\lambda _{i}` [W m\ :sup:`-1` K\ :sup:`-1`]; +volumetric heat capacity :math:`c_{i}` [J m\ :sup:`-3` +K\ :sup:`-1`]) are defined for soil layers at the node depths (Figure 6.1) and for snow layers at the layer midpoints. When present, snow occupies a fraction of a grid cell’s area, therefore snow depth represents the thickness of the snowpack averaged over only the snow @@ -175,7 +175,7 @@ of the snow covered area as :math:`\bar{z}_{sno} =f_{sno} z_{sno}` . By default, the grid cell average snow depth is written to the history file. -The heat flux :math:`F_{i}` (W m\ :math:`{}^{-2}`) from layer :math:`i` +The heat flux :math:`F_{i}` (W m\ :sup:`-2`) from layer :math:`i` to layer :math:`i+1` is .. math:: @@ -257,7 +257,7 @@ element band-diagonal system of equations. For the top soil layer :math:`i=1` , top snow layer :math:`i=snl+1`, or surface water layer, the heat flux from the overlying atmosphere -:math:`h` (W m\ :math:`{}^{-2}`, defined as positive into the surface) +:math:`h` (W m\ :sup:`-2`, defined as positive into the surface) is .. math:: @@ -346,10 +346,8 @@ where the partial derivative of the net longwave radiation is and the partial derivatives of the sensible and latent heat fluxes are given by equations and for non-vegetated surfaces, and by equations and for vegetated surfaces. :math:`\sigma` is the Stefan-Boltzmann constant -(W m\ :math:`{}^{-2}` K\ :math:`{}^{-4}`) (Table 2.6) and -:math:`\varepsilon _{g}` is the ground emissivity (section 4.2). For -purposes of computing :math:`h` and -:math:`\frac{\partial h}{\partial T_{g} }` , the term :math:`\lambda` +(W m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6) and :math:`\varepsilon _{g}` is the ground emissivity (section 4.2). For +purposes of computing :math:`h` and :math:`\frac{\partial h}{\partial T_{g} }` , the term :math:`\lambda` is arbitrarily assumed to be .. math:: @@ -359,9 +357,9 @@ is arbitrarily assumed to be where :math:`\lambda _{sub}` and :math:`\lambda _{vap}` are the latent heat of sublimation and vaporization, respectively (J -kg\ :math:`{}^{-1}`) (Table 2.6), and :math:`w_{liq,\, snl+1}` and +kg\ :sup:`-1`) (Table 2.6), and :math:`w_{liq,\, snl+1}` and :math:`w_{ice,\, snl+1}` are the liquid water and ice contents of the -top snow/soil layer, respectively (kg m\ :math:`{}^{-2}`) (Chapter 7). +top snow/soil layer, respectively (kg m\ :sup:`-2`) (Chapter 7). For the top soil layer, :math:`i=1`, the coefficients are @@ -544,7 +542,7 @@ phase change will take place as where :math:`T_{i}^{n+1}` is the soil layer temperature after solution of the tridiagonal equation set, :math:`w_{ice,\, i}` and :math:`w_{liq,\, i}` are the mass of ice and liquid water (kg -m\ :math:`{}^{-2}`) in each snow/soil layer, respectively, and +m\ :sup:`-2`) in each snow/soil layer, respectively, and :math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). For the freezing process in soil layers, the concept of supercooled soil water from Niu and Yang (2006) is adopted. The supercooled soil water is @@ -558,11 +556,11 @@ depression equation w_{liq,\, \max ,\, i} =\Delta z_{i} \theta _{sat,\, i} \left[\frac{10^{3} L_{f} \left(T_{f} -T_{i} \right)}{gT_{i} \psi _{sat,\, i} } \right]^{{-1\mathord{\left/ {\vphantom {-1 B_{i} }} \right. \kern-\nulldelimiterspace} B_{i} } } \qquad T_{i} 0`), there are no explicit snow layers (:math:`snl=0`), and :math:`\frac{H_{1} \Delta t}{L_{f} } >0` (melting), the snow mass -:math:`W_{sno}` (kg m\ :math:`{}^{-2}`) is reduced according to +:math:`W_{sno}` (kg m\ :sup:`-2`) is reduced according to .. math:: :label: 6.62) @@ -665,9 +663,9 @@ available to the top soil layer as The ice mass, liquid water content, and temperature of the top soil layer are then determined from equations , , and using the recalculated -energy from equation . Snow melt :math:`M_{1S}` (kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) and phase change energy :math:`E_{p,\, 1S}` (W -m\ :math:`{}^{-2}`) for this special case are +energy from equation . Snow melt :math:`M_{1S}` (kg m\ :sup:`-2` +s\ :sup:`-1`) and phase change energy :math:`E_{p,\, 1S}` (W +m\ :sup:`-2`) for this special case are .. math:: :label: 6.66) @@ -679,7 +677,7 @@ m\ :math:`{}^{-2}`) for this special case are E_{p,\, 1S} =L_{f} M_{1S} . -The total energy of phase change :math:`E_{p}` (W m\ :math:`{}^{-2}`) +The total energy of phase change :math:`E_{p}` (W m\ :sup:`-2`) for the snow/soil column is .. math:: @@ -694,8 +692,8 @@ where E_{p,\, i} =L_{f} \frac{\left(w_{ice,\, i}^{n} -w_{ice,\, i}^{n+1} \right)}{\Delta t} . -The total snow melt :math:`M` (kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) is +The total snow melt :math:`M` (kg m\ :sup:`-2` +s\ :sup:`-1`) is .. math:: :label: 6.70) @@ -769,8 +767,8 @@ organic matter fraction :math:`f_{om,i}` is f_{om,i} =\rho _{om,i} /\rho _{om,\max } . -Soil thermal conductivity :math:`\lambda _{i}` (W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}`) is from Farouki (1981) +Soil thermal conductivity :math:`\lambda _{i}` (W m\ :sup:`-1` +K\ :sup:`-1`) is from Farouki (1981) .. math:: :label: 6.78) @@ -781,8 +779,8 @@ where :math:`\lambda _{sat,\, i}` is the saturated thermal conductivity, :math:`\lambda _{dry,\, i}` is the dry thermal conductivity, :math:`K_{e,\, i}` is the Kersten number, :math:`S_{r,\, i}` is the wetness of the soil with respect to -saturation, and :math:`\lambda _{bedrock} =3` W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}` is the thermal conductivity assumed for the deep +saturation, and :math:`\lambda _{bedrock} =3` W m\ :sup:`-1` +K\ :sup:`-1` is the thermal conductivity assumed for the deep ground layers (typical of saturated granitic rock; Clauser and Huenges, 1995). For glaciers and wetlands, @@ -794,7 +792,7 @@ ground layers (typical of saturated granitic rock; Clauser and Huenges, where :math:`\lambda _{liq}` and :math:`\lambda _{ice}` are the thermal conductivities of liquid water and ice, respectively (Table 2.6). The saturated thermal conductivity :math:`\lambda _{sat,\, i}` (W -m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) depends on the thermal +m\ :sup:`-1` K\ :sup:`-1`) depends on the thermal conductivities of the soil solid, liquid water, and ice constituents .. math:: @@ -819,8 +817,8 @@ where the mineral soil solid thermal conductivity \lambda _{s,\, \min ,i} =\frac{8.80{\rm \; }\left(\% sand\right)_{i} +{\rm 2.92\; }\left(\% clay\right)_{i} }{\left(\% sand\right)_{i} +\left(\% clay\right)_{i} } , -and :math:`\lambda _{s,om} =0.25`\ W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}` (Farouki, 1981). :math:`\theta _{sat,\, i}` is the +and :math:`\lambda _{s,om} =0.25`\ W m\ :sup:`-1` +K\ :sup:`-1` (Farouki, 1981). :math:`\theta _{sat,\, i}` is the volumetric water content at saturation (porosity) (section 7.4.1). The thermal conductivity of dry soil is @@ -831,18 +829,18 @@ The thermal conductivity of dry soil is \lambda _{dry,i} =(1-f_{om,i} )\lambda _{dry,\min ,i} +f_{om,i} \lambda _{dry,om} where the thermal conductivity of dry mineral soil -:math:`\lambda _{dry,\min ,i}` \ (W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}`) depends on the bulk density +:math:`\lambda _{dry,\min ,i}` \ (W m\ :sup:`-1` +K\ :sup:`-1`) depends on the bulk density :math:`\rho _{d,\, i} =2700\left(1-\theta _{sat,\, i} \right)` (kg -m\ :math:`{}^{-3}`) as +m\ :sup:`-3`) as .. math:: :label: 6.84) \lambda _{dry,\, \min ,i} =\frac{0.135\rho _{d,\, i} +64.7}{2700-0.947\rho _{d,\, i} } -and :math:`\lambda _{dry,om} =0.05` W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}` (Farouki, 1981) is the dry thermal conductivity of +and :math:`\lambda _{dry,om} =0.05` W m\ :sup:`-1` +K\ :sup:`-1` (Farouki, 1981) is the dry thermal conductivity of organic matter. The Kersten number :math:`K_{e,\, i}` is a function of the degree of saturation :math:`S_{r}` and phase of water @@ -858,8 +856,8 @@ where S_{r,\, i} =\left(\frac{w_{liq,\, i} }{\rho _{liq} \Delta z_{i} } +\frac{w_{ice,\, i} }{\rho _{ice} \Delta z_{i} } \right)\frac{1}{\theta _{sat,\, i} } =\frac{\theta _{liq,\, i} +\theta _{ice,\, i} }{\theta _{sat,\, i} } \le 1. -Thermal conductivity :math:`\lambda _{i}` (W m\ :math:`{}^{-1}` -K\ :math:`{}^{-1}`) for snow is from Jordan (1991) +Thermal conductivity :math:`\lambda _{i}` (W m\ :sup:`-1` +K\ :sup:`-1`) for snow is from Jordan (1991) .. math:: :label: 6.87) @@ -868,15 +866,15 @@ K\ :math:`{}^{-1}`) for snow is from Jordan (1991) where :math:`\lambda _{air}` is the thermal conductivity of air (Table 2.6) and :math:`\rho _{sno,\, i}` is the bulk density of snow (kg -m\ :math:`{}^{-3}`) +m\ :sup:`-3`) .. math:: :label: 6.88) \rho _{sno,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{\Delta z_{i} } . -The volumetric heat capacity :math:`c_{i}` (J m\ :math:`{}^{-3}` -K\ :math:`{}^{-1}`) for soil is from de Vries (1963) and depends on the +The volumetric heat capacity :math:`c_{i}` (J m\ :sup:`-3` +K\ :sup:`-1`) for soil is from de Vries (1963) and depends on the heat capacities of the soil solid, liquid water, and ice constituents .. math:: @@ -885,9 +883,9 @@ heat capacities of the soil solid, liquid water, and ice constituents c_{i} =c_{s,\, i} \left(1-\theta _{sat,\, i} \right)+\frac{w_{ice,\, i} }{\Delta z_{i} } C_{ice} +\frac{w_{liq,\, i} }{\Delta z_{i} } C_{liq} where :math:`C_{liq}` and :math:`C_{ice}` are the specific heat -capacities (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) of liquid water +capacities (J kg\ :sup:`-1` K\ :sup:`-1`) of liquid water and ice, respectively (Table 2.6). The heat capacity of soil solids -:math:`c_{s,i}` \ (J m\ :math:`{}^{-3}` K\ :math:`{}^{-1}`) is +:math:`c_{s,i}` \ (J m\ :sup:`-3` K\ :sup:`-1`) is .. math:: :label: 6.90) @@ -895,17 +893,17 @@ and ice, respectively (Table 2.6). The heat capacity of soil solids c_{s,i} =(1-f_{om,i} )c_{s,\min ,i} +f_{om,i} c_{s,om} where the heat capacity of mineral soil solids -:math:`c_{s,\min ,\, i}` (J m\ :math:`{}^{-3}` K\ :math:`{}^{-1}`) is +:math:`c_{s,\min ,\, i}` (J m\ :sup:`-3` K\ :sup:`-1`) is .. math:: :label: 6.91) \begin{array}{l} {c_{s,\min ,\, i} =\left(\frac{2.128{\rm \; }\left(\% sand\right)_{i} +{\rm 2.385\; }\left(\% clay\right)_{i} }{\left(\% sand\right)_{i} +\left(\% clay\right)_{i} } \right)\times 10^{6} \qquad i=1,\ldots ,N_{levsoi} } \\ {c_{s,\, \min ,i} =c_{s,\, bedrock} \qquad i=N_{levsoi} +1,\ldots ,N_{levgrnd} } \end{array} -where :math:`c_{s,bedrock} =2\times 10^{6}` J m\ :math:`{}^{-3}` -K\ :math:`{}^{-1}` is the heat capacity of bedrock and -:math:`c_{s,om} =2.5\times 10^{6}` \ J m\ :math:`{}^{-3}` -K\ :math:`{}^{-1}` (Farouki, 1981) is the heat capacity of organic +where :math:`c_{s,bedrock} =2\times 10^{6}` J m\ :sup:`-3` +K\ :sup:`-1` is the heat capacity of bedrock and +:math:`c_{s,om} =2.5\times 10^{6}` \ J m\ :sup:`-3` +K\ :sup:`-1` (Farouki, 1981) is the heat capacity of organic matter. For glaciers, wetlands, and snow .. math:: diff --git a/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst b/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst index 47359c6b77..20ed6594d2 100644 --- a/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst +++ b/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst @@ -9,7 +9,7 @@ changes in canopy water :math:`\Delta W_{can}` , surface water :math:`\Delta W_{sfc}` , snow water :math:`\Delta W_{sno}` , soil water :math:`\Delta w_{liq,\, i}` , and soil ice :math:`\Delta w_{ice,\, i}` , and water in the unconfined aquifer :math:`\Delta W_{a}` (all in kg -m\ :math:`{}^{-2}` or mm of H\ :math:`{}_{2}`\ O) (Figure 7.1). +m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (Figure 7.1). The total water balance of the system is @@ -26,8 +26,8 @@ ET from vegetation (Chapter 5), :math:`E_{g}` is ground evaporation :math:`q_{drai}` is sub-surface drainage (section 7.6), :math:`q_{rgwl}` and :math:`q_{snwcp,ice}` are liquid and solid runoff from glaciers, wetlands, and lakes, and runoff from other surface types -due to snow capping (section 7.7) (all in kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`), :math:`N_{levsoi}` is the number of soil layers +due to snow capping (section 7.7) (all in kg m\ :sup:`-2` +s\ :sup:`-1`), :math:`N_{levsoi}` is the number of soil layers (note that hydrology calculations are only done over soil layers 1 to :math:`N_{levsoi}` ; ground levels :math:`N_{levsoi} +1`\ to :math:`N_{levgrnd}` are currently hydrologically inactive; Lawrence et @@ -43,7 +43,7 @@ Canopy Water Precipitation is either intercepted by the canopy, falls directly to the snow/soil surface (throughfall), or drips off the vegetation (canopy drip). Interception by vegetation :math:`q_{intr}` (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) does not distinguish between +m\ :sup:`-2` s\ :sup:`-1`) does not distinguish between liquid and solid phases .. math:: @@ -54,7 +54,7 @@ liquid and solid phases where :math:`L` and :math:`S` are the exposed leaf and stem area index, respectively (section 2.1.4), and :math:`\alpha =0.25` scales interception from point to grid cell (Lawrence et al. 2007). Throughfall -(kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), however, is divided into +(kg m\ :sup:`-2` s\ :sup:`-1`), however, is divided into liquid and solid phases reaching the ground (soil or snow surface) as .. math:: @@ -88,7 +88,7 @@ where is the canopy water after accounting for interception, :math:`W_{can}^{n}` is the canopy water from the previous time step, -and :math:`W_{can,\, \max }` (kg m\ :math:`{}^{-2}`) is the maximum +and :math:`W_{can,\, \max }` (kg m\ :sup:`-2`) is the maximum amount of water the canopy can hold .. math:: @@ -97,7 +97,7 @@ amount of water the canopy can hold W_{can,\, \max } =p\left(L+S\right). The maximum storage of solid water is assumed to be the same as that of -liquid water, :math:`p=0.1` kg m\ :math:`{}^{-2}` (Dickinson et al. +liquid water, :math:`p=0.1` kg m\ :sup:`-2` (Dickinson et al. 1993). The canopy water is updated as .. math:: @@ -164,14 +164,14 @@ Shown are three snow layers, :math:`i=-2`, :math:`i=-1`, and .. image:: image2.png The state variables for snow are the mass of water :math:`w_{liq,i}` -(kg m\ :math:`{}^{-2}`), mass of ice :math:`w_{ice,i}` (kg -m\ :math:`{}^{-2}`), layer thickness :math:`\Delta z_{i}` (m), and +(kg m\ :sup:`-2`), mass of ice :math:`w_{ice,i}` (kg +m\ :sup:`-2`), layer thickness :math:`\Delta z_{i}` (m), and temperature :math:`T_{i}` (Chapter 6). The water vapor phase is neglected. Snow can also exist in the model without being represented by explicit snow layers. This occurs when the snowpack is less than a specified minimum snow depth (:math:`z_{sno} <0.01` m). In this case, the state variable is the mass of snow :math:`W_{sno}` (kg -m\ :math:`{}^{-2}`). +m\ :sup:`-2`). Section 7.2.1 describes the calculation of fractional snow covered area, which is used in the surface albedo calculation (Chapter 3) and the @@ -236,7 +236,7 @@ The conservation equation for mass of ice in snow layers is where :math:`q_{ice,\, i-1}` is the rate of ice accumulation from precipitation or frost or the rate of ice loss from sublimation (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) in the top layer and +m\ :sup:`-2` s\ :sup:`-1`) in the top layer and :math:`{\left(\Delta w_{ice,\, i} \right)_{p} \mathord{\left/ {\vphantom {\left(\Delta w_{ice,\, i} \right)_{p} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` is the change in ice due to phase change (melting rate) (section 6.2). The term :math:`q_{ice,\, i-1}` is computed in two steps as @@ -267,7 +267,7 @@ where \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg -m\ :math:`{}^{-3}`) (CityplaceAnderson 1976) +m\ :sup:`-3`) (CityplaceAnderson 1976) .. math:: :label: 7.21) @@ -315,8 +315,8 @@ content is reset to zero and the liquid water content :math:`w_{ice,\, snl+1}^{n+1}` up to zero. The snow water equivalent :math:`W_{sno}` is capped to not exceed 1000 -kg m\ :math:`{}^{-2}`. If the addition of :math:`q_{frost}` were to -result in :math:`W_{sno} >1000` kg m\ :math:`{}^{-2}`, the frost term +kg m\ :sup:`-2`. If the addition of :math:`q_{frost}` were to +result in :math:`W_{sno} >1000` kg m\ :sup:`-2`, the frost term :math:`q_{frost}` is instead added to the ice runoff term :math:`q_{snwcp,\, ice}` (section 7.7). @@ -411,7 +411,7 @@ Black and organic carbon and mineral dust within snow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Particles within snow originate from atmospheric aerosol deposition -(:math:`D_{sp}` in Table 2.3 (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) +(:math:`D_{sp}` in Table 2.3 (kg m\ :sup:`-2` s\ :sup:`-1`) and influence snow radiative transfer (sections 3.2.1, 3.2.2, and 3.3.3). Particle masses and mixing ratios are represented with a simple mass-conserving scheme. The model maintains masses of the following @@ -453,7 +453,7 @@ radiative calculations are done. Particle masses are then redistributed each time step based on meltwater drainage through the snow column (section 7.2.3) and snow layer combination and subdivision (section 7.2.7). The change in mass of each of the particle species -:math:`\Delta m_{sp,\, i}` (kg m\ :math:`{}^{-2}`) is +:math:`\Delta m_{sp,\, i}` (kg m\ :sup:`-2`) is .. math:: :label: 7.38) @@ -464,10 +464,10 @@ where :math:`k_{sp}` is the meltwater scavenging efficiency that is unique for each species (Table 7.1), :math:`q_{liq,\, i-1}` is the flow of liquid water into layer :math:`i` from the layer above, :math:`q_{liq,\, i}` is the flow of water out of layer :math:`i` into -the layer below (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) (section +the layer below (kg m\ :sup:`-2` s\ :sup:`-1`) (section 7.2.3), :math:`c_{sp,\, i-1}` and :math:`c_{sp,\, i}` are the particle mass mixing ratios in layers :math:`i-1` and :math:`i` (kg -kg\ :math:`{}^{-1}`), :math:`D_{sp}` is the atmospheric deposition rate +kg\ :sup:`-1`), :math:`D_{sp}` is the atmospheric deposition rate (zero for all layers except layer :math:`snl+1`), and :math:`\Delta t` is the model time step (s). The particle mass mixing ratio is @@ -530,7 +530,7 @@ destructive metamorphism of new snow (crystal breakdown due to wind or thermodynamic stress); snow load or overburden (pressure); and melting (changes in snow structure due to melt-freeze cycles plus changes in crystals due to liquid water). The total fractional compaction rate for -each snow layer :math:`C_{R,\, i}` (:math:`\text{s}^{-1}`) is the sum of the +each snow layer :math:`C_{R,\, i}` (s\ :sup:`-1`) is the sum of the three compaction processes .. math:: @@ -548,16 +548,14 @@ Compaction is not allowed if the layer is saturated or if the ice content is below a minimum value (:math:`w_{ice,\, i} \le 0.1`). -Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` -(:math:`{\text s^{-1}}`) is temperature dependent (CityplaceAnderson 1976) +Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (CityplaceAnderson 1976) .. math:: :label: 7.43) C_{R1,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{metamorphism} =-c_{3} c_{1} c_{2} \exp \left[-c_{4} \left(T_{f} -T_{i} \right)\right] -where :math:`c_{3} =2.777\times 10^{-6}` (:math:`\text{s}^{-1}`) is the -fractional compaction rate for :math:`T_{i} =T_{f}`, :math:`c_{4} =0.04` :math:`\text{K}^{-1}`, and +where :math:`c_{3} =2.777\times 10^{-6}` (s\ :sup:`-1`) is the fractional compaction rate for :math:`T_{i} =T_{f}`, :math:`c_{4} =0.04` K\ :sup:`-1`, and .. math:: :label: 7.44) @@ -571,28 +569,25 @@ where :math:`{w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` and :math:`{w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` -are the bulk densities of liquid water and ice (kg m\ :math:`{}^{-3}`). +are the bulk densities of liquid water and ice (kg m\ :sup:`-3`). -The compaction rate as a result of overburden :math:`C_{R2,\; i}` -(:math:`\text{s}^{-1}`) is a linear function of the snow load pressure -:math:`P_{s,\, i}` (:math:`\text{k} \text{g} \text{m}^{-2}`) (CityplaceAnderson 1976) +The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (CityplaceAnderson 1976) .. math:: :label: 7.45) C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } -where :math:`\eta` is a viscosity coefficient (:math:`\text{kg} \text{s} \text{m}^{-2}`) -that varies with density and temperature as +where :math:`\eta` is a viscosity coefficient (kg s m\ :sup:`-2`) that varies with density and temperature as .. math:: :label: 7.46) \eta =\eta _{0} \exp \left[c_{5} \left(T_{f} -T_{i} \right)+c_{6} \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \right] -where :math:`\eta _{0} =9\times 10^{5}` kg s m\ :math:`{}^{-2}`, and -:math:`c_{5} =0.08` K\ :math:`{}^{-1}`, :math:`c_{6} =0.023` -m\ :math:`{}^{3}` kg\ :math:`{}^{-1}` are constants. The snow load +where :math:`\eta _{0} =9\times 10^{5}` kg s m\ :sup:`-2`, and +:math:`c_{5} =0.08` K\ :sup:`-1`, :math:`c_{6} =0.023` +m\ :sup:`3` kg\ :sup:`-1` are constants. The snow load pressure :math:`P_{s,\, i}` is calculated for each layer as the sum of the ice :math:`w_{ice,\, i}` and liquid water contents :math:`w_{liq,\, i}` of the layers above plus half the ice and liquid @@ -603,8 +598,7 @@ water contents of the layer being compacted P_{s,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{2} +\sum _{j=snl+1}^{j=i-1}\left(w_{ice,\, j} +w_{liq,\, j} \right) . -The compaction rate due to melting :math:`C_{R3,\; i}` -(:math:`\text{s}^{-1}`) is taken to be the ratio of the change in snow ice +The compaction rate due to melting :math:`C_{R3,\; i}` (s\ :sup:`-1`) is taken to be the ratio of the change in snow ice mass after the melting to the mass before melting .. math:: @@ -741,8 +735,8 @@ where :math:`h_{c} =h_{1} +h_{2}` is the combined enthalpy h_{i} =\left(C_{ice} w_{ice,\, i} +C_{liq} w_{liq,\, i} \right)\left(T_{i} -T_{f} \right)+L_{f} w_{liq,\, i} . In these equations, :math:`L_{f}` is the latent heat of fusion (J -kg\ :math:`{}^{-1}`) and :math:`C_{liq}` and :math:`C_{ice}` are the -specific heat capacities (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) of +kg\ :sup:`-1`) and :math:`C_{liq}` and :math:`C_{ice}` are the +specific heat capacities (J kg\ :sup:`-1` K\ :sup:`-1`) of liquid water and ice, respectively (Table 2.6). After layer combination, the node depths and layer interfaces (Figure 7.2) are recalculated from @@ -825,7 +819,7 @@ Surface Runoff, Surface Water Storage, and Infiltration The moisture input at the grid cell surface ,\ :math:`q_{liq,\, 0}` , is the sum of liquid precipitation reaching the ground and melt water from -snow (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`). The moisture flux is +snow (kg m\ :sup:`-2` s\ :sup:`-1`). The moisture flux is then partitioned between surface runoff, surface water storage, and infiltration into the soil. @@ -854,7 +848,7 @@ The fractional saturated area is a function of soil moisture where :math:`f_{\max }` is the potential or maximum value of :math:`f_{sat}` , :math:`f_{over}` is a decay factor -(:math:`\text{m}^{-1}`), and :math:`z_{\nabla}` is the water table depth +(m\ :sup:`-1`), and :math:`z_{\nabla}` is the water table depth (m) (section 7.6). The maximum saturated fraction, :math:`f_{\max }` , is defined as the value of the discrete cumulative distribution function (CDF) of the topographic index when the grid cell mean water table depth @@ -864,19 +858,19 @@ mean topographic index. It should be calculated explicitly from the CDF at each grid cell at the resolution that the model is run. However, because this is a computationally intensive task for global applications, :math:`f_{\max }` is calculated once at -0.125\ :math:`{}^\circ` resolution using the 1-km compound topographic +0.125\ :sup:`o` resolution using the 1-km compound topographic indices (CTIs) based on the HYDRO1K dataset (Verdin and Greenlee 1996) from USGS following the algorithm in Niu et al. (2005) and then area-averaged to the desired model resolution (section 2.2.3). Pixels with CTIs exceeding the 95 percentile threshold in each -0.125\ :math:`{}^\circ` grid cell are excluded from the calculation to +0.125\ :sup:`o` grid cell are excluded from the calculation to eliminate biased estimation of statistics due to large CTI values at pixels on stream networks. For grid cells over regions without CTIs such as Australia, the global mean :math:`f_{\max }` is used to fill the gaps. See Li et al. (2013b) for additional details. The decay factor :math:`f_{over}` for global simulations was determined through sensitivity analysis and comparison with observed runoff to be 0.5 -m\ :math:`{}^{-1}`. +m\ :sup:`-1`. Surface Water Storage ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -884,7 +878,7 @@ Surface Water Storage A surface water store has been added to the model to represent wetlands and small, sub-grid scale water bodies. As a result, the wetland land unit has been removed. The state variables for surface water are the -mass of water :math:`W_{sfc}` (kg m\ :math:`{}^{-2}`) and temperature +mass of water :math:`W_{sfc}` (kg m\ :sup:`-2`) and temperature :math:`T_{h2osfc}` (Chapter 6). Surface water storage and outflow are functions of fine spatial scale elevation variations called microtopography. The microtopography is assumed to be distributed @@ -967,8 +961,8 @@ removed, is divided into inputs to surface water (:math:`q_{in,\, h2osfc}` ) and the soil :math:`q_{in,soil}` . If :math:`q_{in,soil}` exceeds the -maximum soil infiltration capacity (kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`), +maximum soil infiltration capacity (kg m\ :sup:`-2` +s\ :sup:`-1`), .. math:: :label: ZEqnNum569150 @@ -1042,12 +1036,12 @@ mass is stated as \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q where :math:`\theta` is the volumetric soil water content -(mm:math:`{}^{3}` of water mm\ :math:`{}^{-3}` of soil), :math:`t` is +(mm:sup:`3` of water mm\ :sup:`-3` of soil), :math:`t` is time (s), :math:`z` is height above some datum in the soil column (mm) -(positive upwards), :math:`q` is soil water flux (kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}` or mm s\ :math:`{}^{-1}`) (positive upwards), and -:math:`Q` is a soil moisture sink term (mm of water mm\ :math:`{}^{-1}` -of soil s\ :math:`{}^{-1}`) (ET loss). This equation is solved +(positive upwards), :math:`q` is soil water flux (kg m\ :sup:`-2` +s\ :sup:`-1` or mm s\ :sup:`-1`) (positive upwards), and +:math:`Q` is a soil moisture sink term (mm of water mm\ :sup:`-1` +of soil s\ :sup:`-1`) (ET loss). This equation is solved numerically by dividing the soil column into multiple layers in the vertical and integrating downward over each layer with an upper boundary condition of the infiltration flux into the top soil layer @@ -1062,7 +1056,7 @@ law q=-k\frac{\partial \psi _{h} }{\partial z} -where :math:`k` is the hydraulic conductivity (mm s\ :math:`{}^{-1}`), +where :math:`k` is the hydraulic conductivity (mm s\ :sup:`-1`), and :math:`\psi _{h}` is the hydraulic potential (mm). The hydraulic potential is @@ -1139,7 +1133,7 @@ where the soil moisture sink term :math:`Q` is now included. Hydraulic Properties ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The hydraulic conductivity :math:`k_{i}` (mm s\ :math:`{}^{-1}`) and +The hydraulic conductivity :math:`k_{i}` (mm s\ :sup:`-1`) and the soil matric potential :math:`\psi _{i}` (mm) for layer :math:`i` vary with volumetric soil water :math:`\theta _{i}` and soil texture. As with the soil thermal properties (section 6.3) the hydraulic @@ -1228,7 +1222,7 @@ matric potential :math:`\psi _{sat,\min ,i}` \ is \psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } . The saturated hydraulic conductivity, -:math:`k_{sat} \left[z_{h,\, i} \right]` (mm s\ :math:`{}^{-1}`), for +:math:`k_{sat} \left[z_{h,\, i} \right]` (mm s\ :sup:`-1`), for organic soils (:math:`k_{sat,\, om}` ) may be two to three orders of magnitude larger than that of mineral soils (:math:`k_{sat,\, \min }` ). Bulk soil layer values of :math:`k_{sat}` \ calculated as weighted @@ -1303,7 +1297,7 @@ where :math:`q_{i}` is the flux of water across interface :math:`z_{h,\, i}` , :math:`q_{i-1}` is the flux of water across interface :math:`z_{h,\, i-1}` , and :math:`e_{i}` is a layer-averaged soil moisture sink term (ET loss) defined as positive for flow out of -the layer (mm s\ :math:`{}^{-1}`). Taking the finite difference with +the layer (mm s\ :sup:`-1`). Taking the finite difference with time and evaluating the fluxes implicitly at time :math:`n+1` yields .. math:: @@ -1339,7 +1333,7 @@ the interface of two layers :math:`z_{h}` . The layer thickness is term :math:`e` (ET loss) is defined as positive for flow out of the layer. -.. image:: image3 +.. image:: image3.png Note that because more than one plant functional type (PFT) may share a soil column, the transpiration :math:`E_{v}^{t}` is a weighted sum of @@ -1495,7 +1489,7 @@ derived from equation \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } =\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } =\left(1-\frac{f_{frz,\, i} +f_{frz,\, i+1} }{2} \right)\left(2B_{i} +3\right)k_{sat} \left[z_{h,\, i} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right)} \end{array}. -7.4.2.1 Equilibrium soil matric potential and volumetric moisture +Equilibrium soil matric potential and volumetric moisture ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The equilibrium soil matric potential :math:`\psi _{E}` can be derived @@ -1579,7 +1573,7 @@ The equilibrium soil matric potential is then \psi _{E,\, i} =\psi _{sat,\, i} \left(\frac{\overline{\theta _{E,\, i} }}{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad \frac{\overline{\theta _{E,\, i} }}{\theta _{sat,\, i} } \ge 0.01 -7.4.2.2 Equation set for layer :math:`i=1` +Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' For the top soil layer (:math:`i=1`), the boundary condition is the @@ -1615,7 +1609,7 @@ equations for :math:`i=1` are r_{i} =q_{infl}^{n+1} -q_{i}^{n} +e_{i} . -7.4.2.3 Equation set for layers :math:`i=2,\ldots ,N_{levsoi} -1` +Equation set for layers :math:`i=2,\ldots ,N_{levsoi} -1` ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The coefficients of the tridiagonal set of equations for @@ -1641,7 +1635,7 @@ The coefficients of the tridiagonal set of equations for r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . -7.4.2.4 Equation set for layers :math:`i=N_{levsoi} ,\ldots N_{levsoi} +1` +Equation set for layers :math:`i=N_{levsoi} ,\ldots N_{levsoi} +1` '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' For the lowest soil layer (:math:`i=N_{levsoi}` ), the bottom boundary @@ -1825,7 +1819,7 @@ Groundwater-Soil Water Interactions Drainage or sub-surface runoff is based on the SIMTOP scheme (Niu et al. 2005) with a modification to account for reduced drainage in frozen soils. In the work of Niu et al. (2005), the drainage :math:`q_{drai}` -(kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) was formulated as +(kg m\ :sup:`-2` s\ :sup:`-1`) was formulated as .. math:: :label: ZEqnNum924767 @@ -1863,13 +1857,13 @@ where :math:`\Omega =6`\ is an adjustable parameter, :math:`jwt` is the index of the layer directly above the water table, :math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the ice-filled fraction of the pore space of soil layer :math:`i` (kg -m\ :math:`{}^{-2}`), and :math:`\Delta z_{i}` is the layer thickness +m\ :sup:`-2`), and :math:`\Delta z_{i}` is the layer thickness (mm). This expression is functionally the same as that used to determine the ice impedance factor in section 7.4. In equation , the decay factor -:math:`f_{drai} =2.5` m\ :math:`{}^{-1}` and the maximum drainage when +:math:`f_{drai} =2.5` m\ :sup:`-1` and the maximum drainage when the water table depth is at the surface -:math:`q_{drai,\, \max } =10\sin (\beta )` kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}` , where :math:`\beta` is the mean grid cell +:math:`q_{drai,\, \max } =10\sin (\beta )` kg m\ :sup:`-2` +s\ :sup:`-1` , where :math:`\beta` is the mean grid cell topographic slope in radians, were determined for global simulations through sensitivity analysis and comparison with observed runoff. @@ -1955,7 +1949,7 @@ soil layer (:math:`w_{liq,\, i}^{excess} =w_{liq,\, i} -\left(\theta _{sat,\, i} -\theta _{ice,\, i} \right)\Delta z_{i} \ge 0`) is successively added to the layer above. Any excess liquid water that remains after saturating the entire soil column (plus a maximum surface -ponding depth :math:`w_{liq}^{pond} =10` kg m\ :math:`{}^{-2}`), is +ponding depth :math:`w_{liq}^{pond} =10` kg m\ :sup:`-2`), is added to drainage :math:`q_{drai}` . Second, to prevent negative :math:`w_{liq,\, i}` , each layer is successively brought up to :math:`w_{liq,\, i} =w_{liq}^{\min }` by taking the required amount of @@ -1993,7 +1987,7 @@ Runoff from glaciers and snow-capped surfaces ------------------------------------------------- All surfaces are constrained to have a snow water equivalent -:math:`W_{sno} \le 1000` kg m\ :math:`{}^{-2}`. For snow-capped +:math:`W_{sno} \le 1000` kg m\ :sup:`-2`. For snow-capped surfaces, the solid and liquid precipitation reaching the snow surface and dew in solid or liquid form, is separated into solid :math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms @@ -2065,7 +2059,7 @@ CLM soil column with thicknesses of :math:`\sum^3_{i=1}{\Delta z_i}`, step, the soil moisture profile is determined following the algorithms detailed in section 7.4, and aggregated to the three VIC layers for runoff generation calculations. The surface runoff generated by the -saturation excess runoff mechanism, *q\ :math:`{}_{over}`*, is +saturation excess runoff mechanism, q\ :sub:`over`, is calculated using equation , but with the fractional saturated area defined as @@ -2077,8 +2071,8 @@ defined as where :math:`w_{top}` and :math:`w_{m,top}` are calculated as :math:`\sum^6_{i=1}{{\theta }_i\Delta z_i}` and :math:`\sum^6_{i=1}{{\theta }_{s,i}\Delta z_i}`, respectively, and -represent the soil moisture (kg m\ :math:`{}^{-2}`) and maximum soil -moisture (kg m\ :math:`{}^{-2}`) in the top two VIC layers combined. +represent the soil moisture (kg m\ :sup:`-2`) and maximum soil +moisture (kg m\ :sup:`-2`) in the top two VIC layers combined. In equation , it is hypothesized that the spatial heterogeneity of soil moisture holding capacity in the top VIC layers can be represented by a @@ -2095,13 +2089,13 @@ conceptually as i=i_m\left(1-{\left(1-A\right)}^{1/b_{inf}}\right) where :math:`i` and :math:`i_{m}` are the point and maximum point soil -moisture holding capacities (kg m\ :math:`{}^{-2}`), respectively; +moisture holding capacities (kg m\ :sup:`-2`), respectively; :math:`A` is the fraction of a grid cell for which the soil moisture holding capacity is less than or equal to :math:`i`; and :math:`i_m=w_{m,top}\left(1+b_{inf}\right)`. When :math:`A` is equal to :math:`f_{sat}`, the corresponding point soil moisture holding capacity is denoted as :math:`i_0`. The maximum soil infiltration capacity (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) in equation becomes +m\ :sup:`-2` s\ :sup:`-1`) in equation becomes .. math:: :label: ZEqnNum202398 @@ -2124,9 +2118,9 @@ The subsurface runoff in equation is parameterized as \right]/\mathrm{\Delta }t where :math:`w_{bot}` and :math:`w_{m,bot}` are the soil moisture (kg -m\ :math:`{}^{-2}`) and maximum soil moisture (kg m\ :math:`{}^{-2}`) in +m\ :sup:`-2`) and maximum soil moisture (kg m\ :sup:`-2`) in the bottom VIC layer, respectively, :math:`D_{smax}` is the maximum -subsurface flow rate (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), +subsurface flow rate (kg m\ :sup:`-2` s\ :sup:`-1`), :math:`D_s` is a fraction of :math:`D_{smax}`, :math:`W_s` is a fraction of :math:`w_{m,bot}`, and :math:`{\mathrm{\Theta }}_{ice,bot}` is an ice impedance factor determined from the ice content of the bottom VIC @@ -2143,9 +2137,9 @@ other four parameters, :math:`b_{inf}` , :math:`D_{smax}` , :math:`D_s` dataset. Users can provide calibrated parameter values determined manually or automatically by modifying the surface dataset. Note that the units of :math:`D_{smax}` on the surface dataset are mm -d\ :math:`{}^{-1}` (the traditional units for other standard VIC -applications) which are then converted to kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}` for use in CLM. A preliminary calibration was +d\ :sup:`-1` (the traditional units for other standard VIC +applications) which are then converted to kg m\ :sup:`-2` +s\ :sup:`-1` for use in CLM. A preliminary calibration was performed by perturbing the three parameters :math:`b_{inf}` , :math:`D_{smax}` , and :math:`W_s`, and fixing :math:`D_s=0.1` globally. The parameter space for :math:`b_{inf}` , :math:`D_{smax}` , and @@ -2154,7 +2148,7 @@ described by Hou et al. (2012) to produce 64 combinations of parameter values based on *a priori* information about the parameters. For each set of parameter values, a global simulation was performed using the compset I\_2000 (i.e., driven by satellite phenology) at a resolution of -0.9\ :math:`{}^\circ`\ x1.25\ :math:`{}^\circ` on the basis of the +0.9\ :sup:`o`\ x1.25\ :sup:`o` on the basis of the development tag betr\_m\_sci10\_clm45sci13\_clm4\_0\_54. At each model grid cell, the set of :math:`b_{inf}` , :math:`D_{smax}` , and :math:`W_s` values corresponding to the simulation that produced the diff --git a/doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst b/doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst index f8ac82d263..6cd61d641c 100644 --- a/doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst +++ b/doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst @@ -6,11 +6,10 @@ Leaf stomatal resistance, which is needed for the water vapor flux (1991, 1992). These equations are solved separately for sunlit and shaded leaves using average absorbed photosynthetically active radiation for sunlit and shaded leaves -[:math:`\phi ^{sun}` ,\ :math:`\phi ^{sha}` :math:`\text{W} \text{m}^{-2}` +[:math:`\phi ^{sun}` ,\ :math:`\phi ^{sha}` W m\ :sup:`-2` (section 4.1)] to give sunlit and shaded stomatal resistance -(:math:`r_{s}^{sun}` ,\ :math:`r_{s}^{sha}` :math:`\text{sm}^{-1}`) and -photosynthesis (:math:`A^{sun}` ,\ :math:`A^{sha}` µmol -:math:`\text{CO}_{2}` m\ :math:`{}^{-2}` :math:`\text{s}^{-1}`). Canopy +(:math:`r_{s}^{sun}` ,\ :math:`r_{s}^{sha}` s m\ :sup:`-1`) and +photosynthesis (:math:`A^{sun}` ,\ :math:`A^{sha}` µmol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`). Canopy photosynthesis is :math:`A^{sun} L^{sun} +A^{sha} L^{sha}` , where :math:`L^{sun}` and :math:`L^{sha}` are the sunlit and shaded leaf area indices (section 4.1). Canopy conductance is @@ -26,7 +25,7 @@ model as described by Collatz et al. (1991) and implemented in global climate models (Sellers et al. 1996). The model relates stomatal conductance (i.e., the inverse of resistance) to net leaf photosynthesis, scaled by the relative humidity at the leaf surface and -the :math:`\text{CO}_{2}` concentration at the leaf surface. Leaf stomatal +the CO\ :sub:`1` concentration at the leaf surface. Leaf stomatal resistance is .. math:: @@ -34,22 +33,22 @@ resistance is \frac{1}{r_{s} } =g_{s} =m\frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } } h_{s} +b\, \beta _{t} -where :math:`r_{s}` is leaf stomatal resistance (s m\ :math:`{}^{2}` -:math:`\mu`\ mol\ :math:`{}^{-1}`), :math:`m` is a plant functional +where :math:`r_{s}` is leaf stomatal resistance (s m\ :sup:`2` +:math:`\mu`\ mol\ :sup:`-1`), :math:`m` is a plant functional type dependent parameter (Table 8.1), :math:`A_{n}` is leaf net -photosynthesis (:math:`\mu`\ mol CO\ :math:`{}_{2}` m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`), :math:`c_{s}` is the CO\ :math:`{}_{2}` partial +photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` +s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), :math:`h_{s} =e_{s} /e_{i}` is the leaf surface humidity with :math:`e_{s}` the vapor pressure at the leaf surface (Pa) and :math:`e_{i}` the saturation vapor pressure (Pa) inside the leaf at the vegetation temperature\ :math:`T_{v}`, and :math:`b` is the minimum -stomatal conductance (:math:`\mu` mol m :math:`{}^{-2}` -s\ :math:`{}^{-1}`). Parameter values are :math:`m=9` for -C\ :math:`{}_{3}` plants and :math:`m=4` for C\ :math:`{}_{4}` plants +stomatal conductance (:math:`\mu` mol m :sup:`-2` +s\ :sup:`-1`). Parameter values are :math:`m=9` for +C\ :sub:`3` plants and :math:`m=4` for C\ :sub:`4` plants (Collatz et al. 1991, 1992, Sellers et al. 1996). Sellers et al. (1996) -used :math:`b=10000` for C :math:`{}_{3}` plants and -:math:`b=40000` for C :math:`{}_{4}` plants, also used here. +used :math:`b=10000` for C\ :sub:`3` plants and +:math:`b=40000` for C\ :sub:`4` plants, also used here. Photosynthesis is calculated for sunlit (:math:`A^{sun}`) and shaded (:math:`A^{sha}`) leaves to give :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}`. Additionally, soil water influences stomatal @@ -58,12 +57,10 @@ water stress function :math:`\beta _{t}` (which ranges from 0 to 1) and also indirectly through :math:`A_{n}`, as in (Sellers et al. 1996). Resistance is converted from units of -:math:`\textrm{s\,m}^{2}\, \mu \, \textrm{mol}^{-1}` to -:math:`\textrm{s\,m}^{-1}` as: -:math:`\text{1\,s\,m}^{-1}` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` -:math:`\mu\,\text{mol}^{-1}` m\ :math:`{}^{2}` s, where -:math:`R_{gas}` is the universal gas constant (J K\ :math:`{}^{-1}` -kmol\ :math:`{}^{-1}`) (Table 2.6) and :math:`\theta _{atm}` is the +s m\ :sup:`2` :math:`\mu` mol\ :sub:`-1` to s m\ :sup:`-1` as: +1 s m\ sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` +:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` +kmol\ :sup:`-1`) (Table 2.6) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). Table 8.1. Plant functional type (PFT) photosynthetic parameters. @@ -93,11 +90,11 @@ Table 8.1. Plant functional type (PFT) photosynthetic parameters. +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ | BDS boreal | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| C\ :math:`{}_{3}` arctic grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | +| C\ :sub:`3` arctic grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| C\ :math:`{}_{3}` grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | +| C\ :sub:`3` grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| C\ :math:`{}_{4}` grass | 4 | 0.05 | 25 | 0.0900 | 0.030 | -74000 | -275000 | 51.6 | +| C\ :sub:`4` grass | 4 | 0.05 | 25 | 0.0900 | 0.030 | -74000 | -275000 | 51.6 | +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ | Crop R | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ @@ -120,18 +117,16 @@ Table 8.1. Plant functional type (PFT) photosynthetic parameters. | Soybean I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -:math:`\alpha` (mol CO\ :math:`{}_{2}` mol\ :math:`{}^{-1}` photon); -:math:`CN_{L}` (g C g\ :math:`{}^{-1}` N); :math:`F_{LNR}` (g N -Rubisco g\ :math:`{}^{-1}` N); :math:`SLA_{0}` (m:math:`{}^{2}` -:math:`\text{g}^{-1}` C); :math:`\psi _{o}` and :math:`\psi _{c}` (mm); -:math:`\text{V}_{cmax25}` (:math:`\mu`\ mol m\ :math:`{}^{-2}` -:math:`\text{s}^{-1}`, calculated from equation for canopy top). +:math:`\alpha` (mol CO\ :sub:`2` mol\ :sup:`-1` photon); +:math:`CN_{L}` (g C g\ :sup:`-1` N); :math:`F_{LNR}` (g N Rubisco g\ :sup:`-1` N); :math:`SLA_{0}` (m\ :sup:`2` g\ :sup:`-1` C); +:math:`\psi _{o}` and :math:`\psi _{c}` (mm); +V\ :sub:`cmax25` (:math:`\mu`\ mol m\ :sup:`-2` s\ :sup:`-1`, calculated from equation for canopy top). Photosynthesis ------------------ -Photosynthesis in C\ :math:`{}_{3}` plants is based on the model of -Farquhar et al. (1980). Photosynthesis in C\ :math:`{}_{4}` plants is +Photosynthesis in C\ :sub:`3` plants is based on the model of +Farquhar et al. (1980). Photosynthesis in C\ :sub:`4` plants is based on the model of Collatz et al. (1992). Bonan et al. (2011) describe the implementation, modified here. In its simplest form, leaf net photosynthesis after accounting for respiration (:math:`R_{d}` ) is @@ -142,8 +137,8 @@ net photosynthesis after accounting for respiration (:math:`R_{d}` ) is A_{n} =\min \left(A_{c} ,A_{j} ,A_{p} \right)-R_{d} . The RuBP carboxylase (Rubisco) limited rate of carboxylation -:math:`A_{c}` (:math:`\mu` \ mol CO\ :math:`{}_{2}` m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) is +:math:`A_{c}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` +s\ :sup:`-1`) is .. math:: :label: ZEqnNum141081 @@ -153,17 +148,17 @@ s\ :math:`{}^{-1}`) is The maximum rate of carboxylation allowed by the capacity to regenerate RuBP (i.e., the light-limited rate) :math:`A_{j}` (:math:`\mu` \ mol -CO\ :math:`{}_{2}` m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is +CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 8.4) A_{j} =\left\{\begin{array}{l} {\frac{J\left(c_{i} -\Gamma _{\*} \right)}{4c_{i} +8\Gamma _{\*} } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\alpha (4.6\phi )\qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. -The product-limited rate of carboxylation for C\ :math:`{}_{3}` plants +The product-limited rate of carboxylation for C\ :sub:`3` plants and the PEP carboxylase-limited rate of carboxylation for -C\ :math:`{}_{4}` plants :math:`A_{p}` (:math:`\mu` \ mol -CO\ :math:`{}_{2}` m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is +C\ :sub:`4` plants :math:`A_{p}` (:math:`\mu` \ mol +CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: ZEqnNum104028 @@ -171,27 +166,27 @@ CO\ :math:`{}_{2}` m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is A_{p} =\left\{\begin{array}{l} {3T_{p\qquad } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {k_{p} \frac{c_{i} }{P_{atm} } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}. In these equations, :math:`c_{i}` is the internal leaf -CO\ :math:`{}_{2}` partial pressure (Pa) and :math:`o_{i} =0.20P_{atm}` -is the O\ :math:`{}_{2}` partial pressure (Pa). :math:`K_{c}` and +CO\ :sub:`2` partial pressure (Pa) and :math:`o_{i} =0.20P_{atm}` +is the O\ :sub:`2` partial pressure (Pa). :math:`K_{c}` and :math:`K_{o}` are the Michaelis-Menten constants (Pa) for -CO\ :math:`{}_{2}` and O\ :math:`{}_{2}`. :math:`\Gamma _{\*}` (Pa) is -the CO\ :math:`{}_{2}` compensation point. :math:`V_{c\max }` is the -maximum rate of carboxylation (µmol m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`) and :math:`J` is the electron transport rate (µmol -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`). :math:`T_{p}` is the triose -phosphate utilization rate (µmol m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), +CO\ :sub:`2` and O\ :sub:`2`. :math:`\Gamma _{\*}` (Pa) is +the CO\ :sub:`2` compensation point. :math:`V_{c\max }` is the +maximum rate of carboxylation (µmol m\ :sup:`-2` +s\ :sup:`-1`) and :math:`J` is the electron transport rate (µmol +m\ :sup:`-2` s\ :sup:`-1`). :math:`T_{p}` is the triose +phosphate utilization rate (µmol m\ :sup:`-2` s\ :sup:`-1`), taken as :math:`T_{p} =0.167V_{c\max }` so that -:math:`A_{p} =0.5V_{c\max }` for C\ :math:`{}_{3}` plants (as in -Collatz et al. 1991). For C\ :math:`{}_{4}` plants, the light-limited +:math:`A_{p} =0.5V_{c\max }` for C\ :sub:`3` plants (as in +Collatz et al. 1991). For C\ :sub:`4` plants, the light-limited rate :math:`A_{j}` varies with :math:`\phi` in relation to the quantum -efficiency (:math:`\alpha =0.05` mol CO\ :math:`{}_{2}` -mol\ :math:`{}^{-1}` photon). :math:`\phi` is the absorbed -photosynthetically active radiation (W m\ :math:`{}^{-2}`) (section +efficiency (:math:`\alpha =0.05` mol CO\ :sub:`2` +mol\ :sup:`-1` photon). :math:`\phi` is the absorbed +photosynthetically active radiation (W m\ :sup:`-2`) (section 4.1), which is converted to photosynthetic photon flux assuming 4.6 :math:`\mu` \ mol photons per joule. :math:`k_{p}` is the initial slope -of C\ :math:`{}_{4}` CO\ :math:`{}_{2}` response curve. +of C\ :sub:`4` CO\ :sub:`2` response curve. -For C\ :math:`{}_{3}` plants, the electron transport rate depends on the +For C\ :sub:`3` plants, the electron transport rate depends on the photosynthetically active radiation absorbed by the leaf. A common expression is the smaller of the two roots of the equation @@ -201,13 +196,13 @@ expression is the smaller of the two roots of the equation \Theta _{PSII} J^{2} -\left(I_{PSII} +J_{\max } \right)J+I_{PSII} J_{\max } =0 where :math:`J_{\max }` is the maximum potential rate of electron -transport (:math:`\mu`\ mol m\ :math:`{}^{--2}` s\ :math:`{}^{--1}`), +transport (:math:`\mu`\ mol m\ :sup:`-2` s\ :sup:`-1`), :math:`I_{PSII}` is the light utilized in electron transport by -photosystem II (µmol m\ :math:`{}^{--2}` s\ :math:`{}^{--1}`), and +photosystem II (µmol m\ :sup:`-2` s\ :sup:`-1`), and :math:`\Theta _{PSII}` is a curvature parameter. For a given amount of photosynthetically active radiation absorbed by a leaf :math:`\phi` (W -m\ :math:`{}^{-2}`), converted to photosynthetic photon flux density -with 4.6 :math:`\mu`\ mol J\ :math:`{}^{-1}`, the light utilized in +m\ :sup:`-2`), converted to photosynthetic photon flux density +with 4.6 :math:`\mu`\ mol J\ :sup:`-1`, the light utilized in electron transport is .. math:: @@ -219,8 +214,8 @@ where :math:`\Phi _{PSII}` is the quantum yield of photosystem II, and the term 0.5 arises because one photon is absorbed by each of the two photosystems to move one electron. Parameter values are :math:`\Theta _{PSII}` \ = 0.7 and :math:`\Phi _{PSII}` \ = 0.85. In -calculating :math:`A_{j}` (for both C\ :math:`{}_{3}` and -C\ :math:`{}_{4}` plants), :math:`\phi =\phi ^{sun}` for sunlit leaves +calculating :math:`A_{j}` (for both C\ :sub:`3` and +C\ :sub:`4` plants), :math:`\phi =\phi ^{sun}` for sunlit leaves and :math:`\phi =\phi ^{sha}` for shaded leaves. The model uses co-limitation as described by Collatz et al. (1991, @@ -233,12 +228,12 @@ smaller root of the equations \begin{array}{rcl} {\Theta _{cj} A_{i}^{2} -\left(A_{c} +A_{j} \right)A_{i} +A_{c} A_{j} } & {=} & {0} \\ {\Theta _{ip} A^{2} -\left(A_{i} +A_{p} \right)A+A_{i} A_{p} } & {=} & {0} \end{array} . Values are :math:`\Theta _{cj} =0.98` and :math:`\Theta _{ip} =0.95` for -C\ :math:`{}_{3}` plants; and :math:`\Theta _{cj} =0.80`\ and -:math:`\Theta _{ip} =0.95` for C\ :math:`{}_{4}` plants. +C\ :sub:`3` plants; and :math:`\Theta _{cj} =0.80`\ and +:math:`\Theta _{ip} =0.95` for C\ :sub:`4` plants. :math:`A_{n} =A-R_{d}` . The parameters :math:`K_{c}`, :math:`K_{o}` , and :math:`\Gamma _{*}` -depend on temperature. Values at 25 :math:`{}^\circ` \ C are +depend on temperature. Values at 25 :sup:`o` \ C are :math:`K_{c25} ={\rm 4}0{\rm 4}.{\rm 9}\times 10^{-6} P_{atm}` , :math:`K_{o25} =278.4\times 10^{-3} P_{atm}` , and :math:`\Gamma _{*25} {\rm =42}.75\times 10^{-6} P_{atm}` . @@ -247,14 +242,14 @@ and :math:`R_{d}` also vary with temperature. Parameter values at 25 :math:`\circ`\ C are calculated from :math:`V_{c\max }` \ at 25 :math:`\circ`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}` , :math:`T_{p25} =0.167V_{c\max 25}` , and -:math:`R_{d25} =0.015V_{c\max 25}` (C :math:`\text{}_{3}`) and -:math:`R_{d25} =0.025V_{c\max 25}` (C :math:`{}_{4}`). For -C\ :math:`{}_{4}` plants, :math:`k_{p25} =20000\; V_{c\max 25}` . +:math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`) and +:math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). For +C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}` . However, when the biogeochemistry is active, :math:`R_{d25}` is calculated from leaf nitrogen as :math:`R_{d25} =0.2577N_{a}` , where :math:`N_{a}` is the area-based leaf nitrogen concentration (g N -m\ :math:`{}^{-2}` leaf area, equation ) and 0.2577 :math:`\mu`\ mol -CO\ :math:`{}_{2}` g\ :math:`{}^{-1}` N s\ :math:`{}^{-1}` the base +m\ :sup:`-2` leaf area, equation ) and 0.2577 :math:`\mu`\ mol +CO\ :sub:`2` g\ :sup:`-1` N s\ :sup:`-1` the base respiration rate. The parameters :math:`V_{c\max 25}` , :math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}` , and :math:`R_{d25}` are scaled over the canopy for sunlit and shaded leaves @@ -284,7 +279,7 @@ Table 8.2 list parameter values for :math:`\Delta H_{a}` , :math:`\Delta H_{d}` , and :math:`\Delta S`, from Bonan et al. (2011). Because :math:`T_{p}` as implemented here varies with :math:`V_{c\max }` , the same temperature parameters are used for -:math:`T_{p}` . For C\ :math:`{}_{4}` plants, +:math:`T_{p}` . For C\ :sub:`4` plants, .. math:: :label: 8.12) @@ -292,10 +287,10 @@ Because :math:`T_{p}` as implemented here varies with \begin{array}{l} {V_{c\max } =V_{c\max 25} \left[\frac{Q_{10} ^{(T_{v} -298.15)/10} }{f_{H} \left(T_{v} \right)f_{L} \left(T_{v} \right)} \right]} \\ {f_{H} \left(T_{v} \right)=1+\exp \left[s_{1} \left(T_{v} -s_{2} \right)\right]} \\ {f_{L} \left(T_{v} \right)=1+\exp \left[s_{3} \left(s_{4} -T_{v} \right)\right]} \end{array} with :math:`Q_{10} =2`, -:math:`s_{1} =0.3`\ K\ :math:`{}^{-}`\ :math:`{}^{1}`, +:math:`s_{1} =0.3`\ K\ :sup:`-1` :math:`s_{2} =313.15` K, -:math:`s_{3} =0.2`\ K\ :math:`{}^{-}`\ :math:`{}^{1}`, and -:math:`s_{4} =288.15` K. Additionally, +:math:`s_{3} =0.2`\ K\ :sup:`-1`, and :math:`s_{4} =288.15` K. +Additionally, .. math:: :label: 8.13) @@ -303,7 +298,7 @@ with :math:`Q_{10} =2`, R_{d} =R_{d25} \left\{\frac{Q_{10} ^{(T_{v} -298.15)/10} }{1+\exp \left[s_{5} \left(T_{v} -s_{6} \right)\right]} \right\} with :math:`Q_{10} =2`, :math:`s_{5} =1.3` -K\ :math:`{}^{-}`\ :math:`{}^{1}`, and :math:`s_{6} =328.15`\ K, and +K\ :sup:`-1` and :math:`s_{6} =328.15`\ K, and .. math:: :label: 8.14) @@ -315,7 +310,7 @@ with :math:`Q_{10} =2`. Table 8.2. Temperature dependence parameters for C3 photosynthesis. +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| Parameter | :math:`\Delta H_{a}` (J mol\ :math:`{}^{-}`\ :math:`{}^{1}`) | :math:`\Delta H_{d}` (J mol\ :math:`{}^{-}`\ :math:`{}^{1}`) | :math:`\Delta S` (J mol\ :math:`{}^{-}`\ :math:`{}^{1}` K\ :math:`{}^{-}`\ :math:`{}^{1}`) | +| Parameter | :math:`\Delta H_{a}` (J mol\ :sup:`-1`) | :math:`\Delta H_{d}` (J mol\ :sup:`-1`) | :math:`\Delta S` (J mol\ :sup:`-1` K\ :sup:`-1`) | +========================+=================================================================+=================================================================+==============================================================================================+ | :math:`V_{c\max }` | 65330 | 149250 | 485 | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ @@ -349,8 +344,7 @@ and :math:`J_{\max }` to increase with warmer temperature. In this parameterization, :math:`\Delta H_{d}` \ = 200000, :math:`\Delta H_{a}` \ = 72000 for :math:`V_{c\max }` , and :math:`\Delta H_{a}` \ = 50000 for :math:`J_{\max }` . Additionally, the -ratio :math:`J_{\max 25} /V_{c\max 25}` at 25 :math:`{}^\circ`\ C -decreases with growth temperature as +ratio :math:`J_{\max 25} /V_{c\max 25}` at 25 :sup:`o`\ C decreases with growth temperature as .. math:: :label: 8.16) @@ -359,15 +353,13 @@ decreases with growth temperature as In these acclimation functions, :math:`T_{10}` is the 10-day mean air temperature (K) and :math:`T_{f}` is the freezing point of water (K). -For lack of data, :math:`T_{p}` acclimates similar to -:math:`V_{c\max }` . Acclimation is restricted over the temperature -range :math:`T_{10} -T_{f} \ge 11`\ :math:`{}^\circ`\ C and -:math:`T_{10} -T_{f} \le 35`\ :math:`{}^\circ`\ C. +For lack of data, :math:`T_{p}` acclimates similar to V :sub:`cmax` . Acclimation is restricted over the temperature +range :math:`T_{10} -T_{f} \ge 11`\ :sup:`o`\ C and :math:`T_{10} -T_{f} \le 35`\ :sup:`o`\ C. -:math:`\text{V}_{cmax25}` and Canopy scaling +V\ :sub:`cmax25` and Canopy scaling -------------------------------------------- -The maximum rate of carboxylation at 25 :math:`{}^\circ`\ C varies with +The maximum rate of carboxylation at 25 :sup:`o`\ C varies with foliage nitrogen concentration and specific leaf area and is calculated as in Thornton and Zimmermann (2007). At 25ºC, @@ -377,12 +369,12 @@ as in Thornton and Zimmermann (2007). At 25ºC, V_{c\max 25} =N_{a} F_{LNR} F_{NR} a_{R25} where :math:`N_{a}` is the area-based leaf nitrogen concentration (g N -m\ :math:`{}^{-2}` leaf area), :math:`F_{LNR}` is the fraction of leaf -nitrogen in Rubisco (g N in Rubisco g\ :math:`{}^{-1}` N), +m\ :sup:`-2` leaf area), :math:`F_{LNR}` is the fraction of leaf +nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N), :math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass -to nitrogen in Rubisco (g Rubisco g\ :math:`{}^{-1}` N in Rubisco), and +to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and :math:`a_{R25} =60` is the specific activity of Rubisco (µmol -CO\ :math:`{}_{2}` g\ :math:`{}^{-1}` Rubisco s\ :math:`{}^{-1}`). +CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`). :math:`N_{a}` is calculated from mass-based leaf N concentration and specific leaf area @@ -392,8 +384,8 @@ specific leaf area N_{a} =\frac{1}{CN_{L} \; SLA_{0} } where :math:`CN_{L}` is the leaf carbon-to-nitrogen ratio (g C -g\ :math:`{}^{-1}` N) and :math:`SLA_{0}` is specific leaf area at the -canopy top ( :math:`\text{m}^{2}\,\text{leaf area}\,\text{g}^{-1}\,\text{C}` ). Table 8.1 +g\ :sup:`-1` N) and :math:`SLA_{0}` is specific leaf area at the +canopy top ( m\ :sup:`2` leaf area g\ :sup:`-1` C ). Table 8.1 lists values of :math:`F_{LNR}` , :math:`CN_{L}` , and :math:`SLA_{0}` for each plant functional type. :math:`F_{LNR}` was chosen to give :math:`V_{c\max 25}` consistent with Kattge et al. (2009), as discussed @@ -450,7 +442,7 @@ extinction coefficient (equation 4.9). Photosynthetic parameters The value :math:`K_{n} = 0.11` chosen by Bonan et al. (2011) is consistent with observationally-derived estimates for forests, mostly -tropical, and provides a gradient in :math:`\text{V}_{cmax}` similar to +tropical, and provides a gradient in V\ :sub:`cmax` similar to the original CLM4 specific leaf area scaling. However, Bonan et al. (2012) showed that the sunlit/shaded canopy parameterization does not match an explicit multi-layer canopy parameterization. The discrepancy @@ -487,8 +479,8 @@ Soil water stress Soil water influences stomatal conductance directly by multiplying the minimum conductance by a soil water stress function :math:`\beta _{t}` -and also indirectly through :math:`A_{n}` in the C\ :math:`{}_{3}` and -C\ :math:`{}_{4}` photosynthesis models, as in Sellers et al. (1996). +and also indirectly through :math:`A_{n}` in the C\ :sub:`3` and +C\ :sub:`4` photosynthesis models, as in Sellers et al. (1996). The latter effect is achieved by multiplying :math:`V_{c\; \max }` and :math:`R_{d}` by :math:`\beta _{t}` . @@ -540,10 +532,10 @@ where :math:`\theta _{ice,\, i} ={w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(\rho _{ice} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{ice} \Delta z_{i} \right)} \le \theta _{sat,\, i}` \ and :math:`\theta _{liq,\, i} ={w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(\rho _{liq} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{liq} \Delta z_{i} \right)} \le \theta _{sat,\, i} -\theta _{ice,\, i}` . :math:`w_{ice,\, i}` and :math:`w_{liq,\, i}` are the ice and liquid -water contents (kg m\ :math:`{}^{-2}`) (Chapter 7), +water contents (kg m\ :sup:`-2`) (Chapter 7), :math:`\theta _{sat,\, i}` is the saturated volumetric water content (section 7.4.1), :math:`\rho _{ice}` and :math:`\rho _{liq}` are the -densities of ice and liquid water (kg m\ :math:`{}^{-3}`) (Table 2.6), +densities of ice and liquid water (kg m\ :sup:`-3`) (Table 2.6), and :math:`\Delta z_{i}` is the soil layer thickness (m) (section 6.1). The root fraction :math:`r_{i}` in each soil layer depends on the plant @@ -587,11 +579,11 @@ Table 8.3. Plant functional type root distribution parameters. +----------------------------------+------------------+------------------+ | BDS boreal | 7.0 | 1.5 | +----------------------------------+------------------+------------------+ -| C\ :math:`{}_{3}` grass arctic | 11.0 | 2.0 | +| C\ :sub:`3` grass arctic | 11.0 | 2.0 | +----------------------------------+------------------+------------------+ -| C\ :math:`{}_{3}` grass | 11.0 | 2.0 | +| C\ :sub:`3` grass | 11.0 | 2.0 | +----------------------------------+------------------+------------------+ -| C\ :math:`{}_{4}` grass | 11.0 | 2.0 | +| C\ :sub:`4` grass | 11.0 | 2.0 | +----------------------------------+------------------+------------------+ | Crop R | 6.0 | 3.0 | +----------------------------------+------------------+------------------+ @@ -617,13 +609,13 @@ Table 8.3. Plant functional type root distribution parameters. Numerical implementation ---------------------------- -The CO\ :math:`{}_{2}` partial pressure at the leaf surface +The CO\ :sub:`2` partial pressure at the leaf surface :math:`c_{s}` (Pa) and the vapor pressure at the leaf surface :math:`e_{s}` (Pa), needed for the stomatal resistance model in -equation , and the internal leaf CO\ :math:`{}_{2}` partial pressure +equation , and the internal leaf CO\ :sub:`2` partial pressure :math:`c_{i}` (Pa), needed for the photosynthesis model in equations -, are calculated assuming there is negligible capacity to store -CO\ :math:`{}_{2}` and water vapor at the leaf surface so that +CO\ :sub:`2` and water vapor at the leaf surface so that .. math:: :label: ZEqnNum581596 @@ -638,13 +630,13 @@ and the transpiration fluxes are related as \frac{e_{a} -e_{i} }{r_{b} +r_{s} } =\frac{e_{a} -e_{s} }{r_{b} } =\frac{e_{s} -e_{i} }{r_{s} } where :math:`r_{b}` is leaf boundary layer resistance (s -m\ :math:`{}^{2}` :math:`\mu` \ mol\ :math:`{}^{-1}`) (section 5.3), the -terms 1.4 and 1.6 are the ratios of diffusivity of CO\ :math:`{}_{2}` to -H\ :math:`{}_{2}`\ O for the leaf boundary layer resistance and stomatal +m\ :sup:`2` :math:`\mu` \ mol\ :sup:`-1`) (section 5.3), the +terms 1.4 and 1.6 are the ratios of diffusivity of CO\ :sub:`2` to +H\ :sub:`2`\ O for the leaf boundary layer resistance and stomatal resistance, :math:`c_{a} ={\rm CO}_{{\rm 2}} \left({\rm mol\; mol}^{{\rm -1}} \right)P_{atm}` -is the atmospheric CO\ :math:`{}_{2}` partial pressure (Pa) calculated -from CO\ :math:`{}_{2}` concentration (ppmv), :math:`e_{i}` is the +is the atmospheric CO\ :sub:`2` partial pressure (Pa) calculated +from CO\ :sub:`2` concentration (ppmv), :math:`e_{i}` is the saturation vapor pressure (Pa) evaluated at the leaf temperature :math:`T_{v}` , and :math:`e_{a}` is the vapor pressure of air (Pa). The vapor pressure of air in the plant canopy :math:`e_{a}` (Pa) is @@ -656,7 +648,7 @@ determined from e_{a} =\frac{P_{atm} q_{s} }{0.622} where :math:`q_{s}` is the specific humidity of canopy air (kg -kg\ :math:`{}^{-1}`) (section 5.3). Equations and are solved for +kg\ :sup:`-1`) (section 5.3). Equations and are solved for :math:`c_{s}` and :math:`e_{s}` .. math:: @@ -706,13 +698,13 @@ resolved at depths in the canopy using a light profile (Chapter 4). In this case, :math:`V_{c\max 25}` is not integrated over the canopy, but is instead given explicitly for each canopy layer using equation . This also uses the Lloyd et al. (2010) relationship whereby -:math:`\text{K}_{n}` scales with :math:`\text{V}_{cmax}` as +K\ :sub:`n` scales with V\ :sub:`cmax` as .. math:: :label: 8.38) K_{n} =\exp \left(0.00963V_{c\max } -2.43\right) -such that higher values of :math:`\text{V}_{cmax}` imply steeper declines +such that higher values of V\ :sub:`cmax` imply steeper declines in photosynthetic capacity through the canopy with respect to cumulative leaf area. diff --git a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst b/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst index b13328cecb..900f8873a9 100644 --- a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst +++ b/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst @@ -41,7 +41,7 @@ implemented, the lake consists of 0-5 snow layers; water and ice layers layer has a fixed water mass (set by the nominal layer thickness and the liquid density), with frozen mass-fraction *I* a state variable. Resolved snow layers are present if the snow thickness -:math:`z_{sno} \ge s_{\min }` , where *s* :math:`{}_{min}` = 4 cm by +:math:`z_{sno} \ge s_{\min }` , where *s*\ :sub:`min` = 4 cm by default, and is adjusted for model timesteps other than 1800 s in order to maintain numerical stability (section 9.6.5). For global simulations with 10 body layers, the default (50 m lake) body layer thicknesses are @@ -58,7 +58,7 @@ maintain fixed proportions. For lakes with *d* :math:`<` 1 m, all layers have equal thickness. Thicknesses of snow, soil, and bedrock layers follow the scheme used over non-vegetated surfaces (Chapter 6), with modifications to the snow layer thickness rules to keep snow layers at -least as thick as *s*\ :math:`{}_{min}` (section 9.6.5). +least as thick as *s*\ :sub:`min` (section 9.6.5). External Data ----------------- @@ -66,7 +66,7 @@ External Data As discussed in Subin et al (2012a, b), the Global Lake and Wetland Database (Lehner and Doll 2004) is currently used to prescribe lake fraction in each land model grid cell, for a total of 2.3 million -km\ :math:`{}^{-2}`. As in Subin et al. (2012a, b), the Kourzeneva +km\ :sup:`-2`. As in Subin et al. (2012a, b), the Kourzeneva (2012) global gridded dataset is currently used to estimate a mean lake depth in each grid cell, based on interpolated compilations of geographic information. @@ -75,7 +75,7 @@ Surface Albedo ------------------ For direct radiation, the albedo *a* for lakes with ground temperature -:math:`\text{T}_{g}` * (K) above freezing is given by (Pivovarov, 1972) +:math:`{T}_{g}` (K) above freezing is given by (Pivovarov, 1972) .. math:: :label: ZEqnNum194122 @@ -86,9 +86,9 @@ where *z* is the zenith angle. For diffuse radiation, the expression in eq. is integrated over the full sky to yield *a* = 0.10. For frozen lakes without resolved snow layers, the albedo at cold -temperatures *a* :math:`{}_{0}` is 0.60 for visible and 0.40 for near +temperatures *a*\ :sub:`0` is 0.60 for visible and 0.40 for near infrared radiation. As the temperature at the ice surface, -:math:`\text{T}_{g}`, approaches freezing [ :math:`\text{T}_{f}` (K) (Table +:math:`{T}_{g}`, approaches freezing [ :math:`{T}_{f}` (K) (Table 2.6)], the albedo is relaxed towards 0.10 based on Mironov et al. (2010): .. math:: @@ -99,7 +99,7 @@ infrared radiation. As the temperature at the ice surface, where *a* is restricted to be no less than that given in eq. . For frozen lakes with resolved snow layers, the reflectance of the ice -surface is fixed at *a* :math:`{}_{0}`, and the snow reflectance is +surface is fixed at *a*\ :sub:`0`, and the snow reflectance is calculated as over non-vegetated surfaces (Chapter 3). These two reflectances are combined to obtain the snow-fraction-weighted albedo as in over non-vegetated surfaces (Chapter 3). @@ -115,12 +115,12 @@ Overview of Changes from CLM4 roughnesses depend (weakly) on the friction velocity :math:`u_{\*}` (which itself depends weakly on the surface roughnesses), their calculation has been incorporated into the iteration solution for - :math:`\text{T}_{g}`, and the maximum number of iterations has been + :math:`{T}_{g}`, and the maximum number of iterations has been increased to 4. Convergence of the modified solution was tested during development. #. A coefficient of :math:`\beta` has been added to - :math:`\text{S}_{g}` in eq. , correcting a previous error. + :math:`{S}_{g}` in eq. , correcting a previous error. .. todo:: fill this equation number in #. The top layer thickness :math:`\Delta z_{T}` used in eq. has been @@ -132,7 +132,7 @@ Overview of Changes from CLM4 conductivity calculated in the previous timestep. #. Several conditions are imposed on the ground temperature - :math:`\text{T}_{g}` to maintain a stable density profile at the lake + :math:`{T}_{g}` to maintain a stable density profile at the lake surface eq. . Surface Properties @@ -154,7 +154,7 @@ forcing. For frozen lakes ( :math:`T_{g} \le T_{f}` ) with resolved snow layers, the momentum roughness length :math:`z_{0m} =2.4\times 10^{-3} {\rm m}` (as over non-vegetated surfaces; Chapter 5), and the scalar roughness lengths -(*z* :math:`{}_{0}`\ :math:`{}_{q}`, for latent heat; and *z* :math:`{}_{0}`\ :math:`{}_{h}`, for sensible heat) are given by +(*z*\ :sub:`0q` for latent heat; and *z*\ :sub:`0h`, for sensible heat) are given by (Zilitinkevich 1970) .. math:: @@ -165,14 +165,13 @@ surfaces; Chapter 5), and the scalar roughness lengths where :math:`R_{0}` is the near-surface atmospheric roughness Reynolds number, :math:`z_{0h}` is the roughness length for sensible heat, :math:`z_{0q}` is the -roughness length for latent heat, :math:`\nu` ( :math:`\text{m}^{2}\,\text{s}^{-1}`) is the kinematic viscosity of air, and -:math:`u_{\*}` ( :math:`\text{m\,s}^{-1}` ) is the friction velocity in the +roughness length for latent heat, :math:`\nu` (m\ :sup:`2` s\ :sup:`-1`) is the kinematic viscosity of air, and +:math:`u_{\*}` (m s\ :sup:`-1`) is the friction velocity in the atmospheric surface layer. For frozen lakes without resolved snow layers, :math:`z_{0m} =1\times 10^{-3} {\rm m}` (Subin et al. 2012a), and the scalar roughness lengths are given by . -For unfrozen lakes, *z* :math:`{}_{0}`\ :math:`{}_{m}` is given by -(Subin et al. 2012a) +For unfrozen lakes, *z*\ :sub:`0m` is given by (Subin et al. 2012a) .. math:: :label: ZEqnNum864823 @@ -193,7 +192,7 @@ where :math:`\nu _{0} =1.51\times 10^{-5} {\textstyle\frac{{\rm m}^{{\rm 2}} }{{\rm s}}}` , :math:`T_{0} ={\rm 293.15\; K}`, :math:`P_{0} =1.013\times 10^{5} {\rm \; Pa}` , and -:math:`\text{P}_{ref}` is the pressure at the atmospheric reference +:math:`\{P}_{ref}` is the pressure at the atmospheric reference height. The Charnock coefficient *C* is a function of the lake fetch *F* (m), given in the surface data or set to 25 times the lake depth *d* by default: @@ -206,7 +205,7 @@ default: where *A* and *B* define the fetch- and depth-limitation, respectively; :math:`C_{\min } =0.01` , :math:`C_{\max } =0.01`, :math:`\varepsilon =1` , :math:`f_{c} =100` , and *u* (m -s\ :math:`{}^{-1}`) is the atmospheric forcing wind. +s\ :sup:`-1`) is the atmospheric forcing wind. Surface Flux Solution ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -224,7 +223,7 @@ where :math:`\vec{S}_{g}` \ is the absorbed solar radiation in the lake, :math:`H_{g}` \ is the sensible heat flux (+ upwards), :math:`E_{g}` \ is the water vapor flux (+ upwards), and *G* is the ground heat flux (+ downwards). All of these fluxes depend implicitly on -the temperature at the lake surface :math:`\text{T}_{g}`. +the temperature at the lake surface :math:`{T}_{g}`. :math:`\lambda` converts :math:`E_{g}` to an energy flux based on .. math:: @@ -232,7 +231,7 @@ the temperature at the lake surface :math:`\text{T}_{g}`. \lambda =\left\{\begin{array}{l} {\lambda _{sub} \qquad T_{g} \le T_{f} } \\ {\lambda _{vap} \qquad T_{g} >T_{f} } \end{array}\right\}. -The sensible heat flux (W m\ :math:`{}^{-2}`) is +The sensible heat flux (W m\ :sup:`-2`) is .. math:: :label: ZEqnNum720553 @@ -240,15 +239,15 @@ The sensible heat flux (W m\ :math:`{}^{-2}`) is H_{g} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{g} \right)}{r_{ah} } where :math:`\rho _{atm}` is the density of moist air (kg -m\ :math:`{}^{-3}`) (Chapter 5), :math:`C_{p}` is the specific heat -capacity of air (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) (Table 2.6), +m\ :sup:`-3`) (Chapter 5), :math:`C_{p}` is the specific heat +capacity of air (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), :math:`\theta _{atm}` is the atmospheric potential temperature (K) (Chapter 5), :math:`T_{g}` is the lake surface temperature (K) (at an infinitesimal interface just above the top resolved model layer: snow, ice, or water), and :math:`r_{ah}` is the aerodynamic resistance to -sensible heat transfer (s m\ :math:`{}^{-1}`) (section 5.1). +sensible heat transfer (s m\ :sup:`-1`) (section 5.1). -The water vapor flux (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is +The water vapor flux (kg m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 9.10) @@ -256,10 +255,10 @@ The water vapor flux (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) is E_{g} =-\frac{\rho _{atm} \left(q_{atm} -q_{sat}^{T_{g} } \right)}{r_{aw} } where :math:`q_{atm}` is the atmospheric specific humidity (kg -kg\ :math:`{}^{-1}`) (section 2.2.1), :math:`q_{sat}^{T_{g} }` \ is the -saturated specific humidity (kg kg\ :math:`{}^{-1}`) (section 5.5) at +kg\ :sup:`-1`) (section 2.2.1), :math:`q_{sat}^{T_{g} }` \ is the +saturated specific humidity (kg kg\ :sup:`-1`) (section 5.5) at the lake surface temperature :math:`T_{g}` , and :math:`r_{aw}` is the -aerodynamic resistance to water vapor transfer (s m\ :math:`{}^{-1}`) +aerodynamic resistance to water vapor transfer (s m\ :sup:`-1`) (section 5.1). The zonal and meridional momentum fluxes are @@ -275,11 +274,11 @@ The zonal and meridional momentum fluxes are \tau _{y} =-\rho _{atm} \frac{v_{atm} }{r_{atm} } where :math:`u_{atm}` and :math:`v_{atm}` are the zonal and -meridional atmospheric winds (m s\ :math:`{}^{-1}`) (section 2.2.1), and +meridional atmospheric winds (m s\ :sup:`-1`) (section 2.2.1), and :math:`r_{am}` is the aerodynamic resistance for momentum (s -m\ :math:`{}^{-1}`) (section 5.1). +m\ :sup:`-1`) (section 5.1). -The heat flux into the lake surface :math:`G` (W m\ :math:`{}^{-2}`) is +The heat flux into the lake surface :math:`G` (W m\ :sup:`-2`) is .. math:: :label: ZEqnNum122376 @@ -287,7 +286,7 @@ The heat flux into the lake surface :math:`G` (W m\ :math:`{}^{-2}`) is G=\frac{2\lambda _{T} }{\Delta z_{T} } \left(T_{g} -T_{T} \right) where :math:`\lambda _{T}` is the thermal conductivity (W -m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), :math:`\Delta z_{T}` is the +m\ :sup:`-1` K\ :sup:`-1`), :math:`\Delta z_{T}` is the thickness (m), and :math:`T_{T}` is the temperature (K) of the top resolved lake layer (snow, ice, or water). The top thermal conductivity :math:`\lambda _{T}` of unfrozen lakes ( :math:`T_{g} >T_{f}` ) @@ -310,7 +309,7 @@ The absorbed solar radiation :math:`\vec{S}_{g}` is where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and :math:`S_{atm} \, \downarrow _{\Lambda }` are the incident direct beam -and diffuse solar fluxes (W m\ :math:`{}^{-2}`) and :math:`\Lambda` +and diffuse solar fluxes (W m\ :sup:`-2`) and :math:`\Lambda` denotes the visible (:math:`<` 0.7\ :math:`\mu {\rm m}`) and near-infrared (:math:`\ge` 0.7\ :math:`\mu {\rm m}`) wavebands (section 2.2.1), and :math:`\alpha _{g,\, \Lambda }^{\mu }` and @@ -335,10 +334,8 @@ the surface is L\, \uparrow =\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) where :math:`\varepsilon _{g} =0.97` is the lake surface emissivity, -:math:`\sigma` is the Stefan-Boltzmann constant (W m\ :math:`{}^{-2}` -K\ :math:`{}^{-4}`) (Table 2.6), and :math:`T_{g}^{n+1} -T_{g}^{n}` is -the difference in lake surface temperature between Newton-Raphson -iterations (see below). +:math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6), and :math:`T_{g}^{n+1} -T_{g}^{n}` is +the difference in lake surface temperature between Newton-Raphson iterations (see below). The sensible heat :math:`H_{g}` , the water vapor flux :math:`E_{g}` through its dependence on the saturated specific humidity, the net @@ -388,14 +385,14 @@ simultaneously with lake surface temperature as follows. The stability-related equations are the same as for non-vegetated surfaces (section 5.2), except that the surface roughnesses are here (weakly varying) functions of the friction velocity :math:`u_{\*}` . To begin, -*z* :math:`{}_{0}`\ :math:`{}_{m}` is set based on the value +*z*\ :sub:`0m` is set based on the value calculated for the last timestep (for :math:`T_{g} >T_{f}` ) or based on the values in section 9.4.2 (otherwise), and the scalar roughness lengths are set based on the relationships in section 9.4.2. #. An initial guess for the wind speed :math:`V_{a}` including the convective velocity :math:`U_{c}` is obtained from eq. assuming an - initial convective velocity :math:`U_{c} =0` m s\ :math:`{}^{-1}` for + initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from eq. ) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). @@ -460,7 +457,7 @@ layer temperature :math:`T_{T}` \ (Subin et al. 2012a). \begin{array}{l} {{\rm 1)\; }T_{T} \le T_{f} T_{g} ^{{'} } >T_{m} \Rightarrow T_{g} =T_{T} ,} \\ {{\rm 3)\; }T_{m} >T_{g} ^{{'} } >T_{T} >T_{f} \Rightarrow T_{g} =T_{T} } \end{array} where :math:`T_{m}` \ is the temperature of maximum liquid water -density, 3.85\ :math:`{}^\circ`\ C (Hostetler and Bartlein 1990). The +density, 3.85\ :sup:`o` C (Hostetler and Bartlein 1990). The first condition requires that, if there is any snow or ice present, the surface temperature is restricted to be less than or equal to freezing. The second and third conditions maintain convective stability in the top @@ -474,7 +471,7 @@ XXX in order to precisely conserve energy. XXX This ground heat flux is taken as a prescribed flux boundary condition for the lake temperature solution (section 9.5.3). An energy balance check is included at each timestep to insure that eq. XXX is obeyed to within -0.1 W m\ :math:`{}^{-2}`. +0.1 W m\ :sup:`-2`. Lake Temperature -------------------- @@ -493,10 +490,10 @@ land units (Chapter 6), is \tilde{c}_{v} \frac{\partial T}{\partial t} =\frac{\partial }{\partial z} \left(\tau \frac{\partial T}{\partial z} \right)-\frac{d\phi }{dz} where :math:`\tilde{c}_{v}` is the volumetric heat capacity (J -m\ :math:`{}^{-3}` K\ :math:`{}^{-1}`), :math:`t` is time (s), *T* is +m\ :sup:`-3` K\ :sup:`-1`), :math:`t` is time (s), *T* is the temperature (K), :math:`\tau` is the thermal conductivity (W -m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), and :math:`\phi` is the solar -radiation (W m\ :math:`{}^{-2}`) penetrating to depth *z* (m). The +m\ :sup:`-1` K\ :sup:`-1`), and :math:`\phi` is the solar +radiation (W m\ :sup:`-2`) penetrating to depth *z* (m). The system is discretized into *N* layers, where .. math:: @@ -555,7 +552,7 @@ The top boundary condition, imposed at the top modeled layer downwards surface flux *G* defined by the energy flux residual during the surface temperature solution (section 9.4.3). The bottom boundary condition, imposed at :math:`i=N_{levlak} +N_{levgrnd}` , is zero flux. -The 2-m windspeed :math:`u_{2}` \ (m s\ :math:`{}^{-1}`) is used in the +The 2-m windspeed :math:`u_{2}` \ (m s\ :sup:`-1`) is used in the calculation of eddy diffusivity: .. math:: @@ -569,7 +566,7 @@ where :math:`u_{*}` \ is the friction velocity calculated in section Eddy Diffusivity and Thermal Conductivities ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The total eddy diffusivity :math:`K_{W}` (:math:`\text{m}^{2}\,\text{s}^{-1}`) for liquid water in the lake body is given by (Subin et al. 2012a) +The total eddy diffusivity :math:`K_{W}` (m\ :sup:`2` s\ :sup:`-1`) for liquid water in the lake body is given by (Subin et al. 2012a) .. math:: :label: 9.29) @@ -582,9 +579,9 @@ intended to represent unresolved mixing processes (Fang and Stefan 1996), :math:`\kappa _{m} =\frac{\lambda _{liq} }{c_{liq} \rho _{liq} }` \ is the molecular diffusivity of water (given by the ratio of its thermal -conductivity (W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) to the product of -its heat capacity (J kg\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) and density -(kg m\ :math:`{}^{-3}`), values given in Table 2.6), and :math:`m_{d}` +conductivity (W m\ :sup:`-1` K\ :sup:`-1`) to the product of +its heat capacity (J kg\ :sup:`-1` K\ :sup:`-1`) and density +(kg m\ :sup:`-3`), values given in Table 2.6), and :math:`m_{d}` (unitless) is a factor which increases the overall diffusivity for large lakes, intended to represent 3-dimensional mixing processes such as caused by horizontal temperature gradients. As currently implemented, @@ -596,8 +593,7 @@ caused by horizontal temperature gradients. As currently implemented, where *d* is the lake depth. -The wind-driven eddy diffusion coefficient :math:`\kappa _{e,\, i}` -( :math:`\text{m}^{2}\,\text{s}^{-1}` ) for layers :math:`1\le i\le N_{levlak}` is +The wind-driven eddy diffusion coefficient :math:`\kappa _{e,\, i}` (m\ :sup:`2` s\ :sup:`-1`) for layers :math:`1\le i\le N_{levlak}` is .. math:: :label: 9.31) @@ -606,13 +602,13 @@ The wind-driven eddy diffusion coefficient :math:`\kappa _{e,\, i}` where :math:`P_{0} =1` is the neutral value of the turbulent Prandtl number, :math:`z_{i}` is the node depth (m), the surface friction -velocity (m s\ :math:`{}^{-1}`) is :math:`w^{*} =0.0012u_{2}` , and +velocity (m s\ :sup:`-1`) is :math:`w^{*} =0.0012u_{2}` , and :math:`k^{*}` varies with latitude :math:`\phi` as :math:`k^{*} =6.6u_{2}^{-1.84} \sqrt{\left|\sin \phi \right|}` . For the bottom layer, :math:`\kappa _{e,\, N_{levlak} } =\kappa _{e,N_{levlak} -1\, }` . As in Hostetler and Bartlein (1990), the 2-m wind speed :math:`u_{2}` (m -s\ :math:`{}^{-1}`) (eq. ) is used to evaluate :math:`w^{*}` and +s\ :sup:`-1`) (eq. ) is used to evaluate :math:`w^{*}` and :math:`k^{*}` rather than the 10-m wind used by Henderson-Sellers (1985). @@ -630,9 +626,9 @@ where N^{2} =\frac{g}{\rho _{i} } \frac{\partial \rho }{\partial z} -and :math:`g` is the acceleration due to gravity (m s\ :math:`{}^{-2}`) +and :math:`g` is the acceleration due to gravity (m s\ :sup:`-2`) (Table 2.6), :math:`\rho _{i}` is the density of water (kg -m\ :math:`{}^{-3}`), and :math:`\frac{\partial \rho }{\partial z}` is +m\ :sup:`-3`), and :math:`\frac{\partial \rho }{\partial z}` is approximated as :math:`\frac{\rho _{i+1} -\rho _{i} }{z_{i+1} -z_{i} }` . Note that because here, *z* is increasing downwards (unlike in Hostetler and @@ -656,7 +652,7 @@ where :math:`N^{2}` \ is calculated as in eq. except for the minimum value imposed in . The thermal conductivity for the liquid water portion of lake body layer -*i*, :math:`\tau _{liq,i}` (W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`) is +*i*, :math:`\tau _{liq,i}` (W m\ :sup:`-1` K\ :sup:`-1`) is given by .. math:: @@ -665,7 +661,7 @@ given by \tau _{liq,i} =K_{W} c_{liq} \rho _{liq} . The thermal conductivity of the ice portion of lake body layer *i*, -:math:`\tau _{ice,eff}` \ (W m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), is +:math:`\tau _{ice,eff}` \ (W m\ :sup:`-1` K\ :sup:`-1`), is constant among layers, and is given by .. math:: @@ -701,7 +697,7 @@ If there are no resolved snow layers, the surface absorption fraction :math:`\be by the atmospheric model. This is apportioned to the surface energy budget (section 9.4.2), and thus no additional radiation is absorbed in the top :math:`z_{a}` (currently 0.6 m) of unfrozen lakes, for which -the light extinction coefficient :math:`\eta` ( :math:`\text{m}^{-1}` ) +the light extinction coefficient :math:`\eta` (m\ :sup:`-1`) varies between lake columns (eq. ). For frozen lakes (:math:`T_{g} \le T_{f}` ), the remaining :math:`\left(1-\beta \right)\vec{S}_{g}` fraction of surface absorbed radiation that is not apportioned to the surface energy budget is @@ -730,11 +726,11 @@ For all lake body layers, the flux absorbed by the layer *i*, \phi _{i} =\left(1-\beta \vec{S}_{g} \right)\left[\exp \left\{-\eta \left(z_{i} -\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}-\exp \left\{-\eta \left(z_{i} +\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}\right] . The argument of each exponent is constrained to be non-negative (so -:math:`\phi _{i}` = 0 for layers contained within :math:`\text{z}_{a}`). +:math:`\phi _{i}` = 0 for layers contained within :math:`{z}_{a}`). The remaining flux exiting the bottom of layer :math:`i=N_{levlak}` is absorbed in the top soil layer. -The light extinction coefficient :math:`\eta` ( :math:`\text{m}^{-1}` ), if +The light extinction coefficient :math:`\eta` (m\ :sup:`-1`), if not provided as external data, is a function of depth *d* (m) (Subin et al. 2012a): @@ -747,8 +743,7 @@ Heat Capacities ^^^^^^^^^^^^^^^^^^^^^ The vertically-integrated heat capacity for each lake layer, -:math:`\text{c}_{v,i}\,\text{J\,m}^{-2}`) is -determined by the mass-weighted average over the heat capacities for the +:math:`\text{c}_{v,i}` (J m\ :sup:`-2`) is determined by the mass-weighted average over the heat capacities for the water and ice fractions: .. math:: @@ -760,7 +755,7 @@ Note that the density of water is used for both ice and water fractions, as the thickness of the layer is fixed. The total heat capacity :math:`c_{v,i}` for each soil, snow, and -bedrock layer (J m\ :math:`{}^{-2}`) is determined as for vegetated land +bedrock layer (J m\ :sup:`-2`) is determined as for vegetated land units (Chapter 6), as the sum of the heat capacities for the water, ice, and mineral constituents. @@ -772,8 +767,8 @@ soil (Chapter 6), except that the lake body layers are sandwiched between the snow and soil layers (section 9.5.1), and radiation flux is absorbed throughout the lake layers. Before solution, layer temperatures :math:`T_{i}` (K), thermal conductivities :math:`\tau _{i}` (W -m\ :math:`{}^{-1}` K\ :math:`{}^{-1}`), heat capacities :math:`c_{v,i}` -(J m\ :math:`{}^{-2}`), and layer and interface depths from all +m\ :sup:`-1` K\ :sup:`-1`), heat capacities :math:`c_{v,i}` +(J m\ :sup:`-2`), and layer and interface depths from all components are transformed into a uniform set of vectors with length :math:`N=n_{sno} +N_{levlak} +N_{levgrnd}` and consistent units to simplify the solution. Thermal conductivities at layer interfaces are @@ -799,7 +794,7 @@ layer as where superscripts *n* + 1 and *n* denote values at the end and beginning of the timestep :math:`\Delta t`, respectively, :math:`F_{i}` -(W m\ :math:`{}^{-2}`) is the downward heat flux at the bottom of layer +(W m\ :sup:`-2`) is the downward heat flux at the bottom of layer *i*, and :math:`\phi _{i}` is the solar radiation absorbed in layer *i*. @@ -833,7 +828,7 @@ given layer if the temperature is below freezing and liquid water remains, or if the temperature is above freezing and ice remains. If melting occurs, the available energy for melting, :math:`Q_{avail}` -(J m\ :math:`{}^{-2}`), is computed as +(J m\ :sup:`-2`), is computed as .. math:: :label: ZEqnNum598199 @@ -842,7 +837,7 @@ If melting occurs, the available energy for melting, :math:`Q_{avail}` where :math:`T_{i}` is the temperature of the layer after thermal diffusion (section 9.5.7), and :math:`c_{v,i}` \ is as calculated in -section 9.5.6. The mass of melt in the layer *M* (kg m\ :math:`{}^{-2}`) +section 9.5.6. The mass of melt in the layer *M* (kg m\ :sup:`-2`) is given by .. math:: @@ -850,7 +845,7 @@ is given by M=\min \left\{M_{ice} ,\frac{Q_{avail} }{H_{fus} } \right\} -where :math:`H_{fus}` (J kg\ :math:`{}^{-1}`) is the latent heat of +where :math:`H_{fus}` (J kg\ :sup:`-1`) is the latent heat of fusion of water (Table 2.6), and :math:`M_{ice}` is the mass of ice in the layer: :math:`I_{i} \rho _{liq} \Delta z_{i}` for a lake body layer, or simply the soil / snow ice content state variable @@ -991,7 +986,7 @@ Energy Conservation To check energy conservation, the left-hand side of eq. XXX is re-written to yield the total enthalpy of the lake system (J -m\ :math:`{}^{-2}`) :math:`H_{tot}` : +m\ :sup:`-2`) :math:`H_{tot}` : .. math:: :label: 9.57) @@ -1004,14 +999,14 @@ present in resolved snow layers. This expression is evaluated once at the beginning and once at the end of the timestep (re-evaluating each :math:`c_{v,i}` ), and the change is compared with the net surface energy flux to yield the error flux :math:`E_{soi}` (W -m\ :math:`{}^{-2}`): +m\ :sup:`-2`): .. math:: :label: 9.58) E_{soi} =\frac{\Delta H_{tot} }{\Delta t} -G-\sum _{i=j_{top} }^{N_{levlak} +N_{levgrnd} }\phi _{i} -If :math:`\left|E_{soi} \right|<0.1`\ W m\ :math:`{}^{-2}`, it is +If :math:`\left|E_{soi} \right|<0.1`\ W m\ :sup:`-2`, it is subtracted from the sensible heat flux and added to *G*. Otherwise, the model is aborted. @@ -1025,8 +1020,8 @@ Hydrology is done similarly to other impervious non-vegetated columns (e.g., glaciers) where snow layers may be resolved but infiltration into the permanent ground is not allowed. The water mass of lake columns is currently maintained constant, aside from overlying snow. The water -budget is balanced with :math:`q_{rgwl}` (eq. ; kg m\ :math:`{}^{-2}` -s\ :math:`{}^{-1}`), a generalized runoff term for impervious land units +budget is balanced with :math:`q_{rgwl}` (eq. ; kg m\ :sup:`-2` +s\ :sup:`-1`), a generalized runoff term for impervious land units that may be negative. There are some modifications to the soil and snow parameterizations as @@ -1055,12 +1050,12 @@ The total water balance of the system is given by \Delta W_{sno} +\sum _{i=1}^{n_{levsoi} }\left(\Delta w_{liq,i} +\Delta w_{ice,i} \right) =\left(q_{rain} +q_{sno} -E_{g} -q_{rgwl} -q_{snwcp,\, ice} \right)\Delta t -where :math:`W_{sno}` (kg m\ :math:`{}^{-2}`) is the total mass of snow +where :math:`W_{sno}` (kg m\ :sup:`-2`) is the total mass of snow (both liquid and ice, in resolved snow layers or bulk snow), :math:`w_{liq,i}` and :math:`w_{ice,i}` are the masses of water phases -(kg m\ :math:`{}^{-2}`) in soil layer *i*, :math:`q_{rain}` and +(kg m\ :sup:`-2`) in soil layer *i*, :math:`q_{rain}` and :math:`q_{sno}` are the precipitation forcing from the atmosphere (kg -m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`), :math:`q_{snwcp,\, ice}` is the +m\ :sup:`-2` s\ :sup:`-1`), :math:`q_{snwcp,\, ice}` is the ice runoff associated with snow-capping (below), :math:`E_{g}` is the ground evaporation (section 9.4.3), and :math:`n_{levsoi}` is the number of hydrologically active soil layers (as opposed to dry bedrock @@ -1092,7 +1087,7 @@ treated as over other land units, except that the allowed evaporation from the ground is unlimited (though the top snow layer cannot lose more water mass than it contains). If there are no resolved snow layers but :math:`W_{sno} >0` and :math:`E_{g} >0`, sublimation -:math:`q_{sub,sno}` \ (kg m\ :math:`{}^{-2}` s\ :math:`{}^{-1}`) will be +:math:`q_{sub,sno}` \ (kg m\ :sup:`-2` s\ :sup:`-1`) will be given by .. math:: @@ -1121,7 +1116,7 @@ Snow Hydrology submodel (section 7.2). Otherwise, the snow ice mass is updated directly, and :math:`z_{sno}` is adjusted by the same proportion as the snow ice (i.e., maintaining the same density), unless there was no snow before adding the frost, in which case the density is -assumed to be 250 kg m\ :math:`{}^{-3}`. +assumed to be 250 kg m\ :sup:`-3`. Soil Hydrology ^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst new file mode 100644 index 0000000000..6adf6f9db7 --- /dev/null +++ b/doc/source/tech_note/index.rst @@ -0,0 +1,43 @@ +.. on documentation master file, created by + sphinx-quickstart on Tue Jan 31 19:46:36 2017. + You can adapt this file completely to your liking, but it should at least + contain the root`toctree` directive. + +.. _tech_note: + +##################################### +CLM Technical Note +##################################### + +.. toctree:: + :maxdepth: 2 + :numbered: + + CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst + CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst + CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst + CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst + CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst + CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst + CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst + CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst + CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst + CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst + CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst + CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst + CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst + CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst + CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst + CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst + CHAPTER_17/CLM45_Tech_Note_Chpt_17_Plant_Mortality.rst + CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst + CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst + CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst + CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst + CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst + CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst + CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst + CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst + CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst + CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst + diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index 6ad113adc5..7d4408bcc8 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -1,7 +1,7 @@ .. _scientific-validiation: ======================== - Scientific Validiation + Scientific Validation ======================== In this section we go over what has been extensively tested and scientifically validated with CLM4.5, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of CLM, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. From d910ae506c43b1b3ba84cb43e0ce3ef72cdf224a Mon Sep 17 00:00:00 2001 From: mvertens Date: Tue, 28 Mar 2017 11:19:41 -0600 Subject: [PATCH 004/255] added all the html for the tech_note --- .../CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst | 3 +-- .../CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst | 10 +++++----- .../CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst | 9 +++++---- .../CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst b/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst index afffe5fec1..c455e50387 100644 --- a/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst +++ b/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst @@ -235,8 +235,7 @@ The fire spread rate in the downwind direction is represented as u_{p} =u_{\max } C_{m} g(W) - (Arora and Boer, 2005), where :math:`u_{\max }` (m -s\ :sup:`-1`) is the PFT-dependent average maximum fire spread +(Arora and Boer, 2005), where :math:`u_{\max }` (m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread rate in natural vegetation regions; :math:`C_{m}` and :math:`g(W)` represent the dependence of :math:`u_{p}` on fuel wetness and wind speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.55 m diff --git a/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst b/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst index e4320a9933..da7150bda6 100644 --- a/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst +++ b/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst @@ -678,15 +678,15 @@ Table 3.4. Spectral bands and weights used for snow radiative transfer +---------------------------------------------------------+----------------------+------------------+ | Spectral band | Direct-beam weight | Diffuse weight | +=========================================================+======================+==================+ -| Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | | | +| Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | | | +---------------------------------------------------------+----------------------+------------------+ -| Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | +| Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | +---------------------------------------------------------+----------------------+------------------+ -| Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.181 | 0.202 | +| Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.181 | 0.202 | +---------------------------------------------------------+----------------------+------------------+ -| Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.121 | 0.109 | +| Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.121 | 0.109 | +---------------------------------------------------------+----------------------+------------------+ -| Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.204 | 0.103 | +| Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.204 | 0.103 | +---------------------------------------------------------+----------------------+------------------+ Under direct-beam conditions, singularities in the radiative diff --git a/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst b/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst index 20ed6594d2..48fe2dd742 100644 --- a/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst +++ b/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst @@ -1730,7 +1730,8 @@ where s_{N_{levsoi} +1} =0.5\left(\frac{\theta _{sat,\, N_{levsoi} } +\theta _{N_{levsoi} } }{\theta _{sat,\, N_{levsoi} } } \right)\qquad 0.01\le s_{N_{levsoi} +1} \le 1, - :math:`\psi _{E,\, N_{levsoi} +1}` is evaluated from equations and , +:math:`\psi _{E,\, N_{levsoi} +1}` is evaluated from equations and , + and .. math:: @@ -1914,7 +1915,7 @@ in water stored in the unconfined aquifer :math:`W_{a}` (mm) is updated as .. math:: - :label: 7.174) + :label: 7.174a) \Delta W_{a}^{} =\left(q_{recharge} -q_{drai} \right)\Delta t @@ -1924,7 +1925,7 @@ layer :math:`N_{levsoi}` . The recharge rate is defined as positive when water enters the aquifer .. math:: - :label: 7.174) + :label: 7.174b) q_{recharge} =\frac{\Delta \theta _{liq,\, N_{levsoi} +1} \Delta z_{N_{levsoi} +1} }{\Delta t} @@ -1935,7 +1936,7 @@ calculated from the solution of the soil water equations (section 7.4), and :math:`\Delta z_{N_{levsoi} +1}` (mm) is .. math:: - :label: 7.174) + :label: 7.174c) \Delta z_{N_{levsoi} +1} =z_{\nabla }^{n} -z_{h,\, N_{levsoi} } . diff --git a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst b/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst index 900f8873a9..40cff9b8d8 100644 --- a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst +++ b/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst @@ -501,7 +501,7 @@ system is discretized into *N* layers, where N=n_{sno} +N_{levlak} +N_{levgrnd} , - :math:`n_{sno}` is the number of actively modeled snow layers at the +:math:`n_{sno}` is the number of actively modeled snow layers at the current timestep (section 7.2), and :math:`N_{levgrnd}` \ is as for vegetated land units (Chapter 6). Energy is conserved as From 428ad361d85f027c76b8246e457dbec4d54c248f Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 31 Mar 2017 11:57:40 -0600 Subject: [PATCH 005/255] Fixed some latex errors --- .../CLM45_Tech_Note_Chpt_11_RTM.rst | 18 ++++++------- .../CLM45_Tech_Note_Chpt_12_Urban.rst | 2 +- .../CLM45_Tech_Note_Chpt_18_Fire.rst | 27 +++++++++---------- .../CLM45_Tech_Note_Chpt_25_Isotopes.rst | 2 +- .../CLM45_Tech_Note_Chpt_27_References.rst | 2 +- .../CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst | 2 +- .../customizing-the-clm-configuration.rst | 8 +++--- 7 files changed, 30 insertions(+), 31 deletions(-) diff --git a/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst b/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst index 032589055f..fd0702da94 100644 --- a/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst +++ b/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst @@ -23,7 +23,7 @@ cell to its downstream neighboring grid cell. The change in storage cell (m\ :sup:`3` s\ :sup:`-1`) is .. math:: - :label: ZEqnNum723341 + :label: 11.1) \frac{dS}{dt} =\sum F_{in} -F_{out} +R @@ -55,7 +55,7 @@ and channel roughness data are not available globally, so a simplified effective flow velocity expression is used in RTM .. math:: - :label: 11.2) + :label: 11.3) v=\max \left(0.05,k\beta ^{1/2} \right) @@ -66,14 +66,14 @@ The distance :math:`d` between two grid cell centers depends on river direction, latitude, and longitude as .. math:: - :label: 11.3) + :label: 11.4) d=\sqrt{\Delta x^{2} +\Delta y^{2} } . The distance in the zonal direction :math:`\Delta x` (m) is .. math:: - :label: 11.4) + :label: 11.5) \Delta x=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right)\left[0.5\left(\cos \phi _{i,\, j} +\cos \phi _{i*,\, j*} \right)\right] @@ -86,7 +86,7 @@ are grid cell indices. The distance in the meridional direction :math:`\Delta y` (m) is .. math:: - :label: 11.5) + :label: 11.6) \Delta y=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right). @@ -97,7 +97,7 @@ total liquid water runoff at the land model resolution (kg m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 11.6) + :label: 11.7) R_{liq} =q_{over} +q_{drai} +q_{rgwl} @@ -108,14 +108,14 @@ where :math:`q_{over}` is surface runoff (section 7.3), 9.6.3). The total ice water runoff, also at the land model resolution is .. math:: - :label: 11.7) + :label: 11.8) R_{ice} =q_{snwcp,ice} where :math:`q_{snwcp,ice}` is the ice runoff from snow-capped surfaces (section 7.7). The runoff at the land model resolution is interpolated to the resolution of RTM and converted to units of -m\ :sup:`3` s\ :sup:`-1` for use in equation by multiplying +m\ :sup:`3` s\ :sup:`-1` for use in equation (11.1) by multiplying by :math:`1\times 10^{-3} A` where :math:`A` is the area (m\ :sup:`2`) of the RTM grid cell. @@ -132,7 +132,7 @@ as a diagnostic tool. The river-routing scheme conserves water globally as .. math:: - :label: 11.8) + :label: 11.9) \sum _{i,\, j}\left(\frac{dS}{dt} \right) _{i,\, j} =\sum _{i,\, j}R_{i,\, j} . diff --git a/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst b/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst index 7e78b328d2..b5415474b1 100644 --- a/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst +++ b/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst @@ -112,7 +112,7 @@ but are not shown for clarity. Figure 12.2. Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind -(:math:`u_{atm}` ), temperature (**:math:`T_{atm}` **), specific +(:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height diff --git a/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst b/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst index c455e50387..df1842bde1 100644 --- a/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst +++ b/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst @@ -27,7 +27,7 @@ where :math:`N_{f}` (count (time step)\ :sup:`-1`) is fire counts in the grid cell; :math:`a` (km:sup:`2`) is average fire spread area of a fire. -18.1.1 Fire counts +Fire counts ^^^^^^^^^^^^^^^^^^ Fire counts :math:`N_{f}` is taken as @@ -176,10 +176,10 @@ influence on fire occurrence for tree PFTs as f_{e} =\left\{\begin{array}{cc} {0.39,} & {GDP\ge 20} \\ {1} & {GDP<20} \end{array}\right. to reproduce that the MODIS fire counts in tree-dominated regions of -GDP\ :math:`\ge 20` k 1995US$ capita\ :sup:`-1` is 39% of that in -other **** tree-dominated regions. +GDP (:math:`\ge 20` k 1995US$ capita\ :sup:`-1` is 39% of that in +other tree-dominated regions. -18.1.2 Average spread area of a fire +Average spread area of a fire ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Fire fighting capacity depends on socioeconomic conditions and affects @@ -235,7 +235,7 @@ The fire spread rate in the downwind direction is represented as u_{p} =u_{\max } C_{m} g(W) -(Arora and Boer, 2005), where :math:`u_{\max }` (m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread +(Arora and Boer, 2005), where :math:`u_{\max }`\ (m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread rate in natural vegetation regions; :math:`C_{m}` and :math:`g(W)` represent the dependence of :math:`u_{p}` on fuel wetness and wind speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.55 m @@ -319,7 +319,7 @@ and Eqs. - reflect that more developed and more densely populated regions have a higher fire fighting capability. -18.1.3 Fire impact +Fire impact ^^^^^^^^^^^^^^^^^^ In post-fire regions, we calculate PFT-level fire carbon emissions from @@ -328,25 +328,25 @@ the *j*\ th PFT, :math:`{\phi}_{j}` (g C (time step)\ :sup:`-1`, as .. math:: :label: 18.26) - \phi _{j} =A_{b,} _{j} C_{j} \bullet CC_{j} + \phi _{j} =A_{b,j} C_{j} \bullet CC_{j} where :math:`A_{b,j}` (km\ :sup:`2`\ (time step)\ :sup:`-1`) is burned area for the *j*\ th PFT; **C**\ :sub:`j` =(*C*\ :sub:`leaf`, *C*\ :sub:`stem`, *C*\ :sub:`root`, *C*\ :sub:`ts`) is a vector with carbon density (g C km\ :sup:`-2`) for leaf, stem (live and dead stem), root (fine, live coarse and dead coarse root), and transfer and storage carbon pools -as elements; **CC**\ :sub:`j` = (*CC*\ :sub:`leaf`, *CC*\ :sub:`stem`, *CC*\ :sub:`root`, *CC*\ sub:`ts`) is the corresponding combustion +as elements; **CC**\ :sub:`j` = (*CC*\ :sub:`leaf`, *CC*\ :sub:`stem`, *CC*\ :sub:`root`, *CC*\ :sub:`ts`) is the corresponding combustion completeness factor vector (Table 18.1). Moreover, we assume that 30% and 20% of column-level litter and coarse woody debris are burned and the corresponding carbon is transferred to atmosphere. Tissue mortality due to fire leads to carbon transfers in two ways. First, carbon from uncombusted leaf, live stem, dead stem, root, and transfer and storage pools -:math:`C^{'} _{j1} =(C_{{\rm leaf}} (1-CC_{{\rm leaf}} ),C_{{\rm livestem}} (1-CC_{{\rm stem}} ),C_{{\rm deadstem}} (1-CC_{{\rm stem}} ),C_{{\rm root}} (1-CC_{{\rm root}} ),C_{{\rm ts}} (1-CC_{{\rm ts}} ))_{j}` +:math:`C^{'} _{j1} =(C_{{\rm leaf}} (1-CC_{{\rm leaf}} ) ,C_{{\rm livestem}} (1-CC_{{\rm stem}} ) ,C_{{\rm deadstem}} (1-CC_{{\rm stem}} ),C_{{\rm root}} (1-CC_{{\rm root}} ),C_{{\rm ts}} (1-CC_{{\rm ts}} )) _{j}` (g C km\ :sup:`-2`) is transferred to litter as .. math:: :label: 18.27) - \Psi _{j1} =\frac{A_{b,} _{j} }{f_{j} A_{g} } C^{'} _{j1} \bullet M_{j1} + \Psi _{j1} =\frac{A_{b,j} }{f_{j} A_{g} } C^{'} _{j1} \bullet M_{j1} where :math:`M_{j1} =(M_{{\rm leaf}} ,M_{{\rm livestem,1}} ,M_{{\rm deadstem}} ,M_{{\rm root}} ,M_{{\rm ts}} )_{j}` @@ -356,7 +356,7 @@ carbon from uncombusted live stems is transferred to dead stems as: .. math:: :label: 18.28) - \Psi _{j2} =\frac{A_{b,} _{j} }{f_{j} A_{g} } C_{livestem} (1-CC_{stem} )M_{livestem,2} + \Psi _{j2} =\frac{A_{b,j} }{f_{j} A_{g} } C_{livestem} (1-CC_{stem} )M_{livestem,2} where :math:`M_{livestem,2}` is the corresponding mortality factor (Table 18.1). @@ -371,7 +371,7 @@ killed by fire per km\ :sup:`2` (individual km\ :sup:`-2` .. math:: :label: 18.29) - P_{disturb,} _{j} =\frac{A_{b,} _{j} }{f_{j} A_{g} } P_{j} \xi _{j} + P_{disturb,j} =\frac{A_{b,j} }{f_{j} A_{g} } P_{j} \xi _{j} where :math:`P_{j}` (individual km\ :sup:`-2`) is the population density for the *j*\ th tree PFT and :math:`\xi _{j}` is the @@ -545,8 +545,7 @@ CLM4.5 version driven by Qian et al. (2006) atmospheric forcing and climatological lightning data to earlier studies: about 2.4 Mha peatland was burned over Indonesia in 1997 (Page et al. 2002) and the average burned area of peat fires in Western Canada was 0.2 Mha -yr\ :sup:`-1` for 1980\ :math:`\math{-}`\ 1999 (Turestky et al. -2004). +yr\ :sup:`-1` for 1980-1999 (Turestky et al. 2004). For tropical peat fires, :math:`f_{cli,p}` is set as a function of long-term precipitation :math:`P_{60d}` : diff --git a/doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst b/doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst index 024b447962..2138ab143a 100644 --- a/doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst +++ b/doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst @@ -93,7 +93,7 @@ This can also be expressed using epsilon notation (:math:`\epsilon`), where \alpha _{A-B} =\frac{\varepsilon _{A-B} }{1000} +1 -In other words, if :math:`{\epsilon }_{A-B} = 4.4{\mathrm{‰}}`, then :math:`{\alpha}_{A-B} =1.0044`. +In other words, if :math:`{\epsilon }_{A-B} = 4.4` ‰ , then :math:`{\alpha}_{A-B} =1.0044`. In addition to the stable isotopes :sup:`1`\ :sup:`2`\ C and :sup:`1`\ :sup:`3`\ C, the unstable isotope :sup:`1`\ :sup:`4`\ C is included in CLM. :sup:`1`\ :sup:`4`\ C can also be described using the delta notation: diff --git a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst index 5b73e1a70a..9a63855c9c 100644 --- a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst +++ b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst @@ -1247,7 +1247,7 @@ Statistics Division. Vallano, D.M. and Sparks, J.P. 2007. Quantifying foliar uptake of gaseous itrogen dioxide using enriched foliar -:math:`\deltaup`\ :math:`{}^{15 }`\ N values. New Phytologist +:math:`\delta^{15}`\ N values. New Phytologist 177:946-955. van der Werf, G.R., Randerson, J.T., Giglio, L., Collatz, G.J., Mu, M., diff --git a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst b/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst index 40cff9b8d8..63bf60ba22 100644 --- a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst +++ b/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst @@ -192,7 +192,7 @@ where :math:`\nu _{0} =1.51\times 10^{-5} {\textstyle\frac{{\rm m}^{{\rm 2}} }{{\rm s}}}` , :math:`T_{0} ={\rm 293.15\; K}`, :math:`P_{0} =1.013\times 10^{5} {\rm \; Pa}` , and -:math:`\{P}_{ref}` is the pressure at the atmospheric reference +:math:`P_{ref}` is the pressure at the atmospheric reference height. The Charnock coefficient *C* is a function of the lake fetch *F* (m), given in the surface data or set to 25 times the lake depth *d* by default: diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index ed00d99483..e4cafcf046 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -102,7 +102,7 @@ CLM_NML_USE_CASE glacierMEC_pd = Running an IG case with the ice sheet model glimmer stdurbpt_pd = Standard Urban Point Namelist Settings - .. note::See the `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + .. note::See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. CLM_BLDNML_OPTS The option CLM_BLDNML_OPTS is for passing options to the CLM "build-namelist" script. @@ -343,7 +343,7 @@ When "-irrig" is used **build-namelist** will try to find surface datasets that For a list of the history fields available see `CLM History Fields `_. - .. note: See the `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + .. note::See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. ``CLM_FORCE_COLDSTART`` when set to on, *requires* that your simulation do a cold start from arbitrary initial conditions. If this is NOT set, it will use an initial condition file if it can find an appropriate one, and otherwise do a cold start. ``CLM_FORCE_COLDSTART`` is a good way to ensure that you are doing a cold start if that is what you want to do. @@ -360,7 +360,7 @@ When "-irrig" is used **build-namelist** will try to find surface datasets that An example of using ``CLM_USRDAT_NAME`` for a simulation is given in `Example 5-4 `_. - .. note:: See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + .. note: See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. ``CLM_CO2_TYPE`` sets the type of input CO2 for either "constant", "diagnostic" or prognostic". @@ -421,7 +421,7 @@ Example: user_nl_clm namelist file **Note:** The comments at the top are some guidance given in the default user_nl_clm and just give some guidance on how to set variables and use the file. -**Note:** See the `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. +**Note:** See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. **Note:** You do NOT need to specify the namelist group that the variables are in because the CLM **build-namelist** knows the namelist that specific variable names belong to, and it puts them there. From 5118ba09dafd6cead0ed3be06bd5f664d21cdc08 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Fri, 7 Apr 2017 16:35:03 -0600 Subject: [PATCH 006/255] Testing change to Chapter 1 --- .../tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst b/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst index bb9b012bdc..6c2db760a5 100644 --- a/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst +++ b/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst @@ -4,7 +4,7 @@ **July 2013** -**Technical Description of version 4.5 of the Community Land Model +**Technical Description of version 5.0 of the Community Land Model (CLM)** ***Coordinating Lead Authors*** From 0ec3302fa4be700af496e2ea3fb4f18d22d5d383 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Mon, 10 Apr 2017 10:18:06 -0600 Subject: [PATCH 007/255] Test of Chapter 1 rename --- ...Introduction.rst => CLM50_Tech_Note_Chpt_1_Introduction.rst} | 0 doc/source/tech_note/index.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename doc/source/tech_note/CHAPTER_1/{CLM45_Tech_Note_Chpt_1_Introduction.rst => CLM50_Tech_Note_Chpt_1_Introduction.rst} (100%) diff --git a/doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst b/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst rename to doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index 6adf6f9db7..a6d675ffed 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -13,7 +13,7 @@ CLM Technical Note :maxdepth: 2 :numbered: - CHAPTER_1/CLM45_Tech_Note_Chpt_1_Introduction.rst + CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst From b7a0c619d0f4387d24b1c992f680fa76a055f82b Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Mon, 10 Apr 2017 15:49:20 -0600 Subject: [PATCH 008/255] 3rd Test of Chapter 1 rename --- .../tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst | 2 +- .../tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst b/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst index 6c2db760a5..7074842c5b 100644 --- a/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst +++ b/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst @@ -281,7 +281,7 @@ The purpose of this technical note is to describe the biogeophysical and biogeochemical parameterizations and numerical implementation of version 4.5 of the Community Land Model (CLM4.5). Scientific justification and evaluation of these parameterizations can be found in the referenced -scientific papers (Chapter 27). This technical note and the CLM4.5 +scientific papers (:ref:`rst_References`). This technical note and the CLM4.5 User’s Guide together provide the user with the scientific description and operating instructions for CLM. diff --git a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst index 9a63855c9c..b953d98b3d 100644 --- a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst +++ b/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst @@ -1,3 +1,5 @@ +.. _rst_References: + References ============== From f5e4f1304b0bad4976d34f5c44193996e30956bc Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Mon, 10 Apr 2017 16:15:30 -0600 Subject: [PATCH 009/255] 1st Test of Chapter 2 rename --- ..._Chpt_2_Ecosystem.rst => CLM50_Tech_Note_Chpt_2_Ecosystem.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/source/tech_note/CHAPTER_2/{CLM45_Tech_Note_Chpt_2_Ecosystem.rst => CLM50_Tech_Note_Chpt_2_Ecosystem.rst} (100%) diff --git a/doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst b/doc/source/tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst rename to doc/source/tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst From 00425245d755df802c3195b4929ae7ecb1a2fa75 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Mon, 10 Apr 2017 16:45:31 -0600 Subject: [PATCH 010/255] 2nd Test of Chapter 2 rename --- doc/source/tech_note/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index a6d675ffed..1848b3d8d5 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -14,7 +14,7 @@ CLM Technical Note :numbered: CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst - CHAPTER_2/CLM45_Tech_Note_Chpt_2_Ecosystem.rst + CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst From c81e2d64e67c2fbfa1cd2f736e7551e3e2f00eca Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 11 Apr 2017 09:45:38 -0600 Subject: [PATCH 011/255] Change chapter titles to CLM50 --- ...st => CLM50_Tech_Note_Chpt_10_Glacier.rst} | 0 ...TM.rst => CLM50_Tech_Note_Chpt_11_RTM.rst} | 0 ....rst => CLM50_Tech_Note_Chpt_12_Urban.rst} | 0 ...ote_Chpt_13_CN_Allocation_Respiration.rst} | 0 ...ech_Note_Chpt_14_Vegetation_Phenology.rst} | 0 ...CLM50_Tech_Note_Chpt_15_Decomposition.rst} | 0 ..._Note_Chpt_16_External_Nitrogen_Cycle.rst} | 0 ...M50_Tech_Note_Chpt_17_Plant_Mortality.rst} | 0 ...e.rst => CLM50_Tech_Note_Chpt_18_Fire.rst} | 0 ...st => CLM50_Tech_Note_Chpt_19_Methane.rst} | 0 ...M50_Tech_Note_Chpt_20_Crop_Irrigation.rst} | 0 ...Tech_Note_Chpt_21_Transient_Landcover.rst} | 0 ...M.rst => CLM50_Tech_Note_Chpt_22_DGVM.rst} | 0 ....rst => CLM50_Tech_Note_Chpt_23_BVOCs.rst} | 0 ...t.rst => CLM50_Tech_Note_Chpt_24_Dust.rst} | 0 ...t => CLM50_Tech_Note_Chpt_25_Isotopes.rst} | 0 ...st => CLM50_Tech_Note_Chpt_26_Offline.rst} | 0 ...=> CLM50_Tech_Note_Chpt_27_References.rst} | 0 ...LM50_Tech_Note_Chpt_3_Surface_Albedos.rst} | 0 ...M50_Tech_Note_Chpt_4_Radiative_Fluxes.rst} | 0 ....rst => CLM50_Tech_Note_Chpt_5_Fluxes.rst} | 0 ...ch_Note_Chpt_6_Soil_Snow_Temperatures.rst} | 0 ...t => CLM50_Tech_Note_Chpt_7_Hydrology.rst} | 0 ...CLM50_Tech_Note_Chpt_8_Photosynthesis.rst} | 0 ...ke.rst => CLM50_Tech_Note_Chpt_9_Lake.rst} | 0 doc/source/tech_note/index.rst | 50 +++++++++---------- 26 files changed, 25 insertions(+), 25 deletions(-) rename doc/source/tech_note/CHAPTER_10/{CLM45_Tech_Note_Chpt_10_Glacier.rst => CLM50_Tech_Note_Chpt_10_Glacier.rst} (100%) rename doc/source/tech_note/CHAPTER_11/{CLM45_Tech_Note_Chpt_11_RTM.rst => CLM50_Tech_Note_Chpt_11_RTM.rst} (100%) rename doc/source/tech_note/CHAPTER_12/{CLM45_Tech_Note_Chpt_12_Urban.rst => CLM50_Tech_Note_Chpt_12_Urban.rst} (100%) rename doc/source/tech_note/CHAPTER_13/{CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst => CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst} (100%) rename doc/source/tech_note/CHAPTER_14/{CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst => CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst} (100%) rename doc/source/tech_note/CHAPTER_15/{CLM45_Tech_Note_Chpt_15_Decomposition.rst => CLM50_Tech_Note_Chpt_15_Decomposition.rst} (100%) rename doc/source/tech_note/CHAPTER_16/{CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst => CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst} (100%) rename doc/source/tech_note/CHAPTER_17/{CLM45_Tech_Note_Chpt_17_Plant_Mortality.rst => CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst} (100%) rename doc/source/tech_note/CHAPTER_18/{CLM45_Tech_Note_Chpt_18_Fire.rst => CLM50_Tech_Note_Chpt_18_Fire.rst} (100%) rename doc/source/tech_note/CHAPTER_19/{CLM45_Tech_Note_Chpt_19_Methane.rst => CLM50_Tech_Note_Chpt_19_Methane.rst} (100%) rename doc/source/tech_note/CHAPTER_20/{CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst => CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst} (100%) rename doc/source/tech_note/CHAPTER_21/{CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst => CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst} (100%) rename doc/source/tech_note/CHAPTER_22/{CLM45_Tech_Note_Chpt_22_DGVM.rst => CLM50_Tech_Note_Chpt_22_DGVM.rst} (100%) rename doc/source/tech_note/CHAPTER_23/{CLM45_Tech_Note_Chpt_23_BVOCs.rst => CLM50_Tech_Note_Chpt_23_BVOCs.rst} (100%) rename doc/source/tech_note/CHAPTER_24/{CLM45_Tech_Note_Chpt_24_Dust.rst => CLM50_Tech_Note_Chpt_24_Dust.rst} (100%) rename doc/source/tech_note/CHAPTER_25/{CLM45_Tech_Note_Chpt_25_Isotopes.rst => CLM50_Tech_Note_Chpt_25_Isotopes.rst} (100%) rename doc/source/tech_note/CHAPTER_26/{CLM45_Tech_Note_Chpt_26_Offline.rst => CLM50_Tech_Note_Chpt_26_Offline.rst} (100%) rename doc/source/tech_note/CHAPTER_27/{CLM45_Tech_Note_Chpt_27_References.rst => CLM50_Tech_Note_Chpt_27_References.rst} (100%) rename doc/source/tech_note/CHAPTER_3/{CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst => CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst} (100%) rename doc/source/tech_note/CHAPTER_4/{CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst => CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst} (100%) rename doc/source/tech_note/CHAPTER_5/{CLM45_Tech_Note_Chpt_5_Fluxes.rst => CLM50_Tech_Note_Chpt_5_Fluxes.rst} (100%) rename doc/source/tech_note/CHAPTER_6/{CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst => CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst} (100%) rename doc/source/tech_note/CHAPTER_7/{CLM45_Tech_Note_Chpt_7_Hydrology.rst => CLM50_Tech_Note_Chpt_7_Hydrology.rst} (100%) rename doc/source/tech_note/CHAPTER_8/{CLM45_Tech_Note_Chpt_8_Photosynthesis.rst => CLM50_Tech_Note_Chpt_8_Photosynthesis.rst} (100%) rename doc/source/tech_note/CHAPTER_9/{CLM45_Tech_Note_Chpt_9_Lake.rst => CLM50_Tech_Note_Chpt_9_Lake.rst} (100%) diff --git a/doc/source/tech_note/CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst b/doc/source/tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst rename to doc/source/tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst diff --git a/doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst b/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst rename to doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst diff --git a/doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst b/doc/source/tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst rename to doc/source/tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst diff --git a/doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst b/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst rename to doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst diff --git a/doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst b/doc/source/tech_note/CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst rename to doc/source/tech_note/CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst diff --git a/doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst b/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst rename to doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst diff --git a/doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst b/doc/source/tech_note/CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst rename to doc/source/tech_note/CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst diff --git a/doc/source/tech_note/CHAPTER_17/CLM45_Tech_Note_Chpt_17_Plant_Mortality.rst b/doc/source/tech_note/CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_17/CLM45_Tech_Note_Chpt_17_Plant_Mortality.rst rename to doc/source/tech_note/CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst diff --git a/doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst b/doc/source/tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst rename to doc/source/tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst diff --git a/doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst b/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst rename to doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst diff --git a/doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst b/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst rename to doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst diff --git a/doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst b/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst rename to doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst diff --git a/doc/source/tech_note/CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst b/doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst rename to doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst diff --git a/doc/source/tech_note/CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst b/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst rename to doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst diff --git a/doc/source/tech_note/CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst b/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst rename to doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst diff --git a/doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst b/doc/source/tech_note/CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst rename to doc/source/tech_note/CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst diff --git a/doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst b/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst rename to doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst diff --git a/doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst b/doc/source/tech_note/CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst rename to doc/source/tech_note/CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst diff --git a/doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst b/doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst rename to doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst diff --git a/doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst b/doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst rename to doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst diff --git a/doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst b/doc/source/tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst rename to doc/source/tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst diff --git a/doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst b/doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst rename to doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst diff --git a/doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst b/doc/source/tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst rename to doc/source/tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst diff --git a/doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst b/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst rename to doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst diff --git a/doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst b/doc/source/tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst rename to doc/source/tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index 1848b3d8d5..4141a560bc 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -15,29 +15,29 @@ CLM Technical Note CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst - CHAPTER_3/CLM45_Tech_Note_Chpt_3_Surface_Albedos.rst - CHAPTER_4/CLM45_Tech_Note_Chpt_4_Radiative_Fluxes.rst - CHAPTER_5/CLM45_Tech_Note_Chpt_5_Fluxes.rst - CHAPTER_6/CLM45_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst - CHAPTER_7/CLM45_Tech_Note_Chpt_7_Hydrology.rst - CHAPTER_8/CLM45_Tech_Note_Chpt_8_Photosynthesis.rst - CHAPTER_9/CLM45_Tech_Note_Chpt_9_Lake.rst - CHAPTER_10/CLM45_Tech_Note_Chpt_10_Glacier.rst - CHAPTER_11/CLM45_Tech_Note_Chpt_11_RTM.rst - CHAPTER_12/CLM45_Tech_Note_Chpt_12_Urban.rst - CHAPTER_13/CLM45_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst - CHAPTER_14/CLM45_Tech_Note_Chpt_14_Vegetation_Phenology.rst - CHAPTER_15/CLM45_Tech_Note_Chpt_15_Decomposition.rst - CHAPTER_16/CLM45_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst - CHAPTER_17/CLM45_Tech_Note_Chpt_17_Plant_Mortality.rst - CHAPTER_18/CLM45_Tech_Note_Chpt_18_Fire.rst - CHAPTER_19/CLM45_Tech_Note_Chpt_19_Methane.rst - CHAPTER_20/CLM45_Tech_Note_Chpt_20_Crop_Irrigation.rst - CHAPTER_21/CLM45_Tech_Note_Chpt_21_Transient_Landcover.rst - CHAPTER_22/CLM45_Tech_Note_Chpt_22_DGVM.rst - CHAPTER_23/CLM45_Tech_Note_Chpt_23_BVOCs.rst - CHAPTER_24/CLM45_Tech_Note_Chpt_24_Dust.rst - CHAPTER_25/CLM45_Tech_Note_Chpt_25_Isotopes.rst - CHAPTER_26/CLM45_Tech_Note_Chpt_26_Offline.rst - CHAPTER_27/CLM45_Tech_Note_Chpt_27_References.rst + CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst + CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst + CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst + CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst + CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst + CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst + CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst + CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst + CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst + CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst + CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst + CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst + CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst + CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst + CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst + CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst + CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst + CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst + CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst + CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst + CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst + CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst + CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst + CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst + CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst From 5f3c4fa68feb3b8f588c2d442962de72d5c5a556 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 11 Apr 2017 11:46:31 -0600 Subject: [PATCH 012/255] Add links to chapters --- .../CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst | 5 +++-- .../tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst | 2 ++ .../tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst | 2 ++ .../tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst | 2 ++ .../CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst | 2 ++ .../CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst | 2 ++ .../CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst | 2 ++ .../CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst | 2 ++ .../CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst | 2 ++ .../tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst | 2 ++ .../tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst | 2 ++ .../tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst | 1 + .../CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst | 2 ++ .../CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst | 2 ++ .../tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst | 2 ++ .../tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst | 2 ++ .../tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst | 2 ++ .../CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst | 2 ++ .../tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst | 2 ++ .../CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst | 2 ++ .../CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst | 2 ++ .../tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst | 2 ++ .../CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst | 2 ++ .../tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst | 2 ++ .../CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst | 2 ++ .../tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst | 2 ++ 26 files changed, 52 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst b/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst index 7074842c5b..2a5ba1d3ae 100644 --- a/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst +++ b/doc/source/tech_note/CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst @@ -273,8 +273,9 @@ National Laboratory); A. Bozbiyik (Bern University); C. Heald National Laboratory); Ying Sun and Z.-L. Yang (University of Texas at Austin) -================= - 1. Introduction +.. _rst_Introduction: + +Introduction ================= The purpose of this technical note is to describe the biogeophysical and diff --git a/doc/source/tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst b/doc/source/tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst index 9bd3e1e11d..6ba68086db 100644 --- a/doc/source/tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst +++ b/doc/source/tech_note/CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst @@ -1,3 +1,5 @@ +.. _rst_Glaciers: + Glaciers ============ diff --git a/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst b/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst index fd0702da94..9568b91b16 100644 --- a/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst +++ b/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst @@ -1,3 +1,5 @@ +.. _rst_River Transport Model (RTM): + River Transport Model (RTM) =============================== diff --git a/doc/source/tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst b/doc/source/tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst index b5415474b1..b95589f7b4 100644 --- a/doc/source/tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst +++ b/doc/source/tech_note/CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst @@ -1,3 +1,5 @@ +.. _rst_Urban Model (CLMU): + Urban Model (CLMU) ====================== diff --git a/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst b/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst index a4173834b5..4512d906c4 100644 --- a/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst +++ b/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst @@ -1,3 +1,5 @@ +.. _rst_Carbon and Nitrogen Pools, Allocation, and Respiration: + Carbon and Nitrogen Pools, Allocation, and Respiration ========================================================== diff --git a/doc/source/tech_note/CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst b/doc/source/tech_note/CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst index 305e532552..df022465a8 100644 --- a/doc/source/tech_note/CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst +++ b/doc/source/tech_note/CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst @@ -1,3 +1,5 @@ +.. _rst_Vegetation Phenology: + Vegetation Phenology ======================== diff --git a/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst b/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst index 89e12a7b94..34a71b2b24 100644 --- a/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst +++ b/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst @@ -1,3 +1,5 @@ +.. _rst_Decomposition: + Decomposition ================= diff --git a/doc/source/tech_note/CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst b/doc/source/tech_note/CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst index 07bb1567f9..20d76e38ad 100644 --- a/doc/source/tech_note/CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst @@ -1,3 +1,5 @@ +.. _rst_External Nitrogen Cycle: + External Nitrogen Cycle =========================== diff --git a/doc/source/tech_note/CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst b/doc/source/tech_note/CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst index 348c0a3649..ba880609bf 100644 --- a/doc/source/tech_note/CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst +++ b/doc/source/tech_note/CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst @@ -1,3 +1,5 @@ +.. _rst_Plant Mortality: + Plant Mortality =================== diff --git a/doc/source/tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst b/doc/source/tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst index df1842bde1..f2236018f6 100644 --- a/doc/source/tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst +++ b/doc/source/tech_note/CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst @@ -1,3 +1,5 @@ +.. _rst_Fire: + Fire ======== diff --git a/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst b/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst index 7bdea2fefb..fc71c600dd 100644 --- a/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst +++ b/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst @@ -1,3 +1,5 @@ +.. _rst_Methane Model: + Methane Model ================= diff --git a/doc/source/tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst b/doc/source/tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst index d19fdd3f5d..888c379382 100644 --- a/doc/source/tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst +++ b/doc/source/tech_note/CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst @@ -1,3 +1,4 @@ +.. _rst_Surface Characterization and Model Input Requirements: Surface Characterization and Model Input Requirements ======================================================== diff --git a/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst b/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst index 570028bc8b..9d2aeb71f4 100644 --- a/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst +++ b/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst @@ -1,3 +1,5 @@ +.. _rst_Crops and Irrigation: + Crops and Irrigation ======================== diff --git a/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst b/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst index 661b1f2e6e..d967dae888 100644 --- a/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst +++ b/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst @@ -1,3 +1,5 @@ +.. _rst_Transient Landcover Change: + Transient Landcover Change ============================== diff --git a/doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst b/doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst index 0ee97d23e3..4a7d378379 100644 --- a/doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst +++ b/doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst @@ -1,3 +1,5 @@ +.. _rst_Dynamic Global Vegetation Model: + Dynamic Global Vegetation Model =================================== diff --git a/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst b/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst index f5f23f8644..bd8259e57c 100644 --- a/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst +++ b/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst @@ -1,3 +1,5 @@ +.. _rst_Biogenic Volatile Organic Compounds (BVOCs): + Biogenic Volatile Organic Compounds (BVOCs) =============================================== diff --git a/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst b/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst index 92dcefad3e..8126f09774 100644 --- a/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst +++ b/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst @@ -1,3 +1,5 @@ +.. _rst_Dust Model: + Dust Model ============== diff --git a/doc/source/tech_note/CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst b/doc/source/tech_note/CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst index 2138ab143a..acb4cf595d 100644 --- a/doc/source/tech_note/CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst +++ b/doc/source/tech_note/CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst @@ -1,3 +1,5 @@ +.. _rst_Carbon Isotopes: + Carbon Isotopes =================== diff --git a/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst b/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst index c6a78b34d9..db2b04d5cf 100644 --- a/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst +++ b/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst @@ -1,3 +1,5 @@ +.. _rst_Offline Mode: + Offline Mode ================ diff --git a/doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst b/doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst index da7150bda6..039691c090 100644 --- a/doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst +++ b/doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst @@ -1,3 +1,5 @@ +.. _rst_Surface Albedos: + Surface Albedos ================== diff --git a/doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst b/doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst index 64506d1032..741801942d 100644 --- a/doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst +++ b/doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst @@ -1,3 +1,5 @@ +.. _rst_Radiative Fluxes: + Radiative Fluxes =================== diff --git a/doc/source/tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst b/doc/source/tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst index 81c25ee0e8..2d2eb57337 100644 --- a/doc/source/tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst +++ b/doc/source/tech_note/CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst @@ -1,3 +1,5 @@ +.. _rst_Momentum, Sensible Heat, and Latent Heat Fluxes: + Momentum, Sensible Heat, and Latent Heat Fluxes ================================================== diff --git a/doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst b/doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst index 83dc1e3579..002aac2b0d 100644 --- a/doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst @@ -1,3 +1,5 @@ +.. _rst_Soil and Snow Temperatures: + Soil and Snow Temperatures ============================= diff --git a/doc/source/tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst b/doc/source/tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst index 48fe2dd742..59751de56c 100644 --- a/doc/source/tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst +++ b/doc/source/tech_note/CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst @@ -1,3 +1,5 @@ +.. _rst_Hydrology: + Hydrology ============ diff --git a/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst b/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst index 6cd61d641c..c380f0d75a 100644 --- a/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst +++ b/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst @@ -1,3 +1,5 @@ +.. _rst_Stomatal Resistance and Photosynthesis: + Stomatal Resistance and Photosynthesis ========================================= diff --git a/doc/source/tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst b/doc/source/tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst index 63bf60ba22..1356ca27a9 100644 --- a/doc/source/tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst +++ b/doc/source/tech_note/CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst @@ -1,3 +1,5 @@ +.. _rst_Lake Model: + Lake Model ============= From 8efdfff444c171833356f3702b701b1a61f83ea8 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Wed, 12 Apr 2017 08:00:40 -0600 Subject: [PATCH 013/255] Rename chapters --- .../CLM50_Tech_Note_BVOCs.rst} | 2 +- .../CLM50_Tech_Note_CN_Allocation.rst} | 98 +-- .../CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 4 + .../CLM50_Tech_Note_Crop_Irrigation.rst} | 24 +- .../CLM50_Tech_Note_DGVM.rst} | 0 .../CLM50_Tech_Note_Decomposition.rst} | 114 ++-- .../CLM50_Tech_Note_Dust.rst} | 20 +- .../CLM50_Tech_Note_Ecosystem.rst} | 0 ...M50_Tech_Note_External_Nitrogen_Cycle.rst} | 36 +- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 4 + .../CLM50_Tech_Note_Fire.rst} | 64 +- .../CLM50_Tech_Note_Fluxes.rst} | 0 .../CLM50_Tech_Note_Glacier.rst} | 0 .../CLM50_Tech_Note_Hydrology.rst} | 0 .../CLM50_Tech_Note_Introduction.rst} | 0 .../CLM50_Tech_Note_Isotopes.rst} | 20 +- .../CLM50_Tech_Note_Lake.rst} | 84 +-- .../CLM50_Tech_Note_Methane.rst} | 26 +- .../CLM50_Tech_Note_Offline.rst} | 26 +- .../CLM50_Tech_Note_Photosynthesis.rst} | 58 +- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 4 + ...CLM50_Tech_Note_Plant_Hydraulic_Stress.rst | 4 + .../CLM50_Tech_Note_Plant_Mortality.rst} | 172 ++--- .../CLM50_Tech_Note_Plant_Respiration.rst | 601 ++++++++++++++++++ .../CLM50_Tech_Note_RTM.rst} | 18 +- .../CLM50_Tech_Note_Radiative_Fluxes.rst} | 0 .../CLM50_Tech_Note_References.rst} | 0 .../CLM50_Tech_Note_Snow_Hydrology.rst | 4 + ...LM50_Tech_Note_Soil_Snow_Temperatures.rst} | 0 .../CLM50_Tech_Note_Surface_Albedos.rst} | 0 .../CLM50_Tech_Note_Transient_Landcover.rst} | 14 +- .../CLM50_Tech_Note_Urban.rst} | 0 ...ch_Note_Vegetation_Phenology_Turnover.rst} | 184 +++--- doc/source/tech_note/index.rst | 59 +- 34 files changed, 1133 insertions(+), 507 deletions(-) rename doc/source/tech_note/{CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst => BVOCs/CLM50_Tech_Note_BVOCs.rst} (99%) rename doc/source/tech_note/{CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst => CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst} (96%) create mode 100644 doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst rename doc/source/tech_note/{CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst => Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst} (99%) rename doc/source/tech_note/{CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst => DGVM/CLM50_Tech_Note_DGVM.rst} (100%) rename doc/source/tech_note/{CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst => Decomposition/CLM50_Tech_Note_Decomposition.rst} (97%) rename doc/source/tech_note/{CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst => Dust/CLM50_Tech_Note_Dust.rst} (98%) rename doc/source/tech_note/{CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst => Ecosystem/CLM50_Tech_Note_Ecosystem.rst} (100%) rename doc/source/tech_note/{CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst => External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst} (98%) create mode 100644 doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst rename doc/source/tech_note/{CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst => Fire/CLM50_Tech_Note_Fire.rst} (98%) rename doc/source/tech_note/{CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst => Fluxes/CLM50_Tech_Note_Fluxes.rst} (100%) rename doc/source/tech_note/{CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst => Glacier/CLM50_Tech_Note_Glacier.rst} (100%) rename doc/source/tech_note/{CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst => Hydrology/CLM50_Tech_Note_Hydrology.rst} (100%) rename doc/source/tech_note/{CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst => Introduction/CLM50_Tech_Note_Introduction.rst} (100%) rename doc/source/tech_note/{CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst => Isotopes/CLM50_Tech_Note_Isotopes.rst} (98%) rename doc/source/tech_note/{CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst => Lake/CLM50_Tech_Note_Lake.rst} (98%) rename doc/source/tech_note/{CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst => Methane/CLM50_Tech_Note_Methane.rst} (99%) rename doc/source/tech_note/{CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst => Offline/CLM50_Tech_Note_Offline.rst} (97%) rename doc/source/tech_note/{CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst => Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst} (98%) create mode 100644 doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst create mode 100644 doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst rename doc/source/tech_note/{CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst => Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst} (86%) create mode 100644 doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst rename doc/source/tech_note/{CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst => RTM/CLM50_Tech_Note_RTM.rst} (97%) rename doc/source/tech_note/{CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst => Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst} (100%) rename doc/source/tech_note/{CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst => References/CLM50_Tech_Note_References.rst} (100%) create mode 100644 doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst rename doc/source/tech_note/{CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst => Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst} (100%) rename doc/source/tech_note/{CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst => Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst} (100%) rename doc/source/tech_note/{CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst => Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst} (99%) rename doc/source/tech_note/{CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst => Urban/CLM50_Tech_Note_Urban.rst} (100%) rename doc/source/tech_note/{CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst => Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst} (94%) diff --git a/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst b/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst similarity index 99% rename from doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst rename to doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst index bd8259e57c..8c5737f171 100644 --- a/doc/source/tech_note/CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst +++ b/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst @@ -50,7 +50,7 @@ some monoterpenes, VOCs and acetone). The activity factor for the light response of emissions is therefore estimated as: .. math:: - :label: 23.2) + :label: 28.2) \gamma _{P,\, i} =\left(1-LDF_{i} \right)+\gamma _{P\_ LDF} LDF_{i} diff --git a/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst similarity index 96% rename from doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst rename to doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 4512d906c4..c6a6fa4aa0 100644 --- a/doc/source/tech_note/CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -1,7 +1,7 @@ -.. _rst_Carbon and Nitrogen Pools, Allocation, and Respiration: +.. _rst_CN Allocation: -Carbon and Nitrogen Pools, Allocation, and Respiration -========================================================== +Carbon and Nitrogen Allocation +============================== Introduction ----------------- @@ -76,17 +76,17 @@ photosynthesis ( :math:`CF_{xs,mr}`, gC m\ :sup:`-2` s\ :sup:`-1`): .. math:: - :label: 13.1) + :label: 19.1) CF_{mr} =CF_{GPP,mr} +CF_{xs,mr} .. math:: - :label: 13.2) + :label: 19.2) CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. .. math:: - :label: 13.3) + :label: 19.3) CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{mr} -CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. @@ -110,12 +110,12 @@ flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC m\ :sup:`-2` s\ :sup:`-1`) is given as .. math:: - :label: 13.4) + :label: 19.4) CF_{GPP,xs,pot} =\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CS_{xs} \ge 0} \\ {-CS_{xs} /(86400\tau _{xs} )\qquad {\rm for\; }CS_{xs} <0} \end{array}\right. .. math:: - :label: 13.5) + :label: 19.5) CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPPpot} -CF_{GPP,mr} } \\ {\max (CF_{GPPpot} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPPpot} -CF_{GPP,mr} } \end{array}\right. @@ -136,7 +136,7 @@ remaining carbon flux from photosynthesis which can be allocated to new growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 13.6) + :label: 19.6) CF_{avail\_ alloc} =CF_{GPPpot} -CF_{GPP,mr} -CF_{GPP,xs} . @@ -162,7 +162,7 @@ ratio for carbon allocation between new stem and new leaf increases with increasing net primary production (NPP), as .. math:: - :label: 13.8) + :label: 19.8) a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 @@ -252,12 +252,12 @@ m\ :sup:`-2` s\ :sup:`-1`): where .. math:: - :label: 13.11) + :label: 19.11) \begin{array}{l} {C_{allom} =\left\{\begin{array}{l} {\left(1+g_{1} \right)\left(1+a_{1} +a_{3} \left(1+a_{2} \right)\right)\qquad {\rm for\; woody\; PFT}} \\ {1+g_{1} +a_{1} \left(1+g_{1} \right)\qquad \qquad {\rm for\; non-woody\; PFT}} \end{array}\right. } \\ {} \end{array} .. math:: - :label: 13.12) + :label: 19.12) N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. @@ -268,7 +268,7 @@ plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`) as: .. math:: - :label: 13.13) + :label: 19.13) NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . @@ -287,7 +287,7 @@ availability of nitrogen from this pool to support new growth s\ :sup:`-1`) is proportional to the plant nitrogen demand, as: .. math:: - :label: 13.14) + :label: 19.14) NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) @@ -313,7 +313,7 @@ m\ :sup:`-2` s\ :sup:`-1`) is never greater than the plant demand for new nitrogen: .. math:: - :label: 13.15) + :label: 19.15) NF_{retrans,alloc} =\min \left(NF_{plant\_ demand} ,NF_{avail\_ retrans} \right) @@ -340,7 +340,7 @@ mineral nitrogen supply and competition with heterotrophs. Plant uptake from the soil mineral nitrogen pool is then given as: .. math:: - :label: 13.17) + :label: 19.17) NF_{sminn,alloc} =NF_{plant\_ demand\_ soil} f_{plant\_ demand} @@ -350,7 +350,7 @@ Final carbon and nitrogen allocation The total flux of allocated nitrogen is given as: .. math:: - :label: 13.18) + :label: 19.18) NF_{alloc} =NF_{retrans,alloc} +NF_{sminn,alloc} @@ -358,14 +358,14 @@ From the stoichiometric relationship in Eq. , the associated carbon allocation flux is: .. math:: - :label: 13.19) + :label: 19.19) CF_{alloc} =NF_{alloc} \frac{C_{allom} }{N_{allom} } . The downregulation of photosynthesis can then be calculated as: .. math:: - :label: 13.20) + :label: 19.20) f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . @@ -373,7 +373,7 @@ Total allocation to new leaf carbon (:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as: .. math:: - :label: 13.21) + :label: 19.21) CF_{alloc,leaf\_ tot} =\frac{CF_{alloc} }{C_{allom} } . @@ -389,124 +389,124 @@ storage pools (where storage is indicated with *\_stor*) for the various tissue types are given as: .. math:: - :label: 13.22) + :label: 19.22) CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} .. math:: - :label: 13.23) + :label: 19.23) CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) .. math:: - :label: 13.24) + :label: 19.24) CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} .. math:: - :label: 13.25) + :label: 19.25) CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) .. math:: - :label: 13.26) + :label: 19.26) CF_{alloc,livestem} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} f_{cur} .. math:: - :label: 13.27) + :label: 19.27) CF_{alloc,livestem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} \left(1-f_{cur} \right) .. math:: - :label: 13.28) + :label: 19.28) CF_{alloc,deadstem} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)f_{cur} .. math:: - :label: 13.29) + :label: 19.29) CF_{alloc,deadstem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right) .. math:: - :label: 13.30) + :label: 19.30) CF_{alloc,livecroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} f_{cur} .. math:: - :label: 13.31) + :label: 19.31) CF_{alloc,livecroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} \left(1-f_{cur} \right) .. math:: - :label: 13.32) + :label: 19.32) CF_{alloc,deadcroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)f_{cur} .. math:: - :label: 13.33) + :label: 19.33) CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). The corresponding nitrogen allocation fluxes are given as: .. math:: - :label: 13.34) + :label: 19.34) NF_{alloc,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} .. math:: - :label: 13.35) + :label: 19.35) NF_{alloc,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) .. math:: - :label: 13.36) + :label: 19.36) NF_{alloc,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} .. math:: - :label: 13.37) + :label: 19.37) NF_{alloc,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) .. math:: - :label: 13.38) + :label: 19.38) NF_{alloc,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: - :label: 13.39) + :label: 19.39) NF_{alloc,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: - :label: 13.40) + :label: 19.40) NF_{alloc,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: - :label: 13.41) + :label: 19.41) NF_{alloc,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) .. math:: - :label: 13.42) + :label: 19.42) NF_{alloc,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: - :label: 13.43) + :label: 19.43) NF_{alloc,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: - :label: 13.44) + :label: 19.44) NF_{alloc,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: - :label: 13.45) + :label: 19.45) NF_{alloc,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). @@ -530,22 +530,22 @@ functions tissue nitrogen content and the relevant temperature, following the empirical relationship reported by Ryan (1991): .. math:: - :label: 13.46) + :label: 19.46) CF_{mr\_ leaf} \_ =NS_{leaf} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} .. math:: - :label: 13.47) + :label: 19.47) CF_{mr\_ livestem} \_ =NS_{livestem} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} .. math:: - :label: 13.48) + :label: 19.48) CF_{mr\_ livecroot} \_ =NS_{livecroot} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} .. math:: - :label: 13.49) + :label: 19.49) CF_{mr\_ froot} \_ =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} @@ -568,7 +568,7 @@ common base maintenance respiration rate for all live tissue types. The total maintenance respiration cost is then given as: .. math:: - :label: 13.50) + :label: 19.50) CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst new file mode 100644 index 0000000000..92903f02e0 --- /dev/null +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -0,0 +1,4 @@ +.. _rst_CN Pools: + +CN Pools +=================== diff --git a/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst similarity index 99% rename from doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst rename to doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 9d2aeb71f4..80cd1e3527 100644 --- a/doc/source/tech_note/CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -155,7 +155,7 @@ for the crop to reach vegetative and physiological maturity, :math:`{GDD}_{mat}`, according to the following AgroIBIS rules: .. math:: - :label: 20.2) + :label: 25.2) \begin{array}{l} {GDD_{{\rm mat}}^{{\rm corn}} =0.85GDD_{{\rm 8}} {\rm \; \; \; and\; \; \; 950}30} \end{array}\right\} .. math:: - :label: 20.13) + :label: 25.13) fxg=\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad \qquad {\rm for\; }GDD_{T_{2m} } \le 0.15} \\ {6.67\times GDD_{T_{2m} } -1\qquad \qquad \qquad {\rm for\; }0.150.75} \end{array}\right\} @@ -646,17 +646,17 @@ mobilized depends on the C:N ratio of the plant tissue, and is calculated as .. math:: - :label: 20.14) + :label: 25.14) leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } .. math:: - :label: 20.15) + :label: 25.15) stemn\_ to\_ retransn=\frac{c_{stem} }{CN_{stem} } -\frac{c_{stem} }{CN_{stem}^{f} } .. math:: - :label: 20.16) + :label: 25.16) frootn\_ to\_ retransn=\frac{c_{froot} }{CN_{froot} } -\frac{c_{froot} }{CN_{froot}^{f} } diff --git a/doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst rename to doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst diff --git a/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst similarity index 97% rename from doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst rename to doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 34a71b2b24..4686f649c2 100644 --- a/doc/source/tech_note/CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -29,7 +29,7 @@ For the single-level model structure, the fundamental equation for carbon balance of the decomposing pools is: .. math:: - :label: 15.1) + :label: 21.1) \frac{\partial C_{i} }{\partial t} =R_{i} +\sum _{j\ne i}\left(i-r_{j} \right)T_{ji} k_{j} C_{j} -k_{i} C_{i} @@ -44,7 +44,7 @@ Adding the vertical dimension to the decomposing pools changes the balance equation to the following: .. math:: - :label: 15.2) + :label: 21.2) \begin{array}{l} {\frac{\partial C_{i} (z)}{\partial t} =R_{i} (z)+\sum _{i\ne j}\left(1-r_{j} \right)T_{ji} k_{j} (z)C_{j} (z) -k_{i} (z)C_{i} (z)} \\ {+\frac{\partial }{\partial z} \left(D(z)\frac{\partial C_{i} }{\partial z} \right)+\frac{\partial }{\partial z} \left(A(z)C_{i} \right)} \end{array} @@ -245,7 +245,7 @@ The Temperature scalar :math:`{r}_{tsoil}` is calculated in CLM using a :math:`{Q}_{10}` approach, with :math:`{Q}_{10} = 1.5`. .. math:: - :label: 15.5) + :label: 21.5) r_{tsoil} =Q_{10} ^{\left(\frac{T_{soil,\, j} -T_{ref} }{10} \right)} @@ -257,7 +257,7 @@ unitless) is calculated using a relationship from Andrén and Paustian (1987) and supported by additional data in Orchard and Cook (1983): .. math:: - :label: 15.6) + :label: 21.6) r_{water} =\sum _{j=1}^{5}\left\{\begin{array}{l} {0\qquad {\rm for\; }\Psi _{j} <\Psi _{\min } } \\ {\frac{\log \left({\Psi _{\min } \mathord{\left/ {\vphantom {\Psi _{\min } \Psi _{j} }} \right. \kern-\nulldelimiterspace} \Psi _{j} } \right)}{\log \left({\Psi _{\min } \mathord{\left/ {\vphantom {\Psi _{\min } \Psi _{\max } }} \right. \kern-\nulldelimiterspace} \Psi _{\max } } \right)} w_{soil,\, j} \qquad {\rm for\; }\Psi _{\min } \le \Psi _{j} \le \Psi _{\max } } \\ {1\qquad {\rm for\; }\Psi _{j} >\Psi _{\max } \qquad \qquad } \end{array}\right\} @@ -268,7 +268,7 @@ water potential control on decomposition rate (set to -10 MPa). potential, calculated using the multivariate regression model from Cosby et al. (1984): .. math:: - :label: 15.7) + :label: 21.7) \Psi _{sat,\, j} =-\left(9.8e-5\right)\exp \left(\left(1.54-0.0095P_{sand,\, j} +0.0063\left(100-P_{sand,\, j} -P_{clay,\, j} \right)\right)\log \left(10\right)\right) @@ -281,7 +281,7 @@ potential is limited by temperature in the supercooled water formulation of Niu and Yang (2006), .. math:: - :label: 15.8) + :label: 21.8) \psi \left(T\right)=-\frac{L_{f} \left(T-T_{f} \right)}{10^{3} T} @@ -319,7 +319,7 @@ includes these unresolved depth controls via an exponential decrease in the soil turnover time with depth: .. math:: - :label: 15.9) + :label: 21.9) r_{depth} =\exp \left(-\frac{z}{z_{\tau } } \right) @@ -328,7 +328,7 @@ where :math:`{z}_{\tau}` is the e-folding depth for decomposition, set by defaul The combined decomposition rate scalar (:math:`{r}_{total}`,unitless) is: .. math:: - :label: 15.10) + :label: 21.10) r_{total} =r_{tsoil} r_{water} r_{oxygen} r_{depth} . @@ -345,7 +345,7 @@ The potential carbon flux out of the upstream pool (:math:`{CF}_{pot,u}`, gC m\ :sup:`-2` s\ :sup:`-1`) is: .. math:: - :label: 15.11) + :label: 21.11) CF_{pot,\, u} =CS_{u} k_{u} @@ -361,7 +361,7 @@ mineral nitrogen (Thornton and Rosenbloom, 2005) is: .. math:: - :label: 15.12) + :label: 21.12) NF_{pot\_ min,\, u\to d} =\frac{CF_{pot,\, u} \left(1-rf_{u} -\frac{CN_{d} }{CN_{u} } \right)}{CN_{d} } @@ -379,37 +379,37 @@ individual pools in the decomposition cascade, for the example of the CLM-CN pool structure, are given as: .. math:: - :label: 15.13) + :label: 21.13) CF_{pot,\, Lit1} ={CS_{Lit1} k_{Lit1} r_{total} \mathord{\left/ {\vphantom {CS_{Lit1} k_{Lit1} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: - :label: 15.14) + :label: 21.14) CF_{pot,\, Lit2} ={CS_{Lit2} k_{Lit2} r_{total} \mathord{\left/ {\vphantom {CS_{Lit2} k_{Lit2} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: - :label: 15.15) + :label: 21.15) CF_{pot,\, Lit3} ={CS_{Lit3} k_{Lit3} r_{total} \mathord{\left/ {\vphantom {CS_{Lit3} k_{Lit3} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: - :label: 15.16) + :label: 21.16) CF_{pot,\, SOM1} ={CS_{SOM1} k_{SOM1} r_{total} \mathord{\left/ {\vphantom {CS_{SOM1} k_{SOM1} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: - :label: 15.17) + :label: 21.17) CF_{pot,\, SOM2} ={CS_{SOM2} k_{SOM2} r_{total} \mathord{\left/ {\vphantom {CS_{SOM2} k_{SOM2} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: - :label: 15.18) + :label: 21.18) CF_{pot,\, SOM3} ={CS_{SOM3} k_{SOM3} r_{total} \mathord{\left/ {\vphantom {CS_{SOM3} k_{SOM3} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} .. math:: - :label: 15.19) + :label: 21.19) CF_{pot,\, SOM4} ={CS_{SOM4} k_{SOM4} r_{total} \mathord{\left/ {\vphantom {CS_{SOM4} k_{SOM4} r_{total} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} @@ -426,27 +426,27 @@ structure will be similar but without the different terminal step): NF_{pot\_ min,\, Lit1\to SOM1} ={CF_{pot,\, Lit1} \left(1-rf_{Lit1} -\frac{CN_{SOM1} }{CN_{Lit1} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit1} \left(1-rf_{Lit1} -\frac{CN_{SOM1} }{CN_{Lit1} } \right) CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } .. math:: - :label: 15.21) + :label: 21.21) NF_{pot\_ min,\, Lit2\to SOM2} ={CF_{pot,\, Lit2} \left(1-rf_{Lit2} -\frac{CN_{SOM2} }{CN_{Lit2} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit2} \left(1-rf_{Lit2} -\frac{CN_{SOM2} }{CN_{Lit2} } \right) CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: - :label: 15.22) + :label: 21.22) NF_{pot\_ min,\, Lit3\to SOM3} ={CF_{pot,\, Lit3} \left(1-rf_{Lit3} -\frac{CN_{SOM3} }{CN_{Lit3} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, Lit3} \left(1-rf_{Lit3} -\frac{CN_{SOM3} }{CN_{Lit3} } \right) CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } .. math:: - :label: 15.23) + :label: 21.23) NF_{pot\_ min,\, SOM1\to SOM2} ={CF_{pot,\, SOM1} \left(1-rf_{SOM1} -\frac{CN_{SOM2} }{CN_{SOM1} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM1} \left(1-rf_{SOM1} -\frac{CN_{SOM2} }{CN_{SOM1} } \right) CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: - :label: 15.24) + :label: 21.24) NF_{pot\_ min,\, SOM2\to SOM3} ={CF_{pot,\, SOM2} \left(1-rf_{SOM2} -\frac{CN_{SOM3} }{CN_{SOM2} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM2} \left(1-rf_{SOM2} -\frac{CN_{SOM3} }{CN_{SOM2} } \right) CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } .. math:: - :label: 15.25) + :label: 21.25) NF_{pot\_ min,\, SOM3\to SOM4} ={CF_{pot,\, SOM3} \left(1-rf_{SOM3} -\frac{CN_{SOM4} }{CN_{SOM3} } \right)\mathord{\left/ {\vphantom {CF_{pot,\, SOM3} \left(1-rf_{SOM3} -\frac{CN_{SOM4} }{CN_{SOM3} } \right) CN_{SOM4} }} \right. \kern-\nulldelimiterspace} CN_{SOM4} } @@ -487,7 +487,7 @@ beginning of the timestep is considered the available supply. Total demand for mineral nitrogen from this pool (:math:`{NF}_{total\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`) is: .. math:: - :label: 15.27) + :label: 21.27) NF_{total\_ demand} =NF_{immob\_ demand} +NF_{plant\_ demand\_ soil} @@ -511,7 +511,7 @@ lower-than-potential rates, defined by the fractions where: .. math:: - :label: 15.28) + :label: 21.28) f_{plant\_ demand} =f_{immob\_ demand} =\frac{NS_{sminn} }{\Delta t\, NF_{total\_ demand} } @@ -532,37 +532,37 @@ CENTURY structure will be similar but, again without the different terminal step), are calculated as: .. math:: - :label: 15.29) + :label: 21.29) CF_{Lit1} =\left\{\begin{array}{l} {CF_{pot,\, Lit1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {CF_{pot,\, Lit1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} .. math:: - :label: 15.30) + :label: 21.30) CF_{Lit2} =\left\{\begin{array}{l} {CF_{pot,\, Lit2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {CF_{pot,\, Lit2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 15.31) + :label: 21.31) CF_{Lit3} =\left\{\begin{array}{l} {CF_{pot,\, Lit3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {CF_{pot,\, Lit3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 15.32) + :label: 21.32) CF_{SOM1} =\left\{\begin{array}{l} {CF_{pot,\, SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {CF_{pot,\, SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 15.33) + :label: 21.33) CF_{SOM2} =\left\{\begin{array}{l} {CF_{pot,\, SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {CF_{pot,\, SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 15.34) + :label: 21.34) CF_{SOM3} =\left\{\begin{array}{l} {CF_{pot,\, SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {CF_{pot,\, SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} .. math:: - :label: 15.35) + :label: 21.35) CF_{SOM4} =CF_{pot,\, SOM4} @@ -570,37 +570,37 @@ Heterotrophic respiration fluxes (losses of carbon as CO\ :sub:`2` to the atmosphere) are: .. math:: - :label: 15.36) + :label: 21.36) CF_{Lit1,\, HR} =CF_{Lit1} rf_{Lit1} .. math:: - :label: 15.37) + :label: 21.37) CF_{Lit2,\, HR} =CF_{Lit2} rf_{Lit2} .. math:: - :label: 15.38) + :label: 21.38) CF_{Lit3,\, HR} =CF_{Lit3} rf_{Lit3} .. math:: - :label: 15.39) + :label: 21.39) CF_{SOM1,\, HR} =CF_{SOM1} rf_{SOM1} .. math:: - :label: 15.40) + :label: 21.40) CF_{SOM2,\, HR} =CF_{SOM2} rf_{SOM2} .. math:: - :label: 15.41) + :label: 21.41) CF_{SOM3,\, HR} =CF_{SOM3} rf_{SOM3} .. math:: - :label: 15.42) + :label: 21.42) CF_{SOM4,\, HR} =CF_{SOM4} rf_{SOM4} @@ -608,32 +608,32 @@ Transfers of carbon from upstream to downstream pools in the decomposition cascade are given as: .. math:: - :label: 15.43) + :label: 21.43) CF_{Lit1,\, SOM1} =CF_{Lit1} \left(1-rf_{Lit1} \right) .. math:: - :label: 15.44) + :label: 21.44) CF_{Lit2,\, SOM2} =CF_{Lit2} \left(1-rf_{Lit2} \right) .. math:: - :label: 15.45) + :label: 21.45) CF_{Lit3,\, SOM3} =CF_{Lit3} \left(1-rf_{Lit3} \right) .. math:: - :label: 15.46) + :label: 21.46) CF_{SOM1,\, SOM2} =CF_{SOM1} \left(1-rf_{SOM1} \right) .. math:: - :label: 15.47) + :label: 21.47) CF_{SOM2,\, SOM3} =CF_{SOM2} \left(1-rf_{SOM2} \right) .. math:: - :label: 15.48) + :label: 21.48) CF_{SOM3,\, SOM4} =CF_{SOM3} \left(1-rf_{SOM3} \right) @@ -647,32 +647,32 @@ or from the downstream pool to the soil mineral nitrogen pool pools in the decomposition cascade are given as: .. math:: - :label: 15.49) + :label: 21.49) NF_{Lit1,\, SOM1} ={CF_{Lit1} \mathord{\left/ {\vphantom {CF_{Lit1} CN_{Lit1} }} \right. \kern-\nulldelimiterspace} CN_{Lit1} } .. math:: - :label: 15.50) + :label: 21.50) NF_{Lit2,\, SOM2} ={CF_{Lit2} \mathord{\left/ {\vphantom {CF_{Lit2} CN_{Lit2} }} \right. \kern-\nulldelimiterspace} CN_{Lit2} } .. math:: - :label: 15.51) + :label: 21.51) NF_{Lit3,\, SOM3} ={CF_{Lit3} \mathord{\left/ {\vphantom {CF_{Lit3} CN_{Lit3} }} \right. \kern-\nulldelimiterspace} CN_{Lit3} } .. math:: - :label: 15.52) + :label: 21.52) NF_{SOM1,\, SOM2} ={CF_{SOM1} \mathord{\left/ {\vphantom {CF_{SOM1} CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } .. math:: - :label: 15.53) + :label: 21.53) NF_{SOM2,\, SOM3} ={CF_{SOM2} \mathord{\left/ {\vphantom {CF_{SOM2} CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: - :label: 15.54) + :label: 21.54) NF_{SOM3,\, SOM4} ={CF_{SOM3} \mathord{\left/ {\vphantom {CF_{SOM3} CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } @@ -681,37 +681,37 @@ whether the decomposition step is an immobilization flux or a mineralization flux: .. math:: - :label: 15.55) + :label: 21.55) NF_{sminn,\, Lit1\to SOM1} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit1\to SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {NF_{pot\_ min,\, Lit1\to SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} .. math:: - :label: 15.56) + :label: 21.56) NF_{sminn,\, Lit2\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit2\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {NF_{pot\_ min,\, Lit2\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 15.57) + :label: 21.57) NF_{sminn,\, Lit3\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit3\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {NF_{pot\_ min,\, Lit3\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 15.58) + :label: 21.58) NF_{sminn,SOM1\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM1\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {NF_{pot\_ min,\, SOM1\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 15.59) + :label: 21.59) NF_{sminn,SOM2\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM2\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {NF_{pot\_ min,\, SOM2\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 15.60) + :label: 21.60) NF_{sminn,SOM3\to SOM4} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM3\to SOM4} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {NF_{pot\_ min,\, SOM3\to SOM4} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} .. math:: - :label: 15.61) + :label: 21.61) NF_{sminn,\, SOM4} =NF_{pot\_ min,\, SOM4} diff --git a/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst similarity index 98% rename from doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst rename to doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst index 8126f09774..381367a4c0 100644 --- a/doc/source/tech_note/CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst +++ b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst @@ -30,7 +30,7 @@ The grid cell fraction of exposed bare soil suitable for dust mobilization :math:`f_{m}` is given by .. math:: - :label: 24.2) + :label: 29.2) f_{m} =\left(1-f_{lake} -f_{wetl} \right)\left(1-f_{sno} \right)\left(1-f_{v} \right)\frac{w_{liq,1} }{w_{liq,1} +w_{ice,1} } @@ -62,7 +62,7 @@ The sandblasting mass efficiency :math:`\alpha` (m:sup:`-1`) is calculated as .. math:: - :label: 24.4) + :label: 29.4) \alpha =100e^{\left(13.4M_{clay} -6.0\right)\ln 10} {\rm \; \; }\left\{\begin{array}{l} {M_{clay} =\% clay\times 0.01{\rm \; \; \; 0}\le \% clay\le 20} \\ {M_{clay} =20\times 0.01{\rm \; \; \; \; \; \; \; \; 20<\% }clay\le 100} \end{array}\right. @@ -98,21 +98,21 @@ diameter (75 x 10\ :math:`{}^{-6}` m) of optimal saltation particles, and :math:`f_{w}` is a factor dependent on soil moisture: .. math:: - :label: 24.7) + :label: 29.7) f_{w} =\left\{\begin{array}{l} {1{\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }w\le w_{t} } \\ {\sqrt{1+1.21\left[100\left(w-w_{t} \right)\right]^{0.68} } {\rm \; \; for\; }w>w_{t} } \end{array}\right. where .. math:: - :label: 24.8) + :label: 29.8) w_{t} =a\left(0.17M_{clay} +0.14M_{clay}^{2} \right){\rm \; \; \; \; \; \; 0}\le M_{clay} =\% clay\times 0.01\le 1 and .. math:: - :label: 24.9) + :label: 29.9) w=\frac{\theta _{1} \rho _{liq} }{\rho _{d,1} } @@ -127,7 +127,7 @@ in section 6.3 rather than as in Zender et al. (2003). factor .. math:: - :label: 24.10) + :label: 29.10) Re_{*t}^{f} =\left\{\begin{array}{l} {\frac{0.1291^{2} }{-1+1.928Re_{*t} } {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; 0.03}\le Re_{*t} \le 10} \\ {0.12^{2} \left(1-0.0858e^{-0.0617(Re_{*t} -10)} \right)^{2} {\rm \; for\; }Re_{*t} >10} \end{array}\right. @@ -135,7 +135,7 @@ and :math:`Re_{*t}` is the threshold friction Reynolds number approximation for optimally sized particles .. math:: - :label: 24.11) + :label: 29.11) Re_{*t} =0.38+1331\left(100D_{osp} \right)^{1.56} @@ -143,7 +143,7 @@ In equation , :math:`u_{*s}` ** is defined as the wind friction speed (m s\ :sup:`-1`) accounting for the Owen effect (Owen 1964) .. math:: - :label: 24.12) + :label: 29.12) u_{\*s} =\left\{\begin{array}{l} {u_{\*} {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }U_{10} 0} \\ {-NF_{pot\_ min,Lit1\to SOM1} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} \le 0} \end{array}\right. .. math:: - :label: 16.3) + :label: 22.3) NF_{denit,Lit2\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} >0} \\ {-NF_{pot\_ min,Lit2\to SOM2} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} \le 0} \end{array}\right. .. math:: - :label: 16.4) + :label: 22.4) NF_{denit,Lit3\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} >0} \\ {-NF_{pot\_ min,Lit3\to SOM3} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} \le 0} \end{array}\right. .. math:: - :label: 16.5) + :label: 22.5) NF_{denit,SOM1\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} >0} \\ {-NF_{pot\_ min,SOM1\to SOM2} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} \le 0} \end{array}\right. .. math:: - :label: 16.6) + :label: 22.6) NF_{denit,SOM2\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} >0} \\ {-NF_{pot\_ min,SOM2\to SOM3} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} \le 0} \end{array}\right. .. math:: - :label: 16.7) + :label: 22.7) NF_{denit,SOM3\to SOM4} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} >0} \\ {-NF_{pot\_ min,SOM3\to SOM4} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} \le 0} \end{array}\right. .. math:: - :label: 16.8) + :label: 22.8) NF_{denit,SOM4} =-NF_{pot\_ min,SOM4} @@ -214,7 +214,7 @@ pool. The denitrification of excess soil mineral nitrogen is non-zero whenever the supply of mineral nitrogen exceeds the demand: .. math:: - :label: 16.9) + :label: 22.9) NF_{sminn,denit} =\left\{\begin{array}{l} {\left(\frac{NS_{sminn} }{\Delta t} \right)-NF_{total\_ demand} f_{dnx} \qquad {\rm for\; }NF_{total\_ demand} \Delta tT_{f} } \\ {0\qquad T_{g} \le T_{f} } \end{array}\right\} @@ -617,7 +617,7 @@ s\ :sup:`-1`) (eq. ) is used to evaluate :math:`w^{*}` and The CityplaceRichardson number is .. math:: - :label: 9.32) + :label: 12.32) R_{i} =\frac{-1+\sqrt{1+\frac{40N^{2} k^{2} z_{i}^{2} }{w^{*^{2} } \exp \left(-2k^{*} z_{i} \right)} } }{20} @@ -638,7 +638,7 @@ Bartlein (1990)), eq. contains no negative sign; this is a correction from CLM4. The density of water is (Hostetler and Bartlein 1990) .. math:: - :label: 9.34) + :label: 12.34) \rho _{i} =1000\left(1-1.9549\times 10^{-5} \left|T_{i} -277\right|^{1.68} \right). @@ -658,7 +658,7 @@ The thermal conductivity for the liquid water portion of lake body layer given by .. math:: - :label: 9.36) + :label: 12.36) \tau _{liq,i} =K_{W} c_{liq} \rho _{liq} . @@ -667,7 +667,7 @@ The thermal conductivity of the ice portion of lake body layer *i*, constant among layers, and is given by .. math:: - :label: 9.37) + :label: 12.37) \tau _{ice,eff} =\tau _{ice} \frac{\rho _{ice} }{\rho _{liq} } @@ -682,7 +682,7 @@ and water fractions, assuming that they will be physically vertically stacked, and is given by .. math:: - :label: 9.38) + :label: 12.38) \tau _{i} =\frac{\tau _{ice,eff} \tau _{liq,i} }{\tau _{liq,i} I_{i} +\tau _{ice} \left(1-I_{i} \right)} . @@ -715,7 +715,7 @@ For unfrozen lakes, the solar radiation remaining at depth :math:`z>z_{a}` in the lake body is given by .. math:: - :label: 9.39) + :label: 12.39) \phi =\left(1-\beta \vec{S}_{g} \right)\exp \left\{-\eta \left(z-z_{a} \right)\right\} . @@ -723,7 +723,7 @@ For all lake body layers, the flux absorbed by the layer *i*, :math:`\phi _{i}` , is .. math:: - :label: 9.40) + :label: 12.40) \phi _{i} =\left(1-\beta \vec{S}_{g} \right)\left[\exp \left\{-\eta \left(z_{i} -\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}-\exp \left\{-\eta \left(z_{i} +\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}\right] . @@ -749,7 +749,7 @@ The vertically-integrated heat capacity for each lake layer, water and ice fractions: .. math:: - :label: 9.42) + :label: 12.42) c_{v,i} =\Delta z_{i} \rho _{liq} \left[c_{liq} \left(1-I_{i} \right)+c_{ice} I_{i} \right] . @@ -778,7 +778,7 @@ calculated as the harmonic mean of the conductivities of the neighboring layers: .. math:: - :label: 9.43) + :label: 12.43) \lambda _{i} =\frac{\tau _{i} \tau _{i+1} \left(z_{i+1} -z_{i} \right)}{\tau _{i} \left(z_{i+1} -\hat{z}_{i} \right)+\tau _{i+1} \left(\hat{z}_{i} -z_{i} \right)} , @@ -804,7 +804,7 @@ Eq. is solved using the semi-implicit Crank-Nicholson Method, resulting in a tridiagonal system of equations: .. math:: - :label: 9.45) + :label: 12.45) \begin{array}{l} {r_{i} =a_{i} T_{i-1}^{n+1} +b_{i} T_{i}^{n+1} +cT_{i+1}^{n+1} ,} \\ {a_{i} =-0.5\frac{\Delta t}{c_{v,i} } \frac{\partial F_{i-1} }{\partial T_{i-1}^{n} } ,} \\ {b_{i} =1+0.5\frac{\Delta t}{c_{v,i} } \left(\frac{\partial F_{i-1} }{\partial T_{i-1}^{n} } +\frac{\partial F_{i} }{\partial T_{i}^{n} } \right),} \\ {c_{i} =-0.5\frac{\Delta t}{c_{v,i} } \frac{\partial F_{i} }{\partial T_{i}^{n} } ,} \\ {r_{i} =T_{i}^{n} +0.5\frac{\Delta t}{c_{v,i} } \left(F_{i-1} -F_{i} \right)+\frac{\Delta t}{c_{v,i} } \phi _{i} .} \end{array} @@ -815,7 +815,7 @@ section 9.4.3 (the factor of 2 merely cancels out the Crank-Nicholson :math:`F_{N_{levlak} +N_{levgrnd} } =0`. For all other layers: .. math:: - :label: 9.46) + :label: 12.46) F_{i} =\lambda _{i} \frac{T_{i} ^{n} -T_{i+1}^{n} }{z_{n+1} -z_{n} } . @@ -843,7 +843,7 @@ section 9.5.6. The mass of melt in the layer *M* (kg m\ :sup:`-2`) is given by .. math:: - :label: 9.48) + :label: 12.48) M=\min \left\{M_{ice} ,\frac{Q_{avail} }{H_{fus} } \right\} @@ -874,7 +874,7 @@ If freezing occurs, :math:`Q_{avail}` is again given by but will be negative. The melt :math:`M`, also negative, is given by .. math:: - :label: 9.51) + :label: 12.51) M=\max \left\{-M_{liq} ,\frac{Q_{avail} }{H_{fus} } \right\} @@ -925,14 +925,14 @@ When this occurs, these two lake layers and all those above mix. Total enthalpy *Q* is conserved as .. math:: - :label: 9.52) + :label: 12.52) Q=\sum _{j=1}^{i+1}\Delta z_{j} \rho _{liq} \left(T_{j} -T_{f} \right)\left[\left(1-I_{j} \right)c_{liq} +I_{j} c_{ice} \right] . Once the average ice fraction :math:`I_{av}` is calculated from .. math:: - :label: 9.53) + :label: 12.53) \begin{array}{l} {I_{av} =\frac{\sum _{j=1}^{i+1}I_{j} \Delta z_{j} }{Z_{i+1} } ,} \\ {Z_{i+1} =\sum _{j=1}^{i+1}\Delta z_{j} ,} \end{array} @@ -950,7 +950,7 @@ If :math:`Q > 0`, then :math:`T_{froz} =T_{f}` , and :math:`T_{unfr}` is given by .. math:: - :label: 9.54) + :label: 12.54) T_{unfr} =\frac{Q}{\rho _{liq} Z_{i+1} \left[\left(1-I_{av} \right)c_{liq} \right]} +T_{f} . @@ -958,7 +958,7 @@ If :math:`Q < 0`, then :math:`T_{unfr} =T_{f}` , and :math:`T_{froz}` is given by .. math:: - :label: 9.55) + :label: 12.55) T_{froz} =\frac{Q}{\rho _{liq} Z_{i+1} \left[I_{av} c_{ice} \right]} +T_{f} . @@ -977,7 +977,7 @@ to *i* + 1, the ice fraction and temperature are set as follows, where by the heat capacity of the layer to yield .. math:: - :label: 9.56) + :label: 12.56) T_{j} =\frac{T_{froz} I_{j} c_{ice} +T_{unfr} \left(1-I_{j} \right)c_{liq} }{I_{j} c_{ice} +\left(1-I_{j} \right)c_{liq} } . @@ -991,7 +991,7 @@ re-written to yield the total enthalpy of the lake system (J m\ :sup:`-2`) :math:`H_{tot}` : .. math:: - :label: 9.57) + :label: 12.57) H_{tot} =\sum _{i=j_{top} }^{N_{levlak} +N_{levgrnd} }\left[c_{v,i} \left(T_{i} -T_{f} \right)+M_{liq,i} H_{fus} \right] -W_{sno,bulk} H_{fus} @@ -1004,7 +1004,7 @@ energy flux to yield the error flux :math:`E_{soi}` (W m\ :sup:`-2`): .. math:: - :label: 9.58) + :label: 12.58) E_{soi} =\frac{\Delta H_{tot} }{\Delta t} -G-\sum _{i=j_{top} }^{N_{levlak} +N_{levgrnd} }\phi _{i} @@ -1093,7 +1093,7 @@ water mass than it contains). If there are no resolved snow layers but given by .. math:: - :label: 9.60) + :label: 12.60) q_{sub,sno} =\min \left\{E_{g} ,\frac{W_{sno} }{\Delta t} \right\} . @@ -1109,7 +1109,7 @@ evaporation or dew deposition is balanced by :math:`q_{rgwl}` .) The snowpack is updated for frost and sublimation: .. math:: - :label: 9.61) + :label: 12.61) W_{sno} =W_{sno} +\Delta t\left(q_{frost} -q_{sub,sno} \right) . @@ -1127,7 +1127,7 @@ The combined water and ice soil volume fraction in a soil layer :math:`\theta _{i}` is given by .. math:: - :label: 9.62) + :label: 12.62) \theta _{i} =\frac{1}{\Delta z_{i} } \left(\frac{w_{ice,i} }{\rho _{ice} } +\frac{w_{liq,i} }{\rho _{liq} } \right) . @@ -1136,7 +1136,7 @@ saturation (as may occur when ice melts), then the liquid water mass is adjusted to .. math:: - :label: 9.63) + :label: 12.63) w_{liq,i} =\left(\theta _{sat,i} \Delta z_{i} -\frac{w_{ice,i} }{\rho _{ice} } \right)\rho _{liq} . @@ -1145,7 +1145,7 @@ Otherwise, if excess ice is melting and water in the layer is reset to .. math:: - :label: 9.64) + :label: 12.64) w_{liq,i} = \theta _{sat,i} \rho _{liq} \Delta z_{i} diff --git a/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst similarity index 99% rename from doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst rename to doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index fc71c600dd..6a29802004 100644 --- a/doc/source/tech_note/CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -137,7 +137,7 @@ The factor :math:`f_{pH}` is nominally set to 1, although a static spatial map of *pH* can be used to determine this factor (Dunfield et al. 1993) by applying: .. math:: - :label: 19.3) + :label: 24.3) f_{pH} =10^{-0.2235pH^{2} +2.7727pH-8.6} . @@ -154,7 +154,7 @@ anoxic microsites above the water table, we apply the Arah and Stephen (1998) estimate of anaerobic fraction: .. math:: - :label: 19.4) + :label: 24.4) \varphi =\frac{1}{1+\eta C_{O_{2} } } . @@ -219,7 +219,7 @@ the water table, by first estimating the Henry’s law partitioning coefficient (:math:`k_{h}^{C}` ) by the method described in Wania et al. (2010): .. math:: - :label: 19.5) + :label: 24.5) \log \left(\frac{1}{k_{H} } \right)=\log k_{H}^{s} -\frac{1}{C_{H} } \left(\frac{1}{T} -\frac{1}{T^{s} } \right) @@ -229,7 +229,7 @@ coefficient (:math:`k_{h}^{C}` ) by the method described in Wania et al. (2010): k_{h}^{C} =Tk_{H} R_{g} .. math:: - :label: 19.7) + :label: 24.7) C_{e} =\frac{C_{w} R_{g} T}{\theta _{s} k_{H}^{C} p} @@ -282,7 +282,7 @@ area index *L* (m:sup:`2` m\ :sup:`-2`), as in Wania et al. (2010): .. math:: - :label: 19.9) + :label: 24.9) T=\frac{f_{N} N_{a} L}{0.22} \pi R^{2} . @@ -304,7 +304,7 @@ and the CLM predicted transpiration (:math:`F_{T}` ) for each PFT, assuming that no methane was oxidized inside the plant tissue: .. math:: - :label: 19.10) + :label: 24.10) F_{CH_{4} -T} =\sum _{j}\rho _{r,j} F_{T} C_{CH_{4} ,j} . @@ -316,7 +316,7 @@ kinetics (Arah and Stephen 1998; Segers 1998), dependent on both the gaseous CH\ :sub:`4` and O\ :sub:`2` concentrations: .. math:: - :label: 19.11) + :label: 24.11) R_{oxic} =R_{o,\max } \left[\frac{C_{CH_{4} } }{K_{CH_{4} } +C_{CH_{4} } } \right]\left[\frac{C_{O_{2} } }{K_{O_{2} } +C_{O_{2} } } \right]Q_{10} F_{\vartheta } @@ -429,7 +429,7 @@ aqueous diffusion in the saturated part of the soil column, we applied (Moldrup et al. 2003): .. math:: - :label: 19.14) + :label: 24.14) D_{e} =D_{0} \theta _{s} ^{2} . @@ -508,7 +508,7 @@ gives: Equation is solved with a standard tridiagonal solver, i.e.: .. math:: - :label: 19.17) + :label: 24.17) aC_{j-1}^{n+1} +bC_{j}^{n+1} +cC_{j+1}^{n+1} =r, @@ -533,7 +533,7 @@ soil element above the interface: .. math:: b=\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(K_{H} \frac{D_{p1}^{} }{\Delta x_{p1} } +\frac{D_{m1}^{} }{\Delta x_{m1} } \right)\right] .. math:: - :label: 19.18) + :label: 24.18) r=\frac{R_{j}^{n} }{\Delta t} C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -K_{H} C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] @@ -544,7 +544,7 @@ and the soil element below the interface: .. math:: a=-K_{H} \frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1} } .. math:: - :label: 19.19) + :label: 24.19) r=\frac{R_{j}^{n} }{\Delta t} +C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -K_{H} C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] @@ -567,7 +567,7 @@ grid cell in a simple model based on simulated water table depth (:math:`{z}_{w}`) and surface runoff (:math:`{Q}_{r}` (mm s\ :sup:`-1`)): .. math:: - :label: 19.20) + :label: 24.20) f_{s} =P_{1} e^{{\raise0.7ex\hbox{$ -z_{w} $}\!\mathord{\left/ {\vphantom {-z_{w} p_{2} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ p_{2} $}} } +p_{3} Q_{r} . @@ -585,7 +585,7 @@ seasonal inundation on CH\ :sub:`4` production (see appendix B in Riley et al. (2011a) for a discussion of this simplified expression): .. math:: - :label: 19.21) + :label: 24.21) S=\frac{\beta \left(f-\bar{f}\right)+\bar{f}}{f} ,S\le 1. diff --git a/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst similarity index 97% rename from doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst rename to doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst index db2b04d5cf..7219e7a293 100644 --- a/doc/source/tech_note/CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst +++ b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst @@ -71,22 +71,22 @@ derived from one year’s worth of hourly CAM output from CAM version cam3\_5\_55 as .. math:: - :label: 26.2) + :label: 31.2) S_{atm} \, \downarrow _{vis}^{\mu } =R_{vis} \left(\alpha S_{atm} \right) .. math:: - :label: 26.3) + :label: 31.3) S_{atm} \, \downarrow _{nir}^{\mu } =R_{nir} \left[\left(1-\alpha \right)S_{atm} \right] .. math:: - :label: 26.4) + :label: 31.4) S_{atm} \, \downarrow _{vis} =\left(1-R_{vis} \right)\left(\alpha S_{atm} \right) .. math:: - :label: 26.5) + :label: 31.5) S_{atm} \, \downarrow _{nir} =\left(1-R_{nir} \right)\left[\left(1-\alpha \right)S_{atm} \right]. @@ -94,7 +94,7 @@ where :math:`\alpha` , the ratio of visible to total incident solar radiation, is assumed to be .. math:: - :label: 26.6) + :label: 31.6) \alpha =\frac{S_{atm} \, \downarrow _{vis}^{\mu } +S_{atm} \, \downarrow _{vis}^{} }{S_{atm} } =0.5. @@ -102,14 +102,14 @@ The ratio of direct to total incident radiation in the visible :math:`R_{vis}` is .. math:: - :label: 26.7) + :label: 31.7) R_{vis} =a_{0} +a_{1} \times \alpha S_{atm} +a_{2} \times \left(\alpha S_{atm} \right)^{2} +a_{3} \times \left(\alpha S_{atm} \right)^{3} \qquad 0.01\le R_{vis} \le 0.99 and in the near-infrared :math:`R_{nir}` is .. math:: - :label: 26.8) + :label: 31.8) R_{nir} =b_{0} +b_{1} \times \left(1-\alpha \right)S_{atm} +b_{2} \times \left[\left(1-\alpha \right)S_{atm} \right]^{2} +b_{3} \times \left[\left(1-\alpha \right)S_{atm} \right]^{3} \qquad 0.01\le R_{nir} \le 0.99 @@ -130,14 +130,14 @@ is derived from the atmospheric vapor pressure :math:`e_{atm}` and temperature :math:`T_{atm}` (Idso 1981) as .. math:: - :label: 26.9) + :label: 31.9) L_{atm} \, \downarrow =\left[0.70+5.95\times 10^{-5} \times 0.01e_{atm} \exp \left(\frac{1500}{T_{atm} } \right)\right]\sigma T_{atm}^{4} where .. math:: - :label: 26.10) + :label: 31.10) e_{atm} =\frac{P_{atm} q_{atm} }{0.622+0.378q_{atm} } @@ -152,14 +152,14 @@ snow is q_{rain} =P\left(f_{P} \right), .. math:: - :label: 26.12) + :label: 31.12) q_{snow} =P\left(1-f_{P} \right) where .. math:: - :label: 26.13) + :label: 31.13) f_{P} =0<0.5\left(T_{atm} -T_{f} \right)<1. @@ -174,7 +174,7 @@ user-supplied relative humidity :math:`RH` (%) and derive specific humidity :math:`q_{atm}` (kg kg\ :sup:`-1`) from .. math:: - :label: 26.14) + :label: 31.14) q_{atm} =\frac{0.622e_{atm} }{P_{atm} -0.378e_{atm} } @@ -190,7 +190,7 @@ temperature :math:`T_{dew}` (K) and derive specific humidity :math:`q_{atm}` from .. math:: - :label: 26.15) + :label: 31.15) q_{atm} = \frac{0.622e_{sat}^{T_{dew} } }{P_{atm} -0.378e_{sat}^{T_{dew} } } . diff --git a/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst similarity index 98% rename from doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst rename to doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index c380f0d75a..e48ba34933 100644 --- a/doc/source/tech_note/CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -134,7 +134,7 @@ describe the implementation, modified here. In its simplest form, leaf net photosynthesis after accounting for respiration (:math:`R_{d}` ) is .. math:: - :label: 8.2) + :label: 9.2) A_{n} =\min \left(A_{c} ,A_{j} ,A_{p} \right)-R_{d} . @@ -153,7 +153,7 @@ RuBP (i.e., the light-limited rate) :math:`A_{j}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 8.4) + :label: 9.4) A_{j} =\left\{\begin{array}{l} {\frac{J\left(c_{i} -\Gamma _{\*} \right)}{4c_{i} +8\Gamma _{\*} } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\alpha (4.6\phi )\qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. @@ -193,7 +193,7 @@ photosynthetically active radiation absorbed by the leaf. A common expression is the smaller of the two roots of the equation .. math:: - :label: 8.6) + :label: 9.6) \Theta _{PSII} J^{2} -\left(I_{PSII} +J_{\max } \right)J+I_{PSII} J_{\max } =0 @@ -208,7 +208,7 @@ with 4.6 :math:`\mu`\ mol J\ :sup:`-1`, the light utilized in electron transport is .. math:: - :label: 8.7) + :label: 9.7) I_{PSII} =0.5\Phi _{PSII} (4.6\phi ) @@ -225,7 +225,7 @@ The model uses co-limitation as described by Collatz et al. (1991, smaller root of the equations .. math:: - :label: 8.8) + :label: 9.8) \begin{array}{rcl} {\Theta _{cj} A_{i}^{2} -\left(A_{c} +A_{j} \right)A_{i} +A_{c} A_{j} } & {=} & {0} \\ {\Theta _{ip} A^{2} -\left(A_{i} +A_{p} \right)A+A_{i} A_{p} } & {=} & {0} \end{array} . @@ -259,21 +259,21 @@ respiration rate. The parameters :math:`V_{c\max 25}` , :math:`T_{v}` (K) as: .. math:: - :label: 8.9) + :label: 9.9) \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma _{*} } & {=} & {\Gamma _{*25} \; f\left(T_{v} \right)} \end{array} with .. math:: - :label: 8.10) + :label: 9.10) f\left(T_{v} \right)=\; \exp \left[\frac{\Delta H_{a} }{298.15\times 0.001R_{gas} } \left(1-\frac{298.15}{T_{v} } \right)\right] and .. math:: - :label: 8.11) + :label: 9.11) f_{H} \left(T_{v} \right)=\frac{1+\exp \left(\frac{298.15\Delta S-\Delta H_{d} }{298.15\times 0.001R_{gas} } \right)}{1+\exp \left(\frac{\Delta ST_{v} -\Delta H_{d} }{0.001R_{gas} T_{v} } \right)} . @@ -284,7 +284,7 @@ Because :math:`T_{p}` as implemented here varies with :math:`T_{p}` . For C\ :sub:`4` plants, .. math:: - :label: 8.12) + :label: 9.12) \begin{array}{l} {V_{c\max } =V_{c\max 25} \left[\frac{Q_{10} ^{(T_{v} -298.15)/10} }{f_{H} \left(T_{v} \right)f_{L} \left(T_{v} \right)} \right]} \\ {f_{H} \left(T_{v} \right)=1+\exp \left[s_{1} \left(T_{v} -s_{2} \right)\right]} \\ {f_{L} \left(T_{v} \right)=1+\exp \left[s_{3} \left(s_{4} -T_{v} \right)\right]} \end{array} @@ -295,7 +295,7 @@ with :math:`Q_{10} =2`, Additionally, .. math:: - :label: 8.13) + :label: 9.13) R_{d} =R_{d25} \left\{\frac{Q_{10} ^{(T_{v} -298.15)/10} }{1+\exp \left[s_{5} \left(T_{v} -s_{6} \right)\right]} \right\} @@ -303,7 +303,7 @@ with :math:`Q_{10} =2`, :math:`s_{5} =1.3` K\ :sup:`-1` and :math:`s_{6} =328.15`\ K, and .. math:: - :label: 8.14) + :label: 9.14) k_{p} =k_{p25} \, Q_{10} ^{(T_{v} -298.15)/10} @@ -337,7 +337,7 @@ achieved by allowing :math:`\Delta S`\ to vary with growth temperature according to .. math:: - :label: 8.15) + :label: 9.15) \begin{array}{l} {\Delta S=668.39-1.07(T_{10} -T_{f} )\qquad \qquad {\rm for\; }V_{c\max } } \\ {\Delta S=659.70-0.75(T_{10} -T_{f} )\qquad \qquad {\rm for\; }J_{\max } } \end{array} @@ -349,7 +349,7 @@ parameterization, :math:`\Delta H_{d}` \ = 200000, ratio :math:`J_{\max 25} /V_{c\max 25}` at 25 :sup:`o`\ C decreases with growth temperature as .. math:: - :label: 8.16) + :label: 9.16) J_{\max 25} /V_{c\max 25} =2.59-0.035(T_{10} -T_{f} ). @@ -415,24 +415,24 @@ coefficient for nitrogen. The canopy integrated value for sunlit and shaded leaves is .. math:: - :label: 8.20) + :label: 9.20) \begin{array}{rcl} {V_{c\; \max 25}^{sun} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)f_{sun} \left(x\right)\, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} } \end{array} .. math:: - :label: 8.21) + :label: 9.21) \begin{array}{rcl} {V_{c\; \max 25}^{sha} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)\left[1-f_{sun} \left(x\right)\right] \, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left\{\left[1-e^{-K_{n} L} \right]\frac{1}{K_{n} } -\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} \right\}} \end{array} and the average value for the sunlit and shaded leaves is .. math:: - :label: 8.22) + :label: 9.22) \bar{V}_{c\; \max 25}^{sun} ={V_{c\; \max 25}^{sun} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sun} L^{sun} }} \right. \kern-\nulldelimiterspace} L^{sun} } .. math:: - :label: 8.23) + :label: 9.23) \bar{V}_{c\; \max 25}^{sha} ={V_{c\; \max 25}^{sha} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sha} L^{sha} }} \right. \kern-\nulldelimiterspace} L^{sha} } . @@ -457,7 +457,7 @@ using the function :math:`f(DYL)`, which introduces seasonal variation to :math:`V_{c\max }` .. math:: - :label: 8.24) + :label: 9.24) f\left(DYL\right)=\frac{\left(DYL\right)^{2} }{\left(DYL_{\max } \right)^{2} } @@ -465,7 +465,7 @@ with :math:`0.01\le f\left(DYL\right)\le 1`. Daylength (seconds) is given by .. math:: - :label: 8.25) + :label: 9.25) DYL=2\times 13750.9871\cos ^{-1} \left[\frac{-\sin \left(lat\right)\sin \left(decl\right)}{\cos \left(lat\right)\cos \left(decl\right)} \right] @@ -492,7 +492,7 @@ of each soil layer, the root distribution of the plant functional type, and a plant-dependent response to soil water stress .. math:: - :label: 8.26) + :label: 9.26) \beta _{t} =\sum _{i}w_{i} r_{i} @@ -501,7 +501,7 @@ where :math:`w_{i}` is a plant wilting factor for layer :math:`i` and wilting factor :math:`w_{i}` is .. math:: - :label: 8.27) + :label: 9.27) w_{i} =\left\{\begin{array}{l} {\frac{\psi _{c} -\psi _{i} }{\psi _{c} -\psi _{o} } \left[\frac{\theta _{sat,i} -\theta _{ice,i} }{\theta _{sat,i} } \right]\le 1\qquad {\rm for\; }T_{i} >T_{f} -2{\rm \; and\; }\theta _{liq,\, i} >0} \\ {0\qquad \qquad \qquad \qquad {\rm for\; }T_{i} \le T_{f} -2{\rm \; or\; }\theta _{liq,\, i} \le 0} \end{array}\right\} @@ -515,7 +515,7 @@ effective porosity (accounting for the ice fraction; Here, the soil water matric potential :math:`\psi _{i}` \ is defined as .. math:: - :label: 8.28) + :label: 9.28) \psi _{i} =\psi _{sat,i} \, s_{i}^{-B_{i} } \ge \psi _{c} @@ -526,7 +526,7 @@ Clapp and Hornberger (1978) parameter (section 7.4.1). The soil wetness :math:`s_{i}` is .. math:: - :label: 8.29) + :label: 9.29) s_{i} =\frac{\theta _{liq,\, i} }{\theta _{sat,\, i} -\theta _{ice,\, i} } \ge 0.01 @@ -544,7 +544,7 @@ The root fraction :math:`r_{i}` in each soil layer depends on the plant functional type .. math:: - :label: 8.30) + :label: 9.30) r_{i} =\left\{\begin{array}{l} {0.5\left[\begin{array}{l} {\exp \left(-r_{a} z_{h,\, i-1} \right)+\exp \left(-r_{b} z_{h,\, i-1} \right)-} \\ {\exp \left(-r_{a} z_{h,\, i} \right)-\exp \left(-r_{b} z_{h,\, i} \right)} \end{array}\right]\qquad {\rm for\; }1\le iCF_{GPPpot} } \end{array}\right. + +.. math:: + :label: 17.3) + + CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{mr} -CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. + +The storage pool that supplies carbon for maintenance respiration in +excess of current :math:`CF_{GPPpot}` ( :math:`CS_{xs}`, gC +m\ :sup:`-2`) is permitted to run a deficit (negative state), and +the magnitude of this deficit determines an allocation demand which +gradually replenishes :math:`CS_{xs}`. The logic for allowing a +negative state for this pool is to eliminate the need to know in advance +what the total maintenance respiration demand will be for a particular +combination of climate and plant type. Using the deficit approach, the +allocation to alleviate the deficit increases as the deficit increases, +until the supply of carbon into the pool balances the demand for carbon +leaving the pool in a quasi-steady state, with variability driven by the +seasonal cycle, climate variation, disturbance, and internal dynamics of +the plant-litter-soil system. In cases where the combination of climate +and plant type are not suitable to sustained growth, the deficit in this +pool increases until the available carbon is being allocated mostly to +alleviate the deficit, and new growth approaches zero. The allocation +flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC +m\ :sup:`-2` s\ :sup:`-1`) is given as + +.. math:: + :label: 17.4) + + CF_{GPP,xs,pot} =\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CS_{xs} \ge 0} \\ {-CS_{xs} /(86400\tau _{xs} )\qquad {\rm for\; }CS_{xs} <0} \end{array}\right. + +.. math:: + :label: 17.5) + + CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPPpot} -CF_{GPP,mr} } \\ {\max (CF_{GPPpot} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPPpot} -CF_{GPP,mr} } \end{array}\right. + +where :math:`\tau_{xs}` is the time constant (currently +set to 30 days) controlling the rate of replenishment of :math:`CS_{xs}`. + +Note that these two top-priority carbon allocation fluxes +(:math:`CF_{GPP,mr}` and :math:`CF_{GPP,xs}`) are not +stoichiometrically associated with any nitrogen fluxes, and so this +initial allocation step can proceed without reference to (or limitation +from) the available mineral nitrogen supply. + +Carbon and Nitrogen Stoichiometry of New Growth +---------------------------------------------------- + +After accounting for the carbon cost of maintenance respiration, the +remaining carbon flux from photosynthesis which can be allocated to new +growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is + +.. math:: + :label: 17.6) + + CF_{avail\_ alloc} =CF_{GPPpot} -CF_{GPP,mr} -CF_{GPP,xs} . + +Potential allocation to new growth is calculated for all of the plant +carbon and nitrogen state variables based on specified C:N ratios for +each tissue type and allometric parameters that relate allocation +between various tissue types. The allometric parameters are defined as +follows: + +.. math:: + :label: ZEqnNum650137 + + \begin{array}{l} {a_{1} ={\rm \; ratio\; of\; new\; fine\; root\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{2} ={\rm \; ratio\; of\; new\; coarse\; root\; :\; new\; stem\; carbon\; allocation}} \\ {a_{3} ={\rm \; ratio\; of\; new\; stem\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{4} ={\rm \; ratio\; new\; live\; wood\; :\; new\; total\; wood\; allocation}} \\ {g_{1} ={\rm ratio\; of\; growth\; respiration\; carbon\; :\; new\; growth\; carbon.\; }} \end{array} + +Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined as constants for a given PFT (Table +13.1), while :math:`g_{l }` = 0.3 (unitless) is prescribed as a +constant for all PFTs, based on construction costs for a range of woody +and non-woody tissues (Larcher, 1995). + +The model includes a dynamic allocation scheme for woody vegetation +(parameter :math:`a_{3}` = -1, Table 13.1), in which case the +ratio for carbon allocation between new stem and new leaf increases with +increasing net primary production (NPP), as + +.. math:: + :label: 17.8) + + a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 + +where :math:`NPP_{ann}` is the annual sum of NPP from the previous +year. This mechanism has the effect of increasing woody allocation in +favorable growth environments (Allen et al., 2005; Vanninen and Makela, +2005) and during the phase of stand growth prior to canopy closure +(Axelsson and Axelsson, 1986). + +Table 13.1. Allocation and carbon:nitrogen ratio parameters + ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`CN_{leaf}` | :math:`CN_{fr}` | :math:`CN_{lw}` | :math:`CN_{dw}` | ++==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ +| NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| NET Boreal | 1 | 0.3 | -1 | 0.1 | 40 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| NDT Boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BET Tropical | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BET temperate | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDT tropical | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDT temperate | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDT boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BES temperate | 1 | 0.3 | 0.2 | 0.5 | 30 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDS temperate | 1 | 0.3 | 0.2 | 0.5 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| C\ :sub:`3` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| C\ :sub:`3` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| C\ :sub:`4` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Crop R | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Crop I | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Corn R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Corn I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Temp Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Temp Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Winter Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Winter Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Soybean R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +| Soybean I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | ++----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + +Carbon to nitrogen ratios are defined for different tissue types as +follows: + +.. math:: + :label: ZEqnNum413927 + + \begin{array}{l} {CN_{leaf} =\_ {\rm \; C:N\; for\; leaf}} \\ {CN_{fr} =\_ {\rm \; C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \; C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\_ {\rm \; C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} + +where all C:N parameters are defined as constants for a given PFT (Table +13.1). + +Given values for the parameters in and , total carbon and nitrogen +allocation to new growth ( :math:`CF_{alloc}`, gC +m\ :sup:`-2` s\ :sup:`-1`, and :math:`NF_{alloc}`, gN +m\ :sup:`-2` s\ :sup:`-1`, respectively) can be expressed as +functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC +m\ :sup:`-2` s\ :sup:`-1`): + +.. math:: + :label: ZEqnNum555154 + + \begin{array}{l} {CF_{alloc} =CF_{GPP,leaf} {\kern 1pt} C_{allom} } \\ {NF_{alloc} =CF_{GPP,leaf} {\kern 1pt} N_{allom} } \end{array} + +where + +.. math:: + :label: 17.11) + + \begin{array}{l} {C_{allom} =\left\{\begin{array}{l} {\left(1+g_{1} \right)\left(1+a_{1} +a_{3} \left(1+a_{2} \right)\right)\qquad {\rm for\; woody\; PFT}} \\ {1+g_{1} +a_{1} \left(1+g_{1} \right)\qquad \qquad {\rm for\; non-woody\; PFT}} \end{array}\right. } \\ {} \end{array} + +.. math:: + :label: 17.12) + + N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. + +Since the C:N stoichiometry for new growth allocation is defined, from +Eq. , as :math:`C_{allom}`/ :math:`N_{allom}`, the total carbon available for new growth allocation +(:math:`CF_{avail\_alloc}`) can be used to calculate the total +plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, +gN m\ :sup:`-2` s\ :sup:`-1`) as: + +.. math:: + :label: 17.13) + + NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . + +Deployment of retranslocated nitrogen +------------------------------------------ + +In many plants, some portion of the nitrogen used to construct new +tissues is mobilized from senescing tissues, especially leaves, and +retained within the plant when the tissues are lost as litter. This +store of retranslocated nitrogen is used to supply part of the nitrogen +demand for subsequent growth (Magill et al., 1997; Oikawa et al., 2005; +Son and Gower, 1991). CLM includes one pool of retranslocated nitrogen +(:math:`NS_{retrans}`, gN m\ :sup:`-2`), and the +availability of nitrogen from this pool to support new growth +(:math:`NF_{avail\_retrans}`, gN m\ :sup:`-2` +s\ :sup:`-1`) is proportional to the plant nitrogen demand, as: + +.. math:: + :label: 17.14) + + NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) + +where :math:`NF_{retrans\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of retranslocated +nitrogen extracted from senescing tissues, +:math:`NF_{plant\_demand\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of +:math:`NF_{plant\_demand}`, and :math:`\Delta`\ *t* (s) is the +model’s biogeochemistry time step. This formulation produces an annual +cycle in the extraction of nitrogen from :math:`NS_{retrans}` +which corresponds to the annual cycle of plant nitrogen demand, and +which is scaled to give :math:`NS_{retrans}` approximately a +one-year turnover time. The minimum function prevents extraction of more +than the remaining pool of retranslocated nitrogen, which can be an +important constraint under conditions where high rates of mortality are +modifying the size of the pool. During the first year of an initial +simulation, before :math:`NF_{plant\_demand\_ann}` and +:math:`NF_{retrans\_ann}` have valid values, +:math:`NF_{avail\_retrans}` is set to 0.0. + +The actual flux of nitrogen from the retranslocated N pool into +allocation of new growth (:math:`NF_{retrans,alloc}`, gN +m\ :sup:`-2` s\ :sup:`-1`) is never greater than the plant +demand for new nitrogen: + +.. math:: + :label: 17.15) + + NF_{retrans,alloc} =\min \left(NF_{plant\_ demand} ,NF_{avail\_ retrans} \right) + +Plant nitrogen uptake from soil mineral nitrogen pool +---------------------------------------------------------- + +The total plant nitrogen demand is reduced by the nitrogen flux from +:math:`NS_{retrans}` to give the plant demand for mineral nitrogen +from the soil (:math:`NF_{plant\_demand\_soil}`, gN +m\ :sup:`-2` s\ :sup:`-1`): + +.. math:: + :label: ZEqnNum491412 + + NF_{plant\_ demand\_ soil} =NF_{plant\_ demand} -NF_{retrans,alloc} . + +The combined demand from all PFTs sharing space on a soil column and the +demand from the heterotrophic community in the soil (nitrogen +immobilization demand) compete for the available soil mineral nitrogen +pool. The result of this competition is passed back to the allocation +algorithm as :math:`f_{plant\_demand}`, the fraction (from 0 to 1) +of the plant nitrogen demand which can be met given the current soil +mineral nitrogen supply and competition with heterotrophs. Plant uptake +from the soil mineral nitrogen pool is then given as: + +.. math:: + :label: 17.17) + + NF_{sminn,alloc} =NF_{plant\_ demand\_ soil} f_{plant\_ demand} + +Final carbon and nitrogen allocation +----------------------------------------- + +The total flux of allocated nitrogen is given as: + +.. math:: + :label: 17.18) + + NF_{alloc} =NF_{retrans,alloc} +NF_{sminn,alloc} + +From the stoichiometric relationship in Eq. , the associated carbon +allocation flux is: + +.. math:: + :label: 17.19) + + CF_{alloc} =NF_{alloc} \frac{C_{allom} }{N_{allom} } . + +The downregulation of photosynthesis can then be calculated as: + +.. math:: + :label: 17.20) + + f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . + +Total allocation to new leaf carbon +(:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as: + +.. math:: + :label: 17.21) + + CF_{alloc,leaf\_ tot} =\frac{CF_{alloc} }{C_{allom} } . + +There are two carbon pools associated with each plant tissue – one which +represents the currently displayed tissue, and another which represents +carbon stored for display in a subsequent growth period. The nitrogen +pools follow this same organization. The model keeps track of stored +carbon according to which tissue type it will eventually be displayed +as, and the separation between display in the current timestep and +storage for later display depends on the parameter :math:`f_{cur}` +(values 0 to 1). Given :math:`CF_{alloc,leaf}` and :math:`f_{cur}`, the allocation fluxes of carbon to display and +storage pools (where storage is indicated with *\_stor*) for the various +tissue types are given as: + +.. math:: + :label: 17.22) + + CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} + +.. math:: + :label: 17.23) + + CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) + +.. math:: + :label: 17.24) + + CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} + +.. math:: + :label: 17.25) + + CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) + +.. math:: + :label: 17.26) + + CF_{alloc,livestem} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} f_{cur} + +.. math:: + :label: 17.27) + + CF_{alloc,livestem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} \left(1-f_{cur} \right) + +.. math:: + :label: 17.28) + + CF_{alloc,deadstem} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)f_{cur} + +.. math:: + :label: 17.29) + + CF_{alloc,deadstem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right) + +.. math:: + :label: 17.30) + + CF_{alloc,livecroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} f_{cur} + +.. math:: + :label: 17.31) + + CF_{alloc,livecroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} \left(1-f_{cur} \right) + +.. math:: + :label: 17.32) + + CF_{alloc,deadcroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)f_{cur} + +.. math:: + :label: 17.33) + + CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). + +The corresponding nitrogen allocation fluxes are given as: + +.. math:: + :label: 17.34) + + NF_{alloc,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} + +.. math:: + :label: 17.35) + + NF_{alloc,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) + +.. math:: + :label: 17.36) + + NF_{alloc,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} + +.. math:: + :label: 17.37) + + NF_{alloc,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) + +.. math:: + :label: 17.38) + + NF_{alloc,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} + +.. math:: + :label: 17.39) + + NF_{alloc,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) + +.. math:: + :label: 17.40) + + NF_{alloc,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} + +.. math:: + :label: 17.41) + + NF_{alloc,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) + +.. math:: + :label: 17.42) + + NF_{alloc,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} + +.. math:: + :label: 17.43) + + NF_{alloc,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) + +.. math:: + :label: 17.44) + + NF_{alloc,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} + +.. math:: + :label: 17.45) + + NF_{alloc,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). + +Autotrophic Respiration +---------------------------- + +The model treats maintenance and growth respiration fluxes separately, +even though it is difficult to measure them as separate fluxes (Lavigne +and Ryan, 1997; Sprugel et al., 1995). Maintenance respiration is +defined as the carbon cost to support the metabolic activity of existing +live tissue, while growth respiration is defined as the additional +carbon cost for the synthesis of new growth. + +13.7.1 Maintenance Respiration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Under the assumption that tissue nitrogen content is a suitable index of +cellular metabolic rate, maintenance respiration costs for live tissues +(leaf, live stem, live coarse root, and fine root) are calculated as +functions tissue nitrogen content and the relevant temperature, +following the empirical relationship reported by Ryan (1991): + +.. math:: + :label: 17.46) + + CF_{mr\_ leaf} \_ =NS_{leaf} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + +.. math:: + :label: 17.47) + + CF_{mr\_ livestem} \_ =NS_{livestem} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + +.. math:: + :label: 17.48) + + CF_{mr\_ livecroot} \_ =NS_{livecroot} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + +.. math:: + :label: 17.49) + + CF_{mr\_ froot} \_ =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} + +where :math:`MR_{base}` (= 2.525e\ :sup:`-6` gC gN\ :sup:`-1` s\ :sup:`-1`) is the base rate of maintenance +respiration per unit nitrogen content, :math:`MR_{q10}` (= 2.0) is +the temperature sensitivity for maintenance respiration, +:math:`T_{2m}` (:sup:`o`\ C) is the air temperature at 2m +height, :math:`Ts_{j}`* (:sup:`o`\ C) is the soil +temperature at level *j*, and :math:`rootfr_{j}` is the fraction +of fine roots distributed in soil level *j*. + +Note that, for woody vegetation, maintenance respiration costs are not +calculated for the dead stem and dead coarse root components. These +components are assumed to consist of dead xylem cells, with no metabolic +function. By separating the small live component of the woody tissue +(ray parenchyma, phloem, and sheathing lateral meristem cells) from the +larger fraction of dead woody tissue, it is reasonable to assume a +common base maintenance respiration rate for all live tissue types. + +The total maintenance respiration cost is then given as: + +.. math:: + :label: 17.50) + + CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . + +13.7.2 Growth Respiration +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Growth respiration is calculated as a factor of 0.3 times the total +carbon in new growth on a given timestep, based on construction costs +for a range of woody and non-woody tissues (Larcher, 1995). For new +carbon and nitrogen allocation that enters storage pools for subsequent +display, it is not clear what fraction of the associated growth +respiration should occur at the time of initial allocation, and what +fraction should occur later, at the time of display of new growth from +storage. Eddy covariance estimates of carbon fluxes in forest ecosystems +suggest that the growth respiration associated with transfer of +allocated carbon and nitrogen from storage into displayed tissue is not +significant (Churkina et al., 2003), and so it is assumed in CLM that +all of the growth respiration cost is incurred at the time of initial +allocation, regardless of the fraction of allocation that is displayed +immediately (i.e. regardless of the value of :math:`f_{cur}`, +section 13.5). This behavior is parameterized in such a way that if +future research suggests that some fraction of the growth respiration +cost should be incurred at the time of display from storage, a simple +parameter modification will effect the change. [1]_ + +.. [1] + Parameter :math:`\text{grpnow}` in routines CNGResp and CNAllocation, currently set to 1.0, could be changed to a smaller + value to transfer some portion (1 - :math:`\text{grpnow}` ) of the growth respiration forward in time to occur at the time of growth + display from storage. + diff --git a/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst b/doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst similarity index 97% rename from doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst rename to doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst index 9568b91b16..773b3f2fe6 100644 --- a/doc/source/tech_note/CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst +++ b/doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst @@ -25,7 +25,7 @@ cell to its downstream neighboring grid cell. The change in storage cell (m\ :sup:`3` s\ :sup:`-1`) is .. math:: - :label: 11.1) + :label: 14.1) \frac{dS}{dt} =\sum F_{in} -F_{out} +R @@ -42,7 +42,7 @@ model (Graham et al. 1999). The flux of water leaving the grid cell :math:`F_{out}` is .. math:: - :label: 11.2) + :label: 14.2) F_{out} =\frac{v}{d} S @@ -57,7 +57,7 @@ and channel roughness data are not available globally, so a simplified effective flow velocity expression is used in RTM .. math:: - :label: 11.3) + :label: 14.3) v=\max \left(0.05,k\beta ^{1/2} \right) @@ -68,14 +68,14 @@ The distance :math:`d` between two grid cell centers depends on river direction, latitude, and longitude as .. math:: - :label: 11.4) + :label: 14.4) d=\sqrt{\Delta x^{2} +\Delta y^{2} } . The distance in the zonal direction :math:`\Delta x` (m) is .. math:: - :label: 11.5) + :label: 14.5) \Delta x=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right)\left[0.5\left(\cos \phi _{i,\, j} +\cos \phi _{i*,\, j*} \right)\right] @@ -88,7 +88,7 @@ are grid cell indices. The distance in the meridional direction :math:`\Delta y` (m) is .. math:: - :label: 11.6) + :label: 14.6) \Delta y=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right). @@ -99,7 +99,7 @@ total liquid water runoff at the land model resolution (kg m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 11.7) + :label: 14.7) R_{liq} =q_{over} +q_{drai} +q_{rgwl} @@ -110,7 +110,7 @@ where :math:`q_{over}` is surface runoff (section 7.3), 9.6.3). The total ice water runoff, also at the land model resolution is .. math:: - :label: 11.8) + :label: 14.8) R_{ice} =q_{snwcp,ice} @@ -134,7 +134,7 @@ as a diagnostic tool. The river-routing scheme conserves water globally as .. math:: - :label: 11.9) + :label: 14.9) \sum _{i,\, j}\left(\frac{dS}{dt} \right) _{i,\, j} =\sum _{i,\, j}R_{i,\, j} . diff --git a/doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst rename to doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst diff --git a/doc/source/tech_note/CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst rename to doc/source/tech_note/References/CLM50_Tech_Note_References.rst diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst new file mode 100644 index 0000000000..d84d3c8a3d --- /dev/null +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -0,0 +1,4 @@ +.. _rst_Snow Hydrology: + +Snow Hydrology +============== diff --git a/doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst rename to doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst diff --git a/doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst similarity index 100% rename from doc/source/tech_note/CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst rename to doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst diff --git a/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst similarity index 99% rename from doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst rename to doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index d967dae888..fad229fe7c 100644 --- a/doc/source/tech_note/CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -56,12 +56,12 @@ algorithm, and :math:`n` is the index value for the :math:`dynpft\_ year(n)=year_{cur}` : .. math:: - :label: 21.1) + :label: 26.1) nt_{1} =\left\{\begin{array}{l} {1\qquad {\rm for}\qquad year_{cur} TKFRZ} \\ {FD_{sum}^{n-1} \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \end{array}\right. . @@ -616,7 +616,7 @@ carbon fluxes, and to Eqs. - for nitrogen fluxes. The onset counter is decrement until it reaches zero, signaling the end of the onset period: .. math:: - :label: 14.67) + :label: 20.67) t_{onfset}^{n} =t_{onfset}^{n-1} -\Delta t @@ -634,7 +634,7 @@ period of dry soils, this control variable can increase or decrease, as follows: .. math:: - :label: 14.68) + :label: 20.68) OSWI_{sum}^{n} =\left\{\begin{array}{l} {OSWI_{sum}^{n-1} +f_{day} \qquad \qquad \qquad {\rm for\; }\Psi _{s,3} \le \Psi _{offset} } \\ {{\rm max}\left(OSWI_{sum}^{n-1} -f_{day} ,0\right)\qquad {\rm for\; }\Psi _{s,3} >\Psi _{onset} } \end{array}\right. @@ -648,7 +648,7 @@ accumulator (:math:`{OFD}_{sum}`, d). To test for a sustained period of cold temperature, this variable can increase or decrease, as follows: .. math:: - :label: 14.69) + :label: 20.69) OFD_{sum}^{n} =\left\{\begin{array}{l} {OFD_{sum}^{n-1} +f_{day} \qquad \qquad \qquad {\rm for\; }T_{s,3} \le TKFRZ} \\ {{\rm max}\left(OFD_{sum}^{n-1} -f_{day} ,0\right)\qquad \qquad {\rm for\; }T_{s,3} >TKFRZ} \end{array}\right. @@ -664,7 +664,7 @@ offset period, until it reaches zero, signaling the end of the offset period: .. math:: - :label: 14.70) + :label: 20.70) t_{offset}^{n} =t_{offset}^{n-1} -\Delta t @@ -682,14 +682,14 @@ of an offset period :math:`{n}_{days\_active}` is reset to 0. A long growing season control variable (*LGS*, range 0 to 1) is calculated as: .. math:: - :label: 14.71) + :label: 20.71) LGS=\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }n_{days\_ active} <365} \\ {\left({n_{days\_ active} \mathord{\left/ {\vphantom {n_{days\_ active} 365}} \right. \kern-\nulldelimiterspace} 365} \right)-1\qquad {\rm for\; }365\le n_{days\_ active} <730} \\ {1\qquad \qquad \qquad {\rm for\; }n_{days\_ active} \ge 730} \end{array}\right. . The rate coefficient for background litterfall (:math:`{r}_{bglf}`, s\ :sup:`-1`) is calculated as a function of *LGS*: .. math:: - :label: 14.72) + :label: 20.72) r_{bglf} =\frac{LGS}{\tau _{leaf} \cdot 365\cdot 86400} @@ -699,71 +699,71 @@ where :math:`{\tau}_{leaf}` is the leaf longevity. The result is a shift to cont The rate coefficient for background onset growth from the transfer pools ( :math:`{r}_{bgtr}`, s\ :sup:`-1`) also depends on *LGS*, as: .. math:: - :label: 14.73) + :label: 20.73) r_{bgtr} =\frac{LGS}{365\cdot 86400} . On each timestep with :math:`{r}_{bgtr}` :math:`\neq` 0, carbon fluxes from storage to transfer pools are calculated as: .. math:: - :label: 14.74) + :label: 20.74) CF_{leaf\_ stor,leaf\_ xfer} =CS_{leaf\_ stor} r_{bgtr} .. math:: - :label: 14.75) + :label: 20.75) CF_{froot\_ stor,froot\_ xfer} =CS_{froot\_ stor} r_{bgtr} .. math:: - :label: 14.76) + :label: 20.76) CF_{livestem\_ stor,livestem\_ xfer} =CS_{livestem\_ stor} r_{bgtr} .. math:: - :label: 14.77) + :label: 20.77) CF_{deadstem\_ stor,deadstem\_ xfer} =CS_{deadstem\_ stor} r_{bgtr} .. math:: - :label: 14.78) + :label: 20.78) CF_{livecroot\_ stor,livecroot\_ xfer} =CS_{livecroot\_ stor} r_{bgtr} .. math:: - :label: 14.79) + :label: 20.79) CF_{deadcroot\_ stor,deadcroot\_ xfer} =CS_{deadcroot\_ stor} r_{bgtr} , with corresponding nitrogen fluxes: .. math:: - :label: 14.80) + :label: 20.80) NF_{leaf\_ stor,leaf\_ xfer} =NS_{leaf\_ stor} r_{bgtr} .. math:: - :label: 14.81) + :label: 20.81) NF_{froot\_ stor,froot\_ xfer} =NS_{froot\_ stor} r_{bgtr} .. math:: - :label: 14.82) + :label: 20.82) NF_{livestem\_ stor,livestem\_ xfer} =NS_{livestem\_ stor} r_{bgtr} .. math:: - :label: 14.83) + :label: 20.83) NF_{deadstem\_ stor,deadstem\_ xfer} =NS_{deadstem\_ stor} r_{bgtr} .. math:: - :label: 14.84) + :label: 20.84) NF_{livecroot\_ stor,livecroot\_ xfer} =NS_{livecroot\_ stor} r_{bgtr} .. math:: - :label: 14.85) + :label: 20.85) NF_{deadcroot\_ stor,deadcroot\_ xfer} =NS_{deadcroot\_ stor} r_{bgtr} . @@ -790,32 +790,32 @@ calculated using a weighted average of the fluxes originating at the PFT level. Carbon fluxes are calculated as: .. math:: - :label: 14.86) + :label: 20.86) CF_{leaf,lit1} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{lab\_ leaf,p} wcol_{p} .. math:: - :label: 14.87) + :label: 20.87) CF_{leaf,lit2} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{cel\_ leaf,p} wcol_{p} .. math:: - :label: 14.88) + :label: 20.88) CF_{leaf,lit3} =\sum _{p=0}^{npfts}CF_{leaf,litter} f_{lig\_ leaf,p} wcol_{p} .. math:: - :label: 14.89) + :label: 20.89) CF_{froot,lit1} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{lab\_ froot,p} wcol_{p} .. math:: - :label: 14.90) + :label: 20.90) CF_{froot,lit2} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{cel\_ froot,p} wcol_{p} .. math:: - :label: 14.91) + :label: 20.91) CF_{froot,lit3} =\sum _{p=0}^{npfts}CF_{froot,litter} f_{lig\_ froot,p} wcol_{p} , @@ -832,32 +832,32 @@ C:N of the senescent tissue, and so are distributed using the same fractions used for carbon fluxes: .. math:: - :label: 14.92) + :label: 20.92) NF_{leaf,lit1} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{lab\_ leaf,p} wcol_{p} .. math:: - :label: 14.93) + :label: 20.93) NF_{leaf,lit2} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{cel\_ leaf,p} wcol_{p} .. math:: - :label: 14.94) + :label: 20.94) NF_{leaf,lit3} =\sum _{p=0}^{npfts}NF_{leaf,litter} f_{lig\_ leaf,p} wcol_{p} .. math:: - :label: 14.95) + :label: 20.95) NF_{froot,lit1} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{lab\_ froot,p} wcol_{p} .. math:: - :label: 14.96) + :label: 20.96) NF_{froot,lit2} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{cel\_ froot,p} wcol_{p} .. math:: - :label: 14.97) + :label: 20.97) NF_{froot,lit3} =\sum _{p=0}^{npfts}NF_{froot,litter} f_{lig\_ froot,p} wcol_{p} . diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index 4141a560bc..74a39e908b 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -13,31 +13,36 @@ CLM Technical Note :maxdepth: 2 :numbered: - CHAPTER_1/CLM50_Tech_Note_Chpt_1_Introduction.rst - CHAPTER_2/CLM50_Tech_Note_Chpt_2_Ecosystem.rst - CHAPTER_3/CLM50_Tech_Note_Chpt_3_Surface_Albedos.rst - CHAPTER_4/CLM50_Tech_Note_Chpt_4_Radiative_Fluxes.rst - CHAPTER_5/CLM50_Tech_Note_Chpt_5_Fluxes.rst - CHAPTER_6/CLM50_Tech_Note_Chpt_6_Soil_Snow_Temperatures.rst - CHAPTER_7/CLM50_Tech_Note_Chpt_7_Hydrology.rst - CHAPTER_8/CLM50_Tech_Note_Chpt_8_Photosynthesis.rst - CHAPTER_9/CLM50_Tech_Note_Chpt_9_Lake.rst - CHAPTER_10/CLM50_Tech_Note_Chpt_10_Glacier.rst - CHAPTER_11/CLM50_Tech_Note_Chpt_11_RTM.rst - CHAPTER_12/CLM50_Tech_Note_Chpt_12_Urban.rst - CHAPTER_13/CLM50_Tech_Note_Chpt_13_CN_Allocation_Respiration.rst - CHAPTER_14/CLM50_Tech_Note_Chpt_14_Vegetation_Phenology.rst - CHAPTER_15/CLM50_Tech_Note_Chpt_15_Decomposition.rst - CHAPTER_16/CLM50_Tech_Note_Chpt_16_External_Nitrogen_Cycle.rst - CHAPTER_17/CLM50_Tech_Note_Chpt_17_Plant_Mortality.rst - CHAPTER_18/CLM50_Tech_Note_Chpt_18_Fire.rst - CHAPTER_19/CLM50_Tech_Note_Chpt_19_Methane.rst - CHAPTER_20/CLM50_Tech_Note_Chpt_20_Crop_Irrigation.rst - CHAPTER_21/CLM50_Tech_Note_Chpt_21_Transient_Landcover.rst - CHAPTER_22/CLM50_Tech_Note_Chpt_22_DGVM.rst - CHAPTER_23/CLM50_Tech_Note_Chpt_23_BVOCs.rst - CHAPTER_24/CLM50_Tech_Note_Chpt_24_Dust.rst - CHAPTER_25/CLM50_Tech_Note_Chpt_25_Isotopes.rst - CHAPTER_26/CLM50_Tech_Note_Chpt_26_Offline.rst - CHAPTER_27/CLM50_Tech_Note_Chpt_27_References.rst + Introduction/CLM50_Tech_Note_Introduction.rst + Ecosystem/CLM50_Tech_Note_Ecosystem.rst + Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst + Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst + Fluxes/CLM50_Tech_Note_Fluxes.rst + Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst + Hydrology/CLM50_Tech_Note_Hydrology.rst + Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst + Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst + Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst + Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst + Lake/CLM50_Tech_Note_Lake.rst + Glacier/CLM50_Tech_Note_Glacier.rst + RTM/CLM50_Tech_Note_RTM.rst + Urban/CLM50_Tech_Note_Urban.rst + CN_Pools/CLM50_Tech_Note_CN_Pools.rst + Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst + FUN/CLM50_Tech_Note_FUN.rst + CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst + Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst + Decomposition/CLM50_Tech_Note_Decomposition.rst + External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst + Fire/CLM50_Tech_Note_Fire.rst + Methane/CLM50_Tech_Note_Methane.rst + Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst + Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst + DGVM/CLM50_Tech_Note_DGVM.rst + BVOCs/CLM50_Tech_Note_BVOCs.rst + Dust/CLM50_Tech_Note_Dust.rst + Isotopes/CLM50_Tech_Note_Isotopes.rst + Offline/CLM50_Tech_Note_Offline.rst + References/CLM50_Tech_Note_References.rst From 0024f6a24bb609555e8220d3f57d870723f0b5c2 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 18 May 2017 13:07:45 -0600 Subject: [PATCH 014/255] split hydrology & snow hydrology --- doc/source/conf.py | 7 + .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 16 +- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 697 +---------------- .../CLM50_Tech_Note_Snow_Hydrology.rst | 710 +++++++++++++++++- ...CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 10 + .../CLM50_Tech_Note_Surface_Albedos.rst | 10 + 6 files changed, 775 insertions(+), 675 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index dc9a7b7ea8..2d69cb46bd 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -162,3 +162,10 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/': None} + +numfig = True +numfig_format = {'figure': 'Figure %s', + 'table': 'Table %s', + 'code-block': 'Code %s', + 'section': '%s', + } diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 2d2eb57337..868d8409a6 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -94,6 +94,8 @@ from the atmospheric specific humidity :math:`q_{atm}` e_{atm} =\frac{q_{atm} P_{atm} }{0.622+0.378q_{atm} } . +.. _Monin-Obukhov Similarity Theory: + Monin-Obukhov Similarity Theory ----------------------------------- @@ -430,7 +432,7 @@ calculate the surface momentum, sensible heat, and water vapor flux using atmospheric and surface values for :math:`\left|{\it u}\right|`, :math:`\theta` , and :math:`q` except that :math:`L` depends on :math:`u_{*}` , :math:`\theta _{*}` , and :math:`q_{*}` . However, the -bulk CityplaceRichardson number +bulk Richardson number .. math:: :label: ZEqnNum750428} @@ -554,6 +556,8 @@ Chapter 24) u_{10m} =\left\{\begin{array}{l} {V_{a} \qquad z_{atm,\, m} \le 10} \\ {V_{a} -\frac{u_{*} }{k} \left[\ln \left(\frac{z_{atm,\, m} -d}{10+z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{10+z_{0m} }{L} \right)\right]\qquad z_{atm,\, m} >10} \end{array}\right\} +.. _Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces: + Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces -------------------------------------------------------------- @@ -813,6 +817,8 @@ determined analytically, are ignored for :math:`\frac{\partial H_{g} }{\partial T_{g} }` and :math:`\frac{\partial E_{g} }{\partial T_{g} }` . +.. _Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces: + Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces -------------------------------------------------------------------------- @@ -828,6 +834,8 @@ using the ground temperature from the previous time step. In section 5.3.1, the equations used in the iteration scheme are derived. Details on the numerical scheme are provided in section 5.3.2. +.. _Theory: + Theory ^^^^^^^^^^^^ @@ -1302,6 +1310,8 @@ Table 5.1. Plant functional type aerodynamic parameters | Soybean I | 0.120 | 0.68 | 0.04 | +----------------------------------+--------------------+------------------+-------------------------+ +.. _Numerical Implementation: + Numerical Implementation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1529,6 +1539,8 @@ flux later. #. 2-m height air temperature :math:`T_{2m}` , specific humidity :math:`q_{2m}` , relative humidity :math:`RH_{2m}` \ (eqs. , , ) +.. _Update of Ground Sensible and Latent Heat Fluxes: + Update of Ground Sensible and Latent Heat Fluxes ---------------------------------------------------- @@ -1667,6 +1679,8 @@ The system balances energy as \overrightarrow{S}_{g} +\overrightarrow{S}_{v} +L_{atm} \, \downarrow -L\, \uparrow -H_{v} -H_{g} -\lambda _{vap} E_{v} -\lambda E_{g} -G=0. +.. _Saturation Vapor Pressure: + Saturation Vapor Pressure ----------------------------- diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 59751de56c..205a14c0e6 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -39,6 +39,8 @@ Figure 7.1. Hydrologic processes represented in CLM. .. image:: image1.png +.. _Canopy Water: + Canopy Water ---------------- @@ -143,678 +145,7 @@ while the fraction of the canopy that is dry and transpiring is f_{dry} =\left\{\begin{array}{l} {\frac{\left(1-f_{wet} \right)L}{L+S} \qquad L+S>0} \\ {0\qquad L+S=0} \end{array}\right\}. -Snow --------- - -The parameterizations for snow are based primarily on Anderson (1976), -country-regionplaceJordan (1991), and Dai and Zeng (1997). The snowpack -can have up to five layers. These layers are indexed in the Fortran code -as :math:`i=-4,-3,-2,-1,0` where layer :math:`i=0` is the snow layer -next to the top soil layer and layer :math:`i=-4` is the top layer of a -five-layer snow pack. Since the number of snow layers varies according -to the snow depth, we use the notation :math:`snl+1` to describe the top -layer of snow for the variable layer snow pack, where :math:`snl` is the -negative of the number of snow layers. Refer to Figure 7.2 for an -example of the snow layer structure for a three layer snow pack. - -Figure 7.2. Example of three layer snow pack (:math:`snl=-3`). - -Shown are three snow layers, :math:`i=-2`, :math:`i=-1`, and -:math:`i=0`. The layer node depth is :math:`z`, the layer interface is -:math:`z_{h}` , and the layer thickness is :math:`\Delta z`. - -.. image:: image2.png - -The state variables for snow are the mass of water :math:`w_{liq,i}` -(kg m\ :sup:`-2`), mass of ice :math:`w_{ice,i}` (kg -m\ :sup:`-2`), layer thickness :math:`\Delta z_{i}` (m), and -temperature :math:`T_{i}` (Chapter 6). The water vapor phase is -neglected. Snow can also exist in the model without being represented by -explicit snow layers. This occurs when the snowpack is less than a -specified minimum snow depth (:math:`z_{sno} <0.01` m). In this case, -the state variable is the mass of snow :math:`W_{sno}` (kg -m\ :sup:`-2`). - -Section 7.2.1 describes the calculation of fractional snow covered area, -which is used in the surface albedo calculation (Chapter 3) and the -surface flux calculations (Chapter 5). The following two sections (7.2.2 -and 7.2.3) describe the ice and water content of the snow pack assuming -that at least one snow layer exists. Section 7.2.4 describes how black -and organic carbon and mineral dust particles are represented within -snow, including meltwater flushing. See section 7.2.5 for a description -of how a snow layer is initialized. - -Snow Covered Area Fraction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The fraction of the ground covered by snow, :math:`f_{sno}` , is based -on the method of Swenson and Lawrence (2012). Because the processes -governing snowfall and snowmelt differ, changes in :math:`f_{sno}` are -calculated separately for accumulation and depletion. When snowfall -occurs, :math:`f_{sno}` is updated as - -.. math:: - :label: 7.14) - - f^{n+1} _{sno} =1-\left(\left(1-\tanh (k_{accum} q_{sno} \Delta t)\right)\left(1-f^{n} _{sno} \right)\right) - -where :math:`k_{accum}` is a constant whose default value is 0.1, -:math:`q_{sno} \Delta t` is the amount of new snow, -:math:`f^{n+1} _{sno}` is the updated snow covered fraction (SCF), and -:math:`f^{n} _{sno}` is the SCF from the previous time step. - -When snow melt occurs, :math:`f_{sno}` is calculated from the depletion -curve - -.. math:: - :label: 7.15) - - f_{sno} =1-\left(\frac{\cos ^{-1} \left(2R_{sno} -1\right)}{\pi } \right)^{N_{melt} } - -where :math:`R_{sno}` is the ratio of :math:`W_{sno}` to the maximum -accumulated snow :math:`W_{\max }` , and :math:`N_{melt}` is a -parameter that depends on the topographic variability within the grid -cell. Whenever :math:`W_{sno}` reaches zero, :math:`W_{\max }` is -reset to zero. The depletion curve shape parameter is defined as - -.. math:: - :label: 7.16) - - N_{melt} =\frac{200}{\min \left(10,\sigma _{topo} \right)} - -The standard deviation of the elevation within a grid cell, -:math:`\sigma _{topo}` , is calculated from a high resolution DEM (a -1km DEM is used for CLM). - -Ice Content -^^^^^^^^^^^^^^^^^ - -The conservation equation for mass of ice in snow layers is - -.. math:: - :label: 7.17) - - \frac{\partial w_{ice,\, i} }{\partial t} =\left\{\begin{array}{l} {f_{sno} q_{ice,\, i-1} -\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} \qquad i=snl+1} \\ {-\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} \qquad i=snl+2,\ldots ,0} \end{array}\right\} - -where :math:`q_{ice,\, i-1}` is the rate of ice accumulation from -precipitation or frost or the rate of ice loss from sublimation (kg -m\ :sup:`-2` s\ :sup:`-1`) in the top layer and -:math:`{\left(\Delta w_{ice,\, i} \right)_{p} \mathord{\left/ {\vphantom {\left(\Delta w_{ice,\, i} \right)_{p} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` -is the change in ice due to phase change (melting rate) (section 6.2). -The term :math:`q_{ice,\, i-1}` is computed in two steps as - -.. math:: - :label: 7.18) - - q_{ice,\, i-1} =q_{grnd,\, ice} +\left(q_{frost} -q_{subl} \right) - -where :math:`q_{grnd,\, ice}` is the rate of solid precipitation -reaching the ground (section 7.1) and :math:`q_{frost}` and -:math:`q_{subl}` are gains due to frost and losses due to sublimation, -respectively (section 5.4). In the first step, immediately after -:math:`q_{grnd,\, ice}` has been determined after accounting for -interception (section 7.1), a new snow depth :math:`z_{sno}` (m) is -calculated from - -.. math:: - :label: 7.19) - - z_{sno}^{n+1} =z_{sno}^{n} +\Delta z_{sno} - -where - -.. math:: - :label: 7.20) - - \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } - -and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg -m\ :sup:`-3`) (CityplaceAnderson 1976) - -.. math:: - :label: 7.21) - - \rho _{sno} =\left\{\begin{array}{l} {50+1.7\left(17\right)^{1.5} \qquad T_{atm} >T_{f} +2} \\ {50+1.7\left(T_{atm} -T_{f} +15\right)^{1.5} \qquad T_{f} -15T_{f}` ). In this case, the incoming solid precipitation -is assigned to the runoff term :math:`q_{rgwl}` (section 7.7). - -In the second step, after surface fluxes and snow/soil temperatures have -been determined (Chapters 5 and 6), :math:`w_{ice,\, snl+1}` is updated -for frost or sublimation as - -.. math:: - :label: ZEqnNum863244 - - w_{ice,\, snl+1}^{n+1} =w_{ice,\, snl+1}^{n} +f_{sno} \left(q_{frost} -q_{subl} \right)\Delta t. - -If :math:`w_{ice,\, snl+1}^{n+1} <0` upon solution of equation , the ice -content is reset to zero and the liquid water content -:math:`w_{liq,\, snl+1}` is reduced by the amount required to bring -:math:`w_{ice,\, snl+1}^{n+1}` up to zero. - -The snow water equivalent :math:`W_{sno}` is capped to not exceed 1000 -kg m\ :sup:`-2`. If the addition of :math:`q_{frost}` were to -result in :math:`W_{sno} >1000` kg m\ :sup:`-2`, the frost term -:math:`q_{frost}` is instead added to the ice runoff term -:math:`q_{snwcp,\, ice}` (section 7.7). - -Water Content -^^^^^^^^^^^^^^^^^^^ - -The conservation equation for mass of water in snow layers is - -.. math:: - :label: 7.26) - - \frac{\partial w_{liq,\, i} }{\partial t} =\left(q_{liq,\, i-1} -q_{liq,\, i} \right)+\frac{\left(\Delta w_{liq,\, i} \right)_{p} }{\Delta t} - -where :math:`q_{liq,\, i-1}` is the flow of liquid water into layer -:math:`i` from the layer above, :math:`q_{liq,\, i}` is the flow of -water out of layer :math:`i` to the layer below, -:math:`{\left(\Delta w_{liq,\, i} \right)_{p} \mathord{\left/ {\vphantom {\left(\Delta w_{liq,\, i} \right)_{p} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` -is the change in liquid water due to phase change (melting rate) -(section 6.2). For the top snow layer only, - -.. math:: - :label: 7.27) - - q_{liq,\, i-1} =f_{sno} \left(q_{grnd,\, liq} +\left(q_{sdew} -q_{seva} \right)\right) - -where :math:`q_{grnd,\, liq}` is the rate of liquid precipitation -reaching the snow (section 7.1), :math:`q_{seva}` is the evaporation of -liquid water and :math:`q_{sdew}` is the liquid dew (section 5.4). -After surface fluxes and snow/soil temperatures have been determined -(Chapters 5 and 6), :math:`w_{liq,\, snl+1}` is updated for the liquid -precipitation reaching the ground and dew or evaporation as - -.. math:: - :label: 7.28) - - w_{liq,\, snl+1}^{n+1} =w_{liq,\, snl+1}^{n} +f_{sno} \left(q_{grnd,\, liq} +q_{sdew} -q_{seva} \right)\Delta t. - -When the liquid water within a snow layer exceeds the layer’s holding -capacity, the excess water is added to the underlying layer, limited by -the effective porosity (:math:`1-\theta _{ice}` ) of the layer. The flow -of water is assumed to be zero (:math:`q_{liq,\, i} =0`) if the -effective porosity of either of the two layers -(:math:`1-\theta _{ice,\, i} {\rm \; and\; }1-\theta _{ice,\, i+1}` ) is -less than :math:`\theta _{imp} =0.05`, the water impermeable volumetric -water content. Thus, water flow between layers, :math:`q_{liq,\, i}` , -for layers :math:`i=snl+1,\ldots ,0`, is initially calculated as - -.. math:: - :label: ZEqnNum767577 - - q_{liq,\, i} =\frac{\rho _{liq} \left[\theta _{liq,\, i} -S_{r} \left(1-\theta _{ice,\, i} \right)\right]f_{sno} \Delta z_{i} }{\Delta t} \ge 0 - -where the volumetric liquid water :math:`\theta _{liq,\, i}` and ice -:math:`\theta _{ice,\, i}` contents are - -.. math:: - :label: 7.30) - - \theta _{ice,\, i} =\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } \le 1 - -.. math:: - :label: 7.31) - - \theta _{liq,\, i} =\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \le 1-\theta _{ice,\, i} , - -and :math:`S_{r} =0.033` is the irreducible water saturation (snow -holds a certain amount of liquid water due to capillary retention after -drainage has ceased (Anderson 1976)). The water holding capacity of the -underlying layer limits the flow of water :math:`q_{liq,\, i}` -calculated in equation , unless the underlying layer is the surface soil -layer, as - -.. math:: - :label: 7.32) - - q_{liq,\, i} \le \frac{\rho _{liq} \left[1-\theta _{ice,\, i+1} -\theta _{liq,\, i+1} \right]\Delta z_{i+1} }{\Delta t} \qquad i=snl+1,\ldots ,-1. - -The liquid water content :math:`w_{liq,\, i}` is updated as - -.. math:: - :label: ZEqnNum265203 - - w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\left(q_{i-1} -q_{i} \right)\Delta t. - -Equations - are solved sequentially from top (:math:`i=snl+1`) to -bottom (:math:`i=0`) snow layer in each time step. The total flow of -liquid water reaching the soil surface is then :math:`q_{liq,\, 0}` -which is used in the calculation of surface runoff and infiltration -(section 7.3). - -Black and organic carbon and mineral dust within snow -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Particles within snow originate from atmospheric aerosol deposition -(:math:`D_{sp}` in Table 2.3 (kg m\ :sup:`-2` s\ :sup:`-1`) -and influence snow radiative transfer (sections 3.2.1, 3.2.2, and -3.3.3). Particle masses and mixing ratios are represented with a simple -mass-conserving scheme. The model maintains masses of the following -eight particle species within each snow layer: hydrophilic black carbon, -hydrophobic black carbon, hydrophilic organic carbon, hydrophobic -organic carbon, and four species of mineral dust with the following -particle sizes: 0.1-1.0, 1.0-2.5, 2.5-5.0, and 5.0-10.0 :math:`\mu m`. -Each of these species has unique optical properties (Table 3.5) and -meltwater removal efficiencies (Table 7.1). - -The black carbon and organic carbon deposition rates described in Table -2.3 are combined into four categories as follows - -.. math:: - :label: 7.34) - - D_{bc,\, hphil} =D_{bc,\, dryhphil} +D_{bc,\, wethphil} - -.. math:: - :label: 7.35) - - D_{bc,\, hphob} =D_{bc,\, dryhphob} - -.. math:: - :label: 7.36) - - D_{oc,\, hphil} =D_{oc,\, dryhphil} +D_{oc,\, wethphil} - -.. math:: - :label: 7.37) - - D_{oc,\, hphob} =D_{oc,\, dryhphob} - -Deposited particles are assumed to be instantly mixed (homogeneously) -within the surface snow layer and are added after the inter-layer water -fluxes are computed (section 7.2.3) so that some aerosol is in the top -layer after deposition and is not immediately washed out before -radiative calculations are done. Particle masses are then redistributed -each time step based on meltwater drainage through the snow column -(section 7.2.3) and snow layer combination and subdivision (section -7.2.7). The change in mass of each of the particle species -:math:`\Delta m_{sp,\, i}` (kg m\ :sup:`-2`) is - -.. math:: - :label: 7.38) - - \Delta m_{sp,\, i} =\left[k_{sp} \left(q_{liq,\, i-1} c_{sp,\, i-1} -q_{liq,\, i} c_{i} \right)+D_{sp} \right]\Delta t - -where :math:`k_{sp}` is the meltwater scavenging efficiency that is -unique for each species (Table 7.1), :math:`q_{liq,\, i-1}` is the flow -of liquid water into layer :math:`i` from the layer above, -:math:`q_{liq,\, i}` is the flow of water out of layer :math:`i` into -the layer below (kg m\ :sup:`-2` s\ :sup:`-1`) (section -7.2.3), :math:`c_{sp,\, i-1}` and :math:`c_{sp,\, i}` are the particle -mass mixing ratios in layers :math:`i-1` and :math:`i` (kg -kg\ :sup:`-1`), :math:`D_{sp}` is the atmospheric deposition rate -(zero for all layers except layer :math:`snl+1`), and :math:`\Delta t` -is the model time step (s). The particle mass mixing ratio is - -.. math:: - :label: 7.39) - - c_{i} =\frac{m_{sp,\, i} }{w_{liq,\, i} +w_{ice,\, i} } . - -Values of :math:`k_{sp}` are partially derived from experiments -published by Conway et al. (1996). Particles masses are re-distributed -proportionately with snow mass when layers are combined or divided, thus -conserving particle mass within the snow column. The mass of particles -carried out with meltwater through the bottom snow layer is assumed to -be permanently lost from the snowpack, and is not maintained within the -model. - -Table 7.1. Meltwater scavenging efficiency for particles within snow - -+------------------------------------------+-------------------+ -| Species | :math:`k_{sp}` | -+==========================================+===================+ -| Hydrophilic black carbon | 0.20 | -+------------------------------------------+-------------------+ -| Hydrophobic black carbon | 0.03 | -+------------------------------------------+-------------------+ -| Hydrophilic organic carbon | 0.20 | -+------------------------------------------+-------------------+ -| Hydrophobic organic carbon | 0.03 | -+------------------------------------------+-------------------+ -| Dust species 1 (0.1-1.0 :math:`\mu m`) | 0.02 | -+------------------------------------------+-------------------+ -| Dust species 2 (1.0-2.5 :math:`\mu m`) | 0.02 | -+------------------------------------------+-------------------+ -| Dust species 3 (2.5-5.0 :math:`\mu m`) | 0.01 | -+------------------------------------------+-------------------+ -| Dust species 4 (5.0-10.0 :math:`\mu m`) | 0.01 | -+------------------------------------------+-------------------+ - -Initialization of snow layer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If there are no existing snow layers (:math:`snl+1=1`) but -:math:`z_{sno} \ge 0.01` m after accounting for solid precipitation -:math:`q_{sno}` , then a snow layer is initialized (:math:`snl=-1`) as -follows - -.. math:: - :label: 7.40) - - \begin{array}{l} {\Delta z_{0} =z_{sno} } \\ {z_{o} =-0.5\Delta z_{0} } \\ {z_{h,\, -1} =-\Delta z_{0} } \\ {T_{0} =\min \left(T_{f} ,T_{atm} \right)} \\ {w_{ice,\, 0} =W_{sno} } \\ {w_{liq,\, 0} =0} \end{array}. - -Snow Compaction -^^^^^^^^^^^^^^^^^^^^^ - -Snow compaction is initiated after the soil hydrology calculations -[surface runoff (section 7.3), infiltration (section 7.3), soil water -(section 7.4), groundwater-soilwater interactions (section 7.6)] are -complete. Compaction of snow includes three types of processes: -destructive metamorphism of new snow (crystal breakdown due to wind or -thermodynamic stress); snow load or overburden (pressure); and melting -(changes in snow structure due to melt-freeze cycles plus changes in -crystals due to liquid water). The total fractional compaction rate for -each snow layer :math:`C_{R,\, i}` (s\ :sup:`-1`) is the sum of the -three compaction processes - -.. math:: - :label: 7.41) - - C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} . - -Compaction is not allowed if the layer is saturated - -.. math:: - :label: 7.42) - - 1-\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } +\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \right)\le 0.001 - -or if the ice content is below a minimum value -(:math:`w_{ice,\, i} \le 0.1`). - -Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (CityplaceAnderson 1976) - -.. math:: - :label: 7.43) - - C_{R1,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{metamorphism} =-c_{3} c_{1} c_{2} \exp \left[-c_{4} \left(T_{f} -T_{i} \right)\right] - -where :math:`c_{3} =2.777\times 10^{-6}` (s\ :sup:`-1`) is the fractional compaction rate for :math:`T_{i} =T_{f}`, :math:`c_{4} =0.04` K\ :sup:`-1`, and - -.. math:: - :label: 7.44) - - c_{1} & = 1\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 100{\rm \; kg\; m}^{{\rm -3}} \\ - c_{1} & = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -100\right)\right]\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >100{\rm \; kg\; m}^{{\rm -3}} \\ - c_{2} & = 2\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } >0.01 \\ - c_{2} & = 1\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } \le 0.01 - -where -:math:`{w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` -and -:math:`{w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` -are the bulk densities of liquid water and ice (kg m\ :sup:`-3`). - -The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (CityplaceAnderson 1976) - -.. math:: - :label: 7.45) - - C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } - -where :math:`\eta` is a viscosity coefficient (kg s m\ :sup:`-2`) that varies with density and temperature as - -.. math:: - :label: 7.46) - - \eta =\eta _{0} \exp \left[c_{5} \left(T_{f} -T_{i} \right)+c_{6} \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \right] - -where :math:`\eta _{0} =9\times 10^{5}` kg s m\ :sup:`-2`, and -:math:`c_{5} =0.08` K\ :sup:`-1`, :math:`c_{6} =0.023` -m\ :sup:`3` kg\ :sup:`-1` are constants. The snow load -pressure :math:`P_{s,\, i}` is calculated for each layer as the sum of -the ice :math:`w_{ice,\, i}` and liquid water contents -:math:`w_{liq,\, i}` of the layers above plus half the ice and liquid -water contents of the layer being compacted - -.. math:: - :label: 7.47) - - P_{s,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{2} +\sum _{j=snl+1}^{j=i-1}\left(w_{ice,\, j} +w_{liq,\, j} \right) . - -The compaction rate due to melting :math:`C_{R3,\; i}` (s\ :sup:`-1`) is taken to be the ratio of the change in snow ice -mass after the melting to the mass before melting - -.. math:: - :label: 7.48) - - C_{R3,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} =-\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) - -and melting is identified during the phase change calculations (section -6.2). Because snow depth is defined as the average depth of the snow -covered area, the snow depth must also be updated for changes in -:math:`f_{sno}` . - -.. math:: - :label: 7.49) - - C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) - -The snow layer thickness after compaction is then - -.. math:: - :label: 7.50) - - \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). - -Snow Layer Combination and Subdivision -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After the determination of snow temperature including phase change -(Chapter 6), snow hydrology (sections 7.2.2, 7.2.3, and 7.2.4), and the -compaction calculations , the number of snow layers is adjusted by -either combining or subdividing layers. The combination and subdivision -of snow layers is based on Jordan (1991). - -7.2.7.1 Combination -''''''''''''''''''' - -If a snow layer has nearly melted or if its thickness -:math:`\Delta z_{i}` is less than the prescribed minimum thickness -:math:`\Delta z_{\min }` (Table 7.2), the layer is combined with a -neighboring layer. The overlying or underlying layer is selected as the -neighboring layer according to the following rules - -#. If the top layer is being removed, it is combined with the underlying - layer - -#. If the underlying layer is not snow (i.e., it is the top soil layer), - the layer is combined with the overlying layer - -#. If the layer is nearly completely melted, the layer is combined with - the underlying layer - -#. If none of the above rules apply, the layer is combined with the - thinnest neighboring layer. - -A first pass is made through all snow layers to determine if any layer -is nearly melted (:math:`w_{ice,\, i} \le 0.1`). If so, the remaining -liquid water and ice content of layer :math:`i` is combined with the -underlying neighbor :math:`i+1` as - -.. math:: - :label: 7.51) - - w_{liq,\, i+1} =w_{liq,\, i+1} +w_{liq,\, i} - -.. math:: - :label: 7.52) - - w_{ice,\, i+1} =w_{ice,\, i+1} +w_{ice,\, i} . - -This includes the snow layer directly above the top soil layer. In this -case, the liquid water and ice content of the melted snow layer is added -to the contents of the top soil layer. The layer properties, -:math:`T_{i}` , :math:`w_{ice,\, i}` , :math:`w_{liq,\, i}` , -:math:`\Delta z_{i}` , are then re-indexed so that the layers above the -eliminated layer are shifted down by one and the number of snow layers -is decremented accordingly. - -At this point, if there are no explicit snow layers remaining -(:math:`snl=0`), the snow water equivalent :math:`W_{sno}` and snow -depth :math:`z_{sno}` are set to zero, otherwise, :math:`W_{sno}` and -:math:`z_{sno}` are re-calculated as - -.. math:: - :label: 7.53) - - W_{sno} =\sum _{i=snl+1}^{i=0}\left(w_{ice,\, i} +w_{liq,\, i} \right) - -.. math:: - :label: 7.54) - - z_{sno} =\sum _{i=snl+1}^{i=0}\Delta z_{i} . - -If the snow depth :math:`0`\ 1 | 0.03 | 0.02 | -+--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ -| 2 | 0.015 | 2 | :math:`>`\ 2 | 0.07 | 0.05 | -+--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ -| 3 | 0.025 | 3 | :math:`>`\ 3 | 0.18 | 0.11 | -+--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ -| 4 | 0.055 | 4 | :math:`>`\ 4 | 0.41 | 0.23 | -+--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ -| 5 (bottom) | 0.115 | 5 | - | - | - | -+--------------+-----------------------------+------------------+------------------+-----------------------------------------------+-----------------------------------------------+ - -The maximum snow layer thickness, :math:`\Delta z_{\max }` , depends on -the number of layers, :math:`N_{l}` and :math:`N_{u}` (section -7.2.7.2). - -7.2.7.2 Subdivision -''''''''''''''''''' - -The snow layers are subdivided when the layer thickness exceeds the -prescribed maximum thickness :math:`\Delta z_{\max }` with lower and -upper bounds that depend on the number of snow layers (Table 7.2). For -example, if there is only one layer, then the maximum thickness of that -layer is 0.03 m, however, if there is more than one layer, then the -maximum thickness of the top layer is 0.02 m. Layers are checked -sequentially from top to bottom for this limit. If there is only one -snow layer and its thickness is greater than 0.03 m (Table 7.2), the -layer is subdivided into two layers of equal thickness, liquid water and -ice contents, and temperature. If there is an existing layer below the -layer to be subdivided, the thickness :math:`\Delta z_{i}` , liquid -water and ice contents, :math:`w_{liq,\; i}` and :math:`w_{ice,\; i}` , -and temperature :math:`T_{i}` of the excess snow are combined with the -underlying layer according to equations -. If there is no underlying -layer after adjusting the layer for the excess snow, the layer is -subdivided into two layers of equal thickness, liquid water and ice -contents. The vertical snow temperature profile is maintained by -calculating the slope between the layer above the splitting layer -(:math:`T_{1}` ) and the splitting layer (:math:`T_{2}` ) and -constraining the new temperatures (:math:`T_{2}^{n+1}` , -:math:`T_{3}^{n+1}` ) to lie along this slope. The temperature of the -lower layer is first evaluated from - -.. math:: - :label: 7.62) - - T'_{3} =T_{2}^{n} -\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right), - -then adjusted as, - -.. math:: - :label: 7.63) - - \begin{array}{l} {T_{3}^{n+1} =T_{2}^{n} \qquad T'_{3} \ge T_{f} } \\ {T_{2}^{n+1} =T_{2}^{n} +\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right)\qquad T'_{3} T_{f} +2} \\ {50+1.7\left(T_{atm} -T_{f} +15\right)^{1.5} \qquad T_{f} -15T_{f}` ). In this case, the incoming solid precipitation +is assigned to the runoff term :math:`q_{rgwl}` (section :numref:`Runoff from glaciers and snow-capped surfaces`). + +In the second step, after surface fluxes and snow/soil temperatures have +been determined (Chapters :numref:`rst_Momentum, Sensible Heat, and Latent Heat +Fluxes` and :numref:`rst_Soil and Snow Temperatures`), +:math:`w_{ice,\, snl+1}` is updated for frost or sublimation as + +.. math:: + :label: ZEqnNum863244 + + w_{ice,\, snl+1}^{n+1} =w_{ice,\, snl+1}^{n} +f_{sno} \left(q_{frost} -q_{subl} \right)\Delta t. + +If :math:`w_{ice,\, snl+1}^{n+1} <0` upon solution of equation , the ice +content is reset to zero and the liquid water content +:math:`w_{liq,\, snl+1}` is reduced by the amount required to bring +:math:`w_{ice,\, snl+1}^{n+1}` up to zero. + +The snow water equivalent :math:`W_{sno}` is capped to not exceed 1000 +kg m\ :sup:`-2`. If the addition of :math:`q_{frost}` were to +result in :math:`W_{sno} >1000` kg m\ :sup:`-2`, the frost term +:math:`q_{frost}` is instead added to the ice runoff term +:math:`q_{snwcp,\, ice}` (section :numref:`Runoff from glaciers and snow-capped surfaces`). + +.. _Water Content: + +Water Content +^^^^^^^^^^^^^^^^^^^ + +The conservation equation for mass of water in snow layers is + +.. math:: + :label: 8.26) + + \frac{\partial w_{liq,\, i} }{\partial t} =\left(q_{liq,\, i-1} -q_{liq,\, i} \right)+\frac{\left(\Delta w_{liq,\, i} \right)_{p} }{\Delta t} + +where :math:`q_{liq,\, i-1}` is the flow of liquid water into layer +:math:`i` from the layer above, :math:`q_{liq,\, i}` is the flow of +water out of layer :math:`i` to the layer below, +:math:`{\left(\Delta w_{liq,\, i} \right)_{p} \mathord{\left/ {\vphantom {\left(\Delta w_{liq,\, i} \right)_{p} \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t}` +is the change in liquid water due to phase change (melting rate) +(section :numref:`Phase Change`). For the top snow layer only, + +.. math:: + :label: 8.27) + + q_{liq,\, i-1} =f_{sno} \left(q_{grnd,\, liq} +\left(q_{sdew} -q_{seva} \right)\right) + +where :math:`q_{grnd,\, liq}` is the rate of liquid precipitation +reaching the snow (section :numref:`Canopy Water`), :math:`q_{seva}` is the +evaporation of liquid water and :math:`q_{sdew}` is the liquid dew (section +5.4). After surface fluxes and snow/soil temperatures have been determined +(Chapters :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes` and +:numref:`rst_Soil and Snow Temperatures`), :math:`w_{liq,\, snl+1}` is +updated for the liquid precipitation reaching the ground and dew or +evaporation as + +.. math:: + :label: 8.28) + + w_{liq,\, snl+1}^{n+1} =w_{liq,\, snl+1}^{n} +f_{sno} \left(q_{grnd,\, liq} +q_{sdew} -q_{seva} \right)\Delta t. + +When the liquid water within a snow layer exceeds the layer’s holding +capacity, the excess water is added to the underlying layer, limited by +the effective porosity (:math:`1-\theta _{ice}` ) of the layer. The flow +of water is assumed to be zero (:math:`q_{liq,\, i} =0`) if the +effective porosity of either of the two layers +(:math:`1-\theta _{ice,\, i} {\rm \; and\; }1-\theta _{ice,\, i+1}` ) is +less than :math:`\theta _{imp} =0.05`, the water impermeable volumetric +water content. Thus, water flow between layers, :math:`q_{liq,\, i}` , +for layers :math:`i=snl+1,\ldots ,0`, is initially calculated as + +.. math:: + :label: ZEqnNum767577 + + q_{liq,\, i} =\frac{\rho _{liq} \left[\theta _{liq,\, i} -S_{r} \left(1-\theta _{ice,\, i} \right)\right]f_{sno} \Delta z_{i} }{\Delta t} \ge 0 + +where the volumetric liquid water :math:`\theta _{liq,\, i}` and ice +:math:`\theta _{ice,\, i}` contents are + +.. math:: + :label: 8.30) + + \theta _{ice,\, i} =\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } \le 1 + +.. math:: + :label: 8.31) + + \theta _{liq,\, i} =\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \le 1-\theta _{ice,\, i} , + +and :math:`S_{r} =0.033` is the irreducible water saturation (snow +holds a certain amount of liquid water due to capillary retention after +drainage has ceased (Anderson 1976)). The water holding capacity of the +underlying layer limits the flow of water :math:`q_{liq,\, i}` +calculated in equation , unless the underlying layer is the surface soil +layer, as + +.. math:: + :label: 8.32) + + q_{liq,\, i} \le \frac{\rho _{liq} \left[1-\theta _{ice,\, i+1} -\theta _{liq,\, i+1} \right]\Delta z_{i+1} }{\Delta t} \qquad i=snl+1,\ldots ,-1. + +The liquid water content :math:`w_{liq,\, i}` is updated as + +.. math:: + :label: ZEqnNum265203 + + w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\left(q_{i-1} -q_{i} \right)\Delta t. + +Equations - are solved sequentially from top (:math:`i=snl+1`) to +bottom (:math:`i=0`) snow layer in each time step. The total flow of +liquid water reaching the soil surface is then :math:`q_{liq,\, 0}` +which is used in the calculation of surface runoff and infiltration +(sections :numref:`Surface Runoff` and :numref:`Infiltration`). + +.. _Black and organic carbon and mineral dust within snow: + +Black and organic carbon and mineral dust within snow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Particles within snow originate from atmospheric aerosol deposition +(:math:`D_{sp}` in Table 2.3 (kg m\ :sup:`-2` s\ :sup:`-1`) +and influence snow radiative transfer (sections :numref:`Snow Albedo`, +:numref:`Snowpack Optical Properties`, and :numref:`Snow Aging`). +Particle masses and mixing ratios are represented with a simple +mass-conserving scheme. The model maintains masses of the following +eight particle species within each snow layer: hydrophilic black carbon, +hydrophobic black carbon, hydrophilic organic carbon, hydrophobic +organic carbon, and four species of mineral dust with the following +particle sizes: 0.1-1.0, 1.0-2.5, 2.5-5.0, and 5.0-10.0 :math:`\mu m`. +Each of these species has unique optical properties (Table 3.5) and +meltwater removal efficiencies (:numref:`Table Meltwater scavenging`). + +The black carbon and organic carbon deposition rates described in Table +2.3 are combined into four categories as follows + +.. math:: + :label: 8.34) + + D_{bc,\, hphil} =D_{bc,\, dryhphil} +D_{bc,\, wethphil} + +.. math:: + :label: 8.35) + + D_{bc,\, hphob} =D_{bc,\, dryhphob} + +.. math:: + :label: 8.36) + + D_{oc,\, hphil} =D_{oc,\, dryhphil} +D_{oc,\, wethphil} + +.. math:: + :label: 8.37) + + D_{oc,\, hphob} =D_{oc,\, dryhphob} + +Deposited particles are assumed to be instantly mixed (homogeneously) +within the surface snow layer and are added after the inter-layer water +fluxes are computed (section :numref:`Water Content`) so that some aerosol is in the top +layer after deposition and is not immediately washed out before radiative +calculations are done. Particle masses are then redistributed each time +step based on meltwater drainage through the snow column (section +:numref:`Water Content`) and snow layer combination and subdivision +(section :numref:`Snow Layer Combination and Subdivision`). The change in +mass of each of the particle species :math:`\Delta m_{sp,\, i}` +(kg m\ :sup:`-2`) is + +.. math:: + :label: 8.38) + + \Delta m_{sp,\, i} =\left[k_{sp} \left(q_{liq,\, i-1} c_{sp,\, i-1} -q_{liq,\, i} c_{i} \right)+D_{sp} \right]\Delta t + +where :math:`k_{sp}` is the meltwater scavenging efficiency that is +unique for each species (:numref:`Table Meltwater scavenging`), :math:`q_{liq,\, i-1}` is the flow +of liquid water into layer :math:`i` from the layer above, +:math:`q_{liq,\, i}` is the flow of water out of layer :math:`i` into +the layer below (kg m\ :sup:`-2` s\ :sup:`-1`) (section +:numref:`Water Content`), :math:`c_{sp,\, i-1}` and :math:`c_{sp,\, i}` are the particle +mass mixing ratios in layers :math:`i-1` and :math:`i` (kg +kg\ :sup:`-1`), :math:`D_{sp}` is the atmospheric deposition rate +(zero for all layers except layer :math:`snl+1`), and :math:`\Delta t` +is the model time step (s). The particle mass mixing ratio is + +.. math:: + :label: 8.39) + + c_{i} =\frac{m_{sp,\, i} }{w_{liq,\, i} +w_{ice,\, i} } . + +Values of :math:`k_{sp}` are partially derived from experiments +published by Conway et al. (1996). Particles masses are re-distributed +proportionately with snow mass when layers are combined or divided, thus +conserving particle mass within the snow column. The mass of particles +carried out with meltwater through the bottom snow layer is assumed to +be permanently lost from the snowpack, and is not maintained within the +model. + +.. _Table Meltwater scavenging: + +.. table:: Meltwater scavenging efficiency for particles within snow + + +------------------------------------------+-------------------+ + | Species | :math:`k_{sp}` | + +==========================================+===================+ + | Hydrophilic black carbon | 0.20 | + +------------------------------------------+-------------------+ + | Hydrophobic black carbon | 0.03 | + +------------------------------------------+-------------------+ + | Hydrophilic organic carbon | 0.20 | + +------------------------------------------+-------------------+ + | Hydrophobic organic carbon | 0.03 | + +------------------------------------------+-------------------+ + | Dust species 1 (0.1-1.0 :math:`\mu m`) | 0.02 | + +------------------------------------------+-------------------+ + | Dust species 2 (1.0-2.5 :math:`\mu m`) | 0.02 | + +------------------------------------------+-------------------+ + | Dust species 3 (2.5-5.0 :math:`\mu m`) | 0.01 | + +------------------------------------------+-------------------+ + | Dust species 4 (5.0-10.0 :math:`\mu m`) | 0.01 | + +------------------------------------------+-------------------+ + +.. _Initialization of snow layer: + +Initialization of snow layer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If there are no existing snow layers (:math:`snl+1=1`) but +:math:`z_{sno} \ge 0.01` m after accounting for solid precipitation +:math:`q_{sno}` , then a snow layer is initialized (:math:`snl=-1`) as +follows + +.. math:: + :label: 8.40) + + \begin{array}{l} {\Delta z_{0} =z_{sno} } \\ {z_{o} =-0.5\Delta z_{0} } \\ {z_{h,\, -1} =-\Delta z_{0} } \\ {T_{0} =\min \left(T_{f} ,T_{atm} \right)} \\ {w_{ice,\, 0} =W_{sno} } \\ {w_{liq,\, 0} =0} \end{array}. + +.. _Snow Compaction: + +Snow Compaction +^^^^^^^^^^^^^^^^^^^^^ + +Snow compaction is initiated after the soil hydrology calculations +[surface runoff (section :numref:`Surface Runoff`), infiltration (section +:numref:`Infiltration`), soil water (section :numref:`Soil Water`), +groundwater-soilwater interactions (section 8.6)] are +complete. Compaction of snow includes three types of processes: +destructive metamorphism of new snow (crystal breakdown due to wind or +thermodynamic stress); snow load or overburden (pressure); and melting +(changes in snow structure due to melt-freeze cycles plus changes in +crystals due to liquid water). The total fractional compaction rate for +each snow layer :math:`C_{R,\, i}` (s\ :sup:`-1`) is the sum of the +three compaction processes + +.. math:: + :label: 8.41) + + C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} . + +Compaction is not allowed if the layer is saturated + +.. math:: + :label: 8.42) + + 1-\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } +\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \right)\le 0.001 + +or if the ice content is below a minimum value +(:math:`w_{ice,\, i} \le 0.1`). + +Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (CityplaceAnderson 1976) + +.. math:: + :label: 8.43) + + C_{R1,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{metamorphism} =-c_{3} c_{1} c_{2} \exp \left[-c_{4} \left(T_{f} -T_{i} \right)\right] + +where :math:`c_{3} =2.777\times 10^{-6}` (s\ :sup:`-1`) is the fractional compaction rate for :math:`T_{i} =T_{f}`, :math:`c_{4} =0.04` K\ :sup:`-1`, and + +.. math:: + :label: 8.44) + + c_{1} & = 1\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{1} & = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -100\right)\right]\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{2} & = 2\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } >0.01 \\ + c_{2} & = 1\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } \le 0.01 + +where +:math:`{w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` +and +:math:`{w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` +are the bulk densities of liquid water and ice (kg m\ :sup:`-3`). + +The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (CityplaceAnderson 1976) + +.. math:: + :label: 8.45) + + C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } + +where :math:`\eta` is a viscosity coefficient (kg s m\ :sup:`-2`) that varies with density and temperature as + +.. math:: + :label: 8.46) + + \eta =\eta _{0} \exp \left[c_{5} \left(T_{f} -T_{i} \right)+c_{6} \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \right] + +where :math:`\eta _{0} =9\times 10^{5}` kg s m\ :sup:`-2`, and +:math:`c_{5} =0.08` K\ :sup:`-1`, :math:`c_{6} =0.023` +m\ :sup:`3` kg\ :sup:`-1` are constants. The snow load +pressure :math:`P_{s,\, i}` is calculated for each layer as the sum of +the ice :math:`w_{ice,\, i}` and liquid water contents +:math:`w_{liq,\, i}` of the layers above plus half the ice and liquid +water contents of the layer being compacted + +.. math:: + :label: 8.47) + + P_{s,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{2} +\sum _{j=snl+1}^{j=i-1}\left(w_{ice,\, j} +w_{liq,\, j} \right) . + +The compaction rate due to melting :math:`C_{R3,\; i}` (s\ :sup:`-1`) is taken to be the ratio of the change in snow ice +mass after the melting to the mass before melting + +.. math:: + :label: 8.48) + + C_{R3,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} =-\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) + +and melting is identified during the phase change calculations (section +:numref:`Phase Change`). Because snow depth is defined as the average depth of the snow +covered area, the snow depth must also be updated for changes in +:math:`f_{sno}` . + +.. math:: + :label: 8.49) + + C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) + +The snow layer thickness after compaction is then + +.. math:: + :label: 8.50) + + \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). + +.. _Snow Layer Combination and Subdivision: + +Snow Layer Combination and Subdivision +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After the determination of snow temperature including phase change(Chapter +:numref:`rst_Soil and Snow Temperatures`), snow hydrology (Chapter +:numref:`rst_Snow Hydrology`), and the compaction calculations (section +:numref:`Snow Compaction`) , the number of snow layers is adjusted by +either combining or subdividing layers. The combination and subdivision +of snow layers is based on Jordan (1991). + +.. _Combination: + +Combination +''''''''''''''''''' + +If a snow layer has nearly melted or if its thickness +:math:`\Delta z_{i}` is less than the prescribed minimum thickness +:math:`\Delta z_{\min }` (:numref:`Table snow layer thickness`), the layer is combined with a +neighboring layer. The overlying or underlying layer is selected as the +neighboring layer according to the following rules + +#. If the top layer is being removed, it is combined with the underlying + layer + +#. If the underlying layer is not snow (i.e., it is the top soil layer), + the layer is combined with the overlying layer + +#. If the layer is nearly completely melted, the layer is combined with + the underlying layer + +#. If none of the above rules apply, the layer is combined with the + thinnest neighboring layer. + +A first pass is made through all snow layers to determine if any layer +is nearly melted (:math:`w_{ice,\, i} \le 0.1`). If so, the remaining +liquid water and ice content of layer :math:`i` is combined with the +underlying neighbor :math:`i+1` as + +.. math:: + :label: 8.51) + + w_{liq,\, i+1} =w_{liq,\, i+1} +w_{liq,\, i} + +.. math:: + :label: 8.52) + + w_{ice,\, i+1} =w_{ice,\, i+1} +w_{ice,\, i} . + +This includes the snow layer directly above the top soil layer. In this +case, the liquid water and ice content of the melted snow layer is added +to the contents of the top soil layer. The layer properties, +:math:`T_{i}` , :math:`w_{ice,\, i}` , :math:`w_{liq,\, i}` , +:math:`\Delta z_{i}` , are then re-indexed so that the layers above the +eliminated layer are shifted down by one and the number of snow layers +is decremented accordingly. + +At this point, if there are no explicit snow layers remaining +(:math:`snl=0`), the snow water equivalent :math:`W_{sno}` and snow +depth :math:`z_{sno}` are set to zero, otherwise, :math:`W_{sno}` and +:math:`z_{sno}` are re-calculated as + +.. math:: + :label: 8.53) + + W_{sno} =\sum _{i=snl+1}^{i=0}\left(w_{ice,\, i} +w_{liq,\, i} \right) + +.. math:: + :label: 8.54) + + z_{sno} =\sum _{i=snl+1}^{i=0}\Delta z_{i} . + +If the snow depth :math:`0`\ 1 | 0.03 | 0.02 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 2 | 0.015 | 2 | :math:`>`\ 2 | 0.07 | 0.05 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 3 | 0.025 | 3 | :math:`>`\ 3 | 0.18 | 0.11 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 4 | 0.055 | 4 | :math:`>`\ 4 | 0.41 | 0.23 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 5 (bottom) | 0.115 | 5 | - | - | - | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + +The maximum snow layer thickness, :math:`\Delta z_{\max }` , depends on +the number of layers, :math:`N_{l}` and :math:`N_{u}` (section +:numref:`Subdivision`). + +.. _Subdivision: + +Subdivision +''''''''''''''''''' + +The snow layers are subdivided when the layer thickness exceeds the +prescribed maximum thickness :math:`\Delta z_{\max }` with lower and +upper bounds that depend on the number of snow layers (numref:`Table snow layer thickness`). For +example, if there is only one layer, then the maximum thickness of that +layer is 0.03 m, however, if there is more than one layer, then the +maximum thickness of the top layer is 0.02 m. Layers are checked +sequentially from top to bottom for this limit. If there is only one +snow layer and its thickness is greater than 0.03 m (:numref:`Table snow layer thickness`), the +layer is subdivided into two layers of equal thickness, liquid water and +ice contents, and temperature. If there is an existing layer below the +layer to be subdivided, the thickness :math:`\Delta z_{i}` , liquid +water and ice contents, :math:`w_{liq,\; i}` and :math:`w_{ice,\; i}` , +and temperature :math:`T_{i}` of the excess snow are combined with the +underlying layer according to equations -. If there is no underlying +layer after adjusting the layer for the excess snow, the layer is +subdivided into two layers of equal thickness, liquid water and ice +contents. The vertical snow temperature profile is maintained by +calculating the slope between the layer above the splitting layer +(:math:`T_{1}` ) and the splitting layer (:math:`T_{2}` ) and +constraining the new temperatures (:math:`T_{2}^{n+1}` , +:math:`T_{3}^{n+1}` ) to lie along this slope. The temperature of the +lower layer is first evaluated from + +.. math:: + :label: 8.62) + + T'_{3} =T_{2}^{n} -\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right), + +then adjusted as, + +.. math:: + :label: 8.63) + + \begin{array}{l} {T_{3}^{n+1} =T_{2}^{n} \qquad T'_{3} \ge T_{f} } \\ {T_{2}^{n+1} =T_{2}^{n} +\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right)\qquad T'_{3} Date: Fri, 19 May 2017 14:17:31 -0600 Subject: [PATCH 015/255] labeled references --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 593 ++++++++-------- .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 399 +++++------ .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 267 +++----- .../tech_note/Lake/CLM50_Tech_Note_Lake.rst | 66 +- .../Offline/CLM50_Tech_Note_Offline.rst | 41 +- .../CLM50_Tech_Note_Radiative_Fluxes.rst | 4 + .../References/CLM50_Tech_Note_References.rst | 632 +++++++++++++++++- .../CLM50_Tech_Note_Snow_Hydrology.rst | 25 +- ...CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 2 +- 9 files changed, 1328 insertions(+), 701 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 888c379382..959a8cbd73 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -3,15 +3,20 @@ Surface Characterization and Model Input Requirements ======================================================== +.. _Surface Characterization: + Surface Characterization ----------------------------- +.. _Surface Heterogeneity and Data Structure: + Surface Heterogeneity and Data Structure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Spatial land surface heterogeneity in CLM is represented as a nested subgrid hierarchy in which grid cells are composed of multiple land -units, snow/soil columns, and PFTs (Figure 2.1). Each grid cell can have +units, snow/soil columns, and PFTs (:numref:`Figure CLM subgrid hierarchy`). +Each grid cell can have a different number of land units, each land unit can have a different number of columns, and each column can have multiple PFTs. The first subgrid level, the land unit, is intended to capture the broadest @@ -43,7 +48,11 @@ single crop occupying each column. The urban land units have five columns (roof, sunlit walls and shaded walls, and pervious and impervious canyon floor) (Oleson et al. 2010b). -Figure 2.1. Configuration of the CLM subgrid hierarchy. +.. _Figure CLM subgrid hierarchy: + +.. Figure:: image1.png + + Configuration of the CLM subgrid hierarchy. Note that the Crop land unit is only used when the model is run with the crop model active. Abbreviations: TBD – Tall Building District; HD – @@ -51,8 +60,6 @@ High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C Crop, V – Vegetated, PFT – Plant Functional Type, I – Irrigated, U – Unirrigated . -.. image:: image1.png - The third subgrid level is referred to as the PFT level, but it also includes the treatment for bare ground. It is intended to capture the biogeophysical and biogeochemical differences between broad categories @@ -62,7 +69,7 @@ structure may coexist on a single column. All fluxes to and from the surface are defined at the PFT level, as are the vegetation state variables (e.g. vegetation temperature and canopy water storage). On the crop land unit, several different crop types can be represented on each -crop land unit column (see Chapter 20 for details). +crop land unit column (see Chapter :numref:`rst_Crops and Irrigation` for details). In addition to state and flux variable data structures for conserved components at each subgrid level (e.g., energy, water, carbon), each @@ -76,7 +83,8 @@ and the fraction of canopy that is wet are defined as physical state variables at the PFT level. The standard configuration of the model subgrid hierarchy is illustrated -in Figure 2.1. Here, only four PFTs are shown associated with the single +in :numref:`Figure CLM subgrid hierarchy`. Here, only four PFTs are shown +associated with the single column beneath the vegetated land unit but up to sixteen are possible. The crop land unit is present only when the crop model is active. @@ -90,13 +98,17 @@ by computing a weighted sum of the desired quantity over all PFTs whose weighting depends on the PFT area relative to all PFTs, unless otherwise noted in the text. +.. _Vegetation Composition: + Vegetation Composition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Vegetated surfaces are comprised of up to 15 possible plant functional -types (PFTs) plus bare ground (Table 2.1). An additional PFT is -added if the irrigation model is active and six additional PFTs are -added if the crop model is active (Chapter 20). These plant types differ +types (PFTs) plus bare ground (:numref:`Table Plant functional types`). An +additional PFT is added if +the irrigation model is active and six additional PFTs are added if the +crop model is active (Chapter :numref:`rst_Crops and Irrigation`). These +plant types differ in leaf and stem optical properties that determine reflection, transmittance, and absorption of solar radiation (Table 3.1), root distribution parameters that control the uptake of water from the soil @@ -109,129 +121,141 @@ within a grid cell can either be prescribed as time-invariant fields evolve with time if the model is run in transient landcover mode (Chapter 21). -Table 2.1. Plant functional types - -+--------------------------------------------------------------+-------------------+ -| Plant functional type | Acronym | -+==============================================================+===================+ -| Needleleaf evergreen tree – temperate | NET Temperate | -+--------------------------------------------------------------+-------------------+ -| Needleleaf evergreen tree - boreal | NET Boreal | -+--------------------------------------------------------------+-------------------+ -| Needleleaf deciduous tree – boreal | NDT Boreal | -+--------------------------------------------------------------+-------------------+ -| Broadleaf evergreen tree – tropical | BET Tropical | -+--------------------------------------------------------------+-------------------+ -| Broadleaf evergreen tree – temperate | BET Temperate | -+--------------------------------------------------------------+-------------------+ -| Broadleaf deciduous tree – tropical | BDT Tropical | -+--------------------------------------------------------------+-------------------+ -| Broadleaf deciduous tree – temperate | BDT Temperate | -+--------------------------------------------------------------+-------------------+ -| Broadleaf deciduous tree – boreal | BDT Boreal | -+--------------------------------------------------------------+-------------------+ -| Broadleaf evergreen shrub - temperate | BES Temperate | -+--------------------------------------------------------------+-------------------+ -| Broadleaf deciduous shrub – temperate | BDS Temperate | -+--------------------------------------------------------------+-------------------+ -| Broadleaf deciduous shrub – boreal | BDS Boreal | -+--------------------------------------------------------------+-------------------+ -| C\ :sub:`3` arctic grass | - | -+--------------------------------------------------------------+-------------------+ -| C\ :sub:`3` grass | - | -+--------------------------------------------------------------+-------------------+ -| C\ :sub:`4` grass | - | -+--------------------------------------------------------------+-------------------+ -| C\ :sub:`3` Unmanaged Rainfed Crop | Crop R | -+--------------------------------------------------------------+-------------------+ -| :sup:`1`\ C\ :sub:`3` Unmanaged Irrigated Crop | Crop I | -+--------------------------------------------------------------+-------------------+ -| :sup:`2`\ Rainfed Corn | Corn R | -+--------------------------------------------------------------+-------------------+ -| :sup:`2`\ Irrigated Corn | Corn I | -+--------------------------------------------------------------+-------------------+ -| :sup:`2`\ Rainfed Temperate Cereals | Temp Cereal R | -+--------------------------------------------------------------+-------------------+ -| :sup:`2`\ Irrigated Temperate Cereals | Temp Cereal I | -+--------------------------------------------------------------+-------------------+ -| :sup:`3`\ Rainfed Winter Cereals | Winter Cereal R | -+--------------------------------------------------------------+-------------------+ -| :sup:`3`\ Irrigated Winter Cereals | Winter Cereal I | -+--------------------------------------------------------------+-------------------+ -| :sup:`2`\ Rainfed Soybean | Soybean R | -+--------------------------------------------------------------+-------------------+ -| :sup:`2`\ Irrigated Soybean | Soybean I | -+--------------------------------------------------------------+-------------------+ - -:sup:`1`\ Only used if irrigation is active (Chapter 20). -:sup:`2`\ Only used if crop model is active (Chapter 20). -:sup:`3`\ Reserved for future implementations of crop model (Chapter 20). +.. _Table Plant functional types: + +.. table:: Plant functional types + + +--------------------------------------------------------------+-------------------+ + | Plant functional type | Acronym | + +==============================================================+===================+ + | Needleleaf evergreen tree – temperate | NET Temperate | + +--------------------------------------------------------------+-------------------+ + | Needleleaf evergreen tree - boreal | NET Boreal | + +--------------------------------------------------------------+-------------------+ + | Needleleaf deciduous tree – boreal | NDT Boreal | + +--------------------------------------------------------------+-------------------+ + | Broadleaf evergreen tree – tropical | BET Tropical | + +--------------------------------------------------------------+-------------------+ + | Broadleaf evergreen tree – temperate | BET Temperate | + +--------------------------------------------------------------+-------------------+ + | Broadleaf deciduous tree – tropical | BDT Tropical | + +--------------------------------------------------------------+-------------------+ + | Broadleaf deciduous tree – temperate | BDT Temperate | + +--------------------------------------------------------------+-------------------+ + | Broadleaf deciduous tree – boreal | BDT Boreal | + +--------------------------------------------------------------+-------------------+ + | Broadleaf evergreen shrub - temperate | BES Temperate | + +--------------------------------------------------------------+-------------------+ + | Broadleaf deciduous shrub – temperate | BDS Temperate | + +--------------------------------------------------------------+-------------------+ + | Broadleaf deciduous shrub – boreal | BDS Boreal | + +--------------------------------------------------------------+-------------------+ + | C\ :sub:`3` arctic grass | - | + +--------------------------------------------------------------+-------------------+ + | C\ :sub:`3` grass | - | + +--------------------------------------------------------------+-------------------+ + | C\ :sub:`4` grass | - | + +--------------------------------------------------------------+-------------------+ + | C\ :sub:`3` Unmanaged Rainfed Crop | Crop R | + +--------------------------------------------------------------+-------------------+ + | :sup:`1`\ C\ :sub:`3` Unmanaged Irrigated Crop | Crop I | + +--------------------------------------------------------------+-------------------+ + | :sup:`2`\ Rainfed Corn | Corn R | + +--------------------------------------------------------------+-------------------+ + | :sup:`2`\ Irrigated Corn | Corn I | + +--------------------------------------------------------------+-------------------+ + | :sup:`2`\ Rainfed Temperate Cereals | Temp Cereal R | + +--------------------------------------------------------------+-------------------+ + | :sup:`2`\ Irrigated Temperate Cereals | Temp Cereal I | + +--------------------------------------------------------------+-------------------+ + | :sup:`3`\ Rainfed Winter Cereals | Winter Cereal R | + +--------------------------------------------------------------+-------------------+ + | :sup:`3`\ Irrigated Winter Cereals | Winter Cereal I | + +--------------------------------------------------------------+-------------------+ + | :sup:`2`\ Rainfed Soybean | Soybean R | + +--------------------------------------------------------------+-------------------+ + | :sup:`2`\ Irrigated Soybean | Soybean I | + +--------------------------------------------------------------+-------------------+ + +:sup:`1`\ Only used if irrigation is active (Chapter :numref:`rst_Crops and Irrigation`). +:sup:`2`\ Only used if crop model is active (Chapter :numref:`rst_Crops and Irrigation`). +:sup:`3`\ Reserved for future implementations of crop model (Chapter :numref:`rst_Crops and Irrigation`). + +.. _Vegetation Structure: Vegetation Structure ^^^^^^^^^^^^^^^^^^^^^^^^^^ Vegetation structure is defined by leaf and stem area indices -(:math:`L,\, S`) and canopy top and bottom heights (:math:`z_{top}`,\ :math:`z_{bot}` ) (Table 2.2). Separate leaf and -stem area indices and canopy heights are prescribed or calculated for each PFT. Daily leaf and stem area indices are obtained from gridded -datasets of monthly values (section 2.2.3). Canopy top and bottom heights are also obtained from gridded datasets. However, these are -currently invariant in space and time and were obtained from PFT-specific values (Bonan et al. 2002a). When the biogeochemistry model -is active, vegetation state (LAI, SAI, canopy top and bottom heights) are calculated prognostically (see Chapter 14). - -Table 2.2. Prescribed plant functional type heights - -+-----------------------------------+------------------------+------------------------+ -| Plant functional type | :math:`z_{top}` (m) | :math:`z_{bot}` (m) | -+===================================+========================+========================+ -| NET Temperate | 17 | 8.5 | -+-----------------------------------+------------------------+------------------------+ -| NET Boreal | 17 | 8.5 | -+-----------------------------------+------------------------+------------------------+ -| NDT Boreal | 14 | 7 | -+-----------------------------------+------------------------+------------------------+ -| BET Tropical | 35 | 1 | -+-----------------------------------+------------------------+------------------------+ -| BET temperate | 35 | 1 | -+-----------------------------------+------------------------+------------------------+ -| BDT tropical | 18 | 10 | -+-----------------------------------+------------------------+------------------------+ -| BDT temperate | 20 | 11.5 | -+-----------------------------------+------------------------+------------------------+ -| BDT boreal | 20 | 11.5 | -+-----------------------------------+------------------------+------------------------+ -| BES temperate | 0.5 | 0.1 | -+-----------------------------------+------------------------+------------------------+ -| BDS temperate | 0.5 | 0.1 | -+-----------------------------------+------------------------+------------------------+ -| BDS boreal | 0.5 | 0.1 | -+-----------------------------------+------------------------+------------------------+ -| C\ :math:`{}_{3}` arctic grass | 0.5 | 0.01 | -+-----------------------------------+------------------------+------------------------+ -| C\ :math:`{}_{3}` grass | 0.5 | 0.01 | -+-----------------------------------+------------------------+------------------------+ -| C\ :math:`{}_{4}` grass | 0.5 | 0.01 | -+-----------------------------------+------------------------+------------------------+ -| Crop R | 0.5 | 0.01 | -+-----------------------------------+------------------------+------------------------+ -| Crop I | 0.5 | 0.01 | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Corn R | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Corn I | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Temp Cereal R | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Temp Cereal I | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Winter Cereal R | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Winter Cereal I | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Soybean R | - | - | -+-----------------------------------+------------------------+------------------------+ -| :sup:`1`\ Soybean I | - | - | -+-----------------------------------+------------------------+------------------------+ - -:sup:`1`\ Determined by the crop model (Chapter 20) +(:math:`L,\, S`) and canopy top and bottom heights (:math:`z_{top}`,\ :math:`z_{bot}` ) +(:numref:`Table Prescribed plant functional type heights`). Separate leaf and +stem area indices and canopy heights are prescribed or calculated for each PFT. Daily leaf +and stem area indices are obtained from griddeddatasets of monthly values (section +:numref:`Surface Data`). Canopy top and bottom heights are also obtained from gridded datasets. +However, these are currently invariant in space and time and were obtained from PFT-specific +values (:ref:`Bonan et al. 2002a `). When the biogeochemistry model is active, +vegetation state (LAI, SAI, canopy top and bottom heights) are calculated prognostically +(see Chapter :numref:`rst_Vegetation Phenology and Turnover`). + +.. _Table Prescribed plant functional type heights: + +.. table:: Prescribed plant functional type heights + + +-----------------------------------+------------------------+------------------------+ + | Plant functional type | :math:`z_{top}` (m) | :math:`z_{bot}` (m) | + +===================================+========================+========================+ + | NET Temperate | 17 | 8.5 | + +-----------------------------------+------------------------+------------------------+ + | NET Boreal | 17 | 8.5 | + +-----------------------------------+------------------------+------------------------+ + | NDT Boreal | 14 | 7 | + +-----------------------------------+------------------------+------------------------+ + | BET Tropical | 35 | 1 | + +-----------------------------------+------------------------+------------------------+ + | BET temperate | 35 | 1 | + +-----------------------------------+------------------------+------------------------+ + | BDT tropical | 18 | 10 | + +-----------------------------------+------------------------+------------------------+ + | BDT temperate | 20 | 11.5 | + +-----------------------------------+------------------------+------------------------+ + | BDT boreal | 20 | 11.5 | + +-----------------------------------+------------------------+------------------------+ + | BES temperate | 0.5 | 0.1 | + +-----------------------------------+------------------------+------------------------+ + | BDS temperate | 0.5 | 0.1 | + +-----------------------------------+------------------------+------------------------+ + | BDS boreal | 0.5 | 0.1 | + +-----------------------------------+------------------------+------------------------+ + | C\ :math:`{}_{3}` arctic grass | 0.5 | 0.01 | + +-----------------------------------+------------------------+------------------------+ + | C\ :math:`{}_{3}` grass | 0.5 | 0.01 | + +-----------------------------------+------------------------+------------------------+ + | C\ :math:`{}_{4}` grass | 0.5 | 0.01 | + +-----------------------------------+------------------------+------------------------+ + | Crop R | 0.5 | 0.01 | + +-----------------------------------+------------------------+------------------------+ + | Crop I | 0.5 | 0.01 | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Corn R | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Corn I | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Temp Cereal R | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Temp Cereal I | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Winter Cereal R | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Winter Cereal I | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Soybean R | - | - | + +-----------------------------------+------------------------+------------------------+ + | :sup:`1`\ Soybean I | - | - | + +-----------------------------------+------------------------+------------------------+ + +:sup:`1`\ Determined by the crop model (Chapter :numref:`rst_Crops and Irrigation`) + +.. _Phenology and vegetation burial by snow: Phenology and vegetation burial by snow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -266,67 +290,74 @@ where :math:`z_{sno} -z_{bot} \ge 0,{\rm \; }0\le f_{veg}^{sno} \le 1`, :math:`z and stem area are set to zero if less than 0.05. If the sum of exposed leaf and stem area is zero, then the surface is treated as snow-covered ground. +.. _Model Input Requirements: + Model Input Requirements ---------------------------- +.. _Atmospheric Coupling: + Atmospheric Coupling ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The current state of the atmosphere (Table 2.3) at a given time step is +The current state of the atmosphere (:numref:`Table Atmospheric input to land model`) +at a given time step is used to force the land model. This atmospheric state is provided by an atmospheric model in coupled mode or from an observed dataset in offline -mode (Chapter 26). The land model then initiates a full set of +mode (Chapter :numref:`rst_Offline Mode`). The land model then initiates a full set of calculations for surface energy, constituent, momentum, and radiative fluxes. The land model calculations are implemented in two steps. The land model proceeds with the calculation of surface energy, constituent, momentum, and radiative fluxes using the snow and soil hydrologic states from the previous time step. The land model then updates the soil and snow hydrology calculations based on these fluxes. These fields are -passed to the atmosphere (Table 2.4). The albedos sent to the atmosphere +passed to the atmosphere (:numref:`Table Land model output to atmospheric model`). The albedos sent to the atmosphere are for the solar zenith angle at the next time step but with surface conditions from the current time step. -Table 2.3. Atmospheric input to land model - -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Field | variable name | units | -+======================================================+================================================+=================================================+ -| :sup:`1`\ Reference height | :math:`z'_{atm}` | m | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Zonal wind at :math:`z_{atm}` | :math:`u_{atm}` | m s\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Meridional wind at :math:`z_{atm}` | :math:`v_{atm}` | m s\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Potential temperature | :math:`\overline{\theta _{atm} }` | K | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Specific humidity at :math:`z_{atm}` | :math:`q_{atm}` | kg kg\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Pressure at :math:`z_{atm}` | :math:`P_{atm}` | Pa | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Temperature at :math:`z_{atm}` | :math:`T_{atm}` | K | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident longwave radiation | :math:`L_{atm} \, \downarrow` | W m\ :sup:`-2` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :sup:`2`\ Liquid precipitation | :math:`q_{rain}` | mm s\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :sup:`2`\ Solid precipitation | :math:`q_{sno}` | mm s\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident direct beam visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}^{\mu }` | W m\ :sup:`-2` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident direct beam near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}^{\mu }` | W m\ :sup:`-2` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident diffuse visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}` | W m\ :sup:`-2` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Incident diffuse near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}` | W m\ :sup:`-2` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| Carbon dioxide (CO:sub:`2`) concentration | :math:`c_{a}` | ppmv | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :sup:`3`\ Aerosol deposition rate | :math:`D_{sp}` | kg m\ :sup:`-2` s\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :sup:`4`\ Nitrogen deposition rate | :math:`NF_{ndep\_ s{\it min}n}` | g (N) m\ :sup:`-2` yr\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ -| :sup:`5`\ Lightning frequency | :math:`I_{l}` | flash km\ :sup:`-2` hr\ :sup:`-1` | -+------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ +.. _Table Atmospheric input to land model: + +.. table:: Atmospheric input to land model + + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Field | variable name | units | + +======================================================+================================================+=================================================+ + | :sup:`1`\ Reference height | :math:`z'_{atm}` | m | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Zonal wind at :math:`z_{atm}` | :math:`u_{atm}` | m s\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Meridional wind at :math:`z_{atm}` | :math:`v_{atm}` | m s\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Potential temperature | :math:`\overline{\theta _{atm} }` | K | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Specific humidity at :math:`z_{atm}` | :math:`q_{atm}` | kg kg\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Pressure at :math:`z_{atm}` | :math:`P_{atm}` | Pa | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Temperature at :math:`z_{atm}` | :math:`T_{atm}` | K | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Incident longwave radiation | :math:`L_{atm} \, \downarrow` | W m\ :sup:`-2` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | :sup:`2`\ Liquid precipitation | :math:`q_{rain}` | mm s\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | :sup:`2`\ Solid precipitation | :math:`q_{sno}` | mm s\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Incident direct beam visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}^{\mu }` | W m\ :sup:`-2` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Incident direct beam near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}^{\mu }` | W m\ :sup:`-2` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Incident diffuse visible solar radiation | :math:`S_{atm} \, \downarrow _{vis}` | W m\ :sup:`-2` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Incident diffuse near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}` | W m\ :sup:`-2` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Carbon dioxide (CO:sub:`2`) concentration | :math:`c_{a}` | ppmv | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | :sup:`3`\ Aerosol deposition rate | :math:`D_{sp}` | kg m\ :sup:`-2` s\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | :sup:`4`\ Nitrogen deposition rate | :math:`NF_{ndep\_ s{\it min}n}` | g (N) m\ :sup:`-2` yr\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | :sup:`5`\ Lightning frequency | :math:`I_{l}` | flash km\ :sup:`-2` hr\ :sup:`-1` | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ :sup:`1`\ The atmospheric reference height received from the atmospheric model :math:`z'_{atm}` is assumed to be the height above @@ -388,7 +419,7 @@ required but is calculated directly from :math:`\rho _{atm} =\frac{P_{atm} -0.378e_{atm} }{R_{da} T_{atm} }` where :math:`P_{atm}` is atmospheric pressure (Pa), :math:`e_{atm}` is atmospheric vapor pressure (Pa), :math:`R_{da}` is the gas constant for -dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), and +dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical constants`), and :math:`T_{atm}` is the atmospheric temperature (K). The atmospheric vapor pressure :math:`e_{atm}` is derived from atmospheric specific humidity :math:`q_{atm}` (kg kg\ :sup:`-1`) as @@ -398,59 +429,63 @@ The O\ :sub:`2` partial pressure (Pa) is required but is calculated from molar ratio and the atmospheric pressure :math:`P_{atm}` as :math:`o_{i} =0.209P_{atm}` . -Table 2.4. Land model output to atmospheric model - -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Field | Variable name | units | -+=======================================+================================================+==============================================================+ -| :sup:`1`\ Latent heat flux | :math:`\lambda _{vap} E_{v} +\lambda E_{g}` | W m\ :sup:`-2` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Sensible heat flux | :math:`H_{v} +H_{g}` | W m\ :sup:`-2` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Water vapor flux | :math:`E_{v} +E_{g}` | mm s\ :sup:`-1` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Zonal momentum flux | :math:`\tau _{x}` | kg m\ :sup:`-1` s\ :sup:`-2` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Meridional momentum flux | :math:`\tau _{y}` | kg m\ :sup:`-1` s\ :sup:`-2` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Emitted longwave radiation | :math:`L\, \uparrow` | W m\ :sup:`-2` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Direct beam visible albedo | :math:`I\, \uparrow _{vis}^{\mu }` | - | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Direct beam near-infrared albedo | :math:`I\, \uparrow _{nir}^{\mu }` | - | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Diffuse visible albedo | :math:`I\, \uparrow _{vis}` | - | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Diffuse near-infrared albedo | :math:`I\, \uparrow _{nir}` | - | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Absorbed solar radiation | :math:`\vec{S}` | W m\ :sup:`-2` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Radiative temperature | :math:`T_{rad}` | K | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Temperature at 2 meter height | :math:`T_{2m}` | K | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Specific humidity at 2 meter height | :math:`q_{2m}` | kg kg\ :sup:`-1` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Snow water equivalent | :math:`W_{sno}` | m | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Aerodynamic resistance | :math:`r_{am}` | s m\ :sup:`-1` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Friction velocity | :math:`u_{*}` | m s\ :sup:`-1` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| :sup:`2`\ Dust flux | :math:`F_{j}` | kg m\ :sup:`-2` s\ :sup:`-1` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ -| Net ecosystem exchange | NEE | kgCO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1` | -+---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ +.. _Table Land model output to atmospheric model: + +.. table:: Land model output to atmospheric model + + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Field | Variable name | units | + +=======================================+================================================+==============================================================+ + | :sup:`1`\ Latent heat flux | :math:`\lambda _{vap} E_{v} +\lambda E_{g}` | W m\ :sup:`-2` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Sensible heat flux | :math:`H_{v} +H_{g}` | W m\ :sup:`-2` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Water vapor flux | :math:`E_{v} +E_{g}` | mm s\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Zonal momentum flux | :math:`\tau _{x}` | kg m\ :sup:`-1` s\ :sup:`-2` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Meridional momentum flux | :math:`\tau _{y}` | kg m\ :sup:`-1` s\ :sup:`-2` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Emitted longwave radiation | :math:`L\, \uparrow` | W m\ :sup:`-2` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Direct beam visible albedo | :math:`I\, \uparrow _{vis}^{\mu }` | - | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Direct beam near-infrared albedo | :math:`I\, \uparrow _{nir}^{\mu }` | - | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Diffuse visible albedo | :math:`I\, \uparrow _{vis}` | - | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Diffuse near-infrared albedo | :math:`I\, \uparrow _{nir}` | - | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Absorbed solar radiation | :math:`\vec{S}` | W m\ :sup:`-2` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Radiative temperature | :math:`T_{rad}` | K | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Temperature at 2 meter height | :math:`T_{2m}` | K | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Specific humidity at 2 meter height | :math:`q_{2m}` | kg kg\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Snow water equivalent | :math:`W_{sno}` | m | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Aerodynamic resistance | :math:`r_{am}` | s m\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Friction velocity | :math:`u_{*}` | m s\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | :sup:`2`\ Dust flux | :math:`F_{j}` | kg m\ :sup:`-2` s\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Net ecosystem exchange | NEE | kgCO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ :sup:`1`\ :math:`\lambda _{vap}` is the latent heat of -vaporization (J kg\ :sup:`-1`) (Table 2.6) and :math:`\lambda` is +vaporization (J kg\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\lambda` is either the latent heat of vaporization :math:`\lambda _{vap}` or latent heat of sublimation :math:`\lambda _{sub}` (J kg\ :sup:`-1`) -(Table 2.6) depending on the liquid water and ice content of the top +(:numref:`Table Physical constants`) depending on the liquid water and ice content of the top snow/soil layer (section 5.4). :sup:`2`\ There are :math:`j=1,\ldots ,4` dust transport bins. +.. _Initialization: + Initialization ^^^^^^^^^^^^^^^^^^^^ @@ -504,16 +539,19 @@ ice contents are initialized as :math:`w_{liq,\, i} =0` and :math:`w_{liq,\, i} =\Delta z_{i} \rho _{liq} \theta _{i}` and :math:`w_{ice,\, i} =0` for :math:`T_{i} >T_{f}` , where :math:`\rho _{ice}` and :math:`\rho _{liq}` are the densities of ice -and liquid water (kg m\ :sup:`-3`) (Table 2.6), and :math:`T_{f}` -is the freezing temperature of water (K) (Table 2.6). All vegetated and +and liquid water (kg m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`T_{f}` +is the freezing temperature of water (K) (:numref:`Table Physical constants`). All vegetated and glacier land units are initialized with water stored in the unconfined aquifer and unsaturated soil :math:`W_{a} =4000` mm and water table depth :math:`z_{\nabla }` at five meters below the soil column. +.. _Surface Data: + Surface Data ^^^^^^^^^^^^^^^^^^ -Required surface data for each land grid cell are listed in Table 2.5 +Required surface data for each land grid cell are listed in +:numref:`Table Surface data required for CLM and their base spatial resolution` and include the glacier, lake, and urban fractions of the grid cell (vegetated and crop occupy the remainder), the fractional cover of each plant functional type (PFT), monthly leaf and stem area index and canopy @@ -523,53 +561,55 @@ elevation, biogenic volatile organic compounds (BVOCs) emissions factors, population density, gross domestic production, peat area fraction, and peak month of agricultural burning. Optional surface data include crop irrigation and managed crops. All fields are aggregated to -the model’s grid from high-resolution input datasets (Table 2.5) that +the model’s grid from high-resolution input datasets ( +:numref:`Table Surface data required for CLM and their base spatial resolution`) that are obtained from a variety of sources described below. -Table 2.5. Surface data required for CLM and their base spatial -resolution - -+--------------------------------------------+---------------------------+ -| Surface Field | Resolution | -+============================================+===========================+ -| Percent glacier | 0.05\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Percent lake and lake depth | 0.05\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Percent urban | 0.05\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Percent plant functional types (PFTs) | 0.05\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Monthly leaf and stem area index | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Canopy height (top, bottom) | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Soil color | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Percent sand, percent clay | 0.083\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Soil organic matter density | 0.083\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Maximum fractional saturated area | 0.125\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Elevation | 1km | -+--------------------------------------------+---------------------------+ -| Slope | 1km | -+--------------------------------------------+---------------------------+ -| Biogenic Volatile Organic Compounds | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Crop Irrigation | 0.083\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Managed crops | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Population density | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Gross domestic production | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Peat area fraction | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ -| Peak month of agricultural waste burning | 0.5\ :sup:`o` | -+--------------------------------------------+---------------------------+ +.. _Table Surface data required for CLM and their base spatial resolution: + +.. table:: Surface data required for CLM and their base spatial resolution + + +--------------------------------------------+---------------------------+ + | Surface Field | Resolution | + +============================================+===========================+ + | Percent glacier | 0.05\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Percent lake and lake depth | 0.05\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Percent urban | 0.05\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Percent plant functional types (PFTs) | 0.05\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Monthly leaf and stem area index | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Canopy height (top, bottom) | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Soil color | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Percent sand, percent clay | 0.083\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Soil organic matter density | 0.083\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Maximum fractional saturated area | 0.125\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Elevation | 1km | + +--------------------------------------------+---------------------------+ + | Slope | 1km | + +--------------------------------------------+---------------------------+ + | Biogenic Volatile Organic Compounds | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Crop Irrigation | 0.083\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Managed crops | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Population density | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Gross domestic production | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Peat area fraction | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ + | Peak month of agricultural waste burning | 0.5\ :sup:`o` | + +--------------------------------------------+---------------------------+ At the base spatial resolution of 0.05\ :sup:`o`, the percentage of each PFT is defined with respect to the vegetated portion of the grid @@ -669,7 +709,7 @@ of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1; Guenther et al. 2012). The default list of PFTs includes an unmanaged crop treated as a second -C3 grass (Table 2.1). The unmanaged crop has grid cell fractional cover +C3 grass (:numref:`Table Plant functional types`). The unmanaged crop has grid cell fractional cover assigned from MODIS satellite data (Lawrence and Chase 2007). A managed crop option uses grid cell fractional cover from the present-day crop dataset of Ramankutty and Foley (1998) (CLM4CNcrop). Managed crops are @@ -695,12 +735,12 @@ not share soil columns and thus permit for differences in land management between crops. CLM includes the option to irrigate cropland areas that are equipped for -irrigation. The application of irrigation responds dynamically to -climate (see Chapter 20). In CLM, irrigation is implemented for the C3 +irrigation. The application of irrigation responds dynamically to climate +(see Chapter :numref:`rst_Crops and Irrigation`). In CLM, irrigation is +implemented for the C3 generic crop only. When irrigation is enabled, the cropland area of each grid cell is divided into an irrigated and unirrigated fraction -according to a dataset of areas equipped for irrigation (Siebert et al. -2005). The area of irrigated cropland in each grid cell is given by the +according to a dataset of areas equipped for irrigation (:ref:`Siebert et al. (2005) `). The area of irrigated cropland in each grid cell is given by the smaller of the grid cell’s total cropland area, according to the default CLM4 dataset, and the grid cell’s area equipped for irrigation. The remainder of the grid cell’s cropland area (if any) is then assigned to @@ -708,7 +748,7 @@ unirrigated cropland. Irrigated and unirrigated crops are placed on separate soil columns, so that irrigation is only applied to the soil beneath irrigated crops. -Several input datasets are required for the fire model (Li et al. 2013a) +Several input datasets are required for the fire model (:ref:`Li et al. 2013a `) including population density, gross domestic production, peat area fraction, and peak month of agricultural waste burning. Population density at 0.5\ :sup:`o` resolution for 1850-2100 combines 5-min @@ -730,6 +770,8 @@ Global Lakes and Wetlands Database (GLWD) (Lehner and Döll, 2004). The climatological peak month for agricultural waste burning is from van der Werf et al. (2010). +.. _Adjustable Parameters and Physical Constants: + Adjustable Parameters and Physical Constants ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -737,10 +779,13 @@ Values of certain adjustable parameters inherent in the biogeophysical or biogeochemical parameterizations have either been obtained from the literature or calibrated based on comparisons with observations. These are described in the text. Physical constants, generally shared by all -of the components in the coupled modeling system, are presented in Table -2.6. +of the components in the coupled modeling system, are presented in +:numref:`Table Physical constants`. + + +.. _Table Physical constants: -.. csv-table:: Table 2.6. Physical constants +.. csv-table:: Physical constants :header: "description", "name", "value", "units" :widths: 40, 20, 20, 20 diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 868d8409a6..0bfdaf6217 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -63,7 +63,7 @@ to sensible heat and water vapor transfer between the atmosphere at heights :math:`z_{atm,\, h}` and :math:`z_{atm,\, w}` and the surface at heights :math:`z_{0h} +d` and :math:`z_{0w} +d`, respectively. The specific heat capacity of air :math:`C_{p}` (J kg\ :sup:`-1` -K\ :sup:`-1`) is a constant (Table 2.6). The atmospheric potential +K\ :sup:`-1`) is a constant (:numref:`Table Physical constants`). The atmospheric potential temperature used here is .. math:: @@ -78,7 +78,7 @@ expression is first-order equivalent to :math:`\theta _{atm} =T_{atm} \left({P_{srf} \mathord{\left/ {\vphantom {P_{srf} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } \right)^{{R_{da} \mathord{\left/ {\vphantom {R_{da} C_{p} }} \right. \kern-\nulldelimiterspace} C_{p} } }` (Stull 1988), where :math:`P_{srf}` is the surface pressure (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`R_{da}` -is the gas constant for dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6)]. By definition, +is the gas constant for dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical constants`)]. By definition, :math:`\theta _{s} =T_{s}` . The density of moist air (kg m\ :sup:`-3`) is .. math:: @@ -130,7 +130,7 @@ where :math:`z` is height in the surface layer (m), :math:`d` is the displacement height (m), :math:`L` is the Monin-Obukhov length scale (m) that accounts for buoyancy effects resulting from vertical density gradients (i.e., the atmospheric stability), k is the von Karman -constant (Table 2.6), and :math:`\left|{\it u}\right|` is the +constant (:numref:`Table Physical constants`), and :math:`\left|{\it u}\right|` is the atmospheric wind speed (m s\ :sup:`-1`). :math:`\phi _{m}` , :math:`\phi _{h}` , and :math:`\phi _{w}` are universal (over any surface) similarity functions of :math:`\zeta` that relate the constant @@ -171,7 +171,7 @@ defined as L=-\frac{u_{*}^{3} }{k\left(\frac{g}{\overline{\theta _{v,\, atm} }} \right)\theta '_{v} w'} =\frac{u_{*}^{2} \overline{\theta _{v,\, atm} }}{kg\theta _{v*} } where :math:`g` is the acceleration of gravity (m s\ :sup:`-2`) -(Table 2.6), and +(:numref:`Table Physical constants`), and :math:`\overline{\theta _{v,\, atm} }=\overline{\theta _{atm} }\left(1+0.61q_{atm} \right)` is the reference virtual potential temperature. :math:`L>0` indicates stable conditions. :math:`L<0` indicates unstable conditions. @@ -186,7 +186,7 @@ stable conditions. :math:`L<0` indicates unstable conditions. where :math:`\overline{\theta _{atm} }` is the atmospheric potential temperature. -Following Panofsky and Dutton (1984), the differential equations for +Following :ref:`Panofsky and Dutton (1984)`, the differential equations for :math:`\phi _{m} \left(\zeta \right)`, :math:`\phi _{h} \left(\zeta \right)`, and :math:`\phi _{w} \left(\zeta \right)` can be integrated formally without @@ -292,15 +292,14 @@ where :math:`w_{\*}` is the convective velocity scale :math:`z_{i} =1000` is the convective boundary layer height (m), and :math:`\beta =1`. -The momentum flux gradient relations are (Zeng et al. 1998) +The momentum flux gradient relations are (:ref:`Zeng et al. 1998 `) .. math:: :label: 5.30 \begin{array}{l} {\phi _{m} \left(\zeta \right)=0.7k^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } \qquad {\rm for\; }\zeta <-1.574{\rm \; (very\; unstable)}} \\ {\phi _{m} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } \qquad {\rm for\; -1.574}\le \zeta <0{\rm \; (unstable)}} \\ {\phi _{m} \left(\zeta \right)=1+5\zeta \qquad {\rm for\; }0\le \zeta \le 1{\rm \; (stable)}} \\ {\phi _{m} \left(\zeta \right)=5+\zeta \qquad {\rm for\; }\zeta {\rm >1\; (very\; stable).}} \end{array} -The sensible and latent heat flux gradient relations are (Zeng et al. -1998) +The sensible and latent heat flux gradient relations are (:ref:`Zeng et al. 1998 `) .. math:: :label: 5.31 @@ -316,7 +315,7 @@ for very unstable and unstable conditions at :math:`\zeta _{m} =-1.574` for :math:`\phi _{m} \left(\zeta \right)` and :math:`\zeta _{h} =\zeta _{w} =-0.465` for :math:`\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)` -(Zeng et al. 1998). The flux gradient relations can be integrated to +(:ref:`Zeng et al. 1998 `). The flux gradient relations can be integrated to yield wind profiles for the following conditions: Very unstable :math:`\left(\zeta <-1.574\right)` @@ -440,7 +439,7 @@ bulk Richardson number R_{iB} =\frac{\theta _{v,\, atm} -\theta _{v,\, s} }{\overline{\theta _{v,\, atm} }} \frac{g\left(z_{atm,\, m} -d\right)}{V_{a}^{2} } -is related to :math:`\zeta` (Arya 2001) as +is related to :math:`\zeta` (:ref:`Arya 2001 `) as .. math:: :label: 5.47 @@ -460,7 +459,7 @@ guess for :math:`\zeta` and thus :math:`L` from \label{ZEqnNum979946} \begin{array}{l} {\zeta =\frac{R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)}{1-5\min \left(R_{iB} ,0.19\right)} \qquad 0.01\le \zeta \le 2\qquad {\rm for\; }R_{iB} \ge 0{\rm \; (neutral\; or\; stable)}} \\ {\zeta =R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)\qquad -100\le \zeta \le -0.01\qquad {\rm for\; }R_{iB} <0{\rm \; (unstable)}} \end{array}. -Upon iteration (section 5.3.2), the following is used to determine +Upon iteration (section :numref:`Numerical Implementation`), the following is used to determine :math:`\zeta` and thus :math:`L` .. math:: @@ -545,11 +544,11 @@ Relative humidity is RH_{2m} =\min \left(100,\, \frac{q_{2m} }{q_{sat}^{T_{2m} } } \times 100\right) where :math:`q_{sat}^{T_{2m} }` is the saturated specific humidity at -the 2-m temperature :math:`T_{2m}` (section 5.5). +the 2-m temperature :math:`T_{2m}` (section :numref:`Saturation Vapor Pressure`). A 10-m wind speed is calculated as (note that this is not consistent with the 10-m wind speed calculated for the dust model as described in -Chapter 24) +Chapter :numref:`rst_Dust Model`) .. math:: :label: 5.61 @@ -562,12 +561,13 @@ Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces -------------------------------------------------------------- Surfaces are considered non-vegetated for the surface flux calculations -if leaf plus stem area index :math:`L+S<0.05` (section 2.1.4). By +if leaf plus stem area index :math:`L+S<0.05` (section +:numref:`Phenology and vegetation burial by snow`). By definition, this includes bare soil, wetlands, and glaciers. The -solution for lakes is described in Chapter 9. For these surfaces, the +solution for lakes is described in Chapter :numref:`rst_Lake Model`. For these surfaces, the surface may be exposed to the atmosphere, snow covered, and/or surface water covered, so that the sensible heat flux :math:`H_{g}` (W -m\ :sup:`-2`) is, with reference to Figure 5.1, +m\ :sup:`-2`) is, with reference to :numref:`Figure Schematic diagram of sensible heat fluxes`, .. math:: :label: ZEqnNum726771 @@ -596,12 +596,13 @@ surface water :math:`T_{h2osfc}` are H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{h2osfc} \right)}{r_{ah} } where :math:`\rho _{atm}` is the density of atmospheric air (kg m\ :sup:`-3`), :math:`C_{p}` is the specific heat capacity of air -(J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), +(J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical constants`), :math:`\theta _{atm}` is the atmospheric potential temperature (K), and :math:`r_{ah}` is the aerodynamic resistance to sensible heat transfer (s m\ :sup:`-1`). -The water vapor flux :math:`E_{g}` (kg m\ :sup:`-2` s\ :sup:`-1`) is, with reference to Figure 5.2, +The water vapor flux :math:`E_{g}` (kg m\ :sup:`-2` s\ :sup:`-1`) is, with reference to +:numref:`Figure Schematic diagram of latent heat fluxes`, .. math:: :label: ZEqnNum419297 @@ -648,7 +649,7 @@ to be proportional to the saturation specific humidity q_{soil} =\alpha _{soil} q_{sat}^{T_{1} } where :math:`q_{sat}^{T_{1} }` is the saturated specific humidity at -the soil surface temperature :math:`T_{1}` (section 5.5). The factor +the soil surface temperature :math:`T_{1}` (section :numref:`Saturation Vapor Pressure`). The factor :math:`\alpha _{soil}` is a function of the surface soil water matric potential :math:`\psi` as in Philip (1957) @@ -657,8 +658,8 @@ potential :math:`\psi` as in Philip (1957) \alpha _{soil} =\exp \left(\frac{\psi _{1} g}{1\times 10^{3} R_{wv} T_{1} } \right) -where :math:`R_{wv}` is the gas constant for water vapor (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), :math:`g` is the -gravitational acceleration (m s\ :sup:`-2`) (Table 2.6), and +where :math:`R_{wv}` is the gas constant for water vapor (J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical constants`), :math:`g` is the +gravitational acceleration (m s\ :sup:`-2`) (:numref:`Table Physical constants`), and :math:`\psi _{1}` is the soil water matric potential of the top soil layer (mm). The soil water matric potential :math:`\psi _{1}` is @@ -668,10 +669,11 @@ layer (mm). The soil water matric potential :math:`\psi _{1}` is \psi _{1} =\psi _{sat,\, 1} s_{1}^{-B_{1} } \ge -1\times 10^{8} where :math:`\psi _{sat,\, 1}` is the saturated matric potential (mm) -(section 7.4.1), :math:`B_{1}` is the Clapp and Hornberger (1978) -parameter (section 7.4.1), and :math:`s_{1}` is the wetness of the top -soil layer with respect to saturation. The surface wetness -:math:`s_{1}` is a function of the liquid water and ice content +(section :numref:`Hydraulic Properties`), +:math:`B_{1}` is the :ref:`Clapp and Hornberger (1978) ` +parameter (section :numref:`Hydraulic Properties`), +and :math:`s_{1}` is the wetness of the top soil layer with respect to saturation. +The surface wetness :math:`s_{1}` is a function of the liquid water and ice content .. math:: :label: 5.75) @@ -680,11 +682,11 @@ soil layer with respect to saturation. The surface wetness where :math:`\Delta z_{1}` is the thickness of the top soil layer (m), :math:`\rho _{liq}` and :math:`\rho _{ice}` are the density of liquid -water and ice (kg m\ :sup:`-3`) (Table 2.6), :math:`w_{liq,\, 1}` +water and ice (kg m\ :sup:`-3`) (:numref:`Table Physical constants`), :math:`w_{liq,\, 1}` and :math:`w_{ice,\, 1}` are the mass of liquid water and ice of the -top soil layer (kg m\ :sup:`-2`) (Chapter 7), and +top soil layer (kg m\ :sup:`-2`) (Chapter :numref:`rst_Hydrology`), and :math:`\theta _{sat,\, 1}` is the saturated volumetric water content -(i.e., porosity) of the top soil layer (mm\ :sup:`3` mm\ :sup:`-3`) (section 7.4.1). If +(i.e., porosity) of the top soil layer (mm\ :sup:`3` mm\ :sup:`-3`) (section :numref:`Hydraulic Properties`). If :math:`q_{sat}^{T_{1} } >q_{atm}` and :math:`q_{atm} >q_{soil}` , then :math:`q_{soil} =q_{atm}` and :math:`\frac{dq_{soil} }{dT} =0`. This prevents large increases (decreases) in :math:`q_{soil}` for small @@ -711,7 +713,7 @@ The volumetric water content of the top soil layer (mm\ :sup:`3` mm\ :sup:`-3`) The volumetric water content at field capacity is derived by assuming a hydraulic conductivity of 0.1 mm day\ :sup:`-1` and inverting the -hydraulic conductivity function (section 7.4.1) as +hydraulic conductivity function (section :numref:`Hydraulic Properties`) as .. math:: :label: 5.78) @@ -719,8 +721,8 @@ hydraulic conductivity function (section 7.4.1) as \theta _{fc,\, 1} =\theta _{sat,\, 1} \left[\frac{0.1}{86400k_{sat,\, 1} } \right]^{\frac{1}{2B_{i} +3} } where :math:`k_{sat,\, 1}` is the saturated hydraulic conductivity of -the top soil layer (mm s\ :sup:`-1`) (section 7.4.1) and the -exponent :math:`B_{1}` is a function of soil texture (section 7.4.1). +the top soil layer (mm s\ :sup:`-1`) (section :numref:`Hydraulic Properties`) and the +exponent :math:`B_{1}` is a function of soil texture (section :numref:`Hydraulic Properties`). The roughness lengths used to calculate :math:`r_{am}` , :math:`r_{ah}` , and :math:`r_{aw}` are :math:`z_{0m} =z_{0m,\, g}` , @@ -734,7 +736,8 @@ fluctuations in the turbulent waves behind the roughness elements, while for heat and water vapor transfer no such dynamical mechanism exists. Rather, heat and water vapor must be transferred by molecular diffusion across the interfacial sublayer. The following relation from -Zilitinkevich (1970) is adopted by Zeng and Dickinson (1998) +:ref:`Zilitinkevich (1970) ` is adopted by +:ref:`Zeng and Dickinson 1998 ` .. math:: :label: ZEqnNum844212 @@ -789,9 +792,9 @@ water vapor flux from non-vegetated surfaces proceeds as follows: :math:`q_{2m}` (eqs. , ) The partial derivatives of the soil surface fluxes with respect to -ground temperature, which are needed for the soil temperature -calculations (section 6.1) and to update the soil surface fluxes -(section 5.4), are +ground temperature, which are needed for the soil temperature calculations (section +:numref:`Numerical Solution Temperature`) and to update the soil surface fluxes +(section :numref:`Update of Ground Sensible and Latent Heat Fluxes`), are .. math:: :label: ZEqnNum806472 @@ -831,8 +834,8 @@ coupling between vegetation temperature and fluxes, Newton-Raphson iteration is used to solve for the vegetation temperature and the sensible heat and water vapor fluxes from vegetation simultaneously using the ground temperature from the previous time step. In section -5.3.1, the equations used in the iteration scheme are derived. Details -on the numerical scheme are provided in section 5.3.2. +:numref:`Theory`, the equations used in the iteration scheme are derived. Details +on the numerical scheme are provided in section :numref:`Numerical Implementation`. .. _Theory: @@ -850,7 +853,7 @@ from the vegetation :math:`H_{v}` and the ground :math:`H_{g}` H=H_{v} +H_{g} -where, with reference to Figure 5.1, +where, with reference to :numref:`Figure Schematic diagram of sensible heat fluxes`, .. math:: :label: 5.84) @@ -883,7 +886,7 @@ where, with reference to Figure 5.1, H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{h2osfc} \right)}{r_{ah} ^{{'} } } where :math:`\rho _{atm}` is the density of atmospheric air (kg m\ :sup:`-3`), :math:`C_{p}` is the specific heat capacity of air -(J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), +(J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical constants`), :math:`\theta _{atm}` is the atmospheric potential temperature (K), and :math:`r_{ah}` is the aerodynamic resistance to sensible heat transfer (s m\ :sup:`-1`). @@ -891,21 +894,25 @@ where :math:`\rho _{atm}` is the density of atmospheric air (kg m\ :sup:`-3`), Here, :math:`T_{s}` is the surface temperature at height :math:`z_{0h} +d`, also referred to as the canopy air temperature. :math:`L` and :math:`S` are the exposed leaf and stem area indices -(section 2.1.4), :math:`r_{b}` is the leaf boundary layer resistance (s +(section :numref:`Phenology and vegetation burial by snow`), :math:`r_{b}` is the leaf boundary layer resistance (s m\ :sup:`-1`), and :math:`r_{ah} ^{{'} }` is the aerodynamic resistance (s m\ :sup:`-1`) to heat transfer between the ground at height :math:`z_{0h} ^{{'} }` and the canopy air at height :math:`z_{0h} +d`. -Figure 5.1. Schematic diagram of sensible heat fluxes for (a) -non-vegetated surfaces and (b) vegetated surfaces. +.. _Figure Schematic diagram of sensible heat fluxes: -.. image:: image1.png +.. figure:: image1.png -Figure 5.2. Schematic diagram of water vapor fluxes for (a) -non-vegetated surfaces and (b) vegetated surfaces. + Figure Schematic diagram of sensible heat fluxes for (a) + non-vegetated surfaces and (b) vegetated surfaces. -.. image:: image2.png +.. _Figure Schematic diagram of latent heat fluxes: + +.. figure:: image2.png + + Figure Schematic diagram of water vapor fluxes for (a) + non-vegetated surfaces and (b) vegetated surfaces. Equations - can be solved for the canopy air temperature :math:`T_{s}` @@ -963,7 +970,7 @@ flux from the vegetation :math:`E_{v}` and the ground :math:`E_{g}` E=E_{v} +E_{g} -where, with reference to Figure 5.2, +where, with reference to :numref:`Figure Schematic diagram of latent heat fluxes`, .. math:: :label: 5.97) @@ -998,19 +1005,21 @@ where, with reference to Figure 5.2, where :math:`q_{atm}` is the atmospheric specific humidity (kg kg\ :sup:`-1`), :math:`r_{aw}` is the aerodynamic resistance to water vapor transfer (s m\ :sup:`-1`), :math:`q_{sat}^{T_{v} }` (kg kg\ :sup:`-1`) is the saturation water vapor specific humidity -at the vegetation temperature (section 5.5), :math:`q_{g}` , +at the vegetation temperature (section :numref:`Saturation Vapor Pressure`), :math:`q_{g}` , :math:`q_{sno}` , and :math:`q_{h2osfc}` are the specific humidities -of the soil, snow, and surface water (section 5.2), +of the soil, snow, and surface water (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`), :math:`r_{aw} ^{{'} }` is the aerodynamic resistance (s m\ :sup:`-1`) to water vapor transfer between the ground at height :math:`z_{0w} ^{{'} }` and the canopy air at height :math:`z_{0w} +d`, :math:`\beta _{soi}` is an empirical function of soil water (section -5.2), and :math:`r_{litter}` is a resistance for the plant litter layer +:numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`), +and :math:`r_{litter}` is a resistance for the plant litter layer (s m\ :sup:`-1`). :math:`r_{total}` is the total resistance to water vapor transfer from the canopy to the canopy air and includes contributions from leaf boundary layer and sunlit and shaded stomatal resistances :math:`r_{b}` , :math:`r_{s}^{sun}` , and -:math:`r_{s}^{sha}` (Figure 5.2). The water vapor flux from vegetation +:math:`r_{s}^{sha}` (:numref:`Figure Schematic diagram of latent heat fluxes`). +The water vapor flux from vegetation is the sum of water vapor flux from wetted leaf and stem area :math:`E_{v}^{w}` (evaporation of water intercepted by the canopy) and transpiration from dry leaf surfaces :math:`E_{v}^{t}` @@ -1057,11 +1066,11 @@ as r''=\left\{\begin{array}{l} {\min \left(f_{wet} +r_{dry} ^{{'} {'} } ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} >0} \\ {\min \left(f_{wet} ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} \le 0} \\ {1\qquad E_{v}^{w,\, pot} \le 0} \end{array}\right\} where :math:`f_{wet}` is the fraction of leaves and stems that are wet -(section 7.1), :math:`W_{can}` is canopy water (kg m\ :sup:`-2`) -(section 7.1), :math:`\Delta t` is the time step (s), and +(section :numref:`Canopy Water`), :math:`W_{can}` is canopy water (kg m\ :sup:`-2`) +(section :numref:`Canopy Water`), :math:`\Delta t` is the time step (s), and :math:`\beta _{t}` is a soil moisture function limiting transpiration -(Chapter 8). The potential evaporation from wet foliage per unit wetted -area is +(Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). The potential +evaporation from wet foliage per unit wetted area is .. math:: :label: 5.109) @@ -1076,10 +1085,10 @@ The term :math:`r_{dry} ^{{'} {'} }` is r_{dry} ^{{'} {'} } =\frac{f_{dry} r_{b} }{L} \left(\frac{L^{sun} }{r_{b} +r_{s}^{sun} } +\frac{L^{sha} }{r_{b} +r_{s}^{sha} } \right) where :math:`f_{dry}` is the fraction of leaves that are dry (section -7.1), :math:`L^{sun}` and :math:`L^{sha}` are the sunlit and shaded -leaf area indices (section 4.1), and :math:`r_{s}^{sun}` and +:numref:`Canopy Water`), :math:`L^{sun}` and :math:`L^{sha}` are the sunlit and shaded +leaf area indices (section :numref:`Solar Fluxes`), and :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}` are the sunlit and shaded stomatal resistances (s -m\ :sup:`-1`) (Chapter 8). +m\ :sup:`-1`) (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). When the expression for :math:`q_{s}` is substituted into equation , the water vapor flux from vegetation :math:`E_{v}` is a function of @@ -1119,8 +1128,7 @@ is the magnitude of the wind velocity incident on the leaves (equivalent here to friction velocity) (m s\ :sup:`-1`) and :math:`C_{s}` is the turbulent transfer coefficient between the underlying soil and the canopy air. :math:`C_{s}` is obtained by -interpolation between values for dense canopy and bare soil (Zeng et al. -2005) +interpolation between values for dense canopy and bare soil (:ref:`Zeng et al. 2005 `) .. math:: :label: 5.115) @@ -1134,8 +1142,8 @@ where the weight :math:`W` is W=e^{-\left(L+S\right)} . -The dense canopy turbulent transfer coefficient in Zeng et al. (2005) -is modified from its original value of 0.004 (Dickinson et al. 1993) by +The dense canopy turbulent transfer coefficient in :ref:`Zeng et al. (2005) ` +is modified from its original value of 0.004 (:ref:`Dickinson et al. 1993 `) by Sakaguchi and Zeng (2009) to account for stability as .. math:: @@ -1152,8 +1160,8 @@ determined from S=\frac{gz_{top} \left(T_{s} -T_{g} \right)}{T_{s} u_{*}^{2} } where :math:`g` is the gravitational acceleration (m -s\ :sup:`-2`) (Table 2.6), and :math:`z_{top}` is canopy top -height (m) (Table 2.2). The bare soil turbulent transfer coefficient is +s\ :sup:`-2`) (:numref:`Table Physical constants`), and :math:`z_{top}` is canopy top +height (m) (:numref:`Table Prescribed plant functional type heights`). The bare soil turbulent transfer coefficient is .. math:: :label: 5.119) @@ -1188,8 +1196,7 @@ The effective snow cover of the litter layer is f_{litter}^{snow} =\frac{z_{sno} }{\Delta z_{litter} } where :math:`\Delta z_{litter} =0.05`\ m is assumed as a typical depth -for the litter layer, and :math:`z_{sno}` is the depth of snow (section -7.2) (m). +for the litter layer, and :math:`z_{sno}` is the depth of snow (Chapter :numref:`rst_Snow Hydrology`) (m). The leaf boundary layer resistance :math:`r_{b}` is @@ -1201,12 +1208,12 @@ The leaf boundary layer resistance :math:`r_{b}` is where :math:`C_{v} =0.01` m\ s\ :sup:`-1/2` is the turbulent transfer coefficient between the canopy surface and canopy air, and :math:`d_{leaf}` is the characteristic dimension of the leaves in the -direction of wind flow (Table 5.1). +direction of wind flow (:numref:`Table Coefficients for saturation vapor pressure`). The partial derivatives of the fluxes from the soil beneath the canopy with respect to ground temperature, which are needed for the soil -temperature calculations (section 6.1) and to update the soil surface -fluxes (section 5.4), are +temperature calculations (section :numref:`Numerical Solution Temperature`) and to update the soil surface +fluxes (section :numref:`Update of Ground Sensible and Latent Heat Fluxes`), are .. math:: :label: ZEqnNum774729 @@ -1230,7 +1237,7 @@ The roughness lengths used to calculate :math:`r_{am}` , :math:`z_{0m} =z_{0m,\, v}` , :math:`z_{0h} =z_{0h,\, v}` , and :math:`z_{0w} =z_{0w,\, v}` . The vegetation displacement height :math:`d` and the roughness lengths are a function of plant height and -adjusted for canopy density following Zeng and Wang (2007) +adjusted for canopy density following :ref:`Zeng and Wang (2007) ` .. math:: :label: 5.126) @@ -1242,11 +1249,12 @@ adjusted for canopy density following Zeng and Wang (2007) d=z_{top} R_{d} V -where :math:`z_{top}` is canopy top height (m) (Table 2.2), +where :math:`z_{top}` is canopy top height (m) (:numref:`Table Prescribed plant functional type heights`), :math:`R_{z0m}` and :math:`R_{d}` are the ratio of momentum roughness -length and displacement height to canopy top height, respectively (Table -5.1), and :math:`z_{0m,\, g}` is the ground momentum roughness length -(m) (section 5.2). The fractional weight :math:`V` is determined from +length and displacement height to canopy top height, respectively +(:numref:`Table Plant functional type aerodynamic parameters`), and +:math:`z_{0m,\, g}` is the ground momentum roughness length +(m) (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`). The fractional weight :math:`V` is determined from .. math:: :label: 5.128) @@ -1256,59 +1264,61 @@ length and displacement height to canopy top height, respectively (Table where :math:`\beta =1` and :math:`\left(L+S\right)_{cr} =2` (m\ :sup:`2` m\ :sup:`-2`) is a critical value of exposed leaf plus stem area for which :math:`z_{0m}` reaches its maximum. -Table 5.1. Plant functional type aerodynamic parameters - -+----------------------------------+--------------------+------------------+-------------------------+ -| Plant functional type | :math:`R_{z0m}` | :math:`R_{d}` | :math:`d_{leaf}` (m) | -+==================================+====================+==================+=========================+ -| NET Temperate | 0.055 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| NET Boreal | 0.055 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| NDT Boreal | 0.055 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BET Tropical | 0.075 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BET temperate | 0.075 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BDT tropical | 0.055 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BDT temperate | 0.055 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BDT boreal | 0.055 | 0.67 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BES temperate | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BDS temperate | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| BDS boreal | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| C\ :sub:`3` arctic grass | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| C\ :sub:`3` grass | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| C\ :sub:`4` grass | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Crop R | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Crop I | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Corn R | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Corn I | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Temp Cereal R | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Temp Cereal I | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Winter Cereal R | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Winter Cereal I | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Soybean R | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ -| Soybean I | 0.120 | 0.68 | 0.04 | -+----------------------------------+--------------------+------------------+-------------------------+ +.. _Table Plant functional type aerodynamic parameters: + +.. table:: Plant functional type aerodynamic parameters + + +----------------------------------+--------------------+------------------+-------------------------+ + | Plant functional type | :math:`R_{z0m}` | :math:`R_{d}` | :math:`d_{leaf}` (m) | + +==================================+====================+==================+=========================+ + | NET Temperate | 0.055 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | NET Boreal | 0.055 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | NDT Boreal | 0.055 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BET Tropical | 0.075 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BET temperate | 0.075 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BDT tropical | 0.055 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BDT temperate | 0.055 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BDT boreal | 0.055 | 0.67 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BES temperate | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BDS temperate | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | BDS boreal | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | C\ :sub:`3` arctic grass | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | C\ :sub:`3` grass | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | C\ :sub:`4` grass | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Crop R | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Crop I | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Corn R | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Corn I | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Temp Cereal R | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Temp Cereal I | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Winter Cereal R | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Winter Cereal I | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Soybean R | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ + | Soybean I | 0.120 | 0.68 | 0.04 | + +----------------------------------+--------------------+------------------+-------------------------+ .. _Numerical Implementation: @@ -1323,12 +1333,12 @@ Canopy energy conservation gives -\overrightarrow{S}_{v} +\overrightarrow{L}_{v} \left(T_{v} \right)+H_{v} \left(T_{v} \right)+\lambda E_{v} \left(T_{v} \right)=0 where :math:`\overrightarrow{S}_{v}` is the solar radiation absorbed by -the vegetation (section 4.1), :math:`\overrightarrow{L}_{v}` is the net -longwave radiation absorbed by vegetation (section 4.2), and +the vegetation (section :numref:`Solar Fluxes`), :math:`\overrightarrow{L}_{v}` is the net +longwave radiation absorbed by vegetation (section :numref:`Longwave Fluxes`), and :math:`H_{v}` and :math:`\lambda E_{v}` are the sensible and latent heat fluxes from vegetation, respectively. The term :math:`\lambda` is taken to be the latent heat of vaporization :math:`\lambda _{vap}` -(Table 2.6). +(:numref:`Table Physical constants`). :math:`\overrightarrow{L}_{v}` , :math:`H_{v}` , and :math:`\lambda E_{v}` depend on the vegetation temperature @@ -1436,7 +1446,7 @@ proceeds as follows: :math:`r_{aw} ^{{'} }` (eq. ) #. Sunlit and shaded stomatal resistances :math:`r_{s}^{sun}` and - :math:`r_{s}^{sha}` (Chapter 8) + :math:`r_{s}^{sha}` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`) #. Sensible heat conductances :math:`c_{a}^{h}` , :math:`c_{g}^{h}` , and :math:`c_{v}^{h}` (eqs. , , ) @@ -1494,10 +1504,10 @@ flux later. :math:`\lambda \Delta _{3}` are also added to the sensible heat flux. -#. The saturated vapor pressure :math:`e_{i}` (Chapter 8), saturated +#. The saturated vapor pressure :math:`e_{i}` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), saturated specific humidity :math:`q_{sat}^{T_{v} }` and its derivative :math:`\frac{dq_{sat}^{T_{v} } }{dT_{v} }` at the leaf surface - (section 5.5), are re-evaluated based on the new :math:`T_{v}` . + (section :numref:`Saturation Vapor Pressure`), are re-evaluated based on the new :math:`T_{v}` . #. Canopy air temperature :math:`T_{s}` (eq. ) @@ -1548,7 +1558,7 @@ The sensible and water vapor heat fluxes derived above for bare soil and soil beneath canopy are based on the ground surface temperature from the previous time step :math:`T_{g}^{n}` and are used as the surface forcing for the solution of the soil temperature equations (section -6.1). This solution yields a new ground surface temperature +:numref:`Numerical Solution Temperature`). This solution yields a new ground surface temperature :math:`T_{g}^{n+1}` . The ground sensible and water vapor fluxes are then updated for :math:`T_{g}^{n+1}` as @@ -1591,7 +1601,7 @@ relative area of the :math:`j^{th}` PFT with respect to the column, and :math:`npft` is the number of PFTs on the column. :math:`w_{ice,\, snl+1}` and :math:`w_{liq,\, snl+1}` are the ice and liquid water contents (kg m\ :sup:`-2`) of the top snow/soil layer -(Chapter 7). Any resulting energy deficit is assigned to sensible heat +(Chapter :numref:`rst_Hydrology`). Any resulting energy deficit is assigned to sensible heat as .. math:: @@ -1626,9 +1636,9 @@ on snow/soil :math:`q_{sdew}` (kg m\ :sup:`-2` s\ :sup:`-1`), or frost on snow/ The loss or gain in snow mass due to :math:`q_{seva}` , :math:`q_{subl}` , :math:`q_{sdew}` , and :math:`q_{frost}` on a snow surface are accounted for during the snow hydrology calculations -(section 7.2). The loss of soil and surface water due to +(Chapter :numref:`rst_Snow Hydrology`). The loss of soil and surface water due to :math:`q_{seva}` is accounted for in the calculation of infiltration -(section 7.3), while losses or gains due to :math:`q_{subl}` , +(section :numref:`Infiltration`), while losses or gains due to :math:`q_{subl}` , :math:`q_{sdew}` , and :math:`q_{frost}` on a soil surface are accounted for following the sub-surface drainage calculations (section 7.6). @@ -1641,8 +1651,8 @@ The ground heat flux :math:`G` is calculated as G=\overrightarrow{S}_{g} -\overrightarrow{L}_{g} -H_{g} -\lambda E_{g} where :math:`\overrightarrow{S}_{g}` is the solar radiation absorbed by -the ground (section 4.1), :math:`\overrightarrow{L}_{g}` is the net -longwave radiation absorbed by the ground (section 4.2) +the ground (section :numref:`Solar Fluxes`), :math:`\overrightarrow{L}_{g}` is the net +longwave radiation absorbed by the ground (section :numref:`Longwave Fluxes`) .. math:: :label: 5.151) @@ -1669,7 +1679,7 @@ When converting ground water vapor flux to an energy flux, the term where :math:`\lambda _{sub}` and :math:`\lambda _{vap}` are the latent heat of sublimation and vaporization, respectively (J -(kg\ :sup:`-1`) (Table 2.6). When converting vegetation water vapor +(kg\ :sup:`-1`) (:numref:`Table Physical constants`). When converting vegetation water vapor flux to an energy flux, :math:`\lambda _{vap}` is used. The system balances energy as @@ -1687,7 +1697,7 @@ Saturation Vapor Pressure Saturation vapor pressure :math:`e_{sat}^{T}` (Pa) and its derivative :math:`\frac{de_{sat}^{T} }{dT}` , as a function of temperature :math:`T` (ºC), are calculated from the eighth-order polynomial fits of -Flatau et al. (1992) +:ref:`Flatau et al. (1992) ` .. math:: :label: 5.155) @@ -1702,10 +1712,11 @@ Flatau et al. (1992) where the coefficients for ice are valid for :math:`-75\, ^{\circ } {\rm C}\le T<0\, ^{\circ } {\rm C}` and the coefficients for water are valid for -:math:`0\, ^{\circ } {\rm C}\le T\le 100\, ^{\circ } {\rm C}` (Table 5.2 -and 5.3). The saturated water vapor specific humidity -:math:`q_{sat}^{T}` and its derivative -:math:`\frac{dq_{sat}^{T} }{dT}` are +:math:`0\, ^{\circ } {\rm C}\le T\le 100\, ^{\circ } {\rm C}` +(:numref:`Table Coefficients for saturation vapor pressure` and +:numref:`Table Coefficients for derivative of esat`). +The saturated water vapor specific humidity :math:`q_{sat}^{T}` and its derivative +:math:`\frac{dq_{sat}^{T} }{dT}` are .. math:: :label: 5.157) @@ -1717,51 +1728,55 @@ and 5.3). The saturated water vapor specific humidity \frac{dq_{sat}^{T} }{dT} =\frac{0.622P_{atm} }{\left(P_{atm} -0.378e_{sat}^{T} \right)^{2} } \frac{de_{sat}^{T} }{dT} . -Table 5.2. Coefficients for :math:`e_{sat}^{T}` - -+------------------+------------------------------------------+----------------------------------------+ -| | water | ice | -+==================+==========================================+========================================+ -| :math:`a_{0}` | 6.11213476 | 6.11123516 | -+------------------+------------------------------------------+----------------------------------------+ -| :math:`a_{1}` | 4.44007856 :math:`\times 10^{-1}` | 5.03109514\ :math:`\times 10^{-1}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{2}` | 1.43064234 :math:`\times 10^{-2}` | 1.88369801\ :math:`\times 10^{-2}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{3}` | 2.64461437 :math:`\times 10^{-4}` | 4.20547422\ :math:`\times 10^{-4}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{4}` | 3.05903558 :math:`\times 10^{-6}` | 6.14396778\ :math:`\times 10^{-6}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{5}` | 1.96237241 :math:`\times 10^{-8}` | 6.02780717\ :math:`\times 10^{-8}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{6}` | 8.92344772 :math:`\times 10^{-11}` | 3.87940929\ :math:`\times 10^{-10}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{7}` | -3.73208410 :math:`\times 10^{-13}` | 1.49436277\ :math:`\times 10^{-12}` | -+------------------+-------------------------------------------+---------------------------------------+ -| :math:`a_{8}` | 2.09339997 :math:`\times 10^{-16}` | 2.62655803\ :math:`\times 10^{-15}` | -+------------------+------------------------------------------+----------------------------------------+ - -Table 5.3. Coefficients for :math:`\frac{de_{sat}^{T} }{dT}` - -+------------------+----------------------------------------+----------------------------------------+ -| | water | ice | -+==================+========================================+========================================+ -| :math:`b_{0}` | 4.44017302\ :math:`\times 10^{-1}` | 5.03277922\ :math:`\times 10^{-1}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{1}` | 2.86064092\ :math:`\times 10^{-2}` | 3.77289173\ :math:`\times 10^{-2}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{2}` | 7.94683137\ :math:`\times 10^{-4}` | 1.26801703\ :math:`\times 10^{-3}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{3}` | 1.21211669\ :math:`\times 10^{-5}` | 2.49468427\ :math:`\times 10^{-5}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{4}` | 1.03354611\ :math:`\times 10^{-7}` | 3.13703411\ :math:`\times 10^{-7}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{5}` | 4.04125005\ :math:`\times 10^{-10}` | 2.57180651\ :math:`\times 10^{-9}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{6}` | -7.88037859 :math:`\times 10^{-13}` | 1.33268878\ :math:`\times 10^{-11}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{7}` | -1.14596802 :math:`\times 10^{-14}` | 3.94116744\ :math:`\times 10^{-14}` | -+------------------+----------------------------------------+----------------------------------------+ -| :math:`b_{8}` | 3.81294516\ :math:`\times 10^{-17}` | 4.98070196\ :math:`\times 10^{-17}` | -+------------------+----------------------------------------+----------------------------------------+ +.. _Table Coefficients for saturation vapor pressure: + +.. table:: Coefficients for :math:`e_{sat}^{T}` + + +------------------+------------------------------------------+----------------------------------------+ + | | water | ice | + +==================+==========================================+========================================+ + | :math:`a_{0}` | 6.11213476 | 6.11123516 | + +------------------+------------------------------------------+----------------------------------------+ + | :math:`a_{1}` | 4.44007856 :math:`\times 10^{-1}` | 5.03109514\ :math:`\times 10^{-1}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{2}` | 1.43064234 :math:`\times 10^{-2}` | 1.88369801\ :math:`\times 10^{-2}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{3}` | 2.64461437 :math:`\times 10^{-4}` | 4.20547422\ :math:`\times 10^{-4}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{4}` | 3.05903558 :math:`\times 10^{-6}` | 6.14396778\ :math:`\times 10^{-6}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{5}` | 1.96237241 :math:`\times 10^{-8}` | 6.02780717\ :math:`\times 10^{-8}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{6}` | 8.92344772 :math:`\times 10^{-11}` | 3.87940929\ :math:`\times 10^{-10}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{7}` | -3.73208410 :math:`\times 10^{-13}` | 1.49436277\ :math:`\times 10^{-12}` | + +------------------+-------------------------------------------+---------------------------------------+ + | :math:`a_{8}` | 2.09339997 :math:`\times 10^{-16}` | 2.62655803\ :math:`\times 10^{-15}` | + +------------------+------------------------------------------+----------------------------------------+ + +.. _Table Coefficients for derivative of esat: + +.. table:: Coefficients for :math:`\frac{de_{sat}^{T} }{dT}` + + +------------------+----------------------------------------+----------------------------------------+ + | | water | ice | + +==================+========================================+========================================+ + | :math:`b_{0}` | 4.44017302\ :math:`\times 10^{-1}` | 5.03277922\ :math:`\times 10^{-1}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{1}` | 2.86064092\ :math:`\times 10^{-2}` | 3.77289173\ :math:`\times 10^{-2}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{2}` | 7.94683137\ :math:`\times 10^{-4}` | 1.26801703\ :math:`\times 10^{-3}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{3}` | 1.21211669\ :math:`\times 10^{-5}` | 2.49468427\ :math:`\times 10^{-5}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{4}` | 1.03354611\ :math:`\times 10^{-7}` | 3.13703411\ :math:`\times 10^{-7}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{5}` | 4.04125005\ :math:`\times 10^{-10}` | 2.57180651\ :math:`\times 10^{-9}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{6}` | -7.88037859 :math:`\times 10^{-13}` | 1.33268878\ :math:`\times 10^{-11}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{7}` | -1.14596802 :math:`\times 10^{-14}` | 3.94116744\ :math:`\times 10^{-14}` | + +------------------+----------------------------------------+----------------------------------------+ + | :math:`b_{8}` | 3.81294516\ :math:`\times 10^{-17}` | 4.98070196\ :math:`\times 10^{-17}` | + +------------------+----------------------------------------+----------------------------------------+ diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 205a14c0e6..f850a383b4 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -11,7 +11,7 @@ changes in canopy water :math:`\Delta W_{can}` , surface water :math:`\Delta W_{sfc}` , snow water :math:`\Delta W_{sno}` , soil water :math:`\Delta w_{liq,\, i}` , and soil ice :math:`\Delta w_{ice,\, i}` , and water in the unconfined aquifer :math:`\Delta W_{a}` (all in kg -m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (Figure 7.1). +m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Hydrologic processes figure`). The total water balance of the system is @@ -22,22 +22,24 @@ The total water balance of the system is where :math:`q_{rain}` is the liquid part of precipitation, :math:`q_{sno}` is the solid part of precipitation, :math:`E_{v}` is -ET from vegetation (Chapter 5), :math:`E_{g}` is ground evaporation -(Chapter 5), :math:`q_{over}` is surface runoff (section 7.3), -:math:`q_{h2osfc}` is runoff from surface water storage (section 7.3), +ET from vegetation (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), :math:`E_{g}` is ground evaporation +(Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), :math:`q_{over}` is surface runoff (section :numref:`Surface Runoff`), +:math:`q_{h2osfc}` is runoff from surface water storage (section :numref:`Surface Runoff`), :math:`q_{drai}` is sub-surface drainage (section 7.6), :math:`q_{rgwl}` and :math:`q_{snwcp,ice}` are liquid and solid runoff from glaciers, wetlands, and lakes, and runoff from other surface types -due to snow capping (section 7.7) (all in kg m\ :sup:`-2` +due to snow capping (section :numref:`Runoff from glaciers and snow-capped surfaces`) (all in kg m\ :sup:`-2` s\ :sup:`-1`), :math:`N_{levsoi}` is the number of soil layers (note that hydrology calculations are only done over soil layers 1 to :math:`N_{levsoi}` ; ground levels :math:`N_{levsoi} +1`\ to -:math:`N_{levgrnd}` are currently hydrologically inactive; Lawrence et -al. 2008) and :math:`\Delta t` is the time step (s). +:math:`N_{levgrnd}` are currently hydrologically inactive; :ref:`(Lawrence et +al. 2008) ` and :math:`\Delta t` is the time step (s). -Figure 7.1. Hydrologic processes represented in CLM. +.. _Hydrologic processes figure: -.. image:: image1.png +.. Figure:: image1.png + + Hydrologic processes represented in CLM. .. _Canopy Water: @@ -57,7 +59,7 @@ liquid and solid phases where :math:`L` and :math:`S` are the exposed leaf and stem area index, respectively (section 2.1.4), and :math:`\alpha =0.25` scales -interception from point to grid cell (Lawrence et al. 2007). Throughfall +interception from point to grid cell (:ref:`Lawrence et al. 2007 `). Throughfall (kg m\ :sup:`-2` s\ :sup:`-1`), however, is divided into liquid and solid phases reaching the ground (soil or snow surface) as @@ -101,8 +103,8 @@ amount of water the canopy can hold W_{can,\, \max } =p\left(L+S\right). The maximum storage of solid water is assumed to be the same as that of -liquid water, :math:`p=0.1` kg m\ :sup:`-2` (Dickinson et al. -1993). The canopy water is updated as +liquid water, :math:`p=0.1` kg m\ :sup:`-2` (:ref:`Dickinson et al. +1993 `). The canopy water is updated as .. math:: :label: 7.9) @@ -110,7 +112,7 @@ liquid water, :math:`p=0.1` kg m\ :sup:`-2` (Dickinson et al. W_{can}^{n+1} =W_{can}^{n} +q_{intr} \Delta t-\left(q_{drip,\, liq} +q_{drip,\, ice} \right)\Delta t-E_{v}^{w} \Delta t\ge 0. where :math:`E_{v}^{w}` is the flux of water vapor from stem and leaf -surfaces (Chapter 5). The total rate of liquid and solid precipitation +surfaces (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). The total rate of liquid and solid precipitation reaching the ground is then .. math:: @@ -125,13 +127,15 @@ reaching the ground is then Solid precipitation reaching the soil or snow surface, :math:`q_{grnd,\, ice} \Delta t`, is added immediately to the snow pack -(section 7.2). The liquid part, :math:`q_{grnd,\, liq} \Delta t` is -added after surface fluxes (Chapter 5) and snow/soil temperatures -(Chapter 6) have been determined. +(Chapter :numref:`rst_Snow Hydrology`). The liquid part, +:math:`q_{grnd,\, liq} \Delta t` is added after surface fluxes +(Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) +and snow/soil temperatures (Chapter :numref:`rst_Soil and Snow Temperatures`) +have been determined. The wetted fraction of the canopy (stems plus leaves), which is required -for the surface albedo (section 3.1) and surface flux (Chapter 5) -calculations is (Dickinson et al. 1993) +for the surface albedo (section :numref:`Canopy Radiative Transfer`) and surface flux (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) +calculations is (:ref:`Dickinson et al.1993 `) .. math:: :label: 7.12) @@ -161,8 +165,9 @@ infiltration into the soil. Surface Runoff ^^^^^^^^^^^^^^^^^^^^ -The simple TOPMODEL-based (Beven and Kirkby 1979) runoff model (SIMTOP) -described by Niu et al. (2005) is implemented to parameterize runoff. A +The simple TOPMODEL-based (:ref:`Beven and Kirkby 1979 `) +runoff model (SIMTOP) described by :ref:`Niu et al. (2005) ` +is implemented to parameterize runoff. A key concept underlying this approach is that of fractional saturated area :math:`f_{sat}` , which is determined by the topographic characteristics and soil moisture state of a grid cell. The saturated @@ -192,17 +197,18 @@ cell whose topographic index is larger than or equal to the grid cell mean topographic index. It should be calculated explicitly from the CDF at each grid cell at the resolution that the model is run. However, because this is a computationally intensive task for global -applications, :math:`f_{\max }` is calculated once at -0.125\ :sup:`o` resolution using the 1-km compound topographic -indices (CTIs) based on the HYDRO1K dataset (Verdin and Greenlee 1996) -from USGS following the algorithm in Niu et al. (2005) and then -area-averaged to the desired model resolution (section 2.2.3). Pixels +applications, :math:`f_{\max }` is calculated once at 0.125\ :sup:`o` +resolution using the 1-km compound topographic indices (CTIs) based on +the HYDRO1K dataset (:ref:`Verdin and Greenlee 1996 `) +from USGS following the algorithm in :ref:`Niu et al. (2005) ` +and then area-averaged to the desired model resolution (section +:numref:`Surface Data`). Pixels with CTIs exceeding the 95 percentile threshold in each 0.125\ :sup:`o` grid cell are excluded from the calculation to eliminate biased estimation of statistics due to large CTI values at pixels on stream networks. For grid cells over regions without CTIs such as Australia, the global mean :math:`f_{\max }` is used to fill the -gaps. See Li et al. (2013b) for additional details. The decay factor +gaps. See :ref:`Li et al. (2013b) ` for additional details. The decay factor :math:`f_{over}` for global simulations was determined through sensitivity analysis and comparison with observed runoff to be 0.5 m\ :sup:`-1`. @@ -216,7 +222,8 @@ A surface water store has been added to the model to represent wetlands and small, sub-grid scale water bodies. As a result, the wetland land unit has been removed. The state variables for surface water are the mass of water :math:`W_{sfc}` (kg m\ :sup:`-2`) and temperature -:math:`T_{h2osfc}` (Chapter 6). Surface water storage and outflow are +:math:`T_{h2osfc}` (Chapter :numref:`rst_Soil and Snow Temperatures`). +Surface water storage and outflow are functions of fine spatial scale elevation variations called microtopography. The microtopography is assumed to be distributed normally around the grid cell mean elevation. Given the standard @@ -364,9 +371,10 @@ Soil Water Soil water is predicted from a multi-layer model, in which the vertical soil moisture transport is governed by infiltration, surface and sub-surface runoff, gradient diffusion, gravity, canopy transpiration -through root extraction, and interactions with groundwater (Figure 7.1). -The following derivation generally follows that of Z.-L. Yang (1998, -unpublished manuscript) with modifications by Zeng and Decker (2009). +through root extraction, and interactions with groundwater +(:numref:`Hydrologic processes figure`). +The following derivation generally follows that of :ref:`Z.-L. Yang (1998, +unpublished manuscript) ` with modifications by Zeng and Decker (2009). For one-dimensional vertical water flow in soils, the conservation of mass is stated as @@ -482,11 +490,13 @@ vary with volumetric soil water :math:`\theta _{i}` and soil texture. As with the soil thermal properties (section 6.3) the hydraulic properties of the soil are assumed to be a weighted combination of the mineral properties, which are determined according to sand and clay -contents based on work by Clapp and Hornberger (1978) and Cosby et al. -(1984), and organic properties of the soil (Lawrence and Slater 2008). +contents based on work by :ref:`Clapp and Hornberger (1978) +` and :ref:`Cosby et al. (1984) `, +and organic properties of the soil +(:ref:`Lawrence and Slater 2008 `). The hydraulic conductivity is defined at the depth of the interface of -two adjacent layers :math:`z_{h,\, i}` (Figure 7.3) and is a function +two adjacent layers :math:`z_{h,\, i}` (:numref:`Water flux schematic figure`) and is a function of the saturated hydraulic conductivity :math:`k_{sat} \left[z_{h,\, i} \right]`, the liquid volumetric soil moisture of the two layers :math:`\theta _{i}` and @@ -500,8 +510,8 @@ moisture of the two layers :math:`\theta _{i}` and The ice impedance factor is a function of ice content, and is meant to quantify the increased tortuosity of the water flow when part of the -pore space is filled with ice. Swenson et al. (2012) used a power law -form :math:`\Theta _{ice} =10^{-\Omega F_{ice} }` where +pore space is filled with ice. :ref:`Swenson et al. (2012) ` +used a power law form :math:`\Theta _{ice} =10^{-\Omega F_{ice} }` where :math:`\Omega =6`\ and :math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the ice-filled fraction of the pore space. @@ -517,7 +527,8 @@ organic components. The water content at saturation (i.e. porosity) is \theta _{sat,i} =(1-f_{om,i} )\theta _{sat,\min ,i} +f_{om,i} \theta _{sat,om} where :math:`f_{om,i}` is the soil organic matter fraction, -:math:`\theta _{sat,om} =0.9` (Farouki 1981; Letts et al. 2000) is the +:math:`\theta _{sat,om} =0.9` (:ref:`Farouki 1981 `; +:ref:`Letts et al. 2000 `) is the porosity of organic matter and the porosity of the mineral soil :math:`\theta _{sat,\min ,i}` is @@ -533,7 +544,7 @@ The exponent “:math:`B`†is B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} -where :math:`B_{om} =2.7`\ (Letts et al. 2000) and +where :math:`B_{om} =2.7`\ (:ref:`Letts et al. 2000 `) and .. math:: :label: 7.93) @@ -541,7 +552,7 @@ where :math:`B_{om} =2.7`\ (Letts et al. 2000) and B_{\min ,i} =2.91+0.159(\% clay)_{i} . The soil matric potential (mm) is defined at the node depth -:math:`z_{i}` of each layer :math:`i` (Figure 7.3) +:math:`z_{i}` of each layer :math:`i` (:numref:`Water flux schematic figure`) .. math:: :label: ZEqnNum316201 @@ -574,8 +585,8 @@ by the organic soil properties even for values of :math:`f_{om}` as low as 1 %. To better represent the influence of organic soil material on the grid cell average saturated hydraulic conductivity, the soil organic matter fraction is further subdivided into “connected†and “unconnected†-fractions using a result from percolation theory (Stauffer and Aharony -1994, Berkowitz and Balberg 1992). Assuming that the organic and mineral +fractions using a result from percolation theory (:ref:`Stauffer and Aharony +1994 `, :ref:`Berkowitz and Balberg 1992 `). Assuming that the organic and mineral fractions are randomly distributed throughout a soil layer, percolation theory predicts that above a threshold value :math:`f_{om} =f_{threshold}` , connected flow pathways consisting of @@ -601,7 +612,7 @@ pass through the mineral and organic components in series k_{sat,\, uncon} =f_{uncon} \left(\frac{\left(1-f_{om} \right)}{k_{sat,\, \min } } +\frac{\left(f_{om} -f_{perc} \right)}{k_{sat,\, om} } \right)^{-1} . where saturated hydraulic conductivity for mineral soil depends on soil -texture (Cosby et al. 1984) as +texture (:ref:`Cosby et al. (1984) `) as .. math:: :label: 7.99) @@ -621,7 +632,7 @@ as Numerical Solution ^^^^^^^^^^^^^^^^^^^^^^^^ -With reference to Figure 7.3, the equation for conservation of mass +With reference to :numref:`Water flux schematic figure`, the equation for conservation of mass (equation ) can be integrated over each layer as .. math:: @@ -657,7 +668,7 @@ is the change in volumetric soil liquid water of layer :math:`i` in time :math:`i` (mm). The water removed by transpiration in each layer :math:`e_{i}` is a -function of the total transpiration :math:`E_{v}^{t}` (Chapter 5) and +function of the total transpiration :math:`E_{v}^{t}` (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) and the effective root fraction :math:`r_{e,\, i}` .. math:: @@ -665,8 +676,11 @@ the effective root fraction :math:`r_{e,\, i}` e_{i} =r_{e,\, i} E_{v}^{t} . -Figure 7.3. Schematic diagram of numerical scheme used to solve for soil -water fluxes. +.. _Water flux schematic figure: + +.. Figure:: image2.png + + Schematic diagram of numerical scheme used to solve for soil water fluxes. Shown are three soil layers, :math:`i-1`, :math:`i`, and :math:`i+1`. The soil matric potential :math:`\psi` and volumetric soil water @@ -678,7 +692,6 @@ the interface of two layers :math:`z_{h}` . The layer thickness is term :math:`e` (ET loss) is defined as positive for flow out of the layer. -.. image:: image2.png Note that because more than one plant functional type (PFT) may share a soil column, the transpiration :math:`E_{v}^{t}` is a weighted sum of @@ -711,10 +724,10 @@ fraction for the :math:`j^{th}` PFT \begin{array}{l} {\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } \qquad \left(\beta _{t} \right)_{j} >0} \\ {\left(r_{e,\, i} \right)_{j} =0\qquad \left(\beta _{t} \right)_{j} =0} \end{array} and :math:`\left(r_{i} \right)_{j}` is the fraction of roots in layer -:math:`i` (Chapter 8), :math:`\left(w_{i} \right)_{j}` is a soil -dryness or plant wilting factor for layer :math:`i` (Chapter 8), and -:math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total -soil column for the :math:`j^{th}` PFT (Chapter 8). +:math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), +:math:`\left(w_{i} \right)_{j}` is a soil dryness or plant wilting factor +for layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total +soil column for the :math:`j^{th}` PFT (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). The soil water fluxes in equation , which are a function of :math:`\theta _{liq,\, i}` and :math:`\theta _{liq,\, i+1}` because of @@ -922,7 +935,7 @@ Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' For the top soil layer (:math:`i=1`), the boundary condition is the -infiltration rate (section 7.3), +infiltration rate (section :numref:`Surface Runoff`), :math:`q_{i-1}^{n+1} =-q_{infl}^{n+1}` , and the water balance equation is @@ -1127,7 +1140,7 @@ Frozen Soils and Perched Water Table ---------------------------------------- When soils freeze, the power-law form of the ice impedance factor -(section 7.4.1) can greatly decrease the hydraulic conductivity of the +(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic conductivity of the soil, leading to nearly impermeable soil layers. When unfrozen soil layers are present above relatively ice-rich frozen layers, the possibility exists for perched saturated zones. Lateral drainage from @@ -1206,12 +1219,12 @@ the ice content of the soil layers interacting with the water table where :math:`\Omega =6`\ is an adjustable parameter, :math:`jwt` is the index of the layer directly above the water table, :math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the -ice-filled fraction of the pore space of soil layer :math:`i` (kg -m\ :sup:`-2`), and :math:`\Delta z_{i}` is the layer thickness -(mm). This expression is functionally the same as that used to determine -the ice impedance factor in section 7.4. In equation , the decay factor -:math:`f_{drai} =2.5` m\ :sup:`-1` and the maximum drainage when -the water table depth is at the surface +ice-filled fraction of the pore space of soil layer :math:`i` (kg +m\ :sup:`-2`), and :math:`\Delta z_{i}` is the layer thickness (mm). This +expression is functionally the same as that used to determine the ice +impedance factor in section :numref:`Hydraulic Properties`. In equation , +the decay factor :math:`f_{drai} =2.5` m\ :sup:`-1` and the maximum drainage +when the water table depth is at the surface :math:`q_{drai,\, \max } =10\sin (\beta )` kg m\ :sup:`-2` s\ :sup:`-1` , where :math:`\beta` is the mean grid cell topographic slope in radians, were determined for global simulations @@ -1219,8 +1232,7 @@ through sensitivity analysis and comparison with observed runoff. Determination of water table depth :math:`z_{\nabla }` is based on work by Niu et al. (2007). In this approach, a groundwater component is added -in the form of an unconfined aquifer lying below the soil column (Figure -7.1). The groundwater solution is dependent on whether the water table +in the form of an unconfined aquifer lying below the soil column (:numref:`Hydrologic processes figure`). The groundwater solution is dependent on whether the water table is within or below the soil column. The water stored in the unconfined aquifer :math:`W_{a}` has a prescribed maximum value (5000 mm). When the water table is within the soil column, :math:`W_{a}` is constant @@ -1380,136 +1392,7 @@ at the beginning and ending of the time step defined as Currently, glaciers are non-vegetated and :math:`E_{v} =W_{can} =0`. The contribution of lake runoff to :math:`q_{rgwl}` is described in -section 9.6.3. The runoff term :math:`q_{rgwl}` may be negative for -glaciers and lakes, which reduces the total amount of runoff available -to the RTM. - -.. _The Variable Infiltration Capacity parameterizations as a hydrologic option: - -The Variable Infiltration Capacity parameterizations as a hydrologic option -------------------------------------------------------------------------------- - -The hydrologic parameterizations from the Variable Infiltration Capacity -(VIC) land surface model (Liang et al. 1994) have been implemented as a -hydrologic option. VIC includes two different time scales of runoff -generation. To capture such dynamics, the soil column in the original -VIC model -(http://www.hydro.washington.edu/Lettenmaier/Models/VIC/Overview/ModelOverview.shtml) -is typically divided into three layers with variable soil depths. The -upper two layers are designed to represent the dynamic responses of the -soil to rainfall events for surface runoff generation, and the lower -layer is used to characterize the seasonal soil moisture behavior and -subsurface runoff generation. The implementation of the VIC -parameterizations are as described in Li et al. (2011) except where -updated for consistency with modifications to CLM hydrology in CLM4.5. -Note that unless explicitly mentioned in this section, any descriptions -from sections 7.1-7.7 are intact and remain valid when the VIC hydrology -option is turned on. - -Three VIC soil layers are defined by aggregating multiple layers in the -CLM soil column with thicknesses of :math:`\sum^3_{i=1}{\Delta z_i}`, -:math:`\sum^6_{i=4}{\Delta z_i}`, -:math:`\sum^{N_{levsoi}}_{i=7}{\Delta z_i}`, respectively. At each time -step, the soil moisture profile is determined following the algorithms -detailed in section 7.4, and aggregated to the three VIC layers for -runoff generation calculations. The surface runoff generated by the -saturation excess runoff mechanism, q\ :sub:`over`, is -calculated using equation , but with the fractional saturated area -defined as - -.. math:: - :label: ZEqnNum627546 - - f_{sat} =1-\left(1-{w_{top} \mathord{\left/ {\vphantom {w_{top} w_{m,\, top} }} \right. \kern-\nulldelimiterspace} w_{m,\, top} } \right)^{{1\mathord{\left/ {\vphantom {1 \left(1+b_{inf} \right)}} \right. \kern-\nulldelimiterspace} \left(1+b_{inf} \right)} } - -where :math:`w_{top}` and :math:`w_{m,top}` are calculated as -:math:`\sum^6_{i=1}{{\theta }_i\Delta z_i}` and -:math:`\sum^6_{i=1}{{\theta }_{s,i}\Delta z_i}`, respectively, and -represent the soil moisture (kg m\ :sup:`-2`) and maximum soil -moisture (kg m\ :sup:`-2`) in the top two VIC layers combined. - -In equation , it is hypothesized that the spatial heterogeneity of soil -moisture holding capacity in the top VIC layers can be represented by a -soil moisture holding capacity curve as defined in equation , in which -:math:`b_{inf}` is a parameter that controls the shape of the curve. -That is, if one assumes that a grid cell (or soil column in this case) -is composed of many pixels (or points) with varying soil moisture -capacity, this variation across the grid cell can be represented -conceptually as - -.. math:: - :label: ZEqnNum929519 - - i=i_m\left(1-{\left(1-A\right)}^{1/b_{inf}}\right) - -where :math:`i` and :math:`i_{m}` are the point and maximum point soil -moisture holding capacities (kg m\ :sup:`-2`), respectively; -:math:`A` is the fraction of a grid cell for which the soil moisture -holding capacity is less than or equal to :math:`i`; and -:math:`i_m=w_{m,top}\left(1+b_{inf}\right)`. When :math:`A` is equal to -:math:`f_{sat}`, the corresponding point soil moisture holding capacity -is denoted as :math:`i_0`. The maximum soil infiltration capacity (kg -m\ :sup:`-2` s\ :sup:`-1`) in equation becomes - -.. math:: - :label: ZEqnNum202398 - - q_{inf,\, max} =\left\{\begin{array}{l} {\left(1-f_{sat} \right)\theta _{ice,\, top} \left(\frac{w_{m,\, top} -w_{top} }{\Delta t} \right)\qquad i_{o} +q_{in,\, soil} \Delta t\ge i_{m} } \\ {\left(1-f_{sat} \right)\frac{\theta _{ice,\, top} }{\Delta t} \left\{\begin{array}{l} {\left(w_{m,\, top} -w_{top} \right)-w_{m,\, top} \times } \\ {\left[1-\max \left(1,\, \frac{\left(i_{o} +q_{in,\, soil} \Delta t\right)}{i_{m} } \right)^{1+b_{inf} } \right]} \end{array}\right\}\qquad i_{o} +q_{in,\, soil} \Delta t`. +It includes extensive modifications to the lake code of +:numref:`Zeng et al. (2002) ` used in CLM versions 2 through 4, which utilized concepts from the lake models of -Bonan (1996), Henderson-Sellers (1985, 1986), Hostetler and Bartlein -(1990) and the coupled lake-atmosphere model of Hostetler et al. (1993, -1994). Lakes have spatially variable depth prescribed in the surface -data (section 9.2); the surface data optionally includes lake optical +:numref:`Bonan (1996) `, +:numref:`Henderson-Sellers (1985) `, +:numref:`Henderson-Sellers (1986) `, +:numref:`Hostetler and Bartlein (1990) `, +and the coupled lake-atmosphere model of :numref:`Hostetler et al. (1993) `, :numref:`Hostetler et al. (1993) `. +Lakes have spatially variable depth prescribed in the surface data (section +:numref:`External Data Lake`); the surface data optionally includes lake optical extinction coeffient and horizontal fetch, currently only used for site simulations. Lake physics includes freezing and thawing in the lake body, resolved snow layers, and “soil†and bedrock layers below the lake @@ -30,6 +34,8 @@ ground heat flux *G* as a top boundary condition. Snow, soil, and bedrock models generally follow the formulations for non-vegetated surfaces (Chapter 6), with modifications described below. +.. _Vertical Discretization Lake: + Vertical Discretization --------------------------- @@ -62,6 +68,8 @@ follow the scheme used over non-vegetated surfaces (Chapter 6), with modifications to the snow layer thickness rules to keep snow layers at least as thick as *s*\ :sub:`min` (section 9.6.5). +.. _External Data Lake: + External Data ----------------- @@ -73,6 +81,8 @@ km\ :sup:`-2`. As in Subin et al. (2012a, b), the Kourzeneva depth in each grid cell, based on interpolated compilations of geographic information. +.. _Surface Albedo Lake: + Surface Albedo ------------------ @@ -106,9 +116,13 @@ calculated as over non-vegetated surfaces (Chapter 3). These two reflectances are combined to obtain the snow-fraction-weighted albedo as in over non-vegetated surfaces (Chapter 3). +.. _Surface Fluxes and Surface Temperature Lake: + Surface Fluxes and Surface Temperature ------------------------------------------ +.. _Overview of Changes from CLM4: + Overview of Changes from CLM4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -137,6 +151,8 @@ Overview of Changes from CLM4 :math:`{T}_{g}` to maintain a stable density profile at the lake surface eq. . +.. _Surface Properties Lake: + Surface Properties ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -209,6 +225,8 @@ where *A* and *B* define the fetch- and depth-limitation, respectively; :math:`\varepsilon =1` , :math:`f_{c} =100` , and *u* (m s\ :sup:`-1`) is the atmospheric forcing wind. +.. _Surface Flux Solution Lake: + Surface Flux Solution ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -475,9 +493,13 @@ temperature solution (section 9.5.3). An energy balance check is included at each timestep to insure that eq. XXX is obeyed to within 0.1 W m\ :sup:`-2`. +.. _Lake Temperature: + Lake Temperature -------------------- +.. _Introduction Lake: + Introduction ^^^^^^^^^^^^^^^^^^ @@ -525,6 +547,8 @@ restricted to occur at :math:`T_{j} =T_{f}` \ in the snow-lake-soil system, allowing eq. to be precisely enforced and justifying the exclusion of :math:`c_{v,j}` from the time derivative in eq. . +.. _Overview of Changes from CLM4 2: + Overview of Changes from CLM4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -546,6 +570,8 @@ arbitrary depth, except for a depth-dependent enhanced mixing (section diffusivity (specifically, the Brunt-Väisälä frequency term; eq. ) was corrected. +.. _Boundary Conditions Lake: + Boundary Conditions ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -565,6 +591,8 @@ calculation of eddy diffusivity: where :math:`u_{*}` \ is the friction velocity calculated in section 9.4.3 and *k* is the von Karman constant (Table 2.6). +.. _Eddy Diffusivity and Thermal Conductivities: + Eddy Diffusivity and Thermal Conductivities ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -614,7 +642,7 @@ s\ :sup:`-1`) (eq. ) is used to evaluate :math:`w^{*}` and :math:`k^{*}` rather than the 10-m wind used by Henderson-Sellers (1985). -The CityplaceRichardson number is +The Richardson number is .. math:: :label: 12.32) @@ -692,6 +720,8 @@ vegetated land units (Chapter 6), except for the adjustment of thermal conductivity for frost heave or excess ice (Subin et al., 2012a, Supporting Information). +.. _Radiation Penetration: + Radiation Penetration ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -741,6 +771,8 @@ al. 2012a): \eta =1.1925d^{-0.424} . +.. _Heat Capacities Lake: + Heat Capacities ^^^^^^^^^^^^^^^^^^^^^ @@ -761,6 +793,8 @@ bedrock layer (J m\ :sup:`-2`) is determined as for vegetated land units (Chapter 6), as the sum of the heat capacities for the water, ice, and mineral constituents. +.. _Crank-Nicholson Solution Lake: + Crank-Nicholson Solution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -819,6 +853,8 @@ section 9.4.3 (the factor of 2 merely cancels out the Crank-Nicholson F_{i} =\lambda _{i} \frac{T_{i} ^{n} -T_{i+1}^{n} }{z_{n+1} -z_{n} } . +.. _Phase Change Lake: + Phase Change ^^^^^^^^^^^^^^^^^^ @@ -896,6 +932,8 @@ is exhausted and the top lake layer is set to freezing. The snow thickness is adjusted downwards in proportion to the amount of melt, maintaining constant density. +.. _Convection Lake: + Convection ^^^^^^^^^^^^^^^^ @@ -983,6 +1021,8 @@ to *i* + 1, the ice fraction and temperature are set as follows, where #. Otherwise, :math:`I_{j} =0` and :math:`T_{j} =T_{unfr}` . +.. _Energy Conservation Lake: + Energy Conservation ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1012,9 +1052,13 @@ If :math:`\left|E_{soi} \right|<0.1`\ W m\ :sup:`-2`, it is subtracted from the sensible heat flux and added to *G*. Otherwise, the model is aborted. +.. _Lake Hydrology: + Lake Hydrology ------------------ +.. _Overview Lake Hydrology: + Overview ^^^^^^^^^^^^^^ @@ -1042,6 +1086,8 @@ explicit time-stepping integration of the surface flux solution, resolved snow layers must be a minimum of :math:`s_{\min }` = 4 cm thick rather than 1 cm when the default timestep of 1800 s is used. +.. _Water Balance Lake: + Water Balance ^^^^^^^^^^^^^^^^^^^ @@ -1063,6 +1109,8 @@ ground evaporation (section 9.4.3), and :math:`n_{levsoi}` is the number of hydrologically active soil layers (as opposed to dry bedrock layers). +.. _Precipitation, Evaporation, and Runoff Lake: + Precipitation, Evaporation, and Runoff ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1120,6 +1168,8 @@ proportion as the snow ice (i.e., maintaining the same density), unless there was no snow before adding the frost, in which case the density is assumed to be 250 kg m\ :sup:`-3`. +.. _Soil Hydrology Lake: + Soil Hydrology ^^^^^^^^^^^^^^^^^^^^ @@ -1153,6 +1203,8 @@ This allows excess ice to be initialized (and begin to be lost only after the pore ice is melted, which is realistic if the excess ice is found in heterogeneous chunks) but irreversibly lost when melt occurs. +.. _Modifications to Snow Layer Logic Lake: + Modifications to Snow Layer Logic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst index 7219e7a293..e4e2db66fa 100644 --- a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst +++ b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst @@ -4,24 +4,26 @@ Offline Mode ================ In offline mode (uncoupled to an atmospheric model), the atmospheric -forcing required by CLM (Table 2.3) is supplied by observed datasets. -The standard forcing provided with the model is a 110-year (1901-2010) -dataset (CRUNCEP; Viovy 2011) that is a combination of two existing -datasets; the CRU TS3.2 0.5\ :math:`{}^\circ` X 0.5\ :math:`{}^\circ` -monthly data covering the period 1901 to 2002 (Mitchell and Jones 2005) +forcing required by CLM (:numref:`Table Atmospheric input to land model`) +is supplied by observed datasets. The standard forcing provided with the +model is a 110-year (1901-2010) dataset (CRUNCEP; :ref:`Viovy 2011 `) +that is a combination of two existing datasets; the CRU TS3.2 0.5\ +:math:`{}^\circ` X 0.5\ :math:`{}^\circ` monthly data covering the period +1901 to 2002 (:ref:`Mitchell and Jones 2005 `) and the NCEP reanalysis 2.5\ :math:`{}^\circ` X 2.5\ :math:`{}^\circ` 6-hourly data covering the period 1948 to 2010. The CRUNCEP dataset has been used to force CLM for studies of vegetation growth, -evapotranspiration, and gross primary production (Mao et al. 2012, Mao -et al. 2013, Shi et al. 2013) and for the TRENDY (trends in net -land-atmosphere carbon exchange over the period 1980-2010) project (Piao -et al. 2012). Version 4 is used here (Viovy 2011). Alternative forcing -datasets can also be used (e.g., the Qian et al. (2006) dataset used for +evapotranspiration, and gross primary production (:ref:`Mao et al. 2012 `, +:ref:`Mao et al. 2013 `, :ref:`Shi et al. 2013 `) +and for the TRENDY (trends in net land-atmosphere carbon exchange over the period +1980-2010) project (:ref:`Piao et al. 2012 `). Version 4 is used +here (:ref:`Viovy 2011 `). Alternative forcing datasets can also be used +(e.g., the :ref:`Qian et al. (2006) ` dataset used for previous versions of CLM is still available). Here, the CRUNCEP dataset, which does not include data over oceans, -lakes, and Antarctica is modified. This missing data is filled with Qian -et al. (2006) data from 1948 that is interpolated by the data atmosphere +lakes, and Antarctica is modified. This missing data is filled with +:ref:`Qian et al. (2006) ` data from 1948 that is interpolated by the data atmosphere model to the 0.5\ :math:`{}^\circ` CRUNCEP grid. This allows the model to be run over Antarctica and ensures data is available along coastlines regardless of model resolution. @@ -119,7 +121,7 @@ and :math:`b_{0} =0.29548,b_{1} =0.00504,b_{2} =-1.4957\times 10^{-5} ,b_{3} =1.4881\times 10^{-8}` are coefficients from polynomial fits to the placeCAM data. -The additional atmospheric forcing variables required by Table 2.3 are +The additional atmospheric forcing variables required by :numref:`Table Atmospheric input to land model` are derived as follows. The atmospheric reference height :math:`z'_{atm}` (m) is set to 30 m. The directional wind components are derived as :math:`u_{atm} =v_{atm} ={W_{atm} \mathord{\left/ {\vphantom {W_{atm} \sqrt{2} }} \right. \kern-\nulldelimiterspace} \sqrt{2} }` . @@ -141,8 +143,8 @@ where e_{atm} =\frac{P_{atm} q_{atm} }{0.622+0.378q_{atm} } -and :math:`\sigma` is the Stefan-Boltzmann constant (W -m\ :sup:`-2` K\ :math:`{}^{-4}`) (Table 2.6). The fraction of +and :math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ +:math:`{}^{-4}`) (:numref:`Table Physical constants`). The fraction of precipitation :math:`P` (mm s\ :sup:`-1`) falling as rain and/or snow is @@ -164,8 +166,9 @@ where f_{P} =0<0.5\left(T_{atm} -T_{f} \right)<1. The aerosol deposition rates :math:`D_{sp}` (14 rates as described in -Table 2.3) are provided by a time-varying, globally-gridded aerosol -deposition file developed by Lamarque et al. (2010). +:numref:`Table Atmospheric input to land model`) are provided by a +time-varying, globally-gridded aerosol deposition file developed by +:ref:`Lamarque et al. (2010) `. If the user wishes to provide atmospheric forcing data from another source, the data format outlined above will need to be followed with the @@ -183,7 +186,7 @@ from the water (:math:`T_{atm} >T_{f}` ) or ice (:math:`T_{atm} \le T_{f}` ) saturation vapor pressure :math:`e_{sat}^{T_{atm} }` as :math:`e_{atm} =\frac{RH}{100} e_{sat}^{T_{atm} }` where :math:`T_{f}` -is the freezing temperature of water (K) (Table 2.6), and +is the freezing temperature of water (K) (:numref:`Table Physical constants`), and :math:`P_{atm}` is the pressure at height :math:`z_{atm}` (Pa). The data atmosphere model will also accept a user-supplied dew point temperature :math:`T_{dew}` (K) and derive specific humidity @@ -195,7 +198,7 @@ temperature :math:`T_{dew}` (K) and derive specific humidity q_{atm} = \frac{0.622e_{sat}^{T_{dew} } }{P_{atm} -0.378e_{sat}^{T_{dew} } } . Here, :math:`e_{sat}^{T}` , the saturation vapor pressure as a function -of temperature, is derived from Lowe’s (1977) polynomials. If not +of temperature, is derived from :ref:`Lowe’s (1977) ` polynomials. If not provided by the user, the atmospheric pressure :math:`P_{atm}` (Pa) is set equal to the standard atmospheric pressure :math:`P_{std} =101325` Pa, and surface pressure :math:`P_{srf}` (Pa) is set equal diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index 741801942d..28f43fce9a 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -9,6 +9,8 @@ where :math:`\vec{S}` is the net solar flux absorbed by the vegetation (“vâ€) and the ground (“gâ€) and :math:`\vec{L}` is the net longwave flux (positive toward the atmosphere) (W m\ :sup:`-2`). +.. _Solar Fluxes: + Solar Fluxes ---------------- @@ -143,6 +145,8 @@ fraction at depth :math:`x`, defined by :math:`f_{sun} =\exp \left(-Kx\right)`, to give fluxes per unit sunlit or shaded plant area at depth :math:`x`. +.. _Longwave Fluxes: + Longwave Fluxes ------------------- diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index b953d98b3d..4b81731fb0 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -3,127 +3,187 @@ References ============== +.. _Aberetal1990: + Aber, J.D., Melillo, J.M. and McClaugherty, C.A., 1990. Predicting long-term patterns of mass loss, nitrogen dynamics, and soil organic matter formation from initial fime litter chemistry in temperate forest ecosystems. Canadian Journal of Botany, 68: 2201-2208. +.. _Aberetal2003: + Aber, J.D., Goodale, C.L., Ollinger, S.V., Smith, M.-L., Magill, A.H., Martin, M.E., Hallett, R.A., and Stoddard, J.L. 2003. Is nitrogen deposition altering the nitrogen status of northeastern forests? BioScience 53:375-389. +.. _Allenetal2005: + Allen, C.B., Will, R.E., and Jacobson, M.A. 2005. Production efficiency and radiation use efficiency of four tree species receiving irrigation and fertilization. Forest Science 51:556-569. +.. _Anderson1976: + Anderson, E.A. 1976. A point energy and mass balance model of a snow cover. NOAA Technical Report NWS 19, Office of Hydrology, National Weather Service, Silver Spring, MD. +.. _Andréetal1986: + André, J.-C., Goutorbe, J.-P., and Perrier, A. 1986. HAPEX-MOBILHY: A hydrologic atmosphere experiment for the study of water budget and evaporation flux at the climatic scale. Bull. Amer. Meteor. Soc. 67:138-144. +.. _AndrénPaustian1987: + Andrén, O. and Paustian, K., 1987. Barley straw decomposition in the field: a comparison of models. Ecology 68:1190-1200. +.. _ArahStephen1998: + Arah, J.R.M. and Stephen, K.D., 1998. A model of the processes leading to methane emission from peatland. Atmos. Environ. 32:3257-3264. +.. _ArahVinten1995: + Arah, J. and Vinten, A., 1995. Simplified models of anoxia and denitrification in aggregated and simple-structured soils. European Journal of Soil Science 46:507-517. +.. _Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global + Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global Glacier Outlines Version: 1.0, Global Land Ice Measurements from Space, Boulder Colorado, USA. Digital Media. +.. _AroraBoer2005: + Arora, V.K. and Boer, G.J. 2005. Fire as an interactive component of dynamic vegetation models. J. Geophys. Res. 110:G02008. DOI:10.1029/2005JG000042. +.. _Arya2001: + Arya, S.P. 2001. Introduction to Meteorology. Academic Press, San Diego, CA. +.. _Asneretal1998: + Asner, G.P., Wessman, C.A., Schimel, D.S., and Archer, S. 1998. Variability in leaf and litter optical properties: implications for BRDF model inversions using AVHRR, MODIS, and MISR. Remote Sens. Environ. 63:243-257. +.. _AxelssonAxelsson1986: + Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation patterns in spruce and pine trees following irrigation and fertilization. Tree Phys. 2:189-204. +.. _Bairdetal2004: + Baird, A.J., Beckwith, C.W., Waldron, S. and Waddington, J.M., 2004. Ebullition of methane-containing gas bubbles from near-surface Sphagnum peat. Geophys. Res. Lett. 31. DOI:10.1029/2004GL021157. +.. _Baldocchietal2001: + Baldocchi, D., et al. 2001. FLUXNET: A new tool to study the temporal and spatial variability of ecosystem-scale carbon dioxide, water vapor, and energy flux densities. Bull. Amer. Meteor. Soc. 82:2415-2433. +.. _Barbottinetal2005: + Barbottin, A., Lecomte, C., Bouchard, C., and Jeuffroy, M.-H. 2005. Nitrogen remobilization during grain filling in wheat: Genotypic and environmental effects. Crop Sci. 45:1141-1150. +.. _Batjes2006: + Batjes, N.H., 2006. ISRIC-WISE derived soil properties on a 5 by 5 arc-minutes global grid. Report 2006/02 (available through : http://www.isric.org) +.. _Berger1978a: + Berger, A.L. 1978a. Long-term variations of daily insolation and quaternary climatic changes. J. Atmos. Sci. 35:2362-2367. +.. _Berger1978b: + Berger, A.L. 1978b. A simple algorithm to compute long-term variations of daily or monthly insolation. Contribution de l’Institut d’Astronomie et de Géophysique, Université Catholique de Louvain, Louvain-la-Neuve, No. 18. +.. _Bergeretal1993: + Berger, A., Loutre, M.-F., and Tricot, C. 1993. Insolation and Earth’s orbital periods. J. Geophys. Res. 98:10341-10362. +.. _BerkowitzBalberg1992: + Berkowitz, B., and Balberg, I. 1992. Percolation approach to the problem of hydraulic conductivity in porous media. Transport in Porous Media 9:275–286. +.. _BevenKirkby1979: + Beven, K.J., and Kirkby, M.J. 1979. A physically based variable contributing area model of basin hydrology. Hydrol. Sci. Bull. 24:43-69. Bohren, C. F., and Huffman, D. R. 1983. Absorption and scattering of light by small particles. John Wiley & Sons, New York, NY. +.. _Bonan1996: + Bonan, G.B. 1996. A land surface model (LSM version 1.0) for ecological, hydrological, and atmospheric studies: Technical description and user’s guide. NCAR Technical Note NCAR/TN-417+STR, National Center for Atmospheric Research, Boulder, CO, 150 pp. +.. _Bonan1998: + Bonan, G.B. 1998. The land surface climatology of the NCAR Land Surface Model coupled to the NCAR Community Climate Model. J. Climate 11:1307-1326. +.. _Bonan2002: + Bonan, G.B. 2002. Ecological Climatology: Concepts and Applications. Cambridge University Press. +.. _Bonanetal2002a: + Bonan, G.B., Oleson, K.W., Vertenstein, M., Levis, S., Zeng, X., Dai, Y., Dickinson, R.E., and Yang, Z.-L. 2002a. The land surface climatology of the Community Land Model coupled to the NCAR Community Climate Model. J. Climate 15: 3123-3149. +.. _Bonanetal2002b: + Bonan, G.B., Levis, S., Kergoat, L., and Oleson, K.W. 2002b. Landscapes as patches of plant functional types: An integrating concept for climate and ecosystem models. Global Biogeochem. Cycles 16: 5.1-5.23. +.. _BonanLevis2006: + Bonan, G.B., and Levis, S. 2006. Evaluating aspects of the Community Land and Atmosphere Models (CLM3 and CAM3) using a dynamic global vegetation model. J. Climate 19:2290-2301. +.. _Bonanetal2011: + Bonan, G.B., Lawrence P.J., Oleson K.W., Levis S., Jung M., Reichstein M., Lawrence, D.M., and Swenson, S.C. 2011. Improving canopy processes in the Community Land Model (CLM4) using global flux fields empirically inferred from FLUXNET data. J. Geophys. Res. 116, G02014. DOI:10.1029/2010JG001593. +.. _Bonanetal2012: + Bonan, G. B., Oleson, K.W., Fisher, R.A., Lasslop, G., and Reichstein, M. 2012. Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4, @@ -138,99 +198,147 @@ Branstetter, M.L. 2001. Development of a parallel river transport algorithm and applications to climate studies. Ph.D. dissertation, University of Texas at Austin. +.. _Brun1989: + Brun, E. 1989. Investigation of wet-snow metamorphism in respect of liquid water content. Ann. Glaciol. 13:22-26. +.. _BugmannSolomon2000: + Bugmann, H., and Solomon, A.M. 2000. Explaining forest composition and biomass across multiple biogeographical regions. Ecol. Appl. 10:95-114. +.. _Busing2005: + Busing, R.T. 2005. Tree mortality, canopy turnover, and woody detritus in old cove forests of the southern Appalachians. Ecology 86:73-84. +.. _CampbellNorman1998: + Campbell, G.S., and Norman, J.M. 1998. An Introduction to Environmental Biophysics (2:math:`{}^{nd}` edition). Springer-Verlag, New York. +.. _Castilloetal2012: + Castillo, G., Kendra, C., Levis, S., and Thornton, P. 2012. Evaluation of the new CNDV option of the Community Land Model: effects of dynamic vegetation and interactive nitrogen on CLM4 means and variability. J. Climate 25:3702–3714. +.. _Caoetal1996: + Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and methane emissions from natural wetlands: Application of a process-based model. J. Geophys. Res. 101(D9):14,399-14,414. +.. _Churkinaetal2003: + Churkina, G. et al., 2003. Analyzing the ecosystem carbon dynamics of four European coniferous forests using a biogeochemistry model. Ecosystems, 6: 168-184. +.. _CIESIN2005: + CIESIN: Gridded population of the world version 3 (GPWv3), 2005. Population density grids, Technical report, Socioeconomic Data and Applications Center (SEDAC), Columbia University, Palisades, New York, USA. +.. _ClappHornberger1978: + Clapp, R.B., and Hornberger, G.M. 1978. Empirical equations for some soil hydraulic properties. Water Resour. Res. 14:601-604. +.. _ClauserHuenges1995: + Clauser, C., and Huenges, E. 1995. Thermal conductivity of rocks and minerals. pp. 105-126. In: T. J. Ahrens (editor) Rock Physics and Phase Relations: A Handbook of Physical Constants. Washington, D.C. +.. _Clevelandetal1999: + Cleveland, C.C., Townsend, A.R., Schimel, D.S., Fisher, H., Howarth, R.W., Hedin, L.O., Perakis, S.S., Latty, E.F., Von Fischer, J.C., Elseroad, A., and Wasson, M.F. 1999. Global patterns of terrestrial biological nitrogen (N2) fixation in natural ecosystems. Global Biogeochem. Cycles 13:623-645. +.. _Collatzetal1991: + Collatz, G.J., Ball, J.T., Grivet, C., and Berry, J.A. 1991. Physiological and environmental regulation of stomatal conductance, photosynthesis, and transpiration: A model that includes a laminar boundary layer. Agric. For. Meteor. 54:107-136. +.. _Collatzetal1992: + Collatz, G.J., Ribas-Carbo, M., and Berry, J.A. 1992. Coupled photosynthesis-stomatal conductance model for leaves of C\ :math:`{}_{4}` plants. Aust. J. Plant Physiol. 19:519-538. +.. _Colmer2003: + Colmer, T.D., 2003. Long-distance transport of gases in plants: a perspective on internal aeration and radial oxygen loss from roots. Plant Cell and Environment 26:17-36. +.. _Conwayetal1996: + Conway, H., Gades, A., and Raymond, C.F. 1996. Albedo of dirty snow during conditions of melt. Water Resour. Res. 32:1713-1718. +.. _Cosbyetal1984: + Cosby, B.J., Hornberger, G.M., Clapp, R.B., and Ginn, T.R. 1984. A statistical exploration of the relationships of soil moisture characteristics to the physical properties of soils. Water Resour. Res. 20:682-690. +.. _Crawfordetal1982: + Crawford, T. W., Rendig, V. V., and Broadent, F. E. 1982. Sources, fluxes, and sinks of nitrogen during early reproductive growth of maize (Zea mays L.). Plant Physiol. 70:1645-1660. +.. _DaiZeng1997: + Dai, Y., and Zeng, Q. 1997. A land surface model (IAP94) for climate studies. Part I: formulation and validation in off-line experiments. Adv. Atmos. Sci. 14:433-460. +.. _Daietal2001: + Dai, Y., et al. 2001. Common Land Model: Technical documentation and user’s guide [Available online at http://climate.eas.gatech.edu/dai/clmdoc.pdf]. +.. _Daietal2003: + Dai, Y., Zeng, X., Dickinson, R.E., Baker, I., Bonan, G.B., Bosilovich, M.G., Denning, A.S., Dirmeyer, P.A., Houser, P.R., Niu, G., Oleson, K.W., Schlosser, C.A., and Yang, Z.-L. 2003. The Common Land Model. Bull. Amer. Meteor. Soc. 84:1013-1023. +.. _Daietal2004: + Dai, Y., Dickinson, R.E., and Wang, Y.-P. 2004. A two-big-leaf model for canopy temperature, photosynthesis, and stomatal conductance. J. Climate 17:2281-2299. +.. _DaiTrenberth2002: + Dai, A., and Trenberth, K.E. 2002. Estimates of freshwater discharge from continents: Latitudinal and seasonal variations. J. Hydrometeor. 3:660-687. +.. _DeFriesetal2000: + DeFries, R.S., Hansen, M.C., Townshend, J.R.G., Janetos, A.C., and Loveland, T.R. 2000. A new global 1-km dataset of percentage tree cover derived from remote sensing. Global Change Biol. 6:247-254. +.. _DegensSparling1996: + Degens, B. and Sparling, G., 1996. Changes in aggregation do not correspond with changes in labile organic C fractions in soil amended with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): @@ -239,187 +347,273 @@ with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): de Vries, D.A. 1963. Thermal Properties of Soils. In: W.R. van Wijk (editor) Physics of the Plant Environment. North-Holland, Amsterdam. +.. _Dickinson1983: + Dickinson, R.E. 1983. Land surface processes and climate-surface albedos and energy balance. Adv. Geophys. 25:305-353. +.. _Dickinsonetal1993: + Dickinson, R.E., Henderson-Sellers, A., and Kennedy, P.J. 1993. Biosphere-Atmosphere Transfer Scheme (BATS) version 1e as coupled to the NCAR Community Climate Model. NCAR Technical Note NCAR/TN-387+STR. National Center for Atmospheric Research, Boulder, CO. +.. _Dickinsonetal2006: + Dickinson, R.E., Oleson, K.W., Bonan, G., Hoffman, F., Thornton, P., Vertenstein, M., Yang, Z.-L., and Zeng, X. 2006. The Community Land Model and its climate statistics as a component of the Community Climate System Model. J. Climate 19:2302-2324. +.. _Dingman2002: + Dingman, S.L. 2002. Physical Hydrology. Second Edition. Prentice Hall, NJ. +.. _Dirmeyeretal1999: + Dirmeyer, P.A., Dolman, A.J., and Sato, N. 1999. The pilot phase of the Global Soil Wetness Project. Bull. Amer. Meteor. Soc. 80:851-878. +.. _Dobsonetal2000: + Dobson, J.E., Bright, E.A., Coleman, P.R., Durfee, R.C., and Worley, B.A. 2000. LandScan: A global population database for estimating populations at risk. Photogramm. Eng. Rem. Sens. 66:849-857. +.. _DormanSellers1989: + Dorman, J.L., and Sellers, P.J. 1989. A global climatology of albedo, roughness length and stomatal resistance for atmospheric general circulation models as represented by the simple biosphere model (SiB). J. Appl. Meteor. 28:833-855. +.. _Doughertyetal1994: + Dougherty, R.L., Bradford, J.A., Coyne, P.I., and Sims, P.L. 1994. Applying an empirical model of stomatal conductance to three C4 grasses. Agric. For. Meteor. 67:269-290. +.. _Drewniaketal2013: + Drewniak, B., Song, J., Prell, J., Kotamarthi, V.R., and Jacob, R. 2013. Modeling agriculture in the Community Land Model. Geosci. Model Dev. 6:495-515. DOI:10.5194/gmd-6-495-2013. +.. _Dunfieldetal1993: + Dunfield, P., Knowles, R., Dumont, R. and Moore, T.R., 1993. Methane Production and Consumption in Temperate and Sub-Arctic Peat Soils - Response to Temperature and Ph. Soil Biology & Biochemistry 25:321-326. +.. _EntekhabiEagleson1989: + Entekhabi, D., and Eagleson, P.S. 1989. Land surface hydrology parameterization for atmospheric general circulation models including subgrid scale spatial variability. J. Climate 2:816-831. +.. _FangStefan1996: + Fang, X. and Stefan, H.G., 1996. Long-term lake water temperature and ice cover simulations/measurements. Cold Regions Science and Technology 24:289-304. +.. _Farouki1981: + Farouki, O.T. 1981. The thermal properties of soils in cold regions. Cold Regions Sci. and Tech. 5:67-75. +.. _Farquharetal1980: + Farquhar, G.D., von Caemmerer, S., and Berry, J.A. 1980. A biochemical model of photosynthetic CO\ :sub:`2` assimilation in leaves of C\ :math:`{}_{3}` species. Planta 149:78-90. +.. _FarquharvonCaemmerer1982: + Farquhar, G.D., and von Caemmerer, S. 1982. Modeling of photosynthetic response to environmental conditions. pp. 549-587. In: O.L. Lange, P.S. Nobel, C.B. Osmond, and H. Zeigler (editors) Encyclopedia of Plant Physiology. Vol. 12B. Physiological Plant Ecology. II. Water Relations and Carbon Assimilation. Springer-Verlag, New York. +.. _Ferrari1999: + Ferrari, J.B., 1999. Fine-scale patterns of leaf litterfall and nitrogen cycling in an old-growth forest. Canadian Journal of Forest Research, 29: 291-302. +.. _FirestoneDavidson1989: + Firestone, M.K. and Davidson, E.A. 1989. Exchange of Trace Gases between Terrestrial Ecosystems and the Atmosphere. In: M.O. Andreae and D.S. Schimel (Editors). John Wiley and Sons, pp. 7-21. +.. _FlannerZender2005: + Flanner, M.G., and Zender. C.S. 2005. Snowpack radiative heating: Influence on Tibetan Plateau climate. Geophys. Res. Lett. 32:L06501. DOI:10.1029/2004GL022076. +.. _FlannerZender2006: + Flanner, M.G., and Zender, C.S. 2006. Linking snowpack microphysics and albedo evolution. J. Geophys. Res. 111:D12208. DOI:10.1029/2005JD006834. +.. _Flanneretal2007: + Flanner, M.G., Zender, C.S., Randerson, J.T., and Rasch, P.J. 2007. Present day climate forcing and response from black carbon in snow. J. Geophys. Res. 112:D11202. DOI:10.1029/2006JD008003. +.. _Flatauetal1992: + Flatau, P.J., Walko, R.L., and Cotton, W.R. 1992. Polynomial fits to saturation vapor pressure. J. Appl. Meteor. 31:1507-1513. +.. _Friedl,etal2002: + Friedl, M.A., McIver, D.K., Hodges, J.C.F., Zhang, X.Y., Muchoney, D., Strahler, A.H., Woodcock, C.E., Gopal, S., Schneider, A., Cooper, A., Baccini, A., Gao, F., and Schaaf, C. 2002. Global land cover mapping from MODIS: algorithms and early results. Remote Sens. Environ. 83:287-302. +.. _Frolkingetal2001: + Frolking, S., et al. 2001. Modeling Northern Peatland Decomposition and Peat Accumulation. Ecosystems. 4:479-498. +.. _Gallaisetal2006: + Gallais, A., Coque, M. Quillere, I., Prioul, J., and Hirel, B. 2006. Modeling postsilking nitrogen fluxes in maize (Zea mays) using 15N-labeling field experiments. New Phytologist 172:696-707. +.. _Gallaisetal2007: + Gallais, A., Coque, M., Gouis, J. L., Prioul, J. L., Hirel, B., and Quillere, I. 2007. Estimating the proportion of nitrogen remobilization and of postsilking nitrogen uptake allocated to maize kernels by Nitrogen-15 labeling. Crop Sci. 47:685-693. +.. _Gallowayetal2004: + Galloway, J.N., et al. 2004. Nitrogen cycles: past, present, and future. Biogeochem. 70:153-226. +.. _Garciaetal1988: + Garcia, R.L., Kanemasu, E.T., Blad, B.L., Bauer, A., Hatfield, J.L., Major, D.A., Reginato, R.J., and Hubbard, K.G. 1988. Interception and use efficiency of light in winter wheat under different nitrogen regimes. Agric. For. Meteor. 44:175-186. +.. _Gashetal1996: + Gash, J.H.C., Nobre, C.A., Roberts, J.M., and Victoria, R.L. 1996. An overview of ABRACOS. pp. 1-14. In: J.H.C. Gash, C.A. Nobre, J.M. Roberts, and R.L. Victoria (editors) Amazonian Deforestation and Climate. John Wiley and Sons, Chichester, England. +.. _Gholzetal1985: + Gholz, H.L., Perry, C.S., Cropper, W.P., Jr. and Hendry, L.C., 1985. Litterfall, decomposition, and nitrogen and phosphorous dynamics in a chronosequence of slash pine (*Pinus elliottii*) plantations. Forest Science, 31: 463-478. +.. _Giglioetal2006: + Giglio, L., Csiszar, I., and Justice, C.O. 2006. Global distribution and seasonality of active fires as observed with the Terra and Aqua Moderate Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. 111:G02016. DOI:10.1029/2005JG000142. +.. _GlobalSoilDataTask2000: + Global Soil Data Task 2000. Global soil data products CD-ROM (IGBP-DIS). International Geosphere-Biosphere Programme-Data and Information Available Services [Available online at http://www.daac.ornl.gov]. +.. _Gomesetal2003: + Gomes, E.P.C., Mantovani, W., and Kageyama, P.Y. 2003. Mortality and recruitment of trees in a secondary montane rain forest in southeastern Brazil. Brazilian Journal of Biology 63:47-60. +.. _Goszetal1973: + Gosz, J.R., Likens, G.E., and Bormann, F.H. 1973. Nutrient release from decomposing leaf and branch litter in the Hubbard Brook Forest, New Hampshire. Ecological Monographs 43:173-191. +.. _GotangcoCastilloetal2012: + Gotangco Castillo C., Levis S., and Thornton P. 2012. Evaluation of the new CNDV option of the Community Land Model: Effects of dynamic vegetation and interactive nitrogen on CLM4 means and variability. J. Climate 25:3702-3714. DOI:10.1175/JCLID-11-00372.1. +.. _Grahametal1999: + Graham, S.T., Famiglietti, J.S., and Maidment, D.R. 1999. Five-minute, 1/2º, and 1º data sets of continental watersheds and river networks for use in regional and global hydrologic and climate system modeling studies. Water Resour. Res. 35:583-587. +.. _GrenfellWarren1999: + Grenfell, T.C., and Warren, S.G. 1999. Representation of a nonspherical ice particle by a collection of independent spheres for scattering and absorption of radiation. J. Geophys. Res. 104(D24):37697-37709. +.. _delGrossoetal2000: + del Grosso, S.J., et al. 2000. General model for N2O and N2 gas emissions from soils due to dentrification. Global Biogeochem. Cycles 14:1045-1060. +.. _Guentheretal1995: + Guenther, A., Hewitt, C.N., Erickson, D., Fall, R., Geron, C., Graedel, T., Harley, P., Klinger, L., Lerdau, M., McKay, W.A., Pierce, T., Scholes, B., Steinbrecher, R., Tallamraju, R., Taylor, J., and Zimmerman, P. 1995. A global model of natural volatile organic compound emissions. J. Geophys. Res. 100:8873-8892. +.. _Guentheretal2006: + Guenther, A., Karl, T., Harley, P., Wiedinmyer, C., Palmer. P.I., and Geron, C. 2006. Estimates of global terrestrial isoprene emissions using MEGAN (Model of Emissions of Gases and Aerosols from Nature). Atmos. Chem. Phys. 6:3181–3210. +.. _Guentheretal2012: + Guenther, A. B., Jiang, X., Heald, C. L., Sakulyanontvittaya, T., Duhl, T., Emmons, L. K., & Wang, X., 2012. The Model of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1): an extended and updated framework for modeling biogenic emissions, Geosci. Model Dev., 5, 1471–1492. DOI:10.5194. +.. _Hacketal2006: + Hack, J.J., Caron, J.M., Yeager, S.G., Oleson, K.W., Holland, M.M., Truesdale, J.E., and Rasch, P.J. 2006. Simulation of the global hydrological cycle in the CCSM Community Atmosphere Model version 3 (CAM3): mean features. J. Climate 19:2199-2221. +.. _Hansenetal2003: + Hansen, M., DeFries, R.S., Townshend, J.R.G., Carroll, M., Dimiceli, C., and Sohlberg, R.A. 2003. Global percent tree cover at a spatial resolution of 500 meters: first results of the MODIS vegetation continuous fields algorithm. Earth Interactions 7:1-15. +.. _Hastingsetal1999: + Hastings, D.A., Dunbar, P.K., Elphingstone, G.M., Bootz, M., Murakami, H., Maruyama, H., Masaharu, H., Holland, P., Payne, J., Bryant, N.A., Logan, T.L., Muller, J.-P., Schreier, G., and MacDonald, J.S., eds., @@ -428,399 +622,583 @@ Elevation Model, Version 1.0. National Oceanic and Atmospheric Administration, National Geophysical Data Center, 325 Broadway, Boulder, Colorado 80305-3328, U.S.A. +.. _Healdetal2008: + Heald, C.L., Henze, D.K., Horowitz, L.W., Feddema, J., Lamarque, J.-F., Guenther, A., Hess, P.G., Vitt, F., Seinfeld, J.H., Goldstein, A.H., and Fung, I. 2008. Predicted change in global secondary organic aerosol concentrations in response to future climate, emissions, and land use change. J. Geophys. Res. 113:D05211. DOI:10.1029/2007JD009092. +.. _Healdetal2009: + Heald, C.L., Wilkinson, M.J., Monson, R.K., Alo, C.A., Wang, G.L., and Guenther, A. 2009. Response of isoprene emission to ambient CO\ :sub:`2` changes and implications for global budgets. Global Change Biol. 15:1127-1140. DOI:10.1111/j.1365-2486.2008.01802.x +.. _Henderson-Sellers1985: + Henderson-Sellers, B. 1985. New formulation of eddy diffusion thermocline models. Appl. Math. Modelling 9:441-446. +.. _Henderson-Sellers1986: + Henderson-Sellers, B. 1986. Calculating the surface energy balance for lake and reservoir modeling: A review. Rev. Geophys. 24:625-649. +.. _Henderson-Sellersetal1993: + Henderson-Sellers, A., Yang, Z.-L., and Dickinson, R.E. 1993. The project for intercomparison of land-surface parameterization schemes. Bull. Amer. Meteor. Soc. 74: 1335-1349. +.. _HostetlerBartlein1990: + Hostetler, S.W., and Bartlein, P.J. 1990. Simulation of lake evaporation with application to modeling lake level variations of Harney-Malheur Lake, Oregon. Water Resour. Res. 26:2603-2612. +.. _Hostetleretal1993: + Hostetler, S.W., Bates, G.T., and Giorgi, F. 1993. Interactive coupling of a lake thermal model with a regional climate model. J. Geophys. Res. 98:5045-5057. +.. _Hostetleretal1994: + Hostetler, S.W., Giorgi, F., Bates, G.T., and Bartlein, P.J. 1994. Lake-atmosphere feedbacks associated with paleolakes Bonneville and Lahontan. Science 263:665-668. +.. _Houetal2012: + Hou, Z., Huang, M., Leung, L.R., Lin, G., and Ricciuto, D.M. 2012. Sensitivity of surface flux simulations to hydrologic parameters based on an uncertainty quantification framework applied to the Community Land Model. J. Geophys. Res. 117:D15108. +.. _HuangLiang2006: + Huang, M., and Liang, X. 2006. On the assessment of the impact of reducing parameters and identification of parameter uncertainties for a hydrologic model with applications to ungauged basins. J. Hydrol. 320:37-61. +.. _Hugeliusetal2012: + Hugelius, G., C. Tarnocai, G. Broll, J.G. Canadell, P. Kuhry, adn D.K. Swanson, 2012. The Northern Circumpolar Soil Carbon Database: spatially distributed datasets of soil coverage and soil carbon storage in the northern permafrost regions. Earth Syst. Sci. Data Discuss., 5, 707-733 (available online at (http://dev1.geo.su.se/bbcc/dev/ncscd/). +.. _Huntetal1988: + Hunt, H.W., Ingham, E.R., Coleman, D.C., Elliott, E.T., and Reid, C.P.P. 1988. Nitrogen limitation of production and decomposition in prairie, mountain meadow, and pine forest. Ecology 69:1009-1016. +.. _HuntRunning1992: + Hunt, E.R., Jr. and Running, S.W., 1992. Simulated dry matter yields for aspen and spruce stands in the north american boreal forest. Canadian Journal of Remote Sensing, 18: 126-133. +.. _Huntetal1996: + Hunt, E.R., Jr. et al., 1996. Global net carbon exchange and intra-annual atmospheric CO\ :sub:`2` concentrations predicted by an ecosystem process model and three-dimensional atmospheric transport model. Global Biogeochemical Cycles, 10: 431-456. +.. _Hurttetal2006: + Hurtt, G.C., Frolking, S., Fearon, M.G., Moore, B., Shevliakova, E., Malyshev, S., Pacala, S.W., and Houghton, R.A. 2006. The underpinnings of land-use history: three centuries of global gridded land-use transitions, wood-harvest activity, and resulting secondary lands. Global Change Biol. 12:1208-1229. +.. _Hurttetal2011: + Hurtt, G.C., et al. 2011. Harmonization of land-use scenarios for the period 1500-2100: 600 years of global gridded annual land-use transitions, wood harvest, and resulting secondary lands. Climatic Change 109:117-161. DOI:10.1007/s10584-011-0153-2. +.. _Idso1981: + Idso, S.B. 1981. A set of equations for full spectrum and 8- to 14-\ :math:`\mu` \ m and 10.5- to 12.5-\ :math:`\mu` \ m thermal radiation from cloudless skies. Water Resour. Res. 17:295-304. +.. _IiyamaHasegawa2005: + Iiyama, I. and Hasegawa, S., 2005. Gas diffusion coefficient of undisturbed peat soils. Soil Science and Plant Nutrition 51:431-435. -Jackson, R. B., Canadell, J., Ehleringer, J. R., Mooney, H. A., Sala, O. +.. _Jacksonetal1996: + +Jacksonetal1996: E., and Schulze, E. D. 1996. A global analysis of root distributions for terrestrial biomes Oecologia 108:389–411. DOI:10.1007/BF00333714. +.. _Jacksonetal2010: + Jackson, T.L., Feddema, J.J., Oleson, K.W., Bonan, G.B., and Bauer, J.T. 2010. Parameterization of urban characteristics for global climate modeling. Annals of the Association of American Geographers. 100:848-865. +.. _JenkinsonColeman2008: + Jenkinson, D. and Coleman, K. 2008. The turnover of organic carbon in subsoils. Part 2. Modelling carbon turnover. European Journal of Soil Science 59:400-413. +.. _Jordan1991: + Jordan, R. 1991. A One-dimensional Temperature Model for a Snow Cover: Technical Documentation for SNTHERM.89. U.S. Army Cold Regions Research and Engineering Laboratory, Special Report 91-16. +.. _KattgeKnorr2007: + Kattge, J., and Knorr, W. 2007. Temperature acclimation in a biochemical model of photosynthesis: a reanalysis of data from 36 species. Plant Cell Environ. 30:1176-1190. DOI:10.1111/j.1365-3040.2007.01690.x. +.. _Kattgeetal2009: + 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 Biol. 15:976–991. +.. _Kelleretal2004: + Keller, M., Palace, M., Asner, G.P., Pereira, R., Jr. and Silva, J.N.M., 2004. Coarse woody debris in undisturbed and logged forests in the eastern Brazilian Amazon. Global Change Biology, 10: 784-795. +.. _Kellneretal2006: + Kellner, E., Baird, A.J., Oosterwoud, M., Harrison, K. and Waddington, J.M., 2006. Effect of temperature and atmospheric pressure on methane (CH4) ebullition from near-surface peats. Geophys. Res. Lett. 33. DOI:10.1029/2006GL027509. +.. _Kimballetal1997: + Kimball, J.S., Thornton, P.E., White, M.A. and Running, S.W. 1997. Simulating forest productivity and surface-atmosphere exchange in the BOREAS study region. Tree Physiology 17:589-599. +.. _Kohyamaetal2001: + Kohyama, T., Suzuki, E., Partomihardjo, T., and Yamada, T. 2001. Dynamic steady state of patch-mosaic tree size structure of a mixed diptocarp forest regulated by local crowding. Ecological Research 16:85-98. +.. _Kourzeneva2009: + Kourzeneva, E., 2009. Global dataset for the parameterization of lakes in Numerical Weather Prediction and Climate modeling. ALADIN Newsletter, No 37, July-December, 2009, F. Bouttier and C. Fischer, Eds., Meteo-France, Toulouse, France, 46-53. +.. _Kourzeneva2010: + Kourzeneva, E., 2010: External data for lake parameterization in Numerical Weather Prediction and climate modeling. Boreal Environment Research, 15, 165-177. +.. _Kourzenevaetal2012: + Kourzeneva, E., Asensio, H., Martin, E. and Faroux, S., 2012. Global gridded dataset of lake coverage and lake depth for use in numerical weather prediction and climate modelling. Tellus A 64. +.. _Kovenetal2009: + Koven, C., et al. 2009. On the formation of high-latitude soil carbon stocks: The effects of cryoturbation and insulation by organic matter in a land surface model. Geophys. Res. Lett. 36: L21501. +.. _Kovenetal2011: + Koven, C.D., et al. 2011. Permafrost carbon-climate feedbacks accelerate global warming. Proceedings of the National Academy of Sciences 108:14769-14774. +.. _Kovenetal2013: + Koven, C.D. et al. 2013. The effect of vertically-resolved soil biogeochemistry and alternate soil C and N models on C dynamics of CLM4. Biogeosciences Discussions 10:7201-7256. +.. _Kuchariketal2000: + Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., Lenters, J.D., Young-Molling, C., and Ramankutty, N. 2000. Testing the performance of a dynamic global ecosystem model: water balance, carbon balance, and vegetation structure. Global Biogeochem. Cycles 14: 795–825. +.. _KucharikBrye2003: + Kucharik, C.J., and Brye, K.R. 2003. Integrated BIosphere Simulator (IBIS) yield and nitrate loss predictions for Wisconsin maize receiving varied amounts of nitrogen fertilizer. Journal of Environmental Quality 32: 247–268. +.. _Laddetal2992: + Ladd, J.N., Jocteur-Monrozier, L. and Amato, M., 1992. Carbon turnover and nitrogen transformations in an alfisol and vertisol amended with [U-:math:`{}^{14}`\ C] glucose and [:math:`{}^{15}`\ N] ammonium sulfate. Soil Biology and Biochemistry, 24: 359-371. +.. _Lamarqueetal2010: + Lamarque, J.-F., et al. 2010. Historical (1850-2000) gridded anthropogenic and biomass burning emissions of reactive gases and aerosols: methodology and application. Atmos. Chem. Phys. Discuss. 10:4963-5019. DOI:10.5194/acpd-10-4963-2010. +.. _Larcher1995: + Larcher, W. 1995. Physiological Plant Ecology, Springer-Verlag, Berlin Heidelberg. +.. _LavigneRyan1997: + Lavigne, M.B., and Ryan, M.G. 1997. Growth and maintenance respiration rates of aspen, black spruce, and jack pine stems at northern and southern BOREAS sites. Tree Phys. 17:543-551. +.. _Lawetal2003: + Law, B.E., Sun, O.J., Campbell, J., Van Tuyl, S. and Thornton, P.E. 2003. Changes in carbon storage and fluxes in a chronosequence of ponderosa pine. Global Change Biology, 9: 510-514. +.. _Lawrenceetal2007: + Lawrence, D.M., Thornton, P.E., Oleson, K.W., and Bonan, G.B. 2007. The partitioning of evapotranspiration into transpiration, soil evaporation, and canopy evaporation in a GCM: Impacts on land-atmosphere interaction. J. Hydrometeor. 8:862-880. +.. _LawrenceSlater2008: + Lawrence, D.M., and Slater, A.G. 2008. Incorporating organic soil into a global climate model. Clim. Dyn. 30. DOI:10.1007/s00382-007-0278-1. +.. _Lawrenceetal2008: + Lawrence, D.M., Slater, A.G., Romanovsky, V.E., and Nicolsky, D.J. 2008. The sensitivity of a model projection of near-surface permafrost degradation to soil column depth and inclusion of soil organic matter. J. Geophys. Res. 113:F02011. DOI:10.1029/2007JF000883. +.. _Lawrenceetal2011: + Lawrence, D.M., K.W. Oleson, M.G. Flanner, P.E. Thornton, S.C. Swenson, P.J. Lawrence, X. Zeng, Z.-L. Yang, S. Levis, K. Sakaguchi, G.B. Bonan, and A.G. Slater, 2011. Parameterization improvements and functional and structural advances in version 4 of the Community Land Model. J. Adv. Model. Earth Sys. 3. DOI:10.1029/2011MS000045. +.. _LawrenceChase2007: + Lawrence, P.J., and Chase, T.N. 2007. Representing a MODIS consistent land surface in the Community Land Model (CLM 3.0). J. Geophys. Res. 112:G01023. DOI:10.1029/2006JG000168. +.. _LawrenceChase2010: + Lawrence, P.J., and Chase, T.N. 2010. Investigating the climate impacts of global land cover change in the Community Climate System Model. Int. J. Climatol. 30:2066-2087. DOI:10.1002/joc.2061. +.. _Lawrenceetal2012: + Lawrence, P.J., et al. 2012. Simulating the biogeochemical and biogeophysical impacts of transient land cover change and wood harvest in the Community Climate System Model (CCSM4) from 1850 to 2100. J. Climate 25:3071-3095. DOI:10.1175/JCLI-D-11-00256.1. +.. _LehnerDoll2004: + Lehner, B. and Döll, P., 2004. Development and validation of a global database of lakes, reservoirs and wetlands, J. Hydrol., 296, 1–22. +.. _LePageetal2010: + Le Page, Y., van der Werf, G.R., Morton, D.C., and Pereira, J.M.C. 2010. Modeling fire-driven deforestation potential in Amazonia under current and projected climate conditions. J. Geophys. Res. 115:G03012. DOI:10.1029/2009JG001190. +.. _Lerman1979: + Lerman, A., 1979. Geochemical processes: Water and sediment environments. John Wiley and Sons, New York, N.Y. +.. _Lettsetal2000: + Letts, M.G., Roulet, N.T., Comer, N.T., Skarupa, M.R., and Verseghy, D.L. 2000. Parametrization of peatland hydraulic properties for the Canadian Land Surface Scheme. Atmos.-Ocean 38:141-160. +.. _LevinKromer2004: + Levin, I. and Kromer, B. 2004. The tropospheric 14CO2 level in mid-latitudes of the Northern Hemisphere (1959-2003) Radiocarbon 46:1. +.. _Levisetal2003: + Levis, S., Wiedinmyer, C., Bonan, G.B., and Guenther, A. 2003. Simulating biogenic volatile organic compound emissions in the Community Climate System Model. J. Geophys. Res. 108:4659. DOI:10.1029/2002JD003203. +.. _Levisetal2004: + Levis, S., Bonan, G.B., Vertenstein, M., and Oleson, K.W. 2004. The community land model’s dynamic global vegetation model (CLM-DGVM): technical description and user’s guide. NCAR Technical Note NCAR/TN-459+STR. National Center for Atmospheric Research, Boulder, Colorado. 50 pp. +.. _Levisetal2009: + Levis, S., Thornton, P., Bonan, G., and Kucharik, C. 2009. Modeling land use and land management with the Community Land Model. iLeaps newsletter, No. 7. +.. _Levisetal2012: + Levis, S., Bonan, G., Kluzek, E., Thornton, P., Jones, A., Sacks, W., and Kucharik, C 2012. Interactive crop management in the Community Earth System Model (CESM1): Seasonal influences on land-atmosphere fluxes. J. Climate 25: 4839-4859. DOI:10.1175/JCLI-D-11-00446.1. +.. _Lietal2000: + Li, C., Aber, J., Stange, F., Butterbach-Bahl, K. and Papen, H. 2000. A process-oriented model of N2O and NO emissions from forest soils: 1. Model development. J. Geophys. Res. 105(D4):4369-4384. +.. _Lietal2012a: + Li, F., Zeng, X.-D., and Levis, S. 2012a. A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model. Biogeosciences 9:2761-2780. +.. _Lietal2012b: + Li, F., Zeng, X. D., and Levis, S. 2012b. Corrigendum to “A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model†published in Biogeosciences, 9, 2761–2780, 2012â€. Biogeosciences 9: 4771-4772. +.. _Lietal2013a: + Li, F., Levis, S., and Ward, D. S. 2013a. Quantifying the role of fire in the Earth system – Part 1: Improved global fire modeling in the Community Earth System Model (CESM1). Biogeosciences 10:2293-2314. +.. _Lietal2013b: + Li, H.-Y., Huang, M., Tesfa, T., Ke, Y., Sun, Y., Liu, Y., and Leung, L. R. 2013b. A subbasin-based framework to represent land surface processes in an Earth System Model, Geosci. Model Dev. Discuss. 6:2699-2730. DOI:10.5194/gmdd-6-2699-2013. +.. _Lietal2011: + Li, H., Huang, M., Wigmosta, M.S., Ke, Y., Coleman, A.M., Leung, L.R., Wang, A., and Ricciuto, D.M. 2011. Evaluating runoff simulations from the Community Land Model 4.0 using observations from flux towers and a mountainous watershed. J. Geophys. Res. 116:D24120. DOI:10.1029/2011JD016276. +.. _Liangetal1994: + Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A simple hydrologically based model of land surface water and energy fluxes for GSMs. J. Geophys. Res. 99(D7):14,415–14,428. +.. _LipscombSacks2012: + Lipscomb, W., and Sacks, W. 2012. The CESM land ice model documentation and user’s guide. 46 pp. [Available online at http://www.cesm.ucar.edu/models/cesm1.1/cism/]. +.. _LloydTaylor1994: + Lloyd, J. and Taylor, J.A., 1994. On the temperature dependence of soil respiration. Functional Ecology, 8: 315-323. +.. _Lloydetal2010: + Lloyd, J., et al. 2010. Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees. Biogeosci. 7:1833-1859. DOI:10.5194/bg-7-1833-2010. +.. _Lobelletal2006: + Lobell, D.B., Bala, G., and Duffy, P.B. 2006. Biogeophysical impacts of cropland management changes on climate. Geophys. Res. Lett. 33:L06708. DOI:10.1029/2005GL025492. +.. _Lovelandetal2000: + Loveland, T.R., Reed, B.C., Brown, J.F., Ohlen, D.O., Zhu, Z., Yang, L., and Merchant, J.W. 2000. Development of a global land cover characteristics database and IGBP DISCover from 1 km AVHRR data. Int. J. Remote Sens. 21:1303-1330. +.. _Lowe1977: + Lowe, P.R. 1977. An approximating polynomial for the computation of saturation vapor pressure. J. Appl. Meteor. 16:100-103. +.. _Luoetal2006: + Luo, Y., Hui, D., and Zhang, D. 2006. Elevated CO2 stimulates net accumulations of carbon and nitrogen in land ecosystems: a meta-analysis. Ecology 87:53-63. +.. _Magilletal1997: + Magill, A.H. et al., 1997. Biogeochemical response of forest ecosystems to simulated chronic nitrogen deposition. Ecological Applications, 7: 402-415. +.. _Mahowaldetal2006: + Mahowald, N.M., Muhs, D.R., Levis, S., Rasch, P.J., Yoshioka, M., Zender, C.S., and Luo, C. 2006. Change in atmospheric mineral aerosols in response to climate: last glacial period, pre-industrial, modern and doubled CO\ :sub:`2` climates. J. Geophys. Res\ *.* 111:D10202. DOI:10.1029/2005JD006653. +.. _Makela2002: + Makela, A. 2002. Derivation of stem taper from the pipe model theory in a carbon balance framework. Tree Phys. 22:891-905. +.. _Manning, M.R. and Melhuish, W.H. 1994. Trends: A Compendium of Data on + Manning, M.R. and Melhuish, W.H. 1994. Trends: A Compendium of Data on Global Change. Carbon Dioxide Information Analysis Center,. Oak Ridge National Laboratory, U.S. Department of Energy, Oak Ridge, Tenn., U.S.A. +.. _Maoetal2012: + Mao, J., Thornton, P.E., Shi, X., Zhao, M., and Post, W.M. 2012. Remote sensing evaluation of CLM4 GPP for the period 2000 to 2009. J. Climate 25:5327-5342. +.. _Maoetal2013: + Mao, J., Shi, X., Thornton, P.E., Hoffman, F.M., Zhu, Z., and Ranga B. Myneni, R.B. 2013. Global latitudinal-asymmetric vegetation growth trends and their driving mechanisms: 1982-2009. Remote Sensing 5:1484-1497. +.. _Martinetal1980: + Martin, J.P., Haider, K. and Kassim, G., 1980. Biodegradation and stabilization after 2 years of specific crop, lignin, and polysaccharide carbons in soils. Soil Science Society of America Journal 44:1250-1255. +.. _Maryetal1993: + Mary, B., Fresneau, C., Morel, J.L. and Mariotti, A., 1993. C and N cycling during decomposition of root mucilage, roots and glucose in soil. Soil Biology and Biochemistry 25:1005-1014. +.. _McGuireetal1992: + McGuire, A.D., Melillo, J.M., Joyce, L.A., Kicklighter, D.W., Grace, A.L., Moore III, B., and Vorosmarty, C.J. 1992. Interactions between carbon and nitrogen dynamics in estimating net primary productivity for potential vegetation in North America. Global Biogeochem. Cycles 6:101-124. +.. _MelzerOLeary1987: + Melzer, E., and O’Leary, M.H. 1987. Anapleurotic CO2 Fixation by Phosphoenolpyruvate Carboxylase in C3 Plants. Plant. Physiol. 84:58. +.. _Milleretal1994: + Miller, J.R., Russell, G.L., and Caliri, G. 1994. Continental-scale river flow in climate models. J. Climate 7:914-928. +.. _MillingtonQuirk1961: + Millington, R. and Quirk, J.P., 1961. Permeability of Porous Solids. Transactions of the Faraday Society 57:1200-1207. +.. _Mironovetal2010: + Mironov, D. et al., 2010. Implementation of the lake parameterisation scheme FLake into the numerical weather prediction model COSMO. Boreal Environment Research 15:218-230. +.. _MitchellJones2005: + Mitchell, T.D., and Jones, P.D. 2005. An improved method of constructing a database of monthly climate observations and associated high-resolution grids. Int. J. Climatol. 25:693-712. +.. _Moldrupetal2003: + Moldrup, P. et al. 2003. Modeling diffusion and reaction in soils: X. A unifying model for solute and gas diffusivity in unsaturated soil. Soil Science 168:321-337. +.. _Mynenietal2002: + Myneni, R.B., et al. 2002. Global products of vegetation leaf area and fraction absorbed PAR from year one of MODIS data. Remote Sens. Environ. 83:214-231. +.. _Neffetal2005: + Neff, J.C., Harden, J.W. and Gleixner, G. 2005. Fire effects on soil organic matter content, composition, and nutrients in boreal interior Alaska. Canadian Journal of Forest Research-Revue Canadienne De Recherche Forestiere 35:2178-2187. +.. _Neitschetal2005: + Neitsch, S.L., Arnold, J.G., Kiniry, J.R., and Williams J.R. 2005. Soil and Water Assessment Tool, Theoretical Documentation: Version 2005. Temple, TX. USDA Agricultural Research Service and Texas A&M Blackland Research Center. +.. _NemaniRunning1996: + Nemani, R.R., and Running, S.W. 1996. Implementation of a hierarchical global vegetation classification in ecosystem function models. J. Veg. Sci. 7:337-346. +.. _Niinemetstal1998: + Niinemets, U., Kull, O., and Tenhunen, J.D. 1998. An analysis of light effects on foliar morphology, physiology, and light interception in temperate deciduous woody species of contrasting shade tolerance. Tree Phys. 18:681-696. +.. _Niuetal2005: + Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. @@ -838,22 +1216,32 @@ Niu, G.-Y., and Yang, Z.-L. 2007. An observation-based formulation of snow cover fraction and its evaluation over large North American river basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674. +.. _NydalLovseth1996: + Nydal, R. and Lövseth, K. 1996. Carbon-14 Measurements In Atmospheric CO2 From Northern And Southern Hemisphere Sites, 1962-1993, Carbon Dioxide Information Analysis Center. +.. _Oikawaetal2005: + Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and nitrogen in the canopy of an annual herb, Xanthium canadense. Oecologia, 143: 517-526. +.. _Oke1987: + Oke, T. 1987. Boundary Layer Climates (2:math:`{}^{nd}` edition). Routledge, London and New York. +.. _OlesonBonan2000: + Oleson, K.W., and Bonan, G.B. 2000. The effects of remotely-sensed plant functional type and leaf area index on simulations of boreal forest surface fluxes by the NCAR land surface model. J. Hydrometeor. 1:431-446. +.. _Olesonetal2004: + Oleson, K.W., Dai, Y., Bonan, G., Bosilovich, M., Dickinson, R., Dirmeyer, P., Hoffman, F., Houser, P., Levis, S., Niu, G.-Y., Thornton, P., Vertenstein, M., Yang, Z.-L., and Zeng. X. 2004. Technical @@ -861,34 +1249,48 @@ description of the Community Land Model (CLM). NCAR Technical Note NCAR/TN-461+STR. National Center for Atmospheric Research, Boulder, Colorado. 173 pp. +.. _Olesonetal2008a: + Oleson, K.W., Niu, G.-Y., Yang, Z.-L., Lawrence, D.M., Thornton, P.E., Lawrence, P.J., Stöckli, R., Dickinson, R.E., Bonan, G.B., Levis, S., Dai, A., and Qian, T. 2008a. Improvements to the Community Land Model and their impact on the hydrological cycle. J. Geophys. Res. 113:G01021. DOI:10.1029/2007JG000563. +.. _Olesonetal2008b: + Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Grimmond, C.S.B. 2008b. An urban parameterization for a global climate model. 1. Formulation and evaluation for two cities. J. Appl. Meteor. Clim. 47:1038-1060. +.. _Olesonetal2008c: + Oleson, K.W., Bonan, G.B., Feddema, J., and Vertenstein, M. 2008c. An urban parameterization for a global climate model. 2. Sensitivity to input parameters and the simulated urban heat island in offline simulations. J. Appl. Meteor. Clim. 47:1061-1076. +.. _Olesonetal2010a: + Oleson, K.W., et al. 2010a. Technical description of version 4.0 of the Community Land model (CLM). NCAR Technical Note NCAR/TN-478+STR, National Center for Atmospheric Research, Boulder, CO, 257 pp. +.. _Olesonetal2010b: + Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Kluzek, E. 2010b. Technical description of an urban parameterization for the Community Land Model (CLMU). NCAR Technical Note NCAR/TN-480+STR, National Center for Atmospheric Research, Boulder, CO, 169 pp. +.. _Olson1963: + Olson, J.S., 1963. Energy storage and the balance of producers and decomposers in ecological systems. Ecology 44:322-331. +.. _Olsonetal2001: + Olson, D.M., Dinerstein, E., Wikramanayake, E.D., Burgess, N.D., Powell, G.V.N., Underwood, E.C., D’Amico, J.A., Itoua, I., Strand, H. E., Morrison, J. C., Loucks, C. J., Allnutt, T. F., Ricketts, T. H., Kura, @@ -896,139 +1298,207 @@ Y., Lamoreux, J. F., Wettengel, W. W., Heda, P., and Kassem, K. R., 2001. Terrestrial ecoregions of the world a new map of life on earth, Bioscience, 51, 933–938. +.. _OrchardCook1983: + Orchard, V.A. and Cook, F.J., 1983. Relationship between soil respiration and soil moisture. Soil Biology and Biochemistry, 15: 447-453. +.. _Owen1964: + Owen, P.R. 1964. Saltation of uniform grains in air. J. Fluid Mech\ *.* 20:225-242. +.. _Ozdoganetal2010: + Ozdogan, M., Rodell, M., Beaudoing, H.K., and Toll, D.L. 2010. Simulating the effects of irrigation over the United States in a land surface model based on satellite-derived agricultural data. Journal of Hydrometeorology 11:171-184. +.. _Pageetal2002: + Page, S.E., Siegert, F., Rieley, J.O., Boehm, H-D.V., Jaya, A., and Limin, S. 2002. The amount of carbon released from peat and forest fires in Indonesia in 1997. Nature 420:61-65. +.. _PanofskyDutton1984: + Panofsky, H.A., and Dutton, J.A. 1984. Atmospheric Turbulence: Models and Methods for Engineering Applications. John Wiley and Sons, New York. +.. _Partonetal1988: + Parton, W., Stewart, J. and Cole, C., 1988. Dynamics of C, N, P And S in Grassland Soils - A Model. Biogeochemistry 5:109-131. +.. _Partonetal1993: + Parton, W.J., et al. 1993. Observations and modeling of biomass and soil organic matter dynamics for the grassland biome worlwide. Global Biogeochemical Cycles 7:785-809. +.. _Partonetal1996: + Parton, W. et al. 1996. Generalized model for N2 and N2O production from nitrification and denitrification. Global Biogeochemical Cycles 10:401-412. +.. _Partonetal2001: + Parton, W.J. et al. 2001. Generalized model for NOx and N2O emissions from soils. J. Geophys. Res. 106(D15):17403-17419. +.. _Paterson1994: + Paterson, W.S.B., 1994. The Physics of Glaciers. Elsevier Science Inc., New York, 480 pp. +.. _Petrescuetal2010: + Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions of boreal and arctic wetlands. Global Biogeochemical Cycles, 24(GB4009). +.. _Philip1957: + Philip, J.R. 1957. Evaporation, and moisture and heat fields in the soil. J. Meteor. 14:354-366. +.. _Piaoetal2012: + Piao, S.L., et al. 2012. The carbon budget of terrestrial ecosystems in East Asia over the last two decades. Biogeosciences 9:3571-3586. +.. _Pivovarov1972: + Pivovarov, A.A., 1972. Thermal Conditions in Freezing Lakes and Reservoirs. John Wiley, New York. +.. _Pollmeretal1979: + Pollmer, W.G., Eberhard, D., Klein, D., and Dhillon, B.S. 1979. Genetic control of nitrogen uptake and translocation in maize. Crop Sci. 19:82-86. +.. _Portmann2010: + Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global monthly irrigated and rainfed crop areas around the year 2000: A new high-resolution data set for agricultural and hydrological modeling. Global Biogeochem. Cycles. 24, GB1011. DOI:10.1029/2008GB003435. +.. _Pressetal1992: + Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P. 1992. Numerical Recipes in FORTRAN: The Art of Scientific Computing. Cambridge University Press, New York. +.. _Prigentetal2007: + Prigent, C., Papa, F., Aires, F., Rossow, W.B. and Matthews, E. 2007. Global inundation dynamics inferred from multiple satellite observations, 1993-2000. J. Geophys. Res. 112(D12). +.. _Pritchardetal2008: + Pritchard, M.S., Bush, A.B.G., and Marshall, S.J. 2008. Neglecting ice-atmosphere interactions underestimates ice sheet melt in millennial-scale deglaciation simulations. Geophys. Res. Lett. ** 35:L01503. DOI:10.1029/2007GL031738. +.. _Qianetal2006: + Qian, T., Dai, A., Trenberth, K.E., and Oleson, K.W. 2006. Simulation of global land surface conditions from 1948 to 2004: Part I: Forcing data and evaluations. J. Hydrometeor. 7:953-975. +.. _RamankuttyFoley1998: + Ramankutty, N., and Foley, J. A., 1998. Characterizing patterns of global land use: An analysis of global croplands data. Global Biogeochemical Cycles, 12, 667-685. +.. _Ramankuttyetal2008: + Ramankutty, N., Evan, A., Monfreda, C., and Foley, J.A. 2008. Farming the Planet. Part 1: The Geographic Distribution of Global Agricultural Lands in the Year 2000. Global Biogeochem. Cycles. 22:GB1003. DOI:10.1029/2007GB002952. +.. _Randlettetal1996: + Randlett, D.L., Zak, D.R., Pregitzer, K.S., and Curtis, P.S. 1996. Elevated atmospheric carbon dioxide and leaf litter chemistry: Influences on microbial respiration and net nitrogen mineralization. Soil Sci. Soc. Am. J. 60:1571-1577. +.. _Rastetteretal1991: + Rastetter, E.B., Ryan, M.G., Shaver, G.R., Melillo, J.M., Nadelhoffer, K.J., Hobbie, J.E., and Aber, J.D. 1991. A general biogeochemical model describing the responses of the C and N cycles in terrestrial ecosystems to changes in CO2, climate and N deposition. Tree Phys. 9:101-126. +.. _Rastneretal2012: + Rastner, P., Bolch, T., Mölg, N., Machguth, H., and Paul, F., 2012. The first complete glacier inventory for the whole of Greenland, The Cryosphere Discuss., 6, 2399-2436, 10.5194/tcd-6-2399-2012. +.. _Rileyetal2011a: + Riley, W. J., Z. M. Subin, D. M. Lawrence, S. C. Swenson, M. S. Torn, L. Meng, N. Mahowald, and P. Hess, 2011a. Barriers to predicting global terrestrial methane fluxes: Analyses using a methane biogeochemistry model integrated in CESM. Biogeosciences, 8, 1925–1953. DOI:10.5194/bg-8-1925-2011. +.. _Rileyetal2011b: + Riley, W.J. et al. 2011b. CLM4Me, a Methane Biogeochemistry Model Integrated in CESM, Land and Biogeochemistry Model Working Group Meeting, Boulder, CO. +.. _Ryan1991: + Ryan, M. G. 1991. A simple method for estimating gross carbon budgets for vegetation in forest ecosystems. Tree Phys. 9:255-266. +.. _RunningCoughlan1988: + Running, S.W. and Coughlan, J.C., 1988. A general model of forest ecosystem processes for regional applications. I. Hydrological balance, canopy gas exchange and primary production processes. Ecological Modelling, 42: 125-154. +.. _Runningetal1989: + Running, S.W. et al., 1989. Mapping regional forest evapotranspiration and photosynthesis by coupling satellite data with ecosystem simlation. Ecology, 70: 1090-1101. +.. _RunningGower1991: + Running, S.W. and Gower, S.T., 1991. FOREST BGC, A general model of forest ecosystem processes for regional applications. II. Dynamic carbon allocation and nitrogen budgets. Tree Physiology, 9: 147-160. +.. _RunningHunt1993: + Running, S.W. and Hunt, E.R., Jr., 1993. Generalization of a forest ecosystem process model for other biomes, BIOME-BGC, and an applicationfor global-scale models. In: J.R. Ehleringer and C. Field (Editors), Scaling Physiological Processes: Leaf to Globe. Academic Press, San Diego, CA, pp. 141-158. -Sacks, W. J., Cook, B. I., Buenning, N., Levis, S., and Helkowski, J. H. +.. _Sacksetal2009: + +Sacks, W. J., Cook, B. I., Buenning, N., Levis, S., and Helkowski, J. H. 2009. Effects of global irrigation on the near-surface climate. Climate Dyn., 33, 159–175. DOI:10.1007/s00382-008-0445-z. +.. _Saggaretal1994: + Saggar, S., Tate, K.R., Feltham, C.W., Childs, C.W. and Parshotam, A., 1994. Carbon turnover in a range of allophanic soils amended with :math:`{}^{14}`\ C-labelled glucose. Soil Biology and Biochemistry, 26: @@ -1039,315 +1509,463 @@ and under-canopy atmospheric stability on ground evaporation in the Community Land Model (CLM3.5). J. Geophys. Res. 114:D01107. DOI:10.1029/2008JD010834. +.. _Schaafetal2002: + Schaaf, C.B., Gao, F., Strahler, A.H., Lucht, W., Li, X., Tsang, T., Strugnell, N.C., Zhang, X., Jin, Y., and Muller, J.-P. 2002. First operational BRDF, albedo nadir reflectance products from MODIS. Remote Sens. Environ. 83:135-148. +.. _Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. + Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. Academic Press, London, 588 pp. +.. _SchnellKing1996: + Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity in soils and cultures to water stress. Applied and Environmental Microbiology 62:3203-3209. +.. _Segers, R., 1998. Methane production and methane consumption: a review + Segers, R., 1998. Methane production and methane consumption: a review of processes underlying wetland methane fluxes. Biogeochemistry 41:23-51. +.. _Sellers1985: + Sellers, P.J. 1985. Canopy reflectance, photosynthesis and transpiration. Int. J. Remote Sens. 6:1335-1372. +.. _Sellersetal1986: + Sellers, P.J., Mintz, Y., Sud, Y.C., and Dalcher, A. 1986. A simple biosphere model (SiB) for use within general circulation models. J. Atmos. Sci. 43:505-531. +.. _Sellersetal1988: + Sellers, P.J., Hall, F.G., Asrar, G., Strebel, D.E., and Murphy, R.E. 1988. The First ISLSCP Field Experiment (FIFE). Bull. Amer. Meteor. Soc. 69:22-27. +.. _Sellersetal1992: + Sellers, P.J., Berry, J.A., Collatz, G.J., Field, C.B., and Hall, F.G. 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. +.. _Sellersetal1995: + Sellers, P.J., et al. 1995. The Boreal Ecosystem-Atmosphere Study (BOREAS): An overview and early results from the 1994 field year. Bull. Amer. Meteor. Soc. 76:1549-1577. +.. _Sellersetal1996: + Sellers, P.J., Randall, D.A., Collatz, G.J., Berry, J.A., Field, C.B., Dazlich, D.A., Zhang, C., Collelo, G.D., and Bounoua, L. 1996. A revised land surface parameterization (SiB2) for atmospheric GCMs. Part I: Model formulation. J. Climate 9:676-705. +.. _Shietal2013: + Shi, X., Mao, J., Thornton, P.E., and Huang, M. 2013. Spatiotemporal patterns of evapotranspiration in response to multiple environmental factors simulated by the Community Land Model. Environ. Res. Lett. 8:024012. +.. _Shiklomanov2000: + Shiklomanov, I.A. 2000. Appraisal and assessment of world water resources. Water International 25:11-32. +.. _Siebertetal2005: + Siebert, S., Döll, P., Hoogeveen, J., Faures, J.M., Frenken, K., Feick, S., 2005. Development and validation of the global map of irrigation areas. Hydrol Earth Syst Sc 9:535–547 +.. _Simpsonetal1983: + Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen redistribution during grain growth in wheat (Triticum avestivum L.). Plant Physiol. 71:7-14. +.. _Smithetal2005: + Smith, A.M.S., Wooster, M.J., Drake, N.A., Dipotso, F.M. and Perry, G.L.W., 2005. Fire in African savanna: Testing the impact of incomplete combustion on pyrogenic emissions estimates. Ecological Applications, 15: 1074-1082. +.. _Sollins1982: + Sollins, P., 1982. Input and decay of coarse woody debris in coniferous stands in western Oregon and Washington. Canadian Journal of Forest Research, 12: 18-28. +.. _SonGower1991: + Son, Y. and Gower, S.T., 1991. Aboveground nitrogen and phosphorus use by five plantation-grown trees with different leaf longevities. Biogeochemistry, 14: 167-191. +.. _Sorensen1981: + Sørensen, L.H., 1981. Carbon-nitrogen relationships during the humification of cellulose in soils containing different amounts of clay. Soil Biology and Biochemistry, 13: 313-321. +.. _Sprugeletal1995: + Sprugel, D.G., Ryan, M.G., Brooks, J.R., Vogt, K.A., and Martin, T.A. 1995. Respiration from the organ level to stand level. pp. 255-299. In: W. K. Smith and T. M. Hinkley (editors) Resource Physiology of Conifers. Academic Press, San Diego,CA. +.. _StaufferAharony1994: + Stauffer, D., and Aharony, A. 1994. Introduction to Percolation Theory. Taylor and Francis, London. +.. _Stilletal2003: + Still, C.J., Berry, J.A., Collatz, G.J., and DeFries, R.S. 2003. Global distribution of C3 and C4 vegetation: carbon cycle implications. Global Biogeochem. Cycles 17:1006. DOI:10.1029/2001GB001807. +.. _Stocklietal2008: + Stöckli, R., Lawrence, D.M., Niu, G.-Y., Oleson, K.W., Thornton, P.E., Yang, Z.-L., Bonan, G.B., Denning, A.S., and Running, S.W. 2008. Use of FLUXNET in the Community Land Model development. J. Geophys. Res. 113:G01025. DOI:10.1029/2007JG000562. +.. _Stracketal2006: + Strack, M., Kellner, E. and Waddington, J.M., 2006. Effect of entrapped gas on peatland surface level fluctuations. Hydrological Processes 20:3611-3622. +.. _Strahleretal1999: + Strahler, A.H., Muchoney, D., Borak, J., Friedl, M., Gopal, S., Lambin, E., and Moody. A. 1999. MODIS Land Cover Product: Algorithm Theoretical Basis Document (Version 5.0). Boston University, Boston. +.. _Stull1988: + Stull, R.B. 1988. An Introduction to Boundary Layer Meteorology. Kluwer Academic Publishers, Dordrecht. +.. _Subinetal2012a: + Subin, Z.M., Riley, W.J. and Mironov, D. 2012a. Improved lake model for climate simulations, J. Adv. Model. Earth Syst., 4, M02001. DOI:10.1029/2011MS000072. +.. _Subinetal2012b: + Subin, Z.M., Murphy, L.N., Li, F., Bonfils, C. and Riley, W.J., 2012b. Boreal lakes moderate seasonal and diurnal temperature variation and perturb atmospheric circulation: analyses in the Community Earth System Model 1 (CESM1). Tellus A, North America, 64. +.. _Sunetal2012: + Sun, Y., Gu, L., and Dickinson, R. E. 2012. A numerical issue in calculating the coupled carbon and water fluxes in a climate model, J. Geophys. Res., 117, D22103. DOI:10.1029/2012JD018059. +.. _Swensonetal2012: + Swenson, S.C., Lawrence, D.M., and Lee, H. 2012. Improved Simulation of the Terrestrial Hydrological Cycle in Permafrost Regions by the Community Land Model. JAMES, 4, M08002. DOI:10.1029/2012MS000165. +.. _SwensonLawrence2012: + Swenson, S.C. and Lawrence, D.M. 2012. A New Fractional Snow Covered Area Parameterization for the Community Land Model and its Effect on the Surface Energy Balance. JGR, 117, D21107. DOI:10.1029/2012JD018178. +.. _TaWeiland1992: + Ta, C.T. and Weiland, R.T. 1992. Nitrogen partitioning in maize during ear development. Crop Sci. 32:443-451. +.. _TangRiley2013: + Tang, J.Y. and Riley, W.J. 2013. A new top boundary condition for modeling surface diffusive exchange of a generic volatile tracer: Theoretical analysis and application to soil evaporation. Hydrol. Earth Syst. Sci. 17:873-893. +.. _Tarnocaietal2011: + Tarnocai, C., Kettles, I. M., and Lacelle, B., 2011. Peatlands of Canada, Geological Survey of Canada, Open File 6561, CD-ROM. DOI:10.495/288786. +.. _Tayloretal1989: + Taylor, B.R., Parkinson, D. and Parsons, W.F.J., 1989. Nitrogen and lignin content as predictors of litter decay rates: A microcosm test. Ecology, 70: 97-104. +.. _Thonickeetal2001: + Thonicke, K., Venevsky, S., Sitch, S., and Cramer, W. 2001. The role of fire disturbance for global vegetation dynamics: coupling fire into a Dynamic Global Vegetation Model. Global Ecology and Biogeography 10:661-667. +.. _Thornton1998: + Thornton, P.E., 1998. Regional ecosystem simulation: combining surface- and satellite-based observations to study linkages between terrestrial energy and mass budgets. Ph.D. Thesis, The University of Montana, Missoula, 280 pp. +.. _Thorntonetal2002: + Thornton, P.E., Law, B.E., Gholz, H.L., Clark, K.L., Falge, E., Ellsworth, D.S., Goldstein, A.H., Monson, R.K., Hollinger, D., Falk, M., Chen, J., and Sparks, J.P. 2002. Modeling and measuring the effects of disturbance history and climate on carbon and water budgets in evergreen needleleaf forests. Agric. For. Meteor. 113:185-222. +.. _ThorntonRosenbloom2005: + Thornton, P.E., and Rosenbloom, N.A. 2005. Ecosystem model spin-up: estimating steady state conditions in a coupled terrestrial carbon and nitrogen cycle model. Ecological Modelling 189:25-48. +.. _ThorntonZimmermann2007: + Thornton, P.E., and Zimmermann, N.E. 2007. An improved canopy integration scheme for a land surface model with prognostic canopy structure. J. Climate 20:3902-3923. +.. _Thorntonetal2007: + Thornton, P.E., Lamarque, J.-F., Rosenbloom, N.A., and Mahowald, N.M. 2007. Influence of carbon-nitrogen cycle coupling on land model response to CO\ :sub:`2` fertilization and climate variability. Global Biogeochem. Cycles 21:GB4018. +.. _Thorntonetal2009: + Thornton, P.E., Doney, S.C., Lindsay, K., Moore, J.K., Mahowald, N., Randerson, J.T., Fung, I., Lamarque, J.F., Feddema, J.J., and Lee, Y.H. 2009. Carbon-nitrogen interactions regulate climate-carbon cycle feedbacks: results from an atmosphere-ocean general circulation model. Biogeosci. 6:2099-2120. +.. _Tianetal2010: + Tian, H. et al. 2010. Spatial and temporal patterns of CH4 and N2O fluxes in terrestrial ecosystems of North America during 1979-2008: application of a global biogeochemistry model. Biogeosciences 7:2673-2694. +.. _Toonetal1989: + Toon, O.B., McKay, C.P., Ackerman, T.P., and Santhanam, K. 1989. Rapid calculation of radiative heating rates and photodissociation rates in inhomogeneous multiple scattering atmospheres. J. Geophys. Res. 94(D13):16,287-16,301. +.. _Turetskyetal2002: + Turetsky, M.R., Wieder, R.K., Halsey, L.A., and Vitt, D.H. 2002. Current disturbance and the diminishing peatland carbon sink. Geophys. Res. Lett. 29:1526. DOI:10.1029/2001GL014000. -Turetsky, M.R., Amiro, B.D., Bosch, E., andBhatti, J.S. 2004. Historical +.. _Turetskyetal2004: + +Turetsky, M.R., Amiro, B.D., Bosch, E., and Bhatti, J.S. 2004. Historical burn area in western Canadian peatlands and its relationship to fire weather indices. Global Biogeochem. Cycles 18:GB4014. DOI:10.1029/2004GB002222. +.. _Turnbulletal2007: + Turnbull, J.C. et al. 2007. A new high precision (CO2)-C-14 time series for North American continental air. Journal of Geophysical Research-Atmospheres 112(D11). +.. _Tyeetal2005: + Tye, A.M., et al. 2005. The fate of N-15 added to high Arctic tundra to mimic increased inputs of atmospheric nitrogen released from a melting snowpack. Global Change Biology 11:1640-1654. +.. _Unlandetal1996: + Unland, H.E., Houser, P.R., Shuttleworth, W.J., and Yang, Z.-L. 1996. Surface flux measurement and modeling at a semi-arid Sonoran Desert site. Agric. For. Meteor. 82:119-153. +.. _UNSTAT2005: + UNSTAT, 2005. National Accounts Main Aggregates Database, United Nations Statistics Division. +.. _VallanoSparks2007: + Vallano, D.M. and Sparks, J.P. 2007. Quantifying foliar uptake of gaseous itrogen dioxide using enriched foliar :math:`\delta^{15}`\ N values. New Phytologist 177:946-955. +.. _vanderWerfetal2010: + van der Werf, G.R., Randerson, J.T., Giglio, L., Collatz, G.J., Mu, M., Kasibhatla, S.P., Morton, D.C., DeFries, R.S., Jin, Y., van Leeuwen, T.T. 2010. Global fire emissions and the contribution of deforestation, savanna, forest, agricultural, and peat fires (1997-2009) Atmos. Chem. Phys. 10:11707-11735. +.. _van Veenetal1984: + van Veen, J.A., Ladd, J.N. and Frissel, M.J., 1984. Modelling C and N turnover through the microbial biomass in soil. Plant and Soil, 76: 257-274. +.. _VanVuurenetal2006: + Van Vuuren, D.P., Lucas, P.S., and Hilderink, H.B.M., 2006. Downscaling drivers of global environmental change: enabling use of global SRES scenarios at the national and grid levels, Report 550025001, Netherlands Environmental Assessment Agency, 45 pp. +.. _Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: + Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: effects of size, competition and site fertility on growth allocation and production. Tree Phys. 25:17-30. +.. _VerdinGreenlee1996: + Verdin, K. L., and S. K. Greenlee, 1996. Development of continental scale digital elevation models and extraction of hydrographic features, paper presented at the Third International Conference/Workshop on Integrating GIS and Environmental Modeling, Santa Fe, New Mexico, 21–26 January, Natl. Cent. for Geogr. Inf. and Anal., Santa Barbara, Calif. +.. _Viovy2011: + Viovy, N. 2011. CRUNCEP dataset. [Description available at http://dods.extra.cea.fr/data/p529viov/cruncep/readme.htm. Data available at http://dods.extra.cea.fr/store/p529viov/cruncep/V4\_1901\_2011/]. +.. _VitousekHowarth1991: + Vitousek, P.M., and Howarth, R.W. 1991. Nitrogen limitation on land and in the sea: How can it occur? Biogeochem. 13:87-115. +.. _Walteretal2001: + Walter, B.P., Heimann, M. and Matthews, E., 2001. Modeling modern methane emissions from natural wetlands 1. Model description and results. J. Geophys. Res. 106(D24):34189-34206. +.. _Waniaetal2009: + Wania, R., Ross, I. and Prentice, I.C. 2009. Integrating peatlands and permafrost into a dynamic global vegetation model: 2. Evaluation and sensitivity of vegetation and carbon cycle processes. Global Biogeochem. Cycles 23. +.. _Waniaetal2010: + Wania, R., Ross, I. and Prentice, I.C. 2010. Implementation and evaluation of a new methane model within a dynamic global vegetation model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions 3:1-59. +.. _WangZeng2009: + Wang, A., and Zeng, X. 2009. Improving the treatment of vertical snow burial fraction over short vegetation in the NCAR CLM3. Adv. Atmos. Sci. 26:877-886. DOI:10.1007/s00376-009-8098-3. +.. _Whiteetal1997: + White, M.A., Thornton, P.E., and Running, S.W. 1997. A continental phenology model for monitoring vegetation responses to interannual climatic variability. Global Biogeochem. Cycles 11:217-234. +.. _Whiteetal2000: + White, M.A., Thornton, P.E., Running, S.W., and Nemani, R.R. 2000. Parameterization and sensitivity analysis of the Biome-BGC terrestrial ecosystem model: net primary production controls. Earth Interactions 4:1-85. +.. _WiscombeWarren1980: + Wiscombe, W.J., and Warren, S.G. 1980. A model for the spectral albedo of snow. I. Pure snow. J. Atmos. Sci. 37:2712-2733. +.. _Woodetal1992: + Wood, E.F., Lettenmaier, D.P., and Zartarian, V.G. 1992. A land-surface hydrology parameterization with subgrid variability for general circulation models. J. Geophys. Res. 97(D3):2717–2728. DOI:10.1029/91JD01786. +.. _World Bank2004: + World Bank, 2004. World development indicators 2004, Oxford University Press, New York, 416 pp. +.. _Yang1998: + Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and temperature model. Unpublished manuscript. +.. _Zenderetal2003: + Zender, C.S., Bian, H., and Newman, D. 2003. Mineral dust entrainment and deposition (DEAD) model: Description and 1990s dust climatology. ** J. Geophys. Res\ *.* 108(D14):4416. DOI:10.1029/2002JD002775. +.. _ZengDickinson1998: + Zeng, X., and Dickinson, R.E. 1998. Effect of surface sublayer on surface skin temperature and fluxes. J.Climate 11:537-550. +.. _Zengetal1998: + Zeng, X., Zhao, M., and Dickinson, R.E. 1998. Intercomparison of bulk aerodynamic algorithms for the computation of sea surface fluxes using the TOGA COARE and TAO data. J. Climate 11:2628-2644. +.. _Zeng2001: + Zeng, X. 2001. Global vegetation root distribution for land modeling. J. Hydrometeor. 2:525-530. +.. _Zengetal2002: + Zeng, X., Shaikh, M., Dai, Y., Dickinson, R.E., and Myneni, R. 2002. Coupling of the Common Land Model to the NCAR Community Climate Model. J. Climate 15:1832-1854. +.. _Zengetal2005: + Zeng, X., Dickinson, R.E., Barlage, M., Dai, Y., Wang, G., and Oleson, K. 2005. Treatment of under-canopy turbulence in land models. J. Climate 18:5086-5094. +.. _ZengWang2007: + Zeng, X., and Wang, A. 2007. Consistent parameterization of roughness length and displacement height for sparse and dense canopies in land models. J. Hydrometeor. 8:730-737. @@ -1356,20 +1974,28 @@ Zeng, X., and Decker, M. 2009. Improving the numerical solution of soil moisture-based Richards equation for land models with a deep or shallow water table. J. Hydrometeor. 10:308-319. +.. _Zengetal2008: + Zeng, X., Zeng, X., and Barlage, M. 2008. Growing temperate shrubs over arid and semiarid regions in the Community Land Model - Dynamic Global Vegetation Model. Global Biogeochem. Cycles 22:GB3003. DOI:10.1029/2007GB003014. +.. _Zhangetal2002: + Zhang, Y., Li, C.S., Trettin, C.C., Li, H. and Sun, G., 2002. An integrated model of soil, hydrology, and vegetation for carbon dynamics in wetland ecosystems. Global Biogeochemical Cycles 16. DOI:10.1029/2001GB001838. +.. _Zhuangetal2004: + Zhuang, Q., et al. 2004. Methane fluxes between terrestrial ecosystems and the atmosphere at northern high latitudes during the past century: A retrospective analysis with a process-based biogeochemistry model. Global Biogeochemical Cycles 18. DOI:10.1029/2004GB002239. +.. _Zilitinkevich1970: + Zilitinkevich, S.S. 1970. Dynamics of the Atmospheric Boundary Layer. Leningrad Gidrometeor. diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index f586313340..f033832ceb 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -3,9 +3,8 @@ Snow Hydrology =============== -The model parameterizes -The parameterizations for snow are based primarily on Anderson (1976), -country-regionplaceJordan (1991), and Dai and Zeng (1997). The snowpack +The parameterizations for snow are based primarily on :ref:`Anderson (1976) `, +:ref:`Jordan (1991) `, and :ref:`Dai and Zeng (1997) `. The snowpack can have up to five layers. These layers are indexed in the Fortran code as :math:`i=-4,-3,-2,-1,0` where layer :math:`i=0` is the snow layer next to the top soil layer and layer :math:`i=-4` is the top layer of a @@ -55,7 +54,8 @@ Snow Covered Area Fraction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The fraction of the ground covered by snow, :math:`f_{sno}` , is based -on the method of Swenson and Lawrence (2012). Because the processes +on the method of :ref:`Swenson and Lawrence (2012) `. +Because the processes governing snowfall and snowmelt differ, changes in :math:`f_{sno}` are calculated separately for accumulation and depletion. When snowfall occurs, :math:`f_{sno}` is updated as @@ -138,7 +138,7 @@ where \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg -m\ :sup:`-3`) (CityplaceAnderson 1976) +m\ :sup:`-3`) (:ref:`Anderson (1976) `) .. math:: :label: 8.21) @@ -260,7 +260,7 @@ where the volumetric liquid water :math:`\theta _{liq,\, i}` and ice and :math:`S_{r} =0.033` is the irreducible water saturation (snow holds a certain amount of liquid water due to capillary retention after -drainage has ceased (Anderson 1976)). The water holding capacity of the +drainage has ceased (:ref:`Anderson (1976) `)). The water holding capacity of the underlying layer limits the flow of water :math:`q_{liq,\, i}` calculated in equation , unless the underlying layer is the surface soil layer, as @@ -357,7 +357,7 @@ is the model time step (s). The particle mass mixing ratio is c_{i} =\frac{m_{sp,\, i} }{w_{liq,\, i} +w_{ice,\, i} } . Values of :math:`k_{sp}` are partially derived from experiments -published by Conway et al. (1996). Particles masses are re-distributed +published by :ref:`Conway et al. (1996) `. Particles masses are re-distributed proportionately with snow mass when layers are combined or divided, thus conserving particle mass within the snow column. The mass of particles carried out with meltwater through the bottom snow layer is assumed to @@ -367,7 +367,7 @@ model. .. _Table Meltwater scavenging: .. table:: Meltwater scavenging efficiency for particles within snow - + +------------------------------------------+-------------------+ | Species | :math:`k_{sp}` | +==========================================+===================+ @@ -410,8 +410,7 @@ Snow Compaction Snow compaction is initiated after the soil hydrology calculations [surface runoff (section :numref:`Surface Runoff`), infiltration (section -:numref:`Infiltration`), soil water (section :numref:`Soil Water`), -groundwater-soilwater interactions (section 8.6)] are +:numref:`Infiltration`), soil water (section :numref:`Soil Water`)] are complete. Compaction of snow includes three types of processes: destructive metamorphism of new snow (crystal breakdown due to wind or thermodynamic stress); snow load or overburden (pressure); and melting @@ -435,7 +434,7 @@ Compaction is not allowed if the layer is saturated or if the ice content is below a minimum value (:math:`w_{ice,\, i} \le 0.1`). -Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (CityplaceAnderson 1976) +Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (:ref:`Anderson (1976) `) .. math:: :label: 8.43) @@ -458,7 +457,7 @@ and :math:`{w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` are the bulk densities of liquid water and ice (kg m\ :sup:`-3`). -The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (CityplaceAnderson 1976) +The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (:ref:`Anderson (1976) `) .. math:: :label: 8.45) @@ -520,7 +519,7 @@ After the determination of snow temperature including phase change(Chapter :numref:`rst_Snow Hydrology`), and the compaction calculations (section :numref:`Snow Compaction`) , the number of snow layers is adjusted by either combining or subdividing layers. The combination and subdivision -of snow layers is based on Jordan (1991). +of snow layers is based on :ref:`Jordan (1991) `. .. _Combination: diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index 946dbd4c45..c1971be79a 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -50,7 +50,7 @@ snow, and surface water layers from the overlying atmosphere (section temperature profile is calculated first without phase change and then readjusted for phase change (section 6.2). -.. _Numerical Solution: +.. _Numerical Solution Temperature: Numerical Solution ---------------------- From cdbd9fe94196b30ffb3b4f7e17df16a37bae29ac Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Tue, 23 May 2017 10:57:23 -0600 Subject: [PATCH 016/255] add vertical discretization --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 40 ++ .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 249 +++++++--- .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 84 +++- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 440 ++++-------------- .../CLM50_Tech_Note_Photosynthesis.rst | 282 +++++------ .../References/CLM50_Tech_Note_References.rst | 17 +- .../CLM50_Tech_Note_Snow_Hydrology.rst | 13 +- ...CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 141 ++---- .../CLM50_Tech_Note_Surface_Albedos.rst | 134 +++--- 9 files changed, 649 insertions(+), 751 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 80cd1e3527..f0f31eac92 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -3,6 +3,8 @@ Crops and Irrigation ======================== +.. _Summary of CLM4.5 updates relative to the CLM4.0: + Summary of CLM4.5 updates relative to the CLM4.0 ----------------------------------------------------- @@ -30,6 +32,8 @@ refers to the interactive crop management model: These updates appear in detail in section 20.4. Most also appear in Drewniak et al. (2013). +.. _The crop model: + The crop model ------------------- @@ -65,6 +69,8 @@ while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., Kucharik and Brye 2003; Lobell et al. 2006). +.. _Crop plant functional types: + Crop plant functional types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -95,6 +101,8 @@ CLM setting). Managed crop PFTs in the human managed land unit do not share soil columns and thus permit for differences in land management between crops. +.. _Phenology: + Phenology ^^^^^^^^^^^^^^^^ @@ -109,6 +117,8 @@ continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. +.. _Planting: + Planting ''''''''''''''''' @@ -175,6 +185,8 @@ outside the above ranges, then it equals the minimum or maximum value in the range. Also :math:`{T}_{f}` equals 273.15 K, :math:`{T}_{2m}` has units of K, and *GDD* has units of :sup:`o`\ days. +.. _Leaf emergence: + Leaf emergence ''''''''''''''''''''''' @@ -188,6 +200,8 @@ time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases and reaches a maximum value during phase 2. +.. _Grain fill: + Grain fill ''''''''''''''''''' @@ -200,6 +214,8 @@ percentage itself is an empirical function of :math:`{GDD}_{mat}` response to a background litterfall rate calculated as the inverse of leaf longevity for the pft as done in the CN part of the model. +.. _Harvest: + Harvest '''''''''''''''' @@ -215,6 +231,8 @@ flow of live stem C and N to litter for corn, soybean, and temperate cereals. This is in contrast to the approach for unmanaged PFTs which puts live stem C and N to dead stems first, rather than to litter. +.. _Allocation: + Allocation ^^^^^^^^^^^^^^^^^ @@ -224,6 +242,8 @@ Simulated C assimilation begins every year upon leaf emergence in phase allocation of such C to the crop’s leaf, live stem, fine root, and reproductive pools. +.. _Leaf emergence to grain fill: + Leaf emergence to grain fill ''''''''''''''''''''''''''''''''''''' @@ -242,6 +262,8 @@ section 20.2.3. At a crop-specific maximum leaf area index, :math:`{L}_{max}` (Table 20.2), carbon allocation is directed exclusively to the fine roots. +.. _Grain fill to harvest: + Grain fill to harvest '''''''''''''''''''''''''''''' @@ -269,6 +291,8 @@ allocation decline factors, and :math:`a_{leaf}^{f}` and :math:`a_{livestem}^{f}` are final values of these allocation coefficients (Table 20.2). +.. _General comments: + General comments ^^^^^^^^^^^^^^^^^^^^^^^ @@ -411,6 +435,8 @@ allocation. Numbers in the first column correspond to the list of pfts in Table Notes: Crop growth phases and corresponding variables are described in the text +.. _The irrigation model: + The irrigation model ------------------------- @@ -480,9 +506,13 @@ added to :math:`{q}_{grnd,liq}`: section 7.1). Added irrigation is removed from total liquid runoff ( :math:`{R}_{liq}`: Chapter 11), simulating removal from nearby rivers. +.. _The details about what is new in CLM4.5: + The details about what is new in CLM4.5 -------------------------------------------- +.. _Interactive irrigation for corn, temperate cereals, and soybean: + Interactive irrigation for corn, temperate cereals, and soybean ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -527,6 +557,8 @@ or without irrigation. In simulations without irrigation, the rainfed and irrigated crops merge into just rainfed crops at run time. Surface datasets with 16 pfts can be used for all other CLM simulations. +.. _Interactive fertilization: + Interactive fertilization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -563,6 +595,8 @@ The crop fertilization scheme was developed in versions of the CLM prior to CLM4.5. In CLM4.5, crops with fertilization may be simulated over productive. +.. _Biological nitrogen fixation for soybeans: + Biological nitrogen fixation for soybeans ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -606,6 +640,8 @@ pool for use that time step. Nitrogen fixation occurs after the plant has accumulated 15%\ :math:`{GDD}_{mat}` and before 75%\ :math:`{GDD}_{mat}`, so before grain fill begins. +.. _Modified C\:N ratios for crops: + Modified C:N ratios for crops ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -625,6 +661,8 @@ harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growth season. +.. _Nitrogen retranslocation for crops: + Nitrogen retranslocation for crops ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -699,6 +737,8 @@ fine root, and reproductive pools. | :math:`CN_{repr}^{f}` | 50 | 40 | 60 | +----------------------------+--------+---------------------+-----------+ +.. _Separate reproductive pool: + Separate reproductive pool ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 959a8cbd73..df44ae6fe1 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -1,7 +1,7 @@ -.. _rst_Surface Characterization and Model Input Requirements: +.. _rst_Surface Characterization, Vertical Discretization, and Model Input Requirements: -Surface Characterization and Model Input Requirements -======================================================== +Surface Characterization, Vertical Discretization, and Model Input Requirements +=================================================================================== .. _Surface Characterization: @@ -91,7 +91,7 @@ The crop land unit is present only when the crop model is active. Note that the biogeophysical processes related to soil and snow require PFT level properties to be aggregated to the column level. For example, the net heat flux into the ground is required as a boundary condition -for the solution of snow/soil temperatures (Chapter 6). This column +for the solution of snow/soil temperatures (Chapter :numref:`rst_Soil and Snow Temperatures`). This column level property must be determined by aggregating the net heat flux from all PFTs sharing the column. This is generally accomplished in the model by computing a weighted sum of the desired quantity over all PFTs whose @@ -108,18 +108,18 @@ types (PFTs) plus bare ground (:numref:`Table Plant functional types`). An additional PFT is added if the irrigation model is active and six additional PFTs are added if the crop model is active (Chapter :numref:`rst_Crops and Irrigation`). These -plant types differ -in leaf and stem optical properties that determine reflection, -transmittance, and absorption of solar radiation (Table 3.1), root +plant types differ in leaf and stem optical properties that determine reflection, +transmittance, and absorption of solar radiation (:numref:`Table Plant functional type optical properties`), root distribution parameters that control the uptake of water from the soil -(Table 8.3), aerodynamic parameters that determine resistance to heat, -moisture, and momentum transfer (Table 5.1), and photosynthetic +(:numref:`Table Plant functional type root distribution parameters`), aerodynamic parameters that determine resistance to heat, +moisture, and momentum transfer (:numref:`Table Plant functional type aerodynamic parameters`), and photosynthetic parameters that determine stomatal resistance, photosynthesis, and -transpiration (Tables 8.1, 8.2). The composition and abundance of PFTs +transpiration (:numref:`Table Plant functional type (PFT) photosynthetic parameters`, +:numref:`Table Temperature dependence parameters for C3 photosynthesis`). The composition and abundance of PFTs within a grid cell can either be prescribed as time-invariant fields (e.g., using the present day dataset described in section 21.3.3) or can evolve with time if the model is run in transient landcover mode -(Chapter 21). +(Chapter :numref:`rst_Transient Landcover Change`). .. _Table Plant functional types: @@ -264,11 +264,12 @@ When the biogeochemistry model is inactive, leaf and stem area indices (m\ :sup:`2` leaf area m\ :sup:`-2` ground area) are updated daily by linearly interpolating between monthly values. Monthly PFT leaf area index values are developed from the 1-km MODIS-derived monthly grid -cell average leaf area index of Myneni et al. (2002), as described in -Lawrence and Chase (2007). Stem area index is calculated from the -monthly PFT leaf area index using the methods of Zeng et al. (2002). The -leaf and stem area indices are adjusted for vertical burying by snow -(Wang and Zeng 2009) as +cell average leaf area index of :ref:`Myneni et al. (2002) `, +as described in :ref:`Lawrence and Chase (2007) `. Stem area +ndex is calculated from the monthly PFT leaf area index using the methods of +:ref:`Zeng et al. (2002) `. The leaf and stem area indices are +adjusted for vertical burying by snow (:ref:`Wang and Zeng 2009 `) +as .. math:: :label: 2.1 @@ -285,10 +286,110 @@ snow, :math:`A` is the remaining exposed leaf or stem area, {f_{veg}^{sno} = \frac{z_{sno} -z_{bot} }{z_{top} -z_{bot} } \qquad {\rm for\; tree\; and\; shrub}} \\ {f_{veg}^{sno} = \frac{\min \left(z_{sno} ,\, z_{c} \right)}{z_{c} } \qquad {\rm for\; grass\; and\; crop}} -where :math:`z_{sno} -z_{bot} \ge 0,{\rm \; }0\le f_{veg}^{sno} \le 1`, :math:`z_{sno}` is the depth of snow (m) (section 7.2), and -:math:`z_{c} = 0.2` is the snow depth when short vegetation is assumed to be completely buried by snow (m). For numerical reasons, exposed leaf -and stem area are set to zero if less than 0.05. If the sum of exposed leaf and stem area is zero, then the surface is treated as snow-covered -ground. +where :math:`z_{sno} -z_{bot} \ge 0,{\rm \; }0\le f_{veg}^{sno} \le 1`, :math:`z_{sno}` is the depth of snow (m) +(Chapter :numref:`rst_Snow Hydrology`), and :math:`z_{c} = 0.2` is the snow depth when short vegetation is assumed to +be completely buried by snow (m). For numerical reasons, exposed leaf and stem area are set to zero if less than +0.05. If the sum of exposed leaf and stem area is zero, then the surface is treated as snow-covered ground. + +.. _Vertical Discretization: + +Vertical Discretization +---------------------------- +.. + (this was taken from Initialization; is it still needed? + Vegetated and glacier land units have fifteen vertical layers, while + lakes have ten. For soil points, temperature calculations are done over + all layers, :math:`N_{levgrnd} =15`, while hydrology calculations are + done over the top ten layers, :math:`N_{levsoi} =10`, the bottom five + layers being specified as bedrock. + +.. _Soil Layers: + +Soil Layers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The soil column can be discretized into an arbitrary number of layers. The default +vertical discretization (:numref:`Table Soil layer structure`) uses +:math:`N_{levgrnd} = 25` layers, of which :math:`N_{levsoi} = 20` are hydrologically and +biogeochemically active. The deepest 5 layers are only included in the thermodynamical +calculations (:ref:`Lawrence et al. 2008 `) described in Chapter +:numref:`rst_Soil and Snow Temperatures`. + +The layer structure of the soil is described by the node depth, :math:`z_{i}` +(m), the thickness of each layer, :math:`\Delta z_{i}` (m), and the depths +at the layer interfaces :math:`z_{h,\, i}` (m). + +.. _Table Soil layer structure: + +.. table:: Soil layer structure + + +---------------+------------------+------------------------+------------------------+ + | Layer | :math:`z_{i}` | :math:`\Delta z_{i}` | :math:`z_{h,\, i}` | + +===============+==================+========================+========================+ + | 1 | 0.010 | 0.020 | 0.020 | + +---------------+------------------+------------------------+------------------------+ + | 2 | 0.040 | 0.040 | 0.060 | + +---------------+------------------+------------------------+------------------------+ + | 3 | 0.090 | 0.060 | 0.120 | + +---------------+------------------+------------------------+------------------------+ + | 4 | 0.160 | 0.080 | 0.200 | + +---------------+------------------+------------------------+------------------------+ + | 5 | 0.260 | 0.120 | 0.320 | + +---------------+------------------+------------------------+------------------------+ + | 6 | 0.400 | 0.160 | 0.480 | + +---------------+------------------+------------------------+------------------------+ + | 7 | 0.580 | 0.200 | 0.680 | + +---------------+------------------+------------------------+------------------------+ + | 8 | 0.800 | 0.240 | 0.920 | + +---------------+------------------+------------------------+------------------------+ + | 9 | 1.060 | 0.280 | 1.200 | + +---------------+------------------+------------------------+------------------------+ + | 10 | 1.360 | 0.320 | 1.520 | + +---------------+------------------+------------------------+------------------------+ + | 11 | 1.700 | 0.360 | 1.880 | + +---------------+------------------+------------------------+------------------------+ + | 12 | 2.080 | 0.400 | 2.280 | + +---------------+------------------+------------------------+------------------------+ + | 13 | 2.500 | 0.440 | 2.720 | + +---------------+------------------+------------------------+------------------------+ + | 14 | 2.990 | 0.540 | 3.260 | + +---------------+------------------+------------------------+------------------------+ + | 15 | 3.580 | 0.640 | 3.900 | + +---------------+------------------+------------------------+------------------------+ + | 16 | 4.270 | 0.740 | 4.640 | + +---------------+------------------+------------------------+------------------------+ + | 17 | 5.060 | 0.840 | 5.480 | + +---------------+------------------+------------------------+------------------------+ + | 18 | 5.950 | 0.940 | 6.420 | + +---------------+------------------+------------------------+------------------------+ + | 19 | 6.940 | 1.040 | 7.460 | + +---------------+------------------+------------------------+------------------------+ + | 20 | 8.030 | 1.140 | 8.600 | + +---------------+------------------+------------------------+------------------------+ + | 21 | 9.795 | 2.390 | 10.990 | + +---------------+------------------+------------------------+------------------------+ + | 22 | 13.328 | 4.676 | 15.666 | + +---------------+------------------+------------------------+------------------------+ + | 23 | 19.483 | 7.635 | 23.301 | + +---------------+------------------+------------------------+------------------------+ + | 24 | 28.871 | 11.140 | 34.441 | + +---------------+------------------+------------------------+------------------------+ + | 25 | 41.998 | 15.115 | 49.556 | + +---------------+------------------+------------------------+------------------------+ + +Layer node depth (:math:`z_{i}` ), thickness (:math:`\Delta z_{i}` ), and depth at +layer interface (:math:`z_{h,\, i}` ) for default soil column. All in meters. + +.. _Depth to Bedrock: + +Depth to Bedrock +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The hydrologically and biogeochemically active portion of the soil column can be +restricted to a thickness less than that of the maximum soil depth. By providing +a depth-to-bedrock dataset, which may vary spatially, the number of layers used +in the hydrologic and biogeochemical calculations, :math:`N_{bedrock}`, may be +specified, subject to the constraint :math:`N_{bedrock} \le N_{levsoi}` .. _Model Input Requirements: @@ -363,7 +464,8 @@ conditions from the current time step. atmospheric model :math:`z'_{atm}` is assumed to be the height above the surface as defined by the roughness length :math:`z_{0}` plus displacement height :math:`d`. Thus, the reference height used for flux -computations (Chapter 5) is :math:`z_{atm} =z'_{atm} +z_{0} +d`. The +computations (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) +is :math:`z_{atm} =z'_{atm} +z_{0} +d`. The reference heights for temperature, wind, and specific humidity (:math:`z_{atm,\, h}` , :math:`z_{atm,\, {\it m}}` , :math:`z_{atm,\, w}` ) are required. These are set equal @@ -396,7 +498,7 @@ sea-surface temperatures and emissions (Lamarque et al. 2010) for short-lived gases and aerosols; observed concentrations were specified for methane, N\ :sub:`2`\ O, the ozone-depleting substances (CFCs) ,and CO\ :sub:`2`. The fluxes are used by the snow-related -parameterizations (Chapters 3 and 7). +parameterizations (Chapters :numref:`rst_Surface Albedos` and numref:`rst_Snow Hydrology`). :sup:`4`\ The nitrogen deposition rate is required by the biogeochemistry model when active and represents the total deposition of @@ -503,11 +605,7 @@ fields that are required from the restart or initial conditions files can be obtained by examining the code. Arbitrary initial conditions are specified as follows. -Vegetated and glacier land units have fifteen vertical layers, while -lakes have ten. For soil points, temperature calculations are done over -all layers, :math:`N_{levgrnd} =15`, while hydrology calculations are -done over the top ten layers, :math:`N_{levsoi} =10`, the bottom five -layers being specified as bedrock. Soil points are initialized with +Soil points are initialized with surface ground temperature :math:`T_{g}` and soil layer temperature :math:`T_{i}` , for :math:`i=1,\ldots ,N_{levgrnd}` , of 274 K, vegetation temperature :math:`T_{v}` of 283 K, no snow or canopy water @@ -624,9 +722,10 @@ The percentage glacier mask was derived from vector data of global glacier and ice sheet spatial coverage. Vector data for glaciers (ice caps, icefields and mountain glaciers) were taken from the first globally complete glacier inventory, the Randolph Glacier Inventory -version 1.0 (RGIv1.0: Arendt et al. 2012). Vector data for the Greenland -Ice Sheet were provided by Frank Paul and Tobias Bolch (University of -Zurich: Rastner et al. 2012). Antarctic Ice Sheet data were provided by +version 1.0 (RGIv1.0: :ref:`Arendt et al. 2012 `). +Vector data for the Greenland Ice Sheet were provided by Frank Paul and +Tobias Bolch (University of Zurich: :ref:`Rastner et al. 2012 `). +Antarctic Ice Sheet data were provided by Andrew Bliss (University of Alaska) and were extracted from the Scientific Committee on Antarctic Research (SCAR) Antarctic Digital Database version 5.0. Floating ice is only provided for the Antarctic @@ -651,75 +750,80 @@ elevation are needed when running CLM4 with multiple glacier elevation classes. Percent lake and lake depth are area-averaged from the 90-second -resolution data of Kourzeneva (2009, 2010) to the 0.05\ :sup:`o` +resolution data of :ref:`Kourzeneva (2009, 2010) ` to the 0.05\ :sup:`o` resolution using the MODIS land-mask. Percent urban is derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road proximity and slope -(Dobson et al. 2000) as described by Jackson et al. (2010) at 1km +(:ref:`Dobson et al. 2000 `) as described by +:ref:`Jackson et al. (2010) ` at 1km resolution and aggregated to 0.05\ :sup:`o`. A number of urban radiative, thermal, and morphological fields are also required and are -obtained from Jackson et al. (2010). Their description can be found in -Table 3 of the Community Land Model Urban (CLMU) technical note (Oleson -et al. 2010b). +obtained from :ref:`Jackson et al. (2010) `. Their description can be found in +Table 3 of the Community Land Model Urban (CLMU) technical note (:ref:`Oleson +et al. 2010b `). Percent PFTs are derived from MODIS satellite data as described in -Lawrence and Chase (2007) (section 21.3.3). Prescribed PFT leaf area -index is derived from the MODIS satellite data of Myneni et al. (2002) -using the de-aggregation methods described in Lawrence and Chase (2007) +:ref:`Lawrence and Chase (2007) ` (section 21.3.3). +Prescribed PFT leaf area index is derived from the MODIS satellite data of +:ref:`Myneni et al. (2002) ` using the de-aggregation methods +described in :ref:`Lawrence and Chase (2007) ` (section 2.2.3). Prescribed PFT stem area index is derived from PFT leaf -area index phenology combined with the methods of Zeng et al. (2002). -Prescribed canopy top and bottom heights are from Bonan (1996) as -described in Bonan et al. (2002b). If the biogeochemistry model is +area index phenology combined with the methods of :ref:`Zeng et al. (2002) `. +Prescribed canopy top and bottom heights are from :ref:`Bonan (1996) ` as +described in :ref:`Bonan et al. (2002b) `. If the biogeochemistry model is active, it supplies the leaf and stem area index and canopy top and bottom heights dynamically, and the prescribed values are ignored. -Soil color determines dry and saturated soil albedo (section 3.2). Soil -colors are from Lawrence and Chase (2007) (section 3.2). +Soil color determines dry and saturated soil albedo (section :numref:`Ground Albedos`). +Soil colors are from :ref:`Lawrence and Chase (2007) `. The soil texture and organic matter content determine soil thermal and hydrologic properties (sections 6.3 and 7.4.1). The International Geosphere-Biosphere Programme (IGBP) soil dataset (Global Soil Data Task 2000) of 4931 soil mapping units and their sand and clay content for each soil layer were used to create a mineral soil texture dataset -(Bonan et al. 2002b). Soil organic matter data is merged from two -sources. The majority of the globe is from ISRIC-WISE (Batjes, 2006). +:ref:`(Bonan et al. 2002b) `. Soil organic matter data is merged from two +sources. The majority of the globe is from ISRIC-WISE (:ref:`Batjes, 2006 `). The high latitudes come from the 0.25\ :sup:`o` version of the -Northern Circumpolar Soil Carbon Database (Hugelius et al. 2012). Both +Northern Circumpolar Soil Carbon Database (:ref:`Hugelius et al. 2012 `). Both datasets report carbon down to 1m depth. Carbon is partitioned across -the top seven CLM4 layers (:math:`\sim`\ 1m depth) as in Lawrence and -Slater (2008). +the top seven CLM4 layers (:math:`\sim`\ 1m depth) as in +:ref:`Lawrence and Slater (2008) `. The maximum fractional saturated area (:math:`f_{\max }` ) is used in determining surface runoff and infiltration (section 7.3). Maximum fractional saturated area at 0.125\ :sup:`o` resolution is calculated from 1-km compound topographic indices (CTIs) based on the -USGS HYDRO1K dataset (Verdin and Greenlee 1996) following the algorithm -in Niu et al. (2005). :math:`f_{\max }` is the ratio between the number +USGS HYDRO1K dataset (:ref:`Verdin and Greenlee 1996 `) +following the algorithm in :ref:`Niu et al. (2005) `. +:math:`f_{\max }` is the ratio between the number of 1-km pixels with CTIs equal to or larger than the mean CTI and the total number of pixels in a 0.125\ :sup:`o` grid cell. See -section 7.3.1 and Li et al. (2013b) for further details. Slope and -elevation are also obtained from the USGS HYDRO1K 1-km dataset (Verdin -and Greenlee 1996). Slope is used in the River Transport Model (Chapter -11) and in the surface water parameterization (section 7.3.2), and +section 7.3.1 and :ref:`Li et al. (2013b) ` for further details. Slope and +elevation are also obtained from the USGS HYDRO1K 1-km dataset +(:ref:`Verdin and Greenlee 1996 `). Slope is used in the +surface water parameterization (section :numref:`Surface Water Storage`), and elevation is used to calculate the grid cell standard deviation of -topography for the snow cover fraction parameterization (section 7.2.1). +topography for the snow cover fraction parameterization (section :numref:`Snow Covered Area Fraction`). Biogenic Volatile Organic Compounds emissions factors are from the Model of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1; -Guenther et al. 2012). +:ref:`Guenther et al. 2012 `). The default list of PFTs includes an unmanaged crop treated as a second C3 grass (:numref:`Table Plant functional types`). The unmanaged crop has grid cell fractional cover -assigned from MODIS satellite data (Lawrence and Chase 2007). A managed +assigned from MODIS satellite data (:ref:`Lawrence and Chase (2007) `). A managed crop option uses grid cell fractional cover from the present-day crop -dataset of Ramankutty and Foley (1998) (CLM4CNcrop). Managed crops are -assigned in the proportions given by Ramankutty and Foley (1998) without +dataset of :ref:`Ramankutty and Foley (1998) ` +(CLM4CNcrop). Managed crops are assigned in the proportions given by +:ref:`Ramankutty and Foley (1998) ` without exceeding the area previously assigned to the unmanaged crop. The unmanaged crop continues to occupy any of its original area that remains and continues to be handled just by the CN part of CLM4CNcrop. The managed crop types (corn, soybean, and temperate cereals) were chosen based on the availability of corresponding algorithms in AgroIBIS -(Kucharik et al. 2000; Kucharik and Brye 2003). Temperate cereals +(:ref:`Kucharik et al. 2000 `; +:ref:`Kucharik and Brye 2003 `). Temperate cereals include wheat, barley, and rye here. All temperate cereals are treated as summer crops (like spring wheat, for example) at this time. Winter cereals (such as winter wheat) may be introduced in a future version of @@ -737,10 +841,11 @@ management between crops. CLM includes the option to irrigate cropland areas that are equipped for irrigation. The application of irrigation responds dynamically to climate (see Chapter :numref:`rst_Crops and Irrigation`). In CLM, irrigation is -implemented for the C3 -generic crop only. When irrigation is enabled, the cropland area of each -grid cell is divided into an irrigated and unirrigated fraction -according to a dataset of areas equipped for irrigation (:ref:`Siebert et al. (2005) `). The area of irrigated cropland in each grid cell is given by the +implemented for the C3 generic crop only. When irrigation is enabled, the +cropland area of each grid cell is divided into an irrigated and unirrigated +fraction according to a dataset of areas equipped for irrigation +(:ref:`Siebert et al. (2005) `). The area of irrigated +cropland in each grid cell is given by the smaller of the grid cell’s total cropland area, according to the default CLM4 dataset, and the grid cell’s area equipped for irrigation. The remainder of the grid cell’s cropland area (if any) is then assigned to @@ -757,18 +862,18 @@ Database of the Global Environment version 3.1 (HYDEv3.1) with 0.5\ :sup:`o` resolution population density data for 1990, 1995, 2000, and 2005 from the Gridded Population of the World version 3 dataset (GPWv3) (CIESIN, 2005). Gross Domestic Production (GDP) per -capita in 2000 at 0.5\ :sup:`o` is from Van Vuuren et al. (2006), +capita in 2000 at 0.5\ :sup:`o` is from :ref:`Van Vuuren et al. (2006) `, which is the base-year GDP data for IPCC-SRES and derived from country-level World Bank’s World Development Indicators (WDI) measured -in constant 1995 US$ (World Bank, 2004) and the UN Statistics Database -(UNSTAT, 2005). The peatland area fraction at 0.5\ :sup:`o` +in constant 1995 US$ (:ref:`World Bank, 2004 `) and the UN Statistics Database +(:ref:`UNSTAT, 2005 `). The peatland area fraction at 0.5\ :sup:`o` resolution is derived from three vector datasets: peatland data in -Indonesia and Malaysian Borneo (Olson et al. 2001); peatland data in -Canada (Tarnocai et al. 2011); and bog, fen and mire data in boreal +Indonesia and Malaysian Borneo (:ref:`Olson et al. 2001 `); peatland data in +Canada (:ref:`Tarnocai et al. 2011 `); and bog, fen and mire data in boreal regions (north of 45\ :sup:`o`\ N) outside Canada provided by the -Global Lakes and Wetlands Database (GLWD) (Lehner and Döll, 2004). The -climatological peak month for agricultural waste burning is from van der -Werf et al. (2010). +Global Lakes and Wetlands Database (GLWD) (:ref:`Lehner and Döll, 2004 `). The +climatological peak month for agricultural waste burning is from :ref:`van der +Werf et al. (2010) `. .. _Adjustable Parameters and Physical Constants: diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 0bfdaf6217..0d8d213cb4 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -612,7 +612,7 @@ The water vapor flux :math:`E_{g}` (kg m\ :sup:`-2` s\ :sup:`-1`) is, with refe .. math:: :label: 5.67 - E_{soil} =-\frac{\beta _{soi} \rho _{atm} \left(q_{atm} -q_{soil} \right)}{r_{aw} } + E_{soil} =-\frac{\rho _{atm} \left(q_{atm} -q_{soil} \right)}{r_{aw} + r_{soil}} .. math:: :label: 5.68 @@ -624,11 +624,11 @@ The water vapor flux :math:`E_{g}` (kg m\ :sup:`-2` s\ :sup:`-1`) is, with refe E_{h2osfc} =-\frac{\rho _{atm} \left(q_{atm} -q_{h2osfc} \right)}{r_{aw} } -where :math:`\beta _{soi}` is an empirical function of soil water (Sakaguchi and Zeng 2009), :math:`q_{atm}` is the atmospheric specific -humidity (kg kg\ :sup:`-1`), :math:`q_{soil}` , :math:`q_{sno}` , and :math:`q_{h2osfc}` are the specific humidities -(kg kg\ :sup:`-1`) of the soil, snow, and surface water, respectively, and :math:`r_{aw}` is the aerodynamic resistance to water vapor -transfer (s m\ :sup:`-1`). The specific humidities of the snow :math:`q_{sno}` and surface water :math:`q_{h2osfc}` are assumed to be -at the saturation specific humidity of their respective temperatures +where :math:`q_{atm}` is the atmospheric specific humidity (kg kg\ :sup:`-1`), :math:`q_{soil}` , :math:`q_{sno}` , +and :math:`q_{h2osfc}` are the specific humidities (kg kg\ :sup:`-1`) of the soil, snow, and surface water, respectively, +:math:`r_{aw}` is the aerodynamic resistance to water vapor transfer (s m\ :sup:`-1`), and :math:`r _{soi}` is the soil +resistance to water vapor transfer (s m\ :sup:`-1`). The specific humidities of the snow :math:`q_{sno}` and surface water +:math:`q_{h2osfc}` are assumed to be at the saturation specific humidity of their respective temperatures .. math:: :label: 5.70) @@ -692,37 +692,71 @@ top soil layer (kg m\ :sup:`-2`) (Chapter :numref:`rst_Hydrology`), and prevents large increases (decreases) in :math:`q_{soil}` for small increases (decreases) in soil moisture in very dry soils. -The function :math:`\beta _{soi}` ranges from 0 to 1 and is intended to -represent the molecular diffusion process from the soil pore to the -surface within the dry part of the soil (Sakaguchi and Zeng 2009) as +The resistance to water vapor transfer occurring within the soil matrix +:math:`r_{soil}` is .. math:: :label: 5.76) - \beta _{soi} =\left\{\begin{array}{l} {1\qquad \theta _{1} \ge \theta _{fc,\, 1} {\rm \; or\; }q_{atm} -q_{soil} >0} \\ {0.25\left(1-f_{sno} -f_{h2osfc} \right)\left[1-\cos \left(\pi \frac{\theta _{1} }{\theta _{fc,\, 1} } \right)\right]^{2} +f_{sno} +f_{h2osfc} \qquad \theta _{1} <\theta _{fc,\, 1} } \end{array}\right\}. + r_{soil} = \frac{DSL}{D_{v} \tau} -where :math:`\theta _{fc,\, 1}` is the field capacity of the top soil -layer and -:math:`0.01{\le \theta _{1} \mathord{\left/ {\vphantom {\le \theta _{1} \theta _{fc,\, 1} \le 1}} \right. \kern-\nulldelimiterspace} \theta _{fc,\, 1} \le 1}` . -The volumetric water content of the top soil layer (mm\ :sup:`3` mm\ :sup:`-3`) is +where :math:`DSL` is the thickness of the dry surface layer, :math:`D_{v}` +is the molecular diffusivity of water vapor in air and :math:`\tau` +describes the tortuosity of the vapor flow paths through +the soil matrix (:ref:`Swenson and Lawrence 2014 `). + +The thickness of the dry surface layer is given by + +.. math:: + :label: 5.77) + + DSL = + \begin{array}{lr} + D_{max} \ \frac{\left( \theta_{init} - \theta_{1}\right)} + {\left(\theta_{init} - \theta_{air}\right)} & \qquad \theta_{1} < \theta_{init} \\ + 0 & \qquad \theta_{1} \ge \theta_{init} + \end{array} + +where :math:`D_{max}` is a parameter specifying the length scale +of the maximum DSL thickness (default value = 15 mm), +:math:`\theta_{init}` is the moisture value at which the DSL initiates, +:math:`\theta_{1}` is the moisture value of the top model soil layer, +and :math:`\theta_{air}` is the 'air dry' soil moisture value +(:ref:`Dingman 2002 `): + +.. math:: + :label: 5.78) + + \theta_{air} = \Phi \left( \frac{\Psi_{sat}}{\Psi_{air}} \right)^{\frac{1}{B_{1}}} \ . + +where :math:`\Phi` is the porosity, :math:`\Psi_{sat}` is the saturated +soil matric potential, :math:`\Psi_{air} = 10^{7}` mm is the air dry +matric potential, and :math:`B_{1}` is a function of soil texture (section +:numref:`Hydraulic Properties`). + +The soil tortuosity is + +.. math:: + :label: 5.79) + + \tau = \Phi^{2}_{air}\left(\frac{\Phi_{air}}{\Phi}\right)^{\frac{3}{B_{1}}} + +where :math:`\Phi_{air}` is the air filled pore space .. math:: - :label: 5.77) + :label: 5.80) - \theta _{1} =\frac{1}{\Delta z_{1} } \left[\frac{w_{liq,\, 1} }{\rho _{liq} } +\frac{w_{ice,\, 1} }{\rho _{ice} } \right]. + \Phi_{air} = \Phi - \theta_{air} \ . -The volumetric water content at field capacity is derived by assuming a -hydraulic conductivity of 0.1 mm day\ :sup:`-1` and inverting the -hydraulic conductivity function (section :numref:`Hydraulic Properties`) as +:math:`D_{v}` depends on temperature .. math:: - :label: 5.78) + :label: 5.81) - \theta _{fc,\, 1} =\theta _{sat,\, 1} \left[\frac{0.1}{86400k_{sat,\, 1} } \right]^{\frac{1}{2B_{i} +3} } + D_{v} = 2.12 \times 10^{-5} \left(\frac{T_{1}}{T_{f}}\right)^{1.75} \ . -where :math:`k_{sat,\, 1}` is the saturated hydraulic conductivity of -the top soil layer (mm s\ :sup:`-1`) (section :numref:`Hydraulic Properties`) and the -exponent :math:`B_{1}` is a function of soil texture (section :numref:`Hydraulic Properties`). +where :math:`T_{1}` is the temperature of the top soil layer and +:math:`T_{f}` is the freezing temperature of water (:numref:`Table Physical Constants`). The roughness lengths used to calculate :math:`r_{am}` , :math:`r_{ah}` , and :math:`r_{aw}` are :math:`z_{0m} =z_{0m,\, g}` , @@ -942,7 +976,7 @@ are the sensible heat conductances from the canopy air to the atmosphere, the ground to canopy air, and leaf surface to canopy air, respectively (m s\ :sup:`-1`). -When the expression for :math:`T_{s}` is substituted into equation , +When the expression for :math:`T_{s}` is substituted into equation :eq:`ZEqnNum675188`, the sensible heat flux from vegetation :math:`H_{v}` is a function of :math:`\theta _{atm}` , :math:`T_{g}` , and :math:`T_{v}` diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index f850a383b4..e6f45af8ff 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -25,7 +25,7 @@ where :math:`q_{rain}` is the liquid part of precipitation, ET from vegetation (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), :math:`E_{g}` is ground evaporation (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), :math:`q_{over}` is surface runoff (section :numref:`Surface Runoff`), :math:`q_{h2osfc}` is runoff from surface water storage (section :numref:`Surface Runoff`), -:math:`q_{drai}` is sub-surface drainage (section 7.6), +:math:`q_{drai}` is sub-surface drainage (section :numref:`Lateral Sub-surface Runoff`), :math:`q_{rgwl}` and :math:`q_{snwcp,ice}` are liquid and solid runoff from glaciers, wetlands, and lakes, and runoff from other surface types due to snow capping (section :numref:`Runoff from glaciers and snow-capped surfaces`) (all in kg m\ :sup:`-2` @@ -140,14 +140,22 @@ calculations is (:ref:`Dickinson et al.1993 `) .. math:: :label: 7.12) - f_{wet} =\left\{\begin{array}{l} {\left[\frac{W_{can} }{p\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \le 1\qquad L+S>0} \\ {0\qquad L+S=0} \end{array}\right\} + f_{wet} = + \left\{\begin{array}{lr} + \left[\frac{W_{can} }{p\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \le 1 & \qquad L+S > 0 \\ + 0 &\qquad L+S = 0 + \end{array}\right\} while the fraction of the canopy that is dry and transpiring is .. math:: :label: 7.13) - f_{dry} =\left\{\begin{array}{l} {\frac{\left(1-f_{wet} \right)L}{L+S} \qquad L+S>0} \\ {0\qquad L+S=0} \end{array}\right\}. + f_{dry} = + \left\{\begin{array}{lr} + \frac{\left(1-f_{wet} \right)L}{L+S} & \qquad L+S > 0 \\ + 0 &\qquad L+S = 0 + \end{array}\right\}. .. _Surface Runoff, Surface Water Storage, and Infiltration: @@ -271,7 +279,7 @@ portion of the grid cell that is interconnected .. math:: :label: 7.69) - \begin{array}{l} {f_{connected} =\left(f_{h2osfc} -f_{c} \right)^{\mu } \qquad for\, f_{h2osfc} >f_{c} } \\ {f_{connected} =0\qquad \qquad \qquad for\, f_{h2osfc} \le f_{c} } \end{array} + \begin{array}{lr} f_{connected} =\left(f_{h2osfc} -f_{c} \right)^{\mu } & \qquad f_{h2osfc} >f_{c} \\ f_{connected} =0 &\qquad f_{h2osfc} \le f_{c} \end{array} where :math:`f_{c}` is a threshold below which no single connected inundated area spans the grid cell and :math:`\mu` is a scaling @@ -316,7 +324,7 @@ s\ :sup:`-1`), q_{infl,\, \max } =(1-fsat){\rm \Theta }iceksat where :math:`{\rm \Theta }ice` is an ice impedance factor (section -7.4), infiltration excess (Hortonian) runoff is generated +:numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff is generated .. math:: :label: 7.73) @@ -370,11 +378,10 @@ Soil Water Soil water is predicted from a multi-layer model, in which the vertical soil moisture transport is governed by infiltration, surface and -sub-surface runoff, gradient diffusion, gravity, canopy transpiration -through root extraction, and interactions with groundwater -(:numref:`Hydrologic processes figure`). +sub-surface runoff, gradient diffusion, gravity, and canopy transpiration +through root extraction (:numref:`Hydrologic processes figure`). The following derivation generally follows that of :ref:`Z.-L. Yang (1998, -unpublished manuscript) ` with modifications by Zeng and Decker (2009). +unpublished manuscript) `. For one-dimensional vertical water flow in soils, the conservation of mass is stated as @@ -394,11 +401,12 @@ of soil s\ :sup:`-1`) (ET loss). This equation is solved numerically by dividing the soil column into multiple layers in the vertical and integrating downward over each layer with an upper boundary condition of the infiltration flux into the top soil layer -:math:`q_{infl}` and a lower boundary condition that depends on the -depth of the water table. +:math:`q_{infl}` and a zero-flux lower boundary condition at the +bottom of the soil column (sub-surface runoff is removed later in the +timestep, section :numref:`Lateral Sub-surface Runoff`). The soil water flux :math:`q` in equation can be described by Darcy’s -law +law :ref:`(Dingman 2002) ` .. math:: :label: 7.80) @@ -427,57 +435,20 @@ becomes q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]. -Darcy’s equation can be further manipulated to yield +Equation :eq:`ZEqnNum186573` can be further manipulated to yield .. math:: :label: 7.83) q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]=-k\left(\frac{\partial \psi }{\partial z} +1\right)=-k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right). -Substitution of this equation into equation , with :math:`Q=0`, yields +Substitution of this equation into equation :eq:`ZEqnNum790844`, with :math:`Q=0`, yields the Richards equation .. math:: :label: ZEqnNum670361 - \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } \right)+1\right]. - -Zeng and Decker (2009) note that this :math:`\theta` -based form of the -Richards equation cannot maintain the hydrostatic equilibrium soil -moisture distribution because of the truncation errors of the -finite-difference numerical scheme. They show that this deficiency can -be overcome by subtracting the equilibrium state from equation as - -.. math:: - :label: ZEqnNum936839 - - q=-k\left[\frac{\partial \left(\psi +z-C\right)}{\partial z} \right] - -where :math:`C` is a constant hydraulic potential above the water table -:math:`z_{\nabla }` - -.. math:: - :label: ZEqnNum126975 - - C=\psi _{E} +z=\psi _{sat} \left[\frac{\theta _{E} \left(z\right)}{\theta _{sat} } \right]^{-B} +z=\psi _{sat} +z_{\nabla } - -so that - -.. math:: - :label: ZEqnNum537733 - - q=-k\left[\frac{\partial \left(\psi -\psi _{E} \right)}{\partial z} \right] - -where :math:`\psi _{E}` \ is the equilibrium soil matric potential -(mm). Substitution of equations and into equation yields Zeng and -Decker’s (2009) modified Richards equation - -.. math:: - :label: 7.88) - - \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \left(\psi -\psi _{E} \right)}{\partial z} \right)\right]-Q - -where the soil moisture sink term :math:`Q` is now included. + \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right)\right]. .. _Hydraulic Properties: @@ -487,7 +458,7 @@ Hydraulic Properties The hydraulic conductivity :math:`k_{i}` (mm s\ :sup:`-1`) and the soil matric potential :math:`\psi _{i}` (mm) for layer :math:`i` vary with volumetric soil water :math:`\theta _{i}` and soil texture. -As with the soil thermal properties (section 6.3) the hydraulic +As with the soil thermal properties (section :numref:`Soil And Snow Thermal Properties`) the hydraulic properties of the soil are assumed to be a weighted combination of the mineral properties, which are determined according to sand and clay contents based on work by :ref:`Clapp and Hornberger (1978) @@ -506,14 +477,18 @@ moisture of the two layers :math:`\theta _{i}` and .. math:: :label: ZEqnNum398074 - k\left[z_{h,\, i} \right]=\left\{\begin{array}{l} {\Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +3} \qquad 1\le i\le N_{levsoi} -1} \\ {\Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{2B_{i} +3} \qquad i=N_{levsoi} } \end{array}\right\}. + k\left[z_{h,\, i} \right] = + \left\{\begin{array}{lr} + \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ + \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} + \end{array}\right\}. The ice impedance factor is a function of ice content, and is meant to quantify the increased tortuosity of the water flow when part of the pore space is filled with ice. :ref:`Swenson et al. (2012) ` -used a power law form :math:`\Theta _{ice} =10^{-\Omega F_{ice} }` where -:math:`\Omega =6`\ and -:math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the +used a power law form :math:`\Theta _{ice} = 10^{-\Omega F_{ice} }` where +:math:`\Omega = 6`\ and +:math:`F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }` is the ice-filled fraction of the pore space. Because the hydraulic properties of mineral and organic soil may differ @@ -535,16 +510,16 @@ porosity of organic matter and the porosity of the mineral soil .. math:: :label: 7.91) - \theta _{sai,\min ,i} =0.489-0.00126(\% sand)_{i} . + \theta _{sai,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . -The exponent “:math:`B`†is +The exponent :math:`B_{i}` is .. math:: :label: 7.92) B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} -where :math:`B_{om} =2.7`\ (:ref:`Letts et al. 2000 `) and +where :math:`B_{om} = 2.7` \ (:ref:`Letts et al. 2000 `) and .. math:: :label: 7.93) @@ -566,7 +541,7 @@ where the saturated soil matric potential (mm) is \psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om} -where :math:`\psi _{sat,om} =-10.3`\ mm (Letts et al. 2000) is the +where :math:`\psi _{sat,om} = -10.3` \ mm (:ref:`Letts et al. 2000 `) is the saturated organic matter matric potential and the saturated mineral soil matric potential :math:`\psi _{sat,\min ,i}` \ is @@ -586,9 +561,9 @@ as 1 %. To better represent the influence of organic soil material on the grid cell average saturated hydraulic conductivity, the soil organic matter fraction is further subdivided into “connected†and “unconnected†fractions using a result from percolation theory (:ref:`Stauffer and Aharony -1994 `, :ref:`Berkowitz and Balberg 1992 `). Assuming that the organic and mineral -fractions are randomly distributed throughout a soil layer, percolation -theory predicts that above a threshold value +1994 `, :ref:`Berkowitz and Balberg 1992 `). +Assuming that the organic and mineral fractions are randomly distributed throughout +a soil layer, percolation theory predicts that above a threshold value :math:`f_{om} =f_{threshold}` , connected flow pathways consisting of organic material only exist and span the soil space. Flow through these pathways interacts only with organic material, and thus can be described @@ -597,7 +572,10 @@ by :math:`k_{sat,\, om}` . This fraction of the grid cell is given by .. math:: :label: 7.97) - \begin{array}{l} {f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta _{perc} } f_{om} {\rm \; }\qquad f_{om} \ge f_{threshold} } \\ {f_{perc} =0\qquad f_{om} `) as +texture (:ref:`Cosby et al. 1984 `) as .. math:: :label: 7.99) @@ -633,7 +611,7 @@ Numerical Solution ^^^^^^^^^^^^^^^^^^^^^^^^ With reference to :numref:`Water flux schematic figure`, the equation for conservation of mass -(equation ) can be integrated over each layer as +(equation :eq:`ZEqnNum790844`) can be integrated over each layer as .. math:: :label: 7.101) @@ -777,8 +755,7 @@ where r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . The tridiagonal equation set is solved over -:math:`i=1,\ldots ,N_{levsoi} +1` where the layer -:math:`i=N_{levsoi} +1` is a virtual layer representing the aquifer. +:math:`i=1,\ldots ,N_{levsoi}`. The finite-difference forms of the fluxes and partial derivatives in equations - can be obtained from equation as @@ -847,90 +824,6 @@ derived from equation \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } =\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } =\left(1-\frac{f_{frz,\, i} +f_{frz,\, i+1} }{2} \right)\left(2B_{i} +3\right)k_{sat} \left[z_{h,\, i} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right)} \end{array}. -Equilibrium soil matric potential and volumetric moisture -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The equilibrium soil matric potential :math:`\psi _{E}` can be derived -from equation as - -.. math:: - :label: ZEqnNum899028 - - \psi _{E} =\psi _{sat} \left(\frac{\theta _{E} \left(z\right)}{\theta _{sat} } \right)^{-B} - -and the equilibrium volumetric water content -:math:`\theta _{E} \left(z\right)` at depth :math:`z` can also be -derived as - -.. math:: - :label: 7.127) - - \theta _{E} \left(z\right)=\theta _{sat} \left(\frac{\psi _{sat} +z_{\nabla } -z}{\psi _{sat} } \right)^{-\frac{1}{B} } . - -Here, the soil matric potentials, the water table depth -:math:`z_{\nabla }` and the soil depths have units of mm. For the -finite-difference scheme, a layer-average equilibrium volumetric water -content is used in equation and can be obtained from - -.. math:: - :label: 7.128) - - \overline{\theta _{E,\, i} }=\int _{z_{h,\, i-1} }^{z_{h,\, i} }\frac{\theta _{E} \left(z\right)}{z_{h,\, i} -z_{h,\, i-1} } \, dz - -which when integrated yields - -.. math:: - :label: ZEqnNum445442 - - \overline{\theta _{E,\, i} }=\frac{\theta _{sat,\, i} \psi _{sat,\, i} }{\left(z_{h,\, i} -z_{h,\, i-1} \right)\left(1-\frac{1}{B_{i} } \right)} \left[\left(\frac{\psi _{sat,\, i} -z_{\nabla } +z_{h,\, i} }{\psi _{sat,\, i} } \right)^{1-\frac{1}{B_{i} } } -\left(\frac{\psi _{sat,\, i} -z_{\nabla } +z_{h,\, i-1} }{\psi _{sat,\, i} } \right)^{1-\frac{1}{B_{i} } } \right]. - -Equation is valid when the water table :math:`z_{\nabla }` is deeper -than both interface depths :math:`z_{h,\, i-1}` and -:math:`z_{h,\, i}` . Since the water table can be within the soil -column, the equation is modified if the water table is within soil layer -:math:`i` (:math:`z_{h,\, i-1} z_{h,\, N_{levsoi} }` ), an equilibrium volumetric -soil moisture is calculated for a virtual layer :math:`i=N_{levsoi} +1` -as - -.. math:: - :label: ZEqnNum235293 - - \overline{\theta _{E,\, i=N_{levsoi+1} } }=\frac{\theta _{sat,i-1} \psi _{sat,\, i-1} }{\left(z_{\nabla } -z_{h,\, i-1} \right)\left(1-\frac{1}{B_{i-1} } \right)} \left[1-\left(\frac{\psi _{sat,\, i-1} -z_{\nabla } +z_{h,\, i-1} }{\psi _{sat,\, i-1} } \right)^{1-\frac{1}{B_{i-1} } } \right] - -The equilibrium volumetric soil moisture is constrained by - -.. math:: - :label: 7.133) - - 0\le \overline{\theta _{E,\, i} }\le \theta _{sat,\, i} - -The equilibrium soil matric potential is then - -.. math:: - :label: ZEqnNum533842 - - \psi _{E,\, i} =\psi _{sat,\, i} \left(\frac{\overline{\theta _{E,\, i} }}{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad \frac{\overline{\theta _{E,\, i} }}{\theta _{sat,\, i} } \ge 0.01 - Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' @@ -993,47 +886,23 @@ The coefficients of the tridiagonal set of equations for r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . -Equation set for layers :math:`i=N_{levsoi} ,\ldots N_{levsoi} +1` +Equation set for layer :math:`i=N_{levsoi}` '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' -For the lowest soil layer (:math:`i=N_{levsoi}` ), the bottom boundary -condition depends on the depth of the water table. If the water table is -within the soil column (:math:`z_{\nabla } \le z_{h,\, N_{levsoi} }` ), -a zero-flux bottom boundary condition is applied (:math:`q_{i}^{n} =0`) +For the lowest soil layer (:math:`i=N_{levsoi}` ), a zero-flux bottom boundary +condition is applied (:math:`q_{i}^{n} =0`) and the coefficients of the tridiagonal set of equations for :math:`i=N_{levsoi}` are -.. math:: - :label: 7.144) - - a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } - -.. math:: - :label: 7.145) - - b_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} - -.. math:: - :label: 7.146) - - c_{i} =0 - -.. math:: - :label: 7.147) - - r_{i} =q_{i-1}^{n} +e_{i} . - -The coefficients for the aquifer layer :math:`i=N_{levsoi} +1` are then - .. math:: :label: 7.148) - a_{i} =0 + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: :label: 7.149) - b_{i} =-\frac{\Delta z_{i} }{\Delta t} + b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: :label: 7.150) @@ -1043,83 +912,28 @@ The coefficients for the aquifer layer :math:`i=N_{levsoi} +1` are then .. math:: :label: 7.151) - r_{i} =0. + r_{i} =q_{i-1}^{n} +e_{i} . -If the water table is below the soil column -(:math:`z_{\nabla } >z_{h,\, N_{levsoi} }` ), the coefficients for -:math:`i=N_{levsoi}` are +Adaptive Time Stepping +''''''''''''''''''''''''''''' +The tridiagonal equation set is solved using an adaptive time-stepping procedure. +An initial solution is found by setting :math:`\Delta t` equal to the model time +step. An estimate of the error is calculated from .. math:: :label: 7.152) - a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } - -.. math:: - :label: 7.153) - - b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} - -.. math:: - :label: 7.154) - - c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } - -.. math:: - :label: 7.155) - - r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . - -The :math:`i=N_{levsoi} +1` terms are evaluated using - -.. math:: - :label: 7.156) - - \psi _{N_{levsoi} +1} =\psi _{sat,\, N_{levsoi} } \left[s_{N_{levsoi} +1} \right]^{-B_{N_{levsoi} } } \ge -1\times 10^{8} - -.. math:: - :label: 7.157) - - z_{N_{levsoi} +1} =0.5\left(z_{\nabla } +z_{N_{levsoi} } \right) - -where - -.. math:: - :label: 7.158) - - s_{N_{levsoi} +1} =0.5\left(\frac{\theta _{sat,\, N_{levsoi} } +\theta _{N_{levsoi} } }{\theta _{sat,\, N_{levsoi} } } \right)\qquad 0.01\le s_{N_{levsoi} +1} \le 1, - -:math:`\psi _{E,\, N_{levsoi} +1}` is evaluated from equations and , - -and - -.. math:: - :label: 7.159) - - \frac{\partial \psi _{N_{levsoi} +1} }{\partial \theta _{liq,\, N_{levsoi} +1} } =-B_{N_{levsoi} } \frac{\psi _{N_{levsoi} +1} }{s_{\, N_{levsoi} } \theta _{sat,\, N_{levsoi} } } . - -The coefficients for the aquifer layer :math:`i=N_{levsoi} +1` are then - -.. math:: - :label: 7.160) - - a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } - -.. math:: - :label: 7.161) + \epsilon = max \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - + \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] - b_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} +If :math:`\epsilon` is greater than a specified error tolerance, the solution is +rejected, :math:`\Delta t` is halved and a new solution is determined. If the solution +is accepted, the procedure repeats until the adaptive sub-stepping spans the full +model time step. During the solution, the sub-steps may be halved until a +specified minimum time step length is reached, and the sub-steps may be doubled +when :math:`\epsilon` is less than a specified error tolerance. -.. math:: - :label: 7.162) - - c_{i} =0 - -.. math:: - :label: 7.163) - - r_{i} =q_{i-1}^{n} . - -Upon solution of the tridiagonal equation set (Press et al. 1992), the +Upon solution of the tridiagonal equation set, the liquid water contents are updated as follows .. math:: @@ -1160,9 +974,8 @@ hydraulic conductivity, k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta _{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right) -where :math:`\Theta _{ice}` is an ice impedance factor determined from -the ice content of the soil layers interacting with the water table -(section 7.6), :math:`\beta` is the mean grid cell topographic slope in +where :math:`\Theta_{ice}` is an ice impedance factor, :math:`\beta` +is the mean grid cell topographic slope in radians, :math:`z_{frost}` \ is the depth to the frost table, and :math:`z_{\nabla ,perch}` is the depth to the perched saturated zone. The frost table :math:`z_{frost}` is defined as the shallowest frozen @@ -1174,88 +987,33 @@ threshold is set to 0.9. Drainage from the perched saturated zone through :math:`N_{frost}` , which are the layers containing :math:`z_{\nabla ,perch}` and, :math:`z_{frost}` \ respectively. -.. _Groundwater-Soil Water Interactions: +.. _Lateral Sub-surface Runoff: -Groundwater-Soil Water Interactions +Lateral Sub-surface Runoff --------------------------------------- - -Drainage or sub-surface runoff is based on the SIMTOP scheme (Niu et al. -2005) with a modification to account for reduced drainage in frozen -soils. In the work of Niu et al. (2005), the drainage :math:`q_{drai}` -(kg m\ :sup:`-2` s\ :sup:`-1`) was formulated as - -.. math:: - :label: ZEqnNum924767 - - q_{drai} =q_{drai,\, \max } \exp \left(-f_{drai} z_{\nabla } \right). - -Here, the water table depth :math:`z_{\nabla }` has units of meters. To -restrict drainage in frozen soils, Niu et al. (2005) added the following -condition - -.. math:: - :label: 7.169) - - q_{drai} =0\qquad {\rm for\; \; }w_{ice,\, N_{levsoi} } >w_{liq,\, N_{levsoi} } . - -In preliminary testing it was found that a more gradual restriction of -drainage was required so that the water table depth remained dynamic -under partially frozen conditions. The following modification is made to -equation - -.. math:: - :label: ZEqnNum150955 - - q_{drai} =\Theta _{ice} q_{drai,\, \max } \exp \left(-f_{drai} z_{\nabla } \right) - -where :math:`\Theta _{ice}` is an ice impedance factor determined from -the ice content of the soil layers interacting with the water table +Lateral sub-surface runoff occurs when saturated soil moisture conditions +exist within the soil column. Sub-surface runoff is .. math:: - :label: 7.171) + :label: 7.168) - \Theta _{ice} =10^{-\Omega \left(\frac{\sum _{i=jwt}^{i=N_{levsoi} }F_{ice,i} \Delta z_{i} }{\sum _{i=jwt}^{i=N_{levsoi} }\Delta z_{i} } \right)} + q_{subsurface} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) + \Delta z_{sat}^{N_{baseflow}} \ , -where :math:`\Omega =6`\ is an adjustable parameter, :math:`jwt` is the -index of the layer directly above the water table, -:math:`F_{ice} =\frac{\theta _{ice} }{\theta _{sat} }` is the -ice-filled fraction of the pore space of soil layer :math:`i` (kg -m\ :sup:`-2`), and :math:`\Delta z_{i}` is the layer thickness (mm). This -expression is functionally the same as that used to determine the ice -impedance factor in section :numref:`Hydraulic Properties`. In equation , -the decay factor :math:`f_{drai} =2.5` m\ :sup:`-1` and the maximum drainage -when the water table depth is at the surface -:math:`q_{drai,\, \max } =10\sin (\beta )` kg m\ :sup:`-2` -s\ :sup:`-1` , where :math:`\beta` is the mean grid cell -topographic slope in radians, were determined for global simulations -through sensitivity analysis and comparison with observed runoff. +where :math:`K_{baseflow}` is a calibration parameter, :math:`\beta` is the +topographic slope, the exponent :math:`N_{baseflow}` = 1, and :math:`\Delta z_{sat}` +is the thickness of the saturated portion of the soil column. -Determination of water table depth :math:`z_{\nabla }` is based on work -by Niu et al. (2007). In this approach, a groundwater component is added -in the form of an unconfined aquifer lying below the soil column (:numref:`Hydrologic processes figure`). The groundwater solution is dependent on whether the water table -is within or below the soil column. The water stored in the unconfined -aquifer :math:`W_{a}` has a prescribed maximum value (5000 mm). When -the water table is within the soil column, :math:`W_{a}` is constant -because there is no water exchange between the soil column and the -underlying aquifer. In this case, recharge to the water table is -diagnosed by applying Darcy’s law across the water table +The saturated thickness is .. math:: - :label: 7.172) - - q_{rech\arg e} =-k_{aq} \frac{\left(\Psi _{\nabla } -\Psi _{jwt} \right)}{\left(z_{\nabla } -z_{jwt} \right)} + :label: 7.1681) -where :math:`\Psi _{\nabla } =0` is the matric potential at the water -table and\ :math:`k_{aq} =\Theta _{ice,jwt+1} k\left[z_{jwt+1} \right]` -is the hydraulic conductivity of the layer containing the water table. -Change in the water table is then calculated as the difference between -recharge and drainage, scaled by the specific yield of the layer -containing the water table + \Delta z_{sat} = z_{bedrock} - z_{\nabla}, -.. math:: - :label: ZEqnNum287831 - - \Delta z_{\nabla } =\frac{\left(q_{rech\arg e} -q_{drai} \right)}{S_{y} } \Delta t. +where the water table :math:`z_{\nabla}` is determined by finding the +first soil layer above the bedrock depth (section ) in which the volumetric water +content drops below a specified threshold. The default threshold is set to 0.9. The specific yield, :math:`S_{y}` , which depends on the soil properties and the water table location, is derived by taking the @@ -1271,36 +1029,6 @@ where B is the Clapp-Hornberger exponent. Because :math:`S_{y}` is a function of the soil properties, it results in water table dynamics that are consistent with the soil water fluxes described in section 7.4. -For the case when the water table is below the soil column, the change -in water stored in the unconfined aquifer :math:`W_{a}` (mm) is updated -as - -.. math:: - :label: 7.174a) - - \Delta W_{a}^{} =\left(q_{recharge} -q_{drai} \right)\Delta t - -and the water table is updated using equation with the specific yield of -layer :math:`N_{levsoi}` . - -The recharge rate is defined as positive when water enters the aquifer - -.. math:: - :label: 7.174b) - - q_{recharge} =\frac{\Delta \theta _{liq,\, N_{levsoi} +1} \Delta z_{N_{levsoi} +1} }{\Delta t} - -where -:math:`\Delta \theta _{liq,\, N_{levsoi} +1} =\theta _{liq,\, N_{levsoi} +1}^{n+1} -\theta _{liq,\, N_{levsoi} +1}^{n}` -is the change in liquid water content for layer :math:`i=N_{levsoi} +1` -calculated from the solution of the soil water equations (section 7.4), -and :math:`\Delta z_{N_{levsoi} +1}` (mm) is - -.. math:: - :label: 7.174c) - - \Delta z_{N_{levsoi} +1} =z_{\nabla }^{n} -z_{h,\, N_{levsoi} } . - After the above calculations, two numerical adjustments are implemented to keep the liquid water content of each soil layer (:math:`w_{liq,\, i}` ) within physical constraints of diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index e48ba34933..ca5fa9f660 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -19,6 +19,8 @@ area indices (section 4.1). Canopy conductance is where :math:`r_{b}` is the leaf boundary layer resistance (section 5.3). The equation set is described by Bonan et al. (2011). +.. _Stomatal resistance: + Stomatal resistance ----------------------- @@ -65,65 +67,69 @@ s m\ :sup:`2` :math:`\mu` mol\ :sub:`-1` to s m\ :sup:`-1` as: kmol\ :sup:`-1`) (Table 2.6) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). -Table 8.1. Plant functional type (PFT) photosynthetic parameters. - -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| PFT | m | :math:`\alpha` | :math:`CN_{L}` | :math:`F_{LNR}` | :math:`SLA_{0}` | :math:`\psi _{o}` | :math:`\psi _{c}` | :math:`{V}_{cmax25}` | -+==================================+=====+====================+===================+====================+====================+======================+======================+===========================+ -| NET Temperate | 9 | – | 35 | 0.0509 | 0.010 | -66000 | -255000 | 62.5 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| NET Boreal | 9 | – | 40 | 0.0466 | 0.008 | -66000 | -255000 | 62.6 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| NDT Boreal | 9 | – | 25 | 0.0546 | 0.024 | -66000 | -255000 | 39.1 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BET Tropical | 9 | – | 30 | 0.0461 | 0.012 | -66000 | -255000 | 55.0 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BET temperate | 9 | – | 30 | 0.0515 | 0.012 | -66000 | -255000 | 61.5 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BDT tropical | 9 | – | 25 | 0.0716 | 0.030 | -35000 | -224000 | 41.0 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BDT temperate | 9 | – | 25 | 0.1007 | 0.030 | -35000 | -224000 | 57.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BDT boreal | 9 | – | 25 | 0.1007 | 0.030 | -35000 | -224000 | 57.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BES temperate | 9 | – | 30 | 0.0517 | 0.012 | -83000 | -428000 | 61.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BDS temperate | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| BDS boreal | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| C\ :sub:`3` arctic grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| C\ :sub:`3` grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| C\ :sub:`4` grass | 4 | 0.05 | 25 | 0.0900 | 0.030 | -74000 | -275000 | 51.6 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Crop R | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Crop I | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Corn R | 4 | 0.05 | 25 | 0.2930 | 0.050 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Corn I | 4 | 0.05 | 25 | 0.2930 | 0.050 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Temp Cereal R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Temp Cereal I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Winter Cereal R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Winter Cereal I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Soybean R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ -| Soybean I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | -+----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ +.. _Table Plant functional type (PFT) photosynthetic parameters: + +.. table:: Plant functional type (PFT) photosynthetic parameters. + + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | PFT | m | :math:`\alpha` | :math:`CN_{L}` | :math:`F_{LNR}` | :math:`SLA_{0}` | :math:`\psi _{o}` | :math:`\psi _{c}` | :math:`{V}_{cmax25}` | + +==================================+=====+====================+===================+====================+====================+======================+======================+===========================+ + | NET Temperate | 9 | – | 35 | 0.0509 | 0.010 | -66000 | -255000 | 62.5 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | NET Boreal | 9 | – | 40 | 0.0466 | 0.008 | -66000 | -255000 | 62.6 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | NDT Boreal | 9 | – | 25 | 0.0546 | 0.024 | -66000 | -255000 | 39.1 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BET Tropical | 9 | – | 30 | 0.0461 | 0.012 | -66000 | -255000 | 55.0 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BET temperate | 9 | – | 30 | 0.0515 | 0.012 | -66000 | -255000 | 61.5 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BDT tropical | 9 | – | 25 | 0.0716 | 0.030 | -35000 | -224000 | 41.0 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BDT temperate | 9 | – | 25 | 0.1007 | 0.030 | -35000 | -224000 | 57.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BDT boreal | 9 | – | 25 | 0.1007 | 0.030 | -35000 | -224000 | 57.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BES temperate | 9 | – | 30 | 0.0517 | 0.012 | -83000 | -428000 | 61.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BDS temperate | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | BDS boreal | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | C\ :sub:`3` arctic grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | C\ :sub:`3` grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | C\ :sub:`4` grass | 4 | 0.05 | 25 | 0.0900 | 0.030 | -74000 | -275000 | 51.6 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Crop R | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Crop I | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Corn R | 4 | 0.05 | 25 | 0.2930 | 0.050 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Corn I | 4 | 0.05 | 25 | 0.2930 | 0.050 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Temp Cereal R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Temp Cereal I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Winter Cereal R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Winter Cereal I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Soybean R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ + | Soybean I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | + +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ :math:`\alpha` (mol CO\ :sub:`2` mol\ :sup:`-1` photon); :math:`CN_{L}` (g C g\ :sup:`-1` N); :math:`F_{LNR}` (g N Rubisco g\ :sup:`-1` N); :math:`SLA_{0}` (m\ :sup:`2` g\ :sup:`-1` C); :math:`\psi _{o}` and :math:`\psi _{c}` (mm); V\ :sub:`cmax25` (:math:`\mu`\ mol m\ :sup:`-2` s\ :sup:`-1`, calculated from equation for canopy top). +.. _Photosynthesis: + Photosynthesis ------------------ @@ -309,30 +315,32 @@ K\ :sup:`-1` and :math:`s_{6} =328.15`\ K, and with :math:`Q_{10} =2`. -Table 8.2. Temperature dependence parameters for C3 photosynthesis. - -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| Parameter | :math:`\Delta H_{a}` (J mol\ :sup:`-1`) | :math:`\Delta H_{d}` (J mol\ :sup:`-1`) | :math:`\Delta S` (J mol\ :sup:`-1` K\ :sup:`-1`) | -+========================+=================================================================+=================================================================+==============================================================================================+ -| :math:`V_{c\max }` | 65330 | 149250 | 485 | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :math:`J_{\max }` | 43540 | 152040 | 495 | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :math:`T_{p}` | 65330 | 149250 | 485 | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :math:`R_{d}` | 46390 | 150650 | 490 | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :math:`K_{c}` | 79430 | – | – | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :math:`K_{o}` | 36380 | – | – | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :math:`\Gamma _{\*}` | 37830 | – | – | -+------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - -The parameters in Table 8.2 do not allow for temperature acclimation of -photosynthesis. In the model, acclimation is implemented as in Kattge -and Knorr (2007). In this parameterization, :math:`V_{c\max }` and -:math:`J_{\max }` vary with the plant growth temperature. This is +.. _Table Temperature dependence parameters for C3 photosynthesis: + +.. table:: Temperature dependence parameters for C3 photosynthesis. + + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | Parameter | :math:`\Delta H_{a}` (J mol\ :sup:`-1`) | :math:`\Delta H_{d}` (J mol\ :sup:`-1`) | :math:`\Delta S` (J mol\ :sup:`-1` K\ :sup:`-1`) | + +========================+=================================================================+=================================================================+==============================================================================================+ + | :math:`V_{c\max }` | 65330 | 149250 | 485 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | :math:`J_{\max }` | 43540 | 152040 | 495 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | :math:`T_{p}` | 65330 | 149250 | 485 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | :math:`R_{d}` | 46390 | 150650 | 490 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | :math:`K_{c}` | 79430 | – | – | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | :math:`K_{o}` | 36380 | – | – | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + | :math:`\Gamma _{\*}` | 37830 | – | – | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + +The parameters in numref:`Table Temperature dependence parameters for C3 photosynthesis` +do not allow for temperature acclimation of photosynthesis. In the model, acclimation is +implemented as in :ref:`Kattge and Knorr (2007) `. In this parameterization, +:math:`V_{c\max }` and :math:`J_{\max }` vary with the plant growth temperature. This is achieved by allowing :math:`\Delta S`\ to vary with growth temperature according to @@ -358,6 +366,8 @@ temperature (K) and :math:`T_{f}` is the freezing point of water (K). For lack of data, :math:`T_{p}` acclimates similar to V :sub:`cmax` . Acclimation is restricted over the temperature range :math:`T_{10} -T_{f} \ge 11`\ :sup:`o`\ C and :math:`T_{10} -T_{f} \le 35`\ :sup:`o`\ C. +.. _V\ :sub:`cmax25` and Canopy scaling: + V\ :sub:`cmax25` and Canopy scaling -------------------------------------------- @@ -476,6 +486,8 @@ orbital geometry (:math:`\pm`\ 23.4667º [:math:`\pm`\ 0.409571 radians], positive for Northern Hemisphere latitudes and negative for Southern Hemisphere). +.. _Soil water stress: + Soil water stress --------------------- @@ -551,62 +563,66 @@ functional type where :math:`z_{h,\, i}` (m) is the depth from the soil surface to the interface between layers :math:`i` and :math:`i+1` (:math:`z_{h,\, 0}` , the soil surface) (section 6.1), and :math:`r_{a}` and :math:`r_{b}` -are plant-dependent root distribution parameters adopted from Zeng -(2001) (Table 8.3). - -Table 8.3. Plant functional type root distribution parameters. - -+----------------------------------+------------------+------------------+ -| Plant Functional Type | :math:`r_{a}` | :math:`r_{b}` | -+==================================+==================+==================+ -| NET Temperate | 7.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| NET Boreal | 7.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| NDT Boreal | 7.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| BET Tropical | 7.0 | 1.0 | -+----------------------------------+------------------+------------------+ -| BET temperate | 7.0 | 1.0 | -+----------------------------------+------------------+------------------+ -| BDT tropical | 6.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| BDT temperate | 6.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| BDT boreal | 6.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| BES temperate | 7.0 | 1.5 | -+----------------------------------+------------------+------------------+ -| BDS temperate | 7.0 | 1.5 | -+----------------------------------+------------------+------------------+ -| BDS boreal | 7.0 | 1.5 | -+----------------------------------+------------------+------------------+ -| C\ :sub:`3` grass arctic | 11.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| C\ :sub:`3` grass | 11.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| C\ :sub:`4` grass | 11.0 | 2.0 | -+----------------------------------+------------------+------------------+ -| Crop R | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Crop I | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Corn R | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Corn I | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Temp Cereal R | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Temp Cereal I | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Winter Cereal R | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Winter Cereal I | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Soybean R | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ -| Soybean I | 6.0 | 3.0 | -+----------------------------------+------------------+------------------+ +are plant-dependent root distribution parameters adopted from :ref:`Zeng (2001) ` +(:numref:`Table Plant functional type root distribution parameters`). + +.. _Table Plant functional type root distribution parameters: + +.. table:: Plant functional type root distribution parameters + + +----------------------------------+------------------+------------------+ + | Plant Functional Type | :math:`r_{a}` | :math:`r_{b}` | + +==================================+==================+==================+ + | NET Temperate | 7.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | NET Boreal | 7.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | NDT Boreal | 7.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | BET Tropical | 7.0 | 1.0 | + +----------------------------------+------------------+------------------+ + | BET temperate | 7.0 | 1.0 | + +----------------------------------+------------------+------------------+ + | BDT tropical | 6.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | BDT temperate | 6.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | BDT boreal | 6.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | BES temperate | 7.0 | 1.5 | + +----------------------------------+------------------+------------------+ + | BDS temperate | 7.0 | 1.5 | + +----------------------------------+------------------+------------------+ + | BDS boreal | 7.0 | 1.5 | + +----------------------------------+------------------+------------------+ + | C\ :sub:`3` grass arctic | 11.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | C\ :sub:`3` grass | 11.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | C\ :sub:`4` grass | 11.0 | 2.0 | + +----------------------------------+------------------+------------------+ + | Crop R | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Crop I | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Corn R | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Corn I | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Temp Cereal R | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Temp Cereal I | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Winter Cereal R | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Winter Cereal I | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Soybean R | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + | Soybean I | 6.0 | 3.0 | + +----------------------------------+------------------+------------------+ + +.. _Numerical implementation photosynthesis: Numerical implementation ---------------------------- diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 4b81731fb0..3e52821ef7 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -52,7 +52,7 @@ Arah, J. and Vinten, A., 1995. Simplified models of anoxia and denitrification in aggregated and simple-structured soils. European Journal of Soil Science 46:507-517. -.. _Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global +.. _Arendtetal2012: Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global Glacier Outlines Version: 1.0, Global Land Ice Measurements from Space, @@ -344,6 +344,8 @@ correspond with changes in labile organic C fractions in soil amended with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): 453-462. +.. _deVries1963: + de Vries, D.A. 1963. Thermal Properties of Soils. In: W.R. van Wijk (editor) Physics of the Plant Environment. North-Holland, Amsterdam. @@ -1692,6 +1694,17 @@ Swenson, S.C. and Lawrence, D.M. 2012. A New Fractional Snow Covered Area Parameterization for the Community Land Model and its Effect on the Surface Energy Balance. JGR, 117, D21107. DOI:10.1029/2012JD018178. +.. _SwensonLawrence2014: +Swenson, S.C., and D. M. Lawrence. 2014. Assessing a dry surface +layer-based soil resistance parameterization for the Community Land Model +using GRACE and FLUXNET-MTE data. JGR, 119, 10, 299–10,312, +DOI:10.1002/2014JD022314. + +.. _SwensonLawrence2015: +Swenson, S.C., and D. M. Lawrence. 2015. A GRACE-based assessment of +interannual groundwater dynamics in the Community Land Model. WRR, 51, +doi:10.1002/2015WR017582. + .. _TaWeiland1992: Ta, C.T. and Weiland, R.T. 1992. Nitrogen partitioning in maize during @@ -1920,7 +1933,7 @@ hydrology parameterization with subgrid variability for general circulation models. J. Geophys. Res. 97(D3):2717–2728. DOI:10.1029/91JD01786. -.. _World Bank2004: +.. _WorldBank2004: World Bank, 2004. World development indicators 2004, Oxford University Press, New York, 416 pp. diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index f033832ceb..dbe949bd34 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -103,7 +103,11 @@ The conservation equation for mass of ice in snow layers is .. math:: :label: 8.17) - \frac{\partial w_{ice,\, i} }{\partial t} =\left\{\begin{array}{l} {f_{sno} q_{ice,\, i-1} -\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} \qquad i=snl+1} \\ {-\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} \qquad i=snl+2,\ldots ,0} \end{array}\right\} + \frac{\partial w_{ice,\, i} }{\partial t} = + \left\{\begin{array}{lr} + f_{sno} \ q_{ice,\, i-1} -\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} & \qquad i=snl+1 \\ + -\frac{\left(\Delta w_{ice,\, i} \right)_{p} }{\Delta t} & \qquad i=snl+2,\ldots ,0 + \end{array}\right\} where :math:`q_{ice,\, i-1}` is the rate of ice accumulation from precipitation or frost or the rate of ice loss from sublimation (kg @@ -143,7 +147,12 @@ m\ :sup:`-3`) (:ref:`Anderson (1976) `) .. math:: :label: 8.21) - \rho _{sno} =\left\{\begin{array}{l} {50+1.7\left(17\right)^{1.5} \qquad T_{atm} >T_{f} +2} \\ {50+1.7\left(T_{atm} -T_{f} +15\right)^{1.5} \qquad T_{f} -15T_{f} +2 \ \\ + 50+1.7 \left(T_{atm} -T_{f} + 15\right)^{1.5} & \qquad T_{f} - 15 < T_{atm} \le T_{f} + 2 \ \\ + 50 &\qquad T_{atm} \le T_{f} - 15 + \end{array}\right\} where :math:`T_{atm}` is the atmospheric temperature (K), and :math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). The diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index c1971be79a..083c6b651e 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -46,82 +46,17 @@ surface water temperatures for a fifteen-layer soil column with up to five overlying layers of snow and a single surface water layer with the boundary conditions of :math:`h` as the heat flux into the top soil, snow, and surface water layers from the overlying atmosphere (section -6.1) and zero heat flux at the bottom of the soil column. The -temperature profile is calculated first without phase change and then -readjusted for phase change (section 6.2). +:numref:`Numerical Solution Temperature`) and zero heat flux at the bottom +of the soil column. The temperature profile is calculated first without +phase change and then readjusted for phase change (section :numref:`Phase Change`). .. _Numerical Solution Temperature: Numerical Solution ---------------------- -The soil column is discretized into fifteen layers (Table 6.1) where the -depth of soil layer :math:`i`, or node depth, :math:`z_{i}` (m), is - -.. math:: - :label: ZEqnNum185766 - - z_{i} =f_{s} \left\{\exp \left[0.5\left(i-0.5\right)\right]-1\right\} - -where :math:`f_{s} =0.025` is a scaling factor. The thickness of each -layer :math:`\Delta z_{i}` (m) is - -.. math:: - :label: 6.6) - - \Delta z_{i} =\left\{\begin{array}{l} {0.5\left(z_{1} +z_{2} \right)\qquad i=1} \\ {0.5\left(z_{i+1} -z_{i-1} \right)\qquad i=2,3,\ldots ,N_{levgrnd} -1} \\ {z_{N} -z_{N-1} \qquad i=N_{levgrnd} } \end{array}\right\} - -where :math:`N_{levgrnd} =15` is the number of soil layers. The depths -at the layer interfaces :math:`z_{h,\, i}` (m) are - -.. math:: - :label: 6.7) - - z_{h,\, i} =\left\{\begin{array}{l} {0.5\left(z_{i} +z_{i+1} \right)\qquad i=1,2,\ldots ,N_{levgrnd} -1} \\ {z_{N_{levgrnd} } +0.5\Delta z_{N_{levgrnd} } \qquad i=N_{levgrnd} } \end{array}\right\}. - -The exponential form of equation is to obtain more soil layers near the -soil surface where the soil water gradient is generally strong (section -7.4). - -Table 6.1. Soil layer structure. - -Layer node depth (:math:`z_{i}` ), thickness (:math:`\Delta z_{i}` ), -and depth at layer interface (:math:`z_{h,\, i}` ) for fifteen-layer -soil column. All in meters. - -+---------------+------------------+-------------------------+-----------------------+ -| Layer | :math:`z_{i}` | :math:`\Delta z_{i}` | :math:`z_{h,\, i}` | -+===============+==================+=========================+=======================+ -| 1 (top) | 0.0071 | 0.0175 | 0.0175 | -+---------------+------------------+-------------------------+-----------------------+ -| 2 | 0.0279 | 0.0276 | 0.0451 | -+---------------+------------------+-------------------------+-----------------------+ -| 3 | 0.0623 | 0.0455 | 0.0906 | -+---------------+------------------+-------------------------+-----------------------+ -| 4 | 0.1189 | 0.0750 | 0.1655 | -+---------------+------------------+-------------------------+-----------------------+ -| 5 | 0.2122 | 0.1236 | 0.2891 | -+---------------+------------------+-------------------------+-----------------------+ -| 6 | 0.3661 | 0.2038 | 0.4929 | -+---------------+------------------+-------------------------+-----------------------+ -| 7 | 0.6198 | 0.3360 | 0.8289 | -+---------------+------------------+-------------------------+-----------------------+ -| 8 | 1.0380 | 0.5539 | 1.3828 | -+---------------+------------------+-------------------------+-----------------------+ -| 9 | 1.7276 | 0.9133 | 2.2961 | -+---------------+------------------+-------------------------+-----------------------+ -| 10 | 2.8646 | 1.5058 | 3.8019 | -+---------------+------------------+-------------------------+-----------------------+ -| 11 | 4.7392 | 2.4826 | 6.2845 | -+---------------+------------------+-------------------------+-----------------------+ -| 12 | 7.8298 | 4.0931 | 10.3775 | -+---------------+------------------+-------------------------+-----------------------+ -| 13 | 12.9253 | 6.7484 | 17.1259 | -+---------------+------------------+-------------------------+-----------------------+ -| 14 | 21.3265 | 11.1262 | 28.2520 | -+---------------+------------------+-------------------------+-----------------------+ -| 15 (bottom) | 35.1776 | 13.8512 | 42.1032 | -+---------------+------------------+-------------------------+-----------------------+ +The soil column is discretized into 25 layers (section :numref:`Vertical Discretization`) +where :math:`N_{levgrnd} = 25` is the number of soil layers (:numref:`Table Soil layer structure`). The overlying snow pack is modeled with up to five layers depending on the total snow depth. The layers from top to bottom are indexed in the @@ -209,9 +144,6 @@ equals the heat flux from the interface to :math:`i+1` (depth where :math:`T_{m}` is the temperature at the interface of layers :math:`i` and :math:`i+1`. -Figure 6.1. Schematic diagram of numerical scheme used to solve for soil -temperature. - Shown are three soil layers, :math:`i-1`, :math:`i`, and :math:`i+1`. The thermal conductivity :math:`\lambda` , specific heat capacity :math:`c`, and temperature :math:`T` are defined at the layer node depth @@ -222,8 +154,11 @@ interface of two layers :math:`z_{h}` . The layer thickness is :math:`\Delta z`. The heat fluxes :math:`F_{i-1}` and :math:`F_{i}` are defined as positive upwards. -.. image:: image1.png +.. _Figure Soil Temperature Schematic: +.. figure:: image1.png + + Schematic diagram of numerical scheme used to solve for soil temperature. The energy balance for the :math:`i^{th}` layer is @@ -769,23 +704,31 @@ cool the snow layer. Soil and Snow Thermal Properties ------------------------------------ -The thermal and hydraulic (section 6.3 and 7.4.1) properties of the soil -are assumed to be a weighted combination of the mineral and organic -properties of the soil (Lawrence and Slater 2008). The soil layer -organic matter fraction :math:`f_{om,i}` is +The thermal properties of the soil are assumed to be a weighted combination of +the mineral and organic properties of the soil +(:ref:`Lawrence and Slater 2008 `). +The soil layer organic matter fraction :math:`f_{om,i}` is .. math:: :label: 6.77) f_{om,i} =\rho _{om,i} /\rho _{om,\max } . -Soil thermal conductivity :math:`\lambda _{i}` (W m\ :sup:`-1` -K\ :sup:`-1`) is from Farouki (1981) +Soil thermal conductivity :math:`\lambda _{i}` (W m\ :sup:`-1` K\ :sup:`-1`) +is from :ref:`Farouki (1981) ` .. math:: :label: 6.78) - \begin{array}{l} {\lambda _{i} =\left\{\begin{array}{l} {K_{e,\, i} \lambda _{sat,\, i} +\left(1-K_{e,\, i} \right)\lambda _{dry,\, i} \qquad S_{r,\, i} >1\times 10^{-7} } \\ {\lambda _{dry,\, i} \qquad S_{r,\, i} \le 1\times 10^{-7} } \end{array}\right\}\qquad i=1,\ldots ,N_{levsoi} } \\ {\lambda _{i} =\lambda _{bedrock} \qquad i=N_{levsoi} +1,\ldots N_{levgrnd} } \end{array} + \begin{array}{lr} + \lambda _{i} = \left\{ + \begin{array}{lr} + K_{e,\, i} \lambda _{sat,\, i} +\left(1-K_{e,\, i} \right)\lambda _{dry,\, i} &\qquad S_{r,\, i} > 1\times 10^{-7} \\ + \lambda _{dry,\, i} &\qquad S_{r,\, i} \le 1\times 10^{-7} + \end{array}\right\} &\qquad i=1,\ldots ,N_{levsoi} \\ + + \lambda _{i} =\lambda _{bedrock} &\qquad i=N_{levsoi} +1,\ldots N_{levgrnd} + \end{array} where :math:`\lambda _{sat,\, i}` is the saturated thermal conductivity, :math:`\lambda _{dry,\, i}` is the dry thermal @@ -793,8 +736,8 @@ conductivity, :math:`K_{e,\, i}` is the Kersten number, :math:`S_{r,\, i}` is the wetness of the soil with respect to saturation, and :math:`\lambda _{bedrock} =3` W m\ :sup:`-1` K\ :sup:`-1` is the thermal conductivity assumed for the deep -ground layers (typical of saturated granitic rock; Clauser and Huenges, -1995). For glaciers and wetlands, +ground layers (typical of saturated granitic rock; +:ref:`Clauser and Huenges 1995 `). For glaciers and wetlands, .. math:: :label: 6.79) @@ -830,8 +773,8 @@ where the mineral soil solid thermal conductivity \lambda _{s,\, \min ,i} =\frac{8.80{\rm \; }\left(\% sand\right)_{i} +{\rm 2.92\; }\left(\% clay\right)_{i} }{\left(\% sand\right)_{i} +\left(\% clay\right)_{i} } , and :math:`\lambda _{s,om} =0.25`\ W m\ :sup:`-1` -K\ :sup:`-1` (Farouki, 1981). :math:`\theta _{sat,\, i}` is the -volumetric water content at saturation (porosity) (section 7.4.1). +K\ :sup:`-1` (:ref:`Farouki 1981 `). :math:`\theta _{sat,\, i}` is the +volumetric water content at saturation (porosity) (section :numref:`Hydraulic Properties`). The thermal conductivity of dry soil is @@ -852,14 +795,18 @@ m\ :sup:`-3`) as \lambda _{dry,\, \min ,i} =\frac{0.135\rho _{d,\, i} +64.7}{2700-0.947\rho _{d,\, i} } and :math:`\lambda _{dry,om} =0.05` W m\ :sup:`-1` -K\ :sup:`-1` (Farouki, 1981) is the dry thermal conductivity of +K\ :sup:`-1` (:ref:`Farouki 1981 `) is the dry thermal conductivity of organic matter. The Kersten number :math:`K_{e,\, i}` is a function of the degree of saturation :math:`S_{r}` and phase of water .. math:: :label: 6.85) - K_{e,\, i} =\left\{\begin{array}{l} {\log \left(S_{r,\, i} \right)+1\ge 0\qquad T_{i} \ge T_{f} } \\ {S_{r,\, i} \qquad T_{i} ` .. math:: :label: 6.87) \lambda _{i} =\lambda _{air} +\left(7.75\times 10^{-5} \rho _{sno,\, i} +1.105\times 10^{-6} \rho _{sno,\, i}^{2} \right)\left(\lambda _{ice} -\lambda _{air} \right) -where :math:`\lambda _{air}` is the thermal conductivity of air (Table -2.6) and :math:`\rho _{sno,\, i}` is the bulk density of snow (kg -m\ :sup:`-3`) +where :math:`\lambda _{air}` is the thermal conductivity of air (:numref:`Table Physical Constants`) +and :math:`\rho _{sno,\, i}` is the bulk density of snow (kg m\ :sup:`-3`) .. math:: :label: 6.88) \rho _{sno,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{\Delta z_{i} } . -The volumetric heat capacity :math:`c_{i}` (J m\ :sup:`-3` -K\ :sup:`-1`) for soil is from de Vries (1963) and depends on the +The volumetric heat capacity :math:`c_{i}` (J m\ :sup:`-3` K\ :sup:`-1`) for +soil is from :ref:`de Vries (1963) ` and depends on the heat capacities of the soil solid, liquid water, and ice constituents .. math:: @@ -896,7 +842,7 @@ heat capacities of the soil solid, liquid water, and ice constituents where :math:`C_{liq}` and :math:`C_{ice}` are the specific heat capacities (J kg\ :sup:`-1` K\ :sup:`-1`) of liquid water -and ice, respectively (Table 2.6). The heat capacity of soil solids +and ice, respectively (:numref:`Table Physical Constants`). The heat capacity of soil solids :math:`c_{s,i}` \ (J m\ :sup:`-3` K\ :sup:`-1`) is .. math:: @@ -910,12 +856,15 @@ where the heat capacity of mineral soil solids .. math:: :label: 6.91) - \begin{array}{l} {c_{s,\min ,\, i} =\left(\frac{2.128{\rm \; }\left(\% sand\right)_{i} +{\rm 2.385\; }\left(\% clay\right)_{i} }{\left(\% sand\right)_{i} +\left(\% clay\right)_{i} } \right)\times 10^{6} \qquad i=1,\ldots ,N_{levsoi} } \\ {c_{s,\, \min ,i} =c_{s,\, bedrock} \qquad i=N_{levsoi} +1,\ldots ,N_{levgrnd} } \end{array} + \begin{array}{lr} + c_{s,\min ,\, i} =\left(\frac{2.128{\rm \; }\left(\% sand\right)_{i} +{\rm 2.385\; }\left(\% clay\right)_{i} }{\left(\% sand\right)_{i} +\left(\% clay\right)_{i} } \right)\times 10^{6} &\qquad i=1,\ldots ,N_{levsoi} \\ + c_{s,\, \min ,i} =c_{s,\, bedrock} &\qquad i=N_{levsoi} +1,\ldots ,N_{levgrnd} + \end{array} where :math:`c_{s,bedrock} =2\times 10^{6}` J m\ :sup:`-3` K\ :sup:`-1` is the heat capacity of bedrock and :math:`c_{s,om} =2.5\times 10^{6}` \ J m\ :sup:`-3` -K\ :sup:`-1` (Farouki, 1981) is the heat capacity of organic +K\ :sup:`-1` (ref:`Farouki 1981 `) is the heat capacity of organic matter. For glaciers, wetlands, and snow .. math:: diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index f2d54987f9..82a25eba77 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -420,71 +420,75 @@ for grasslands and crops from full optical range spectra of measured optical properties (Asner et al. 1998). Optical properties for intercepted snow (Table 3.2) are from Sellers et al. (1986). -Table 3.1. Plant functional type optical properties - -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Plant Functional Type | :math:`\chi _{L}` | :math:`\alpha _{vis}^{leaf}` | :math:`\alpha _{nir}^{leaf}` | :math:`\alpha _{vis}^{stem}` | :math:`\alpha _{nir}^{stem}` | :math:`\tau _{vis}^{leaf}` | :math:`\tau _{nir}^{leaf}` | :math:`\tau _{vis}^{stem}` | :math:`\tau _{nir}^{stem}` | -+==================================+======================+=================================+=================================+=================================+=================================+===============================+===============================+===============================+===============================+ -| NET Temperate | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| NET Boreal | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| NDT Boreal | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BET Tropical | 0.10 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BET temperate | 0.10 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BDT tropical | 0.01 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BDT temperate | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BDT boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BES temperate | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BDS temperate | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| BDS boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| C\ :sub:`3` arctic grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| C\ :sub:`3` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| C\ :sub:`4` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Crop R | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Crop I | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Corn R | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Corn I | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Temp Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Temp Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Winter Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Winter Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Soybean R | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ -| Soybean I | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | -+----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - -Table 3.2. Intercepted snow optical properties - -+-----------------------------+-------+-------+ -| Parameter | vis | nir | -+=============================+=======+=======+ -| :math:`\omega ^{sno}` | 0.8 | 0.4 | -+-----------------------------+-------+-------+ -| :math:`\beta ^{sno}` | 0.5 | 0.5 | -+-----------------------------+-------+-------+ -| :math:`\beta _{0}^{sno}` | 0.5 | 0.5 | -+-----------------------------+-------+-------+ +.. _Table Plant functional type optical properties: + +.. table:: Plant functional type optical properties + + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Plant Functional Type | :math:`\chi _{L}` | :math:`\alpha _{vis}^{leaf}` | :math:`\alpha _{nir}^{leaf}` | :math:`\alpha _{vis}^{stem}` | :math:`\alpha _{nir}^{stem}` | :math:`\tau _{vis}^{leaf}` | :math:`\tau _{nir}^{leaf}` | :math:`\tau _{vis}^{stem}` | :math:`\tau _{nir}^{stem}` | + +==================================+======================+=================================+=================================+=================================+=================================+===============================+===============================+===============================+===============================+ + | NET Temperate | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | NET Boreal | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | NDT Boreal | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BET Tropical | 0.10 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BET temperate | 0.10 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BDT tropical | 0.01 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BDT temperate | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BDT boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BES temperate | 0.01 | 0.07 | 0.35 | 0.16 | 0.39 | 0.05 | 0.10 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BDS temperate | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | BDS boreal | 0.25 | 0.10 | 0.45 | 0.16 | 0.39 | 0.05 | 0.25 | 0.001 | 0.001 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | C\ :sub:`3` arctic grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | C\ :sub:`3` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | C\ :sub:`4` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Crop R | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Crop I | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Corn R | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Corn I | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Temp Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Temp Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Winter Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Winter Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Soybean R | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + | Soybean I | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ + +.. _Table Intercepted snow optical properties: + +.. table:: Intercepted snow optical properties + + +-----------------------------+-------+-------+ + | Parameter | vis | nir | + +=============================+=======+=======+ + | :math:`\omega ^{sno}` | 0.8 | 0.4 | + +-----------------------------+-------+-------+ + | :math:`\beta ^{sno}` | 0.5 | 0.5 | + +-----------------------------+-------+-------+ + | :math:`\beta _{0}^{sno}` | 0.5 | 0.5 | + +-----------------------------+-------+-------+ .. _Ground Albedos: From 500487cd7a735c37f09562a142c91c10e5c10397 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 24 May 2017 09:06:54 -0600 Subject: [PATCH 017/255] revise irrigation section --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 136 ++++-- .../CLM50_Tech_Note_Photosynthesis.rst | 5 +- .../References/CLM50_Tech_Note_References.rst | 6 +- .../CLM50_Tech_Note_Surface_Albedos.rst | 450 ++++++++++-------- 4 files changed, 337 insertions(+), 260 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index f0f31eac92..449341c0f9 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -443,68 +443,110 @@ The irrigation model The CLM includes the option to irrigate cropland areas that are equipped for irrigation. The application of irrigation responds dynamically to the soil moisture conditions simulated by the CLM. This irrigation -algorithm is based loosely on the implementation of Ozdogan et al. -(2010). +algorithm is based loosely on the implementation of +:ref:`Ozdogan et al. (2010) `. When irrigation is enabled, the crop areas of each grid cell are divided into irrigated and rainfed fractions according to a dataset of areas -equipped for irrigation (Portmann et al. 2010). Irrigated and rainfed -crops are placed on separate soil columns, so that irrigation is only -applied to the soil beneath irrigated crops. +equipped for irrigation (:ref:`Portmann et al. 2010 `). +Irrigated and rainfed crops are placed on separate soil columns, so that +irrigation is only applied to the soil beneath irrigated crops. In irrigated croplands, a check is made once per day to determine whether irrigation is required on that day. This check is made in the first time step after 6 AM local time. Irrigation is required if crop -leaf area :math:`>` 0, and :math:`\beta_{t} < 1`, i.e., water is limiting for photosynthesis (see section 8.4). +leaf area :math:`>` 0, and the available soil water is below a specified +threshold. -If irrigation is required, the model computes the deficit between the -current soil moisture content and a target soil moisture content; this -deficit is the amount of water that will be added through irrigation. -The target soil moisture content in each soil layer *i* -(:math:`{s}_{target,i}`, kg m\ :sup:`-2`) is a weighted -average of the minimum soil moisture content that results in no water -stress in that layer (:math:`{s}_{o,i}`, kg m\ :sup:`-2`) and -the soil moisture content at saturation in that layer (:math:`{w}_{sat,i}`, kg m\ :sup:`-2`): +The soil moisture deficit :math:`D_{irrig}` is .. math:: - :label: 25.7) - - w_{target,i} =(1-0.7)\cdot w_{o,i} +0.7\cdot w_{sat,i} - -:math:`{w}_{o,i}` is determined by inverting equation 8.19 in Oleson -et al. (2010a) to solve for the value of :math:`{s}_{i}` (soil -wetness) that makes :math:`\Psi_{i} = \Psi_{o}` (where :math:`\Psi_{i}` is -the soil water matric potential and :math:`\Psi_{o}` is -the soil water potential when stomata are fully open), and then -converting this value to units of kg m\ :sup:`-2`. -:math:`{w}_{sat,i}` is calculated simply by converting effective -porosity (section 7.4) to units of kg m\ :sup:`-2`. The value 0.7 -was determined empirically, in order to give global, annual irrigation -amounts that approximately match observed gross irrigation water use -around the year 2000 (i.e., total water withdrawals for irrigation: -:math:`\sim` 2500 – 3000 km\ :sup:`3` year\ :sup:`-1` -(Shiklomanov 2000)). The total water deficit (:math:`{w}_{deficit}`, -kg m\ :sup:`-2`) of the column is then determined by: + :label: 25.61) + + D_{irrig} = \left\{ + \begin{array}{lr} + w_{thresh} - w_{avail} &\qquad w_{thresh} > w_{avail} \\ + 0 &\qquad w_{thresh} \le w_{avail} + \end{array} \right\} + +where :math:`w_{thresh}` is the irrigation moisture threshold (mm) and +:math:`w_{avail}` is the available moisture (mm). The moisture threshold +is + +.. math:: + :label: 25.62) + + w_{thresh} = f_{thresh} \left(w_{target} - w_{wilt}\right) + w_{wilt} + +where :math:`w_{target}` is the irrigation target soil moisture (mm) + +.. math:: + :label: 25.63) + + w_{target} = \sum_{j=1}^{N_{irr}} \theta_{target} \Delta z_{j} \ , + +:math:`w_{wilt}` is the wilting point soil moisture (mm) .. math:: - :label: 25.8) + :label: 25.64) - w_{deficit} =\sum _{i}\max \left(w_{target,i} -w_{liq,i} ,0\right) + w_{wilt} = \sum_{j=1}^{N_{irr}} \theta_{wilt} \Delta z_{j} \ , -where :math:`{w}_{liq,i}` (kg m\ :sup:`-2`) is the current -soil water content of layer *i* (Chapter 7). The max function means that -a surplus in one layer cannot make up for a deficit in another layer. -The sum is taken only over soil layers that contain roots. In addition, -if the temperature of any soil layer is below freezing, then the sum -only includes layers above the top-most frozen soil layer. +and :math:`f_{thresh}` is a tuning parameter. The available moisture in +the soil is -The amount of water added to this column through irrigation is then -equal to :math:`{w}_{deficit}`. This irrigation is applied at a -constant rate over the following four hours. Irrigation water is applied +.. math:: + :label: 25.65) + + w_{avail} = \sum_{j=1}^{N_{irr}} \theta_{j} \Delta z_{j} \ , + +:math:`N_{irr}` is the index of the soil layer corresponding to a specified +depth :math:`z_{irrig}` (:numref:`Table Irrigation parameters`) and +:math:`\Delta z` is the thickness of the soil layer (section +:numref:`Vertical Discretization`). :math:`\theta_{j}` is the +volumetric soil moisture in layer :math:`j` (section :numref:`Soil Water`). +:math:`\theta_{target}` and +:math:`\theta_{wilt}` are the target and wilting point volumetric +soil moisture values, respectively, and are determined by inverting +:eq:`ZEqnNum316201` using soil matric +potential parameters :math:`\Psi_{target}` and :math:`\Psi_{wilt}` +(:numref:`Table Irrigation parameters`). After the soil moisture deficit +:math:`D_{irrig}` is calculated, irrigation in an amount equal to +:math:`\frac{D_{irrig}}{T_{irrig}}` (mm/s) is applied uniformly over +the irrigation period :math:`T_{irrig}` (s). Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., -added to :math:`{q}_{grnd,liq}`: section 7.1). Added irrigation is -removed from total liquid runoff ( :math:`{R}_{liq}`: Chapter 11), -simulating removal from nearby rivers. +added to :math:`{q}_{grnd,liq}`: section :numref:`Canopy Water`). + +To conserve mass, irrigation is removed from river water storage (Chapter 11). +When river water storage is inadequate to meet irrigation demand, +there are two options: 1) the additional water can be removed from the +ocean model, or 2) the irrigation demand can be reduced such that +river water storage is maintained above a specified threshold. + +.. _Table Irrigation parameters: + +.. table:: Irrigation parameters + + +--------------------------------------+-------------+ + | Parameter | | + +======================================+=============+ + | :math:`f_{thresh}` | 1.0 | + +--------------------------------------+-------------+ + | :math:`z_{irrig}` (m) | 0.6 | + +--------------------------------------+-------------+ + | :math:`\Psi_{target}` (mm) | -3400 | + +--------------------------------------+-------------+ + | :math:`\Psi_{wilt}` (mm) | -150000 | + +--------------------------------------+-------------+ + +.. add a reference to surface data in chapter2 + To accomplish this we downloaded + data of percent irrigated and percent rainfed corn, soybean, and + temperate cereals (wheat, barley, and rye) (:ref:`Portmann et al. 2010 `), + available online from + *ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* + + .. _The details about what is new in CLM4.5: @@ -525,7 +567,7 @@ exclusive in CLM4.0. In CLM4.5 we have reversed this situation. Now the irrigation model can be used only while running with CROP. To accomplish this we downloaded data of percent irrigated and percent rainfed corn, soybean, and -temperate cereals (wheat, barley, and rye) (Portmann et al. 2010), +temperate cereals (wheat, barley, and rye) (:ref:`Portmann et al. 2010 `), available online from *ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index ca5fa9f660..70fa76baf7 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -562,8 +562,9 @@ functional type where :math:`z_{h,\, i}` (m) is the depth from the soil surface to the interface between layers :math:`i` and :math:`i+1` (:math:`z_{h,\, 0}` , -the soil surface) (section 6.1), and :math:`r_{a}` and :math:`r_{b}` -are plant-dependent root distribution parameters adopted from :ref:`Zeng (2001) ` +the soil surface) (section :numref:`Vertical Discretization`), and :math:`r_{a}` +and :math:`r_{b}` are plant-dependent root distribution parameters adopted from +:ref:`Zeng (2001) ` (:numref:`Table Plant functional type root distribution parameters`). .. _Table Plant functional type root distribution parameters: diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 3e52821ef7..f884270f62 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -134,6 +134,8 @@ of hydraulic conductivity in porous media. Transport in Porous Media Beven, K.J., and Kirkby, M.J. 1979. A physically based variable contributing area model of basin hydrology. Hydrol. Sci. Bull. 24:43-69. +.. _BohrenHuffman1983: + Bohren, C. F., and Huffman, D. R. 1983. Absorption and scattering of light by small particles. John Wiley & Sons, New York, NY. @@ -1382,7 +1384,7 @@ Pollmer, W.G., Eberhard, D., Klein, D., and Dhillon, B.S. 1979. Genetic control of nitrogen uptake and translocation in maize. Crop Sci. 19:82-86. -.. _Portmann2010: +.. _Portmannetal2010: Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global monthly irrigated and rainfed crop areas around the year 2000: A new @@ -1695,12 +1697,14 @@ Area Parameterization for the Community Land Model and its Effect on the Surface Energy Balance. JGR, 117, D21107. DOI:10.1029/2012JD018178. .. _SwensonLawrence2014: + Swenson, S.C., and D. M. Lawrence. 2014. Assessing a dry surface layer-based soil resistance parameterization for the Community Land Model using GRACE and FLUXNET-MTE data. JGR, 119, 10, 299–10,312, DOI:10.1002/2014JD022314. .. _SwensonLawrence2015: + Swenson, S.C., and D. M. Lawrence. 2015. A GRACE-based assessment of interannual groundwater dynamics in the Community Land Model. WRR, 51, doi:10.1002/2015WR017582. diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 82a25eba77..0cd135e220 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -9,8 +9,8 @@ Canopy Radiative Transfer ----------------------------- Radiative transfer within vegetative canopies is calculated from the -two-stream approximation of Dickinson (1983) and Sellers (1985) as -described by Bonan (1996) +two-stream approximation of :ref:`Dickinson (1983) ` and +:ref:`Sellers (1985) ` as described by :ref:`Bonan (1996) ` .. math:: :label: 3.1 @@ -33,10 +33,10 @@ stem elements in the direction :math:`\cos ^{-1} \mu` , leaf and stem area, :math:`\omega` is a scattering coefficient, :math:`\beta` and :math:`\beta _{0}` are upscatter parameters for diffuse and direct beam radiation, respectively, :math:`L` is the -exposed leaf area index (section 2.1.4), and :math:`S` is the exposed -stem area index (section 2.1.4). Given the direct beam albedo -:math:`\alpha _{g,\, \Lambda }^{\mu }` and diffuse albedo -:math:`\alpha _{g,\, \Lambda }` of the ground (section 3.2), these +exposed leaf area index , and :math:`S` is the exposed stem area index +(section :numref:`Phenology and vegetation burial by snow`). Given the +direct beam albedo :math:`\alpha _{g,\, \Lambda }^{\mu }` and diffuse albedo +:math:`\alpha _{g,\, \Lambda }` of the ground (section :numref:`Ground Albedos`), these equations are solved to calculate the fluxes, per unit incident flux, absorbed by the vegetation, reflected by the vegetation, and transmitted through the vegetation for direct and diffuse radiation and for visible @@ -45,7 +45,7 @@ through the vegetation for direct and diffuse radiation and for visible radiation is partitioned to sunlit and shaded fractions of the canopy. The optical parameters :math:`G\left(\mu \right)`, :math:`\bar{\mu }`, :math:`\omega`, :math:`\beta`, and :math:`\beta _{0}` are calculated -based on work in Sellers (1985) as follows. +based on work in :ref:`Sellers (1985) ` as follows. The relative projected area of leaves and stems in the direction :math:`\cos ^{-1} \mu` is @@ -70,10 +70,12 @@ The average inverse diffuse optical depth per unit leaf and stem area is where :math:`\mu '` is the direction of the scattered flux. -The optical parameters :math:`\omega`, :math:`\beta`, and :math:`\beta _{0}`, which vary with wavelength (:math:`\Lambda` ), are -weighted combinations of values for vegetation and snow. The model determines that snow is on the canopy if :math:`T_{v} \le T_{f}` , where -:math:`T_{v}` is the vegetation temperature (K) (Chapter 5) and :math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). In -this case, the optical parameters are +The optical parameters :math:`\omega`, :math:`\beta`, and :math:`\beta _{0}`, +which vary with wavelength (:math:`\Lambda` ), are weighted combinations of values +for vegetation and snow. The model determines that snow is on the canopy if +:math:`T_{v} \le T_{f}` , where :math:`T_{v}` is the vegetation temperature (K) (Chapter +:numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) and :math:`T_{f}` is the +freezing temperature of water (K) (:numref:`Table Physical Constants`). In this case, the optical parameters are .. math:: :label: 3.5 @@ -90,7 +92,7 @@ this case, the optical parameters are \omega _{\Lambda } \beta _{0,\, \Lambda } =\omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} \beta _{0,\, \Lambda }^{sno} f_{wet} -where :math:`f_{wet}` is the wetted fraction of the canopy (section 7.1). The snow and vegetation weights are applied to the products +where :math:`f_{wet}` is the wetted fraction of the canopy (section :numref:`Canopy Water`). The snow and vegetation weights are applied to the products :math:`\omega _{\Lambda } \beta _{\Lambda }` and :math:`\omega _{\Lambda } \beta _{0,\, \Lambda }` because these products are used in the two-stream equations. If there is no snow on the canopy, @@ -413,12 +415,13 @@ The parameters :math:`h_{1}` –:math:`h_{10}` , :math:`\sigma` , h_{10} =\frac{-s_{1} \left(u_{2} -\bar{\mu }h\right)}{d_{2} } . -Plant functional type optical properties (Table 3.1) for trees and -shrubs are from Dorman and Sellers (1989). Leaf and stem optical +Plant functional type optical properties (:numref:`Table Plant functional type optical properties`) +for trees and shrubs are from :ref:`Dorman and Sellers (1989) `. Leaf and stem optical properties (placeVIS and NIR reflectance and transmittance) were derived for grasslands and crops from full optical range spectra of measured -optical properties (Asner et al. 1998). Optical properties for -intercepted snow (Table 3.2) are from Sellers et al. (1986). +optical properties (:ref:`Asner et al. 1998 `). Optical properties for +intercepted snow (:numref:`Table Intercepted snow optical properties`) are +:ref:`from Sellers et al. (1986) `. .. _Table Plant functional type optical properties: @@ -495,7 +498,8 @@ intercepted snow (Table 3.2) are from Sellers et al. (1986). Ground Albedos ------------------ -The overall direct beam :math:`\alpha _{g,\, \Lambda }^{\mu }` and diffuse :math:`\alpha _{g,\, \Lambda }` ground albedos are weighted +The overall direct beam :math:`\alpha _{g,\, \Lambda }^{\mu }` and diffuse +:math:`\alpha _{g,\, \Lambda }` ground albedos are weighted combinations of “soil†and snow albedos .. math:: @@ -508,11 +512,12 @@ combinations of “soil†and snow albedos \alpha _{g,\, \Lambda } =\alpha _{soi,\, \Lambda } \left(1-f_{sno} \right)+\alpha _{sno,\, \Lambda } f_{sno} -where :math:`f_{sno}` is the fraction of the ground covered with snow (section 7.2.1). +where :math:`f_{sno}` is the fraction of the ground covered with snow +(section :numref:`Snow Covered Area Fraction`). :math:`\alpha _{soi,\, \Lambda }^{\mu }` and :math:`\alpha _{soi,\, \Lambda }` vary with glacier, lake, wetland, and -soil surfaces. Glacier albedos are from Paterson (1994) +soil surfaces. Glacier albedos are from :ref:`Paterson (1994) ` .. math:: \alpha _{soi,\, vis}^{\mu } =\alpha _{soi,\, vis} =0.6 @@ -526,13 +531,13 @@ zenith angle :math:`\mu` \alpha _{soi,\, \Lambda }^{\mu } =\alpha _{soi,\, \Lambda } =0.05\left(\mu +0.15\right)^{-1} . -Frozen lake and wetland albedos are from NCAR LSM (Bonan 1996) +Frozen lake and wetland albedos are from NCAR LSM (:ref:`Bonan 1996 `) .. math:: \alpha _{soi,\, vis}^{\mu } =\alpha _{soi,\, vis} =0.60 .. math:: \alpha _{soi,\, nir}^{\mu } =\alpha _{soi,\, nir} =0.40. -As in NCAR LSM (Bonan 1996), soil albedos vary with color class +As in NCAR LSM (:ref:`Bonan 1996 `), soil albedos vary with color class .. math:: :label: 3.61 @@ -540,18 +545,20 @@ As in NCAR LSM (Bonan 1996), soil albedos vary with color class \alpha _{soi,\, \Lambda }^{\mu } =\alpha _{soi,\, \Lambda } =\left(\alpha _{sat,\, \Lambda } +\Delta \right)\le \alpha _{dry,\, \Lambda } where :math:`\Delta` depends on the volumetric water content of the -first soil layer :math:`\theta _{1}` (section 7.4) as +first soil layer :math:`\theta _{1}` (section :numref:`Soil Water`) as :math:`\Delta =0.11-0.40\theta _{1} >0`, and :math:`\alpha _{sat,\, \Lambda }` and :math:`\alpha _{dry,\, \Lambda }` are albedos for saturated and dry -soil color classes (Table 3.3). +soil color classes (:numref:`Table Dry and saturated soil albedos`). CLM soil colors are prescribed so that they best reproduce observed MODIS local solar noon surface albedo values at the CLM grid cell -following the methods of Lawrence and Chase (2007). The soil colors are -fitted over the range of 20 soil classes shown in Table 3.3 and compared +following the methods of :ref:`Lawrence and Chase (2007) `. +The soil colors are fitted over the range of 20 soil classes shown in +:numref:`Table Dry and saturated soil albedos` and compared to the MODIS monthly local solar noon all-sky surface albedo as -described in Strahler et al. (1999) and Schaaf et al. (2002). The CLM +described in :ref:`Strahler et al. (1999) ` and +:ref:`Schaaf et al. (2002) `. The CLM two-stream radiation model was used to calculate the model equivalent surface albedo using climatological monthly soil moisture along with the vegetation parameters of PFT fraction, LAI, and SAI. The soil color that @@ -563,31 +570,33 @@ snow-free surface albedo for the year, the soil color derived from snow-affected albedo was used to give a representative soil color that included the effects of the minimum permanent snow cover. -Table 3.3. Dry and saturated soil albedos - -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| Color Class | vis | nir | vis | nir | Color Class | vis | nir | vis | nir | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 1 | 0.36 | 0.61 | 0.25 | 0.50 | 11 | 0.24 | 0.37 | 0.13 | 0.26 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 2 | 0.34 | 0.57 | 0.23 | 0.46 | 12 | 0.23 | 0.35 | 0.12 | 0.24 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 3 | 0.32 | 0.53 | 0.21 | 0.42 | 13 | 0.22 | 0.33 | 0.11 | 0.22 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 4 | 0.31 | 0.51 | 0.20 | 0.40 | 14 | 0.20 | 0.31 | 0.10 | 0.20 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 5 | 0.30 | 0.49 | 0.19 | 0.38 | 15 | 0.18 | 0.29 | 0.09 | 0.18 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 6 | 0.29 | 0.48 | 0.18 | 0.36 | 16 | 0.16 | 0.27 | 0.08 | 0.16 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 7 | 0.28 | 0.45 | 0.17 | 0.34 | 17 | 0.14 | 0.25 | 0.07 | 0.14 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 8 | 0.27 | 0.43 | 0.16 | 0.32 | 18 | 0.12 | 0.23 | 0.06 | 0.12 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 9 | 0.26 | 0.41 | 0.15 | 0.30 | 19 | 0.10 | 0.21 | 0.05 | 0.10 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ -| 10 | 0.25 | 0.39 | 0.14 | 0.28 | 20 | 0.08 | 0.16 | 0.04 | 0.08 | -+---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ +.. _Table Dry and saturated soil albedos: + +.. table:: Dry and saturated soil albedos + + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | Color Class | vis | nir | vis | nir | Color Class | vis | nir | vis | nir | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 1 | 0.36 | 0.61 | 0.25 | 0.50 | 11 | 0.24 | 0.37 | 0.13 | 0.26 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 2 | 0.34 | 0.57 | 0.23 | 0.46 | 12 | 0.23 | 0.35 | 0.12 | 0.24 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 3 | 0.32 | 0.53 | 0.21 | 0.42 | 13 | 0.22 | 0.33 | 0.11 | 0.22 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 4 | 0.31 | 0.51 | 0.20 | 0.40 | 14 | 0.20 | 0.31 | 0.10 | 0.20 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 5 | 0.30 | 0.49 | 0.19 | 0.38 | 15 | 0.18 | 0.29 | 0.09 | 0.18 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 6 | 0.29 | 0.48 | 0.18 | 0.36 | 16 | 0.16 | 0.27 | 0.08 | 0.16 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 7 | 0.28 | 0.45 | 0.17 | 0.34 | 17 | 0.14 | 0.25 | 0.07 | 0.14 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 8 | 0.27 | 0.43 | 0.16 | 0.32 | 18 | 0.12 | 0.23 | 0.06 | 0.12 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 9 | 0.26 | 0.41 | 0.15 | 0.30 | 19 | 0.10 | 0.21 | 0.05 | 0.10 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | 10 | 0.25 | 0.39 | 0.14 | 0.28 | 20 | 0.08 | 0.16 | 0.04 | 0.08 | + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ .. _Snow Albedo: @@ -596,16 +605,18 @@ Snow Albedo Snow albedo and solar absorption within each snow layer are simulated with the Snow, Ice, and Aerosol Radiative Model (SNICAR), which -incorporates a two-stream radiative transfer solution from Toon et al. -(1989). Albedo and the vertical absorption profile depend on solar -zenith angle, albedo of the substrate underlying snow, mass +incorporates a two-stream radiative transfer solution from +:ref:`Toon et al. (1989) `. Albedo and the vertical absorption +profile depend on solar zenith angle, albedo of the substrate underlying snow, mass concentrations of atmospheric-deposited aerosols (black carbon, mineral dust, and organic carbon), and ice effective grain size (:math:`r_{e}`), which is simulated with a snow aging routine -described in section 3.2.3. Representation of impurity mass -concentrations within the snowpack is described in section 7.2.4. -Implementation of SNICAR in CLM is also described somewhat by Flanner -and Zender (2005) and Flanner et al. (2007). +described in section :numref:`Snow Aging`. Representation of impurity mass +concentrations within the snowpack is described in section +:numref:`Black and organic carbon and mineral dust within snow`. +Implementation of SNICAR in CLM is also described somewhat by +:ref:`Flanner and Zender (2005) ` and +:ref:`Flanner et al. (2007) `. The two-stream solution requires the following bulk optical properties for each snow layer and spectral band: extinction optical depth @@ -615,7 +626,7 @@ calculations are identical to snow layers applied elsewhere in CLM, except for the case when snow mass is greater than zero but no snow layers exist. When this occurs, a single radiative layer is specified to have the column snow mass and an effective grain size of freshly-fallen -snow (section 3.2.3). The bulk optical properties are weighted functions +snow (section :numref:`Snow Aging`). The bulk optical properties are weighted functions of each constituent *k*, computed for each snow layer and spectral band as @@ -634,39 +645,42 @@ as g=\frac{\sum _{1}^{k}g_{k} \omega _{k} \tau _{k} }{\sum _{1}^{k}\omega _{k} \tau _{k} } -For each constituent (ice, two black carbon species, two organic carbon species, and four dust species), :math:`\omega`, *g*, and -the mass extinction cross-section :math:`\psi` (m\ :sup:`2` kg\ :sub:`-1`) -are computed offline with Mie Theory, e.g., applying the computational technique from Bohren and Huffman (1983). The -extinction optical depth for each constituent depends on its mass extinction cross-section and layer mass, :math:`w _{k}` (kg\ m\ :sup:`-1`) as +For each constituent (ice, two black carbon species, two organic carbon species, and +four dust species), :math:`\omega`, *g*, and the mass extinction cross-section +:math:`\psi` (m\ :sup:`2` kg\ :sub:`-1`) are computed offline with Mie Theory, e.g., +applying the computational technique from :ref:`Bohren and Huffman (1983) `. +The extinction optical depth for each constituent depends on its mass extinction +cross-section and layer mass, :math:`w _{k}` (kg\ m\ :sup:`-1`) as .. math:: :label: 3.65 \tau _{k} =\psi _{k} w_{k} -The two-stream solution (Toon et al. 1989) applies a tri-diagonal matrix +The two-stream solution (:ref:`Toon et al. (1989) `) applies a tri-diagonal matrix solution to produce upward and downward radiative fluxes at each layer interface, from which net radiation, layer absorption, and surface albedo are easily derived. Solar fluxes are computed in five spectral -bands, listed in Table 3.4. Because snow albedo varies strongly across +bands, listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`. +Because snow albedo varies strongly across the solar spectrum, it was determined that four bands were needed to accurately represent the near-infrared (NIR) characteristics of snow, whereas only one band was needed for the visible spectrum. Boundaries of the NIR bands were selected to capture broad radiative features and -maximize accuracy and computational efficiency. We partition NIR -(0.7-5.0 :math:`\mu` m) surface downwelling flux from CLM -according to the weights listed in Table 3.4, which are unique for -diffuse and direct incident flux. These fixed weights were determined -with offline hyperspectral radiative transfer calculations for an -atmosphere typical of mid-latitude winter (Flanner et al. 2007). The -tri-diagonal solution includes intermediate terms that allow for easy +maximize accuracy and computational efficiency. We partition NIR (0.7-5.0 +:math:`\mu` m) surface downwelling flux from CLM according to the weights listed +in :numref:`Table Spectral bands and weights used for snow radiative transfer`, +which are unique for diffuse and direct incident flux. These fixed weights were +determined with offline hyperspectral radiative transfer calculations for an +atmosphere typical of mid-latitude winter (:ref:`Flanner et al. (2007) `). +The tri-diagonal solution includes intermediate terms that allow for easy interchange of two-stream techniques. We apply the Eddington solution -for the visible band (following Wiscombe and Warren 1980) and the -hemispheric mean solution (Toon et al. 1989) for NIR bands. These +for the visible band (following :ref:`Wiscombe and Warren 1980 `) and the +hemispheric mean solution ((:ref:`Toon et al. (1989) `) for NIR bands. These choices were made because the Eddington scheme works well for highly scattering media, but can produce negative albedo for absorptive NIR bands with diffuse incident flux. Delta scalings are applied to -:math:`\tau`, :math:`\omega`, and :math:`g` (Wiscombe and Warren 1980) in +:math:`\tau`, :math:`\omega`, and :math:`g` (:ref:`Wiscombe and Warren 1980 `) in all spectral bands, producing effective values (denoted with \*) that are applied in the two-stream solution @@ -685,21 +699,23 @@ are applied in the two-stream solution g^{*} =\frac{g}{1+g} -Table 3.4. Spectral bands and weights used for snow radiative transfer - -+---------------------------------------------------------+----------------------+------------------+ -| Spectral band | Direct-beam weight | Diffuse weight | -+=========================================================+======================+==================+ -| Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | | | -+---------------------------------------------------------+----------------------+------------------+ -| Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | -+---------------------------------------------------------+----------------------+------------------+ -| Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.181 | 0.202 | -+---------------------------------------------------------+----------------------+------------------+ -| Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.121 | 0.109 | -+---------------------------------------------------------+----------------------+------------------+ -| Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.204 | 0.103 | -+---------------------------------------------------------+----------------------+------------------+ +.. _Table Spectral bands and weights used for snow radiative transfer: + +.. table:: Spectral bands and weights used for snow radiative transfer + + +---------------------------------------------------------+----------------------+------------------+ + | Spectral band | Direct-beam weight | Diffuse weight | + +=========================================================+======================+==================+ + | Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | | | + +---------------------------------------------------------+----------------------+------------------+ + | Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | + +---------------------------------------------------------+----------------------+------------------+ + | Band 3: 1.0-1.2\ :math:`\mu`\ m (near-IR) | 0.181 | 0.202 | + +---------------------------------------------------------+----------------------+------------------+ + | Band 4: 1.2-1.5\ :math:`\mu`\ m (near-IR) | 0.121 | 0.109 | + +---------------------------------------------------------+----------------------+------------------+ + | Band 5: 1.5-5.0\ :math:`\mu`\ m (near-IR) | 0.204 | 0.103 | + +---------------------------------------------------------+----------------------+------------------+ Under direct-beam conditions, singularities in the radiative approximation are occasionally approached in spectral bands 4 and 5 that @@ -743,7 +759,8 @@ absorption fluxes that are used for column temperature calculations are This weighting is performed for direct-beam and diffuse, visible and NIR fluxes. After the ground-incident fluxes (transmitted through the vegetation canopy) have been calculated for the current time step -(sections 3.1 and 4.1), the layer absorption factors +(sections :numref:`Canopy Radiative Transfer` and :numref:`Solar Fluxes`), +the layer absorption factors (:math:`S_{g,\, i}`) are multiplied by the ground-incident fluxes to produce solar absorption (W m\ :sup:`-2`) in each snow layer and @@ -779,98 +796,107 @@ weighted by the diffuse albedo for a semi-infinite snowpack (:math:`\alpha _{sno Inclusion of this additional albedo weight was found to improve accuracy of the five-band albedo solutions (relative to 470-band solutions) because of the strong dependence of optically-thick snowpack albedo on -ice grain single-scatter albedo (Flanner et al. 2007). The lookup tables -contain optical properties for lognormal distributions of ice particles -over the range of effective radii: 30\ :math:`\mu`\ m -:math:`< r _{e} < \text{1500} \mu \text{m}`, at 1 :math:`\mu` m resolution. Single-scatter albedos for the end-members of this size -range are listed in Table 3.5. - -Optical properties for black carbon are described in Flanner et al. -(2007). Single-scatter albedo, mass extinction cross-section, and +ice grain single-scatter albedo (:ref:`Flanner et al. (2007) `). +The lookup tables contain optical properties for lognormal distributions of ice +particles over the range of effective radii: 30\ :math:`\mu`\ m +:math:`< r _{e} < \text{1500} \mu \text{m}`, at 1 :math:`\mu` m resolution. +Single-scatter albedos for the end-members of this size range are listed in +:numref:`Table Single-scatter albedo values used for snowpack impurities and ice`. + +Optical properties for black carbon are described in :ref:`Flanner et al. (2007) `. +Single-scatter albedo, mass extinction cross-section, and asymmetry parameter values for all snowpack species, in the five -spectral bands used, are listed in Tables 3.5, 3.6, and 3.7. These -properties were also derived with Mie Theory, using various published +spectral bands used, are listed in :numref:`Table Single-scatter albedo values used for snowpack impurities and ice`, +:numref:`Table Mass extinction values`, and +:numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice`. +These properties were also derived with Mie Theory, using various published sources of indices of refraction and assumptions about particle size distribution. Weighting into the five CLM spectral bands was determined only with incident solar flux, as in equation . -Table 3.5. Single-scatter albedo values used for snowpack impurities and ice - -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | -+================================================================+==========+==========+==========+==========+==========+ -| Hydrophilic black carbon | 0.516 | 0.434 | 0.346 | 0.276 | 0.139 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophobic black carbon | 0.288 | 0.187 | 0.123 | 0.089 | 0.040 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophilic organic carbon | 0.997 | 0.994 | 0.990 | 0.987 | 0.951 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophobic organic carbon | 0.963 | 0.921 | 0.860 | 0.814 | 0.744 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 1 | 0.979 | 0.994 | 0.993 | 0.993 | 0.953 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 2 | 0.944 | 0.984 | 0.989 | 0.992 | 0.983 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 3 | 0.904 | 0.965 | 0.969 | 0.973 | 0.978 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 4 | 0.850 | 0.940 | 0.948 | 0.953 | 0.955 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 0.9999 | 0.9999 | 0.9992 | 0.9938 | 0.9413 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 0.9998 | 0.9960 | 0.9680 | 0.8730 | 0.5500 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ - -Table 3.6. Mass extinction values (m\ :sup:`2` kg\ :sub:`-1`) used for snowpack impurities and ice. - -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | -+================================================================+==========+==========+==========+==========+==========+ -| Hydrophilic black carbon | 25369 | 12520 | 7739 | 5744 | 3527 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophobic black carbon | 11398 | 5923 | 4040 | 3262 | 2224 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophilic organic carbon | 37774 | 22112 | 14719 | 10940 | 5441 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophobic organic carbon | 3289 | 1486 | 872 | 606 | 248 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 1 | 2687 | 2420 | 1628 | 1138 | 466 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 2 | 841 | 987 | 1184 | 1267 | 993 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 3 | 388 | 419 | 400 | 397 | 503 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 4 | 197 | 203 | 208 | 205 | 229 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 55.7 | 56.1 | 56.3 | 56.6 | 57.3 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 1.09 | 1.09 | 1.09 | 1.09 | 1.1 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ - -Table 3.7. Asymmetry scattering parameters used for snowpack impurities and ice. - -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | -+================================================================+==========+==========+==========+==========+==========+ -| Hydrophilic black carbon | 0.52 | 0.34 | 0.24 | 0.19 | 0.10 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophobic black carbon | 0.35 | 0.21 | 0.15 | 0.11 | 0.06 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophilic organic carbon | 0.77 | 0.75 | 0.72 | 0.70 | 0.64 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Hydrophobic organic carbon | 0.62 | 0.57 | 0.54 | 0.51 | 0.44 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 1 | 0.69 | 0.72 | 0.67 | 0.61 | 0.44 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 2 | 0.70 | 0.65 | 0.70 | 0.72 | 0.70 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 3 | 0.79 | 0.75 | 0.68 | 0.63 | 0.67 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Dust 4 | 0.83 | 0.79 | 0.77 | 0.76 | 0.73 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Ice (:math:`r _{e}` = 30\ :math:`\mu`\ m) | 0.88 | 0.88 | 0.88 | 0.88 | 0.90 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ -| Ice (:math:`r _{e}` = 1500\ :math:`\mu`\ m) | 0.89 | 0.90 | 0.90 | 0.92 | 0.97 | -+----------------------------------------------------------------+----------+----------+----------+----------+----------+ +.. _Table Single-scatter albedo values used for snowpack impurities and ice: + +.. table:: Single-scatter albedo values used for snowpack impurities and ice + + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | + +================================================================+==========+==========+==========+==========+==========+ + | Hydrophilic black carbon | 0.516 | 0.434 | 0.346 | 0.276 | 0.139 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophobic black carbon | 0.288 | 0.187 | 0.123 | 0.089 | 0.040 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophilic organic carbon | 0.997 | 0.994 | 0.990 | 0.987 | 0.951 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophobic organic carbon | 0.963 | 0.921 | 0.860 | 0.814 | 0.744 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 1 | 0.979 | 0.994 | 0.993 | 0.993 | 0.953 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 2 | 0.944 | 0.984 | 0.989 | 0.992 | 0.983 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 3 | 0.904 | 0.965 | 0.969 | 0.973 | 0.978 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 4 | 0.850 | 0.940 | 0.948 | 0.953 | 0.955 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 0.9999 | 0.9999 | 0.9992 | 0.9938 | 0.9413 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 0.9998 | 0.9960 | 0.9680 | 0.8730 | 0.5500 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + +.. _Table Mass extinction values: + +.. table:: Mass extinction values (m\ :sup:`2` kg\ :sub:`-1`) used for snowpack impurities and ice + + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | + +================================================================+==========+==========+==========+==========+==========+ + | Hydrophilic black carbon | 25369 | 12520 | 7739 | 5744 | 3527 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophobic black carbon | 11398 | 5923 | 4040 | 3262 | 2224 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophilic organic carbon | 37774 | 22112 | 14719 | 10940 | 5441 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophobic organic carbon | 3289 | 1486 | 872 | 606 | 248 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 1 | 2687 | 2420 | 1628 | 1138 | 466 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 2 | 841 | 987 | 1184 | 1267 | 993 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 3 | 388 | 419 | 400 | 397 | 503 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 4 | 197 | 203 | 208 | 205 | 229 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Ice (:math:`r _{e}` = 30 :math:`\mu` m) | 55.7 | 56.1 | 56.3 | 56.6 | 57.3 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Ice (:math:`r _{e}` = 1500 :math:`\mu` m) | 1.09 | 1.09 | 1.09 | 1.09 | 1.1 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + +.. _Table Asymmetry scattering parameters used for snowpack impurities and ice: + +.. table:: Asymmetry scattering parameters used for snowpack impurities and ice. + + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | + +================================================================+==========+==========+==========+==========+==========+ + | Hydrophilic black carbon | 0.52 | 0.34 | 0.24 | 0.19 | 0.10 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophobic black carbon | 0.35 | 0.21 | 0.15 | 0.11 | 0.06 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophilic organic carbon | 0.77 | 0.75 | 0.72 | 0.70 | 0.64 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Hydrophobic organic carbon | 0.62 | 0.57 | 0.54 | 0.51 | 0.44 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 1 | 0.69 | 0.72 | 0.67 | 0.61 | 0.44 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 2 | 0.70 | 0.65 | 0.70 | 0.72 | 0.70 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 3 | 0.79 | 0.75 | 0.68 | 0.63 | 0.67 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Dust 4 | 0.83 | 0.79 | 0.77 | 0.76 | 0.73 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Ice (:math:`r _{e}` = 30\ :math:`\mu`\ m) | 0.88 | 0.88 | 0.88 | 0.88 | 0.90 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ + | Ice (:math:`r _{e}` = 1500\ :math:`\mu`\ m) | 0.89 | 0.90 | 0.90 | 0.92 | 0.97 | + +----------------------------------------------------------------+----------+----------+----------+----------+----------+ .. _Snow Aging: @@ -881,9 +907,9 @@ Snow aging is represented as evolution of the ice effective grain size (:math:`r_{e}`). Previous studies have shown that use of spheres which conserve the surface area-to-volume ratio (or specific surface area) of ice media composed of more complex shapes produces relatively -small errors in simulated hemispheric fluxes (e.g., Grenfell and Warren -1999). Effective radius is the surface area-weighted mean radius of an -ensemble of spherical particles and is directly related to specific +small errors in simulated hemispheric fluxes (e.g., :ref:`Grenfell and Warren +1999 `). Effective radius is the surface area-weighted mean +radius of an ensemble of spherical particles and is directly related to specific surface area (*SSA*) as :math:`r_{e} ={3\mathord{\left/ {\vphantom {3 \left(\rho _{ice} SSA\right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{ice} SSA\right)}` , where :math:`\rho_{ice}` is the density of ice. Hence, @@ -892,7 +918,7 @@ snowpack microphysical state to dry snow radiative characteristics. Wet snow processes can also drive rapid changes in albedo. The presence of liquid water induces rapid coarsening of the surrounding ice grains -(e.g., Brun 1989), and liquid water tends to refreeze into large ice +(e.g., :ref:`Brun 1989 `), and liquid water tends to refreeze into large ice clumps that darken the bulk snowpack. The presence of small liquid drops, by itself, does not significantly darken snowpack, as ice and water have very similar indices of refraction throughout the solar @@ -920,9 +946,9 @@ Here, the effective radius of freshly-fallen snow (:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sub:`-1`), and the effective radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. -Dry snow aging is based on a microphysical model described by Flanner -and Zender (2006). This model simulates diffusive vapor flux amongst -collections of ice crystals with various size and inter-particle +Dry snow aging is based on a microphysical model described by :ref:`Flanner +and Zender (2006) `. This model simulates diffusive vapor flux +amongst collections of ice crystals with various size and inter-particle spacing. Specific surface area and effective radius are prognosed for any combination of snow temperature, temperature gradient, density, and initial size distribution. The combination of warm snow, large @@ -960,7 +986,7 @@ top soil layer, and for the top snow layer it is assumed that :math:`T_{n-1}` = :math:`T_{n}`. The contribution of liquid water to enhanced metamorphism is based on -parametric equations published by Brun (1989), who measured grain +parametric equations published by :ref:`Brun (1989) `, who measured grain growth rates under different liquid water contents. This relationship, expressed in terms of :math:`r_{e} (\mu \text{m})` and subtracting an offset due to dry aging, depends on the mass liquid water @@ -972,16 +998,18 @@ fraction :math:`f_{liq}` as \frac{dr_{e} }{dt} =\frac{10^{18} C_{1} f_{liq} ^{3} }{4\pi r_{e} ^{2} } The constant *C*\ :sub:`1` is 4.22\ :math:`\times`\ 10\ :sup:`-13`, and: -:math:`f_{liq} =w_{liq} /(w_{liq} +w_{ice} )`\ (section 7.2). +:math:`f_{liq} =w_{liq} /(w_{liq} +w_{ice} )`\ (Chapter :numref:`rst_Snow Hydrology`). In cases where snow mass is greater than zero, but a snow layer has not yet been defined, :math:`r_{e}` is set to :math:`r_{e,0}`. When snow layers are combined or divided, :math:`r_{e}` is calculated as a mass-weighted mean of the two layers, following computations of other state variables (section -7.2.7). Finally, the allowable range of :math:`r_{e}`, +:numref:`Snow Layer Combination and Subdivision`). Finally, the allowable range of :math:`r_{e}`, corresponding to the range over which Mie optical properties have been defined, is 30-1500\ :math:`\mu` m. +.. _Solar Zenith Angle: + Solar Zenith Angle ---------------------- @@ -1008,8 +1036,8 @@ where :math:`d` is calendar day (:math:`d=0.0` at 0Z on January 1), and :math:`\theta` is longitude (radians) (positive east of the CityplaceGreenwich meridian). -The solar declination angle :math:`\delta` is calculated as in Berger -(1978a,b) and is valid for one million years past or hence, relative to +The solar declination angle :math:`\delta` is calculated as in :ref:`Berger +(1978a,b) ` and is valid for one million years past or hence, relative to 1950 A.D. The orbital parameters may be specified directly or the orbital parameters are calculated for the desired year. The required orbital parameters to be input by the user are the obliquity of the @@ -1018,7 +1046,7 @@ Earth :math:`\varepsilon` (degrees, :math:`e` (:math:`0.0`)). The solar declination :math:`\delta` (radians) is .. math:: @@ -1036,10 +1064,10 @@ The obliquity of the Earth :math:`\varepsilon` (degrees) is \varepsilon =\varepsilon *+\sum _{i=1}^{i=47}A_{i} \cos \left(f_{i} t+\delta _{i} \right) -where :math:`\varepsilon *` is a constant of integration (Table 3.8), +where :math:`\varepsilon *` is a constant of integration (:numref:`Table Orbital parameters`), :math:`A_{i}` , :math:`f_{i}` , and :math:`\delta _{i}` are amplitude, -mean rate, and phase terms in the cosine series expansion (Berger -1978a,b), and :math:`t=t_{0} -1950` where :math:`t_{0}` is the year. +mean rate, and phase terms in the cosine series expansion (:ref:`Berger +(1978a,b) `, and :math:`t=t_{0} -1950` where :math:`t_{0}` is the year. The series expansion terms are not shown here but can be found in the source code file shr\_orb\_mod.F90. @@ -1087,7 +1115,7 @@ where are the cosine and sine series expansions for :math:`e`, and :math:`M_{j}` , :math:`g_{j}` , and :math:`B_{j}` are amplitude, mean -rate, and phase terms in the series expansions (Berger 1978a,b). The +rate, and phase terms in the series expansions (:ref:`Berger (1978a,b) `). The longitude of the perihelion relative to the moving vernal equinox :math:`\tilde{\omega }` (degrees) is @@ -1110,9 +1138,9 @@ orbit relative to the fixed stars. The general precession :math:`\psi` \psi =\frac{\tilde{\psi }t}{3600} +\zeta +\sum _{i=1}^{78}F_{i} \sin \left(f_{i} ^{{'} } t+\delta _{i} ^{{'} } \right) where :math:`\tilde{\psi }` (arcseconds) and :math:`\zeta` (degrees) -are constants (Table 3.8), and :math:`F_{i}` , :math:`f_{i} ^{{'} }` , +are constants (:numref:`Table Orbital parameters`), and :math:`F_{i}` , :math:`f_{i} ^{{'} }` , and :math:`\delta _{i} ^{{'} }` are amplitude, mean rate, and phase -terms in the sine series expansion (Berger 1978a,b). The longitude of +terms in the sine series expansion (:ref:`Berger (1978a,b) `)). The longitude of the perihelion :math:`\Pi` (radians) depends on the sine and cosine series expansions for the eccentricity :math:`e`\ as follows: @@ -1125,16 +1153,18 @@ The numerical solution for the longitude of the perihelion :math:`\tilde{\omega }` is constrained to be between 0 and 360 degrees (measured from the autumn equinox). A constant 180 degrees is then added to :math:`\tilde{\omega }` because the Sun is considered as revolving -around the Earth (geocentric coordinate system) (Berger et al. 1993). - -Table 3.8. Orbital parameters - -+--------------------------------------+-------------+ -| Parameter | | -+======================================+=============+ -| :math:`\varepsilon *` | 23.320556 | -+--------------------------------------+-------------+ -| :math:`\tilde{\psi }` (arcseconds) | 50.439273 | -+--------------------------------------+-------------+ -| :math:`\zeta` (degrees) | 3.392506 | -+--------------------------------------+-------------+ +around the Earth (geocentric coordinate system) (:ref:`Berger et al. 1993 `)). + +.. _Table Orbital parameters: + +.. table:: Orbital parameters + + +--------------------------------------+-------------+ + | Parameter | | + +======================================+=============+ + | :math:`\varepsilon *` | 23.320556 | + +--------------------------------------+-------------+ + | :math:`\tilde{\psi }` (arcseconds) | 50.439273 | + +--------------------------------------+-------------+ + | :math:`\zeta` (degrees) | 3.392506 | + +--------------------------------------+-------------+ From 76f93f7ff0c06d7c98ea478d8d3989c3ac777c5b Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Wed, 24 May 2017 12:12:18 -0600 Subject: [PATCH 018/255] Updated Crop chapter summary and added CLM4.5 tech note reference --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 39 ++++++++++++------- .../References/CLM50_Tech_Note_References.rst | 4 ++ 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 80cd1e3527..aa2e130e68 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -3,32 +3,43 @@ Crops and Irrigation ======================== -Summary of CLM4.5 updates relative to the CLM4.0 +Summary of CLM5.0 updates relative to the CLM4.5 ----------------------------------------------------- We describe here the complete crop and irrigation parameterizations that -appear in CLM4.5. Corresponding information for CLM4.0 appeared on the -CLM4.0 web site in a pdf document independent of the CLM4.0 Technical +appear in CLM5.0. Corresponding information for CLM4.5 appeared on the +CLM4.5 web site in a pdf document independent of the CLM4.5 Technical Note (Oleson et al. 2010a). The CLM4.0 crop model description also appeared in Levis et al. (2012). -CLM4.5 includes the following updates to the CROP option, where CROP -refers to the interactive crop management model: +CLM5.0 includes the following updates to the CROP option, where CROP +refers to the interactive crop management model and is included by default with the BGC configuration: -- Interactive irrigation +- New crop functional types -- Interactive fertilization +- All crop areas are actively managed -- Biological nitrogen fixation for soybeans +- Fertilization rates updated based on crop type and geographic region -- Modified C:N ratios for crops +- Irrigation updates -- Nitrogen retranslocation for crops +- Phenological triggers vary by latitude for some crop types -- Separate reproductive pool +- Ability to simulate transient crop management -These updates appear in detail in section 20.4. Most also appear in -Drewniak et al. (2013). +- Adjustments to allocation and phenological parameters + +- Crops reaching their maximum LAI triggers the grain fill phase + +- Grain C and N pools are included in a 1-year product pool + +- C for annual crop seeding comes from the grain C pool + +- Initial seed C for planting is increased from 1 to 3 g C/m^2 + + +These updates appear in detail in the sections below. Many also appear in +Levis et al. (2016). The crop model ------------------- @@ -55,7 +66,7 @@ management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, Oleson et al. (2004)] (not published), then coupled to the CLM3.5 (Levis et al. 2009) and later released to the community with -CLM4CN (Levis et al. 2012). +CLM4CN (Levis et al. 2012) and CLM4.5. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM’s diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index b953d98b3d..a7c59328dd 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -886,6 +886,10 @@ Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Kluzek, E. Community Land Model (CLMU). NCAR Technical Note NCAR/TN-480+STR, National Center for Atmospheric Research, Boulder, CO, 169 pp. +Oleson, K.W., et al. 2013. Technical description of version 4.5 of the +Community Land Model (CLM). NCAR Technical Note NCAR/TN-503+STR, +National Center for Atmospheric Research, Boulder, CO, 420 pp. + Olson, J.S., 1963. Energy storage and the balance of producers and decomposers in ecological systems. Ecology 44:322-331. From 9255276dd7f087458921c1cb663818e39dc58f74 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 24 May 2017 13:56:30 -0600 Subject: [PATCH 019/255] update irrigation --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 449341c0f9..ef249b0ee0 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -273,14 +273,14 @@ phase 3. Other allocation coefficients change to: .. math:: :label: ZEqnNum833921 - \begin{array}{l} - {a_{leaf} =a_{leaf}^{i,3} {\rm \; \; \; when\; \; \; }a_{leaf}^{i,3} \le a_{leaf}^{f} {\rm \; \; \; else...}} \\ - {a_{leaf} =a_{leaf} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} {\rm \; \; \; where\; \; \; }\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \le 1} \\ - {} \\ - {a_{livestem} =a_{livestem}^{i,3} {\rm \; \; \; when\; \; \; }a_{livestem}^{i,3} \le a_{livestem}^{f} {\rm \; \; \; else...}} \\ - {a_{livestem} =a_{livestem} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} {\rm \; \; \; where\; \; \; }\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \le 1} \\ - {} \\ - {a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} } + \begin{array}{lr} + a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le a_{leaf}^{f} \quad {\rm else} \\ + a_{leaf} =a_{leaf} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \le 1 \\ + \\ + a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le a_{livestem}^{f} \quad {\rm else} \\ + a_{livestem} =a_{livestem} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \le 1 \\ + \\ + a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} \end{array} where :math:`a_{leaf}^{i,3}` and :math:`a_{livestem}^{i,3}` (initial From c5821ded00e5980d12937106ee4b0814df4dca08 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Wed, 24 May 2017 16:22:26 -0600 Subject: [PATCH 020/255] Add html files back in, and make a few changes to getting-help for Users Guide --- doc/source/users_guide/overview/getting-help.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index fb5069226b..8d45c71bcb 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -3,13 +3,13 @@ ============== Getting Help ============== -In addition to this users-guide there are several other resources that are available to help you use CLM4.5. The first one is the CESM1.2.0 User's-Guide, which documents the entire process of creating cases with CESM1.2.0. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in CESM1.2.0. +In addition to this users-guide there are several other resources that are available to help you use CLM5.0. The first one is the CESM1.2.0 User's-Guide, which documents the entire process of creating cases with CESM1.2.0. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in CESM1.2.0. --------------------------- The CESM User's-Guide --------------------------- -CLM4.5 in CESM1.2.0 is always run from within the standard CESM1.2.0 build and run scripts. Therefore, the user of CLM4.5 should familiarize themselves with the CESM1.2.0 scripts and understand how to work with them. User's-Guide documentation on the CESM1.2.0 scripts are available from the following web-page. The purpose of this CLM4.5 in CESM1.2.0 User's Guide is to give the CLM4.5 user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the CESM1.2.0 Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. +CLM5.0 in CESM2.0 is always run from within the standard CESM2.0 build and run scripts. Therefore, the user of CLM4.5 should familiarize themselves with the CESM1.2.0 scripts and understand how to work with them. User's-Guide documentation on the CESM1.2.0 scripts are available from the following web-page. The purpose of this CLM4.5 in CESM1.2.0 User's Guide is to give the CLM4.5 user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the CESM1.2.0 Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. `cesmrel; Scripts User's-Guide (http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/usersguide/book1.html) `_ From 804853929eebc035575551ddd98a369126f9d7c7 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Wed, 24 May 2017 16:51:39 -0600 Subject: [PATCH 021/255] More update to clm50 in users guide --- doc/source/users_guide/overview/introduction.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 37eb0cb82d..de8dcc25fa 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -4,21 +4,21 @@ Introduction ============== -The Community Land Model (CLM4.5 in CESM1.2.0) is the latest in a +The Community Land Model (CLM5.0 in CESM2.0) is the latest in a series of global land models developed by t he CESM Land Model Working Group (LMWG) and maintained at the National Center for Atmospheric Research (NCAR). This guide is intended to instruct both the novice and experienced user on running CLM. This guide pertains to the latest -version CLM4.5 in CESM1.2.0 available for download from the public +version CLM5.0 in CESM2.0 available for download from the public release subversion repository as a part of CESM1.2.0. Documentation may be different if you are using an older version, you should either use the documentation for that release version, update to the latest version, or use the documentation inside your own source tree. There is information in the ChangeLog file and in the `What is new with -CLM4.5 in CESM1.2.0 since previous public releases? `_ +CLM5.0 in CESM2.0 since previous public releases? `_ regarding the changes from previous versions of CESM. -.. note:: This release of CLM4.5 in CESM1.2.0 includes BOTH CLM4.0 +.. note:: This release of CLM5.0 in CESM1.2.0 includes BOTH CLM4.0 physics used in previous releases as well as the updated CLM4.5 physics. Both CLM as well as CLM support tools allow you to trigger between the two physics modes. Most often when we refer to CLM4.0 we From aa96a511b92f111f5b835f8c03010707459898d8 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Thu, 25 May 2017 16:55:33 -0600 Subject: [PATCH 022/255] Updated references, added reference links & updated text in Crop chapter, added Vcmax text to Photosynthetic Capacity chapter for Chonggang to edit --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 66 +++++----- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 120 ++++++++++++++++++ .../References/CLM50_Tech_Note_References.rst | 12 ++ 3 files changed, 164 insertions(+), 34 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index b8791663a2..98c5ddcea3 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -11,8 +11,7 @@ Summary of CLM5.0 updates relative to the CLM4.5 We describe here the complete crop and irrigation parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared on the CLM4.5 web site in a pdf document independent of the CLM4.5 Technical -Note (Oleson et al. 2010a). The CLM4.0 crop model description also -appeared in Levis et al. (2012). +Note (:ref:`Oleson et al. 2013 `). CLM5.0 includes the following updates to the CROP option, where CROP refers to the interactive crop management model and is included by default with the BGC configuration: @@ -23,7 +22,7 @@ refers to the interactive crop management model and is included by default with - Fertilization rates updated based on crop type and geographic region -- Irrigation updates +- New Irrigation triggers - Phenological triggers vary by latitude for some crop types @@ -41,7 +40,7 @@ refers to the interactive crop management model and is included by default with These updates appear in detail in the sections below. Many also appear in -Levis et al. (2016). +Levis et al. (:ref:`2016 `). .. _The crop model: @@ -64,13 +63,14 @@ biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. AgroIBIS is a state-of-the-art land surface model with options to -simulate dynamic vegetation (Kucharik et al. 2000) and interactive -crop management (Kucharik and Brye 2003). The interactive crop +simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive +crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 -[CLM3.0, Oleson et al. (2004)] (not published), then coupled to the -CLM3.5 (Levis et al. 2009) and later released to the community with -CLM4CN (Levis et al. 2012) and CLM4.5. +[CLM3.0, :ref:`Oleson et al. (2004) `] (not published), then coupled to the +CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with +CLM4CN (:ref:`Levis et al. 2012 `), with additional updates +available by request after the release of CLM4.5 (:ref:`Levis et al. 2016 `). With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM’s @@ -78,39 +78,37 @@ simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land -use, and land management change (e.g., Kucharik and Brye 2003; Lobell et al. 2006). +use, and land management change (e.g., :ref:`Kucharik and Brye 2003 ; Lobell et al. 2006 `). .. _Crop plant functional types: Crop plant functional types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To allow crops to coexist with natural vegetation in a grid cell, the +vegetated land unit is separated into a naturally vegetated land unit and +a managed crop land unit. Unlike the plant functional types (pfts) in the +naturally vegetated land unit, the managed crop pfts in the managed crop +land unit do not share soil columns and thus permit for differences in the +land management between crops. Crop grid cell coverage is assigned from +satellite data (similar to all natural pfts), and the managed crop type +proportions within the crop area is based on the dataset created by +(:ref:`Portmann et al. 2010 `) for present day and +extrapolated through time using the LUMIP data (insert citation). Each +actively managed crop type has a rainfed and an irrigated pft that are on +independent soil columns. Actively managed crop types (Table XX) are chosen +based on the availability of corresponding algorithms in AgroIBIS and as +developed by Badger and Dirmeyer (:ref:`2015 `) and +described by Levis et al. (:ref:`2016 `). A parameterization +for winter cereals is developed but is not included in CLM5.0 due to the +inability to distinguish between winter and summer cereals in the LUMIP dataset (insert citation). + CLM’s default list of plant functional types (pfts) includes an -unmanaged crop (Table 2.1) treated as a second C3 grass. The unmanaged +unmanaged crop (Table 2.1) treated as a second C3 grass, as well as several +additional crop types that do not have associated parameters. The unmanaged crop has grid cell coverage assigned from satellite data, as do all -natural pfts when CLM’s dynamic vegetation model (CNDV; Castillo et al. 2012) is not active. - -The new crop pfts used in the CLM get grid cell coverage from the -present-day crop dataset of Portmann et al. (2010). We assign these -managed crops in the proportions given by Portmann et al. (2010) without -exceeding the area previously assigned to the unmanaged crop. The -unmanaged crop continues to occupy any of its original area that remains -and continues to be handled just by the carbon/nitrogen cycling part of -the CLM (i.e., CN). The managed crop types (corn, soybean, and temperate -cereals) were chosen based on the availability of corresponding -algorithms in AgroIBIS. Temperate cereals include wheat, barley, and rye -here. We treat all temperate cereals as summer crops (like spring wheat, -for example) at this time. We may introduce winter cereals (such as -winter wheat) in a future version of the model. - -To allow crops to coexist with natural vegetation in a grid cell and be -treated by separate models (i.e., CLM4.5CNcrop versus CLM4.5CNDV), we -separate the vegetated land unit into a naturally vegetated land unit -and a human managed land unit. Plant functional types in the naturally -vegetated land unit share one soil column and compete for water (default -CLM setting). Managed crop PFTs in the human managed land unit do not -share soil columns and thus permit for differences in land management -between crops. +natural pfts when CLM’s crop model is not active. [include remapping text here]. + .. _Phenology: diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index c294531b44..803964c6df 100644 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -2,3 +2,123 @@ Photosynthetic Capacity ======================= + +.. _V\ :sub:`cmax25` and Canopy scaling: + +V\ :sub:`cmax25` and Canopy scaling +-------------------------------------------- + +The maximum rate of carboxylation at 25 :sup:`o`\ C varies with +foliage nitrogen concentration and specific leaf area and is calculated +as in Thornton and Zimmermann (2007). At 25ºC, + +.. math:: + :label: ZEqnNum217783 + + V_{c\max 25} =N_{a} F_{LNR} F_{NR} a_{R25} + +where :math:`N_{a}` is the area-based leaf nitrogen concentration (g N +m\ :sup:`-2` leaf area), :math:`F_{LNR}` is the fraction of leaf +nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N), +:math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass +to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and +:math:`a_{R25} =60` is the specific activity of Rubisco (µmol +CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`). +:math:`N_{a}` is calculated from mass-based leaf N concentration and +specific leaf area + +.. math:: + :label: ZEqnNum561340 + + N_{a} =\frac{1}{CN_{L} \; SLA_{0} } + +where :math:`CN_{L}` is the leaf carbon-to-nitrogen ratio (g C +g\ :sup:`-1` N) and :math:`SLA_{0}` is specific leaf area at the +canopy top ( m\ :sup:`2` leaf area g\ :sup:`-1` C ). Table 8.1 +lists values of :math:`F_{LNR}` , :math:`CN_{L}` , and :math:`SLA_{0}` +for each plant functional type. :math:`F_{LNR}` was chosen to give +:math:`V_{c\max 25}` consistent with Kattge et al. (2009), as discussed +by Bonan et al. (2011, 2012). Table 8.1 lists derived values for +:math:`V_{c\max 25}` at the top of the canopy using :math:`SLA_{0}` . +Tropical broadleaf evergreen trees are an exception, and a higher +:math:`V_{c\max 25}` is used to alleviate model biases (Bonan et al. +2012). + +:math:`V_{c\max 25}` is calculated separately for sunlit and shaded +leaves using an exponential profile to area-based leaf nitrogen +(:math:`N_{a}` ), as in Bonan et al. (2011). :math:`V_{c\max 25}` at +cumulative leaf area index :math:`x` from the canopy top scales directly +with :math:`N_{a}` , which decreases exponentially with greater +cumulative leaf area, so that + +.. math:: + :label: ZEqnNum745439 + + V_{c\; \max 25}^{} \left(x\right)=V_{c\; \max 25}^{} \left(0\right)e^{-K_{n} x} + +where :math:`V_{c\; \max 25}^{} \left(0\right)` is defined at the top of +the canopy using :math:`SLA_{0}` , and :math:`K_{n}` is the decay +coefficient for nitrogen. The canopy integrated value for sunlit and +shaded leaves is + +.. math:: + :label: 9.20) + + \begin{array}{rcl} {V_{c\; \max 25}^{sun} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)f_{sun} \left(x\right)\, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} } \end{array} + +.. math:: + :label: 9.21) + + \begin{array}{rcl} {V_{c\; \max 25}^{sha} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)\left[1-f_{sun} \left(x\right)\right] \, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left\{\left[1-e^{-K_{n} L} \right]\frac{1}{K_{n} } -\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} \right\}} \end{array} + +and the average value for the sunlit and shaded leaves is + +.. math:: + :label: 9.22) + + \bar{V}_{c\; \max 25}^{sun} ={V_{c\; \max 25}^{sun} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sun} L^{sun} }} \right. \kern-\nulldelimiterspace} L^{sun} } + +.. math:: + :label: 9.23) + + \bar{V}_{c\; \max 25}^{sha} ={V_{c\; \max 25}^{sha} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sha} L^{sha} }} \right. \kern-\nulldelimiterspace} L^{sha} } . + +This integration is over all leaf area (:math:`L`) with +:math:`f_{sun} (x)=\exp \left(-Kx\right)` and :math:`K` the direct beam +extinction coefficient (equation 4.9). Photosynthetic parameters +:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}` , and +:math:`R_{d25}` scale similarly. + +The value :math:`K_{n} = 0.11` chosen by Bonan et al. (2011) is +consistent with observationally-derived estimates for forests, mostly +tropical, and provides a gradient in V\ :sub:`cmax` similar to +the original CLM4 specific leaf area scaling. However, Bonan et al. +(2012) showed that the sunlit/shaded canopy parameterization does not +match an explicit multi-layer canopy parameterization. The discrepancy +arises from absorption of scattered radiation by shaded leaves and can +be tuned out with higher :math:`K_{n}` . The model uses +:math:`K_{n} =0.30` to match an explicit multi-layer canopy. + +:math:`V_{c\max 25}` additionally varies with daylength (:math:`DYL`) +using the function :math:`f(DYL)`, which introduces seasonal variation +to :math:`V_{c\max }` + +.. math:: + :label: 9.24) + + f\left(DYL\right)=\frac{\left(DYL\right)^{2} }{\left(DYL_{\max } \right)^{2} } + +with :math:`0.01\le f\left(DYL\right)\le 1`. Daylength (seconds) is +given by + +.. math:: + :label: 9.25) + + DYL=2\times 13750.9871\cos ^{-1} \left[\frac{-\sin \left(lat\right)\sin \left(decl\right)}{\cos \left(lat\right)\cos \left(decl\right)} \right] + +where :math:`lat` (latitude) and :math:`decl` (declination angle) are +from section 3.3. Maximum daylength (:math:`DYL_{\max }` ) is calculated +similarly but using the maximum declination angle for present-day +orbital geometry (:math:`\pm`\ 23.4667º [:math:`\pm`\ 0.409571 radians], +positive for Northern Hemisphere latitudes and negative for Southern +Hemisphere). diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index fcbbde344d..7fb1521105 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -82,6 +82,12 @@ Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation patterns in spruce and pine trees following irrigation and fertilization. Tree Phys. 2:189-204. +.. _BadgerandDirmeyer2015: + +Badger, A.M., and Dirmeyer, P.A., 2015. Climate response to Amazon forest +replacement by heterogeneous crop cover. Hydrol. Earth. Syst. Sci. 19:4547- +4557. + .. _Bairdetal2004: Baird, A.J., Beckwith, C.W., Waldron, S. and Waddington, J.M., 2004. @@ -990,6 +996,12 @@ and Kucharik, C 2012. Interactive crop management in the Community Earth System Model (CESM1): Seasonal influences on land-atmosphere fluxes. J. Climate 25: 4839-4859. DOI:10.1175/JCLI-D-11-00446.1. +.. _Levisetal2016: + +Levis, S., Badger, A., Drewniak, B., Nevison, C., Ren, X. 2016. CLMcrop +yields and water requirements: avoided impacts by choosing RCP 4.5 over 8.5. +Climatic Change. DOI:10.1007/s10584-016-1654-9. + .. _Lietal2000: Li, C., Aber, J., Stange, F., Butterbach-Bahl, K. and Papen, H. 2000. A From 48450d9730fbfef31a5bdde1eef6c5afe0fd8257 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 26 May 2017 07:17:12 -0600 Subject: [PATCH 023/255] correct lake references --- .../tech_note/Lake/CLM50_Tech_Note_Lake.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst index aa0489964d..860bc2ae7c 100644 --- a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst +++ b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst @@ -4,17 +4,17 @@ Lake Model ============= The lake model, denoted the *Lake, Ice, Snow, and Sediment Simulator* -(LISSS), is from :numref:`Subin et al. (2012a) `. +(LISSS), is from :ref:`Subin et al. (2012a) `. It includes extensive modifications to the lake code of -:numref:`Zeng et al. (2002) ` used in CLM +:ref:`Zeng et al. (2002) ` used in CLM versions 2 through 4, which utilized concepts from the lake models of -:numref:`Bonan (1996) `, -:numref:`Henderson-Sellers (1985) `, -:numref:`Henderson-Sellers (1986) `, -:numref:`Hostetler and Bartlein (1990) `, -and the coupled lake-atmosphere model of :numref:`Hostetler et al. (1993) `, :numref:`Hostetler et al. (1993) `. +:ref:`Bonan (1996) `, +:ref:`Henderson-Sellers (1985) `, +:ref:`Henderson-Sellers (1986) `, +:ref:`Hostetler and Bartlein (1990) `, +and the coupled lake-atmosphere model of :ref:`Hostetler et al. (1993) `, :ref:`Hostetler et al. (1993) `. Lakes have spatially variable depth prescribed in the surface data (section -:numref:`External Data Lake`); the surface data optionally includes lake optical +:ref:`External Data Lake`); the surface data optionally includes lake optical extinction coeffient and horizontal fetch, currently only used for site simulations. Lake physics includes freezing and thawing in the lake body, resolved snow layers, and “soil†and bedrock layers below the lake From 95c43a0bafd9c8d4deb67603816777db52f5a039 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 26 May 2017 10:52:56 -0600 Subject: [PATCH 024/255] Updates to radiative fluxes and surface albedos --- .../CLM50_Tech_Note_Radiative_Fluxes.rst | 11 +++-- .../CLM50_Tech_Note_Surface_Albedos.rst | 48 ++++++++++--------- 2 files changed, 32 insertions(+), 27 deletions(-) diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index 28f43fce9a..1115bf1dc6 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -32,14 +32,17 @@ albedos (section 3.2). :math:`L` and :math:`S` are the exposed leaf area index and stem area index (section 2.1.4). :math:`K` is the optical depth of direct beam per unit leaf and stem area (section 3.1). -Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse -solar radiation, and (c) longwave radiation absorbed, transmitted, and -reflected by vegetation and ground. +.. Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. + +.. _Figure schematic diagram of radiation: + +.. Figure:: image1.png + + Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. For clarity, terms involving :math:`T^{n+1} -T^{n}` are not shown in (c). -.. image:: image1.png The total solar radiation absorbed by the vegetation and ground is diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 0cd135e220..33fd1c0792 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -41,7 +41,7 @@ equations are solved to calculate the fluxes, per unit incident flux, absorbed by the vegetation, reflected by the vegetation, and transmitted through the vegetation for direct and diffuse radiation and for visible (:math:`<` 0.7\ :math:`\mu {\rm m}`) and near-infrared -(:math:`ge` 0.7\ :math:`\mu {\rm m}`) wavebands. The absorbed +(:math:`\geq` 0.7\ :math:`\mu {\rm m}`) wavebands. The absorbed radiation is partitioned to sunlit and shaded fractions of the canopy. The optical parameters :math:`G\left(\mu \right)`, :math:`\bar{\mu }`, :math:`\omega`, :math:`\beta`, and :math:`\beta _{0}` are calculated @@ -156,15 +156,15 @@ Using this approximation, for vertical leaves (:math:`\chi _{L} =-1`, and for horizontal leaves (:math:`\chi _{L} =1`, :math:`\bar{\theta }=0^{{\rm o}}` ) , :math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} =\alpha _{\Lambda }` , -which agree with both Dickinson (1983) and Sellers (1985). For random +which agree with both :ref:`Dickinson (1983) ` and :ref:`Sellers (1985) `. For random (spherically distributed) leaves (:math:`\chi _{L} =0`, :math:`\bar{\theta }=60^{{\rm o}}` ), the approximation yields :math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} ={5\mathord{\left/ {\vphantom {5 8}} \right. \kern-\nulldelimiterspace} 8} \alpha _{\Lambda } +{3\mathord{\left/ {\vphantom {3 8}} \right. \kern-\nulldelimiterspace} 8} \tau _{\Lambda }` -whereas the approximate solution of Dickinson (1983) is +whereas the approximate solution of :ref:`Dickinson (1983) ` is :math:`\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} ={2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} \alpha _{\Lambda } +{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} \tau _{\Lambda }` . This discrepancy arises from the fact that a spherical leaf angle distribution has a true mean leaf inclination -:math:`\bar{\theta }\approx 57` (Campbell and Norman 1998) in equation , +:math:`\bar{\theta }\approx 57` :ref:`(Campbell and Norman 1998) ` in equation , while :math:`\bar{\theta }=60` in equation . The upscatter for direct beam radiation is @@ -178,7 +178,11 @@ where the single scattering albedo is .. math:: :label: 3.16 - \begin{array}{rcl} {a_{s} \left(\mu \right)_{\Lambda } } & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \int _{0}^{1}\frac{\mu 'G\left(\mu \right)}{\mu G\left(\mu '\right)+\mu 'G\left(\mu \right)} d\mu '} \\ {} & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \frac{G\left(\mu \right)}{\mu \phi _{2} +G\left(\mu \right)} \left[1-\frac{\mu \phi _{1} }{\mu \phi _{2} +G\left(\mu \right)} \ln \left(\frac{\mu \phi _{1} +\mu \phi _{2} +G\left(\mu \right)}{\mu \phi _{1} } \right)\right].} \end{array} + \begin{array}{rcl} {a_{s} \left(\mu \right)_{\Lambda } } & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \int _{0}^{1}\frac{\mu 'G\left(\mu \right)}{\mu G\left(\mu '\right)+\mu 'G\left(\mu \right)} d\mu '} \\ {} & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \frac{G\left(\mu \right)}{\min (\mu \phi _{2} +G\left(\mu \right),1e-6)} \left[1-\frac{\mu \phi _{1} }{\min (\mu \phi _{2} +G\left(\mu \right),1e-6)} \ln \left(\frac{\mu \phi _{1} +\min (\mu \phi _{2} +G\left(\mu \right),1e-6)}{\mu \phi _{1} } \right)\right].} \end{array} + +Note here the restriction on :math:`\mu \phi _{2} +G\left(\mu \right)`. We have seen cases where small values +can cause unrealistic single scattering albedo associated with the log calculation, +thereby eventually causing a negative soil albedo. The upward diffuse fluxes per unit incident direct beam and diffuse flux (i.e., the surface albedos) are @@ -206,7 +210,7 @@ radiation, respectively, are I\, \downarrow _{\Lambda } =h_{9} s_{1} +\frac{h_{10} }{s_{1} } . -With reference to Figure 4.1, the direct beam flux transmitted through +With reference to :numref:`Figure schematic diagram of radiation`, the direct beam flux transmitted through the canopy, per unit incident flux, is :math:`e^{-K\left(L+S\right)}` , and the direct beam and diffuse fluxes absorbed by the vegetation, per unit incident flux, are @@ -223,7 +227,7 @@ unit incident flux, are These fluxes are partitioned to the sunlit and shaded canopy using an analytical solution to the two-stream approximation for sunlit and -shaded leaves (Dai et al. 2004), as described by Bonan et al. (2011). +shaded leaves :ref:`(Dai et al. 2004) `, as described by :ref:`Bonan et al. (2011) `. The absorption of direct beam radiation by sunlit leaves is .. math:: @@ -277,8 +281,8 @@ with a_{2} =h_{9} \left[\frac{1-s_{2} s_{1} }{K+h} \right]+h_{10} \left[\frac{1-{s_{2} \mathord{\left/ {\vphantom {s_{2} s_{1} }} \right. \kern-\nulldelimiterspace} s_{1} } }{K-h} \right]. The parameters :math:`h_{1}` –:math:`h_{10}` , :math:`\sigma` , -:math:`h`, :math:`s_{1}` , and :math:`s_{2}` are from Sellers (1985) -[note the error in :math:`h_{4}` in Sellers (1985)]: +:math:`h`, :math:`s_{1}` , and :math:`s_{2}` are from :ref:`Sellers (1985) ` +[note the error in :math:`h_{4}` in :ref:`Sellers (1985) `]: .. math:: :label: 3.31 @@ -417,11 +421,11 @@ The parameters :math:`h_{1}` –:math:`h_{10}` , :math:`\sigma` , Plant functional type optical properties (:numref:`Table Plant functional type optical properties`) for trees and shrubs are from :ref:`Dorman and Sellers (1989) `. Leaf and stem optical -properties (placeVIS and NIR reflectance and transmittance) were derived +properties (VIS and NIR reflectance and transmittance) were derived for grasslands and crops from full optical range spectra of measured optical properties (:ref:`Asner et al. 1998 `). Optical properties for -intercepted snow (:numref:`Table Intercepted snow optical properties`) are -:ref:`from Sellers et al. (1986) `. +intercepted snow (:numref:`Table Intercepted snow optical properties`) are from +:ref:`Sellers et al. (1986) `. .. _Table Plant functional type optical properties: @@ -458,25 +462,23 @@ intercepted snow (:numref:`Table Intercepted snow optical properties`) are +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ | C\ :sub:`4` grass | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Crop R | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | - +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Crop I | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | C\ :sub:`3` Crop | -0.30 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Corn R | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Temp Corn | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Corn I | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Spring Wheat | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Temp Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Temp Soybean | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Temp Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Cotton | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Winter Cereal R | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Rice | 0.65 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Winter Cereal I | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Sugarcane | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Soybean R | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Tropical Corn | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Soybean I | -0.5 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Tropical Soybean | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ .. _Table Intercepted snow optical properties: From 8d902b3761bd4453c5622afb45417dac7b19a431 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 30 May 2017 11:32:20 -0600 Subject: [PATCH 025/255] Chapter 3 Surface Albedos updates and cleanup --- .../CLM50_Tech_Note_Surface_Albedos.rst | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 33fd1c0792..0b45f9faec 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -576,6 +576,8 @@ included the effects of the minimum permanent snow cover. .. table:: Dry and saturated soil albedos + +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ + | | Dry | Saturated | | Dry | Saturated | +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ | Color Class | vis | nir | vis | nir | Color Class | vis | nir | vis | nir | +---------------+--------+--------+--------+--------+---------------+--------+--------+--------+--------+ @@ -708,7 +710,7 @@ are applied in the two-stream solution +---------------------------------------------------------+----------------------+------------------+ | Spectral band | Direct-beam weight | Diffuse weight | +=========================================================+======================+==================+ - | Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | | | + | Band 1: 0.3-0.7\ :math:`\mu`\ m (visible) | (1.0) | (1.0) | +---------------------------------------------------------+----------------------+------------------+ | Band 2: 0.7-1.0\ :math:`\mu`\ m (near-IR) | 0.494 | 0.586 | +---------------------------------------------------------+----------------------+------------------+ @@ -739,15 +741,18 @@ boundary condition, SNICAR simulates solar absorption in all snow layers as well as the underlying soil or ground. With a thin snowpack, penetrating solar radiation to the underlying soil can be quite large and heat cannot be released from the soil to the atmosphere in this -situation. Thus, solar radiation penetration is limited to snowpacks -with total snow depth greater than or equal to 0.1 m -(:math:`z_{sno} \ge 0.1`) to prevent unrealistic soil warming within a -single timestep. +situation. Thus, if the snowpack has total snow depth less than 0.1 m +(:math:`z_{sno} < 0.1`) and there are no explicit snow layers, the solar +radiation is absorbed by the top soil layer. If there is a single snow layer, +the solar radiation is absorbed in that layer. If there is more than a single +snow layer, 75% of the solar radiation is absorbed in the top snow layer, +and 25% is absorbed in the next lowest snow layer. This prevents unrealistic +soil warming within a single timestep. The radiative transfer calculation is performed twice for each column containing a mass of snow greater than :math:`1 \times 10^{-30}` kg\ m\ :sup:`-2` (excluding lake and urban columns); once each for -direct-beam and diffuse incident flux. Absorption in each layer +direct-beam and diffuse incident flux. Absorption in each layer :math:`i` of pure snow is initially recorded as absorbed flux per unit incident flux on the ground (:math:`S_{sno,\, i}` ), as albedos must be calculated for the next timestep with unknown incident flux. The snow @@ -775,7 +780,7 @@ Snowpack Optical Properties Ice optical properties for the five spectral bands are derived offline and stored in a namelist-defined lookup table for online retrieval (see -CLM4.5 User’s Guide). Mie properties are first computed at fine spectral +CLM5.0 User’s Guide). Mie properties are first computed at fine spectral resolution (470 bands), and are then weighted into the five bands applied by CLM according to incident solar flux, :math:`I^{\downarrow } (\lambda )`. For example, the broadband @@ -846,7 +851,7 @@ only with incident solar flux, as in equation . .. _Table Mass extinction values: -.. table:: Mass extinction values (m\ :sup:`2` kg\ :sub:`-1`) used for snowpack impurities and ice +.. table:: Mass extinction values (m\ :sup:`2` kg\ :sup:`-1`) used for snowpack impurities and ice +----------------------------------------------------------------+----------+----------+----------+----------+----------+ | Species | Band 1 | Band 2 | Band 3 | Band 4 | Band 5 | @@ -945,7 +950,7 @@ each time step *t* as r_{e} \left(t\right)=\left[r_{e} \left(t-1\right)+dr_{e,\, dry} +dr_{e,\, wet} \right]f_{old} +r_{e,\, 0} f_{new} +r_{e,\, rfz} f_{rfrz} Here, the effective radius of freshly-fallen snow -(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sub:`-1`), and the effective +(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sup:`-1`), and the effective radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. Dry snow aging is based on a microphysical model described by :ref:`Flanner @@ -1036,7 +1041,7 @@ The solar hour angle :math:`h` (radians) is where :math:`d` is calendar day (:math:`d=0.0` at 0Z on January 1), and :math:`\theta` is longitude (radians) (positive east of the -CityplaceGreenwich meridian). +Greenwich meridian). The solar declination angle :math:`\delta` is calculated as in :ref:`Berger (1978a,b) ` and is valid for one million years past or hence, relative to From a890a94e4d26d4174e74ac77bc84de5ff39e567a Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 30 May 2017 14:50:22 -0600 Subject: [PATCH 026/255] Chapter 4 updates and cleanup --- .../CLM50_Tech_Note_Radiative_Fluxes.rst | 51 +++++++++++-------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index 1115bf1dc6..af386af482 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -14,23 +14,25 @@ where :math:`\vec{S}` is the net solar flux absorbed by the vegetation Solar Fluxes ---------------- -Figure 4.1 illustrates the direct beam and diffuse fluxes in the canopy. +:numref:`Figure schematic diagram of radiation` illustrates the direct beam and diffuse fluxes in the canopy. :math:`I\, \uparrow _{\Lambda }^{\mu }` and :math:`I\, \uparrow _{\Lambda }` are the upward diffuse fluxes, per -unit incident direct beam and diffuse flux (section 3.1). +unit incident direct beam and diffuse flux (section :numref:`Canopy Radiative Transfer`). :math:`I\, \downarrow _{\Lambda }^{\mu }` and :math:`I\, \downarrow _{\Lambda }` \ are the downward diffuse fluxes below the vegetation per unit incident direct beam and diffuse radiation -(section 3.1). The direct beam flux transmitted through the canopy, per +(section :numref:`Canopy Radiative Transfer`). The direct beam flux +transmitted through the canopy, per unit incident flux, is :math:`e^{-K\left(L+S\right)}` . :math:`\vec{I}_{\Lambda }^{\mu }` and :math:`\vec{I}_{\Lambda }^{}` are the fluxes absorbed by the vegetation, per unit incident direct beam -and diffuse radiation (section 3.1). +and diffuse radiation (section :numref:`Canopy Radiative Transfer`). :math:`\alpha _{g,\, \Lambda }^{\mu }` and :math:`\alpha _{g,\, \Lambda }` are the direct beam and diffuse ground -albedos (section 3.2). :math:`L` and :math:`S` are the exposed leaf area -index and stem area index (section 2.1.4). :math:`K` is the optical -depth of direct beam per unit leaf and stem area (section 3.1). +albedos (section :numref:`Ground Albedos`). :math:`L` and :math:`S` are the exposed leaf area +index and stem area index (section :numref:`Phenology and vegetation burial by snow`). +:math:`K` is the optical +depth of direct beam per unit leaf and stem area (section :numref:`Canopy Radiative Transfer`). .. Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. @@ -82,7 +84,8 @@ Photosynthesis and transpiration depend non-linearly on solar radiation, via the light response of stomata. The canopy is treated as two leaves (sunlit and shaded) and the solar radiation in the visible waveband (:math:`<` 0.7 µm) absorbed by the vegetation is apportioned to the -sunlit and shaded leaves (section 3.1). The absorbed photosynthetically +sunlit and shaded leaves (section :numref:`Canopy Radiative Transfer`). +The absorbed photosynthetically active (visible waveband) radiation averaged over the sunlit canopy (per unit plant area) is @@ -116,15 +119,17 @@ calculating :math:`L^{sun}` , K=\frac{G\left(\mu \right)}{\mu } where :math:`G\left(\mu \right)` and :math:`\mu` are parameters in the -two-stream approximation (section 3.1). +two-stream approximation (section :numref:`Canopy Radiative Transfer`). The model uses the two-stream approximation to calculate radiative transfer of direct and diffuse radiation through a canopy that is differentiated into leaves that are sunlit and those that are shaded -(section 3.1). The two-stream equations are integrated over all plant +(section :numref:`Canopy Radiative Transfer`). The two-stream equations +are integrated over all plant area (leaf and stem area) in the canopy. The model has an optional -(though not supported) multi-layer canopy, as described by Bonan et al. -(2012). The multi-layer model is only intended to address the +(though not supported) multi-layer canopy, as described by +:ref:`Bonan et al. (2012) `. +The multi-layer model is only intended to address the non-linearity of light profiles, photosynthesis, and stomatal conductance in the plant canopy. @@ -171,8 +176,10 @@ longwave radiation (W m\ :sup:`-2`). The radiative temperature T_{rad} =\left(\frac{L\, \uparrow }{\sigma } \right)^{{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } -where :math:`\sigma` is the Stefan-Boltzmann constant (W\ m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6). With reference to -Figure 4.1, the upward longwave radiation from the surface to the atmosphere is +where :math:`\sigma` is the Stefan-Boltzmann constant (W\ m\ :sup:`-2` K\ :sup:`-4`) +(:numref:`Table Physical constants`). With reference to +:numref:`Figure schematic diagram of radiation`, the upward longwave radiation +from the surface to the atmosphere is .. math:: :label: 4.11 @@ -185,7 +192,7 @@ the vegetation/soil system for exposed leaf and stem area zero for :math:`L+S<0.05` and one otherwise, :math:`\varepsilon _{g}` is the ground emissivity, and :math:`T_{g}^{n+1}` and :math:`T_{g}^{n}` are the snow/soil surface temperatures at the current -and previous time steps, respectively (Chapter 6). +and previous time steps, respectively (:ref:`rst_Soil and Snow Temperatures`). For non-vegetated surfaces, the above equation reduces to @@ -218,7 +225,8 @@ where where :math:`\varepsilon _{v}` is the vegetation emissivity and :math:`T_{v}^{n+1}` and :math:`T_{v}^{n}` are the vegetation temperatures at the current and previous time steps, respectively -(Chapter 5). The first term in the equation above is the atmospheric +(:ref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). +The first term in the equation above is the atmospheric longwave radiation that is transmitted through the canopy, reflected by the ground, and transmitted through the canopy to the atmosphere. The second term is the longwave radiation emitted by the canopy directly to @@ -259,10 +267,11 @@ atmosphere) The above expression for :math:`\vec{L}_{g}` is the net longwave radiation forcing that is used in the soil temperature calculation -(Chapter 6). Once updated soil temperatures have been obtained, the term +(:ref:`rst_Soil and Snow Temperatures`). Once updated soil +temperatures have been obtained, the term :math:`4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right)` is added to :math:`\vec{L}_{g}` to calculate the ground heat flux -(section 5.4) +(section :numref:`Update of Ground Sensible and Latent Heat Fluxes`) The net longwave radiation flux for vegetation is (positive toward the atmosphere) @@ -282,7 +291,8 @@ emissivity of the ground is where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, and 0.96 for wetland, :math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` -is the fraction of ground covered by snow (section 7.2.1). The +is the fraction of ground covered by snow +(section :numref:`Snow Covered Area Fraction`). The vegetation emissivity is .. math:: @@ -291,6 +301,7 @@ vegetation emissivity is \varepsilon _{v} =1-e^{-{\left(L+S\right)\mathord{\left/ {\vphantom {\left(L+S\right) \bar{\mu }}} \right. \kern-\nulldelimiterspace} \bar{\mu }} } where :math:`L` and :math:`S` are the leaf and stem area indices -(section 2.1.4) and :math:`\bar{\mu }=1` is the average inverse optical +(section :numref:`Phenology and vegetation burial by snow`) and +:math:`\bar{\mu }=1` is the average inverse optical depth for longwave radiation. From cd853dffbcbd962316c06c6bde789197e38bbf74 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Tue, 30 May 2017 15:14:05 -0600 Subject: [PATCH 027/255] add links to Introduction --- .../CLM50_Tech_Note_CN_Allocation.rst | 126 ++++---- .../CLM50_Tech_Note_Crop_Irrigation.rst | 166 +++++----- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 66 ++-- .../CLM50_Tech_Note_Decomposition.rst | 208 ++++++------ .../tech_note/Dust/CLM50_Tech_Note_Dust.rst | 68 ++-- ...LM50_Tech_Note_External_Nitrogen_Cycle.rst | 8 +- .../tech_note/Fire/CLM50_Tech_Note_Fire.rst | 87 ++--- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 14 +- .../CLM50_Tech_Note_Introduction.rst | 296 +++++++++--------- .../Isotopes/CLM50_Tech_Note_Isotopes.rst | 8 +- .../Methane/CLM50_Tech_Note_Methane.rst | 119 +++---- .../CLM50_Tech_Note_Radiative_Fluxes.rst | 15 +- ...CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 5 +- .../CLM50_Tech_Note_Transient_Landcover.rst | 14 +- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 15 +- ...ech_Note_Vegetation_Phenology_Turnover.rst | 6 +- 16 files changed, 636 insertions(+), 585 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index c6a6fa4aa0..3206f3ab28 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -29,18 +29,22 @@ nitrogen pool tracks retranslocated nitrogen, mobilized from leaf tissue prior to abscission and litterfall. Altogether there are 20 state variables for vegetation carbon, and 19 for vegetation nitrogen. -Figure 13.1. Vegetation fluxes and pools. +.. _Figure Vegetation fluxes and pools: -.. image:: image1.png +.. figure:: image1.png :width: 800px :height: 800px -Figure 13.2: Carbon and nitrogen pools. + Vegetation fluxes and pools. -.. image:: image2.png +.. _Figure Carbon and nitrogen pools: + +.. figure:: image2.png :width: 400px :height: 400px + Carbon and nitrogen pools. + Carbon Allocation for Maintenance Respiration Costs -------------------------------------------------------- @@ -157,7 +161,7 @@ constant for all PFTs, based on construction costs for a range of woody and non-woody tissues (Larcher, 1995). The model includes a dynamic allocation scheme for woody vegetation -(parameter :math:`a_{3}` = -1, Table 13.1), in which case the +(parameter :math:`a_{3}` = -1, :numref:`Table Allocation and CN ratio parameters`), in which case the ratio for carbon allocation between new stem and new leaf increases with increasing net primary production (NPP), as @@ -172,59 +176,61 @@ favorable growth environments (Allen et al., 2005; Vanninen and Makela, 2005) and during the phase of stand growth prior to canopy closure (Axelsson and Axelsson, 1986). -Table 13.1. Allocation and carbon:nitrogen ratio parameters - -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`CN_{leaf}` | :math:`CN_{fr}` | :math:`CN_{lw}` | :math:`CN_{dw}` | -+==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ -| NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| NET Boreal | 1 | 0.3 | -1 | 0.1 | 40 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| NDT Boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BET Tropical | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BET temperate | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDT tropical | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDT temperate | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDT boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BES temperate | 1 | 0.3 | 0.2 | 0.5 | 30 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDS temperate | 1 | 0.3 | 0.2 | 0.5 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :sub:`3` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :sub:`3` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :sub:`4` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Crop R | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Crop I | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Corn R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Corn I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Temp Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Temp Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Winter Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Winter Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Soybean R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Soybean I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +.. _Table Allocation and CN ratio parameters: + +.. table:: Allocation and carbon\:nitrogen ratio parameters + + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`CN_{leaf}` | :math:`CN_{fr}` | :math:`CN_{lw}` | :math:`CN_{dw}` | + +==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ + | NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | NET Boreal | 1 | 0.3 | -1 | 0.1 | 40 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | NDT Boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BET Tropical | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BET temperate | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BDT tropical | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BDT temperate | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BDT boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BES temperate | 1 | 0.3 | 0.2 | 0.5 | 30 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BDS temperate | 1 | 0.3 | 0.2 | 0.5 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | C\ :sub:`3` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | C\ :sub:`3` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | C\ :sub:`4` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Crop R | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Crop I | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Corn R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Corn I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Temp Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Temp Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Winter Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Winter Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Soybean R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ + | Soybean I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | + +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ Carbon to nitrogen ratios are defined for different tissue types as follows: @@ -234,8 +240,8 @@ follows: \begin{array}{l} {CN_{leaf} =\_ {\rm \; C:N\; for\; leaf}} \\ {CN_{fr} =\_ {\rm \; C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \; C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\_ {\rm \; C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} -where all C:N parameters are defined as constants for a given PFT (Table -13.1). +where all C:N parameters are defined as constants for a given PFT +(:numref:`Table Allocation and CN ratio parameters`). Given values for the parameters in and , total carbon and nitrogen allocation to new growth ( :math:`CF_{alloc}`, gC diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index dc14d45c6b..2961569d3a 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -78,7 +78,7 @@ simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land -use, and land management change (e.g., :ref:`Kucharik and Brye 2003 ; Lobell et al. 2006 `). +use, and land management change (e.g., :ref:`Kucharik and Brye 2003 `; :ref:`Lobell et al. 2006 `). .. _Crop plant functional types: @@ -147,12 +147,12 @@ where :math:`{T}_{10d}` is the 10-day running mean of :math:`{T}_{2m}`, (the sim temperature at every model time step) and :math:`T_{10d}^{\min}` is the 10-day running mean of :math:`T_{2m}^{\min }` (the daily minimum of :math:`{T}_{2m}`. :math:`{T}_{p}` and :math:`T_{p}^{\min }` are crop-specific coldest planting temperatures -(Table 20.1), :math:`{GDD}_{8}` is the 20-year running mean growing +(:numref:`Table Crop plant functional types`), :math:`{GDD}_{8}` is the 20-year running mean growing degree-days (units are degree-days or :sup:`o` days) tracked from April through September (NH) base 8\ :sup:`o` C with maximum daily increments of 30\ :sup:`o` days (see Eq.XXX ), and :math:`{GDD}_{min }`\ is the minimum growing degree day requirement -(Table 20.1). Soy must meet the same requirements but between May +(:numref:`Table Crop plant functional types`). Soy must meet the same requirements but between May 1\ :sup:`st` and June 14\ :sup:`th` for planting. If the requirements in Eq. are not met by June 14\ :sup:`th`, then corn, soybean, and temperate cereals are still planted on June @@ -202,7 +202,7 @@ Leaf emergence According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth tracked since planting (:math:`GDD_{T_{soi} }` ) reaches 3 to 5% of :math:`{GDD}_{mat}` -(Table 20.1). :math:`GDD_{T_{soi} }` is base 8, 0, and +(:numref:`Table Crop plant functional types`). :math:`GDD_{T_{soi} }` is base 8, 0, and 10\ :math:`{}^\circ`\ C for corn, soybean, and temperate cereals. Leaf onset, as defined in the CN part of the model, occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf @@ -217,7 +217,7 @@ Grain fill Phase 3 begins in a similar way to phase 2. A variable tracked since planting like :math:`GDD_{T_{soi} }` but for 2-m air temperature, :math:`GDD_{T_{{\rm 2m}} }`, must reach a heat unit threshold, *h*, -of 40 to 70% of :math:`{GDD}_{mat}` (Table 20.1). For corn the +of 40 to 70% of :math:`{GDD}_{mat}` (:numref:`Table Crop plant functional types`). For corn the percentage itself is an empirical function of :math:`{GDD}_{mat}` (not shown). In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of @@ -365,42 +365,42 @@ crop and from each other: #. Slope, *m*, of conductance-to-photosynthesis relationship from 9 to 4 for C4 crops as in AgroIBIS. -#. Specific leaf areas, *SLA*, to the AgroIBIS values (Table 20.1). +#. Specific leaf areas, *SLA*, to the AgroIBIS values (:numref:`Table Crop plant functional types`). -#. Leaf orientation, :math:`\chi _{L}`, to the AgroIBIS values (Table 20.1). +#. Leaf orientation, :math:`\chi _{L}`, to the AgroIBIS values (:numref:`Table Crop plant functional types`). #. Soil moisture photosynthesis limitation factor, :math:`\beta _{t}`, for soybeans multiplied as in AgroIBIS by 1.25 for increased drought tolerance. -Table 20.1. Crop plant functional types (pfts) in CLM4.5CNcrop and their -parameters relating to phenology and morphology. Numbers in the first -column correspond to the list of pfts in Table 2.1. - -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| | Phenological | :math:`T_{p}` | :math:`T_{p}^{\min }` | :math:`{GDD}_{min}` | :math:`{GDD}_{mat}` | Phase 2 | Phase 3 | Harvest: days | :math:`z_{top}^{\max }` | *SLA* | :math:`\chi _{L}` | | -| | Type | K | K | ºdays | ºdays | %\ :math:`{GDD}_{mat}` | %\ :math:`{GDD}_{mat}` | past planting | m | m\ :sup:`2`\ leaf g\ :sup:`-1`\ C | index | | -+=======+==============================================+======================+==============================+===========================+===========================+==============================+==============================+=================+==============================+=================================================+========================+====+ -| 15. | C\ :sub:`3` unmanaged rainfed crop | | | | | | | 0.03 | -0.30 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 16. | C\ :sub:`3` unmanaged irrigated crop | | | | | | | 0.03 | -0.30 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 17. | Rainfed Corn (also known as Maize) | | 950-1850 | 3 | 55-65 | :math:`\mathrm{\le}`\ 165 | 2.50 | 0.05 | -0.50 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 18. | Irrigated Corn (also known as Maize) | | 950-1850 | 3 | 55-65 | :math:`\mathrm{\le}`\ 165 | 2.50 | 0.05 | -0.50 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 19. | Rainfed Temperate Cereals | | :math:`\mathrm{\le}`\ 1700 | 5 | 60 | :math:`\mathrm{\le}`\ 150 | 1.20 | 0.07 | 0.65 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 20. | Irrigated Temperate Cereals | | :math:`\mathrm{\le}`\ 1700 | 5 | 60 | :math:`\mathrm{\le}`\ 150 | 1.20 | 0.07 | 0.65 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 21. | Rainfed Winter cereals (place holder) | | 1900 | 5 | 40 | :math:`\mathrm{\le}`\ 265 | 1.20 | 0.07 | 0.65 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 22. | Irrigated Winter cereals (place holder) | | 1900 | 5 | 40 | :math:`\mathrm{\le}`\ 265 | 1.20 | 0.07 | 0.65 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 23. | Rainfed Soybean | | :math:`\mathrm{\le}`\ 1700 | 3 | 70 | :math:`\mathrm{\le}`\ 150 | 0.75 | 0.07 | -0.50 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ -| 24. | Irrigated Soybean | | :math:`\mathrm{\le}`\ 1700 | 3 | 70 | :math:`\mathrm{\le}`\ 150 | 0.75 | 0.07 | -0.50 | | | | -+-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ +.. _Table Crop plant functional types: + +.. table:: Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. + + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | | Phenological | :math:`T_{p}` | :math:`T_{p}^{\min }` | :math:`{GDD}_{min}` | :math:`{GDD}_{mat}` | Phase 2 | Phase 3 | Harvest: days | :math:`z_{top}^{\max }` | *SLA* | :math:`\chi _{L}` | | + | | Type | K | K | ºdays | ºdays | %\ :math:`{GDD}_{mat}` | %\ :math:`{GDD}_{mat}` | past planting | m | m\ :sup:`2`\ leaf g\ :sup:`-1`\ C | index | | + +=======+==============================================+======================+==============================+===========================+===========================+==============================+==============================+=================+==============================+=================================================+========================+====+ + | 15. | C\ :sub:`3` unmanaged rainfed crop | | | | | | | 0.03 | -0.30 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 16. | C\ :sub:`3` unmanaged irrigated crop | | | | | | | 0.03 | -0.30 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 17. | Rainfed Corn (also known as Maize) | | 950-1850 | 3 | 55-65 | :math:`\mathrm{\le}`\ 165 | 2.50 | 0.05 | -0.50 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 18. | Irrigated Corn (also known as Maize) | | 950-1850 | 3 | 55-65 | :math:`\mathrm{\le}`\ 165 | 2.50 | 0.05 | -0.50 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 19. | Rainfed Temperate Cereals | | :math:`\mathrm{\le}`\ 1700 | 5 | 60 | :math:`\mathrm{\le}`\ 150 | 1.20 | 0.07 | 0.65 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 20. | Irrigated Temperate Cereals | | :math:`\mathrm{\le}`\ 1700 | 5 | 60 | :math:`\mathrm{\le}`\ 150 | 1.20 | 0.07 | 0.65 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 21. | Rainfed Winter cereals (place holder) | | 1900 | 5 | 40 | :math:`\mathrm{\le}`\ 265 | 1.20 | 0.07 | 0.65 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 22. | Irrigated Winter cereals (place holder) | | 1900 | 5 | 40 | :math:`\mathrm{\le}`\ 265 | 1.20 | 0.07 | 0.65 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 23. | Rainfed Soybean | | :math:`\mathrm{\le}`\ 1700 | 3 | 70 | :math:`\mathrm{\le}`\ 150 | 0.75 | 0.07 | -0.50 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ + | 24. | Irrigated Soybean | | :math:`\mathrm{\le}`\ 1700 | 3 | 70 | :math:`\mathrm{\le}`\ 150 | 0.75 | 0.07 | -0.50 | | | | + +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ Notes: :math:`T_{p}` and :math:`T_{p}^{\min }` are coldest planting temperatures but for winter cereals :math:`T_{p}^{\min }` @@ -416,30 +416,31 @@ top-of-canopy height of a crop, *SLA* is specific leaf area, and leaf orientation index, :math:`\chi _{L}` , equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. -Table 20.2. Crop pfts in CLM4.5CNcrop and their parameters relating to -allocation. Numbers in the first column correspond to the list of pfts in Table 2.1. - -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| | :math:`a_{leaf}^{i}` | :math:`{L}_{max}` | :math:`a_{froot}^{i}` | :math:`a_{froot}^{f}` | :math:`a_{leaf}^{f}` | :math:`a_{livestem}^{f}` | :math:`d_{L}` | :math:`d_{alloc}^{stem}` | :math:`d_{alloc}^{leaf}` | | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| | fraction | m\ :sup:`2` m\ :sup:`-2` | | | | | | | | | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 17. | Rainfed Corn (also referred to as Maize) | 0.800 | 5 | 0.400 | 0.050 | 0.000 | 0.000 | 1.05 | 2 | 5 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 18. | Irrigated Corn (also referred to as Maize) | 0.800 | 5 | 0.400 | 0.050 | 0.000 | 0.000 | 1.05 | 2 | 5 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 19. | Rainfed Temperate Cereals | 0.750 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 20. | Irrigated Temperate Cereals | 0.750 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 21. | Rainfed Winter cereals (place holder) | 0.425 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 22. | Irrigated Winter cereals (place holder) | 0.425 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 23. | Rainfed Soybean | 0.850 | 6 | 0.500 | 0.200 | 0.000 | 0.300 | 1.05 | 5 | 2 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ -| 24. | Irrigated Soybean | 0.850 | 6 | 0.500 | 0.200 | 0.000 | 0.300 | 1.05 | 5 | 2 | -+-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ +.. _Table Crop pfts in CLM4.5CNcrop and their parameters: + +.. table:: Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. + + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | | :math:`a_{leaf}^{i}` | :math:`{L}_{max}` | :math:`a_{froot}^{i}` | :math:`a_{froot}^{f}` | :math:`a_{leaf}^{f}` | :math:`a_{livestem}^{f}` | :math:`d_{L}` | :math:`d_{alloc}^{stem}` | :math:`d_{alloc}^{leaf}` | | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | | fraction | m\ :sup:`2` m\ :sup:`-2` | | | | | | | | | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 17. | Rainfed Corn (also referred to as Maize) | 0.800 | 5 | 0.400 | 0.050 | 0.000 | 0.000 | 1.05 | 2 | 5 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 18. | Irrigated Corn (also referred to as Maize) | 0.800 | 5 | 0.400 | 0.050 | 0.000 | 0.000 | 1.05 | 2 | 5 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 19. | Rainfed Temperate Cereals | 0.750 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 20. | Irrigated Temperate Cereals | 0.750 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 21. | Rainfed Winter cereals (place holder) | 0.425 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 22. | Irrigated Winter cereals (place holder) | 0.425 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 23. | Rainfed Soybean | 0.850 | 6 | 0.500 | 0.200 | 0.000 | 0.300 | 1.05 | 5 | 2 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ + | 24. | Irrigated Soybean | 0.850 | 6 | 0.500 | 0.200 | 0.000 | 0.300 | 1.05 | 5 | 2 | + +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ Notes: Crop growth phases and corresponding variables are described in the text @@ -753,7 +754,7 @@ where :math:`{C}_{leaf}`, :math:`{C}_{stem}`, and :math:`{C}_{froot}` is the car root, respectively, :math:`{CN}_{leaf}`, :math:`{CN}_{stem}`, and :math:`{CN}_{froot}` is the pre-grain fill C:N ratio of the leaf, stem, and fine root respectively, and :math:`CN^f_{leaf}`, :math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N -ratio of the leaf, stem, and fine root respectively (Table 20.3). Since +ratio of the leaf, stem, and fine root respectively (:numref:`Table Pre- and post-grain fill CN ratios`). Since C:N measurements are taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots are optimized to allow maximum nitrogen accumulation for later use during organ development. Post-grain @@ -765,28 +766,29 @@ retranslocated pool equal to the plant nitrogen demand. Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. -Table 20.3. Pre- and post-grain fill C:N ratios for crop leaf, stem, -fine root, and reproductive pools. - -+----------------------------+--------+---------------------+-----------+ -| Pre-grain fill stage | Corn | Temperate Cereals | Soybean | -+============================+========+=====================+===========+ -| :math:`{CN}_{leaf}` | 10 | 15 | 25 | -+----------------------------+--------+---------------------+-----------+ -| :math:`{CN}_{stem}` | 50 | 50 | 50 | -+----------------------------+--------+---------------------+-----------+ -| :math:`{CN}_{froot}` | 42 | 30 | 42 | -+----------------------------+--------+---------------------+-----------+ -| Post-grain fill stage | | | | -+----------------------------+--------+---------------------+-----------+ -| :math:`CN_{leaf}^{f}` | 65 | 65 | 65 | -+----------------------------+--------+---------------------+-----------+ -| :math:`CN_{stem}^{f}` | 120 | 100 | 130 | -+----------------------------+--------+---------------------+-----------+ -| :math:`CN_{froot}^{f}` | 42 | 40 | 42 | -+----------------------------+--------+---------------------+-----------+ -| :math:`CN_{repr}^{f}` | 50 | 40 | 60 | -+----------------------------+--------+---------------------+-----------+ +.. _Table Pre- and post-grain fill CN ratios: + +.. table:: Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. + + +----------------------------+--------+---------------------+-----------+ + | Pre-grain fill stage | Corn | Temperate Cereals | Soybean | + +============================+========+=====================+===========+ + | :math:`{CN}_{leaf}` | 10 | 15 | 25 | + +----------------------------+--------+---------------------+-----------+ + | :math:`{CN}_{stem}` | 50 | 50 | 50 | + +----------------------------+--------+---------------------+-----------+ + | :math:`{CN}_{froot}` | 42 | 30 | 42 | + +----------------------------+--------+---------------------+-----------+ + | Post-grain fill stage | | | | + +----------------------------+--------+---------------------+-----------+ + | :math:`CN_{leaf}^{f}` | 65 | 65 | 65 | + +----------------------------+--------+---------------------+-----------+ + | :math:`CN_{stem}^{f}` | 120 | 100 | 130 | + +----------------------------+--------+---------------------+-----------+ + | :math:`CN_{froot}^{f}` | 42 | 40 | 42 | + +----------------------------+--------+---------------------+-----------+ + | :math:`CN_{repr}^{f}` | 50 | 40 | 60 | + +----------------------------+--------+---------------------+-----------+ .. _Separate reproductive pool: diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 4a7d378379..8608521802 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -40,7 +40,7 @@ The PFT distribution in the vegetated land unit is typically prescribed in CLM (see section 2.1.2) except for the case when CNDV is active. In CNDV the model begins with no PFT information per grid cell and evaluates whether or not a PFT may establish or survive according to the -PFT’s bioclimatic limits (Table 22.1). Shrub PFTs are treated as trees +PFT’s bioclimatic limits (:numref:`Table Plant functional type (PFT) biogeography rules`). Shrub PFTs are treated as trees at establishment. CNDV omits the CLM3DGVM’s annual introduction of saplings when a PFT can @@ -113,8 +113,39 @@ values in the old PFT-physiology file to get a reasonable simulation of PFTs. For CNDV to use the calculated fraction, we will need to change the algorithm for PFTs in early stages of growth. -Table 22.1. Plant functional type (PFT) biogeography rules with respect -to climate. +.. _Table Plant functional type (PFT) biogeography rules: + +.. table:: Plant functional type (PFT) biogeography rules with respect to climate. + + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | | Survival | | | | + +=============================================+==============================================+==============================================+=========================+========+ + | | :math:`{T}_{c,min}` (:math:`\circ`\ C) | :math:`{T}_{c,max}` (:math:`\circ`\ C) | :math:`{GDD}_{min}` | | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Tropical broadleaf evergreen tree (BET) | | 15.5 | No limit | 0 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Tropical broadleaf deciduous tree (BDT) | | 15.5 | No limit | 0 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Temperate needleleaf evergreen tree (NET) | | -2.0 | 22.0 | 900 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Temperate broadleaf evergreen tree (BET) | | 3.0 | 18.8 | 1200 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Temperate broadleaf deciduous tree (BDT) | | -17.0 | 15.5 | 1200 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Boreal needleleaf evergreen tree (NET) | | -32.5 | -2.0 | 600 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Boreal deciduous tree | | No limit | -2.0 | 350 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Temperate broadleaf deciduous shrub (BDS) | | -17.0 | No limit | 1200 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | Boreal broadleaf deciduous shrub (BDS) | | No limit | -2.0 | 350 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | C\ :sub:`4` | | 15.5 | No limit | 0 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | C\ :sub:`3` | | -17.0 | 15.5 | 0 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ + | C\ :sub:`3` arctic | | No limit | -17.0 | 0 | + +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ Adapted from Table 1 of Levis et al. (2004) to include shrub PFTs. :math:`T_{c,\min }` , coldest minimum monthly air temperature for @@ -124,32 +155,3 @@ minimum monthly air temperature for establishment of new PFTs; 5\ :math:`{}^\circ`\ C for establishment of new PFTs. Levis et al. (2004) include an explanation of these variables and their use. -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| | Survival | | | | -+=============================================+==============================================+==============================================+=========================+========+ -| | :math:`{T}_{c,min}` (:math:`\circ`\ C) | :math:`{T}_{c,max}` (:math:`\circ`\ C) | :math:`{GDD}_{min}` | | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Tropical broadleaf evergreen tree (BET) | | 15.5 | No limit | 0 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Tropical broadleaf deciduous tree (BDT) | | 15.5 | No limit | 0 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Temperate needleleaf evergreen tree (NET) | | -2.0 | 22.0 | 900 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Temperate broadleaf evergreen tree (BET) | | 3.0 | 18.8 | 1200 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Temperate broadleaf deciduous tree (BDT) | | -17.0 | 15.5 | 1200 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Boreal needleleaf evergreen tree (NET) | | -32.5 | -2.0 | 600 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Boreal deciduous tree | | No limit | -2.0 | 350 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Temperate broadleaf deciduous shrub (BDS) | | -17.0 | No limit | 1200 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| Boreal broadleaf deciduous shrub (BDS) | | No limit | -2.0 | 350 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| C\ :sub:`4` | | 15.5 | No limit | 0 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| C\ :sub:`3` | | -17.0 | 15.5 | 0 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ -| C\ :sub:`3` arctic | | No limit | -17.0 | 0 | -+---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 4686f649c2..d35feab5be 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -17,14 +17,16 @@ slower decomposition rates, based on the Century model (Parton et al. allow :math:`{n}_{lev}` to equal 1, as in CLM4.0, or to equal the number of soil levels used for the soil hydrology (default 10). -Figure 15.1. Schematic of decomposition model in CLM. +.. _Figure Schematic of decomposition model in CLM: + +.. figure:: image1.png + + Schematic of decomposition model in CLM. Model is structured to allow different representations of the soil C and N decomposition cascade, as well as a vertically-explicit treatment of soil biogeochemistry. -.. image:: image1.png - For the single-level model structure, the fundamental equation for carbon balance of the decomposing pools is: @@ -60,11 +62,13 @@ pools. Further discussion of the vertical distribution of carbon inputs Discussion of the vertical model and analysis of both decomposition structures is in Koven et al (2013). -Figure 15.2. Pool structure, transitions, respired fractions (numbers at -end of arrows), and turnover times (numbers in boxes) for the 2 -alternate soil decomposition models included in CLM. +.. _Figure Pool structure: + +.. figure:: image2.png -.. image:: image2.png + Pool structure, transitions, respired fractions (numbers at + end of arrows), and turnover times (numbers in boxes) for the 2 + alternate soil decomposition models included in CLM. CLM-CN Pool Structure, Rate Constants and Parameters --------------------------------------------------------- @@ -90,39 +94,39 @@ estimate exponential decay rates and respiration fractions (Thornton, conducted at constant temperature and under moist conditions with relatively high mineral nitrogen concentrations, and so the resulting rate constants are assumed not limited by the availability of water or -mineral nitrogen. Table 15.1 lists the base decomposition rates for each +mineral nitrogen. :numref:`Table Decomposition rate constants` lists the base decomposition rates for each litter and SOM pool, as well as a base rate for physical fragmentation for the coarse woody debris pool (CWD). -Table 15.1. Decomposition rate constants for litter and SOM pools, C:N -ratios, and acceleration parameters (see section 15.8 for explanation) -for the CLM-CN decomposition pool structure. - -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| | Biome-BGC | CLM-CN | | | -+==========================+================================================+===============================================+===============+=========================================+ -| | :math:`{k}_{disc1}`\ (d\ :sup:`-1`) | :math:`{k}_{disc2}` (hr\ :sup:`-1`) | *C:N ratio* | Acceleration term (:math:`{a}_{i}`) | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{Lit1}` | 0.7 | 0.04892 | - | 1 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{Lit2}` | 0.07 | 0.00302 | - | 1 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{Lit3}` | 0.014 | 0.00059 | - | 1 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{SOM1}` | 0.07 | 0.00302 | 12 | 1 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{SOM2}` | 0.014 | 0.00059 | 12 | 1 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{SOM3}` | 0.0014 | 0.00006 | 10 | 5 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{SOM4}` | 0.0001 | 0.000004 | 10 | 70 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ -| :math:`{k}_{CWD}` | 0.001 | 0.00004 | - | 1 | -+--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ - -The first column of Table 15.1 gives the rates as used for the Biome-BGC +.. _Table Decomposition rate constants: + +.. table:: Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. + + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | | Biome-BGC | CLM-CN | | | + +==========================+================================================+===============================================+===============+=========================================+ + | | :math:`{k}_{disc1}`\ (d\ :sup:`-1`) | :math:`{k}_{disc2}` (hr\ :sup:`-1`) | *C:N ratio* | Acceleration term (:math:`{a}_{i}`) | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{Lit1}` | 0.7 | 0.04892 | - | 1 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{Lit2}` | 0.07 | 0.00302 | - | 1 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{Lit3}` | 0.014 | 0.00059 | - | 1 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{SOM1}` | 0.07 | 0.00302 | 12 | 1 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{SOM2}` | 0.014 | 0.00059 | 12 | 1 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{SOM3}` | 0.0014 | 0.00006 | 10 | 5 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{SOM4}` | 0.0001 | 0.000004 | 10 | 70 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + | :math:`{k}_{CWD}` | 0.001 | 0.00004 | - | 1 | + +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ + +The first column of :numref:`Table Decomposition rate constants` gives the rates as used for the Biome-BGC model, which uses a discrete-time model with a daily timestep. The -second column of Table 15.1 shows the rates transformed for a one-hour +second column of :numref:`Table Decomposition rate constants` shows the rates transformed for a one-hour discrete timestep typical of CLM-CN. The transformation is based on the conversion of the initial discrete-time value (:math:`{k}_{disc1}`) first to a continuous time value (:math:`{k}_{cont}`), then to the @@ -150,27 +154,29 @@ or SOM pools that is released as CO\ :sub:`2` due to heterotrophic respiration. Respiration fractions and exponential decay rates are estimated simultaneously from the results of microcosm decomposition experiments (Thornton, 1998). The same values are used in CLM-CN and -Biome-BGC (Table 15.2). - -Table 15.2. Respiration fractions for litter and SOM pools - -+---------------------------+-----------------------+ -| Pool | *rf* | -+===========================+=======================+ -| :math:`{rf}_{Lit1}` | 0.39 | -+---------------------------+-----------------------+ -| :math:`{rf}_{Lit2}` | 0.55 | -+---------------------------+-----------------------+ -| :math:`{rf}_{Lit3}` | 0.29 | -+---------------------------+-----------------------+ -| :math:`{rf}_{SOM1}` | 0.28 | -+---------------------------+-----------------------+ -| :math:`{rf}_{SOM2}` | 0.46 | -+---------------------------+-----------------------+ -| :math:`{rf}_{SOM3}` | 0.55 | -+---------------------------+-----------------------+ -| :math:`{rf}_{SOM4}` | :math:`{1.0}^{a}` | -+---------------------------+-----------------------+ +Biome-BGC (:numref:`Table Respiration fractions for litter and SOM pools`). + +.. _Table Respiration fractions for litter and SOM pools: + +.. table:: Respiration fractions for litter and SOM pools + + +---------------------------+-----------------------+ + | Pool | *rf* | + +===========================+=======================+ + | :math:`{rf}_{Lit1}` | 0.39 | + +---------------------------+-----------------------+ + | :math:`{rf}_{Lit2}` | 0.55 | + +---------------------------+-----------------------+ + | :math:`{rf}_{Lit3}` | 0.29 | + +---------------------------+-----------------------+ + | :math:`{rf}_{SOM1}` | 0.28 | + +---------------------------+-----------------------+ + | :math:`{rf}_{SOM2}` | 0.46 | + +---------------------------+-----------------------+ + | :math:`{rf}_{SOM3}` | 0.55 | + +---------------------------+-----------------------+ + | :math:`{rf}_{SOM4}` | :math:`{1.0}^{a}` | + +---------------------------+-----------------------+ :sup:`a`:math:`{}^{a}` The respiration fraction for pool SOM4 is 1.0 by definition: since there is no pool downstream of SOM4, the entire carbon @@ -184,49 +190,51 @@ decay model; the two structures differ in the number of pools, the connections between those pools, the turnover times of the pools, and the respired fraction during each transition (Figure 15.2). The turnover times are different for the Century-based pool structure, following -those described in Parton et al. (1988) (Table 15.3). - -Table 15.3. Turnover times, C:N ratios, and acceleration parameters (see -section 15.8 for explanation) for the Century-based decomposition -cascade. - -+------------+------------------------+-------------+-------------------------------------------+ -| | Turnover time (year) | C:N ratio | Acceleration term (:math:`{a}_{i}`) | -+============+========================+=============+===========================================+ -| CWD | 4.1 | - | 1 | -+------------+------------------------+-------------+-------------------------------------------+ -| Litter 1 | 0.066 | - | 1 | -+------------+------------------------+-------------+-------------------------------------------+ -| Litter 2 | 0.25 | - | 1 | -+------------+------------------------+-------------+-------------------------------------------+ -| Litter 3 | 0.25 | - | 1 | -+------------+------------------------+-------------+-------------------------------------------+ -| SOM 1 | 0.17 | 8 | 1 | -+------------+------------------------+-------------+-------------------------------------------+ -| SOM 2 | 6.1 | 11 | 15 | -+------------+------------------------+-------------+-------------------------------------------+ -| SOM 3 | 270 | 11 | 675 | -+------------+------------------------+-------------+-------------------------------------------+ - -Likewise, values for the respiration fraction of Century-based structure are in Table 15.4. - -Table 15.4. Respiration fractions for litter and SOM pools for Century-based structure - -+---------------------------+----------+ -| Pool | *rf* | -+===========================+==========+ -| :math:`{rf}_{Lit1}` | 0.55 | -+---------------------------+----------+ -| :math:`{rf}_{Lit2}` | 0.5 | -+---------------------------+----------+ -| :math:`{rf}_{Lit3}` | 0.5 | -+---------------------------+----------+ -| :math:`{rf}_{SOM1}` | f(txt) | -+---------------------------+----------+ -| :math:`{rf}_{SOM2}` | 0.55 | -+---------------------------+----------+ -| :math:`{rf}_{SOM3}` | 0.55 | -+---------------------------+----------+ +those described in Parton et al. (1988) (:numref:`Table Turnover times`). + +.. _Table Turnover times: + +.. table:: Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. + + +------------+------------------------+-------------+-------------------------------------------+ + | | Turnover time (year) | C:N ratio | Acceleration term (:math:`{a}_{i}`) | + +============+========================+=============+===========================================+ + | CWD | 4.1 | - | 1 | + +------------+------------------------+-------------+-------------------------------------------+ + | Litter 1 | 0.066 | - | 1 | + +------------+------------------------+-------------+-------------------------------------------+ + | Litter 2 | 0.25 | - | 1 | + +------------+------------------------+-------------+-------------------------------------------+ + | Litter 3 | 0.25 | - | 1 | + +------------+------------------------+-------------+-------------------------------------------+ + | SOM 1 | 0.17 | 8 | 1 | + +------------+------------------------+-------------+-------------------------------------------+ + | SOM 2 | 6.1 | 11 | 15 | + +------------+------------------------+-------------+-------------------------------------------+ + | SOM 3 | 270 | 11 | 675 | + +------------+------------------------+-------------+-------------------------------------------+ + +Likewise, values for the respiration fraction of Century-based structure are in :numref:`Table Respiration fractions for Century-based structure`. + +.. _Table Respiration fractions for Century-based structure: + +.. table:: Respiration fractions for litter and SOM pools for Century-based structure + + +---------------------------+----------+ + | Pool | *rf* | + +===========================+==========+ + | :math:`{rf}_{Lit1}` | 0.55 | + +---------------------------+----------+ + | :math:`{rf}_{Lit2}` | 0.5 | + +---------------------------+----------+ + | :math:`{rf}_{Lit3}` | 0.5 | + +---------------------------+----------+ + | :math:`{rf}_{SOM1}` | f(txt) | + +---------------------------+----------+ + | :math:`{rf}_{SOM2}` | 0.55 | + +---------------------------+----------+ + | :math:`{rf}_{SOM3}` | 0.55 | + +---------------------------+----------+ Environmental modifiers on decomposition rate -------------------------------------------------- diff --git a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst index 381367a4c0..2b3bfa6dd7 100644 --- a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst +++ b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst @@ -83,8 +83,8 @@ flux where the saltation constant :math:`c_{s}` equals 2.61 and :math:`\rho _{atm}` is the atmospheric density (kg m\ :sup:`-3`) -(Table 2.3), :math:`g` the acceleration of gravity (m -s\ :sup:`-2`) (Table 2.6). The threshold wind friction speed for saltation :math:`u_{*t}` (m s\ :sup:`-1`) is +(:numref:`Table Atmospheric input to land model`), :math:`g` the acceleration of gravity (m +s\ :sup:`-2`) (:numref:`Table Physical constants`). The threshold wind friction speed for saltation :math:`u_{*t}` (m s\ :sup:`-1`) is .. math:: :label: ZEqnNum888452 @@ -120,7 +120,7 @@ where :math:`a=M_{clay}^{-1}` for tuning purposes, :math:`\theta _{1}` is the volumetric soil moisture in the top soil layer (m:math:`{}^{3 }`\ m\ :sup:`-3`) (section 7.4), :math:`\rho _{liq}` is the density of liquid water (kg -m\ :sup:`-3`) (Table 2.6), and :math:`\rho _{d,\, 1}` is the bulk +m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{d,\, 1}` is the bulk density of soil in the top soil layer (kg m\ :sup:`-3`) defined as in section 6.3 rather than as in Zender et al. (2003). :math:`Re_{*t}^{f}` from equation is the threshold friction Reynolds @@ -172,34 +172,36 @@ mode :math:`i` carried in each of *:math:`J=4`* transport bins :math:`j` where :math:`m_{i}` , :math:`\tilde{D}_{v,\, i}` , and :math:`\sigma _{g,\, i}` are the mass fraction, mass median diameter, and geometric standard deviation assigned to each particle source mode -:math:`i` (Table 24.1), while :math:`D_{j,\, \min }` and +:math:`i` (:numref:`Table Dust Mass fraction`), while :math:`D_{j,\, \min }` and :math:`D_{j,\, \max }` are the minimum and maximum diameters (m) in -each transport bin :math:`j` ** (Table 24.2). - -Table 24.1. Mass fraction :math:`m_{i}` , mass median diameter -:math:`\tilde{D}_{v,\, i}` , and geometric standard deviation -:math:`\sigma _{g,\, i}` , per dust source mode :math:`i` - -+-------------+-----------------------------+-----------------------------------+-----------------------------+ -| :math:`i` | :math:`m_{i}` (fraction) | :math:`\tilde{D}_{v,\, i}` (m) | :math:`\sigma _{g,\, i}` | -+=============+=============================+===================================+=============================+ -| 1 | 0.036 | 0.832 x 10\ :math:`{}^{-6}` | 2.1 | -+-------------+-----------------------------+-----------------------------------+-----------------------------+ -| 2 | 0.957 | 4.820 x 10\ :math:`{}^{-6}` | 1.9 | -+-------------+-----------------------------+-----------------------------------+-----------------------------+ -| 3 | 0.007 | 19.38 x 10\ :math:`{}^{-6}` | 1.6 | -+-------------+-----------------------------+-----------------------------------+-----------------------------+ - -Table 24.2. Minimum and maximum particle diameters in each dust transport bin :math:`j` - -+-------------+-------------------------------+-------------------------------+ -| :math:`j` | :math:`D_{j,\, \min }` (m) | :math:`D_{j,\, \max }` (m) | -+=============+===============================+===============================+ -| 1 | 0.1 x 10\ :math:`{}^{-6}` | 1.0 x 10\ :math:`{}^{-6}` | -+-------------+-------------------------------+-------------------------------+ -| 2 | 1.0 x 10\ :math:`{}^{-6}` | 2.5 x 10\ :math:`{}^{-6}` | -+-------------+-------------------------------+-------------------------------+ -| 3 | 2.5 x 10\ :math:`{}^{-6}` | 5.0 x 10\ :math:`{}^{-6}` | -+-------------+-------------------------------+-------------------------------+ -| 4 | 5.0 x 10\ :math:`{}^{-6}` | 10.0 x 10\ :math:`{}^{-6}` | -+-------------+-------------------------------+-------------------------------+ +each transport bin :math:`j` ** (:numref:`Table Dust Minimum and maximum particle diameters`). + +.. _Table Dust Mass fraction: + +.. table:: Mass fraction :math:`m_{i}` , mass median diameter :math:`\tilde{D}_{v,\, i}` , and geometric standard deviation :math:`\sigma _{g,\, i}` , per dust source mode :math:`i` + + +-------------+-----------------------------+-----------------------------------+-----------------------------+ + | :math:`i` | :math:`m_{i}` (fraction) | :math:`\tilde{D}_{v,\, i}` (m) | :math:`\sigma _{g,\, i}` | + +=============+=============================+===================================+=============================+ + | 1 | 0.036 | 0.832 x 10\ :math:`{}^{-6}` | 2.1 | + +-------------+-----------------------------+-----------------------------------+-----------------------------+ + | 2 | 0.957 | 4.820 x 10\ :math:`{}^{-6}` | 1.9 | + +-------------+-----------------------------+-----------------------------------+-----------------------------+ + | 3 | 0.007 | 19.38 x 10\ :math:`{}^{-6}` | 1.6 | + +-------------+-----------------------------+-----------------------------------+-----------------------------+ + +.. _Table Dust Minimum and maximum particle diameters: + +.. table:: Minimum and maximum particle diameters in each dust transport bin :math:`j` + + +-------------+-------------------------------+-------------------------------+ + | :math:`j` | :math:`D_{j,\, \min }` (m) | :math:`D_{j,\, \max }` (m) | + +=============+===============================+===============================+ + | 1 | 0.1 x 10\ :math:`{}^{-6}` | 1.0 x 10\ :math:`{}^{-6}` | + +-------------+-------------------------------+-------------------------------+ + | 2 | 1.0 x 10\ :math:`{}^{-6}` | 2.5 x 10\ :math:`{}^{-6}` | + +-------------+-------------------------------+-------------------------------+ + | 3 | 2.5 x 10\ :math:`{}^{-6}` | 5.0 x 10\ :math:`{}^{-6}` | + +-------------+-------------------------------+-------------------------------+ + | 4 | 5.0 x 10\ :math:`{}^{-6}` | 10.0 x 10\ :math:`{}^{-6}` | + +-------------+-------------------------------+-------------------------------+ diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst index 2678b845e7..b8f6536a46 100644 --- a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst @@ -88,10 +88,12 @@ on the carbon supply to nitrogen fixing microorganisms (Cleveland et al. where :math:`{NF}_{nfix,sminn}` (gN m\ :sup:`-2` s\ :sup:`-1`) is the rate of BNF. Eq. is plotted over a range of annual NPP in Figure 16.1. -Figure 16.1. Biological nitrogen fixation as a function of annual net -primary production. +.. _Figure Biological nitrogen fixation: + +.. figure:: image1.png -.. image:: image1.png + Biological nitrogen fixation as a function of annual net +primary production. Because of the empirical nature of this NPP-BNF relationship, the timescale for calculating NPP and thus BNF is unconstrained. Using diff --git a/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst b/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst index 74e2c334da..d6b6495827 100644 --- a/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst +++ b/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst @@ -336,7 +336,7 @@ where :math:`A_{b,j}` (km\ :sup:`2`\ (time step)\ :sup:`-1`) is burned area for **C**\ :sub:`j` =(*C*\ :sub:`leaf`, *C*\ :sub:`stem`, *C*\ :sub:`root`, *C*\ :sub:`ts`) is a vector with carbon density (g C km\ :sup:`-2`) for leaf, stem (live and dead stem), root (fine, live coarse and dead coarse root), and transfer and storage carbon pools as elements; **CC**\ :sub:`j` = (*CC*\ :sub:`leaf`, *CC*\ :sub:`stem`, *CC*\ :sub:`root`, *CC*\ :sub:`ts`) is the corresponding combustion -completeness factor vector (Table 18.1). Moreover, we assume that 30% and 20% of column-level litter and coarse woody debris are burned and +completeness factor vector (:numref:`Table PFT-specific combustion completeness and fire mortality`). Moreover, we assume that 30% and 20% of column-level litter and coarse woody debris are burned and the corresponding carbon is transferred to atmosphere. Tissue mortality due to fire leads to carbon transfers in two ways. @@ -352,7 +352,7 @@ transfer and storage pools where :math:`M_{j1} =(M_{{\rm leaf}} ,M_{{\rm livestem,1}} ,M_{{\rm deadstem}} ,M_{{\rm root}} ,M_{{\rm ts}} )_{j}` -is the corresponding mortality factor vector (Table 18.1). Second, +is the corresponding mortality factor vector (:numref:`Table PFT-specific combustion completeness and fire mortality`). Second, carbon from uncombusted live stems is transferred to dead stems as: .. math:: @@ -361,7 +361,7 @@ carbon from uncombusted live stems is transferred to dead stems as: \Psi _{j2} =\frac{A_{b,j} }{f_{j} A_{g} } C_{livestem} (1-CC_{stem} )M_{livestem,2} where :math:`M_{livestem,2}` is the corresponding mortality factor -(Table 18.1). +(:numref:`Table PFT-specific combustion completeness and fire mortality`). Fire nitrogen emissions and nitrogen transfers due to fire-induced mortality are calculated the same way as for carbon, using the same @@ -377,7 +377,7 @@ killed by fire per km\ :sup:`2` (individual km\ :sup:`-2` where :math:`P_{j}` (individual km\ :sup:`-2`) is the population density for the *j*\ th tree PFT and :math:`\xi _{j}` is the -whole-plant mortality factor (Table 18.1). +whole-plant mortality factor (:numref:`Table PFT-specific combustion completeness and fire mortality`). Agricultural fires ----------------------- @@ -437,7 +437,7 @@ simulated planting and harvesting dates. In the post-fire region, fire impact is parameterized similar to section 18.1.3 but with combustion completeness factors and tissue mortality -factors for crop PFTs (Table 18.1). +factors for crop PFTs (:numref:`Table PFT-specific combustion completeness and fire mortality`). Deforestation fires ------------------------ @@ -579,44 +579,45 @@ peat combustion are set as 2.2 kg C m\ :sup:`-2`\ peat fire area (Turetsky et al peatlands are set the same as section 18.1.3 for non-crop PFTs and as section 18.2 for crops PFTs. -Table 18.1. PFT-specific combustion completeness and fire mortality -factors. - -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem` | :math:`\xi`\ :sub:`j` | -+==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+ -| NET Temperate | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| NET Boreal | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| NDT Boreal | - | - | - | - | - | - | - | - | - | - | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BET Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BET Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BDT Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BDT Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BDT Boreal | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BES Temperate | - | - | - | - | - | - | - | - | - | - | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BDS Temperate | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| BDS Boreal | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| Crop 1 | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -| Crop 2 | - | - | - | - | - | - | - | - | - | - | - | -+----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ +.. _Table PFT-specific combustion completeness and fire mortality: + +.. table:: PFT-specific combustion completeness and fire mortality factors. + + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem` | :math:`\xi`\ :sub:`j` | + +==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+ + | NET Temperate | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | NET Boreal | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | NDT Boreal | - | - | - | - | - | - | - | - | - | - | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BET Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BET Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BDT Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BDT Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BDT Boreal | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BES Temperate | - | - | - | - | - | - | - | - | - | - | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BDS Temperate | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | BDS Boreal | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | Crop 1 | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ + | Crop 2 | - | - | - | - | - | - | - | - | - | - | - | + +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ Leaves (:math:`CC_{{\rm leaf}}` ), stems (:math:`CC_{{\rm stem}}` ), roots (:math:`CC_{{\rm root}}` ) , and transfer and storage carbon diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index e6f45af8ff..f1f78574df 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -11,7 +11,7 @@ changes in canopy water :math:`\Delta W_{can}` , surface water :math:`\Delta W_{sfc}` , snow water :math:`\Delta W_{sno}` , soil water :math:`\Delta w_{liq,\, i}` , and soil ice :math:`\Delta w_{ice,\, i}` , and water in the unconfined aquifer :math:`\Delta W_{a}` (all in kg -m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Hydrologic processes figure`). +m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Figure Hydrologic processes`). The total water balance of the system is @@ -35,7 +35,7 @@ s\ :sup:`-1`), :math:`N_{levsoi}` is the number of soil layers :math:`N_{levgrnd}` are currently hydrologically inactive; :ref:`(Lawrence et al. 2008) ` and :math:`\Delta t` is the time step (s). -.. _Hydrologic processes figure: +.. _Figure Hydrologic processes: .. Figure:: image1.png @@ -379,7 +379,7 @@ Soil Water Soil water is predicted from a multi-layer model, in which the vertical soil moisture transport is governed by infiltration, surface and sub-surface runoff, gradient diffusion, gravity, and canopy transpiration -through root extraction (:numref:`Hydrologic processes figure`). +through root extraction (:numref:`Figure Hydrologic processes`). The following derivation generally follows that of :ref:`Z.-L. Yang (1998, unpublished manuscript) `. @@ -467,7 +467,7 @@ and organic properties of the soil (:ref:`Lawrence and Slater 2008 `). The hydraulic conductivity is defined at the depth of the interface of -two adjacent layers :math:`z_{h,\, i}` (:numref:`Water flux schematic figure`) and is a function +two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) and is a function of the saturated hydraulic conductivity :math:`k_{sat} \left[z_{h,\, i} \right]`, the liquid volumetric soil moisture of the two layers :math:`\theta _{i}` and @@ -527,7 +527,7 @@ where :math:`B_{om} = 2.7` \ (:ref:`Letts et al. 2000 `) and B_{\min ,i} =2.91+0.159(\% clay)_{i} . The soil matric potential (mm) is defined at the node depth -:math:`z_{i}` of each layer :math:`i` (:numref:`Water flux schematic figure`) +:math:`z_{i}` of each layer :math:`i` (:numref:`Figure Water flux schematic`) .. math:: :label: ZEqnNum316201 @@ -610,7 +610,7 @@ as Numerical Solution ^^^^^^^^^^^^^^^^^^^^^^^^ -With reference to :numref:`Water flux schematic figure`, the equation for conservation of mass +With reference to :numref:`Figure Water flux schematic`, the equation for conservation of mass (equation :eq:`ZEqnNum790844`) can be integrated over each layer as .. math:: @@ -654,7 +654,7 @@ the effective root fraction :math:`r_{e,\, i}` e_{i} =r_{e,\, i} E_{v}^{t} . -.. _Water flux schematic figure: +.. _Figure Water flux schematic: .. Figure:: image2.png diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 2a5ba1d3ae..9e6c3f2fd0 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -120,123 +120,127 @@ Jinyun Tang, Zong-Liang Yang** **LIST OF FIGURES** -- Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). +- :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). -- Figure 2.1. Configuration of the CLM subgrid hierarchy. +- :numref:`Figure CLM subgrid hierarchy` Configuration of the CLM subgrid hierarchy. -- Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. +- :numref:`Figure Radiation Schematic` Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. -- Figure 5.1. Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. +- :numref:`Figure Schematic diagram of sensible heat fluxes` Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. -- Figure 5.2. Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. +- :numref:`Figure Schematic diagram of latent heat fluxes` Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. -- Figure 6.1. Schematic diagram of numerical scheme used to solve for soil temperature. +- :numref:`Figure Soil Temperature Schematic`. Schematic diagram of numerical scheme used to solve for soil temperature. -- Figure 7.1. Hydrologic processes represented in CLM. +- :numref:`Figure Hydrologic processes` Hydrologic processes represented in CLM. -- Figure 7.2. Example of three layer snow pack (snl=-3). +- :numref:`Figure Water flux schematic` Schematic diagram of numerical scheme used to solve for soil water fluxes. -- Figure 7.3. Schematic diagram of numerical scheme used to solve for soil water fluxes. +- :numref:`three layer snow pack` Example of three layer snow pack (snl=-3). -- Figure 12.1. Schematic representation of the urban land unit. +- :numref:`Figure Schematic representation of the urban land unit` Schematic representation of the urban land unit. -- Figure 12.2. Schematic of urban and atmospheric model coupling. +- :numref:`Figure Schematic of urban and atmospheric model coupling` Schematic of urban and atmospheric model coupling. -- Figure 13.1. Vegetation fluxes and pools. +- :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. -- Figure 13.2: Carbon and nitrogen pools. +- :numref:`Figure Carbon and nitrogen pools` Carbon and nitrogen pools. -- Figure 14.1. Example of annual phenology cycle for seasonal deciduous. +- :numref:`Figure annual phenology cycle` Example of annual phenology cycle for seasonal deciduous. -- Figure 14.2. Example fluxes and pools sizes for an onset growth period of 15 days, with initial transfer pool size of 100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool (e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). +- 14.2. Example fluxes and pools sizes for an onset growth period of 15 days, with initial transfer pool size of 100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool (e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). -- Figure 14.3. Example fluxes and pool sizes for an offset (litterfall) period of 15 days, with initial display pool size of 100 gC m-2 and a timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon content of display pool and litter pool through the litterfall period, ignoring the losses from litter pool due to decomposition during this period. +- 14.3. Example fluxes and pool sizes for an offset (litterfall) period of 15 days, with initial display pool size of 100 gC m-2 and a timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon content of display pool and litter pool through the litterfall period, ignoring the losses from litter pool due to decomposition during this period. -- Figure 15.1. Schematic of decomposition model in CLM. +- :numref:`Figure Schematic of decomposition model in CLM` Schematic of decomposition model in CLM. -- Figure 15.2. Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. +- :numref:`Figure Pool structure` Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. -- Figure 16.1. Biological nitrogen fixation as a function of annual net primary production. 300Figure 19.1. Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. +- :numref:`Figure Biological nitrogen fixation` Biological nitrogen fixation as a function of annual net primary production. -- Figure 21.1. Schematic of land cover change impacts on CLM carbon pools and fluxes. +- :numref:`Figure Methane Schematic` Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. -- Figure 21.2. Schematic of translation of annual UNH land units to CLM4 plant functional types. +- :numref:`Figure Schematic of land cover change` Schematic of land cover change impacts on CLM carbon pools and fluxes. -- Figure 25.1. Atmospheric :math:`\mathrm{\Delta}` 14C used to drive 14C model over the historical period. +- :numref:`Figure Schematic of translation of annual UNH land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. + +- :numref:`Figure Atmospheric Delta C14` Atmospheric :math:`\mathrm{\Delta}` 14C used to drive 14C model over the historical period. **LIST OF TABLES** -- Table 2.1. Plant functional types +- :numref:`Table Plant functional types` Plant functional types + +- :numref:`Table Prescribed plant functional type heights` Prescribed plant functional type heights -- Table 2.2. Prescribed plant functional type heights +- :numref:`Table Soil layer structure` Soil layer structure -- Table 2.3. Atmospheric input to land model +- :numref:`Table Atmospheric input to land model` Atmospheric input to land model -- Table 2.4. Land model output to atmospheric model +- :numref:`Table Land model output to atmospheric model` Land model output to atmospheric model -- Table 2.5. Surface data required for CLM4.5 and their base spatial resolution +- :numref:`Table Surface data required for CLM and their base spatial resolution` Surface data required for CLM4.5 and their base spatial resolution -- Table 2.6. Physical constants +- :numref:`Table Physical constants` Physical constants -- Table 3.1. Plant functional type optical properties +- :numref:`Table Plant functional type optical properties` Plant functional type optical properties -- Table 3.2. Intercepted snow optical properties +- :numref:`Table Intercepted snow optical properties` Intercepted snow optical properties -- Table 3.3. Dry and saturated soil albedos +- :numref:`Table Dry and saturated soil albedos` Dry and saturated soil albedos -- Table 3.4. Spectral bands and weights used for snow radiative transfer +- :numref:`Table Spectral bands and weights used for snow radiative transfer` Spectral bands and weights used for snow radiative transfer -- Table 3.5. Single-scatter albedo values used for snowpack impurities and ice +- :numref:`Table Single-scatter albedo values used for snowpack impurities and ice` Single-scatter albedo values used for snowpack impurities and ice -- Table 3.6. Mass extinction values (m2 kg-1) used for snowpack impurities and ice. +- :numref:`Table Mass extinction values` Mass extinction values (m2 kg-1) used for snowpack impurities and ice. -- Table 3.7. Asymmetry scattering parameters used for snowpack impurities and ice. +- :numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice` Asymmetry scattering parameters used for snowpack impurities and ice. -- Table 3.8. Orbital parameters +- :numref:`Table Orbital parameters` Orbital parameters -- Table 5.1. Plant functional type aerodynamic parameters +- :numref:`Table Plant functional type aerodynamic parameters` Plant functional type aerodynamic parameters -- Table 5.2. Coefficients for e\ :sub:`sat`\ :sup:`T` +- :numref:`Table Coefficients for saturation vapor pressure` Coefficients for e\ :sub:`sat`\ :sup:`T` -- Table 5.3. Coefficients for 112Table 6.1. Soil layer structure. +- :numref:`Table Coefficients for derivative of esat` Coefficients for 112:numref:`` 6.1. Soil layer structure. -- Table 7.1. Meltwater scavenging efficiency for particles within snow +- :numref:`Table Meltwater scavenging` Meltwater scavenging efficiency for particles within snow -- Table 7.2. Minimum and maximum thickness of snow layers (m) +- :numref:`Table snow layer thickness` Minimum and maximum thickness of snow layers (m) -- Table 8.1. Plant functional type (PFT) photosynthetic parameters. +- :numref:`Table Plant functional type (PFT) photosynthetic parameters` Plant functional type (PFT) photosynthetic parameters. -- Table 8.2. Temperature dependence parameters for C3 photosynthesis. +- :numref:`Table Temperature dependence parameters for C3 photosynthesis` Temperature dependence parameters for C3 photosynthesis. -- Table8.3. Plant functional type root distribution parameters. +- :numref:`Table Plant functional type root distribution parameters` Plant functional type root distribution parameters. -- Table 13.1. Allocation and carbon:nitrogen ratio parameters +- :numref:`Table Allocation and CN ratio parameters` Allocation and carbon:nitrogen ratio parameters -- Table 15.1. Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. +- :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. -- Table 15.2. Respiration fractions for litter and SOM pools +- :numref:`Table Respiration fractions for litter and SOM pools` Respiration fractions for litter and SOM pools -- Table 15.3. Respiration fractions for litter and SOM pools for Century-based structure +- :numref:`Table Turnover times` Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. -- Table 15.4.Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. +- :numref:`Table Respiration fractions for Century-based structure` Respiration fractions for litter and SOM pools for Century-based structure -- Table 18.1. PFT-specific combustion completeness and fire mortality factors. +- :numref:`Table PFT-specific combustion completeness and fire mortality` PFT-specific combustion completeness and fire mortality factors. -- Table 19.1. Parameter descriptions and sensitivity analysis ranges applied in the methane model. +- :numref:`Table Methane Parameter descriptions` Parameter descriptions and sensitivity analysis ranges applied in the methane model. -- Table 19.2. Temperature dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. +- :numref:`Table Temperature dependence of aqueous and gaseous diffusion` Temperature dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. -- Table 20.1. Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in Table 2.1. +- :numref:`Table Crop plant functional types` Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. -- Table 20.2. Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in Table 2.1. +- :numref:`Table Crop pfts in CLM4.5CNcrop and their parameters` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. -- Table 20.3. Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. +- :numref:`Table Pre- and post-grain fill CN ratios` Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. -- Table 22.1. Plant functional type (PFT) biogeography rules with respect to climate. +- :numref:`Table Plant functional type (PFT) biogeography rules` Plant functional type (PFT) biogeography rules with respect to climate. -- Table 24.1. Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i +- :numref:`Table Dust Mass fraction` Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i -- Table 24.2. Minimum and maximum particle diameters in each dust transport bin j +- :numref:`Table Dust Minimum and maximum particle diameters` Minimum and maximum particle diameters in each dust transport bin j **ACKNOWLEDGEMENTS** @@ -295,17 +299,17 @@ Inception of CLM The early development of the Community Land Model can be described as the merging of a community-developed land model focusing on biogeophysics and a concurrent effort at NCAR to expand the NCAR Land -Surface Model (NCAR LSM, Bonan 1996) to include the carbon cycle, +Surface Model (NCAR LSM, :ref:`Bonan 1996`) to include the carbon cycle, vegetation dynamics, and river routing. The concept of a community-developed land component of the Community Climate System Model (CCSM) was initially proposed at the CCSM Land Model Working Group (LMWG) meeting in February 1996. Initial software specifications and development focused on evaluating the best features of three existing -land models: the NCAR LSM (Bonan 1996, 1998) used in the Community +land models: the NCAR LSM (:ref:`Bonan 1996, 1998`) used in the Community Climate Model (CCM3) and the initial version of CCSM; the Institute of -Atmospheric Physics, Chinese Academy of Sciences land model (IAP94) (Dai -and Zeng 1997); and the Biosphere-Atmosphere Transfer Scheme (BATS) -(Dickinson et al. 1993) used with CCM2. A scientific steering committee +Atmospheric Physics, Chinese Academy of Sciences land model (IAP94) (:ref:`Dai +and Zeng 1997`); and the Biosphere-Atmosphere Transfer Scheme (BATS) +(:ref:`Dickinson et al. 1993`) used with CCM2. A scientific steering committee was formed to review the initial specifications of the design provided by Robert Dickinson, Gordon Bonan, Xubin Zeng, and Yongjiu Dai and to facilitate further development. Steering committee members were selected @@ -329,11 +333,11 @@ Oleson, M. Bosilovich, Zong-Liang Yang, Ian Baker, P. Houser, and P. Dirmeyer at the LMWG meeting hosted by COLA (Center for Ocean-Land-Atmosphere Studies) in November 1999. Field data used for validation included sites adopted by the Project for Intercomparison of -Land-surface Parameterization Schemes (Henderson-Sellers et al. 1993) -(Cabauw, Valdai, Red-Arkansas river basin) and others [FIFE (Sellers et -al. 1988), BOREAS (Sellers et al. 1995), HAPEX-MOBILHY (André et al. -1986), ABRACOS (Gash et al. 1996), Sonoran Desert (Unland et al. 1996), -GSWP (Dirmeyer et al. 1999)]. Y. Dai also presented results from a +Land-surface Parameterization Schemes (:ref:`Henderson-Sellers et al. 1993`) +(Cabauw, Valdai, Red-Arkansas river basin) and others [FIFE (:ref:`Sellers et +al. 1988`), BOREAS :ref:`(Sellers et al. 1995`), HAPEX-MOBILHY (:ref:`André et al. +1986`), ABRACOS (:ref:`Gash et al. 1996`), Sonoran Desert (:ref:`Unland et al. 1996`), +GSWP (:ref:`Dirmeyer et al. 1999`)]. Y. Dai also presented results from a preliminary coupling of the Common Land Model to CCM3, indicating that the land model could be successfully coupled to a climate model. @@ -348,9 +352,9 @@ and soil temperatures. Sam Levis reported on efforts to incorporate a river routing model to deliver runoff to the ocean model in CCSM. Soon after the workshop, the code was delivered to NCAR for implementation into the CCSM framework. Documentation for the Common Land Model is -provided by Dai et al. (2001) while the coupling with CCM3 is described -in Zeng et al. (2002). The model was introduced to the modeling -community in Dai et al. (2003). +provided by :ref:`Dai et al. (2001)` while the coupling with CCM3 is described +in :ref:`Zeng et al. (2002)`. The model was introduced to the modeling +community in :ref:`Dai et al. (2003)`. CLM2 ^^^^^^^^^^ @@ -361,8 +365,8 @@ cycling, vegetation dynamics, and river routing. The preservation of these advancements necessitated several modifications to the Common Land Model. The biome-type land cover classification scheme was replaced with a plant functional type (PFT) representation with the specification of -PFTs and leaf area index from satellite data (Oleson and Bonan 2000; -Bonan et al. 2002a, b). This also required modifications to +PFTs and leaf area index from satellite data (:ref:`Oleson and Bonan 2000`; +:ref:`Bonan et al. 2002a, b`). This also required modifications to parameterizations for vegetation albedo and vertical burying of vegetation by snow. Changes were made to canopy scaling, leaf physiology, and soil water limitations on photosynthesis to resolve @@ -382,7 +386,7 @@ K. Oleson reported on initial results from a coupling of CCM3 with CLM2 at the June 2001 CCSM Workshop LMWG meeting. Generally, the CLM2 preserved most of the improvements seen in the Common Land Model, particularly with respect to surface air temperature, runoff, and snow. -These simulations are documented in Bonan et al. (2002a). Further small +These simulations are documented in :ref:`Bonan et al. (2002a)`. Further small improvements to the biogeophysical parameterizations, ongoing software development, and extensive analysis and validation within CAM2 and CCSM2 culminated in the release of CLM2 to the community in May 2002. @@ -414,14 +418,14 @@ added stability corrections to the diagnostic 2-m air temperature calculation which reduced biases in this temperature. Competition between PFTs for water, in which PFTs share a single soil column, is the default mode of operation in this model version. CLM3 was released to -the community in June 2004. Dickinson et al. (2006) describe the climate -statistics of CLM3 when coupled to CCSM3.0. Hack et al. (2006) provide +the community in June 2004.:ref:`Dickinson et al. (2006)` describe the climate +statistics of CLM3 when coupled to CCSM3.0. :ref:`Hack et al. (2006)` provide an analysis of selected features of the land hydrological cycle. -Lawrence et al. (2007) examine the impact of changes in CLM3 +:ref:`Lawrence et al. (2007)` examine the impact of changes in CLM3 hydrological parameterizations on partitioning of evapotranspiration (ET) and its effect on the timescales of ET response to precipitation events, interseasonal soil moisture storage, soil moisture memory, and -land-atmosphere coupling. Qian et al. (2006) evaluate CLM3’s performance +land-atmosphere coupling. :ref:`Qian et al. (2006)` evaluate CLM3’s performance in simulating soil moisture content, runoff, and river discharge when forced by observed precipitation, temperature and other atmospheric data. @@ -442,16 +446,16 @@ integration, canopy interception, frozen soil, soil water availability, and soil evaporation, a TOPMODEL-based model for surface and subsurface runoff, a groundwater model for determining water table depth, and the introduction of a factor to simulate nitrogen limitation on plant -productivity. Oleson et al. (2008a) show that CLM3.5 exhibits +productivity. :ref:`Oleson et al. (2008a)` show that CLM3.5 exhibits significant improvements over CLM3 in its partitioning of global ET which result in wetter soils, less plant water stress, increased transpiration and photosynthesis, and an improved annual cycle of total water storage. Phase and amplitude of the runoff annual cycle is generally improved. Dramatic improvements in vegetation biogeography result when CLM3.5 is coupled to a dynamic global vegetation model. -Stöckli et al. (2008) examine the performance of CLM3.5 at local scales +:ref:`Stöckli et al. (2008)` examine the performance of CLM3.5 at local scales by making use of a network of long-term ground-based ecosystem -observations [FLUXNET (Baldocchi et al. 2001)]. Data from 15 FLUXNET +observations [FLUXNET (:ref:`Baldocchi et al. 2001`)]. Data from 15 FLUXNET sites were used to demonstrate significantly improved soil hydrology and energy partitioning in CLM3.5. CLM3.5 was released to the community in May, 2007. @@ -462,7 +466,7 @@ CLM4 The motivation for the next version of the model, CLM4, was to incorporate several recent scientific advances in the understanding and representation of land surface processes, expand model capabilities, and -improve surface and atmospheric forcing datasets (Lawrence et al. 2011). +improve surface and atmospheric forcing datasets (:ref:`Lawrence et al. 2011`). Included in the first category are more sophisticated representations of soil hydrology and snow processes. In particular, new treatments of soil column-groundwater interactions, soil evaporation, aerodynamic @@ -488,25 +492,25 @@ ecosystem process model Biome-BGC (Biome BioGeochemical Cycles), originating at the Numerical Terradynamic Simulation Group (NTSG) at the University of Montana, under the guidance of Prof. Steven Running. Biome-BGC itself is an extension of an earlier model, Forest-BGC -**(Running and Coughlan, 1988; Running and Gower, 1991)**, which +(:ref:`Running and Coughlan, 1988`; :ref:`Running and Gower, 1991`), which simulates water, carbon, and, to a limited extent, nitrogen fluxes for forest ecosystems. Forest-BGC was designed to be driven by remote sensing inputs of vegetation structure, and so used a diagnostic (prescribed) leaf area index, or, in the case of the dynamic allocation -version of the model **(Running and Gower, 1991)**, prescribed maximum +version of the model (:ref:`Running and Gower, 1991`), prescribed maximum leaf area index. Biome-BGC expanded on the Forest-BGC logic by introducing a more -mechanistic calculation of leaf and canopy scale photosynthesis **(Hunt -and Running, 1992)**, and extending the physiological parameterizations -to include multiple woody and non-woody vegetation types **(Hunt et al. -1996; Running and Hunt, 1993)**. Later versions of Biome-BGC introduced +mechanistic calculation of leaf and canopy scale photosynthesis (:ref:`Hunt +and Running, 1992`), and extending the physiological parameterizations +to include multiple woody and non-woody vegetation types (:ref:`Hunt et al. +1996`; :ref:`Running and Hunt, 1993`). Later versions of Biome-BGC introduced more mechanistic descriptions of belowground carbon and nitrogen cycles, nitrogen controls on photosynthesis and decomposition, sunlit and shaded canopies, vertical gradient in leaf morphology, and explicit treatment -of fire and harvest disturbance and regrowth dynamics **(Kimball et al. -1997; Thornton, 1998; Thornton et al. 2002; White et al. 2000)**. -Biome-BGC version 4.1.2 **(Thornton et al. 2002)** provided a point of +of fire and harvest disturbance and regrowth dynamics (:ref:`Kimball et al. +1997`; :ref:`Thornton, 1998`; :ref:`Thornton et al. 2002`; :ref:`White et al. 2000`). +Biome-BGC version 4.1.2 (:ref:`Thornton et al. 2002`) provided a point of departure for integrating new biogeochemistry components into CLM4. CLM4 was released to the community in June, 2010 along with the @@ -535,26 +539,26 @@ problems or biases. The main modifications include updates to canopy processes including a revised canopy radiation scheme and canopy scaling of leaf processes, co-limitations on photosynthesis, revisions to photosynthetic parameters -(Bonan et al. 2011), +(:ref:`Bonan et al. 2011`), .. todo:: had three stars here - need to resolve this temperature acclimation of photosynthesis, and improved stability of the iterative solution in the photosynthesis and -stomatal conductance model (Sun et al. 2012). Hydrology updates include +stomatal conductance model (:ref:`Sun et al. 2012`). Hydrology updates include modifications such that hydraulic properties of frozen soils are determined by liquid water content only rather than total water content and the introduction of an ice impedance function, and other corrections that increase the consistency between soil water state and water table position and allow for a perched water table above icy permafrost ground -(Swenson et al. 2012). A new snow cover fraction parameterization is +(:ref:`Swenson et al. 2012`). A new snow cover fraction parameterization is incorporated that reflects the hysteresis in fractional snow cover for a -given snow depth between accumulation and melt phases (Swenson and -Lawrence, 2012). The lake model in CLM4 is replaced with a completely -revised and more realistic lake model (Subin et al. 2012a). A surface +given snow depth between accumulation and melt phases (:ref:`Swenson and +Lawrence, 2012`). The lake model in CLM4 is replaced with a completely +revised and more realistic lake model (:ref:`Subin et al. 2012a`). A surface water store is introduced, replacing the wetland land unit and permitting prognostic wetland distribution modeling, and the surface -energy fluxes are calculated separately (Swenson and Lawrence, 2012) for +energy fluxes are calculated separately (:ref:`Swenson and Lawrence, 2012`) for snow-covered, water-covered, and snow/water-free portions of vegetated and crop land units, and snow-covered and snow-free portions of glacier land units. Globally constant river flow velocity is replaced with @@ -562,28 +566,28 @@ variable flow velocity based on mean grid cell slope. A vertically resolved soil biogeochemistry scheme is introduced with base decomposition rates modified by soil temperature, water, and oxygen limitations and also including vertical mixing of soil carbon and -nitrogen due to bioturbation, cryoturbation, and diffusion (Koven et al. -2013). The litter and soil carbon and nitrogen pool structure as well as +nitrogen due to bioturbation, cryoturbation, and diffusion (:ref:`Koven et al. +2013`). The litter and soil carbon and nitrogen pool structure as well as nitrification and denitrification are modified based on the Century model and biological fixation is revised to distribute fixation more -realistically over the year (Koven et al. 2013). The fire model is +realistically over the year (:ref:`Koven et al. 2013`). The fire model is replaced with a model that includes representations of natural and anthropogenic triggers and suppression as well as agricultural, -deforestation, and peat fires (Li et al. 2012a,b; Li et al. 2013a). The +deforestation, and peat fires (:ref:`Li et al. 2012a,b`; :ref:`Li et al. 2013a`). The biogenic volatile organic compounds model is updated to MEGAN2.1 -(Guenther et al. 2012). +(:ref:`Guenther et al. 2012`). Additions to the model include a methane production, oxidation, and -emissions model (Riley et al. 2011a) and an extension of the crop model -to include interactive fertilization, organ pools (Drewniak et al. -2013), and irrigation (Sacks et al. 2009). Elements of the Variable +emissions model (:ref:`Riley et al. 2011a`) and an extension of the crop model +to include interactive fertilization, organ pools (:ref:`Drewniak et al. +2013`), and irrigation (:ref:`Sacks et al. 2009`). Elements of the Variable Infiltration Capacity (VIC) model are included as an alternative -optional runoff generation scheme (Li et al. 2011). There is also an -option to run with a multilayer canopy (Bonan et al. 2012). Multiple +optional runoff generation scheme (:ref:`Li et al. 2011`). There is also an +option to run with a multilayer canopy (:ref:`Bonan et al. 2012`). Multiple urban density classes, rather than the single dominant urban density class used in CLM4, are modeled in the urban land unit. Carbon -(:math:`{}^{13}`\ C and :math:`{}^{14}`\ C) isotopes are enabled (Koven -et al. 2013). Minor changes include a switch of the C3 Arctic grass and +(:math:`{}^{13}`\ C and :math:`{}^{14}`\ C) isotopes are enabled (:ref:`Koven +et al. 2013`). Minor changes include a switch of the C3 Arctic grass and shrub phenology from stress deciduous to seasonal deciduous and a change in the glacier bare ice albedo to better reflect recent estimates. Finally, the carbon and nitrogen cycle spinup is accelerated and @@ -594,9 +598,9 @@ Finally, the predominantly low resolution input data for provided with CLM4 to create CLM4 surface datasets is replaced with newer and higher resolution input datasets where possible (see section 2.2.3 for details). The default meteorological forcing dataset provided with CLM4 -(Qian et al. 2006) is replaced with the 1901-2010 CRUNCEP forcing +(:ref:`Qian et al. 2006)` is replaced with the 1901-2010 CRUNCEP forcing dataset (see Chapter 26) for CLM4.5, though users can also still use the -Qian et al. (2006) dataset or other alternative forcing datasets. +:ref:`Qian et al. (2006)` dataset or other alternative forcing datasets. CLM4.5 was released to the community in June 2013 along with the Community Earth System Model version 1.2 (CESM1.2). @@ -607,73 +611,75 @@ Biogeophysical and Biogeochemical Processes Biogeophysical and biogeochemical processes are simulated for each subgrid land unit, column, and plant functional type (PFT) independently and each subgrid unit maintains its own prognostic variables (see -section 2.1.1 for definitions of subgrid units). The same atmospheric +section :numref:`Surface Heterogeneity and Data Structure` for definitions +of subgrid units). The same atmospheric forcing is used to force all subgrid units within a grid cell. The surface variables and fluxes required by the atmosphere are obtained by averaging the subgrid quantities weighted by their fractional areas. The -processes simulated include (Figure 1.1): +processes simulated include (:numref:`Figure Land processes`): #. Surface characterization including land type heterogeneity and - ecosystem structure (Chapter 2) + ecosystem structure (Chapter :numref:`rst_Surface Characterization, Vertical Discretization, and Model Input Requirements`) #. Absorption, reflection, and transmittance of solar radiation (Chapter - 3, 4) + :numref:`rst_Surface Albedos`, :numref:`rst_Radiative Fluxes`) -#. Absorption and emission of longwave radiation (Chapter 4) +#. Absorption and emission of longwave radiation (Chapter :numref:`rst_Radiative Fluxes`) #. Momentum, sensible heat (ground and canopy), and latent heat (ground - evaporation, canopy evaporation, transpiration) fluxes (Chapter 5) + evaporation, canopy evaporation, transpiration) fluxes (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) -#. Heat transfer in soil and snow including phase change (Chapter 6) +#. Heat transfer in soil and snow including phase change (Chapter :numref:`rst_Soil and Snow Temperatures`) -#. Canopy hydrology (interception, throughfall, and drip) (Chapter 7) - -#. Snow hydrology (snow accumulation and melt, compaction, water - transfer between snow layers) (Chapter 7) +#. Canopy hydrology (interception, throughfall, and drip) (Chapter :numref:`rst_Hydrology`) #. Soil hydrology (surface runoff, infiltration, redistribution of water - within the column, sub-surface drainage, groundwater) (Chapter 7) + within the column, sub-surface drainage, groundwater) (Chapter :numref:`rst_Hydrology`) -#. Stomatal physiology and photosynthesis (Chapter 8) +#. Snow hydrology (snow accumulation and melt, compaction, water + transfer between snow layers) (Chapter :numref:`rst_Snow Hydrology`) + +#. Stomatal physiology and photosynthesis (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`) -#. place Lake temperatures and fluxes (Chapter 9) +#. Lake temperatures and fluxes (Chapter :numref:`rst_Lake Model`) -#. Glacier processes (Chapter 10) +#. Glacier processes (Chapter :numref:`rst_Glaciers`) -#. Routing of runoff from rivers to ocean (Chapter 11) +#. Routing of runoff from rivers to ocean (Chapter :numref:`rst_River Transport Model (RTM)`) -#. Urban energy balance and climate (Chapter 12) +#. Urban energy balance and climate (Chapter :numref:`rst_Urban Model (CLMU)`) #. Vegetation carbon and nitrogen allocation and respiration (Chapter - 13) + :numref:`rst_CN Allocation`) -#. Vegetation phenology (Chapter 14) +#. Vegetation phenology (Chapter :numref:`rst_Vegetation Phenology and Turnover`) -#. Soil and litter carbon decomposition (Chapter 15) +#. Soil and litter carbon decomposition (Chapter :numref:`rst_Decomposition`) #. Nitrogen cycling including deposition, biological fixation, - denitrification, leaching, and losses due to fire (Chapter 16) + denitrification, leaching, and losses due to fire (Chapter :numref:`rst_External Nitrogen Cycle`) -#. Plant mortality (Chapter 17) +#. Plant mortality (Chapter :numref:`rst_Plant Mortality`) #. Fire ignition and suppression, including natural, deforestation, and - agricultural fire (Chapter 18) + agricultural fire (Chapter :numref:`rst_Fire`) + +#. Methane production, oxidation, and emissions (Chapter :numref:`rst_Methane Model`) -#. Methane production, oxidation, and emissions (Chapter 19) +#. Crop dynamics and irrigation (Chapter :numref:`rst_Crops and Irrigation`) -#. Crop dynamics and irrigation (Chapter 20) +#. Land cover and land use change including wood harvest (Chapter :numref:`rst_Transient Landcover Change`) -#. Land cover and land use change including wood harvest (Chapter 21) +#. Dynamic global vegetation distribution (Chapter :numref:`rst_Dynamic Global Vegetation Model`) -#. Dynamic global vegetation distribution (Chapter 22) +#. Biogenic volatile organic compound emissions (Chapter :numref:`rst_Biogenic Volatile Organic Compounds (BVOCs)`) -#. Biogenic volatile organic compound emissions (Chapter 23) +#. Dust mobilization and deposition (Chapter :numref:`rst_Dust Model`) -#. Dust mobilization and deposition (Chapter 24) +#. Carbon isotope fractionation (Chapter :numref:`rst_Carbon Isotopes`) -#. Carbon isotope fractionation (Chapter 25) +.. _Figure Land processes: -Figure 1.1. Land biogeophysical, biogeochemical, and landscape processes -simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). +.. figure:: image1.png -.. image:: image1.png + Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM4.5). diff --git a/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst b/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst index f4b8127a2c..093b7d7a37 100644 --- a/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst +++ b/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst @@ -235,7 +235,9 @@ datasets spanning the 20\ :math:`{}^{th}` century: (Levin and Kromer, 2004; Manning and Melhuish, 1994; Nydal and Lövseth, 1996; Turnbull et al. 2007). This is shown in Figure 25.1. -Figure 25.1. Atmospheric :math:`\mathrm{\Delta}`\ :sup:`14`\ C -used to drive :sup:`14`\ C model over the historical period. +.. _Figure Atmospheric Delta C14: -.. image:: image1.png +.. figure:: image1.png + + Atmospheric :math:`\mathrm{\Delta}`\ :sup:`14`\ C + used to drive :sup:`14`\ C model over the historical period. diff --git a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index 6a29802004..c881a2c7c2 100644 --- a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -39,7 +39,7 @@ the atmosphere. Governing Mass-Balance Relationship ---------------------------------------- -The model (Figure 19.1) accounts for CH\ :sub:`4` production in +The model (:numref:`Figure Methane Schematic`) accounts for CH\ :sub:`4` production in the anaerobic fraction of soil (*P*, mol m\ :sup:`-3` s\ :sup:`-1`), ebullition (*E*, mol m\ :sup:`-3` s\ :sup:`-1`), aerenchyma transport (*A*, mol m\ :sup:`-3` s\ :sup:`-1`), aqueous and gaseous diffusion (:math:`{F}_{D}`, mol m\ :sup:`-2` s\ :sup:`-1`), and oxidation (*O*, mol m\ :sup:`-3` s\ :sup:`-1`) via a transient reaction @@ -78,12 +78,14 @@ CH\ :sub:`4` to the atmosphere when the inundated fraction decreases, and averaging a portion of the non-inundated concentration into the inundated concentration when the inundated fraction increases. -Figure 19.1. Schematic representation of biological and physical -processes integrated in CLM that affect the net CH\ :sub:`4` -surface flux (Riley et al. 2011a). (left) Fully inundated portion of a -CLM gridcell and (right) variably saturated portion of a gridcell. +.. _Figure Methane Schematic: -.. image:: image1.png +.. figure:: image1.png + + Schematic representation of biological and physical + processes integrated in CLM that affect the net CH\ :sub:`4` + surface flux (:ref:`Riley et al. 2011a`). (left) Fully inundated portion of a + CLM gridcell and (right) variably saturated portion of a gridcell. CH\ :sub:`4` Production ---------------------------------- @@ -112,7 +114,7 @@ seasonal inundation fraction (*S*, described below): Here, :math:`f_{CH_{4} }` is the baseline ratio between CO\ :sub:`2` and CH\ :sub:`4` production (all parameters -values are given in Table 19.1). Currently, :math:`f_{CH_{4} }` is +values are given in :numref:`Table Methane Parameter descriptions`). Currently, :math:`f_{CH_{4} }` is modified to account for our assumptions that methanogens may have a higher Q\ :math:`{}_{10}` than aerobic decomposers; are not N limited; and do not have a low-moisture limitation. @@ -170,44 +172,46 @@ The model also calculates the O\ :sub:`2` required during nitrification, and the total O\ :sub:`2` demand is used in the O\ :sub:`2` mass balance solution. -Table 19.1. Parameter descriptions and sensitivity analysis ranges -applied in the methane model. - -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Mechanism | Parameter | Baseline Value | Range for Sensitivity Analysis | Units | Description | -+==============+============================+==============================================+==================================================================================================+=============================================+============================================================================================+ -| Production | :math:`{Q}_{10}` | 2 | 1.5 – 4 | - | CH\ :sub:`4` production :math:`{Q}_{10}` | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`f_{pH}` | 1 | On, off | - | Impact of pH on CH\ :sub:`4` production | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`f_{pE}` | 1 | On, off | - | Impact of redox potential on CH\ :sub:`4` production | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | *S* | Varies | NA | - | Seasonal inundation factor | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`\beta` | 0.2 | NA | - | Effect of anoxia on decomposition rate (used to calculate *S* only) | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`f_{CH_{4} }` | 0.2 | NA | - | Ratio between CH\ :sub:`4` and CO\ :sub:`2` production below the water table | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Ebullition | :math:`{C}_{e,max}` | 0.15 | NA | mol m\ :sup:`-3` | CH\ :sub:`4` concentration to start ebullition | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`{C}_{e,min}` | 0.15 | NA | - | CH\ :sub:`4` concentration to end ebullition | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Diffusion | :math:`f_{D_{0} }` | 1 | 1, 10 | m\ :sup:`2` s\ :sup:`-1` | Diffusion coefficient multiplier (Table 19.2) | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Aerenchyma | *p* | 0.3 | NA | - | Grass aerenchyma porosity | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | *R* | 2.9\ :math:`\times`\ 10\ :sup:`-3` m | NA | m | Aerenchyma radius | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`{r}_{L}` | 3 | NA | - | Root length to depth ratio | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`{F}_{a}` | 1 | 0.5 – 1.5 | - | Aerenchyma conductance multiplier | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| Oxidation | :math:`K_{CH_{4} }` | 5 x 10\ :sup:`-3` | 5\ :math:`\times`\ 10\ :math:`{}^{-4}`\ :math:`{}_{ }`- 5\ :math:`\times`\ 10\ :sup:`-2` | mol m\ :sup:`-3` | CH\ :sub:`4` half-saturation oxidation coefficient (wetlands) | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`K_{O_{2} }` | 2 x 10\ :sup:`-2` | 2\ :math:`\times`\ 10\ :sup:`-3` - 2\ :math:`\times`\ 10\ :sup:`-1` | mol m\ :sup:`-3` | O\ :sub:`2` half-saturation oxidation coefficient | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ -| | :math:`R_{o,\max }` | 1.25 x 10\ :math:`{}^{-5}` | 1.25\ :math:`\times`\ 10\ :math:`{}^{-6}` - 1.25\ :math:`\times`\ 10\ :math:`{}^{-4}` | mol m\ :sup:`-3` s\ :sup:`-1` | Maximum oxidation rate (wetlands) | -+--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ +.. _Table Methane Parameter descriptions: + +.. table:: Parameter descriptions and sensitivity analysis ranges applied in the methane model + + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | Mechanism | Parameter | Baseline Value | Range for Sensitivity Analysis | Units | Description | + +==============+============================+==============================================+==================================================================================================+=============================================+============================================================================================+ + | Production | :math:`{Q}_{10}` | 2 | 1.5 – 4 | - | CH\ :sub:`4` production :math:`{Q}_{10}` | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`f_{pH}` | 1 | On, off | - | Impact of pH on CH\ :sub:`4` production | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`f_{pE}` | 1 | On, off | - | Impact of redox potential on CH\ :sub:`4` production | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | *S* | Varies | NA | - | Seasonal inundation factor | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`\beta` | 0.2 | NA | - | Effect of anoxia on decomposition rate (used to calculate *S* only) | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`f_{CH_{4} }` | 0.2 | NA | - | Ratio between CH\ :sub:`4` and CO\ :sub:`2` production below the water table | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | Ebullition | :math:`{C}_{e,max}` | 0.15 | NA | mol m\ :sup:`-3` | CH\ :sub:`4` concentration to start ebullition | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`{C}_{e,min}` | 0.15 | NA | - | CH\ :sub:`4` concentration to end ebullition | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | Diffusion | :math:`f_{D_{0} }` | 1 | 1, 10 | m\ :sup:`2` s\ :sup:`-1` | Diffusion coefficient multiplier (Table 19.2) | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | Aerenchyma | *p* | 0.3 | NA | - | Grass aerenchyma porosity | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | *R* | 2.9\ :math:`\times`\ 10\ :sup:`-3` m | NA | m | Aerenchyma radius | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`{r}_{L}` | 3 | NA | - | Root length to depth ratio | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`{F}_{a}` | 1 | 0.5 – 1.5 | - | Aerenchyma conductance multiplier | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | Oxidation | :math:`K_{CH_{4} }` | 5 x 10\ :sup:`-3` | 5\ :math:`\times`\ 10\ :math:`{}^{-4}`\ :math:`{}_{ }`- 5\ :math:`\times`\ 10\ :sup:`-2` | mol m\ :sup:`-3` | CH\ :sub:`4` half-saturation oxidation coefficient (wetlands) | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`K_{O_{2} }` | 2 x 10\ :sup:`-2` | 2\ :math:`\times`\ 10\ :sup:`-3` - 2\ :math:`\times`\ 10\ :sup:`-1` | mol m\ :sup:`-3` | O\ :sub:`2` half-saturation oxidation coefficient | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + | | :math:`R_{o,\max }` | 1.25 x 10\ :math:`{}^{-5}` | 1.25\ :math:`\times`\ 10\ :math:`{}^{-6}` - 1.25\ :math:`\times`\ 10\ :math:`{}^{-4}` | mol m\ :sup:`-3` s\ :sup:`-1` | Maximum oxidation rate (wetlands) | + +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ + Ebullition --------------- @@ -384,18 +388,19 @@ source through aerenchyma. For gaseous diffusion, we adopted the temperature dependence of molecular free-air diffusion coefficients (:math:`{D}_{0}` -(m:sup:`2` s\ :sup:`-1`)) as described by Lerman et al. (1979) and applied by Wania et al. (2010) (Table 19.2). - -Table 19.2. Temperature dependence of aqueous and gaseous diffusion -coefficients for CH\ :sub:`4` and O\ :sub:`2`. - -+----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ -| :math:`{D}_{0}` (m\ :sup:`2` s\ :sup:`-1`) | CH\ :sub:`4` | O\ :sub:`2` | -+==========================================================+==========================================================+========================================================+ -| Aqueous | 0.9798 + 0.02986\ *T* + 0.0004381\ *T*\ :sup:`2` | 1.172+ 0.03443\ *T* + 0.0005048\ *T*\ :sup:`2` | -+----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ -| Gaseous | 0.1875 + 0.0013\ *T* | 0.1759 + 0.0011\ *T* | -+----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ +(m:sup:`2` s\ :sup:`-1`)) as described by Lerman et al. (1979) and applied by Wania et al. (2010) (:numref:`Table Temperature dependence of aqueous and gaseous diffusion`). + +.. _Table Temperature dependence of aqueous and gaseous diffusion: + +.. table:: Temperature dependence of aqueous and gaseous diffusion coefficients for CH\ :sub:`4` and O\ :sub:`2` + + +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ + | :math:`{D}_{0}` (m\ :sup:`2` s\ :sup:`-1`) | CH\ :sub:`4` | O\ :sub:`2` | + +==========================================================+==========================================================+========================================================+ + | Aqueous | 0.9798 + 0.02986\ *T* + 0.0004381\ *T*\ :sup:`2` | 1.172+ 0.03443\ *T* + 0.0005048\ *T*\ :sup:`2` | + +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ + | Gaseous | 0.1875 + 0.0013\ *T* | 0.1759 + 0.0011\ *T* | + +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ Gaseous diffusivity in soils also depends on the molecular diffusivity, soil structure, porosity, and organic matter content. Moldrup et al. diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index 28f43fce9a..c451a6dbef 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -14,7 +14,7 @@ where :math:`\vec{S}` is the net solar flux absorbed by the vegetation Solar Fluxes ---------------- -Figure 4.1 illustrates the direct beam and diffuse fluxes in the canopy. +:numref:`Figure Radiation Schematic` illustrates the direct beam and diffuse fluxes in the canopy. :math:`I\, \uparrow _{\Lambda }^{\mu }` and :math:`I\, \uparrow _{\Lambda }` are the upward diffuse fluxes, per unit incident direct beam and diffuse flux (section 3.1). @@ -32,14 +32,17 @@ albedos (section 3.2). :math:`L` and :math:`S` are the exposed leaf area index and stem area index (section 2.1.4). :math:`K` is the optical depth of direct beam per unit leaf and stem area (section 3.1). -Figure 4.1. Schematic diagram of (a) direct beam radiation, (b) diffuse -solar radiation, and (c) longwave radiation absorbed, transmitted, and -reflected by vegetation and ground. +.. _Figure Radiation Schematic: + +.. figure:: image1.png + + Schematic diagram of (a) direct beam radiation, (b) diffuse + solar radiation, and (c) longwave radiation absorbed, transmitted, and + reflected by vegetation and ground. For clarity, terms involving :math:`T^{n+1} -T^{n}` are not shown in (c). -.. image:: image1.png The total solar radiation absorbed by the vegetation and ground is @@ -169,7 +172,7 @@ longwave radiation (W m\ :sup:`-2`). The radiative temperature T_{rad} =\left(\frac{L\, \uparrow }{\sigma } \right)^{{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } where :math:`\sigma` is the Stefan-Boltzmann constant (W\ m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6). With reference to -Figure 4.1, the upward longwave radiation from the surface to the atmosphere is +:numref:`Figure Radiation Schematic`, the upward longwave radiation from the surface to the atmosphere is .. math:: :label: 4.11 diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index 083c6b651e..0a7b941359 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -106,7 +106,7 @@ temperature :math:`T_{i}` [K]; thermal conductivity :math:`\lambda _{i}` [W m\ :sup:`-1` K\ :sup:`-1`]; volumetric heat capacity :math:`c_{i}` [J m\ :sup:`-3` K\ :sup:`-1`]) are defined for soil layers at the node depths -(Figure 6.1) and for snow layers at the layer midpoints. When present, +(:numref:`Figure Soil Temperature Schematic`) and for snow layers at the layer midpoints. When present, snow occupies a fraction of a grid cell’s area, therefore snow depth represents the thickness of the snowpack averaged over only the snow covered area. The grid cell average snow depth is related to the depth @@ -130,7 +130,8 @@ where the thermal conductivity at the interface \lambda \left[z_{h,\, i} \right]=\left\{\begin{array}{l} {\frac{\lambda _{i} \lambda _{i+1} \left(z_{i+1} -z_{i} \right)}{\lambda _{i} \left(z_{i+1} -z_{h,\, i} \right)+\lambda _{i+1} \left(z_{h,\, i} -z_{i} \right)} \qquad i=snl+1,\ldots ,N_{levgrnd} -1} \\ {0\qquad i=N_{levgrnd} } \end{array}\right\}. -These equations are derived, with reference to Figure 6.1, assuming +These equations are derived, with reference to +:numref:`Figure Soil Temperature Schematic`, assuming that the heat flux from :math:`i` (depth :math:`z_{i}` ) to the interface between :math:`i` and :math:`i+1` (depth :math:`z_{h,\, i}` ) equals the heat flux from the interface to :math:`i+1` (depth diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index fad229fe7c..e6f40c34ef 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -345,12 +345,14 @@ discussions new amended wood harvest targets were generated with regional targets through GLM for the RCP 6.0 and RCP 8.5 time series as described in Lawrence et al. (2012). -Figure 21.1. Schematic of land cover change impacts on CLM carbon pools -and fluxes. +.. _Figure Schematic of land cover change: -.. image:: image1.png +.. figure:: image1.png -Figure 21.2. Schematic of translation of annual UNH land units to CLM4 -plant functional types. + Schematic of land cover change impacts on CLM carbon pools and fluxes. -.. image:: image2.png +.. _Figure Schematic of translation of annual UNH land units: + +.. figure:: image2.png + + Schematic of translation of annual UNH land units to CLM4 plant functional types. diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index b95589f7b4..df42e024e9 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -103,15 +103,22 @@ climate and socioeconomic considerations. The surface dataset creation routines (see CLM4.5 User’s Guide) aggregate the data to the desired resolution. -Figure 12.1. Schematic representation of the urban land unit. +.. _Figure Schematic representation of the urban land unit: + +.. figure:: image1.png + + Schematic representation of the urban land unit. See the text for description of notation. Incident, reflected, and net solar and longwave radiation are calculated for each individual surface but are not shown for clarity. -.. image:: image1.png -Figure 12.2. Schematic of urban and atmospheric model coupling. +.. _Figure Schematic of urban and atmospheric model coupling: + +.. figure:: image2.png + + Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific @@ -129,4 +136,4 @@ absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. -.. image:: image2.png + diff --git a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst index de270ebdc6..251e1acfcd 100644 --- a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst +++ b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst @@ -31,9 +31,11 @@ maintained as a separate state variable for each tissue type. Storage reduce the complexity of accounting for transfers into and out of storage over the course of a single growing season. -Figure 14.1. Example of annual phenology cycle for seasonal deciduous. +.. _Figure annual phenology cycle: -.. image:: image1.png +.. figure:: image1.png + + Example of annual phenology cycle for seasonal deciduous. 14.1.1 Onset Periods ^^^^^^^^^^^^^^^^^^^^ From 9b9e27d1a21af2007037f38d3a7f7d381b3524c0 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 30 May 2017 15:39:12 -0600 Subject: [PATCH 028/255] Chapter 15 urban model updates and cleanup --- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 49 +++++++++---------- 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index b95589f7b4..e53b33463f 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -5,7 +5,8 @@ Urban Model (CLMU) At the global scale, and at the coarse spatial resolution of current climate models, urbanization has negligible impact on climate. However, -the urban parameterization (CLMU; Oleson et al. 2008b,c) allows +the urban parameterization (CLMU; :ref:`Oleson et al. (2008b) `; +:ref:`Oleson et al. (2008c) `) allows simulation of the urban environment within a climate model, and particularly the temperature where people live. As such, the urban model allows scientific study of how climate change affects the urban heat @@ -13,7 +14,8 @@ island and possible urban planning and design strategies to mitigate warming (e.g., white roofs). The urban model that was released as a component of CLM4.0 is separately -described in the urban technical note (Oleson et al. 2010b). Here, we +described in the urban technical note (:ref:`Oleson et al. (2010b) `). +Here, we provide a brief overview of the urban model released as a component of CLM4.5. The main changes in the urban model from CLM4.0 to CLM4.5 are 1) an expansion of the single urban landunit to up to three landunits per @@ -28,9 +30,11 @@ calculations for the pervious road now follows CLM4.5 parameterizations. Urban areas in CLM are represented by up to three urban landunits per gridcell according to density class. The urban landunit is based on the -“urban canyon†concept of Oke (1987) in which the canyon geometry is +“urban canyon†concept of :ref:`Oke (1987) ` in which +the canyon geometry is described by building height (:math:`H`) and street width (:math:`W`) -(Figure 12.1). The canyon system consists of roofs, walls, and canyon +(:numref:`Figure schematic representation of urban`). The canyon system +consists of roofs, walls, and canyon floor. Walls are further divided into shaded and sunlit components. The canyon floor is divided into pervious (e.g., to represent residential lawns, parks) and impervious (e.g., to represent roads, parking lots, @@ -39,12 +43,13 @@ pervious fraction; instead evaporation is parameterized by a simplified bulk scheme. Each of the five urban surfaces is treated as a column within the -landunit (Figure 12.1). Radiation parameterizations account for trapping +landunit (:numref:`Figure schematic representation of urban`). +Radiation parameterizations account for trapping of solar and longwave radiation inside the canyon. Momentum fluxes are determined for the urban landunit using a roughness length and displacement height appropriate for the urban canyon and stability formulations from CLM. A one-dimensional heat conduction equation is -solved numerically for a multiple-layer (:math:`N_{levurb} =5`) column +solved numerically for a multiple-layer (:math:`N_{levurb} =10`) column to determine conduction fluxes into and out of canyon surfaces. The interior boundary conditions for roofs and walls are determined by an interior building temperature (:math:`T_{iB}` ) held between prescribed @@ -67,7 +72,8 @@ maximum ponding depth runs off The heat and moisture fluxes from each surface interact with each other through a bulk air mass that represents air in the urban canopy layer for which specific humidity (:math:`q_{ac}` ) and temperature -(:math:`T_{ac}` ) are prognosed (Figure 12.2). The air temperature can +(:math:`T_{ac}` ) are prognosed (:numref:`Figure schematic of urban and atmospheric model coupling`). +The air temperature can be compared with that from surrounding vegetated/soil (rural) surfaces in the model to ascertain heat island characteristics. As with other landunits, the CLMU is forced either with output from a host atmospheric @@ -103,30 +109,19 @@ climate and socioeconomic considerations. The surface dataset creation routines (see CLM4.5 User’s Guide) aggregate the data to the desired resolution. -Figure 12.1. Schematic representation of the urban land unit. +.. Figure 12.1. Schematic representation of the urban land unit -See the text for description of notation. Incident, reflected, and net -solar and longwave radiation are calculated for each individual surface -but are not shown for clarity. +.. _Figure schematic representation of urban: -.. image:: image1.png +.. Figure:: image1.png -Figure 12.2. Schematic of urban and atmospheric model coupling. + Schematic representation of the urban land unit. See the text for description of notation. Incident, reflected, and net solar and longwave radiation are calculated for each individual surface but are not shown for clarity. -The urban model is forced by the atmospheric model wind -(:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific -humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar -(:math:`S_{atm} \, \downarrow` ) and longwave -(:math:`L_{atm} \, \downarrow` ) radiation at reference height -:math:`z'_{atm}` (section 2.2.1). Fluxes from the urban landunit to the -atmosphere are turbulent sensible (:math:`H`) and latent heat -(:math:`\lambda E`), momentum (:math:`\tau` ), albedo -(:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and -absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature +.. Figure 12.2. Schematic of urban and atmospheric model coupling -(:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed -(:math:`u_{c}` ) within the urban canopy layer are diagnosed by the -urban model. :math:`H` is the average building height. +.. _Figure schematic of urban and atmospheric model coupling: -.. image:: image2.png +.. Figure:: image2.png + + Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section 2.2.1). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. From 0bdb352242c6bc6d4b88b67786325e3748325004 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 30 May 2017 17:46:39 -0600 Subject: [PATCH 029/255] Chapter 15 Urban model updates and cleanup --- .../References/CLM50_Tech_Note_References.rst | 12 +++ .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 80 ++++++++++++------- 2 files changed, 64 insertions(+), 28 deletions(-) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 7fb1521105..5c278d1e0f 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -221,6 +221,12 @@ biomass across multiple biogeographical regions. Ecol. Appl. 10:95-114. Busing, R.T. 2005. Tree mortality, canopy turnover, and woody detritus in old cove forests of the southern Appalachians. Ecology 86:73-84. +.. _Buzanetal2015: + +Buzan, J.R., Oleson, K., and Huber, M. 2015: Implementation and +comparison of a suite of heat stress metrics within the Community Land +Model version 4.5, Geosci. Model Dev., 8, 151-170, doi:10.5194/gmd-8-151-2015. + .. _CampbellNorman1998: Campbell, G.S., and Norman, J.M. 1998. An Introduction to Environmental @@ -1616,6 +1622,12 @@ Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen redistribution during grain growth in wheat (Triticum avestivum L.). Plant Physiol. 71:7-14. +.. _Sivak2013: + +Sivak, M. 2013. Air conditioning versus heating: climate control is more +energy demanding in Minneapolis than in Miami. Environ. Res. Lett., 8, +doi:10.1088/1748-9326/8/1/014050. + .. _Smithetal2005: Smith, A.M.S., Wooster, M.J., Drake, N.A., Dipotso, F.M. and Perry, diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 8292ea3394..35a77b901f 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -13,21 +13,6 @@ allows scientific study of how climate change affects the urban heat island and possible urban planning and design strategies to mitigate warming (e.g., white roofs). -The urban model that was released as a component of CLM4.0 is separately -described in the urban technical note (:ref:`Oleson et al. (2010b) `). -Here, we -provide a brief overview of the urban model released as a component of -CLM4.5. The main changes in the urban model from CLM4.0 to CLM4.5 are 1) -an expansion of the single urban landunit to up to three landunits per -grid cell stratified by urban density types, 2) the number of urban -layers for roofs and walls is no longer constrained to be equal to the -number of ground layers, 3) space heating and air conditioning wasteheat -factors are now set to zero by default so that the user can customize -these factors for their own application, 4) the elevation threshold used -to eliminate urban areas in the surface dataset creation routines has -been changed from 2200 meters to 2600 meters, 5) hydrologic and thermal -calculations for the pervious road now follows CLM4.5 parameterizations. - Urban areas in CLM are represented by up to three urban landunits per gridcell according to density class. The urban landunit is based on the “urban canyon†concept of :ref:`Oke (1987) ` in which @@ -50,15 +35,25 @@ determined for the urban landunit using a roughness length and displacement height appropriate for the urban canyon and stability formulations from CLM. A one-dimensional heat conduction equation is solved numerically for a multiple-layer (:math:`N_{levurb} =10`) column -to determine conduction fluxes into and out of canyon surfaces. The -interior boundary conditions for roofs and walls are determined by an -interior building temperature (:math:`T_{iB}` ) held between prescribed -maximum and minimum temperatures +to determine conduction fluxes into and out of canyon surfaces. + +A new building energy model has been developed for CLM5.0. It accounts +for the conduction of heat through interior surfaces (roof, sunlit and +shaded walls, and floors), convection (sensible heat exchange) between +interior surfaces and building air, longwave radiation exchange between +interior surfaces, and ventilation (natural infiltration and exfiltration). +Idealized HAC systems are assumed where the system capacity is infinite and +the system supplies the amount of energy needed to keep the indoor air +temperature (:math:`T_{iB}`) within maximum and minimum emperatures (:math:`T_{iB,\, \max } ,\, T_{iB,\, \min }` ), thus explicitly -resolving space heating and air conditioning fluxes. Anthropogenic -sources of waste heat (:math:`Q_{H,\, waste}` ) from air conditioning -and space heating can be optionally incorporated as modifications to the -canyon energy budget. Turbulent [sensible heat (:math:`Q_{H,\, u}` ) and +resolving space heating and air conditioning fluxes. Anthropogenic sources +of waste heat (:math:`Q_{H,\, waste}` ) from HAC that account for inefficiencies +in the heating and air conditioning equipment and from energy lost in the +conversion of primary energy sources to end use energy are derived from +:ref:`Sivak (2013) `. These sources of waste heat are incorporated +as modifications to the canyon energy budget. + +Turbulent [sensible heat (:math:`Q_{H,\, u}` ) and latent heat (:math:`Q_{E,\, u}` )] and storage (:math:`Q_{S,\, u}` ) heat fluxes and surface (:math:`T_{u,\, s}` ) and internal (:math:`T_{u,\, i=1,\, N_{levgrnd} }` ) temperatures are determined for @@ -77,7 +72,7 @@ The air temperature can be compared with that from surrounding vegetated/soil (rural) surfaces in the model to ascertain heat island characteristics. As with other landunits, the CLMU is forced either with output from a host atmospheric -model (e.g., the Community Atmosphere Model (stocktickerCAM)) or +model (e.g., the Community Atmosphere Model (CAM)) or observed forcing (e.g., reanalysis or field observations). The urban model produces sensible, latent heat, and momentum fluxes, emitted longwave, and reflected solar radiation, which are area-averaged with @@ -85,11 +80,11 @@ fluxes from non-urban “landunits†(e.g., vegetation, lakes) to supply grid cell averaged fluxes to the atmospheric model. Present day global urban extent and urban properties were developed by -Jackson et al. (2010). Urban extent, defined for four classes [tall +:ref:`Jackson et al. (2010) `. Urban extent, defined for four classes [tall building district (TBD), and high, medium, and low density (HD, MD, LD)], was derived from LandScan 2004, a population density dataset derived from census data, nighttime lights satellite observations, road -proximity, and slope (Dobson et al. 2000). The urban extent data for +proximity, and slope (:ref:`Dobson et al. 2000 `). The urban extent data for TBD, HD, and MD classes are aggregated from the original 1 km resolution to both a 0.05\ :sup:`o` by 0.05\ :sup:`o` global grid for high-resolution studies or a 0.5\ :sup:`o` by @@ -106,7 +101,7 @@ fraction, average building height, and pervious fraction of the canyon floor) properties are provided for each of the density classes. Building interior minimum and maximum temperatures are prescribed based on climate and socioeconomic considerations. The surface dataset creation -routines (see CLM4.5 User’s Guide) aggregate the data to the desired +routines (see CLM5.0 User’s Guide) aggregate the data to the desired resolution. .. Figure 12.1. Schematic representation of the urban land unit @@ -123,4 +118,33 @@ resolution. .. Figure:: image2.png - Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section 2.2.1). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. + Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section :numref:`Atmospheric Coupling`). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. + +The urban model that was first lreleased as a component of CLM4.0 is separately +described in the urban technical note (:ref:`Oleson et al. (2010b) `). +The main changes in the urban model from CLM4.0 to CLM4.5 were 1) +an expansion of the single urban landunit to up to three landunits per +grid cell stratified by urban density types, 2) the number of urban +layers for roofs and walls was no longer constrained to be equal to the +number of ground layers, 3) space heating and air conditioning wasteheat +factors were set to zero by default so that the user could customize +these factors for their own application, 4) the elevation threshold used +to eliminate urban areas in the surface dataset creation routines was +increased from 2200 meters to 2600 meters, 5) hydrologic and thermal +calculations for the pervious road followed CLM4.5 parameterizations. + +The main changes in the urban model from CLM4.5 to CLM5.0 are 1) a more +sophisticated and realistic building space heating and air conditioning +submodel that prognoses interior building air temperature and includes more +realistic space heating and air conditioning wasteheat factors (see above), 2) the maximum +building temperature (which determines air conditioning demand) is now read in +from a namelist-defined file which allows for dynamic control of this input +variable. The maximum building temperatures that are defined in +:ref:`Jackson et al. (2010) ` are implemented in year 1950 (thus +air conditioning is off in prior years) and air conditioning is turned off in year +2100 (because the buildings are not suitable for air conditioning in some extreme +global warming scenarios). These feature will be described in more detail in +a forthcoming paper. In addition, a module of heat stress indices calculated online +in the model that can be used to assess human thermal comfort for rural and urban +areas has been added. This last development is described and evaluated by +:ref:`Buzan et al. (2015) `. From a9fcbcfb792a6f63adec14e59e68d4ba0f036a1f Mon Sep 17 00:00:00 2001 From: djk2120 Date: Wed, 31 May 2017 11:08:47 -0400 Subject: [PATCH 030/255] Update PHS equations for sections 11.1-3 --- ...CLM50_Tech_Note_Plant_Hydraulic_Stress.rst | 253 ++++++++++++++++++ 1 file changed, 253 insertions(+) diff --git a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst index ed75965d41..e5541bf2b4 100644 --- a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst +++ b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst @@ -2,3 +2,256 @@ Plant Hydraulic Stress ====================== + +Hello + +.. _Plant Water Supply: + +Plant Water Supply +----------------------- + +PHS explicitly models water transport through the vegetation according to a simple hydraulic framework following Darcy's Law for porous media flow equations. The supply equations are used to solve for vegetation water potential forced by a given transpiration and the set of layer-by-layer soil water potentials. + +The water supply is discretized into segments: soil-to-root, root-to-stem, and stem-to-leaf. There are typically several (1-49) soil-to-root flows operating in parallel, one per soil layer. There are two stem-to-leaf flows operating in parallel, corresponding to the sunlit and shaded "leaves". + +In general the water fluxes (e.g. soil-to-root, root-to-stem, etc) are calculated as: + +.. math:: + :label: 11.1) + + q = kA\Delta\psi + + +:math:`q` is the flux of water (mmH\ :sub:`2`\ O) + +:math:`k` is the hydraulic conductance (s\ :sup:`-1`\ ) + +:math:`A` is the area basis (m\ :sup:`2`\ /m\ :sup:`2`\ ) + +:math:`\Delta\psi` is the gradient in water potential (mmH\ :sub:`2`\ O) + +.. math:: + :label: 11.2) + + k=k_{max}\cdot 2^{-\left(\dfrac{\psi}{p50}\right)^{c_k}} + +:math:`k_{max}` is the maximum segment conductance (s-1) + +:math:`p50` is the water potential at 50% loss of conductivity (mmH2O) + +:math:`\psi` is the water potential of the lower segment terminus (mmH2O) + +.. math:: + :label: 11.3) + + q_{1a}=k_{1a}*\mbox{LAI}_{sun}*\left(\psi_{stem}-\psi_{sunleaf} \right) + +.. math:: + :label: 11.4) + + q_{1b}=k_{1b}*\mbox{LAI}_{shade}*\left(\psi_{stem}-\psi_{shadeleaf} \right) + +.. math:: + :label: 11.5) + + k_{1a}=k_{1a,max}*2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} + +.. math:: + :label: 11.6) + + k_{1b}=k_{1b,max}*2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} + +Variables: + +:math:`LAI_{sun}` = sunlit leaf area index (m2/m2) + +:math:`LAI_{shade}` = shaded leaf area index (m2/m2) + +:math:`\psi_{stem}` = stem water potential (mmH20) + +:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH20) + +:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH20) + +Parameters: + +:math:`k_{1a,max}` = maximum leaf conductance (s-1) + +:math:`k_{1b,max}` = maximum leaf conductance (s-1) + +:math:`p50_{1}` = water potential at 50% loss of conductance (mmH2O) + +:math:`c_{k}` = vulnerability curve shape-fitting parameter (-) + +.. math:: + :label: 11.7) + + q_2=k_2 \cdot SAI \cdot \left( \psi_{root} - \psi_{stem} - \Delta \psi_z \right) + +.. math:: + :label: 11.8) + + k_2=\dfrac{k_{2,max}}{z_2} \cdot 2^{-\left(\dfrac{\psi_{root}}{p50_2}\right)^{c_k}} + +Variables: + +:math:`SAI` = stem area index (m2/m2) + +:math:`\Delta\psi_z` = gravitational potential (mmH2O) + +:math:`\psi_{root}` = root water potential (mmH2O) + +:math:`\psi_{stem}` = stem water potential (mmH2O) + +Parameters: + +:math:`k_{2,max}` = maximum stem conductivity (m/s) + +:math:`p50_2` = water potential at 50% loss of conductivity (mmH2O) + +:math:`z_2` = vegetation height (m) + +.. math:: + :label: 11.9) + + q_{3,i}=k_{3,i}*RAI*\left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right) + +.. math:: + :label: 11.10) + + RAI=\left(LAI+SAI \right)\cdot r_i \cdot f_{root-leaf} + +.. math:: + :label: 11.11) + + k_{3,i}=\dfrac{k_{root}*k_{soil-to-root}}{k_{root}+k_{soil-to-root}} + +.. math:: + :label: 11.12) + + k_{root,i}=\dfrac{k_{3,max}}{z_{3,i}}*2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}} + +.. math:: + :label: 11.13) + + k_{soil-to-root} = \dfrac{k_{soil,i}}{dx_{root,i}} + +.. math:: + :label: 11.14) + + dx_{root,i} = \left(\pi*\mbox{root-length-density}_i\right)^{-0.5} + +.. math:: + :label: 11.15) + + \mbox{root-length-density} = \dfrac{\mbox{total root length}}{\mbox{soil volume}} + +Variables: + +:math:`\Delta\psi_{z,i}` = change in gravitational potential from soil layer :math:`i` to surface (mmH2O) + +:math:`LAI` = total leaf area index (m2/m2) + +:math:`SAI` = stem area index (m2/m2) + +:math:`\psi_{soil,i}` = water potential in soil layer :math:`i` (mmH2O) + +:math:`\psi_{root}` = root water potential (mmH2O) + +:math:`z_{3,i}` = length of root tissue conducting path = soil layer depth + root lateral length (m) + +:math:`r_i` = root fraction in soil layer :math:`i` (-) + +:math:`k_{soil,i}` = Brooks-Corey soil conductivity in soil layer :math:`i` (m/s) + +Parameters: + +:math:`f_{root-leaf}` = root-to-shoot ratio (-) + +:math:`p50_3` = water potential at 50% loss of root tissue conductance (mmH2O) + +:math:`ck` = shape-fitting parameter for vulnerability curve (-) + +.. _Plant Water Demand: + +Plant Water Demand +----------------------- + +.. math:: + :label: 11.16) + + E_{sun} = E_{sun,max}*2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} + +.. math:: + :label: 11.17) + + E_{shade} = E_{shade,max}*2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}} + +.. math:: + :label: 11.18) + + B_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,B_t=1}} + +.. math:: + :label: 11.19) + + B_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,B_t=1}} + +:math:`E_{sun}` = sunlit leaf transpiration (mm/s) + +:math:`E_{shade}` = shaded leaf transpiration (mm/s) + +:math:`E_{sun,max}` = sunlit leaf transpiration absent water stress (mm/s) + +:math:`E_{shade,max}` = shaded leaf transpiration absent water stress (mm/s) + +:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH2O) + +:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH2O) + +:math:`g_{s,sun}` = stomatal conductance of water corresponding to :math:`E_{sun}` + +:math:`g_{s,shade}` = stomatal conductance of water corresponding to :math:`E_{shade}` + +:math:`g_{s,sun,max}` = stomatal conductance of water corresponding to :math:`E_{sun,max}` + +:math:`g_{s,shade,max}` = stomatal conductance of water corresponding to :math:`E_{shade,max}` + +.. _Vegetation Water Potential: + +Vegetation Water Potential +----------------------------- + +PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential at each timestep. PHS iterates to find the vegetation water potential vector :math:`\psi` that satisfies continuity in the non-linear vegetation water supply and demand equations. + +.. math:: + :label: 11.20) + + \psi=\left[\psi_{sunleaf},\psi_{shadeleaf},\psi_{stem},\psi_{root}\right] + +.. math:: + :label: 11.21) + + \begin{aligned} + E_{sun}&=q_{1a}\\ + E_{shade}&=q_{1b}\\ + E_{sun}+E_{shade}&=q_{1a}+q_{1b}\\ + &=q_2\\ + &=\sum_{i=1}^{nlevsoi}{q_{3,i}} + \end{aligned} + +The demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy equations in (11.21). + +.. math:: + :label: 11.21) + + ff + + + +Yo + + + + + From a6688bd5ff15bf17801cca034cd4b0ad57e52af6 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 31 May 2017 11:20:53 -0600 Subject: [PATCH 031/255] update Fluxes chapter --- .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 555 +++++++++--------- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 2 +- 3 files changed, 282 insertions(+), 277 deletions(-) diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 0d8d213cb4..0ffe6e43f3 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -45,12 +45,12 @@ momentum between the atmosphere at height :math:`z_{atm,\, m}` and the surface at height :math:`z_{0m} +d`. Thus, the momentum fluxes become .. math:: - :label: + :label: 5.5 \tau _{x} =-\rho _{atm} \frac{u_{atm} }{r_{am} } .. math:: - :label: + :label: 5.6 \tau _{y} =-\rho _{atm} \frac{v_{atm} }{r_{am} } . @@ -76,7 +76,7 @@ where :math:`T_{atm}` is the air temperature (K) at height m\ :sup:`-1` is the negative of the dry adiabatic lapse rate [this expression is first-order equivalent to :math:`\theta _{atm} =T_{atm} \left({P_{srf} \mathord{\left/ {\vphantom {P_{srf} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } \right)^{{R_{da} \mathord{\left/ {\vphantom {R_{da} C_{p} }} \right. \kern-\nulldelimiterspace} C_{p} } }` -(Stull 1988), where :math:`P_{srf}` is the surface pressure (Pa), +(:ref:`Stull 1988 `), where :math:`P_{srf}` is the surface pressure (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`R_{da}` is the gas constant for dry air (J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical constants`)]. By definition, :math:`\theta _{s} =T_{s}` . The density of moist air (kg m\ :sup:`-3`) is @@ -109,7 +109,7 @@ from Monin-Obukhov similarity applied to the surface layer. This theory states that when scaled appropriately, the dimensionless mean horizontal wind speed, mean potential temperature, and mean specific humidity profile gradients depend on unique functions of -:math:`\zeta =\frac{z-d}{L}` (Zeng et al. 1998) as +:math:`\zeta =\frac{z-d}{L}` (:ref:`Zeng et al. 1998`) as .. math:: :label: 5.10 @@ -162,8 +162,7 @@ components :math:`\overline{u'w'}=-\frac{\tau _{x} }{\rho _{atm} }` and :math:`H` is the sensible heat flux (W m\ :sup:`-2`) and :math:`E` is the water vapor flux (kg m\ :sup:`-2` s\ :sup:`-1`). -The dimensionless length scale :math:`L` is the Monin-Obukhov length -defined as +The length scale :math:`L` is the Monin-Obukhov length defined as .. math:: :label: 5.16 @@ -179,7 +178,7 @@ stable conditions. :math:`L<0` indicates unstable conditions. :math:`\theta _{v*}` is defined as .. math:: - :label: ZEqnNum632600 + :label: 5.17 \theta _{v*} u_{*} =\left[\theta _{*} \left(1+0.61q_{atm} \right)+0.61\overline{\theta _{atm} }q_{*} \right]u_{*} @@ -246,7 +245,7 @@ Defining the surface values and the atmospheric values at :math:`z_{2} =z_{atm,\, x}` .. math:: - :label: ZEqnNum228149 + :label: 5.24 \left|{\it u}\right|_{2} =V_{a} {\rm =\; }\sqrt{u_{atm}^{2} +v_{atm}^{2} +U_{c}^{2} } \ge 1, @@ -280,15 +279,18 @@ surface fluxes as follows .. math:: :label: 5.28 - {U_{c} = 0\ \qquad \zeta \ge {\rm 0} {\rm (stable)}} \\ - {U_{c} = \beta w_{\*} \qquad \zeta <0 {\rm (unstable})} + U_{c} = \left\{ + \begin{array}{ll} + 0 & \qquad \zeta \ge {\rm 0} \quad {\rm (stable)} \\ + \beta w_{*} & \qquad \zeta < 0 \quad {\rm (unstable)} + \end{array} \right\} -where :math:`w_{\*}` is the convective velocity scale +where :math:`w_{*}` is the convective velocity scale .. math:: :label: 5.29 - w_{\*} =\left(\frac{-gu_{\*} \theta _{v*} z_{i} }{\overline{\theta _{v,\, atm} }} \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } , + w_{*} =\left(\frac{-gu_{\*} \theta _{v*} z_{i} }{\overline{\theta _{v,\, atm} }} \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } , :math:`z_{i} =1000` is the convective boundary layer height (m), and :math:`\beta =1`. @@ -297,14 +299,24 @@ The momentum flux gradient relations are (:ref:`Zeng et al. 1998 ` .. math:: :label: 5.30 - \begin{array}{l} {\phi _{m} \left(\zeta \right)=0.7k^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } \qquad {\rm for\; }\zeta <-1.574{\rm \; (very\; unstable)}} \\ {\phi _{m} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } \qquad {\rm for\; -1.574}\le \zeta <0{\rm \; (unstable)}} \\ {\phi _{m} \left(\zeta \right)=1+5\zeta \qquad {\rm for\; }0\le \zeta \le 1{\rm \; (stable)}} \\ {\phi _{m} \left(\zeta \right)=5+\zeta \qquad {\rm for\; }\zeta {\rm >1\; (very\; stable).}} \end{array} + \begin{array}{llr} + \phi _{m} \left(\zeta \right)=0.7k^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } & \qquad {\rm for\; }\zeta <-1.574 & \ {\rm \; (very\; unstable)} \\ + \phi _{m} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 4}} \right. \kern-\nulldelimiterspace} 4} } & \qquad {\rm for\; -1.574}\le \zeta <0 & \ {\rm \; (unstable)} \\ + \phi _{m} \left(\zeta \right)=1+5\zeta & \qquad {\rm for\; }0\le \zeta \le 1& \ {\rm \; (stable)} \\ + \phi _{m} \left(\zeta \right)=5+\zeta & \qquad {\rm for\; }\zeta >1 & \ {\rm\; (very\; stable).} + \end{array} The sensible and latent heat flux gradient relations are (:ref:`Zeng et al. 1998 `) .. math:: :label: 5.31 - \begin{array}{l} {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=0.9k^{{4\mathord{\left/ {\vphantom {4 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } \qquad {\rm for\; }\zeta <-0.465{\rm \; (very\; unstable)}} \\ {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 2}} \right. \kern-\nulldelimiterspace} 2} } \qquad {\rm for\; -0.465}\le \zeta <0{\rm \; (unstable)}} \\ {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=1+5\zeta \qquad {\rm for\; }0\le \zeta \le 1{\rm \; (stable)}} \\ {\phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=5+\zeta \qquad {\rm for\; }\zeta {\rm >1\; (very\; stable).}} \end{array} + \begin{array}{llr} + \phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=0.9k^{{4\mathord{\left/ {\vphantom {4 3}} \right. \kern-\nulldelimiterspace} 3} } \left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } & \qquad {\rm for\; }\zeta <-0.465 & \ {\rm \; (very\; unstable)} \\ + \phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=\left(1-16\zeta \right)^{-{1\mathord{\left/ {\vphantom {1 2}} \right. \kern-\nulldelimiterspace} 2} } & \qquad {\rm for\; -0.465}\le \zeta <0 & \ {\rm \; (unstable)} \\ + \phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=1+5\zeta & \qquad {\rm for\; }0\le \zeta \le 1 & \ {\rm \; (stable)} \\ + \phi _{h} \left(\zeta \right)=\phi _{w} \left(\zeta \right)=5+\zeta & \qquad {\rm for\; }\zeta >1 & \ {\rm \; (very\; stable).} + \end{array} To ensure continuous functions of :math:`\phi _{m} \left(\zeta \right)`, @@ -321,28 +333,28 @@ yield wind profiles for the following conditions: Very unstable :math:`\left(\zeta <-1.574\right)` .. math:: - :label: ZEqnNum566843 + :label: 5.32 V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{\zeta _{m} L}{z_{0m} } -\psi _{m} \left(\zeta _{m} \right)\right]+1.14\left[\left(-\zeta \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } -\left(-\zeta _{m} \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } \right]+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right\} Unstable :math:`\left(-1.574\le \zeta <0\right)` .. math:: - :label: ZEqnNum309568 + :label: 5.33 V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, m} -d}{z_{0m} } -\psi _{m} \left(\zeta \right)\right]+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right\} Stable :math:`\left(0\le \zeta \le 1\right)` .. math:: - :label: ZEqnNum973766 + :label: 5.34 V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, m} -d}{z_{0m} } +5\zeta \right]-5\frac{z_{0m} }{L} \right\} Very stable :math:`\left(\zeta >1\right)` .. math:: - :label: ZEqnNum310559 + :label: 5.35 V_{a} =\frac{u_{*} }{k} \left\{\left[\ln \frac{L}{z_{0m} } +5\right]+\left[5\ln \zeta +\zeta -1\right]-5\frac{z_{0m} }{L} \right\} @@ -362,14 +374,14 @@ The potential temperature profiles are: Very unstable :math:`\left(\zeta <-0.465\right)` .. math:: - :label: ZEqnNum382106 + :label: 5.37 \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{\zeta _{h} L}{z_{0h} } -\psi _{h} \left(\zeta _{h} \right)\right]+0.8\left[\left(-\zeta _{h} \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } -\left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } \right]+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right\} Unstable :math:`\left(-0.465\le \zeta <0\right)` .. math:: - :label: ZEqnNum767002 + :label: 5.38 \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{z_{atm,\, h} -d}{z_{0h} } -\psi _{h} \left(\zeta \right)\right]+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right\} @@ -377,14 +389,14 @@ Unstable :math:`\left(-0.465\le \zeta <0\right)` Stable :math:`\left(0\le \zeta \le 1\right)` .. math:: - :label: ZEqnNum556410 + :label: 5.39 \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{z_{atm,\, h} -d}{z_{0h} } +5\zeta \right]-5\frac{z_{0h} }{L} \right\} Very stable :math:`\left(\zeta >1\right)` .. math:: - :label: ZEqnNum846197 + :label: 5.40 \theta _{atm} -\theta _{s} =\frac{\theta _{*} }{k} \left\{\left[\ln \frac{L}{z_{0h} } +5\right]+\left[5\ln \zeta +\zeta -1\right]-5\frac{z_{0h} }{L} \right\}. @@ -393,28 +405,28 @@ The specific humidity profiles are: Very unstable :math:`\left(\zeta <-0.465\right)` .. math:: - :label: ZEqnNum299834 + :label: 5.41 q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{\zeta _{w} L}{z_{0w} } -\psi _{w} \left(\zeta _{w} \right)\right]+0.8\left[\left(-\zeta _{w} \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } -\left(-\zeta \right)^{{-1\mathord{\left/ {\vphantom {-1 3}} \right. \kern-\nulldelimiterspace} 3} } \right]+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right\} Unstable :math:`\left(-0.465\le \zeta <0\right)` .. math:: + :label: 5.42 - \label{ZEqnNum142122} q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, w} -d}{z_{0w} } -\psi _{w} \left(\zeta \right)\right]+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right\} Stable :math:`\left(0\le \zeta \le 1\right)` .. math:: - :label: ZEqnNum350694 + :label: 5.43 q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{z_{atm,\, w} -d}{z_{0w} } +5\zeta \right]-5\frac{z_{0w} }{L} \right\} Very stable :math:`\left(\zeta >1\right)` .. math:: - :label: ZEqnNum211437 + :label: 5.44 q_{atm} -q_{s} =\frac{q_{*} }{k} \left\{\left[\ln \frac{L}{z_{0w} } +5\right]+\left[5\ln \zeta +\zeta -1\right]-5\frac{z_{0w} }{L} \right\} @@ -434,7 +446,7 @@ using atmospheric and surface values for :math:`\left|{\it u}\right|`, bulk Richardson number .. math:: - :label: ZEqnNum750428} + :label: 5.46 R_{iB} =\frac{\theta _{v,\, atm} -\theta _{v,\, s} }{\overline{\theta _{v,\, atm} }} \frac{g\left(z_{atm,\, m} -d\right)}{V_{a}^{2} } @@ -455,27 +467,35 @@ stable conditions to determine :math:`\psi _{m} \left(\zeta \right)` and guess for :math:`\zeta` and thus :math:`L` from .. math:: + :label: 5.48 - \label{ZEqnNum979946} - \begin{array}{l} {\zeta =\frac{R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)}{1-5\min \left(R_{iB} ,0.19\right)} \qquad 0.01\le \zeta \le 2\qquad {\rm for\; }R_{iB} \ge 0{\rm \; (neutral\; or\; stable)}} \\ {\zeta =R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)\qquad -100\le \zeta \le -0.01\qquad {\rm for\; }R_{iB} <0{\rm \; (unstable)}} \end{array}. + \begin{array}{lcr} + \zeta =\frac{R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)}{1-5\min \left(R_{iB} ,0.19\right)} & \qquad 0.01\le \zeta \le 2 & \qquad {\rm for\; }R_{iB} \ge 0 {\rm \; (neutral\; or\; stable)} \\ + \zeta =R_{iB} \ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right) & \qquad -100\le \zeta \le -0.01 & \qquad {\rm for\; }R_{iB} <0 \ {\rm \; (unstable)} + \end{array}. Upon iteration (section :numref:`Numerical Implementation`), the following is used to determine :math:`\zeta` and thus :math:`L` .. math:: + :label: 5.49 - \label{ZEqnNum153243} \zeta =\frac{\left(z_{atm,\, m} -d\right)kg\theta _{v*} }{u_{*}^{2} \overline{\theta _{v,\, atm} }} where -.. math:: \begin{array}{l} {0.01\le \zeta \le 2\qquad {\rm for\; }\zeta \ge 0{\rm \; (neutral\; or\; stable)}} \\ {{\rm -100}\le \zeta \le {\rm -0.01}\qquad {\rm for\; }\zeta <0{\rm \; (unstable)}} \end{array}. +.. math:: + + \begin{array}{cr} + 0.01\le \zeta \le 2 & \qquad {\rm for\; }\zeta \ge 0{\rm \; (neutral\; or\; stable)} \\ + {\rm -100}\le \zeta \le {\rm -0.01} & \qquad {\rm for\; }\zeta <0{\rm \; (unstable)} + \end{array}. The difference in virtual potential air temperature between the reference height and the surface is .. math:: - :label: ZEqnNum516498 + :label: 5.50 \theta _{v,\, atm} -\theta _{v,\, s} =\left(\theta _{atm} -\theta _{s} \right)\left(1+0.61q_{atm} \right)+0.61\overline{\theta _{atm} }\left(q_{atm} -q_{s} \right). @@ -483,39 +503,39 @@ The momentum, sensible heat, and water vapor fluxes between the surface and the atmosphere can also be written in the form .. math:: - :label: ZEqnNum567382 + :label: 5.51 \tau _{x} =-\rho _{atm} \frac{\left(u_{atm} -u_{s} \right)}{r_{am} } .. math:: - :label: ZEqnNum615113 + :label: 5.52 \tau _{y} =-\rho _{atm} \frac{\left(v_{atm} -v_{s} \right)}{r_{am} } .. math:: - :label: ZEqnNum588623 + :label: 5.53 H=-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -\theta _{s} \right)}{r_{ah} } .. math:: - :label: ZEqnNum154565 + :label: 5.54 E=-\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } where the aerodynamic resistances (s m\ :sup:`-1`) are .. math:: - :label: ZEqnNum660763 + :label: 5.55 r_{am} =\frac{V_{a} }{u_{*}^{2} } =\frac{1}{k^{2} V_{a} } \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right]^{2} .. math:: - :label: ZEqnNum193138 + :label: 5.56 \begin{array}{l} {r_{ah} =\frac{\theta _{atm} -\theta _{s} }{\theta _{*} u_{*} } =\frac{1}{k^{2} V_{a} } \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right]} \\ {\qquad \left[\ln \left(\frac{z_{atm,\, h} -d}{z_{0h} } \right)-\psi _{h} \left(\frac{z_{atm,\, h} -d}{L} \right)+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right]} \end{array} .. math:: - :label: ZEqnNum382229 + :label: 5.57 \begin{array}{l} {r_{aw} =\frac{q_{atm} -q_{s} }{q_{*} u_{*} } =\frac{1}{k^{2} V_{a} } \left[\ln \left(\frac{z_{atm,\, m} -d}{z_{0m} } \right)-\psi _{m} \left(\frac{z_{atm,\, m} -d}{L} \right)+\psi _{m} \left(\frac{z_{0m} }{L} \right)\right]} \\ {\qquad \left[\ln \left(\frac{z_{atm,\, {\it w}} -d}{z_{0w} } \right)-\psi _{w} \left(\frac{z_{atm,\, w} -d}{L} \right)+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right]} \end{array}. @@ -523,7 +543,7 @@ A 2-m height “screen†temperature is useful for comparison with observations .. math:: - :label: ZEqnNum664652 + :label: 5.58 T_{2m} =\theta _{s} +\frac{\theta _{*} }{k} \left[\ln \left(\frac{2+z_{0h} }{z_{0h} } \right)-\psi _{h} \left(\frac{2+z_{0h} }{L} \right)+\psi _{h} \left(\frac{z_{0h} }{L} \right)\right] @@ -532,14 +552,14 @@ for sensible heat (:math:`z_{0h} +d`). Similarly, a 2-m height specific humidity is defined as .. math:: - :label: ZEqnNum735237 + :label: 5.59 q_{2m} =q_{s} +\frac{q_{*} }{k} \left[\ln \left(\frac{2+z_{0w} }{z_{0w} } \right)-\psi _{w} \left(\frac{2+z_{0w} }{L} \right)+\psi _{w} \left(\frac{z_{0w} }{L} \right)\right]. Relative humidity is .. math:: - :label: ZEqnNum299365 + :label: 5.60 RH_{2m} =\min \left(100,\, \frac{q_{2m} }{q_{sat}^{T_{2m} } } \times 100\right) @@ -570,7 +590,7 @@ water covered, so that the sensible heat flux :math:`H_{g}` (W m\ :sup:`-2`) is, with reference to :numref:`Figure Schematic diagram of sensible heat fluxes`, .. math:: - :label: ZEqnNum726771 + :label: 5.62 H_{g} =\left(1-f_{sno} -f_{h2osfc} \right)H_{soil} +f_{sno} H_{snow} +f_{h2osfc} H_{h2osfc} @@ -605,7 +625,7 @@ The water vapor flux :math:`E_{g}` (kg m\ :sup:`-2` s\ :sup:`-1`) is, with refe :numref:`Figure Schematic diagram of latent heat fluxes`, .. math:: - :label: ZEqnNum419297 + :label: 5.66 E_{g} =\left(1-f_{sno} -f_{h2osfc} \right)E_{soil} +f_{sno} E_{snow} +f_{h2osfc} E_{h2osfc} @@ -631,12 +651,12 @@ resistance to water vapor transfer (s m\ :sup:`-1`). The specific humidities of :math:`q_{h2osfc}` are assumed to be at the saturation specific humidity of their respective temperatures .. math:: - :label: 5.70) + :label: 5.70 q_{sno} =q_{sat}^{T_{snl+1} } .. math:: - :label: 5.71) + :label: 5.71 q_{h2osfc} =q_{sat}^{T_{h2osfc} } @@ -644,17 +664,17 @@ The specific humidity of the soil surface :math:`q_{soil}` is assumed to be proportional to the saturation specific humidity .. math:: - :label: 5.72) + :label: 5.72 q_{soil} =\alpha _{soil} q_{sat}^{T_{1} } where :math:`q_{sat}^{T_{1} }` is the saturated specific humidity at the soil surface temperature :math:`T_{1}` (section :numref:`Saturation Vapor Pressure`). The factor :math:`\alpha _{soil}` is a function of the surface soil water matric -potential :math:`\psi` as in Philip (1957) +potential :math:`\psi` as in :ref:`Philip (1957)` .. math:: - :label: 5.73) + :label: 5.73 \alpha _{soil} =\exp \left(\frac{\psi _{1} g}{1\times 10^{3} R_{wv} T_{1} } \right) @@ -664,7 +684,7 @@ gravitational acceleration (m s\ :sup:`-2`) (:numref:`Table Physical constants`) layer (mm). The soil water matric potential :math:`\psi _{1}` is .. math:: - :label: 5.74) + :label: 5.74 \psi _{1} =\psi _{sat,\, 1} s_{1}^{-B_{1} } \ge -1\times 10^{8} @@ -676,7 +696,7 @@ and :math:`s_{1}` is the wetness of the top soil layer with respect to saturati The surface wetness :math:`s_{1}` is a function of the liquid water and ice content .. math:: - :label: 5.75) + :label: 5.75 s_{1} =\frac{1}{\Delta z_{1} \theta _{sat,\, 1} } \left[\frac{w_{liq,\, 1} }{\rho _{liq} } +\frac{w_{ice,\, 1} }{\rho _{ice} } \right]\qquad 0.01\le s_{1} \le 1.0 @@ -693,22 +713,22 @@ prevents large increases (decreases) in :math:`q_{soil}` for small increases (decreases) in soil moisture in very dry soils. The resistance to water vapor transfer occurring within the soil matrix -:math:`r_{soil}` is +:math:`r_{soil}` (s m\ :sup:`-1`) is .. math:: - :label: 5.76) + :label: 5.76 r_{soil} = \frac{DSL}{D_{v} \tau} -where :math:`DSL` is the thickness of the dry surface layer, :math:`D_{v}` -is the molecular diffusivity of water vapor in air and :math:`\tau` -describes the tortuosity of the vapor flow paths through +where :math:`DSL` is the thickness of the dry surface layer (m), :math:`D_{v}` +is the molecular diffusivity of water vapor in air (m\ :sup:`2` s\ :sup:`-2`) +and :math:`\tau` (*unitless*) describes the tortuosity of the vapor flow paths through the soil matrix (:ref:`Swenson and Lawrence 2014 `). The thickness of the dry surface layer is given by .. math:: - :label: 5.77) + :label: 5.77 DSL = \begin{array}{lr} @@ -719,44 +739,47 @@ The thickness of the dry surface layer is given by where :math:`D_{max}` is a parameter specifying the length scale of the maximum DSL thickness (default value = 15 mm), -:math:`\theta_{init}` is the moisture value at which the DSL initiates, -:math:`\theta_{1}` is the moisture value of the top model soil layer, -and :math:`\theta_{air}` is the 'air dry' soil moisture value -(:ref:`Dingman 2002 `): +:math:`\theta_{init}` (mm\ :sup:`3` mm\ :sup:`-3`) is the moisture value +at which the DSL initiates, :math:`\theta_{1}` (mm\ :sup:`3` mm\ :sup:`-3`) +is the moisture value of the top model soil layer, and +:math:`\theta_{air}` (mm\ :sup:`3` mm\ :sup:`-3`) is the 'air dry' soil +moisture value (:ref:`Dingman 2002 `): .. math:: - :label: 5.78) + :label: 5.78 \theta_{air} = \Phi \left( \frac{\Psi_{sat}}{\Psi_{air}} \right)^{\frac{1}{B_{1}}} \ . -where :math:`\Phi` is the porosity, :math:`\Psi_{sat}` is the saturated -soil matric potential, :math:`\Psi_{air} = 10^{7}` mm is the air dry -matric potential, and :math:`B_{1}` is a function of soil texture (section +where :math:`\Phi` is the porosity (mm\ :sup:`3` mm\ :sup:`-3`), +:math:`\Psi_{sat}` is the saturated soil matric potential (mm), +:math:`\Psi_{air} = 10^{7}` mm is the air dry matric potential, and +:math:`B_{1}` is a function of soil texture (section :numref:`Hydraulic Properties`). The soil tortuosity is .. math:: - :label: 5.79) + :label: 5.79 \tau = \Phi^{2}_{air}\left(\frac{\Phi_{air}}{\Phi}\right)^{\frac{3}{B_{1}}} -where :math:`\Phi_{air}` is the air filled pore space +where :math:`\Phi_{air}` (mm\ :sup:`3` mm\ :sup:`-3`) is the air filled pore space .. math:: - :label: 5.80) + :label: 5.80 \Phi_{air} = \Phi - \theta_{air} \ . :math:`D_{v}` depends on temperature .. math:: - :label: 5.81) + :label: 5.81 D_{v} = 2.12 \times 10^{-5} \left(\frac{T_{1}}{T_{f}}\right)^{1.75} \ . -where :math:`T_{1}` is the temperature of the top soil layer and -:math:`T_{f}` is the freezing temperature of water (:numref:`Table Physical Constants`). +where :math:`T_{1}` (K) is the temperature of the top soil layer and +:math:`T_{f}` (K) is the freezing temperature of water +(:numref:`Table Physical Constants`). The roughness lengths used to calculate :math:`r_{am}` , :math:`r_{ah}` , and :math:`r_{aw}` are :math:`z_{0m} =z_{0m,\, g}` , @@ -774,7 +797,7 @@ across the interfacial sublayer. The following relation from :ref:`Zeng and Dickinson 1998 ` .. math:: - :label: ZEqnNum844212 + :label: 5.82 z_{0h,\, g} =z_{0w,\, g} =z_{0m,\, g} e^{-a\left({u_{*} z_{0m,\, g} \mathord{\left/ {\vphantom {u_{*} z_{0m,\, g} \upsilon }} \right. \kern-\nulldelimiterspace} \upsilon } \right)^{0.45} } @@ -787,43 +810,43 @@ The numerical solution for the fluxes of momentum, sensible heat, and water vapor flux from non-vegetated surfaces proceeds as follows: #. An initial guess for the wind speed :math:`V_{a}` is obtained from - eq. assuming an initial convective velocity :math:`U_{c} =0` m + :eq:`5.24` assuming an initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from - eq. ) and :math:`U_{c} =0.5` for unstable conditions + :eq:`5.50` ) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). #. An initial guess for the Monin-Obukhov length :math:`L` is obtained - from the bulk Richardson number using eqs. and . + from the bulk Richardson number using :eq:`5.46` and :eq:`5.48`. #. The following system of equations is iterated three times: -#. Friction velocity :math:`u_{*}` (eqs. , , , ) +#. Friction velocity :math:`u_{*}` (:eq:`5.32`, :eq:`5.33`, :eq:`5.34`, :eq:`5.35`) -#. Potential temperature scale :math:`\theta _{*}` (eqs. , , , ) +#. Potential temperature scale :math:`\theta _{*}` (:eq:`5.37` , :eq:`5.38`, :eq:`5.39`, :eq:`5.40`) -#. Humidity scale :math:`q_{*}` (eqs. , , , ) +#. Humidity scale :math:`q_{*}` (:eq:`5.41`, :eq:`5.42`, :eq:`5.43`, :eq:`5.44`) #. Roughness lengths for sensible :math:`z_{0h,\, g}` and latent heat - :math:`z_{0w,\, g}` (eq. ) + :math:`z_{0w,\, g}` (:eq:`5.82` ) -#. Virtual potential temperature scale :math:`\theta _{v*}` (eq. ) +#. Virtual potential temperature scale :math:`\theta _{v*}` ( :eq:`5.17`) -#. Wind speed including the convective velocity, :math:`V_{a}` (eq. ) +#. Wind speed including the convective velocity, :math:`V_{a}` ( :eq:`5.24`) -#. Monin-Obukhov length :math:`L` (eq. ) +#. Monin-Obukhov length :math:`L` (:eq:`5.49`) #. Aerodynamic resistances :math:`r_{am}` , :math:`r_{ah}` , and - :math:`r_{aw}` (eqs. , , ) + :math:`r_{aw}` (:eq:`5.55`, :eq:`5.56`, :eq:`5.57`) -#. Momentum fluxes :math:`\tau _{x}` , :math:`\tau _{y}` (eqs. , ) +#. Momentum fluxes :math:`\tau _{x}` , :math:`\tau _{y}` (:eq:`5.5`, :eq:`5.6`) -#. Sensible heat flux :math:`H_{g}` (eq. ) +#. Sensible heat flux :math:`H_{g}` (:eq:`5.62`) -#. Water vapor flux :math:`E_{g}` (eq. ) +#. Water vapor flux :math:`E_{g}` (:eq:`5.66`) #. 2-m height air temperature :math:`T_{2m}` and specific humidity - :math:`q_{2m}` (eqs. , ) + :math:`q_{2m}` (:eq:`5.58` , :eq:`5.59`) The partial derivatives of the soil surface fluxes with respect to ground temperature, which are needed for the soil temperature calculations (section @@ -831,19 +854,19 @@ ground temperature, which are needed for the soil temperature calculations (sect (section :numref:`Update of Ground Sensible and Latent Heat Fluxes`), are .. math:: - :label: ZEqnNum806472 + :label: 5.83 \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r_{ah} } .. math:: - :label: ZEqnNum497230 + :label: 5.84 \frac{\partial E_{g} }{\partial T_{g} } =\frac{\beta _{soi} \rho _{atm} }{r_{aw} } \frac{dq_{g} }{dT_{g} } where .. math:: - :label: 5.82) + :label: 5.85 \frac{dq_{g} }{dT_{g} } =\left(1-f_{sno} -f_{h2osfc} \right)\alpha _{soil} \frac{dq_{sat}^{T_{soil} } }{dT_{soil} } +f_{sno} \frac{dq_{sat}^{T_{sno} } }{dT_{sno} } +f_{h2osfc} \frac{dq_{sat}^{T_{h2osfc} } }{dT_{h2osfc} } . @@ -883,39 +906,41 @@ at height :math:`z_{0h} +d` and the atmosphere at height from the vegetation :math:`H_{v}` and the ground :math:`H_{g}` .. math:: - :label: ZEqnNum550014 + :label: 5.86 H=H_{v} +H_{g} where, with reference to :numref:`Figure Schematic diagram of sensible heat fluxes`, .. math:: - :label: 5.84) + :label: 5.87 H=-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{s} \right)}{r_{ah} } .. math:: - :label: ZEqnNum675188 + :label: 5.88 H_{v} =-\rho _{atm} C_{p} \left(T_{s} -T_{v} \right)\frac{\left(L+S\right)}{r_{b} } .. math:: - :label: ZEqnNum293573 + :label: 5.89 - H_{g} =\left(1-f_{sno} -f_{h2osfc} \right)H_{soil} +f_{sno} H_{snow} +f_{h2osfc} H_{h2osfc} + H_{g} =\left(1-f_{sno} -f_{h2osfc} \right)H_{soil} +f_{sno} H_{snow} +f_{h2osfc} H_{h2osfc} \ , + +where .. math:: - :label: 5.87) + :label: 5.90 H_{soil} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{1} \right)}{r_{ah} ^{{'} } } .. math:: - :label: 5.88) + :label: 5.91 H_{sno} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{snl+1} \right)}{r_{ah} ^{{'} } } .. math:: - :label: 5.89) + :label: 5.92 H_{h2osfc} =-\rho _{atm} C_{p} \frac{\left(T_{s} -T_{h2osfc} \right)}{r_{ah} ^{{'} } } @@ -948,27 +973,28 @@ height :math:`z_{0h} ^{{'} }` and the canopy air at height Figure Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. -Equations - can be solved for the canopy air temperature :math:`T_{s}` +Equations :eq:`5.86` - :eq:`5.89` can be solved for the canopy air +temperature :math:`T_{s}` .. math:: - :label: ZEqnNum103571 + :label: 5.93 T_{s} =\frac{c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} +c_{v}^{h} T_{v} }{c_{a}^{h} +c_{g}^{h} +c_{v}^{h} } where .. math:: - :label: ZEqnNum298904 + :label: 5.94 c_{a}^{h} =\frac{1}{r_{ah} } .. math:: - :label: ZEqnNum991533 + :label: 5.95 c_{g}^{h} =\frac{1}{r_{ah} ^{{'} } } .. math:: - :label: ZEqnNum284616 + :label: 5.96 c_{v}^{h} =\frac{\left(L+S\right)}{r_{b} } @@ -976,22 +1002,22 @@ are the sensible heat conductances from the canopy air to the atmosphere, the ground to canopy air, and leaf surface to canopy air, respectively (m s\ :sup:`-1`). -When the expression for :math:`T_{s}` is substituted into equation :eq:`ZEqnNum675188`, +When the expression for :math:`T_{s}` is substituted into equation :eq:`5.88`, the sensible heat flux from vegetation :math:`H_{v}` is a function of :math:`\theta _{atm}` , :math:`T_{g}` , and :math:`T_{v}` .. math:: - :label: ZEqnNum362496 + :label: 5.97 - H_{v} =-\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} -\left(c_{a}^{h} +c_{g}^{h} \right)T_{v} \right]\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . + H_{v} = -\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} -\left(c_{a}^{h} +c_{g}^{h} \right)T_{v} \right]\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . Similarly, the expression for :math:`T_{s}` can be substituted into equation to obtain the sensible heat flux from ground :math:`H_{g}` .. math:: - :label: ZEqnNum527667 + :label: 5.98 - H_{g} =-\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{v}^{h} T_{v} -\left(c_{a}^{h} +c_{v}^{h} \right)T_{g} \right]\frac{c_{g}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . + H_{g} = -\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{v}^{h} T_{v} -\left(c_{a}^{h} +c_{v}^{h} \right)T_{g} \right]\frac{c_{g}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . The air within the canopy is assumed to have negligible capacity to store water vapor so that the water vapor flux :math:`E` between the @@ -1000,41 +1026,43 @@ surface at height :math:`z_{0w} +d` and the atmosphere at height flux from the vegetation :math:`E_{v}` and the ground :math:`E_{g}` .. math:: - :label: ZEqnNum365017 + :label: 5.99 - E=E_{v} +E_{g} + E = E_{v} +E_{g} where, with reference to :numref:`Figure Schematic diagram of latent heat fluxes`, .. math:: - :label: 5.97) + :label: 5.100 - E=-\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } + E = -\rho _{atm} \frac{\left(q_{atm} -q_{s} \right)}{r_{aw} } .. math:: - :label: ZEqnNum351492 + :label: 5.101 - E_{v} =-\rho _{atm} \frac{\left(q_{s} -q_{sat}^{T_{v} } \right)}{r_{total} } + E_{v} = -\rho _{atm} \frac{\left(q_{s} -q_{sat}^{T_{v} } \right)}{r_{total} } .. math:: - :label: ZEqnNum145330 + :label: 5.102 - E_{g} =\left(1-f_{sno} -f_{h2osfc} \right)E_{soil} +f_{sno} E_{snow} +f_{h2osfc} E_{h2osfc} + E_{g} = \left(1-f_{sno} -f_{h2osfc} \right)E_{soil} +f_{sno} E_{snow} +f_{h2osfc} E_{h2osfc} \ , + +where .. math:: - :label: 5.100) + :label: 5.103 - E_{soil} =-\rho _{atm} \frac{\beta _{soi} \left(q_{s} -q_{soil} \right)}{r_{aw} ^{{'} } +r_{litter} } + E_{soil} = -\rho _{atm} \frac{\beta _{soi} \left(q_{s} -q_{soil} \right)}{r_{aw} ^{{'} } +r_{soil} } .. math:: - :label: 5.101) + :label: 5.104 - E_{sno} =-\rho _{atm} \frac{\left(q_{s} -q_{sno} \right)}{r_{aw} ^{{'} } +r_{litter} } + E_{sno} = -\rho _{atm} \frac{\left(q_{s} -q_{sno} \right)}{r_{aw} ^{{'} } +r_{soil} } .. math:: - :label: 5.102) + :label: 5.105 - E_{h2osfc} =-\rho _{atm} \frac{\left(q_{s} -q_{h2osfc} \right)}{r_{aw} ^{{'} } +r_{litter} } + E_{h2osfc} = -\rho _{atm} \frac{\left(q_{s} -q_{h2osfc} \right)}{r_{aw} ^{{'} } +r_{soil} } where :math:`q_{atm}` is the atmospheric specific humidity (kg kg\ :sup:`-1`), :math:`r_{aw}` is the aerodynamic resistance to water vapor transfer (s m\ :sup:`-1`), :math:`q_{sat}^{T_{v} }` @@ -1047,7 +1075,7 @@ m\ :sup:`-1`) to water vapor transfer between the ground at height :math:`z_{0w} ^{{'} }` and the canopy air at height :math:`z_{0w} +d`, :math:`\beta _{soi}` is an empirical function of soil water (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`), -and :math:`r_{litter}` is a resistance for the plant litter layer +and :math:`r_{soil}` (:eq:`5.76`) is a resistance to diffusion through the soil (s m\ :sup:`-1`). :math:`r_{total}` is the total resistance to water vapor transfer from the canopy to the canopy air and includes contributions from leaf boundary layer and sunlit and shaded stomatal @@ -1059,34 +1087,34 @@ is the sum of water vapor flux from wetted leaf and stem area transpiration from dry leaf surfaces :math:`E_{v}^{t}` .. math:: - :label: 5.103) + :label: 5.106 E_{v} =E_{v}^{w} +E_{v}^{t} . -Equations - can be solved for the canopy specific humidity +Equations :eq:`5.99` - :eq:`5.102` can be solved for the canopy specific humidity :math:`q_{s}` .. math:: - :label: ZEqnNum362168 + :label: 5.107 q_{s} =\frac{c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} +c_{v}^{w} q_{sat}^{T_{v} } }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } where .. math:: - :label: ZEqnNum533553 + :label: 5.108 c_{a}^{w} =\frac{1}{r_{aw} } .. math:: - :label: ZEqnNum544982 + :label: 5.109 c_{v}^{w} =\frac{\left(L+S\right)}{r_{b} } r'' .. math:: - :label: ZEqnNum888691 + :label: 5.110 - c_{g}^{w} =\frac{\beta _{soi} }{r_{aw} ^{{'} } +r_{litter} } + c_{g}^{w} =\frac{1}{r_{aw} ^{{'} } +r_{soil} } are the water vapor conductances from the canopy air to the atmosphere, the leaf to canopy air, and ground to canopy air, respectively. The term @@ -1095,9 +1123,14 @@ transpiration and limited by available water and potential evaporation as .. math:: - :label: ZEqnNum166006 + :label: 5.111 - r''=\left\{\begin{array}{l} {\min \left(f_{wet} +r_{dry} ^{{'} {'} } ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} >0} \\ {\min \left(f_{wet} ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right)\qquad E_{v}^{w,\, pot} >0,\, \beta _{t} \le 0} \\ {1\qquad E_{v}^{w,\, pot} \le 0} \end{array}\right\} + r'' = \left\{ + \begin{array}{lr} + \min \left(f_{wet} +r_{dry} ^{{'} {'} } ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right) & \qquad E_{v}^{w,\, pot} >0,\, \beta _{t} >0 \\ + \min \left(f_{wet} ,\, \frac{E_{v}^{w,\, pot} r_{dry} ^{{'} {'} } +\frac{W_{can} }{\Delta t} }{E_{v}^{w,\, pot} } \right) & \qquad E_{v}^{w,\, pot} >0,\, \beta _{t} \le 0 \\ + 1 & \qquad E_{v}^{w,\, pot} \le 0 + \end{array}\right\} where :math:`f_{wet}` is the fraction of leaves and stems that are wet (section :numref:`Canopy Water`), :math:`W_{can}` is canopy water (kg m\ :sup:`-2`) @@ -1107,14 +1140,14 @@ where :math:`f_{wet}` is the fraction of leaves and stems that are wet evaporation from wet foliage per unit wetted area is .. math:: - :label: 5.109) + :label: 5.112 E_{v}^{w,\, pot} =-\frac{\rho _{atm} \left(q_{s} -q_{sat}^{T_{v} } \right)}{r_{b} } . The term :math:`r_{dry} ^{{'} {'} }` is .. math:: - :label: 5.110) + :label: 5.113 r_{dry} ^{{'} {'} } =\frac{f_{dry} r_{b} }{L} \left(\frac{L^{sun} }{r_{b} +r_{s}^{sun} } +\frac{L^{sha} }{r_{b} +r_{s}^{sha} } \right) @@ -1124,21 +1157,21 @@ leaf area indices (section :numref:`Solar Fluxes`), and :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}` are the sunlit and shaded stomatal resistances (s m\ :sup:`-1`) (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). -When the expression for :math:`q_{s}` is substituted into equation , +When the expression for :math:`q_{s}` is substituted into equation :eq:`5.101`, the water vapor flux from vegetation :math:`E_{v}` is a function of :math:`q_{atm}` , :math:`q_{g}` , and :math:`q_{sat}^{T_{v} }` .. math:: - :label: ZEqnNum256012 + :label: 5.114 E_{v} =-\rho _{atm} \left[c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} -\left(c_{a}^{w} +c_{g}^{w} \right)q_{sat}^{T_{v} } \right]\frac{c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } . Similarly, the expression for :math:`q_{s}` can be substituted into -equation to obtain the water vapor flux from the ground beneath the +:eq:`5.84` to obtain the water vapor flux from the ground beneath the canopy :math:`E_{g}` .. math:: - :label: ZEqnNum243941 + :label: 5.115 E_{g} =-\rho _{atm} \left[c_{a}^{w} q_{atm} +c_{v}^{w} q_{sat}^{T_{v} } -\left(c_{a}^{w} +c_{v}^{w} \right)q_{g} \right]\frac{c_{g}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } . @@ -1147,14 +1180,14 @@ ground at height :math:`z_{0h} ^{{'} }` (:math:`z_{0w} ^{{'} }` ) and the canopy air at height :math:`z_{0h} +d` (:math:`z_{0w} +d`) are .. math:: - :label: ZEqnNum496775 + :label: 5.116 r_{ah} ^{{'} } =r_{aw} ^{{'} } =\frac{1}{C_{s} U_{av} } where .. math:: - :label: ZEqnNum781547 + :label: 5.117 U_{av} =V_{a} \sqrt{\frac{1}{r_{am} V_{a} } } =u_{*} @@ -1162,80 +1195,43 @@ is the magnitude of the wind velocity incident on the leaves (equivalent here to friction velocity) (m s\ :sup:`-1`) and :math:`C_{s}` is the turbulent transfer coefficient between the underlying soil and the canopy air. :math:`C_{s}` is obtained by -interpolation between values for dense canopy and bare soil (:ref:`Zeng et al. 2005 `) +interpolation between values for dense canopy and bare soil +(:ref:`Zeng et al. 2005 `) .. math:: - :label: 5.115) + :label: 5.118 C_{s} =C_{s,\, bare} W+C_{s,\, dense} (1-W) where the weight :math:`W` is .. math:: - :label: 5.116) + :label: 5.119 W=e^{-\left(L+S\right)} . -The dense canopy turbulent transfer coefficient in :ref:`Zeng et al. (2005) ` -is modified from its original value of 0.004 (:ref:`Dickinson et al. 1993 `) by -Sakaguchi and Zeng (2009) to account for stability as +The dense canopy turbulent transfer coefficient +(:ref:`Dickinson et al. 1993 `) is .. math:: - :label: 5.117) - - C_{s,\, dense} =\left\{\begin{array}{l} {0.004\qquad T_{s} -T_{g} \le 0} \\ {\frac{0.004}{1+\gamma \min \left(S,10\right)} \qquad T_{s} -T_{g} >0} \end{array}\right\} - -where :math:`\gamma =0.5` and :math:`S` is a stability parameter -determined from - -.. math:: - :label: 5.118) + :label: 5.120) - S=\frac{gz_{top} \left(T_{s} -T_{g} \right)}{T_{s} u_{*}^{2} } + C_{s,\, dense} =0.004 \ . -where :math:`g` is the gravitational acceleration (m -s\ :sup:`-2`) (:numref:`Table Physical constants`), and :math:`z_{top}` is canopy top -height (m) (:numref:`Table Prescribed plant functional type heights`). The bare soil turbulent transfer coefficient is +The bare soil turbulent transfer coefficient is .. math:: - :label: 5.119) + :label: 5.121 C_{s,\, bare} =\frac{k}{a} \left(\frac{z_{0m,\, g} U_{av} }{\upsilon } \right)^{-0.45} where the kinematic viscosity of air -:math:`\upsilon =1.5\times 10^{-5}` m\ :sup:`2` -s\ :sup:`-1` and :math:`a=0.13`. - -The litter resistance :math:`r_{litter}` (Sakaguchi and Zeng 2009) (s -m\ :sup:`-1`) is - -.. math:: - :label: 5.120) - - r_{litter} =\frac{1}{0.004u_{*} } \left(1-e^{-L_{litter}^{eff} } \right) - -where the effective litter area index :math:`L_{litter}^{eff}` (m\ :sup:`2` m\ :sup:`-2`) is the fraction of plant litter -area index :math:`L_{litter}` (currently set to 0.5 m\ :sup:`2` m\ :sup:`-2`) that is not covered by snow - -.. math:: - :label: 5.121) - - L_{litter}^{eff} =L_{litter} \left[1-\min \left(f_{litter}^{snow} ,\, 1\right)\right]. - -The effective snow cover of the litter layer is - -.. math:: - :label: 5.122) - - f_{litter}^{snow} =\frac{z_{sno} }{\Delta z_{litter} } - -where :math:`\Delta z_{litter} =0.05`\ m is assumed as a typical depth -for the litter layer, and :math:`z_{sno}` is the depth of snow (Chapter :numref:`rst_Snow Hydrology`) (m). +:math:`\upsilon =1.5\times 10^{-5}` m\ :sup:`2` s\ :sup:`-1` and :math:`a=0.13`. The leaf boundary layer resistance :math:`r_{b}` is .. math:: - :label: ZEqnNum181758 + :label: 5.122 r_{b} =\frac{1}{C_{v} } \left({U_{av} \mathord{\left/ {\vphantom {U_{av} d_{leaf} }} \right. \kern-\nulldelimiterspace} d_{leaf} } \right)^{{-1\mathord{\left/ {\vphantom {-1 2}} \right. \kern-\nulldelimiterspace} 2} } @@ -1246,16 +1242,17 @@ direction of wind flow (:numref:`Table Coefficients for saturation vapor pressur The partial derivatives of the fluxes from the soil beneath the canopy with respect to ground temperature, which are needed for the soil -temperature calculations (section :numref:`Numerical Solution Temperature`) and to update the soil surface -fluxes (section :numref:`Update of Ground Sensible and Latent Heat Fluxes`), are +temperature calculations (section :numref:`Numerical Solution Temperature`) +and to update the soil surface fluxes (section +:numref:`Update of Ground Sensible and Latent Heat Fluxes`), are .. math:: - :label: ZEqnNum774729 + :label: 5.123 \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r'_{ah} } \frac{c_{a}^{h} +c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } .. math:: - :label: ZEqnNum562232 + :label: 5.124 \frac{\partial E_{g} }{\partial T_{g} } =\frac{\beta _{soi} \rho _{atm} }{r'_{aw} +r_{litter} } \frac{c_{a}^{w} +c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{g} }{dT_{g} } . @@ -1267,35 +1264,38 @@ determined analytically, are ignored for :math:`\frac{\partial E_{g} }{\partial T_{g} }` . The roughness lengths used to calculate :math:`r_{am}` , -:math:`r_{ah}` , and :math:`r_{aw}` from equations , , and are +:math:`r_{ah}` , and :math:`r_{aw}` from :eq:`5.55`, :eq:`5.56`, and :eq:`5.57` are :math:`z_{0m} =z_{0m,\, v}` , :math:`z_{0h} =z_{0h,\, v}` , and :math:`z_{0w} =z_{0w,\, v}` . The vegetation displacement height :math:`d` and the roughness lengths are a function of plant height and adjusted for canopy density following :ref:`Zeng and Wang (2007) ` .. math:: - :label: 5.126) + :label: 5.125 - z_{0m,\, v} =z_{0h,\, v} =z_{0w,\, v} =\exp \left[V\ln \left(z_{top} R_{z0m} \right)+\left(1-V\right)\ln \left(z_{0m,\, g} \right)\right] + z_{0m,\, v} = z_{0h,\, v} =z_{0w,\, v} =\exp \left[V\ln \left(z_{top} R_{z0m} \right)+\left(1-V\right)\ln \left(z_{0m,\, g} \right)\right] .. math:: - :label: 5.127) + :label: 5.126 - d=z_{top} R_{d} V + d = z_{top} R_{d} V -where :math:`z_{top}` is canopy top height (m) (:numref:`Table Prescribed plant functional type heights`), +where :math:`z_{top}` is canopy top height (m) +(:numref:`Table Prescribed plant functional type heights`), :math:`R_{z0m}` and :math:`R_{d}` are the ratio of momentum roughness length and displacement height to canopy top height, respectively -(:numref:`Table Plant functional type aerodynamic parameters`), and -:math:`z_{0m,\, g}` is the ground momentum roughness length -(m) (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`). The fractional weight :math:`V` is determined from +(:numref:`Table Plant functional type aerodynamic parameters`), and :math:`z_{0m,\, g}` +is the ground momentum roughness length (m) (section +:numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`). The +fractional weight :math:`V` is determined from .. math:: - :label: 5.128) + :label: 5.127 - V=\frac{1-\exp \left\{-\beta \min \left[L+S,\, \left(L+S\right)_{cr} \right]\right\}}{1-\exp \left[-\beta \left(L+S\right)_{cr} \right]} + V = \frac{1-\exp \left\{-\beta \min \left[L+S,\, \left(L+S\right)_{cr} \right]\right\}}{1-\exp \left[-\beta \left(L+S\right)_{cr} \right]} -where :math:`\beta =1` and :math:`\left(L+S\right)_{cr} =2` (m\ :sup:`2` m\ :sup:`-2`) is a critical value of exposed leaf +where :math:`\beta =1` and :math:`\left(L+S\right)_{cr} = 2` +(m\ :sup:`2` m\ :sup:`-2`) is a critical value of exposed leaf plus stem area for which :math:`z_{0m}` reaches its maximum. .. _Table Plant functional type aerodynamic parameters: @@ -1362,7 +1362,7 @@ Numerical Implementation Canopy energy conservation gives .. math:: - :label: 5.129) + :label: 5.128 -\overrightarrow{S}_{v} +\overrightarrow{L}_{v} \left(T_{v} \right)+H_{v} \left(T_{v} \right)+\lambda E_{v} \left(T_{v} \right)=0 @@ -1381,7 +1381,7 @@ non-linear systems of equations can be applied to iteratively solve for :math:`T_{v}` as .. math:: - :label: ZEqnNum247755 + :label: 5.129 \Delta T_{v} =\frac{\overrightarrow{S}_{v} -\overrightarrow{L}_{v} -H_{v} -\lambda E_{v} }{\frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } +\frac{\partial H_{v} }{\partial T_{v} } +\frac{\partial \lambda E_{v} }{\partial T_{v} } } @@ -1391,17 +1391,17 @@ where :math:`\Delta T_{v} =T_{v}^{n+1} -T_{v}^{n}` and the subscript The partial derivatives are .. math:: - :label: 5.131) + :label: 5.130 \frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } =4\varepsilon _{v} \sigma \left[2-\varepsilon _{v} \left(1-\varepsilon _{g} \right)\right]T_{v}^{3} .. math:: - :label: 5.132) + :label: 5.131 \frac{\partial H_{v} }{\partial T_{v} } =\rho _{atm} C_{p} \left(c_{a}^{h} +c_{g}^{h} \right)\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } .. math:: - :label: 5.133) + :label: 5.132 \frac{\partial \lambda E_{v} }{\partial T_{v} } =\lambda \rho _{atm} \left(c_{a}^{w} +c_{g}^{w} \right)\frac{c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{sat}^{T_{v} } }{dT_{v} } . @@ -1418,17 +1418,17 @@ between stable and unstable conditions. The total water vapor flux flux :math:`H_{v}` are updated for changes in leaf temperature as .. math:: - :label: ZEqnNum420059 + :label: 5.133 E_{v} =-\rho _{atm} \left[c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} -\left(c_{a}^{w} +c_{g}^{w} \right)\left(q_{sat}^{T_{v} } +\frac{dq_{sat}^{T_{v} } }{dT_{v} } \Delta T_{v} \right)\right]\frac{c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } .. math:: - :label: ZEqnNum554100 + :label: 5.134 E_{v}^{t} =-r_{dry} ^{{'} {'} } \rho _{atm} \left[c_{a}^{w} q_{atm} +c_{g}^{w} q_{g} -\left(c_{a}^{w} +c_{g}^{w} \right)\left(q_{sat}^{T_{v} } +\frac{dq_{sat}^{T_{v} } }{dT_{v} } \Delta T_{v} \right)\right]\frac{c_{v}^{h} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } .. math:: - :label: ZEqnNum839021 + :label: 5.135 H_{v} =-\rho _{atm} C_{p} \left[c_{a}^{h} \theta _{atm} +c_{g}^{h} T_{g} -\left(c_{a}^{h} +c_{g}^{h} \right)\left(T_{v} +\Delta T_{v} \right)\right]\frac{c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } . @@ -1440,57 +1440,57 @@ proceeds as follows: obtained from .. math:: - :label: 5.137) + :label: 5.136 T_{s} =\frac{T_{g} +\theta _{atm} }{2} .. math:: - :label: 5.138) + :label: 5.137 q_{s} =\frac{q_{g} +q_{atm} }{2} . #. An initial guess for the wind speed :math:`V_{a}` is obtained from - eq. assuming an initial convective velocity :math:`U_{c} =0` m + :eq:`5.24` assuming an initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` as evaluated from - eq. ) and :math:`U_{c} =0.5` for unstable conditions + :eq:`5.50` ) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). #. An initial guess for the Monin-Obukhov length :math:`L` is obtained - from the bulk Richardson number using equation and . + from the bulk Richardson number using equation and :eq:`5.46` and :eq:`5.48`. #. Iteration proceeds on the following system of equations: -#. Friction velocity :math:`u_{*}` (eqs. , , , ) +#. Friction velocity :math:`u_{*}` (:eq:`5.32`, :eq:`5.33`, :eq:`5.34`, :eq:`5.35`) -#. Ratio :math:`\frac{\theta _{*} }{\theta _{atm} -\theta _{s} }` (eqs. - , , , ) +#. Ratio :math:`\frac{\theta _{*} }{\theta _{atm} -\theta _{s} }` + (:eq:`5.37` , :eq:`5.38`, :eq:`5.39`, :eq:`5.40`) -#. Ratio :math:`\frac{q_{*} }{q_{atm} -q_{s} }` (eqs. , , , ) +#. Ratio :math:`\frac{q_{*} }{q_{atm} -q_{s} }` (:eq:`5.41`, :eq:`5.42`, :eq:`5.43`, :eq:`5.44`) #. Aerodynamic resistances :math:`r_{am}` , :math:`r_{ah}` , and - :math:`r_{aw}` (eqs. , , ) + :math:`r_{aw}` (:eq:`5.55`, :eq:`5.56`, :eq:`5.57`) #. Magnitude of the wind velocity incident on the leaves :math:`U_{av}` - (eq. ) + (:eq:`5.117` ) -#. Leaf boundary layer resistance :math:`r_{b}` (eq. ) +#. Leaf boundary layer resistance :math:`r_{b}` (:eq:`5.136` ) #. Aerodynamic resistances :math:`r_{ah} ^{{'} }` and - :math:`r_{aw} ^{{'} }` (eq. ) + :math:`r_{aw} ^{{'} }` (:eq:`5.116` ) #. Sunlit and shaded stomatal resistances :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`) #. Sensible heat conductances :math:`c_{a}^{h}` , :math:`c_{g}^{h}` , - and :math:`c_{v}^{h}` (eqs. , , ) + and :math:`c_{v}^{h}` (:eq:`5.94`, :eq:`5.95`, :eq:`5.96`) #. Latent heat conductances :math:`c_{a}^{w}` , :math:`c_{v}^{w}` , and - :math:`c_{g}^{w}` (eqs. , , ) + :math:`c_{g}^{w}` (:eq:`5.108`, :eq:`5.109`, :eq:`5.110`) -#. Sensible heat flux from vegetation :math:`H_{v}` (eq. ) +#. Sensible heat flux from vegetation :math:`H_{v}` (:eq:`5.97` ) -#. Latent heat flux from vegetation :math:`\lambda E_{v}` (eq. ) +#. Latent heat flux from vegetation :math:`\lambda E_{v}` (:eq:`5.101` ) #. If the latent heat flux has changed sign from the latent heat flux computed at the previous iteration @@ -1500,23 +1500,23 @@ proceeds as follows: (:math:`\Delta _{1} =0.1\lambda E_{v} ^{n+1} -\lambda E_{v} ^{n+1}` ) is added to the sensible heat flux later. -#. Change in vegetation temperature :math:`\Delta T_{v}` (eq. ) and +#. Change in vegetation temperature :math:`\Delta T_{v}` (:eq:`5.129` ) and update the vegetation temperature as :math:`T_{v}^{n+1} =T_{v}^{n} +\Delta T_{v}` . :math:`T_{v}` is constrained to change by no more than 1ºK in one iteration. If this limit is exceeded, the energy error is .. math:: - :label: 5.139) + :label: 5.138 \Delta _{2} =\overrightarrow{S}_{v} -\overrightarrow{L}_{v} -\frac{\partial \overrightarrow{L}_{v} }{\partial T_{v} } \Delta T_{v} -H_{v} -\frac{\partial H_{v} }{\partial T_{v} } \Delta T_{v} -\lambda E_{v} -\frac{\partial \lambda E_{v} }{\partial T_{v} } \Delta T_{v} where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error :math:`\Delta _{2}` is added to the sensible heat flux later. -#. Water vapor flux :math:`E_{v}` (eq. ) +#. Water vapor flux :math:`E_{v}` (:eq:`5.133` ) -#. Transpiration :math:`E_{v}^{t}` (eq. if :math:`\beta _{t} >0`, +#. Transpiration :math:`E_{v}^{t}` (:eq:`5.134` if :math:`\beta_{t} >0`, otherwise :math:`E_{v}^{t} =0`) #. The water vapor flux :math:`E_{v}` is constrained to be less than or @@ -1526,26 +1526,28 @@ where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error The energy error due to this constraint is .. math:: - :label: 5.140) + :label: 5.139 \Delta _{3} =\max \left(0,\, E_{v} -E_{v}^{t} -\frac{W_{can} }{\Delta t} \right). The error :math:`\lambda \Delta _{3}` is added to the sensible heat flux later. -#. Sensible heat flux :math:`H_{v}` (eq. ). The three energy error +#. Sensible heat flux :math:`H_{v}` (:eq:`` ). The three energy error terms, :math:`\Delta _{1}` , :math:`\Delta _{2}` , and :math:`\lambda \Delta _{3}` are also added to the sensible heat flux. -#. The saturated vapor pressure :math:`e_{i}` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), saturated +#. The saturated vapor pressure :math:`e_{i}` (Chapter + :numref:`rst_Stomatal Resistance and Photosynthesis`), saturated specific humidity :math:`q_{sat}^{T_{v} }` and its derivative :math:`\frac{dq_{sat}^{T_{v} } }{dT_{v} }` at the leaf surface - (section :numref:`Saturation Vapor Pressure`), are re-evaluated based on the new :math:`T_{v}` . + (section :numref:`Saturation Vapor Pressure`), are re-evaluated based on + the new :math:`T_{v}` . -#. Canopy air temperature :math:`T_{s}` (eq. ) +#. Canopy air temperature :math:`T_{s}` (:eq:`5.93` ) -#. Canopy air specific humidity :math:`q_{s}` (eq. ) +#. Canopy air specific humidity :math:`q_{s}` (:eq:`5.107` ) #. Temperature difference :math:`\theta _{atm} -\theta _{s}` @@ -1561,11 +1563,11 @@ flux later. where :math:`\frac{q_{*} }{q_{atm} -q_{s} }` was calculated earlier in the iteration -#. Virtual potential temperature scale :math:`\theta _{v*}` (eq. ) +#. Virtual potential temperature scale :math:`\theta _{v*}` (:eq:`5.17` ) -#. Wind speed including the convective velocity, :math:`V_{a}` (eq. ) +#. Wind speed including the convective velocity, :math:`V_{a}` (:eq:`5.24` ) -#. Monin-Obukhov length :math:`L` (eq. ) +#. Monin-Obukhov length :math:`L` (:eq:`5.49` ) #. The iteration is stopped after two or more steps if :math:`\tilde{\Delta }T_{v} <0.01` and @@ -1574,14 +1576,14 @@ flux later. :math:`\tilde{\Delta }T_{v} =\max \left(\left|T_{v}^{n+1} -T_{v}^{n} \right|,\, \left|T_{v}^{n} -T_{v}^{n-1} \right|\right)`, or after forty iterations have been carried out. -#. Momentum fluxes :math:`\tau _{x}` , :math:`\tau _{y}` (eqs. , ) +#. Momentum fluxes :math:`\tau _{x}` , :math:`\tau _{y}` (:eq:`5.5`, :eq:`5.6`) -#. Sensible heat flux from ground :math:`H_{g}` (eq. ) +#. Sensible heat flux from ground :math:`H_{g}` (:eq:`5.89` ) -#. Water vapor flux from ground :math:`E_{g}` (eq. ) +#. Water vapor flux from ground :math:`E_{g}` (:eq:`5.102` ) #. 2-m height air temperature :math:`T_{2m}` , specific humidity - :math:`q_{2m}` , relative humidity :math:`RH_{2m}` \ (eqs. , , ) + :math:`q_{2m}` , relative humidity :math:`RH_{2m}` \ (:eq:`5.58` , :eq:`5.59`, :eq:`5.60`) .. _Update of Ground Sensible and Latent Heat Fluxes: @@ -1592,17 +1594,17 @@ The sensible and water vapor heat fluxes derived above for bare soil and soil beneath canopy are based on the ground surface temperature from the previous time step :math:`T_{g}^{n}` and are used as the surface forcing for the solution of the soil temperature equations (section -:numref:`Numerical Solution Temperature`). This solution yields a new ground surface temperature -:math:`T_{g}^{n+1}` . The ground sensible and water vapor fluxes are -then updated for :math:`T_{g}^{n+1}` as +:numref:`Numerical Solution Temperature`). This solution yields a new ground +surface temperature :math:`T_{g}^{n+1}` . The ground sensible and water +vapor fluxes are then updated for :math:`T_{g}^{n+1}` as .. math:: - :label: 5.141) + :label: 5.140 H'_{g} =H_{g} +\left(T_{g}^{n+1} -T_{g}^{n} \right)\frac{\partial H_{g} }{\partial T_{g} } .. math:: - :label: 5.142) + :label: 5.141 E'_{g} =E_{g} +\left(T_{g}^{n+1} -T_{g}^{n} \right)\frac{\partial E_{g} }{\partial T_{g} } @@ -1611,18 +1613,18 @@ vapor fluxes derived from equations and for non-vegetated surfaces and equations and for vegetated surfaces using :math:`T_{g}^{n}` . One further adjustment is made to :math:`H'_{g}` and :math:`E'_{g}` . If the soil moisture in the top snow/soil layer is not sufficient to -support the updated ground evaporation, i.e., if :math:`E'_{g} >0` and -:math:`f_{evap} <1` where +support the updated ground evaporation, i.e., if :math:`E'_{g} > 0` and +:math:`f_{evap} < 1` where .. math:: - :label: 5.143) + :label: 5.142 f_{evap} =\frac{{\left(w_{ice,\; snl+1} +w_{liq,\, snl+1} \right)\mathord{\left/ {\vphantom {\left(w_{ice,\; snl+1} +w_{liq,\, snl+1} \right) \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} }{\sum _{j=1}^{npft}\left(E'_{g} \right)_{j} \left(wt\right)_{j} } \le 1, an adjustment is made to reduce the ground evaporation accordingly as .. math:: - :label: 5.144) + :label: 5.143 E''_{g} =f_{evap} E'_{g} . @@ -1635,35 +1637,38 @@ relative area of the :math:`j^{th}` PFT with respect to the column, and :math:`npft` is the number of PFTs on the column. :math:`w_{ice,\, snl+1}` and :math:`w_{liq,\, snl+1}` are the ice and liquid water contents (kg m\ :sup:`-2`) of the top snow/soil layer -(Chapter :numref:`rst_Hydrology`). Any resulting energy deficit is assigned to sensible heat +(Chapter :numref:`rst_Hydrology`). Any resulting energy deficit is assigned +to sensible heat as .. math:: - :label: 5.145) + :label: 5.144 H''_{g} =H_{g} +\lambda \left(E'_{g} -E''_{g} \right). -The ground water vapor flux :math:`E''_{g}` is partitioned into evaporation of liquid water from snow/soil :math:`q_{seva}` -(kg\ m\ :sup:`-2` s\ :sup:`-1`), sublimation from snow/soil ice :math:`q_{subl}` (kg m\ :sup:`-2` s\ :sup:`-1`), liquid dew -on snow/soil :math:`q_{sdew}` (kg m\ :sup:`-2` s\ :sup:`-1`), or frost on snow/soil :math:`q_{frost}` (kg m\ :sup:`-2` s\ :sup:`-1`) as +The ground water vapor flux :math:`E''_{g}` is partitioned into evaporation +of liquid water from snow/soil :math:`q_{seva}` (kg\ m\ :sup:`-2` s\ :sup:`-1`), +sublimation from snow/soil ice :math:`q_{subl}` (kg m\ :sup:`-2` s\ :sup:`-1`), +liquid dew on snow/soil :math:`q_{sdew}` (kg m\ :sup:`-2` s\ :sup:`-1`), or +frost on snow/soil :math:`q_{frost}` (kg m\ :sup:`-2` s\ :sup:`-1`) as .. math:: - :label: 5.146) + :label: 5.145 q_{seva} =\max \left(E''_{sno} \frac{w_{liq,\, snl+1} }{w_{ice,\; snl+1} +w_{liq,\, snl+1} } ,0\right)\qquad E''_{sno} \ge 0,\, w_{ice,\; snl+1} +w_{liq,\, snl+1} >0 .. math:: - :label: 5.147) + :label: 5.146 q_{subl} =E''_{sno} -q_{seva} \qquad E''_{sno} \ge 0 .. math:: - :label: 5.148) + :label: 5.147 q_{sdew} =\left|E''_{sno} \right|\qquad E''_{sno} <0{\rm \; and\; }T_{g} \ge T_{f} .. math:: - :label: 5.149) + :label: 5.148 q_{frost} =\left|E''_{sno} \right|\qquad E''_{sno} <0{\rm \; and\; }T_{g} 0} \\ {\lambda _{vap} \qquad {\rm otherwise}} \end{array}\right\} @@ -1719,7 +1724,7 @@ flux to an energy flux, :math:`\lambda _{vap}` is used. The system balances energy as .. math:: - :label: 5.154) + :label: 5.153 \overrightarrow{S}_{g} +\overrightarrow{S}_{v} +L_{atm} \, \downarrow -L\, \uparrow -H_{v} -H_{g} -\lambda _{vap} E_{v} -\lambda E_{g} -G=0. @@ -1734,12 +1739,12 @@ Saturation vapor pressure :math:`e_{sat}^{T}` (Pa) and its derivative :ref:`Flatau et al. (1992) ` .. math:: - :label: 5.155) + :label: 5.154 e_{sat}^{T} =100\left[a_{0} +a_{1} T+\cdots +a_{n} T^{n} \right] .. math:: - :label: 5.156) + :label: 5.155 \frac{de_{sat}^{T} }{dT} =100\left[b_{0} +b_{1} T+\cdots +b_{n} T^{n} \right] @@ -1753,12 +1758,12 @@ The saturated water vapor specific humidity :math:`q_{sat}^{T}` and its derivati :math:`\frac{dq_{sat}^{T} }{dT}` are .. math:: - :label: 5.157) + :label: 5.156 q_{sat}^{T} =\frac{0.622e_{sat}^{T} }{P_{atm} -0.378e_{sat}^{T} } .. math:: - :label: 5.158) + :label: 5.157 \frac{dq_{sat}^{T} }{dT} =\frac{0.622P_{atm} }{\left(P_{atm} -0.378e_{sat}^{T} \right)^{2} } \frac{de_{sat}^{T} }{dT} . diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index f1f78574df..69a8907f89 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -392,7 +392,7 @@ mass is stated as \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q where :math:`\theta` is the volumetric soil water content -(mm:sup:`3` of water mm\ :sup:`-3` of soil), :math:`t` is +(mm\ :sup:`3` of water mm\ :sup:`-3` of soil), :math:`t` is time (s), :math:`z` is height above some datum in the soil column (mm) (positive upwards), :math:`q` is soil water flux (kg m\ :sup:`-2` s\ :sup:`-1` or mm s\ :sup:`-1`) (positive upwards), and diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 35a77b901f..136272973d 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -106,7 +106,7 @@ resolution. .. Figure 12.1. Schematic representation of the urban land unit -.. _Figure schematic representation of urban: +.. _Figure schematic representation of the urban land unit: .. figure:: image1.png From 80662a29eea077ab7cb7511ee0c037ee77ab49fa Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Wed, 31 May 2017 11:38:37 -0600 Subject: [PATCH 032/255] Update html --- .../CLM50_Tech_Note_External_Nitrogen_Cycle.rst | 2 +- .../CLM50_Tech_Note_Plant_Hydraulic_Stress.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst index b8f6536a46..69959b0a8c 100644 --- a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst @@ -93,7 +93,7 @@ annual NPP in Figure 16.1. .. figure:: image1.png Biological nitrogen fixation as a function of annual net -primary production. + primary production. Because of the empirical nature of this NPP-BNF relationship, the timescale for calculating NPP and thus BNF is unconstrained. Using diff --git a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst index e5541bf2b4..02132af76d 100644 --- a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst +++ b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst @@ -230,7 +230,7 @@ PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential a \psi=\left[\psi_{sunleaf},\psi_{shadeleaf},\psi_{stem},\psi_{root}\right] .. math:: - :label: 11.21) + :label: 11.21 \begin{aligned} E_{sun}&=q_{1a}\\ @@ -240,10 +240,10 @@ PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential a &=\sum_{i=1}^{nlevsoi}{q_{3,i}} \end{aligned} -The demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy equations in (11.21). +The demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy :eq:`11.21`. .. math:: - :label: 11.21) + :label: 11.22) ff From 4f2077ed2cd2c4f1f5a09c37f353c8e7e6b0e6bd Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 31 May 2017 13:34:20 -0600 Subject: [PATCH 033/255] update methane and lake chapters --- .../CLM50_Tech_Note_CN_Allocation.rst | 100 ++-- .../tech_note/Lake/CLM50_Tech_Note_Lake.rst | 479 +++++++++--------- .../Methane/CLM50_Tech_Note_Methane.rst | 211 +++++--- .../References/CLM50_Tech_Note_References.rst | 2 +- 4 files changed, 418 insertions(+), 374 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 3206f3ab28..a63ec9ae3d 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -80,17 +80,17 @@ photosynthesis ( :math:`CF_{xs,mr}`, gC m\ :sup:`-2` s\ :sup:`-1`): .. math:: - :label: 19.1) + :label: 19.1 CF_{mr} =CF_{GPP,mr} +CF_{xs,mr} .. math:: - :label: 19.2) + :label: 19.2 CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. .. math:: - :label: 19.3) + :label: 19.3 CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{mr} -CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. @@ -114,12 +114,12 @@ flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC m\ :sup:`-2` s\ :sup:`-1`) is given as .. math:: - :label: 19.4) + :label: 19.4 CF_{GPP,xs,pot} =\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CS_{xs} \ge 0} \\ {-CS_{xs} /(86400\tau _{xs} )\qquad {\rm for\; }CS_{xs} <0} \end{array}\right. .. math:: - :label: 19.5) + :label: 19.5 CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPPpot} -CF_{GPP,mr} } \\ {\max (CF_{GPPpot} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPPpot} -CF_{GPP,mr} } \end{array}\right. @@ -140,7 +140,7 @@ remaining carbon flux from photosynthesis which can be allocated to new growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 19.6) + :label: 19.6 CF_{avail\_ alloc} =CF_{GPPpot} -CF_{GPP,mr} -CF_{GPP,xs} . @@ -151,7 +151,7 @@ between various tissue types. The allometric parameters are defined as follows: .. math:: - :label: ZEqnNum650137 + :label: 19.7 \begin{array}{l} {a_{1} ={\rm \; ratio\; of\; new\; fine\; root\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{2} ={\rm \; ratio\; of\; new\; coarse\; root\; :\; new\; stem\; carbon\; allocation}} \\ {a_{3} ={\rm \; ratio\; of\; new\; stem\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{4} ={\rm \; ratio\; new\; live\; wood\; :\; new\; total\; wood\; allocation}} \\ {g_{1} ={\rm ratio\; of\; growth\; respiration\; carbon\; :\; new\; growth\; carbon.\; }} \end{array} @@ -166,7 +166,7 @@ ratio for carbon allocation between new stem and new leaf increases with increasing net primary production (NPP), as .. math:: - :label: 19.8) + :label: 19.8 a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 @@ -236,7 +236,7 @@ Carbon to nitrogen ratios are defined for different tissue types as follows: .. math:: - :label: ZEqnNum413927 + :label: 19.9 \begin{array}{l} {CN_{leaf} =\_ {\rm \; C:N\; for\; leaf}} \\ {CN_{fr} =\_ {\rm \; C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \; C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\_ {\rm \; C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} @@ -251,19 +251,19 @@ functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC m\ :sup:`-2` s\ :sup:`-1`): .. math:: - :label: ZEqnNum555154 + :label: 19.10 \begin{array}{l} {CF_{alloc} =CF_{GPP,leaf} {\kern 1pt} C_{allom} } \\ {NF_{alloc} =CF_{GPP,leaf} {\kern 1pt} N_{allom} } \end{array} where .. math:: - :label: 19.11) + :label: 19.11 \begin{array}{l} {C_{allom} =\left\{\begin{array}{l} {\left(1+g_{1} \right)\left(1+a_{1} +a_{3} \left(1+a_{2} \right)\right)\qquad {\rm for\; woody\; PFT}} \\ {1+g_{1} +a_{1} \left(1+g_{1} \right)\qquad \qquad {\rm for\; non-woody\; PFT}} \end{array}\right. } \\ {} \end{array} .. math:: - :label: 19.12) + :label: 19.12 N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. @@ -274,7 +274,7 @@ plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`) as: .. math:: - :label: 19.13) + :label: 19.13 NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . @@ -293,7 +293,7 @@ availability of nitrogen from this pool to support new growth s\ :sup:`-1`) is proportional to the plant nitrogen demand, as: .. math:: - :label: 19.14) + :label: 19.14 NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) @@ -319,7 +319,7 @@ m\ :sup:`-2` s\ :sup:`-1`) is never greater than the plant demand for new nitrogen: .. math:: - :label: 19.15) + :label: 19.15 NF_{retrans,alloc} =\min \left(NF_{plant\_ demand} ,NF_{avail\_ retrans} \right) @@ -332,7 +332,7 @@ from the soil (:math:`NF_{plant\_demand\_soil}`, gN m\ :sup:`-2` s\ :sup:`-1`): .. math:: - :label: ZEqnNum491412 + :label: 19.16 NF_{plant\_ demand\_ soil} =NF_{plant\_ demand} -NF_{retrans,alloc} . @@ -346,7 +346,7 @@ mineral nitrogen supply and competition with heterotrophs. Plant uptake from the soil mineral nitrogen pool is then given as: .. math:: - :label: 19.17) + :label: 19.17 NF_{sminn,alloc} =NF_{plant\_ demand\_ soil} f_{plant\_ demand} @@ -356,7 +356,7 @@ Final carbon and nitrogen allocation The total flux of allocated nitrogen is given as: .. math:: - :label: 19.18) + :label: 19.18 NF_{alloc} =NF_{retrans,alloc} +NF_{sminn,alloc} @@ -364,14 +364,14 @@ From the stoichiometric relationship in Eq. , the associated carbon allocation flux is: .. math:: - :label: 19.19) + :label: 19.19 CF_{alloc} =NF_{alloc} \frac{C_{allom} }{N_{allom} } . The downregulation of photosynthesis can then be calculated as: .. math:: - :label: 19.20) + :label: 19.20 f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . @@ -379,7 +379,7 @@ Total allocation to new leaf carbon (:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as: .. math:: - :label: 19.21) + :label: 19.21 CF_{alloc,leaf\_ tot} =\frac{CF_{alloc} }{C_{allom} } . @@ -395,124 +395,124 @@ storage pools (where storage is indicated with *\_stor*) for the various tissue types are given as: .. math:: - :label: 19.22) + :label: 19.22 CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} .. math:: - :label: 19.23) + :label: 19.23 CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) .. math:: - :label: 19.24) + :label: 19.24 CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} .. math:: - :label: 19.25) + :label: 19.25 CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) .. math:: - :label: 19.26) + :label: 19.26 CF_{alloc,livestem} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} f_{cur} .. math:: - :label: 19.27) + :label: 19.27 CF_{alloc,livestem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} \left(1-f_{cur} \right) .. math:: - :label: 19.28) + :label: 19.28 CF_{alloc,deadstem} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)f_{cur} .. math:: - :label: 19.29) + :label: 19.29 CF_{alloc,deadstem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right) .. math:: - :label: 19.30) + :label: 19.30 CF_{alloc,livecroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} f_{cur} .. math:: - :label: 19.31) + :label: 19.31 CF_{alloc,livecroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} \left(1-f_{cur} \right) .. math:: - :label: 19.32) + :label: 19.32 CF_{alloc,deadcroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)f_{cur} .. math:: - :label: 19.33) + :label: 19.33 CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). The corresponding nitrogen allocation fluxes are given as: .. math:: - :label: 19.34) + :label: 19.34 NF_{alloc,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} .. math:: - :label: 19.35) + :label: 19.35 NF_{alloc,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) .. math:: - :label: 19.36) + :label: 19.36 NF_{alloc,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} .. math:: - :label: 19.37) + :label: 19.37 NF_{alloc,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) .. math:: - :label: 19.38) + :label: 19.38 NF_{alloc,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: - :label: 19.39) + :label: 19.39 NF_{alloc,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: - :label: 19.40) + :label: 19.40 NF_{alloc,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: - :label: 19.41) + :label: 19.41 NF_{alloc,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) .. math:: - :label: 19.42) + :label: 19.42 NF_{alloc,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: - :label: 19.43) + :label: 19.43 NF_{alloc,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: - :label: 19.44) + :label: 19.44 NF_{alloc,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: - :label: 19.45) + :label: 19.45 NF_{alloc,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). @@ -536,22 +536,22 @@ functions tissue nitrogen content and the relevant temperature, following the empirical relationship reported by Ryan (1991): .. math:: - :label: 19.46) + :label: 19.46 CF_{mr\_ leaf} \_ =NS_{leaf} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} .. math:: - :label: 19.47) + :label: 19.47 CF_{mr\_ livestem} \_ =NS_{livestem} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} .. math:: - :label: 19.48) + :label: 19.48 CF_{mr\_ livecroot} \_ =NS_{livecroot} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} .. math:: - :label: 19.49) + :label: 19.49 CF_{mr\_ froot} \_ =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} @@ -574,7 +574,7 @@ common base maintenance respiration rate for all live tissue types. The total maintenance respiration cost is then given as: .. math:: - :label: 19.50) + :label: 19.50 CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . diff --git a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst index 860bc2ae7c..28cf52f8a1 100644 --- a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst +++ b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst @@ -21,10 +21,13 @@ body, resolved snow layers, and “soil†and bedrock layers below the lake body. Temperatures and ice fractions are simulated for :math:`N_{levlak} =10` layers (for global simulations) or :math:`N_{levlak} =25` (for site simulations) with discretization -described in section 9.1. Lake albedo is described in section 9.3. Lake -surface fluxes (section 9.4) generally follow the formulations for -non-vegetated surfaces, including the calculations of aerodynamic -resistances (section 5.2); however, the lake surface temperature +described in section :numref:`Vertical Discretization Lake`. Lake albedo is +described in section :numref:`Surface Albedo Lake`. Lake surface fluxes +(section :numref:`Surface Fluxes and Surface Temperature Lake`) generally +follow the formulations for non-vegetated surfaces, including the calculations +of aerodynamic resistances (section +:numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`); +however, the lake surface temperature :math:`T_{g}` (representing an infinitesimal interface layer between the top resolved lake layer and the atmosphere) is solved for simultaneously with the surface fluxes. After surface fluxes are @@ -32,7 +35,8 @@ evaluated, temperatures are solved simultaneously in the resolved snow layers (if present), the lake body, and the soil and bedrock, using the ground heat flux *G* as a top boundary condition. Snow, soil, and bedrock models generally follow the formulations for non-vegetated -surfaces (Chapter 6), with modifications described below. +surfaces (Chapter :numref:`rst_Soil and Snow Temperatures`), with +modifications described below. .. _Vertical Discretization Lake: @@ -51,7 +55,7 @@ liquid density), with frozen mass-fraction *I* a state variable. Resolved snow layers are present if the snow thickness :math:`z_{sno} \ge s_{\min }` , where *s*\ :sub:`min` = 4 cm by default, and is adjusted for model timesteps other than 1800 s in order -to maintain numerical stability (section 9.6.5). For global simulations +to maintain numerical stability (section :numref:`Modifications to Snow Layer Logic Lake`). For global simulations with 10 body layers, the default (50 m lake) body layer thicknesses are given by: :math:`\Delta z_{i}` of 0.1, 1, 2, 3, 4, 5, 7, 7, 10.45, and 10.45 m, with node depths :math:`z_{i}` located at the center of each @@ -64,22 +68,23 @@ layers 10-13; 2 for layers 14-15; 2.5 for layers 16-17; 3.5 for layers layer is kept at 10 cm and the other 9 layer thicknesses are adjusted to maintain fixed proportions. For lakes with *d* :math:`<` 1 m, all layers have equal thickness. Thicknesses of snow, soil, and bedrock layers -follow the scheme used over non-vegetated surfaces (Chapter 6), with +follow the scheme used over non-vegetated surfaces (Chapter :numref:`rst_Soil and Snow Temperatures`), with modifications to the snow layer thickness rules to keep snow layers at -least as thick as *s*\ :sub:`min` (section 9.6.5). +least as thick as *s*\ :sub:`min` (section :numref:`Modifications to Snow Layer Logic Lake`). .. _External Data Lake: External Data ----------------- -As discussed in Subin et al (2012a, b), the Global Lake and Wetland -Database (Lehner and Doll 2004) is currently used to prescribe lake -fraction in each land model grid cell, for a total of 2.3 million -km\ :sup:`-2`. As in Subin et al. (2012a, b), the Kourzeneva -(2012) global gridded dataset is currently used to estimate a mean lake -depth in each grid cell, based on interpolated compilations of -geographic information. +As discussed in :ref:`Subin et al. (2012a, b) `, the +Global Lake and Wetland Database (:ref:`Lehner and Doll 2004`) +is currently used to prescribe lake fraction in each land model grid cell, +for a total of 2.3 million km\ :sup:`-2`. As in +:ref:`Subin et al. (2012a, b) `, the +:ref:`Kourzeneva et al. (2012)` global gridded dataset is currently +used to estimate a mean lake depth in each grid cell, based on interpolated +compilations of geographic information. .. _Surface Albedo Lake: @@ -87,10 +92,10 @@ Surface Albedo ------------------ For direct radiation, the albedo *a* for lakes with ground temperature -:math:`{T}_{g}` (K) above freezing is given by (Pivovarov, 1972) +:math:`{T}_{g}` (K) above freezing is given by (:ref:`Pivovarov, 1972`) .. math:: - :label: ZEqnNum194122 + :label: 12.1 a=\frac{0.5}{\cos z+0.15} @@ -100,57 +105,27 @@ eq. is integrated over the full sky to yield *a* = 0.10. For frozen lakes without resolved snow layers, the albedo at cold temperatures *a*\ :sub:`0` is 0.60 for visible and 0.40 for near infrared radiation. As the temperature at the ice surface, -:math:`{T}_{g}`, approaches freezing [ :math:`{T}_{f}` (K) (Table -2.6)], the albedo is relaxed towards 0.10 based on Mironov et al. (2010): +:math:`{T}_{g}`, approaches freezing [ :math:`{T}_{f}` (K) (:numref:`Table Physical Constants`)], the albedo is relaxed towards 0.10 based on +:ref:`Mironov et al. (2010)`: .. math:: - :label: 12.2) + :label: 12.2 a=a_{0} \left(1-x\right)+0.10x,x=\exp \left(-95\frac{T_{f} -T_{g} }{T_{f} } \right) -where *a* is restricted to be no less than that given in eq. . +where *a* is restricted to be no less than that given in :eq:`12.1`. For frozen lakes with resolved snow layers, the reflectance of the ice surface is fixed at *a*\ :sub:`0`, and the snow reflectance is -calculated as over non-vegetated surfaces (Chapter 3). These two -reflectances are combined to obtain the snow-fraction-weighted albedo as -in over non-vegetated surfaces (Chapter 3). +calculated as over non-vegetated surfaces (Chapter :numref:`rst_Surface Albedos`). +These two reflectances are combined to obtain the snow-fraction-weighted albedo as +in over non-vegetated surfaces (Chapter :numref:`rst_Surface Albedos`). .. _Surface Fluxes and Surface Temperature Lake: Surface Fluxes and Surface Temperature ------------------------------------------ -.. _Overview of Changes from CLM4: - -Overview of Changes from CLM4 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -#. The surface roughnesses, and surface absorption fraction - :math:`\beta`, are diagnostic rather than constants. As the surface - roughnesses depend (weakly) on the friction velocity :math:`u_{\*}` - (which itself depends weakly on the surface roughnesses), their - calculation has been incorporated into the iteration solution for - :math:`{T}_{g}`, and the maximum number of iterations has been - increased to 4. Convergence of the modified solution was tested - during development. - -#. A coefficient of :math:`\beta` has been added to - :math:`{S}_{g}` in eq. , correcting a previous error. - .. todo:: fill this equation number in - -#. The top layer thickness :math:`\Delta z_{T}` used in eq. has been - appended with a coefficient of ½, correcting a previous error. - -#. The thermal conductivity :math:`\lambda _{T}` used in eq. depends on - the properties of the top model layer (e.g., snow, ice, or water). - When this layer is unfrozen, :math:`\lambda _{T}` includes the eddy - conductivity calculated in the previous timestep. - -#. Several conditions are imposed on the ground temperature - :math:`{T}_{g}` to maintain a stable density profile at the lake - surface eq. . - .. _Surface Properties Lake: Surface Properties @@ -159,24 +134,25 @@ Surface Properties The fraction of shortwave radiation absorbed at the surface, :math:`\beta`, depends on the lake state. If resolved snow layers are present, then :math:`\beta` is set equal to the absorption fraction -predicted by the snow-optics submodel (Chapter 3) for the top snow +predicted by the snow-optics submodel (Chapter :numref:`rst_Surface Albedos`) +for the top snow layer. Otherwise, :math:`\beta` is set equal to the near infrared fraction of the shortwave radiation reaching the surface simulated by the atmospheric model or atmospheric data model used for offline -simulations (Chapter 26). The remainder of the shortwave radiation +simulations (Chapter :numref:`rst_Offline Mode`). The remainder of the shortwave radiation fraction (1 :math:`{-}` :math:`\beta`) is absorbed in the lake -body or soil as described in section 9.5.5. +body or soil as described in section :numref:`Radiation Penetration`. The surface roughnesses are functions of the lake state and atmospheric forcing. For frozen lakes ( :math:`T_{g} \le T_{f}` ) with resolved snow layers, the momentum roughness length -:math:`z_{0m} =2.4\times 10^{-3} {\rm m}` (as over non-vegetated -surfaces; Chapter 5), and the scalar roughness lengths +:math:`z_{0m} =2.4 \times 10^{-3} {\rm m}` (as over non-vegetated +surfaces; Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), and the scalar roughness lengths (*z*\ :sub:`0q` for latent heat; and *z*\ :sub:`0h`, for sensible heat) are given by -(Zilitinkevich 1970) +(:ref:`Zilitinkevich 1970`) .. math:: - :label: ZEqnNum631483 + :label: 12.3 \begin{array}{l} {R_{0} =\frac{z_{0m} u_{*} }{\nu } ,} \\ {z_{0h} =z_{0q} =z_{0m} \exp \left\{-0.13R_{0} ^{0.45} \right\}} \end{array} @@ -186,23 +162,23 @@ length for sensible heat, :math:`z_{0q}` is the roughness length for latent heat, :math:`\nu` (m\ :sup:`2` s\ :sup:`-1`) is the kinematic viscosity of air, and :math:`u_{\*}` (m s\ :sup:`-1`) is the friction velocity in the atmospheric surface layer. For frozen lakes without resolved snow -layers, :math:`z_{0m} =1\times 10^{-3} {\rm m}` (Subin et al. 2012a), +layers, :math:`z_{0m} =1\times 10^{-3} {\rm m}` (:ref:`Subin et al. (2012a) `), and the scalar roughness lengths are given by . -For unfrozen lakes, *z*\ :sub:`0m` is given by (Subin et al. 2012a) +For unfrozen lakes, *z*\ :sub:`0m` is given by (:ref:`Subin et al. (2012a) `) .. math:: - :label: ZEqnNum864823 + :label: 12.4 z_{0m} =\max \left(\frac{\alpha \nu }{u_{*} } ,C\frac{u_{*} ^{2} }{g} \right) where :math:`\alpha` = 0.1, :math:`\nu` is the kinematic viscosity of air given below, *C* is the effective Charnock coefficient given -below, and *g* is the acceleration of gravity (Table 2.6). The kinematic +below, and *g* is the acceleration of gravity (:numref:`Table Physical Constants`). The kinematic viscosity is given by .. math:: - :label: 12.5) + :label: 12.5 \nu =\nu _{0} \left(\frac{T_{g} }{T_{0} } \right)^{1.5} \frac{P_{0} }{P_{ref} } @@ -216,7 +192,7 @@ height. The Charnock coefficient *C* is a function of the lake fetch *F* default: .. math:: - :label: 12.6) + :label: 12.6 \begin{array}{l} {C=C_{\min } +(C_{\max } -C_{\min } )\exp \left\{-\min \left(A,B\right)\right\}} \\ {A={\left(\frac{Fg}{u_{\*} ^{2} } \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } \mathord{\left/ {\vphantom {\left(\frac{Fg}{u_{\*} ^{2} } \right)^{{1\mathord{\left/ {\vphantom {1 3}} \right. \kern-\nulldelimiterspace} 3} } f_{c} }} \right. \kern-\nulldelimiterspace} f_{c} } } \\ {B=\varepsilon \frac{\sqrt{dg} }{u} } \end{array} @@ -233,7 +209,7 @@ Surface Flux Solution Conservation of energy at the lake surface requires .. math:: - :label: ZEqnNum309023 + :label: 12.7 \beta \vec{S}_{g} -\vec{L}_{g} -H_{g} -\lambda E_{g} -G=0 @@ -247,61 +223,63 @@ the temperature at the lake surface :math:`{T}_{g}`. :math:`\lambda` converts :math:`E_{g}` to an energy flux based on .. math:: - :label: ZEqnNum257687 + :label: 12.8 \lambda =\left\{\begin{array}{l} {\lambda _{sub} \qquad T_{g} \le T_{f} } \\ {\lambda _{vap} \qquad T_{g} >T_{f} } \end{array}\right\}. The sensible heat flux (W m\ :sup:`-2`) is .. math:: - :label: ZEqnNum720553 + :label: 12.9 H_{g} =-\rho _{atm} C_{p} \frac{\left(\theta _{atm} -T_{g} \right)}{r_{ah} } where :math:`\rho _{atm}` is the density of moist air (kg -m\ :sup:`-3`) (Chapter 5), :math:`C_{p}` is the specific heat -capacity of air (J kg\ :sup:`-1` K\ :sup:`-1`) (Table 2.6), +m\ :sup:`-3`) (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), :math:`C_{p}` is the specific heat +capacity of air (J kg\ :sup:`-1` K\ :sup:`-1`) (:numref:`Table Physical Constants`), :math:`\theta _{atm}` is the atmospheric potential temperature (K) -(Chapter 5), :math:`T_{g}` is the lake surface temperature (K) (at an +(Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), :math:`T_{g}` is the lake surface temperature (K) (at an infinitesimal interface just above the top resolved model layer: snow, ice, or water), and :math:`r_{ah}` is the aerodynamic resistance to -sensible heat transfer (s m\ :sup:`-1`) (section 5.1). +sensible heat transfer (s m\ :sup:`-1`) (section :numref:`Monin-Obukhov Similarity Theory`). The water vapor flux (kg m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 12.10) + :label: 12.10 E_{g} =-\frac{\rho _{atm} \left(q_{atm} -q_{sat}^{T_{g} } \right)}{r_{aw} } where :math:`q_{atm}` is the atmospheric specific humidity (kg -kg\ :sup:`-1`) (section 2.2.1), :math:`q_{sat}^{T_{g} }` \ is the -saturated specific humidity (kg kg\ :sup:`-1`) (section 5.5) at +kg\ :sup:`-1`) (section :numref:`Atmospheric Coupling`), +:math:`q_{sat}^{T_{g} }` \ is the saturated specific humidity +(kg kg\ :sup:`-1`) (section :numref:`Saturation Vapor Pressure`) at the lake surface temperature :math:`T_{g}` , and :math:`r_{aw}` is the aerodynamic resistance to water vapor transfer (s m\ :sup:`-1`) -(section 5.1). +(section :numref:`Monin-Obukhov Similarity Theory`). The zonal and meridional momentum fluxes are .. math:: - :label: 12.11) + :label: 12.11 \tau _{x} =-\rho _{atm} \frac{u_{atm} }{r_{atm} } .. math:: - :label: 12.12) + :label: 12.12 \tau _{y} =-\rho _{atm} \frac{v_{atm} }{r_{atm} } where :math:`u_{atm}` and :math:`v_{atm}` are the zonal and -meridional atmospheric winds (m s\ :sup:`-1`) (section 2.2.1), and +meridional atmospheric winds (m s\ :sup:`-1`) (section +:numref:`Atmospheric Coupling`), and :math:`r_{am}` is the aerodynamic resistance for momentum (s -m\ :sup:`-1`) (section 5.1). +m\ :sup:`-1`) (section :numref:`Monin-Obukhov Similarity Theory`). The heat flux into the lake surface :math:`G` (W m\ :sup:`-2`) is .. math:: - :label: ZEqnNum122376 + :label: 12.13 G=\frac{2\lambda _{T} }{\Delta z_{T} } \left(T_{g} -T_{T} \right) @@ -311,10 +289,9 @@ thickness (m), and :math:`T_{T}` is the temperature (K) of the top resolved lake layer (snow, ice, or water). The top thermal conductivity :math:`\lambda _{T}` of unfrozen lakes ( :math:`T_{g} >T_{f}` ) includes conductivities due to molecular ( :math:`\lambda _{liq}` ) and -eddy (:math:`\lambda _{K}` ) diffusivities (section 9.5.4), as evaluated +eddy (:math:`\lambda _{K}` ) diffusivities (section :numref:`Eddy Diffusivity and Thermal Conductivities`), as evaluated in the top lake layer at the previous timestep, where -:math:`\lambda _{liq}` is the thermal conductivity of water (Table -2.6). For frozen lakes without resolved snow layers, +:math:`\lambda _{liq}` is the thermal conductivity of water (:numref:`Table Physical Constants`). For frozen lakes without resolved snow layers, :math:`\lambda _{T} =\lambda _{ice}` . When resolved snow layers are present, :math:`\lambda _{T}` \ is calculated based on the water content, ice content, and thickness of the top snow layer, as for @@ -323,7 +300,7 @@ non-vegetated surfaces. The absorbed solar radiation :math:`\vec{S}_{g}` is .. math:: - :label: 12.14) + :label: 12.14 \vec{S}_{g} =\sum _{\Lambda }S_{atm} \, \downarrow _{\Lambda }^{\mu } \left(1-\alpha _{g,\, \Lambda }^{\mu } \right) +S_{atm} \, \downarrow _{\Lambda } \left(1-\alpha _{g,\, \Lambda } \right) @@ -332,30 +309,32 @@ where :math:`S_{atm} \, \downarrow _{\Lambda }^{\mu }` and and diffuse solar fluxes (W m\ :sup:`-2`) and :math:`\Lambda` denotes the visible (:math:`<` 0.7\ :math:`\mu {\rm m}`) and near-infrared (:math:`\ge` 0.7\ :math:`\mu {\rm m}`) wavebands (section -2.2.1), and :math:`\alpha _{g,\, \Lambda }^{\mu }` and +:numref:`Atmospheric Coupling`), and :math:`\alpha _{g,\, \Lambda }^{\mu }` and :math:`\alpha _{g,\, \mu }` are the direct beam and diffuse lake -albedos (section 9.3). +albedos (section :numref:`Surface Albedo Lake`). The net emitted longwave radiation is .. math:: - :label: 12.15) + :label: 12.15 \vec{L}_{g} =L_{g} \, \uparrow -L_{atm} \, \downarrow where :math:`L_{g} \, \uparrow` is the upward longwave radiation from the surface, :math:`L_{atm} \, \downarrow` is the downward atmospheric -longwave radiation (section 2.2.1). The upward longwave radiation from -the surface is +longwave radiation (section :numref:`Atmospheric Coupling`). The upward +longwave radiation from the surface is .. math:: - :label: 12.16) + :label: 12.16 L\, \uparrow =\left(1-\varepsilon _{g} \right)L_{atm} \, \downarrow +\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{4} +4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} \left(T_{g}^{n+1} -T_{g}^{n} \right) where :math:`\varepsilon _{g} =0.97` is the lake surface emissivity, -:math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6), and :math:`T_{g}^{n+1} -T_{g}^{n}` is -the difference in lake surface temperature between Newton-Raphson iterations (see below). +:math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ +:sup:`-4`) (:numref:`Table Physical Constants`), and +:math:`T_{g}^{n+1} -T_{g}^{n}` is the difference in lake surface +temperature between Newton-Raphson iterations (see below). The sensible heat :math:`H_{g}` , the water vapor flux :math:`E_{g}` through its dependence on the saturated specific humidity, the net @@ -365,7 +344,7 @@ Newton-Raphson iteration is applied to solve for :math:`T_{g}` and the surface fluxes as .. math:: - :label: ZEqnNum858039 + :label: 12.17 \Delta T_{g} =\frac{\beta \overrightarrow{S}_{g} -\overrightarrow{L}_{g} -H_{g} -\lambda E_{g} -G}{\frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } +\frac{\partial H_{g} }{\partial T_{g} } +\frac{\partial \lambda E_{g} }{\partial T_{g} } +\frac{\partial G}{\partial T_{g} } } @@ -374,79 +353,80 @@ where :math:`\Delta T_{g} =T_{g}^{n+1} -T_{g}^{n}` and the subscript :math:`T_{g}^{n+1}` can be written as .. math:: - :label: ZEqnNum878786 + :label: 12.18 T_{g}^{n+1} =\frac{\beta \overrightarrow{S}_{g} -\overrightarrow{L}_{g} -H_{g} -\lambda E_{g} -G+T_{g}^{n} \left(\frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } +\frac{\partial H_{g} }{\partial T_{g} } +\frac{\partial \lambda E_{g} }{\partial T_{g} } +\frac{\partial G}{\partial T_{g} } \right)}{\frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } +\frac{\partial H_{g} }{\partial T_{g} } +\frac{\partial \lambda E_{g} }{\partial T_{g} } +\frac{\partial G}{\partial T_{g} } } where the partial derivatives are .. math:: - :label: 12.19) + :label: 12.19 \frac{\partial \overrightarrow{L}_{g} }{\partial T_{g} } =4\varepsilon _{g} \sigma \left(T_{g}^{n} \right)^{3} , .. math:: - :label: 12.20) + :label: 12.20 \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r_{ah} } , .. math:: - :label: 12.21) + :label: 12.21 \frac{\partial \lambda E_{g} }{\partial T_{g} } =\frac{\lambda \rho _{atm} }{r_{aw} } \frac{dq_{sat}^{T_{g} } }{dT_{g} } , .. math:: - :label: 12.22) + :label: 12.22 \frac{\partial G}{\partial T_{g} } =\frac{2\lambda _{T} }{\Delta z_{T} } . The fluxes of momentum, sensible heat, and water vapor are solved for simultaneously with lake surface temperature as follows. The stability-related equations are the same as for non-vegetated surfaces -(section 5.2), except that the surface roughnesses are here (weakly -varying) functions of the friction velocity :math:`u_{\*}` . To begin, -*z*\ :sub:`0m` is set based on the value -calculated for the last timestep (for :math:`T_{g} >T_{f}` ) or based on -the values in section 9.4.2 (otherwise), and the scalar roughness -lengths are set based on the relationships in section 9.4.2. +(section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`), +except that the surface roughnesses are here (weakly varying) functions +of the friction velocity :math:`u_{\*}` . To begin, *z*\ :sub:`0m` is set +based on the value calculated for the last timestep (for +:math:`T_{g} >T_{f}` ) or based on the values in section +:numref:`Surface Properties Lake` (otherwise), and the scalar roughness +lengths are set based on the relationships in section :numref:`Surface Properties Lake`. #. An initial guess for the wind speed :math:`V_{a}` including the - convective velocity :math:`U_{c}` is obtained from eq. assuming an + convective velocity :math:`U_{c}` is obtained from :eq:`5.24` assuming an initial convective velocity :math:`U_{c} =0` m s\ :sup:`-1` for stable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} \ge 0` - as evaluated from eq. ) and :math:`U_{c} =0.5` for unstable + as evaluated from :eq:`5.50`) and :math:`U_{c} =0.5` for unstable conditions (:math:`\theta _{v,\, atm} -\theta _{v,\, s} <0`). #. An initial guess for the Monin-Obukhov length :math:`L` is obtained - from the bulk Richardson number using equations and . + from the bulk Richardson number using :eq:`5.46` and :eq:`5.48`. #. The following system of equations is iterated four times: -#. Heat of vaporization / sublimation :math:`\lambda` \ (eq. ) +#. Heat of vaporization / sublimation :math:`\lambda` \ (:eq:`12.8`) #. Thermal conductivity :math:`\lambda _{T}` \ (above) -#. Friction velocity :math:`u_{\*}` (eqs. , , , ) +#. Friction velocity :math:`u_{\*}` (:eq:`5.32`, :eq:`5.33`, :eq:`5.34`, :eq:`5.35`) -#. Potential temperature scale :math:`\theta _{\*}` (eqs. , , , ) +#. Potential temperature scale :math:`\theta _{\*}` (:eq:`5.37` , :eq:`5.38`, :eq:`5.39`, :eq:`5.40`) -#. Humidity scale :math:`q_{\*}` (eqs. , , , ) +#. Humidity scale :math:`q_{\*}` (:eq:`5.41`, :eq:`5.42`, :eq:`5.43`, :eq:`5.44`) #. Aerodynamic resistances :math:`r_{am}` , :math:`r_{ah}` , and - :math:`r_{aw}` (eqs. , , ) + :math:`r_{aw}` (:eq:`5.55`, :eq:`5.56`, :eq:`5.57`) -#. Lake surface temperature :math:`T_{g}^{n+1}` (eq.) +#. Lake surface temperature :math:`T_{g}^{n+1}` (:eq:`12.18`) -#. Heat of vaporization / sublimation :math:`\lambda` (eq. ) +#. Heat of vaporization / sublimation :math:`\lambda` (:eq:`12.8`) #. Sensible heat flux :math:`H_{g}` is updated for :math:`T_{g}^{n+1}` - (eq.) + (:eq:`12.9`) #. Water vapor flux :math:`E_{g}` is updated for :math:`T_{g}^{n+1}` as .. math:: - :label: ZEqnNum331835 + :label: 12.23 E_{g} =-\frac{\rho _{atm} }{r_{aw} } \left[q_{atm} -q_{sat}^{T_{g} } -\frac{\partial q_{sat}^{T_{g} } }{\partial T_{g} } \left(T_{g}^{n+1} -T_{g}^{n} \right)\right] @@ -456,28 +436,28 @@ iterations. #. Saturated specific humidity :math:`q_{sat}^{T_{g} }` and its derivative :math:`\frac{dq_{sat}^{T_{g} } }{dT_{g} }` are updated - for :math:`T_{g}^{n+1}` (section 5.1). + for :math:`T_{g}^{n+1}` (section :numref:`Monin-Obukhov Similarity Theory`). -#. Virtual potential temperature scale :math:`\theta _{v\*}` (eq. ) +#. Virtual potential temperature scale :math:`\theta _{v\*}` (:eq:`5.17`) -#. Wind speed including the convective velocity, :math:`V_{a}` (eq. ) +#. Wind speed including the convective velocity, :math:`V_{a}` (:eq:`5.24`) -#. Monin-Obukhov length :math:`L` (eq. ). +#. Monin-Obukhov length :math:`L` (:eq:`5.49`) -#. Roughness lengths (eq. , ). +#. Roughness lengths (:eq:`12.3`, :eq:`12.4`). Once the four iterations for lake surface temperature have been yielded a tentative solution :math:`T_{g} ^{{'} }` , several restrictions are imposed in order to maintain consistency with the top lake model -layer temperature :math:`T_{T}` \ (Subin et al. 2012a). +layer temperature :math:`T_{T}` \ (:ref:`Subin et al. (2012a) `). .. math:: - :label: ZEqnNum180534 + :label: 12.24 \begin{array}{l} {{\rm 1)\; }T_{T} \le T_{f} T_{g} ^{{'} } >T_{m} \Rightarrow T_{g} =T_{T} ,} \\ {{\rm 3)\; }T_{m} >T_{g} ^{{'} } >T_{T} >T_{f} \Rightarrow T_{g} =T_{T} } \end{array} where :math:`T_{m}` \ is the temperature of maximum liquid water -density, 3.85\ :sup:`o` C (Hostetler and Bartlein 1990). The +density, 3.85\ :sup:`o` C (:ref:`Hostetler and Bartlein (1990) `). The first condition requires that, if there is any snow or ice present, the surface temperature is restricted to be less than or equal to freezing. The second and third conditions maintain convective stability in the top @@ -489,7 +469,8 @@ the momentum fluxes are re-evaluated in any case. The final ground heat flux :math:`G` is calculated from the residual of the energy balance eq. XXX in order to precisely conserve energy. XXX This ground heat flux is taken as a prescribed flux boundary condition for the lake -temperature solution (section 9.5.3). An energy balance check is +temperature solution (section :numref:`Boundary Conditions Lake`). +An energy balance check is included at each timestep to insure that eq. XXX is obeyed to within 0.1 W m\ :sup:`-2`. @@ -506,10 +487,10 @@ Introduction The (optional-) snow, lake body (water and/or ice), soil, and bedrock system is unified for the lake temperature solution. The governing equation, similar to that for the snow-soil-bedrock system for vegetated -land units (Chapter 6), is +land units (Chapter :numref:`rst_Soil and Snow Temperatures`), is .. math:: - :label: ZEqnNum239244 + :label: 12.25 \tilde{c}_{v} \frac{\partial T}{\partial t} =\frac{\partial }{\partial z} \left(\tau \frac{\partial T}{\partial z} \right)-\frac{d\phi }{dz} @@ -521,21 +502,23 @@ radiation (W m\ :sup:`-2`) penetrating to depth *z* (m). The system is discretized into *N* layers, where .. math:: - :label: 12.26) + :label: 12.26 N=n_{sno} +N_{levlak} +N_{levgrnd} , :math:`n_{sno}` is the number of actively modeled snow layers at the -current timestep (section 7.2), and :math:`N_{levgrnd}` \ is as for -vegetated land units (Chapter 6). Energy is conserved as +current timestep (Chapter :numref:`rst_Snow Hydrology`), and +:math:`N_{levgrnd}` \ is as for vegetated land units (Chapter +:numref:`rst_Soil and Snow Temperatures`). Energy is conserved as .. math:: - :label: ZEqnNum317718 + :label: 12.27 \frac{d}{dt} \sum _{j=1}^{N}\left[\tilde{c}_{v,j} (t)\left(T_{j} -T_{f} \right)+L_{j} (t)\right] \Delta z_{j} =G+\left(1-\beta \right)\vec{S}_{g} where :math:`\tilde{c}_{v,j} (t)`\ is the volumetric heat capacity of -the *j*\ th layer (section 9.5.5), :math:`L_{j} (t)`\ is the latent heat +the *j*\ th layer (section :numref:`Radiation Penetration`), +:math:`L_{j} (t)`\ is the latent heat of fusion per unit volume of the *j*\ th layer (proportional to the mass of liquid water present), and the right-hand side represents the net influx of energy to the lake system. Note that @@ -553,20 +536,21 @@ Overview of Changes from CLM4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Thermal conductivities include additional eddy diffusivity, beyond the -Hostetler and Bartlein (1990) formulation, due to unresolved processes -(Fang and Stefan 1996; Subin et al. 2012a). Lake water is now allowed to +:ref:`Hostetler and Bartlein (1990)` formulation, +due to unresolved processes (:ref:`Fang and Stefan 1996`; +:ref:`Subin et al. (2012a) `). Lake water is now allowed to freeze by an arbitrary fraction for each layer, which releases latent heat and changes thermal properties. Convective mixing occurs for all lakes, even if frozen. Soil and bedrock are included beneath the lake. The full snow model is used if the snow thickness exceeds a threshold; if there are resolved snow layers, radiation transfer is predicted by -the snow-optics submodel (Chapter 3), and the remaining radiation +the snow-optics submodel (Chapter :numref:`rst_Surface Albedos`), and the remaining radiation penetrating the bottom snow layer is absorbed in the top layer of lake ice; conversely, if there are no snow layers, the solar radiation penetrating the bottom lake layer is absorbed in the top soil layer. The lakes have variable depth, and all physics is assumed valid for arbitrary depth, except for a depth-dependent enhanced mixing (section -9.5.4). Finally, a previous sign error in the calculation of eddy +:numref:`Eddy Diffusivity and Thermal Conductivities`). Finally, a previous sign error in the calculation of eddy diffusivity (specifically, the Brunt-Väisälä frequency term; eq. ) was corrected. @@ -576,48 +560,50 @@ Boundary Conditions ^^^^^^^^^^^^^^^^^^^^^^^^^ The top boundary condition, imposed at the top modeled layer -:math:`i=j_{top}` , where :math:`j_{top} =-n_{sno} +1`, is the -downwards surface flux *G* defined by the energy flux residual during -the surface temperature solution (section 9.4.3). The bottom boundary -condition, imposed at :math:`i=N_{levlak} +N_{levgrnd}` , is zero flux. +:math:`i=j_{top}` , where :math:`j_{top} =-n_{sno} +1`, is the downwards +surface flux *G* defined by the energy flux residual during the surface +temperature solution (section :numref:`Boundary Conditions Lake`). The bottom +boundary condition, imposed at :math:`i=N_{levlak} +N_{levgrnd}` , is zero flux. The 2-m windspeed :math:`u_{2}` \ (m s\ :sup:`-1`) is used in the calculation of eddy diffusivity: .. math:: - :label: ZEqnNum997977 + :label: 12.28 u_{2} =\frac{u_{*} }{k} \ln \left(\frac{2}{z_{0m} } \right)\ge 0.1. where :math:`u_{*}` \ is the friction velocity calculated in section -9.4.3 and *k* is the von Karman constant (Table 2.6). +:numref:`Boundary Conditions Lake` and *k* is the von Karman constant +(:numref:`Table Physical Constants`). .. _Eddy Diffusivity and Thermal Conductivities: Eddy Diffusivity and Thermal Conductivities ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The total eddy diffusivity :math:`K_{W}` (m\ :sup:`2` s\ :sup:`-1`) for liquid water in the lake body is given by (Subin et al. 2012a) +The total eddy diffusivity :math:`K_{W}` (m\ :sup:`2` s\ :sup:`-1`) for liquid water in the lake body is given by (:ref:`Subin et al. (2012a) `) .. math:: - :label: 12.29) + :label: 12.29 K_{W} = m_{d} \left(\kappa _{e} +K_{ed} +\kappa _{m} \right) -where :math:`\kappa _{e}` is due to wind-driven eddies (Hostetler and -Bartlein 1990), :math:`K_{ed}` is a modest enhanced diffusivity -intended to represent unresolved mixing processes (Fang and Stefan -1996), +where :math:`\kappa _{e}` is due to wind-driven eddies +(:ref:`Hostetler and Bartlein (1990)`), +:math:`K_{ed}` is a modest enhanced diffusivity +intended to represent unresolved mixing processes +(:ref:`Fang and Stefan 1996`), :math:`\kappa _{m} =\frac{\lambda _{liq} }{c_{liq} \rho _{liq} }` \ is the molecular diffusivity of water (given by the ratio of its thermal conductivity (W m\ :sup:`-1` K\ :sup:`-1`) to the product of its heat capacity (J kg\ :sup:`-1` K\ :sup:`-1`) and density -(kg m\ :sup:`-3`), values given in Table 2.6), and :math:`m_{d}` +(kg m\ :sup:`-3`), values given in :numref:`Table Physical Constants`), and :math:`m_{d}` (unitless) is a factor which increases the overall diffusivity for large lakes, intended to represent 3-dimensional mixing processes such as caused by horizontal temperature gradients. As currently implemented, .. math:: - :label: 12.30) + :label: 12.30 m_{d} =\left\{\begin{array}{l} {1,\qquad d<25{\rm m}} \\ {10,\qquad d\ge 25{\rm m}} \end{array}\right\} @@ -626,7 +612,7 @@ where *d* is the lake depth. The wind-driven eddy diffusion coefficient :math:`\kappa _{e,\, i}` (m\ :sup:`2` s\ :sup:`-1`) for layers :math:`1\le i\le N_{levlak}` is .. math:: - :label: 12.31) + :label: 12.31 \kappa _{e,\, i} =\left\{\begin{array}{l} {\frac{kw^{*} z_{i} }{P_{0} \left(1+37Ri^{2} \right)} \exp \left(-k^{*} z_{i} \right)\qquad T_{g} >T_{f} } \\ {0\qquad T_{g} \le T_{f} } \end{array}\right\} @@ -637,44 +623,45 @@ velocity (m s\ :sup:`-1`) is :math:`w^{*} =0.0012u_{2}` , and :math:`k^{*} =6.6u_{2}^{-1.84} \sqrt{\left|\sin \phi \right|}` . For the bottom layer, :math:`\kappa _{e,\, N_{levlak} } =\kappa _{e,N_{levlak} -1\, }` . As in -Hostetler and Bartlein (1990), the 2-m wind speed :math:`u_{2}` (m -s\ :sup:`-1`) (eq. ) is used to evaluate :math:`w^{*}` and -:math:`k^{*}` rather than the 10-m wind used by Henderson-Sellers -(1985). +:ref:`Hostetler and Bartlein (1990)`, +the 2-m wind speed :math:`u_{2}` (m s\ :sup:`-1`) (eq. ) is used to evaluate +:math:`w^{*}` and :math:`k^{*}` rather than the 10-m wind used by +:ref:`Henderson-Sellers (1985) `. + The Richardson number is .. math:: - :label: 12.32) + :label: 12.32 R_{i} =\frac{-1+\sqrt{1+\frac{40N^{2} k^{2} z_{i}^{2} }{w^{*^{2} } \exp \left(-2k^{*} z_{i} \right)} } }{20} where .. math:: - :label: ZEqnNum230908 + :label: 12.33 N^{2} =\frac{g}{\rho _{i} } \frac{\partial \rho }{\partial z} and :math:`g` is the acceleration due to gravity (m s\ :sup:`-2`) -(Table 2.6), :math:`\rho _{i}` is the density of water (kg +(:numref:`Table Physical Constants`), :math:`\rho _{i}` is the density of water (kg m\ :sup:`-3`), and :math:`\frac{\partial \rho }{\partial z}` is approximated as :math:`\frac{\rho _{i+1} -\rho _{i} }{z_{i+1} -z_{i} }` . Note that -because here, *z* is increasing downwards (unlike in Hostetler and -Bartlein (1990)), eq. contains no negative sign; this is a correction -from CLM4. The density of water is (Hostetler and Bartlein 1990) +because here, *z* is increasing downwards (unlike in :ref:`Hostetler and Bartlein (1990)`), eq. contains no negative sign; this is a correction +from CLM4. The density of water is +(:ref:`Hostetler and Bartlein (1990)`) .. math:: - :label: 12.34) + :label: 12.34 \rho _{i} =1000\left(1-1.9549\times 10^{-5} \left|T_{i} -277\right|^{1.68} \right). -The enhanced diffusivity :math:`K_{ed}` is given by (Fang and Stefan -1996) +The enhanced diffusivity :math:`K_{ed}` is given by +(:ref:`Fang and Stefan 1996`) .. math:: - :label: ZEqnNum809542 + :label: 12.35 K_{ed} =1.04\times 10^{-8} \left(N^{2} \right)^{-0.43} ,N^{2} \ge 7.5\times 10^{-5} {\rm s}^{2} @@ -686,7 +673,7 @@ The thermal conductivity for the liquid water portion of lake body layer given by .. math:: - :label: 12.36) + :label: 12.36 \tau _{liq,i} =K_{W} c_{liq} \rho _{liq} . @@ -695,11 +682,11 @@ The thermal conductivity of the ice portion of lake body layer *i*, constant among layers, and is given by .. math:: - :label: 12.37) + :label: 12.37 \tau _{ice,eff} =\tau _{ice} \frac{\rho _{ice} }{\rho _{liq} } -where :math:`\tau _{ice}` \ (Table 2.6) is the nominal thermal +where :math:`\tau _{ice}` \ (:numref:`Table Physical Constants`) is the nominal thermal conductivity of ice: :math:`\tau _{ice,eff}` \ is adjusted for the fact that the nominal model layer thicknesses remain constant even while the physical ice thickness exceeds the water thickness. @@ -710,15 +697,15 @@ and water fractions, assuming that they will be physically vertically stacked, and is given by .. math:: - :label: 12.38) + :label: 12.38 \tau _{i} =\frac{\tau _{ice,eff} \tau _{liq,i} }{\tau _{liq,i} I_{i} +\tau _{ice} \left(1-I_{i} \right)} . The thermal conductivity of snow, soil, and bedrock layers above and below the lake, respectively, are computed identically to those for -vegetated land units (Chapter 6), except for the adjustment of thermal -conductivity for frost heave or excess ice (Subin et al., 2012a, -Supporting Information). +vegetated land units (Chapter :numref:`rst_Soil and Snow Temperatures`), except for the adjustment of thermal +conductivity for frost heave or excess ice (:ref:`Subin et al., 2012a, +Supporting Information`). .. _Radiation Penetration: @@ -727,7 +714,7 @@ Radiation Penetration If there are no resolved snow layers, the surface absorption fraction :math:`\beta` is set according to the near-infrared fraction simulated by the atmospheric model. This is apportioned to the surface energy -budget (section 9.4.2), and thus no additional radiation is absorbed in +budget (section :numref:`Surface Properties Lake`), and thus no additional radiation is absorbed in the top :math:`z_{a}` (currently 0.6 m) of unfrozen lakes, for which the light extinction coefficient :math:`\eta` (m\ :sup:`-1`) varies between lake columns (eq. ). For frozen lakes @@ -735,7 +722,7 @@ varies between lake columns (eq. ). For frozen lakes radiation that is not apportioned to the surface energy budget is absorbed in the top lake body layer. This is a simplification, as lake ice is partially transparent. If there are resolved snow layers, then -the snow optics submodel (Chapter 3) is used to calculate the snow layer +the snow optics submodel (Chapter :numref:`rst_Surface Albedos`) is used to calculate the snow layer absorption (except for the absorption predicted for the top layer by the snow optics submodel, which is assigned to the surface energy budget), with the remainder penetrating snow layers absorbed in the top lake body @@ -745,7 +732,7 @@ For unfrozen lakes, the solar radiation remaining at depth :math:`z>z_{a}` in the lake body is given by .. math:: - :label: 12.39) + :label: 12.39 \phi =\left(1-\beta \vec{S}_{g} \right)\exp \left\{-\eta \left(z-z_{a} \right)\right\} . @@ -753,7 +740,7 @@ For all lake body layers, the flux absorbed by the layer *i*, :math:`\phi _{i}` , is .. math:: - :label: 12.40) + :label: 12.40 \phi _{i} =\left(1-\beta \vec{S}_{g} \right)\left[\exp \left\{-\eta \left(z_{i} -\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}-\exp \left\{-\eta \left(z_{i} +\frac{\Delta z_{i} }{2} -z_{a} \right)\right\}\right] . @@ -763,11 +750,11 @@ The remaining flux exiting the bottom of layer :math:`i=N_{levlak}` is absorbed in the top soil layer. The light extinction coefficient :math:`\eta` (m\ :sup:`-1`), if -not provided as external data, is a function of depth *d* (m) (Subin et -al. 2012a): +not provided as external data, is a function of depth *d* (m) +(:ref:`Subin et al. (2012a) `): .. math:: - :label: ZEqnNum284649 + :label: 12.41 \eta =1.1925d^{-0.424} . @@ -781,7 +768,7 @@ The vertically-integrated heat capacity for each lake layer, water and ice fractions: .. math:: - :label: 12.42) + :label: 12.42 c_{v,i} =\Delta z_{i} \rho _{liq} \left[c_{liq} \left(1-I_{i} \right)+c_{ice} I_{i} \right] . @@ -790,7 +777,7 @@ as the thickness of the layer is fixed. The total heat capacity :math:`c_{v,i}` for each soil, snow, and bedrock layer (J m\ :sup:`-2`) is determined as for vegetated land -units (Chapter 6), as the sum of the heat capacities for the water, ice, +units (Chapter :numref:`rst_Soil and Snow Temperatures`), as the sum of the heat capacities for the water, ice, and mineral constituents. .. _Crank-Nicholson Solution Lake: @@ -799,8 +786,9 @@ Crank-Nicholson Solution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The solution method for thermal diffusion is similar to that used for -soil (Chapter 6), except that the lake body layers are sandwiched -between the snow and soil layers (section 9.5.1), and radiation flux is +soil (Chapter :numref:`rst_Soil and Snow Temperatures`), except that the +lake body layers are sandwiched between the snow and soil layers +(section :numref:`Introduction Lake`), and radiation flux is absorbed throughout the lake layers. Before solution, layer temperatures :math:`T_{i}` (K), thermal conductivities :math:`\tau _{i}` (W m\ :sup:`-1` K\ :sup:`-1`), heat capacities :math:`c_{v,i}` @@ -812,7 +800,7 @@ calculated as the harmonic mean of the conductivities of the neighboring layers: .. math:: - :label: 12.43) + :label: 12.43 \lambda _{i} =\frac{\tau _{i} \tau _{i+1} \left(z_{i+1} -z_{i} \right)}{\tau _{i} \left(z_{i+1} -\hat{z}_{i} \right)+\tau _{i+1} \left(\hat{z}_{i} -z_{i} \right)} , @@ -824,7 +812,7 @@ between lake and soil. The governing equation is discretized for each layer as .. math:: - :label: ZEqnNum991615 + :label: 12.44 \frac{c_{v,i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=F_{i-1} -F_{i} +\phi _{i} @@ -838,18 +826,19 @@ Eq. is solved using the semi-implicit Crank-Nicholson Method, resulting in a tridiagonal system of equations: .. math:: - :label: 12.45) + :label: 12.45 \begin{array}{l} {r_{i} =a_{i} T_{i-1}^{n+1} +b_{i} T_{i}^{n+1} +cT_{i+1}^{n+1} ,} \\ {a_{i} =-0.5\frac{\Delta t}{c_{v,i} } \frac{\partial F_{i-1} }{\partial T_{i-1}^{n} } ,} \\ {b_{i} =1+0.5\frac{\Delta t}{c_{v,i} } \left(\frac{\partial F_{i-1} }{\partial T_{i-1}^{n} } +\frac{\partial F_{i} }{\partial T_{i}^{n} } \right),} \\ {c_{i} =-0.5\frac{\Delta t}{c_{v,i} } \frac{\partial F_{i} }{\partial T_{i}^{n} } ,} \\ {r_{i} =T_{i}^{n} +0.5\frac{\Delta t}{c_{v,i} } \left(F_{i-1} -F_{i} \right)+\frac{\Delta t}{c_{v,i} } \phi _{i} .} \end{array} The fluxes :math:`F_{i}` are defined as follows: for the top layer, :math:`F_{j_{top} -1} =2G;a_{j_{top} } =0`, where *G* is defined as in -section 9.4.3 (the factor of 2 merely cancels out the Crank-Nicholson -0.5 in the equation for :math:`r_{j_{top} }` ). For the bottom layer, -:math:`F_{N_{levlak} +N_{levgrnd} } =0`. For all other layers: +section :numref:`Boundary Conditions Lake` (the factor of 2 merely cancels +out the Crank-Nicholson 0.5 in the equation for :math:`r_{j_{top} }` ). +For the bottom layer, :math:`F_{N_{levlak} +N_{levgrnd} } =0`. +For all other layers: .. math:: - :label: 12.46) + :label: 12.46 F_{i} =\lambda _{i} \frac{T_{i} ^{n} -T_{i+1}^{n} }{z_{n+1} -z_{n} } . @@ -859,7 +848,7 @@ Phase Change ^^^^^^^^^^^^^^^^^^ Phase change in the lake, snow, and soil is done similarly to that done -for the soil and snow for vegetated land units (Chapter 6), except +for the soil and snow for vegetated land units (Chapter :numref:`rst_Soil and Snow Temperatures`), except without the allowance for freezing point depression in soil underlying lakes. After the heat diffusion is calculated, phase change occurs in a given layer if the temperature is below freezing and liquid water @@ -869,29 +858,30 @@ If melting occurs, the available energy for melting, :math:`Q_{avail}` (J m\ :sup:`-2`), is computed as .. math:: - :label: ZEqnNum598199 + :label: 12.47 Q_{avail} =\left(T_{i} -T_{f} \right)c_{v,i} where :math:`T_{i}` is the temperature of the layer after thermal -diffusion (section 9.5.7), and :math:`c_{v,i}` \ is as calculated in -section 9.5.6. The mass of melt in the layer *M* (kg m\ :sup:`-2`) -is given by +diffusion (section :numref:`Crank-Nicholson Solution Lake`), and +:math:`c_{v,i}` \ is as calculated in section +:numref:`Heat Capacities Lake`. The mass of melt in the layer *M* +(kg m\ :sup:`-2`) is given by .. math:: - :label: 12.48) + :label: 12.48 M=\min \left\{M_{ice} ,\frac{Q_{avail} }{H_{fus} } \right\} where :math:`H_{fus}` (J kg\ :sup:`-1`) is the latent heat of -fusion of water (Table 2.6), and :math:`M_{ice}` is the mass of ice in +fusion of water (:numref:`Table Physical Constants`), and :math:`M_{ice}` is the mass of ice in the layer: :math:`I_{i} \rho _{liq} \Delta z_{i}` for a lake body layer, or simply the soil / snow ice content state variable (:math:`w_{ice}` ) for a soil / snow layer. The heat remainder, :math:`Q_{rem}` \ is given by .. math:: - :label: ZEqnNum889387 + :label: 12.49 Q_{rem} =Q_{avail} -MH_{fus} . @@ -900,7 +890,7 @@ downwards by :math:`M`, and the temperature :math:`T_{i}` of the layer is adjusted to .. math:: - :label: ZEqnNum926437 + :label: 12.50 T_{i} =T_{f} +\frac{Q_{rem} }{c'_{v,i} } @@ -910,7 +900,7 @@ If freezing occurs, :math:`Q_{avail}` is again given by but will be negative. The melt :math:`M`, also negative, is given by .. math:: - :label: 12.51) + :label: 12.51 M=\max \left\{-M_{liq} ,\frac{Q_{avail} }{H_{fus} } \right\} @@ -937,7 +927,8 @@ maintaining constant density. Convection ^^^^^^^^^^^^^^^^ -Convective mixing is based on Hostetler et al.’s (1993, 1994) coupled +Convective mixing is based on +:ref:`Hostetler et al.’s (1993, 1994)` coupled lake-atmosphere model, adjusting the lake temperature after diffusion and phase change to maintain a stable density profile. Unfrozen lakes overturn when :math:`\rho _{i} >\rho _{i+1}` , in which case the layer @@ -946,9 +937,11 @@ applied to layers 1 to :math:`i+1` and the densities are updated. This scheme is applied iteratively to layers :math:`1\le i`), as occasionally +these can be induced by +heat expelled from the sediments (not present in the original +:ref:`Hostetler et al. (1994)` model). Mixing proceeds +from the bottom upward in this case (i.e., first mixing layers :math:`i=N_{levlak} -1` and :math:`i=N_{levlak}` , then checking :math:`i=N_{levlak} -2` and :math:`i=N_{levlak} -1` and mixing down to :math:`i=N_{levlak}` if @@ -963,14 +956,14 @@ When this occurs, these two lake layers and all those above mix. Total enthalpy *Q* is conserved as .. math:: - :label: 12.52) + :label: 12.52 Q=\sum _{j=1}^{i+1}\Delta z_{j} \rho _{liq} \left(T_{j} -T_{f} \right)\left[\left(1-I_{j} \right)c_{liq} +I_{j} c_{ice} \right] . Once the average ice fraction :math:`I_{av}` is calculated from .. math:: - :label: 12.53) + :label: 12.53 \begin{array}{l} {I_{av} =\frac{\sum _{j=1}^{i+1}I_{j} \Delta z_{j} }{Z_{i+1} } ,} \\ {Z_{i+1} =\sum _{j=1}^{i+1}\Delta z_{j} ,} \end{array} @@ -988,7 +981,7 @@ If :math:`Q > 0`, then :math:`T_{froz} =T_{f}` , and :math:`T_{unfr}` is given by .. math:: - :label: 12.54) + :label: 12.54 T_{unfr} =\frac{Q}{\rho _{liq} Z_{i+1} \left[\left(1-I_{av} \right)c_{liq} \right]} +T_{f} . @@ -996,7 +989,7 @@ If :math:`Q < 0`, then :math:`T_{unfr} =T_{f}` , and :math:`T_{froz}` is given by .. math:: - :label: 12.55) + :label: 12.55 T_{froz} =\frac{Q}{\rho _{liq} Z_{i+1} \left[I_{av} c_{ice} \right]} +T_{f} . @@ -1015,7 +1008,7 @@ to *i* + 1, the ice fraction and temperature are set as follows, where by the heat capacity of the layer to yield .. math:: - :label: 12.56) + :label: 12.56 T_{j} =\frac{T_{froz} I_{j} c_{ice} +T_{unfr} \left(1-I_{j} \right)c_{liq} }{I_{j} c_{ice} +\left(1-I_{j} \right)c_{liq} } . @@ -1031,12 +1024,12 @@ re-written to yield the total enthalpy of the lake system (J m\ :sup:`-2`) :math:`H_{tot}` : .. math:: - :label: 12.57) + :label: 12.57 H_{tot} =\sum _{i=j_{top} }^{N_{levlak} +N_{levgrnd} }\left[c_{v,i} \left(T_{i} -T_{f} \right)+M_{liq,i} H_{fus} \right] -W_{sno,bulk} H_{fus} where :math:`M_{liq,i}` is the water mass of the *i*\ th layer (similar -to section 9.5.8), and :math:`W_{sno,bulk}` is the mass of snow-ice not +to section :numref:`Phase Change Lake`), and :math:`W_{sno,bulk}` is the mass of snow-ice not present in resolved snow layers. This expression is evaluated once at the beginning and once at the end of the timestep (re-evaluating each :math:`c_{v,i}` ), and the change is compared with the net surface @@ -1044,7 +1037,7 @@ energy flux to yield the error flux :math:`E_{soi}` (W m\ :sup:`-2`): .. math:: - :label: 12.58) + :label: 12.58 E_{soi} =\frac{\Delta H_{tot} }{\Delta t} -G-\sum _{i=j_{top} }^{N_{levlak} +N_{levgrnd} }\phi _{i} @@ -1074,7 +1067,8 @@ There are some modifications to the soil and snow parameterizations as compared with the soil in vegetated land units, or the snow overlying other impervious columns. The soil can freeze or thaw, with the allowance for frost heave (or the initialization of excess ice) -(sections 9.5.4 and 9.5.8), but no air-filled pore space is allowed in +(sections :numref:`Eddy Diffusivity and Thermal Conductivities` and +:numref:`Phase Change Lake`), but no air-filled pore space is allowed in the soil. To preserve numerical stability in the lake model (which uses a slightly different surface flux algorithm than over other non-vegetated land units), two changes are made to the snow model. @@ -1094,7 +1088,7 @@ Water Balance The total water balance of the system is given by .. math:: - :label: ZEqnNum932128 + :label: 12.59 \Delta W_{sno} +\sum _{i=1}^{n_{levsoi} }\left(\Delta w_{liq,i} +\Delta w_{ice,i} \right) =\left(q_{rain} +q_{sno} -E_{g} -q_{rgwl} -q_{snwcp,\, ice} \right)\Delta t @@ -1103,10 +1097,10 @@ where :math:`W_{sno}` (kg m\ :sup:`-2`) is the total mass of snow :math:`w_{liq,i}` and :math:`w_{ice,i}` are the masses of water phases (kg m\ :sup:`-2`) in soil layer *i*, :math:`q_{rain}` and :math:`q_{sno}` are the precipitation forcing from the atmosphere (kg -m\ :sup:`-2` s\ :sup:`-1`), :math:`q_{snwcp,\, ice}` is the -ice runoff associated with snow-capping (below), :math:`E_{g}` is the -ground evaporation (section 9.4.3), and :math:`n_{levsoi}` is the -number of hydrologically active soil layers (as opposed to dry bedrock +m\ :sup:`-2` s\ :sup:`-1`), :math:`q_{snwcp,\, ice}` is the ice runoff +associated with snow-capping (below), :math:`E_{g}` is the ground +evaporation (section :numref:`Surface Flux Solution Lake`), and :math:`n_{levsoi}` +is the number of hydrologically active soil layers (as opposed to dry bedrock layers). .. _Precipitation, Evaporation, and Runoff Lake: @@ -1120,8 +1114,9 @@ As for other land types, incident snowfall accumulates (with ice mass exceeds a minimum thickness :math:`s_{\min }` , at which point a resolved snow layer is initiated, with water, ice, dissolved aerosol, snow-grain radius, etc., state variables tracked by the Snow Hydrology -submodel (section 7.2). The density of fresh snow is assigned as for -other land types (section 7.2). Solid precipitation is added immediately +submodel (Chapter :numref:`rst_Snow Hydrology`). The density of fresh snow is +assigned as for other land types (Chapter :numref:`rst_Snow Hydrology`). +Solid precipitation is added immediately to the snow, while liquid precipitation is added to snow layers, if they exist, after accounting for dew, frost, and sublimation (below). If :math:`z_{sno}` exceeds :math:`s_{\min }` after solid precipitation is @@ -1141,29 +1136,30 @@ water mass than it contains). If there are no resolved snow layers but given by .. math:: - :label: 12.60) + :label: 12.60 q_{sub,sno} =\min \left\{E_{g} ,\frac{W_{sno} }{\Delta t} \right\} . If :math:`E_{g} <0,T_{g} \le T_{f}` , and there are no resolved snow layers or the top snow layer is not unfrozen, then the rate of frost production :math:`q_{frost} =\left|E_{g} \right|`. If :math:`E_{g} <0` -but the top snow layer has completely thawed during the Phase Change -step of the Lake Temperature solution (section 9.5.8), then frost (or -dew) is not allowed to accumulate (:math:`q_{frost} =0`), to insure that -the layer is eliminated by the Snow Hydrology (section 7.2) code. (If -:math:`T_{g} >T_{f}` , then no snow is present (section 9.4.3), and +but the top snow layer has completely thawed during the Phase Change step +of the Lake Temperature solution (section :numref:`Phase Change Lake`), then +frost (or dew) is not allowed to accumulate (:math:`q_{frost} =0`), to +insure that the layer is eliminated by the Snow Hydrology +(Chapter :numref:`rst_Snow Hydrology`) code. (If :math:`T_{g} >T_{f}`, +then no snow is present (section :numref:`Surface Flux Solution Lake`), and evaporation or dew deposition is balanced by :math:`q_{rgwl}` .) The snowpack is updated for frost and sublimation: .. math:: - :label: 12.61) + :label: 12.61 W_{sno} =W_{sno} +\Delta t\left(q_{frost} -q_{sub,sno} \right) . -If there are resolved snow layers, then this update occurs using the -Snow Hydrology submodel (section 7.2). Otherwise, the snow ice mass is -updated directly, and :math:`z_{sno}` is adjusted by the same +If there are resolved snow layers, then this update occurs using the Snow +Hydrology submodel (Chapter :numref:`rst_Snow Hydrology`). Otherwise, the +snow ice mass is updated directly, and :math:`z_{sno}` is adjusted by the same proportion as the snow ice (i.e., maintaining the same density), unless there was no snow before adding the frost, in which case the density is assumed to be 250 kg m\ :sup:`-3`. @@ -1177,7 +1173,7 @@ The combined water and ice soil volume fraction in a soil layer :math:`\theta _{i}` is given by .. math:: - :label: 12.62) + :label: 12.62 \theta _{i} =\frac{1}{\Delta z_{i} } \left(\frac{w_{ice,i} }{\rho _{ice} } +\frac{w_{liq,i} }{\rho _{liq} } \right) . @@ -1186,7 +1182,7 @@ saturation (as may occur when ice melts), then the liquid water mass is adjusted to .. math:: - :label: 12.63) + :label: 12.63 w_{liq,i} =\left(\theta _{sat,i} \Delta z_{i} -\frac{w_{ice,i} }{\rho _{ice} } \right)\rho _{liq} . @@ -1195,7 +1191,7 @@ Otherwise, if excess ice is melting and water in the layer is reset to .. math:: - :label: 12.64) + :label: 12.64 w_{liq,i} = \theta _{sat,i} \rho _{liq} \Delta z_{i} @@ -1213,10 +1209,11 @@ adjusts the minimum resolved snow layer thickness for lake columns as compared to non-lake columns. The value of :math:`z_{lsa}` is chosen to satisfy the CFL condition for the model timestep. By default, :math:`\tilde{s}_{\min }` \ = 1 cm and :math:`s_{\min }` \ = 4 cm. See -Subin et al. (2012a; including Supporting Information) for further -discussion. +:ref:`Subin et al. (2012a; including Supporting Information)` +for further discussion. -The rules for combining and sub-dividing snow layers (section 7.2.7) are +The rules for combining and sub-dividing snow layers (section +:numref:`Snow Layer Combination and Subdivision`) are adjusted for lakes to maintain minimum thicknesses of :math:`s_{\min }` and to increase all target layer thicknesses by :math:`z_{lsa}` . The rules for combining layers are modified by simply increasing layer @@ -1234,5 +1231,5 @@ are performed. In rare instances, resolved snow layers may be present over an unfrozen top lake body layer. In this case, the snow layers may be eliminated if -enough heat is present in the top layer to melt the snow: see Subin et -al. (2012a, Supporting Information). +enough heat is present in the top layer to melt the snow: see +:ref:`Subin et al. (2012a, Supporting Information) `. diff --git a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index c881a2c7c2..f78f464779 100644 --- a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -4,16 +4,19 @@ Methane Model ================= The representation of processes in the methane biogeochemical model -integrated in CLM [CLM4Me; (Riley et al. 2011a)] is based on several -previously published models (Cao et al. 1996; Petrescu et al. 2010; Tian -et al. 2010; Walter et al. 2001; Wania et al. 2010; Zhang et al. 2002; -Zhuang et al. 2004). Although the model has similarities with these -precursor models, a number of new process representations and +integrated in CLM [CLM4Me; (:ref:`Riley et al. 2011a`)] +is based on several previously published models +(:ref:`Cao et al. 1996`; :ref:`Petrescu et al. 2010`; +:ref:`Tianet al. 2010`; :ref:`Walter et al. 2001`; +:ref:`Wania et al. 2010`; :ref:`Zhang et al. 2002`; +:ref:`Zhuang et al. 2004`). Although the model has similarities +with these precursor models, a number of new process representations and parameterization have been integrated into CLM. -Mechanistically modeling net surface CH\ :sub:`4` emissions -requires representing a complex and interacting series of processes. We -first (section 19.1) describe the overall model structure and flow of +Mechanistically modeling net surface CH\ :sub:`4` emissions requires +representing a complex and interacting series of processes. We first +(section :numref:`Methane Model Structure and Flow`) describe the overall +model structure and flow of information in the CH\ :sub:`4` model, then describe the methods used to represent: CH\ :sub:`4` mass balance; CH\ :sub:`4` production; ebullition; aerenchyma transport; CH\ :sub:`4` @@ -22,6 +25,8 @@ numerical solution, water table interface, etc.; seasonal inundation effects; and impact of seasonal inundation on CH\ :sub:`4` production. +.. _Methane Model Structure and Flow: + Methane Model Structure and Flow ------------------------------------- @@ -36,17 +41,21 @@ fraction; performs a mass balance check; and calculates the average gridcell CH\ :sub:`4` production, oxidation, and exchanges with the atmosphere. +.. _Governing Mass-Balance Relationship: + Governing Mass-Balance Relationship ---------------------------------------- -The model (:numref:`Figure Methane Schematic`) accounts for CH\ :sub:`4` production in -the anaerobic fraction of soil (*P*, mol m\ :sup:`-3` s\ :sup:`-1`), ebullition (*E*, mol m\ :sup:`-3` s\ :sup:`-1`), -aerenchyma transport (*A*, mol m\ :sup:`-3` s\ :sup:`-1`), aqueous and gaseous diffusion (:math:`{F}_{D}`, -mol m\ :sup:`-2` s\ :sup:`-1`), and oxidation (*O*, mol m\ :sup:`-3` s\ :sup:`-1`) via a transient reaction +The model (:numref:`Figure Methane Schematic`) accounts for CH\ :sub:`4` +production in the anaerobic fraction of soil (*P*, mol m\ :sup:`-3` +s\ :sup:`-1`), ebullition (*E*, mol m\ :sup:`-3` s\ :sup:`-1`), +aerenchyma transport (*A*, mol m\ :sup:`-3` s\ :sup:`-1`), aqueous and +gaseous diffusion (:math:`{F}_{D}`, mol m\ :sup:`-2` s\ :sup:`-1`), and +oxidation (*O*, mol m\ :sup:`-3` s\ :sup:`-1`) via a transient reaction diffusion equation: .. math:: - :label: ZEqnNum628535 + :label: 24.1 \frac{\partial \left(RC\right)}{\partial t} =\frac{\partial F_{D} }{\partial z} +P\left(z,t\right)-E\left(z,t\right)-A\left(z,t\right)-O\left(z,t\right) @@ -84,9 +93,12 @@ into the inundated concentration when the inundated fraction increases. Schematic representation of biological and physical processes integrated in CLM that affect the net CH\ :sub:`4` - surface flux (:ref:`Riley et al. 2011a`). (left) Fully inundated portion of a + surface flux (:ref:`Riley et al. 2011a`). (left) + Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. +.. _CH4 Production: + CH\ :sub:`4` Production ---------------------------------- @@ -108,25 +120,25 @@ redox potential (:math:`f_{pE}`), and a factor accounting for the seasonal inundation fraction (*S*, described below): .. math:: - :label: ZEqnNum109798 + :label: 24.2 P=R_{H} f_{CH_{4} } f_{T} f_{pH} f_{pE} S. -Here, :math:`f_{CH_{4} }` is the baseline ratio between -CO\ :sub:`2` and CH\ :sub:`4` production (all parameters -values are given in :numref:`Table Methane Parameter descriptions`). Currently, :math:`f_{CH_{4} }` is -modified to account for our assumptions that methanogens may have a +Here, :math:`f_{CH_{4} }` is the baseline ratio between CO\ :sub:`2` +and CH\ :sub:`4` production (all parameters values are given in +:numref:`Table Methane Parameter descriptions`). Currently, :math:`f_{CH_{4} }` +is modified to account for our assumptions that methanogens may have a higher Q\ :math:`{}_{10}` than aerobic decomposers; are not N limited; and do not have a low-moisture limitation. -When the single BGC soil level is used in CLM (Chapter 15), the +When the single BGC soil level is used in CLM (Chapter :numref:`rst_Decomposition`), the temperature factor, :math:`f_{T}` , is set to 0 for temperatures equal to or below freezing, even though CLM allows heterotrophic respiration below freezing. However, if the vertically resolved BGC soil column is used, CH\ :sub:`4` production continues below freezing because liquid water stress limits decomposition. The base temperature for the -:math:`{Q}_{10}` factor, :math:`{T}_{B}`, is 22\ :sup:`o` C and effectively modified the base -:math:`f_{CH_{4}}` value. +:math:`{Q}_{10}` factor, :math:`{T}_{B}`, is 22\ :sup:`o` C and effectively +modified the base :math:`f_{CH_{4}}` value. For the single-layer BGC version, :math:`{R}_{H}` is distributed among soil levels by assuming that 50% is associated with the roots @@ -136,10 +148,11 @@ decomposition algorithm). For the vertically resolved BGC version, the prognosed distribution of :math:`{R}_{H}` is used to estimate CH\ :sub:`4` production. The factor :math:`f_{pH}` is nominally set to 1, although a static -spatial map of *pH* can be used to determine this factor (Dunfield et al. 1993) by applying: +spatial map of *pH* can be used to determine this factor +(:ref:`Dunfield et al. 1993`) by applying: .. math:: - :label: 24.3) + :label: 24.3 f_{pH} =10^{-0.2235pH^{2} +2.7727pH-8.6} . @@ -156,7 +169,7 @@ anoxic microsites above the water table, we apply the Arah and Stephen (1998) estimate of anaerobic fraction: .. math:: - :label: 24.4) + :label: 24.4 \varphi =\frac{1}{1+\eta C_{O_{2} } } . @@ -195,7 +208,7 @@ O\ :sub:`2` mass balance solution. +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ | | :math:`{C}_{e,min}` | 0.15 | NA | - | CH\ :sub:`4` concentration to end ebullition | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ - | Diffusion | :math:`f_{D_{0} }` | 1 | 1, 10 | m\ :sup:`2` s\ :sup:`-1` | Diffusion coefficient multiplier (Table 19.2) | + | Diffusion | :math:`f_{D_{0} }` | 1 | 1, 10 | m\ :sup:`2` s\ :sup:`-1` | Diffusion coefficient multiplier (Table 24.2) | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ | Aerenchyma | *p* | 0.3 | NA | - | Grass aerenchyma porosity | +--------------+----------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+---------------------------------------------+--------------------------------------------------------------------------------------------+ @@ -220,20 +233,21 @@ Briefly, the simulated aqueous CH\ :sub:`4` concentration in each soil level is used to estimate the expected equilibrium gaseous partial pressure (:math:`C_{e}` ), as a function of temperature and depth below the water table, by first estimating the Henry’s law partitioning -coefficient (:math:`k_{h}^{C}` ) by the method described in Wania et al. (2010): +coefficient (:math:`k_{h}^{C}` ) by the method described in +:ref:`Wania et al. (2010)`: .. math:: - :label: 24.5) + :label: 24.5 \log \left(\frac{1}{k_{H} } \right)=\log k_{H}^{s} -\frac{1}{C_{H} } \left(\frac{1}{T} -\frac{1}{T^{s} } \right) .. math:: - :label: ZEqnNum493232 + :label: 24.6 k_{h}^{C} =Tk_{H} R_{g} .. math:: - :label: 24.7) + :label: 24.7 C_{e} =\frac{C_{w} R_{g} T}{\theta _{s} k_{H}^{C} p} @@ -248,11 +262,14 @@ ponding (if applicable). When the CH\ :sub:`4` partial pressure exceeds 15% of the local pressure (Baird et al. 2004; Strack et al. 2006; Wania et al. 2010), bubbling occurs to remove CH\ :sub:`4` to below this value, modified by the fraction of CH\ :sub:`4` in -the bubbles [taken as 57%; (Kellner et al. 2006; Wania et al. 2010)]. +the bubbles [taken as 57%; (:ref:`Kellner et al. 2006`; +:ref:`Wania et al. 2010`)]. Bubbles are immediately added to the surface flux for saturated columns and are placed immediately above the water table interface in unsaturated columns. +.. _Aerenchyma Transport: + Aerenchyma Transport ------------------------- @@ -265,7 +282,7 @@ also occur, but we did not include that mechanism in the current model. The diffusive transport through aerenchyma (*A*, mol m\ :sup:`-2` s\ :sup:`-1`) from each soil layer is represented in the model as: .. math:: - :label: ZEqnNum158128 + :label: 24.8 A=\frac{C\left(z\right)-C_{a} }{{\raise0.7ex\hbox{$ r_{L} z $}\!\mathord{\left/ {\vphantom {r_{L} z D}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ D $}} +r_{a} } pT\rho _{r} , @@ -278,21 +295,20 @@ height (s m:sup:`-1`); and :math:`\rho _{r}` is the rooting density as a function of depth (-). The gaseous concentration is calculated with Henry’s law as described in equation . -Based on the ranges reported in Colmer (2003), we have chosen baseline -aerenchyma porosity values of 0.3 for grass and crop PFTs and 0.1 for +Based on the ranges reported in :ref:`Colmer (2003)`, we have chosen +baseline aerenchyma porosity values of 0.3 for grass and crop PFTs and 0.1 for tree and shrub PFTs. The aerenchyma area varies over the course of the growing season; we parameterize this dependency using the simulated leaf -area index *L* (m:sup:`2` m\ :sup:`-2`), as in Wania et al. -(2010): +area index *L* (m:sup:`2` m\ :sup:`-2`), as in :ref:`Wania et al. 2010`: .. math:: - :label: 24.9) + :label: 24.9 T=\frac{f_{N} N_{a} L}{0.22} \pi R^{2} . Here :math:`N_{a}` is annual net primary production (NPP, mol m\ :sup:`-2` s\ :sup:`-1`); *R* is the aerenchyma radius -(2.9:math:`\times`\ 10\ :sup:`-3` m); :math:`{f}_{N}` is the +(2.9 :math:`\times`\ 10\ :sup:`-3` m); :math:`{f}_{N}` is the belowground fraction of annual NPP; and the 0.22 factor represents the amount of C per tiller. O\ :sub:`2` can also diffuse in from the atmosphere to the soil layer via the reverse of the same pathway, with @@ -308,19 +324,21 @@ and the CLM predicted transpiration (:math:`F_{T}` ) for each PFT, assuming that no methane was oxidized inside the plant tissue: .. math:: - :label: 24.10) + :label: 24.10 F_{CH_{4} -T} =\sum _{j}\rho _{r,j} F_{T} C_{CH_{4} ,j} . +.. _CH4 Oxidation: + CH\ :sub:`4` Oxidation --------------------------------- CLM represents CH\ :sub:`4` oxidation with double Michaelis-Menten -kinetics (Arah and Stephen 1998; Segers 1998), dependent on both the -gaseous CH\ :sub:`4` and O\ :sub:`2` concentrations: +kinetics (:ref:`Arah and Stephen 1998`; :ref:`Segers 1998`), +dependent on both the gaseous CH\ :sub:`4` and O\ :sub:`2` concentrations: .. math:: - :label: 24.11) + :label: 24.11 R_{oxic} =R_{o,\max } \left[\frac{C_{CH_{4} } }{K_{CH_{4} } +C_{CH_{4} } } \right]\left[\frac{C_{O_{2} } }{K_{O_{2} } +C_{O_{2} } } \right]Q_{10} F_{\vartheta } @@ -332,23 +350,31 @@ m\ :sup:`-3` s\ :sup:`-1`); and :math:`{Q}_{10}` specifies the temperature dependence of the reaction with a base temperature set to 12 :sup:`o` C. The soil moisture limitation factor :math:`F_{\theta }` is applied above the water table to -represent water stress for methanotrophs. Based on the data in Schnell -and King (1996), we take :math:`F_{\theta } = {e}^{-P/{P}_{c}}`, where *P* is the soil moisture potential and -:math:`{P}_{c} = -2.4 \times {10}^{5}` mm. +represent water stress for methanotrophs. Based on the data in +:ref:`Schnell and King (1996)`, we take +:math:`F_{\theta } = {e}^{-P/{P}_{c}}`, where *P* is the soil moisture +potential and :math:`{P}_{c} = -2.4 \times {10}^{5}` mm. + +.. _Reactive Transport Solution: Reactive Transport Solution -------------------------------- The solution to equation is solved in several sequential steps: resolve competition for CH\ :sub:`4` and O\ :sub:`2` (section -19.7.1); add the ebullition flux into the layer directly above the water +:numref:`Competition for CH4and O2`); add the ebullition flux into the +layer directly above the water table or into the atmosphere; calculate the overall CH\ :sub:`4` or O\ :sub:`2` source term based on production, aerenchyma transport, ebullition, and oxidation; establish boundary conditions, including surface conductance to account for snow, ponding, and -turbulent conductances and bottom flux condition (section 19.7.2); -calculate diffusivity (section 19.7.3); and solve the resulting mass -balance using a tridiagonal solver (section 19.7.5). +turbulent conductances and bottom flux condition +(section :numref:`CH4 and O2 Source Terms`); calculate diffusivity +(section :numref:`Aqueous and Gaseous Diffusion`); and solve the resulting +mass balance using a tridiagonal solver (section +:numref:`Crank-Nicholson Solution Methane`). + +.. _Competition for CH4and O2: Competition for CH\ :sub:`4` and O\ :sub:`2` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -371,7 +397,9 @@ the concentrations are reset to zero; if it occurs for CH\ :sub:`4`, the surface flux is adjusted and the concentration is set to zero if the adjustment is not too large. -19.7.2 CH\ :sub:`4` and O\ :sub:`2` Source Terms +.. _CH4 and O2 Source Terms: + +CH\ :sub:`4` and O\ :sub:`2` Source Terms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The overall CH\ :sub:`4` net source term consists of production, @@ -383,12 +411,17 @@ source term consists of O\ :sub:`2` losses from methanotrophy, SOM decomposition, and autotrophic respiration, and an O\ :sub:`2` source through aerenchyma. -19.7.3 Aqueous and Gaseous Diffusion +.. _Aqueous and Gaseous Diffusion: + +Aqueous and Gaseous Diffusion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For gaseous diffusion, we adopted the temperature dependence of molecular free-air diffusion coefficients (:math:`{D}_{0}` -(m:sup:`2` s\ :sup:`-1`)) as described by Lerman et al. (1979) and applied by Wania et al. (2010) (:numref:`Table Temperature dependence of aqueous and gaseous diffusion`). +(m:sup:`2` s\ :sup:`-1`)) as described by +:ref:`Lerman (1979) ` and applied by +:ref:`Wania et al. (2010)` +(:numref:`Table Temperature dependence of aqueous and gaseous diffusion`). .. _Table Temperature dependence of aqueous and gaseous diffusion: @@ -403,26 +436,26 @@ molecular free-air diffusion coefficients (:math:`{D}_{0}` +----------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------+ Gaseous diffusivity in soils also depends on the molecular diffusivity, -soil structure, porosity, and organic matter content. Moldrup et al. -(2003), using observations across a range of unsaturated mineral soils, -showed that the relationship between effective diffusivity -(:math:`D_{e}` (m:sup:`2` s\ :sup:`-1`)) and soil +soil structure, porosity, and organic matter content. +:ref:`Moldrup et al. (2003)`, using observations across a +range of unsaturated mineral soils, showed that the relationship between +effective diffusivity (:math:`D_{e}` (m:sup:`2` s\ :sup:`-1`)) and soil properties can be represented as: .. math:: - :label: ZEqnNum730978 + :label: 24.12 D_{e} =D_{0} \theta _{a}^{2} \left(\frac{\theta _{a} }{\theta _{s} } \right)^{{\raise0.7ex\hbox{$ 3 $}\!\mathord{\left/ {\vphantom {3 b}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ b $}} } , where :math:`\theta _{a}` and :math:`\theta _{s}` are the air-filled and total (saturated water-filled) porosities (-), respectively, and *b* -is the slope of the water retention curve (-). However, Iiyama and -Hasegawa (2005) have shown that the original Millington-Quirk -(Millington and Quirk 1961) relationship matched measurements more -closely in unsaturated peat soils: +is the slope of the water retention curve (-). However, :ref:`Iiyama and +Hasegawa (2005)` have shown that the original Millington-Quirk +(:ref:`Millington and Quirk 1961`) relationship matched +measurements more closely in unsaturated peat soils: .. math:: - :label: ZEqnNum437147 + :label: 24.13 D_{e} =D_{0} \frac{\theta _{a} ^{{\raise0.7ex\hbox{$ 10 $}\!\mathord{\left/ {\vphantom {10 3}} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ 3 $}} } }{\theta _{s} ^{2} } @@ -431,24 +464,27 @@ and equation for soils with more than 130 kg m\ :sup:`-3` organic matter content. A linear interpolation between these two limits is applied for soils with SOM content below 130 kg m\ :sup:`-3`. For aqueous diffusion in the saturated part of the soil column, we applied -(Moldrup et al. 2003): +(:ref:`Moldrup et al. (2003)`): .. math:: - :label: 24.14) + :label: 24.14 D_{e} =D_{0} \theta _{s} ^{2} . To simplify the solution, we assumed that gaseous diffusion dominates above the water table interface and aqueous diffusion below the water table interface. Descriptions, baseline values, and dimensions for -parameters specific to the CH\ :sub:`4` model are given in Table -19.1. For freezing or frozen soils below the water table, diffusion is -limited to the remaining liquid (CLM allows for some freezing point -depression), and the diffusion coefficients are scaled by the +parameters specific to the CH\ :sub:`4` model are given in +:numref:`Table Methane Parameter descriptions`. For freezing or frozen +soils below the water table, diffusion is limited to the remaining +liquid (CLM allows for some freezing point depression), and the diffusion +coefficients are scaled by the volume-fraction of liquid. For unsaturated soils, Henry’s law equilibrium is assumed at the interface with the water table. -19.7.4 Boundary Conditions +.. _Boundary Conditions: + +Boundary Conditions ^^^^^^^^^^^^^^^^^^^^^^^^^^ We assume the CH\ :sub:`4` and O\ :sub:`2` surface fluxes @@ -458,7 +494,8 @@ the gaseous concentration in the first soil layer (unsaturated soils) or in equilibrium with the water (saturated soil\ :math:`w\left(C_{1}^{n} -C_{a} \right)` and :math:`w\left(C_{1}^{n+1} -C_{a} \right)` for the fully explicit and -fully implicit cases, respectively (however, see Tang and Riley (2013) +fully implicit cases, respectively (however, see +:ref:`Tang and Riley (2013)` for a more complete representation of this process). Here, *w* is the surface boundary layer conductance as calculated in the existing CLM surface latent heat calculations. If the top layer is not fully @@ -470,7 +507,7 @@ and if the top layer is saturated, this term is replaced with where :math:`{K}_{H}` is the Henry’s law equilibrium constant. When snow is present, a resistance is added to account for diffusion -through the snow based on the Millington-Quirk expression (equation ) +through the snow based on the Millington-Quirk expression :eq:`24.13` and CLM’s prediction of the liquid water, ice, and air fractions of each snow layer. When the soil is ponded, the diffusivity is assumed to be that of methane in pure water, and the resistance as the ratio of the @@ -478,15 +515,18 @@ ponding depth to diffusivity. The overall conductance is taken as the series combination of surface, snow, and ponding resistances. We assume a zero flux gradient at the bottom of the soil column. +.. _Crank-Nicholson Solution Methane: + Crank-Nicholson Solution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Equation is solved using a Crank-Nicholson solution (Press et al. 1992), +Equation is solved using a Crank-Nicholson solution +(:ref:`Press et al. 1992`), which combines fully explicit and implicit representations of the mass balance. The fully explicit decomposition of equation can be written as .. math:: - :label: ZEqnNum395184 + :label: 24.15 \frac{R_{j}^{n+1} C_{j}^{n+1} -R_{j}^{n} C_{j}^{n} }{\Delta t} =\frac{1}{\Delta x_{j} } \left[\frac{D_{p1}^{n} }{\Delta x_{p1}^{} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{n} }{\Delta x_{m1}^{} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+S_{j}^{n} , @@ -506,14 +546,14 @@ Using an average of the fully implicit and fully explicit relationships gives: .. math:: - :label: ZEqnNum463314 + :label: 24.16 \begin{array}{l} {-\frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1}^{} } C_{j-1}^{n+1} +\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(\frac{D_{p1}^{} }{\Delta x_{p1}^{} } +\frac{D_{m1}^{} }{\Delta x_{m1}^{} } \right)\right]C_{j}^{n+1} -\frac{1}{2\Delta x_{j} } \frac{D_{p1}^{} }{\Delta x_{p1}^{} } C_{j+1}^{n+1} =} \\ {\frac{R_{j}^{n} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1}^{} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1}^{} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right]} \end{array}, Equation is solved with a standard tridiagonal solver, i.e.: .. math:: - :label: 24.17) + :label: 24.17 aC_{j-1}^{n+1} +bC_{j}^{n+1} +cC_{j+1}^{n+1} =r, @@ -524,6 +564,8 @@ the diffusion solution and the time-varying aggregation over inundated and non-inundated areas strictly conserves methane molecules (except for production minus consumption) and carbon atoms. +.. _Interface between water table and unsaturated zone: + Interface between water table and unsaturated zone ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -538,7 +580,7 @@ soil element above the interface: .. math:: b=\left[\frac{R_{j}^{n+1} }{\Delta t} +\frac{1}{2\Delta x_{j} } \left(K_{H} \frac{D_{p1}^{} }{\Delta x_{p1} } +\frac{D_{m1}^{} }{\Delta x_{m1} } \right)\right] .. math:: - :label: 24.18) + :label: 24.18 r=\frac{R_{j}^{n} }{\Delta t} C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -K_{H} C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] @@ -549,18 +591,20 @@ and the soil element below the interface: .. math:: a=-K_{H} \frac{1}{2\Delta x_{j} } \frac{D_{m1}^{} }{\Delta x_{m1} } .. math:: - :label: 24.19) + :label: 24.19 r=\frac{R_{j}^{n} }{\Delta t} +C_{j}^{n} +\frac{1}{2\Delta x_{j} } \left[\frac{D_{p1}^{} }{\Delta x_{p1} } \left(C_{j+1}^{n} -C_{j}^{n} \right)-\frac{D_{m1}^{} }{\Delta x_{m1} } \left(C_{j}^{n} -K_{H} C_{j-1}^{n} \right)\right]+\frac{1}{2} \left[S_{j}^{n} +S_{j}^{n+1} \right] +.. _Inundated Fraction Prediction: + Inundated Fraction Prediction ---------------------------------- We developed a simplified dynamic representation of spatial inundation -based on recent work by Prigent et al. (2007), who described a +based on recent work by :ref:`Prigent et al. (2007)`, who described a multi-satellite approach to estimate the global monthly inundated fraction (:math:`{F}_{i}`) over an equal area grid -(0.25:math:`\circ`\ :math:`\times`\ 0.25\ :math:`\circ` at the equator) +(0.25 :math:`\circ` \ :math:`\times`\ 0.25\ :math:`\circ` at the equator) from 1993 - 2000. They suggested that the IGBP estimate for inundation could be used as a measure of sensitivity of their detection approach at low inundation. We therefore used the sum of their satellite-derived @@ -572,7 +616,7 @@ grid cell in a simple model based on simulated water table depth (:math:`{z}_{w}`) and surface runoff (:math:`{Q}_{r}` (mm s\ :sup:`-1`)): .. math:: - :label: 24.20) + :label: 24.20 f_{s} =P_{1} e^{{\raise0.7ex\hbox{$ -z_{w} $}\!\mathord{\left/ {\vphantom {-z_{w} p_{2} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ p_{2} $}} } +p_{3} Q_{r} . @@ -582,15 +626,18 @@ coarser simulations. We expect that ongoing work in the hydrology submodel of CLM will alleviate the need for this crude simplification of inundated fraction in future model versions. +.. _Seasonal Inundation: + Seasonal Inundation ------------------------ We have developed a simplified scaling factor to mimic the impact of seasonal inundation on CH\ :sub:`4` production (see appendix B in -Riley et al. (2011a) for a discussion of this simplified expression): +:ref:`Riley et al. (2011a)` for a discussion of this +simplified expression): .. math:: - :label: 24.21) + :label: 24.21 S=\frac{\beta \left(f-\bar{f}\right)+\bar{f}}{f} ,S\le 1. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 5c278d1e0f..dfe1f67abb 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1555,7 +1555,7 @@ Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity in soils and cultures to water stress. Applied and Environmental Microbiology 62:3203-3209. -.. _Segers, R., 1998. Methane production and methane consumption: a review +.. _Segers1998: Segers, R., 1998. Methane production and methane consumption: a review of processes underlying wetland methane fluxes. Biogeochemistry From 89a87adda6bdd1ac608ae1ad9b594ee9752d85f4 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 31 May 2017 14:01:49 -0600 Subject: [PATCH 034/255] update Dust chapter --- .../tech_note/Dust/CLM50_Tech_Note_Dust.rst | 106 ++++++++++-------- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 6 +- 2 files changed, 62 insertions(+), 50 deletions(-) diff --git a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst index 2b3bfa6dd7..c40ac583f7 100644 --- a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst +++ b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst @@ -6,45 +6,48 @@ Dust Model Atmospheric dust is mobilized from the land by wind in the CLM. The most important factors determining soil erodibility and dust emission include the wind friction speed, the vegetation cover, and the soil moisture. -The CLM dust mobilization scheme (Mahowald et al. ** 2006) accounts for -these factors based on the DEAD (Dust Entrainment and Deposition) model -of Zender et al. (2003). Please refer to the Zender et al. ** (2003) -article for additional information regarding the equations presented in -this section. +The CLM dust mobilization scheme (:ref:`Mahowald et al. 2006`) +accounts for these factors based on the DEAD (Dust Entrainment and Deposition) +model of :ref:`Zender et al. (2003)`. Please refer to the +:ref:`Zender et al. (2003)` article for additional +information regarding the equations presented in this section. -The total vertical mass flux of dust, :math:`F_{j}` (kg m\ :sup:`-2` s\ :sup:`-1`), from the ground into transport -bin :math:`j` is given by +The total vertical mass flux of dust, :math:`F_{j}` +(kg m\ :sup:`-2` s\ :sup:`-1`), from the ground into transport bin +:math:`j` is given by .. math:: - :label: ZEqnNum146272 + :label: 29.1 F_{j} =TSf_{m} \alpha Q_{s} \sum _{i=1}^{I}M_{i,j} where :math:`T` is a global factor that compensates for the DEAD model’s sensitivity to horizontal and temporal resolution and equals 5 x 10\ :sup:`-4` in the CLM instead of 7 x 10\ :sup:`-4` in -Zender et al. (2003). :math:`S` is the source erodibility factor set to -1 in the CLM and serves as a place holder at this time. +:ref:`Zender et al. (2003)`. :math:`S` is the source +erodibility factor set to 1 in the CLM and serves as a place holder +at this time. The grid cell fraction of exposed bare soil suitable for dust mobilization :math:`f_{m}` is given by .. math:: - :label: 29.2) + :label: 29.2 f_{m} =\left(1-f_{lake} -f_{wetl} \right)\left(1-f_{sno} \right)\left(1-f_{v} \right)\frac{w_{liq,1} }{w_{liq,1} +w_{ice,1} } -where ** :math:`f_{lake}` and ** :math:`f_{wetl}` and :math:`f_{sno}` -are the CLM grid cell fractions of lake and wetland (section 2.2.3) and -snow cover (section 7.2.1), all ranging from zero to one. Not mentioned -by Zender et al. (2003), :math:`w_{liq,\, 1}` and +where :math:`f_{lake}` and :math:`f_{wetl}` and :math:`f_{sno}` +are the CLM grid cell fractions of lake and wetland (section +:numref:`Surface Data`) and snow cover (section +:numref:`Snow Covered Area Fraction`), all ranging from zero to one. Not mentioned +by :ref:`Zender et al. (2003)`, :math:`w_{liq,\, 1}` and :math:`{}_{w_{ice,\, 1} }` are the CLM top soil layer liquid water and ice contents (mm) entered as a ratio expressing the decreasing ability of dust to mobilize from increasingly frozen soil. The grid cell fraction of vegetation cover,\ :math:`{}_{f_{v} }`, is defined as .. math:: - :label: ZEqnNum242183 + :label: 29.3 0\le f_{v} =\frac{L+S}{\left(L+S\right)_{t} } \le 1{\rm \; \; \; \; where\; }\left(L+S\right)_{t} =0.3{\rm \; m}^{2} {\rm m}^{-2} @@ -52,34 +55,38 @@ where equation applies only for dust mobilization and is not related to the plant functional type fractions prescribed from the CLM input data or simulated by the CLM dynamic vegetation model (Chapter 22). :math:`L` and :math:`S` are the CLM leaf and stem area index values -(m:sup:`2` m\ :sup:`-2`) averaged at the land unit level so +(m :sup:`2` m\ :sup:`-2`) averaged at the land unit level so as to include all the pfts and the bare ground present in a vegetated land unit. :math:`L` and :math:`S` may be prescribed from the CLM -input data (section 2.1.4) or simulated by the CLM biogeochemistry model -(Chapter 13). +input data (section :numref:`Phenology and vegetation burial by snow`) +or simulated by the CLM biogeochemistry model (Chapter +:numref:`rst_Vegetation Phenology and Turnover`). -The sandblasting mass efficiency :math:`\alpha` (m:sup:`-1`) is +The sandblasting mass efficiency :math:`\alpha` (m :sup:`-1`) is calculated as .. math:: - :label: 29.4) + :label: 29.4 \alpha =100e^{\left(13.4M_{clay} -6.0\right)\ln 10} {\rm \; \; }\left\{\begin{array}{l} {M_{clay} =\% clay\times 0.01{\rm \; \; \; 0}\le \% clay\le 20} \\ {M_{clay} =20\times 0.01{\rm \; \; \; \; \; \; \; \; 20<\% }clay\le 100} \end{array}\right. where :math:`M_{clay}` is the mass fraction of clay particles in the soil and %clay is determined from the surface dataset -(section 2.2.3). :math:`M_{clay} =0` corresponds to sand and +(section :numref:`Surface Data`). :math:`M_{clay} =0` corresponds to sand and :math:`M_{clay} =0.2` to sandy loam. :math:`Q_{s}` is the total horizontally saltating mass flux (kg -m\ :sup:`-1` s\ :sup:`-1`) of “large†particles (Table -24.1), also referred to as the vertically integrated streamwise mass -flux +m\ :sup:`-1` s\ :sup:`-1`) of “large†particles (:numref:`Table Dust Mass fraction`), +also referred to as the vertically integrated streamwise mass flux .. math:: - :label: ZEqnNum832592 + :label: 29.5 - Q_{s} =\left\{\begin{array}{l} {\frac{c_{s} \rho _{atm} u_{*s}^{3} }{g} \left(1-\frac{u_{*t} }{u_{*s} } \right)\left(1+\frac{u_{*t} }{u_{*s} } \right)^{2} {\rm \; }\qquad {\rm for\; }u_{*t} w_{t} } \end{array}\right. where .. math:: - :label: 29.8) + :label: 29.8 w_{t} =a\left(0.17M_{clay} +0.14M_{clay}^{2} \right){\rm \; \; \; \; \; \; 0}\le M_{clay} =\% clay\times 0.01\le 1 and .. math:: - :label: 29.9) + :label: 29.9 w=\frac{\theta _{1} \rho _{liq} }{\rho _{d,1} } where :math:`a=M_{clay}^{-1}` for tuning purposes, :math:`\theta _{1}` is the volumetric soil moisture in the top soil -layer (m:math:`{}^{3 }`\ m\ :sup:`-3`) (section 7.4), +layer (m :math:`{}^{3 }`\ m\ :sup:`-3`) (section :numref:`Soil Water`), :math:`\rho _{liq}` is the density of liquid water (kg -m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{d,\, 1}` is the bulk -density of soil in the top soil layer (kg m\ :sup:`-3`) defined as -in section 6.3 rather than as in Zender et al. (2003). +m\ :sup:`-3`) (:numref:`Table Physical constants`), and :math:`\rho _{d,\, 1}` +is the bulk density of soil in the top soil layer (kg m\ :sup:`-3`) +defined as in section :numref:`Soil and Snow Thermal Properties` +rather than as in :ref:`Zender et al. (2003)`. :math:`Re_{*t}^{f}` from equation is the threshold friction Reynolds factor .. math:: - :label: 29.10) + :label: 29.10 Re_{*t}^{f} =\left\{\begin{array}{l} {\frac{0.1291^{2} }{-1+1.928Re_{*t} } {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; 0.03}\le Re_{*t} \le 10} \\ {0.12^{2} \left(1-0.0858e^{-0.0617(Re_{*t} -10)} \right)^{2} {\rm \; for\; }Re_{*t} >10} \end{array}\right. @@ -135,28 +143,32 @@ and :math:`Re_{*t}` is the threshold friction Reynolds number approximation for optimally sized particles .. math:: - :label: 29.11) + :label: 29.11 Re_{*t} =0.38+1331\left(100D_{osp} \right)^{1.56} -In equation , :math:`u_{*s}` ** is defined as the wind friction speed -(m s\ :sup:`-1`) accounting for the Owen effect (Owen 1964) +In :eq:`29.5` , :math:`u_{*s}` is defined as the wind friction speed +(m s\ :sup:`-1`) accounting for the Owen effect (:ref:`Owen 1964`) .. math:: - :label: 29.12) + :label: 29.12 - u_{\*s} =\left\{\begin{array}{l} {u_{\*} {\rm \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; for\; }U_{10} ` but here for 10 m above the ground, and :math:`U_{10,\, t}` is the threshold wind speed at 10 m (m s\ :sup:`-1`) .. math:: - :label: 29.13) + :label: 29.13 U_{10,t} =u_{*t} \frac{U_{10} }{u_{*} } @@ -165,7 +177,7 @@ In equation we sum :math:`M_{i,\, j}` over :math:`I=3` source modes mode :math:`i` carried in each of *:math:`J=4`* transport bins :math:`j` .. math:: - :label: 29.14) + :label: 29.14 M_{i,j} =\frac{m_{i} }{2} \left[{\rm erf}\left(\frac{\ln {\textstyle\frac{D_{j,\max } }{\tilde{D}_{v,i} }} }{\sqrt{2} \ln \sigma _{g,i} } \right)-{\rm erf}\left(\frac{\ln {\textstyle\frac{D_{j,\min } }{\tilde{D}_{v,i} }} }{\sqrt{2} \ln \sigma _{g,i} } \right)\right] @@ -174,7 +186,7 @@ where :math:`m_{i}` , :math:`\tilde{D}_{v,\, i}` , and and geometric standard deviation assigned to each particle source mode :math:`i` (:numref:`Table Dust Mass fraction`), while :math:`D_{j,\, \min }` and :math:`D_{j,\, \max }` are the minimum and maximum diameters (m) in -each transport bin :math:`j` ** (:numref:`Table Dust Minimum and maximum particle diameters`). +each transport bin :math:`j` (:numref:`Table Dust Minimum and maximum particle diameters`). .. _Table Dust Mass fraction: diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 136272973d..4a6192aacb 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -18,7 +18,7 @@ gridcell according to density class. The urban landunit is based on the “urban canyon†concept of :ref:`Oke (1987) ` in which the canyon geometry is described by building height (:math:`H`) and street width (:math:`W`) -(:numref:`Figure schematic representation of urban`). The canyon system +(:numref:`Figure schematic representation of the urban landunit`). The canyon system consists of roofs, walls, and canyon floor. Walls are further divided into shaded and sunlit components. The canyon floor is divided into pervious (e.g., to represent residential @@ -28,7 +28,7 @@ pervious fraction; instead evaporation is parameterized by a simplified bulk scheme. Each of the five urban surfaces is treated as a column within the -landunit (:numref:`Figure schematic representation of urban`). +landunit (:numref:`Figure schematic representation of the urban landunit`). Radiation parameterizations account for trapping of solar and longwave radiation inside the canyon. Momentum fluxes are determined for the urban landunit using a roughness length and @@ -106,7 +106,7 @@ resolution. .. Figure 12.1. Schematic representation of the urban land unit -.. _Figure schematic representation of the urban land unit: +.. _Figure schematic representation of the urban landunit: .. figure:: image1.png From bcf269c2f8755f38a334dd00e4dad2c54b8846d7 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 1 Jun 2017 09:27:10 -0600 Subject: [PATCH 035/255] Update Chapter 6 --- .../CLM50_Tech_Note_Introduction.rst | 4 +- .../References/CLM50_Tech_Note_References.rst | 2 + ...CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 371 +++++++++++------- 3 files changed, 230 insertions(+), 147 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 9e6c3f2fd0..29892825d8 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -1,4 +1,4 @@ -**NCAR/TN-503+STR** +g**NCAR/TN-503+STR** **NCAR Technical Note** @@ -138,7 +138,7 @@ Jinyun Tang, Zong-Liang Yang** - :numref:`three layer snow pack` Example of three layer snow pack (snl=-3). -- :numref:`Figure Schematic representation of the urban land unit` Schematic representation of the urban land unit. +- :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. - :numref:`Figure Schematic of urban and atmospheric model coupling` Schematic of urban and atmospheric model coupling. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index dfe1f67abb..dfb4b81d9c 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1225,6 +1225,8 @@ Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. +.. _NiuYang2006: + Niu, G.-Y., and Yang, Z.-L. 2006. Effects of frozen soil on snowmelt runoff and soil water storage at a continental scale. J. Hydrometeor. 7:937-952. diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index 0a7b941359..780ccb4752 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -6,7 +6,7 @@ Soil and Snow Temperatures The first law of heat conduction is .. math:: - :label: 6.1) + :label: 6.1 F=-\lambda \nabla T @@ -17,7 +17,7 @@ K\ :sup:`-1`), and :math:`\nabla T` is the spatial gradient of temperature (K m\ :sup:`-1`). In one-dimensional form .. math:: - :label: ZEqnNum105915 + :label: 6.2 F_{z} =-\lambda \frac{\partial T}{\partial z} @@ -27,7 +27,7 @@ non-steady or transient conditions, the principle of energy conservation in the form of the continuity equation is invoked as .. math:: - :label: ZEqnNum376834 + :label: 6.3 c\frac{\partial T}{\partial t} =-\frac{\partial F_{z} }{\partial z} @@ -37,7 +37,7 @@ Combining equations and yields the second law of heat conduction in one-dimensional form .. math:: - :label: 6.4) + :label: 6.4 c\frac{\partial T}{\partial t} =\frac{\partial }{\partial z} \left[\lambda \frac{\partial T}{\partial z} \right]. @@ -55,8 +55,9 @@ phase change and then readjusted for phase change (section :numref:`Phase Change Numerical Solution ---------------------- -The soil column is discretized into 25 layers (section :numref:`Vertical Discretization`) -where :math:`N_{levgrnd} = 25` is the number of soil layers (:numref:`Table Soil layer structure`). +The soil column is discretized into 25 layers (section +:numref:`Vertical Discretization`) where :math:`N_{levgrnd} = 25` is the +number of soil layers (:numref:`Table Soil layer structure`). The overlying snow pack is modeled with up to five layers depending on the total snow depth. The layers from top to bottom are indexed in the @@ -68,35 +69,88 @@ is the negative of the number of snow layers. The number of snow layers and the thickness of each layer is a function of snow depth :math:`z_{sno}` (m) as follows. -.. math:: \left\{\begin{array}{l} {snl=-1} \\ {\Delta z_{0} =z_{sno} \qquad {\rm for\; 0.01}\le {\rm z}_{{\rm sno}} \le 0.03} \end{array}\right\}, +.. math:: -.. math:: \left\{\begin{array}{l} {snl=-2} \\ {\Delta z_{-1} ={z_{sno} \mathord{\left/ {\vphantom {z_{sno} 2}} \right. \kern-\nulldelimiterspace} 2} \qquad {\rm for\; 0.03}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.04} \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, - -.. math:: \left\{\begin{array}{l} {snl=-2} \\ {\Delta z_{-1} =0.02\qquad {\rm for\; 0.04}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.07} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-1} } \end{array}\right\}, - -.. math:: \left\{\begin{array}{l} {snl=-3} \\ {\Delta z_{-2} =0.02} \\ {\Delta z_{-1} ={\left(z_{sno} -0.02\right)\mathord{\left/ {\vphantom {\left(z_{sno} -0.02\right) 2}} \right. \kern-\nulldelimiterspace} 2} \qquad {\rm for\; 0.07}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.12} \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, - -.. math:: \left\{\begin{array}{l} {snl=-3} \\ {\Delta z_{-2} =0.02} \\ {\Delta z_{-1} =0.05\qquad {\rm for\; 0.12}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.18} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-2} -\Delta z_{-1} } \end{array}\right\}, - -.. math:: \left\{\begin{array}{l} {snl=-4} \\ {\Delta z_{-3} =0.02} \\ {\Delta z_{-2} =0.05\qquad {\rm for\; 0.18}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.29} \\ {\Delta z_{-1} ={\left(z_{sno} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, - -.. math:: \left\{\begin{array}{l} {snl=-4} \\ {\Delta z_{-3} =0.02} \\ {\Delta z_{-2} =0.05\qquad {\rm for\; 0.29}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.41} \\ {\Delta z_{-1} =0.11} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} } \end{array}\right\}, + \begin{array}{lr} -.. math:: \left\{\begin{array}{l} {snl=-5} \\ {\Delta z_{-4} =0.02} \\ {\Delta z_{-3} =0.05\qquad {\rm for\; 0.41}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.64} \\ {\Delta z_{-2} =0.11} \\ {\Delta z_{-1} ={\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \\ {\Delta z_{0} =\Delta z_{-1} } \end{array}\right\}, + \left\{ \begin{array}{l} + snl=-1 \\ + \Delta z_{0} = z_{sno} + \end{array} \right\} & \qquad {\rm for\; 0.01}\le {\rm z}_{{\rm sno}} \le 0.03 \\ + + \left\{ \begin{array}{l} + snl=-2 \\ + \Delta z_{-1} ={z_{sno} \mathord{\left/ {\vphantom {z_{sno} 2}} \right. \kern-\nulldelimiterspace} 2} \\ + \Delta z_{0} = \Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.03}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.04 \\ + + \left\{ \begin{array}{l} + snl=-2 \\ + \Delta z_{-1} = 0.02 \\ + \Delta z_{0} = z_{sno} -\Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.04}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.07 \\ + \left\{ \begin{array}{l} + snl=-3 \\ + \Delta z_{-2} = 0.02 \\ + \Delta z_{-1} = {\left(z_{sno} -0.02\right)\mathord{\left/ {\vphantom {\left(z_{sno} -0.02\right) 2}} \right. \kern-\nulldelimiterspace} 2} \\ + \Delta z_{0} = \Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.07}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.12 \\ + + \left\{ \begin{array}{l} + snl=-3 \\ + \Delta z_{-2} = 0.02 \\ + \Delta z_{-1} = 0.05 \\ + \Delta z_{0} = z_{sno} -\Delta z_{-2} -\Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.12}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.18 \\ + + \left\{ \begin{array}{l} + snl=-4 \\ + \Delta z_{-3} = 0.02 \\ + \Delta z_{-2} = 0.05 \\ + \Delta z_{-1} = {\left(z_{sno} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} \\ + \Delta z_{0} =\Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.18}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.29 \\ + + \left\{ \begin{array}{l} + snl=-4 \\ + \Delta z_{-3} = 0.02 \\ + \Delta z_{-2} = 0.05 \\ + \Delta z_{-1} = 0.11 \\ + \Delta z_{0} = z_{sno} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.29}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.41 \\ + + \left\{ \begin{array}{l} + snl=-5 \\ + \Delta z_{-4} = 0.02 \\ + \Delta z_{-3} = 0.05 \\ + \Delta z_{-2} = 0.11 \\ + \Delta z_{-1} = {\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} \\ + \Delta z_{0} = \Delta z_{-1} + + \end{array} \right\} & \qquad {\rm for\; 0.41}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.64 \\ + + \left\{ \begin{array}{l} + snl=-5 \\ + \Delta z_{-4} = 0.02 \\ + \Delta z_{-3} = 0.05 \\ + \Delta z_{-2} = 0.11 \\ + \Delta z_{-1} = 0.23 \\ + \Delta z_{0} = z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} + \end{array} \right\} & \qquad {\rm for\; 0.64}\, {\rm <}\, {\rm z}_{{\rm sno}} -.. math:: \left\{\begin{array}{l} {snl=-5} \\ {\Delta z_{-4} =0.02} \\ {\Delta z_{-3} =0.05\qquad {\rm for\; 0.64}\, {\rm <}\, {\rm z}_{{\rm sno}} } \\ {\Delta z_{-2} =0.11} \\ {\Delta z_{-1} =0.23} \\ {\Delta z_{0} =z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} } \end{array}\right\}. + \end{array} The node depths, which are located at the midpoint of the snow layers, and the layer interfaces are both referenced from the soil surface and are defined as negative values .. math:: - :label: 6.8) + :label: 6.8 z_{i} =z_{h,\, i} -0.5\Delta z_{i} \qquad i=snl+1,\ldots ,0 .. math:: - :label: 6.9) + :label: 6.9 z_{h,\, i} =z_{h,\, i+1} -\Delta z_{i+1} \qquad i=snl,\ldots ,-1. @@ -118,7 +172,7 @@ The heat flux :math:`F_{i}` (W m\ :sup:`-2`) from layer :math:`i` to layer :math:`i+1` is .. math:: - :label: ZEqnNum443713 + :label: 6.10 F_{i} =-\lambda \left[z_{h,\, i} \right]\left(\frac{T_{i} -T_{i+1} }{z_{i+1} -z_{i} } \right) @@ -126,7 +180,7 @@ where the thermal conductivity at the interface :math:`\lambda \left[z_{h,\, i} \right]` is .. math:: - :label: ZEqnNum604125 + :label: 6.11 \lambda \left[z_{h,\, i} \right]=\left\{\begin{array}{l} {\frac{\lambda _{i} \lambda _{i+1} \left(z_{i+1} -z_{i} \right)}{\lambda _{i} \left(z_{i+1} -z_{h,\, i} \right)+\lambda _{i+1} \left(z_{h,\, i} -z_{i} \right)} \qquad i=snl+1,\ldots ,N_{levgrnd} -1} \\ {0\qquad i=N_{levgrnd} } \end{array}\right\}. @@ -138,7 +192,7 @@ equals the heat flux from the interface to :math:`i+1` (depth :math:`z_{i+1}` ), i.e., .. math:: - :label: ZEqnNum726244 + :label: 6.12 -\lambda _{i} \frac{T_{i} -T_{m} }{z_{h,\, i} -z_{i} } =-\lambda _{i+1} \frac{T_{m} -T_{i+1} }{z_{i+1} -z_{h,\, i} } @@ -164,7 +218,7 @@ interface of two layers The energy balance for the :math:`i^{th}` layer is .. math:: - :label: 6.13) + :label: 6.13 \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=-F_{i-1} +F_{i} @@ -176,7 +230,7 @@ method, which combines the explicit method with fluxes evaluated at fluxes evaluated at :math:`n+1` (:math:`F_{i-1}^{n+1} ,F_{i}^{n+1}` ) .. math:: - :label: 6.14) + :label: 6.14 \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=\alpha \left(-F_{i-1}^{n} +F_{i}^{n} \right)+\left(1-\alpha \right)\left(-F_{i-1}^{n+1} +F_{i}^{n+1} \right) @@ -184,7 +238,7 @@ where :math:`\alpha =0.5`, resulting in a tridiagonal system of equations .. math:: - :label: 6.15) + :label: 6.15 r_{i} =a_{i} T_{i-1}^{n+1} +b_{i} T_{i}^{n+1} +c_{i} T_{i+1}^{n+1} @@ -201,57 +255,57 @@ surface water layer, the heat flux from the overlying atmosphere is .. math:: - :label: 6.16) + :label: 6.16 h^{n+1} =-\alpha F_{i-1}^{n} -\left(1-\alpha \right)F_{i-1}^{n+1} . The energy balance for these layers is then .. math:: - :label: 6.17) + :label: 6.17 \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=h^{n+1} +\alpha F_{i}^{n} +\left(1-\alpha \right)F_{i}^{n+1} . The heat flux :math:`h` at :math:`n+1` may be approximated as follows .. math:: - :label: 6.18) + :label: 6.18 h^{n+1} =h^{n} +\frac{\partial h}{\partial T_{i} } \left(T_{i}^{n+1} -T_{i}^{n} \right). The resulting equations are then .. math:: - :label: ZEqnNum219926 + :label: 6.19 \begin{array}{rcl} {\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)} & {=} & {h^{n} +\frac{\partial h}{\partial T_{i} } \left(T_{i}^{n+1} -T_{i} \right)} \\ {} & {} & {-\alpha \frac{\lambda \left[z_{h,\, i} \right]\left(T_{i}^{n} -T_{i+1}^{n} \right)}{z_{i+1} -z_{i} } -\left(1-\alpha \right)\frac{\lambda \left[z_{h,\, i} \right]\left(T_{i}^{n+1} -T_{i+1}^{n+1} \right)}{z_{i+1} -z_{i} } } \end{array} For the top snow layer, :math:`i=snl+1`, the coefficients are .. math:: - :label: 6.20) + :label: 6.20 a_{i} =0 .. math:: - :label: 6.21) + :label: 6.21 b_{i} =1+\frac{\Delta t}{c_{i} \Delta z_{i} } \left[\left(1-\alpha \right)\frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } -\frac{\partial h}{\partial T_{i} } \right] .. math:: - :label: 6.22) + :label: 6.22 c_{i} =-\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } .. math:: - :label: 6.23) + :label: 6.23 r_{i} =T_{i}^{n} +\frac{\Delta t}{c_{i} \Delta z_{i} } \left[h_{sno} ^{n} -\frac{\partial h}{\partial T_{i} } T_{i}^{n} +\alpha F_{i} \right] where .. math:: - :label: ZEqnNum455578 + :label: 6.24 F_{i} =-\lambda \left[z_{h,\, i} \right]\left(\frac{T_{i}^{n} -T_{i+1}^{n} }{z_{i+1} -z_{i} } \right). @@ -259,67 +313,72 @@ The heat flux into the snow surface from the overlying atmosphere :math:`h` is .. math:: - :label: 6.25) + :label: 6.25 h=\overrightarrow{S}_{sno} -\overrightarrow{L}_{sno} -H_{sno} -\lambda E_{sno} where :math:`\overrightarrow{S}_{sno}` is the solar radiation absorbed -by the top snow layer (section 3.2.1), :math:`\overrightarrow{L}_{sno}` +by the top snow layer (section :numref:`Snow Albedo`), :math:`\overrightarrow{L}_{sno}` is the longwave radiation absorbed by the snow (positive toward the -atmosphere) (section 4.2), :math:`H_{sno}` is the sensible heat flux -from the snow (Chapter 5), and :math:`\lambda E_{sno}` is the latent -heat flux from the snow (Chapter 5). The partial derivative of the heat -flux :math:`h` with respect to temperature is +atmosphere) (section :numref:`Longwave Fluxes`), :math:`H_{sno}` is the +sensible heat flux from the snow (Chapter +:numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), and +:math:`\lambda E_{sno}` is the latent heat flux from the snow (Chapter +:numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). The partial +derivative of the heat flux :math:`h` with respect to temperature is .. math:: - :label: 6.26) + :label: 6.26 \frac{\partial h}{\partial T_{} } =-\frac{\partial \overrightarrow{L}_{} }{\partial T_{} } -\frac{\partial H_{} }{\partial T_{} } -\frac{\partial \lambda E_{} }{\partial T_{} } where the partial derivative of the net longwave radiation is .. math:: - :label: 6.27) + :label: 6.27 \frac{\partial \overrightarrow{L}_{} }{\partial T_{} } =4\varepsilon _{g} \sigma \left(T_{}^{n} \right)^{3} and the partial derivatives of the sensible and latent heat fluxes are given by equations and for non-vegetated surfaces, and by equations and for vegetated surfaces. :math:`\sigma` is the Stefan-Boltzmann constant -(W m\ :sup:`-2` K\ :sup:`-4`) (Table 2.6) and :math:`\varepsilon _{g}` is the ground emissivity (section 4.2). For -purposes of computing :math:`h` and :math:`\frac{\partial h}{\partial T_{g} }` , the term :math:`\lambda` +(W m\ :sup:`-2` K\ :sup:`-4`) (:numref:`Table Physical Constants`) and +:math:`\varepsilon _{g}` is the ground emissivity (section +:numref:`Longwave Fluxes`). For purposes of computing :math:`h` and +:math:`\frac{\partial h}{\partial T_{g} }` , the term :math:`\lambda` is arbitrarily assumed to be .. math:: - :label: 6.28) + :label: 6.28 \lambda =\left\{\begin{array}{l} {\lambda _{sub} \qquad {\rm if\; }w_{liq,\, snl+1} =0{\rm \; and\; }w_{ice,\, snl+1} >0} \\ {\lambda _{vap} \qquad {\rm otherwise}} \end{array}\right\} where :math:`\lambda _{sub}` and :math:`\lambda _{vap}` are the latent heat of sublimation and vaporization, respectively (J -kg\ :sup:`-1`) (Table 2.6), and :math:`w_{liq,\, snl+1}` and -:math:`w_{ice,\, snl+1}` are the liquid water and ice contents of the -top snow/soil layer, respectively (kg m\ :sup:`-2`) (Chapter 7). +kg\ :sup:`-1`) (:numref:`Table Physical Constants`), and :math:`w_{liq,\, snl+1}` +and :math:`w_{ice,\, snl+1}` are the liquid water and ice contents of the +top snow/soil layer, respectively (kg m\ :sup:`-2`) +(Chapter :numref:`rst_Hydrology`). For the top soil layer, :math:`i=1`, the coefficients are .. math:: - :label: 6.29) + :label: 6.29 a_{i} =-f_{sno} \left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } .. math:: - :label: 6.30) + :label: 6.30 b_{i} =1+\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \left[f_{sno} \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } +\frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \right]-\left(1-f_{sno} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} .. math:: - :label: 6.31) + :label: 6.31 c_{i} =-\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } .. math:: - :label: 6.32) + :label: 6.32 r_{i} =T_{i}^{n} +\frac{\Delta t}{c_{i} \Delta z_{i} } \left[\left(1-f_{sno} \right)\left(h_{soil} ^{n} -\frac{\partial h}{\partial T_{} } T_{i}^{n} \right)+\alpha \left(F_{i} -f_{sno} F_{i-1} \right)\right] @@ -327,7 +386,7 @@ The heat flux into the soil surface from the overlying atmosphere :math:`h` is .. math:: - :label: 6.33) + :label: 6.33 h=\overrightarrow{S}_{soil} -\overrightarrow{L}_{soil} -H_{soil} -\lambda E_{soil} @@ -345,13 +404,13 @@ for diurnal heating. The top layer thickness for :math:`i=snl+1` is given by .. math:: - :label: 6.34) + :label: 6.34 \Delta z_{i*} =0.5\left[z_{i} -z_{h,\, i-1} +c_{a} \left(z_{i+1} -z_{h,\, i-1} \right)\right] where :math:`c_{a}` is a tunable parameter, varying from 0 to 1, and is taken as 0.34 by comparing the numerical solution with the analytic -solution (Z.-L. Yang 1998, unpublished manuscript). +solution (:ref:`Z.-L. Yang 1998, unpublished manuscript`). :math:`\Delta z_{i*}` is used in place of :math:`\Delta z_{i}` for :math:`i=snl+1` in equations -. The top snow/soil layer temperature computed in this way is the ground surface temperature @@ -361,34 +420,34 @@ The boundary condition at the bottom of the snow/soil column is zero heat flux, :math:`F_{i} =0`, resulting in, for :math:`i=N_{levgrnd}` , .. math:: - :label: 6.35) + :label: 6.35 \frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=\alpha \frac{\lambda \left[z_{h,\, i-1} \right]\left(T_{i-1}^{n} -T_{i}^{n} \right)}{z_{i} -z_{i-1} } +\left(1-\alpha \right)\frac{\lambda \left[z_{h,\, i-1} \right]\left(T_{i-1}^{n+1} -T_{i}^{n+1} \right)}{z_{i} -z_{i-1} } .. math:: - :label: 6.36) + :label: 6.36 a_{i} =-\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } .. math:: - :label: 6.37) + :label: 6.37 b_{i} =1+\left(1-\alpha \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } .. math:: - :label: 6.38) + :label: 6.38 c_{i} =0 .. math:: - :label: 6.39) + :label: 6.39 r_{i} =T_{i}^{n} -\alpha \frac{\Delta t}{c_{i} \Delta z_{i} } F_{i-1} where .. math:: - :label: ZEqnNum768674 + :label: 6.40 F_{i-1} =-\frac{\lambda \left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \left(T_{i-1}^{n} -T_{i}^{n} \right). @@ -396,48 +455,48 @@ For the interior snow/soil layers, :math:`snl+1T_{f} {\rm \; and\; }w_{ice,\, i} >0 & \qquad i=snl+1,\ldots ,N_{levgrnd} \qquad {\rm melting} \end{array} + +.. math:: + :label: 6.53b - \begin{array}{l} {T_{i}^{n+1} >T_{f} {\rm \; and\; }w_{ice,\, i} >0\qquad i=snl+1,\ldots ,N_{levgrnd} \qquad {\rm melting}} \\ {T_{i}^{n+1} 0\qquad i=snl+1,\ldots ,0\qquad {\rm freezing}} \\ {T_{i}^{n+1} w_{liq,\, \max ,\, i} \qquad i=1,\ldots ,N_{levgrnd} \qquad {\rm freezing}} \end{array} + \begin{array}{lr} + \begin{array}{lr} + T_{i}^{n+1} 0 & \qquad i=snl+1,\ldots ,0 \\ + T_{i}^{n+1} w_{liq,\, \max ,\, i} & \quad i=1,\ldots ,N_{levgrnd} + \end{array} & \quad {\rm freezing} + \end{array} where :math:`T_{i}^{n+1}` is the soil layer temperature after solution of the tridiagonal equation set, :math:`w_{ice,\, i}` and :math:`w_{liq,\, i}` are the mass of ice and liquid water (kg -m\ :sup:`-2`) in each snow/soil layer, respectively, and -:math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). For -the freezing process in soil layers, the concept of supercooled soil -water from Niu and Yang (2006) is adopted. The supercooled soil water is -the liquid water that coexists with ice over a wide range of +m\ :sup:`-2`) in each snow/soil layer, respectively, and :math:`T_{f}` +is the freezing temperature of water (K) (:numref:`Table Physical Constants`). +For the freezing process in soil layers, the concept of supercooled soil +water from :ref:`Niu and Yang (2006)` is adopted. The supercooled +soil water is the liquid water that coexists with ice over a wide range of temperatures below freezing and is implemented through a freezing point depression equation .. math:: - :label: ZEqnNum547401 + :label: 6.54 w_{liq,\, \max ,\, i} =\Delta z_{i} \theta _{sat,\, i} \left[\frac{10^{3} L_{f} \left(T_{f} -T_{i} \right)}{gT_{i} \psi _{sat,\, i} } \right]^{{-1\mathord{\left/ {\vphantom {-1 B_{i} }} \right. \kern-\nulldelimiterspace} B_{i} } } \qquad T_{i} ` exponent +(section :numref:`Soil Water`). For the special case when snow is present (snow mass :math:`W_{sno} >0`) but there are no explicit snow layers (:math:`snl=0`) (i.e., there is @@ -521,38 +592,46 @@ The excess or deficit of energy :math:`H_{i}` (W m\ :sup:`-2`) is determined as follows .. math:: - :label: 6.55) + :label: 6.55 - H_{i} =\left\{\begin{array}{l} {\frac{\partial h}{\partial T} \left(T_{f} -T_{i}^{n} \right)-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\qquad \quad \quad \quad i=snl+1} \\ {\left(1-f_{sno} -f_{h2osfc} \right)\frac{\partial h}{\partial T} \left(T_{f} -T_{i}^{n} \right)-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\quad {\kern 1pt} {\kern 1pt} {\kern 1pt} {\kern 1pt} i=1} \\ {-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\qquad \quad \quad \quad i\ne \left\{1,snl+1\right\}} \end{array}\right\}. + H_{i} =\left\{\begin{array}{lr} + \frac{\partial h}{\partial T} \left(T_{f} -T_{i}^{n} \right)-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right) & \quad \quad i=snl+1 \\ + \left(1-f_{sno} -f_{h2osfc} \right)\frac{\partial h}{\partial T} \left(T_{f} -T_{i}^{n} \right)-\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right)\quad {\kern 1pt} {\kern 1pt} {\kern 1pt} {\kern 1pt} & i=1 \\ + -\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{f} -T_{i}^{n} \right) & \quad \quad i\ne \left\{1,snl+1\right\} + \end{array}\right\}. -If the melting criteria is met (equation ) and +If the melting criteria is met :eq:`6.53a` and :math:`H_{m} =\frac{H_{i} \Delta t}{L_{f} } >0`, then the ice mass is readjusted as .. math:: - :label: ZEqnNum547839 + :label: 6.56 w_{ice,\, i}^{n+1} =w_{ice,\, i}^{n} -H_{m} \ge 0\qquad i=snl+1,\ldots ,N_{levgrnd} . -If the freezing criteria is met (equation ) and :math:`H_{m} <0`, then +If the freezing criteria is met :eq:`6.53b` and :math:`H_{m} <0`, then the ice mass is readjusted for :math:`i=snl+1,\ldots ,0` as .. math:: - :label: 6.57) + :label: 6.57 w_{ice,\, i}^{n+1} =\min \left(w_{liq,\, i}^{n} +w_{ice,\, i}^{n} ,w_{ice,\, i}^{n} -H_{m} \right) and for :math:`i=1,\ldots ,N_{levgrnd}` as .. math:: - :label: 6.58) + :label: 6.58 - w_{ice,\, i}^{n+1} =\left\{\begin{array}{l} {\min \left(w_{liq,\, i}^{n} +w_{ice,\, i}^{n} -w_{liq,\, \max ,\, i}^{n} ,\, w_{ice,\, i}^{n} -H_{m} \right)\qquad w_{liq,\, i}^{n} +w_{ice,\, i}^{n} \ge w_{liq,\, \max ,\, i}^{n} {\rm \; }} \\ {{\rm 0}\qquad w_{liq,\, i}^{n} +w_{ice,\, i}^{n} 0`) as .. math:: - :label: ZEqnNum190862 + :label: 6.61 - T_{i}^{n+1} =\left\{\begin{array}{l} {T_{f} +{\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \mathord{\left/ {\vphantom {\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \left(1-\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)}} \right. \kern-\nulldelimiterspace} \left(1-\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)} \qquad \quad \quad \quad \quad \quad \, i=snl+1} \\ {T_{f} +{\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \mathord{\left/ {\vphantom {\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \left(1-\left(1-f_{sno} -f_{h2osfc} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)}} \right. \kern-\nulldelimiterspace} \left(1-\left(1-f_{sno} -f_{h2osfc} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)} \qquad i=1} \\ {T_{f} +\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \qquad \quad \quad \quad \quad \quad \, i\ne \left\{1,snl+1\right\}} \end{array}\right\}. + T_{i}^{n+1} = + \left\{\begin{array}{lr} + T_{f} +{\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \mathord{\left/ {\vphantom {\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \left(1-\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)}} \right. \kern-\nulldelimiterspace} \left(1-\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)} & \quad \quad \quad \quad \, i=snl+1 \\ + T_{f} +{\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \mathord{\left/ {\vphantom {\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} \left(1-\left(1-f_{sno} -f_{h2osfc} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)}} \right. \kern-\nulldelimiterspace} \left(1-\left(1-f_{sno} -f_{h2osfc} \right)\frac{\Delta t}{c_{i} \Delta z_{i} } \frac{\partial h}{\partial T} \right)} & \qquad i=1 \\ + T_{f} +\frac{\Delta t}{c_{i} \Delta z_{i} } H_{i*} & \quad \quad \quad \quad \, i\ne \left\{1,snl+1\right\} + \end{array}\right\}. For the special case when snow is present (:math:`W_{sno} >0`), there are no explicit snow layers (:math:`snl=0`), and @@ -578,14 +662,14 @@ are no explicit snow layers (:math:`snl=0`), and :math:`W_{sno}` (kg m\ :sup:`-2`) is reduced according to .. math:: - :label: 6.62) + :label: 6.62 W_{sno}^{n+1} =W_{sno}^{n} -\frac{H_{1} \Delta t}{L_{f} } \ge 0. The snow depth is reduced proportionally .. math:: - :label: 6.63) + :label: 6.63 z_{sno}^{n+1} =\frac{W_{sno}^{n+1} }{W_{sno}^{n} } z_{sno}^{n} . @@ -593,7 +677,7 @@ Again, because part of the energy may not be consumed in melting, the energy for the surface soil layer :math:`i=1` is recalculated as .. math:: - :label: 6.64) + :label: 6.64 H_{1*} =H_{1} -\frac{L_{f} \left(W_{sno}^{n} -W_{sno}^{n+1} \right)}{\Delta t} . @@ -601,23 +685,23 @@ If there is excess energy (:math:`H_{1*} >0`), this energy becomes available to the top soil layer as .. math:: - :label: ZEqnNum985120 + :label: 6.65 H_{1} =H_{1*} . The ice mass, liquid water content, and temperature of the top soil -layer are then determined from equations , , and using the recalculated -energy from equation . Snow melt :math:`M_{1S}` (kg m\ :sup:`-2` -s\ :sup:`-1`) and phase change energy :math:`E_{p,\, 1S}` (W -m\ :sup:`-2`) for this special case are +layer are then determined from :eq:`6.56`, :eq:`6.59`, and :eq:`6.61` +using the recalculated energy from :eq:`6.65`. Snow melt :math:`M_{1S}` +(kg m\ :sup:`-2` s\ :sup:`-1`) and phase change energy :math:`E_{p,\, 1S}` +(W m\ :sup:`-2`) for this special case are .. math:: - :label: 6.66) + :label: 6.66 M_{1S} =\frac{W_{sno}^{n} -W_{sno}^{n+1} }{\Delta t} \ge 0 .. math:: - :label: 6.67) + :label: 6.67 E_{p,\, 1S} =L_{f} M_{1S} . @@ -625,14 +709,14 @@ The total energy of phase change :math:`E_{p}` (W m\ :sup:`-2`) for the snow/soil column is .. math:: - :label: 6.68) + :label: 6.68 E_{p} =E_{p,\, 1S} +\sum _{i=snl+1}^{N_{levgrnd} }E_{p,i} where .. math:: - :label: 6.69) + :label: 6.69 E_{p,\, i} =L_{f} \frac{\left(w_{ice,\, i}^{n} -w_{ice,\, i}^{n+1} \right)}{\Delta t} . @@ -640,25 +724,26 @@ The total snow melt :math:`M` (kg m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 6.70) + :label: 6.70 M=M_{1S} +\sum _{i=snl+1}^{i=0}M_{i} where .. math:: - :label: 6.71) + :label: 6.71 M_{i} =\frac{\left(w_{ice,\, i}^{n} -w_{ice,\, i}^{n+1} \right)}{\Delta t} \ge 0. The solution for snow/soil temperatures conserves energy as .. math:: - :label: 6.72) + :label: 6.72 G-E_{p} -\sum _{i=snl+1}^{i=N_{levgrnd} }\frac{c_{i} \Delta z_{i} }{\Delta t} \left(T_{i}^{n+1} -T_{i}^{n} \right)=0 -where :math:`G` is the ground heat flux (section 5.4). +where :math:`G` is the ground heat flux (section +:numref:`Update of Ground Sensible and Latent Heat Fluxes`). .. _Surface Water: @@ -670,7 +755,7 @@ temperature, :math:`T_{h2osfc}` , becomes less than :math:`T_{f}` . The energy available for freezing is .. math:: - :label: 6.73) + :label: 6.73 H_{h2osfc} =\frac{\partial h}{\partial T} \left(T_{f} -T_{h2osfc}^{n} \right)-\frac{c_{h2osfc} \Delta z_{h2osfc} }{\Delta t} \left(T_{f} -T_{h2osfc}^{n} \right) @@ -680,19 +765,19 @@ where :math:`c_{h2osfc}` is the volumetric heat capacity of water, and is removed from surface water and added to the snow column as ice .. math:: - :label: 6.74) + :label: 6.74 H^{n+1} _{h2osfc} =H^{n} _{h2osfc} -H_{m} .. math:: - :label: 6.75) + :label: 6.75 w_{ice,\, 0}^{n+1} =w_{ice,\, 0}^{n} +H_{m} The snow depth is adjusted to account for the additional ice mass .. math:: - :label: 6.76) + :label: 6.76 \Delta z_{sno} =\frac{H_{m} }{\rho _{ice} } @@ -711,7 +796,7 @@ the mineral and organic properties of the soil The soil layer organic matter fraction :math:`f_{om,i}` is .. math:: - :label: 6.77) + :label: 6.77 f_{om,i} =\rho _{om,i} /\rho _{om,\max } . @@ -719,7 +804,7 @@ Soil thermal conductivity :math:`\lambda _{i}` (W m\ :sup:`-1` K\ :sup:`-1`) is from :ref:`Farouki (1981) ` .. math:: - :label: 6.78) + :label: 6.78 \begin{array}{lr} \lambda _{i} = \left\{ @@ -741,18 +826,17 @@ ground layers (typical of saturated granitic rock; :ref:`Clauser and Huenges 1995 `). For glaciers and wetlands, .. math:: - :label: 6.79) + :label: 6.79 \lambda _{i} =\left\{\begin{array}{l} {\lambda _{liq,\, i} \qquad T_{i} \ge T_{f} } \\ {\lambda _{ice,\, i} \qquad T_{i} ` .. math:: - :label: 6.87) + :label: 6.87 \lambda _{i} =\lambda _{air} +\left(7.75\times 10^{-5} \rho _{sno,\, i} +1.105\times 10^{-6} \rho _{sno,\, i}^{2} \right)\left(\lambda _{ice} -\lambda _{air} \right) @@ -828,7 +912,7 @@ where :math:`\lambda _{air}` is the thermal conductivity of air (:numref:`Table and :math:`\rho _{sno,\, i}` is the bulk density of snow (kg m\ :sup:`-3`) .. math:: - :label: 6.88) + :label: 6.88 \rho _{sno,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{\Delta z_{i} } . @@ -837,7 +921,7 @@ soil is from :ref:`de Vries (1963) ` and depends on the heat capacities of the soil solid, liquid water, and ice constituents .. math:: - :label: ZEqnNum222806 + :label: 6.89 c_{i} =c_{s,\, i} \left(1-\theta _{sat,\, i} \right)+\frac{w_{ice,\, i} }{\Delta z_{i} } C_{ice} +\frac{w_{liq,\, i} }{\Delta z_{i} } C_{liq} @@ -847,7 +931,7 @@ and ice, respectively (:numref:`Table Physical Constants`). The heat capacity of :math:`c_{s,i}` \ (J m\ :sup:`-3` K\ :sup:`-1`) is .. math:: - :label: 6.90) + :label: 6.90 c_{s,i} =(1-f_{om,i} )c_{s,\min ,i} +f_{om,i} c_{s,om} @@ -855,7 +939,7 @@ where the heat capacity of mineral soil solids :math:`c_{s,\min ,\, i}` (J m\ :sup:`-3` K\ :sup:`-1`) is .. math:: - :label: 6.91) + :label: 6.91 \begin{array}{lr} c_{s,\min ,\, i} =\left(\frac{2.128{\rm \; }\left(\% sand\right)_{i} +{\rm 2.385\; }\left(\% clay\right)_{i} }{\left(\% sand\right)_{i} +\left(\% clay\right)_{i} } \right)\times 10^{6} &\qquad i=1,\ldots ,N_{levsoi} \\ @@ -865,11 +949,11 @@ where the heat capacity of mineral soil solids where :math:`c_{s,bedrock} =2\times 10^{6}` J m\ :sup:`-3` K\ :sup:`-1` is the heat capacity of bedrock and :math:`c_{s,om} =2.5\times 10^{6}` \ J m\ :sup:`-3` -K\ :sup:`-1` (ref:`Farouki 1981 `) is the heat capacity of organic +K\ :sup:`-1` (:ref:`Farouki 1981 `) is the heat capacity of organic matter. For glaciers, wetlands, and snow .. math:: - :label: ZEqnNum107679 + :label: 6.92 c_{i} =\frac{w_{ice,\, i} }{\Delta z_{i} } C_{ice} +\frac{w_{liq,\, i} }{\Delta z_{i} } C_{liq} . @@ -878,11 +962,8 @@ there are no explicit snow layers (:math:`snl=0`), the heat capacity of the top layer is a blend of ice and soil heat capacity .. math:: - :label: 6.93) - - c_{1} =c_{1}^{\*} +\frac{C_{ice} W_{sno} }{\Delta z_{1} } - -where :math:`c_{1}^{\*}` is calculated from equation or . + :label: 6.93 -.. todo:: fill in the above - should be calculated form equation (6.89) or (6.92) + c_{1} =c_{1}^{*} +\frac{C_{ice} W_{sno} }{\Delta z_{1} } +where :math:`c_{1}^{*}` is calculated from :eq:`6.89` or :eq:`6.92`. From 0073bde0ccbed500f5052cdbc09484685cb37cdd Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 1 Jun 2017 12:37:44 -0600 Subject: [PATCH 036/255] Update Chaptes 7,8 --- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 256 +++++++++--------- .../CLM50_Tech_Note_Snow_Hydrology.rst | 157 ++++++----- 2 files changed, 219 insertions(+), 194 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 69a8907f89..0db3456163 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -16,7 +16,7 @@ m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Figure Hydrologic processes`). The total water balance of the system is .. math:: - :label: 7.1) + :label: 7.1 \begin{array}{l} {\Delta W_{can} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} @@ -53,42 +53,43 @@ m\ :sup:`-2` s\ :sup:`-1`) does not distinguish between liquid and solid phases .. math:: - :label: 7.2) + :label: 7.2 q_{intr} =\alpha \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} where :math:`L` and :math:`S` are the exposed leaf and stem area index, -respectively (section 2.1.4), and :math:`\alpha =0.25` scales -interception from point to grid cell (:ref:`Lawrence et al. 2007 `). Throughfall +respectively (section :numref:`Phenology and vegetation burial by snow`), +and :math:`\alpha =0.25` scales interception from point to grid cell +(:ref:`Lawrence et al. 2007 `). Throughfall (kg m\ :sup:`-2` s\ :sup:`-1`), however, is divided into liquid and solid phases reaching the ground (soil or snow surface) as .. math:: - :label: 7.3) + :label: 7.3 q_{thru,\, liq} =q_{rain} \left[1-\alpha \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right] .. math:: - :label: 7.4) + :label: 7.4 q_{thru,\, ice} =q_{sno} \left[1-\alpha \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right]. Similarly, the canopy drip is .. math:: - :label: 7.5) + :label: 7.5 q_{drip,\, liq} =\frac{W_{can}^{intr} -W_{can,\, \max } }{\Delta t} \frac{q_{rain} }{q_{rain} +q_{sno} } \ge 0 .. math:: - :label: 7.6) + :label: 7.6 q_{drip,\, ice} =\frac{W_{can}^{intr} -W_{can,\, \max } }{\Delta t} \frac{q_{sno} }{q_{rain} +q_{sno} } \ge 0 where .. math:: - :label: 7.7) + :label: 7.7 W_{can}^{intr} =W_{can}^{n} +q_{intr} \Delta t\ge 0 @@ -98,7 +99,7 @@ and :math:`W_{can,\, \max }` (kg m\ :sup:`-2`) is the maximum amount of water the canopy can hold .. math:: - :label: 7.8) + :label: 7.8 W_{can,\, \max } =p\left(L+S\right). @@ -107,7 +108,7 @@ liquid water, :math:`p=0.1` kg m\ :sup:`-2` (:ref:`Dickinson et al. 1993 `). The canopy water is updated as .. math:: - :label: 7.9) + :label: 7.9 W_{can}^{n+1} =W_{can}^{n} +q_{intr} \Delta t-\left(q_{drip,\, liq} +q_{drip,\, ice} \right)\Delta t-E_{v}^{w} \Delta t\ge 0. @@ -116,12 +117,12 @@ surfaces (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) reaching the ground is then .. math:: - :label: ZEqnNum946822 + :label: 7.10 q_{grnd,liq} =q_{thru,\, liq} +q_{drip,\, liq} .. math:: - :label: ZEqnNum339590 + :label: 7.11 q_{grnd,ice} =q_{thru,\, ice} +q_{drip,\, ice} . @@ -138,7 +139,7 @@ for the surface albedo (section :numref:`Canopy Radiative Transfer`) and surface calculations is (:ref:`Dickinson et al.1993 `) .. math:: - :label: 7.12) + :label: 7.12 f_{wet} = \left\{\begin{array}{lr} @@ -149,7 +150,7 @@ calculations is (:ref:`Dickinson et al.1993 `) while the fraction of the canopy that is dry and transpiring is .. math:: - :label: 7.13) + :label: 7.13 f_{dry} = \left\{\begin{array}{lr} @@ -183,21 +184,21 @@ portion of a grid cell contributes to surface runoff, :math:`q_{over}` , by the saturation excess mechanism (Dunne runoff) .. math:: - :label: ZEqnNum549608 + :label: 7.64 q_{over} =f_{sat} q_{liq,\, 0} The fractional saturated area is a function of soil moisture .. math:: - :label: 7.65) + :label: 7.65 - f_{sat} =f_{\max } \exp \left(-0.5f_{over} z_{\nabla } \right) + f_{sat} = f_{\max } \exp \left(-0.5 f_{over} z_{\nabla } \right) -where :math:`f_{\max }` is the potential or maximum value of -:math:`f_{sat}` , :math:`f_{over}` is a decay factor -(m\ :sup:`-1`), and :math:`z_{\nabla}` is the water table depth -(m) (section 7.6). The maximum saturated fraction, :math:`f_{\max }` , +where :math:`f_{\max }` is the potential or maximum value of +:math:`f_{sat}`, :math:`f_{over}` is a decay factor (m\ :sup:`-1`), and +:math:`z_{\nabla}` is the water table depth (m) (section +:numref:`Lateral Sub-surface Runoff`). The maximum saturated fraction, :math:`f_{\max }` , is defined as the value of the discrete cumulative distribution function (CDF) of the topographic index when the grid cell mean water table depth is zero. Thus, :math:`f_{\max }` is the percent of pixels in a grid @@ -242,7 +243,7 @@ height (relative to the grid cell mean elevation) of the surface water, :math:`d`, by .. math:: - :label: ZEqnNum277892 + :label: 7.66 W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)+\frac{\sigma _{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma _{micro} ^{2} } } @@ -252,7 +253,7 @@ Newton-Raphson method. Once :math:`d` is known, one can determine the fraction of the area that is inundated as .. math:: - :label: 7.67) + :label: 7.67 f_{h2osfc} =\frac{1}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right) @@ -260,7 +261,7 @@ No global datasets exist for microtopography, so the default parameterization is a simple function of slope .. math:: - :label: 7.68) + :label: 7.68 \sigma _{micro} =\left(\beta +\beta _{0} \right)^{\eta } @@ -277,7 +278,7 @@ percolation theory can be used to quantify the fraction of the inundated portion of the grid cell that is interconnected .. math:: - :label: 7.69) + :label: 7.69 \begin{array}{lr} f_{connected} =\left(f_{h2osfc} -f_{c} \right)^{\mu } & \qquad f_{h2osfc} >f_{c} \\ f_{connected} =0 &\qquad f_{h2osfc} \le f_{c} \end{array} @@ -289,7 +290,7 @@ surpasses :math:`f_{c}` , the surface water store acts as a linear reservoir .. math:: - :label: 7.70) + :label: 7.70 qout,h2osfc=kh2osfcf_{connected} (Wsfc-Wc)\frac{1}{\Delta t} @@ -309,7 +310,7 @@ The surface moisture flux remaining after surface runoff has been removed, .. math:: - :label: 7.71) + :label: 7.71 qin,surface=(1-f_{sat} )q_{liq,\, 0} @@ -319,7 +320,7 @@ maximum soil infiltration capacity (kg m\ :sup:`-2` s\ :sup:`-1`), .. math:: - :label: ZEqnNum569150 + :label: 7.72 q_{infl,\, \max } =(1-fsat){\rm \Theta }iceksat @@ -327,7 +328,7 @@ where :math:`{\rm \Theta }ice` is an ice impedance factor (section :numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff is generated .. math:: - :label: 7.73) + :label: 7.73 q_{infl,\, excess} =\max \left(q_{in,soil} -\left(1-f_{h2osfc} \right)q_{\inf l,\max } ,0\right) @@ -335,28 +336,28 @@ and transferred from :math:`q_{in,soil}` to :math:`q_{in,h2osfc}` . After evaporative losses have been removed, these moisture fluxes are .. math:: - :label: 7.74) + :label: 7.74 q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} +q_{infl,excess} -q_{evap,h2osfc} and .. math:: - :label: 7.75) + :label: 7.75 qin,soil=(1-f_{h2osfc} )q_{in,surface} -q_{\inf l,excess} -(1-f_{sno} -f_{h2osfc} )qevap,soil. The balance of surface water is then calculated as .. math:: - :label: 7.76) + :label: 7.76 \Delta W_{sfc} =\left(qin,h2osfc-qout,h2osfc-qdrain,h2osfc\right)\Delta t. Bottom drainage from the surface water store .. math:: - :label: 7.77) + :label: 7.77 qdrain,h2osfc=\min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) @@ -364,7 +365,7 @@ is then added to :math:`q_{in,soil}` giving the total infiltration into the surface soil layer .. math:: - :label: 7.78) + :label: 7.78 q_{infl} =q_{in,soil} +q_{drain,h2osfc} @@ -387,7 +388,7 @@ For one-dimensional vertical water flow in soils, the conservation of mass is stated as .. math:: - :label: ZEqnNum790844 + :label: 7.79 \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q @@ -409,7 +410,7 @@ The soil water flux :math:`q` in equation can be described by Darcy’s law :ref:`(Dingman 2002) ` .. math:: - :label: 7.80) + :label: 7.80 q=-k\frac{\partial \psi _{h} }{\partial z} @@ -418,7 +419,7 @@ and :math:`\psi _{h}` is the hydraulic potential (mm). The hydraulic potential is .. math:: - :label: 7.81) + :label: 7.81 \psi _{h} =\psi _{m} +\psi _{z} @@ -431,22 +432,22 @@ If the reference elevation is the soil surface, then becomes .. math:: - :label: ZEqnNum186573 + :label: 7.82 q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]. -Equation :eq:`ZEqnNum186573` can be further manipulated to yield +Equation :eq:`7.82` can be further manipulated to yield .. math:: - :label: 7.83) + :label: 7.83 q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]=-k\left(\frac{\partial \psi }{\partial z} +1\right)=-k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right). -Substitution of this equation into equation :eq:`ZEqnNum790844`, with :math:`Q=0`, yields +Substitution of this equation into equation :eq:`7.79`, with :math:`Q=0`, yields the Richards equation .. math:: - :label: ZEqnNum670361 + :label: 7.84 \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right)\right]. @@ -458,7 +459,8 @@ Hydraulic Properties The hydraulic conductivity :math:`k_{i}` (mm s\ :sup:`-1`) and the soil matric potential :math:`\psi _{i}` (mm) for layer :math:`i` vary with volumetric soil water :math:`\theta _{i}` and soil texture. -As with the soil thermal properties (section :numref:`Soil And Snow Thermal Properties`) the hydraulic +As with the soil thermal properties (section +:numref:`Soil And Snow Thermal Properties`) the hydraulic properties of the soil are assumed to be a weighted combination of the mineral properties, which are determined according to sand and clay contents based on work by :ref:`Clapp and Hornberger (1978) @@ -475,7 +477,7 @@ moisture of the two layers :math:`\theta _{i}` and :math:`\Theta _{ice}` .. math:: - :label: ZEqnNum398074 + :label: 7.85 k\left[z_{h,\, i} \right] = \left\{\begin{array}{lr} @@ -497,7 +499,7 @@ computed as weighted averages of the properties of the mineral and organic components. The water content at saturation (i.e. porosity) is .. math:: - :label: 7.90) + :label: 7.90 \theta _{sat,i} =(1-f_{om,i} )\theta _{sat,\min ,i} +f_{om,i} \theta _{sat,om} @@ -508,21 +510,21 @@ porosity of organic matter and the porosity of the mineral soil :math:`\theta _{sat,\min ,i}` is .. math:: - :label: 7.91) + :label: 7.91 \theta _{sai,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . The exponent :math:`B_{i}` is .. math:: - :label: 7.92) + :label: 7.92 B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} where :math:`B_{om} = 2.7` \ (:ref:`Letts et al. 2000 `) and .. math:: - :label: 7.93) + :label: 7.93 B_{\min ,i} =2.91+0.159(\% clay)_{i} . @@ -530,14 +532,14 @@ The soil matric potential (mm) is defined at the node depth :math:`z_{i}` of each layer :math:`i` (:numref:`Figure Water flux schematic`) .. math:: - :label: ZEqnNum316201 + :label: 7.94 \psi _{i} =\psi _{sat,\, i} \left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta _{i} }{\theta _{sat,\, i} } \le 1 where the saturated soil matric potential (mm) is .. math:: - :label: 7.95) + :label: 7.95 \psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om} @@ -546,7 +548,7 @@ saturated organic matter matric potential and the saturated mineral soil matric potential :math:`\psi _{sat,\min ,i}` \ is .. math:: - :label: 7.96) + :label: 7.96 \psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } . @@ -570,7 +572,7 @@ pathways interacts only with organic material, and thus can be described by :math:`k_{sat,\, om}` . This fraction of the grid cell is given by .. math:: - :label: 7.97) + :label: 7.97 \begin{array}{lr} f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta _{perc} } f_{om} {\rm \; } & \qquad f_{om} \ge f_{threshold} \\ @@ -585,7 +587,7 @@ hydraulic conductivity is assumed to correspond to flow pathways that pass through the mineral and organic components in series .. math:: - :label: 7.98) + :label: 7.98 k_{sat,\, uncon} =f_{uncon} \left(\frac{\left(1-f_{om} \right)}{k_{sat,\, \min } } +\frac{\left(f_{om} -f_{perc} \right)}{k_{sat,\, om} } \right)^{-1} . @@ -593,7 +595,7 @@ where saturated hydraulic conductivity for mineral soil depends on soil texture (:ref:`Cosby et al. 1984 `) as .. math:: - :label: 7.99) + :label: 7.99 k_{sat,\, \min } \left[z_{h,\, i} \right]=0.0070556\times 10^{-0.884+0.0153\left(\% sand\right)_{i} } . @@ -601,7 +603,7 @@ The bulk soil layer saturated hydraulic conductivity is then computed as .. math:: - :label: 7.100) + :label: 7.100 k_{sat} \left[z_{h,\, i} \right]=f_{uncon,\, i} k_{sat,\, uncon} \left[z_{h,\, i} \right]+(1-f_{uncon,\, i} )k_{sat,\, om} \left[z_{h,\, i} \right]. @@ -610,11 +612,11 @@ as Numerical Solution ^^^^^^^^^^^^^^^^^^^^^^^^ -With reference to :numref:`Figure Water flux schematic`, the equation for conservation of mass -(equation :eq:`ZEqnNum790844`) can be integrated over each layer as +With reference to :numref:`Figure Water flux schematic`, the equation for +conservation of mass :eq:`7.79` can be integrated over each layer as .. math:: - :label: 7.101) + :label: 7.101 \int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }Q\, dz . @@ -623,7 +625,7 @@ as positive upward from the soil surface. This equation can be written as .. math:: - :label: ZEqnNum225309 + :label: 7.102 \Delta z_{i} \frac{\partial \theta _{liq,\, i} }{\partial t} =-q_{i-1} +q_{i} -e_{i} @@ -635,7 +637,7 @@ the layer (mm s\ :sup:`-1`). Taking the finite difference with time and evaluating the fluxes implicitly at time :math:`n+1` yields .. math:: - :label: ZEqnNum181361 + :label: 7.103 \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =-q_{i-1}^{n+1} +q_{i}^{n+1} -e_{i} @@ -650,7 +652,7 @@ function of the total transpiration :math:`E_{v}^{t}` (Chapter :numref:`rst_Mom the effective root fraction :math:`r_{e,\, i}` .. math:: - :label: ZEqnNum357392 + :label: 7.104 e_{i} =r_{e,\, i} E_{v}^{t} . @@ -676,7 +678,7 @@ soil column, the transpiration :math:`E_{v}^{t}` is a weighted sum of transpiration from all PFTs whose weighting depends on PFT area as .. math:: - :label: 7.105) + :label: 7.105 E_{v}^{t} =\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} @@ -689,7 +691,7 @@ quantity that is a weighted sum over all PFTs. The weighting depends on the per unit area transpiration of each PFT and its relative area as .. math:: - :label: 7.106) + :label: 7.106 r_{e,\, i} =\frac{\sum _{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} } @@ -697,15 +699,20 @@ where :math:`\left(r_{e,\, i} \right)_{j}` is the effective root fraction for the :math:`j^{th}` PFT .. math:: - :label: 7.107) + :label: 7.107 - \begin{array}{l} {\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } \qquad \left(\beta _{t} \right)_{j} >0} \\ {\left(r_{e,\, i} \right)_{j} =0\qquad \left(\beta _{t} \right)_{j} =0} \end{array} + \begin{array}{lr} + \left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } & \qquad \left(\beta _{t} \right)_{j} >0 \\ + \left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta _{t} \right)_{j} =0 + \end{array} and :math:`\left(r_{i} \right)_{j}` is the fraction of roots in layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), -:math:`\left(w_{i} \right)_{j}` is a soil dryness or plant wilting factor -for layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total -soil column for the :math:`j^{th}` PFT (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). +:math:`\left(w_{i} \right)_{j}` is a soil dryness or plant wilting factor for +layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), +and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total +soil column for the :math:`j^{th}` PFT (Chapter +:numref:`rst_Stomatal Resistance and Photosynthesis`). The soil water fluxes in equation , which are a function of :math:`\theta _{liq,\, i}` and :math:`\theta _{liq,\, i+1}` because of @@ -714,12 +721,12 @@ can be linearized about :math:`\theta` using a Taylor series expansion as .. math:: - :label: 7.108) + :label: 7.108 q_{i}^{n+1} =q_{i}^{n} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } \Delta \theta _{liq,\, i+1} .. math:: - :label: 7.109) + :label: 7.109 q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } \Delta \theta _{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} . @@ -728,29 +735,29 @@ Substitution of these expressions for :math:`q_{i}^{n+1}` and equation set of the form .. math:: - :label: 7.110) + :label: 7.110 r_{i} =a_{i} \Delta \theta _{liq,\, i-1} +b_{i} \Delta \theta _{liq,\, i} +c_{i} \Delta \theta _{liq,\, i+1} where .. math:: - :label: ZEqnNum557934 + :label: 7.111 a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: - :label: 7.112) + :label: 7.112 b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.113) + :label: 7.113 c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } .. math:: - :label: ZEqnNum981892 + :label: 7.114 r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . @@ -761,32 +768,32 @@ The finite-difference forms of the fluxes and partial derivatives in equations - can be obtained from equation as .. math:: - :label: 7.115) + :label: 7.115 q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.116) + :label: 7.116 q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] .. math:: - :label: 7.117) + :label: 7.117 \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.118) + :label: 7.118 \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.119) + :label: 7.119 \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] .. math:: - :label: 7.120) + :label: 7.120 \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right]. @@ -794,17 +801,17 @@ The derivatives of the soil matric potential at the node depth are derived from equation .. math:: - :label: 7.121) + :label: 7.121 \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta _{\, \, i-1} } .. math:: - :label: 7.122) + :label: 7.122 \frac{\partial \psi _{i} }{\partial \theta _{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta _{i} } .. math:: - :label: 7.123) + :label: 7.123 \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta _{\, i+1} } @@ -815,12 +822,12 @@ The derivatives of the hydraulic conductivity at the layer interface are derived from equation .. math:: - :label: 7.124) + :label: 7.124 \begin{array}{l} {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } =\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } =\left(1-\frac{f_{frz,\, i-1} +f_{frz,\, i} }{2} \right)\left(2B_{i-1} +3\right)k_{sat} \left[z_{h,\, i-1} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right]^{2B_{i-1} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right)} \end{array} .. math:: - :label: 7.125) + :label: 7.125 \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } =\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } =\left(1-\frac{f_{frz,\, i} +f_{frz,\, i+1} }{2} \right)\left(2B_{i} +3\right)k_{sat} \left[z_{h,\, i} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right)} \end{array}. @@ -833,7 +840,7 @@ infiltration rate (section :numref:`Surface Runoff`), is .. math:: - :label: 7.135) + :label: 7.135 \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =q_{infl}^{n+1} +q_{i}^{n+1} -e_{i} . @@ -841,22 +848,22 @@ After grouping like terms, the coefficients of the tridiagonal set of equations for :math:`i=1` are .. math:: - :label: 7.136) + :label: 7.136 a_{i} =0 .. math:: - :label: 7.137) + :label: 7.137 b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.138) + :label: 7.138 c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } .. math:: - :label: 7.139) + :label: 7.139 r_{i} =q_{infl}^{n+1} -q_{i}^{n} +e_{i} . @@ -867,22 +874,22 @@ The coefficients of the tridiagonal set of equations for :math:`i=2,\ldots ,N_{levsoi} -1` are .. math:: - :label: 7.140) + :label: 7.140 a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: - :label: 7.141) + :label: 7.141 b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.142) + :label: 7.142 c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } .. math:: - :label: 7.143) + :label: 7.143 r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . @@ -895,22 +902,22 @@ and the coefficients of the tridiagonal set of equations for :math:`i=N_{levsoi}` are .. math:: - :label: 7.148) + :label: 7.148 a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: - :label: 7.149) + :label: 7.149 b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.150) + :label: 7.150 c_{i} =0 .. math:: - :label: 7.151) + :label: 7.151 r_{i} =q_{i-1}^{n} +e_{i} . @@ -921,7 +928,7 @@ An initial solution is found by setting :math:`\Delta t` equal to the model time step. An estimate of the error is calculated from .. math:: - :label: 7.152) + :label: 7.152 \epsilon = max \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] @@ -937,14 +944,14 @@ Upon solution of the tridiagonal equation set, the liquid water contents are updated as follows .. math:: - :label: 7.164) + :label: 7.164 w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta _{liq,\, i} \Delta z_{i} \qquad i=1,\ldots ,N_{levsoi} . The volumetric water content is .. math:: - :label: 7.165) + :label: 7.165 \theta _{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } . @@ -954,7 +961,8 @@ Frozen Soils and Perched Water Table ---------------------------------------- When soils freeze, the power-law form of the ice impedance factor -(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic conductivity of the +(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic +conductivity of the soil, leading to nearly impermeable soil layers. When unfrozen soil layers are present above relatively ice-rich frozen layers, the possibility exists for perched saturated zones. Lateral drainage from @@ -962,7 +970,7 @@ perched saturated regions is parameterized as a function of the thickness of the saturated zone .. math:: - :label: 7.166) + :label: 7.166 q_{drai,perch} =k_{drai,\, perch} \left(z_{frost} -z_{\nabla ,perch} \right) @@ -970,7 +978,7 @@ where :math:`k_{drai,\, perch}` depends on topographic slope and soil hydraulic conductivity, .. math:: - :label: 7.167) + :label: 7.167 k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta _{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right) @@ -995,7 +1003,7 @@ Lateral sub-surface runoff occurs when saturated soil moisture conditions exist within the soil column. Sub-surface runoff is .. math:: - :label: 7.168) + :label: 7.168 q_{subsurface} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) \Delta z_{sat}^{N_{baseflow}} \ , @@ -1007,13 +1015,14 @@ is the thickness of the saturated portion of the soil column. The saturated thickness is .. math:: - :label: 7.1681) + :label: 7.1681 \Delta z_{sat} = z_{bedrock} - z_{\nabla}, where the water table :math:`z_{\nabla}` is determined by finding the -first soil layer above the bedrock depth (section ) in which the volumetric water -content drops below a specified threshold. The default threshold is set to 0.9. +first soil layer above the bedrock depth (section :numref:`Depth to Bedrock`) +in which the volumetric water content drops below a specified threshold. +The default threshold is set to 0.9. The specific yield, :math:`S_{y}` , which depends on the soil properties and the water table location, is derived by taking the @@ -1021,13 +1030,13 @@ difference between two equilibrium soil moisture profiles whose water tables differ by an infinitesimal amount .. math:: - :label: 7.174) + :label: 7.174 S_{y} =\theta _{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right) where B is the Clapp-Hornberger exponent. Because :math:`S_{y}` is a function of the soil properties, it results in water table dynamics that -are consistent with the soil water fluxes described in section 7.4. +are consistent with the soil water fluxes described in section :numref:`Soil Water`. After the above calculations, two numerical adjustments are implemented to keep the liquid water content of each soil layer @@ -1052,22 +1061,22 @@ those layers subject to the constraint found, then the water is removed from :math:`W_{t}` and :math:`q_{drai}` . -The soil surface layer liquid water and ice contents are then updated -for dew :math:`q_{sdew}` , frost :math:`q_{frost}` , or sublimation -:math:`q_{subl}` (section 5.4) as +The soil surface layer liquid water and ice contents are then updated for +dew :math:`q_{sdew}`, frost :math:`q_{frost}`, or sublimation :math:`q_{subl}` +(section :numref:`Update of Ground Sensible and Latent Heat Fluxes`) as .. math:: - :label: 7.175) + :label: 7.175 w_{liq,\, 1}^{n+1} =w_{liq,\, 1}^{n} +q_{sdew} \Delta t .. math:: - :label: 7.176) + :label: 7.176 w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} +q_{frost} \Delta t .. math:: - :label: 7.177) + :label: 7.177 w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} -q_{subl} \Delta t. @@ -1085,12 +1094,12 @@ and dew in solid or liquid form, is separated into solid :math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms .. math:: - :label: 7.178) + :label: 7.178 q_{snwcp,ice} =q_{grnd,ice} +q_{frost} .. math:: - :label: 7.179) + :label: 7.179 q_{snwcp,liq} =q_{grnd,liq} +q_{dew} @@ -1106,7 +1115,7 @@ For glacier surfaces the runoff term :math:`q_{rgwl}` is calculated from the residual of the water balance .. math:: - :label: 7.180) + :label: 7.180 q_{rgwl} =q_{grnd,ice} +q_{grnd,liq} -E_{g} -E_{v} -\frac{\left(W_{b}^{n+1} -W_{b}^{n} \right)}{\Delta t} -q_{snwcp,ice} @@ -1114,7 +1123,7 @@ where :math:`W_{b}^{n}` and :math:`W_{b}^{n+1}` are the water balances at the beginning and ending of the time step defined as .. math:: - :label: 7.181) + :label: 7.181 W_{b} =W_{can} +W_{sno} +\sum _{i=1}^{N}\left(w_{ice,i} +w_{liq,i} \right) . @@ -1122,5 +1131,6 @@ Currently, glaciers are non-vegetated and :math:`E_{v} =W_{can} =0`. The contribution of lake runoff to :math:`q_{rgwl}` is described in section :numref:`Precipitation, Evaporation, and Runoff Lake`. The runoff term :math:`q_{rgwl}` may be negative for glaciers and lakes, which reduces -the total amount of runoff available to the river routing model (Chapter :numref:`rst_River Transport Model (RTM)`). +the total amount of runoff available to the river routing model +(Chapter :numref:`rst_River Transport Model (RTM)`). diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index dbe949bd34..5f87ec2f1a 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -3,21 +3,20 @@ Snow Hydrology =============== -The parameterizations for snow are based primarily on :ref:`Anderson (1976) `, -:ref:`Jordan (1991) `, and :ref:`Dai and Zeng (1997) `. The snowpack +The parameterizations for snow are based primarily on +:ref:`Anderson (1976) `, :ref:`Jordan (1991) `, +and :ref:`Dai and Zeng (1997) `. The snowpack can have up to five layers. These layers are indexed in the Fortran code as :math:`i=-4,-3,-2,-1,0` where layer :math:`i=0` is the snow layer next to the top soil layer and layer :math:`i=-4` is the top layer of a five-layer snow pack. Since the number of snow layers varies according to the snow depth, we use the notation :math:`snl+1` to describe the top layer of snow for the variable layer snow pack, where :math:`snl` is the -negative of the number of snow layers. Refer to Figure :numref:`three layer +negative of the number of snow layers. Refer to :numref:`Figure three layer snow pack` for an example of the snow layer structure for a three layer snow pack. -.. Figure 8.2. Example of three layer snow pack (:math:`snl=-3`). - -.. _three layer snow pack: +.. _Figure three layer snow pack: .. Figure:: image1.png @@ -61,7 +60,7 @@ calculated separately for accumulation and depletion. When snowfall occurs, :math:`f_{sno}` is updated as .. math:: - :label: 8.14) + :label: 8.14 f^{n+1} _{sno} =1-\left(\left(1-\tanh (k_{accum} q_{sno} \Delta t)\right)\left(1-f^{n} _{sno} \right)\right) @@ -74,7 +73,7 @@ When snow melt occurs, :math:`f_{sno}` is calculated from the depletion curve .. math:: - :label: 8.15) + :label: 8.15 f_{sno} =1-\left(\frac{\cos ^{-1} \left(2R_{sno} -1\right)}{\pi } \right)^{N_{melt} } @@ -85,7 +84,7 @@ cell. Whenever :math:`W_{sno}` reaches zero, :math:`W_{\max }` is reset to zero. The depletion curve shape parameter is defined as .. math:: - :label: 8.16) + :label: 8.16 N_{melt} =\frac{200}{\min \left(10,\sigma _{topo} \right)} @@ -101,7 +100,7 @@ Ice Content The conservation equation for mass of ice in snow layers is .. math:: - :label: 8.17) + :label: 8.17 \frac{\partial w_{ice,\, i} }{\partial t} = \left\{\begin{array}{lr} @@ -117,7 +116,7 @@ is the change in ice due to phase change (melting rate) (section :numref:`Phase The term :math:`q_{ice,\, i-1}` is computed in two steps as .. math:: - :label: 8.18) + :label: 8.18 q_{ice,\, i-1} =q_{grnd,\, ice} +\left(q_{frost} -q_{subl} \right) @@ -130,14 +129,14 @@ interception (section :numref:`Canopy Water`), a new snow depth :math:`z_{sno}` calculated from .. math:: - :label: 8.19) + :label: 8.19 z_{sno}^{n+1} =z_{sno}^{n} +\Delta z_{sno} where .. math:: - :label: 8.20) + :label: 8.20 \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } @@ -145,7 +144,7 @@ and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg m\ :sup:`-3`) (:ref:`Anderson (1976) `) .. math:: - :label: 8.21) + :label: 8.21 \rho _{sno} = \left\{\begin{array}{lr} @@ -159,26 +158,27 @@ where :math:`T_{atm}` is the atmospheric temperature (K), and mass of snow :math:`W_{sno}` is .. math:: - :label: 8.22) + :label: 8.22 W_{sno}^{n+1} =W_{sno}^{n} +q_{grnd,\, ice} \Delta t. The ice content of the top layer and the layer thickness are updated as .. math:: - :label: 8.23) + :label: 8.23 w_{ice,\, snl+1}^{n+1} =w_{ice,\, snl+1}^{n} +q_{grnd,\, ice} \Delta t .. math:: - :label: 8.24) + :label: 8.24 \Delta z_{snl+1}^{n+1} =\Delta z_{snl+1}^{n} +\Delta z_{sno} . Since wetlands are modeled as columns of water (no soil), snow is not allowed to accumulate if the surface temperature is above freezing (:math:`T_{g} >T_{f}` ). In this case, the incoming solid precipitation -is assigned to the runoff term :math:`q_{rgwl}` (section :numref:`Runoff from glaciers and snow-capped surfaces`). +is assigned to the runoff term :math:`q_{rgwl}` (section +:numref:`Runoff from glaciers and snow-capped surfaces`). In the second step, after surface fluxes and snow/soil temperatures have been determined (Chapters :numref:`rst_Momentum, Sensible Heat, and Latent Heat @@ -186,7 +186,7 @@ Fluxes` and :numref:`rst_Soil and Snow Temperatures`), :math:`w_{ice,\, snl+1}` is updated for frost or sublimation as .. math:: - :label: ZEqnNum863244 + :label: 8.25 w_{ice,\, snl+1}^{n+1} =w_{ice,\, snl+1}^{n} +f_{sno} \left(q_{frost} -q_{subl} \right)\Delta t. @@ -209,7 +209,7 @@ Water Content The conservation equation for mass of water in snow layers is .. math:: - :label: 8.26) + :label: 8.26 \frac{\partial w_{liq,\, i} }{\partial t} =\left(q_{liq,\, i-1} -q_{liq,\, i} \right)+\frac{\left(\Delta w_{liq,\, i} \right)_{p} }{\Delta t} @@ -221,21 +221,22 @@ is the change in liquid water due to phase change (melting rate) (section :numref:`Phase Change`). For the top snow layer only, .. math:: - :label: 8.27) + :label: 8.27 q_{liq,\, i-1} =f_{sno} \left(q_{grnd,\, liq} +\left(q_{sdew} -q_{seva} \right)\right) where :math:`q_{grnd,\, liq}` is the rate of liquid precipitation reaching the snow (section :numref:`Canopy Water`), :math:`q_{seva}` is the evaporation of liquid water and :math:`q_{sdew}` is the liquid dew (section -5.4). After surface fluxes and snow/soil temperatures have been determined +:numref:`Update of Ground Sensible and Latent Heat Fluxes`). After surface +fluxes and snow/soil temperatures have been determined (Chapters :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes` and :numref:`rst_Soil and Snow Temperatures`), :math:`w_{liq,\, snl+1}` is updated for the liquid precipitation reaching the ground and dew or evaporation as .. math:: - :label: 8.28) + :label: 8.28 w_{liq,\, snl+1}^{n+1} =w_{liq,\, snl+1}^{n} +f_{sno} \left(q_{grnd,\, liq} +q_{sdew} -q_{seva} \right)\Delta t. @@ -250,7 +251,7 @@ water content. Thus, water flow between layers, :math:`q_{liq,\, i}` , for layers :math:`i=snl+1,\ldots ,0`, is initially calculated as .. math:: - :label: ZEqnNum767577 + :label: 8.29 q_{liq,\, i} =\frac{\rho _{liq} \left[\theta _{liq,\, i} -S_{r} \left(1-\theta _{ice,\, i} \right)\right]f_{sno} \Delta z_{i} }{\Delta t} \ge 0 @@ -258,12 +259,12 @@ where the volumetric liquid water :math:`\theta _{liq,\, i}` and ice :math:`\theta _{ice,\, i}` contents are .. math:: - :label: 8.30) + :label: 8.30 \theta _{ice,\, i} =\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } \le 1 .. math:: - :label: 8.31) + :label: 8.31 \theta _{liq,\, i} =\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \le 1-\theta _{ice,\, i} , @@ -275,14 +276,14 @@ calculated in equation , unless the underlying layer is the surface soil layer, as .. math:: - :label: 8.32) + :label: 8.32 q_{liq,\, i} \le \frac{\rho _{liq} \left[1-\theta _{ice,\, i+1} -\theta _{liq,\, i+1} \right]\Delta z_{i+1} }{\Delta t} \qquad i=snl+1,\ldots ,-1. The liquid water content :math:`w_{liq,\, i}` is updated as .. math:: - :label: ZEqnNum265203 + :label: 8.33 w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\left(q_{i-1} -q_{i} \right)\Delta t. @@ -307,29 +308,30 @@ eight particle species within each snow layer: hydrophilic black carbon, hydrophobic black carbon, hydrophilic organic carbon, hydrophobic organic carbon, and four species of mineral dust with the following particle sizes: 0.1-1.0, 1.0-2.5, 2.5-5.0, and 5.0-10.0 :math:`\mu m`. -Each of these species has unique optical properties (Table 3.5) and -meltwater removal efficiencies (:numref:`Table Meltwater scavenging`). +Each of these species has unique optical properties +(:numref:`Table Single-scatter albedo values used for snowpack impurities and ice`) +and meltwater removal efficiencies (:numref:`Table Meltwater scavenging`). The black carbon and organic carbon deposition rates described in Table 2.3 are combined into four categories as follows .. math:: - :label: 8.34) + :label: 8.34 D_{bc,\, hphil} =D_{bc,\, dryhphil} +D_{bc,\, wethphil} .. math:: - :label: 8.35) + :label: 8.35 D_{bc,\, hphob} =D_{bc,\, dryhphob} .. math:: - :label: 8.36) + :label: 8.36 D_{oc,\, hphil} =D_{oc,\, dryhphil} +D_{oc,\, wethphil} .. math:: - :label: 8.37) + :label: 8.37 D_{oc,\, hphob} =D_{oc,\, dryhphob} @@ -345,7 +347,7 @@ mass of each of the particle species :math:`\Delta m_{sp,\, i}` (kg m\ :sup:`-2`) is .. math:: - :label: 8.38) + :label: 8.38 \Delta m_{sp,\, i} =\left[k_{sp} \left(q_{liq,\, i-1} c_{sp,\, i-1} -q_{liq,\, i} c_{i} \right)+D_{sp} \right]\Delta t @@ -361,7 +363,7 @@ kg\ :sup:`-1`), :math:`D_{sp}` is the atmospheric deposition rate is the model time step (s). The particle mass mixing ratio is .. math:: - :label: 8.39) + :label: 8.39 c_{i} =\frac{m_{sp,\, i} }{w_{liq,\, i} +w_{ice,\, i} } . @@ -408,9 +410,16 @@ If there are no existing snow layers (:math:`snl+1=1`) but follows .. math:: - :label: 8.40) + :label: 8.40 - \begin{array}{l} {\Delta z_{0} =z_{sno} } \\ {z_{o} =-0.5\Delta z_{0} } \\ {z_{h,\, -1} =-\Delta z_{0} } \\ {T_{0} =\min \left(T_{f} ,T_{atm} \right)} \\ {w_{ice,\, 0} =W_{sno} } \\ {w_{liq,\, 0} =0} \end{array}. + \begin{array}{lcr} + \Delta z_{0} & = & z_{sno} \\ + z_{o} & = & -0.5\Delta z_{0} \\ + z_{h,\, -1} & = & -\Delta z_{0} \\ + T_{0} & = & \min \left(T_{f} ,T_{atm} \right) \\ + w_{ice,\, 0} & = & W_{sno} \\ + w_{liq,\, 0} & = & 0 + \end{array}. .. _Snow Compaction: @@ -429,14 +438,14 @@ each snow layer :math:`C_{R,\, i}` (s\ :sup:`-1`) is the sum of the three compaction processes .. math:: - :label: 8.41) + :label: 8.41 C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} . Compaction is not allowed if the layer is saturated .. math:: - :label: 8.42) + :label: 8.42 1-\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} \rho _{ice} } +\frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} \rho _{liq} } \right)\le 0.001 @@ -446,19 +455,21 @@ or if the ice content is below a minimum value Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (:ref:`Anderson (1976) `) .. math:: - :label: 8.43) + :label: 8.43 C_{R1,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{metamorphism} =-c_{3} c_{1} c_{2} \exp \left[-c_{4} \left(T_{f} -T_{i} \right)\right] where :math:`c_{3} =2.777\times 10^{-6}` (s\ :sup:`-1`) is the fractional compaction rate for :math:`T_{i} =T_{f}`, :math:`c_{4} =0.04` K\ :sup:`-1`, and .. math:: - :label: 8.44) + :label: 8.44 - c_{1} & = 1\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 100{\rm \; kg\; m}^{{\rm -3}} \\ - c_{1} & = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -100\right)\right]\qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >100{\rm \; kg\; m}^{{\rm -3}} \\ - c_{2} & = 2\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } >0.01 \\ - c_{2} & = 1\qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } \le 0.01 + \begin{array}{lr} + c_{1} = 1 & \qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{1} = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -100\right)\right] & \qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{2} = 2 & \qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } >0.01 \\ + c_{2} = 1 & \qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } \le 0.01 + \end{array} where :math:`{w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` @@ -469,14 +480,14 @@ are the bulk densities of liquid water and ice (kg m\ :sup:`-3`). The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (:ref:`Anderson (1976) `) .. math:: - :label: 8.45) + :label: 8.45 C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } where :math:`\eta` is a viscosity coefficient (kg s m\ :sup:`-2`) that varies with density and temperature as .. math:: - :label: 8.46) + :label: 8.46 \eta =\eta _{0} \exp \left[c_{5} \left(T_{f} -T_{i} \right)+c_{6} \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \right] @@ -489,7 +500,7 @@ the ice :math:`w_{ice,\, i}` and liquid water contents water contents of the layer being compacted .. math:: - :label: 8.47) + :label: 8.47 P_{s,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{2} +\sum _{j=snl+1}^{j=i-1}\left(w_{ice,\, j} +w_{liq,\, j} \right) . @@ -497,7 +508,7 @@ The compaction rate due to melting :math:`C_{R3,\; i}` (s\ :sup:`-1`) is taken t mass after the melting to the mass before melting .. math:: - :label: 8.48) + :label: 8.48 C_{R3,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} =-\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) @@ -507,14 +518,14 @@ covered area, the snow depth must also be updated for changes in :math:`f_{sno}` . .. math:: - :label: 8.49) + :label: 8.49 C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) The snow layer thickness after compaction is then .. math:: - :label: 8.50) + :label: 8.50 \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). @@ -559,12 +570,12 @@ liquid water and ice content of layer :math:`i` is combined with the underlying neighbor :math:`i+1` as .. math:: - :label: 8.51) + :label: 8.51 w_{liq,\, i+1} =w_{liq,\, i+1} +w_{liq,\, i} .. math:: - :label: 8.52) + :label: 8.52 w_{ice,\, i+1} =w_{ice,\, i+1} +w_{ice,\, i} . @@ -582,12 +593,12 @@ depth :math:`z_{sno}` are set to zero, otherwise, :math:`W_{sno}` and :math:`z_{sno}` are re-calculated as .. math:: - :label: 8.53) + :label: 8.53 W_{sno} =\sum _{i=snl+1}^{i=0}\left(w_{ice,\, i} +w_{liq,\, i} \right) .. math:: - :label: 8.54) + :label: 8.54 z_{sno} =\sum _{i=snl+1}^{i=0}\Delta z_{i} . @@ -603,26 +614,26 @@ When two snow layers are combined (denoted here as 1 and 2), their thickness combination (:math:`c`) is .. math:: - :label: ZEqnNum956014 + :label: 8.55 \Delta z_{c} =\Delta z_{1} +\Delta z_{2} , their mass combination is .. math:: - :label: 8.56) + :label: 8.56 w_{liq,\, c} =w_{liq,\, 1} +w_{liq,\, 2} .. math:: - :label: 8.57) + :label: 8.57 w_{ice,\, c} =w_{ice,\, 1} +w_{ice,\, 2} , and their temperatures are combined as .. math:: - :label: ZEqnNum325173 + :label: 8.58 T_{c} =T_{f} +\frac{h_{c} -L_{f} w_{liq,\, c} }{C_{ice} w_{ice,\, c} +C_{liq} w_{liq,\, c} } @@ -630,23 +641,24 @@ where :math:`h_{c} =h_{1} +h_{2}` is the combined enthalpy :math:`h_{i}` of the two layers where .. math:: - :label: 8.59) + :label: 8.59 h_{i} =\left(C_{ice} w_{ice,\, i} +C_{liq} w_{liq,\, i} \right)\left(T_{i} -T_{f} \right)+L_{f} w_{liq,\, i} . -In these equations, :math:`L_{f}` is the latent heat of fusion (J -kg\ :sup:`-1`) and :math:`C_{liq}` and :math:`C_{ice}` are the -specific heat capacities (J kg\ :sup:`-1` K\ :sup:`-1`) of -liquid water and ice, respectively (Table 2.6). After layer combination, -the node depths and layer interfaces (Figure 8.2) are recalculated from +In these equations, :math:`L_{f}` is the latent heat of fusion (J kg\ +:sup:`-1`) and :math:`C_{liq}` and :math:`C_{ice}` are the specific +heat capacities (J kg\ :sup:`-1` K\ :sup:`-1`) of liquid water and ice, +respectively (:numref:`Table Physical Constants`). After layer combination, +the node depths and layer interfaces (:numref:`Figure three layer snow pack`) +are recalculated from .. math:: - :label: ZEqnNum639853 + :label: 8.60 z_{i} =z_{h,\, i} -0.5\Delta z_{i} \qquad i=0,\ldots ,snl+1 .. math:: - :label: ZEqnNum295008 + :label: 8.61 z_{h,\, i-1} =z_{h,\, i} -\Delta z_{i} \qquad i=0,\ldots ,snl+1 @@ -703,16 +715,19 @@ constraining the new temperatures (:math:`T_{2}^{n+1}` , lower layer is first evaluated from .. math:: - :label: 8.62) + :label: 8.62 T'_{3} =T_{2}^{n} -\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1}^{n} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right), then adjusted as, .. math:: - :label: 8.63) + :label: 8.63 - \begin{array}{l} {T_{3}^{n+1} =T_{2}^{n} \qquad T'_{3} \ge T_{f} } \\ {T_{2}^{n+1} =T_{2}^{n} +\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1} +\Delta z_{2}^{n} \right) 2}} \right. \kern-\nulldelimiterspace} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right)\qquad T'_{3} Date: Thu, 1 Jun 2017 14:07:59 -0600 Subject: [PATCH 037/255] Add anomaly forcing subsection --- .../Glacier/CLM50_Tech_Note_Glacier.rst | 23 ++++-- .../Offline/CLM50_Tech_Note_Offline.rst | 73 ++++++++++++++----- 2 files changed, 73 insertions(+), 23 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index 6ba68086db..fa25eeb5c8 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -5,9 +5,13 @@ Glaciers This chapter describes features of CLM that are specific to coupling to an ice sheet model (in the CESM context, this is the Glimmer-CISM model; -Lipscomb and Sacks (2012) provide documentation and user’s guide for -Glimmer-CISM). General information about glacier land units can be found -elsewhere in this document (see Chapter 2 for an overview). +:ref:`Lipscomb and Sacks (2012)` provide documentation +and user’s guide for Glimmer-CISM). General information about glacier +land units can be found elsewhere in this document (see Chapter +:numref:`rst_Surface Characterization, Vertical Discretization, and +Model Input Requirements` for an overview). + +.. _Overview: Overview ------------- @@ -16,7 +20,8 @@ CLM is responsible for computing three quantities that are passed to the ice sheet model: #. Surface mass balance (SMB) – the net annual accumulation/ablation of - mass at the upper surface (section 10.3) + mass at the upper surface (section + :numref:`Computation of the surface mass balance`) #. Ground surface temperature, which serves as an upper boundary condition for Glimmer-CISM’s temperature calculation @@ -47,7 +52,8 @@ Glimmer-CISM: improvements to the CLM are applied to ice sheets automatically. #. The atmosphere model can respond during runtime to ice-sheet surface - changes. As shown by Pritchard et al. (2008), runtime albedo feedback + changes. As shown by :ref:`Pritchard et al. (2008)`, + runtime albedo feedback from the ice sheet is critical for simulating ice-sheet retreat on paleoclimate time scales. Without this feedback the atmosphere warms much less, and the retreat is delayed. @@ -71,11 +77,14 @@ which ice-sheet elevation changes are modest. For longer runs with larger elevation changes, two-way coupling is highly desirable. A two-way coupling scheme is under development. +.. _Multiple elevation class scheme: + Multiple elevation class scheme ------------------------------------ In the typical operation of CLM, the glacier land unit contains a single -column (section 2.1.1). However, when running CESM with an active ice +column (section :numref:`Surface Heterogeneity and Data Structure`). +However, when running CESM with an active ice sheet model, the glacier land unit is replaced by a glacier\_mec land unit, where “mec†denotes “multiple elevation classesâ€. In most ways, glacier\_mec land units behave the same as standard glacier land units. @@ -119,6 +128,8 @@ elevation classes. Some columns may have zero area and are called the land and the atmosphere, but are included for potential forcing of Glimmer-CISM. +.. _Computation of the surface mass balance: + Computation of the surface mass balance -------------------------------------------- diff --git a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst index e4e2db66fa..da2788a5f9 100644 --- a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst +++ b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst @@ -51,9 +51,12 @@ solar radiation supplied by the six-hourly forcing data is actually used. The solar radiation at model time step :math:`t_{M}` is .. math:: - :label: ZEqnNum160435 + :label: 31.1 - \begin{array}{l} {S_{atm} \left(t_{M} \right)=\frac{\frac{\Delta t_{FD} }{\Delta t_{M} } S_{atm} \left(t_{FD} \right)\mu \left(t_{M} \right)}{\sum _{i=1}^{\frac{\Delta t_{FD} }{\Delta t_{M} } }\mu \left(t_{M_{i} } \right) } \qquad {\rm for\; }\mu \left(t_{M} \right)>0.001} \\ {S_{atm} \left(t_{M} \right)=0\qquad {\rm for\; }\mu \left(t_{M} \right)\le 0.001} \end{array} + \begin{array}{lr} + S_{atm} \left(t_{M} \right)=\frac{\frac{\Delta t_{FD} }{\Delta t_{M} } S_{atm} \left(t_{FD} \right)\mu \left(t_{M} \right)}{\sum _{i=1}^{\frac{\Delta t_{FD} }{\Delta t_{M} } }\mu \left(t_{M_{i} } \right) } & \qquad {\rm for\; }\mu \left(t_{M} \right)>0.001 \\ + S_{atm} \left(t_{M} \right)=0 & \qquad {\rm for\; }\mu \left(t_{M} \right)\le 0.001 + \end{array} where :math:`\Delta t_{FD}` is the time step of the forcing data (6 hours :math:`\times` 3600 seconds hour\ :sup:`-1` = 21600 @@ -73,22 +76,22 @@ derived from one year’s worth of hourly CAM output from CAM version cam3\_5\_55 as .. math:: - :label: 31.2) + :label: 31.2 S_{atm} \, \downarrow _{vis}^{\mu } =R_{vis} \left(\alpha S_{atm} \right) .. math:: - :label: 31.3) + :label: 31.3 S_{atm} \, \downarrow _{nir}^{\mu } =R_{nir} \left[\left(1-\alpha \right)S_{atm} \right] .. math:: - :label: 31.4) + :label: 31.4 S_{atm} \, \downarrow _{vis} =\left(1-R_{vis} \right)\left(\alpha S_{atm} \right) .. math:: - :label: 31.5) + :label: 31.5 S_{atm} \, \downarrow _{nir} =\left(1-R_{nir} \right)\left[\left(1-\alpha \right)S_{atm} \right]. @@ -96,7 +99,7 @@ where :math:`\alpha` , the ratio of visible to total incident solar radiation, is assumed to be .. math:: - :label: 31.6) + :label: 31.6 \alpha =\frac{S_{atm} \, \downarrow _{vis}^{\mu } +S_{atm} \, \downarrow _{vis}^{} }{S_{atm} } =0.5. @@ -104,14 +107,14 @@ The ratio of direct to total incident radiation in the visible :math:`R_{vis}` is .. math:: - :label: 31.7) + :label: 31.7 R_{vis} =a_{0} +a_{1} \times \alpha S_{atm} +a_{2} \times \left(\alpha S_{atm} \right)^{2} +a_{3} \times \left(\alpha S_{atm} \right)^{3} \qquad 0.01\le R_{vis} \le 0.99 and in the near-infrared :math:`R_{nir}` is .. math:: - :label: 31.8) + :label: 31.8 R_{nir} =b_{0} +b_{1} \times \left(1-\alpha \right)S_{atm} +b_{2} \times \left[\left(1-\alpha \right)S_{atm} \right]^{2} +b_{3} \times \left[\left(1-\alpha \right)S_{atm} \right]^{3} \qquad 0.01\le R_{nir} \le 0.99 @@ -129,17 +132,17 @@ The potential temperature :math:`\overline{\theta _{atm} }` (K) is set to the atmospheric temperature :math:`T_{atm}` . The atmospheric longwave radiation :math:`L_{atm} \, \downarrow` (W m\ :sup:`-2`) is derived from the atmospheric vapor pressure :math:`e_{atm}` and -temperature :math:`T_{atm}` (Idso 1981) as +temperature :math:`T_{atm}` (:ref:`Idso 1981`) as .. math:: - :label: 31.9) + :label: 31.9 L_{atm} \, \downarrow =\left[0.70+5.95\times 10^{-5} \times 0.01e_{atm} \exp \left(\frac{1500}{T_{atm} } \right)\right]\sigma T_{atm}^{4} where .. math:: - :label: 31.10) + :label: 31.10 e_{atm} =\frac{P_{atm} q_{atm} }{0.622+0.378q_{atm} } @@ -149,19 +152,19 @@ precipitation :math:`P` (mm s\ :sup:`-1`) falling as rain and/or snow is .. math:: - :label: ZEqnNum336485 + :label: 31.11 q_{rain} =P\left(f_{P} \right), .. math:: - :label: 31.12) + :label: 31.12 q_{snow} =P\left(1-f_{P} \right) where .. math:: - :label: 31.13) + :label: 31.13 f_{P} =0<0.5\left(T_{atm} -T_{f} \right)<1. @@ -177,7 +180,7 @@ user-supplied relative humidity :math:`RH` (%) and derive specific humidity :math:`q_{atm}` (kg kg\ :sup:`-1`) from .. math:: - :label: 31.14) + :label: 31.14 q_{atm} =\frac{0.622e_{atm} }{P_{atm} -0.378e_{atm} } @@ -193,7 +196,7 @@ temperature :math:`T_{dew}` (K) and derive specific humidity :math:`q_{atm}` from .. math:: - :label: 31.15) + :label: 31.15 q_{atm} = \frac{0.622e_{sat}^{T_{dew} } }{P_{atm} -0.378e_{sat}^{T_{dew} } } . @@ -211,3 +214,39 @@ the procedure described above and then each term equally apportioned into the visible and near-infrared wavebands (e.g., :math:`S_{atm} \, \downarrow _{vis}^{\mu } =0.5S_{atm} \, \downarrow ^{\mu }` , :math:`S_{atm} \, \downarrow _{nir}^{\mu } =0.5S_{atm} \, \downarrow ^{\mu }` ). + +.. _Anomaly Forcing: + +Anomaly Forcing +----------------------------- + +The 'Anomaly Forcing' atmospheric forcing mode provides a means to drive +CLM with projections of future climate conditions without the need for +large, high-frequency datasets. From an existing climate simulation +spanning both the historical and future time periods, a set of anomalies +are created by removing a climatological seasonal cycle based on the end +of the historical period from each year of the future time period of the +simulation. These anomalies can then be applied to a repeating +high-frequency forcing dataset of finite duration (e.g. 10 years). State +and flux forcing variables are adjusted using additive and multiplicative +anomalies, respectively: + +.. math:: + :label: 31.16 + + \begin{array}{lr} + S^{'} = S + k_{anomaly} & \quad {\rm state \ variable} \\ + F^{'} = f * k_{anomaly} & \quad {\rm flux \ variable} + \end{array} + +where :math:`S^{'}` is the adjusted atmospheric state variable, :math:`S` +is the state variable from the high-frequency reference atmospheric +forcing dataset, and :math:`k_{anomaly}` is an additive anomaly. +Similarly, math:`F^{'}` is the adjusted atmospheric flux variable, +:math:`F` is the flux variable from the high-frequency reference +atmospheric forcing dataset, and :math:`k_{anomaly}` is a +multiplicative anomaly. State variables are temperature :math:`T_{atm}`, +pressure :math:`P_{atm}`, humidity :math:`q_{atm}`, and wind +:math:`W_{atm}`. Flux variables are precipitation :math:`P`, atmospheric +shortwave radiation :math:`S_{atm} \, \downarrow`, and atmospheric +longwave radiation :math:`L_{atm} \, \downarrow`. From e92ef848265e40a16d1eccac7505286192a78e92 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 2 Jun 2017 09:30:57 -0600 Subject: [PATCH 038/255] Update Hydrology Chapter --- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 108 +++++++++++------- 1 file changed, 65 insertions(+), 43 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 0db3456163..4e203f8586 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -186,14 +186,14 @@ by the saturation excess mechanism (Dunne runoff) .. math:: :label: 7.64 - q_{over} =f_{sat} q_{liq,\, 0} + q_{over} =f_{sat} \ q_{liq,\, 0} The fractional saturated area is a function of soil moisture .. math:: :label: 7.65 - f_{sat} = f_{\max } \exp \left(-0.5 f_{over} z_{\nabla } \right) + f_{sat} = f_{\max } \ \exp \left(-0.5 f_{over} z_{\nabla } \right) where :math:`f_{\max }` is the potential or maximum value of :math:`f_{sat}`, :math:`f_{over}` is a decay factor (m\ :sup:`-1`), and @@ -248,7 +248,7 @@ height (relative to the grid cell mean elevation) of the surface water, W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)+\frac{\sigma _{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma _{micro} ^{2} } } where :math:`erf` is the error function. For a given value of -:math:`W_{sfc}` , equation can be solved for :math:`d` using the +:math:`W_{sfc}`, :eq:`7.66` can be solved for :math:`d` using the Newton-Raphson method. Once :math:`d` is known, one can determine the fraction of the area that is inundated as @@ -267,7 +267,7 @@ parameterization is a simple function of slope where :math:`\beta` is the topographic slope, :math:`\beta _{0} =\left(\sigma _{\max } \right)^{\frac{1}{\eta } }` \ determines -the maximum value of :math:`\sigma _{}` , and :math:`\eta` is an +the maximum value of :math:`\sigma _{micro}` , and :math:`\eta` is an adjustable parameter. Default values in the model are :math:`\sigma _{\max } =0.4` and :math:`\eta =-3`. @@ -292,12 +292,12 @@ reservoir .. math:: :label: 7.70 - qout,h2osfc=kh2osfcf_{connected} (Wsfc-Wc)\frac{1}{\Delta t} + q_{out,h2osfc}=k_{h2osfc} \ f_{connected} \ (Wsfc-Wc)\frac{1}{\Delta t} -where :math:`qout,h2osfc` is the surface water runoff, :math:`kh2osfc` +where :math:`q_{out,h2osfc}` is the surface water runoff, :math:`k_{h2osfc}` is a constant, :math:`Wc` is the amount of surface water present when -:math:`f_{h2osfc} =f_{c}` , and :math:`\Delta t` is the model time step. -The linear storage coefficent :math:`kh2osfc=\sin \left(\beta \right)` +:math:`f_{h2osfc} = f_{c}` , and :math:`\Delta t` is the model time step. +The linear storage coefficent :math:`k_{h2osfc} = \sin \left(\beta \right)` is a function of grid cell mean topographic slope where :math:`\beta` is the slope in radians. @@ -312,7 +312,7 @@ removed, .. math:: :label: 7.71 - qin,surface=(1-f_{sat} )q_{liq,\, 0} + q_{in,surface} = (1-f_{sat}) \ q_{liq,\, 0} is divided into inputs to surface water (:math:`q_{in,\, h2osfc}` ) and the soil :math:`q_{in,soil}` . If :math:`q_{in,soil}` exceeds the @@ -322,10 +322,11 @@ s\ :sup:`-1`), .. math:: :label: 7.72 - q_{infl,\, \max } =(1-fsat){\rm \Theta }iceksat + q_{infl,\, \max } =(1-f_{sat}) \ \Theta_{ice} k_{sat} -where :math:`{\rm \Theta }ice` is an ice impedance factor (section -:numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff is generated +where :math:`\Theta_{ice}` is an ice impedance factor (section +:numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff +is generated .. math:: :label: 7.73 @@ -338,28 +339,28 @@ After evaporative losses have been removed, these moisture fluxes are .. math:: :label: 7.74 - q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} +q_{infl,excess} -q_{evap,h2osfc} + q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} + q_{infl,excess} - q_{evap,h2osfc} and .. math:: :label: 7.75 - qin,soil=(1-f_{h2osfc} )q_{in,surface} -q_{\inf l,excess} -(1-f_{sno} -f_{h2osfc} )qevap,soil. + q_{in,soil} = (1-f_{h2osfc}) q_{in,surface} - q_{\inf l,excess} - (1 - f_{sno} - f_{h2osfc} ) q_{evap,soil}. The balance of surface water is then calculated as .. math:: :label: 7.76 - \Delta W_{sfc} =\left(qin,h2osfc-qout,h2osfc-qdrain,h2osfc\right)\Delta t. + \Delta W_{sfc} =\left(q_{in,h2osfc} - q_{out,h2osfc} - q_{drain,h2osfc} \right) \ \Delta t. Bottom drainage from the surface water store .. math:: :label: 7.77 - qdrain,h2osfc=\min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) + q_{drain,h2osfc} = \min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) is then added to :math:`q_{in,soil}` giving the total infiltration into the surface soil layer @@ -367,7 +368,7 @@ into the surface soil layer .. math:: :label: 7.78 - q_{infl} =q_{in,soil} +q_{drain,h2osfc} + q_{infl} = q_{in,soil} + q_{drain,h2osfc} Infiltration :math:`q_{infl}` and explicit surface runoff :math:`q_{over}` are not allowed for glaciers. @@ -469,27 +470,34 @@ and organic properties of the soil (:ref:`Lawrence and Slater 2008 `). The hydraulic conductivity is defined at the depth of the interface of -two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) and is a function -of the saturated hydraulic conductivity +two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) +and is a function of the saturated hydraulic conductivity :math:`k_{sat} \left[z_{h,\, i} \right]`, the liquid volumetric soil -moisture of the two layers :math:`\theta _{i}` and -:math:`\theta _{i+1}` and an ice impedance factor -:math:`\Theta _{ice}` +moisture of the two layers :math:`\theta_{i}` and +:math:`\theta_{i+1}` and an ice impedance factor +:math:`\Theta_{ice}` .. math:: :label: 7.85 k\left[z_{h,\, i} \right] = \left\{\begin{array}{lr} - \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ - \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} + \Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)}{0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ + \Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} \end{array}\right\}. The ice impedance factor is a function of ice content, and is meant to quantify the increased tortuosity of the water flow when part of the pore space is filled with ice. :ref:`Swenson et al. (2012) ` -used a power law form :math:`\Theta _{ice} = 10^{-\Omega F_{ice} }` where -:math:`\Omega = 6`\ and +used a power law form + +.. math:: + :label: 7.86 + + \Theta _{ice} = 10^{-\Omega F_{ice}} + +where +:math:`\Omega = 6` and :math:`F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }` is the ice-filled fraction of the pore space. @@ -512,7 +520,7 @@ porosity of organic matter and the porosity of the mineral soil .. math:: :label: 7.91 - \theta _{sai,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . + \theta _{sat,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . The exponent :math:`B_{i}` is @@ -566,10 +574,10 @@ fractions using a result from percolation theory (:ref:`Stauffer and Aharony 1994 `, :ref:`Berkowitz and Balberg 1992 `). Assuming that the organic and mineral fractions are randomly distributed throughout a soil layer, percolation theory predicts that above a threshold value -:math:`f_{om} =f_{threshold}` , connected flow pathways consisting of +:math:`f_{om} =f_{threshold}`, connected flow pathways consisting of organic material only exist and span the soil space. Flow through these pathways interacts only with organic material, and thus can be described -by :math:`k_{sat,\, om}` . This fraction of the grid cell is given by +by :math:`k_{sat,\, om}`. This fraction of the grid cell is given by .. math:: :label: 7.97 @@ -714,7 +722,7 @@ and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total soil column for the :math:`j^{th}` PFT (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). -The soil water fluxes in equation , which are a function of +The soil water fluxes in :eq:`7.103`, which are a function of :math:`\theta _{liq,\, i}` and :math:`\theta _{liq,\, i+1}` because of their dependence on hydraulic conductivity and soil matric potential, can be linearized about :math:`\theta` using a Taylor series expansion @@ -730,8 +738,8 @@ as q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } \Delta \theta _{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} . -Substitution of these expressions for :math:`q_{i}^{n+1}` and -:math:`q_{i-1}^{n+1}` into equation results in a general tridiagonal +Substitution of these expressions for :math:`q_{i}^{n+1}` and +:math:`q_{i-1}^{n+1}` into equation :eq:`7.103` results in a general tridiagonal equation set of the form .. math:: @@ -765,40 +773,40 @@ The tridiagonal equation set is solved over :math:`i=1,\ldots ,N_{levsoi}`. The finite-difference forms of the fluxes and partial derivatives in -equations - can be obtained from equation as +equations :eq:`7.111` - :eq:`7.114` can be obtained from :eq:`7.80` as .. math:: :label: 7.115 - q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: :label: 7.116 - q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] + q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right] .. math:: :label: 7.117 - \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right] .. math:: :label: 7.118 - \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right] .. math:: :label: 7.119 - \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] + \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right] .. math:: :label: 7.120 - \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right]. + \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]. The derivatives of the soil matric potential at the node depth are -derived from equation +derived from :eq:`7.94` .. math:: :label: 7.121 @@ -819,17 +827,31 @@ with the constraint :math:`0.01\, \theta _{sat,\, i} \le \theta _{\, i} \le \theta _{sat,\, i}` . The derivatives of the hydraulic conductivity at the layer interface are -derived from equation +derived from :eq:`7.85` + +.. check eqn .. math:: :label: 7.124 - \begin{array}{l} {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } =\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } =\left(1-\frac{f_{frz,\, i-1} +f_{frz,\, i} }{2} \right)\left(2B_{i-1} +3\right)k_{sat} \left[z_{h,\, i-1} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right]^{2B_{i-1} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right)} \end{array} + \begin{array}{l} + {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } + = \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } + = \left(2B_{i-1} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i-1} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i-1} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array} + +where :math:`\overline{\theta}_{liq} = 0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)`, +:math:`\overline{\theta}_{sat} = 0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)`, +and :math:`\overline{\Theta}_{ice} = \Theta_{ice}(\overline{\theta}_{ice})` :eq:`7.86` + +and .. math:: :label: 7.125 - \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } =\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } =\left(1-\frac{f_{frz,\, i} +f_{frz,\, i+1} }{2} \right)\left(2B_{i} +3\right)k_{sat} \left[z_{h,\, i} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right)} \end{array}. + \begin{array}{l} + {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } + = \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } + = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}. Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' From 4a9c173c03674dce7078118106d573d979df5961 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 2 Jun 2017 09:42:44 -0600 Subject: [PATCH 039/255] correct reference in crop --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 55 ++++++++++--------- .../CLM50_Tech_Note_Introduction.rst | 2 +- 2 files changed, 29 insertions(+), 28 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 2961569d3a..f5acbeca61 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -103,8 +103,8 @@ described by Levis et al. (:ref:`2016 `). A parameterization for winter cereals is developed but is not included in CLM5.0 due to the inability to distinguish between winter and summer cereals in the LUMIP dataset (insert citation). -CLM’s default list of plant functional types (pfts) includes an -unmanaged crop (Table 2.1) treated as a second C3 grass, as well as several +CLM’s default list of plant functional types (pfts) includes an unmanaged crop +(:numref:`Table Plant functional types`) treated as a second C3 grass, as well as several additional crop types that do not have associated parameters. The unmanaged crop has grid cell coverage assigned from satellite data, as do all natural pfts when CLM’s crop model is not active. [include remapping text here]. @@ -135,7 +135,7 @@ Corn and temperate cereals must meet the following requirements between April 1\ :sup:`st` and June 14\ :sup:`th` for planting in the northern hemisphere (NH): .. math:: - :label: ZEqnNum568682 + :label: 25.1 \begin{array}{l} {T_{10d} >T_{p} } \\ @@ -174,7 +174,7 @@ for the crop to reach vegetative and physiological maturity, :math:`{GDD}_{mat}`, according to the following AgroIBIS rules: .. math:: - :label: 25.2) + :label: 25.2 \begin{array}{l} {GDD_{{\rm mat}}^{{\rm corn}} =0.85GDD_{{\rm 8}} {\rm \; \; \; and\; \; \; 950}30} \end{array}\right\} .. math:: - :label: 25.13) + :label: 25.13 fxg=\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad \qquad {\rm for\; }GDD_{T_{2m} } \le 0.15} \\ {6.67\times GDD_{T_{2m} } -1\qquad \qquad \qquad {\rm for\; }0.150.75} \end{array}\right\} @@ -736,17 +737,17 @@ mobilized depends on the C:N ratio of the plant tissue, and is calculated as .. math:: - :label: 25.14) + :label: 25.14 leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } .. math:: - :label: 25.15) + :label: 25.15 stemn\_ to\_ retransn=\frac{c_{stem} }{CN_{stem} } -\frac{c_{stem} }{CN_{stem}^{f} } .. math:: - :label: 25.16) + :label: 25.16 frootn\_ to\_ retransn=\frac{c_{froot} }{CN_{froot} } -\frac{c_{froot} }{CN_{froot}^{f} } diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 29892825d8..027d92e9e2 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -136,7 +136,7 @@ Jinyun Tang, Zong-Liang Yang** - :numref:`Figure Water flux schematic` Schematic diagram of numerical scheme used to solve for soil water fluxes. -- :numref:`three layer snow pack` Example of three layer snow pack (snl=-3). +- :numref:`Figure three layer snow pack` Example of three layer snow pack (snl=-3). - :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. From 779cab3a879ac6ef875b18649d6dbd6b60543c50 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 2 Jun 2017 11:11:03 -0600 Subject: [PATCH 040/255] add new snow density equations --- .../References/CLM50_Tech_Note_References.rst | 7 +++++ .../CLM50_Tech_Note_Snow_Hydrology.rst | 30 +++++++++++++++---- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index dfb4b81d9c..73691897a2 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1885,6 +1885,13 @@ van Veen, J.A., Ladd, J.N. and Frissel, M.J., 1984. Modelling C and N turnover through the microbial biomass in soil. Plant and Soil, 76: 257-274. +.. _vanKampenhoutetal2017: + +van Kampenhout, L., J.T.M. Lenaerts, W.H. Lipscomb, W.J. Sacks, D.M. +Lawrence, A.G. Slater, and M.R. van den Broeke, 2017. +Improving the representation of polar snow and firn in the +Community Earth System Model, submitted. + .. _VanVuurenetal2006: Van Vuuren, D.P., Lucas, P.S., and Hilderink, H.B.M., 2006. Downscaling diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index 5f87ec2f1a..a97e161526 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -141,21 +141,39 @@ where \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg -m\ :sup:`-3`) (:ref:`Anderson (1976) `) +m\ :sup:`-3`) (:ref:`van Kampenhout et al. (2017) `, +:ref:`Anderson (1976) `) .. math:: :label: 8.21 - \rho _{sno} = + \rho_{sno} = \left\{\begin{array}{lr} 50 + 1.7 \left(17\right)^{1.5} & \qquad T_{atm} >T_{f} +2 \ \\ 50+1.7 \left(T_{atm} -T_{f} + 15\right)^{1.5} & \qquad T_{f} - 15 < T_{atm} \le T_{f} + 2 \ \\ - 50 &\qquad T_{atm} \le T_{f} - 15 + -3.833 \ \left( T_{atm} -T_{f} \right) - 0.0333 \ \left( T_{atm} -T_{f} \right)^{2} + &\qquad T_{atm} \le T_{f} - 15 \end{array}\right\} -where :math:`T_{atm}` is the atmospheric temperature (K), and -:math:`T_{f}` is the freezing temperature of water (K) (Table 2.6). The -mass of snow :math:`W_{sno}` is +.. bifall(c) = -(50._r8/15._r8 + 0.0333_r8*15_r8)*(forc_t(c)-tfrz) - 0.0333_r8*(forc_t(c)-tfrz)**2 + +where :math:`T_{atm}` is the atmospheric temperature (K), and :math:`T_{f}` is +the freezing temperature of water (K) (:numref:`Table Physical Constants`). When +wind speed :math:`W_{atm}` is greater than 0.1 m :sub:`-1`, snow density +increases due to wind-driven compaction according to +:ref:`(van Kampenhout et al. 2017) ` + +.. math:: + :label: 8.21b + + \Delta \rho_{sno} = 266.861 \left(\frac{1 + tanh(\frac{W_{atm}}{5})}{2}\right)^{8.8} + +where :math:`\Delta \rho_{sno}` (kg m\ :sup:`-3`) is the increase in snow +density relative to :eq:`8.21`. + +.. bifall(c) = bifall(c) + (266.861_r8 * ((1._r8 + TANH(forc_wind(g)/5.0_r8))/2._r8)**8.8_r8) + +The mass of snow :math:`W_{sno}` is .. math:: :label: 8.22 From 84cedaf9968119bd9b4c0a9e47b4729a8a67fa35 Mon Sep 17 00:00:00 2001 From: Justin Perket Date: Fri, 2 Jun 2017 16:01:29 -0600 Subject: [PATCH 041/255] Added descriptions of canopy snow hydrology and albedo. And fixed a couple typos --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 2 +- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 520 ++++++++++-------- .../References/CLM50_Tech_Note_References.rst | 15 +- .../CLM50_Tech_Note_Surface_Albedos.rst | 23 +- 4 files changed, 315 insertions(+), 245 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index df44ae6fe1..e8b78225dc 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -906,7 +906,7 @@ of the components in the coupled modeling system, are presented in "Molecular weight of water vapor", :math:`MW_{wv}`, 18.016, kg kmol :sup:`-1` "Water vapor gas constant", :math:`R_{wv}`, :math:`{R_{gas} \mathord{\left/ {\vphantom {R_{gas} MW_{wv} }} \right. \kern-\nulldelimiterspace} MW_{wv} }`, J K :sup:`-1` kg :sup:`-1` "Von Karman constant", :math:`k`, 0.4, "\-" - "Freezing temperature of fresh water", :math:`T_{f}`, 273.5, K + "Freezing temperature of fresh water", :math:`T_{f}`, 273.15, K "Density of liquid water", :math:`\rho _{liq}`, 1000, kg m :sup:`-3` "Density of ice", :math:`\rho _{ice}`, 917, kg m :sup:`-3` "Specific heat capacity of dry air", :math:`C_{p}`, 1.00464 :math:`\times 10^{3}`, J kg :sup:`-1` K :sup:`-1` diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 4e203f8586..e86d47e701 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -7,8 +7,9 @@ The model parameterizes interception, throughfall, canopy drip, snow accumulation and melt, water transfer between snow layers, infiltration, evaporation, surface runoff, sub-surface drainage, redistribution within the soil column, and groundwater discharge and recharge to simulate -changes in canopy water :math:`\Delta W_{can}` , surface water -:math:`\Delta W_{sfc}` , snow water :math:`\Delta W_{sno}` , soil water +changes in canopy water :math:`\Delta W_{can,\,liq}` , canopy snow water +:math:`\Delta W_{can,\,sno}` surface water :math:`\Delta W_{sfc}` , +snow water :math:`\Delta W_{sno}` , soil water :math:`\Delta w_{liq,\, i}` , and soil ice :math:`\Delta w_{ice,\, i}` , and water in the unconfined aquifer :math:`\Delta W_{a}` (all in kg m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Figure Hydrologic processes`). @@ -16,9 +17,9 @@ m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Figure Hydrologic processes`). The total water balance of the system is .. math:: - :label: 7.1 + :label: 7.1) - \begin{array}{l} {\Delta W_{can} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} + \begin{array}{l} {\Delta W_{can,\,liq} +\Delta W_{can,\,sno} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} where :math:`q_{rain}` is the liquid part of precipitation, :math:`q_{sno}` is the solid part of precipitation, :math:`E_{v}` is @@ -31,8 +32,8 @@ from glaciers, wetlands, and lakes, and runoff from other surface types due to snow capping (section :numref:`Runoff from glaciers and snow-capped surfaces`) (all in kg m\ :sup:`-2` s\ :sup:`-1`), :math:`N_{levsoi}` is the number of soil layers (note that hydrology calculations are only done over soil layers 1 to -:math:`N_{levsoi}` ; ground levels :math:`N_{levsoi} +1`\ to -:math:`N_{levgrnd}` are currently hydrologically inactive; :ref:`(Lawrence et +:math:`N_{levsoi}` ; ground levels :math:`N_{levsoi} +1` \ to +:math:`N_{levgrnd}` are currently hydrologically inactive; :ref:`(Lawrence et al. 2008) ` and :math:`\Delta t` is the time step (s). .. _Figure Hydrologic processes: @@ -46,85 +47,158 @@ al. 2008) ` and :math:`\Delta t` is the time step (s). Canopy Water ---------------- -Precipitation is either intercepted by the canopy, falls directly to the +Liquid precipitation is either intercepted by the canopy, falls directly to the snow/soil surface (throughfall), or drips off the vegetation (canopy -drip). Interception by vegetation :math:`q_{intr}` (kg -m\ :sup:`-2` s\ :sup:`-1`) does not distinguish between -liquid and solid phases +drip). Solid precipitation is treated similiar, with the addition of unloading of previously intercepted snow. +Interception by vegetation is divided between liquid and solid phases +:math:`q_{intr,\,liq}` and :math:`q_{intr,\,ice}` (kg m\ :sup:`-2` s\ :sup:`-1`) .. math:: - :label: 7.2 + :label: 7.2) - q_{intr} =\alpha \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + q_{intr,\,liq} =\alpha_{liq} \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} +.. math:: + :label: 7.3) + + q_{intr,\,ice} =\alpha_{sno} \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + + where :math:`L` and :math:`S` are the exposed leaf and stem area index, -respectively (section :numref:`Phenology and vegetation burial by snow`), -and :math:`\alpha =0.25` scales interception from point to grid cell -(:ref:`Lawrence et al. 2007 `). Throughfall -(kg m\ :sup:`-2` s\ :sup:`-1`), however, is divided into -liquid and solid phases reaching the ground (soil or snow surface) as +respectively (section 2.1.4), and the :math:`\alpha`\'s scale +the fractional area of a leaf that collects water (:ref:`Lawrence et al. 2007 `). +Values of :math:`\alpha_{liq} = 0.25` and :math:`\alpha_{sno} = 1` reflect the increased capacity one side of a leaf has for snow than liquid water. +Throughfall (kg m\ :sup:`-2` s\ :sup:`-1`) is also divided into +liquid and solid phases, reaching the ground (soil or snow surface) as .. math:: - :label: 7.3 + :label: 7.4) - q_{thru,\, liq} =q_{rain} \left[1-\alpha \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right] + q_{thru,\, liq} =q_{rain} \left[1-\alpha_{liq} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right] .. math:: - :label: 7.4 + :label: 7.5) - q_{thru,\, ice} =q_{sno} \left[1-\alpha \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right]. + q_{thru,\, ice} =q_{sno} \left[1-\alpha_{sno} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right]. -Similarly, the canopy drip is +Similarly, the liquid and solid canopy drip fluxes are .. math:: - :label: 7.5 + :label: 7.6) - q_{drip,\, liq} =\frac{W_{can}^{intr} -W_{can,\, \max } }{\Delta t} \frac{q_{rain} }{q_{rain} +q_{sno} } \ge 0 + q_{drip,\, liq} =\frac{W_{can,\,liq}^{intr} -W_{can,\,liq}^{max } }{\Delta t} \ge 0 .. math:: - :label: 7.6 + :label: 7.7) - q_{drip,\, ice} =\frac{W_{can}^{intr} -W_{can,\, \max } }{\Delta t} \frac{q_{sno} }{q_{rain} +q_{sno} } \ge 0 + q_{drip,\, ice} =\frac{W_{can,\,sno}^{intr} -W_{can,\,sno}^{max } }{\Delta t} \ge 0 where .. math:: - :label: 7.7 + :label: 7.8) + + W_{can,liq}^{intr} =W_{can,liq}^{n} +q_{intr} \Delta t\ge 0 + +and + +.. math:: + :label: 7.9) + + W_{can,sno}^{intr} =W_{can,sno}^{n} +q_{intr} \Delta t\ge 0 + + +are the the canopy liquid water and snow water equivalent after accounting for interception, +:math:`W_{can,\,liq}^{n}` and :math:`W_{can,\,sno}^{n}` are the canopy liquid and snow water +from the previous time step, and :math:`W_{can,\,liq}^{max }` and :math:`W_{can,\,snow}^{max }` +(kg m\ :sup:`-2` or mm of H\ :sub:`2`\ O) are the maximum amounts of liquid water and snow the canopy can hold. +They are defined by + +.. math:: + :label: 7.10) + + W_{can,\,liq}^{max } =p_{liq}\left(L+S\right) + +.. math:: + :label: 7.11) + + W_{can,\,sno}^{max } =p_{ice}\left(L+S\right). + +The maximum storage of liquid water is :math:`p_{liq}=0.1` kg m\ :sup:`-2` (:ref:`Dickinson et al. +1993 `), and that of snow is :math:`p_{sno}=6`, consistent with reported +field measurements (:ref:`Pomeroy et al. 1998 `). + +Canopy snow unloading from wind speed :math:`u` and above-freezing temperatures are modeled from linear +fluxes and e-folding times similar to :ref:`Roesch et al. (2001) ` + +.. math:: + :label: 7.12) + + q_{unl,\, wind} =\frac{u W_{can,sno}}{1.56\times 10^5 \text{ m}} + +.. math:: + :label: 7.13) + + q_{unl,\, temp} =\frac{W_{can,sno}(T-270 \textrm{ K})}{1.87\times 10^5 \text{ K s}} > 0 + +.. math:: + :label: 7.14) + + q_{unl,\, tot} =\min \left( q_{unl,\, wind} +q_{unl,\, temp} ,W_{can,\, sno} \right) + + +The canopy liquid water and snow water equivalent are updated as + +.. math:: + :label: 7.15) - W_{can}^{intr} =W_{can}^{n} +q_{intr} \Delta t\ge 0 + W_{can,\, liq}^{n+1} =W_{can,liq}^{n} + q_{intr,\, liq} - q_{drip,\, liq} \Delta t - E_{v}^{liq} \Delta t \ge 0 -is the canopy water after accounting for interception, -:math:`W_{can}^{n}` is the canopy water from the previous time step, -and :math:`W_{can,\, \max }` (kg m\ :sup:`-2`) is the maximum -amount of water the canopy can hold +and .. math:: - :label: 7.8 + :label: 7.16) + + W_{can,\, sno}^{n+1} =W_{can,sno}^{n} + q_{intr,\, ice} - \left(q_{drip,\, ice}+q_{unl,\, tot} \right)\Delta t + - E_{v}^{ice} \Delta t \ge 0 + +.. W_{can}^{n+1} =W_{can}^{n} +q_{intr} \Delta t-\left(q_{drip,\, liq} +q_{drip,\, ice} \right)\Delta t-E_{v}^{w} \Delta t\ge 0. + +where :math:`E_{v}^{liq}` and :math:`E_{v}^{ice}` are partitioned from the stem and leaf +surface evaporation :math:`E_{v}^{w}` (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) based on the vegetation temperature :math:`T_{v}` (K) (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) and its relation to the freezing temperature of water :math:`T_{f}` (K) (:numref:`Table Physical Constants`) - W_{can,\, \max } =p\left(L+S\right). +.. math:: + :label: 7.17) -The maximum storage of solid water is assumed to be the same as that of -liquid water, :math:`p=0.1` kg m\ :sup:`-2` (:ref:`Dickinson et al. -1993 `). The canopy water is updated as + E_{v}^{liq} &= \begin{cases} + E_{v}^{w} & T_v > T_{f} \\ + 0 & T_v \le T_f + \end{cases} .. math:: - :label: 7.9 + :label: 7.18) + + E_{v}^{ice} &= \begin{cases} + 0 & T_v > T_f \\ + E_{v}^{w} & T_v \le T_f + \end{cases} . - W_{can}^{n+1} =W_{can}^{n} +q_{intr} \Delta t-\left(q_{drip,\, liq} +q_{drip,\, ice} \right)\Delta t-E_{v}^{w} \Delta t\ge 0. +.. \begin{array}{lr} +.. E_{v}^{liq} = E_{v}^{w} \qquad T > 273 \text{K} \\ +.. E_{v}^{ice} = E_{v}^{w} \qquad T \le 273 \text{K} +.. \end{array} -where :math:`E_{v}^{w}` is the flux of water vapor from stem and leaf -surfaces (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). The total rate of liquid and solid precipitation -reaching the ground is then +The total rate of liquid and solid precipitation reaching the ground is then .. math:: - :label: 7.10 + :label: ZEqnNum946822 q_{grnd,liq} =q_{thru,\, liq} +q_{drip,\, liq} .. math:: - :label: 7.11 + :label: ZEqnNum339590 - q_{grnd,ice} =q_{thru,\, ice} +q_{drip,\, ice} . + q_{grnd,ice} =q_{thru,\, ice} +q_{drip,\, ice} +q_{unl,\, tot} . Solid precipitation reaching the soil or snow surface, :math:`q_{grnd,\, ice} \Delta t`, is added immediately to the snow pack @@ -135,22 +209,22 @@ and snow/soil temperatures (Chapter :numref:`rst_Soil and Snow Temperatures`) have been determined. The wetted fraction of the canopy (stems plus leaves), which is required -for the surface albedo (section :numref:`Canopy Radiative Transfer`) and surface flux (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) -calculations is (:ref:`Dickinson et al.1993 `) +for surface flux (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) +calculations, is (:ref:`Dickinson et al.1993 `) .. math:: - :label: 7.12 + :label: 7.21) f_{wet} = \left\{\begin{array}{lr} - \left[\frac{W_{can} }{p\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \le 1 & \qquad L+S > 0 \\ + \left[\frac{W_{can} }{p_{liq}\left(L+S\right)} \right]^{{2\mathord{\left/ {\vphantom {2 3}} \right. \kern-\nulldelimiterspace} 3} } \le 1 & \qquad L+S > 0 \\ 0 &\qquad L+S = 0 \end{array}\right\} while the fraction of the canopy that is dry and transpiring is .. math:: - :label: 7.13 + :label: 7.22) f_{dry} = \left\{\begin{array}{lr} @@ -158,6 +232,19 @@ while the fraction of the canopy that is dry and transpiring is 0 &\qquad L+S = 0 \end{array}\right\}. +Similarly, the snow-covered fraction of the canopy is used for surface alebdo when intercepted snow is present (Chapter :numref:`rst_Surface Albedos`) + + +.. math:: + :label: 7.23) + + f_{can,\, sno} = + \left\{\begin{array}{lr} + \left[\frac{W_{can,\, sno} }{p_{sno}\left(L+S\right)} \right]^{{3\mathord{\left/ {\vphantom {3 20}} \right. \kern-\nulldelimiterspace} 20} } \le 1 & \qquad L+S > 0 \\ + 0 &\qquad L+S = 0 + \end{array}\right\}. + + .. _Surface Runoff, Surface Water Storage, and Infiltration: Surface Runoff, Surface Water Storage, and Infiltration @@ -184,21 +271,21 @@ portion of a grid cell contributes to surface runoff, :math:`q_{over}` , by the saturation excess mechanism (Dunne runoff) .. math:: - :label: 7.64 + :label: ZEqnNum549608 - q_{over} =f_{sat} \ q_{liq,\, 0} + q_{over} =f_{sat} q_{liq,\, 0} The fractional saturated area is a function of soil moisture .. math:: - :label: 7.65 + :label: 7.65) - f_{sat} = f_{\max } \ \exp \left(-0.5 f_{over} z_{\nabla } \right) + f_{sat} =f_{\max } \exp \left(-0.5f_{over} z_{\nabla } \right) -where :math:`f_{\max }` is the potential or maximum value of -:math:`f_{sat}`, :math:`f_{over}` is a decay factor (m\ :sup:`-1`), and -:math:`z_{\nabla}` is the water table depth (m) (section -:numref:`Lateral Sub-surface Runoff`). The maximum saturated fraction, :math:`f_{\max }` , +where :math:`f_{\max }` is the potential or maximum value of +:math:`f_{sat}` , :math:`f_{over}` is a decay factor +(m\ :sup:`-1`), and :math:`z_{\nabla}` is the water table depth +(m) (section 7.6). The maximum saturated fraction, :math:`f_{\max }` , is defined as the value of the discrete cumulative distribution function (CDF) of the topographic index when the grid cell mean water table depth is zero. Thus, :math:`f_{\max }` is the percent of pixels in a grid @@ -243,17 +330,17 @@ height (relative to the grid cell mean elevation) of the surface water, :math:`d`, by .. math:: - :label: 7.66 + :label: ZEqnNum277892 W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)+\frac{\sigma _{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma _{micro} ^{2} } } where :math:`erf` is the error function. For a given value of -:math:`W_{sfc}`, :eq:`7.66` can be solved for :math:`d` using the +:math:`W_{sfc}` , equation can be solved for :math:`d` using the Newton-Raphson method. Once :math:`d` is known, one can determine the fraction of the area that is inundated as .. math:: - :label: 7.67 + :label: 7.67) f_{h2osfc} =\frac{1}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right) @@ -261,13 +348,13 @@ No global datasets exist for microtopography, so the default parameterization is a simple function of slope .. math:: - :label: 7.68 + :label: 7.68) \sigma _{micro} =\left(\beta +\beta _{0} \right)^{\eta } where :math:`\beta` is the topographic slope, :math:`\beta _{0} =\left(\sigma _{\max } \right)^{\frac{1}{\eta } }` \ determines -the maximum value of :math:`\sigma _{micro}` , and :math:`\eta` is an +the maximum value of :math:`\sigma _{}` , and :math:`\eta` is an adjustable parameter. Default values in the model are :math:`\sigma _{\max } =0.4` and :math:`\eta =-3`. @@ -278,7 +365,7 @@ percolation theory can be used to quantify the fraction of the inundated portion of the grid cell that is interconnected .. math:: - :label: 7.69 + :label: 7.69) \begin{array}{lr} f_{connected} =\left(f_{h2osfc} -f_{c} \right)^{\mu } & \qquad f_{h2osfc} >f_{c} \\ f_{connected} =0 &\qquad f_{h2osfc} \le f_{c} \end{array} @@ -290,14 +377,14 @@ surpasses :math:`f_{c}` , the surface water store acts as a linear reservoir .. math:: - :label: 7.70 + :label: 7.70) - q_{out,h2osfc}=k_{h2osfc} \ f_{connected} \ (Wsfc-Wc)\frac{1}{\Delta t} + qout,h2osfc=kh2osfcf_{connected} (Wsfc-Wc)\frac{1}{\Delta t} -where :math:`q_{out,h2osfc}` is the surface water runoff, :math:`k_{h2osfc}` +where :math:`qout,h2osfc` is the surface water runoff, :math:`kh2osfc` is a constant, :math:`Wc` is the amount of surface water present when -:math:`f_{h2osfc} = f_{c}` , and :math:`\Delta t` is the model time step. -The linear storage coefficent :math:`k_{h2osfc} = \sin \left(\beta \right)` +:math:`f_{h2osfc} =f_{c}` , and :math:`\Delta t` is the model time step. +The linear storage coefficent :math:`kh2osfc=\sin \left(\beta \right)` is a function of grid cell mean topographic slope where :math:`\beta` is the slope in radians. @@ -310,9 +397,9 @@ The surface moisture flux remaining after surface runoff has been removed, .. math:: - :label: 7.71 + :label: 7.71) - q_{in,surface} = (1-f_{sat}) \ q_{liq,\, 0} + qin,surface=(1-f_{sat} )q_{liq,\, 0} is divided into inputs to surface water (:math:`q_{in,\, h2osfc}` ) and the soil :math:`q_{in,soil}` . If :math:`q_{in,soil}` exceeds the @@ -320,16 +407,15 @@ maximum soil infiltration capacity (kg m\ :sup:`-2` s\ :sup:`-1`), .. math:: - :label: 7.72 + :label: ZEqnNum569150 - q_{infl,\, \max } =(1-f_{sat}) \ \Theta_{ice} k_{sat} + q_{infl,\, \max } =(1-fsat){\rm \Theta }iceksat -where :math:`\Theta_{ice}` is an ice impedance factor (section -:numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff -is generated +where :math:`{\rm \Theta }ice` is an ice impedance factor (section +:numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff is generated .. math:: - :label: 7.73 + :label: 7.73) q_{infl,\, excess} =\max \left(q_{in,soil} -\left(1-f_{h2osfc} \right)q_{\inf l,\max } ,0\right) @@ -337,38 +423,38 @@ and transferred from :math:`q_{in,soil}` to :math:`q_{in,h2osfc}` . After evaporative losses have been removed, these moisture fluxes are .. math:: - :label: 7.74 + :label: 7.74) - q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} + q_{infl,excess} - q_{evap,h2osfc} + q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} +q_{infl,excess} -q_{evap,h2osfc} and .. math:: - :label: 7.75 + :label: 7.75) - q_{in,soil} = (1-f_{h2osfc}) q_{in,surface} - q_{\inf l,excess} - (1 - f_{sno} - f_{h2osfc} ) q_{evap,soil}. + qin,soil=(1-f_{h2osfc} )q_{in,surface} -q_{\inf l,excess} -(1-f_{sno} -f_{h2osfc} )qevap,soil. The balance of surface water is then calculated as .. math:: - :label: 7.76 + :label: 7.76) - \Delta W_{sfc} =\left(q_{in,h2osfc} - q_{out,h2osfc} - q_{drain,h2osfc} \right) \ \Delta t. + \Delta W_{sfc} =\left(qin,h2osfc-qout,h2osfc-qdrain,h2osfc\right)\Delta t. Bottom drainage from the surface water store .. math:: - :label: 7.77 + :label: 7.77) - q_{drain,h2osfc} = \min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) + qdrain,h2osfc=\min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) is then added to :math:`q_{in,soil}` giving the total infiltration into the surface soil layer .. math:: - :label: 7.78 + :label: 7.78) - q_{infl} = q_{in,soil} + q_{drain,h2osfc} + q_{infl} =q_{in,soil} +q_{drain,h2osfc} Infiltration :math:`q_{infl}` and explicit surface runoff :math:`q_{over}` are not allowed for glaciers. @@ -389,12 +475,12 @@ For one-dimensional vertical water flow in soils, the conservation of mass is stated as .. math:: - :label: 7.79 + :label: ZEqnNum790844 \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q where :math:`\theta` is the volumetric soil water content -(mm\ :sup:`3` of water mm\ :sup:`-3` of soil), :math:`t` is +(mm\ :sup:`3` of water / mm\ :sup:`-3` of soil), :math:`t` is time (s), :math:`z` is height above some datum in the soil column (mm) (positive upwards), :math:`q` is soil water flux (kg m\ :sup:`-2` s\ :sup:`-1` or mm s\ :sup:`-1`) (positive upwards), and @@ -411,7 +497,7 @@ The soil water flux :math:`q` in equation can be described by Darcy’s law :ref:`(Dingman 2002) ` .. math:: - :label: 7.80 + :label: 7.80) q=-k\frac{\partial \psi _{h} }{\partial z} @@ -420,7 +506,7 @@ and :math:`\psi _{h}` is the hydraulic potential (mm). The hydraulic potential is .. math:: - :label: 7.81 + :label: 7.81) \psi _{h} =\psi _{m} +\psi _{z} @@ -433,22 +519,22 @@ If the reference elevation is the soil surface, then becomes .. math:: - :label: 7.82 + :label: ZEqnNum186573 q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]. -Equation :eq:`7.82` can be further manipulated to yield +Equation :eq:`ZEqnNum186573` can be further manipulated to yield .. math:: - :label: 7.83 + :label: 7.83) q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]=-k\left(\frac{\partial \psi }{\partial z} +1\right)=-k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right). -Substitution of this equation into equation :eq:`7.79`, with :math:`Q=0`, yields +Substitution of this equation into equation :eq:`ZEqnNum790844`, with :math:`Q=0`, yields the Richards equation .. math:: - :label: 7.84 + :label: ZEqnNum670361 \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right)\right]. @@ -460,8 +546,7 @@ Hydraulic Properties The hydraulic conductivity :math:`k_{i}` (mm s\ :sup:`-1`) and the soil matric potential :math:`\psi _{i}` (mm) for layer :math:`i` vary with volumetric soil water :math:`\theta _{i}` and soil texture. -As with the soil thermal properties (section -:numref:`Soil And Snow Thermal Properties`) the hydraulic +As with the soil thermal properties (section :numref:`Soil And Snow Thermal Properties`) the hydraulic properties of the soil are assumed to be a weighted combination of the mineral properties, which are determined according to sand and clay contents based on work by :ref:`Clapp and Hornberger (1978) @@ -470,34 +555,27 @@ and organic properties of the soil (:ref:`Lawrence and Slater 2008 `). The hydraulic conductivity is defined at the depth of the interface of -two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) -and is a function of the saturated hydraulic conductivity +two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) and is a function +of the saturated hydraulic conductivity :math:`k_{sat} \left[z_{h,\, i} \right]`, the liquid volumetric soil -moisture of the two layers :math:`\theta_{i}` and -:math:`\theta_{i+1}` and an ice impedance factor -:math:`\Theta_{ice}` +moisture of the two layers :math:`\theta _{i}` and +:math:`\theta _{i+1}` and an ice impedance factor +:math:`\Theta _{ice}` .. math:: - :label: 7.85 + :label: ZEqnNum398074 k\left[z_{h,\, i} \right] = \left\{\begin{array}{lr} - \Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)}{0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ - \Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} + \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ + \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} \end{array}\right\}. The ice impedance factor is a function of ice content, and is meant to quantify the increased tortuosity of the water flow when part of the pore space is filled with ice. :ref:`Swenson et al. (2012) ` -used a power law form - -.. math:: - :label: 7.86 - - \Theta _{ice} = 10^{-\Omega F_{ice}} - -where -:math:`\Omega = 6` and +used a power law form :math:`\Theta _{ice} = 10^{-\Omega F_{ice} }` where +:math:`\Omega = 6`\ and :math:`F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }` is the ice-filled fraction of the pore space. @@ -507,7 +585,7 @@ computed as weighted averages of the properties of the mineral and organic components. The water content at saturation (i.e. porosity) is .. math:: - :label: 7.90 + :label: 7.90) \theta _{sat,i} =(1-f_{om,i} )\theta _{sat,\min ,i} +f_{om,i} \theta _{sat,om} @@ -518,21 +596,21 @@ porosity of organic matter and the porosity of the mineral soil :math:`\theta _{sat,\min ,i}` is .. math:: - :label: 7.91 + :label: 7.91) - \theta _{sat,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . + \theta _{sai,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . The exponent :math:`B_{i}` is .. math:: - :label: 7.92 + :label: 7.92) B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} where :math:`B_{om} = 2.7` \ (:ref:`Letts et al. 2000 `) and .. math:: - :label: 7.93 + :label: 7.93) B_{\min ,i} =2.91+0.159(\% clay)_{i} . @@ -540,14 +618,14 @@ The soil matric potential (mm) is defined at the node depth :math:`z_{i}` of each layer :math:`i` (:numref:`Figure Water flux schematic`) .. math:: - :label: 7.94 + :label: ZEqnNum316201 \psi _{i} =\psi _{sat,\, i} \left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta _{i} }{\theta _{sat,\, i} } \le 1 where the saturated soil matric potential (mm) is .. math:: - :label: 7.95 + :label: 7.95) \psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om} @@ -556,7 +634,7 @@ saturated organic matter matric potential and the saturated mineral soil matric potential :math:`\psi _{sat,\min ,i}` \ is .. math:: - :label: 7.96 + :label: 7.96) \psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } . @@ -574,13 +652,13 @@ fractions using a result from percolation theory (:ref:`Stauffer and Aharony 1994 `, :ref:`Berkowitz and Balberg 1992 `). Assuming that the organic and mineral fractions are randomly distributed throughout a soil layer, percolation theory predicts that above a threshold value -:math:`f_{om} =f_{threshold}`, connected flow pathways consisting of +:math:`f_{om} =f_{threshold}` , connected flow pathways consisting of organic material only exist and span the soil space. Flow through these pathways interacts only with organic material, and thus can be described -by :math:`k_{sat,\, om}`. This fraction of the grid cell is given by +by :math:`k_{sat,\, om}` . This fraction of the grid cell is given by .. math:: - :label: 7.97 + :label: 7.97) \begin{array}{lr} f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta _{perc} } f_{om} {\rm \; } & \qquad f_{om} \ge f_{threshold} \\ @@ -595,7 +673,7 @@ hydraulic conductivity is assumed to correspond to flow pathways that pass through the mineral and organic components in series .. math:: - :label: 7.98 + :label: 7.98) k_{sat,\, uncon} =f_{uncon} \left(\frac{\left(1-f_{om} \right)}{k_{sat,\, \min } } +\frac{\left(f_{om} -f_{perc} \right)}{k_{sat,\, om} } \right)^{-1} . @@ -603,7 +681,7 @@ where saturated hydraulic conductivity for mineral soil depends on soil texture (:ref:`Cosby et al. 1984 `) as .. math:: - :label: 7.99 + :label: 7.99) k_{sat,\, \min } \left[z_{h,\, i} \right]=0.0070556\times 10^{-0.884+0.0153\left(\% sand\right)_{i} } . @@ -611,7 +689,7 @@ The bulk soil layer saturated hydraulic conductivity is then computed as .. math:: - :label: 7.100 + :label: 7.100) k_{sat} \left[z_{h,\, i} \right]=f_{uncon,\, i} k_{sat,\, uncon} \left[z_{h,\, i} \right]+(1-f_{uncon,\, i} )k_{sat,\, om} \left[z_{h,\, i} \right]. @@ -620,11 +698,11 @@ as Numerical Solution ^^^^^^^^^^^^^^^^^^^^^^^^ -With reference to :numref:`Figure Water flux schematic`, the equation for -conservation of mass :eq:`7.79` can be integrated over each layer as +With reference to :numref:`Figure Water flux schematic`, the equation for conservation of mass +(equation :eq:`ZEqnNum790844`) can be integrated over each layer as .. math:: - :label: 7.101 + :label: 7.101) \int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }Q\, dz . @@ -633,7 +711,7 @@ as positive upward from the soil surface. This equation can be written as .. math:: - :label: 7.102 + :label: ZEqnNum225309 \Delta z_{i} \frac{\partial \theta _{liq,\, i} }{\partial t} =-q_{i-1} +q_{i} -e_{i} @@ -645,7 +723,7 @@ the layer (mm s\ :sup:`-1`). Taking the finite difference with time and evaluating the fluxes implicitly at time :math:`n+1` yields .. math:: - :label: 7.103 + :label: ZEqnNum181361 \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =-q_{i-1}^{n+1} +q_{i}^{n+1} -e_{i} @@ -660,7 +738,7 @@ function of the total transpiration :math:`E_{v}^{t}` (Chapter :numref:`rst_Mom the effective root fraction :math:`r_{e,\, i}` .. math:: - :label: 7.104 + :label: ZEqnNum357392 e_{i} =r_{e,\, i} E_{v}^{t} . @@ -686,7 +764,7 @@ soil column, the transpiration :math:`E_{v}^{t}` is a weighted sum of transpiration from all PFTs whose weighting depends on PFT area as .. math:: - :label: 7.105 + :label: 7.105) E_{v}^{t} =\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} @@ -699,7 +777,7 @@ quantity that is a weighted sum over all PFTs. The weighting depends on the per unit area transpiration of each PFT and its relative area as .. math:: - :label: 7.106 + :label: 7.106) r_{e,\, i} =\frac{\sum _{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} } @@ -707,65 +785,60 @@ where :math:`\left(r_{e,\, i} \right)_{j}` is the effective root fraction for the :math:`j^{th}` PFT .. math:: - :label: 7.107 + :label: 7.107) - \begin{array}{lr} - \left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } & \qquad \left(\beta _{t} \right)_{j} >0 \\ - \left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta _{t} \right)_{j} =0 - \end{array} + \begin{array}{l} {\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } \qquad \left(\beta _{t} \right)_{j} >0} \\ {\left(r_{e,\, i} \right)_{j} =0\qquad \left(\beta _{t} \right)_{j} =0} \end{array} and :math:`\left(r_{i} \right)_{j}` is the fraction of roots in layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), -:math:`\left(w_{i} \right)_{j}` is a soil dryness or plant wilting factor for -layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), -and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total -soil column for the :math:`j^{th}` PFT (Chapter -:numref:`rst_Stomatal Resistance and Photosynthesis`). +:math:`\left(w_{i} \right)_{j}` is a soil dryness or plant wilting factor +for layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total +soil column for the :math:`j^{th}` PFT (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). -The soil water fluxes in :eq:`7.103`, which are a function of +The soil water fluxes in equation , which are a function of :math:`\theta _{liq,\, i}` and :math:`\theta _{liq,\, i+1}` because of their dependence on hydraulic conductivity and soil matric potential, can be linearized about :math:`\theta` using a Taylor series expansion as .. math:: - :label: 7.108 + :label: 7.108) q_{i}^{n+1} =q_{i}^{n} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } \Delta \theta _{liq,\, i+1} .. math:: - :label: 7.109 + :label: 7.109) q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } \Delta \theta _{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} . -Substitution of these expressions for :math:`q_{i}^{n+1}` and -:math:`q_{i-1}^{n+1}` into equation :eq:`7.103` results in a general tridiagonal +Substitution of these expressions for :math:`q_{i}^{n+1}` and +:math:`q_{i-1}^{n+1}` into equation results in a general tridiagonal equation set of the form .. math:: - :label: 7.110 + :label: 7.110) r_{i} =a_{i} \Delta \theta _{liq,\, i-1} +b_{i} \Delta \theta _{liq,\, i} +c_{i} \Delta \theta _{liq,\, i+1} where .. math:: - :label: 7.111 + :label: ZEqnNum557934 a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: - :label: 7.112 + :label: 7.112) b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.113 + :label: 7.113) c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } .. math:: - :label: 7.114 + :label: ZEqnNum981892 r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . @@ -773,53 +846,53 @@ The tridiagonal equation set is solved over :math:`i=1,\ldots ,N_{levsoi}`. The finite-difference forms of the fluxes and partial derivatives in -equations :eq:`7.111` - :eq:`7.114` can be obtained from :eq:`7.80` as +equations - can be obtained from equation as .. math:: - :label: 7.115 + :label: 7.115) - q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} -z_{i-1} } \right] + q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.116 + :label: 7.116) - q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right] + q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] .. math:: - :label: 7.117 + :label: 7.117) - \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right] + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.118 + :label: 7.118) - \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right] + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.119 + :label: 7.119) - \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right] + \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] .. math:: - :label: 7.120 + :label: 7.120) - \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]. + \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right]. The derivatives of the soil matric potential at the node depth are -derived from :eq:`7.94` +derived from equation .. math:: - :label: 7.121 + :label: 7.121) \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta _{\, \, i-1} } .. math:: - :label: 7.122 + :label: 7.122) \frac{\partial \psi _{i} }{\partial \theta _{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta _{i} } .. math:: - :label: 7.123 + :label: 7.123) \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta _{\, i+1} } @@ -827,31 +900,17 @@ with the constraint :math:`0.01\, \theta _{sat,\, i} \le \theta _{\, i} \le \theta _{sat,\, i}` . The derivatives of the hydraulic conductivity at the layer interface are -derived from :eq:`7.85` - -.. check eqn +derived from equation .. math:: - :label: 7.124 - - \begin{array}{l} - {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } - = \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } - = \left(2B_{i-1} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i-1} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i-1} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array} - -where :math:`\overline{\theta}_{liq} = 0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)`, -:math:`\overline{\theta}_{sat} = 0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)`, -and :math:`\overline{\Theta}_{ice} = \Theta_{ice}(\overline{\theta}_{ice})` :eq:`7.86` + :label: 7.124) -and + \begin{array}{l} {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } =\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } =\left(1-\frac{f_{frz,\, i-1} +f_{frz,\, i} }{2} \right)\left(2B_{i-1} +3\right)k_{sat} \left[z_{h,\, i-1} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right]^{2B_{i-1} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right)} \end{array} .. math:: - :label: 7.125 + :label: 7.125) - \begin{array}{l} - {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } - = \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } - = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}. + \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } =\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } =\left(1-\frac{f_{frz,\, i} +f_{frz,\, i+1} }{2} \right)\left(2B_{i} +3\right)k_{sat} \left[z_{h,\, i} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right)} \end{array}. Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' @@ -862,7 +921,7 @@ infiltration rate (section :numref:`Surface Runoff`), is .. math:: - :label: 7.135 + :label: 7.135) \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =q_{infl}^{n+1} +q_{i}^{n+1} -e_{i} . @@ -870,22 +929,22 @@ After grouping like terms, the coefficients of the tridiagonal set of equations for :math:`i=1` are .. math:: - :label: 7.136 + :label: 7.136) a_{i} =0 .. math:: - :label: 7.137 + :label: 7.137) b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.138 + :label: 7.138) c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } .. math:: - :label: 7.139 + :label: 7.139) r_{i} =q_{infl}^{n+1} -q_{i}^{n} +e_{i} . @@ -896,22 +955,22 @@ The coefficients of the tridiagonal set of equations for :math:`i=2,\ldots ,N_{levsoi} -1` are .. math:: - :label: 7.140 + :label: 7.140) a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: - :label: 7.141 + :label: 7.141) b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.142 + :label: 7.142) c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } .. math:: - :label: 7.143 + :label: 7.143) r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . @@ -924,22 +983,22 @@ and the coefficients of the tridiagonal set of equations for :math:`i=N_{levsoi}` are .. math:: - :label: 7.148 + :label: 7.148) a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } .. math:: - :label: 7.149 + :label: 7.149) b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.150 + :label: 7.150) c_{i} =0 .. math:: - :label: 7.151 + :label: 7.151) r_{i} =q_{i-1}^{n} +e_{i} . @@ -950,7 +1009,7 @@ An initial solution is found by setting :math:`\Delta t` equal to the model time step. An estimate of the error is calculated from .. math:: - :label: 7.152 + :label: 7.152) \epsilon = max \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] @@ -966,14 +1025,14 @@ Upon solution of the tridiagonal equation set, the liquid water contents are updated as follows .. math:: - :label: 7.164 + :label: 7.164) w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta _{liq,\, i} \Delta z_{i} \qquad i=1,\ldots ,N_{levsoi} . The volumetric water content is .. math:: - :label: 7.165 + :label: 7.165) \theta _{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } . @@ -983,8 +1042,7 @@ Frozen Soils and Perched Water Table ---------------------------------------- When soils freeze, the power-law form of the ice impedance factor -(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic -conductivity of the +(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic conductivity of the soil, leading to nearly impermeable soil layers. When unfrozen soil layers are present above relatively ice-rich frozen layers, the possibility exists for perched saturated zones. Lateral drainage from @@ -992,7 +1050,7 @@ perched saturated regions is parameterized as a function of the thickness of the saturated zone .. math:: - :label: 7.166 + :label: 7.166) q_{drai,perch} =k_{drai,\, perch} \left(z_{frost} -z_{\nabla ,perch} \right) @@ -1000,7 +1058,7 @@ where :math:`k_{drai,\, perch}` depends on topographic slope and soil hydraulic conductivity, .. math:: - :label: 7.167 + :label: 7.167) k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta _{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right) @@ -1025,7 +1083,7 @@ Lateral sub-surface runoff occurs when saturated soil moisture conditions exist within the soil column. Sub-surface runoff is .. math:: - :label: 7.168 + :label: 7.168) q_{subsurface} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) \Delta z_{sat}^{N_{baseflow}} \ , @@ -1037,14 +1095,13 @@ is the thickness of the saturated portion of the soil column. The saturated thickness is .. math:: - :label: 7.1681 + :label: 7.1681) \Delta z_{sat} = z_{bedrock} - z_{\nabla}, where the water table :math:`z_{\nabla}` is determined by finding the -first soil layer above the bedrock depth (section :numref:`Depth to Bedrock`) -in which the volumetric water content drops below a specified threshold. -The default threshold is set to 0.9. +first soil layer above the bedrock depth (section ) in which the volumetric water +content drops below a specified threshold. The default threshold is set to 0.9. The specific yield, :math:`S_{y}` , which depends on the soil properties and the water table location, is derived by taking the @@ -1052,13 +1109,13 @@ difference between two equilibrium soil moisture profiles whose water tables differ by an infinitesimal amount .. math:: - :label: 7.174 + :label: 7.174) S_{y} =\theta _{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right) where B is the Clapp-Hornberger exponent. Because :math:`S_{y}` is a function of the soil properties, it results in water table dynamics that -are consistent with the soil water fluxes described in section :numref:`Soil Water`. +are consistent with the soil water fluxes described in section 7.4. After the above calculations, two numerical adjustments are implemented to keep the liquid water content of each soil layer @@ -1083,22 +1140,22 @@ those layers subject to the constraint found, then the water is removed from :math:`W_{t}` and :math:`q_{drai}` . -The soil surface layer liquid water and ice contents are then updated for -dew :math:`q_{sdew}`, frost :math:`q_{frost}`, or sublimation :math:`q_{subl}` -(section :numref:`Update of Ground Sensible and Latent Heat Fluxes`) as +The soil surface layer liquid water and ice contents are then updated +for dew :math:`q_{sdew}` , frost :math:`q_{frost}` , or sublimation +:math:`q_{subl}` (section 5.4) as .. math:: - :label: 7.175 + :label: 7.175) w_{liq,\, 1}^{n+1} =w_{liq,\, 1}^{n} +q_{sdew} \Delta t .. math:: - :label: 7.176 + :label: 7.176) w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} +q_{frost} \Delta t .. math:: - :label: 7.177 + :label: 7.177) w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} -q_{subl} \Delta t. @@ -1116,12 +1173,12 @@ and dew in solid or liquid form, is separated into solid :math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms .. math:: - :label: 7.178 + :label: 7.178) q_{snwcp,ice} =q_{grnd,ice} +q_{frost} .. math:: - :label: 7.179 + :label: 7.179) q_{snwcp,liq} =q_{grnd,liq} +q_{dew} @@ -1137,7 +1194,7 @@ For glacier surfaces the runoff term :math:`q_{rgwl}` is calculated from the residual of the water balance .. math:: - :label: 7.180 + :label: 7.180) q_{rgwl} =q_{grnd,ice} +q_{grnd,liq} -E_{g} -E_{v} -\frac{\left(W_{b}^{n+1} -W_{b}^{n} \right)}{\Delta t} -q_{snwcp,ice} @@ -1145,7 +1202,7 @@ where :math:`W_{b}^{n}` and :math:`W_{b}^{n+1}` are the water balances at the beginning and ending of the time step defined as .. math:: - :label: 7.181 + :label: 7.181) W_{b} =W_{can} +W_{sno} +\sum _{i=1}^{N}\left(w_{ice,i} +w_{liq,i} \right) . @@ -1153,6 +1210,5 @@ Currently, glaciers are non-vegetated and :math:`E_{v} =W_{can} =0`. The contribution of lake runoff to :math:`q_{rgwl}` is described in section :numref:`Precipitation, Evaporation, and Runoff Lake`. The runoff term :math:`q_{rgwl}` may be negative for glaciers and lakes, which reduces -the total amount of runoff available to the river routing model -(Chapter :numref:`rst_River Transport Model (RTM)`). +the total amount of runoff available to the river routing model (Chapter :numref:`rst_River Transport Model (RTM)`). diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index dfb4b81d9c..6d989d2b1c 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1225,8 +1225,6 @@ Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. -.. _NiuYang2006: - Niu, G.-Y., and Yang, Z.-L. 2006. Effects of frozen soil on snowmelt runoff and soil water storage at a continental scale. J. Hydrometeor. 7:937-952. @@ -1410,6 +1408,12 @@ Pollmer, W.G., Eberhard, D., Klein, D., and Dhillon, B.S. 1979. Genetic control of nitrogen uptake and translocation in maize. Crop Sci. 19:82-86. +.. _Pomeroyetal1998: + +Pomeroy, J. W., D. M. Gray, K. R. Shook, B. Toth, R. L. H. Essery, +A. Pietroniro, and N. Hedstrom. 1998. An evaluation of snow accumulation +and ablation processes for land surface modelling. Hydrol. Process. 12:2339–2367. + .. _Portmannetal2010: Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global @@ -1489,6 +1493,11 @@ Riley, W.J. et al. 2011b. CLM4Me, a Methane Biogeochemistry Model Integrated in CESM, Land and Biogeochemistry Model Working Group Meeting, Boulder, CO. +.. _Roeschetal2001: + +Roesch, A., M. Wild, H. Gilgen, and A. Ohmura. 2001. A new snow cover +fraction parametrization for the ECHAM4 GCM, Clim. Dyn., 17:933–946. + .. _Ryan1991: Ryan, M. G. 1991. A simple method for estimating gross carbon budgets @@ -1557,7 +1566,7 @@ Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity in soils and cultures to water stress. Applied and Environmental Microbiology 62:3203-3209. -.. _Segers1998: +.. _Segers, R., 1998. Methane production and methane consumption: a review Segers, R., 1998. Methane production and methane consumption: a review of processes underlying wetland methane fluxes. Biogeochemistry diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index d20ac17a27..256648359f 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -72,29 +72,34 @@ where :math:`\mu '` is the direction of the scattered flux. The optical parameters :math:`\omega`, :math:`\beta`, and :math:`\beta _{0}`, which vary with wavelength (:math:`\Lambda` ), are weighted combinations of values -for vegetation and snow. The model determines that snow is on the canopy if -:math:`T_{v} \le T_{f}` , where :math:`T_{v}` is the vegetation temperature (K) (Chapter -:numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) and :math:`T_{f}` is the -freezing temperature of water (K) (:numref:`Table Physical Constants`). In this case, the optical parameters are +for vegetation and snow, using the canopy snow-covered fraction :math:`f_{can,\, sno}` +(Chapter :numref:`rst_Hydrology`). The optical parameters are + + +.. + The model determines that snow is on the canopy if + :math:`T_{v} \le T_{f}` , where :math:`T_{v}` is the vegetation temperature (K) (Chapter + :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`) and :math:`T_{f}` is the + freezing temperature of water (K) (:numref:`Table Physical Constants`). In this case, the optical parameters are .. math:: :label: 3.5 - \omega _{\Lambda } =\omega _{\Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} f_{wet} + \omega _{\Lambda } =\omega _{\Lambda }^{veg} \left(1-f_{can,\, sno} \right)+\omega _{\Lambda }^{sno} f_{can,\, sno} .. math:: :label: 3.6 - \omega _{\Lambda } \beta _{\Lambda } =\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} \beta _{\Lambda }^{sno} f_{wet} + \omega _{\Lambda } \beta _{\Lambda } =\omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} \left(1-f_{can,\, sno} \right)+\omega _{\Lambda }^{sno} \beta _{\Lambda }^{sno} f_{can,\, sno} .. math:: :label: 3.7 - \omega _{\Lambda } \beta _{0,\, \Lambda } =\omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} \left(1-f_{wet} \right)+\omega _{\Lambda }^{sno} \beta _{0,\, \Lambda }^{sno} f_{wet} + \omega _{\Lambda } \beta _{0,\, \Lambda } =\omega _{\Lambda }^{veg} \beta _{0,\, \Lambda }^{veg} \left(1-f_{can,\, sno} \right)+\omega _{\Lambda }^{sno} \beta _{0,\, \Lambda }^{sno} f_{can,\, sno} -where :math:`f_{wet}` is the wetted fraction of the canopy (section :numref:`Canopy Water`). The snow and vegetation weights are applied to the products +The snow and vegetation weights are applied to the products :math:`\omega _{\Lambda } \beta _{\Lambda }` and :math:`\omega _{\Lambda } \beta _{0,\, \Lambda }` because these -products are used in the two-stream equations. If there is no snow on the canopy, +products are used in the two-stream equations. If there is no snow on the canopy, this reduces to .. math:: :label: 3.8 From aa7cc7a6ec1053ca8058fe10e686e5340d409936 Mon Sep 17 00:00:00 2001 From: Yaqiong Lu Date: Fri, 2 Jun 2017 16:39:37 -0600 Subject: [PATCH 042/255] updated crop tables --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 110 ++++++++---------- 1 file changed, 51 insertions(+), 59 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 2961569d3a..79e089380b 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -375,72 +375,64 @@ crop and from each other: .. _Table Crop plant functional types: -.. table:: Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. - - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | | Phenological | :math:`T_{p}` | :math:`T_{p}^{\min }` | :math:`{GDD}_{min}` | :math:`{GDD}_{mat}` | Phase 2 | Phase 3 | Harvest: days | :math:`z_{top}^{\max }` | *SLA* | :math:`\chi _{L}` | | - | | Type | K | K | ºdays | ºdays | %\ :math:`{GDD}_{mat}` | %\ :math:`{GDD}_{mat}` | past planting | m | m\ :sup:`2`\ leaf g\ :sup:`-1`\ C | index | | - +=======+==============================================+======================+==============================+===========================+===========================+==============================+==============================+=================+==============================+=================================================+========================+====+ - | 15. | C\ :sub:`3` unmanaged rainfed crop | | | | | | | 0.03 | -0.30 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 16. | C\ :sub:`3` unmanaged irrigated crop | | | | | | | 0.03 | -0.30 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 17. | Rainfed Corn (also known as Maize) | | 950-1850 | 3 | 55-65 | :math:`\mathrm{\le}`\ 165 | 2.50 | 0.05 | -0.50 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 18. | Irrigated Corn (also known as Maize) | | 950-1850 | 3 | 55-65 | :math:`\mathrm{\le}`\ 165 | 2.50 | 0.05 | -0.50 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 19. | Rainfed Temperate Cereals | | :math:`\mathrm{\le}`\ 1700 | 5 | 60 | :math:`\mathrm{\le}`\ 150 | 1.20 | 0.07 | 0.65 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 20. | Irrigated Temperate Cereals | | :math:`\mathrm{\le}`\ 1700 | 5 | 60 | :math:`\mathrm{\le}`\ 150 | 1.20 | 0.07 | 0.65 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 21. | Rainfed Winter cereals (place holder) | | 1900 | 5 | 40 | :math:`\mathrm{\le}`\ 265 | 1.20 | 0.07 | 0.65 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 22. | Irrigated Winter cereals (place holder) | | 1900 | 5 | 40 | :math:`\mathrm{\le}`\ 265 | 1.20 | 0.07 | 0.65 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 23. | Rainfed Soybean | | :math:`\mathrm{\le}`\ 1700 | 3 | 70 | :math:`\mathrm{\le}`\ 150 | 0.75 | 0.07 | -0.50 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - | 24. | Irrigated Soybean | | :math:`\mathrm{\le}`\ 1700 | 3 | 70 | :math:`\mathrm{\le}`\ 150 | 0.75 | 0.07 | -0.50 | | | | - +-------+----------------------------------------------+----------------------+------------------------------+---------------------------+---------------------------+------------------------------+------------------------------+-----------------+------------------------------+-------------------------------------------------+------------------------+----+ - -Notes: :math:`T_{p}` and :math:`T_{p}^{\min }` are coldest -planting temperatures but for winter cereals :math:`T_{p}^{\min }` -is a warmest planting temperature. :math:`{GDD}_{min}` is the lowest -(for planting) 20-year running mean growing degree-days base 0ºC (winter -cereals) or 8 (other crops) tracked from April to September (NH). +.. table:: Crop plant functional types (pfts) in CLM5BGCCROP and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. + + === =========================== ================= =========================== ============================= =========================== ============================= ============================= =========================== =========================== =================================== ======================= + IVT Phenological Type :math:`T_{p}` (K) :math:`{GDD}_{min}` (ºdays) base temperature for GDD (ºC) :math:`{GDD}_{mat}` (ºdays) Phase 2 % :math:`{GDD}_{mat}` Phase 3 % :math:`{GDD}_{mat}` Harvest: days past planting :math:`z_{top}^{\max }` (m) SLA (m :sup:`2` leaf g :sup:`-1` C) :math:`\chi _{L}` index + === =========================== ================= =========================== ============================= =========================== ============================= ============================= =========================== =========================== =================================== ======================= + 17 rainfed temperate corn 279.15 50 8 950-1850 0.03 0.65 :math:`\mathrm{\le}`\ 165 2.50 0.05 -0.50 + 18 irrigated temperate corn 279.15 50 8 950-1850 0.03 0.65 :math:`\mathrm{\le}`\ 165 2.50 0.05 -0.50 + 19 rainfed spring wheat 272.15 50 0 :math:`\mathrm{\le}`\ 1700 0.05 0.60 :math:`\mathrm{\le}`\ 150 1.20 0.04 0.65 + 20 irrigated spring wheat 272.15 50 0 :math:`\mathrm{\le}`\ 1700 0.05 0.60 :math:`\mathrm{\le}`\ 150 1.20 0.04 0.65 + 23 rainfed temperate soybean 279.15 50 10 :math:`\mathrm{\le}`\ 1900 0.03 0.50 :math:`\mathrm{\le}`\ 150 0.75 0.04 -0.50 + 24 irrigated temperate soybean 279.15 50 10 :math:`\mathrm{\le}`\ 1900 0.03 0.50 :math:`\mathrm{\le}`\ 150 0.75 0.04 -0.50 + 41 rainfed cotton 283.15 50 10 :math:`\mathrm{\le}`\ 1700 0.03 0.50 :math:`\mathrm{\le}`\ 160 1.50 0.04 -0.50 + 42 irrigated cotton 283.15 50 10 :math:`\mathrm{\le}`\ 1700 0.03 0.50 :math:`\mathrm{\le}`\ 160 1.50 0.04 -0.50 + 61 rainfed rice 283.15 50 10 :math:`\mathrm{\le}`\ 2100 0.01 0.40 :math:`\mathrm{\le}`\ 150 1.80 0.04 0.65 + 62 irrigated rice 283.15 50 10 :math:`\mathrm{\le}`\ 2100 0.01 0.40 :math:`\mathrm{\le}`\ 150 1.80 0.04 0.65 + 67 rainfed sugarcane 283.15 50 10 950-1850 0.03 0.65 :math:`\mathrm{\le}`\ 300 4.00 0.05 -0.50 + 68 irrigated sugarcane 283.15 50 10 950-1850 0.03 0.65 :math:`\mathrm{\le}`\ 300 4.00 0.05 -0.50 + 75 rainfed tropical corn 283.15 50 10 :math:`\mathrm{\le}`\ 1800 0.03 0.50 :math:`\mathrm{\le}`\ 160 2.50 0.05 -0.50 + 76 irrigated tropical corn 283.15 50 10 :math:`\mathrm{\le}`\ 1800 0.03 0.50 :math:`\mathrm{\le}`\ 160 2.50 0.05 -0.50 + 77 rainfed tropical soybean 283.15 50 10 :math:`\mathrm{\le}`\ 2100 0.03 0.50 :math:`\mathrm{\le}`\ 150 1.00 0.04 -0.50 + 78 irrigated tropical soybean 283.15 50 10 :math:`\mathrm{\le}`\ 2100 0.03 0.50 :math:`\mathrm{\le}`\ 150 1.00 0.04 -0.50 + === =========================== ================= =========================== ============================= =========================== ============================= ============================= =========================== =========================== =================================== ======================= + +Notes: :math:`T_{p}` is the minimum planting temperatures. :math:`{GDD}_{min}` is the lowest +(for planting) 20-year running mean growing degree-days base on the base temperature in the 5\ :sup:`th` column, tracked from April to September (NH). :math:`{GDD}_{mat}` is a crop’s 20-year running mean growing degree-days needed for vegetative and physiological maturity. Harvest occurs at 100%\ :math:`{GDD}_{mat}` or when the days past planting -reach the number in the 10\ :sup:`th` column. Crop growth phases +reach the number in the 9\ :sup:`th` column. Crop growth phases are described in the text. :math:`z_{top}^{\max }` is the maximum -top-of-canopy height of a crop, *SLA* is specific leaf area, and leaf -orientation index, :math:`\chi _{L}` , equals -1 for vertical, 0 for +top-of-canopy height of a crop, *SLA* is specific leaf area. :math:`\chi _{L}` is the leaf +orientation index, equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. .. _Table Crop pfts in CLM4.5CNcrop and their parameters: -.. table:: Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. - - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | | :math:`a_{leaf}^{i}` | :math:`{L}_{max}` | :math:`a_{froot}^{i}` | :math:`a_{froot}^{f}` | :math:`a_{leaf}^{f}` | :math:`a_{livestem}^{f}` | :math:`d_{L}` | :math:`d_{alloc}^{stem}` | :math:`d_{alloc}^{leaf}` | | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | | fraction | m\ :sup:`2` m\ :sup:`-2` | | | | | | | | | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 17. | Rainfed Corn (also referred to as Maize) | 0.800 | 5 | 0.400 | 0.050 | 0.000 | 0.000 | 1.05 | 2 | 5 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 18. | Irrigated Corn (also referred to as Maize) | 0.800 | 5 | 0.400 | 0.050 | 0.000 | 0.000 | 1.05 | 2 | 5 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 19. | Rainfed Temperate Cereals | 0.750 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 20. | Irrigated Temperate Cereals | 0.750 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 21. | Rainfed Winter cereals (place holder) | 0.425 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 22. | Irrigated Winter cereals (place holder) | 0.425 | 7 | 0.300 | 0.000 | 0.000 | 0.050 | 1.05 | 1 | 3 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 23. | Rainfed Soybean | 0.850 | 6 | 0.500 | 0.200 | 0.000 | 0.300 | 1.05 | 5 | 2 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ - | 24. | Irrigated Soybean | 0.850 | 6 | 0.500 | 0.200 | 0.000 | 0.300 | 1.05 | 5 | 2 | - +-------+----------------------------------------------+------------------------------------------+--------------------------+--------------------------+-------------------------+-----------------------------+----------------------+---------------------------------+-----------------------------+-----+ +.. table:: Crop pfts in CLM5BGCCROP and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. + + === =========================== ==================== =========================================== ===================== ===================== ==================== ======================== ============= ======================== ======================== + IVT Phenological Type :math:`a_{leaf}^{i}` :math:`{L}_{max}` (m :sup:`2` m :sup:`-2`) :math:`a_{froot}^{i}` :math:`a_{froot}^{f}` :math:`a_{leaf}^{f}` :math:`a_{livestem}^{f}` :math:`d_{L}` :math:`d_{alloc}^{stem}` :math:`d_{alloc}^{leaf}` + === =========================== ==================== =========================================== ===================== ===================== ==================== ======================== ============= ======================== ======================== + 17 rainfed temperate corn 0.80 5 0.4 0.05 0 0.00 1.05 2 5 + 18 irrigated temperate corn 0.80 5 0.4 0.05 0 0.00 1.05 2 5 + 19 rainfed spring wheat 0.90 7 0.1 0.00 0 0.05 1.05 1 3 + 20 irrigated spring wheat 0.90 7 0.1 0.00 0 0.05 1.05 1 3 + 23 rainfed temperate soybean 0.85 6 0.2 0.20 0 0.30 1.05 5 2 + 24 irrigated temperate soybean 0.85 6 0.2 0.20 0 0.30 1.05 5 2 + 41 rainfed cotton 0.85 6 0.2 0.20 0 0.30 1.05 5 2 + 42 irrigated cotton 0.85 6 0.2 0.20 0 0.30 1.05 5 2 + 61 rainfed rice 0.75 7 0.1 0.00 0 0.05 1.05 1 3 + 62 irrigated rice 0.75 7 0.1 0.00 0 0.05 1.05 1 3 + 67 rainfed sugarcane 0.80 5 0.4 0.05 0 0.00 1.05 2 5 + 68 irrigated sugarcane 0.80 5 0.4 0.05 0 0.00 1.05 2 5 + 75 rainfed tropical corn 0.80 5 0.4 0.05 0 0.00 1.05 2 5 + 76 irrigated tropical corn 0.80 5 0.4 0.05 0 0.00 1.05 2 5 + 77 rainfed tropical soybean 0.85 6 0.2 0.20 0 0.30 1.05 5 2 + 78 irrigated tropical soybean 0.85 6 0.2 0.20 0 0.30 1.05 5 2 + === =========================== ==================== =========================================== ===================== ===================== ==================== ======================== ============= ======================== ======================== Notes: Crop growth phases and corresponding variables are described in the text @@ -738,7 +730,7 @@ calculated as .. math:: :label: 25.14) - leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } + leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } .. math:: :label: 25.15) From 8229a0839a9161f773ffda4979586311cdae92b1 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Mon, 5 Jun 2017 08:00:34 -0600 Subject: [PATCH 043/255] math cleanup --- .../tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 5 ++++- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- .../Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 4e203f8586..253ea92109 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -851,7 +851,10 @@ and \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } = \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } - = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}. + = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array} + +where :math:`\overline{\theta}_{liq} = 0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)`, +:math:`\overline{\theta}_{sat} = 0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)`. Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 027d92e9e2..157b564d7e 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -232,7 +232,7 @@ Jinyun Tang, Zong-Liang Yang** - :numref:`Table Crop plant functional types` Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. -- :numref:`Table Crop pfts in CLM4.5CNcrop and their parameters` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. +- :numref:`Table Crop pfts` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. - :numref:`Table Pre- and post-grain fill CN ratios` Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index d20ac17a27..ec565fe1d3 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -136,17 +136,17 @@ and The upscatter for diffuse radiation is .. math:: - :label: ZEqnNum472968 + :label: 3.13 \omega _{\Lambda }^{veg} \beta _{\Lambda }^{veg} =\frac{1}{2} \left[\alpha _{\Lambda } +\tau _{\Lambda } +\left(\alpha _{\Lambda } -\tau _{\Lambda } \right)\cos ^{2} \bar{\theta }\right] where :math:`\bar{\theta }` is the mean leaf inclination angle relative to the horizontal plane (i.e., the angle between leaf normal and local -vertical) (Sellers 1985). Here, :math:`\cos \bar{\theta }` is +vertical) (:ref:`Sellers (1985) `). Here, :math:`\cos \bar{\theta }` is approximated by .. math:: - :label: ZEqnNum720349 + :label: 3.14 \cos \bar{\theta }=\frac{1+\chi _{L} }{2} From 692bd7f8b2ddd43e542ed40c6a892ae497e8101a Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Mon, 5 Jun 2017 09:00:59 -0600 Subject: [PATCH 044/255] fix overwritten hydrology changes --- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 485 +++++++++--------- .../References/CLM50_Tech_Note_References.rst | 2 +- 2 files changed, 257 insertions(+), 230 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 126fd05cda..9dec375356 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -17,7 +17,7 @@ m\ :sup:`-2` or mm of H\ :sub:`2`\ O) (:numref:`Figure Hydrologic processes`). The total water balance of the system is .. math:: - :label: 7.1) + :label: 7.1 \begin{array}{l} {\Delta W_{can,\,liq} +\Delta W_{can,\,sno} +\Delta W_{sfc} +\Delta W_{sno} +} \\ {\sum _{i=1}^{N_{levsoi} }\left(\Delta w_{liq,\, i} +\Delta w_{ice,\, i} \right)+\Delta W_{a} =\left(\begin{array}{l} {q_{rain} +q_{sno} -E_{v} -E_{g} -q_{over} } \\ {-q_{h2osfc} -q_{drai} -q_{rgwl} -q_{snwcp,\, ice} } \end{array}\right) \Delta t} \end{array} @@ -54,56 +54,58 @@ Interception by vegetation is divided between liquid and solid phases :math:`q_{intr,\,liq}` and :math:`q_{intr,\,ice}` (kg m\ :sup:`-2` s\ :sup:`-1`) .. math:: - :label: 7.2) + :label: 7.2 q_{intr,\,liq} =\alpha_{liq} \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} .. math:: - :label: 7.3) + :label: 7.3 q_{intr,\,ice} =\alpha_{sno} \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} where :math:`L` and :math:`S` are the exposed leaf and stem area index, -respectively (section 2.1.4), and the :math:`\alpha`\'s scale -the fractional area of a leaf that collects water (:ref:`Lawrence et al. 2007 `). -Values of :math:`\alpha_{liq} = 0.25` and :math:`\alpha_{sno} = 1` reflect the increased capacity one side of a leaf has for snow than liquid water. +respectively (section :numref:`Phenology and vegetation burial by snow`), and +the :math:`\alpha`\'s scale the fractional area of a leaf that collects water +(:ref:`Lawrence et al. 2007 `). Values of +:math:`\alpha_{liq} = 0.25` and :math:`\alpha_{sno} = 1` reflect the increased +capacity one side of a leaf has for snow than liquid water. Throughfall (kg m\ :sup:`-2` s\ :sup:`-1`) is also divided into liquid and solid phases, reaching the ground (soil or snow surface) as .. math:: - :label: 7.4) + :label: 7.4 q_{thru,\, liq} =q_{rain} \left[1-\alpha_{liq} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right] .. math:: - :label: 7.5) + :label: 7.5 q_{thru,\, ice} =q_{sno} \left[1-\alpha_{sno} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right]. Similarly, the liquid and solid canopy drip fluxes are .. math:: - :label: 7.6) + :label: 7.6 q_{drip,\, liq} =\frac{W_{can,\,liq}^{intr} -W_{can,\,liq}^{max } }{\Delta t} \ge 0 .. math:: - :label: 7.7) + :label: 7.7 q_{drip,\, ice} =\frac{W_{can,\,sno}^{intr} -W_{can,\,sno}^{max } }{\Delta t} \ge 0 where .. math:: - :label: 7.8) + :label: 7.8 W_{can,liq}^{intr} =W_{can,liq}^{n} +q_{intr} \Delta t\ge 0 and .. math:: - :label: 7.9) + :label: 7.9 W_{can,sno}^{intr} =W_{can,sno}^{n} +q_{intr} \Delta t\ge 0 @@ -115,12 +117,12 @@ from the previous time step, and :math:`W_{can,\,liq}^{max }` and :math:`W_{can, They are defined by .. math:: - :label: 7.10) + :label: 7.10 W_{can,\,liq}^{max } =p_{liq}\left(L+S\right) .. math:: - :label: 7.11) + :label: 7.11 W_{can,\,sno}^{max } =p_{ice}\left(L+S\right). @@ -132,17 +134,17 @@ Canopy snow unloading from wind speed :math:`u` and above-freezing temperatures fluxes and e-folding times similar to :ref:`Roesch et al. (2001) ` .. math:: - :label: 7.12) + :label: 7.12 q_{unl,\, wind} =\frac{u W_{can,sno}}{1.56\times 10^5 \text{ m}} .. math:: - :label: 7.13) + :label: 7.13 q_{unl,\, temp} =\frac{W_{can,sno}(T-270 \textrm{ K})}{1.87\times 10^5 \text{ K s}} > 0 .. math:: - :label: 7.14) + :label: 7.14 q_{unl,\, tot} =\min \left( q_{unl,\, wind} +q_{unl,\, temp} ,W_{can,\, sno} \right) @@ -150,14 +152,14 @@ fluxes and e-folding times similar to :ref:`Roesch et al. (2001) T_{f} \\ - 0 & T_v \le T_f - \end{cases} + E_{v}^{liq} = + \left\{\begin{array}{lr} + E_{v}^{w} & T_v > T_{f} \\ + 0 & T_v \le T_f + \end{array}\right\} .. math:: - :label: 7.18) + :label: 7.18 - E_{v}^{ice} &= \begin{cases} - 0 & T_v > T_f \\ - E_{v}^{w} & T_v \le T_f - \end{cases} . + E_{v}^{ice} = + \left\{\begin{array}{lr} + 0 & T_v > T_f \\ + E_{v}^{w} & T_v \le T_f + \end{array}\right\}. .. \begin{array}{lr} .. E_{v}^{liq} = E_{v}^{w} \qquad T > 273 \text{K} \\ @@ -191,12 +195,12 @@ surface evaporation :math:`E_{v}^{w}` (Chapter :numref:`rst_Momentum, Sensible H The total rate of liquid and solid precipitation reaching the ground is then .. math:: - :label: ZEqnNum946822 + :label: 7.19 q_{grnd,liq} =q_{thru,\, liq} +q_{drip,\, liq} .. math:: - :label: ZEqnNum339590 + :label: 7.20 q_{grnd,ice} =q_{thru,\, ice} +q_{drip,\, ice} +q_{unl,\, tot} . @@ -213,7 +217,7 @@ for surface flux (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat calculations, is (:ref:`Dickinson et al.1993 `) .. math:: - :label: 7.21) + :label: 7.21 f_{wet} = \left\{\begin{array}{lr} @@ -224,7 +228,7 @@ calculations, is (:ref:`Dickinson et al.1993 `) while the fraction of the canopy that is dry and transpiring is .. math:: - :label: 7.22) + :label: 7.22 f_{dry} = \left\{\begin{array}{lr} @@ -236,7 +240,7 @@ Similarly, the snow-covered fraction of the canopy is used for surface alebdo wh .. math:: - :label: 7.23) + :label: 7.23 f_{can,\, sno} = \left\{\begin{array}{lr} @@ -271,28 +275,28 @@ portion of a grid cell contributes to surface runoff, :math:`q_{over}` , by the saturation excess mechanism (Dunne runoff) .. math:: - :label: ZEqnNum549608 + :label: 7.64 - q_{over} =f_{sat} q_{liq,\, 0} + q_{over} =f_{sat} \ q_{liq,\, 0} The fractional saturated area is a function of soil moisture .. math:: - :label: 7.65) + :label: 7.65 - f_{sat} =f_{\max } \exp \left(-0.5f_{over} z_{\nabla } \right) + f_{sat} =f_{\max } \ \exp \left(-0.5f_{over} z_{\nabla } \right) where :math:`f_{\max }` is the potential or maximum value of -:math:`f_{sat}` , :math:`f_{over}` is a decay factor -(m\ :sup:`-1`), and :math:`z_{\nabla}` is the water table depth -(m) (section 7.6). The maximum saturated fraction, :math:`f_{\max }` , -is defined as the value of the discrete cumulative distribution function -(CDF) of the topographic index when the grid cell mean water table depth -is zero. Thus, :math:`f_{\max }` is the percent of pixels in a grid -cell whose topographic index is larger than or equal to the grid cell -mean topographic index. It should be calculated explicitly from the CDF -at each grid cell at the resolution that the model is run. However, -because this is a computationally intensive task for global +:math:`f_{sat}` , :math:`f_{over}` is a decay factor (m\ :sup:`-1`), and +:math:`z_{\nabla}` is the water table depth (m) (section +:numref:`Lateral Sub-surface Runoff`). The maximum saturated fraction, +:math:`f_{\max }`, is defined as the value of the discrete cumulative +distribution function (CDF) of the topographic index when the grid cell +mean water table depth is zero. Thus, :math:`f_{\max }` is the percent of +pixels in a grid cell whose topographic index is larger than or equal to +the grid cell mean topographic index. It should be calculated explicitly +from the CDF at each grid cell at the resolution that the model is run. +However, because this is a computationally intensive task for global applications, :math:`f_{\max }` is calculated once at 0.125\ :sup:`o` resolution using the 1-km compound topographic indices (CTIs) based on the HYDRO1K dataset (:ref:`Verdin and Greenlee 1996 `) @@ -330,17 +334,17 @@ height (relative to the grid cell mean elevation) of the surface water, :math:`d`, by .. math:: - :label: ZEqnNum277892 + :label: 7.66 W_{sfc} =\frac{d}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right)+\frac{\sigma _{micro} }{\sqrt{2\pi } } e^{\frac{-d^{2} }{2\sigma _{micro} ^{2} } } where :math:`erf` is the error function. For a given value of -:math:`W_{sfc}` , equation can be solved for :math:`d` using the +:math:`W_{sfc}` , :eq:`7.66` can be solved for :math:`d` using the Newton-Raphson method. Once :math:`d` is known, one can determine the fraction of the area that is inundated as .. math:: - :label: 7.67) + :label: 7.67 f_{h2osfc} =\frac{1}{2} \left(1+erf\left(\frac{d}{\sigma _{micro} \sqrt{2} } \right)\right) @@ -348,15 +352,15 @@ No global datasets exist for microtopography, so the default parameterization is a simple function of slope .. math:: - :label: 7.68) + :label: 7.68 \sigma _{micro} =\left(\beta +\beta _{0} \right)^{\eta } where :math:`\beta` is the topographic slope, -:math:`\beta _{0} =\left(\sigma _{\max } \right)^{\frac{1}{\eta } }` \ determines -the maximum value of :math:`\sigma _{}` , and :math:`\eta` is an +:math:`\beta_{0} =\left(\sigma_{\max } \right)^{\frac{1}{\eta } }` \ determines +the maximum value of :math:`\sigma_{micro}` , and :math:`\eta` is an adjustable parameter. Default values in the model are -:math:`\sigma _{\max } =0.4` and :math:`\eta =-3`. +:math:`\sigma_{\max } =0.4` and :math:`\eta =-3`. If the spatial scale of the microtopography is small relative to that of the grid cell, one can assume that the inundated areas are distributed @@ -365,7 +369,7 @@ percolation theory can be used to quantify the fraction of the inundated portion of the grid cell that is interconnected .. math:: - :label: 7.69) + :label: 7.69 \begin{array}{lr} f_{connected} =\left(f_{h2osfc} -f_{c} \right)^{\mu } & \qquad f_{h2osfc} >f_{c} \\ f_{connected} =0 &\qquad f_{h2osfc} \le f_{c} \end{array} @@ -377,14 +381,14 @@ surpasses :math:`f_{c}` , the surface water store acts as a linear reservoir .. math:: - :label: 7.70) + :label: 7.70 - qout,h2osfc=kh2osfcf_{connected} (Wsfc-Wc)\frac{1}{\Delta t} + q_{out,h2osfc}=k_{h2osfc} \ f_{connected} \ (Wsfc-Wc)\frac{1}{\Delta t} -where :math:`qout,h2osfc` is the surface water runoff, :math:`kh2osfc` +where :math:`q_{out,h2osfc}` is the surface water runoff, :math:`k_{h2osfc}` is a constant, :math:`Wc` is the amount of surface water present when :math:`f_{h2osfc} =f_{c}` , and :math:`\Delta t` is the model time step. -The linear storage coefficent :math:`kh2osfc=\sin \left(\beta \right)` +The linear storage coefficent :math:`k_{h2osfc} = \sin \left(\beta \right)` is a function of grid cell mean topographic slope where :math:`\beta` is the slope in radians. @@ -397,9 +401,9 @@ The surface moisture flux remaining after surface runoff has been removed, .. math:: - :label: 7.71) + :label: 7.71 - qin,surface=(1-f_{sat} )q_{liq,\, 0} + q_{in,surface} = (1-f_{sat}) \ q_{liq,\, 0} is divided into inputs to surface water (:math:`q_{in,\, h2osfc}` ) and the soil :math:`q_{in,soil}` . If :math:`q_{in,soil}` exceeds the @@ -407,15 +411,15 @@ maximum soil infiltration capacity (kg m\ :sup:`-2` s\ :sup:`-1`), .. math:: - :label: ZEqnNum569150 + :label: 7.72 - q_{infl,\, \max } =(1-fsat){\rm \Theta }iceksat + q_{infl,\, \max } =(1-f_{sat}) \ \Theta_{ice} k_{sat} -where :math:`{\rm \Theta }ice` is an ice impedance factor (section +where :math:`\Theta_{ice}` is an ice impedance factor (section :numref:`Hydraulic Properties`), infiltration excess (Hortonian) runoff is generated .. math:: - :label: 7.73) + :label: 7.73 q_{infl,\, excess} =\max \left(q_{in,soil} -\left(1-f_{h2osfc} \right)q_{\inf l,\max } ,0\right) @@ -423,38 +427,39 @@ and transferred from :math:`q_{in,soil}` to :math:`q_{in,h2osfc}` . After evaporative losses have been removed, these moisture fluxes are .. math:: - :label: 7.74) + :label: 7.74 - q_{in,\, h2osfc} =f_{h2osfc} q_{in,surface} +q_{infl,excess} -q_{evap,h2osfc} + q_{in,\, h2osfc} = f_{h2osfc} q_{in,surface} + q_{infl,excess} - q_{evap,h2osfc} and .. math:: - :label: 7.75) + :label: 7.75 - qin,soil=(1-f_{h2osfc} )q_{in,surface} -q_{\inf l,excess} -(1-f_{sno} -f_{h2osfc} )qevap,soil. + qin,soil=(1-f_{h2osfc} )q_{in,surface} - q_{\inf l,excess} - (1-f_{sno} -f_{h2osfc} ) \ qevap,soil. The balance of surface water is then calculated as .. math:: - :label: 7.76) + :label: 7.76 + + \Delta W_{sfc} =\left(q_{in,h2osfc} - q_{out,h2osfc} - q_{drain,h2osfc} \right) \ \Delta t. - \Delta W_{sfc} =\left(qin,h2osfc-qout,h2osfc-qdrain,h2osfc\right)\Delta t. Bottom drainage from the surface water store .. math:: - :label: 7.77) + :label: 7.77 - qdrain,h2osfc=\min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) + q_{drain,h2osfc} = \min \left(f_{h2osfc} q_{\inf l,\max } ,\frac{W_{sfc} }{\Delta t} \right) is then added to :math:`q_{in,soil}` giving the total infiltration into the surface soil layer .. math:: - :label: 7.78) + :label: 7.78 - q_{infl} =q_{in,soil} +q_{drain,h2osfc} + q_{infl} = q_{in,soil} + q_{drain,h2osfc} Infiltration :math:`q_{infl}` and explicit surface runoff :math:`q_{over}` are not allowed for glaciers. @@ -475,7 +480,7 @@ For one-dimensional vertical water flow in soils, the conservation of mass is stated as .. math:: - :label: ZEqnNum790844 + :label: 7.79 \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q @@ -497,16 +502,16 @@ The soil water flux :math:`q` in equation can be described by Darcy’s law :ref:`(Dingman 2002) ` .. math:: - :label: 7.80) + :label: 7.80 - q=-k\frac{\partial \psi _{h} }{\partial z} + q = -k \frac{\partial \psi _{h} }{\partial z} where :math:`k` is the hydraulic conductivity (mm s\ :sup:`-1`), and :math:`\psi _{h}` is the hydraulic potential (mm). The hydraulic potential is .. math:: - :label: 7.81) + :label: 7.81 \psi _{h} =\psi _{m} +\psi _{z} @@ -519,22 +524,22 @@ If the reference elevation is the soil surface, then becomes .. math:: - :label: ZEqnNum186573 + :label: 7.82 - q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]. + q = -k \left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]. -Equation :eq:`ZEqnNum186573` can be further manipulated to yield +Equation :eq:`7.82` can be further manipulated to yield .. math:: - :label: 7.83) + :label: 7.83 q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]=-k\left(\frac{\partial \psi }{\partial z} +1\right)=-k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right). -Substitution of this equation into equation :eq:`ZEqnNum790844`, with :math:`Q=0`, yields +Substitution of this equation into equation :eq:`7.79`, with :math:`Q=0`, yields the Richards equation .. math:: - :label: ZEqnNum670361 + :label: 7.84 \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right)\right]. @@ -546,7 +551,8 @@ Hydraulic Properties The hydraulic conductivity :math:`k_{i}` (mm s\ :sup:`-1`) and the soil matric potential :math:`\psi _{i}` (mm) for layer :math:`i` vary with volumetric soil water :math:`\theta _{i}` and soil texture. -As with the soil thermal properties (section :numref:`Soil And Snow Thermal Properties`) the hydraulic +As with the soil thermal properties (section +:numref:`Soil And Snow Thermal Properties`) the hydraulic properties of the soil are assumed to be a weighted combination of the mineral properties, which are determined according to sand and clay contents based on work by :ref:`Clapp and Hornberger (1978) @@ -555,29 +561,33 @@ and organic properties of the soil (:ref:`Lawrence and Slater 2008 `). The hydraulic conductivity is defined at the depth of the interface of -two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) and is a function -of the saturated hydraulic conductivity +two adjacent layers :math:`z_{h,\, i}` (:numref:`Figure Water flux schematic`) +and is a function of the saturated hydraulic conductivity :math:`k_{sat} \left[z_{h,\, i} \right]`, the liquid volumetric soil -moisture of the two layers :math:`\theta _{i}` and -:math:`\theta _{i+1}` and an ice impedance factor -:math:`\Theta _{ice}` +moisture of the two layers :math:`\theta _{i}` and :math:`\theta_{i+1}` +and an ice impedance factor :math:`\Theta_{ice}` .. math:: - :label: ZEqnNum398074 + :label: 7.85 k\left[z_{h,\, i} \right] = \left\{\begin{array}{lr} - \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)}{0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ - \Theta _{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} + \Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left[\frac{0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)}{0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)} \right]^{2B_{i} +3} & \qquad 1 \le i \le N_{levsoi} - 1 \\ + \Theta_{ice} k_{sat} \left[z_{h,\, i} \right]\left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{2B_{i} +3} & \qquad i = N_{levsoi} \end{array}\right\}. The ice impedance factor is a function of ice content, and is meant to quantify the increased tortuosity of the water flow when part of the pore space is filled with ice. :ref:`Swenson et al. (2012) ` -used a power law form :math:`\Theta _{ice} = 10^{-\Omega F_{ice} }` where -:math:`\Omega = 6`\ and -:math:`F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }` is the -ice-filled fraction of the pore space. +used a power law form + +.. math:: + :label: 7.86 + + \Theta_{ice} = 10^{-\Omega F_{ice} } + +where :math:`\Omega = 6`\ and :math:`F_{ice} = \frac{\theta_{ice} }{\theta_{sat} }` +is the ice-filled fraction of the pore space. Because the hydraulic properties of mineral and organic soil may differ significantly, the bulk hydraulic properties of each soil layer are @@ -585,32 +595,32 @@ computed as weighted averages of the properties of the mineral and organic components. The water content at saturation (i.e. porosity) is .. math:: - :label: 7.90) + :label: 7.90 - \theta _{sat,i} =(1-f_{om,i} )\theta _{sat,\min ,i} +f_{om,i} \theta _{sat,om} + \theta_{sat,i} =(1-f_{om,i} )\theta_{sat,\min ,i} +f_{om,i} \theta_{sat,om} where :math:`f_{om,i}` is the soil organic matter fraction, -:math:`\theta _{sat,om} =0.9` (:ref:`Farouki 1981 `; +:math:`\theta_{sat,om} =0.9` (:ref:`Farouki 1981 `; :ref:`Letts et al. 2000 `) is the porosity of organic matter and the porosity of the mineral soil -:math:`\theta _{sat,\min ,i}` is +:math:`\theta_{sat,\min ,i}` is .. math:: - :label: 7.91) + :label: 7.91 - \theta _{sai,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . + \theta_{sat,\min ,i} = 0.489 - 0.00126(\% sand)_{i} . The exponent :math:`B_{i}` is .. math:: - :label: 7.92) + :label: 7.92 B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} where :math:`B_{om} = 2.7` \ (:ref:`Letts et al. 2000 `) and .. math:: - :label: 7.93) + :label: 7.93 B_{\min ,i} =2.91+0.159(\% clay)_{i} . @@ -618,14 +628,14 @@ The soil matric potential (mm) is defined at the node depth :math:`z_{i}` of each layer :math:`i` (:numref:`Figure Water flux schematic`) .. math:: - :label: ZEqnNum316201 + :label: 7.94 - \psi _{i} =\psi _{sat,\, i} \left(\frac{\theta _{\, i} }{\theta _{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta _{i} }{\theta _{sat,\, i} } \le 1 + \psi _{i} =\psi _{sat,\, i} \left(\frac{\theta_{\, i} }{\theta_{sat,\, i} } \right)^{-B_{i} } \ge -1\times 10^{8} \qquad 0.01\le \frac{\theta_{i} }{\theta_{sat,\, i} } \le 1 where the saturated soil matric potential (mm) is .. math:: - :label: 7.95) + :label: 7.95 \psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om} @@ -634,7 +644,7 @@ saturated organic matter matric potential and the saturated mineral soil matric potential :math:`\psi _{sat,\min ,i}` \ is .. math:: - :label: 7.96) + :label: 7.96 \psi _{sat,\, \min ,\, i} =-10.0\times 10^{1.88-0.0131(\% sand)_{i} } . @@ -652,28 +662,28 @@ fractions using a result from percolation theory (:ref:`Stauffer and Aharony 1994 `, :ref:`Berkowitz and Balberg 1992 `). Assuming that the organic and mineral fractions are randomly distributed throughout a soil layer, percolation theory predicts that above a threshold value -:math:`f_{om} =f_{threshold}` , connected flow pathways consisting of +:math:`f_{om} = f_{threshold}`, connected flow pathways consisting of organic material only exist and span the soil space. Flow through these pathways interacts only with organic material, and thus can be described -by :math:`k_{sat,\, om}` . This fraction of the grid cell is given by +by :math:`k_{sat,\, om}`. This fraction of the grid cell is given by .. math:: - :label: 7.97) + :label: 7.97 \begin{array}{lr} - f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta _{perc} } f_{om} {\rm \; } & \qquad f_{om} \ge f_{threshold} \\ + f_{perc} =\; N_{perc} \left(f_{om} {\rm \; }-f_{threshold} \right)^{\beta_{perc} } f_{om} {\rm \; } & \qquad f_{om} \ge f_{threshold} \\ f_{perc} = 0 & \qquad f_{om} `) as .. math:: - :label: 7.99) + :label: 7.99 k_{sat,\, \min } \left[z_{h,\, i} \right]=0.0070556\times 10^{-0.884+0.0153\left(\% sand\right)_{i} } . @@ -689,7 +699,7 @@ The bulk soil layer saturated hydraulic conductivity is then computed as .. math:: - :label: 7.100) + :label: 7.100 k_{sat} \left[z_{h,\, i} \right]=f_{uncon,\, i} k_{sat,\, uncon} \left[z_{h,\, i} \right]+(1-f_{uncon,\, i} )k_{sat,\, om} \left[z_{h,\, i} \right]. @@ -698,11 +708,11 @@ as Numerical Solution ^^^^^^^^^^^^^^^^^^^^^^^^ -With reference to :numref:`Figure Water flux schematic`, the equation for conservation of mass -(equation :eq:`ZEqnNum790844`) can be integrated over each layer as +With reference to :numref:`Figure Water flux schematic`, the equation for +conservation of mass (equation :eq:`7.79`) can be integrated over each layer as .. math:: - :label: 7.101) + :label: 7.101 \int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }Q\, dz . @@ -711,9 +721,9 @@ as positive upward from the soil surface. This equation can be written as .. math:: - :label: ZEqnNum225309 + :label: 7.102 - \Delta z_{i} \frac{\partial \theta _{liq,\, i} }{\partial t} =-q_{i-1} +q_{i} -e_{i} + \Delta z_{i} \frac{\partial \theta_{liq,\, i} }{\partial t} =-q_{i-1} +q_{i} -e_{i} where :math:`q_{i}` is the flux of water across interface :math:`z_{h,\, i}` , :math:`q_{i-1}` is the flux of water across @@ -723,12 +733,12 @@ the layer (mm s\ :sup:`-1`). Taking the finite difference with time and evaluating the fluxes implicitly at time :math:`n+1` yields .. math:: - :label: ZEqnNum181361 + :label: 7.103 - \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =-q_{i-1}^{n+1} +q_{i}^{n+1} -e_{i} + \frac{\Delta z_{i} \Delta \theta_{liq,\, i} }{\Delta t} =-q_{i-1}^{n+1} +q_{i}^{n+1} -e_{i} where -:math:`\Delta \theta _{liq,\, i} =\theta _{liq,\, i}^{n+1} -\theta _{liq,\, i}^{n}` +:math:`\Delta \theta_{liq,\, i} =\theta_{liq,\, i}^{n+1} -\theta_{liq,\, i}^{n}` is the change in volumetric soil liquid water of layer :math:`i` in time :math:`\Delta t`\ and :math:`\Delta z_{i}` is the thickness of layer :math:`i` (mm). @@ -738,7 +748,7 @@ function of the total transpiration :math:`E_{v}^{t}` (Chapter :numref:`rst_Mom the effective root fraction :math:`r_{e,\, i}` .. math:: - :label: ZEqnNum357392 + :label: 7.104 e_{i} =r_{e,\, i} E_{v}^{t} . @@ -750,7 +760,7 @@ the effective root fraction :math:`r_{e,\, i}` Shown are three soil layers, :math:`i-1`, :math:`i`, and :math:`i+1`. The soil matric potential :math:`\psi` and volumetric soil water -:math:`\theta _{liq}` are defined at the layer node depth :math:`z`. +:math:`\theta_{liq}` are defined at the layer node depth :math:`z`. The hydraulic conductivity :math:`k\left[z_{h} \right]` is defined at the interface of two layers :math:`z_{h}` . The layer thickness is :math:`\Delta z`. The soil water fluxes :math:`q_{i-1}` and @@ -764,7 +774,7 @@ soil column, the transpiration :math:`E_{v}^{t}` is a weighted sum of transpiration from all PFTs whose weighting depends on PFT area as .. math:: - :label: 7.105) + :label: 7.105 E_{v}^{t} =\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} @@ -777,7 +787,7 @@ quantity that is a weighted sum over all PFTs. The weighting depends on the per unit area transpiration of each PFT and its relative area as .. math:: - :label: 7.106) + :label: 7.106 r_{e,\, i} =\frac{\sum _{j=1}^{npft}\left(r_{e,\, i} \right)_{j} \left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} }{\sum _{j=1}^{npft}\left(E_{v}^{t} \right)_{j} \left(wt\right)_{j} } @@ -785,60 +795,63 @@ where :math:`\left(r_{e,\, i} \right)_{j}` is the effective root fraction for the :math:`j^{th}` PFT .. math:: - :label: 7.107) - - \begin{array}{l} {\left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } \qquad \left(\beta _{t} \right)_{j} >0} \\ {\left(r_{e,\, i} \right)_{j} =0\qquad \left(\beta _{t} \right)_{j} =0} \end{array} + :label: 7.107 + \begin{array}{lr} + \left(r_{e,\, i} \right)_{j} =\frac{\left(r_{i} \right)_{j} \left(w_{i} \right)_{j} }{\left(\beta _{t} \right)_{j} } & \qquad \left(\beta _{t} \right)_{j} >0 \\ + \left(r_{e,\, i} \right)_{j} =0 & \qquad \left(\beta _{t} \right)_{j} =0 + \end{array} + and :math:`\left(r_{i} \right)_{j}` is the fraction of roots in layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), :math:`\left(w_{i} \right)_{j}` is a soil dryness or plant wilting factor -for layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), and :math:`\left(\beta _{t} \right)_{j}` is a wetness factor for the total +for layer :math:`i` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`), and :math:`\left(\beta_{t} \right)_{j}` is a wetness factor for the total soil column for the :math:`j^{th}` PFT (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). -The soil water fluxes in equation , which are a function of -:math:`\theta _{liq,\, i}` and :math:`\theta _{liq,\, i+1}` because of +The soil water fluxes in :eq:`7.103`,, which are a function of +:math:`\theta_{liq,\, i}` and :math:`\theta_{liq,\, i+1}` because of their dependence on hydraulic conductivity and soil matric potential, can be linearized about :math:`\theta` using a Taylor series expansion as .. math:: - :label: 7.108) + :label: 7.108 - q_{i}^{n+1} =q_{i}^{n} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} +\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } \Delta \theta _{liq,\, i+1} + q_{i}^{n+1} =q_{i}^{n} +\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } \Delta \theta_{liq,\, i} +\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} } \Delta \theta_{liq,\, i+1} .. math:: - :label: 7.109) + :label: 7.109 - q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } \Delta \theta _{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } \Delta \theta _{liq,\, i} . + q_{i-1}^{n+1} =q_{i-1}^{n} +\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} } \Delta \theta_{liq,\, i-1} +\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } \Delta \theta_{liq,\, i} . Substitution of these expressions for :math:`q_{i}^{n+1}` and -:math:`q_{i-1}^{n+1}` into equation results in a general tridiagonal +:math:`q_{i-1}^{n+1}` into :eq:`7.103` results in a general tridiagonal equation set of the form .. math:: - :label: 7.110) + :label: 7.110 - r_{i} =a_{i} \Delta \theta _{liq,\, i-1} +b_{i} \Delta \theta _{liq,\, i} +c_{i} \Delta \theta _{liq,\, i+1} + r_{i} =a_{i} \Delta \theta_{liq,\, i-1} +b_{i} \Delta \theta_{liq,\, i} +c_{i} \Delta \theta_{liq,\, i+1} where .. math:: - :label: ZEqnNum557934 + :label: 7.111 - a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} } .. math:: - :label: 7.112) + :label: 7.112 - b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.113) + :label: 7.113 - c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + c_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} } .. math:: - :label: ZEqnNum981892 + :label: 7.114 r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . @@ -846,77 +859,89 @@ The tridiagonal equation set is solved over :math:`i=1,\ldots ,N_{levsoi}`. The finite-difference forms of the fluxes and partial derivatives in -equations - can be obtained from equation as +equations :eq:`7.111` - :eq:`7.114` can be obtained from equation as .. math:: - :label: 7.115) + :label: 7.115 - q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + q_{i-1}^{n} =-k\left[z_{h,\, i-1} \right]\left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.116) + :label: 7.116 - q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] + q_{i}^{n} =-k\left[z_{h,\, i} \right]\left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} -z_{i} } \right] .. math:: - :label: 7.117) + :label: 7.117 - \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } =-\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, i-1} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right] .. math:: - :label: 7.118) + :label: 7.118 + + \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(z_{i} - z_{i-1} \right)}{z_{i} - z_{i-1} } \right] - \frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } =\left[\frac{k\left[z_{h,\, i-1} \right]}{z_{i} -z_{i-1} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i-1} -\psi _{i} \right)+\left(\psi _{E,\, i} -\psi _{E,\, i-1} \right)}{z_{i} -z_{i-1} } \right] .. math:: - :label: 7.119) + :label: 7.119 - \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right] + \frac{\partial q_{i} }{\partial \theta _{liq,\, i} } =-\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i} }{\partial \theta _{liq,\, i} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right] .. math:: - :label: 7.120) + :label: 7.120 - \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(\psi _{E,\, i+1} -\psi _{E,\, i} \right)}{z_{i+1} -z_{i} } \right]. + \frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } =\left[\frac{k\left[z_{h,\, i} \right]}{z_{i+1} -z_{i} } \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } \right]-\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } \left[\frac{\left(\psi _{i} -\psi _{i+1} \right)+\left(z_{i+1} - z_{i} \right)}{z_{i+1} - z_{i} } \right]. The derivatives of the soil matric potential at the node depth are -derived from equation +derived from :eq:`7.94` .. math:: - :label: 7.121) + :label: 7.121 - \frac{\partial \psi _{i-1} }{\partial \theta _{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta _{\, \, i-1} } + \frac{\partial \psi _{i-1} }{\partial \theta_{liq,\, \, i-1} } =-B_{i-1} \frac{\psi _{i-1} }{\theta_{\, \, i-1} } .. math:: - :label: 7.122) + :label: 7.122 - \frac{\partial \psi _{i} }{\partial \theta _{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta _{i} } + \frac{\partial \psi _{i} }{\partial \theta_{\, liq,\, i} } =-B_{i} \frac{\psi _{i} }{\theta_{i} } .. math:: - :label: 7.123) + :label: 7.123 - \frac{\partial \psi _{i+1} }{\partial \theta _{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta _{\, i+1} } + \frac{\partial \psi _{i+1} }{\partial \theta_{liq,\, i+1} } =-B_{i+1} \frac{\psi _{i+1} }{\theta_{\, i+1} } with the constraint -:math:`0.01\, \theta _{sat,\, i} \le \theta _{\, i} \le \theta _{sat,\, i}` . +:math:`0.01\, \theta_{sat,\, i} \le \theta_{\, i} \le \theta_{sat,\, i}` . The derivatives of the hydraulic conductivity at the layer interface are -derived from equation +derived from :eq:`7.85` .. math:: - :label: 7.124) + :label: 7.124 - \begin{array}{l} {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } =\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } =\left(1-\frac{f_{frz,\, i-1} +f_{frz,\, i} }{2} \right)\left(2B_{i-1} +3\right)k_{sat} \left[z_{h,\, i-1} \right]\times } \\ {\qquad \left[\frac{0.5\left(\theta _{\, i-1} +\theta _{\, i} \right)}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right]^{2B_{i-1} +2} \left(\frac{0.5}{0.5\left(\theta _{sat,\, i-1} +\theta _{sat,\, i} \right)} \right)} \end{array} + \begin{array}{l} + {\frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i-1} } + = \frac{\partial k\left[z_{h,\, i-1} \right]}{\partial \theta _{liq,\, i} } + = \left(2B_{i-1} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i-1} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i-1} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array} + +where :math:`\overline{\Theta}_{ice} = \Theta(\overline{\theta}_{ice})` :eq:`7.86`, +:math:`\overline{\theta}_{ice} = 0.5\left(\theta_{ice\, i-1} +\theta_{ice\, i} \right)`, +:math:`\overline{\theta}_{liq} = 0.5\left(\theta_{liq\, i-1} +\theta_{liq\, i} \right)`, +and +:math:`\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i-1} +\theta_{sat,\, i} \right)` + +and .. math:: - :label: 7.125) + :label: 7.125 \begin{array}{l} {\frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i} } = \frac{\partial k\left[z_{h,\, i} \right]}{\partial \theta _{liq,\, i+1} } - = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array} + = \left(2B_{i} +3\right) \ \overline{\Theta}_{ice} \ k_{sat} \left[z_{h,\, i} \right] \ \left[\frac{\overline{\theta}_{liq}}{\overline{\theta}_{sat}} \right]^{2B_{i} +2} \left(\frac{0.5}{\overline{\theta}_{sat}} \right)} \end{array}. -where :math:`\overline{\theta}_{liq} = 0.5\left(\theta _{\, i} +\theta _{\, i+1} \right)`, -:math:`\overline{\theta}_{sat} = 0.5\left(\theta _{sat,\, i} +\theta _{sat,\, i+1} \right)`. +where :math:`\overline{\theta}_{liq} = 0.5\left(\theta_{\, i} +\theta_{\, i+1} \right)`, +:math:`\overline{\theta}_{sat} = 0.5\left(\theta_{sat,\, i} +\theta_{sat,\, i+1} \right)`. Equation set for layer :math:`i=1` '''''''''''''''''''''''''''''''''''''''''' @@ -927,30 +952,30 @@ infiltration rate (section :numref:`Surface Runoff`), is .. math:: - :label: 7.135) + :label: 7.135 - \frac{\Delta z_{i} \Delta \theta _{liq,\, i} }{\Delta t} =q_{infl}^{n+1} +q_{i}^{n+1} -e_{i} . + \frac{\Delta z_{i} \Delta \theta_{liq,\, i} }{\Delta t} =q_{infl}^{n+1} +q_{i}^{n+1} -e_{i} . After grouping like terms, the coefficients of the tridiagonal set of equations for :math:`i=1` are .. math:: - :label: 7.136) + :label: 7.136 a_{i} =0 .. math:: - :label: 7.137) + :label: 7.137 - b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.138) + :label: 7.138 - c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + c_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} } .. math:: - :label: 7.139) + :label: 7.139 r_{i} =q_{infl}^{n+1} -q_{i}^{n} +e_{i} . @@ -961,22 +986,22 @@ The coefficients of the tridiagonal set of equations for :math:`i=2,\ldots ,N_{levsoi} -1` are .. math:: - :label: 7.140) + :label: 7.140 - a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} } .. math:: - :label: 7.141) + :label: 7.141 - b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.142) + :label: 7.142 - c_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i+1} } + c_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i+1} } .. math:: - :label: 7.143) + :label: 7.143 r_{i} =q_{i-1}^{n} -q_{i}^{n} +e_{i} . @@ -989,22 +1014,22 @@ and the coefficients of the tridiagonal set of equations for :math:`i=N_{levsoi}` are .. math:: - :label: 7.148) + :label: 7.148 - a_{i} =-\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i-1} } + a_{i} =-\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i-1} } .. math:: - :label: 7.149) + :label: 7.149 - b_{i} =\frac{\partial q_{i} }{\partial \theta _{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta _{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} + b_{i} =\frac{\partial q_{i} }{\partial \theta_{liq,\, i} } -\frac{\partial q_{i-1} }{\partial \theta_{liq,\, i} } -\frac{\Delta z_{i} }{\Delta t} .. math:: - :label: 7.150) + :label: 7.150 c_{i} =0 .. math:: - :label: 7.151) + :label: 7.151 r_{i} =q_{i-1}^{n} +e_{i} . @@ -1015,7 +1040,7 @@ An initial solution is found by setting :math:`\Delta t` equal to the model time step. An estimate of the error is calculated from .. math:: - :label: 7.152) + :label: 7.152 \epsilon = max \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] @@ -1031,16 +1056,16 @@ Upon solution of the tridiagonal equation set, the liquid water contents are updated as follows .. math:: - :label: 7.164) + :label: 7.164 - w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta _{liq,\, i} \Delta z_{i} \qquad i=1,\ldots ,N_{levsoi} . + w_{liq,\, i}^{n+1} =w_{liq,\, i}^{n} +\Delta \theta_{liq,\, i} \Delta z_{i} \qquad i=1,\ldots ,N_{levsoi} . The volumetric water content is .. math:: - :label: 7.165) + :label: 7.165 - \theta _{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } . + \theta_{i} =\frac{w_{liq,\, i} }{\Delta z_{i} \rho _{liq} } +\frac{w_{ice,\, i} }{\Delta z_{i} \rho _{ice} } . .. _Frozen Soils and Perched Water Table: @@ -1048,15 +1073,15 @@ Frozen Soils and Perched Water Table ---------------------------------------- When soils freeze, the power-law form of the ice impedance factor -(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic conductivity of the -soil, leading to nearly impermeable soil layers. When unfrozen soil -layers are present above relatively ice-rich frozen layers, the +(section :numref:`Hydraulic Properties`) can greatly decrease the hydraulic +conductivity of the soil, leading to nearly impermeable soil layers. When unfrozen +soil layers are present above relatively ice-rich frozen layers, the possibility exists for perched saturated zones. Lateral drainage from perched saturated regions is parameterized as a function of the thickness of the saturated zone .. math:: - :label: 7.166) + :label: 7.166 q_{drai,perch} =k_{drai,\, perch} \left(z_{frost} -z_{\nabla ,perch} \right) @@ -1064,9 +1089,9 @@ where :math:`k_{drai,\, perch}` depends on topographic slope and soil hydraulic conductivity, .. math:: - :label: 7.167) + :label: 7.167 - k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta _{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right) + k_{drai,\, perch} =10^{-5} \sin (\beta )\left(\frac{\sum _{i=N_{perch} }^{i=N_{frost} }\Theta_{ice,i} k_{sat} \left[z_{i} \right]\Delta z_{i} }{\sum _{i=N_{perch} }^{i=N_{frost} }\Delta z_{i} } \right) where :math:`\Theta_{ice}` is an ice impedance factor, :math:`\beta` is the mean grid cell topographic slope in @@ -1089,7 +1114,7 @@ Lateral sub-surface runoff occurs when saturated soil moisture conditions exist within the soil column. Sub-surface runoff is .. math:: - :label: 7.168) + :label: 7.168 q_{subsurface} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) \Delta z_{sat}^{N_{baseflow}} \ , @@ -1101,13 +1126,14 @@ is the thickness of the saturated portion of the soil column. The saturated thickness is .. math:: - :label: 7.1681) + :label: 7.1681 \Delta z_{sat} = z_{bedrock} - z_{\nabla}, where the water table :math:`z_{\nabla}` is determined by finding the -first soil layer above the bedrock depth (section ) in which the volumetric water -content drops below a specified threshold. The default threshold is set to 0.9. +irst soil layer above the bedrock depth (section :numref:`Depth to Bedrock`) +in which the volumetric water content drops below a specified threshold. +The default threshold is set to 0.9. The specific yield, :math:`S_{y}` , which depends on the soil properties and the water table location, is derived by taking the @@ -1115,22 +1141,22 @@ difference between two equilibrium soil moisture profiles whose water tables differ by an infinitesimal amount .. math:: - :label: 7.174) + :label: 7.174 - S_{y} =\theta _{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right) + S_{y} =\theta_{sat} \left(1-\left(1+\frac{z_{\nabla } }{\Psi _{sat} } \right)^{\frac{-1}{B} } \right) where B is the Clapp-Hornberger exponent. Because :math:`S_{y}` is a function of the soil properties, it results in water table dynamics that -are consistent with the soil water fluxes described in section 7.4. +are consistent with the soil water fluxes described in section :numref:`Soil Water`. After the above calculations, two numerical adjustments are implemented to keep the liquid water content of each soil layer (:math:`w_{liq,\, i}` ) within physical constraints of -:math:`w_{liq}^{\min } \le w_{liq,\, i} \le \left(\theta _{sat,\, i} -\theta _{ice,\, i} \right)\Delta z_{i}` +:math:`w_{liq}^{\min } \le w_{liq,\, i} \le \left(\theta_{sat,\, i} -\theta_{ice,\, i} \right)\Delta z_{i}` where :math:`w_{liq}^{\min } =0.01` (mm). First, beginning with the bottom soil layer :math:`i=N_{levsoi}` , any excess liquid water in each soil layer -(:math:`w_{liq,\, i}^{excess} =w_{liq,\, i} -\left(\theta _{sat,\, i} -\theta _{ice,\, i} \right)\Delta z_{i} \ge 0`) +(:math:`w_{liq,\, i}^{excess} =w_{liq,\, i} -\left(\theta_{sat,\, i} -\theta_{ice,\, i} \right)\Delta z_{i} \ge 0`) is successively added to the layer above. Any excess liquid water that remains after saturating the entire soil column (plus a maximum surface ponding depth :math:`w_{liq}^{pond} =10` kg m\ :sup:`-2`), is @@ -1147,21 +1173,21 @@ found, then the water is removed from :math:`W_{t}` and :math:`q_{drai}` . The soil surface layer liquid water and ice contents are then updated -for dew :math:`q_{sdew}` , frost :math:`q_{frost}` , or sublimation -:math:`q_{subl}` (section 5.4) as +for dew :math:`q_{sdew}` , frost :math:`q_{frost}` , or sublimation :math:`q_{subl}` +(section :numref:`Update of Ground Sensible and Latent Heat Fluxes`) as .. math:: - :label: 7.175) + :label: 7.175 w_{liq,\, 1}^{n+1} =w_{liq,\, 1}^{n} +q_{sdew} \Delta t .. math:: - :label: 7.176) + :label: 7.176 w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} +q_{frost} \Delta t .. math:: - :label: 7.177) + :label: 7.177 w_{ice,\, 1}^{n+1} =w_{ice,\, 1}^{n} -q_{subl} \Delta t. @@ -1179,12 +1205,12 @@ and dew in solid or liquid form, is separated into solid :math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms .. math:: - :label: 7.178) + :label: 7.178 q_{snwcp,ice} =q_{grnd,ice} +q_{frost} .. math:: - :label: 7.179) + :label: 7.179 q_{snwcp,liq} =q_{grnd,liq} +q_{dew} @@ -1200,7 +1226,7 @@ For glacier surfaces the runoff term :math:`q_{rgwl}` is calculated from the residual of the water balance .. math:: - :label: 7.180) + :label: 7.180 q_{rgwl} =q_{grnd,ice} +q_{grnd,liq} -E_{g} -E_{v} -\frac{\left(W_{b}^{n+1} -W_{b}^{n} \right)}{\Delta t} -q_{snwcp,ice} @@ -1208,7 +1234,7 @@ where :math:`W_{b}^{n}` and :math:`W_{b}^{n+1}` are the water balances at the beginning and ending of the time step defined as .. math:: - :label: 7.181) + :label: 7.181 W_{b} =W_{can} +W_{sno} +\sum _{i=1}^{N}\left(w_{ice,i} +w_{liq,i} \right) . @@ -1218,3 +1244,4 @@ section :numref:`Precipitation, Evaporation, and Runoff Lake`. The runoff term :math:`q_{rgwl}` may be negative for glaciers and lakes, which reduces the total amount of runoff available to the river routing model (Chapter :numref:`rst_River Transport Model (RTM)`). +> diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 987ac62c8e..3781c4b7a2 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1566,7 +1566,7 @@ Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity in soils and cultures to water stress. Applied and Environmental Microbiology 62:3203-3209. -.. _Segers, R., 1998. Methane production and methane consumption: a review +.. _Segers1998: Segers, R., 1998. Methane production and methane consumption: a review of processes underlying wetland methane fluxes. Biogeochemistry From 4f1c013b4fb53b6bc26a5488314b54456db29e85 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Mon, 5 Jun 2017 09:42:32 -0600 Subject: [PATCH 045/255] one more hydrology fix --- doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +- doc/source/tech_note/References/CLM50_Tech_Note_References.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 9dec375356..db82c6ac68 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -436,7 +436,7 @@ and .. math:: :label: 7.75 - qin,soil=(1-f_{h2osfc} )q_{in,surface} - q_{\inf l,excess} - (1-f_{sno} -f_{h2osfc} ) \ qevap,soil. + q_{in,soil} = (1-f_{h2osfc} ) \ q_{in,surface} - q_{\inf l,excess} - (1 - f_{sno} - f_{h2osfc} ) \ q_{evap,soil}. The balance of surface water is then calculated as diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 3781c4b7a2..1847c205df 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1225,6 +1225,8 @@ Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. +.. _NiuYang2006: + Niu, G.-Y., and Yang, Z.-L. 2006. Effects of frozen soil on snowmelt runoff and soil water storage at a continental scale. J. Hydrometeor. 7:937-952. From d75f87650aac53df6e10f018475003705516332d Mon Sep 17 00:00:00 2001 From: djk2120 Date: Mon, 5 Jun 2017 15:20:54 -0400 Subject: [PATCH 046/255] PHS update, including circuit diagram and more explantory text, part 2 --- ...CLM50_Tech_Note_Plant_Hydraulic_Stress.rst | 58 ++++++++++++++----- 1 file changed, 42 insertions(+), 16 deletions(-) diff --git a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst index 02132af76d..d8bad01423 100644 --- a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst +++ b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst @@ -3,7 +3,13 @@ Plant Hydraulic Stress ====================== -Hello +Introductory text... + +.. _Figure Soil Temperature Schematic: + +.. figure:: circuit.jpg + + Circuit diagram of plant hydraulics scheme .. _Plant Water Supply: @@ -19,27 +25,32 @@ In general the water fluxes (e.g. soil-to-root, root-to-stem, etc) are calculate .. math:: :label: 11.1) - q = kA\Delta\psi + q = kA\left( \psi_1 - \psi_2 \right) -:math:`q` is the flux of water (mmH\ :sub:`2`\ O) +:math:`q` is the flux of water (mmH\ :sub:`2`\ O) spanning the segment between :math:`\psi_1` and :math:`\psi_2` :math:`k` is the hydraulic conductance (s\ :sup:`-1`\ ) -:math:`A` is the area basis (m\ :sup:`2`\ /m\ :sup:`2`\ ) +:math:`A` is the area basis (m\ :sup:`2`\ /m\ :sup:`2`\ ) relating the conducting area basis to ground area -:math:`\Delta\psi` is the gradient in water potential (mmH\ :sub:`2`\ O) +:math:`\psi_1 - \psi_2` is the gradient in water potential (mmH\ :sub:`2`\ O) across the segment .. math:: :label: 11.2) - k=k_{max}\cdot 2^{-\left(\dfrac{\psi}{p50}\right)^{c_k}} + k=k_{max}\cdot 2^{-\left(\dfrac{\psi_1}{p50}\right)^{c_k}} :math:`k_{max}` is the maximum segment conductance (s-1) :math:`p50` is the water potential at 50% loss of conductivity (mmH2O) -:math:`\psi` is the water potential of the lower segment terminus (mmH2O) +:math:`\psi_1` is the water potential of the lower segment terminus (mmH2O) + +The area basis and conductance parameterization varies by segment. There are two stem-to-leaf fluxes in parallel, from stem to sunlit leaf and from stem to shaded leaf (:math:`q_{1a}` and :math:`q_{1a}`). +The water flux from stem-to-leaf is the product of the segment conductance, the conducting area basis, and the water potential gradient from stem to leaf. Stem-to-leaf conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve. +The maximum conductance is a PFT parameter representing the maximum conductance of water from stem to leaf per unit leaf area. +This parameter can be defined separately for sunlit and shaded segments and should already include the appropriate length scaling (in other words this is a conductance, not conductivity). The water potential gradient is the difference between leaf water potential and stem water potential. There is no gravity term, assuming a negligible difference in height across the segment. The area basis is the leaf area index (either sunlit or shaded). .. math:: :label: 11.3) @@ -63,15 +74,19 @@ In general the water fluxes (e.g. soil-to-root, root-to-stem, etc) are calculate Variables: +:math:`q_{1a}` = flux of water (mmH2O/s) from stem to sunlit leaf + +:math:`q_{1b}` = flux of water (mmH2O/s) from stem to shaded leaf + :math:`LAI_{sun}` = sunlit leaf area index (m2/m2) :math:`LAI_{shade}` = shaded leaf area index (m2/m2) -:math:`\psi_{stem}` = stem water potential (mmH20) +:math:`\psi_{stem}` = stem water potential (mmH2O) -:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH20) +:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH2O) -:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH20) +:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH2O) Parameters: @@ -83,6 +98,8 @@ Parameters: :math:`c_{k}` = vulnerability curve shape-fitting parameter (-) +There is one root-to-stem flux. This represents a flux from the root collar to the upper branch reaches. The water flux from root-to-stem is the product of the segment conductance, the conducting area basis, and the water potential gradient from root to stem. Root-to-stem conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve (two parameters). The maximum conductance is defined as the maximum root-to-stem conductivity per unit stem area (PFT parameter) divided by the length of the conducting path, which is taken to be the vegetation height. The area basis is the stem area index. The gradient in water potential is the difference between the root water potential and the stem water potential less the difference in gravitational potential. + .. math:: :label: 11.7) @@ -95,6 +112,8 @@ Parameters: Variables: +:math:`q_2` = flux of water (mmH2O/s) from root to stem + :math:`SAI` = stem area index (m2/m2) :math:`\Delta\psi_z` = gravitational potential (mmH2O) @@ -111,6 +130,14 @@ Parameters: :math:`z_2` = vegetation height (m) +There are several soil-to-root fluxes operating in parallel (one for each root-containing soil layer). Each represents a flux from the given soil layer to the root collar. The water flux from soil-to-root is the product of the segment conductance, the conducting area basis, and the water potential gradient from soil to root. The area basis is a proxy for root area index, defined as the summed leaf and stem area index multiplied by the root-to-shoot ratio (PFT parameter) multiplied by the layer root fraction. The root fraction comes from an empirical root profile (see section zqz). + +The gradient in water potential is the difference between the soil water potential and the root water potential less the difference in gravitational potential. There is only one root water potential to which all soil layers are connected in parallel. A soil-to-root flux can be either positive (vegetation water uptake) or negative (water deposition), depending on the relative values of the root and soil water potentials. This allows for the occurrence of hydraulic redistribution where water moves through vegetation tissue from one soil layer to another. + +Soil-to-root conductance is the result of two resistances in series, first across the soil-root interface and then through the root tissue. The root tissue conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve. The maximum conductance is defined as the maximum root-tissue conductivity (PFT parameter) divided by the length of the conducting path, which is taken to be the soil layer depth plus lateral root length. + +The soil-root interface conductance is defined as the soil conductivity divided by the conducting length from soil to root. The soil conductivity varies by soil layer and is calculated based on soil potential and soil properties, via the Brooks-Corey theory. The conducting length is computed by calculating the characteristic root spacing following Bonan-2014. The root spacing depends on total root biomass and PFT parameters defining root structure (see section zqz). + .. math:: :label: 11.9) @@ -124,17 +151,17 @@ Parameters: .. math:: :label: 11.11) - k_{3,i}=\dfrac{k_{root}*k_{soil-to-root}}{k_{root}+k_{soil-to-root}} + k_{3,i}=\dfrac{k_{r,i}*k_{s,i}}{k_{r,i}+k_{s,i}} .. math:: :label: 11.12) - k_{root,i}=\dfrac{k_{3,max}}{z_{3,i}}*2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}} + k_{r,i}=\dfrac{k_{3,max}}{z_{3,i}}*2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}} .. math:: :label: 11.13) - k_{soil-to-root} = \dfrac{k_{soil,i}}{dx_{root,i}} + k_{s,i} = \dfrac{k_{soil,i}}{dx_{root,i}} .. math:: :label: 11.14) @@ -148,6 +175,8 @@ Parameters: Variables: +:math:`q_{3,i}` = flux of water (mmH2O/s) from soil layer :math:`i` to root + :math:`\Delta\psi_{z,i}` = change in gravitational potential from soil layer :math:`i` to surface (mmH2O) :math:`LAI` = total leaf area index (m2/m2) @@ -249,9 +278,6 @@ The demand terms (left-hand side) are decreasing functions of absolute leaf wate -Yo - - From 481ad0a657c8ba200b1d807b42f7b1cff16334a7 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Mon, 5 Jun 2017 16:32:32 -0600 Subject: [PATCH 047/255] Updated crop chapter, crop functional type section, and added associated references --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 35 ++++++++++++------- .../References/CLM50_Tech_Note_References.rst | 6 ++++ 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 98c5ddcea3..1de6809021 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -90,25 +90,34 @@ vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (pfts) in the naturally vegetated land unit, the managed crop pfts in the managed crop land unit do not share soil columns and thus permit for differences in the -land management between crops. Crop grid cell coverage is assigned from +land management between crops. Each crop type has a rainfed and an irrigated +pft that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural pfts), and the managed crop type proportions within the crop area is based on the dataset created by (:ref:`Portmann et al. 2010 `) for present day and -extrapolated through time using the LUMIP data (insert citation). Each -actively managed crop type has a rainfed and an irrigated pft that are on -independent soil columns. Actively managed crop types (Table XX) are chosen +extrapolated through time using the dataset provided by Land Use Model +Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries +(:ref:`Lawrence et al. 2016 `). For more details about how +crop distributions are determined, see chapter 26 on :ref:`rst_Transient Landcover Change`. + +CLM5 includes eight actively managed crop types +(temperate soybean, tropical soybean, temperate corn, tropical +corn, spring wheat, cotton, rice, and sugarcane) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by Badger and Dirmeyer (:ref:`2015 `) and -described by Levis et al. (:ref:`2016 `). A parameterization -for winter cereals is developed but is not included in CLM5.0 due to the -inability to distinguish between winter and summer cereals in the LUMIP dataset (insert citation). - +described by Levis et al. (:ref:`2016 `). In addition, CLM’s default list of plant functional types (pfts) includes an -unmanaged crop (Table 2.1) treated as a second C3 grass, as well as several -additional crop types that do not have associated parameters. The unmanaged -crop has grid cell coverage assigned from satellite data, as do all -natural pfts when CLM’s crop model is not active. [include remapping text here]. - +irrigated and unirrigated unmanaged C3 crop (Table 2.1)[update table reference] treated as a second C3 grass. +The unmanaged C3 crop is only used when the crop model is not active and +has grid cell coverage assigned from satellite data. [info here about irrigation for unmanaged C3 crop] +The default list of pfts also includes twenty-three inactive crop pfts +that do not yet have associated parameters required for active management. So that all crop area is actively managed, +each of the inactive crop types is simulated using the parameters of the +spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), +which is required to maintain similar phenological parameters. +The information detailing which parameters are used for each crop type is +included in Table XX. It should be noted that analysis with pft-level history output will +need to remap the crop types, as pft-level data will only include actively managed crop types. .. _Phenology: diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 7fb1521105..2c168c5fd4 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -894,6 +894,12 @@ Law, B.E., Sun, O.J., Campbell, J., Van Tuyl, S. and Thornton, P.E. 2003. Changes in carbon storage and fluxes in a chronosequence of ponderosa pine. Global Change Biology, 9: 510-514. +.. _Lawrenceetal2016: + +Lawrence, D.M., et al. 2016. The Land Use Model Intercomparison Project +(LUMIP) contribution to CMIP6: rationale and experimental design. Geo. Sci. +Dev. 9:2973-2998. + .. _Lawrenceetal2007: Lawrence, D.M., Thornton, P.E., Oleson, K.W., and Bonan, G.B. 2007. The From 0e3abef7bb61aa4b3610495893871bf36cfa1cc7 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Tue, 6 Jun 2017 07:51:43 -0600 Subject: [PATCH 048/255] reformat Surfacealbedo --- .../Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 45977ead34..f16a46ec97 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -1159,7 +1159,14 @@ series expansions for the eccentricity :math:`e`\ as follows: .. math:: :label: 3.87 - \Pi =\left\{\begin{array}{l} {0\qquad {\rm for\; -1}\times {\rm 10}^{{\rm -8}} \le e^{\cos } \le 1\times 10^{-8} {\rm \; and\; }e^{\sin } =0} \\ {1.5\pi \qquad {\rm for\; -1}\times {\rm 10}^{{\rm -8}} \le e^{\cos } \le 1\times 10^{-8} {\rm \; and\; }e^{\sin } <0} \\ {0.5\pi \qquad {\rm for\; -1}\times {\rm 10}^{{\rm -8}} \le e^{\cos } \le 1\times 10^{-8} {\rm \; and\; }e^{\sin } >0} \\ {\tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]+\pi \qquad {\rm for\; }e^{\cos } <{\rm -1}\times {\rm 10}^{{\rm -8}} } \\ {\tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]+2\pi \qquad {\rm for\; }e^{\cos } >{\rm 1}\times {\rm 10}^{{\rm -8}} {\rm \; and\; }e^{\sin } <0} \\ {\tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]\qquad {\rm for\; }e^{\cos } >{\rm 1}\times {\rm 10}^{{\rm -8}} {\rm \; and\; }e^{\sin } \ge 0} \end{array}\right\}. + \Pi =\left\{\begin{array}{lr} + 0 & \qquad {\rm for\; -1}\times {\rm 10}^{{\rm -8}} \le e^{\cos } \le 1\times 10^{-8} {\rm \; and\; }e^{\sin } = 0 \\ + 1.5\pi & \qquad {\rm for\; -1}\times {\rm 10}^{{\rm -8}} \le e^{\cos } \le 1\times 10^{-8} {\rm \; and\; }e^{\sin } < 0 \\ + 0.5\pi & \qquad {\rm for\; -1}\times {\rm 10}^{{\rm -8}} \le e^{\cos } \le 1\times 10^{-8} {\rm \; and\; }e^{\sin } > 0 \\ + \tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]+\pi & \qquad {\rm for\; }e^{\cos } <{\rm -1}\times {\rm 10}^{{\rm -8}} \\ + \tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right]+2\pi & \qquad {\rm for\; }e^{\cos } >{\rm 1}\times {\rm 10}^{{\rm -8}} {\rm \; and\; }e^{\sin } <0 \\ + \tan ^{-1} \left[\frac{e^{\sin } }{e^{\cos } } \right] & \qquad {\rm for\; }e^{\cos } >{\rm 1}\times {\rm 10}^{{\rm -8}} {\rm \; and\; }e^{\sin } \ge 0 + \end{array}\right\}. The numerical solution for the longitude of the perihelion :math:`\tilde{\omega }` is constrained to be between 0 and 360 degrees From 3e1dbc96f21bf6659a052becd1bf8aaa5243aa66 Mon Sep 17 00:00:00 2001 From: Yaqiong Lu Date: Tue, 6 Jun 2017 10:57:16 -0600 Subject: [PATCH 049/255] updated fertilization and latvery GDD --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 54 ++++++++++++++----- .../References/CLM50_Tech_Note_References.rst | 9 ++++ 2 files changed, 50 insertions(+), 13 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 1b2548d64f..4f85e4309b 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -610,13 +610,18 @@ Interactive fertilization CLM adds nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands. CLM’s separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. -Fertilizer amounts are obtained from the Agro-IBIS model (Kucharik and -Brye 2003), but can be modified in CLM’s pft-physiology input dataset. -Fertilizer is reported in g N/m\ :sup:`2` by plant functional -type. Total nitrogen fertilizer amounts are 150 g N/m\ :sup:`2` -for maize, 80 g N/m\ :sup:`2` for temperate cereals, and 25 g -N/m\ :sup:`2` for soybean, representative of central U.S. annual -fertilizer application amounts. Since CLM’s denitrification rate is high +Fertilizer in CLM5BGCCROP is prescribed by crop function types spatially +for each year based on the LUMIP land use and land cover change +time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). +There are two fields that are used to prescribe industrial fertilizer. +On the surface data set the field CONST_FERTNITRO_CFT specifies the +annual fertilizer application for a non-transient simulations in g N/m\ :sup:`2`/yr. +In the case of a transient simulation this is replaced by the landuse.timeseries +file with the field FERTNITRO_CFT which is also in g N/m\ :sup:`2`/yr. +The values for both of these fields come from the LUMIP time series for each year. +In addition to the industrial fertilizer there is a background manure fertilizer +on the clm parameters file with the field manunitro. For the current CLM5BGCCROP, +this is set to 0.002 kg N/m\ :sup:`2`/yr. Since CLM’s denitrification rate is high and results in a 50% loss of the unused available nitrogen each day, fertilizer is applied slowly to minimize the loss and maximize plant uptake. Fertilizer application begins during the emergence phase of crop @@ -627,18 +632,18 @@ limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the onset growth for crops initiates: -*f* = *n* \* 86400 [20.9)] +.. math:: + :label: 25.18 + + f = n \times 86400 where *n* is set to 20 fertilizer application days. When the crop enters phase 2 (leaf emergence to the beginning of grain fill) of its growth cycle, fertilizer application begins by initializing fertilizer amount -to the total fertilizer divided by the initialized *f*. Fertilizer is -applied and *f* is decremented each time step until a zero balance on +to the total fertilizer at each grid cell divided by the initialized *f*. +Fertilizer is applied and *f* is decremented each time step until a zero balance on the counter is reached. -The crop fertilization scheme was developed in versions of the CLM prior -to CLM4.5. In CLM4.5, crops with fertilization may be simulated over -productive. .. _Biological nitrogen fixation for soybeans: @@ -800,3 +805,26 @@ the CLM4.0, allocation of carbon to the reproductive pool was calculated but merged with the stem pool. In the model, as allocation declines during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. + +.. _Latitude vary base tempereature for growing degree days: + +Latitude vary base tempereature for growing degree days +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For both rainfed and irrigated spring wheat and sugarcane, +a latitude vary base temperature in calculating :math:`GDD_{T_{{\rm 2m}} }` +(growing degree days since planting) was introduced. + +.. math:: + :label: 25.17 + + latitude\ vary\ baset = \left\{ + \begin{array}{lr} + baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ + baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 + \end{array} \right\} + +where :math:`baset` is the 5\ :sup:`th` column in :numref:`Table Crop plant functional types`. +Such latitude vary baset could increase the base temperature, slow down :math:`GDD_{T_{{\rm 2m}} }` +accumulation, and extend the growing season for -30º to 30º regions for spring wheat +and sugarcane. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 1847c205df..4a88ae39e2 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -927,6 +927,15 @@ and A.G. Slater, 2011. Parameterization improvements and functional and structural advances in version 4 of the Community Land Model. J. Adv. Model. Earth Sys. 3. DOI:10.1029/2011MS000045. +.. _Lawrenceetal2016: + +Lawrence, D. M., Hurtt, G. C., Arneth, A., Brovkin, V., Calvin, K. V., +Jones, A. D., Jones, C. D., Lawrence, P. J., de Noblet-Ducoudré, N., Pongratz, +J., Seneviratne, S. I., and Shevliakova, E, 2016. The Land Use Model +Intercomparison Project (LUMIP) contribution to CMIP6: rationale +and experimental design, Geosci. Model Dev., 9, 2973-2998, +doi:10.5194/gmd-9-2973-2016. + .. _LawrenceChase2007: Lawrence, P.J., and Chase, T.N. 2007. Representing a MODIS consistent From b8cc331040e3eb7fc8bdd075d931d91f7d17d30c Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 6 Jun 2017 12:08:06 -0600 Subject: [PATCH 050/255] Updates to Offline chapter --- .../Offline/CLM50_Tech_Note_Offline.rst | 55 ++++++++++--------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst index da2788a5f9..0419ec668e 100644 --- a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst +++ b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst @@ -5,26 +5,29 @@ Offline Mode In offline mode (uncoupled to an atmospheric model), the atmospheric forcing required by CLM (:numref:`Table Atmospheric input to land model`) -is supplied by observed datasets. The standard forcing provided with the -model is a 110-year (1901-2010) dataset (CRUNCEP; :ref:`Viovy 2011 `) -that is a combination of two existing datasets; the CRU TS3.2 0.5\ -:math:`{}^\circ` X 0.5\ :math:`{}^\circ` monthly data covering the period +is supplied by observed datasets. The standard forcing provided with the +model is a 110-year (1901-2010) dataset provided by the Global Soil Wetness +Project (GSWP3; NEED A REFERENCE). The GSWP3 dataset has a spatial resolution of +0.5\ :math:`{}^o` X 0.5\ :math:`{}^o` and a temporal resolution of three +hours. + +An alternative forcing dataset is also available, CRUNCEP, a 110-year (1901-2010) dataset +(CRUNCEP; :ref:`Viovy 2011 `) that is a combination of two existing datasets; +the CRU TS3.2 0.5\ :math:`{}^o` X 0.5\ :math:`{}^o` monthly data covering the period 1901 to 2002 (:ref:`Mitchell and Jones 2005 `) -and the NCEP reanalysis 2.5\ :math:`{}^\circ` X 2.5\ :math:`{}^\circ` +and the NCEP reanalysis 2.5\ :math:`{}^o` X 2.5\ :math:`{}^o` 6-hourly data covering the period 1948 to 2010. The CRUNCEP dataset has been used to force CLM for studies of vegetation growth, evapotranspiration, and gross primary production (:ref:`Mao et al. 2012 `, :ref:`Mao et al. 2013 `, :ref:`Shi et al. 2013 `) and for the TRENDY (trends in net land-atmosphere carbon exchange over the period -1980-2010) project (:ref:`Piao et al. 2012 `). Version 4 is used -here (:ref:`Viovy 2011 `). Alternative forcing datasets can also be used -(e.g., the :ref:`Qian et al. (2006) ` dataset used for -previous versions of CLM is still available). +1980-2010) project (:ref:`Piao et al. 2012 `). Version 7 is available +here (:ref:`Viovy 2011 `). -Here, the CRUNCEP dataset, which does not include data over oceans, +Here, the GSWP3 dataset, which does not include data for particular fields over oceans, lakes, and Antarctica is modified. This missing data is filled with :ref:`Qian et al. (2006) ` data from 1948 that is interpolated by the data atmosphere -model to the 0.5\ :math:`{}^\circ` CRUNCEP grid. This allows the model +model to the 0.5\ :math:`{}^o` GSWP3 grid. This allows the model to be run over Antarctica and ensures data is available along coastlines regardless of model resolution. @@ -35,19 +38,19 @@ fields [atmospheric pressure :math:`P_{atm}` (Pa), atmospheric specific humidity :math:`q_{atm}` (kg kg\ :sup:`-1`), atmospheric temperature :math:`T_{atm}` (K), and atmospheric wind :math:`W_{atm}` (m s\ :sup:`-1`)]. These are separate streams because they are -handled differently according to the type of field. In the CRUNCEP -dataset, the precipitation stream is provided at six hour intervals and +handled differently according to the type of field. In the GSWP3 +dataset, the precipitation stream is provided at three hour intervals and the data atmosphere model prescribes the same precipitation rate for -each model time step within the six hour period. The four fields that +each model time step within the three hour period. The four fields that are grouped together in another stream (pressure, humidity, temperature, -and wind) are provided at six hour intervals and the data atmosphere +and wind) are provided at three hour intervals and the data atmosphere model linearly interpolates these fields to the time step of the model. -The total solar radiation is also provided at six hour intervals. The +The total solar radiation is also provided at three hour intervals. The data is fit to the model time step using a diurnal function that depends on the cosine of the solar zenith angle :math:`\mu` to provide a smoother diurnal cycle of solar radiation and to ensure that all of the -solar radiation supplied by the six-hourly forcing data is actually +solar radiation supplied by the three-hourly forcing data is actually used. The solar radiation at model time step :math:`t_{M}` is .. math:: @@ -58,15 +61,15 @@ used. The solar radiation at model time step :math:`t_{M}` is S_{atm} \left(t_{M} \right)=0 & \qquad {\rm for\; }\mu \left(t_{M} \right)\le 0.001 \end{array} -where :math:`\Delta t_{FD}` is the time step of the forcing data (6 -hours :math:`\times` 3600 seconds hour\ :sup:`-1` = 21600 +where :math:`\Delta t_{FD}` is the time step of the forcing data (3 +hours :math:`\times` 3600 seconds hour\ :sup:`-1` = 10800 seconds), :math:`\Delta t_{M}` is the model time step (seconds), -:math:`S_{atm} \left(t_{FD} \right)` is the six-hourly solar radiation +:math:`S_{atm} \left(t_{FD} \right)` is the three-hourly solar radiation from the forcing data (W m\ :sup:`-2`), and :math:`\mu \left(t_{M} \right)` is the cosine of the solar zenith angle -at model time step :math:`t_{M}` (section 3.3). The term in the -denominator of equation is the sum of the cosine of the solar zenith -angle for each model time step falling within the six hour period. For +at model time step :math:`t_{M}` (section :numref:`Solar Zenith Angle`). The term in the +denominator of equation (1) is the sum of the cosine of the solar zenith +angle for each model time step falling within the three hour period. For numerical purposes, :math:`\mu \left(t_{M_{i} } \right)\ge 0.001`. The total incident solar radiation :math:`S_{atm}` at the model time @@ -122,7 +125,7 @@ where :math:`a_{0} =0.17639,\, a_{1} =0.00380,\, a_{2} =-9.0039\times 10^{-6} ,\, a_{3} =8.1351\times 10^{-9}` and :math:`b_{0} =0.29548,b_{1} =0.00504,b_{2} =-1.4957\times 10^{-5} ,b_{3} =1.4881\times 10^{-8}` -are coefficients from polynomial fits to the placeCAM data. +are coefficients from polynomial fits to the CAM data. The additional atmospheric forcing variables required by :numref:`Table Atmospheric input to land model` are derived as follows. The atmospheric reference height :math:`z'_{atm}` @@ -146,8 +149,8 @@ where e_{atm} =\frac{P_{atm} q_{atm} }{0.622+0.378q_{atm} } -and :math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ -:math:`{}^{-4}`) (:numref:`Table Physical constants`). The fraction of +and :math:`\sigma` is the Stefan-Boltzmann constant (W m\ :sup:`-2` K\ :sup:`-4`) +(:numref:`Table Physical constants`). The fraction of precipitation :math:`P` (mm s\ :sup:`-1`) falling as rain and/or snow is From a890f67bcc1f1274cf24a83c75a741a6fd9dd999 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Tue, 6 Jun 2017 14:53:03 -0600 Subject: [PATCH 051/255] fix references in Introduction --- .../CLM50_Tech_Note_Introduction.rst | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 157b564d7e..48452d358f 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -418,10 +418,12 @@ added stability corrections to the diagnostic 2-m air temperature calculation which reduced biases in this temperature. Competition between PFTs for water, in which PFTs share a single soil column, is the default mode of operation in this model version. CLM3 was released to -the community in June 2004.:ref:`Dickinson et al. (2006)` describe the climate -statistics of CLM3 when coupled to CCSM3.0. :ref:`Hack et al. (2006)` provide -an analysis of selected features of the land hydrological cycle. -:ref:`Lawrence et al. (2007)` examine the impact of changes in CLM3 +the community in June 2004. :ref:`Dickinson et al. (2006)` +describe the climate statistics of CLM3 when coupled to CCSM3.0. +:ref:`Hack et al. (2006)` provide an analysis of selected +features of the land hydrological cycle. +:ref:`Lawrence et al. (2007)` examine the impact of +changes in CLM3 hydrological parameterizations on partitioning of evapotranspiration (ET) and its effect on the timescales of ET response to precipitation events, interseasonal soil moisture storage, soil moisture memory, and @@ -596,11 +598,12 @@ remains long. Finally, the predominantly low resolution input data for provided with CLM4 to create CLM4 surface datasets is replaced with newer and higher -resolution input datasets where possible (see section 2.2.3 for -details). The default meteorological forcing dataset provided with CLM4 -(:ref:`Qian et al. 2006)` is replaced with the 1901-2010 CRUNCEP forcing -dataset (see Chapter 26) for CLM4.5, though users can also still use the -:ref:`Qian et al. (2006)` dataset or other alternative forcing datasets. +resolution input datasets where possible (see section :numref:`Surface Data` +for details). The default meteorological forcing dataset provided with CLM4 +(:ref:`Qian et al. 2006)` is replaced with the 1901-2010 +CRUNCEP forcing dataset (see Chapter :numref:`rst_Offline Mode`) for CLM4.5, +though users can also still use the :ref:`Qian et al. (2006)` +dataset or other alternative forcing datasets. CLM4.5 was released to the community in June 2013 along with the Community Earth System Model version 1.2 (CESM1.2). From 1d543aea4af058faed4ddde07ffe5182ccf212ab Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Tue, 6 Jun 2017 16:49:44 -0600 Subject: [PATCH 052/255] Updated portions of the crop chapter, including harvest and grain fill phenology --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 35 +++++++++++-------- .../References/CLM50_Tech_Note_References.rst | 16 +++------ 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index b44a1874b6..3ff2afc0b5 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -107,17 +107,21 @@ based on the availability of corresponding algorithms in AgroIBIS and as developed by Badger and Dirmeyer (:ref:`2015 `) and described by Levis et al. (:ref:`2016 `). In addition, CLM’s default list of plant functional types (pfts) includes an -irrigated and unirrigated unmanaged C3 crop (Table 2.1)[update table reference] treated as a second C3 grass. +irrigated and unirrigated unmanaged C3 crop (Table 25.1) treated as a second C3 grass, The unmanaged C3 crop is only used when the crop model is not active and -has grid cell coverage assigned from satellite data. [info here about irrigation for unmanaged C3 crop] +has grid cell coverage assigned from satellite data, and +the unmanaged C3 irrigated crop type is currently not used +since irrigation requires the crop model to be active. The default list of pfts also includes twenty-three inactive crop pfts -that do not yet have associated parameters required for active management. So that all crop area is actively managed, -each of the inactive crop types is simulated using the parameters of the +that do not yet have associated parameters required for active management. +Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), -which is required to maintain similar phenological parameters. -The information detailing which parameters are used for each crop type is -included in Table XX. It should be noted that analysis with pft-level history output will -need to remap the crop types, as pft-level data will only include actively managed crop types. +which is required to maintain similar phenological parameters based on temperature thresholds. +Information detailing which parameters are used for each crop type is +included in Table 25.1. It should be noted that analysis with pft-level history output merges +all crop types into the actively managed crop type, so analysis +of crop-specific output will require use of the land surface dataset to +remap the yields of each actively and inactively managed crop type. .. _Phenology: @@ -210,7 +214,7 @@ Leaf emergence According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth tracked since planting -(:math:`GDD_{T_{soi} }` ) reaches 3 to 5% of :math:`{GDD}_{mat}` +(:math:`GDD_{T_{soi} }` ) reaches 1 to 5% of :math:`{GDD}_{mat}` (:numref:`Table Crop plant functional types`). :math:`GDD_{T_{soi} }` is base 8, 0, and 10\ :math:`{}^\circ`\ C for corn, soybean, and temperate cereals. Leaf onset, as defined in the CN part of the model, occurs in the first @@ -223,12 +227,13 @@ a maximum value during phase 2. Grain fill ''''''''''''''''''' -Phase 3 begins in a similar way to phase 2. A variable tracked since +Phase 3 begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting like :math:`GDD_{T_{soi} }` but for 2-m air temperature, :math:`GDD_{T_{{\rm 2m}} }`, must reach a heat unit threshold, *h*, -of 40 to 70% of :math:`{GDD}_{mat}` (:numref:`Table Crop plant functional types`). For corn the -percentage itself is an empirical function of :math:`{GDD}_{mat}` -(not shown). In phase 3, the leaf area index begins to decline in +of 40 to 65% of :math:`{GDD}_{mat}` (:numref:`Table Crop plant functional types`). +The second potential trigger for phase 3 is based on leaf area index. +When the maximum value of leaf area index is reached in phase 2, phase 3 begins. +In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the pft as done in the CN part of the model. @@ -240,12 +245,12 @@ Harvest Harvest is assumed to occur as soon as the crop reaches maturity. When :math:`GDD_{T_{{\rm 2m}} }` reaches 100% of :math:`{GDD}_{mat}` or the number of days past planting reaches a crop-specific maximum -(:numref:`Table Crop plant functional types`), then the crop is harvested. +(:numref:`Table Crop plant functional types`)[update table reference], then the crop is harvested. Harvest occurs in one time step using CN’s leaf offset algorithm. New variables track the flow of grain C and N to food and of live stem C and N to litter. Currently, food C and N are routed directly to litter using the labile, cellulose, and lignin -fractions for leaves. The same fractions for leaves are used for the +fractions for leaves. [update to product pool] The same fractions for leaves are used for the flow of live stem C and N to litter for corn, soybean, and temperate cereals. This is in contrast to the approach for unmanaged PFTs which puts live stem C and N to dead stems first, rather than to litter. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index b6df8ed437..7c89fc063b 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -900,12 +900,6 @@ Law, B.E., Sun, O.J., Campbell, J., Van Tuyl, S. and Thornton, P.E. 2003. Changes in carbon storage and fluxes in a chronosequence of ponderosa pine. Global Change Biology, 9: 510-514. -.. _Lawrenceetal2016: - -Lawrence, D.M., et al. 2016. The Land Use Model Intercomparison Project -(LUMIP) contribution to CMIP6: rationale and experimental design. Geo. Sci. -Dev. 9:2973-2998. - .. _Lawrenceetal2007: Lawrence, D.M., Thornton, P.E., Oleson, K.W., and Bonan, G.B. 2007. The @@ -935,12 +929,12 @@ Model. Earth Sys. 3. DOI:10.1029/2011MS000045. .. _Lawrenceetal2016: -Lawrence, D. M., Hurtt, G. C., Arneth, A., Brovkin, V., Calvin, K. V., -Jones, A. D., Jones, C. D., Lawrence, P. J., de Noblet-Ducoudré, N., Pongratz, -J., Seneviratne, S. I., and Shevliakova, E, 2016. The Land Use Model +Lawrence, D.M., Hurtt, G.C., Arneth, A., Brovkin, V., Calvin, K.V., +Jones, A.D., Jones, C.D., Lawrence, P.J., de Noblet-Ducoudré, N., Pongratz, +J., Seneviratne, S.I., and Shevliakova, E. 2016. The Land Use Model Intercomparison Project (LUMIP) contribution to CMIP6: rationale -and experimental design, Geosci. Model Dev., 9, 2973-2998, -doi:10.5194/gmd-9-2973-2016. +and experimental design. Geosci. Model Dev. 9:2973-2998. +DOI:10.5194/gmd-9-2973-2016. .. _LawrenceChase2007: From 3e3655cc0e47e2deb7c3630284c5796a60d0a128 Mon Sep 17 00:00:00 2001 From: Justin Perket Date: Wed, 7 Jun 2017 13:09:33 -0600 Subject: [PATCH 053/255] fixed couple typos in 7.1 --- .../tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index db82c6ac68..bce8c53b23 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -56,12 +56,12 @@ Interception by vegetation is divided between liquid and solid phases .. math:: :label: 7.2 - q_{intr,\,liq} =\alpha_{liq} \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + q_{intr,\,liq} =\alpha_{liq} q_{rain} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} .. math:: :label: 7.3 - q_{intr,\,ice} =\alpha_{sno} \left(q_{rain} +q_{sno} \right)\left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + q_{intr,\,ice} =\alpha_{sno} q_{sno} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} where :math:`L` and :math:`S` are the exposed leaf and stem area index, @@ -100,14 +100,14 @@ where .. math:: :label: 7.8 - W_{can,liq}^{intr} =W_{can,liq}^{n} +q_{intr} \Delta t\ge 0 + W_{can,liq}^{intr} =W_{can,liq}^{n} +q_{intr,\, liq} \Delta t\ge 0 and .. math:: :label: 7.9 - W_{can,sno}^{intr} =W_{can,sno}^{n} +q_{intr} \Delta t\ge 0 + W_{can,sno}^{intr} =W_{can,sno}^{n} +q_{intr,\, ice} \Delta t\ge 0 are the the canopy liquid water and snow water equivalent after accounting for interception, From 5c6e5b0861a7a976e25b2299bf42d55ee0173623 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 8 Jun 2017 08:21:51 -0600 Subject: [PATCH 054/255] Hydrology update --- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 71 +++++++++++++------ .../References/CLM50_Tech_Note_References.rst | 6 ++ 2 files changed, 55 insertions(+), 22 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index db82c6ac68..ad50ea0f5e 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -473,8 +473,6 @@ Soil water is predicted from a multi-layer model, in which the vertical soil moisture transport is governed by infiltration, surface and sub-surface runoff, gradient diffusion, gravity, and canopy transpiration through root extraction (:numref:`Figure Hydrologic processes`). -The following derivation generally follows that of :ref:`Z.-L. Yang (1998, -unpublished manuscript) `. For one-dimensional vertical water flow in soils, the conservation of mass is stated as @@ -482,14 +480,14 @@ mass is stated as .. math:: :label: 7.79 - \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} -Q + \frac{\partial \theta }{\partial t} =-\frac{\partial q}{\partial z} - e where :math:`\theta` is the volumetric soil water content (mm\ :sup:`3` of water / mm\ :sup:`-3` of soil), :math:`t` is time (s), :math:`z` is height above some datum in the soil column (mm) (positive upwards), :math:`q` is soil water flux (kg m\ :sup:`-2` s\ :sup:`-1` or mm s\ :sup:`-1`) (positive upwards), and -:math:`Q` is a soil moisture sink term (mm of water mm\ :sup:`-1` +:math:`e` is a soil moisture sink term (mm of water mm\ :sup:`-1` of soil s\ :sup:`-1`) (ET loss). This equation is solved numerically by dividing the soil column into multiple layers in the vertical and integrating downward over each layer with an upper boundary @@ -533,15 +531,22 @@ Equation :eq:`7.82` can be further manipulated to yield .. math:: :label: 7.83 - q=-k\left[\frac{\partial \left(\psi +z\right)}{\partial z} \right]=-k\left(\frac{\partial \psi }{\partial z} +1\right)=-k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right). + q = -k \left[\frac{\partial \left(\psi +z\right)}{\partial z} \right] + = -k \left(\frac{\partial \psi }{\partial z} + 1 \right) \ . -Substitution of this equation into equation :eq:`7.79`, with :math:`Q=0`, yields -the Richards equation +Substitution of this equation into equation :eq:`7.79`, with :math:`e = 0`, yields +the Richards equation :ref:`(Dingman 2002) ` .. math:: :label: 7.84 - \frac{\partial \theta }{\partial t} =\frac{\partial }{\partial z} \left[k\left(\frac{\partial \theta }{\partial z} \frac{\partial \psi }{\partial \theta } +1\right)\right]. + \frac{\partial \theta }{\partial t} = + \frac{\partial }{\partial z} \left[k\left(\frac{\partial \psi }{\partial z} + 1 + \right)\right]. + +In practice (Section :numref:`Numerical Solution Hydrology`), changes in soil +water content are predicted from :eq:`7.79` using finite-difference approximations +for :eq:`7.83`. .. _Hydraulic Properties: @@ -714,7 +719,7 @@ conservation of mass (equation :eq:`7.79`) can be integrated over each layer as .. math:: :label: 7.101 - \int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }Q\, dz . + \int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial \theta }{\partial t} \, dz=-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} }\frac{\partial q}{\partial z} \, dz-\int _{-z_{h,\, i} }^{-z_{h,\, i-1} } e\, dz . Note that the integration limits are negative since :math:`z` is defined as positive upward from the soil surface. This equation can be written @@ -1035,25 +1040,47 @@ and the coefficients of the tridiagonal set of equations for Adaptive Time Stepping ''''''''''''''''''''''''''''' -The tridiagonal equation set is solved using an adaptive time-stepping procedure. -An initial solution is found by setting :math:`\Delta t` equal to the model time -step. An estimate of the error is calculated from + +To improve the accuracy and stability of the numerical solutions, the +length of the time step is adjusted. The difference between two numerical +approximations is used to estimate the temporal truncation error, and then +the step size is adjusted to meet a user-prescribed error tolerance +:ref:`[Kavetski et al., 2002]`. The temporal truncation +error is estimated by comparing the flux obtained from the first-order +Taylor series expansion (:math:`q_{i-1}^{n+1}` and :math:`q_{i}^{n+1}`, +equations :eq:`7.108` and :eq:`7.109`) against the flux at the start of the +time step (:math:`q_{i-1}^{n}` and :math:`q_{i}^{n}`). Since the tridiagonal +solution already provides an estimate of :math:`\Delta \theta_{liq,i}`, it is +convenient to compute the error for each of the :math:`i` layers from equation +:eq:`7.103` as .. math:: :label: 7.152 - \epsilon = max \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - - \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] + \epsilon_{i} = \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - + \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] \ \frac{\Delta t_{sub}}{2} + +and the maximum absolute error across all layers as + +.. math:: + :label: 7.153 + + \begin{array}{lr} + \epsilon_{crit} = {\rm max} \left( \left| \epsilon_{i} \right| \right) & \qquad 1 \le i \le nlevsoi + \end{array} \ . -If :math:`\epsilon` is greater than a specified error tolerance, the solution is -rejected, :math:`\Delta t` is halved and a new solution is determined. If the solution -is accepted, the procedure repeats until the adaptive sub-stepping spans the full -model time step. During the solution, the sub-steps may be halved until a -specified minimum time step length is reached, and the sub-steps may be doubled -when :math:`\epsilon` is less than a specified error tolerance. +The adaptive step size selection is based on specified upper and lower error +tolerances, :math:`\tau_{U}` and :math:`\tau_{L}`. The solution is accepted if +:math:`\epsilon_{crit} \le \tau_{U}` and the procedure repeats until the adaptive +sub-stepping spans the full model time step (the sub-steps are doubled if +:math:`\epsilon_{crit} \le \tau_{L}`, i.e., if the solution is very accurate). +Conversely, the solution is rejected if :math:`\epsilon_{crit} > \tau_{U}`. In +this case the length of the sub-steps is halved and a new solution is obtained. +The halving of substeps continues until either :math:`\epsilon_{crit} \le \tau_{U}` +or the specified minimum time step length is reached. -Upon solution of the tridiagonal equation set, the -liquid water contents are updated as follows +Upon solution of the tridiagonal equation set, the liquid water contents are updated +as follows .. math:: :label: 7.164 diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index b6df8ed437..a1dbf281ea 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -792,6 +792,12 @@ photosynthetic capacity and its relationship to leaf nitrogen content for global–scale terrestrial biosphere models. Global Change Biol. 15:976–991. +.. _Kavetskietal2002: + +Kavetski, D., Binning, P. and Sloan, S.W., 2002. Noniterative time +stepping schemes with adaptive truncation error control for the +solution of Richards equation. Water Resources Research, 38(10). + .. _Kelleretal2004: Keller, M., Palace, M., Asner, G.P., Pereira, R., Jr. and Silva, J.N.M., From 645daaed9e0f0ccfa5eb86f8d53b7e398423c45a Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 8 Jun 2017 08:50:33 -0600 Subject: [PATCH 055/255] Hydrology typo fix --- .../tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 8afb068892..404943dd97 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -546,7 +546,7 @@ the Richards equation :ref:`(Dingman 2002) ` In practice (Section :numref:`Numerical Solution Hydrology`), changes in soil water content are predicted from :eq:`7.79` using finite-difference approximations -for :eq:`7.83`. +for :eq:`7.84`. .. _Hydraulic Properties: @@ -1041,10 +1041,10 @@ and the coefficients of the tridiagonal set of equations for Adaptive Time Stepping ''''''''''''''''''''''''''''' -To improve the accuracy and stability of the numerical solutions, the -length of the time step is adjusted. The difference between two numerical +The length of the time step is adjusted in order to improve the accuracy +and stability of the numerical solutions. The difference between two numerical approximations is used to estimate the temporal truncation error, and then -the step size is adjusted to meet a user-prescribed error tolerance +the step size :math:`\Delta t_{sub}` is adjusted to meet a user-prescribed error tolerance :ref:`[Kavetski et al., 2002]`. The temporal truncation error is estimated by comparing the flux obtained from the first-order Taylor series expansion (:math:`q_{i-1}^{n+1}` and :math:`q_{i}^{n+1}`, @@ -1057,7 +1057,7 @@ convenient to compute the error for each of the :math:`i` layers from equation .. math:: :label: 7.152 - \epsilon_{i} = \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t} - + \epsilon_{i} = \left[ \frac{\Delta \theta_{liq,\, i} \Delta z_{i}}{\Delta t_{sub}} - \left( q_{i-1}^{n} - q_{i}^{n} + e_{i}\right) \right] \ \frac{\Delta t_{sub}}{2} and the maximum absolute error across all layers as From e23f4731c1e175614d99f776ca7f16537bd396fa Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 8 Jun 2017 10:47:39 -0600 Subject: [PATCH 056/255] Fire Chapter Update from F.Li --- .../tech_note/Fire/CLM50_Tech_Note_Fire.rst | 613 ++++++++++-------- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +- .../References/CLM50_Tech_Note_References.rst | 6 + 3 files changed, 332 insertions(+), 289 deletions(-) diff --git a/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst b/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst index d6b6495827..caef87c2b3 100644 --- a/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst +++ b/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst @@ -4,162 +4,166 @@ Fire ======== The fire parameterization in CLM contains four components: non-peat -fires outside cropland and tropical closed forests, agricultural fires, -deforestation fires in the tropical closed forests, and peat fires (Li -et al. 2012a, b, 2013). In this fire parameterization, burned area is -affected by climate and weather conditions, vegetation composition and -structure, and human activities. After burned area is calculated, we -estimate the fire impact, including biomass and peat burning, -fire-induced vegetation mortality, and the adjustment of the carbon and -nitrogen (C/N) pools. Justification for all equations and parameter -values is given by Li et al. (2012a, b; 2013) in detail. +fires outside cropland and tropical closed forests, agricultural fires +in cropland, deforestation fires in the tropical closed forests, and +peat fires (see :ref:`Li et al. 2012a `, +:ref:`Li et al. 2012b `, :ref:`Li et al. 2013 `, +:ref:`Li and Lawrence 2017 ` for details). +In this fire parameterization, burned area is affected by climate and +weather conditions, vegetation composition and structure, and human +activities. After burned area is calculated, we estimate the fire impact, +including biomass and peat burning, fire-induced vegetation mortality, +adjustment of the carbon and nitrogen (C/N) pools, and fire emissions. + +.. _Non-peat fires outside cropland and tropical closed forest: Non-peat fires outside cropland and tropical closed forest --------------------------------------------------------------- -Burned area in a grid cell per time step,\ :math:`A_{b}` -(km :sup:`2` (time step) :sup:`-1`), is determined by +Burned area in a grid cell, \ :math:`A_{b}` (km\ :sup:`2` s :sup:`-1`), +is determined by .. math:: - :label: 23.1) + :label: 23.1 A_{b} =N_{f} a -where :math:`N_{f}` (count (time step)\ :sup:`-1`) is fire -counts in the grid cell; :math:`a` (km:sup:`2`) is average fire +where :math:`N_{f}` (count s\ :sup:`-1`) is fire +counts in the grid cell; :math:`a` (km\ :sup:`2`) is average fire spread area of a fire. +.. _Fire counts: + Fire counts ^^^^^^^^^^^^^^^^^^ Fire counts :math:`N_{f}` is taken as .. math:: - :label: 23.2) + :label: 23.2 - N_{f} =N_{i} f_{b} f_{m} f_{se,o} + N_{f} = N_{i} f_{b} f_{m} f_{se,o} -where :math:`N_{i}` \ ( count (time step)\ :sup:`-1`) is the +where :math:`N_{i}` ( count s\ :sup:`-1`) is the number of ignition sources due to natural causes and human activities; :math:`f_{b}` and :math:`f_{m}` (fractions) represent the availability and combustibility of fuel, respectively; :math:`f_{se,o}` is the fraction of anthropogenic and natural fires unsuppressed by humans and related to the socioeconomic conditions. -:math:`N_{i}` (count (time step)\ :sup:`-1`) is given as +:math:`N_{i}` (count s\ :sup:`-1`) is given as .. math:: - :label: 23.3) + :label: 23.3 - N_{i} =(I_{n} +I_{a} )A_{g} + N_{i} = \left(I_{n} +I_{a} \right) A_{g} -where :math:`I_{n}` \ (count km\ :sup:`-2` (time step)\ :sub:`-1`) and :math:`I_{a}` \ (count km\ :sup:`-2` (time step)\ :sup:`-1`) are the number of natural and -anthropogenic ignitions per km\ :sup:`2`, respectively; -*A*\ :sub:`g` is the area of the grid cell (km\ :sup:`2`). -:math:`I_{n}` is estimated by +where :math:`I_{n}` (count km\ :sup:`-2` s\ :sup:`-1`) and :math:`I_{a}` +(count km\ :sup:`-2` s\ :sup:`-1`) are the number of natural and anthropogenic +ignitions per km\ :sup:`2`, respectively; :math:`A_{g}` is the area of the +grid cell (km\ :sup:`2`). :math:`I_{n}` is estimated by .. math:: - :label: 23.4) + :label: 23.4 - I_{n} =\gamma \psi I_{l} + I_{n} = \gamma \psi I_{l} -where :math:`\gamma` \ =0.25 is ignition efficiency of cloud-to-ground -lightning; :math:`\psi =\frac{1}{5.16+2.16\cos (3\lambda )}` is the -cloud-to-ground lightning fraction and depends on the latitude -:math:`\lambda` ; :math:`I_{l}` (flash km\ :sup:`-2` (time step)\ :sup:`-1`) is the total lightning flashes. :math:`I_{a}` , -is modeled as a monotonic increasing function of population density:\ +where :math:`\gamma` \ =0.22 is ignition efficiency of cloud-to-ground +lightning; :math:`\psi =\frac{1}{5.16+2.16\cos [3min(60,\lambda )]}` is the +cloud-to-ground lightning fraction and depends on the latitude +:math:`\lambda` (degrees) ; :math:`I_{l}` (flash km\ :sup:`-2` s\ :sup:`-1`) is +the total lightning flashes. :math:`I_{a}` is modeled as a monotonic +increasing function of population density: .. math:: - :label: 23.5) + :label: 23.5 I_{a} =\frac{\alpha D_{P} k(D_{P} )}{n} -where :math:`\alpha =0.0035` (count person\ :sup:`-1` mon\ :sup:`-1`) is the number of potential ignition sources by a -person per month; :math:`D_{P}` (person km\ :sup:`-2`) is the population density; -:math:`k(D_{P} )=6.8D_{P} ^{-0.6}` represents anthropogenic ignition -potential as a function of human population density\ :math:`D_{P}` ; *n* -is the number of time steps in a month. +where :math:`\alpha =0.01` (count person\ :sup:`-1` mon\ :sup:`-1`) is the number of potential ignition sources by a +person per month; :math:`D_{P}` (person km\ :sup:`-2`) is the population density; :math:`k(D_{P} )=6.8D_{P} ^{-0.6}` represents anthropogenic ignition +potential as a function of human population density :math:`D_{P}` ; *n* +is the seconds in a month. -Fuel availability\ :math:`f_{b}` is given as +Fuel availability :math:`f_{b}` is given as .. math:: - :label: ZEqnNum730456 + :label: 23.6 - f_{b} =\left\{\begin{array}{c} {0} \\ {\frac{B_{ag} -B_{low} }{B_{up} -B_{low} } } \\ {1} \end{array}\right. ,\begin{array}{cc} {} & {} \end{array}\begin{array}{c} {B_{ag} B_{up} } \end{array} + f_{b} =\left\{\begin{array}{c} + {0} \\ {\frac{B_{ag} -B_{low} }{B_{up} -B_{low} } } \\ {1} \end{array} + \begin{array}{cc} {} & {} \end{array}\begin{array}{c} {B_{ag} B_{up} } + \end{array}\right\} \ , -where :math:`B_{ag}` (g C m\ :sup:`-2`) is the aboveground -biomass of combined leaf, stem and aboveground litter (leaf litter and -woody debris) pools; :math:`B_{low}` \ =155 g C m\ :sup:`-2` is -the lower fuel threshold below which fire does not occur; -:math:`B_{up}` \ = 1050 g C m\ :sup:`-2` is the upper fuel -threshold above which fire occurrence is not limited by fuel -availability. +where :math:`B_{ag}` (g C m\ :sup:`-2`) is the biomass of combined leaf, +stem, litter, and woody debris pools; :math:`B_{low}` = 105 g C m :sup:`-2` +is the lower fuel threshold below which fire does not occur; :math:`B_{up}` += 1050 g C m\ :sup:`-2` is the upper fuel threshold above which fire +occurrence is not limited by fuel availability. Fuel combustibility :math:`f_{m}` is estimated by .. math:: - :label: 23.7) - - f_{m} =f_{RH} f_{\theta } f_{T} + :label: 23.7 -where :math:`f_{RH}`, :math:`f_{\theta }`, :math:`f_{T}` -represent the dependence of fuel combustibility on relative humidity -*RH* (%), surface soil wetness :math:`\theta` , and surface air -temperature *T* (ºC), respectively. :math:`f_{RH}` is calculated by + f_{m} = {f_{RH} f_{\beta}}, &\qquad T_{17cm} > T_{f} + +where :math:`f_{RH}` and :math:`f_{\beta }` represent the dependence of +fuel combustibility on relative humidity :math:`RH` (%) and root-zone +soil moisture limitation :math:`\beta` (fraction); :math:`T_{17cm}` is +the temperature of the top 17 cm of soil (K) and :math:`T_{f}` is the +freezing temperature. :math:`f_{RH}` is a weighted average of real time +:math:`RH` (:math:`RH_{0}`) and 30-day running mean :math:`RH` +(:math:`RH_{30d}`): .. math:: - :label: 23.8) - - f_{RH} =\left\{\begin{array}{cccc} {1} & {} & {} & {RH\le RH_{low} } \\ {\frac{RH_{up} -RH}{RH_{up} -RH_{low} } ,} & {} & {} & {RH_{low} 0.1` person km\ :sup:`-2`, we parameterize the fraction of anthropogenic and natural fires unsuppressed by human activities as .. math:: - :label: 23.10) + :label: 23.10 f_{se,o} =f_{d} f_{e} -where :math:`{f}_{d}` and :math:`{f}_{e}` are -the effects of the demographic and economic conditions on fire -occurrence. The demographic influence on fire occurrence is +where :math:`{f}_{d}` and :math:`{f}_{e}` are the effects of the +demographic and economic conditions on fire occurrence. The demographic +influence on fire occurrence is .. math:: - :label: 23.11) + :label: 23.11 - f_{d} =0.01+0.98\exp (-0.025D_{P} ). + f_{d} =0.01 + 0.98 \exp (-0.025D_{P} ). For shrub and grass PFTs, the economic influence on fire occurrence is parameterized as a function of Gross Domestic Product GDP (k 1995US$ capita\ :sup:`-1`): .. math:: - :label: 23.12) + :label: 23.12 f_{e} =0.1+0.9\times \exp [-\pi (\frac{GDP}{8} )^{0.5} ] @@ -167,19 +171,20 @@ which captures 73% of the observed MODIS fire counts with variable GDP in regions where shrub and grass PFTs are dominant (fractional coverage of shrub and grass PFTs :math:`>` 50%). In regions outside tropical closed forests and dominated by trees (fractional coverage of tree PFTs -:math:`>` 50%), we divide the MODIS fire counts into only two bins -(:math:`GDP\ge 20` k 1995US$ capita\ :sup:`-1`, and :math:`GDP<20` -k 1995US$ capita\ :sup:`-1`) and parameterize the economic -influence on fire occurrence for tree PFTs as +:math:`>` 50%), we use .. math:: - :label: 23.13) + :label: 23.13 + + f_{e} =\left\{\begin{array}{c} + {0.39} \\ {0.79} \\ {1} \end{array} + \begin{array}{cc} {} & {} \end{array}\begin{array}{c} {GDP > 20 } \\ + { 8 < GDP \le 20 } \\ { GDP \le 8 } + \end{array}\right\} \ , - f_{e} =\left\{\begin{array}{cc} {0.39,} & {GDP\ge 20} \\ {1} & {GDP<20} \end{array}\right. +to reproduce the relationship between MODIS fire counts and GDP. -to reproduce that the MODIS fire counts in tree-dominated regions of -GDP (:math:`\ge 20` k 1995US$ capita\ :sup:`-1` is 39% of that in -other tree-dominated regions. +.. _Average spread area of a fire: Average spread area of a fire ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -190,7 +195,7 @@ socioeconomic impact on the average burned area rather than separately on fire spread rate and fire duration： .. math:: - :label: 23.14) + :label: 23.14 a=a^{*} F_{se} @@ -205,19 +210,19 @@ formula for an ellipse, average burned area of a fire can be represented as: .. math:: - :label: 23.15) + :label: 23.15 a^{*} =\pi \frac{l}{2} \frac{w}{2} \times 10^{-6} =\frac{\pi u_{p}^{2} \tau ^{2} }{4L_{B} } (1+\frac{1}{H_{B} } )^{2} \times 10^{-6} -where :math:`u_{p}` \ (m s\ :sup:`-1`) is the fire spread rate in -the downwind direction; :math:`\tau` \ (s) is average fire -duration;\ :math:`L_{B}` and :math:`H_{B}` are length-to-breadth ratio -and head-to-back ratio of the ellipse; 10\ :sup:`-6` converts m\ :sup:`2` to km\ :sup:`2`. +where :math:`u_{p}` (m s\ :sup:`-1`) is the fire spread rate in the +downwind direction; :math:`\tau` (s) is average fire duration; :math:`L_{B}` +and :math:`H_{B}` are length-to-breadth ratio and head-to-back ratio of +the ellipse; 10 :sup:`-6` converts m :sup:`2` to km :sup:`2`. -According to Arora and Boer (2005), +According to :ref:`Arora and Boer (2005)`, .. math:: - :label: ZEqnNum696342 + :label: 23.16 L_{B} =1.0+10.0[1-\exp (-0.06W)] @@ -226,61 +231,55 @@ the mathematical properties of the ellipse, the head-to-back ratio :math:`H_{B}` is .. math:: - :label: ZEqnNum179757 + :label: 23.17 H_{B} =\frac{u_{p} }{u_{b} } =\frac{L_{B} +(L_{B} ^{2} -1)^{0.5} }{L_{B} -(L_{B} ^{2} -1)^{0.5} } . The fire spread rate in the downwind direction is represented as .. math:: - :label: 23.18) + :label: 23.18 u_{p} =u_{\max } C_{m} g(W) -(Arora and Boer, 2005), where :math:`u_{\max }`\ (m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread -rate in natural vegetation regions; :math:`C_{m}` and :math:`g(W)` +(:ref:`Arora and Boer, 2005`), where :math:`u_{\max }` +(m s\ :sup:`-1`) is the PFT-dependent average maximum fire spread +rate in natural vegetation regions; :math:`C_{m} =\sqrt{f_{m}}` and :math:`g(W)` represent the dependence of :math:`u_{p}` on fuel wetness and wind -speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.55 m -s\ :sup:`-1`\ for grass PFTs, 0.46 m s\ :sup:`-1` for -shrub PFTs, 0.43 m s\ :sup:`-1` for needleleaf tree PFTs, and 0.40 m s\ :sup:`-1` for other tree PFTs. -:math:`C_{m} =C_{\beta } C_{RH}` is estimated by the dependence of -:math:`u_{p}` \ on root zone soil wetness (:math:`C_{\beta }` ) and -relative humidity (:math:`C_{RH}` ). Here,\ :math:`\beta` is a root -zone soil moisture limitation function. Due to a lack of observations to -calibrate :math:`C_{\beta }` , we adopt a simple linear function, where -:math:`\beta _{low}` \ =0.3 and :math:`\beta _{up}` \ =0.7 are the lower -and upper thresholds of root zone soil wetness, respectively. -**:math:`C_{RH}` ** is set equal to :math:`f_{RH}` . :math:`g(W)` is -derived from the mathematical properties of the ellipse and Eqs and - -.. math:: - :label: 23.19) +speed :math:`W`, respectively. :math:`u_{\max }` is set to 0.33 +m s :sup:`-1`\ for grass PFTs, 0.28 m s :sup:`-1` for shrub PFTs, 0.26 +m s\ :sup:`-1` for needleleaf tree PFTs, and 0.25 m s\ :sup:`-1` for +other tree PFTs. :math:`g(W)` is derived from the mathematical properties +of the ellipse and equation :eq:`23.16` and :eq:`23.17`. + +.. math:: + :label: 23.19 g(W)=\frac{2L_{B} }{1+\frac{1}{H_{B} } } g(0). -Since g(\ *W*)=1.0, and\ :math:`L_{B}` and :math:`H_{B}` are at their -maxima\ :math:`L_{B} ^{\max } =11.0`\ and :math:`H_{B} ^{\max } =482.0` +Since g(\ *W*)=1.0, and \ :math:`L_{B}` and :math:`H_{B}` are at their +maxima \ :math:`L_{B} ^{\max } =11.0` and \ :math:`H_{B} ^{\max } =482.0` when :math:`W\to \infty` , g(0) can be derived as .. math:: - :label: 23.20) + :label: 23.20 g(0)=\frac{1+\frac{1}{H_{B} ^{\max } } }{2L_{B} ^{\max } } =0.05. In the absence of globally gridded data on barriers to fire (e.g. rivers, lakes, roads, firebreaks) and human fire-fighting efforts, average fire duration is simply assumed equal to 1 which is the observed -2001–2004 mean persistence of most fires in the world (Giglio et al. -2006). +2001–2004 mean persistence of most fires in the world +(:ref:`Giglio et al. 2006 `). As with the socioeconomic influence on fire occurrence, we assume that the socioeconomic influence on fire spreading is negligible in regions -of\ :math:`D_{p} \le 0.1` person km\ :sup:`-2`, i.e., -:math:`F_{se} =1.0`. In regions of :math:`D_{p} >0.1` person +of :math:`D_{p} \le 0.1` person km\ :sup:`-2`, i.e., +:math:`F_{se} = 1.0`. In regions of :math:`D_{p} >0.1` person km\ :sup:`-2`, we parameterize such socioeconomic influence as: .. math:: - :label: 23.21) + :label: 23.21 F_{se} =F_{d} F_{e} @@ -292,14 +291,14 @@ indices in grid cells with various dominant vegetation types. For shrub and grass PFTs, the demographic impact factor is .. math:: - :label: ZEqnNum900584 + :label: 23.22 F_{d} =0.2+0.8\times \exp [-\pi (\frac{D_{p} }{450} )^{0.5} ] and the economic impact factor is .. math:: - :label: ZEqnNum213480 + :label: 23.23 F_{e} =0.2+0.8\times \exp (-\pi \frac{GDP}{7} ). @@ -307,144 +306,154 @@ For tree PFTs outside tropical closed forests, the demographic and economic impact factors are given as .. math:: - :label: 23.24) + :label: 23.24 F_{d} =0.4+0.6\times \exp (-\pi \frac{D_{p} }{125} ) and .. math:: - :label: ZEqnNum543524 + :label: 23.25 + + F_{e} =\left\{\begin{array}{cc} + {0.62,} & {GDP>20} \\ {0.83,} & {820} \\ {0.83,} & {8` that shows the +2001-2009 average contribution of cropland fires is 4.7% of the total +global burned area. -We assume the same fuel-load requirement for all fires, so -:math:`f_{b}` is set by Eq. . The socioeconomic factor :math:`f_{se}` -is given as follows: +The socioeconomic factor :math:`f_{se}` is given as follows: .. math:: - :label: 23.31) + :label: 23.31 f_{se} =f_{d} f_{e} . Here .. math:: - :label: 23.32) + :label: 23.32 f_{d} =0.04+0.96\times \exp [-\pi (\frac{D_{p} }{350} )^{0.5} ] and .. math:: - :label: 23.33) + :label: 23.33 f_{e} =0.01+0.99\times \exp (-\pi \frac{GDP}{10} ) are the effects of population density and GDP on burned area, derived -in a similar way to Eqs. and . :math:`f_{t}` is set to 1 during the -climatological peak month for agricultural fires (van der Werf et al. -2010) in time steps with no precipitation and -*T*\ :math:`>`\ :math:`{T}_{f}` if no agricultural fires occurred -earlier in the year; :math:`{f}_{t}` is set to 0 otherwise. Peak +in a similar way to equation :eq:`23.32` and :eq:`23.33`. :math:`f_{t}` +is set to 1 at the first time step during the climatological peak month +for agricultural fires (:ref:`van der Werf et al. 2010 `); +:math:`{f}_{t}` is set to 0 otherwise. Peak month in this dataset correlates with the month after harvesting or the month before planting. In CLM we use this dataset the same way whether the CROP option is active or not, without regard to the CROP option’s simulated planting and harvesting dates. -In the post-fire region, fire impact is parameterized similar to section -18.1.3 but with combustion completeness factors and tissue mortality -factors for crop PFTs (:numref:`Table PFT-specific combustion completeness and fire mortality`). +In the post-fire region, fire impact is parameterized similar to section +:numref:`Fire impact` but with combustion completeness factors and tissue +mortality factors for crop PFTs +(:numref:`Table PFT-specific combustion completeness and fire mortality factors`). +.. _Deforestation fires: + Deforestation fires ------------------------ CLM focuses on deforestation fires in tropical closed forests. Tropical -closed forests are defined as grid cells with tropical tree coverage -:math:`>`\ 60% according to the FAO classification. Deforestation fires +closed forests are defined as grid cells with tropical tree (BET and BDT tropical) +coverage :math:`>` 60% according to the FAO classification. Deforestation fires are defined as fires caused by deforestation, including escaped deforestation fires, termed degradation fires. Deforestation and degradation fires are assumed to occur outside of cropland areas in @@ -452,71 +461,74 @@ these grid cells. Burned area is controlled by the deforestation rate and climate: .. math:: - :label: 23.34) + :label: 23.34 - A_{b} =bf_{lu} f_{cli,d} A_{g} + A_{b} = b \ f_{lu} f_{cli,d} f_{b} A_{g} -where *b* (time step)\ :sup:`-1` is a global constant; +where :math:`b` (s\ :sup:`-1`) is a global constant; :math:`f_{lu}` (fraction) represents the effect of decreasing -fractional coverage of tree PFTs derived from land use data; and +fractional coverage of tree PFTs derived from land use data; :math:`f_{cli,d}` (fraction) represents the effect of climate conditions on the burned area. -Constants *b* and :math:`{f}_{lu}` are calibrated +Constants :math:`b` and :math:`{f}_{lu}` are calibrated based on observations and reanalysis datasets in the Amazon rainforest -(tropical closed forests within 15.5ºS\ :math:`\text{-}`\ 10.5ºN, -30.5ºW\ :math:`\text{-}`\ 91ºW). *b=*\ 0.035 d\ :sup:`-1` and -:math:`f_{lu}` is defined as +(tropical closed forests within 15.5 :sup:`o` S :math:`\text{-}` 10.5 +:sup:`o` N, 30.5 :sup:`o` W :math:`\text{-}` 91 :sup:`o` W). +:math:`b` = 0.033 d\ :sup:`-1` and :math:`f_{lu}` is defined as .. math:: - :label: 23.35) + :label: 23.35 - f_{lu} =\max (0.0005,0.19D-0.0011) + f_{lu} = \max (0.0005,0.19D-0.001) -where :math:`D`\ (yr:sup:`-1`) is the annual loss of tree cover -based on CLM4’s land use and land cover change data. +where :math:`D` (yr\ :sup:`-1`) is the annual loss of tree cover +based on CLM land use and land cover change data. The effect of climate on deforestation fires is parameterized as: .. math:: - :label: ZEqnNum336915 - - \begin{array}{l} {f_{cli,d} =\max [0,\min (1,\frac{b_{2} -P_{60d} }{b_{2} } )]^{0.5} \max [0,\min (1,\frac{b_{3} -P_{10d} }{b_{3} } )]^{0.5} } \\ {\qquad \max [0,\min (1,\frac{0.25-P}{0.25} )]} \end{array} - -where\ :math:`P`\ (mm d\ :sup:`-1`) is instantaneous -precipitation, while :math:`P_{60d}` (mm d\ :sup:`-1`) and -:math:`P_{10d}` (mm d\ :sup:`-1`) are 60-day and 10-day running -means of precipitation, respectively; :math:`b_{2}` (mm -d\ :sup:`-1`) and :math:`b_{3}` (mm d\ :sup:`-1`) are the -grid-cell dependent thresholds of :math:`P_{60d}` and :math:`P_{10d}` ; -0.25 mm d\ :sup:`-1` is the maximum precipitation rate for -drizzle. Le Page et al. (2010) analyzed the relationship between -large-scale deforestation fire counts and precipitation during -2003\ :math:`\text{-}`\ 2006 in southern Amazonia where tropical -evergreen trees (BET Tropical) are dominant. Figure 2 in Le Page et al. -(2010) showed that fires generally occurred if both :math:`P_{60d}` and -:math:`P_{10d}` were less than about 4.0 mm d\ :sup:`-1`, and -fires occurred more frequently in a drier environment. Based on the -30-yr (1985:math:`\text{-}`\ 2004) precipitation data in Qian et al. -(2006), the climatological precipitation of dry months (P:math:`<`\ 4.0 -mm d\ :sup:`-1`) in a year over tropical deciduous tree (BDT -Tropical) dominated regions is 46% of that over BET Tropical dominated -regions, so we set the PFT-dependent thresholds of :math:`P_{60d}` and -:math:`P_{10d}` as 4.0 mm d\ :sup:`-1` for BET Tropical and 1.8 -mm d\ :sup:`-1` (= 4.0 mm d\ :sup:`-1` :math:`\times` 46%) -for BDT Tropical, and *b*\ :sub:`2` and *b*\ :sub:`3` are -the average of thresholds of BET Tropical and BDT Tropical weighted by -their coverage. + :label: 23.36 + + \begin{array}{ll} + f_{cli,d} \quad = & \quad \max \left[0,\min (1,\frac{b_{2} -P_{60d} }{b_{2} } )\right]^{0.5} \times \\ + & \quad \max \left[0,\min (1,\frac{b_{3} -P_{10d} }{b_{3} } )\right]^{0.5} \times \\ + & \quad \max \left[0,\min (1,\frac{0.25-P}{0.25} )\right] + \end{array} + +where :math:`P` (mm d :sup:`-1`) is instantaneous precipitation, while +:math:`P_{60d}` (mm d\ :sup:`-1`) and :math:`P_{10d}` (mm d :sup:`-1`) +are 60-day and 10-day running means of precipitation, respectively; +:math:`b_{2}` (mm d :sup:`-1`) and :math:`b_{3}` (mm d :sup:`-1`) are +the grid-cell dependent thresholds of :math:`P_{60d}` and :math:`P_{10d}` ; +0.25 mm d :sup:`-1` is the maximum precipitation rate for drizzle. +:ref:`Le Page et al. (2010) ` analyzed the relationship +between large-scale deforestation fire counts and precipitation during 2003 +:math:`\text{-}`\ 2006 in southern Amazonia where tropical evergreen trees +(BET Tropical) are dominant. Figure 2 in +:ref:`Le Page et al. (2010) ` showed that fires generally +occurred if both :math:`P_{60d}` and :math:`P_{10d}` were less than about +4.0 mm d :sup:`-1`, and fires occurred more frequently in a drier environment. +Based on the 30-yr (1985 to 2004) precipitation data in +:ref:`Qian et al. (2006) `. The climatological precipitation +of dry months (P < 4.0 mm d :sup:`-1`) in a year over tropical deciduous +tree (BDT Tropical) dominated regions is 46% of that over BET Tropical +dominated regions, so we set the PFT-dependent thresholds of :math:`P_{60d}` +and :math:`P_{10d}` as 4.0 mm d :sup:`-1` for BET Tropical and 1.8 mm d +:sup:`-1` (= 4.0 mm d :sup:`-1` :math:`\times` 46%) for BDT Tropical, and +:math:`b`\ :sub:`2` and :math:`b`\ :sub:`3` are the average of thresholds +of BET Tropical and BDT Tropical weighted bytheir coverage. The post-fire area due to deforestation is not limited to land-type conversion regions. In the tree-reduced region, the maximum fire carbon emissions are assumed to be 80% of the total conversion flux. According to the fraction of conversion flux for tropical trees in the -tree-reduced region (60%) assigned by CLM, to reach the maximum fire +tree-reduced region (60%) assigned by CLM4-CN, to reach the maximum fire carbon emissions in a conversion region requires burning this region about twice when we set PFT-dependent combustion completeness factors to -about 0.3 for stem [the mean of 0.2\ :math:`{-}`\ 0.4 used in van -der Werf (2010)]. Therefore, when the burned area calculated from Eq. is +about 0.3 for stem [the mean of 0.2\ :math:`{-}`\ 0.4 used in +:ref:`van der Werf et al. (2010) `. Therefore, when +the burned area calculated from equation :eq:`23.36` is no more than twice the tree-reduced area, we assume no escaped fires outside the land-type conversion region, and the fire-related fraction of the total conversion flux is estimated as @@ -524,7 +536,9 @@ of the total conversion flux is estimated as conversion flux is assumed to be fire carbon emissions, and the biomass combustion and vegetation mortality outside the tree-reduced regions with an area fraction of :math:`\frac{A_{b} }{A_{g} } -2D` are set as in -section 18.1.3. +section :numref:`Fire impact`. + +.. _Peat fires: Peat fires --------------- @@ -532,102 +546,125 @@ Peat fires The burned area due to peat fires is given as :math:`{A}_{b}`: .. math:: - :label: 23.37) + :label: 23.37 - A_{b} =cf_{cli,p} f_{peat} (1-f_{sat} )A_{g} + A_{b} = c \ f_{cli,p} f_{peat} (1 - f_{sat} ) A_{g} -where *c* (time step)\ :sup:`-1` is a constant; :math:`f_{cli,p}` -represents the effect of climate on the burned area;\ :math:`f_{peat}` -is the fractional coverage of peatland in the grid cell; and -:math:`f_{sat}` is the fraction of the grid cell with a water table at -the surface or higher. *c*\ =1.0\ :math:`\times`\ 10\ :sup:`-3` hr\ :sup:`-1` for tropical peat fires and -*c*\ =4.2\ :math:`\times`\ 10\ :sup:`-5` hr\ :sup:`-1` for boreal peat fires are derived using an inverse -method, by matching simulations from an unreleased -CLM4.5 version driven by Qian et al. (2006) atmospheric forcing and -climatological lightning data to earlier studies: about 2.4 Mha peatland -was burned over Indonesia in 1997 (Page et al. 2002) and the average -burned area of peat fires in Western Canada was 0.2 Mha -yr\ :sup:`-1` for 1980-1999 (Turestky et al. 2004). +where :math:`c` (s\ :sup:`-1`) is a constant; :math:`f_{cli,p}` represents +the effect of climate on the burned area; :math:`f_{peat}` is the fractional +coverage of peatland in the grid cell; and :math:`f_{sat}` is the fraction +of the grid cell with a water table at the surface or higher. :math:`c` = 0.17 +:math:`\times` 10 :sup:`-3` hr\ :sup:`-1` for tropical peat fires and +:math:`c` = 0.9 :math:`\times` 10 :sup:`-5` hr :sup:`-1` for boreal peat fires +are derived using an inverse method, by matching simulations to earlier +studies: about 2.4 Mha peatland was burned over Indonesia in 1997 +(:ref:`Page et al. 2002 `) and the average burned area of peat +fires in Western Canada was 0.2 Mha yr :sup:`-1` for 1980-1999 +(:ref:`Turetsky et al. 2004 `). For tropical peat fires, :math:`f_{cli,p}` is set as a function of long-term precipitation :math:`P_{60d}` : .. math:: - :label: 23.38) + :label: 23.38 - f_{cli,p} =\max [0,\min (1,\frac{4-P_{60d} }{4} )]^{2} . + f_{cli,p} = \ max \left[0,\min \left(1,\frac{4-P_{60d} }{4} \right)\right]^{2} . For boreal peat fires, :math:`f_{cli,p}` is set to .. math:: - :label: 23.39) + :label: 23.39 f_{cli,p} = \exp (-\pi \frac{\theta _{17cm} }{0.3} )\cdot \max [0,\min (1,\frac{T_{17cm} -T_{f} }{10} )] -where :math:`\theta _{17cm}` and :math:`T_{17cm}` are the wetness and -temperature of the top 17 cm of soil; :math:`T_{f}` \ =273.15 K is the -freezing temperature. +where :math:`\theta _{17cm}` is the wetness of the top 17 cm of soil. + +Peat fires lead to peat burning and the combustion and mortality of +vegetation over peatlands. For tropical peat fires, based on +:ref:`Page et al. (2002) `, about 6% of the peat carbon loss +from stored carbon is caused by 33.9% of the peatland burned. Carbon emissions +due to peat burning (g C m\ :sup:`-2` s\ :sup:`-1`) are therefore set as the +product of 6%/33.9%, burned area fraction of peat fire (s\ :sup:`-1`), and +soil organic carbon (g C m\ :sup:`-2`). For boreal peat fires, the carbon +emissions due to peat burning are set as 2.2 kg C m\ :sup:`-2` \ peat fire +area (:ref:`Turetsky et al. 2002 `). Biomass combustion +and vegetation mortality in post-fire peatlands are set the same as section +:numref:`Fire impact` for non-crop PFTs and as section +:numref:`Agricultural fires` for crops PFTs. -Peat fires lead to peat combustion and the combustion and mortality of -vegetation in peatlands. For tropical peat fires, based on Page et al. -(2002), about 6% of the peat carbon loss from stored carbon is caused by -33.9% of the peatland burned. Carbon emissions due to peat combustion (g C m\ :sup:`-2` (time step)\ :sup:`-1`) are therefore set as -the product of 6%/33.9%, by burned area fraction of peat fire ((time -step)\ :sup:`-1`), by soil organic carbon (g C m\ :sup:`-2`). For boreal peat fires, the carbon emissions due to -peat combustion are set as 2.2 kg C m\ :sup:`-2`\ peat fire area (Turetsky et al. -2002). Biomass combustion and vegetation mortality in post-fire -peatlands are set the same as section 18.1.3 for non-crop PFTs and as -section 18.2 for crops PFTs. +.. _Fire trace gas and aerosol emissions: -.. _Table PFT-specific combustion completeness and fire mortality: +Fire trace gas and aerosol emissions +------------------------------------- +CESM2 is the first Earth system model that can model the full coupling +among fire, fire emissions, land, and atmosphere. CLM5, as the land +component of CESM2, calculates the surface trace gas and aerosol emissions +due to fire and fire emission heights, as the inputs of atmospheric +chemistry model and aerosol model. + +Emissions for trace gas and aerosol species x and the j-th PFT, :math:`E_{x,j}` +(g species s\ :sup:`-1`), are given by + +.. math:: + :label: 23.40 + + E_{x,j} = EF_{x,j}\frac{\phi _{j} }{[C]}. + +Here, :math:`EF_{x,j}` (g species (g dm)\ :sup:`-1`) is PFT-dependent emission +factor scaled from biome-level values (Li et al., in prep, also used for FireMIP +fire emissions data) by Dr. Val Martin and Dr. Li. :math:`[C]` = 0.5 +(g C (g dm)\ :sup:`-1`) is a conversion factor from dry matter to carbon. + +Emission height is PFT-dependent: 4.3 km for needleleaf tree PFTs, 3 km for other +boreal and temperate tree PFTs, 2.5 km for tropical tree PFTs, 2 km for shrub +PFTs, and 1 km for grass and crop PFTs. These values are compiled from earlier +studies by Dr. Val Martin. + +.. _Table PFT-specific combustion completeness and fire mortality factors: .. table:: PFT-specific combustion completeness and fire mortality factors. +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem` | :math:`\xi`\ :sub:`j` | + | PFT | *CC*\ :sub:`leaf` | *CC*\ :sub:`stem` | *CC*\ :sub:`root` | *CC*\ :sub:`ts` | *M*\ :sub:`leaf` | *M*\ :sub:`livestem,1` | *M*\ :sub:`deadstem` | *M*\ :sub:`root` | *M*\ :sub:`ts` | *M*\ :sub:`livestem,2` | :math:`\xi`\ :sub:`j` | +==================================+===========================+===========================+===========================+=========================+==========================+==============================+==============================+==========================+========================+==============================+=================================+ - | NET Temperate | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | - +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | NET Boreal | 0.80 | 0.25 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | + | NET Temperate | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | NDT Boreal | - | - | - | - | - | - | - | - | - | - | - | + | NET Boreal | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BET Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | + | NDT Boreal | 0.80 | 0.30 | 0.00 | 0.50 | 0.80 | 0.15 | 0.15 | 0.15 | 0.50 | 0.35 | 0.15 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BET Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | + | BET Tropical | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDT Tropical | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | + | BET Temperate | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDT Temperate | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | + | BDT Tropical | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDT Boreal | 0.80 | 0.22 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | + | BDT Temperate | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.10 | 0.10 | 0.10 | 0.35 | 0.25 | 0.10 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BES Temperate | - | - | - | - | - | - | - | - | - | - | - | + | BDT Boreal | 0.80 | 0.27 | 0.00 | 0.45 | 0.80 | 0.13 | 0.13 | 0.13 | 0.45 | 0.32 | 0.13 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDS Temperate | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | + | BES Temperate | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | BDS Boreal | 0.80 | 0.30 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | + | BDS Temperate | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + | BDS Boreal | 0.80 | 0.35 | 0.00 | 0.55 | 0.80 | 0.17 | 0.17 | 0.17 | 0.55 | 0.38 | 0.17 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + | C\ :sub:`3` Grass Arctic | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + | C\ :sub:`3` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | Crop 1 | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | - | + | C\ :sub:`4` Grass | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ - | Crop 2 | - | - | - | - | - | - | - | - | - | - | - | + | Crop | 0.80 | 0.80 | 0.00 | 0.80 | 0.80 | 0.20 | 0.20 | 0.20 | 0.80 | 0.60 | 0.20 | +----------------------------------+---------------------------+---------------------------+---------------------------+-------------------------+--------------------------+------------------------------+------------------------------+--------------------------+------------------------+------------------------------+---------------------------------+ -Leaves (:math:`CC_{{\rm leaf}}` ), stems (:math:`CC_{{\rm stem}}` ), -roots (:math:`CC_{{\rm root}}` ) , and transfer and storage carbon -(:math:`CC_{{\rm ts}}` ); mortality factors for leaves -(:math:`M_{{\rm leaf}}` ), live stems (:math:`M_{{\rm livestem,1}}` ), -dead stems (:math:`M_{{\rm deadstem}}` ), roots -(:math:`M_{{\rm root}}` ), and transfer and storage carbon -(:math:`M_{{\rm ts}}` ) related to the carbon transfers from these pools +Leaves (:math:`CC_{leaf}` ), stems (:math:`CC_{stem}` ), +roots (:math:`CC_{root}` ) , and transfer and storage carbon +(:math:`CC_{ts}` ); mortality factors for leaves +(:math:`M_{leaf}` ), live stems (:math:`M_{livestem,1}` ), +dead stems (:math:`M_{deadstem}` ), roots +(:math:`M_{root}` ), and transfer and storage carbon +(:math:`M_{ts}` ) related to the carbon transfers from these pools to litter pool; mortality factors for live stems -(:math:`M_{{\rm livestem,2}}` ) related to the carbon transfer from live +(:math:`M_{livestem,2}` ) related to the carbon transfer from live stems to dead stems; whole-plant mortality factor (:math:`\xi _{j}` ). -Parameters are calibrated in an unreleased CLM4.5 version driven by Qian -et al. (2006) atmospheric forcing and climatological lightning data. diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 404943dd97..8b9a9df144 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -38,7 +38,7 @@ al. 2008) ` and :math:`\Delta t` is the time step (s). .. _Figure Hydrologic processes: -.. Figure:: image1.png +.. Figure:: hydrologic.processes.png Hydrologic processes represented in CLM. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index be084381b3..724fd493f8 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1048,6 +1048,12 @@ Li, F., Levis, S., and Ward, D. S. 2013a. Quantifying the role of fire in the Earth system – Part 1: Improved global fire modeling in the Community Earth System Model (CESM1). Biogeosciences 10:2293-2314. +.. _LiLawrence2017: + +Li, F., and Lawrence, D. 2017. Role of fire in the global land water +budget during the 20th century through changing ecosystems. +J. Clim. 30: 1894-1908. + .. _Lietal2013b: Li, H.-Y., Huang, M., Tesfa, T., Ke, Y., Sun, Y., Liu, Y., and Leung, L. From db54a61e329f96e2724d328e4a13ec74bc0cab0f Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 8 Jun 2017 11:22:27 -0600 Subject: [PATCH 057/255] update Offline Chapter --- .../tech_note/Offline/CLM50_Tech_Note_Offline.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst index 0419ec668e..f41a24a1d6 100644 --- a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst +++ b/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst @@ -8,14 +8,14 @@ forcing required by CLM (:numref:`Table Atmospheric input to land model`) is supplied by observed datasets. The standard forcing provided with the model is a 110-year (1901-2010) dataset provided by the Global Soil Wetness Project (GSWP3; NEED A REFERENCE). The GSWP3 dataset has a spatial resolution of -0.5\ :math:`{}^o` X 0.5\ :math:`{}^o` and a temporal resolution of three +0.5\ :sup:`o` X 0.5\ :sup:`o` and a temporal resolution of three hours. An alternative forcing dataset is also available, CRUNCEP, a 110-year (1901-2010) dataset (CRUNCEP; :ref:`Viovy 2011 `) that is a combination of two existing datasets; -the CRU TS3.2 0.5\ :math:`{}^o` X 0.5\ :math:`{}^o` monthly data covering the period +the CRU TS3.2 0.5\ :sup:`o` X 0.5\ :sup:`o` monthly data covering the period 1901 to 2002 (:ref:`Mitchell and Jones 2005 `) -and the NCEP reanalysis 2.5\ :math:`{}^o` X 2.5\ :math:`{}^o` +and the NCEP reanalysis 2.5\ :sup:`o` X 2.5\ :sup:`o` 6-hourly data covering the period 1948 to 2010. The CRUNCEP dataset has been used to force CLM for studies of vegetation growth, evapotranspiration, and gross primary production (:ref:`Mao et al. 2012 `, @@ -27,7 +27,7 @@ here (:ref:`Viovy 2011 `). Here, the GSWP3 dataset, which does not include data for particular fields over oceans, lakes, and Antarctica is modified. This missing data is filled with :ref:`Qian et al. (2006) ` data from 1948 that is interpolated by the data atmosphere -model to the 0.5\ :math:`{}^o` GSWP3 grid. This allows the model +model to the 0.5\ :sup:`o` GSWP3 grid. This allows the model to be run over Antarctica and ensures data is available along coastlines regardless of model resolution. @@ -239,13 +239,13 @@ anomalies, respectively: \begin{array}{lr} S^{'} = S + k_{anomaly} & \quad {\rm state \ variable} \\ - F^{'} = f * k_{anomaly} & \quad {\rm flux \ variable} + F^{'} = f \times k_{anomaly} & \quad {\rm flux \ variable} \end{array} where :math:`S^{'}` is the adjusted atmospheric state variable, :math:`S` is the state variable from the high-frequency reference atmospheric forcing dataset, and :math:`k_{anomaly}` is an additive anomaly. -Similarly, math:`F^{'}` is the adjusted atmospheric flux variable, +Similarly, :math:`F^{'}` is the adjusted atmospheric flux variable, :math:`F` is the flux variable from the high-frequency reference atmospheric forcing dataset, and :math:`k_{anomaly}` is a multiplicative anomaly. State variables are temperature :math:`T_{atm}`, From f237ae31a4af2a23c38ff9b00e3d1f995e8c0631 Mon Sep 17 00:00:00 2001 From: djk2120 Date: Thu, 8 Jun 2017 15:09:24 -0400 Subject: [PATCH 058/255] PHS update: including flow diagram, numerical implementation, and other edits --- ...CLM50_Tech_Note_Plant_Hydraulic_Stress.rst | 352 ++++++++++++++++-- 1 file changed, 313 insertions(+), 39 deletions(-) diff --git a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst index d8bad01423..d49d3a04b3 100644 --- a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst +++ b/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst @@ -3,7 +3,14 @@ Plant Hydraulic Stress ====================== -Introductory text... +The Plant Hydraulic Stress (PHS) routine explicitly models water transport through the vegetation according to a simple hydraulic framework following Darcy's Law for porous media flow equations influenced by +:ref:`Bonan et al. (2014) `, +:ref:`Chuang et al. (2006) `, +:ref:`Sperry et al. (1998) `, +:ref:`Sperry and Love (2015) `, +:ref:`Williams et al (1996) `. + +PHS solves for the vegetation water potential that matches water supply with transpiration demand. Water supply is modeled according to the circuit analog in :numref:`Figure Soil Temperature Schematic`. Transpiration demand is modeled relative to maximum transpiration by a transpiration loss function dependent on leaf water potential. .. _Figure Soil Temperature Schematic: @@ -16,18 +23,16 @@ Introductory text... Plant Water Supply ----------------------- -PHS explicitly models water transport through the vegetation according to a simple hydraulic framework following Darcy's Law for porous media flow equations. The supply equations are used to solve for vegetation water potential forced by a given transpiration and the set of layer-by-layer soil water potentials. - +The supply equations are used to solve for vegetation water potential forced by transpiration demand and the set of layer-by-layer soil water potentials. The water supply is discretized into segments: soil-to-root, root-to-stem, and stem-to-leaf. There are typically several (1-49) soil-to-root flows operating in parallel, one per soil layer. There are two stem-to-leaf flows operating in parallel, corresponding to the sunlit and shaded "leaves". -In general the water fluxes (e.g. soil-to-root, root-to-stem, etc) are calculated as: +In general the water fluxes (e.g. soil-to-root, root-to-stem, etc.) are modeled according to Darcy's Law for porous media flow as: .. math:: - :label: 11.1) + :label: 11.101) q = kA\left( \psi_1 - \psi_2 \right) - :math:`q` is the flux of water (mmH\ :sub:`2`\ O) spanning the segment between :math:`\psi_1` and :math:`\psi_2` :math:`k` is the hydraulic conductance (s\ :sup:`-1`\ ) @@ -36,8 +41,11 @@ In general the water fluxes (e.g. soil-to-root, root-to-stem, etc) are calculate :math:`\psi_1 - \psi_2` is the gradient in water potential (mmH\ :sub:`2`\ O) across the segment +The segments in :numref:`Figure Soil Temperature Schematic` have variable resistance, as the water potentials become lower, hydraulic conductance decreases. +This is captured by multiplying the maximum segment conductance by a sigmoidal function capturing the percent loss of conductivity. The function uses two parameters to fit experimental vulnerability curves: the water potential at 50% loss of conductivity (:math:`p50`) and a shape fitting parameter (:math:`c_k`). + .. math:: - :label: 11.2) + :label: 11.102) k=k_{max}\cdot 2^{-\left(\dfrac{\psi_1}{p50}\right)^{c_k}} @@ -47,35 +55,40 @@ In general the water fluxes (e.g. soil-to-root, root-to-stem, etc) are calculate :math:`\psi_1` is the water potential of the lower segment terminus (mmH2O) +.. _Stem-to-leaf: + +Stem-to-leaf +'''''''''''''''''''''''' + The area basis and conductance parameterization varies by segment. There are two stem-to-leaf fluxes in parallel, from stem to sunlit leaf and from stem to shaded leaf (:math:`q_{1a}` and :math:`q_{1a}`). The water flux from stem-to-leaf is the product of the segment conductance, the conducting area basis, and the water potential gradient from stem to leaf. Stem-to-leaf conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve. The maximum conductance is a PFT parameter representing the maximum conductance of water from stem to leaf per unit leaf area. This parameter can be defined separately for sunlit and shaded segments and should already include the appropriate length scaling (in other words this is a conductance, not conductivity). The water potential gradient is the difference between leaf water potential and stem water potential. There is no gravity term, assuming a negligible difference in height across the segment. The area basis is the leaf area index (either sunlit or shaded). .. math:: - :label: 11.3) + :label: 11.103) - q_{1a}=k_{1a}*\mbox{LAI}_{sun}*\left(\psi_{stem}-\psi_{sunleaf} \right) + q_{1a}=k_{1a}\cdot\mbox{LAI}_{sun}\cdot\left(\psi_{stem}-\psi_{sunleaf} \right) .. math:: - :label: 11.4) + :label: 11.104) - q_{1b}=k_{1b}*\mbox{LAI}_{shade}*\left(\psi_{stem}-\psi_{shadeleaf} \right) + q_{1b}=k_{1b}\cdot\mbox{LAI}_{shade}\cdot\left(\psi_{stem}-\psi_{shadeleaf} \right) .. math:: - :label: 11.5) + :label: 11.105) - k_{1a}=k_{1a,max}*2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} + k_{1a}=k_{1a,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} .. math:: - :label: 11.6) + :label: 11.106) - k_{1b}=k_{1b,max}*2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} + k_{1b}=k_{1b,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} Variables: :math:`q_{1a}` = flux of water (mmH2O/s) from stem to sunlit leaf - +12 :math:`q_{1b}` = flux of water (mmH2O/s) from stem to shaded leaf :math:`LAI_{sun}` = sunlit leaf area index (m2/m2) @@ -98,15 +111,20 @@ Parameters: :math:`c_{k}` = vulnerability curve shape-fitting parameter (-) +.. _Root-to-stem: + +Root-to-stem +'''''''''''''''''''''''' + There is one root-to-stem flux. This represents a flux from the root collar to the upper branch reaches. The water flux from root-to-stem is the product of the segment conductance, the conducting area basis, and the water potential gradient from root to stem. Root-to-stem conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve (two parameters). The maximum conductance is defined as the maximum root-to-stem conductivity per unit stem area (PFT parameter) divided by the length of the conducting path, which is taken to be the vegetation height. The area basis is the stem area index. The gradient in water potential is the difference between the root water potential and the stem water potential less the difference in gravitational potential. .. math:: - :label: 11.7) + :label: 11.107) q_2=k_2 \cdot SAI \cdot \left( \psi_{root} - \psi_{stem} - \Delta \psi_z \right) .. math:: - :label: 11.8) + :label: 11.108) k_2=\dfrac{k_{2,max}}{z_2} \cdot 2^{-\left(\dfrac{\psi_{root}}{p50_2}\right)^{c_k}} @@ -130,6 +148,11 @@ Parameters: :math:`z_2` = vegetation height (m) +.. _Soil-to-root: + +Soil-to-root +'''''''''''''''''''''''' + There are several soil-to-root fluxes operating in parallel (one for each root-containing soil layer). Each represents a flux from the given soil layer to the root collar. The water flux from soil-to-root is the product of the segment conductance, the conducting area basis, and the water potential gradient from soil to root. The area basis is a proxy for root area index, defined as the summed leaf and stem area index multiplied by the root-to-shoot ratio (PFT parameter) multiplied by the layer root fraction. The root fraction comes from an empirical root profile (see section zqz). The gradient in water potential is the difference between the soil water potential and the root water potential less the difference in gravitational potential. There is only one root water potential to which all soil layers are connected in parallel. A soil-to-root flux can be either positive (vegetation water uptake) or negative (water deposition), depending on the relative values of the root and soil water potentials. This allows for the occurrence of hydraulic redistribution where water moves through vegetation tissue from one soil layer to another. @@ -139,37 +162,37 @@ Soil-to-root conductance is the result of two resistances in series, first acros The soil-root interface conductance is defined as the soil conductivity divided by the conducting length from soil to root. The soil conductivity varies by soil layer and is calculated based on soil potential and soil properties, via the Brooks-Corey theory. The conducting length is computed by calculating the characteristic root spacing following Bonan-2014. The root spacing depends on total root biomass and PFT parameters defining root structure (see section zqz). .. math:: - :label: 11.9) + :label: 11.109) q_{3,i}=k_{3,i}*RAI*\left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right) .. math:: - :label: 11.10) + :label: 11.110) RAI=\left(LAI+SAI \right)\cdot r_i \cdot f_{root-leaf} .. math:: - :label: 11.11) + :label: 11.111) k_{3,i}=\dfrac{k_{r,i}*k_{s,i}}{k_{r,i}+k_{s,i}} .. math:: - :label: 11.12) + :label: 11.112) k_{r,i}=\dfrac{k_{3,max}}{z_{3,i}}*2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}} .. math:: - :label: 11.13) + :label: 11.113) k_{s,i} = \dfrac{k_{soil,i}}{dx_{root,i}} .. math:: - :label: 11.14) + :label: 11.114) dx_{root,i} = \left(\pi*\mbox{root-length-density}_i\right)^{-0.5} .. math:: - :label: 11.15) + :label: 11.115) \mbox{root-length-density} = \dfrac{\mbox{total root length}}{\mbox{soil volume}} @@ -206,25 +229,35 @@ Parameters: Plant Water Demand ----------------------- +Plant water demand depends on stomatal conductance, which is described in section :numref:`Stomatal resistance`. +Here we describe the influence of PHS and the coupling of vegetation water demand and supply. +PHS models vegetation water demand as transpiration attenuated by a transpiration loss function based on leaf water potential. +Sunlit leaf transpiration is modeled as the maximum sunlit leaf transpiration multiplied by the percent of maximum transpiration as modeled by the sigmoidal loss function. +The same follows for shaded leaf transpiration. +Maximum stomatal conductance is calculated from the Medlyn model :ref:`(Medlyn et al. 2011) ` absent water stress and used to calculate the maximum transpiration (see section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). +Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. +Water stress is calculated with distinct values for sunlit and shaded leaves. +Vegetation water stress is calculated based on leaf water potential and is used to attenuate photosynthesis (see section :numref:`Photosynthesis`) + .. math:: - :label: 11.16) + :label: 11.201) - E_{sun} = E_{sun,max}*2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} + E_{sun} = E_{sun,max} \cdot 2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} .. math:: - :label: 11.17) + :label: 11.202) - E_{shade} = E_{shade,max}*2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}} + E_{shade} = E_{shade,max} \cdot 2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}} .. math:: - :label: 11.18) + :label: 11.203) - B_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,B_t=1}} + \beta_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,\beta_t=1}} .. math:: - :label: 11.19) + :label: 11.204) - B_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,B_t=1}} + \beta_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,\beta_t=1}} :math:`E_{sun}` = sunlit leaf transpiration (mm/s) @@ -238,6 +271,10 @@ Plant Water Demand :math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH2O) +:math:`\beta_{t,sun}` = sunlit transpiration water stress (-) + +:math:`\beta_{t,shade}` = shaded transpiration water stress (-) + :math:`g_{s,sun}` = stomatal conductance of water corresponding to :math:`E_{sun}` :math:`g_{s,shade}` = stomatal conductance of water corresponding to :math:`E_{shade}` @@ -251,15 +288,15 @@ Plant Water Demand Vegetation Water Potential ----------------------------- -PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential at each timestep. PHS iterates to find the vegetation water potential vector :math:`\psi` that satisfies continuity in the non-linear vegetation water supply and demand equations. +Both plant water supply and demand are functions of vegetation water potential. PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential at each timestep. PHS iterates to find the vegetation water potential :math:`\psi` (vector) that satisfies continuity between the non-linear vegetation water supply and demand (equations :eq:`11.103)`, :eq:`11.104)`, :eq:`11.107)`, :eq:`11.109)`, :eq:`11.201)`, :eq:`11.202)`). .. math:: - :label: 11.20) + :label: 11.301) \psi=\left[\psi_{sunleaf},\psi_{shadeleaf},\psi_{stem},\psi_{root}\right] .. math:: - :label: 11.21 + :label: 11.302) \begin{aligned} E_{sun}&=q_{1a}\\ @@ -269,15 +306,252 @@ PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential a &=\sum_{i=1}^{nlevsoi}{q_{3,i}} \end{aligned} -The demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy :eq:`11.21`. +PHS finds the water potentials that match supply and demand. In the plant water transport equations :eq:`11.302)`, the demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy continuity :eq:`11.302)`. + + + +.. _PHS Numerical Implementation: + +Numerical Implementation +-------------------------------- + +The four plant water potential nodes are ( :math:`\psi_{root}`, :math:`\psi_{xylem}`, :math:`\psi_{shadeleaf}`, :math:`\psi_{sunleaf}`). +The fluxes between each pair of nodes are labeled in Figure 1. +:math:`E_{sun}` and :math:`E_{sha}` are the transpiration from sunlit and shaded leaves, respectively. +We use the circuit-analog model to calculate the vegetation water potential ( :math:`\psi`) for the four plant nodes, forced by soil matric potential and unstressed transpiration. +The unstressed transpiration is acquired by running the photosynthesis model with :math:`\beta_t=1`. +The unstressed transpiration flux is attenuated based on the leaf-level vegetation water potential. +Using the attenuated transpiration, we solve for :math:`g_{s,stressed}` and output :math:`\beta_t=\dfrac{g_{s,stressed}}{g_{s,unstressed}}`. + +The continuity of water flow through the system yields four equations + +.. math:: + :label: 11.401) + + \begin{aligned} + E_{sun}&=q_{1a}\\ + E_{shade}&=q_{1b}\\ + q_{1a}+q_{1b}&=q_2\\ + q_2&=\sum_{i=1}^{nlevsoi}{q_{3,i}} + \end{aligned} + + +We seek the set of vegetation water potential values, + +.. math:: + :label: 11.402) + + \psi=\left[ \begin {array}{c} + \psi_{sunleaf}\cr\psi_{shadeleaf}\cr\psi_{stem}\cr\psi_{root} + \end {array} \right] + +that satisfies these equations, as forced by the soil moisture and atmospheric state. +Each flux on the schematic can be represented in terms of the relevant water potentials. Defining the transpiration fluxes: + +.. math:: + :label: 11.403) + + \begin{aligned} + E_{sun} &= E_{sun,max} \cdot 2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} \\ + E_{shade} &= E_{shade,max} \cdot 2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}} + \end{aligned} + +Defining the water supply fluxes: + +.. math:: + :label: 11.404) + + \begin{aligned} + q_{1a}&=k_{1a,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} \cdot\mbox{LAI}_{sun}\cdot\left(\psi_{stem}-\psi_{sunleaf} \right) \\ + q_{1b}&=k_{1b,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}}\cdot\mbox{LAI}_{shade}\cdot\left(\psi_{stem}-\psi_{shadeleaf} \right) \\ + q_2&=\dfrac{k_{2,max}}{z_2} \cdot 2^{-\left(\dfrac{\psi_{root}}{p50_2}\right)^{c_k}} \cdot SAI \cdot \left( \psi_{root} - \psi_{stem} - \Delta \psi_z \right) \\ + q_{soil}&=\sum_{i=1}^{nlevsoi}{q_{3,i}}=\sum_{i=1}^{nlevsoi}{k_{3,i}\cdot RAI\cdot\left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right)} + \end{aligned} + +We're looking to find the vector :math:`\psi` +that fits with soil and atmospheric forcings while satisfying water flow continuity. +Due to the model non-linearity, we use a linearized explicit approach, iterating with Newton's method. +The initial guess is the solution for :math:`\psi` (vector) from the previous time step. +The general framework, from iteration `m` to `m+1` is: + +.. math:: + :label: 11.405) + + q^{m+1}=q^m+\dfrac{\delta q}{\delta\psi}\Delta\psi \\ + \psi^{m+1}=\psi^{m}+\Delta\psi + +So for our first flux balance equation, at iteration `m+1`, we have: + +.. math:: + :label: 11.406) + + E_{sun}^{m+1}=q_{1a}^{m+1} + +Which can be linearized to: + +.. math:: + :label: 11.407) + + E_{sun}^{m}+\dfrac{\delta E_{sun}}{\delta\psi}\Delta\psi=q_{1a}^{m}+\dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi + +And rearranged to be: + +.. math:: + :label: 11.408) + + \dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi-\dfrac{\delta E_{sun}}{\delta\psi}\Delta\psi=E_{sun}^{m}-q_{1a}^{m} + +And for the other 3 flux balance equations: + +.. math:: + :label: 11.409) + + \begin{aligned} + \dfrac{\delta q_{1b}}{\delta\psi}\Delta\psi-\dfrac{\delta E_{sha}}{\delta\psi}\Delta\psi&=E_{sha}^{m}-q_{1b}^{m} \\ + \dfrac{\delta q_2}{\delta\psi}\Delta\psi-\dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi-\dfrac{\delta q_{1b}}{\delta\psi}\Delta\psi&=q_{1a}^{m}+q_{1b}^{m}-q_2^{m} \\ + \dfrac{\delta q_{soil}}{\delta\psi}\Delta\psi-\dfrac{\delta q_2}{\delta\psi}\Delta\psi&=q_2^{m}-q_{soil}^{m} + \end{aligned} + +Putting all four together in matrix form: + +.. math:: + :label: 11.410) + + \left[ \begin {array}{c} + \dfrac{\delta q_{1a}}{\delta\psi}-\dfrac{\delta E_{sun}}{\delta\psi} \cr + \dfrac{\delta q_{1b}}{\delta\psi}-\dfrac{\delta E_{sha}}{\delta\psi} \cr + \dfrac{\delta q_2}{\delta\psi}-\dfrac{\delta q_{1a}}{\delta\psi}-\dfrac{\delta q_{1b}}{\delta\psi} \cr + \dfrac{\delta q_{soil}}{\delta\psi}-\dfrac{\delta q_2}{\delta\psi} + \end {array} \right] + \Delta\psi= + \left[ \begin {array}{c} + E_{sun}^{m}-q_{1a}^{m} \cr + E_{sha}^{m}-q_{1b}^{m} \cr + q_{1a}^{m}+q_{1b}^{m}-q_2^{m} \cr + q_2^{m}-q_{soil}^{m} + \end {array} \right] + +Now to expand the left-hand side, from generic :math:`\psi` to all four plant water potential nodes, noting that many derivatives are zero (e.g. :math:`\dfrac{\delta E_{sun}}{\delta\psi_{sha}}=0`) + +Introducing the notation: +:math:`A\Delta\psi=b` + +.. math:: + :label: 11.411) + + \Delta\psi=\left[ \begin {array}{c} + \Delta\psi_{sunleaf} \cr + \Delta\psi_{shadeleaf} \cr + \Delta\psi_{stem} \cr + \Delta\psi_{root} + \end {array} \right] + +.. math:: + :label: 11.412) + + A= + \left[ \begin {array}{cccc} + \dfrac{\delta q_{1a}}{\delta \psi_{sun}}-\dfrac{\delta E_{sun}}{\delta \psi_{sun}}&0&\dfrac{\delta q_{1a}}{\delta \psi_{stem}}&0\cr + 0&\dfrac{\delta q_{1b}}{\delta \psi_{sha}}-\dfrac{\delta E_{sha}}{\delta \psi_{sha}}&\dfrac{\delta q_{1b}}{\delta \psi_{stem}}&0\cr + -\dfrac{\delta q_{1a}}{\delta \psi_{sun}}& + -\dfrac{\delta q_{1b}}{\delta \psi_{sha}}& + \dfrac{\delta q_2}{\delta \psi_{stem}}-\dfrac{\delta q_{1a}}{\delta \psi_{stem}}-\dfrac{\delta q_{1b}}{\delta \psi_{stem}}& + \dfrac{\delta q_2}{\delta \psi_{root}}\cr + 0&0&-\dfrac{\delta q_2}{\delta \psi_{stem}}&\dfrac{\delta q_{soil}}{\delta \psi_{root}}-\dfrac{\delta q_2}{\delta \psi_{root}} + \end {array} \right] + +.. math:: + :label: 11.413) + + b= + \left[ \begin {array}{c} + E_{sun}^{m}-q_{b1}^{m} \cr + E_{sha}^{m}-q_{b2}^{m} \cr + q_{b1}^{m}+q_{b2}^{m}-q_{stem}^{m} \cr + q_{stem}^{m}-q_{soil}^{m} + \end {array} \right] + +Now we compute all the entries for :math:`A` and :math:`b` based on the soil moisture and maximum transpiration forcings and can solve to find: + +.. math:: + :label: 11.414) + + \Delta\psi=A^{-1}b .. math:: - :label: 11.22) + :label: 11.415) + + \psi_{m+1}=\psi_m+\Delta\psi + +We iterate until :math:`b\to 0`, signifying water flux balance through the system. The result is a final set of water potentials ( :math:`\psi_{root}`, :math:`\psi_{xylem}`, :math:`\psi_{shadeleaf}`, :math:`\psi_{sunleaf}`) satisfying non-divergent water flux through the system. +The magnitude of the water flux is driven by soil matric potential and unstressed ( :math:`\beta_t=1`) transpiration. + +We use the transpiration solution (corresponding to the final solution for :math:`\psi`) to compute stomatal conductance. The stomatal conductance is then used to compute :math:`\beta_t`. + +.. math:: + :label: 11.416) + + \beta_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,\beta_t=1}} + +.. math:: + :label: 11.417) + + \beta_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,\beta_t=1}} + +The :math:`\beta_t` values are used in the Photosynthesis module (see section :numref:`Photosynthesis`) to apply water stress. +The solution for :math:`\psi` is saved as a new variable (vegetation water potential) and is indicative of plant water status. +The soil-to-root fluxes :math:`\left( q_{3,1},q_{3,2},\mbox{...},q_{3,n}\right)` are used as the soil transpiration sink in the Richards' equation subsurface flow equations (see section :numref:`Soil Water`). + +.. _Flow Diagram of Leaf Flux Calculations: + +Flow Diagram of Leaf Flux Calculations: +------------------------------------------- + +PHS runs nested in the loop that solves for sensible and latent heat fluxes and temperature for vegetated surfaces (see section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). +The scheme iterates for convergence of leaf temperature (:math:`T_l`), transpiration water stress (:math:`\beta_t`), and intercellular CO2 concentration (:math:`c_i`). +PHS is forced by maximum transpiration (absent water stress, :math:`\beta_t=1`), whereby we first solve for assimilation, stomatal conductance, and intercellular CO2 with :math:`\beta_{t,sun}` and :math:`\beta_{t,shade}` both set to 1. +This involves iterating to convergence of :math:`c_i` (see section :numref:`Photosynthesis`). + +Next, using the solutions for :math:`E_{sun,max}` and :math:`E_{shade,max}`, PHS solves for :math:`\psi`, :math:`\beta_{t,sun}`, and :math:`\beta_{t,shade}`. +The values for :math:`\beta_{t,sun}`, and :math:`\beta_{t,shade}` are inputs to the photosynthesis routine, which now solves for attenuated photosynthesis and stomatal conductance (reflecting water stress). +Again this involves iterating to convergence of :math:`c_i`. +Non-linearities between :math:`\beta_t` and transpiration require also iterating to convergence of :math:`\beta_t`. +The outermost level of iteration works towards convergence of leaf temperature, reflecting leaf surface energy balance. + +.. _Figure PHS Flow Diagram: + +.. figure:: flow.png + + Flow diagram of leaf flux calculations + + +.. _PHS Refs: + +References +----------------------------- + +Local references. Will copy over + +.. _Bonanetal2014: + +Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling stomatal conductance in the earth system: linking leaf water-use efficiency and water transport along the soil–plant–atmosphere continuum, Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. + +.. _Chuangetal2006: + +Chuang Y.L., Oren R., Bertozzi A.L, Phillips N., Katul G.G. 2006. The porous media model for the hydraulic system of a conifer tree: Linking sap flux data to transpiration rate, Ecological Modelling, 191, 447-468, doi:10.1016/j.ecolmodel.2005.03.027. + +.. _Medlynetal2011: - ff +Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., Barton, C.V.M., 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. doi:10.1111/j.1365-2486.2010.02375.x +.. _Sperryetal1998: +Sperry, J.S., Adler, F.R., Campbell, G.S. and Comstock, J.P. (1998), Limitation of plant water use by rhizosphere and xylem conductance: results from a model. Plant, Cell & Environment, 21: 347–359. doi:10.1046/j.1365-3040.1998.00287.x +.. _SperryandLove2015: +Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us about responses to climate-change droughts. New Phytol, 207: 14–27. doi:10.1111/nph.13354 +.. _Williamsetal1996: +Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere continuum in a Quercus–Acer stand at Harvard Forest: the regulation of stomatal conductance by light, nitrogen and soil/plant hydraulic properties. Plant, Cell & Environment, 19: 911–927. doi:10.1111/j.1365-3040.1996.tb00456.x \ No newline at end of file From ad6b0e0289c6c06293422d19086f1c222ea2361c Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 9 Jun 2017 08:58:00 -0600 Subject: [PATCH 059/255] change chapter names --- .../CLM50_Tech_Note_Land-Only_Mode.rst} | 6 +- .../CLM50_Tech_Note_Plant_Hydraulics.rst} | 146 +++++++++++------- doc/source/tech_note/index.rst | 4 +- 3 files changed, 92 insertions(+), 64 deletions(-) rename doc/source/tech_note/{Offline/CLM50_Tech_Note_Offline.rst => Land-Only_Mode/CLM50_Tech_Note_Land-Only_Mode.rst} (99%) rename doc/source/tech_note/{Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst => Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst} (86%) diff --git a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst b/doc/source/tech_note/Land-Only_Mode/CLM50_Tech_Note_Land-Only_Mode.rst similarity index 99% rename from doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst rename to doc/source/tech_note/Land-Only_Mode/CLM50_Tech_Note_Land-Only_Mode.rst index f41a24a1d6..9fba6f187c 100644 --- a/doc/source/tech_note/Offline/CLM50_Tech_Note_Offline.rst +++ b/doc/source/tech_note/Land-Only_Mode/CLM50_Tech_Note_Land-Only_Mode.rst @@ -1,9 +1,9 @@ -.. _rst_Offline Mode: +.. _rst_Land-only Mode: -Offline Mode +Land-Only Mode ================ -In offline mode (uncoupled to an atmospheric model), the atmospheric +In land-only mode (uncoupled to an atmospheric model), the atmospheric forcing required by CLM (:numref:`Table Atmospheric input to land model`) is supplied by observed datasets. The standard forcing provided with the model is a 110-year (1901-2010) dataset provided by the Global Soil Wetness diff --git a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst similarity index 86% rename from doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst rename to doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index d49d3a04b3..60bfc568ef 100644 --- a/doc/source/tech_note/Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -1,18 +1,34 @@ -.. _rst_Plant Hydraulic Stress: +.. _rst_Plant Hydraulics: -Plant Hydraulic Stress +Plant Hydraulics ====================== -The Plant Hydraulic Stress (PHS) routine explicitly models water transport through the vegetation according to a simple hydraulic framework following Darcy's Law for porous media flow equations influenced by +.. _Rooting Profiles: + +Rooting Profiles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _Plant Hydraulic Stress: + +Plant Hydraulic Stress +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Plant Hydraulic Stress (PHS) routine explicitly models water transport +through the vegetation according to a simple hydraulic framework following +Darcy's Law for porous media flow equations influenced by :ref:`Bonan et al. (2014) `, :ref:`Chuang et al. (2006) `, :ref:`Sperry et al. (1998) `, :ref:`Sperry and Love (2015) `, :ref:`Williams et al (1996) `. -PHS solves for the vegetation water potential that matches water supply with transpiration demand. Water supply is modeled according to the circuit analog in :numref:`Figure Soil Temperature Schematic`. Transpiration demand is modeled relative to maximum transpiration by a transpiration loss function dependent on leaf water potential. +PHS solves for the vegetation water potential that matches water supply with +transpiration demand. Water supply is modeled according to the circuit analog +in :numref:`Figure Plant hydraulic circuit`. Transpiration demand is modeled +relative to maximum transpiration by a transpiration loss function dependent +on leaf water potential. -.. _Figure Soil Temperature Schematic: +.. _Figure Plant hydraulic circuit: .. figure:: circuit.jpg @@ -23,29 +39,41 @@ PHS solves for the vegetation water potential that matches water supply with tra Plant Water Supply ----------------------- -The supply equations are used to solve for vegetation water potential forced by transpiration demand and the set of layer-by-layer soil water potentials. -The water supply is discretized into segments: soil-to-root, root-to-stem, and stem-to-leaf. There are typically several (1-49) soil-to-root flows operating in parallel, one per soil layer. There are two stem-to-leaf flows operating in parallel, corresponding to the sunlit and shaded "leaves". +The supply equations are used to solve for vegetation water potential forced +by transpiration demand and the set of layer-by-layer soil water potentials. +The water supply is discretized into segments: soil-to-root, root-to-stem, and +stem-to-leaf. There are typically several (1-49) soil-to-root flows operating +in parallel, one per soil layer. There are two stem-to-leaf flows operating in +parallel, corresponding to the sunlit and shaded "leaves". -In general the water fluxes (e.g. soil-to-root, root-to-stem, etc.) are modeled according to Darcy's Law for porous media flow as: +In general the water fluxes (e.g. soil-to-root, root-to-stem, etc.) are +modeled according to Darcy's Law for porous media flow as: .. math:: - :label: 11.101) + :label: 11.101 q = kA\left( \psi_1 - \psi_2 \right) -:math:`q` is the flux of water (mmH\ :sub:`2`\ O) spanning the segment between :math:`\psi_1` and :math:`\psi_2` +:math:`q` is the flux of water (mmH\ :sub:`2`\ O) spanning the segment +between :math:`\psi_1` and :math:`\psi_2` :math:`k` is the hydraulic conductance (s\ :sup:`-1`\ ) -:math:`A` is the area basis (m\ :sup:`2`\ /m\ :sup:`2`\ ) relating the conducting area basis to ground area +:math:`A` is the area basis (m\ :sup:`2`\ /m\ :sup:`2`\ ) relating the +conducting area basis to ground area -:math:`\psi_1 - \psi_2` is the gradient in water potential (mmH\ :sub:`2`\ O) across the segment +:math:`\psi_1 - \psi_2` is the gradient in water potential (mmH\ :sub:`2`\ O) +across the segment -The segments in :numref:`Figure Soil Temperature Schematic` have variable resistance, as the water potentials become lower, hydraulic conductance decreases. -This is captured by multiplying the maximum segment conductance by a sigmoidal function capturing the percent loss of conductivity. The function uses two parameters to fit experimental vulnerability curves: the water potential at 50% loss of conductivity (:math:`p50`) and a shape fitting parameter (:math:`c_k`). +The segments in :numref:`Figure Plant hydraulic circuit` have variable resistance, +as the water potentials become lower, hydraulic conductance decreases. This is +captured by multiplying the maximum segment conductance by a sigmoidal function +capturing the percent loss of conductivity. The function uses two parameters to +fit experimental vulnerability curves: the water potential at 50% loss of +conductivity (:math:`p50`) and a shape fitting parameter (:math:`c_k`). .. math:: - :label: 11.102) + :label: 11.102 k=k_{max}\cdot 2^{-\left(\dfrac{\psi_1}{p50}\right)^{c_k}} @@ -66,29 +94,29 @@ The maximum conductance is a PFT parameter representing the maximum conductance This parameter can be defined separately for sunlit and shaded segments and should already include the appropriate length scaling (in other words this is a conductance, not conductivity). The water potential gradient is the difference between leaf water potential and stem water potential. There is no gravity term, assuming a negligible difference in height across the segment. The area basis is the leaf area index (either sunlit or shaded). .. math:: - :label: 11.103) + :label: 11.103 q_{1a}=k_{1a}\cdot\mbox{LAI}_{sun}\cdot\left(\psi_{stem}-\psi_{sunleaf} \right) .. math:: - :label: 11.104) + :label: 11.104 q_{1b}=k_{1b}\cdot\mbox{LAI}_{shade}\cdot\left(\psi_{stem}-\psi_{shadeleaf} \right) .. math:: - :label: 11.105) + :label: 11.105 k_{1a}=k_{1a,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} .. math:: - :label: 11.106) + :label: 11.106 k_{1b}=k_{1b,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} Variables: :math:`q_{1a}` = flux of water (mmH2O/s) from stem to sunlit leaf -12 + :math:`q_{1b}` = flux of water (mmH2O/s) from stem to shaded leaf :math:`LAI_{sun}` = sunlit leaf area index (m2/m2) @@ -119,12 +147,12 @@ Root-to-stem There is one root-to-stem flux. This represents a flux from the root collar to the upper branch reaches. The water flux from root-to-stem is the product of the segment conductance, the conducting area basis, and the water potential gradient from root to stem. Root-to-stem conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve (two parameters). The maximum conductance is defined as the maximum root-to-stem conductivity per unit stem area (PFT parameter) divided by the length of the conducting path, which is taken to be the vegetation height. The area basis is the stem area index. The gradient in water potential is the difference between the root water potential and the stem water potential less the difference in gravitational potential. .. math:: - :label: 11.107) + :label: 11.107 q_2=k_2 \cdot SAI \cdot \left( \psi_{root} - \psi_{stem} - \Delta \psi_z \right) .. math:: - :label: 11.108) + :label: 11.108 k_2=\dfrac{k_{2,max}}{z_2} \cdot 2^{-\left(\dfrac{\psi_{root}}{p50_2}\right)^{c_k}} @@ -162,37 +190,37 @@ Soil-to-root conductance is the result of two resistances in series, first acros The soil-root interface conductance is defined as the soil conductivity divided by the conducting length from soil to root. The soil conductivity varies by soil layer and is calculated based on soil potential and soil properties, via the Brooks-Corey theory. The conducting length is computed by calculating the characteristic root spacing following Bonan-2014. The root spacing depends on total root biomass and PFT parameters defining root structure (see section zqz). .. math:: - :label: 11.109) + :label: 11.109 - q_{3,i}=k_{3,i}*RAI*\left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right) + q_{3,i}=k_{3,i} \cdot RAI \cdot \left(\psi_{soil,i}-\psi_{root} + \Delta\psi_{z,i} \right) .. math:: - :label: 11.110) + :label: 11.110 - RAI=\left(LAI+SAI \right)\cdot r_i \cdot f_{root-leaf} + RAI=\left(LAI+SAI \right) \cdot r_i \cdot f_{root-leaf} .. math:: - :label: 11.111) + :label: 11.111 - k_{3,i}=\dfrac{k_{r,i}*k_{s,i}}{k_{r,i}+k_{s,i}} + k_{3,i}=\dfrac{k_{r,i} \cdot k_{s,i}}{k_{r,i}+k_{s,i}} .. math:: - :label: 11.112) + :label: 11.112 - k_{r,i}=\dfrac{k_{3,max}}{z_{3,i}}*2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}} + k_{r,i}=\dfrac{k_{3,max}}{z_{3,i}} \cdot 2^{-\left(\dfrac{\psi_{soil,i}}{p50_3}\right)^{c_k}} .. math:: - :label: 11.113) + :label: 11.113 k_{s,i} = \dfrac{k_{soil,i}}{dx_{root,i}} .. math:: - :label: 11.114) + :label: 11.114 dx_{root,i} = \left(\pi*\mbox{root-length-density}_i\right)^{-0.5} .. math:: - :label: 11.115) + :label: 11.115 \mbox{root-length-density} = \dfrac{\mbox{total root length}}{\mbox{soil volume}} @@ -240,22 +268,22 @@ Water stress is calculated with distinct values for sunlit and shaded leaves. Vegetation water stress is calculated based on leaf water potential and is used to attenuate photosynthesis (see section :numref:`Photosynthesis`) .. math:: - :label: 11.201) + :label: 11.201 E_{sun} = E_{sun,max} \cdot 2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} .. math:: - :label: 11.202) + :label: 11.202 E_{shade} = E_{shade,max} \cdot 2^{-\left(\dfrac{\psi_{shadeleaf}}{p50_e}\right)^{c_k}} .. math:: - :label: 11.203) + :label: 11.203 \beta_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,\beta_t=1}} .. math:: - :label: 11.204) + :label: 11.204 \beta_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,\beta_t=1}} @@ -288,15 +316,15 @@ Vegetation water stress is calculated based on leaf water potential and is used Vegetation Water Potential ----------------------------- -Both plant water supply and demand are functions of vegetation water potential. PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential at each timestep. PHS iterates to find the vegetation water potential :math:`\psi` (vector) that satisfies continuity between the non-linear vegetation water supply and demand (equations :eq:`11.103)`, :eq:`11.104)`, :eq:`11.107)`, :eq:`11.109)`, :eq:`11.201)`, :eq:`11.202)`). +Both plant water supply and demand are functions of vegetation water potential. PHS explicitly models root, stem, shaded leaf, and sunlit leaf water potential at each timestep. PHS iterates to find the vegetation water potential :math:`\psi` (vector) that satisfies continuity between the non-linear vegetation water supply and demand (equations :eq:`11.103`, :eq:`11.104`, :eq:`11.107`, :eq:`11.109`, :eq:`11.201`, :eq:`11.202`). .. math:: - :label: 11.301) + :label: 11.301 \psi=\left[\psi_{sunleaf},\psi_{shadeleaf},\psi_{stem},\psi_{root}\right] .. math:: - :label: 11.302) + :label: 11.302 \begin{aligned} E_{sun}&=q_{1a}\\ @@ -306,7 +334,7 @@ Both plant water supply and demand are functions of vegetation water potential. &=\sum_{i=1}^{nlevsoi}{q_{3,i}} \end{aligned} -PHS finds the water potentials that match supply and demand. In the plant water transport equations :eq:`11.302)`, the demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy continuity :eq:`11.302)`. +PHS finds the water potentials that match supply and demand. In the plant water transport equations :eq:`11.302`, the demand terms (left-hand side) are decreasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, water stress increases, causing a decrease in transpiration demand. The supply terms (right-hand side) are increasing functions of absolute leaf water potential. As absolute leaf water potential becomes larger, the gradients in water potential increase, causing an increase in vegetation water supply. PHS takes a Newton's method approach to iteratively solve for the vegetation water potentials that satisfy continuity :eq:`11.302`. @@ -326,7 +354,7 @@ Using the attenuated transpiration, we solve for :math:`g_{s,stressed}` and outp The continuity of water flow through the system yields four equations .. math:: - :label: 11.401) + :label: 11.401 \begin{aligned} E_{sun}&=q_{1a}\\ @@ -339,7 +367,7 @@ The continuity of water flow through the system yields four equations We seek the set of vegetation water potential values, .. math:: - :label: 11.402) + :label: 11.402 \psi=\left[ \begin {array}{c} \psi_{sunleaf}\cr\psi_{shadeleaf}\cr\psi_{stem}\cr\psi_{root} @@ -349,7 +377,7 @@ that satisfies these equations, as forced by the soil moisture and atmospheric s Each flux on the schematic can be represented in terms of the relevant water potentials. Defining the transpiration fluxes: .. math:: - :label: 11.403) + :label: 11.403 \begin{aligned} E_{sun} &= E_{sun,max} \cdot 2^{-\left(\dfrac{\psi_{sunleaf}}{p50_e}\right)^{c_k}} \\ @@ -359,7 +387,7 @@ Each flux on the schematic can be represented in terms of the relevant water pot Defining the water supply fluxes: .. math:: - :label: 11.404) + :label: 11.404 \begin{aligned} q_{1a}&=k_{1a,max}\cdot 2^{-\left(\dfrac{\psi_{stem}}{p50_1}\right)^{c_k}} \cdot\mbox{LAI}_{sun}\cdot\left(\psi_{stem}-\psi_{sunleaf} \right) \\ @@ -375,7 +403,7 @@ The initial guess is the solution for :math:`\psi` (vector) from the previous ti The general framework, from iteration `m` to `m+1` is: .. math:: - :label: 11.405) + :label: 11.405 q^{m+1}=q^m+\dfrac{\delta q}{\delta\psi}\Delta\psi \\ \psi^{m+1}=\psi^{m}+\Delta\psi @@ -383,28 +411,28 @@ The general framework, from iteration `m` to `m+1` is: So for our first flux balance equation, at iteration `m+1`, we have: .. math:: - :label: 11.406) + :label: 11.406 E_{sun}^{m+1}=q_{1a}^{m+1} Which can be linearized to: .. math:: - :label: 11.407) + :label: 11.407 E_{sun}^{m}+\dfrac{\delta E_{sun}}{\delta\psi}\Delta\psi=q_{1a}^{m}+\dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi And rearranged to be: .. math:: - :label: 11.408) + :label: 11.408 \dfrac{\delta q_{1a}}{\delta\psi}\Delta\psi-\dfrac{\delta E_{sun}}{\delta\psi}\Delta\psi=E_{sun}^{m}-q_{1a}^{m} And for the other 3 flux balance equations: .. math:: - :label: 11.409) + :label: 11.409 \begin{aligned} \dfrac{\delta q_{1b}}{\delta\psi}\Delta\psi-\dfrac{\delta E_{sha}}{\delta\psi}\Delta\psi&=E_{sha}^{m}-q_{1b}^{m} \\ @@ -415,7 +443,7 @@ And for the other 3 flux balance equations: Putting all four together in matrix form: .. math:: - :label: 11.410) + :label: 11.410 \left[ \begin {array}{c} \dfrac{\delta q_{1a}}{\delta\psi}-\dfrac{\delta E_{sun}}{\delta\psi} \cr @@ -437,7 +465,7 @@ Introducing the notation: :math:`A\Delta\psi=b` .. math:: - :label: 11.411) + :label: 11.411 \Delta\psi=\left[ \begin {array}{c} \Delta\psi_{sunleaf} \cr @@ -447,7 +475,7 @@ Introducing the notation: \end {array} \right] .. math:: - :label: 11.412) + :label: 11.412 A= \left[ \begin {array}{cccc} @@ -461,7 +489,7 @@ Introducing the notation: \end {array} \right] .. math:: - :label: 11.413) + :label: 11.413 b= \left[ \begin {array}{c} @@ -474,12 +502,12 @@ Introducing the notation: Now we compute all the entries for :math:`A` and :math:`b` based on the soil moisture and maximum transpiration forcings and can solve to find: .. math:: - :label: 11.414) + :label: 11.414 \Delta\psi=A^{-1}b .. math:: - :label: 11.415) + :label: 11.415 \psi_{m+1}=\psi_m+\Delta\psi @@ -489,12 +517,12 @@ The magnitude of the water flux is driven by soil matric potential and unstresse We use the transpiration solution (corresponding to the final solution for :math:`\psi`) to compute stomatal conductance. The stomatal conductance is then used to compute :math:`\beta_t`. .. math:: - :label: 11.416) + :label: 11.416 \beta_{t,sun} = \dfrac{g_{s,sun}}{g_{s,sun,\beta_t=1}} .. math:: - :label: 11.417) + :label: 11.417 \beta_{t,shade} = \dfrac{g_{s,shade}}{g_{s,shade,\beta_t=1}} @@ -554,4 +582,4 @@ Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us about respon .. _Williamsetal1996: -Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere continuum in a Quercus–Acer stand at Harvard Forest: the regulation of stomatal conductance by light, nitrogen and soil/plant hydraulic properties. Plant, Cell & Environment, 19: 911–927. doi:10.1111/j.1365-3040.1996.tb00456.x \ No newline at end of file +Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere continuum in a Quercus–Acer stand at Harvard Forest: the regulation of stomatal conductance by light, nitrogen and soil/plant hydraulic properties. Plant, Cell & Environment, 19: 911–927. doi:10.1111/j.1365-3040.1996.tb00456.x diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index 74a39e908b..a05aa6210b 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -23,7 +23,7 @@ CLM Technical Note Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst - Plant_Hydraulic_Stress/CLM50_Tech_Note_Plant_Hydraulic_Stress.rst + Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst Lake/CLM50_Tech_Note_Lake.rst Glacier/CLM50_Tech_Note_Glacier.rst RTM/CLM50_Tech_Note_RTM.rst @@ -43,6 +43,6 @@ CLM Technical Note BVOCs/CLM50_Tech_Note_BVOCs.rst Dust/CLM50_Tech_Note_Dust.rst Isotopes/CLM50_Tech_Note_Isotopes.rst - Offline/CLM50_Tech_Note_Offline.rst + Land-Only_Mode/CLM50_Tech_Note_Land-Only_Mode.rst References/CLM50_Tech_Note_References.rst From 92a6e84f18a271ad58fcbb5f44d1212cccf18df5 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 9 Jun 2017 09:37:02 -0600 Subject: [PATCH 060/255] Update Photosynthetic Capacity --- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 380 ++++++++++++------ 1 file changed, 256 insertions(+), 124 deletions(-) mode change 100644 => 100755 doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst old mode 100644 new mode 100755 index 803964c6df..0f24520566 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -1,124 +1,256 @@ -.. _rst_Photosynthetic Capacity: - -Photosynthetic Capacity -======================= - -.. _V\ :sub:`cmax25` and Canopy scaling: - -V\ :sub:`cmax25` and Canopy scaling --------------------------------------------- - -The maximum rate of carboxylation at 25 :sup:`o`\ C varies with -foliage nitrogen concentration and specific leaf area and is calculated -as in Thornton and Zimmermann (2007). At 25ºC, - -.. math:: - :label: ZEqnNum217783 - - V_{c\max 25} =N_{a} F_{LNR} F_{NR} a_{R25} - -where :math:`N_{a}` is the area-based leaf nitrogen concentration (g N -m\ :sup:`-2` leaf area), :math:`F_{LNR}` is the fraction of leaf -nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N), -:math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass -to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and -:math:`a_{R25} =60` is the specific activity of Rubisco (µmol -CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`). -:math:`N_{a}` is calculated from mass-based leaf N concentration and -specific leaf area - -.. math:: - :label: ZEqnNum561340 - - N_{a} =\frac{1}{CN_{L} \; SLA_{0} } - -where :math:`CN_{L}` is the leaf carbon-to-nitrogen ratio (g C -g\ :sup:`-1` N) and :math:`SLA_{0}` is specific leaf area at the -canopy top ( m\ :sup:`2` leaf area g\ :sup:`-1` C ). Table 8.1 -lists values of :math:`F_{LNR}` , :math:`CN_{L}` , and :math:`SLA_{0}` -for each plant functional type. :math:`F_{LNR}` was chosen to give -:math:`V_{c\max 25}` consistent with Kattge et al. (2009), as discussed -by Bonan et al. (2011, 2012). Table 8.1 lists derived values for -:math:`V_{c\max 25}` at the top of the canopy using :math:`SLA_{0}` . -Tropical broadleaf evergreen trees are an exception, and a higher -:math:`V_{c\max 25}` is used to alleviate model biases (Bonan et al. -2012). - -:math:`V_{c\max 25}` is calculated separately for sunlit and shaded -leaves using an exponential profile to area-based leaf nitrogen -(:math:`N_{a}` ), as in Bonan et al. (2011). :math:`V_{c\max 25}` at -cumulative leaf area index :math:`x` from the canopy top scales directly -with :math:`N_{a}` , which decreases exponentially with greater -cumulative leaf area, so that - -.. math:: - :label: ZEqnNum745439 - - V_{c\; \max 25}^{} \left(x\right)=V_{c\; \max 25}^{} \left(0\right)e^{-K_{n} x} - -where :math:`V_{c\; \max 25}^{} \left(0\right)` is defined at the top of -the canopy using :math:`SLA_{0}` , and :math:`K_{n}` is the decay -coefficient for nitrogen. The canopy integrated value for sunlit and -shaded leaves is - -.. math:: - :label: 9.20) - - \begin{array}{rcl} {V_{c\; \max 25}^{sun} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)f_{sun} \left(x\right)\, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} } \end{array} - -.. math:: - :label: 9.21) - - \begin{array}{rcl} {V_{c\; \max 25}^{sha} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)\left[1-f_{sun} \left(x\right)\right] \, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left\{\left[1-e^{-K_{n} L} \right]\frac{1}{K_{n} } -\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} \right\}} \end{array} - -and the average value for the sunlit and shaded leaves is - -.. math:: - :label: 9.22) - - \bar{V}_{c\; \max 25}^{sun} ={V_{c\; \max 25}^{sun} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sun} L^{sun} }} \right. \kern-\nulldelimiterspace} L^{sun} } - -.. math:: - :label: 9.23) - - \bar{V}_{c\; \max 25}^{sha} ={V_{c\; \max 25}^{sha} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sha} L^{sha} }} \right. \kern-\nulldelimiterspace} L^{sha} } . - -This integration is over all leaf area (:math:`L`) with -:math:`f_{sun} (x)=\exp \left(-Kx\right)` and :math:`K` the direct beam -extinction coefficient (equation 4.9). Photosynthetic parameters -:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}` , and -:math:`R_{d25}` scale similarly. - -The value :math:`K_{n} = 0.11` chosen by Bonan et al. (2011) is -consistent with observationally-derived estimates for forests, mostly -tropical, and provides a gradient in V\ :sub:`cmax` similar to -the original CLM4 specific leaf area scaling. However, Bonan et al. -(2012) showed that the sunlit/shaded canopy parameterization does not -match an explicit multi-layer canopy parameterization. The discrepancy -arises from absorption of scattered radiation by shaded leaves and can -be tuned out with higher :math:`K_{n}` . The model uses -:math:`K_{n} =0.30` to match an explicit multi-layer canopy. - -:math:`V_{c\max 25}` additionally varies with daylength (:math:`DYL`) -using the function :math:`f(DYL)`, which introduces seasonal variation -to :math:`V_{c\max }` - -.. math:: - :label: 9.24) - - f\left(DYL\right)=\frac{\left(DYL\right)^{2} }{\left(DYL_{\max } \right)^{2} } - -with :math:`0.01\le f\left(DYL\right)\le 1`. Daylength (seconds) is -given by - -.. math:: - :label: 9.25) - - DYL=2\times 13750.9871\cos ^{-1} \left[\frac{-\sin \left(lat\right)\sin \left(decl\right)}{\cos \left(lat\right)\cos \left(decl\right)} \right] - -where :math:`lat` (latitude) and :math:`decl` (declination angle) are -from section 3.3. Maximum daylength (:math:`DYL_{\max }` ) is calculated -similarly but using the maximum declination angle for present-day -orbital geometry (:math:`\pm`\ 23.4667º [:math:`\pm`\ 0.409571 radians], -positive for Northern Hemisphere latitudes and negative for Southern -Hemisphere). +.. _rst_Photosynthetic Capacity: + +Photosynthetic Capacity +======================= + +The photosynthetic capacity is represented by two key parameters: 1) the maximum rate of carboxylation at +25 :sup:`o`\ C, :math:`V_{\text{c,max25}}`; and 2) the maximum rate of electron transport at +25 :sup:`o`\ C, :math:`J_{\text{max25}}` . They are predicted by a mechanistic model of leaf +utilization of nitrogen for assimilation (LUNA V1.0) (Ali et al. 2016) based on an optimality hypothesis to nitrogen allocation +among light capture, electron transport, carboxylation, respiration and storage. +Specifically, the model allocates the nitrogen by maximizing the daily +net photosynthetic carbon gain under following two key assumptions: + +- nitrogen allocated for light capture, electron transport and carboxylation are co-limiting; +- respiratory nitrogen is allocated to maintain dark respiration determined by :math:`V_{\text{c,max}}`. + +Compared to traditional photosynthetic capacity models, a key advantage of LUNA is that the model is able to predict the potential +acclimation of photosynthetic capacities at different environmental conditions as determined by temperature, radiation, +CO :sub:`2` concentrations, day length, and humidity. + +.. _Model inputs and parameter estimations: + +Model inputs and parameter estimations +------------------------------------------------------- +The LUNA model includes the following four unitless parameters: + +- :math:`J_{maxb0}` , which specifies the baseline proportion of nitrogen allocated for electron transport; +- :math:`J_{maxb1}` , which determines response of electron transport rate to light availability; +- :math:`t_{c,j0}` , which defines the baseline ratio of Rubisco-limited rate to light-limited rate; +- :math:`H` , which determines the response of electron transport rate to relative humidity. + +The above four parameters are estimated by fitting the LUNA model to a global compilation of >800 obervations +located at different biomes, canopy locations, and time of the year from 1993-2013 (Ali et al 2015). The model inputs +are area-based leaf nitrogen content, leaf mass per unit leaf area and the driving environmental conditions (average of past 10 days) +including temperature, CO :sub:`2` concentrations, daily mean and maximum radiation, relative humidity and day length. +The estimated values in CLM5 for the listed parameters are 0.0311, 0.1745, 0.8054, and 6.0999, repectively. In LUNA V1.0, the estimated +parameter values are for C3 natural vegetations. In view that potentially large differences in photosythetic capacity could exist +between crops and natural vegetations due to human selection and genetic modifications, in CLM5, +the LUNA model are used only for C3 natural vegetations. The photosynthetic capacity for crops and C4 plants are thus +still kept the same as CLM4.5. Namely, it is estimated based on the leaf nitrogen content, fixed RUBISCO allocations for +:math:`V_{c\max 25}` and an adjusting factor to account for the impact of day length. In CLM5, the model simulates both sun-lit and shaded leaves; +however, because the sun-lit and shaded leaves can changes through the day based on the sun angles, +we do not differentiate the photosynthetic capacity difference for sun-lit or shaded leaves. + + +.. _Model structure: + +Model structure +---------------------------------------------------------- + +The structure of the LUNA model is adapted from Xu et al.(2012), where the plant nitrogen at the leaf level ( :math:`\text{LNC}_{a}`; gN/ m :sup:`2` leaf) is divided into +four pools: structural nitrogen( :math:`N_{\text{str}}`; gN/m :sup:`2` leaf), +photosynthetic nitrogen ( :math:`N_{\text{psn}}`; gN/ m:sup:`2` leaf), +storage nitrogen( :math:`N_{\text{store}}`; gN/m :sup:`2` leaf), +and respiratory nitrogen ( :math:`N_{\text{resp}}`; gN/m :sup:`2` leaf). +Namely, + +.. math:: + :label: 10.1) + + \text{LNC}_{a} = N_{\text{psn}} + N_{\text{str}}+ N_{\text{store}} + N_{\text{resp}}. + +The photosynthetic nitrogen, :math:`N_{\text{psn}}`, is further divided into +nitrogen for light capture ( :math:`N_{\text{lc}}`; gN/m :sup:`2` leaf), +nitrogen for electron transport ( :math:`N_{\text{et}}`; gN/m :sup:`2` leaf), +and nitrogen for carboxylation ( :math:`N_{\text{cb}}`; gN/m :sup:`2` leaf). +Namely, + +.. math:: + :label: 10.2) + + N_{\text{psn}} =N_{\text{et}} + N_{\text{cb}} + N_{\text{lc}}. + +The structural nitrogen, :math:`N_{\text{str}}`, is calculated as the +multiplication of leaf mass per unit area (LMA: g biomass/m :sup:`2` leaf), and the structural nitrogen content (SNC; gN/g biomass). Namely, + +.. math:: + :label: 10.3) + + N_{\text{str}} = \text{SNC} \cdot \text{LMA} + +where SNC is set to be fixed at 0.002 (gN/g biomass), based on data on C:N ratio from dead wood (White etal.,2000). + +We assume that plants optimize their nitrogen allocations (i.e., :math:`N_{\text{store}}`, :math:`N_{\text{resp}}`, :math:`N_{\text{lc}}`, :math:`N_{\text{et}}`, :math:`N_{\text{cb}}`) to maximize the photosynthetic carbon gain, defined as +the gross photosynthesis ( :math:`A` ) minus the maintenance respiration for +photosynthetic enzymes ( :math:`R_{\text{psn}}` ), under specific +environmental conditions and given plant's strategy of leaf nitrogen +use. Namely, the solutions of nitrogen allocations \{ :math:`N_{\text{store}}`, :math:`N_{\text{resp}}`, :math:`N_{\text{lc}}`, :math:`N_{\text{et}}`, :math:`N_{\text{cb}}` \} can be estimated as follows, + +.. math:: + :label: 10.4) + + \left\{\hat{N}_{\text{{store}}}, \hat{N}_{\text{{resp}}}, + \hat{\mathrm{N}}_{\text{lc}}, \hat{N}_{\text{et}}, \hat{\mathrm{N}}_{\text{cb}} + \right\} = \underset{\mathrm{N}_{\text{store}}\,+\,\mathrm{N}_{\text{resp}}\,+\,\mathrm{N}_{\text{lc}}\,+\,\mathrm{N}_{\text{et}}\,+\,\mathrm{N}_{\text{cb}}\,<\text{FNC}_{\mathrm{a}}}{\text{argmax}} (A-R_{\text{psn}}), + +where :math:`\text{FNC}_{a}` is the functional nitrogen content defined as the total leaf nitrogen content ( :math:`\text{LNC}_{a}`) minus the structural nitrogen content ( :math:`N_{\text{str}}` ). + +The gross photosynthesis, :math:`A`, was calculated with a coupled leaf gas exchange model based on the Farquhar et al. (1980) model of +photosynthesis and Ball--Berry-type stomatal conductance model (Ball et al., 1987). The maintenance respiration for photosynthetic enzymes, :math:`R_{\text{psn}}`, is +calculated by the multiplication of total photosynthetic nitrogen ( :math:`N_{\text{psn}}` ) and the maintenance respiration cost for photosynthetic enzymes. + +In the LUNA model, the maximum electron transport rate +( :math:`J_{\text{max}}`; :math:`{\mu} mol` electron / m :sup:`-2`/s) +is simulated to have a baseline allocation of nitrogen and additional +nitrogen allocation to change depending on the average daytime +photosynthetic active radiation (PAR; :math:`{\mu} mol` electron / m :sup:`-2`/s), day length (hours) and air humidity. +Specifically, the LUNA model has + +.. math:: + :label: 10.5) + + J_{\text{{max}}} = J_{\text{max}0} + J_{\text{max}b1} + f\left(\text{day length} \right)f\left(\text{humidity} + \right)\alpha \text{PAR} + +The baseline electron transport rate, :math:`J_{\text{max}0}`, is calculated as follows, + +.. math:: + :label: 10.6) + + J_{\text{max}0} = J_{\text{max}b0}{\text{FNC}}_{\mathrm{a}}{\text{NUE}}_{J_{\text{{max}}}} + + +where :math:`J_{\text{max}b0}` (unitless) is the baseline proportion of nitrogen +allocated for electron transport rate. :math:`{\text{NUE}}_{J_{\text{{max}}}}` ( :math:`{\mu} mol` electron /s/g N) +is the nitrogen use efficiency of :math:`J_{\text{{max}}}`. :math:`J_{\text{max}b1}` (unitless) is a coefficient determining the response of the electron +transport rate to amount of absorbed light (i.e., :math:`\alpha \text{PAR}`). +:math:`f\left(\text{day length} \right)` is a function specifies the impact of day +length (hours) on :math:`J_{\text{max}}` in view that longer day length has been demonstrated by previous studies to alter :math:`V_{\mathrm{c}\text{max}25}` and +:math:`J_{\text{max}25}` (Bauerle et al., 2012; Comstock and Ehleringer, 1986) through photoperiod sensing and regulation (e.g. Song et al., 2013). +Following Bauerle et al. (2012), :math:`f\left(\text{day length} \right)` is simulated as follows, + +.. math:: + :label: 10.7) + + f\left(\text{day length} \right) = \left(\frac{\text{day length}}{12} \right)^{2}. + +:math:`f\left(\text{humidity} \right)` represents the impact of air humitidy on +:math:`J_{\text{{max}}}`. We assume that higher humidity leads to higher +:math:`J_{\text{{max}}}` with less water limiation on stomta opening and that low +relative humidity has a stronger impact on nitrogen allocation due to greater +water limitation. When relative humidity (RH; unitless) is too low, we assume +that plants are physiologically unable to reallocate nitrogen. We therefore +assume that there exists a critical value of relative humidity ( :math:`RH_{0} = +0.25`; unitless), below which there is no optimal nitrogen allocation. Based +on the above assumptions, we have + +.. math:: + :label: 10.8) + + f\left(\text{humidity} + \right) = \left(1-\mathrm{e}^{\left(-H + \frac{\text{max}\left(\text{RH}-{\text{RH}}_{0}, 0 \right)}{1-\text{RH}_{0}} \right)} \right), + + +where :math:`H` (unitless) specifies the impact of relative humidity on electron transport rate. + +The efficiency of light energy absorption (unitless), :math:`\alpha`, is calculated +depending on the amount of nitrogen allocated for light capture, +:math:`\mathrm{N}_{\text{lc}}`. Following Niinemets and Tenhunen (1997), the LUNA model has, + +.. math:: + :label: 10.9) + + \alpha =\frac{0.292}{1+\frac{0.076}{\mathrm{N}_{\text{lc}}C_{b}}} + + +where 0.292 is the conversion factor from photon to electron. :math:`C_{b}` +is the conversion factor (1.78) from nitrogen to chlorophyll. After we +estimate :math:`J_{\text{{max}}}`, the actual electron transport rate with +the daily maximum radiation ( :math:`J_{x}`) can be calculated using the +empirical expression of leaf (1937), + +.. math:: + :label: 10.10) + + J_{x} = \frac{\alpha \text{PAR}_{\text{max}}} {\left(1 + \frac{\alpha^{2}{\text{PAR}}_{\text{{max}}}^{2}}{J_{\text{{max}}}^{2}} + \right)^{0.5}} + + +where :math:`\text{PAR}_{\text{{max}}}` ( :math:`\mu mol`/m :sup:`2`/s) is the +maximum photosynthetically active radiation during the day. + + +Based on Farquhar et al. (1980) and Wullschleger (1993), we can calculate the +electron-limited photosynthetic rate under daily maximum radiation ( :math:`W_{jx}`) +and the Rubisco-limited photosynthetic rate ( :math:`W_{\mathrm{c}}`) as follows, + + +.. math:: + :label: 10.11) + + W_{J_{x}} = K_{j}J_{x} , + +.. math:: + :label: 10.12) + + W_{\mathrm{c}} = K_{\mathrm{c}} V_{{\mathrm{c}, \text{max}}}, + + +where :math:`K_{j}` and :math:`K_{\mathrm{c}}` as the conversion factors for +:math:`J_{x}` and :math:`V_{{\mathrm{c}, \text{max}}}` ( :math:`V_{{\mathrm{c}, \text{max}}}` to +:math:`W_{\mathrm{c}}` and :math:`J_{x}` to :math:`W_{J_{x}}`), respectively. Based on +Xu et al. (2012), Maire et al. (2012) and Walker et al. (2014), we +assume that :math:`W_{\mathrm{c}}` is proportional to +:math:`W_{J_{x}}`. Specifically, we have + +.. math:: + :label: 10.13) + + W_{\mathrm{c}}=t_{\alpha}t_{\mathrm{c}, j0}W_{J_{x}} + + +where :math:`t_{\mathrm{c}, j0}` is the baseline ratio of :math:`W_{\mathrm{c}}` to +:math:`W_{J_{x}}`. We recognize that this ratio may change depending on the +nitrogen use efficiency of carboxylation and electron transport (Ainsworth and Rogers, 2007), +therefore the LUNA model has the modification factor, :math:`t_{\alpha}`, to adjust baseline +the ratio depending on the nitrogen use efficiency for electron vs carboxylation (Ali et al 2016). + +Following Collatz et al.(1991a), the total respiration ( :math:`R_{\mathrm{t}}`) is +calculated in proportion to :math:`V_{\text{c,max}}`, + +.. math:: + :label: 10.14) + + R_{\mathrm{t}} = 0.015 V_{\text{c,max}}. + + +Accounting for the daytime and nighttime temperature, the daily respirations is calculated as follows, + + +.. math:: + :label: 10.15) + + + R_{\text{td}}={R}_{\mathrm{t}} [D_{\text{day}} + D_{\text{night}} f_{\mathrm{r}}{(T_{\text{night}})/f_{\mathrm{r}}{(T_{\text{day}})}}], + + +where :math:`D_{\text{day}}` and :math:`D_{\text{night}}` are daytime and +nighttime durations in seconds. :math:`f_{\mathrm{r}}(T_{\text{night}})` and +:math:`f_{\mathrm{r}}(T_{\text{day}})` are the temperature response functions for +respiration [see Appendix B in Ali et al (2016) for details ]. + + +.. _Numerical scheme: + +Numerical scheme +--------------------------------------------------------- + +The LUNA model searches for the "optimal" nitrogen allocations for maximum net photosynthetic carbon gain +by incrementally increase the nitrogen allocated for light capture (i.e., :math:`N_{\text{lc}}`) (see Ali et al 2016 for details) . +We assume that plants only optimize the nitrogen allocation when they can grow (i.e., GPP>0.0). +If GPP become zero under stress, then the LUNA model assume a certain amount of enzyme will decay at daily rates of 0.1, +in view that the half-life time for photosynthetic enzymes are short (~7 days) (Suzuki et al. 2001). +To avoid unrealistic low values of photosynthetic capacity, the decay is only limited to 50 percent of the original enzyme levels. \ No newline at end of file From 11fd281ef02e33f454588105da8812db342b92c5 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 9 Jun 2017 11:00:43 -0600 Subject: [PATCH 061/255] Move root profile --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 4 +- .../CLM50_Tech_Note_Introduction.rst | 6 +- .../CLM50_Tech_Note_Photosynthesis.rst | 71 ------ .../CLM50_Tech_Note_Plant_Hydraulics.rst | 214 ++++++++++++++++-- .../References/CLM50_Tech_Note_References.rst | 5 + 5 files changed, 200 insertions(+), 100 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index e8b78225dc..d5f9b85560 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -404,8 +404,8 @@ Atmospheric Coupling The current state of the atmosphere (:numref:`Table Atmospheric input to land model`) at a given time step is used to force the land model. This atmospheric state is provided by an -atmospheric model in coupled mode or from an observed dataset in offline -mode (Chapter :numref:`rst_Offline Mode`). The land model then initiates a full set of +atmospheric model in coupled mode or from an observed dataset in land-only +mode (Chapter :numref:`rst_Land-Only Mode`). The land model then initiates a full set of calculations for surface energy, constituent, momentum, and radiative fluxes. The land model calculations are implemented in two steps. The land model proceeds with the calculation of surface energy, constituent, diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 48452d358f..ed7a66f332 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -485,11 +485,11 @@ canyon model to contrast rural and urban energy balance and climate Other modifications of note include refinement of the global PFT, wetland, and lake distributions, more realistic optical properties for grasslands and croplands, and an improved diurnal cycle and spectral -distribution of incoming solar radiation to force the model in offline +distribution of incoming solar radiation to force the model in land-only mode. Many of the ideas incorporated into the carbon and nitrogen cycle -component of CLM4 derive from the earlier development of the offline +component of CLM4 derive from the earlier development of the land-only ecosystem process model Biome-BGC (Biome BioGeochemical Cycles), originating at the Numerical Terradynamic Simulation Group (NTSG) at the University of Montana, under the guidance of Prof. Steven Running. @@ -601,7 +601,7 @@ CLM4 to create CLM4 surface datasets is replaced with newer and higher resolution input datasets where possible (see section :numref:`Surface Data` for details). The default meteorological forcing dataset provided with CLM4 (:ref:`Qian et al. 2006)` is replaced with the 1901-2010 -CRUNCEP forcing dataset (see Chapter :numref:`rst_Offline Mode`) for CLM4.5, +CRUNCEP forcing dataset (see Chapter :numref:`rst_Land-Only Mode`) for CLM4.5, though users can also still use the :ref:`Qian et al. (2006)` dataset or other alternative forcing datasets. diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index 70fa76baf7..d50b90a814 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -552,77 +552,6 @@ water contents (kg m\ :sup:`-2`) (Chapter 7), densities of ice and liquid water (kg m\ :sup:`-3`) (Table 2.6), and :math:`\Delta z_{i}` is the soil layer thickness (m) (section 6.1). -The root fraction :math:`r_{i}` in each soil layer depends on the plant -functional type - -.. math:: - :label: 9.30) - - r_{i} =\left\{\begin{array}{l} {0.5\left[\begin{array}{l} {\exp \left(-r_{a} z_{h,\, i-1} \right)+\exp \left(-r_{b} z_{h,\, i-1} \right)-} \\ {\exp \left(-r_{a} z_{h,\, i} \right)-\exp \left(-r_{b} z_{h,\, i} \right)} \end{array}\right]\qquad {\rm for\; }1\le i` -(:numref:`Table Plant functional type root distribution parameters`). - -.. _Table Plant functional type root distribution parameters: - -.. table:: Plant functional type root distribution parameters - - +----------------------------------+------------------+------------------+ - | Plant Functional Type | :math:`r_{a}` | :math:`r_{b}` | - +==================================+==================+==================+ - | NET Temperate | 7.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | NET Boreal | 7.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | NDT Boreal | 7.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | BET Tropical | 7.0 | 1.0 | - +----------------------------------+------------------+------------------+ - | BET temperate | 7.0 | 1.0 | - +----------------------------------+------------------+------------------+ - | BDT tropical | 6.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | BDT temperate | 6.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | BDT boreal | 6.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | BES temperate | 7.0 | 1.5 | - +----------------------------------+------------------+------------------+ - | BDS temperate | 7.0 | 1.5 | - +----------------------------------+------------------+------------------+ - | BDS boreal | 7.0 | 1.5 | - +----------------------------------+------------------+------------------+ - | C\ :sub:`3` grass arctic | 11.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | C\ :sub:`3` grass | 11.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | C\ :sub:`4` grass | 11.0 | 2.0 | - +----------------------------------+------------------+------------------+ - | Crop R | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Crop I | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Corn R | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Corn I | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Temp Cereal R | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Temp Cereal I | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Winter Cereal R | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Winter Cereal I | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Soybean R | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - | Soybean I | 6.0 | 3.0 | - +----------------------------------+------------------+------------------+ - .. _Numerical implementation photosynthesis: Numerical implementation diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index 60bfc568ef..703f9b8ed9 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -3,11 +3,140 @@ Plant Hydraulics ====================== -.. _Rooting Profiles: +.. _Roots: -Rooting Profiles +Roots ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _Vertical Root Distribution: + +Vertical Root Distribution +--------------------------- + +The root fraction :math:`r_{i}` in each soil layer depends on the plant +functional type + +.. math:: + :label: 11.1 + + r_{i} = + \begin{array}{lr} + \left(\beta^{z_{h,\, i-1} \cdot 100} - \beta^{z_{h,\, i} \cdot 100} \right) & \qquad {\rm for\; }1 \le i \le N_{levsoi} + \end{array} + +where :math:`z_{h,\, i}` (m) is the depth from the soil surface to the +interface between layers :math:`i` and :math:`i+1` (:math:`z_{h,\, 0}` , +the soil surface) (section :numref:`Vertical Discretization`), the factor of 100 +converts from m to cm, and :math:`\beta` is a plant-dependent root +distribution parameter adopted from :ref:`Jackson et al. (1996)` +(:numref:`Table Plant functional type root distribution parameters`). + +.. rootfr(p,lev) = ( & + beta ** (col%zi(c,lev-1)*m_to_cm) - & + beta ** (col%zi(c,lev)*m_to_cm) ) + +.. 0, 0.976, 0.943, 0.943, 0.993, 0.966, 0.993, 0.966, 0.943, 0.964, 0.964, + 0.914, 0.914, 0.943, 0.943, 0.943, 0.943, 0.943, 0.943, 0.943, 0.943, + +.. _Table Plant functional type root distribution parameters: + +.. table:: Plant functional type root distribution parameters + + +----------------------------------+------------------+ + | Plant Functional Type | :math:`\beta` | + +==================================+==================+ + | NET Temperate | 0.976 | + +----------------------------------+------------------+ + | NET Boreal | 0.943 | + +----------------------------------+------------------+ + | NDT Boreal | 0.943 | + +----------------------------------+------------------+ + | BET Tropical | 0.993 | + +----------------------------------+------------------+ + | BET temperate | 0.966 | + +----------------------------------+------------------+ + | BDT tropical | 0.993 | + +----------------------------------+------------------+ + | BDT temperate | 0.966 | + +----------------------------------+------------------+ + | BDT boreal | 0.943 | + +----------------------------------+------------------+ + | BES temperate | 0.964 | + +----------------------------------+------------------+ + | BDS temperate | 0.964 | + +----------------------------------+------------------+ + | BDS boreal | 0.914 | + +----------------------------------+------------------+ + | C\ :sub:`3` grass arctic | 0.914 | + +----------------------------------+------------------+ + | C\ :sub:`3` grass | 0.943 | + +----------------------------------+------------------+ + | C\ :sub:`4` grass | 0.943 | + +----------------------------------+------------------+ + | Crop R | 0.943 | + +----------------------------------+------------------+ + | Crop I | 0.943 | + +----------------------------------+------------------+ + | Corn R | 0.943 | + +----------------------------------+------------------+ + | Corn I | 0.943 | + +----------------------------------+------------------+ + | Temp Cereal R | 0.943 | + +----------------------------------+------------------+ + | Temp Cereal I | 0.943 | + +----------------------------------+------------------+ + | Winter Cereal R | 0.943 | + +----------------------------------+------------------+ + | Winter Cereal I | 0.943 | + +----------------------------------+------------------+ + | Soybean R | 0.943 | + +----------------------------------+------------------+ + | Soybean I | 0.943 | + +----------------------------------+------------------+ + +.. _Root Spacing: + +Root Spacing +----------------------------- + +To determine the conductance along the soil to root pathway (section +:numref:`Soil-to-root`) an estimate of the spacing between the roots within +a soil layer is required. The distance between roots :math:`dx_{root,i}` (m) +is calculated by assuming that roots are distributed uniformly throughout +the soil (:ref:`Gardner 1960`) + +.. math:: + :label: 11.12 + + dx_{root,i} = \left(\pi \cdot L_i\right)^{\frac{1}{2}} + +where :math:`L_{i}` is the root length density (m m :sup:`-3`) + +.. math:: + :label: 11.13 + + L_{i} = \frac{B_{root,i}}{\rho_{root} {CA}_{root}} \ , + +:math:`B_{root,i}` is the root biomass density (kg m :sup:`-3`) + +.. math:: + :label: 11.14 + + B_{root,i} = \frac{c\_to\_b \cdot C_{fineroot} \cdot r_{i}}{dz_{i}} + +where :math:`c\_to\_b = 2` (kg biomass kg carbon :sup:`-1`) and +:math:`C_{fineroot}` is the amount of fine root carbon (kg m :sup:`-2`). + +:math:`\rho_{root}` is the root density (kg m :sup:`-3`), and +:math:`{CA}_{root}` is the fine root cross sectional area (m :sup:`2`) + +.. math:: + :label: 11.15 + + CA_{root} = \pi r_{root}^{2} + +where :math:`r_{root}` is the root radius (m). + .. _Plant Hydraulic Stress: Plant Hydraulic Stress @@ -88,10 +217,21 @@ conductivity (:math:`p50`) and a shape fitting parameter (:math:`c_k`). Stem-to-leaf '''''''''''''''''''''''' -The area basis and conductance parameterization varies by segment. There are two stem-to-leaf fluxes in parallel, from stem to sunlit leaf and from stem to shaded leaf (:math:`q_{1a}` and :math:`q_{1a}`). -The water flux from stem-to-leaf is the product of the segment conductance, the conducting area basis, and the water potential gradient from stem to leaf. Stem-to-leaf conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve. -The maximum conductance is a PFT parameter representing the maximum conductance of water from stem to leaf per unit leaf area. -This parameter can be defined separately for sunlit and shaded segments and should already include the appropriate length scaling (in other words this is a conductance, not conductivity). The water potential gradient is the difference between leaf water potential and stem water potential. There is no gravity term, assuming a negligible difference in height across the segment. The area basis is the leaf area index (either sunlit or shaded). +The area basis and conductance parameterization varies by segment. There +are two stem-to-leaf fluxes in parallel, from stem to sunlit leaf and from +stem to shaded leaf (:math:`q_{1a}` and :math:`q_{1a}`). The water flux from +stem-to-leaf is the product of the segment conductance, the conducting area +basis, and the water potential gradient from stem to leaf. Stem-to-leaf +conductance is defined as the maximum conductance multiplied by the percent +of maximum conductance, as calculated by the sigmoidal vulnerability curve. +The maximum conductance is a PFT parameter representing the maximum +conductance of water from stem to leaf per unit leaf area. This parameter +can be defined separately for sunlit and shaded segments and should already +include the appropriate length scaling (in other words this is a conductance, +not conductivity). The water potential gradient is the difference between +leaf water potential and stem water potential. There is no gravity term, +assuming a negligible difference in height across the segment. The area +basis is the leaf area index (either sunlit or shaded). .. math:: :label: 11.103 @@ -144,7 +284,18 @@ Parameters: Root-to-stem '''''''''''''''''''''''' -There is one root-to-stem flux. This represents a flux from the root collar to the upper branch reaches. The water flux from root-to-stem is the product of the segment conductance, the conducting area basis, and the water potential gradient from root to stem. Root-to-stem conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve (two parameters). The maximum conductance is defined as the maximum root-to-stem conductivity per unit stem area (PFT parameter) divided by the length of the conducting path, which is taken to be the vegetation height. The area basis is the stem area index. The gradient in water potential is the difference between the root water potential and the stem water potential less the difference in gravitational potential. +There is one root-to-stem flux. This represents a flux from the root collar +to the upper branch reaches. The water flux from root-to-stem is the product +of the segment conductance, the conducting area basis, and the water +potential gradient from root to stem. Root-to-stem conductance is defined +as the maximum conductance multiplied by the percent of maximum conductance, +as calculated by the sigmoidal vulnerability curve (two parameters). The +maximum conductance is defined as the maximum root-to-stem conductivity per +unit stem area (PFT parameter) divided by the length of the conducting path, +which is taken to be the vegetation height. The area basis is the stem area +index. The gradient in water potential is the difference between the root +water potential and the stem water potential less the difference in +gravitational potential. .. math:: :label: 11.107 @@ -181,13 +332,38 @@ Parameters: Soil-to-root '''''''''''''''''''''''' -There are several soil-to-root fluxes operating in parallel (one for each root-containing soil layer). Each represents a flux from the given soil layer to the root collar. The water flux from soil-to-root is the product of the segment conductance, the conducting area basis, and the water potential gradient from soil to root. The area basis is a proxy for root area index, defined as the summed leaf and stem area index multiplied by the root-to-shoot ratio (PFT parameter) multiplied by the layer root fraction. The root fraction comes from an empirical root profile (see section zqz). - -The gradient in water potential is the difference between the soil water potential and the root water potential less the difference in gravitational potential. There is only one root water potential to which all soil layers are connected in parallel. A soil-to-root flux can be either positive (vegetation water uptake) or negative (water deposition), depending on the relative values of the root and soil water potentials. This allows for the occurrence of hydraulic redistribution where water moves through vegetation tissue from one soil layer to another. - -Soil-to-root conductance is the result of two resistances in series, first across the soil-root interface and then through the root tissue. The root tissue conductance is defined as the maximum conductance multiplied by the percent of maximum conductance, as calculated by the sigmoidal vulnerability curve. The maximum conductance is defined as the maximum root-tissue conductivity (PFT parameter) divided by the length of the conducting path, which is taken to be the soil layer depth plus lateral root length. - -The soil-root interface conductance is defined as the soil conductivity divided by the conducting length from soil to root. The soil conductivity varies by soil layer and is calculated based on soil potential and soil properties, via the Brooks-Corey theory. The conducting length is computed by calculating the characteristic root spacing following Bonan-2014. The root spacing depends on total root biomass and PFT parameters defining root structure (see section zqz). +There are several soil-to-root fluxes operating in parallel (one for each +root-containing soil layer). Each represents a flux from the given soil +layer to the root collar. The water flux from soil-to-root is the product +of the segment conductance, the conducting area basis, and the water +potential gradient from soil to root. The area basis is a proxy for root +area index, defined as the summed leaf and stem area index multiplied by +the root-to-shoot ratio (PFT parameter) multiplied by the layer root +fraction. The root fraction comes from an empirical root profile (section +:numref:`Vertical Root Distribution`). + +The gradient in water potential is the difference between the soil water +potential and the root water potential less the difference in gravitational +potential. There is only one root water potential to which all soil layers +are connected in parallel. A soil-to-root flux can be either positive +(vegetation water uptake) or negative (water deposition), depending on the +relative values of the root and soil water potentials. This allows for the +occurrence of hydraulic redistribution where water moves through vegetation +tissue from one soil layer to another. + +Soil-to-root conductance is the result of two resistances in series, first +across the soil-root interface and then through the root tissue. The root +tissue conductance is defined as the maximum conductance multiplied by the +percent of maximum conductance, as calculated by the sigmoidal vulnerability +curve. The maximum conductance is defined as the maximum root-tissue +conductivity (PFT parameter) divided by the length of the conducting path, +which is taken to be the soil layer depth plus lateral root length. + +The soil-root interface conductance is defined as the soil conductivity +divided by the conducting length from soil to root. The soil conductivity +varies by soil layer and is calculated based on soil potential and soil +properties, via the Brooks-Corey theory. The conducting length is determined +from the characteristic root spacing (section :numref:`Root Spacing`). .. math:: :label: 11.109 @@ -214,16 +390,6 @@ The soil-root interface conductance is defined as the soil conductivity divided k_{s,i} = \dfrac{k_{soil,i}}{dx_{root,i}} -.. math:: - :label: 11.114 - - dx_{root,i} = \left(\pi*\mbox{root-length-density}_i\right)^{-0.5} - -.. math:: - :label: 11.115 - - \mbox{root-length-density} = \dfrac{\mbox{total root length}}{\mbox{soil volume}} - Variables: :math:`q_{3,i}` = flux of water (mmH2O/s) from soil layer :math:`i` to root diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 724fd493f8..699bef7769 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -526,6 +526,11 @@ Major, D.A., Reginato, R.J., and Hubbard, K.G. 1988. Interception and use efficiency of light in winter wheat under different nitrogen regimes. Agric. For. Meteor. 44:175-186. +.. _Gardner1960: + +Gardner, W. R. 1960. Dynamic aspects of water availability to plants, +Soil Sci., 89, 63–73. + .. _Gashetal1996: Gash, J.H.C., Nobre, C.A., Roberts, J.M., and Victoria, R.L. 1996. An From 8b846e92b9c2519e53539d59e958cc5713c60d93 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 9 Jun 2017 11:09:46 -0600 Subject: [PATCH 062/255] add references --- .../CLM50_Tech_Note_Introduction.rst | 2 +- .../CLM50_Tech_Note_Plant_Hydraulics.rst | 32 ------------ .../References/CLM50_Tech_Note_References.rst | 50 ++++++++++++++++--- 3 files changed, 44 insertions(+), 40 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index ed7a66f332..7f409914b2 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -224,7 +224,7 @@ Jinyun Tang, Zong-Liang Yang** - :numref:`Table Respiration fractions for Century-based structure` Respiration fractions for litter and SOM pools for Century-based structure -- :numref:`Table PFT-specific combustion completeness and fire mortality` PFT-specific combustion completeness and fire mortality factors. +- :numref:`Table PFT-specific combustion completeness and fire mortality factors` PFT-specific combustion completeness and fire mortality factors. - :numref:`Table Methane Parameter descriptions` Parameter descriptions and sensitivity analysis ranges applied in the methane model. diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index 703f9b8ed9..5e0063817b 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -717,35 +717,3 @@ The outermost level of iteration works towards convergence of leaf temperature, .. figure:: flow.png Flow diagram of leaf flux calculations - - -.. _PHS Refs: - -References ------------------------------ - -Local references. Will copy over - -.. _Bonanetal2014: - -Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling stomatal conductance in the earth system: linking leaf water-use efficiency and water transport along the soil–plant–atmosphere continuum, Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. - -.. _Chuangetal2006: - -Chuang Y.L., Oren R., Bertozzi A.L, Phillips N., Katul G.G. 2006. The porous media model for the hydraulic system of a conifer tree: Linking sap flux data to transpiration rate, Ecological Modelling, 191, 447-468, doi:10.1016/j.ecolmodel.2005.03.027. - -.. _Medlynetal2011: - -Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., Barton, C.V.M., 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. doi:10.1111/j.1365-2486.2010.02375.x - -.. _Sperryetal1998: - -Sperry, J.S., Adler, F.R., Campbell, G.S. and Comstock, J.P. (1998), Limitation of plant water use by rhizosphere and xylem conductance: results from a model. Plant, Cell & Environment, 21: 347–359. doi:10.1046/j.1365-3040.1998.00287.x - -.. _SperryandLove2015: - -Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us about responses to climate-change droughts. New Phytol, 207: 14–27. doi:10.1111/nph.13354 - -.. _Williamsetal1996: - -Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere continuum in a Quercus–Acer stand at Harvard Forest: the regulation of stomatal conductance by light, nitrogen and soil/plant hydraulic properties. Plant, Cell & Environment, 19: 911–927. doi:10.1111/j.1365-3040.1996.tb00456.x diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 699bef7769..076af343be 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -197,14 +197,12 @@ M. 2012. Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4, J. Geophys. Res., 117, G02026. DOI:10.1029/2011JG001913. -Branstetter, M.L., and Famiglietti, J.S. 1999. Testing the sensitivity -of GCM-simulated runoff to climate model resolution using a parallel -river transport algorithm. Preprints, 14\ :math:`{}^{th}` Conference on -Hydrology, Dallas, TX, Amer. Meteor. Soc., 391-392. +.. _Bonanetal2014: -Branstetter, M.L. 2001. Development of a parallel river transport -algorithm and applications to climate studies. Ph.D. dissertation, -University of Texas at Austin. +Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling +stomatal conductance in the earth system: linking leaf water-use +efficiency and water transport along the soil–plant–atmosphere continuum, +Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. .. _Brun1989: @@ -245,6 +243,13 @@ Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and methane emissions from natural wetlands: Application of a process-based model. J. Geophys. Res. 101(D9):14,399-14,414. +.. _Chuangetal2006: + +Chuang Y.L., Oren R., Bertozzi A.L, Phillips N., Katul G.G. 2006. The +porous media model for the hydraulic system of a conifer tree: Linking +sap flux data to transpiration rate, Ecological Modelling, 191, 447-468, +doi:10.1016/j.ecolmodel.2005.03.027. + .. _Churkinaetal2003: Churkina, G. et al., 2003. Analyzing the ecosystem carbon dynamics of @@ -1179,6 +1184,14 @@ carbon and nitrogen dynamics in estimating net primary productivity for potential vegetation in North America. Global Biogeochem. Cycles 6:101-124. +.. _Medlynetal2011: + +Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., +Barton, C.V.M., 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. +doi:10.1111/j.1365-2486.2010.02375.x + .. _MelzerOLeary1987: Melzer, E., and O’Leary, M.H. 1987. Anapleurotic CO2 Fixation by @@ -1692,6 +1705,19 @@ Sørensen, L.H., 1981. Carbon-nitrogen relationships during the humification of cellulose in soils containing different amounts of clay. Soil Biology and Biochemistry, 13: 313-321. +.. _Sperryetal1998: + +Sperry, J.S., Adler, F.R., Campbell, G.S. and Comstock, J.P. 1998. +Limitation of plant water use by rhizosphere and xylem conductance: +results from a model. Plant, Cell & Environment, 21: 347–359. +doi:10.1046/j.1365-3040.1998.00287.x + +.. _SperryandLove2015: + +Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us +about responses to climate-change droughts. New Phytol, 207: 14–27. +doi:10.1111/nph.13354 + .. _Sprugeletal1995: Sprugel, D.G., Ryan, M.G., Brooks, J.R., Vogt, K.A., and Martin, T.A. @@ -2001,6 +2027,16 @@ Parameterization and sensitivity analysis of the Biome-BGC terrestrial ecosystem model: net primary production controls. Earth Interactions 4:1-85. +.. _Williamsetal1996: + +Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., +Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. +and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere +continuum in a Quercus–Acer stand at Harvard Forest: the regulation +of stomatal conductance by light, nitrogen and soil/plant hydraulic +properties. Plant, Cell & Environment, 19: 911–927. +doi:10.1111/j.1365-3040.1996.tb00456.x + .. _WiscombeWarren1980: Wiscombe, W.J., and Warren, S.G. 1980. A model for the spectral albedo From 3b59bde5078b275f7bddff9b0c76c8f1c7b495e7 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Fri, 9 Jun 2017 17:34:13 -0600 Subject: [PATCH 063/255] Updated the N retranslocation section of the Crop chapter --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 110 ++++++++---------- 1 file changed, 49 insertions(+), 61 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 3ff2afc0b5..d130d29bb8 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -79,6 +79,9 @@ fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., :ref:`Kucharik and Brye 2003 `; :ref:`Lobell et al. 2006 `). +As implemented here, the crop model uses the same physiology as the +natural vegetation, though uses different crop-specific parameter values, +phenology, and allocation, as well as fertilizer and irrigation management. .. _Crop plant functional types: @@ -94,7 +97,7 @@ land management between crops. Each crop type has a rainfed and an irrigated pft that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural pfts), and the managed crop type proportions within the crop area is based on the dataset created by -(:ref:`Portmann et al. 2010 `) for present day and +(:ref:`Portmann et al. 2010 `) for present day. New in CLM5, crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries (:ref:`Lawrence et al. 2016 `). For more details about how @@ -105,8 +108,15 @@ CLM5 includes eight actively managed crop types corn, spring wheat, cotton, rice, and sugarcane) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by Badger and Dirmeyer (:ref:`2015 `) and -described by Levis et al. (:ref:`2016 `). In addition, -CLM’s default list of plant functional types (pfts) includes an +described by Levis et al. (:ref:`2016 `). The representations of +sugarcane, rice, cotton, tropical corn, and tropical soy are new in CLM5. +Sugarcane and tropical corn are both C4 plants and are therefore represented +using the temperate corn functional form. Tropical soybean uses the temperate +soybean functional form, while rice and cotton use the wheat functional form. +In tropical regions, parameter values were developed for the Amazon Basin, and planting +date window is shifted by six months relative to the Northern Hemisphere. + +In addition, CLM’s default list of plant functional types (pfts) includes an irrigated and unirrigated unmanaged C3 crop (Table 25.1) treated as a second C3 grass, The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and @@ -231,6 +241,8 @@ Phase 3 begins in one of two ways. The first potential trigger is based on tempe planting like :math:`GDD_{T_{soi} }` but for 2-m air temperature, :math:`GDD_{T_{{\rm 2m}} }`, must reach a heat unit threshold, *h*, of 40 to 65% of :math:`{GDD}_{mat}` (:numref:`Table Crop plant functional types`). +For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), +the :math:`{GDD}_{mat}` is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2, phase 3 begins. In phase 3, the leaf area index begins to decline in @@ -243,17 +255,17 @@ Harvest '''''''''''''''' Harvest is assumed to occur as soon as the crop reaches maturity. When -:math:`GDD_{T_{{\rm 2m}} }` reaches 100% of :math:`{GDD}_{mat}` or +:math:`GDD_{T_{{\rm 2m}} }` reaches 100% of :math:`{GDD}_{mat}` or the number of days past planting reaches a crop-specific maximum (:numref:`Table Crop plant functional types`)[update table reference], then the crop is harvested. Harvest occurs in one time step using -CN’s leaf offset algorithm. New variables track the flow of grain C and -N to food and of live stem C and N to litter. Currently, food C and N -are routed directly to litter using the labile, cellulose, and lignin -fractions for leaves. [update to product pool] The same fractions for leaves are used for the -flow of live stem C and N to litter for corn, soybean, and temperate -cereals. This is in contrast to the approach for unmanaged PFTs which -puts live stem C and N to dead stems first, rather than to litter. +CN’s leaf offset algorithm. Variables track the flow of grain C and +N to food and of live stem C and N to litter. Putting live +stem C and N into the litter pool is in contrast to the approach for unmanaged PFTs which +puts live stem C and N into dead stem pools first. Leaf and root C and N pools +are routed to the litter pools in the same manner as natural vegetation. In CLM5, food C and N +are routed to a grain product pool where the C and N decay to the atmosphere over one year, +similar in structure to the wood product pools. .. _Allocation: @@ -315,6 +327,12 @@ allocation decline factors, and :math:`a_{leaf}^{f}` and :math:`a_{livestem}^{f}` are final values of these allocation coefficients (:numref:`Table Crop pfts`). +Harvest to seed +'''''''''''''''''''''''''''''' + +In CLM5, the C and N required for crop seeding is removed from the grain +product pool during harvest and used to seed crops in the subsequent year. + .. _General comments: General comments @@ -664,54 +682,24 @@ the counter is reached. Biological nitrogen fixation for soybeans ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Nitrogen fixation by soybeans is similar to that in the SWAT model -(Neitsch et al. 2005) and depends on soil moisture, nitrogen -availability, and growth stage. Soybean fixation is calculated only for -unmet nitrogen demand; if soil nitrogen meets soybean demand, there will -be no fixation during the time step. Soybean fixation is determined by - -.. math:: - :label: 25.10 - - N_{fix} \; =\; N_{plant\_ ndemand} \; *\; min\; \left(\; 1,\; fxw,\; fxn\; \right)*\; fxg - -where :math:`{N}_{plant\_demand}` is the balance of nitrogen needed -to reach potential growth that cannot be supplied from the soil mineral -nitrogen pool, *fxw* is the soil water factor, *fxn* is the soil -nitrogen factor, and *fxg* is the growth stage factor calculated by - -.. math:: - :label: 25.11 - - fxw=\frac{wf}{0.85} - -.. math:: - :label: 25.12 - - fxn=\; \left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }sminn\le 10} \\ {1.5-0.005\left(sminn\times 10\right)\qquad {\rm for\; 10\; <\; }sminn{\rm \; }\ge 30} \\ {1\qquad \qquad \qquad \qquad {\rm for\; }sminn>30} \end{array}\right\} - -.. math:: - :label: 25.13 - - fxg=\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad \qquad {\rm for\; }GDD_{T_{2m} } \le 0.15} \\ {6.67\times GDD_{T_{2m} } -1\qquad \qquad \qquad {\rm for\; }0.150.75} \end{array}\right\} - -where *wf* is the soil water content as a fraction of the water holding -capacity for the top 0.05 m, *sminn* is the total nitrogen in the soil -pool (g/m:sup:`2`), and :math:`{GDD}_{T_{2m}}` is the fraction of -growing degree-days accumulated during the growing season. -:math:`N\mathrm{fix}` is added directly to the soil mineral nitrogen -pool for use that time step. Nitrogen fixation occurs after the plant -has accumulated 15%\ :math:`{GDD}_{mat}` and before -75%\ :math:`{GDD}_{mat}`, so before grain fill begins. +Biological N fixation for soybeans is calculated by the fixation and +uptake of nitrogen module [add reference to chapter 18]. Unlike natural +vegetation, where a fraction of the vegetation are N fixers, all soybeans +are treated as N fixers. .. _Modified C\:N ratios for crops: Modified C:N ratios for crops ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Typically, C:N ratios in plant tissue vary throughout the growing season -and tend to be lower during early growth stages and higher in later -growth stages. In order to account for this change, two sets of C:N +Carbon to nitrogen ratios (C:N) for crops are calculated by the flexible C:N +module that is new to CLM5. + +In CLM5, the flexible C:N module allows leaf C:N to vary based +on residual N allocated to the leaf pool after the demands of other plant organs +are met. Grain C/N is similarly xxx... + +In order to account for this change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops. This modified C:N ratio approach accounts for the nitrogen retranslocation that occurs during phase 3 of crop growth. Leaf and stem @@ -740,9 +728,9 @@ soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage -for corn and temperate cereals, but not until after LAI decline in -soybean. Nitrogen stored in the leaf and stem is moved into a storage -retranslocation pool. For temperate cereals, nitrogen in roots is also +for all crops except soybean, for which retranslocation is after LAI decline. +Nitrogen stored in the leaf and stem is moved into a storage +retranslocation pool. For wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized depends on the C:N ratio of the plant tissue, and is calculated as @@ -750,21 +738,21 @@ calculated as .. math:: :label: 25.14 - leaf\_ to\_ retransn=\frac{c_{leaf} }{CN_{leaf} } -\frac{c_{leaf} }{CN_{leaf}^{f} } + leaf\_ to\_ retransn=n_{leaf} -\frac{c_{leaf} }{CN_{leaf}^{f} } .. math:: :label: 25.15 - stemn\_ to\_ retransn=\frac{c_{stem} }{CN_{stem} } -\frac{c_{stem} }{CN_{stem}^{f} } + stemn\_ to\_ retransn=n_{stem} -\frac{c_{stem} }{CN_{stem}^{f} } .. math:: :label: 25.16 - frootn\_ to\_ retransn=\frac{c_{froot} }{CN_{froot} } -\frac{c_{froot} }{CN_{froot}^{f} } + frootn\_ to\_ retransn=n_{froot} -\frac{c_{froot} }{CN_{froot}^{f} } where :math:`{C}_{leaf}`, :math:`{C}_{stem}`, and :math:`{C}_{froot}` is the carbon in the plant leaf, stem, and fine -root, respectively, :math:`{CN}_{leaf}`, :math:`{CN}_{stem}`, and :math:`{CN}_{froot}` is the pre-grain fill C:N ratio of the -leaf, stem, and fine root respectively, and :math:`CN^f_{leaf}`, +root, respectively, :math:`{N}_{leaf}`, :math:`{N}_{stem}`, and :math:`{N}_{froot}` +is the nitrogen in the plant leaf, stem, and fine root, respectively, and :math:`CN^f_{leaf}`, :math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively (:numref:`Table Pre- and post-grain fill CN ratios`). Since C:N measurements are taken from mature crops, pre-grain development C:N From 9a4e0fe38d0bec27012d01c52e55f3ae9764034b Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Tue, 13 Jun 2017 12:14:07 -0600 Subject: [PATCH 064/255] Updated CN and N retranslocation sections of crop chapter --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 97 +++++-------------- 1 file changed, 24 insertions(+), 73 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index d130d29bb8..e54cb0d30f 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -101,7 +101,7 @@ proportions within the crop area is based on the dataset created by extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries (:ref:`Lawrence et al. 2016 `). For more details about how -crop distributions are determined, see chapter 26 on :ref:`rst_Transient Landcover Change`. +crop distributions are determined, see Chapter :numref: `rst_Transient Landcover Change`. CLM5 includes eight actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical @@ -117,7 +117,7 @@ In tropical regions, parameter values were developed for the Amazon Basin, and p date window is shifted by six months relative to the Northern Hemisphere. In addition, CLM’s default list of plant functional types (pfts) includes an -irrigated and unirrigated unmanaged C3 crop (Table 25.1) treated as a second C3 grass, +irrigated and unirrigated unmanaged C3 crop (Table 25.1) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used @@ -128,7 +128,7 @@ Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is -included in Table 25.1. It should be noted that analysis with pft-level history output merges +included in Table 25.1. It should be noted that pft-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. @@ -588,52 +588,6 @@ river water storage is maintained above a specified threshold. The details about what is new in CLM4.5 -------------------------------------------- -.. _Interactive irrigation for corn, temperate cereals, and soybean: - -Interactive irrigation for corn, temperate cereals, and soybean -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CLM4.0 included interactive irrigation only for the generic C3 crops, -i.e. plant functional types (pfts) 15 (rainfed) and 16 (irrigated) in -the CLM list of pfts and not for the additional crops of the interactive -crop management model (CROP). Irrigation and CROP were mutually -exclusive in CLM4.0. - -In CLM4.5 we have reversed this situation. Now the irrigation model can -be used only while running with CROP. To accomplish this we downloaded -data of percent irrigated and percent rainfed corn, soybean, and -temperate cereals (wheat, barley, and rye) (:ref:`Portmann et al. 2010 `), -available online from - -*ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* - -We embedded this data in CLM’s high-resolution pft data for use with the -tool mksurfdat to generate surface datasets at any desired resolution. -Now this data includes percent cover for 24 pfts: - -1-16 as in the standard list of pfts, plus six more: - -17 corn - -18 irrigated\_corn - -19 spring\_temperate\_cereal - -20 irrigated\_spring\_temperate\_cereal - -21 winter\_temperate\_cereal - -22 irrigated\_winter\_temperate\_cereal - -23 soybean - -24 irrigated\_soybean - -We intend surface datasets with 24 pfts only for CROP simulations with -or without irrigation. In simulations without irrigation, the rainfed -and irrigated crops merge into just rainfed crops at run time. Surface -datasets with 16 pfts can be used for all other CLM simulations. - .. _Interactive fertilization: Interactive fertilization @@ -682,30 +636,27 @@ the counter is reached. Biological nitrogen fixation for soybeans ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Biological N fixation for soybeans is calculated by the fixation and -uptake of nitrogen module [add reference to chapter 18]. Unlike natural +Biological N fixation for soybeans is calculated by the fixation and uptake of +nitrogen module (Chapter :numref:`rst_FUN`). Unlike natural vegetation, where a fraction of the vegetation are N fixers, all soybeans are treated as N fixers. .. _Modified C\:N ratios for crops: -Modified C:N ratios for crops +C:N ratios for crops ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Carbon to nitrogen ratios (C:N) for crops are calculated by the flexible C:N -module that is new to CLM5. - -In CLM5, the flexible C:N module allows leaf C:N to vary based -on residual N allocated to the leaf pool after the demands of other plant organs -are met. Grain C/N is similarly xxx... - -In order to account for this change, two sets of C:N +Typically, C:N ratios in plant tissue vary throughout the growing season and +tend to be lower during early growth stages and higher in later growth stages. +In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops. This modified C:N ratio approach accounts for the nitrogen -retranslocation that occurs during phase 3 of crop growth. Leaf and stem -(and root for temperate cereals) C:N ratios for phases 1 and 2 are lower -than measurements (Table 20.3) to allow excess nitrogen storage in plant -tissue. During grain fill (phase 3) of the crop growth cycle, the +retranslocation that occurs during phase 3 of crop growth. Leaf, stem, and root +C:N ratios for phases 1 and 2 are calculated +using the new CLM5 carbon and nitrogen allocation scheme +(Chapter :numref:`rst_CN Allocation`), which provides a target C:N value +and allows C:N to vary through time. +During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at @@ -720,9 +671,10 @@ Nitrogen retranslocation for crops Nitrogen retranslocation in crops occurs when nitrogen that was used for tissue growth of leaves, stems, and fine roots during the early growth -season is remobilized and used for grain development (Pollmer et al. -1979; Crawford et al. 1982; Simpson et al. 1983; Ta and Weiland 1992; -Barbottin et al. 2005; Gallais et al. 2006, 2007). Nitrogen allocation +season is remobilized and used for grain development (:ref:`Pollmer et al. 1979 +`, :ref:`Crawford et al. 1982 `, :ref:`Simpson et al. 1983 +`, :ref:`Ta and Weiland 1992 `, :ref:`Barbottin et al. 2005 `, +:ref:`Gallais et al. 2006 `, :ref:`Gallais et al. 2007 `). Nitrogen allocation for crops follows that of natural vegetation, is supplied in CLM by the soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled @@ -798,13 +750,12 @@ Separate reproductive pool One notable difference between natural vegetation and crops is the presence of a reproductive carbon pool (and nitrogen pool). Accounting for the reproductive pool helps determine whether crops are performing -reasonably, through yield calculations, seasonal GPP and NEE changes, -etc. The reproductive pool is maintained similarly to the leaf, stem, +reasonably through yield calculations. +The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not -begin until the grain fill stage of crop development. Eq. shows the -carbon and nitrogen allocation coefficients to the reproductive pool. In -the CLM4.0, allocation of carbon to the reproductive pool was calculated -but merged with the stem pool. In the model, as allocation declines +begin until the grain fill stage of crop development. Eq. :eq:`(5)` shows the +carbon and nitrogen allocation coefficients to the reproductive pool. +In CLM, as allocation declines during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. From 88ca8dab03e41c3f0286e7294b06699ffa69f31f Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Tue, 13 Jun 2017 15:14:54 -0600 Subject: [PATCH 065/255] Restructured text in crop chapter --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 432 +++++++----------- 1 file changed, 176 insertions(+), 256 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index e54cb0d30f..7d959d3f39 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -69,8 +69,9 @@ management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) `] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with -CLM4CN (:ref:`Levis et al. 2012 `), with additional updates -available by request after the release of CLM4.5 (:ref:`Levis et al. 2016 `). +CLM4CN (:ref:`Levis et al. 2012 `), and CLM4.5. Additional updates after the +release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), +and those are now incorporated into CLM5. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM’s @@ -101,7 +102,7 @@ proportions within the crop area is based on the dataset created by extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries (:ref:`Lawrence et al. 2016 `). For more details about how -crop distributions are determined, see Chapter :numref: `rst_Transient Landcover Change`. +crop distributions are determined, see Chapter :numref:`rst_Transient Landcover Change`. CLM5 includes eight actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical @@ -138,10 +139,10 @@ remap the yields of each actively and inactively managed crop type. Phenology ^^^^^^^^^^^^^^^^ -CLM4.5CN includes evergreen, seasonally deciduous (responding to changes +CLM5-BGC includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in -temperature and/or soil moisture) phenology algorithms (Chapter 14). In -CLM4.5CNcrop we have added the AgroIBIS crop phenology algorithm, +temperature and/or soil moisture) phenology algorithms (Chapter :numref:`rst_Vegetation Phenology and Turnover`). +CLM5-BGC-crop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. Phase 1 starts at planting and ends with leaf emergence, phase 2 @@ -247,7 +248,7 @@ The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2, phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of -leaf longevity for the pft as done in the CN part of the model. +leaf longevity for the pft as done in the BGC part of the model. .. _Harvest: @@ -257,14 +258,15 @@ Harvest Harvest is assumed to occur as soon as the crop reaches maturity. When :math:`GDD_{T_{{\rm 2m}} }` reaches 100% of :math:`{GDD}_{mat}` or the number of days past planting reaches a crop-specific maximum -(:numref:`Table Crop plant functional types`)[update table reference], then the crop is harvested. +(:numref:`Table Crop plant functional types`), then the crop is harvested. Harvest occurs in one time step using -CN’s leaf offset algorithm. Variables track the flow of grain C and +the BGC leaf offset algorithm. Variables track the flow of grain C and N to food and of live stem C and N to litter. Putting live stem C and N into the litter pool is in contrast to the approach for unmanaged PFTs which puts live stem C and N into dead stem pools first. Leaf and root C and N pools -are routed to the litter pools in the same manner as natural vegetation. In CLM5, food C and N -are routed to a grain product pool where the C and N decay to the atmosphere over one year, +are routed to the litter pools in the same manner as natural vegetation. Whereas food C and N +formerly was transferred to the litter pool, CLM5 routes food C and N +to a grain product pool where the C and N decay to the atmosphere over one year, similar in structure to the wood product pools. .. _Allocation: @@ -272,12 +274,40 @@ similar in structure to the wood product pools. Allocation ^^^^^^^^^^^^^^^^^ -Allocation responds to the same phases as phenology (section 20.2.3). +Allocation responds to the same phases as phenology (section :numref: `_Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop’s leaf, live stem, fine root, and reproductive pools. +Typically, C:N ratios in plant tissue vary throughout the growing season and +tend to be lower during early growth stages and higher in later growth stages. +In order to account for this seasonal change, two sets of C:N +ratios are established in CLM for the leaf, stem, and fine root of +crops. This modified C:N ratio approach accounts for the nitrogen +retranslocation that occurs during phase 3 of crop growth. Leaf, stem, and root +C:N ratios for phases 1 and 2 are calculated +using the new CLM5 carbon and nitrogen allocation scheme +(Chapter :numref:`rst_CN Allocation`), which provides a target C:N value +and allows C:N to vary through time. +During grain fill (phase 3) of the crop growth cycle, a portion of the +nitrogen in the plant tissues is moved to a storage pool to fulfill +nitrogen demands of organ (reproductive pool) development, such that the +resulting C:N ratio of the plant tissue is reflective of measurements at +harvest. All C:N ratios were determined by calibration process, through +comparisons of model output versus observations of plant carbon +throughout the growth season. + +The BGC part of the model keeps track of a term representing excess +maintenance respiration that for perennial pfts or pfts with C storage +may be extracted from later gross primary production. Later extraction +cannot continue to happen after harvest for annual crops, so at harvest +we turn the excess respiration pool into a flux that extracts +CO\ :sub:`2` directly from the atmosphere. This way we eliminate +any excess maintenance respiration remaining at harvest as if such +respiration had not taken place. + + .. _Leaf emergence to grain fill: Leaf emergence to grain fill @@ -327,27 +357,72 @@ allocation decline factors, and :math:`a_{leaf}^{f}` and :math:`a_{livestem}^{f}` are final values of these allocation coefficients (:numref:`Table Crop pfts`). -Harvest to seed +Nitrogen retranslocation for crops +,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Nitrogen retranslocation in crops occurs when nitrogen that was used for +tissue growth of leaves, stems, and fine roots during the early growth +season is remobilized and used for grain development (:ref:`Pollmer et al. 1979 +`, :ref:`Crawford et al. 1982 `, :ref:`Simpson et al. 1983 +`, :ref:`Ta and Weiland 1992 `, :ref:`Barbottin et al. 2005 `, +:ref:`Gallais et al. 2006 `, :ref:`Gallais et al. 2007 `). Nitrogen allocation +for crops follows that of natural vegetation, is supplied in CLM by the +soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, +roots, and organs. Nitrogen demand during organ development is fulfilled +through retranslocation from leaves, stems, and roots. Nitrogen +retranslocation is initiated at the beginning of the grain fill stage +for all crops except soybean, for which retranslocation is after LAI decline. +Nitrogen stored in the leaf and stem is moved into a storage +retranslocation pool. For wheat and rice, nitrogen in roots is also +released into the retranslocation storage pool. The quantity of nitrogen +mobilized depends on the C:N ratio of the plant tissue, and is +calculated as + +.. math:: + :label: 25.14 + + leaf\_ to\_ retransn=n_{leaf} -\frac{c_{leaf} }{CN_{leaf}^{f} } + +.. math:: + :label: 25.15 + + stemn\_ to\_ retransn=n_{stem} -\frac{c_{stem} }{CN_{stem}^{f} } + +.. math:: + :label: 25.16 + + frootn\_ to\_ retransn=n_{froot} -\frac{c_{froot} }{CN_{froot}^{f} } + +where :math:`{C}_{leaf}`, :math:`{C}_{stem}`, and :math:`{C}_{froot}` is the carbon in the plant leaf, stem, and fine +root, respectively, :math:`{N}_{leaf}`, :math:`{N}_{stem}`, and :math:`{N}_{froot}` +is the nitrogen in the plant leaf, stem, and fine root, respectively, and :math:`CN^f_{leaf}`, +:math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N +ratio of the leaf, stem, and fine root respectively (:numref:`Table Pre- and post-grain fill CN ratios`). Since +C:N measurements are taken from mature crops, pre-grain development C:N +ratios for leaves, stems, and roots are optimized to allow maximum +nitrogen accumulation for later use during organ development. Post-grain +fill C:N ratios are assigned the same as crop residue. Once excess +nitrogen is moved into the retranslocated pool, during the remainder of +the growing season the retranslocated pool is used first to meet plant +nitrogen demand by assigning the available nitrogen from the +retranslocated pool equal to the plant nitrogen demand. Once the +retranslocation pool is depleted, soil mineral nitrogen pool is used to +fulfill plant nitrogen demands. + +Harvest to food and seed '''''''''''''''''''''''''''''' In CLM5, the C and N required for crop seeding is removed from the grain -product pool during harvest and used to seed crops in the subsequent year. +product pool during harvest and used to seed crops in the subsequent year. +Caluating the crop yields requires... .. _General comments: -General comments +Other Features ^^^^^^^^^^^^^^^^^^^^^^^ -C and N accounting now includes new pools and fluxes pertaining to live -stems and reproductive tissues. For example, the calculations of growth -respiration, above ground net primary production, litter fall, and -displayed vegetation all now account for reproductive C. - -We track allocation to reproductive C separately from CN’s allocation to -other C pools but within the CN framework. CN uses -:math:`{\textstyle\frac{a_{root} }{a_{leaf} }}` and :math:`{\textstyle\frac{a_{livestem} }{a_{leaf} }}` to calculate C and -N allometry and plant N demand. - +Physical Crop Characteristics +'''''''''''''''''''''''''''''' Stem area index (*S*) is equal to 0.1\ *L* for corn and 0.2\ *L* for other crops, as in AgroIBIS, where *L* is the leaf area index. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to @@ -364,47 +439,92 @@ and :math:`{z}_{bot}` (m), come from the AgroIBIS formulation: {z_{bot} =0.02{\rm m}} \end{array} -The CN part of the model keeps track of a term representing excess -maintenance respiration that for perennial pfts or pfts with C storage -may be extracted from later gross primary production. Later extraction -cannot continue to happen after harvest for annual crops, so at harvest -we turn the excess respiration pool into a flux that extracts -CO\ :sub:`2` directly from the atmosphere. This way we eliminate -any excess maintenance respiration remaining at harvest as if such -respiration had not taken place. +.. _Interactive fertilization: + +Interactive Fertilization +'''''''''''''''''''''''''''''' +CLM adds nitrogen directly to the soil mineral nitrogen pool to meet +crop nitrogen demands. CLM’s separate crop land unit ensures that +natural vegetation will not access the fertilizer applied to crops. +Fertilizer in CLM5BGCCROP is prescribed by crop function types spatially +for each year based on the LUMIP land use and land cover change +time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). +There are two fields that are used to prescribe industrial fertilizer. +On the surface data set the field CONST_FERTNITRO_CFT specifies the +annual fertilizer application for a non-transient simulations in g N/m\ :sup:`2`/yr. +In the case of a transient simulation this is replaced by the landuse.timeseries +file with the field FERTNITRO_CFT which is also in g N/m\ :sup:`2`/yr. +The values for both of these fields come from the LUMIP time series for each year. +In addition to the industrial fertilizer there is a background manure fertilizer +on the clm parameters file with the field manunitro. For the current CLM5BGCCROP, +this is set to 0.002 kg N/m\ :sup:`2`/yr. Since CLM’s denitrification rate is high +and results in a 50% loss of the unused available nitrogen each day, +fertilizer is applied slowly to minimize the loss and maximize plant +uptake. Fertilizer application begins during the emergence phase of crop +development and continues for 20 days, which helps reduce large losses +of nitrogen from leaching and denitrification during the early stage of +crop development. The 20-day period is chosen as an optimization to +limit fertilizer application to the emergence stage. A fertilizer +counter in seconds, *f*, is set as soon as the onset growth for crops +initiates: -In the list of plant physiological and other parameters used by the CLM, -we started the managed crops with the existing values assigned to the -unmanaged C3 crop. Then we changed the following parameters to -distinguish corn, soybean, and temperate cereals from the unmanaged C3 -crop and from each other: +.. math:: + :label: 25.18 -#. Growth respiration coefficient from 0.30 to the AgroIBIS value of - 0.25. + f = n \times 86400 -#. Fraction of leaf N in the Rubisco enzyme from 0.1 to 0.2 g N Rubisco - g\ :sup:`-1` N leaf for temperate cereals to increase - productivity (not chosen based on AgroIBIS). +where *n* is set to 20 fertilizer application days. When the crop enters +phase 2 (leaf emergence to the beginning of grain fill) of its growth +cycle, fertilizer application begins by initializing fertilizer amount +to the total fertilizer at each grid cell divided by the initialized *f*. +Fertilizer is applied and *f* is decremented each time step until a zero balance on +the counter is reached. -#. Fraction of current photosynthesis displayed as growth changed from - 0.5 to 1 (not chosen based on AgroIBIS). -#. CLM4.5CN curve for the effect of temperature on photosynthesis - instead of crop-specific curves from AgroIBIS. +.. _Biological nitrogen fixation for soybeans: -#. Quantum efficiency at 25\ :sup:`o`\ C, - :math:`\alpha` , from 0.06 to 0.04 *µ*\ mol CO\ :sub:`2` *µ*\ mol\ :sup:`-1` photon for C4 crops (corn and unmanaged C4 - crop), using CLM4.5CN’s C4 grass value. +Biological nitrogen fixation for soybeans +'''''''''''''''''''''''''''''' +Biological N fixation for soybeans is calculated by the fixation and uptake of +nitrogen module (Chapter :numref:`rst_FUN`). Unlike natural +vegetation, where a fraction of the vegetation are N fixers, all soybeans +are treated as N fixers. -#. Slope, *m*, of conductance-to-photosynthesis relationship from 9 to 4 for C4 crops as in AgroIBIS. +.. _Latitude vary base tempereature for growing degree days: -#. Specific leaf areas, *SLA*, to the AgroIBIS values (:numref:`Table Crop plant functional types`). +Latitude vary base tempereature for growing degree days +'''''''''''''''''''''''''''''' +For both rainfed and irrigated spring wheat and sugarcane, +a latitude vary base temperature in calculating :math:`GDD_{T_{{\rm 2m}} }` +(growing degree days since planting) was introduced. -#. Leaf orientation, :math:`\chi _{L}`, to the AgroIBIS values (:numref:`Table Crop plant functional types`). +.. math:: + :label: 25.17 -#. Soil moisture photosynthesis limitation factor, - :math:`\beta _{t}`, for soybeans multiplied as in AgroIBIS by 1.25 - for increased drought tolerance. + latitude\ vary\ baset = \left\{ + \begin{array}{lr} + baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ + baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 + \end{array} \right\} + +where :math:`baset` is the 5\ :sup:`th` column in :numref:`Table Crop plant functional types`. +Such latitude vary baset could increase the base temperature, slow down :math:`GDD_{T_{{\rm 2m}} }` +accumulation, and extend the growing season for -30º to 30º regions for spring wheat +and sugarcane. + +Separate reproductive pool +'''''''''''''''''''''''''''''' +One notable difference between natural vegetation and crops is the +presence of a reproductive carbon pool (and nitrogen pool). Accounting +for the reproductive pool helps determine whether crops are performing +reasonably through yield calculations. +The reproductive pool is maintained similarly to the leaf, stem, +and fine root pools, but allocation of carbon and nitrogen does not +begin until the grain fill stage of crop development. Eq. :eq:`(5)` shows the +carbon and nitrogen allocation coefficients to the reproductive pool. +In CLM, as allocation declines +during the grain fill stage of growth, increasing amounts of carbon and +nitrogen are available for grain development. .. _Table Crop plant functional types: @@ -581,203 +701,3 @@ river water storage is maintained above a specified threshold. available online from *ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* - - -.. _The details about what is new in CLM4.5: - -The details about what is new in CLM4.5 --------------------------------------------- - -.. _Interactive fertilization: - -Interactive fertilization -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CLM adds nitrogen directly to the soil mineral nitrogen pool to meet -crop nitrogen demands. CLM’s separate crop land unit ensures that -natural vegetation will not access the fertilizer applied to crops. -Fertilizer in CLM5BGCCROP is prescribed by crop function types spatially -for each year based on the LUMIP land use and land cover change -time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). -There are two fields that are used to prescribe industrial fertilizer. -On the surface data set the field CONST_FERTNITRO_CFT specifies the -annual fertilizer application for a non-transient simulations in g N/m\ :sup:`2`/yr. -In the case of a transient simulation this is replaced by the landuse.timeseries -file with the field FERTNITRO_CFT which is also in g N/m\ :sup:`2`/yr. -The values for both of these fields come from the LUMIP time series for each year. -In addition to the industrial fertilizer there is a background manure fertilizer -on the clm parameters file with the field manunitro. For the current CLM5BGCCROP, -this is set to 0.002 kg N/m\ :sup:`2`/yr. Since CLM’s denitrification rate is high -and results in a 50% loss of the unused available nitrogen each day, -fertilizer is applied slowly to minimize the loss and maximize plant -uptake. Fertilizer application begins during the emergence phase of crop -development and continues for 20 days, which helps reduce large losses -of nitrogen from leaching and denitrification during the early stage of -crop development. The 20-day period is chosen as an optimization to -limit fertilizer application to the emergence stage. A fertilizer -counter in seconds, *f*, is set as soon as the onset growth for crops -initiates: - -.. math:: - :label: 25.18 - - f = n \times 86400 - -where *n* is set to 20 fertilizer application days. When the crop enters -phase 2 (leaf emergence to the beginning of grain fill) of its growth -cycle, fertilizer application begins by initializing fertilizer amount -to the total fertilizer at each grid cell divided by the initialized *f*. -Fertilizer is applied and *f* is decremented each time step until a zero balance on -the counter is reached. - - -.. _Biological nitrogen fixation for soybeans: - -Biological nitrogen fixation for soybeans -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Biological N fixation for soybeans is calculated by the fixation and uptake of -nitrogen module (Chapter :numref:`rst_FUN`). Unlike natural -vegetation, where a fraction of the vegetation are N fixers, all soybeans -are treated as N fixers. - -.. _Modified C\:N ratios for crops: - -C:N ratios for crops -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Typically, C:N ratios in plant tissue vary throughout the growing season and -tend to be lower during early growth stages and higher in later growth stages. -In order to account for this seasonal change, two sets of C:N -ratios are established in CLM for the leaf, stem, and fine root of -crops. This modified C:N ratio approach accounts for the nitrogen -retranslocation that occurs during phase 3 of crop growth. Leaf, stem, and root -C:N ratios for phases 1 and 2 are calculated -using the new CLM5 carbon and nitrogen allocation scheme -(Chapter :numref:`rst_CN Allocation`), which provides a target C:N value -and allows C:N to vary through time. -During grain fill (phase 3) of the crop growth cycle, a portion of the -nitrogen in the plant tissues is moved to a storage pool to fulfill -nitrogen demands of organ (reproductive pool) development, such that the -resulting C:N ratio of the plant tissue is reflective of measurements at -harvest. All C:N ratios were determined by calibration process, through -comparisons of model output versus observations of plant carbon -throughout the growth season. - -.. _Nitrogen retranslocation for crops: - -Nitrogen retranslocation for crops -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Nitrogen retranslocation in crops occurs when nitrogen that was used for -tissue growth of leaves, stems, and fine roots during the early growth -season is remobilized and used for grain development (:ref:`Pollmer et al. 1979 -`, :ref:`Crawford et al. 1982 `, :ref:`Simpson et al. 1983 -`, :ref:`Ta and Weiland 1992 `, :ref:`Barbottin et al. 2005 `, -:ref:`Gallais et al. 2006 `, :ref:`Gallais et al. 2007 `). Nitrogen allocation -for crops follows that of natural vegetation, is supplied in CLM by the -soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, -roots, and organs. Nitrogen demand during organ development is fulfilled -through retranslocation from leaves, stems, and roots. Nitrogen -retranslocation is initiated at the beginning of the grain fill stage -for all crops except soybean, for which retranslocation is after LAI decline. -Nitrogen stored in the leaf and stem is moved into a storage -retranslocation pool. For wheat and rice, nitrogen in roots is also -released into the retranslocation storage pool. The quantity of nitrogen -mobilized depends on the C:N ratio of the plant tissue, and is -calculated as - -.. math:: - :label: 25.14 - - leaf\_ to\_ retransn=n_{leaf} -\frac{c_{leaf} }{CN_{leaf}^{f} } - -.. math:: - :label: 25.15 - - stemn\_ to\_ retransn=n_{stem} -\frac{c_{stem} }{CN_{stem}^{f} } - -.. math:: - :label: 25.16 - - frootn\_ to\_ retransn=n_{froot} -\frac{c_{froot} }{CN_{froot}^{f} } - -where :math:`{C}_{leaf}`, :math:`{C}_{stem}`, and :math:`{C}_{froot}` is the carbon in the plant leaf, stem, and fine -root, respectively, :math:`{N}_{leaf}`, :math:`{N}_{stem}`, and :math:`{N}_{froot}` -is the nitrogen in the plant leaf, stem, and fine root, respectively, and :math:`CN^f_{leaf}`, -:math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N -ratio of the leaf, stem, and fine root respectively (:numref:`Table Pre- and post-grain fill CN ratios`). Since -C:N measurements are taken from mature crops, pre-grain development C:N -ratios for leaves, stems, and roots are optimized to allow maximum -nitrogen accumulation for later use during organ development. Post-grain -fill C:N ratios are assigned the same as crop residue. Once excess -nitrogen is moved into the retranslocated pool, during the remainder of -the growing season the retranslocated pool is used first to meet plant -nitrogen demand by assigning the available nitrogen from the -retranslocated pool equal to the plant nitrogen demand. Once the -retranslocation pool is depleted, soil mineral nitrogen pool is used to -fulfill plant nitrogen demands. - -.. _Table Pre- and post-grain fill CN ratios: - -.. table:: Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. - - +----------------------------+--------+---------------------+-----------+ - | Pre-grain fill stage | Corn | Temperate Cereals | Soybean | - +============================+========+=====================+===========+ - | :math:`{CN}_{leaf}` | 10 | 15 | 25 | - +----------------------------+--------+---------------------+-----------+ - | :math:`{CN}_{stem}` | 50 | 50 | 50 | - +----------------------------+--------+---------------------+-----------+ - | :math:`{CN}_{froot}` | 42 | 30 | 42 | - +----------------------------+--------+---------------------+-----------+ - | Post-grain fill stage | | | | - +----------------------------+--------+---------------------+-----------+ - | :math:`CN_{leaf}^{f}` | 65 | 65 | 65 | - +----------------------------+--------+---------------------+-----------+ - | :math:`CN_{stem}^{f}` | 120 | 100 | 130 | - +----------------------------+--------+---------------------+-----------+ - | :math:`CN_{froot}^{f}` | 42 | 40 | 42 | - +----------------------------+--------+---------------------+-----------+ - | :math:`CN_{repr}^{f}` | 50 | 40 | 60 | - +----------------------------+--------+---------------------+-----------+ - -.. _Separate reproductive pool: - -Separate reproductive pool -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One notable difference between natural vegetation and crops is the -presence of a reproductive carbon pool (and nitrogen pool). Accounting -for the reproductive pool helps determine whether crops are performing -reasonably through yield calculations. -The reproductive pool is maintained similarly to the leaf, stem, -and fine root pools, but allocation of carbon and nitrogen does not -begin until the grain fill stage of crop development. Eq. :eq:`(5)` shows the -carbon and nitrogen allocation coefficients to the reproductive pool. -In CLM, as allocation declines -during the grain fill stage of growth, increasing amounts of carbon and -nitrogen are available for grain development. - -.. _Latitude vary base tempereature for growing degree days: - -Latitude vary base tempereature for growing degree days -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For both rainfed and irrigated spring wheat and sugarcane, -a latitude vary base temperature in calculating :math:`GDD_{T_{{\rm 2m}} }` -(growing degree days since planting) was introduced. - -.. math:: - :label: 25.17 - - latitude\ vary\ baset = \left\{ - \begin{array}{lr} - baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ - baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 - \end{array} \right\} - -where :math:`baset` is the 5\ :sup:`th` column in :numref:`Table Crop plant functional types`. -Such latitude vary baset could increase the base temperature, slow down :math:`GDD_{T_{{\rm 2m}} }` -accumulation, and extend the growing season for -30º to 30º regions for spring wheat -and sugarcane. From 4cf8315e1c6cbed837761b7ec6ef8e923ca9a216 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 13 Jun 2017 16:45:17 -0600 Subject: [PATCH 066/255] Update html --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 7d959d3f39..f7219c640e 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -358,7 +358,7 @@ allocation decline factors, and :math:`a_{leaf}^{f}` and coefficients (:numref:`Table Crop pfts`). Nitrogen retranslocation for crops -,,,,,,,,,,,,,,,,,,,,,,,,,,,, +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, Nitrogen retranslocation in crops occurs when nitrogen that was used for tissue growth of leaves, stems, and fine roots during the early growth @@ -484,7 +484,7 @@ the counter is reached. .. _Biological nitrogen fixation for soybeans: Biological nitrogen fixation for soybeans -'''''''''''''''''''''''''''''' +'''''''''''''''''''''''''''''''''''''''''' Biological N fixation for soybeans is calculated by the fixation and uptake of nitrogen module (Chapter :numref:`rst_FUN`). Unlike natural vegetation, where a fraction of the vegetation are N fixers, all soybeans @@ -493,7 +493,7 @@ are treated as N fixers. .. _Latitude vary base tempereature for growing degree days: Latitude vary base tempereature for growing degree days -'''''''''''''''''''''''''''''' +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' For both rainfed and irrigated spring wheat and sugarcane, a latitude vary base temperature in calculating :math:`GDD_{T_{{\rm 2m}} }` (growing degree days since planting) was introduced. From 9d9e6e71b0eb5ff1be5e9a5cda747028e86b26c3 Mon Sep 17 00:00:00 2001 From: Yaqiong Lu Date: Wed, 14 Jun 2017 12:55:06 -0600 Subject: [PATCH 067/255] updated crop chapter tables and text --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 307 ++++++++++++------ 1 file changed, 201 insertions(+), 106 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index f7219c640e..a9eafc3320 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -118,7 +118,7 @@ In tropical regions, parameter values were developed for the Amazon Basin, and p date window is shifted by six months relative to the Northern Hemisphere. In addition, CLM’s default list of plant functional types (pfts) includes an -irrigated and unirrigated unmanaged C3 crop (Table 25.1) treated as a second C3 grass. +irrigated and unirrigated unmanaged C3 crop (:numref:`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used @@ -129,11 +129,86 @@ Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is -included in Table 25.1. It should be noted that pft-level history output merges +included in :numref:`Table Crop plant functional types`. It should be noted that pft-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. +.. _Table Crop plant functional types: + +.. table:: Crop plant functional types (pfts) in CLM5BGCCROP. + + === =========================== ================ =========================== + ITV Plant function types (PFTs) Management Class Crop Parameters Used + === =========================== ================ =========================== + 15 c3 unmanaged rainfed crop none not applicable + 16 c3 unmanaged irrigated crop none not applicable + 17 rainfed temperate corn active rainfed temperate corn + 18 irrigated temperate corn active irrigated temperate corn + 19 rainfed spring wheat active rainfed spring wheat + 20 irrigated spring wheat active irrigated spring wheat + 21 rainfed winter wheat inactive rainfed spring wheat + 22 irrigated winter wheat inactive irrigated spring wheat + 23 rainfed temperate soybean active rainfed temperate soybean + 24 irrigated temperate soybean active irrigated temperate soybean + 25 rainfed barley inactive rainfed spring wheat + 26 irrigated barley inactive irrigated spring wheat + 27 rainfed winter barley inactive rainfed spring wheat + 28 irrigated winter barley inactive irrigated spring wheat + 29 rainfed rye inactive rainfed spring wheat + 30 irrigated rye inactive irrigated spring wheat + 31 rainfed winter rye inactive rainfed spring wheat + 32 irrigated winter rye inactive irrigated spring wheat + 33 rainfed cassava inactive rainfed rice + 34 irrigated cassava inactive irrigated rice + 35 rainfed citrus inactive rainfed spring wheat + 36 irrigated citrus inactive irrigated spring wheat + 37 rainfed cocoa inactive rainfed rice + 38 irrigated cocoa inactive irrigated rice + 39 rainfed coffee inactive rainfed rice + 40 irrigated coffee inactive irrigated rice + 41 rainfed cotton active rainfed cotton + 42 irrigated cotton active irrigated cotton + 43 rainfed datepalm inactive rainfed cotton + 44 irrigated datepalm inactive irrigated cotton + 45 rainfed foddergrass inactive rainfed spring wheat + 46 irrigated foddergrass inactive irrigated spring wheat + 47 rainfed grapes inactive rainfed spring wheat + 48 irrigated grapes inactive irrigated spring wheat + 49 rainfed groundnuts inactive rainfed rice + 50 irrigated groundnuts inactive irrigated rice + 51 rainfed millet inactive rainfed tropical corn + 52 irrigated millet inactive irrigated tropical corn + 53 rainfed oilpalm inactive rainfed rice + 54 irrigated oilpalm inactive irrigated rice + 55 rainfed potatoes inactive rainfed spring wheat + 56 irrigated potatoes inactive irrigated spring wheat + 57 rainfed pulses inactive rainfed spring wheat + 58 irrigated pulses inactive irrigated spring wheat + 59 rainfed rapeseed inactive rainfed spring wheat + 60 irrigated rapeseed inactive irrigated spring wheat + 61 rainfed rice active rainfed rice + 62 irrigated rice active irrigated rice + 63 rainfed sorghum inactive rainfed tropical corn + 64 irrigated sorghum inactive irrigated tropical corn + 65 rainfed sugarbeet inactive rainfed spring wheat + 66 irrigated sugarbeet inactive irrigated spring wheat + 67 rainfed sugarcane active rainfed sugarcane + 68 irrigated sugarcane active irrigated sugarcane + 69 rainfed sunflower inactive rainfed spring wheat + 70 irrigated sunflower inactive irrigated spring wheat + 71 rainfed miscanthus inactive rainfed tropical corn + 72 irrigated miscanthus inactive irrigated tropical corn + 73 rainfed switchgrass inactive rainfed tropical corn + 74 irrigated switchgrass inactive irrigated tropical corn + 75 rainfed tropical corn active rainfed tropical corn + 76 irrigated tropical corn active irrigated tropical corn + 77 rainfed tropical soybean active rainfed tropical soybean + 78 irrigated tropical soybean active irrigated tropical soybean + === =========================== ================ =========================== + + + .. _Phenology: Phenology @@ -155,8 +230,8 @@ maturity and harvest. Planting ''''''''''''''''' -Corn and temperate cereals must meet the following requirements between -April 1\ :sup:`st` and June 14\ :sup:`th` for planting in the northern hemisphere (NH): +All crops must meet the following requirements between the minimum planting date and the maximum +planting date (for northern hemisphere) in :numref:`Table Crop phenology parameters`: .. math:: :label: 25.1 @@ -171,41 +246,36 @@ where :math:`{T}_{10d}` is the 10-day running mean of :math:`{T}_{2m}`, (the sim temperature at every model time step) and :math:`T_{10d}^{\min}` is the 10-day running mean of :math:`T_{2m}^{\min }` (the daily minimum of :math:`{T}_{2m}`. :math:`{T}_{p}` and :math:`T_{p}^{\min }` are crop-specific coldest planting temperatures -(:numref:`Table Crop plant functional types`), :math:`{GDD}_{8}` is the 20-year running mean growing +(:numref:`Table Crop phenology parameters`), :math:`{GDD}_{8}` is the 20-year running mean growing degree-days (units are degree-days or :sup:`o` days) tracked from April through September (NH) base 8\ :sup:`o` C with -maximum daily increments of 30\ :sup:`o` days (see Eq.XXX ), and +maximum daily increments of 30\ :sup:`o` days (see equation :eq:`25.3`), and :math:`{GDD}_{min }`\ is the minimum growing degree day requirement -(:numref:`Table Crop plant functional types`). Soy must meet the same requirements but between May -1\ :sup:`st` and June 14\ :sup:`th` for planting. If the -requirements in Eq. are not met by June 14\ :sup:`th`, then corn, -soybean, and temperate cereals are still planted on June -15\ :sup:`th` as long as :math:`{GDD}_{8} > 0`. In -the southern hemisphere (SH) the NH requirements apply 6 months later. - -:math:`{GDD}_{8}` does not change as quickly as :math:`{T}_{10d}` and :math:`T_{10d}^{\min }`, so +(:numref:`Table Crop phenology parameters`). :math:`{GDD}_{8}` does not change as quickly as :math:`{T}_{10d}` and :math:`T_{10d}^{\min }`, so it determines whether the crop can be planted in a grid cell, while the two faster-changing variables determine when the crop may be planted. -At planting, each crop is assigned 1 g leaf C m\ :sup:`-2` pft +If the requirements in equation :eq:`25.1` are not met by the maximum planting date, +crops are still planted on the maximum planting date as long as :math:`{GDD}_{8} > 0`. In +the southern hemisphere (SH) the NH requirements apply 6 months later. + +At planting, each crop is assigned 3 g leaf C m\ :sup:`-2` pft column area to be transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the pft’s C to N -ratio for leaves (:math:`{CN}_{leaf}`). (This differs from AgroIBIS, -which uses a seed leaf area index instead of seed C.) - -At planting, the model updates the average growing degree-days necessary +ratio for leaves (:math:`{CN}_{leaf}` in :numref:`Table Crop allocation parameters`,this differs from AgroIBIS, +which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, :math:`{GDD}_{mat}`, according to the following AgroIBIS rules: .. math:: :label: 25.2 - \begin{array}{l} {GDD_{{\rm mat}}^{{\rm corn}} =0.85GDD_{{\rm 8}} {\rm \; \; \; and\; \; \; 950} Date: Wed, 14 Jun 2017 17:22:32 -0600 Subject: [PATCH 068/255] Text revisions to introduction and other features section of crop chapter --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 66 ++++++++++--------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index a9eafc3320..863e03ecfe 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -9,12 +9,11 @@ Summary of CLM5.0 updates relative to the CLM4.5 ----------------------------------------------------- We describe here the complete crop and irrigation parameterizations that -appear in CLM5.0. Corresponding information for CLM4.5 appeared on the -CLM4.5 web site in a pdf document independent of the CLM4.5 Technical -Note (:ref:`Oleson et al. 2013 `). +appear in CLM5.0. Corresponding information for CLM4.5 appeared in the +CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `). -CLM5.0 includes the following updates to the CROP option, where CROP -refers to the interactive crop management model and is included by default with the BGC configuration: +CLM5.0 includes the following new updates to the CROP option, where CROP +refers to the interactive crop management model and is included as an option with the BGC configuration: - New crop functional types @@ -38,7 +37,6 @@ refers to the interactive crop management model and is included by default with - Initial seed C for planting is increased from 1 to 3 g C/m^2 - These updates appear in detail in the sections below. Many also appear in Levis et al. (:ref:`2016 `). @@ -69,7 +67,7 @@ management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) `] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with -CLM4CN (:ref:`Levis et al. 2012 `), and CLM4.5. Additional updates after the +CLM4CN (:ref:`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), and those are now incorporated into CLM5. @@ -578,8 +576,9 @@ Other Features Physical Crop Characteristics '''''''''''''''''''''''''''''' +Leaf area index (*L*) is calculated as a function of XXX [update]. Stem area index (*S*) is equal to 0.1\ *L* for corn and 0.2\ *L* for -other crops, as in AgroIBIS, where *L* is the leaf area index. All live +other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to simulate a post-harvest “stubble†on the ground. @@ -599,24 +598,26 @@ and :math:`{z}_{bot}` (m), come from the AgroIBIS formulation: Interactive Fertilization '''''''''''''''''''''''''''''' -CLM adds nitrogen directly to the soil mineral nitrogen pool to meet -crop nitrogen demands. CLM’s separate crop land unit ensures that +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet +crop nitrogen demands using both industrial fertilizer and manure application. CLM’s separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. -Fertilizer in CLM5BGCCROP is prescribed by crop function types spatially +Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). -There are two fields that are used to prescribe industrial fertilizer. -On the surface data set the field CONST_FERTNITRO_CFT specifies the -annual fertilizer application for a non-transient simulations in g N/m\ :sup:`2`/yr. -In the case of a transient simulation this is replaced by the landuse.timeseries -file with the field FERTNITRO_CFT which is also in g N/m\ :sup:`2`/yr. +One of two fields is used to prescribe industrial fertilizer based on the type of simulation. +For non-transient simulations, annual fertilizer application in g N/m\ :sup:`2`/yr +is specified on the land surface data set by the field CONST_FERTNITRO_CFT. +In transient simulations, annual fertilizer application is specified on the land use time series +file by the field FERTNITRO_CFT, which is also in g N/m\ :sup:`2`/yr. The values for both of these fields come from the LUMIP time series for each year. -In addition to the industrial fertilizer there is a background manure fertilizer -on the clm parameters file with the field manunitro. For the current CLM5BGCCROP, -this is set to 0.002 kg N/m\ :sup:`2`/yr. Since CLM’s denitrification rate is high -and results in a 50% loss of the unused available nitrogen each day, -fertilizer is applied slowly to minimize the loss and maximize plant -uptake. Fertilizer application begins during the emergence phase of crop +In addition to the industrial fertilizer, background manure fertilizer is specified +on the parameter file by the field 'manunitro'. For the current CLM5BGCCROP, +manure N is applied at a rate of 0.002 kg N/m\ :sup:`2`/yr. Because previous versions +of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly +to minimize N loss (primarily through denitrification) and maximize plant uptake. +The current implementation of CLM5 inherits this legacy, although denitrification rates +are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, +fertilizer application begins during the emergence phase of crop development and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to @@ -648,24 +649,25 @@ are treated as N fixers. .. _Latitude vary base tempereature for growing degree days: -Latitude vary base tempereature for growing degree days +Latitudinal variation in base growth tempereature '''''''''''''''''''''''''''''''''''''''''''''''''''''''' -For both rainfed and irrigated spring wheat and sugarcane, -a latitude vary base temperature in calculating :math:`GDD_{T_{{\rm 2m}} }` -(growing degree days since planting) was introduced. +For most crops, :math:`GDD_{T_{{\rm 2m}} }` (growing degree days since planting) +is the same in all locations. However, +the for both rainfed and irrigated spring wheat and sugarcane, the calculation of +:math:`GDD_{T_{{\rm 2m}} }` allows for latitudinal variation: .. math:: :label: 25.11 - latitude\ vary\ baset = \left\{ + latitudinal\ variation\ in\ base\ T = \left\{ \begin{array}{lr} baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 \end{array} \right\} -where :math:`baset` is the 5\ :sup:`th` row in :numref:`Table Crop phenology parameters`. -Such latitude vary baset could increase the base temperature, slow down :math:`GDD_{T_{{\rm 2m}} }` -accumulation, and extend the growing season for -30º to 30º regions for spring wheat +where :math:`baset` is the *base temperature for GDD* (7\ :sup:`th` row) in :numref:`Table Crop phenology parameters`. +Such latitudinal variation in base growth temperature could increase the base temperature, slow down :math:`GDD_{T_{{\rm 2m}} }` +accumulation, and extend the growing season for regions within 30ºS to 30ºN for spring wheat and sugarcane. .. _Separate reproductive pool: @@ -678,9 +680,9 @@ for the reproductive pool helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not -begin until the grain fill stage of crop development. Eq. :eq:`(5)` shows the +begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. -In CLM, as allocation declines +In CLM5BGCCROP, as allocation declines during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. From 944cbcec2ee5b26b0f05a1dd2c01c93b4227c79b Mon Sep 17 00:00:00 2001 From: Yaqiong Lu Date: Thu, 15 Jun 2017 10:36:11 -0600 Subject: [PATCH 069/255] changed crop text --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 863e03ecfe..4ceedd3c28 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -229,7 +229,7 @@ Planting ''''''''''''''''' All crops must meet the following requirements between the minimum planting date and the maximum -planting date (for northern hemisphere) in :numref:`Table Crop phenology parameters`: +planting date (for the northern hemisphere) in :numref:`Table Crop phenology parameters`: .. math:: :label: 25.1 @@ -252,15 +252,14 @@ maximum daily increments of 30\ :sup:`o` days (see equation :eq:`25.3`), and (:numref:`Table Crop phenology parameters`). :math:`{GDD}_{8}` does not change as quickly as :math:`{T}_{10d}` and :math:`T_{10d}^{\min }`, so it determines whether the crop can be planted in a grid cell, while the two faster-changing variables determine when the crop may be planted. - If the requirements in equation :eq:`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as :math:`{GDD}_{8} > 0`. In the southern hemisphere (SH) the NH requirements apply 6 months later. -At planting, each crop is assigned 3 g leaf C m\ :sup:`-2` pft -column area to be transferred to the leaves upon leaf emergence. An +At planting, each crop seed pool is assigned 3 gC m\ :sup:`-2` from its +grain product pool. The seed carbon transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the pft’s C to N -ratio for leaves (:math:`{CN}_{leaf}` in :numref:`Table Crop allocation parameters`,this differs from AgroIBIS, +ratio for leaves (:math:`{CN}_{leaf}` in :numref:`Table Crop allocation parameters`, this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, :math:`{GDD}_{mat}`, according to the following AgroIBIS rules: @@ -272,8 +271,8 @@ for the crop to reach vegetative and physiological maturity, where :math:`{GDD}_{10}` is the 20-year running mean growing degree-days tracked from April through September (NH) base -10\ :math:`{}^\circ`\ C with maximum daily increments of -30\ :math:`{}^\circ`\ days. Equation :eq:`25.3` shows how we calculate +10\ :sup:`o`\C with maximum daily increments of +30\ :sup:`o`\days. Equation :eq:`25.3` shows how we calculate :math:`{GDD}_{0}`, :math:`{GDD}_{8}`, and :math:`{GDD}_{10}`: .. math:: @@ -294,12 +293,13 @@ Leaf emergence According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth tracked since planting (:math:`GDD_{T_{soi} }` ) reaches 1 to 5% of :math:`{GDD}_{mat}` -(:numref:`Table Crop phenology parameters`). :math:`GDD_{T_{soi} }` is base 8, 0, and -10\ :math:`{}^\circ`\ C for corn, soybean, and temperate cereals. -Leaf onset, as defined in the CN part of the model, occurs in the first +(:numref:`Table Crop phenology parameters`). The base temperature for :math:`GDD_{T_{soi} }` +are listed in :numref:`Table Crop phenology parameters`. +Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases and reaches -a maximum value during phase 2. +a maximum value during phase 2. Stem and root C are also increasing, based on +the carbon allocation algorithem in section :numref:`Leaf emergence to grain fill`. .. _Grain fill: @@ -368,13 +368,13 @@ similar in structure to the wood product pools. Notes: :math:`Date_{planting}^{min}` and :math:`Date_{planting}^{max}` are the minimum and maximum planting date in the Northern Hemisphere, the corresponding dates in the Southern Hemisphere apply 6 months later. -:math:`T_{p}` and :math:`T_{p}^{ min }` are crop-specific temperatures threshold for planting. +:math:`T_{p}` and :math:`T_{p}^{ min }` are crop-specific coldest planting temperatures. :math:`{GDD}_{min}` is the lowest (for planting) 20-year running mean growing degree-days base -on the base temperature in the 5\ :sup:`th` row, tracked from April to September (NH). +on the base temperature in the 7\ :sup:`th` row, tracked from April to September (NH). :math:`{GDD}_{mat}` is a crop’s 20-year running mean growing degree-days needed for vegetative and physiological maturity. Harvest occurs at 100%\ :math:`{GDD}_{mat}` or when the days past planting -reach the number in the 9\ :sup:`th` row. Crop growth phases +reach the number in the 11\ :sup:`th` row. Crop growth phases are described in the text. :math:`z_{top}^{\max }` is the maximum top-of-canopy height of a crop, *SLA* is specific leaf area. :math:`\chi _{L}` is the leaf orientation index, equals -1 for vertical, 0 for From a304d84830edd00b994acd1157b7e1d62d7f4c98 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Thu, 15 Jun 2017 12:11:31 -0600 Subject: [PATCH 070/255] Updates to the Introduction chapter --- .../CLM50_Tech_Note_Introduction.rst | 170 +++++------------- 1 file changed, 49 insertions(+), 121 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 7f409914b2..ded640dda9 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -1,74 +1,24 @@ -g**NCAR/TN-503+STR** -**NCAR Technical Note** -**July 2013** +**July 2017** **Technical Description of version 5.0 of the Community Land Model (CLM)** ***Coordinating Lead Authors*** -**Keith W. Oleson, David M. Lawrence** +**David M. Lawrence, Rosie Fisher, Charles D. Koven, Keith W. Oleson, Sean Swenson** ***Lead Authors*** -**Gordon B. Bonan, Beth Drewniak, Maoyi Huang, Charles D. Koven, Samuel -Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, -Peter E. Thornton** +**Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Peter J. Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William J. Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu +** ***Contributing Authors*** -**Anil Bozbiyik, Rosie Fisher, Colette L. Heald, Erik Kluzek, -Jean-Francois Lamarque, Peter J. Lawrence, L. Ruby Leung, William -Lipscomb, Stefan Muszala, Daniel M. Ricciuto, William Sacks, Ying Sun, -Jinyun Tang, Zong-Liang Yang** +**Ben Andre, Ali Ashehad, Gautam Bisht, Gordon Bonan, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, +L. Ruby Leung, William Lipscomb, Daniel M. Ricciuto, Ben Sanderson, Andrew Slater, Zachary M. Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** -**NCAR Earth System Laboratory** - -**Climate and Global Dynamics Division** - -**NATIONAL CENTER FOR ATMOSPHERIC RESEARCH** - -**P. O. Box 3000** - -**BOULDER, COLORADO 80307-3000** - -**ISSN Print Edition 2153-2397** - -**ISSN Electronic Edition 2153-2400** - -**NCAR TECHNICAL NOTES** - -http://library.ucar.edu/research/publish-technote - -The Technical Notes series provides an outlet for a variety of NCAR -Manuscripts that contribute in specialized ways to the body of -scientific knowledge but that are not yet at a point of a formal -journal, monograph or book publication. Reports in this series are -issued by the NCAR scientific divisions, serviced by OpenSky and -operated through the NCAR Library. Designation symbols for the series -include: - -**EDD – Engineering, Design, or Development Reports** - -Equipment descriptions, test results, instrumentation, and operating and maintenance manuals. - -**IA – Instructional Aids** - -Instruction manuals, bibliographies, film supplements, and other research or instructional aids. - -**PPR – Program Progress Reports** - -Field program reports, interim and working reports, survey reports, and plans for experiments. - -**PROC – Proceedings** - -Documentation or symposia, colloquia, conferences, workshops, and lectures. (Distribution maybe limited to attendees). - -**STR – Scientific and Technical Reports** - -Data compilations, theoretical and numerical investigations, and experimental results. The National Center for Atmospheric Research (NCAR) is operated by the nonprofit University Corporation for Atmospheric Research (UCAR) under @@ -80,43 +30,7 @@ the National Science Foundation. National Center for Atmospheric Research P. O. Box 3000, Boulder, Colorado 80307-300 -**NCAR/TN-503+STR** - -**NCAR Technical Note** - -**July 2013** - -**Technical Description of version 4.5 of the Community Land Model (CLM)** - -**Coordinating Lead Authors** - -**Keith W. Oleson, David M. Lawrence** -**Lead Authors** - -**Gordon B. Bonan, Beth Drewniak, Maoyi Huang, Charles D. Koven, Samuel -Levis, Fang Li, William J. Riley, Zachary M. Subin, Sean C. Swenson, Peter E. Thornton** - -**Contributing Authors** - -**Anil Bozbiyik, Rosie Fisher, Colette L. Heald, Erik Kluzek, -Jean-Francois Lamarque, Peter J. Lawrence, L. Ruby Leung, William -Lipscomb, Stefan Muszala, Daniel M. Ricciuto, William Sacks, Ying Sun, -Jinyun Tang, Zong-Liang Yang** - -**NCAR Earth System Laboratory** - -**Climate and Global Dynamics Division** - -**NATIONAL CENTER FOR ATMOSPHERIC RESEARCH** - -**P. O. Box 3000** - -**BOULDER, COLORADO 80307-3000** - -**ISSN Print Edition 2153-2397** - -**ISSN Electronic Edition 2153-2400** **LIST OF FIGURES** @@ -255,19 +169,16 @@ Fung, David Gochis, Alex Guenther, Tim Hoar, Forrest Hoffman, Paul Houser, Trish Jackson, Brian Kauffman, Silvia Kloster, Natalie Mahowald, Jiafu Mao, Lei Meng, Sheri Michelson, Guo-Yue Niu, Adam Phillips, Taotao Qian, Jon Radakovich, James Randerson, Nan Rosenbloom, Steve Running, -Koichi Sakaguchi, Adam Schlosser, Andrew Slater, Reto Stöckli, Quinn -Thomas, Mariana Vertenstein, Nicholas Viovy, Aihui Wang, Guiling Wang, +Koichi Sakaguchi, Adam Schlosser, Andrew Slater, Reto Stöckli, Ying Sun, Quinn +Thomas, Peter Thornton, Mariana Vertenstein, Nicholas Viovy, Aihui Wang, Guiling Wang, Charlie Zender, Xiaodong Zeng, and Xubin Zeng. -The authors also thank the following people for their review of this -document: Jonathan Buzan, Kyla Dahlin, Sanjiv Kumar, Hanna Lee, Danica -Lombardozzi, Quinn Thomas, and Will Wieder. + Current affiliations for the authors are as follows: -K.W. Oleson, D.M. Lawrence, G.B. Bonan, S. Levis, S.C. Swenson, R. -Fisher, E. Kluzek, J.-F. Lamarque, P.J. Lawrence, S. Muszala, and W. -Sacks (National Center for Atmospheric Research); B. Drewniak (Argonne +K.W. Oleson, D.M. Lawrence, G.B. Bonan, S.C. Swenson, R. +Fisher, E. Kluzek, P.J. Lawrence, W. Sacks and M. Vertenstein (National Center for Atmospheric Research); B. Drewniak (Argonne National Laboratory); M. Huang, L.R. Leung (Pacific Northwest National Laboratory); C.D. Koven, W.J. Riley, and J. Tang (Lawrence Berkeley National Laboratory); F. Li (Chinese Academy of Sciences); Z.M. Subin @@ -282,11 +193,11 @@ Austin) Introduction ================= -The purpose of this technical note is to describe the biogeophysical and +The purpose of this document is to fully describe the biogeophysical and biogeochemical parameterizations and numerical implementation of version -4.5 of the Community Land Model (CLM4.5). Scientific justification and +5.0 of the Community Land Model (CLM5.0). Scientific justification and evaluation of these parameterizations can be found in the referenced -scientific papers (:ref:`rst_References`). This technical note and the CLM4.5 +scientific papers (:ref:`rst_References`). This document and the CLM5.0 User’s Guide together provide the user with the scientific description and operating instructions for CLM. @@ -523,8 +434,7 @@ model option for coupled simulations in CESM1.2. CLM4.5 ^^^^^^^^^^^^ -The motivations for the development of CLM4.5 (the model version -described in this Technical Description) were similar to those for CLM4: +The motivations for the development of CLM4.5 were similar to those for CLM4: incorporate several recent scientific advances in the understanding and representation of land surface processes, expand model capabilities, and improve surface and atmospheric forcing datasets. @@ -541,13 +451,9 @@ problems or biases. The main modifications include updates to canopy processes including a revised canopy radiation scheme and canopy scaling of leaf processes, co-limitations on photosynthesis, revisions to photosynthetic parameters -(:ref:`Bonan et al. 2011`), - -.. todo:: had three stars here - need to resolve this - -temperature acclimation of photosynthesis, and +(:ref:`Bonan et al. 2011`), temperature acclimation of photosynthesis, and improved stability of the iterative solution in the photosynthesis and -stomatal conductance model (:ref:`Sun et al. 2012`). Hydrology updates include +stomatal conductance model (:ref:`Sun et al. 2012`). Hydrology updates included modifications such that hydraulic properties of frozen soils are determined by liquid water content only rather than total water content and the introduction of an ice impedance function, and other corrections @@ -556,10 +462,10 @@ position and allow for a perched water table above icy permafrost ground (:ref:`Swenson et al. 2012`). A new snow cover fraction parameterization is incorporated that reflects the hysteresis in fractional snow cover for a given snow depth between accumulation and melt phases (:ref:`Swenson and -Lawrence, 2012`). The lake model in CLM4 is replaced with a completely +Lawrence, 2012`). The lake model in CLM4 was replaced with a completely revised and more realistic lake model (:ref:`Subin et al. 2012a`). A surface -water store is introduced, replacing the wetland land unit and -permitting prognostic wetland distribution modeling, and the surface +water store was introduced, replacing the wetland land unit and +permitting prognostic wetland distribution modeling. The surface energy fluxes are calculated separately (:ref:`Swenson and Lawrence, 2012`) for snow-covered, water-covered, and snow/water-free portions of vegetated and crop land units, and snow-covered and snow-free portions of glacier @@ -570,9 +476,9 @@ decomposition rates modified by soil temperature, water, and oxygen limitations and also including vertical mixing of soil carbon and nitrogen due to bioturbation, cryoturbation, and diffusion (:ref:`Koven et al. 2013`). The litter and soil carbon and nitrogen pool structure as well as -nitrification and denitrification are modified based on the Century -model and biological fixation is revised to distribute fixation more -realistically over the year (:ref:`Koven et al. 2013`). The fire model is +nitrification and denitrification that were modified based on the Century +model. Biological fixation was revised to distribute fixation more +realistically over the year (:ref:`Koven et al. 2013`). The fire model was replaced with a model that includes representations of natural and anthropogenic triggers and suppression as well as agricultural, deforestation, and peat fires (:ref:`Li et al. 2012a,b`; :ref:`Li et al. 2013a`). The @@ -608,6 +514,21 @@ dataset or other alternative forcing datasets. CLM4.5 was released to the community in June 2013 along with the Community Earth System Model version 1.2 (CESM1.2). +CLM5.0 +^^^^^^^^^^^^ + +Developments for CLM5.0 build on the progress made in CLM4.5. Much of the focus of development centered on a +push towards more mechanistic treatment of several key processes, in addition to more comprehensive and explicit representation +of land use and land-cover change. In particular, + +To represent … Stomatal conductance is a function of prognostic (predicted) leaf water potential. LWP is the result of atmospheric demand and supply from soil via resistance network. + +Dynamic land units. + +Included within the codebase of the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, +reference Fisher???). This version of CLM5-FATES that is supported in this release is described here??? Short blurb on what FATES can do??? + + Biogeophysical and Biogeochemical Processes ----------------------------------------------- @@ -644,6 +565,10 @@ processes simulated include (:numref:`Figure Land processes`): #. Stomatal physiology and photosynthesis (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`) +#. Prognostic photosynthetic capacity (Chapter :number:`rst_Photosynthetic Capacity`) + +#. Plant hydraulics (Chapter :number: `rst_Plant Hydraulics`) + #. Lake temperatures and fluxes (Chapter :numref:`rst_Lake Model`) #. Glacier processes (Chapter :numref:`rst_Glaciers`) @@ -652,19 +577,22 @@ processes simulated include (:numref:`Figure Land processes`): #. Urban energy balance and climate (Chapter :numref:`rst_Urban Model (CLMU)`) -#. Vegetation carbon and nitrogen allocation and respiration (Chapter - :numref:`rst_CN Allocation`) +#. Vegetation carbon and nitrogen allocation (Chapter :numref:`rst_CN Allocation`) #. Vegetation phenology (Chapter :numref:`rst_Vegetation Phenology and Turnover`) +#. Plant respiration (Chapter :number:`rst_Plant Respiration`) + #. Soil and litter carbon decomposition (Chapter :numref:`rst_Decomposition`) -#. Nitrogen cycling including deposition, biological fixation, +#. Fixation and uptake of nitrogen (Chapter :number:`rst_FUN`) + +#. External nitrogen cycling including deposition, denitrification, leaching, and losses due to fire (Chapter :numref:`rst_External Nitrogen Cycle`) #. Plant mortality (Chapter :numref:`rst_Plant Mortality`) -#. Fire ignition and suppression, including natural, deforestation, and +#. Fire ignition, suppression, spread, and emissions, including natural, deforestation, and agricultural fire (Chapter :numref:`rst_Fire`) #. Methane production, oxidation, and emissions (Chapter :numref:`rst_Methane Model`) From cee897951a2db6502bc83202ca8e3ed8a17062af Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Thu, 15 Jun 2017 14:14:12 -0600 Subject: [PATCH 071/255] A few small changes to the crop chapter in collaboration with Yaqiong --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 4ceedd3c28..a40cba747e 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -532,7 +532,12 @@ Harvest to food and seed In CLM5, the C and N required for crop seeding is removed from the grain product pool during harvest and used to seed crops in the subsequent year. -Caluating the crop yields requires... +Caluating the crop yields requires that you sum the GRAINC_TO_FOOD variable +for each year. Additionally, harvest is not typically 100% efficient, so +analysis needs to assume that harvest efficiency is less. We assume a harvest +efficiency of 85%, and a grain C of 45% of the grain dry weight. + +equation (g/m^2) = (sum(GRAINC_TO_FOOD)/0.45)*.85 @@ -576,8 +581,9 @@ Other Features Physical Crop Characteristics '''''''''''''''''''''''''''''' -Leaf area index (*L*) is calculated as a function of XXX [update]. -Stem area index (*S*) is equal to 0.1\ *L* for corn and 0.2\ *L* for +Leaf area index (*L*) is calculated as a function of specific leaf area +(SLA) and leaf C (:ref:`Crop phenology parameters`). +Stem area index (*S*) is equal to 0.1\ *L* for temperate and tropical corn and sugarcane and 0.2\ *L* for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to simulate a post-harvest “stubble†on the ground. From d0b6860393ac2cc0a4ca98ac9c7569c13e26a8dc Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 15 Jun 2017 14:27:02 -0600 Subject: [PATCH 072/255] Update MOSART Chapter --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 26 +++- .../CLM50_Tech_Note_Plant_Hydraulics.rst | 2 +- .../tech_note/RTM/CLM50_Tech_Note_RTM.rst | 141 ------------------ .../References/CLM50_Tech_Note_References.rst | 37 +++++ doc/source/tech_note/index.rst | 2 +- 5 files changed, 57 insertions(+), 151 deletions(-) delete mode 100644 doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 4ceedd3c28..11d8f6c109 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -38,7 +38,7 @@ refers to the interactive crop management model and is included as an option wit - Initial seed C for planting is increased from 1 to 3 g C/m^2 These updates appear in detail in the sections below. Many also appear in -Levis et al. (:ref:`2016 `). +:ref:`Levis et al. (2016) `. .. _The crop model: @@ -65,7 +65,7 @@ simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 -[CLM3.0, :ref:`Oleson et al. (2004) `] (not published), then coupled to the +[CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), @@ -106,8 +106,8 @@ CLM5 includes eight actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, and sugarcane) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as -developed by Badger and Dirmeyer (:ref:`2015 `) and -described by Levis et al. (:ref:`2016 `). The representations of +developed by :ref:`Badger and Dirmeyer (2015)` and +described by :ref:`Levis et al. (2016)`. The representations of sugarcane, rice, cotton, tropical corn, and tropical soy are new in CLM5. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate @@ -234,7 +234,7 @@ planting date (for the northern hemisphere) in :numref:`Table Crop phenology par .. math:: :label: 25.1 - \begin{array}{l} + \begin{array}{c} {T_{10d} >T_{p} } \\ {T_{10d}^{\min } >T_{p}^{\min } } \\ {GDD_{8} \ge GDD_{\min } } @@ -267,7 +267,13 @@ for the crop to reach vegetative and physiological maturity, .. math:: :label: 25.2 - \begin{array}{l} {GDD_{{\rm mat}}^{{\rm corn,sugarcane}} =0.85GDD_{{\rm 8}} {\rm \; \; \; and\; \; \; 950}`) .. math:: :label: 11.12 - dx_{root,i} = \left(\pi \cdot L_i\right)^{\frac{1}{2}} + dx_{root,i} = \left(\pi \cdot L_i\right)^{- \frac{1}{2}} where :math:`L_{i}` is the root length density (m m :sup:`-3`) diff --git a/doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst b/doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst deleted file mode 100644 index 773b3f2fe6..0000000000 --- a/doc/source/tech_note/RTM/CLM50_Tech_Note_RTM.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. _rst_River Transport Model (RTM): - -River Transport Model (RTM) -=============================== - -The RTM was developed to route total runoff from the land surface model -to either the active ocean or marginal seas which enables the hydrologic -cycle to be closed (Branstetter 2001, Branstetter and Famiglietti 1999). -This is needed to model ocean convection and circulation, which is -affected by freshwater input. It also provides another method of -diagnosing the performance of the land model because the river flow can -be directly compared to gauging station data (e.g., Dai and Trenberth -2002). - -To improve global energy conservation when CLM is being run as part of -the Community Climate System Model, runoff is split into two streams, a -liquid water stream and an ice water stream (derived from excess -snowfall in snow-capped grid cells, section 7.7). The liquid and ice -streams are routed through the RTM, passed to, and dealt with by the -ocean separately. - -The RTM uses a linear transport scheme to route water from each grid -cell to its downstream neighboring grid cell. The change in storage -:math:`S` of river water, whether it be liquid or ice, within a RTM grid -cell (m\ :sup:`3` s\ :sup:`-1`) is - -.. math:: - :label: 14.1) - - \frac{dS}{dt} =\sum F_{in} -F_{out} +R - -where :math:`\sum F_{in}` is the sum of inflows of water from -neighboring upstream grid cells (m\ :sup:`3` s\ :sup:`-1`), -:math:`F_{out}` is the flux of water leaving the grid cell in the -downstream direction (m :sup:`3` s\ :sup:`-1`), and :math:`R` -is the total runoff generated by the land model grid cell -(m\ :sup:`3` s\ :sup:`-1`). Downstream water flow direction in -each grid cell is determined as one of eight compass points (north, -northeast, east, southeast, south, southwest, west, and northwest) based -on the steepest downhill slope as determined from a digital elevation -model (Graham et al. 1999). The flux of water leaving the grid cell -:math:`F_{out}` is - -.. math:: - :label: 14.2) - - F_{out} =\frac{v}{d} S - -where :math:`v` is the effective water flow velocity (m -s\ :sup:`-1`), :math:`d` is the distance between centers of -neighboring grid cells (m), and :math:`S` is the volume of river water -stored within the grid cell (m\ :sup:`3`). The effective water flow -velocity can be estimated from Manning’s equation, which is a function -of surface water slope, the hydraulic radius of the river channel, and a -channel roughness coefficient (Dingman, 2002). However, hydraulic radius -and channel roughness data are not available globally, so a simplified -effective flow velocity expression is used in RTM - -.. math:: - :label: 14.3) - - v=\max \left(0.05,k\beta ^{1/2} \right) - -where :math:`\beta` is the grid cell mean topographic slope, and -:math:`k=1`. - -The distance :math:`d` between two grid cell centers depends on river -direction, latitude, and longitude as - -.. math:: - :label: 14.4) - - d=\sqrt{\Delta x^{2} +\Delta y^{2} } . - -The distance in the zonal direction :math:`\Delta x` (m) is - -.. math:: - :label: 14.5) - - \Delta x=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right)\left[0.5\left(\cos \phi _{i,\, j} +\cos \phi _{i*,\, j*} \right)\right] - -where :math:`\theta _{i,\, j}` and :math:`\theta _{i*,\, j*}` are the -latitudes (radians) of the upstream and downstream grid cells, -:math:`\phi _{i,\, j}` and :math:`\phi _{i*,\, j*}` are the longitudes -(radians) of the upstream and downstream grid cells, :math:`R_{e}` is -the radius of the earth (km) (Table 2.6), and :math:`i` and :math:`j` -are grid cell indices. The distance in the meridional direction -:math:`\Delta y` (m) is - -.. math:: - :label: 14.6) - - \Delta y=\left(1\times 10^{3} \left|\theta _{i,\, j} -\theta _{i*,\, j*} \right|R_{e} \right). - -The RTM is generally run at a time step greater than that of the CLM -because of computational constraints. The total runoff from the land -model at each time step is accumulated until the RTM is invoked. The -total liquid water runoff at the land model resolution (kg -m\ :sup:`-2` s\ :sup:`-1`) is - -.. math:: - :label: 14.7) - - R_{liq} =q_{over} +q_{drai} +q_{rgwl} - -where :math:`q_{over}` is surface runoff (section 7.3), -:math:`q_{drai}` is sub-surface drainage (section 7.6), and -:math:`q_{rgwl}` is liquid runoff from glaciers, wetlands, and lakes -(all in kg m\ :sup:`-2` s\ :sup:`-1`) (sections 7.7 and -9.6.3). The total ice water runoff, also at the land model resolution is - -.. math:: - :label: 14.8) - - R_{ice} =q_{snwcp,ice} - -where :math:`q_{snwcp,ice}` is the ice runoff from snow-capped -surfaces (section 7.7). The runoff at the land model resolution is -interpolated to the resolution of RTM and converted to units of -m\ :sup:`3` s\ :sup:`-1` for use in equation (11.1) by multiplying -by :math:`1\times 10^{-3} A` where :math:`A` is the area -(m\ :sup:`2`) of the RTM grid cell. - -The RTM grid cells that are at river mouths, hence providing freshwater -flux to the ocean, are identified by examining each RTM ocean grid cell -and determining if a RTM land grid cell flows to that ocean grid cell. -River mouth grid cells are also assigned if any overlapping grid cells -at the land model resolution contain land. When used as part of the -Community Climate System Model, the ocean freshwater liquid and ice -fluxes at the RTM resolution are passed to the flux coupler which -distributes the fluxes to the appropriate ocean grid cells. When used -with the Community Atmosphere Model or when run offline, RTM serves only -as a diagnostic tool. The river-routing scheme conserves water globally -as - -.. math:: - :label: 14.9) - - \sum _{i,\, j}\left(\frac{dS}{dt} \right) _{i,\, j} =\sum _{i,\, j}R_{i,\, j} . - - diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 076af343be..97e221f702 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -543,6 +543,12 @@ overview of ABRACOS. pp. 1-14. In: J.H.C. Gash, C.A. Nobre, J.M. Roberts, and R.L. Victoria (editors) Amazonian Deforestation and Climate. John Wiley and Sons, Chichester, England. +.. _Getiranaetal2012: + +Getirana, A. C. V., A. Boone, D. Yamazaki, B. Decharme, F. Papa, and +N. Mognard. 2012. The hydrological modeling and analysis platform +(HyMAP): Evaluation in the Amazon basin, J. Hydrometeorol., 13, 1641–1665. + .. _Gholzetal1985: Gholz, H.L., Perry, C.S., Cropper, W.P., Jr. and Hendry, L.C., 1985. @@ -976,6 +982,11 @@ Climate 25:3071-3095. DOI:10.1175/JCLI-D-11-00256.1. Lehner, B. and Döll, P., 2004. Development and validation of a global database of lakes, reservoirs and wetlands, J. Hydrol., 296, 1–22. +.. _Lehneretal2008: + +Lehner, B., Verdin, K. and Jarvis, A., 2008. New global hydrograhy +derived from spaceborne elevation data. Eos Trans., AGU, 89, 93 – 94. + .. _LePageetal2010: Le Page, Y., van der Werf, G.R., Morton, D.C., and Pereira, J.M.C. 2010. @@ -1079,6 +1090,20 @@ the Community Land Model 4.0 using observations from flux towers and a mountainous watershed. J. Geophys. Res. 116:D24120. DOI:10.1029/2011JD016276. +.. _Lietal2015a: + +Li, H., L. Leung, A. Getirana, M. Huang, H. Wu, Y. Xu, J. Guo and +N. Voisin. 2015a. Evaluating global streamflow simulations by a +physically-based routing model coupled with the Community Land Model, +J. of Hydromet., 16(2):948-971, doi: 10.1175/JHM-D-14-0079.1 + +.. _Lietal2015b: + +Li, H., L. Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, +J. Rice, H. Wu, and X. Yang. 2015. Modeling stream temperature in the +Anthropocene: An earth system modeling approach, J. Adv. Model. +Earth Syst., 7, doi:10.1002/2015MS000471. + .. _Liangetal1994: Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A @@ -2054,6 +2079,18 @@ DOI:10.1029/91JD01786. World Bank, 2004. World development indicators 2004, Oxford University Press, New York, 416 pp. +.. _Wuetal2011: + +Wu, H., J. S. Kimball, N. Mantua, and J. Stanford, 2011: Automated +upscaling of river networks for macroscale hydrological modeling. +Water Resour. Res., 47, W03517, doi:10.1029/2009WR008871. + +.. _Wuetal2012: + +Wu, H., J. S. Kimball, H. Li, M. Huang, L. R. Leung, and R. F. Adler +(2012), A New Global River Network Database for Macroscale Hydrologic +modeling, Water Resour. Res., 48, W09701, doi:10.1029/2012WR012313. + .. _Yang1998: Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index a05aa6210b..3f60029854 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -26,7 +26,7 @@ CLM Technical Note Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst Lake/CLM50_Tech_Note_Lake.rst Glacier/CLM50_Tech_Note_Glacier.rst - RTM/CLM50_Tech_Note_RTM.rst + MOSART/CLM50_Tech_Note_MOSART.rst Urban/CLM50_Tech_Note_Urban.rst CN_Pools/CLM50_Tech_Note_CN_Pools.rst Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst From 1179e59af9ccf43e14d4dc7e5f149d5b16e4b21d Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 15 Jun 2017 15:01:16 -0600 Subject: [PATCH 073/255] Add table to MOSART --- .../CLM50_Tech_Note_Introduction.rst | 13 +- .../MOSART/CLM50_Tech_Note_MOSART.rst | 243 ++++++++++++++++++ 2 files changed, 250 insertions(+), 6 deletions(-) create mode 100644 doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index ded640dda9..bbad06b077 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -11,8 +11,7 @@ ***Lead Authors*** -**Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Peter J. Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William J. Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu -** +**Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Peter J. Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William J. Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu** ***Contributing Authors*** @@ -128,6 +127,8 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Plant functional type root distribution parameters` Plant functional type root distribution parameters. +- :numref:`Table MOSART Parameters` List of parameters in the global hydrography dataset. + - :numref:`Table Allocation and CN ratio parameters` Allocation and carbon:nitrogen ratio parameters - :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. @@ -565,9 +566,9 @@ processes simulated include (:numref:`Figure Land processes`): #. Stomatal physiology and photosynthesis (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`) -#. Prognostic photosynthetic capacity (Chapter :number:`rst_Photosynthetic Capacity`) +#. Prognostic photosynthetic capacity (Chapter :numref:`rst_Photosynthetic Capacity`) -#. Plant hydraulics (Chapter :number: `rst_Plant Hydraulics`) +#. Plant hydraulics (Chapter :numref: `rst_Plant Hydraulics`) #. Lake temperatures and fluxes (Chapter :numref:`rst_Lake Model`) @@ -581,11 +582,11 @@ processes simulated include (:numref:`Figure Land processes`): #. Vegetation phenology (Chapter :numref:`rst_Vegetation Phenology and Turnover`) -#. Plant respiration (Chapter :number:`rst_Plant Respiration`) +#. Plant respiration (Chapter :numref:`rst_Plant Respiration`) #. Soil and litter carbon decomposition (Chapter :numref:`rst_Decomposition`) -#. Fixation and uptake of nitrogen (Chapter :number:`rst_FUN`) +#. Fixation and uptake of nitrogen (Chapter :numref:`rst_FUN`) #. External nitrogen cycling including deposition, denitrification, leaching, and losses due to fire (Chapter :numref:`rst_External Nitrogen Cycle`) diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst new file mode 100644 index 0000000000..cae3bd0493 --- /dev/null +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -0,0 +1,243 @@ +.. _rst_River Transport Model (RTM): + +Model for Scale Adaptive River Transport (MOSART) +================================================= + +.. _Overview: + +Overview +--------- + +MOSART is a river transport model designed for applications across local, +regional and global scales :ref:`(Li et al., 2013b) `. A +major purpose of MOSART is to provide freshwater input for the ocean +model in coupled Earth system model. MOSART also provides an effective +way of evaluating and diagnosing the soil hydrology simulated by land +surface models through direction comparison of the simulated river flow +with observations of natural streamflow at gauging stations +:ref:`(Li et al., 2015a)`. Moreover, MOSART provides a +modeling framework for representing riverine transport and transformation +of energy and biogeochemical fluxes under both natural and human-influenced +conditions ( :ref:`(Li et al., 2015b) `. + +.. _Routing Processes: + +Routing Processes +------------------ + +MOSART divides each spatial unit such as a lat/lon grid or watershed into +three categories of hydrologic units (as shown in +:numref:`Figure MOSART conceptual diagram`): hillslopes +that contribute both surface and subsurface runoff into tributaries, +tributaries that discharge into a single main channel, and the main channel +connects the local spatial unit with upstream/downstream units through the +river network. MOSART assumes that all the tributaries within a spatial unit +can be treated as a single hypothetical sub-network channel with a transport +capacity equivalent to all the tributaries combined. Correspondingly, three +routing processes are represented in MOSART: 1) hillslope routing: in each +spatial unit, surface runoff is routed as overland flow into the sub-network +channel, while subsurface runoff generated in the spatial unit directly enters +the sub-network channel; 2) sub-network channel routing: the sub-network channel +receives water from the hillslopes, routes water through the channel and discharges +it into the main channel; 3) main channel routing: the main channel receives water +from the sub-network channel and/or inflow, if any, from the upstream spatial units, +and discharges the water to its downstream spatial unit or the ocean. + +.. _Figure MOSART conceptual diagram: + +.. figure:: mosart_diagram.png + :width: 800px + :height: 400px + + +MOSART only route positive runoff, although negative runoff could be generated +occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any +runoff component including :math:`q_{sur}`, :math:`q_{sub}`, :math:`q_{gwl}` +is mapped directly from the spatial unit where it is generated at any time step to +the basin outlet of the corresponding spatial unit. + +In MOSART, the travel velocities of water across hillslopes, sub-network and main +channel are all estimated using the Manning’s equation with different levels of +simplifications. Generally the Manning’s equation is in the form of + +.. math:: + :label: 14.1 + + V = \frac{R^{\frac{2}{3}} S_{f}}{n} + +where :math: `V` is the travel velocity (m s :sup:`-1` ), :math:`R` is the hydraulic +radius (m). :math:`S_{f}` is the friction slope, and accounting for the effects +of gravity, friction, inertia and other forces onthe water. If the channel slope +is steep enough, the gravity force dominates over the others so one can approximate +:math:`S_{f}` by the channel bed slope :math:`S` , which is the key assumption +underpinning the kinematic wave method. :math:`n` is the Manning’s roughness +coefficient, which is mainly controlled by surface roughness and sinuosity of the +flow path. + +If the water surface is sufficiently large or the water depth :math:`h` is +sufficiently shallow, the hydraulic radius can be approximated by the water depth. +This is the case for both hillslope and sub-network channel routing. + +.. math:: + :label: 14.2 + + R_{h} = h_{h} + R_{t} = h_{t} + +Here :math:`R_{h}` (m) and :math:`R_{t}` (m) are hydraulic radius for hillslope and +sub-network channel routing respectively, and :math:`h_{h}` (m) and :math:`h_{t}` +(m) are water depth during hillslope and sub-network channel routing respectively. + +For the main channel, the hydraulic radius is given by + +.. math:: + :label: 14.3 + + R_{r} = \frac{A_{r}}{P_{r}} + +where :math:`A_{r}` (m :sup:`2` ) is the wetted area defined as the part of the +channel cross-section area below the water surface, :math:`P_{r}` (m) is the +wetted perimeter (m), the perimeter confines in the wetted area. + +For hillslopes, sub-network and main channels, a common continuity equation can +be written as + +.. math:: + :label: 14.4 + + \frac{dS}{dt} = Q_{in} - Q_{out} + R + + +where :math:`Q_{in}` (m :sup:`3` s :sup:`-1` ) is the main channel flow from +the upstream grid(s) into the main channel of the current grid, which is zero for +hillslope and sub-network routing. :math:`Q_{out}` (m :sup:`3` s :sup:`-1` ) is +the outflow rate from hillslope into the sub-network, from the sub-network into +the main channel, or from the current main channel to the main channel of its +downstream grid (if not the outlet grid) or ocean (if the current grid is the +basin outlet). :math:`R` (m :sup:`3` s :sup:`-1` ) is a source term, which +could be the surface +runoff generation rate for hillslopes, or lateral inflow (from hillslopes) into +sub-network channel or water-atmosphere exchange fluxes such as precipitation +and evaporation. It is assumed that surface runoff is generated uniformly +across all the hillslopes. Currently, MOSART does not exchange water with +the atmosphere or return water to the land model so its function is strictly +to transport water from runoff generation through the hillslope, tributaries, +and main channels to the basin outlets. + +.. _Numerical Solution MOSART: + +Numerical Solution +---------------------------- + +The numerical implementation of MOSART is mainly based on a subcycling +scheme and a local time-stepping algorithm. There are two levels of +subcycling. For convenience, we denote :math:`T_{inputs}` (s), +:math:`T_{mosart}` (s), :math:`T_{hillslope}` (s) and +:math:`T_{channel}` (s) as the time steps of runoff inputs (from CLM +to MOSART via the flux coupler), MOSART routing, hillslope routing and +channel routing respectively. The first level of subcycling is between +the runoff inputs and MOSART routing. If :math:`T_{inputs}` is 10800s +and :math:`T_{mosart}` is 3600s, three MOSART time steps will be +invoked each time the runoff inputs are updated. The second level of +subcycling is between the hillslope routing and channel routing. This +is to account for the fact that the travel velocity of water across +hillslope is usually much slower than that in the channels. +:math:`T_{hillslope}` is usually set as the same as :math:`T_{mosart}`, +but within each time step of hillslope routing there are a few time +steps for channel routing, i.e., +:math:`T_{hillslope} = D_{levelH2R} \cdot T_{channel}`. The local +time-stepping algorithm is to account for the fact that the travel +velocity of water is much faster in some river channels (e.g., with +steeper bed slope, narrower channel width) than others. That is, for +each channel (either a sub-network or main channel), the final time +step of local channel routing is given as +:math:`T_{local}=T_{channel}/D_{local}`. :math:`D_{local}` is +currently estimated empirically as a function of local channel slope, +width, length and upstream drainage area. If MOSART crashes due to a +numerical issue, we recommend to increase :math:`D_{levelH2R}` and, if +the issue remains, reducing :math:`T_{mosart}`. + +.. _Parameters and Input Data: + +Parameters and Input Data +--------------------------------- + +MOSART is supported by a comprehensive, global hydrography dataset at 0.5 +:sup:`o` resolution. As such, the fundamental spatial unit of MOSART is a 0.5 +:sup:`o` lat/lon grid. The topographic parameters (such as flow direction, +channel length, topographic and channel slopes etc.) were derived using the +Dominant River Tracing (DRT) algorithm (:ref:`Wu et al., 2011` ; +:ref:`Wu et al. 2012 `). The DRT algorithm produces the topographic +parameters in a scale-consistent way to preserve/upscale the key features of +a baseline high-resolution hydrography dataset at multiple coarser spatial +resolutions. Here the baseline high-resolution hydrography dataset is the +1km resolution Hydrological data and maps based on SHuttle Elevation +Derivatives at multiple Scales (HydroSHEDS) +(:ref:`Lehner and Döll, 2004 ` ; +:ref:`Lehner et al., 2008 `). The channel geometry +parameters, e.g., bankfull width and depth, were estimated from empirical +hydraulic geometry relationships as functions of the mean annual discharge. +The Manning roughness coefficients for overland and channel flow were +calculated as functions of landcover and water depth. For more details +on the methodology to derive channel geometry and the Manning’s roughness +coefficients, please refer to +:ref:`Getirana et al. (2012) ` . The full list of +parameters included in this global hydrography dataset is provided in +the :numref:`Table MOSART Parameters`. Evaluation of global simulations +by MOSART using the aforementioned parameters is described in +:ref:`Li et al. (2015b) ` . + +.. _Table MOSART Parameters: + +.. table:: List of parameters in the global hydrography dataset + + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Unit | Description | + +=========================+===============+====================================================================================================================================+ + | :math:`F_{dir}` | \- | The D8 single flow direction for each coarse grid cell coded using 1 (E), 2 (SE), 4 (S), 8 (SW), 16 (W), 32 (NW), 64 (N), 128 (NE) | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`A_{total}` | km :sup:`2` | The upstream drainage area of each coarse grid cell | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`F_{dis}` | m | The dominant river length for each coarse grid cell | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`S_{channel}` | \- | The average channel slope for each coarse grid cell | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`S_{topographic}` | \- | The average topographic slope (for overland flow routing) for each coarse grid cell | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`A_{local}` | km :sup:`2` | The surface area for each coarse grid cell | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`D_{p}` | m :sup:`-1` | Drainage density, calculated as the total channel length within each coarse grid cell divided by the local cell area | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`D_{r}` | m | The bankfull depth of main channel | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`W_{r}` | m | The bankfull width of main channel | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`D_{t}` | m | The average bankfull depth of tributary channels | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`W_{t}` | m | The average bankfull width of tributary channels | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`n_{r}` | \- | Manning’s roughness coefficient for channel flow routing | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + | :math:`n_{h}` | \- | Manning’s roughness coefficient for overland flow routing | + +-------------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------+ + + + +Difference between CLM5.0 and CLM4.5 +------------------------------------- + +1. Routing methods: RTM, a linear reservoir method, is used in CLM4.5 for +river routing, whilst in CLM5.0, MOSART is an added option for river routing +based on the more physically-based kinematic wave method. +2. Runoff treatment: In RTM runoff is routed regardless of its sign so +negative streamflow can be simulated at times. MOSART routes only nonnegative +runoff and always produces positive streamflow, which is important for +future extension for modeling riverine heat and biogeochemical fluxes. +3. Input parameters: RTM in CLM4.5 only requires one layer of spatial variable +of channel velocity, whilst MOSART in CLM5.0 requires 13 parameters that +are all available globally at 0.5 :sup:`o` resolution. +4. Outputs: RTM only produces streamflow simulation, whilst MOSART +additionally simulates the time-varying channel velocities and channel +water depth and channel surface water variation. + + From 3754e4d33471263fb24dbff22e9ea8e8ae3e21a6 Mon Sep 17 00:00:00 2001 From: Yaqiong Lu Date: Thu, 15 Jun 2017 15:20:36 -0600 Subject: [PATCH 074/255] updated crop --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 66f9d2b59f..a91ec4b6f9 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -371,7 +371,6 @@ similar in structure to the wood product pools. :math:`\chi _{L}` index -0.5 0.65 -0.5 -0.5 0.65 -0.5 -0.5 -0.5 grperc 0.11 0.11 0.11 0.11 0.11 0.11 0.11 0.11 flnr 0.293 0.41 0.41 0.41 0.41 0.293 0.293 0.41 - mbbopt 4 9 9 9 9 4 4 9 fcur 1 1 1 1 1 1 1 1 =================================== ========================= ========================== ========================== ========================== ========================== ========================= ========================= ========================== @@ -390,8 +389,7 @@ top-of-canopy height of a crop, *SLA* is specific leaf area. :math:`\chi _{L}` i orientation index, equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. grperc is the growth respiration factor. flnr is the fraction of leaf N in Rubisco enzyme. -mbbopt is the Ball-Berry slope of conductance-photosynthesis relationship. -fcur is the fraction of allocation that goes to currently displayed growth +fcur is the fraction of allocation that goes to currently displayed growth. .. _Allocation: @@ -547,9 +545,10 @@ for each year. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less. We assume a harvest efficiency of 85%, and a grain C of 45% of the grain dry weight. -equation (g/m^2) = (sum(GRAINC_TO_FOOD)/0.45)*.85 - +.. math:: + :label: 25.9 + Grain\ yield(g.m^{-2})=\frac{\sum(GRAINC\_ TO\_ FOOD)*0.85}{0.45} .. _Table Crop allocation parameters: @@ -592,7 +591,7 @@ Other Features Physical Crop Characteristics '''''''''''''''''''''''''''''' Leaf area index (*L*) is calculated as a function of specific leaf area -(SLA) and leaf C (:ref:`Crop phenology parameters`). +(SLA, :numref:`Table Crop phenology parameters`) and leaf C. Stem area index (*S*) is equal to 0.1\ *L* for temperate and tropical corn and sugarcane and 0.2\ *L* for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to @@ -603,7 +602,7 @@ and :math:`{z}_{bot}` (m), come from the AgroIBIS formulation: .. math:: - :label: 25.9 + :label: 25.10 \begin{array}{l} {z_{top} =z_{top}^{\max } \left(\frac{L}{L_{\max } -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{L_{\max } -1} \le 1} \\ @@ -642,7 +641,7 @@ counter in seconds, *f*, is set as soon as the onset growth for crops initiates: .. math:: - :label: 25.10 + :label: 25.11 f = n \times 86400 @@ -673,7 +672,7 @@ the for both rainfed and irrigated spring wheat and sugarcane, the calculation o :math:`GDD_{T_{{\rm 2m}} }` allows for latitudinal variation: .. math:: - :label: 25.11 + :label: 25.12 latitudinal\ variation\ in\ base\ T = \left\{ \begin{array}{lr} From caf97209b788bdf57df0da20fdfa837ae1513966 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Thu, 15 Jun 2017 17:09:03 -0600 Subject: [PATCH 075/255] Updated introduction of photosynthesis chapter --- .../CLM50_Tech_Note_Photosynthesis.rst | 32 ++++++++++++++++--- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index d50b90a814..f54c7da3c1 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -3,21 +3,43 @@ Stomatal Resistance and Photosynthesis ========================================= +Summary of CLM5.0 updates relative to the CLM4.5 +----------------------------------------------------- + +We describe here the complete photosynthesis and stomatal conductance parameterizations that +appear in CLM5.0. Corresponding information for CLM4.5 appeared in the +CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `). + +CLM5 includes the following new changes to photosynthesis and stomatal conductance: + +- Default stomatal conductance calculation uses the Medlyn conductance model + +- :math:`V_{cmax}` is predicted by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) + +- Water stress is applied by the hydraulic conductance model (Chapter :numref:`rst_Plant Hydraulics`) + + +Introduction +----------------------- + Leaf stomatal resistance, which is needed for the water vapor flux -(Chapter 5), is coupled to leaf photosynthesis similar to Collatz et al. -(1991, 1992). These equations are solved separately for sunlit and +(Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`), +is coupled to leaf photosynthesis similar to Collatz et al. +(:ref:`1991 `, :ref:`1992 `). These equations are solved separately for sunlit and shaded leaves using average absorbed photosynthetically active radiation for sunlit and shaded leaves [:math:`\phi ^{sun}` ,\ :math:`\phi ^{sha}` W m\ :sup:`-2` -(section 4.1)] to give sunlit and shaded stomatal resistance +(section :numref:`Solar Fluxes`)] to give sunlit and shaded stomatal resistance (:math:`r_{s}^{sun}` ,\ :math:`r_{s}^{sha}` s m\ :sup:`-1`) and photosynthesis (:math:`A^{sun}` ,\ :math:`A^{sha}` µmol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`). Canopy photosynthesis is :math:`A^{sun} L^{sun} +A^{sha} L^{sha}` , where :math:`L^{sun}` and :math:`L^{sha}` are the sunlit and shaded leaf -area indices (section 4.1). Canopy conductance is +area indices (section :numref:`Solar Fluxes`). Canopy conductance is :math:`\frac{1}{r_{b} +r_{s}^{sun} } L^{sun} +\frac{1}{r_{b} +r_{s}^{sha} } L^{sha}` , where :math:`r_{b}` is the leaf boundary layer resistance (section -5.3). The equation set is described by Bonan et al. (2011). +:numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). +The implementation is described by Bonan et al. (:ref:`2011 `), though different +methods of calculating stomatal conductance and :math:`V_{cmax}` are used in CLM5. .. _Stomatal resistance: From e2fb2b8d51bdbc181e8200049d3ccb03ceab3d7d Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 16 Jun 2017 08:35:39 -0600 Subject: [PATCH 076/255] add mosart figure --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index bbad06b077..31ab7685d8 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -53,6 +53,8 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. +- :numref:`Figure MOSART conceptual diagram` MOSART conceptual diagram. + - :numref:`Figure Schematic of urban and atmospheric model coupling` Schematic of urban and atmospheric model coupling. - :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. From c1de9a28f715cf6db65c7538ea3cfad8e18ebbe6 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 16 Jun 2017 08:39:14 -0600 Subject: [PATCH 077/255] mosart label change --- doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst | 2 +- doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index fa25eeb5c8..84752b5429 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -11,7 +11,7 @@ land units can be found elsewhere in this document (see Chapter :numref:`rst_Surface Characterization, Vertical Discretization, and Model Input Requirements` for an overview). -.. _Overview: +.. _Overview Glaciers: Overview ------------- diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index cae3bd0493..24df209f08 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -3,7 +3,7 @@ Model for Scale Adaptive River Transport (MOSART) ================================================= -.. _Overview: +.. _Overview MOSART: Overview --------- From f2daf15ca8f6887d74023d245fb73e016d944bc7 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Wed, 28 Jun 2017 17:16:04 -0600 Subject: [PATCH 078/255] Detailed editing of crop chapter through the end of the phenology section --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 72 ++++++++++--------- .../CLM50_Tech_Note_Photosynthesis.rst | 66 ----------------- 2 files changed, 37 insertions(+), 101 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index a91ec4b6f9..37eca59b4e 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -96,7 +96,7 @@ land management between crops. Each crop type has a rainfed and an irrigated pft that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural pfts), and the managed crop type proportions within the crop area is based on the dataset created by -(:ref:`Portmann et al. 2010 `) for present day. New in CLM5, crop area is +:ref:`Portmann et al. (2010)` for present day. New in CLM5, crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries (:ref:`Lawrence et al. 2016 `). For more details about how @@ -130,11 +130,13 @@ Information detailing which parameters are used for each crop type is included in :numref:`Table Crop plant functional types`. It should be noted that pft-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to -remap the yields of each actively and inactively managed crop type. +remap the yields of each actively and inactively managed crop type. Otherwise, the +actively managed crop type will include yields for that crop type and all inactively +managed crop types that are using the same parameter set. .. _Table Crop plant functional types: -.. table:: Crop plant functional types (pfts) in CLM5BGCCROP. +.. table:: Crop plant functional types (pfts) included in CLM5BGCCROP. === =========================== ================ =========================== ITV Plant function types (PFTs) Management Class Crop Parameters Used @@ -241,25 +243,25 @@ planting date (for the northern hemisphere) in :numref:`Table Crop phenology par \end{array} where :math:`{T}_{10d}` is the 10-day running mean of :math:`{T}_{2m}`, (the simulated 2-m air -temperature at every model time step) and :math:`T_{10d}^{\min}` is +temperature during each model time step) and :math:`T_{10d}^{\min}` is the 10-day running mean of :math:`T_{2m}^{\min }` (the daily minimum of -:math:`{T}_{2m}`. :math:`{T}_{p}` and :math:`T_{p}^{\min }` are crop-specific coldest planting temperatures +:math:`{T}_{2m}`). :math:`{T}_{p}` and :math:`T_{p}^{\min }` are crop-specific coldest planting temperatures (:numref:`Table Crop phenology parameters`), :math:`{GDD}_{8}` is the 20-year running mean growing degree-days (units are degree-days or :sup:`o` days) tracked -from April through September (NH) base 8\ :sup:`o` C with +from April through September (NH) above 8\ :sup:`o` C with maximum daily increments of 30\ :sup:`o` days (see equation :eq:`25.3`), and :math:`{GDD}_{min }`\ is the minimum growing degree day requirement (:numref:`Table Crop phenology parameters`). :math:`{GDD}_{8}` does not change as quickly as :math:`{T}_{10d}` and :math:`T_{10d}^{\min }`, so -it determines whether the crop can be planted in a grid cell, while the -two faster-changing variables determine when the crop may be planted. +it determines whether it is warm enough for the crop to be planted in a grid cell, while the +2-m air temperature variables determine the day when the crop may be planted if the :math:`{GDD}_{8}` threshold is met. If the requirements in equation :eq:`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as :math:`{GDD}_{8} > 0`. In the southern hemisphere (SH) the NH requirements apply 6 months later. At planting, each crop seed pool is assigned 3 gC m\ :sup:`-2` from its -grain product pool. The seed carbon transferred to the leaves upon leaf emergence. An +grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the pft’s C to N -ratio for leaves (:math:`{CN}_{leaf}` in :numref:`Table Crop allocation parameters`, this differs from AgroIBIS, +ratio for leaves (:math:`{CN}_{leaf}` in :numref:`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, :math:`{GDD}_{mat}`, according to the following AgroIBIS rules: @@ -275,11 +277,11 @@ for the crop to reach vegetative and physiological maturity, GDD_{{\rm mat}}^{{\rm trop.soy}} =GDD_{{\rm 10}} & {\rm \; \; \; and\; \; \; } & GDD_{{\rm mat}}^{{\rm trop.soy}} <2100{}^\circ {\rm days} \end{array} -where :math:`{GDD}_{10}` is the 20-year running mean growing -degree-days tracked from April through September (NH) base -10\ :sup:`o`\C with maximum daily increments of -30\ :sup:`o`\days. Equation :eq:`25.3` shows how we calculate -:math:`{GDD}_{0}`, :math:`{GDD}_{8}`, and :math:`{GDD}_{10}`: +where :math:`{GDD}_{0}`, :math:`{GDD}_{8}`, and :math:`{GDD}_{10}` are the 20-year running mean growing +degree-days tracked from April through September (NH) over 0\ :sup:`o`\C, 8\ :sup:`o`\C, and +10\ :sup:`o`\C, respectively, with maximum daily increments of +26\ :sup:`o`\days (for :math:`{GDD}_{0}`) or 30\ :sup:`o`\days (for :math:`{GDD}_{8}` and :math:`{GDD}_{10}`). Equation :eq:`25.3` shows how we calculate +:math:`{GDD}_{0}`, :math:`{GDD}_{8}`, and :math:`{GDD}_{10}` for each model timestep: .. math:: :label: 25.3 @@ -291,9 +293,9 @@ degree-days tracked from April through September (NH) base \end{array} where, if :math:`{T}_{2m}` - :math:`{T}_{f}` takes on values -outside the above ranges, then it equals the minimum or maximum value in -the range. Also :math:`{T}_{f}` equals 273.15 K, -:math:`{T}_{2m}` has units of K, and *GDD* has units of ºdays. +outside the above ranges within a day, then it equals the minimum or maximum value in +the range for that day. :math:`{T}_{f}` is the freezing temperature of water and equals 273.15 K, +:math:`{T}_{2m}` is the 2-m air temperature in units of K, and *GDD* is in units of ºdays. .. _Leaf emergence: @@ -301,25 +303,25 @@ Leaf emergence ''''''''''''''''''''''' According to AgroIBIS, leaves may emerge when the growing degree-days of -soil temperature to 0.05 m depth tracked since planting -(:math:`GDD_{T_{soi} }` ) reaches 1 to 5% of :math:`{GDD}_{mat}` -(:numref:`Table Crop phenology parameters`). The base temperature for :math:`GDD_{T_{soi} }` -are listed in :numref:`Table Crop phenology parameters`. -Leaf onset occurs in the first +soil temperature to 0.05 m depth (:math:`GDD_{T_{soi} }` ), which is tracked since planting, +reaches 1 to 5% of :math:`{GDD}_{mat}` +(see Phase 2 % :math:`{GDD}_{mat}` in :numref:`Table Crop phenology parameters`). The base temperature threshold for :math:`GDD_{T_{soi} }` +are listed in :numref:`Table Crop phenology parameters`, and leaf emergence (crop phenology phase 2) +starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf -C. Subsequently, the leaf area index generally increases and reaches -a maximum value during phase 2. Stem and root C are also increasing, based on -the carbon allocation algorithem in section :numref:`Leaf emergence to grain fill`. +C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches +a predetermined maximum value. Stem and root C also increase throughout phase 2 based on +the carbon allocation algorithm in section :numref:`Leaf emergence to grain fill`. .. _Grain fill: Grain fill ''''''''''''''''''' -Phase 3 begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since -planting like :math:`GDD_{T_{soi} }` but for 2-m air temperature, -:math:`GDD_{T_{{\rm 2m}} }`, must reach a heat unit threshold, *h*, -of 40 to 65% of :math:`{GDD}_{mat}` (:numref:`Table Crop phenology parameters`). +The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since +planting, similar to :math:`GDD_{T_{soi} }` but for 2-m air temperature, +:math:`GDD_{T_{{\rm 2m}} }`, must reach a threshold +of 40 to 65% of :math:`{GDD}_{mat}` (see Phase 3 % :math:`{GDD}_{mat}` in :numref:`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the :math:`{GDD}_{mat}` is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. @@ -339,11 +341,11 @@ the number of days past planting reaches a crop-specific maximum (:numref:`Table Crop phenology parameters`), then the crop is harvested. Harvest occurs in one time step using the BGC leaf offset algorithm. Variables track the flow of grain C and -N to food and of live stem C and N to litter. Putting live +N to food and of all other plant pools, including live stem C and N, to litter. Putting live stem C and N into the litter pool is in contrast to the approach for unmanaged PFTs which puts live stem C and N into dead stem pools first. Leaf and root C and N pools are routed to the litter pools in the same manner as natural vegetation. Whereas food C and N -formerly was transferred to the litter pool, CLM5 routes food C and N +was formerly transferred to the litter pool, CLM5 routes food C and N to a grain product pool where the C and N decay to the atmosphere over one year, similar in structure to the wood product pools. @@ -378,8 +380,8 @@ Notes: :math:`Date_{planting}^{min}` and :math:`Date_{planting}^{max}` are the minimum and maximum planting date in the Northern Hemisphere, the corresponding dates in the Southern Hemisphere apply 6 months later. :math:`T_{p}` and :math:`T_{p}^{ min }` are crop-specific coldest planting temperatures. -:math:`{GDD}_{min}` is the lowest (for planting) 20-year running mean growing degree-days base -on the base temperature in the 7\ :sup:`th` row, tracked from April to September (NH). +:math:`{GDD}_{min}` is the lowest (for planting) 20-year running mean growing degree-days based +on the base temperature threshold in the 7\ :sup:`th` row, tracked from April to September (NH). :math:`{GDD}_{mat}` is a crop’s 20-year running mean growing degree-days needed for vegetative and physiological maturity. Harvest occurs at 100%\ :math:`{GDD}_{mat}` or when the days past planting @@ -388,7 +390,7 @@ are described in the text. :math:`z_{top}^{\max }` is the maximum top-of-canopy height of a crop, *SLA* is specific leaf area. :math:`\chi _{L}` is the leaf orientation index, equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. -grperc is the growth respiration factor. flnr is the fraction of leaf N in Rubisco enzyme. +grperc is the growth respiration factor. flnr is the fraction of leaf N in the Rubisco enzyme. fcur is the fraction of allocation that goes to currently displayed growth. .. _Allocation: diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index f54c7da3c1..de6693e76b 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -508,72 +508,6 @@ orbital geometry (:math:`\pm`\ 23.4667º [:math:`\pm`\ 0.409571 radians], positive for Northern Hemisphere latitudes and negative for Southern Hemisphere). -.. _Soil water stress: - -Soil water stress ---------------------- - -Soil water influences stomatal conductance directly by multiplying the -minimum conductance by a soil water stress function :math:`\beta _{t}` -and also indirectly through :math:`A_{n}` in the C\ :sub:`3` and -C\ :sub:`4` photosynthesis models, as in Sellers et al. (1996). -The latter effect is achieved by multiplying :math:`V_{c\; \max }` and -:math:`R_{d}` by :math:`\beta _{t}` . - -The function :math:`\beta _{t}` ranges from one when the soil is wet to -near zero when the soil is dry and depends on the soil water potential -of each soil layer, the root distribution of the plant functional type, -and a plant-dependent response to soil water stress - -.. math:: - :label: 9.26) - - \beta _{t} =\sum _{i}w_{i} r_{i} - -where :math:`w_{i}` is a plant wilting factor for layer :math:`i` and -:math:`r_{i}` is the fraction of roots in layer :math:`i`. The plant -wilting factor :math:`w_{i}` is - -.. math:: - :label: 9.27) - - w_{i} =\left\{\begin{array}{l} {\frac{\psi _{c} -\psi _{i} }{\psi _{c} -\psi _{o} } \left[\frac{\theta _{sat,i} -\theta _{ice,i} }{\theta _{sat,i} } \right]\le 1\qquad {\rm for\; }T_{i} >T_{f} -2{\rm \; and\; }\theta _{liq,\, i} >0} \\ {0\qquad \qquad \qquad \qquad {\rm for\; }T_{i} \le T_{f} -2{\rm \; or\; }\theta _{liq,\, i} \le 0} \end{array}\right\} - -where :math:`\psi _{i}` is the soil water matric potential (mm) and -:math:`\psi _{c}` and :math:`\psi _{o}` are the soil water potential -(mm) when stomata are fully closed or fully open (respectively) (Table -8.1). The term in brackets scales :math:`w_{i}` by the ratio of the -effective porosity (accounting for the ice fraction; -:math:`\theta _{sat} -\theta _{ice}` ) relative to the total porosity. - -Here, the soil water matric potential :math:`\psi _{i}` \ is defined as - -.. math:: - :label: 9.28) - - \psi _{i} =\psi _{sat,i} \, s_{i}^{-B_{i} } \ge \psi _{c} - -where :math:`s_{i}` is the soil wetness for layer :math:`i` with -respect to the effective porosity and :math:`\psi _{sat,i}` and -:math:`B_{i}` are the saturated soil matric potential (mm) and the -Clapp and Hornberger (1978) parameter (section 7.4.1). The soil wetness -:math:`s_{i}` is - -.. math:: - :label: 9.29) - - s_{i} =\frac{\theta _{liq,\, i} }{\theta _{sat,\, i} -\theta _{ice,\, i} } \ge 0.01 - -where -:math:`\theta _{ice,\, i} ={w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(\rho _{ice} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{ice} \Delta z_{i} \right)} \le \theta _{sat,\, i}` \ and -:math:`\theta _{liq,\, i} ={w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(\rho _{liq} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{liq} \Delta z_{i} \right)} \le \theta _{sat,\, i} -\theta _{ice,\, i}` . -:math:`w_{ice,\, i}` and :math:`w_{liq,\, i}` are the ice and liquid -water contents (kg m\ :sup:`-2`) (Chapter 7), -:math:`\theta _{sat,\, i}` is the saturated volumetric water content -(section 7.4.1), :math:`\rho _{ice}` and :math:`\rho _{liq}` are the -densities of ice and liquid water (kg m\ :sup:`-3`) (Table 2.6), -and :math:`\Delta z_{i}` is the soil layer thickness (m) (section 6.1). - .. _Numerical implementation photosynthesis: Numerical implementation From c87be809421b5ce7e38f371a315d1fe16b27fc2f Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Fri, 30 Jun 2017 13:48:02 -0600 Subject: [PATCH 079/255] Detailed edits on full crop chapter --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 115 ++++++++++-------- 1 file changed, 61 insertions(+), 54 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 37eca59b4e..1694764136 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -320,12 +320,12 @@ Grain fill The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to :math:`GDD_{T_{soi} }` but for 2-m air temperature, -:math:`GDD_{T_{{\rm 2m}} }`, must reach a threshold +:math:`GDD_{T_{{\rm 2m}} }`, must reach a heat unit threshold, *h*, of of 40 to 65% of :math:`{GDD}_{mat}` (see Phase 3 % :math:`{GDD}_{mat}` in :numref:`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the :math:`{GDD}_{mat}` is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. -When the maximum value of leaf area index is reached in phase 2, phase 3 begins. +When the maximum value of leaf area index is reached in phase 2 (:numref:`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the pft as done in the BGC part of the model. @@ -339,15 +339,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When :math:`GDD_{T_{{\rm 2m}} }` reaches 100% of :math:`{GDD}_{mat}` or the number of days past planting reaches a crop-specific maximum (:numref:`Table Crop phenology parameters`), then the crop is harvested. -Harvest occurs in one time step using -the BGC leaf offset algorithm. Variables track the flow of grain C and -N to food and of all other plant pools, including live stem C and N, to litter. Putting live -stem C and N into the litter pool is in contrast to the approach for unmanaged PFTs which -puts live stem C and N into dead stem pools first. Leaf and root C and N pools -are routed to the litter pools in the same manner as natural vegetation. Whereas food C and N -was formerly transferred to the litter pool, CLM5 routes food C and N -to a grain product pool where the C and N decay to the atmosphere over one year, -similar in structure to the wood product pools. +Harvest occurs in one time step using the BGC leaf offset algorithm. .. _Table Crop phenology parameters: @@ -398,7 +390,7 @@ fcur is the fraction of allocation that goes to currently displayed growth. Allocation ^^^^^^^^^^^^^^^^^ -Allocation responds to the same phases as phenology (section :numref:`Phenology`). +Allocation changes based on the crop phenology phases phenology (section :numref:`Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop’s leaf, live stem, fine root, and @@ -408,33 +400,35 @@ Typically, C:N ratios in plant tissue vary throughout the growing season and tend to be lower during early growth stages and higher in later growth stages. In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of -crops. This modified C:N ratio approach accounts for the nitrogen -retranslocation that occurs during phase 3 of crop growth. Leaf, stem, and root -C:N ratios for phases 1 and 2 are calculated +crops: one during the leaf emergence phase (phenology phase 2), and a second during +grain fill phase (phenology phase 3). This modified C:N ratio approach accounts for the nitrogen +retranslocation that occurs during the grain fill phase (phase 3) of crop growth. Leaf, stem, and root +C:N ratios for phase 2 are calculated using the new CLM5 carbon and nitrogen allocation scheme (Chapter :numref:`rst_CN Allocation`), which provides a target C:N value -and allows C:N to vary through time. +(:numref:`Table Crop allocation parameters`) and allows C:N to vary through time. During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon -throughout the growth season. +throughout the growing season. The BGC part of the model keeps track of a term representing excess -maintenance respiration that for perennial pfts or pfts with C storage -may be extracted from later gross primary production. Later extraction +maintenance respiration, which supplies the carbon required for maintenance respiration during periods of +low photosynthesis (Chapter :numref:`rst_Plant Respiration`). +Carbon supply for excess maintenance respiration cannot continue to happen after harvest for annual crops, so at harvest -we turn the excess respiration pool into a flux that extracts -CO\ :sub:`2` directly from the atmosphere. This way we eliminate -any excess maintenance respiration remaining at harvest as if such +the excess respiration pool is turned into a flux that extracts +CO\ :sub:`2` directly from the atmosphere. This way +any excess maintenance respiration remaining at harvest is eliminated as if such respiration had not taken place. .. _Leaf emergence to grain fill: -Leaf emergence to grain fill +Leaf emergence ''''''''''''''''''''''''''''''''''''' During phase 2, the allocation coefficients (fraction of available C) to @@ -454,11 +448,11 @@ exclusively to the fine roots. .. _Grain fill to harvest: -Grain fill to harvest +Grain fill '''''''''''''''''''''''''''''' The calculation of :math:`a_{froot}` remains the same from phase 2 to -phase 3. Other allocation coefficients change to: +phase 3. During grain fill (phase 3), other allocation coefficients change to: .. math:: :label: 25.5 @@ -499,7 +493,7 @@ through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage for all crops except soybean, for which retranslocation is after LAI decline. Nitrogen stored in the leaf and stem is moved into a storage -retranslocation pool. For wheat and rice, nitrogen in roots is also +retranslocation pool for all crops, and for wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized depends on the C:N ratio of the plant tissue, and is calculated as @@ -524,28 +518,37 @@ root, respectively, :math:`{N}_{leaf}`, :math:`{N}_{stem}`, and :math:`{N}_{froo is the nitrogen in the plant leaf, stem, and fine root, respectively, and :math:`CN^f_{leaf}`, :math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively (:numref:`Table Crop allocation parameters`). Since -C:N measurements are taken from mature crops, pre-grain development C:N -ratios for leaves, stems, and roots are optimized to allow maximum -nitrogen accumulation for later use during organ development. Post-grain -fill C:N ratios are assigned the same as crop residue. Once excess -nitrogen is moved into the retranslocated pool, during the remainder of -the growing season the retranslocated pool is used first to meet plant +C:N measurements are often taken from mature crops, pre-grain development C:N +ratios for leaves, stems, and roots in the model are optimized to allow maximum +nitrogen accumulation for later use during organ development, and post-grain +fill C:N ratios are assigned the same as crop residue. After +nitrogen is moved into the retranslocated pool, +the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the -retranslocated pool equal to the plant nitrogen demand. Once the +retranslocated pool equal to the plant nitrogen demand for each organ (:math:`{CN_{[organ]}^{f} }` in :numref:`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. .. _Harvest to food and seed: -Harvest to food and seed +Harvest '''''''''''''''''''''''''''''' -In CLM5, the C and N required for crop seeding is removed from the grain -product pool during harvest and used to seed crops in the subsequent year. -Caluating the crop yields requires that you sum the GRAINC_TO_FOOD variable -for each year. Additionally, harvest is not typically 100% efficient, so +Variables track the flow of grain C and +N to food and of all other plant pools, including live stem C and N, to litter. Putting live +stem C and N into the litter pool is in contrast to the approach for unmanaged PFTs which +puts live stem C and N into dead stem pools first. Leaf and root C and N pools +are routed to the litter pools in the same manner as natural vegetation. Whereas food C and N +was formerly transferred to the litter pool, CLM5 routes food C and N +to a grain product pool where the C and N decay to the atmosphere over one year, +similar in structure to the wood product pools. +Additionally, CLM5 accounts for the C and N required for crop seeding by removing the seed C and N from the grain +product pool during harvest. The crop seed pool is then used to seed crops in the subsequent year. +Calcuating the crop yields (Equation :eq:`25.9`) requires that you sum the GRAINC_TO_FOOD variable +for each year, and must account for the proportion of C in the dry crop weight. +Here, we assume that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less. We assume a harvest -efficiency of 85%, and a grain C of 45% of the grain dry weight. +efficiency of 85%. .. math:: :label: 25.9 @@ -579,8 +582,9 @@ efficiency of 85%, and a grain C of 45% of the grain dry weight. :math:`{CN}_{grain}` 50 50 50 50 50 50 50 50 =========================================== ============== ============ ================== ====== ====== ========= ============= ================ -Notes: Crop growth phases and corresponding variables are described in -the text +Notes: Crop growth phases and corresponding variables are described throughout +the text. :math:`{CN}_{leaf}`, :math:`{CN}_{stem}`, and :math:`{CN}_{froot}` are +the target C:N ratios used during the leaf emergence phase (phase 2). .. _Other Features: @@ -611,6 +615,9 @@ and :math:`{z}_{bot}` (m), come from the AgroIBIS formulation: {z_{bot} =0.02{\rm m}} \end{array} +where :math:`z_{top}^{\max }` is the maximum top-of-canopy height of the crop (:numref:`Table Crop phenology parameters`) +and :math:`L_{\max }` is the maximum leaf area index (:numref:`Table Crop allocation parameters`). + .. _Interactive fertilization: Interactive Fertilization @@ -634,12 +641,12 @@ of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowl to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, -fertilizer application begins during the emergence phase of crop -development and continues for 20 days, which helps reduce large losses +fertilizer application begins during the leaf emergence phase of crop +development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer -counter in seconds, *f*, is set as soon as the onset growth for crops +counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: .. math:: @@ -647,10 +654,10 @@ initiates: f = n \times 86400 -where *n* is set to 20 fertilizer application days. When the crop enters -phase 2 (leaf emergence to the beginning of grain fill) of its growth +where *n* is set to 20 fertilizer application days and 86400 is the number of seconds per day. When the crop enters +phase 2 (leaf emergence) of its growth cycle, fertilizer application begins by initializing fertilizer amount -to the total fertilizer at each grid cell divided by the initialized *f*. +to the total fertilizer at each column within the grid cell divided by the initialized *f*. Fertilizer is applied and *f* is decremented each time step until a zero balance on the counter is reached. @@ -660,8 +667,8 @@ the counter is reached. Biological nitrogen fixation for soybeans '''''''''''''''''''''''''''''''''''''''''' Biological N fixation for soybeans is calculated by the fixation and uptake of -nitrogen module (Chapter :numref:`rst_FUN`). Unlike natural -vegetation, where a fraction of the vegetation are N fixers, all soybeans +nitrogen module (Chapter :numref:`rst_FUN`) and is the same as N fixation in natural vegetation. Unlike natural +vegetation, where a fraction of each pft are N fixers, all soybeans are treated as N fixers. .. _Latitude vary base tempereature for growing degree days: @@ -692,14 +699,14 @@ and sugarcane. Separate reproductive pool '''''''''''''''''''''''''''''' One notable difference between natural vegetation and crops is the -presence of a reproductive carbon pool (and nitrogen pool). Accounting -for the reproductive pool helps determine whether crops are performing +presence of reproductive carbon and nitrogen pools. Accounting +for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. -In CLM5BGCCROP, as allocation declines +In CLM5BGCCROP, as allocation declines in stem, leaf, and root pools (see section :numref:`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. @@ -771,7 +778,7 @@ the soil is :math:`N_{irr}` is the index of the soil layer corresponding to a specified depth :math:`z_{irrig}` (:numref:`Table Irrigation parameters`) and -:math:`\Delta z` is the thickness of the soil layer (section +:math:`\Delta z_{j}` is the thickness of the soil layer in layer :math:`j` (section :numref:`Vertical Discretization`). :math:`\theta_{j}` is the volumetric soil moisture in layer :math:`j` (section :numref:`Soil Water`). :math:`\theta_{target}` and @@ -786,7 +793,7 @@ the irrigation period :math:`T_{irrig}` (s). Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., added to :math:`{q}_{grnd,liq}`: section :numref:`Canopy Water`). -To conserve mass, irrigation is removed from river water storage (Chapter 11). +To conserve mass, irrigation is removed from river water storage (Chapter :numref:`rst_River Transport Model (RTM)`). When river water storage is inadequate to meet irrigation demand, there are two options: 1) the additional water can be removed from the ocean model, or 2) the irrigation demand can be reduced such that From 6cf7a5d1b0b7fe6672e5e1aaf219a7503f181195 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Fri, 30 Jun 2017 14:22:54 -0600 Subject: [PATCH 080/255] One more small update to crop chapter text --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 1694764136..85c284cd89 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -305,8 +305,9 @@ Leaf emergence According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth (:math:`GDD_{T_{soi} }` ), which is tracked since planting, reaches 1 to 5% of :math:`{GDD}_{mat}` -(see Phase 2 % :math:`{GDD}_{mat}` in :numref:`Table Crop phenology parameters`). The base temperature threshold for :math:`GDD_{T_{soi} }` -are listed in :numref:`Table Crop phenology parameters`, and leaf emergence (crop phenology phase 2) +(see Phase 2 % :math:`{GDD}_{mat}` in :numref:`Table Crop phenology parameters`). The base temperature threshold values for :math:`GDD_{T_{soi} }` +are listed in :numref:`Table Crop phenology parameters` (the same base temperature threshold values are also used for +:math:`GDD_{T_{{\rm 2m}} }` in section :numref:`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches From 03a437d3a6ec85018d85e137d8f927b0486b6bf3 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Fri, 30 Jun 2017 17:16:50 -0600 Subject: [PATCH 081/255] Updates to photosynthesis chapter (canopy scaling & numerical implementation) and photosynthetic capacity chapter (included section headings and moved Vcmax calculations here, though calculation still needs to be verified) --- .../CLM50_Tech_Note_Photosynthesis.rst | 165 ++++++------------ ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 67 ++++++- 2 files changed, 117 insertions(+), 115 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index de6693e76b..cfe155d42a 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -14,7 +14,10 @@ CLM5 includes the following new changes to photosynthesis and stomatal conductan - Default stomatal conductance calculation uses the Medlyn conductance model -- :math:`V_{cmax}` is predicted by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) +- :math:`J_{max}` is predicted by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) + +- Leaf N concentration and the fraction of leaf N in Rubisco used to calculate +:math:`V_{cmax}` are determined by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) - Water stress is applied by the hydraulic conductance model (Chapter :numref:`rst_Plant Hydraulics`) @@ -39,7 +42,8 @@ area indices (section :numref:`Solar Fluxes`). Canopy conductance is where :math:`r_{b}` is the leaf boundary layer resistance (section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). The implementation is described by Bonan et al. (:ref:`2011 `), though different -methods of calculating stomatal conductance and :math:`V_{cmax}` are used in CLM5. +methods of calculating stomatal conductance, :math:`J_{max}`, and the nitrogen variables +used to calculate :math:`V_{cmax}` are used in CLM5. .. _Stomatal resistance: @@ -55,7 +59,7 @@ the CO\ :sub:`1` concentration at the leaf surface. Leaf stomatal resistance is .. math:: - :label: ZEqnNum230514 + :label: 9.1 \frac{1}{r_{s} } =g_{s} =m\frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } } h_{s} +b\, \beta _{t} @@ -162,7 +166,7 @@ describe the implementation, modified here. In its simplest form, leaf net photosynthesis after accounting for respiration (:math:`R_{d}` ) is .. math:: - :label: 9.2) + :label: 9.2 A_{n} =\min \left(A_{c} ,A_{j} ,A_{p} \right)-R_{d} . @@ -171,9 +175,8 @@ The RuBP carboxylase (Rubisco) limited rate of carboxylation s\ :sup:`-1`) is .. math:: - :label: ZEqnNum141081 + :label: 9.3 - \label{ZEqnNum141081} A_{c} =\left\{\begin{array}{l} {\frac{V_{c\max } \left(c_{i} -\Gamma _{\*} \right)}{c_{i} +K_{c} \left(1+{o_{i} \mathord{\left/ {\vphantom {o_{i} K_{o} }} \right. \kern-\nulldelimiterspace} K_{o} } \right)} \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {V_{c\max } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. The maximum rate of carboxylation allowed by the capacity to regenerate @@ -181,7 +184,7 @@ RuBP (i.e., the light-limited rate) :math:`A_{j}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 9.4) + :label: 9.4 A_{j} =\left\{\begin{array}{l} {\frac{J\left(c_{i} -\Gamma _{\*} \right)}{4c_{i} +8\Gamma _{\*} } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\alpha (4.6\phi )\qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. @@ -191,7 +194,7 @@ C\ :sub:`4` plants :math:`A_{p}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: ZEqnNum104028 + :label: 9.5 A_{p} =\left\{\begin{array}{l} {3T_{p\qquad } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {k_{p} \frac{c_{i} }{P_{atm} } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}. @@ -221,7 +224,7 @@ photosynthetically active radiation absorbed by the leaf. A common expression is the smaller of the two roots of the equation .. math:: - :label: 9.6) + :label: 9.6 \Theta _{PSII} J^{2} -\left(I_{PSII} +J_{\max } \right)J+I_{PSII} J_{\max } =0 @@ -236,7 +239,7 @@ with 4.6 :math:`\mu`\ mol J\ :sup:`-1`, the light utilized in electron transport is .. math:: - :label: 9.7) + :label: 9.7 I_{PSII} =0.5\Phi _{PSII} (4.6\phi ) @@ -253,7 +256,7 @@ The model uses co-limitation as described by Collatz et al. (1991, smaller root of the equations .. math:: - :label: 9.8) + :label: 9.8 \begin{array}{rcl} {\Theta _{cj} A_{i}^{2} -\left(A_{c} +A_{j} \right)A_{i} +A_{c} A_{j} } & {=} & {0} \\ {\Theta _{ip} A^{2} -\left(A_{i} +A_{p} \right)A+A_{i} A_{p} } & {=} & {0} \end{array} . @@ -287,21 +290,21 @@ respiration rate. The parameters :math:`V_{c\max 25}` , :math:`T_{v}` (K) as: .. math:: - :label: 9.9) + :label: 9.9 \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma _{*} } & {=} & {\Gamma _{*25} \; f\left(T_{v} \right)} \end{array} with .. math:: - :label: 9.10) + :label: 9.10 f\left(T_{v} \right)=\; \exp \left[\frac{\Delta H_{a} }{298.15\times 0.001R_{gas} } \left(1-\frac{298.15}{T_{v} } \right)\right] and .. math:: - :label: 9.11) + :label: 9.11 f_{H} \left(T_{v} \right)=\frac{1+\exp \left(\frac{298.15\Delta S-\Delta H_{d} }{298.15\times 0.001R_{gas} } \right)}{1+\exp \left(\frac{\Delta ST_{v} -\Delta H_{d} }{0.001R_{gas} T_{v} } \right)} . @@ -312,7 +315,7 @@ Because :math:`T_{p}` as implemented here varies with :math:`T_{p}` . For C\ :sub:`4` plants, .. math:: - :label: 9.12) + :label: 9.12 \begin{array}{l} {V_{c\max } =V_{c\max 25} \left[\frac{Q_{10} ^{(T_{v} -298.15)/10} }{f_{H} \left(T_{v} \right)f_{L} \left(T_{v} \right)} \right]} \\ {f_{H} \left(T_{v} \right)=1+\exp \left[s_{1} \left(T_{v} -s_{2} \right)\right]} \\ {f_{L} \left(T_{v} \right)=1+\exp \left[s_{3} \left(s_{4} -T_{v} \right)\right]} \end{array} @@ -323,7 +326,7 @@ with :math:`Q_{10} =2`, Additionally, .. math:: - :label: 9.13) + :label: 9.13 R_{d} =R_{d25} \left\{\frac{Q_{10} ^{(T_{v} -298.15)/10} }{1+\exp \left[s_{5} \left(T_{v} -s_{6} \right)\right]} \right\} @@ -331,7 +334,7 @@ with :math:`Q_{10} =2`, :math:`s_{5} =1.3` K\ :sup:`-1` and :math:`s_{6} =328.15`\ K, and .. math:: - :label: 9.14) + :label: 9.14 k_{p} =k_{p25} \, Q_{10} ^{(T_{v} -298.15)/10} @@ -367,7 +370,7 @@ achieved by allowing :math:`\Delta S`\ to vary with growth temperature according to .. math:: - :label: 9.15) + :label: 9.15 \begin{array}{l} {\Delta S=668.39-1.07(T_{10} -T_{f} )\qquad \qquad {\rm for\; }V_{c\max } } \\ {\Delta S=659.70-0.75(T_{10} -T_{f} )\qquad \qquad {\rm for\; }J_{\max } } \end{array} @@ -379,7 +382,7 @@ parameterization, :math:`\Delta H_{d}` \ = 200000, ratio :math:`J_{\max 25} /V_{c\max 25}` at 25 :sup:`o`\ C decreases with growth temperature as .. math:: - :label: 9.16) + :label: 9.16 J_{\max 25} /V_{c\max 25} =2.59-0.035(T_{10} -T_{f} ). @@ -388,83 +391,49 @@ temperature (K) and :math:`T_{f}` is the freezing point of water (K). For lack of data, :math:`T_{p}` acclimates similar to V :sub:`cmax` . Acclimation is restricted over the temperature range :math:`T_{10} -T_{f} \ge 11`\ :sup:`o`\ C and :math:`T_{10} -T_{f} \le 35`\ :sup:`o`\ C. -.. _V\ :sub:`cmax25` and Canopy scaling: +.. Canopy scaling: -V\ :sub:`cmax25` and Canopy scaling +Canopy scaling -------------------------------------------- -The maximum rate of carboxylation at 25 :sup:`o`\ C varies with -foliage nitrogen concentration and specific leaf area and is calculated -as in Thornton and Zimmermann (2007). At 25ºC, - -.. math:: - :label: ZEqnNum217783 - - V_{c\max 25} =N_{a} F_{LNR} F_{NR} a_{R25} - -where :math:`N_{a}` is the area-based leaf nitrogen concentration (g N -m\ :sup:`-2` leaf area), :math:`F_{LNR}` is the fraction of leaf -nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N), -:math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass -to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and -:math:`a_{R25} =60` is the specific activity of Rubisco (µmol -CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`). -:math:`N_{a}` is calculated from mass-based leaf N concentration and -specific leaf area - -.. math:: - :label: ZEqnNum561340 - - N_{a} =\frac{1}{CN_{L} \; SLA_{0} } - -where :math:`CN_{L}` is the leaf carbon-to-nitrogen ratio (g C -g\ :sup:`-1` N) and :math:`SLA_{0}` is specific leaf area at the -canopy top ( m\ :sup:`2` leaf area g\ :sup:`-1` C ). Table 8.1 -lists values of :math:`F_{LNR}` , :math:`CN_{L}` , and :math:`SLA_{0}` -for each plant functional type. :math:`F_{LNR}` was chosen to give -:math:`V_{c\max 25}` consistent with Kattge et al. (2009), as discussed -by Bonan et al. (2011, 2012). Table 8.1 lists derived values for -:math:`V_{c\max 25}` at the top of the canopy using :math:`SLA_{0}` . -Tropical broadleaf evergreen trees are an exception, and a higher -:math:`V_{c\max 25}` is used to alleviate model biases (Bonan et al. -2012). - :math:`V_{c\max 25}` is calculated separately for sunlit and shaded leaves using an exponential profile to area-based leaf nitrogen -(:math:`N_{a}` ), as in Bonan et al. (2011). :math:`V_{c\max 25}` at +(:math:`LNC_{a}`, see Chapter :numref:`rst_Photosynthetic Capacity` ), +as in :ref:`Bonan et al. (2011)`. :math:`V_{c\max 25}` at cumulative leaf area index :math:`x` from the canopy top scales directly -with :math:`N_{a}` , which decreases exponentially with greater +with :math:`LNC_{a}` , which decreases exponentially with greater cumulative leaf area, so that .. math:: - :label: ZEqnNum745439 + :label: 9.17 V_{c\; \max 25}^{} \left(x\right)=V_{c\; \max 25}^{} \left(0\right)e^{-K_{n} x} where :math:`V_{c\; \max 25}^{} \left(0\right)` is defined at the top of -the canopy using :math:`SLA_{0}` , and :math:`K_{n}` is the decay +the canopy using :math:`SLA_{0}`, whic is the specific leaf area at +the canopy top and :math:`K_{n}` is the decay coefficient for nitrogen. The canopy integrated value for sunlit and shaded leaves is .. math:: - :label: 9.20) + :label: 9.20 \begin{array}{rcl} {V_{c\; \max 25}^{sun} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)f_{sun} \left(x\right)\, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} } \end{array} .. math:: - :label: 9.21) + :label: 9.21 \begin{array}{rcl} {V_{c\; \max 25}^{sha} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)\left[1-f_{sun} \left(x\right)\right] \, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left\{\left[1-e^{-K_{n} L} \right]\frac{1}{K_{n} } -\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} \right\}} \end{array} and the average value for the sunlit and shaded leaves is .. math:: - :label: 9.22) + :label: 9.22 \bar{V}_{c\; \max 25}^{sun} ={V_{c\; \max 25}^{sun} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sun} L^{sun} }} \right. \kern-\nulldelimiterspace} L^{sun} } .. math:: - :label: 9.23) + :label: 9.23 \bar{V}_{c\; \max 25}^{sha} ={V_{c\; \max 25}^{sha} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sha} L^{sha} }} \right. \kern-\nulldelimiterspace} L^{sha} } . @@ -474,39 +443,16 @@ extinction coefficient (equation 4.9). Photosynthetic parameters :math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}` , and :math:`R_{d25}` scale similarly. -The value :math:`K_{n} = 0.11` chosen by Bonan et al. (2011) is +The value :math:`K_{n} = 0.11` chosen by :ref:`Bonan et al. (2011)` is consistent with observationally-derived estimates for forests, mostly tropical, and provides a gradient in V\ :sub:`cmax` similar to -the original CLM4 specific leaf area scaling. However, Bonan et al. -(2012) showed that the sunlit/shaded canopy parameterization does not +the original CLM4 specific leaf area scaling. However, +:ref:`Bonan et al. (2012)` showed that the sunlit/shaded canopy parameterization does not match an explicit multi-layer canopy parameterization. The discrepancy arises from absorption of scattered radiation by shaded leaves and can be tuned out with higher :math:`K_{n}` . The model uses :math:`K_{n} =0.30` to match an explicit multi-layer canopy. -:math:`V_{c\max 25}` additionally varies with daylength (:math:`DYL`) -using the function :math:`f(DYL)`, which introduces seasonal variation -to :math:`V_{c\max }` - -.. math:: - :label: 9.24) - - f\left(DYL\right)=\frac{\left(DYL\right)^{2} }{\left(DYL_{\max } \right)^{2} } - -with :math:`0.01\le f\left(DYL\right)\le 1`. Daylength (seconds) is -given by - -.. math:: - :label: 9.25) - - DYL=2\times 13750.9871\cos ^{-1} \left[\frac{-\sin \left(lat\right)\sin \left(decl\right)}{\cos \left(lat\right)\cos \left(decl\right)} \right] - -where :math:`lat` (latitude) and :math:`decl` (declination angle) are -from section 3.3. Maximum daylength (:math:`DYL_{\max }` ) is calculated -similarly but using the maximum declination angle for present-day -orbital geometry (:math:`\pm`\ 23.4667º [:math:`\pm`\ 0.409571 radians], -positive for Northern Hemisphere latitudes and negative for Southern -Hemisphere). .. _Numerical implementation photosynthesis: @@ -516,29 +462,29 @@ Numerical implementation The CO\ :sub:`2` partial pressure at the leaf surface :math:`c_{s}` (Pa) and the vapor pressure at the leaf surface :math:`e_{s}` (Pa), needed for the stomatal resistance model in -equation , and the internal leaf CO\ :sub:`2` partial pressure -:math:`c_{i}` (Pa), needed for the photosynthesis model in equations -, +equation :eq:`9.1`, and the internal leaf CO\ :sub:`2` partial pressure +:math:`c_{i}` (Pa), needed for the photosynthesis model in equations :eq:`9.3`-:eq:`9.5`, are calculated assuming there is negligible capacity to store CO\ :sub:`2` and water vapor at the leaf surface so that .. math:: - :label: ZEqnNum581596 + :label: 9.31 A_{n} =\frac{c_{a} -c_{i} }{\left(1.4r_{b} +1.6r_{s} \right)P_{atm} } =\frac{c_{a} -c_{s} }{1.4r_{b} P_{atm} } =\frac{c_{s} -c_{i} }{1.6r_{s} P_{atm} } and the transpiration fluxes are related as .. math:: - :label: ZEqnNum323660 + :label: 9.32 \frac{e_{a} -e_{i} }{r_{b} +r_{s} } =\frac{e_{a} -e_{s} }{r_{b} } =\frac{e_{s} -e_{i} }{r_{s} } where :math:`r_{b}` is leaf boundary layer resistance (s -m\ :sup:`2` :math:`\mu` \ mol\ :sup:`-1`) (section 5.3), the +m\ :sup:`2` :math:`\mu` \ mol\ :sup:`-1`) (section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`), the terms 1.4 and 1.6 are the ratios of diffusivity of CO\ :sub:`2` to H\ :sub:`2`\ O for the leaf boundary layer resistance and stomatal resistance, -:math:`c_{a} ={\rm CO}_{{\rm 2}} \left({\rm mol\; mol}^{{\rm -1}} \right)P_{atm}` +:math:`c_{a} ={\rm CO}_{{\rm 2}} \left({\rm mol\; mol}^{{\rm -1}} \right)`, :math:`P_{atm}` is the atmospheric CO\ :sub:`2` partial pressure (Pa) calculated from CO\ :sub:`2` concentration (ppmv), :math:`e_{i}` is the saturation vapor pressure (Pa) evaluated at the leaf temperature @@ -547,31 +493,32 @@ The vapor pressure of air in the plant canopy :math:`e_{a}` (Pa) is determined from .. math:: - :label: 9.33) + :label: 9.33 e_{a} =\frac{P_{atm} q_{s} }{0.622} where :math:`q_{s}` is the specific humidity of canopy air (kg -kg\ :sup:`-1`) (section 5.3). Equations and are solved for +kg\ :sup:`-1`) (section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). +Equations and are solved for :math:`c_{s}` and :math:`e_{s}` .. math:: - :label: 9.34) + :label: 9.34 c_{s} =c_{a} -1.4r_{b} P_{atm} A_{n} .. math:: - :label: ZEqnNum123611 + :label: 9.35 e_{s} =\frac{e_{a} r_{s} +e_{i} r_{b} }{r_{b} +r_{s} } -Substitution of equation into equation gives an expression for stomatal +Substitution of equation :eq:`9.35` into equation :eq:`9.1` gives an expression for stomatal resistance (:math:`r_{s}` ) as a function of photosynthesis (:math:`A_{n}` ), given here in terms of conductance with :math:`g_{s} =1/r_{s}` and :math:`g_{b} =1/r_{b}` .. math:: - :label: 9.36) + :label: 9.36 c_{s} g_{s}^{2} +\left[c_{s} \left(g_{b} -b\right)-m{\it A}_{n} P_{atm} \right]g_{s} -g_{b} \left[c_{s} b+mA_{n} P_{atm} {e_{a} \mathord{\left/ {\vphantom {e_{a} e_{\*} \left(T_{v} \right)}} \right. \kern-\nulldelimiterspace} e_{\*} \left(T_{v} \right)} \right]=0. @@ -579,13 +526,13 @@ Stomatal conductance is the larger of the two roots that satisfy the quadratic equation. Values for :math:`c_{i}` are given by .. math:: - :label: 9.37) + :label: 9.37 c_{i} =c_{a} -\left(1.4r_{b} +1.6r_{s} \right)P_{atm} A{}_{n} The equations for :math:`c_{i}` , :math:`c_{s}` , :math:`r_{s}` , and :math:`A_{n}` are solved iteratively until :math:`c_{i}` converges. -Sun et al. (2012) pointed out that the CLM4 numerical approach does not +:ref:`Sun et al. (2012)` pointed out that the CLM4 numerical approach does not always converge. Therefore, the model uses a hybrid algorithm that combines the secant method and Brent’s method to solve for :math:`c_{i}` . The equation set is solved separately for sunlit @@ -593,19 +540,19 @@ combines the secant method and Brent’s method to solve for (:math:`A_{n}^{sha}` , :math:`r_{s}^{sha}` ) leaves. The model has an optional (though not supported) multi-layer canopy, as -described by Bonan et al. (2012). The multi-layer model is only intended +described by :ref:`Bonan et al. (2012)`. The multi-layer model is only intended to address the non-linearity of light profiles, photosynthesis, and stomatal conductance in the plant canopy. In the multi-layer canopy, sunlit (:math:`A_{n}^{sun}` , :math:`r_{s}^{sun}` ) and shaded (:math:`A_{n}^{sha}` , :math:`r_{s}^{sha}` ) leaves are explicitly -resolved at depths in the canopy using a light profile (Chapter 4). In +resolved at depths in the canopy using a light profile (Chapter :numref:`rst_Radiative Fluxes`). In this case, :math:`V_{c\max 25}` is not integrated over the canopy, but is instead given explicitly for each canopy layer using equation . This -also uses the Lloyd et al. (2010) relationship whereby +also uses the :ref:`Lloyd et al. (2010)` relationship whereby K\ :sub:`n` scales with V\ :sub:`cmax` as .. math:: - :label: 9.38) + :label: 9.38 K_{n} =\exp \left(0.00963V_{c\max } -2.43\right) diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index 0f24520566..704f0d4be5 100755 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -48,6 +48,9 @@ we do not differentiate the photosynthetic capacity difference for sun-lit or sh Model structure ---------------------------------------------------------- +Plant Nitrogen +'''''''''''''''''''''''''' + The structure of the LUNA model is adapted from Xu et al.(2012), where the plant nitrogen at the leaf level ( :math:`\text{LNC}_{a}`; gN/ m :sup:`2` leaf) is divided into four pools: structural nitrogen( :math:`N_{\text{str}}`; gN/m :sup:`2` leaf), photosynthetic nitrogen ( :math:`N_{\text{psn}}`; gN/ m:sup:`2` leaf), @@ -100,6 +103,9 @@ The gross photosynthesis, :math:`A`, was calculated with a coupled leaf gas exc photosynthesis and Ball--Berry-type stomatal conductance model (Ball et al., 1987). The maintenance respiration for photosynthetic enzymes, :math:`R_{\text{psn}}`, is calculated by the multiplication of total photosynthetic nitrogen ( :math:`N_{\text{psn}}` ) and the maintenance respiration cost for photosynthetic enzymes. +Maximum electron transport rate +'''''''''''''''''''''' + In the LUNA model, the maximum electron transport rate ( :math:`J_{\text{max}}`; :math:`{\mu} mol` electron / m :sup:`-2`/s) is simulated to have a baseline allocation of nitrogen and additional @@ -182,6 +188,52 @@ empirical expression of leaf (1937), where :math:`\text{PAR}_{\text{{max}}}` ( :math:`\mu mol`/m :sup:`2`/s) is the maximum photosynthetically active radiation during the day. +Maximum rate of carboxylation +''''''''''''''''' + +The maximum rate of carboxylation at 25 :sup:`o`\ C varies with +foliage nitrogen concentration and specific leaf area and is calculated +as in Thornton and Zimmermann (2007). At 25ºC, + +.. math:: + :label: 10.11) + + V_{c\max 25} =N_{str} N_{cb} F_{NR} a_{R25} + +where :math:`N_{str}` is the area-based leaf nitrogen concentration (g N +m\ :sup:`-2` leaf area), :math:`N_{cb}` is the fraction of leaf +nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N), +:math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass +to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and +:math:`a_{R25} =60` is the specific activity of Rubisco (µmol +CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`). + +:math:`V_{c\max 25}` additionally varies with daylength (:math:`DYL`) +using the function :math:`f(DYL)`, which introduces seasonal variation +to :math:`V_{c\max }` + +.. math:: + :label: 10.12) + + f\left(DYL\right)=\frac{\left(DYL\right)^{2} }{\left(DYL_{\max } \right)^{2} } + +with :math:`0.01\le f\left(DYL\right)\le 1`. Daylength (seconds) is +given by + +.. math:: + :label: 10.13) + + DYL=2\times 13750.9871\cos ^{-1} \left[\frac{-\sin \left(lat\right)\sin \left(decl\right)}{\cos \left(lat\right)\cos \left(decl\right)} \right] + +where :math:`lat` (latitude) and :math:`decl` (declination angle) are +from section :numref:`Solar Zenith Angle`. Maximum daylength (:math:`DYL_{\max }` ) is calculated +similarly but using the maximum declination angle for present-day +orbital geometry (:math:`\pm`\ 23.4667º [:math:`\pm`\ 0.409571 radians], +positive for Northern Hemisphere latitudes and negative for Southern +Hemisphere). + +Implementation of Photosynthetic Capacity +''''''''''''''''' Based on Farquhar et al. (1980) and Wullschleger (1993), we can calculate the electron-limited photosynthetic rate under daily maximum radiation ( :math:`W_{jx}`) @@ -189,12 +241,12 @@ and the Rubisco-limited photosynthetic rate ( :math:`W_{\mathrm{c}}`) as follows .. math:: - :label: 10.11) + :label: 10.14) W_{J_{x}} = K_{j}J_{x} , .. math:: - :label: 10.12) + :label: 10.15) W_{\mathrm{c}} = K_{\mathrm{c}} V_{{\mathrm{c}, \text{max}}}, @@ -207,7 +259,7 @@ assume that :math:`W_{\mathrm{c}}` is proportional to :math:`W_{J_{x}}`. Specifically, we have .. math:: - :label: 10.13) + :label: 10.16) W_{\mathrm{c}}=t_{\alpha}t_{\mathrm{c}, j0}W_{J_{x}} @@ -218,11 +270,14 @@ nitrogen use efficiency of carboxylation and electron transport (Ainsworth and R therefore the LUNA model has the modification factor, :math:`t_{\alpha}`, to adjust baseline the ratio depending on the nitrogen use efficiency for electron vs carboxylation (Ali et al 2016). +Total Respiration +''''''''''''''' + Following Collatz et al.(1991a), the total respiration ( :math:`R_{\mathrm{t}}`) is calculated in proportion to :math:`V_{\text{c,max}}`, .. math:: - :label: 10.14) + :label: 10.17) R_{\mathrm{t}} = 0.015 V_{\text{c,max}}. @@ -231,7 +286,7 @@ Accounting for the daytime and nighttime temperature, the daily respirations is .. math:: - :label: 10.15) + :label: 10.18) R_{\text{td}}={R}_{\mathrm{t}} [D_{\text{day}} + D_{\text{night}} f_{\mathrm{r}}{(T_{\text{night}})/f_{\mathrm{r}}{(T_{\text{day}})}}], @@ -253,4 +308,4 @@ by incrementally increase the nitrogen allocated for light capture (i.e., :math We assume that plants only optimize the nitrogen allocation when they can grow (i.e., GPP>0.0). If GPP become zero under stress, then the LUNA model assume a certain amount of enzyme will decay at daily rates of 0.1, in view that the half-life time for photosynthetic enzymes are short (~7 days) (Suzuki et al. 2001). -To avoid unrealistic low values of photosynthetic capacity, the decay is only limited to 50 percent of the original enzyme levels. \ No newline at end of file +To avoid unrealistic low values of photosynthetic capacity, the decay is only limited to 50 percent of the original enzyme levels. From b005a83568b118ea26a34e28c7f9d70a0e43eb29 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Thu, 27 Jul 2017 16:16:47 -0600 Subject: [PATCH 082/255] Updates to the stomatal conductance section of the photosynthesis chapter --- .../CLM50_Tech_Note_Photosynthesis.rst | 165 +++++++++--------- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 8 +- 2 files changed, 88 insertions(+), 85 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index cfe155d42a..163c476d08 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -16,8 +16,7 @@ CLM5 includes the following new changes to photosynthesis and stomatal conductan - :math:`J_{max}` is predicted by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) -- Leaf N concentration and the fraction of leaf N in Rubisco used to calculate -:math:`V_{cmax}` are determined by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) +- Leaf N concentration and the fraction of leaf N in Rubisco used to calculate :math:`V_{cmax25}` are determined by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) - Water stress is applied by the hydraulic conductance model (Chapter :numref:`rst_Plant Hydraulics`) @@ -43,54 +42,54 @@ where :math:`r_{b}` is the leaf boundary layer resistance (section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). The implementation is described by Bonan et al. (:ref:`2011 `), though different methods of calculating stomatal conductance, :math:`J_{max}`, and the nitrogen variables -used to calculate :math:`V_{cmax}` are used in CLM5. +used to calculate :math:`V_{cmax25}` are used in CLM5. .. _Stomatal resistance: Stomatal resistance ----------------------- -Leaf stomatal resistance is calculated from the Ball-Berry conductance -model as described by Collatz et al. (1991) and implemented in global -climate models (Sellers et al. 1996). The model relates stomatal -conductance (i.e., the inverse of resistance) to net leaf -photosynthesis, scaled by the relative humidity at the leaf surface and -the CO\ :sub:`1` concentration at the leaf surface. Leaf stomatal -resistance is +CLM5 calculates stomatal conductance using the Medlyn stomatal conductance model (:ref:`Medlyn et al. 2011`). +Previous versions of CLM calculated leaf stomatal resistance is using the Ball-Berry conductance +model as described by :ref:`Collatz et al. (1991)` and implemented in global +climate models (:ref:`Sellers et al. 1996`). The Medlyn model +calculates stomatal conductance (i.e., the inverse of resistance) based on net leaf +photosynthesis, the vapor pressure deficit, and the CO\ :sub:`2` concentration at the leaf surface. +Leaf stomatal resistance is: .. math:: :label: 9.1 - \frac{1}{r_{s} } =g_{s} =m\frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } } h_{s} +b\, \beta _{t} + \frac{1}{r_{s} } =g_{s} = g_{o} + (1 + \frac{g_{1} }{\sqrt{D}}) \frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } } where :math:`r_{s}` is leaf stomatal resistance (s m\ :sup:`2` -:math:`\mu`\ mol\ :sup:`-1`), :math:`m` is a plant functional -type dependent parameter (Table 8.1), :math:`A_{n}` is leaf net +:math:`\mu`\ mol\ :sup:`-1`), :math:`g_{o}` is the minimum stomatal conductance +(:math:`\mu` mol m :sup:`-2` s\ :sup:`-1`), :math:`A_{n}` is leaf net photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric -pressure (Pa), :math:`h_{s} =e_{s} /e_{i}` is the leaf surface humidity -with :math:`e_{s}` the vapor pressure at the leaf surface (Pa) and -:math:`e_{i}` the saturation vapor pressure (Pa) inside the leaf at the -vegetation temperature\ :math:`T_{v}`, and :math:`b` is the minimum -stomatal conductance (:math:`\mu` mol m :sup:`-2` -s\ :sup:`-1`). Parameter values are :math:`m=9` for -C\ :sub:`3` plants and :math:`m=4` for C\ :sub:`4` plants -(Collatz et al. 1991, 1992, Sellers et al. 1996). Sellers et al. (1996) -used :math:`b=10000` for C\ :sub:`3` plants and -:math:`b=40000` for C\ :sub:`4` plants, also used here. +pressure (Pa), and :math:`D` is the vapor pressure deficit at the leaf surface (Pa). +:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) photosynthetic parameters`) +and can be calculated as + +.. math:: + :label: 9.2 + + g_{1} = {\sqrt{\frac{3\Gamma*\lambda}{1.6}}} + +Parameter values are :math:`g_{o}=X` for +C\ :sub:`3` plants and :math:`g_{o}=4` for C\ :sub:`4` plants Photosynthesis is calculated for sunlit (:math:`A^{sun}`) and shaded (:math:`A^{sha}`) leaves to give :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}`. Additionally, soil water influences stomatal -resistance directly by multiplying the minimum conductance by a soil -water stress function :math:`\beta _{t}` (which ranges from 0 to 1) and -also indirectly through :math:`A_{n}`, as in (Sellers et al. 1996). +resistance through plant hydraulic stress, detailed in +the :ref:`rst_Plant Hydraulics` chapter. Resistance is converted from units of s m\ :sup:`2` :math:`\mu` mol\ :sub:`-1` to s m\ :sup:`-1` as: -1 s m\ sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` +1 s m\ :sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` :math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` -kmol\ :sup:`-1`) (Table 2.6) and :math:`\theta _{atm}` is the +kmol\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). .. _Table Plant functional type (PFT) photosynthetic parameters: @@ -160,13 +159,13 @@ Photosynthesis ------------------ Photosynthesis in C\ :sub:`3` plants is based on the model of -Farquhar et al. (1980). Photosynthesis in C\ :sub:`4` plants is -based on the model of Collatz et al. (1992). Bonan et al. (2011) +:ref:`Farquhar et al. (1980)`. Photosynthesis in C\ :sub:`4` plants is +based on the model of :ref:`Collatz et al. (1992)`. :ref:`Bonan et al. (2011)` describe the implementation, modified here. In its simplest form, leaf net photosynthesis after accounting for respiration (:math:`R_{d}` ) is .. math:: - :label: 9.2 + :label: 9.3 A_{n} =\min \left(A_{c} ,A_{j} ,A_{p} \right)-R_{d} . @@ -175,7 +174,7 @@ The RuBP carboxylase (Rubisco) limited rate of carboxylation s\ :sup:`-1`) is .. math:: - :label: 9.3 + :label: 9.4 A_{c} =\left\{\begin{array}{l} {\frac{V_{c\max } \left(c_{i} -\Gamma _{\*} \right)}{c_{i} +K_{c} \left(1+{o_{i} \mathord{\left/ {\vphantom {o_{i} K_{o} }} \right. \kern-\nulldelimiterspace} K_{o} } \right)} \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {V_{c\max } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. @@ -184,7 +183,7 @@ RuBP (i.e., the light-limited rate) :math:`A_{j}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 9.4 + :label: 9.5 A_{j} =\left\{\begin{array}{l} {\frac{J\left(c_{i} -\Gamma _{\*} \right)}{4c_{i} +8\Gamma _{\*} } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\alpha (4.6\phi )\qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. @@ -194,7 +193,7 @@ C\ :sub:`4` plants :math:`A_{p}` (:math:`\mu` \ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 9.5 + :label: 9.6 A_{p} =\left\{\begin{array}{l} {3T_{p\qquad } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {k_{p} \frac{c_{i} }{P_{atm} } \qquad \qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}. @@ -210,12 +209,12 @@ m\ :sup:`-2` s\ :sup:`-1`). :math:`T_{p}` is the triose phosphate utilization rate (µmol m\ :sup:`-2` s\ :sup:`-1`), taken as :math:`T_{p} =0.167V_{c\max }` so that :math:`A_{p} =0.5V_{c\max }` for C\ :sub:`3` plants (as in -Collatz et al. 1991). For C\ :sub:`4` plants, the light-limited +:ref:`Collatz et al. 1992 `). For C\ :sub:`4` plants, the light-limited rate :math:`A_{j}` varies with :math:`\phi` in relation to the quantum efficiency (:math:`\alpha =0.05` mol CO\ :sub:`2` mol\ :sup:`-1` photon). :math:`\phi` is the absorbed -photosynthetically active radiation (W m\ :sup:`-2`) (section -4.1), which is converted to photosynthetic photon flux assuming 4.6 +photosynthetically active radiation (W m\ :sup:`-2`) (section :numref:`Solar Fluxes`) +, which is converted to photosynthetic photon flux assuming 4.6 :math:`\mu` \ mol photons per joule. :math:`k_{p}` is the initial slope of C\ :sub:`4` CO\ :sub:`2` response curve. @@ -224,7 +223,7 @@ photosynthetically active radiation absorbed by the leaf. A common expression is the smaller of the two roots of the equation .. math:: - :label: 9.6 + :label: 9.7 \Theta _{PSII} J^{2} -\left(I_{PSII} +J_{\max } \right)J+I_{PSII} J_{\max } =0 @@ -239,7 +238,7 @@ with 4.6 :math:`\mu`\ mol J\ :sup:`-1`, the light utilized in electron transport is .. math:: - :label: 9.7 + :label: 9.8 I_{PSII} =0.5\Phi _{PSII} (4.6\phi ) @@ -251,12 +250,12 @@ calculating :math:`A_{j}` (for both C\ :sub:`3` and C\ :sub:`4` plants), :math:`\phi =\phi ^{sun}` for sunlit leaves and :math:`\phi =\phi ^{sha}` for shaded leaves. -The model uses co-limitation as described by Collatz et al. (1991, -1992). The actual gross photosynthesis rate, :math:`A`, is given by the +The model uses co-limitation as described by :ref:`Collatz et al. (1991, 1992) +`. The actual gross photosynthesis rate, :math:`A`, is given by the smaller root of the equations .. math:: - :label: 9.8 + :label: 9.9 \begin{array}{rcl} {\Theta _{cj} A_{i}^{2} -\left(A_{c} +A_{j} \right)A_{i} +A_{c} A_{j} } & {=} & {0} \\ {\Theta _{ip} A^{2} -\left(A_{i} +A_{p} \right)A+A_{i} A_{p} } & {=} & {0} \end{array} . @@ -265,57 +264,61 @@ C\ :sub:`3` plants; and :math:`\Theta _{cj} =0.80`\ and :math:`\Theta _{ip} =0.95` for C\ :sub:`4` plants. :math:`A_{n} =A-R_{d}` . -The parameters :math:`K_{c}`, :math:`K_{o}` , and :math:`\Gamma _{*}` +The parameters :math:`K_{c}`, :math:`K_{o}`, and :math:`\Gamma _{*}` depend on temperature. Values at 25 :sup:`o` \ C are -:math:`K_{c25} ={\rm 4}0{\rm 4}.{\rm 9}\times 10^{-6} P_{atm}` , -:math:`K_{o25} =278.4\times 10^{-3} P_{atm}` , and -:math:`\Gamma _{*25} {\rm =42}.75\times 10^{-6} P_{atm}` . -:math:`V_{c\max }` , :math:`J_{\max }` , :math:`T_{p}` , :math:`k_{p}` , -and :math:`R_{d}` also vary with temperature. Parameter values at 25 +:math:`K_{c25} ={\rm 4}0{\rm 4}.{\rm 9}\times 10^{-6} P_{atm}`, +:math:`K_{o25} =278.4\times 10^{-3} P_{atm}`, and +:math:`\Gamma _{*25} {\rm =42}.75\times 10^{-6} P_{atm}`. +:math:`V_{c\max }`, :math:`J_{\max }`, :math:`T_{p}`, :math:`k_{p}`, +and :math:`R_{d}` also vary with temperature. Parameter values at 25 :math:`\circ`\ C are calculated from :math:`V_{c\max }` \ at 25 -:math:`\circ`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}` , -:math:`T_{p25} =0.167V_{c\max 25}` , and -:math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`) and -:math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). For -C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}` . +:math:`\circ`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}`, +:math:`T_{p25} =0.167V_{c\max 25}`, and +:math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`) and +:math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). For +C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}`. However, when the biogeochemistry is active, :math:`R_{d25}` is -calculated from leaf nitrogen as :math:`R_{d25} =0.2577N_{a}` , where -:math:`N_{a}` is the area-based leaf nitrogen concentration (g N -m\ :sup:`-2` leaf area, equation ) and 0.2577 :math:`\mu`\ mol -CO\ :sub:`2` g\ :sup:`-1` N s\ :sup:`-1` the base -respiration rate. The parameters :math:`V_{c\max 25}` , -:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}` , and -:math:`R_{d25}` are scaled over the canopy for sunlit and shaded leaves -(section 8.3). In C3 plants, these are adjusted for leaf temperature -:math:`T_{v}` (K) as: +calculated from leaf nitrogen as :math:`R_{d25} = 0.2577LNC_{a}`, +where :math:`LNC_{a}` is the area-based leaf nitrogen concentration +(g N m\ :sup:`-2` leaf area, Chapter :numref:`rst_Photosynthetic Capacity`), +and 0.2577 :math:`\mu`\ mol CO\ :sub:`2` g\ :sup:`-1` N s\ :sup:`-1` is the base respiration rate. +The parameters :math:`V_{c\max 25}`, +:math:`J_{\max 25}`, :math:`T_{p25}`, :math:`k_{p25}`, and +:math:`R_{d25}` are scaled over the canopy for sunlit and shaded leaves +(section :numref:`Canopy scaling`). In C\ :sub:`3` plants, these are adjusted for leaf temperature, +:math:`T_{v}` (K), as: .. math:: - :label: 9.9 + :label: 9.10 \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma _{*} } & {=} & {\Gamma _{*25} \; f\left(T_{v} \right)} \end{array} with .. math:: - :label: 9.10 + :label: 9.11 f\left(T_{v} \right)=\; \exp \left[\frac{\Delta H_{a} }{298.15\times 0.001R_{gas} } \left(1-\frac{298.15}{T_{v} } \right)\right] and .. math:: - :label: 9.11 + :label: 9.12 f_{H} \left(T_{v} \right)=\frac{1+\exp \left(\frac{298.15\Delta S-\Delta H_{d} }{298.15\times 0.001R_{gas} } \right)}{1+\exp \left(\frac{\Delta ST_{v} -\Delta H_{d} }{0.001R_{gas} T_{v} } \right)} . -Table 8.2 list parameter values for :math:`\Delta H_{a}` , -:math:`\Delta H_{d}` , and :math:`\Delta S`, from Bonan et al. (2011). +:numref:`Table Temperature dependence parameters for C3 photosynthesis` +lists parameter values for :math:`\Delta H_{a}` , +:math:`\Delta H_{d}` , and :math:`\Delta S`, from :ref:`Bonan et al. (2011)`. +[Note: should we remove :math:`\Delta S` from the table below since we no longer use these? +Also, we should consider updating :math:`\Delta H_{a}` , +:math:`\Delta H_{d}` in this table] Because :math:`T_{p}` as implemented here varies with -:math:`V_{c\max }` , the same temperature parameters are used for -:math:`T_{p}` . For C\ :sub:`4` plants, +:math:`V_{c\max }` , :math:`T_{p}` uses the same temperature parameters as +:math:`V_{c\max}` . For C\ :sub:`4` plants, .. math:: - :label: 9.12 + :label: 9.13 \begin{array}{l} {V_{c\max } =V_{c\max 25} \left[\frac{Q_{10} ^{(T_{v} -298.15)/10} }{f_{H} \left(T_{v} \right)f_{L} \left(T_{v} \right)} \right]} \\ {f_{H} \left(T_{v} \right)=1+\exp \left[s_{1} \left(T_{v} -s_{2} \right)\right]} \\ {f_{L} \left(T_{v} \right)=1+\exp \left[s_{3} \left(s_{4} -T_{v} \right)\right]} \end{array} @@ -326,7 +329,7 @@ with :math:`Q_{10} =2`, Additionally, .. math:: - :label: 9.13 + :label: 9.14 R_{d} =R_{d25} \left\{\frac{Q_{10} ^{(T_{v} -298.15)/10} }{1+\exp \left[s_{5} \left(T_{v} -s_{6} \right)\right]} \right\} @@ -334,7 +337,7 @@ with :math:`Q_{10} =2`, :math:`s_{5} =1.3` K\ :sup:`-1` and :math:`s_{6} =328.15`\ K, and .. math:: - :label: 9.14 + :label: 9.15 k_{p} =k_{p25} \, Q_{10} ^{(T_{v} -298.15)/10} @@ -362,36 +365,36 @@ with :math:`Q_{10} =2`. | :math:`\Gamma _{\*}` | 37830 | – | – | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -The parameters in numref:`Table Temperature dependence parameters for C3 photosynthesis` +The parameters in :numref:`Table Temperature dependence parameters for C3 photosynthesis` do not allow for temperature acclimation of photosynthesis. In the model, acclimation is implemented as in :ref:`Kattge and Knorr (2007) `. In this parameterization, :math:`V_{c\max }` and :math:`J_{\max }` vary with the plant growth temperature. This is -achieved by allowing :math:`\Delta S`\ to vary with growth temperature +achieved by allowing :math:`\Delta S`\ to vary with growth temperature according to .. math:: - :label: 9.15 + :label: 9.16 \begin{array}{l} {\Delta S=668.39-1.07(T_{10} -T_{f} )\qquad \qquad {\rm for\; }V_{c\max } } \\ {\Delta S=659.70-0.75(T_{10} -T_{f} )\qquad \qquad {\rm for\; }J_{\max } } \end{array} The effect is to cause the temperature optimum of :math:`V_{c\max }` -and :math:`J_{\max }` to increase with warmer temperature. In this +and :math:`J_{\max }` to increase with warmer temperatures. In this parameterization, :math:`\Delta H_{d}` \ = 200000, :math:`\Delta H_{a}` \ = 72000 for :math:`V_{c\max }` , and :math:`\Delta H_{a}` \ = 50000 for :math:`J_{\max }` . Additionally, the ratio :math:`J_{\max 25} /V_{c\max 25}` at 25 :sup:`o`\ C decreases with growth temperature as .. math:: - :label: 9.16 + :label: 9.17 J_{\max 25} /V_{c\max 25} =2.59-0.035(T_{10} -T_{f} ). In these acclimation functions, :math:`T_{10}` is the 10-day mean air temperature (K) and :math:`T_{f}` is the freezing point of water (K). -For lack of data, :math:`T_{p}` acclimates similar to V :sub:`cmax` . Acclimation is restricted over the temperature +For lack of data, :math:`T_{p}` acclimates similar to :math:`V_{c\max }`. Acclimation is restricted over the temperature range :math:`T_{10} -T_{f} \ge 11`\ :sup:`o`\ C and :math:`T_{10} -T_{f} \le 35`\ :sup:`o`\ C. -.. Canopy scaling: +.. _Canopy scaling: Canopy scaling -------------------------------------------- @@ -405,7 +408,7 @@ with :math:`LNC_{a}` , which decreases exponentially with greater cumulative leaf area, so that .. math:: - :label: 9.17 + :label: 9.18 V_{c\; \max 25}^{} \left(x\right)=V_{c\; \max 25}^{} \left(0\right)e^{-K_{n} x} @@ -547,7 +550,7 @@ sunlit (:math:`A_{n}^{sun}` , :math:`r_{s}^{sun}` ) and shaded (:math:`A_{n}^{sha}` , :math:`r_{s}^{sha}` ) leaves are explicitly resolved at depths in the canopy using a light profile (Chapter :numref:`rst_Radiative Fluxes`). In this case, :math:`V_{c\max 25}` is not integrated over the canopy, but -is instead given explicitly for each canopy layer using equation . This +is instead given explicitly for each canopy layer using equation :eq:`9.18`. This also uses the :ref:`Lloyd et al. (2010)` relationship whereby K\ :sub:`n` scales with V\ :sub:`cmax` as diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index 704f0d4be5..0c99101fa0 100755 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -104,7 +104,7 @@ photosynthesis and Ball--Berry-type stomatal conductance model (Ball et al., 198 calculated by the multiplication of total photosynthetic nitrogen ( :math:`N_{\text{psn}}` ) and the maintenance respiration cost for photosynthetic enzymes. Maximum electron transport rate -'''''''''''''''''''''' +''''''''''''''''''''''''''''''''' In the LUNA model, the maximum electron transport rate ( :math:`J_{\text{max}}`; :math:`{\mu} mol` electron / m :sup:`-2`/s) @@ -189,7 +189,7 @@ where :math:`\text{PAR}_{\text{{max}}}` ( :math:`\mu mol`/m :sup:`2`/s) is the maximum photosynthetically active radiation during the day. Maximum rate of carboxylation -''''''''''''''''' +'''''''''''''''''''''''''''''' The maximum rate of carboxylation at 25 :sup:`o`\ C varies with foliage nitrogen concentration and specific leaf area and is calculated @@ -233,7 +233,7 @@ positive for Northern Hemisphere latitudes and negative for Southern Hemisphere). Implementation of Photosynthetic Capacity -''''''''''''''''' +'''''''''''''''''''''''''''''''''''''''''' Based on Farquhar et al. (1980) and Wullschleger (1993), we can calculate the electron-limited photosynthetic rate under daily maximum radiation ( :math:`W_{jx}`) @@ -271,7 +271,7 @@ therefore the LUNA model has the modification factor, :math:`t_{\alpha}`, to adj the ratio depending on the nitrogen use efficiency for electron vs carboxylation (Ali et al 2016). Total Respiration -''''''''''''''' +''''''''''''''''''' Following Collatz et al.(1991a), the total respiration ( :math:`R_{\mathrm{t}}`) is calculated in proportion to :math:`V_{\text{c,max}}`, From 073dddd8d41a0d07b0ae0ebcbfcfe97559268493 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Mon, 31 Jul 2017 17:40:28 -0600 Subject: [PATCH 083/255] Edited stomatal conductance section & updated the parameter table --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 2 +- .../CLM50_Tech_Note_Introduction.rst | 2 +- .../CLM50_Tech_Note_Photosynthesis.rst | 128 +++++++++--------- 3 files changed, 64 insertions(+), 68 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index d5f9b85560..10315b7d98 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -114,7 +114,7 @@ distribution parameters that control the uptake of water from the soil (:numref:`Table Plant functional type root distribution parameters`), aerodynamic parameters that determine resistance to heat, moisture, and momentum transfer (:numref:`Table Plant functional type aerodynamic parameters`), and photosynthetic parameters that determine stomatal resistance, photosynthesis, and -transpiration (:numref:`Table Plant functional type (PFT) photosynthetic parameters`, +transpiration (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`, :numref:`Table Temperature dependence parameters for C3 photosynthesis`). The composition and abundance of PFTs within a grid cell can either be prescribed as time-invariant fields (e.g., using the present day dataset described in section 21.3.3) or can diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 31ab7685d8..7c006efab7 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -123,7 +123,7 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table snow layer thickness` Minimum and maximum thickness of snow layers (m) -- :numref:`Table Plant functional type (PFT) photosynthetic parameters` Plant functional type (PFT) photosynthetic parameters. +- :numref:`Table Plant functional type (PFT) stomatal conductance parameters` Plant functional type (PFT) stomatal conductance parameters. - :numref:`Table Temperature dependence parameters for C3 photosynthesis` Temperature dependence parameters for C3 photosynthesis. diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index 163c476d08..a6cb6e987a 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -69,16 +69,20 @@ photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`D` is the vapor pressure deficit at the leaf surface (Pa). -:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) photosynthetic parameters`) +:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`) and can be calculated as .. math:: :label: 9.2 - g_{1} = {\sqrt{\frac{3\Gamma*\lambda}{1.6}}} + g_{1} = {\sqrt{\frac{3\Gamma\lambda}{1.6}}} -Parameter values are :math:`g_{o}=X` for -C\ :sub:`3` plants and :math:`g_{o}=4` for C\ :sub:`4` plants +where :math:`\Gamma` (mol mol\ :sup:`-1`) is the CO\ :sub:`2` compensation point +for photosynthesis without dark respiration and :math:`\lambda` +(mol H\ :sub:`2` O mol\ :sup:`-1`) is a parameter +describing the marginal water cost of carbon gain. +The value for :math:`g_{o}=100` :math:`\mu` mol m :sup:`-2` s\ :sup:`-1` for +C\ :sub:`3` and C\ :sub:`4` plants. Photosynthesis is calculated for sunlit (:math:`A^{sun}`) and shaded (:math:`A^{sha}`) leaves to give :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}`. Additionally, soil water influences stomatal @@ -86,72 +90,64 @@ resistance through plant hydraulic stress, detailed in the :ref:`rst_Plant Hydraulics` chapter. Resistance is converted from units of -s m\ :sup:`2` :math:`\mu` mol\ :sub:`-1` to s m\ :sup:`-1` as: +s m\ :sup:`2` :math:`\mu` mol\ :sup:`-1` to s m\ :sup:`-1` as: 1 s m\ :sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` -:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` +:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, [check units are correct here] +where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` kmol\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). -.. _Table Plant functional type (PFT) photosynthetic parameters: - -.. table:: Plant functional type (PFT) photosynthetic parameters. - - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | PFT | m | :math:`\alpha` | :math:`CN_{L}` | :math:`F_{LNR}` | :math:`SLA_{0}` | :math:`\psi _{o}` | :math:`\psi _{c}` | :math:`{V}_{cmax25}` | - +==================================+=====+====================+===================+====================+====================+======================+======================+===========================+ - | NET Temperate | 9 | – | 35 | 0.0509 | 0.010 | -66000 | -255000 | 62.5 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | NET Boreal | 9 | – | 40 | 0.0466 | 0.008 | -66000 | -255000 | 62.6 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | NDT Boreal | 9 | – | 25 | 0.0546 | 0.024 | -66000 | -255000 | 39.1 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BET Tropical | 9 | – | 30 | 0.0461 | 0.012 | -66000 | -255000 | 55.0 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BET temperate | 9 | – | 30 | 0.0515 | 0.012 | -66000 | -255000 | 61.5 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BDT tropical | 9 | – | 25 | 0.0716 | 0.030 | -35000 | -224000 | 41.0 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BDT temperate | 9 | – | 25 | 0.1007 | 0.030 | -35000 | -224000 | 57.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BDT boreal | 9 | – | 25 | 0.1007 | 0.030 | -35000 | -224000 | 57.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BES temperate | 9 | – | 30 | 0.0517 | 0.012 | -83000 | -428000 | 61.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BDS temperate | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | BDS boreal | 9 | – | 25 | 0.0943 | 0.030 | -83000 | -428000 | 54.0 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | C\ :sub:`3` arctic grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | C\ :sub:`3` grass | 9 | – | 25 | 0.1365 | 0.030 | -74000 | -275000 | 78.2 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | C\ :sub:`4` grass | 4 | 0.05 | 25 | 0.0900 | 0.030 | -74000 | -275000 | 51.6 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Crop R | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Crop I | 9 | – | 25 | 0.1758 | 0.030 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Corn R | 4 | 0.05 | 25 | 0.2930 | 0.050 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Corn I | 4 | 0.05 | 25 | 0.2930 | 0.050 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Temp Cereal R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Temp Cereal I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Winter Cereal R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Winter Cereal I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Soybean R | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - | Soybean I | 9 | – | 25 | 0.4102 | 0.070 | -74000 | -275000 | 100.7 | - +----------------------------------+-----+--------------------+-------------------+--------------------+--------------------+----------------------+----------------------+---------------------------+ - -:math:`\alpha` (mol CO\ :sub:`2` mol\ :sup:`-1` photon); -:math:`CN_{L}` (g C g\ :sup:`-1` N); :math:`F_{LNR}` (g N Rubisco g\ :sup:`-1` N); :math:`SLA_{0}` (m\ :sup:`2` g\ :sup:`-1` C); -:math:`\psi _{o}` and :math:`\psi _{c}` (mm); -V\ :sub:`cmax25` (:math:`\mu`\ mol m\ :sup:`-2` s\ :sup:`-1`, calculated from equation for canopy top). +.. _Table Plant functional type (PFT) stomatal conductance parameters: + +.. table:: Plant functional type (PFT) stomatal conductance parameters. + + +----------------------------------+-------------------+ + | PFT | g\ :sub:`1` (Pa) | + +==================================+===================+ + | NET Temperate | 2.35 | + +----------------------------------+-------------------+ + | NET Boreal | 2.35 | + +----------------------------------+-------------------+ + | NDT Boreal | 2.35 | + +----------------------------------+-------------------+ + | BET Tropical | 4.12 | + +----------------------------------+-------------------+ + | BET temperate | 4.12 | + +----------------------------------+-------------------+ + | BDT tropical | 4.45 | + +----------------------------------+-------------------+ + | BDT temperate | 4.45 | + +----------------------------------+-------------------+ + | BDT boreal | 4.45 | + +----------------------------------+-------------------+ + | BES temperate | 4.70 | + +----------------------------------+-------------------+ + | BDS temperate | 4.70 | + +----------------------------------+-------------------+ + | BDS boreal | 4.70 | + +----------------------------------+-------------------+ + | C\ :sub:`3` arctic grass | 2.22 | + +----------------------------------+-------------------+ + | C\ :sub:`3` grass | 5.25 | + +----------------------------------+-------------------+ + | C\ :sub:`4` grass | 1.62 | + +----------------------------------+-------------------+ + | Temperate Corn | 1.79 | + +----------------------------------+-------------------+ + | Spring Wheat | 5.79 | + +----------------------------------+-------------------+ + | Temperate Soybean | 5.79 | + +----------------------------------+-------------------+ + | Cotton | 5.79 | + +----------------------------------+-------------------+ + | Rice | 5.79 | + +----------------------------------+-------------------+ + | Sugarcane | 1.79 | + +----------------------------------+-------------------+ + | Tropical Corn | 1.79 | + +----------------------------------+-------------------+ + | Tropical Soybean | 5.79 | + +----------------------------------+-------------------+ .. _Photosynthesis: From 8bcfd46472b961a68f52ccbcb4822160469c595b Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Tue, 1 Aug 2017 17:38:32 -0600 Subject: [PATCH 084/255] Minor edits in the photosynthesis section --- .../CLM50_Tech_Note_Photosynthesis.rst | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index a6cb6e987a..b3d512121d 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -92,7 +92,7 @@ the :ref:`rst_Plant Hydraulics` chapter. Resistance is converted from units of s m\ :sup:`2` :math:`\mu` mol\ :sup:`-1` to s m\ :sup:`-1` as: 1 s m\ :sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` -:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, [check units are correct here] +:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, [same as 4.5, but seems off. check that units are correct] where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` kmol\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). @@ -181,7 +181,7 @@ CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 9.5 - A_{j} =\left\{\begin{array}{l} {\frac{J\left(c_{i} -\Gamma _{\*} \right)}{4c_{i} +8\Gamma _{\*} } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\alpha (4.6\phi )\qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. + A_{j} =\left\{\begin{array}{l} {\frac{J_{x}\left(c_{i} -\Gamma _{\*} \right)}{4c_{i} +8\Gamma _{\*} } \qquad \qquad {\rm for\; C}_{{\rm 3}} {\rm \; plants}} \\ {\alpha (4.6\phi )\qquad \qquad {\rm for\; C}_{{\rm 4}} {\rm \; plants}} \end{array}\right\}\qquad \qquad c_{i} -\Gamma _{\*} \ge 0. The product-limited rate of carboxylation for C\ :sub:`3` plants and the PEP carboxylase-limited rate of carboxylation for @@ -200,7 +200,8 @@ is the O\ :sub:`2` partial pressure (Pa). :math:`K_{c}` and CO\ :sub:`2` and O\ :sub:`2`. :math:`\Gamma _{\*}` (Pa) is the CO\ :sub:`2` compensation point. :math:`V_{c\max }` is the maximum rate of carboxylation (µmol m\ :sup:`-2` -s\ :sup:`-1`) and :math:`J` is the electron transport rate (µmol +s\ :sup:`-1`, Chapter :numref:`rst_Photosynthetic Capacity`) +and :math:`J_{x}` is the electron transport rate (µmol m\ :sup:`-2` s\ :sup:`-1`). :math:`T_{p}` is the triose phosphate utilization rate (µmol m\ :sup:`-2` s\ :sup:`-1`), taken as :math:`T_{p} =0.167V_{c\max }` so that @@ -221,14 +222,14 @@ expression is the smaller of the two roots of the equation .. math:: :label: 9.7 - \Theta _{PSII} J^{2} -\left(I_{PSII} +J_{\max } \right)J+I_{PSII} J_{\max } =0 + \Theta _{PSII} J_{x}^{2} -\left(I_{PSII} +J_{\max } \right)J_{x}+I_{PSII} J_{\max } =0 where :math:`J_{\max }` is the maximum potential rate of electron -transport (:math:`\mu`\ mol m\ :sup:`-2` s\ :sup:`-1`), +transport (:math:`\mu`\ mol m\ :sup:`-2` s\ :sup:`-1`, Chapter :numref:`rst_Photosynthetic Capacity`), :math:`I_{PSII}` is the light utilized in electron transport by photosystem II (µmol m\ :sup:`-2` s\ :sup:`-1`), and :math:`\Theta _{PSII}` is a curvature parameter. For a given amount of -photosynthetically active radiation absorbed by a leaf :math:`\phi` (W +photosynthetically active radiation absorbed by a leaf (:math:`\phi`, W m\ :sup:`-2`), converted to photosynthetic photon flux density with 4.6 :math:`\mu`\ mol J\ :sup:`-1`, the light utilized in electron transport is @@ -258,17 +259,18 @@ smaller root of the equations Values are :math:`\Theta _{cj} =0.98` and :math:`\Theta _{ip} =0.95` for C\ :sub:`3` plants; and :math:`\Theta _{cj} =0.80`\ and :math:`\Theta _{ip} =0.95` for C\ :sub:`4` plants. +:math:`A_{i}` is the intermediate co-limited photosynthesis. :math:`A_{n} =A-R_{d}` . -The parameters :math:`K_{c}`, :math:`K_{o}`, and :math:`\Gamma _{*}` +The parameters :math:`K_{c}`, :math:`K_{o}`, and :math:`\Gamma` depend on temperature. Values at 25 :sup:`o` \ C are :math:`K_{c25} ={\rm 4}0{\rm 4}.{\rm 9}\times 10^{-6} P_{atm}`, :math:`K_{o25} =278.4\times 10^{-3} P_{atm}`, and -:math:`\Gamma _{*25} {\rm =42}.75\times 10^{-6} P_{atm}`. +:math:`\Gamma _{25} {\rm =42}.75\times 10^{-6} P_{atm}`. :math:`V_{c\max }`, :math:`J_{\max }`, :math:`T_{p}`, :math:`k_{p}`, and :math:`R_{d}` also vary with temperature. Parameter values at 25 -:math:`\circ`\ C are calculated from :math:`V_{c\max }` \ at 25 -:math:`\circ`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}`, +:sup:`o`\ C are calculated from :math:`V_{c\max }` \ at 25 +:sup:`\o`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}`, :math:`T_{p25} =0.167V_{c\max 25}`, and :math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`) and :math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). For @@ -278,6 +280,7 @@ calculated from leaf nitrogen as :math:`R_{d25} = 0.2577LNC_{a}`, where :math:`LNC_{a}` is the area-based leaf nitrogen concentration (g N m\ :sup:`-2` leaf area, Chapter :numref:`rst_Photosynthetic Capacity`), and 0.2577 :math:`\mu`\ mol CO\ :sub:`2` g\ :sup:`-1` N s\ :sup:`-1` is the base respiration rate. +[this doesn't look correct based on the code, which lists two options; verify with Rosie] The parameters :math:`V_{c\max 25}`, :math:`J_{\max 25}`, :math:`T_{p25}`, :math:`k_{p25}`, and :math:`R_{d25}` are scaled over the canopy for sunlit and shaded leaves @@ -287,7 +290,7 @@ The parameters :math:`V_{c\max 25}`, .. math:: :label: 9.10 - \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma _{*} } & {=} & {\Gamma _{*25} \; f\left(T_{v} \right)} \end{array} + \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma } & {=} & {\Gamma _{25} \; f\left(T_{v} \right)} \end{array} with @@ -306,9 +309,6 @@ and :numref:`Table Temperature dependence parameters for C3 photosynthesis` lists parameter values for :math:`\Delta H_{a}` , :math:`\Delta H_{d}` , and :math:`\Delta S`, from :ref:`Bonan et al. (2011)`. -[Note: should we remove :math:`\Delta S` from the table below since we no longer use these? -Also, we should consider updating :math:`\Delta H_{a}` , -:math:`\Delta H_{d}` in this table] Because :math:`T_{p}` as implemented here varies with :math:`V_{c\max }` , :math:`T_{p}` uses the same temperature parameters as :math:`V_{c\max}` . For C\ :sub:`4` plants, @@ -346,11 +346,11 @@ with :math:`Q_{10} =2`. +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ | Parameter | :math:`\Delta H_{a}` (J mol\ :sup:`-1`) | :math:`\Delta H_{d}` (J mol\ :sup:`-1`) | :math:`\Delta S` (J mol\ :sup:`-1` K\ :sup:`-1`) | +========================+=================================================================+=================================================================+==============================================================================================+ - | :math:`V_{c\max }` | 65330 | 149250 | 485 | + | :math:`V_{c\max }` | 72000 | 200000 | 485 | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`J_{\max }` | 43540 | 152040 | 495 | + | :math:`J_{\max }` | 50000 | 152040 | 495 | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`T_{p}` | 65330 | 149250 | 485 | + | :math:`T_{p}` | 72000 | 149250 | 485 | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ | :math:`R_{d}` | 46390 | 150650 | 490 | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ @@ -361,6 +361,8 @@ with :math:`Q_{10} =2`. | :math:`\Gamma _{\*}` | 37830 | – | – | +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +[Note: updated the Vcmax :math:`\Delta H_{a}` and :math:`\Delta H_{d}` +and the Jmax :math:`\Delta H_{a}` based on acclimation values. All other values are the same as previous] The parameters in :numref:`Table Temperature dependence parameters for C3 photosynthesis` do not allow for temperature acclimation of photosynthesis. In the model, acclimation is implemented as in :ref:`Kattge and Knorr (2007) `. In this parameterization, @@ -374,10 +376,8 @@ according to \begin{array}{l} {\Delta S=668.39-1.07(T_{10} -T_{f} )\qquad \qquad {\rm for\; }V_{c\max } } \\ {\Delta S=659.70-0.75(T_{10} -T_{f} )\qquad \qquad {\rm for\; }J_{\max } } \end{array} The effect is to cause the temperature optimum of :math:`V_{c\max }` -and :math:`J_{\max }` to increase with warmer temperatures. In this -parameterization, :math:`\Delta H_{d}` \ = 200000, -:math:`\Delta H_{a}` \ = 72000 for :math:`V_{c\max }` , and -:math:`\Delta H_{a}` \ = 50000 for :math:`J_{\max }` . Additionally, the +and :math:`J_{\max }` to increase with warmer temperatures. +Additionally, the ratio :math:`J_{\max 25} /V_{c\max 25}` at 25 :sup:`o`\ C decreases with growth temperature as .. math:: From e3bb7122a6bf1b91e491675f3f11e7afb3fc4045 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Wed, 2 Aug 2017 13:32:49 -0600 Subject: [PATCH 085/255] More edits on photosynthesis, canopy scaling, and numerical implementation sections of photosynthesis chapter --- .../CLM50_Tech_Note_Photosynthesis.rst | 73 ++++++++++--------- .../References/CLM50_Tech_Note_References.rst | 6 ++ 2 files changed, 44 insertions(+), 35 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index b3d512121d..b8e443f10a 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -78,7 +78,8 @@ and can be calculated as g_{1} = {\sqrt{\frac{3\Gamma\lambda}{1.6}}} where :math:`\Gamma` (mol mol\ :sup:`-1`) is the CO\ :sub:`2` compensation point -for photosynthesis without dark respiration and :math:`\lambda` +for photosynthesis without dark respiration, +1.6 is the ratio of diffusivity of CO\ :sub:`2` to H\ :sub:`2` O and :math:`\lambda` (mol H\ :sub:`2` O mol\ :sup:`-1`) is a parameter describing the marginal water cost of carbon gain. The value for :math:`g_{o}=100` :math:`\mu` mol m :sup:`-2` s\ :sup:`-1` for @@ -92,7 +93,7 @@ the :ref:`rst_Plant Hydraulics` chapter. Resistance is converted from units of s m\ :sup:`2` :math:`\mu` mol\ :sup:`-1` to s m\ :sup:`-1` as: 1 s m\ :sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` -:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, [same as 4.5, but seems off. check that units are correct] +:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, [same as 4.5, but units seem off. check that units are correct] where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` kmol\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). @@ -307,8 +308,12 @@ and f_{H} \left(T_{v} \right)=\frac{1+\exp \left(\frac{298.15\Delta S-\Delta H_{d} }{298.15\times 0.001R_{gas} } \right)}{1+\exp \left(\frac{\Delta ST_{v} -\Delta H_{d} }{0.001R_{gas} T_{v} } \right)} . :numref:`Table Temperature dependence parameters for C3 photosynthesis` -lists parameter values for :math:`\Delta H_{a}` , -:math:`\Delta H_{d}` , and :math:`\Delta S`, from :ref:`Bonan et al. (2011)`. +lists parameter values for :math:`\Delta H_{a}` and +:math:`\Delta H_{d}` . :math:`\Delta S` is calculated +separately for :math:`V_{c\max }` and :math:`J_{max }` +to allow for temperature acclimation of photosynthesis (see equation :eq:`9.16`), +and :math:`\Delta S` is 490 J mol :sup:`-1` K :sup:`-1` for :math:`R_d` +(:ref:`Bonan et al. 2011`, :ref:`Lombardozzi et al. 2015`). Because :math:`T_{p}` as implemented here varies with :math:`V_{c\max }` , :math:`T_{p}` uses the same temperature parameters as :math:`V_{c\max}` . For C\ :sub:`4` plants, @@ -343,28 +348,25 @@ with :math:`Q_{10} =2`. .. table:: Temperature dependence parameters for C3 photosynthesis. - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | Parameter | :math:`\Delta H_{a}` (J mol\ :sup:`-1`) | :math:`\Delta H_{d}` (J mol\ :sup:`-1`) | :math:`\Delta S` (J mol\ :sup:`-1` K\ :sup:`-1`) | - +========================+=================================================================+=================================================================+==============================================================================================+ - | :math:`V_{c\max }` | 72000 | 200000 | 485 | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`J_{\max }` | 50000 | 152040 | 495 | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`T_{p}` | 72000 | 149250 | 485 | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`R_{d}` | 46390 | 150650 | 490 | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`K_{c}` | 79430 | – | – | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`K_{o}` | 36380 | – | – | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - | :math:`\Gamma _{\*}` | 37830 | – | – | - +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - -[Note: updated the Vcmax :math:`\Delta H_{a}` and :math:`\Delta H_{d}` -and the Jmax :math:`\Delta H_{a}` based on acclimation values. All other values are the same as previous] -The parameters in :numref:`Table Temperature dependence parameters for C3 photosynthesis` -do not allow for temperature acclimation of photosynthesis. In the model, acclimation is + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | Parameter | :math:`\Delta H_{a}` (J mol\ :sup:`-1`) | :math:`\Delta H_{d}` (J mol\ :sup:`-1`) | + +========================+=================================================================+=================================================================+ + | :math:`V_{c\max }` | 72000 | 200000 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | :math:`J_{\max }` | 50000 | 200000 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | :math:`T_{p}` | 72000 | 200000 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | :math:`R_{d}` | 46390 | 150650 | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | :math:`K_{c}` | 79430 | – | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | :math:`K_{o}` | 36380 | – | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + | :math:`\Gamma _{\*}` | 37830 | – | + +------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ + +In the model, acclimation is implemented as in :ref:`Kattge and Knorr (2007) `. In this parameterization, :math:`V_{c\max }` and :math:`J_{\max }` vary with the plant growth temperature. This is achieved by allowing :math:`\Delta S`\ to vary with growth temperature @@ -401,7 +403,7 @@ leaves using an exponential profile to area-based leaf nitrogen as in :ref:`Bonan et al. (2011)`. :math:`V_{c\max 25}` at cumulative leaf area index :math:`x` from the canopy top scales directly with :math:`LNC_{a}` , which decreases exponentially with greater -cumulative leaf area, so that +cumulative leaf area, so that [Verify with Rosie- different based on Vcmax option 0, 3, & 4] .. math:: :label: 9.18 @@ -409,7 +411,7 @@ cumulative leaf area, so that V_{c\; \max 25}^{} \left(x\right)=V_{c\; \max 25}^{} \left(0\right)e^{-K_{n} x} where :math:`V_{c\; \max 25}^{} \left(0\right)` is defined at the top of -the canopy using :math:`SLA_{0}`, whic is the specific leaf area at +the canopy using :math:`SLA_{0}`, which is the specific leaf area at the canopy top and :math:`K_{n}` is the decay coefficient for nitrogen. The canopy integrated value for sunlit and shaded leaves is @@ -438,10 +440,12 @@ and the average value for the sunlit and shaded leaves is This integration is over all leaf area (:math:`L`) with :math:`f_{sun} (x)=\exp \left(-Kx\right)` and :math:`K` the direct beam -extinction coefficient (equation 4.9). Photosynthetic parameters -:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}` , and +extinction coefficient (equation :eq:`4.8` in chapter :numref:`rst_Radiative Fluxes`). Photosynthetic parameters +:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}`, and :math:`R_{d25}` scale similarly. +The model uses :math:`K_{n} =0.30` to match an explicit multi-layer canopy, as in +:ref:`Bonan et al. (2012)`. The value :math:`K_{n} = 0.11` chosen by :ref:`Bonan et al. (2011)` is consistent with observationally-derived estimates for forests, mostly tropical, and provides a gradient in V\ :sub:`cmax` similar to @@ -449,8 +453,7 @@ the original CLM4 specific leaf area scaling. However, :ref:`Bonan et al. (2012)` showed that the sunlit/shaded canopy parameterization does not match an explicit multi-layer canopy parameterization. The discrepancy arises from absorption of scattered radiation by shaded leaves and can -be tuned out with higher :math:`K_{n}` . The model uses -:math:`K_{n} =0.30` to match an explicit multi-layer canopy. +be tuned out with higher :math:`K_{n}`. .. _Numerical implementation photosynthesis: @@ -458,8 +461,8 @@ be tuned out with higher :math:`K_{n}` . The model uses Numerical implementation ---------------------------- -The CO\ :sub:`2` partial pressure at the leaf surface -:math:`c_{s}` (Pa) and the vapor pressure at the leaf surface +The CO\ :sub:`2` partial pressure at the leaf surface, +:math:`c_{s}` (Pa), and the vapor pressure at the leaf surface, :math:`e_{s}` (Pa), needed for the stomatal resistance model in equation :eq:`9.1`, and the internal leaf CO\ :sub:`2` partial pressure :math:`c_{i}` (Pa), needed for the photosynthesis model in equations :eq:`9.3`-:eq:`9.5`, @@ -497,7 +500,7 @@ determined from e_{a} =\frac{P_{atm} q_{s} }{0.622} where :math:`q_{s}` is the specific humidity of canopy air (kg -kg\ :sup:`-1`) (section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). +kg\ :sup:`-1`, section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). Equations and are solved for :math:`c_{s}` and :math:`e_{s}` diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 97e221f702..eb5a00c9c8 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1133,6 +1133,12 @@ Lobell, D.B., Bala, G., and Duffy, P.B. 2006. Biogeophysical impacts of cropland management changes on climate. Geophys. Res. Lett. 33:L06708. DOI:10.1029/2005GL025492. +.. _Lombardozzietal2015: + +Lombardozzi, D.L., Bonan, G.B., Smith, N.G., Dukes, J.S. 2015. Temperature +acclimation of photosynthesis and respiration: A key uncertainty in the +carbon cycle-climate feedback. Geophys. Res. Lett. 42:8624-8631. + .. _Lovelandetal2000: Loveland, T.R., Reed, B.C., Brown, J.F., Ohlen, D.O., Zhu, Z., Yang, L., From 1f01fcbd8936d392589748cf4d93e1e694bd14b6 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Wed, 2 Aug 2017 13:54:12 -0600 Subject: [PATCH 086/255] Updated the crop chapter to reflect the new changes in leaf angle distribution --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 85c284cd89..fb6a180edd 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -363,7 +363,7 @@ Harvest occurs in one time step using the BGC leaf offset algorithm. Harvest: days past planting :math:`\mathrm{\le}`\ 165 :math:`\mathrm{\le}`\ 150 :math:`\mathrm{\le}`\ 150 :math:`\mathrm{\le}`\ 160 :math:`\mathrm{\le}`\ 150 :math:`\mathrm{\le}`\ 300 :math:`\mathrm{\le}`\ 160 :math:`\mathrm{\le}`\ 150 :math:`z_{top}^{\max }` (m) 2.5 1.2 0.75 1.5 1.8 4 2.5 1 SLA (m :sup:`2` leaf g :sup:`-1` C) 0.05 0.035 0.035 0.035 0.035 0.05 0.05 0.035 - :math:`\chi _{L}` index -0.5 0.65 -0.5 -0.5 0.65 -0.5 -0.5 -0.5 + :math:`\chi _{L}` index -0.5 -0.5 -0.5 -0.5 -0.5 -0.5 -0.5 -0.5 grperc 0.11 0.11 0.11 0.11 0.11 0.11 0.11 0.11 flnr 0.293 0.41 0.41 0.41 0.41 0.293 0.293 0.41 fcur 1 1 1 1 1 1 1 1 From 172db34303856a407a5996159385e0ca26ef8970 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 16 Aug 2017 13:22:53 -0600 Subject: [PATCH 087/255] removed bsoil from fluxes chapter --- doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst | 6 ++---- doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 0ffe6e43f3..04d0a6a83c 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1052,7 +1052,7 @@ where .. math:: :label: 5.103 - E_{soil} = -\rho _{atm} \frac{\beta _{soi} \left(q_{s} -q_{soil} \right)}{r_{aw} ^{{'} } +r_{soil} } + E_{soil} = -\rho _{atm} \frac{\left(q_{s} -q_{soil} \right)}{r_{aw} ^{{'} } +r_{soil} } .. math:: :label: 5.104 @@ -1072,9 +1072,7 @@ at the vegetation temperature (section :numref:`Saturation Vapor Pressure`), :ma of the soil, snow, and surface water (section :numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`), :math:`r_{aw} ^{{'} }` is the aerodynamic resistance (s m\ :sup:`-1`) to water vapor transfer between the ground at height -:math:`z_{0w} ^{{'} }` and the canopy air at height :math:`z_{0w} +d`, -:math:`\beta _{soi}` is an empirical function of soil water (section -:numref:`Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces`), +:math:`z_{0w} ^{{'} }` and the canopy air at height :math:`z_{0w} +d`, and :math:`r_{soil}` (:eq:`5.76`) is a resistance to diffusion through the soil (s m\ :sup:`-1`). :math:`r_{total}` is the total resistance to water vapor transfer from the canopy to the canopy air and includes diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index 24df209f08..b844b4a433 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -53,8 +53,8 @@ and discharges the water to its downstream spatial unit or the ocean. MOSART only route positive runoff, although negative runoff could be generated occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any runoff component including :math:`q_{sur}`, :math:`q_{sub}`, :math:`q_{gwl}` -is mapped directly from the spatial unit where it is generated at any time step to -the basin outlet of the corresponding spatial unit. +is not routed through MOSART, but instead is mapped directly from the spatial unit +where it is generated at any time step to the coupler. In MOSART, the travel velocities of water across hillslopes, sub-network and main channel are all estimated using the Manning’s equation with different levels of From 24bf0b52d6daa04745dbc235a327c76e39468744 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Fri, 18 Aug 2017 10:50:24 -0600 Subject: [PATCH 088/255] Updates to Introduction, very minor updates to BVOCs, and some references added --- .../tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst | 4 +- .../CLM50_Tech_Note_Introduction.rst | 94 +++++++++++-------- .../References/CLM50_Tech_Note_References.rst | 38 +++++++- 3 files changed, 96 insertions(+), 40 deletions(-) diff --git a/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst b/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst index 8c5737f171..433f26d97d 100644 --- a/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst +++ b/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst @@ -7,7 +7,7 @@ This chapter briefly describes the biogenic volatile organic compound (BVOC) emissions model implemented in CLM. The CLM3 version (Levis et al. 2003; Oleson et al. 2004) was based on Guenther et al. (1995). Heald et al. (2008) updated this scheme in CLM4 based on Guenther et al. -(2006). The current version in CLM4.5 is based on MEGAN2.1 discussed in +(2006). The current version was implemented in CLM4.5 and is based on MEGAN2.1 discussed in detail in Guenther et al. (2012). This update of MEGAN incorporates four main features: expansion to 147 chemical compounds the treatment of the light-dependent fraction (LDF) for each compound inclusion of the @@ -58,6 +58,6 @@ where the LDF activity factor (:math:`\gamma _{P\_ LDF}` ) is specified as a function of PAR as in previous versions of MEGAN. The values for each emission factor :math:`\epsilon _{i,\, j}` are -now available for each of the 15 plant functional types in the CLM and +now available for each of the plant functional types in the CLM and each chemical compound. This information is distributed through an external file, allowing for more frequent and easier updates. diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 31ab7685d8..2c9abf86cc 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -11,12 +11,12 @@ ***Lead Authors*** -**Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Peter J. Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William J. Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu** +**Gordon Bonan, Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Peter J. Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William J. Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu** ***Contributing Authors*** -**Ben Andre, Ali Ashehad, Gautam Bisht, Gordon Bonan, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, -L. Ruby Leung, William Lipscomb, Daniel M. Ricciuto, Ben Sanderson, Andrew Slater, Zachary M. Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** +**Ben Andre, Ali Ashehad, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, +L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Andrew Slater, Zachary M. Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** The National Center for Atmospheric Research (NCAR) is operated by the @@ -176,21 +176,6 @@ Koichi Sakaguchi, Adam Schlosser, Andrew Slater, Reto Stöckli, Ying Sun, Quinn Thomas, Peter Thornton, Mariana Vertenstein, Nicholas Viovy, Aihui Wang, Guiling Wang, Charlie Zender, Xiaodong Zeng, and Xubin Zeng. - - -Current affiliations for the authors are as follows: - -K.W. Oleson, D.M. Lawrence, G.B. Bonan, S.C. Swenson, R. -Fisher, E. Kluzek, P.J. Lawrence, W. Sacks and M. Vertenstein (National Center for Atmospheric Research); B. Drewniak (Argonne -National Laboratory); M. Huang, L.R. Leung (Pacific Northwest National -Laboratory); C.D. Koven, W.J. Riley, and J. Tang (Lawrence Berkeley -National Laboratory); F. Li (Chinese Academy of Sciences); Z.M. Subin -(Princeton University); P.E. Thornton and D.M. Ricciuto (Oak Ridge -National Laboratory); A. Bozbiyik (Bern University); C. Heald -(Massachusetts Institute of Technology), W. Lipscomb (Los Alamos -National Laboratory); Ying Sun and Z.-L. Yang (University of Texas at -Austin) - .. _rst_Introduction: Introduction @@ -520,17 +505,55 @@ Community Earth System Model version 1.2 (CESM1.2). CLM5.0 ^^^^^^^^^^^^ -Developments for CLM5.0 build on the progress made in CLM4.5. Much of the focus of development centered on a -push towards more mechanistic treatment of several key processes, in addition to more comprehensive and explicit representation -of land use and land-cover change. In particular, - -To represent … Stomatal conductance is a function of prognostic (predicted) leaf water potential. LWP is the result of atmospheric demand and supply from soil via resistance network. - -Dynamic land units. - -Included within the codebase of the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, -reference Fisher???). This version of CLM5-FATES that is supported in this release is described here??? Short blurb on what FATES can do??? - +Developments for CLM5.0 build on the progress made in CLM4.5. Most major components of the model have been udpated with particularly +notable changes made to soil and plant hydrology, snow density, river modeling, carbon and nitrogen cycling and coupling, +and crop modeling. +Much of the focus of development centered on a +push towards more mechanistic treatment of key processes, in addition to more comprehensive and explicit representation +of land use and land-cover change. Prior versions of CLM included relatively few options for physics parameterizations or structure. +In CLM5, where new parameterizations or model decisions were made, in most cases, the CLM4.5 parameterization was maintained so that users could switch back and forth between different parameterizations via namelist control where appropriate or desirable. Throughout the CLM5 Technical Descpription, in general only the default parameterization for any given process is described. Readers are referred to the CLM4.5 or CLM4 Technical Descriptions for detailed descriptions of non-default parameterizations. + +The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. + +Several changes are included that are mainly targeted at improving the simulation of surface mass balance over ice +sheets. The fresh snow density parameterization is updated to more realistically capture the temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is active for Greenland by default with one-way coupling (surface mass balance impacts ice sheet dynamics, but ice sheet dynamics do not feedback onto surface elevation). Two-way coupling can be activated through a namelist switch. The introduction in CLM5 of the capability to +dynamically adjust landunit weights means that a glacier can initiate, grow, shrink, or disappear during +a simulation when two-way coupling is active. Multiple elevation classes (10 elevation classes by default) and associated temperature, rain/snow partitioning, and downwelling longwave downscaling are used for glacier landunits to account for the strong topographic elevation heterogeneity over glaciers and ice sheets. + +A plant hydraulic stress routine is introduced which explicitly models water transport through the vegetation according to a simple hydraulic framework (Kennedy et al., to be submitted). The water supply equations are used to solve for vegetation water potential forced by transpiration demand and a set of layer-by-layer soil water potentials. Stomatal conductance, therefore, is a function of prognostic leaf water potential. Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. An emergent feature of the plant hydraulics is soil hydraulic redistribution. In CLM5, maximum stomatal conductance is obtained from the Medlyn conductance model :ref:(Medlyn et al., 2011)`, rather than the Ball-Berry stomatal conductance model that was utilized in CLM4.5 and prior versions of the model. The Medlyn stomatal conductance model is preferred mainly for it's more realistic behavior at low humidity levels :ref:`(Rogers et al., 2017)`. The stress deciduous vegetation phenology trigger is augmented with a antecedent precipitation requirement :ref:`(Dahlin et al. 2015)`. + +Plant nutrient dynamics are substantially updated to resolve several deficiencies with the CLM4 and CLM4.5 nutrient cycling representation. The Fixation and Update of Nitrogen (FUN) model (refs???) is adapted for CLM :ref:`(Shi et al., 2016)` to resolve the +unrealistic feature that plants get nitrogen for free in CLM4 and CLM4.5. With FUN, the fact that plants typically spend a +significant fraction of their available carbon on nutrient aquisition is acounted for. The static plant carbon:nitrogen (C:N) ratios utilized in CLM4 and CLM4.5 are replaced with variable plant C:N ratios which +allows plants to adjust their C:N ratio, and therefore their leaf nitrogen content, with the cost of N uptake :ref:`(Ghimire et al. 2016)`. +The implementation of a flexible C:N ratio means that the model no longer relies on instantaneous downregulation +of potential photosynthesis rates based on soil mineral nitrogen availability to represent nutrient limitation. Furthermore, stomatal conductance +is now based on the N-limited photosynthesis rather than on potential photosynthesis. Finally, the Leaf Use of +Nitrogen for Assimilation (LUNA, :ref:`(Xu et al., 2012` and :ref:`Ali et al., 2016)` model is incorporated. The LUNA model calculates +photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that +light capture, carboxylation, and respiration are co-limiting. Allocation changes ... Fixation ??? + +Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. +Fertilization rates and irrigation equipped area updated based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that +vary by latitude for selected crop types, grain C and N is now removed at harvest to a 1-year product pool with +the carbon for the next season's crop seed removed from the grain carbon at harvest. Through the introduction of +the capability to dynamically adjust landunit weights during a simulation, the crop model can now be run coincidentally +with prescribed land use, which significantly expands the capabilities of the model. Mass-based rather than area-based wood harvest is applied. Several heat stress indices for both urban and rural areas are calculated and output by default :ref:`(Buzan et al., 2015)`. A more sophisticated and realistic building space heating and air conditioning submodel that prognoses interior building air temperature and includes more realistic space heating and air conditioning wasteheat factors +is incorporated. + +The fire model is the same as utilized in CLM4.5 except that a modified scheme is used to estimate the dependence of fire occurrence and spread on fuel wetness for non-peat fires outside cropland and tropical closed forests :ref:`Li and Lawrence, 2017)` and the dependence of agricultural fires on fuel load is removed. + +Included with the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, :ref:`Fisher et al., 2015)`. A major motivation of this development is to allow the prediction of biome boundaries directly from plant physiological traits via their competitive interactions. The version of CLM5-FATES that is supported in this release is described here??? Short blurb on what FATES can do??? Note that the classical dynamic global vegetation model (DGVM) that has been available within CLM4 and CLM4.5 remains available, though it is largely untested. The technical description of the CLM-DGVM can be found within the CLM4.5 Technical Description (:ref:`Oleson et al. 2013)`. + +During the course of the development of CLM5.0, it became clear that the increasing complexity of the model combined with the increasing number and range +of model development projects required updates to the underlying CLM infrastructure. Many such software improvements +are included in CLM5.0 including a partial transition to an object-oriented modular software structure, extraction of many hard coded model +parameters into either the parameter file or the CLM namelist, which allows users to more readily calibrate the model for use at +specific locations or to conduct parameter sensitivity studies. As part of the effort to increase +the scientific utility of the code, in most instances older generation parameterizations (i.e., the parameterizations +available in CLM4 or CLM4.5) are retained under namelist switches, allowing the user to revert to CLM4.5 +from the same code base or to revert individual parameterizations where the old parameterizations are compatible with the new code. Finally, multiple vertical soil layer structures +are defined and it is relatively easy to add additional structures. Biogeophysical and Biogeochemical Processes ----------------------------------------------- @@ -566,9 +589,8 @@ processes simulated include (:numref:`Figure Land processes`): #. Snow hydrology (snow accumulation and melt, compaction, water transfer between snow layers) (Chapter :numref:`rst_Snow Hydrology`) -#. Stomatal physiology and photosynthesis (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`) - -#. Prognostic photosynthetic capacity (Chapter :numref:`rst_Photosynthetic Capacity`) +#. Stomatal physiology, photosythetic capacity, and photosynthesis (Chapters :numref:`rst_Stomatal Resistance and Photosynthesis` and + :numref:`rst_Photosynthetic Capacity`) #. Plant hydraulics (Chapter :numref: `rst_Plant Hydraulics`) @@ -576,7 +598,7 @@ processes simulated include (:numref:`Figure Land processes`): #. Glacier processes (Chapter :numref:`rst_Glaciers`) -#. Routing of runoff from rivers to ocean (Chapter :numref:`rst_River Transport Model (RTM)`) +#. River routing and river flow (Chapter :numref:`rst_River Transport Model (RTM)`) #. Urban energy balance and climate (Chapter :numref:`rst_Urban Model (CLMU)`) @@ -593,19 +615,17 @@ processes simulated include (:numref:`Figure Land processes`): #. External nitrogen cycling including deposition, denitrification, leaching, and losses due to fire (Chapter :numref:`rst_External Nitrogen Cycle`) -#. Plant mortality (Chapter :numref:`rst_Plant Mortality`) +#. Plant mortality (Chapter :numref:`rst_Plant_Mortality`) #. Fire ignition, suppression, spread, and emissions, including natural, deforestation, and agricultural fire (Chapter :numref:`rst_Fire`) #. Methane production, oxidation, and emissions (Chapter :numref:`rst_Methane Model`) -#. Crop dynamics and irrigation (Chapter :numref:`rst_Crops and Irrigation`) +#. Crop dynamics, irrigation, and fertilization (Chapter :numref:`rst_Crops and Irrigation`) #. Land cover and land use change including wood harvest (Chapter :numref:`rst_Transient Landcover Change`) -#. Dynamic global vegetation distribution (Chapter :numref:`rst_Dynamic Global Vegetation Model`) - #. Biogenic volatile organic compound emissions (Chapter :numref:`rst_Biogenic Volatile Organic Compounds (BVOCs)`) #. Dust mobilization and deposition (Chapter :numref:`rst_Dust Model`) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 97e221f702..f71c59d22d 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -17,6 +17,10 @@ Martin, M.E., Hallett, R.A., and Stoddard, J.L. 2003. Is nitrogen deposition altering the nitrogen status of northeastern forests? BioScience 53:375-389. +.. _Alietal2016: + +Ali, A. A., C. Xu, A. Rogers, R. A. Fisher, S. D. Wullschleger, E. Massoud, J. A. Vrugt, J. D. Muss, N. McDowell, and J. Fisher, 2016: A global scale mechanistic model of photosynthetic capacity (LUNA V1. 0). Geosci. Mod. Dev., 9:587-606. + .. _Allenetal2005: Allen, C.B., Will, R.E., and Jacobson, M.A. 2005. Production efficiency @@ -209,6 +213,10 @@ Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. Brun, E. 1989. Investigation of wet-snow metamorphism in respect of liquid water content. Ann. Glaciol. 13:22-26. +.. _Brunkeetal2016: + +Brunke, M. A., P. Broxton, J. Pelletier, D. Gochis, P. Hazenberg, D. M. Lawrence, L. R. Leung, G.-Y. Niu, P. A. Troch, and X. Zeng, 2016: Implementing and Evaluating Variable Soil Thickness in the Community Land Model, Version 4.5 (CLM4.5). J. Clim. 29:3441-3461. + .. _BugmannSolomon2000: Bugmann, H., and Solomon, A.M. 2000. Explaining forest composition and @@ -319,6 +327,10 @@ Crawford, T. W., Rendig, V. V., and Broadent, F. E. 1982. Sources, fluxes, and sinks of nitrogen during early reproductive growth of maize (Zea mays L.). Plant Physiol. 70:1645-1660. +.. _Dahlinetal2015: + +Dahlin, K., R. Fisher, and P. Lawrence, 2015: Environmental drivers of drought deciduous phenology in the Community Land Model. Biogeosciences, 12:5061-5074. + .. _DaiZeng1997: Dai, Y., and Zeng, Q. 1997. A land surface model (IAP94) for climate @@ -471,6 +483,10 @@ Firestone, M.K. and Davidson, E.A. 1989. Exchange of Trace Gases between Terrestrial Ecosystems and the Atmosphere. In: M.O. Andreae and D.S. Schimel (Editors). John Wiley and Sons, pp. 7-21. +.. _Fisheretal2015: + +Fisher, R. A., S. Muszala, M. Verteinstein, P. Lawrence, C. Xu, N. G. McDowell, R. G. Knox, C. Koven, J. Holm, B. M. Rogers, A. Spessa, D. Lawrence, and G. Bonan, 2015: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED). Geosci. Model Dev., 8: 3593-3619, doi:10.5194/gmd-8-3593-2015. + .. _FlannerZender2005: Flanner, M.G., and Zender. C.S. 2005. Snowpack radiative heating: @@ -547,7 +563,11 @@ Climate. John Wiley and Sons, Chichester, England. Getirana, A. C. V., A. Boone, D. Yamazaki, B. Decharme, F. Papa, and N. Mognard. 2012. The hydrological modeling and analysis platform -(HyMAP): Evaluation in the Amazon basin, J. Hydrometeorol., 13, 1641–1665. +(HyMAP): Evaluation in the Amazon basin, J. Hydrometeorol., 13, 1641-1665. + +.. _Ghimireetal2016: + +Ghimire, B., W. J. Riley, C. D. Koven, M. Mu, and J. T. Randerson, 2016: Representing leaf and root physiological traits in CLM improves global carbon and nitrogen cycling predictions. J. Adv. Mod. Earth Sys. 8: 598-613. .. _Gholzetal1985: @@ -1448,6 +1468,10 @@ from soils. J. Geophys. Res. 106(D15):17403-17419. Paterson, W.S.B., 1994. The Physics of Glaciers. Elsevier Science Inc., New York, 480 pp. +.. _Pelletieretal2016: + +Pelletier, J. D., P. D. Broxton, P. Hazenberg, X. Zeng, P. A. Troch, G. Y. Niu, Z. Williams, M. A. Brunke, and D. Gochis, 2016: A gridded global data set of soil, intact regolith, and sedimentary deposit thicknesses for regional and global land surface modeling. J. Adv. Mod. Earth Sys. 8:41-65. + .. _Petrescuetal2010: Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions @@ -1564,6 +1588,10 @@ Meeting, Boulder, CO. Roesch, A., M. Wild, H. Gilgen, and A. Ohmura. 2001. A new snow cover fraction parametrization for the ECHAM4 GCM, Clim. Dyn., 17:933–946. +.. _Rogersetal2017: + +Rogers, A., B. E. Medlyn, J. S. Dukes, G. Bonan, S. Caemmerer, M. C. Dietze, J. Kattge, A. D. Leakey, L. M. Mercado, and U. Niinemets, 2017: A roadmap for improving the representation of photosynthesis in Earth system models. New Phytologist, 213:22-42. + .. _Ryan1991: Ryan, M. G. 1991. A simple method for estimating gross carbon budgets @@ -1682,6 +1710,10 @@ patterns of evapotranspiration in response to multiple environmental factors simulated by the Community Land Model. Environ. Res. Lett. 8:024012. +.. _Shietal2016: + +Shi, M., J. B. Fisher, E. R. Brzostek, and R. P. Phillips, 2016: Carbon cost of plant nitrogen acquisition: global carbon cycle impact from an improved plant nitrogen cycle in the Community Land Model. Glob. Change Biol., 22:1299-1314. + .. _Shiklomanov2000: Shiklomanov, I.A. 2000. Appraisal and assessment of world water @@ -2091,6 +2123,10 @@ Wu, H., J. S. Kimball, H. Li, M. Huang, L. R. Leung, and R. F. Adler (2012), A New Global River Network Database for Macroscale Hydrologic modeling, Water Resour. Res., 48, W09701, doi:10.1029/2012WR012313. +.. _Xuetal2012: + +Xu, C., R. Fisher, S. D. Wullschleger, C. J. Wilson, M. Cai, and N. G. McDowell, 2012: Toward a mechanistic modeling of nitrogen limitation on vegetation dynamics. PloS one, 7:e37914. + .. _Yang1998: Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and From 4a563c250a28559a3f39b29fffe53985c6408cff Mon Sep 17 00:00:00 2001 From: Peter Lawrence Date: Wed, 23 Aug 2017 15:51:19 -0600 Subject: [PATCH 089/255] PJL Updated the Transient Landcover Chapter --- .../CLM50_Tech_Note_Transient_Landcover.rst | 441 +++++++----------- 1 file changed, 180 insertions(+), 261 deletions(-) diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index e6f40c34ef..16aaa120a8 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -1,71 +1,76 @@ .. _rst_Transient Landcover Change: -Transient Landcover Change -============================== +Transient Land Use and Land Cover Change +=========================================== CLM includes a treatment of mass and energy fluxes associated with -prescribed temporal change in land cover. Using an annual time series of -the spatial distribution of PFTs and wood harvest, CLM diagnoses the -change in area for PFTs at each model time step and then performs mass -and energy balance accounting necessary to represent the expansion and -contraction of PFT area. This implementation currently only pertains to -the case where all PFTs for a particular grid cell coexist on a single -soil/snow column. In this case, the only biogeophysical state variable -affected is canopy water (:math:`W_{can}` ). The biogeochemical impacts -of land use and land cover change are simulated through changes in CLM -carbon pools and fluxes as shown in Figure 21.1 and described further in -Chapter 13. Other implementations are possible, such as changing the -area of soil/snow columns or land unit area, however these require -additional consideration of conservation of mass and energy among the -soil/snow columns and land units which will be implemented in future -versions of CLM. - -Annual Transient Land Cover Data and Time Interpolation ------------------------------------------------------------- - -The changes in area over time associated with individual PFTs are -prescribed through a forcing dataset, referred to here as the *dynpft* -dataset. The *dynpft* dataset consists of an annual time series of -global grids, where each annual time slice describes the fractional area -occupied by all PFTs and the annual wood harvest within each grid cell. -Changes in area and wood harvest for each PFT within a grid cell at each -model time step are inferred from a time-interpolation of the area -information for the PFT from the two bracketing annual time slices in -the *dynpft* dataset. - -As a special case, when the time dimension of the *dynpft* dataset +prescribed temporal land use and land cover change (LULCC). The model uses an annual +time series of the spatial distribution of the natural and crop land units +of each grid cell, in combination with the distribution of PFTs and CFTs +that exist in those land units. Additional land use is prescribed through annual +crop specific management of nitrogen fertilizer and irrigation described further +in Chapter 25, and through wood harvest on tree PFTs. For changes in the distributions +of natural and crop vegetation CLM diagnoses the change in area of the PFTs and CFTs +on January 1st of each model year and then performs mass and energy balance accounting +necessary to represent the expansion and contraction of the PFT and CFT areas. The +biogeophysical impacts of LULCC are simulated through changes +in surface properties which in turn impact the surface albedo, hydrology, and roughness +which then impact fluxes of energy, moisture and momentum to the atmosphere under the +altered properties. Additionally changes in energy and moisture associated with changes +in the natural and crop vegetation distribution are accounted for through small +fluxes to the atmosphere. The biogeochemical impacts of LULCC +are simulated through changes in CLM carbon pools and fluxes as shown in Figure xx.x and +described further in Chapter 16. + +Annual Transient Land Use and Land Cover Data and Time Interpolation +----------------------------------------------------------------------- + +The changes in area over time associated with changes in natural and crop +vegetation and the land use on that vegetation are prescribed through a forcing dataset, +referred to here as the *landuse.timeseries* dataset. The *landuse.timeseries* dataset +consists of an annual time series of global grids, where each annual time slice describes +the fractional area occupied by all PFTs and CFTs along with the nitrogen fertilizer and +irrigation fraction of each crop CFT, and the annual wood harvest applied to tree PFTs. +Changes in area of PFTs and CFTs are performed annually on the first time step of January +1st of the year. Fertilizer application, irrigation and wood harvest for each PFT and CFT +are performed at each model time step depending on rules from the crop and natural vegetation +phenology models. The irrigation fraction is set annually however fertlizer application and +wood harvest are set from a time-interpolation of the application rates from the two bracketing +annual time slices in the *landuse.timeseries* dataset. + +As a special case, when the time dimension of the *landuse.timeseries* dataset starts at a later year than the current model time step, the first time -slice from the *dynpft* dataset is used to represent the current time -step PFT fractional area distributions. Similarly, when the time -dimension of the *dynpft* dataset stops at an earlier year than the -current model time step, the last time slice of the *dynpft* dataset is -used. Thus, the simulation will have invariant representations of PFT +slice from the *landuse.timeseries* dataset is used to represent the current time +step PFT and CFT fractional area distributions. Similarly, when the time +dimension of the *landuse.timeseries* dataset stops at an earlier year than the +current model time step, the last time slice of the *landuse.timeseries* dataset is +used. Thus, the simulation will have invariant representations of PFT and CFT distributions through time for the periods prior to and following the -time duration of the *dynpft* dataset, with transient PFT distributions -during the period covered by the *dynpft* dataset. +time duration of the *landuse.timeseries* dataset, with transient PFT and CFT distributions +during the period covered by the *landuse.timeseries* dataset. The following equations capture this logic, where :math:`year_{cur}` is the calendar year for the current timestep, -:math:`dynpft\_ year\eqref{GrindEQ__1_}` and -:math:`dynpft\_ year(nyears)`\ are the first and last calendar years in -the *dynpft* dataset, respectively, :math:`nyears` is the number of -years in the *dynpft* dataset, :math:`nt_{1}` and :math:`nt_{2}` +:math:`landuse.timeseries\_ year(1)` and +:math:`landuse.timeseries\_ year(nyears)` are the first and last calendar years in +the *landuse.timeseries* dataset, respectively, :math:`nyears` is the number of +years in the *landuse.timeseries* dataset, :math:`nt_{1}` and :math:`nt_{2}` :math:`{}_{ }`\ are the two bracketing years used in the interpolation algorithm, and :math:`n` is the index value for the -:math:`dynpft\_ year` array corresponding to -:math:`dynpft\_ year(n)=year_{cur}` : +:math:`landuse.timeseries\_ year` array corresponding to +:math:`landuse.timeseries\_ year(n)=year_{cur}` : .. math:: :label: 26.1) - nt_{1} =\left\{\begin{array}{l} {1\qquad {\rm for}\qquad year_{cur} 0` and decreases for :math:`\Delta w_{p} <0`. Mass and Energy Conservation --------------------------------- -Mass conservation is maintained across a PFT weight transition by -summing up all the water state variables to get the total vegetated land -unit water content before (:math:`W_{tot,1}` ) and after -(:math:`W_{tot,2}` ) new PFT weights are calculated. For example, +Mass conservation is maintained across PFT and CFT weight transitions by +summing up all the carbon, nitrogen, water and energy state variables to get the total vegetated land +units value before (:math:`W_{tot,1}` ) and after +(:math:`W_{tot,2}` ) the new PFT and CFT weights are calculated. Transitions are performed on above ground +variables first and then at the land unit level for below ground variables second. For example the hydrological +balance is calculated, :math:`W_{tot,1}` is .. math:: @@ -125,12 +132,11 @@ unit water content before (:math:`W_{tot,1}` ) and after where :math:`W_{a}` is the aquifer water, :math:`W_{sno}` is the snow water, :math:`w_{liq,i}` and :math:`w_{ice,i}` \ are the liquid and ice soil water contents, :math:`W_{can,j}` \ is the canopy water content for -PFT :math:`j`, and :math:`wt_{j,1}` is the PFT weight for PFT -:math:`j`. For the situation where only PFT weights are changing and all -other land unit fractions are constant, any difference between -:math:`W_{tot,1}` and :math:`W_{tot,2}` \ can only be due to -differences in the total canopy water before and after the PFT weight -change. To ensure water conservation, the typically very small +PFT and CFT :math:`j`, and :math:`wt_{j,1}` is the PFT or CFT weight for +:math:`j`. For the situation where PFT and CFT weights are changing, any difference +between :math:`W_{tot,1}` and :math:`W_{tot,2}` \ are due to +differences in the total canopy water before and after the PFT and CFT weight +change. To ensure conservation, the typically very small difference between :math:`W_{tot,2}` \ and :math:`W_{tot,1}` is subtracted from the grid cell runoff @@ -140,210 +146,117 @@ subtracted from the grid cell runoff R_{liq} =R_{liq} +W_{tot,2} -W_{tot,1} . Total energy is unperturbed in this case and therefore an energy -conservation treatment is not required. As noted above, other -implementations are possible and will be desirable in the future, such -as changing the area of soil/snow columns or land unit area, for example -in a situation in which crops are implemented on a separate soil column. -These would require additional consideration of conservation of mass and -energy among the soil/snow columns and land units. +conservation treatment is not required. Changing the area of natural and crop land units +in association with the change in PFTs and CFTs results in changes in the soil/snow columns +and land unit area. To address these additional changes, conservation of mass and +energy among the soil/snow columns and land units is performed as a secondary calculation once +all above ground PFT and CFT changes have been done. Annual Transient Land Cover Dataset Development ---------------------------------------------------- -This section describes the development of the d\ *ynpft* dataset. -Development of this dataset requires adapting for use with the CLM a -harmonized dataset of land cover change for the historical period and -for different representations of the scenario period. +This section describes the development of the *landuse.timeseries* dataset. +Development of this dataset involves the translation of +harmonized datasets of LULCC for the historical period and +for the different Shared Socioeconomic Pathway (SSP) - Representative +Concentration Pathway (RCP) scenarios. Additionally, LULCC time +series are to be generated for the Last Millennium and the extension beyond 2100 experiments +of CMIP6. -21.3.1 UNH Transient Land Use and Land Cover Change Dataset +LUH2 Transient Land Use and Land Cover Change Dataset ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To coordinate the processing and consistency of land use and land cover -change data between the historical period (1850-2005) and the four IPCC -representative concentration pathways (RCPs) derived from integrated -assessment models (IAM), the University of New Hampshire -(stocktickerUNH) research group (Louise Chini, George Hurtt, Steve -Frolking; luh.unh.edu) produced a harmonized transient dataset for use -in climate change simulations. The historical component of the transient -land use and land cover change dataset is Version 1 of the Land-Use -History A product (LUHa.v1) covering the period 1850-2005. The RCP -transient land use and land cover change components (2005-2100) are -referred to as the Future Land-Use Harmonization A products. Version 1 -(LUHa.v1\_future.v1) is used for the AIM, MESSAGE, and MiniCAM IAMs; -Version 1.1 (LUHa.v1\_future.v1.1) is used for the IMAGE IAM. The land -cover information is provided at 0.5 degree grid resolution and includes -fractional grid cell coverage by crops, pasture, and primary and -secondary natural vegetation. - -The crop fraction of the grid cell represents the area of the grid cell -used to grow any type of crop. Similarly, pasture represents the -fraction of a grid cell used for grazing livestock. The remaining area -in a half degree grid cell is partitioned into primary and secondary -vegetation. Primary vegetation represents the fractional area of a grid -cell with vegetation undisturbed by human activities. Secondary -vegetation represents vegetated areas that have recovered from some -human disturbance; this could include re-vegetation of pasture and crop -areas as well as primary vegetation areas that have been logged. - -The stocktickerUNH dataset provides a transition matrix that describes -the annual fraction of land that is transformed from one category to -another (e.g. primary land to crop, pasture to crop, etc.; Hurtt et al. -2006). Included in these transitions is the conversion of secondary land -to secondary land, representing the logging on land recovering from an -earlier disturbance. These transitions provide information on all -changes in land cover through the sum of all transitions in a given -year. Harmonized prescriptions of CMIP5 wood harvest statistics also are -provided by (Hurtt et al. 2011) for the historical and RCP time series. -The wood harvest is prescribed spatially on the same 0.5 degree grid as -the land use class transitions for each year. - -To ensure consistency with the various land use classes wood harvest is -prescribed as both the area of land harvested and the amount of carbon -extracted in the grid cell for a particular year. To account for the -differences in standing amount of wood carbon as well as the differences -in harvest intensity associated with the different land units, the -harvest area and carbon amounts are prescribed for the five classes of: -PlaceNamePrimary PlaceTypeForest, PlaceNamePrimary PlaceTypeNon-Forest, -PlaceNameSecondary PlaceNameMature PlaceTypeForest, PlaceNameSecondary -PlaceNameYoung PlaceTypeForest, and PlaceNameplaceSecondary -PlaceTypeNon-Forest. - -21.3.2 Representing Land Use and Land Cover Change in CLM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CLM represents the land surface as a hierarchy of sub-grid types: -glacier; lake; wetland; urban; and vegetated land. The vegetated land is -further divided into a mosaic of PFTs. To represent the UNH transient -land use and land cover change dataset in CLM, the annual fractional -composition of crop, pasture, primary vegetation, and secondary -vegetation land units specified in the UNH dataset needs to be -faithfully represented with a corresponding PFT mosaic in CLM using the -methods described in Lawrence et al (2012). This method translated each -of the UNH land units into fractional PFT values based on current day -and potential vegetation CLM land surface parameters for that grid cell -and for that year, as shown in Figure 21.2. - -The methodology for creating the transient PFT dataset is based on four -steps which are applied across the time series. First, crop PFT -composition is directly specified from the crop land unit fractional -area. Second, pasture PFTs are assigned based on grass PFTs found in the -potential vegetation and current day CLM land surface parameters scaled -by the area of pasture. Third, potential vegetation PFTs are assigned to -the grid cell scaled by the fractional area of the primary land unit. -Last, current day non-crop and non-pasture PFTs are assigned to the grid -cell scaled by the fractional area of the secondary land unit. The -annual tree harvest values also are calculated from the harvest -information of the UNH dataset used in conjunction with transient tree -PFT values. Separate datasets representing the extent of water, wetland, -ice and urban land cover are used to compile the final land cover -present in each CLM grid cell. These additional non-vegetated land cover -fractions are held constant throughout the time series. All datasets are -resolved at the half degree grid resolution. - -21.3.3 Present Day PFT Dataset -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The present day dataset is based on the methodology of Lawrence and -Chase (2007) and uses a variety of satellite products to develop present -day PFT distributions with matching leaf area index values. The dataset -initially derives fractions of bare ground and tree cover from the -Moderate Resolution Imaging Spectroradiometer (MODIS) vegetation -continuous fields product (Hansen et al. 2003). To further distinguish -tree types, the tree fraction is divided into broadleaf/needleleaf and -evergreen/deciduous types based on the Advanced Very High Resolution -Radiometer (AVHRR) continuous fields tree cover (DeFries et al. 2000). -The remaining grid cell area is assumed to be herbaceous grasses and -shrubs, including crops. The area of crop is initially determined from -Ramankutty et al. (2008) circa 2000 global crop land areas, and the -remaining grass and shrub fractions are derived from the MODIS land -cover (Friedl et al. 2002). Further subdivisions of grass, shrub and -tree PFTs into tropical, temperate and boreal types were based on the -physiology and climate rules from Nemani and Running (1996), and for -C3/C4 photosynthetic pathways based on MODIS derived leaf area index -values and the mapping methods of Still et al. (2003). In contrast to -Lawrence and Chase (2007), the understory grasses of forested areas have -been replaced with trees for the dataset. Some advantages of this -dataset are that it reproduces the physical properties as observed by -the MODIS land surface data (e.g. grid cell albedo and leaf area index -values) while maintaining the multiple PFT representation. - -21.3.4 Potential PFT Distribution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Essential to any reconstruction of past vegetation distributions is the -need to know the potential vegetation that would be there prior to human -activities. Many researchers have worked to estimate potential -vegetation types at regional and global scales from remnant vegetation -and other field data or from bioclimatic models. The CLM potential PFT -distribution is derived from Ramankutty et al. (2008) at 5 arc-minute -resolution. However, this product is based on a biome type -classification system that is not directly compatible with the CLM PFT -distributions. - -The CLM potential vegetation is described by Lawrence and Chase (2010). -This reconstruction describes potential PFT distributions extrapolated -from the current day PFT composition of remnant natural biomes as mapped -by Ramankutty et al. (2008). The current day remnant natural PFT -parameters were taken from the Lawrence and Chase (2007) dataset with -the same forest understory changes as described above to ensure -consistency between the two datasets. The current day remnant natural -PFT biome compositions were spatially extrapolated to the potential -vegetation biome distributions provided by Ramankutty et al. (2008) -using inverse distance weighted methods. The resulting product is a CLM -PFT distribution that may have existed prior to human disturbance under -current day climate conditions. - -21.3.5 Transient Land Cover Change Dataset -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For each year from 1850 to 2005 and to 2100 for each of the four RCPs, -PFT distributions and wood harvest are adjusted based on the -stocktickerUNH dataset. Initially the grid cell is checked to adjust the -crop area based on the stocktickerUNH crop area. If the crop area -exceeds the available land area (i.e. the grid cell area minus the area -assigned to glacier, wetlands, lake and urban areas) then all the -available area is allocated to crops and no other PFTs are added. After -the crop area is assigned, any remaining area is considered available -for pasture. - -As the pasture data from the stocktickerUNH dataset represents grazing, -pasture areas are assigned in the present day based on the availability -of grasses (C3, C4 and boreal C3 PFTs) and shrubs relative to the bare -soil fraction. If the grazing area exceeds the total vegetated area from -both the potential and current day PFT data, then the grazed area is -limited to the larger of the potential or current day vegetated area. -This is done to prevent representing sparsely vegetated grazing areas as -100% vegetated pastures. Once the grazing area is less than or equal to -the total vegetated area, then grazing areas are assigned to the C3 and -C4 grass areas based on their potential vegetation and current day -fractions. In areas where the grazing area cannot be met through the -current day or potential vegetation grass fraction alone, the current -day tree PFTs are converted to grass PFTs, with the remaining shrub PFTs -included as being grazed. - -Once crop and pasture areas are assigned to a grid cell, the remaining -area is assigned to primary and secondary natural vegetation. Primary -vegetation is assumed to be undisturbed and reflects the potential -vegetation PFT distributions. In the secondary region, the PFT -distributions are based on the current day non-crop and non-pasture PFTs -in the grid cell. This process ensures that the PFT distributions are -kept consistent with the original current day and potential vegetation -CLM parameters, while remaining faithful to the stocktickerUNH assigned -areas. - -Forest Harvest Dataset Changes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Discussions following the initial analysis of CCSM4 land cover change -experiments found there were very high wood harvest areas compared to -wood harvest carbon in the RCP 6.0 and RCP 8.5 time series. The high -wood harvest areas were traced to using gridded spatially explicit wood -harvest targets from the MESSAGE and AIM groups for these two time -series, rather than using regional targets with spatial downscaling in -GLM as done with the other three time periods. As a result of these -discussions new amended wood harvest targets were generated with -regional targets through GLM for the RCP 6.0 and RCP 8.5 time series as -described in Lawrence et al. (2012). +To coordinate the processing and consistency of LULCC data between +the historical period (1850-2015) and the six +SSP-RCP (2016-2100) scenarios derived from Integrated +Assessment Models (IAM), the University of Maryland and the University of New Hampshire +research groups (Louise Chini, George Hurtt, Steve +Frolking and Ritvik Sahajpal; luh.umd.edu) produced a new version of the Land Use Harmonized version 2 +(LUH2) transient datasets for use with Earth System Model simulations. The new data sets +are the product of the Land Use Model Intercomparison Project (LUMIP; https://cmip.ucar.edu/lumip) +as part of the Coupled Model Intercomparison Project 6 (CMIP6). The historical component of the +transient LULCC dataset has agriculture and urban +land use based on HYDE 3.2 with wood harvest based on FAO, Landsat and other sources, for the period 850-2015. +The SSP-RCP transient LULCC components (2015-2100) are +referred to as the LUH2 Future Scenario datasets. The LULCC information is provided at 0.25 degree grid resolution and includes +fractional grid cell coverage by the 12 land units of: + +Primary Forest, Secondary Forest, Primary Non-Forest, Secondary Non-Forest, + +Pasture, Rangeland, Urban, + +C3 Annual Crop, C4 Annual Crop, C3 Perennial Crop, C4 Perennial Crop, and C3 Nitrogen Fixing Crop. + +The new land unit format is an improvement on the CMIP5 LULCC +datasets as they: provide Forest and Non Forest information in combination with Primary and Secondary +land; differentiate between Pasture and Rangelands for grazing livestock; and specify annual details +on the types of Crops grown and management practices applied in each grid cell. Like the CMIP5 LULCC datasets Primary vegetation +represents the fractional area of a grid cell with vegetation undisturbed by human activities. Secondary +vegetation represents vegetated areas that have recovered from some human disturbance; this could include +re-vegetation of pasture and crop areas as well as primary vegetation areas that have been logged. +In this manner the land units can change through deforestation from Forested to Non Forested land and in the +opposite direction from Non Forested to Forested land through reforestation or afforestation without going +through the Crop, Pasture or Rangeland states. + +The LUH2 dataset provides a time series of land cover states as well as a transition matrices that describes +the annual fraction of land that is transformed from one land unit category to +another (e.g. Primary Forest to C3 Annual Crop, Pasture to C3 Perrenial Crop, etc.; Lawrence et al. +2016). Included in these transition matrices is the total conversion of one land cover type to another referred to +as Gross LULCC. This value can be larger than the sum of the changes in the state of a land unit from one time period +to the next known as the Net LULCC. This difference is possible as land unit changes can occur both from the land unit +and to the land unit at the same time. An example of this difference occurs with shifting cultivation where Secondary Forest +can be converted to C3 Annual Crop at the same time as C3 Annual Crop is abandoned to Secondary Forest. + +The transition matrices also provide harmonized prescriptions of wood harvest both in area of the grid cell harvested +and in the amount of biomass carbon harvested. The wood harvest biomass amount includes a 30% slash component inline with +the CMIP5 LULCC data described in (Hurtt et al. 2011). The harvest area and carbon amounts are prescribed for the five classes of: +Primary Forest, Primary Non-Forest, +Secondary Mature Forest, Secondary +Young Forest, and Secondary +Non-Forest. + +Additional land use management is prescribed on the Crop land units for +nitrogen fertilization and irrigation equipped land. The fertilizer application and the the irrigation fraction is +prescribed for each Crop land unit in a grid cell individually for each year of the time series. The wood harvest +and crop management are both prescribed spatially on the same 0.25 degree grid as the land use class transitions. + +Representing LUH2 Land Use and Land Cover Change in CLM5 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To represent the LUH2 transient LULCC dataset in CLM5, the annual fractional +composition of the twelve land units specified in the dataset needs to be +faithfully represented with a corresponding PFT and CFT mosaics of CLM. +CLM5 represents the land surface as a hierarchy of sub-grid types: +glacier; lake; wetland; urban; vegetated land; and crop land. The vegetated land is +further divided into a mosaic of Plant Functional Types (PFTs), while the crop land +is divided into a mosaic of Crop Functional Types (CFTs). + +To support this translation task the CLM5 Land Use Data tool has been built that extends the +methods described in Lawrence et al (2012) to include all the new functionality of CMIP6 and CLM5 LULCC. +The tool translates each of the LUH2 land units for a given year into fractional PFT and CFT values based on +the current day CLM5 data for the land unit in that grid cell. The current day land unit descriptions are generated from +from 1km resolution MODIS, MIRCA2000, ICESAT, AVHRR, SRTM, and CRU climate data products combined with reference year +LUH2 land unit data, usually set to 2005. Where the land unit does not exist in a grid cell for the current +day, the land unit description is generated from nearest neighbors with an inverse distance weighted search +algorithm. + +The Land Use Data tool produces raw vegetation, crop, and management data files which are combined with +other raw land surface data to produce the CLM5 initial surface dataset and the dynamic +*landuse.timeseries* dataset with the CLM5 mksurfdata_map tool. The schematic of this entire process from +LUH2 time series and high resolution current day data to the output of CLM5 surface datasets from the +mksurfdata_map tool is shown in Figure 21.2. + +The methodology for creating the CLM5 transient PFT and CFT dataset is based on four +steps which are applied across all of the historical and future time series. +The first step involves generating the current day descriptions of natural and managed vegetation PFTs at +1km resolution from the global source datasets, and the current day description of crop CFTs at the 10km resolution +from the MIRCA 2000 datasets. The second step combines the current day (2005) LUH2 land units with the current +day CLM5 PFT and CFT distributions to get CLM5 land unit descriptions in either PFTs or CFTs at the LUH2 resolution of +0.25 degrees. The third step involves combining the LUH2 land unit time series with the CLM5 PFT and CFT descriptions +for that land unit to generate the CLM5 raw PFT and CFT time series in the *landuse.timeseries* file. At this point in the process +management information in terms of fertilizer, irrigation and wood harvest are added to the CLM5 PFT and CFT data +to complete the CLM5 raw PFT and CFT files. The final step is to combine these files with the other raw CLM5 surface +data files in the mksurfdata_map tool. .. _Figure Schematic of land cover change: @@ -351,8 +264,14 @@ described in Lawrence et al. (2012). Schematic of land cover change impacts on CLM carbon pools and fluxes. -.. _Figure Schematic of translation of annual UNH land units: +.. _Figure Schematic of translation of annual LUH2 land units: .. figure:: image2.png - Schematic of translation of annual UNH land units to CLM4 plant functional types. + Schematic of translation of annual LUH2 land units to CLM5 plant and crop functional types. + + .. _Figure Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool + +.. figure :: image3.png + + Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool From b8ca1aa0a5a26f6f570c2afeada0a8c169e3c0e4 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Wed, 23 Aug 2017 16:23:57 -0600 Subject: [PATCH 090/255] Updates to BVOC and methane (finundated) chapters --- .../tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst | 10 +++---- .../Methane/CLM50_Tech_Note_Methane.rst | 26 +++++++++---------- 2 files changed, 17 insertions(+), 19 deletions(-) diff --git a/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst b/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst index 433f26d97d..e7e8637649 100644 --- a/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst +++ b/doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst @@ -9,17 +9,17 @@ al. 2003; Oleson et al. 2004) was based on Guenther et al. (1995). Heald et al. (2008) updated this scheme in CLM4 based on Guenther et al. (2006). The current version was implemented in CLM4.5 and is based on MEGAN2.1 discussed in detail in Guenther et al. (2012). This update of MEGAN incorporates four -main features: expansion to 147 chemical compounds the treatment of the -light-dependent fraction (LDF) for each compound inclusion of the +main features: 1) expansion to 147 chemical compounds, 2) the treatment of the +light-dependent fraction (LDF) for each compound, 3) inclusion of the inhibition of isoprene emission by atmospheric CO\ :sub:`2` and -emission factors mapped to the specific PFTs of the CLM. +4) emission factors mapped to the specific PFTs of the CLM. MEGAN2.1 now describes the emissions of speciated monoterpenes, -sesquiterpenes, oxygenated VOC as well as isoprene. A flexible scheme +sesquiterpenes, oxygenated VOCs as well as isoprene. A flexible scheme has been implemented in the CLM to specify a subset of emissions. This allows for additional flexibility in grouping chemical compounds to form the lumped species frequently used in atmospheric chemistry. The mapping -or grouping are therefore defined through a namelist parameter in +or grouping is therefore defined through a namelist parameter in drv\_flds\_in, e.g. megan\_specifier = ’ISOP = isoprene’, ’BIGALK = pentane + hexane + heptane + tricyclene’. diff --git a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index f78f464779..7c89f857e3 100644 --- a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -297,14 +297,12 @@ calculated with Henry’s law as described in equation . Based on the ranges reported in :ref:`Colmer (2003)`, we have chosen baseline aerenchyma porosity values of 0.3 for grass and crop PFTs and 0.1 for -tree and shrub PFTs. The aerenchyma area varies over the course of the -growing season; we parameterize this dependency using the simulated leaf -area index *L* (m:sup:`2` m\ :sup:`-2`), as in :ref:`Wania et al. 2010`: +tree and shrub PFTs: .. math:: :label: 24.9 - T=\frac{f_{N} N_{a} L}{0.22} \pi R^{2} . + T=\frac{4 f_{N} N_{a}}{0.22} \pi R^{2} . Here :math:`N_{a}` is annual net primary production (NPP, mol m\ :sup:`-2` s\ :sup:`-1`); *R* is the aerenchyma radius @@ -600,8 +598,8 @@ and the soil element below the interface: Inundated Fraction Prediction ---------------------------------- -We developed a simplified dynamic representation of spatial inundation -based on recent work by :ref:`Prigent et al. (2007)`, who described a +A simplified dynamic representation of spatial inundation +based on recent work by :ref:`Prigent et al. (2007)` is used. Prigent et al. (2007) described a multi-satellite approach to estimate the global monthly inundated fraction (:math:`{F}_{i}`) over an equal area grid (0.25 :math:`\circ` \ :math:`\times`\ 0.25\ :math:`\circ` at the equator) @@ -610,20 +608,20 @@ could be used as a measure of sensitivity of their detection approach at low inundation. We therefore used the sum of their satellite-derived :math:`{F}_{i}` and the constant IGBP estimate when it was less than 10% to perform a simple inversion for the inundated fraction for methane -production (:math:`{f}_{s}`). The method optimized three parameters -(:math:`{p}_{1}`, *p*\ :sub:`2`, :math:`{p}_{3}`) for each -grid cell in a simple model based on simulated water table depth -(:math:`{z}_{w}`) and surface runoff (:math:`{Q}_{r}` (mm s\ :sup:`-1`)): +production (:math:`{f}_{s}`). The method optimized two parameters +(:math:`{fws}_{slope}` and :math:`{fws}_{intercept}`) for each +grid cell in a simple model based on simulated total water storage +(:math:`{TWS}`): .. math:: :label: 24.20 - f_{s} =P_{1} e^{{\raise0.7ex\hbox{$ -z_{w} $}\!\mathord{\left/ {\vphantom {-z_{w} p_{2} }} \right. \kern-\nulldelimiterspace}\!\lower0.7ex\hbox{$ p_{2} $}} } +p_{3} Q_{r} . + f_{s} =fws_{slope} TWS + fws_{intercept} . These parameters were evaluated at the 0.5\ :sup:`o` resolution, and aggregated for -coarser simulations. We expect that ongoing work in the hydrology -submodel of CLM will alleviate the need for this crude simplification of +coarser simulations. Ongoing work in the hydrology +submodel of CLM may alleviate the need for this crude simplification of inundated fraction in future model versions. .. _Seasonal Inundation: @@ -631,7 +629,7 @@ inundated fraction in future model versions. Seasonal Inundation ------------------------ -We have developed a simplified scaling factor to mimic the impact of +A simple scaling factor is used to mimic the impact of seasonal inundation on CH\ :sub:`4` production (see appendix B in :ref:`Riley et al. (2011a)` for a discussion of this simplified expression): From 34c574ca24b53b29197c78c4656b5a5fb007192c Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 24 Aug 2017 10:45:15 -0600 Subject: [PATCH 091/255] Update pft optical properties --- .../CLM50_Tech_Note_Surface_Albedos.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index f16a46ec97..2548b228fa 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -471,19 +471,19 @@ intercepted snow (:numref:`Table Intercepted snow optical properties`) are from +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ | Temp Corn | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Spring Wheat | 0.65 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | + | Spring Wheat | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ | Temp Soybean | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Cotton | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | + | Cotton | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Rice | 0.65 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | + | Rice | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Sugarcane | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | + | Sugarcane | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Tropical Corn | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | + | Tropical Corn | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ - | Tropical Soybean | -0.50 | 0.11 | 0.58 | 0.31 | 0.53 | 0.07 | 0.25 | 0.120 | 0.250 | + | Tropical Soybean | -0.50 | 0.11 | 0.35 | 0.31 | 0.53 | 0.05 | 0.34 | 0.120 | 0.250 | +----------------------------------+----------------------+---------------------------------+---------------------------------+---------------------------------+---------------------------------+-------------------------------+-------------------------------+-------------------------------+-------------------------------+ .. _Table Intercepted snow optical properties: From bedbaf7a3ae9d6cf9eb5bc8f283695d13e0ed340 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Fri, 25 Aug 2017 15:39:31 -0600 Subject: [PATCH 092/255] First part of FUN documentation --- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index 3deceec659..7c11f2bd7d 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -2,3 +2,287 @@ Fixation and uptake of nitrogen =============================== + +Introduction +----------------- + + +The Fixation and Uptake of Nitrogen model is based on work by Fisher (J.) et al., (2008), Brzostek et al. (2015) and Shi et al. (2016). The concept of FUN is that in most cases, Nitrogen uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of Nitrogen in the environment which a plant may exchange for carbon. The ratio of carbon expended to Nitrogen acquired is referred to here as the cost, or exchange rate, of N acquisition (:math:`E_{nacq}`, gC/gN)). There are four pathways for N uptake: + +1. Fixation by symbiotic bacteria in root nodules (for N fixing plants) (:math:`fix`) +2. Retranslocation of N from senescing tissues (:math:`ret`) +3. Active uptake of Nitrogen by plant roots as nitrate (:math:`NO`:sub:`3`) (:math:`act_{no3}`) +4. Active uptake of Nitrogen by plant roots as ammonia (:math:`NH`:sub:`4`) (:math:`act_{nh4}`) + +The notation suffix for each pathway is given in parentheses here. At each timestep, each of these pathways is associated with a cost term (:math:`cost_x`), a payment in carbon (:math:`C_{nuptake,x}`), and an influx of Nitrogen (:math:`N_{uptake,x}`), any of which may be zero, and where :math:`x` is one of the four uptake streams listed above (:math:`fix`, :math:`ret`, :math:`act_{no3}` or :math:`act_{nh4}`). + + +Boundary conditions of FUN +-------------------------------------------------------- + +Available Carbon +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The carbon available for FUN, :math:`C_{avail}` (gC m\ :sup:`-2`) is the total canopy photosynthetic uptake (GPP), minus the maintenance respiration fluxes (:math:`m_r`) and multiplied by the time step in seconds (:math:`\delta t`). Thus, the remainder of this chapter considers fluxes per timestep, and integrates these fluxes as they are calculated. + + .. math:: + + C_{avail} = (GPP - m_r) \delta t + +Growth respiration is thus only calculated on the part of the carbon uptake that remains after expenditure of C by the FUN module. + +Available Soil Nitrogen +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Cost of Nitrogen Fixation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Cost of Active Uptake +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + + +Resolving N cost across simultaneous uptake streams +-------------------------------------------------------- +The total cost of N uptake is calculated based on the assumption that carbon is partitioned to each stream in proportion to the inverse of the cost of uptake. So, more expensive pathways receive less carbon. Earlier versions of FUN (Fisher et al. 2008) utilized a scheme whereby plants only took up N from the cheapest pathway. Brzostek et al. introduced a scheme for the simultaneous uptake from different pathways. Here we calcualate a 'conductance' to N uptake (analagous to the inverse of the cost function conceptualized as a resistance term) :math:`N_{conductance}` ( gN/gC) as: + + .. math:: + + N_{conductance}= \sum{(1/cost_{x})} + +From this, we then calculate the fraction of the carbon allocated to each pathway as + + .. math:: + + C_{frac,x} = \frac{1/cost_{x}}{N_{conductance}} + + +These fractions are used later, to calculate the carbon expended on different uptake pathways. Next, the N acquired from each uptake stream per unit C spent (:math:`N_{exch,x}`, gN/gC) is determined as + + .. math:: + + N_{exch,x} = \frac{C_{frac,x}}{cost_{x}} + +We then determine the total amount of N uptake per unit C spent (:math:`N_{exch,tot}`, gN/gC) as the sum of all the uptake streams. + + .. math:: + N_{exch,tot} = \sum{N_{exch,x}} + +and thus the subsequent overall N cost is + + .. math:: + N_{cost,tot} = 1/{N_{exch,tot}} + +Throughout these calculations, :math:`x` is the sum of the fixation and active uptake pathways. Retranslocation is determined via a different set of mechanisms, once the :math:`N_{cost,tot}` is known. + +Nitrogen Retranslocation +-------------------------------------------------------- +The retranslocation uses an iterative algorithm to remove Nitrogen from each piece of falling litter. There are two pathways for this, 'free' uptake which removes the labile N pool, and 'paid-for' uptake which uses C to extract N from increasingly more recalcitrant pools. + +At each timestep, the pool of carbon in falling leaves (:math:`C_{fallingleaf}`, g m\ :sup:`-2`) is generated from the quantity of litterfall on that day (see Phenology chapter for details). The amount of N in the litter pool (:math:`N_{fallingleaf}`, g m\ :sup:`-2`) is calculated as the total leaf N multiplied by the fraction of the leaf pool passed to litter that timestep. + + .. math:: + + N_{fallingleaf} = N_{leaf}.C_{fallingleaf}/C_{leaf} + +The carbon available at the beginning of the iterative retranslocation calculation is equal to the :math:`C_{avail}` input into FUN. + + .. math:: + + C_{avail_retrans,0} = C_{avail} + + +Free Retranslocation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Some part of the leaf Nitrogen pool is removed without the need for an C expenditure. This 'free' N uptake amount, (:math:`N_{retrans,free}`, gN m\ :sup:`-2`) is calculated as + + .. math:: + + N_{retrans,free} = max(N_{fallingleaf} - (C_{fallingleaf}/CN_{litter,min} ),0.0) + +where :math:`CN_{litter,min}` is the minimum C:N ratio of the falling litter (currently set to 1.5 x the target C:N ratio). + +The new :math:`N_{fallingleaf}` (gN m\ :sup:`-2`) is then determined as + + .. math:: + + N_{fallingleaf} = N_{fallingleaf} - N_{retrans,free} + +and the new litter C:N ratio as + + .. math:: + + CN_{fallingleaf}=C_{fallingleaf}/N_{fallingleaf} + + +Paid-for Retranslocation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The remaining calculations conduct an iterative calculation to determine the degree to which N retranslocation from leaves is paid for as C:N ratios and thus cost increase as N is extracted. The iteration continues until either + +1. The cost of retranslocation (:math:`cost_{retrans}` increases beyond the cost of acquiring N from alternative pathways (:math:`N_{cost,tot}`). +2. :math:`CN_{fallingleaf}` rises to a maximum level, after which no more extraction is possible (representing unavoidable N loss) or +3. There is no more carbon left to pay for extraction. + +First we calculate the cost of extraction (:math:`cost_{retrans}`, gC/gN) for the current leaf C:N ratio as + + .. math:: + + cost_{retrans}= k_{retrans} / (1/CN_{fallingleaf})^{1.3} + +where :math:`k_{retrans}` is a parameter controlling the overall cost of resorption, which also increases exponentially as the C:N ratio increases **Say something about 1.3 exponent**). + +Next, we calculate the amount of C needed to be spent to increase the falling leaf C:N ratio by 1.0 in this iteration :math:`i` (:math:`C_{retrans_spent,i}`, gC m\ :sup:`-2`) as: + .. math:: + + C_{retrans,spent,i} = cost_{retrans}.(N_{fallingleaf} - C_{fallingleaf}/ + (CN_{fallingleaf} + 1.0)) + +(wherein the retranslocation cost is assumed to not change over the increment of 1.0 in C:N ratio). Next, we calculate whether this is larger than the remaining C available to spend. + + .. math:: + + C_{retrans,spent,i} = min(C_{retrans,spent,i}, C_{avail,retrans,i}) + +The amount of N retranslocated from the leaf in this iteration (:math:`N_{retrans_paid,i}`, gN m\ :sup:`-2`) is calculated, checking that it does not fall below zero: + + .. math:: + + N_{retrans,paid,i} = min(N_{fallingleaf},C_{retrans,spent,i} / cost_{retrans}) + +The next step calculates the growth C which is accounted for by this amount of N extraction in this iteration (:math:`C_{retrans,accounted,i}`). This is calculated using the current plant C:N ratio, and also for the additional C which will need to be spent on growth respiration to build this amount of new tissue. + + .. math:: + + C_{retrans,accounted,i} = N_{retrans,paid,i} . CN_{plant} . (1.0 + gr_{frac}) + +Then the falling leaf N is updated: + + .. math:: + + N_{fallingleaf} = N_{fallingleaf} - N_{ret,i} + +and the :math:`CN_{fallingleaf}` and cost_{retrans} are updated. The amount of available carbon that is either unspent on N acquisition nor accounted for by N uptake is updated: + + .. math:: + + C_{avail,retrans,i+1} = C_{avail,retrans,i} - C_{retrans,spent,i} - C_{retrans,accounted,i} + + +Outputs of Retranslocation algorithm. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The final output of the retranslocation calculation are the retranslocated N (:math:`N_{retrans}`, gN m\ :sup:`-2`), C spent on retranslocation (:math:`C_{retrans_paid}`, gC m\ :sup:`-2`), and C accounted for by retranslocation (:math:`C_{retrans_accounted}`, gC m\ :sup:`-2`). + +For paid-for uptake, we accumulate the total carbon spent on retranslocation (:math:`C_{spent_retrans}`), + + .. math:: + + C_{retrans,spent} = \sum{C_{retrans,i}} + +The total N acquired from retranslocation is + + .. math:: + + N_{retrans} = N_{retrans,paid}+N_{retrans,free} + +where N acquired by paid-for retranslocation is + + .. math:: + + N_{retrans,paid} = \sum{N_{retrans,paid,i}} + +The total carbon accounted for by retranslocation is the sum of the C accounted for by paid-for N uptake (:math:`N_{retrans_paid}`) and by free N uptake (:math:`N_{retrans_free}`). + + .. math:: + + C_{retrans,accounted} = \sum{C_{retrans,accounted,i}}+N_{retrans,free}.CN_{plant} . (1.0 + gr_{frac}) + + +The total available carbon in FUN to spend on fixation and active uptake (:math:`C_{tospend}`, gC m\ :sup:`-2`) is calculated as the carbon available minus that account for by retranslocation: + + .. math:: + + C_{tospend} = C_{avail} - C_{retrans,accounted} + + +Carbon expenditure on fixation and active uptake. +-------------------------------------------------------- + +At each model timestep, the overall cost of N uptake is calculated (see below) in terms of C:N ratios. The available carbon (:math:`C_{avail}`, g m\ :sup:`-2` s\ :sup:`-1`) is then allocated to two alternative outcomes, payment for N uptake, or conservation for growth. For each carbon conserved for growth, a corresponding quantity of N must be made available. In the case where the plant target C:N ratio is fixed, the partitioning between carbon for growth (:math:`C_{growth}`) and carbon for N uptake (:math:`C_{nuptake}`) is calculated by solving a system of simultaneous equations. First, the carbon available must equal the carbon spent on N uptake plus that saved for growth. + + .. math:: + + C_{growth}+C_{nuptake}=C_{avail} + +Second, the nitrogen acquired from expenditure of N (left hand side of term below) must equal the N that is required to match the growth carbon (right hand side of term below). + + .. math:: + + C_{nuptake}/N_{cost} =C_{growth}/CN_{target} + +The solution to these two equated terms can be used to estimate the ideal :math:`C_{nuptake}` as follows, + + .. math:: + C_{nuptake} =C_{tospend}/ ( (1.0+f_{gr}*(CN_{target} / N_{cost}) + 1) . + +and the other C and N fluxes can be determined following the logic above. + +Modifications to allow variation in C:N ratios +-------------------------------------------------------- +The original FUN model as developed by Fisher et al. (2008) and Brzostek et al. (2015) assumes a fixed plant tissue C:N ratio. This means that in the case where N is especially limiting, all excess carbon will be utilized in an attempt to take up more Nitrogen. It has been repeatedly observed, however, that in these circumstances in real life, plants have some flexibility in the C:N stoichiometry of their tissues, and therefore, this assumption may not be realistic. **lit review on CN ratios** + +Thus, in CLM5, we introduce the capacity for tissue C:N ratios to be prognostic, rather than static. Overall N and C availability (:math:`N_uptake` and :math:`C_{growth}`) and hence tissue C:N ratios, are both determined by FUN. Allocation to individual tissues is discussed in the allocation chapter + +Here we introduce an algorithm which adjusts the C expenditure on uptake to allow varying tissue C:N ratios. Increasing C spent on uptake will directly reduce the C:N ratio, and reducing C spent on uptake (retaining more for tissue growth) will increase it. C spent on uptake is impacted by both the N cost in the environment, and the existing tissue C:N ratio of the plant. The output of this algorithm is :math:`\gamma_{FUN}`, the fraction of the ideal :math:`C_{nuptake}` calculated from +the FUN equation above (**link equation**). + + .. math:: + C_{nuptake} = C_{nuptake}.\gamma_{FUN} + + +Response of C expenditure to Nitrogen uptake cost +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The environmental cost of Nitrogen (:math:`N_{cost,tot}`) is used to determine :math:`\gamma_{FUN}`. + + .. math:: + \gamma_{FUN} = max(0.0,1.0 - (N_{cost,tot}-a_{cnflex})/b_{cnflex}) + +where :math:`a_{cnflex}` and :math:`b_{cnflex}` are parameters fitted to give flexible C:N ranges over the operating range of N costs of the model. Calibration of these parameters should be subject to future testing in idealized experimental settings; they are here intended as a placeholder to allow some flexible stoichiometry, in the absence of adequate understanding of this process. Here :math:`a_{cnflex}` operates as the :math:`N_{cost,tot}` above which there is a modification in the C expenditure (to allow higher C:N ratios), and :math:`b_{cnflex}` is the scalar which determines how much the C expenditure is modified for a given discrepancy between :math:`a_{cnflex}` and the actual cost of uptake. + + +Response of C expenditure to plant C:N ratios +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We first calculate a :math:`\delta_{CN}`, which is the difference between the target C:N (:math:`target_{CN}`) a model parameter, and the existing C:N ratio (:math:`CN_{plant}`) **This isn't strictly how it is worked out. Need to remember why we use c_allometry instead**. + + .. math:: + + CN_{plant} = \frac{C_{leaf} + C_{leaf,storage}}{N_{leaf} + N_{leaf,storage})} + +and + .. math:: + \delta_{CN} = CN_{plant} - target_{CN} + + +We then modify :math:`\gamma_{FUN}` to account for situations where (even if N is expensive) plant C:N ratios have increased too far from the target. For situations where :math:`\delta_{CN}` is positive and :math:`\gamma_{FUN}` is <1: + + .. math:: + \gamma_{FUN} = \gamma_{FUN}+(1-\gamma_{FUN}).min(1,\delta_{CN}/c_{flexcn}) + +For situations where :math:`\delta_{CN}` is negative, we reduce C spent on N uptake and retain more C for growth: + + .. math:: + \gamma_{FUN} = \gamma_{FUN}+ 0.5.(delta_CN/c_{flexcn}) + + +We then restrict the degree to which C expenditure can be reduced ( to prevent unrea;istically high C:N ratios) as + + .. math:: + \gamma_{FUN} = max(min(1.0,\gamma_{FUN}),0.5) + + + + + + + + + + From 609d3b9573635185d5d2f6539d3e4d40e74c4f82 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Tue, 29 Aug 2017 16:32:31 -0600 Subject: [PATCH 093/255] Phase 2 of FUN tech note --- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 174 +++++++++++++++--- 1 file changed, 151 insertions(+), 23 deletions(-) diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index 7c11f2bd7d..94c9027a23 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -1,20 +1,32 @@ .. _rst_FUN: -Fixation and uptake of nitrogen +Fixation and Uptake of Nitrogen (FUN) =============================== Introduction ----------------- -The Fixation and Uptake of Nitrogen model is based on work by Fisher (J.) et al., (2008), Brzostek et al. (2015) and Shi et al. (2016). The concept of FUN is that in most cases, Nitrogen uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of Nitrogen in the environment which a plant may exchange for carbon. The ratio of carbon expended to Nitrogen acquired is referred to here as the cost, or exchange rate, of N acquisition (:math:`E_{nacq}`, gC/gN)). There are four pathways for N uptake: +The Fixation and Uptake of Nitrogen model is based on work by Fisher (J.) et al., (2008), Brzostek et al. (2015) and Shi et al. (2016). The concept of FUN is that in most cases, Nitrogen uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of Nitrogen in the environment which a plant may exchange for carbon. The ratio of carbon expended to Nitrogen acquired is referred to here as the cost, or exchange rate, of N acquisition (:math:`E_{nacq}`, gC/gN)). There are eight pathways for N uptake: -1. Fixation by symbiotic bacteria in root nodules (for N fixing plants) (:math:`fix`) -2. Retranslocation of N from senescing tissues (:math:`ret`) -3. Active uptake of Nitrogen by plant roots as nitrate (:math:`NO`:sub:`3`) (:math:`act_{no3}`) -4. Active uptake of Nitrogen by plant roots as ammonia (:math:`NH`:sub:`4`) (:math:`act_{nh4}`) +1. Fixation by symbiotic bacteria in root nodules (for N fixing plants) (:math:`_{fix}`) +2. Retranslocation of N from senescing tissues (:math:`_{ret}`) +3. Active uptake of NH4 by arbuscular mycorrhizal plants (:math:`_{active,nh4}`) +4. Active uptake of NH4 by ectomycorrhizal plants (:math:`_{active,nh4}`) +5. Active uptake of NO3 by arbuscular mycorrhizal plants (:math:`_{active,no3}`) +6. Active uptake of NO3 by ectomycorrhizal plants (:math:`_{active,no3}`) +7. Nonmycorrhizal uptake of NH4 (:math:`_{nonmyc,no3}`) +8. Nonmycorrhizal uptake of NO3 (:math:`_{nonmyc,nh4}`) + + +The notation suffix for each pathway is given in parentheses here. At each timestep, each of these pathways is associated with a cost term (:math:`N_{cost,x}`), a payment in carbon (:math:`C_{nuptake,x}`), and an influx of Nitrogen (:math:`N_{uptake,x}`) where :math:`x` is one of the eight uptake streams listed above. + + +For each PFT, we define a fraction of the total C acquisition that can be used for N fixation (:math:`f_{fixers}`), which is broadly equivalent to the fraction of a given PFT that is capable of fixing Nitrogen, and thus represents an upper limit on the amount to which fixation can be increased in low n conditions. For each PFT, the cost calculation is conducted twice. Once where fixation is possible and once where it is not. (:math:`f_{fixers}`) + + +For all of the active uptake pathways, whose cost depends on varying concentrations of N through the soil profile, the costs and fluxes are also determined by soil layer :math:`j`. -The notation suffix for each pathway is given in parentheses here. At each timestep, each of these pathways is associated with a cost term (:math:`cost_x`), a payment in carbon (:math:`C_{nuptake,x}`), and an influx of Nitrogen (:math:`N_{uptake,x}`), any of which may be zero, and where :math:`x` is one of the four uptake streams listed above (:math:`fix`, :math:`ret`, :math:`act_{no3}` or :math:`act_{nh4}`). Boundary conditions of FUN @@ -35,32 +47,67 @@ Available Soil Nitrogen Cost of Nitrogen Fixation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The cost of fixation is derived from Houlton et al. (2008). + .. math:: + + N_{cost,fix} = -s_{fix}/(1.25 e^{a_{fix} + b_{fix} . t_{soil} (1 - 0.5 t_{soil}/ c_{fix}) }) + +Herein, :math:`a_{fix}`, :math:`b_{fix}` and :math:`c_{fix}` are all parameters of the temperature response function of fixation reported by Houlton et al. (2008) (:math:`exp[a+bT_s(1-0.5T_s/c)`). t_{soil} is the soil temperature in C. The values of these parameters are fitted to empirical data as a=-3.62 :math:`\pm` 0.52, b=0.27:math:`\pm` 0.04 and c=25.15 :math:`\pm` 0.66. 1.25 converts from the temperature response function to a 0-1 limitation factor (as specifically employed by Houlton et al.). This function is a 'rate' of uptake for a given temperature. Here we assimilated the rate of fixation into the cost term by assuming that the rate is analagous to a conductance for N, and inverting the term to produce a cost/resistance analagoue. We then multiply this temperature term by the minimum cost at optimal temperature (:math:`s_{fix}`) to give a temperature limited cost in terms of C to N ratios. + + Cost of Active Uptake ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The cost of N uptake from soil, for each layer :math:`j`, is controlled by two uptake parameters that pertain respectively to the relationship between soil N content and N uptake, and root C density and N uptake. + +For non-mycorrhizal uptake: + + .. math:: + + N_{cost,nonmyc,j} = \frac{k_{n,nonmyc}}{N_{smin,j}} + \frac{k_{c,nonmyc}}{c_{root,j}} + +and for active uptake: + + .. math:: + + N_{cost,active,j} = \frac{k_{n,active}}{N_{smin,j}} + \frac{k_{c,active}}{c_{root,j}} + +where :math:`k_{n,active}` varies according to whether we are considering ecto or arbuscular mycorrhizal uptake. + .. math:: + :label: 18.2 + + k_{n,active} = + \left\{\begin{array}{lr} + k_{n,Eactive}& e = 1\\ + k_{n,Aactive}& e = 0 + \end{array}\right\} + +where m=1 pertains to the fraction of the PFT that is ecotmycorrhizal, as opposed to arbuscular mycorrhizal. + Resolving N cost across simultaneous uptake streams -------------------------------------------------------- The total cost of N uptake is calculated based on the assumption that carbon is partitioned to each stream in proportion to the inverse of the cost of uptake. So, more expensive pathways receive less carbon. Earlier versions of FUN (Fisher et al. 2008) utilized a scheme whereby plants only took up N from the cheapest pathway. Brzostek et al. introduced a scheme for the simultaneous uptake from different pathways. Here we calcualate a 'conductance' to N uptake (analagous to the inverse of the cost function conceptualized as a resistance term) :math:`N_{conductance}` ( gN/gC) as: .. math:: - N_{conductance}= \sum{(1/cost_{x})} + N_{conductance,f}= \sum{(1/N_{cost,x})} + From this, we then calculate the fraction of the carbon allocated to each pathway as .. math:: - C_{frac,x} = \frac{1/cost_{x}}{N_{conductance}} + C_{frac,x} = \frac{1/N_{cost,x}}{N_{conductance}} These fractions are used later, to calculate the carbon expended on different uptake pathways. Next, the N acquired from each uptake stream per unit C spent (:math:`N_{exch,x}`, gN/gC) is determined as .. math:: - N_{exch,x} = \frac{C_{frac,x}}{cost_{x}} + N_{exch,x} = \frac{C_{frac,x}}{N_{cost,x}} We then determine the total amount of N uptake per unit C spent (:math:`N_{exch,tot}`, gN/gC) as the sum of all the uptake streams. @@ -72,7 +119,7 @@ and thus the subsequent overall N cost is .. math:: N_{cost,tot} = 1/{N_{exch,tot}} -Throughout these calculations, :math:`x` is the sum of the fixation and active uptake pathways. Retranslocation is determined via a different set of mechanisms, once the :math:`N_{cost,tot}` is known. + Retranslocation is determined via a different set of mechanisms, once the :math:`N_{cost,tot}` is known. Nitrogen Retranslocation -------------------------------------------------------- @@ -88,7 +135,7 @@ The carbon available at the beginning of the iterative retranslocation calculati .. math:: - C_{avail_retrans,0} = C_{avail} + C_{avail,retrans,0} = C_{avail} Free Retranslocation @@ -261,28 +308,109 @@ and \delta_{CN} = CN_{plant} - target_{CN} -We then modify :math:`\gamma_{FUN}` to account for situations where (even if N is expensive) plant C:N ratios have increased too far from the target. For situations where :math:`\delta_{CN}` is positive and :math:`\gamma_{FUN}` is <1: - - .. math:: - \gamma_{FUN} = \gamma_{FUN}+(1-\gamma_{FUN}).min(1,\delta_{CN}/c_{flexcn}) +We then increase :math:`\gamma_{FUN}` to account for situations where (even if N is expensive) plant C:N ratios have increased too far from the target. Where :math:`\delta_{CN}` is negative, we reduce C spent on N uptake and retain more C for growth + + .. math:: + :label: 7.23 -For situations where :math:`\delta_{CN}` is negative, we reduce C spent on N uptake and retain more C for growth: + \gamma_{FUN} = + \left\{\begin{array}{lr} + \gamma_{FUN}+ 0.5.(delta_{CN}/c_{flexcn})& delta_{CN} > 0\\ + \gamma_{FUN}+(1-\gamma_{FUN}).min(1,\delta_{CN}/c_{flexcn}) & delta_{CN} < 0 + \end{array}\right\} - .. math:: - \gamma_{FUN} = \gamma_{FUN}+ 0.5.(delta_CN/c_{flexcn}) - - -We then restrict the degree to which C expenditure can be reduced ( to prevent unrea;istically high C:N ratios) as +We then restrict the degree to which C expenditure can be reduced (to prevent unrealistically high C:N ratios) as .. math:: \gamma_{FUN} = max(min(1.0,\gamma_{FUN}),0.5) + + +Calculation of N uptake streams from active uptake and fixation +-------------------------------------------------------- + +Once the final :math:`C_{nuptake}` is known, the fluxes of C to the individual pools can be derived as + + .. math:: + C_{nuptake,x} = C_{frac,x}.C_{nuptake} + - + .. math:: + + N_{uptake,x} = \frac{C_{nuptake}}{N_{cost}} + + +Following this, we determine whether the extraction estimates exceed the pool size for each source of N. Where :math:`N_{active,no3} + N_{nonmyc,no3} > N_{avail,no3}`, we calculate the unmet uptake, :math:`N_{unmet,no3}` + + .. math:: + + N_{unmet,no3} = N_{active,no3} + N_{nonmyc,no3} - N_{avail,no3} + +then modify both fluxes to account + + .. math:: + + N_{active,no3} = N_{active,no3} + N_{unmet,no3}.\frac{N_{active,no3}}{N_{active,no3}+N_{nonmyc,no3}} + + .. math:: + + N_{nonmyc,no3} = N_{nonmyc,no3} + N_{unmet,no3}.\frac{N_{nonmyc,no3}}{N_{active,no3}+N_{nonmyc,no3}} + +and similarly, for NH4, where :math:`N_{active,nh4} + N_{nonmyc,nh4} > N_{avail,nh4}`, we calculate the unmet uptake, :math:`N_{unmet,no3}` + + .. math:: + + N_{unmet,nh4} = N_{active,nh4} + N_{nonmyc,nh4} - N_{avail,nh4} + +then modify both fluxes to account + + .. math:: + + N_{active,nh4} = N_{active,nh4} + N_{unmet,nh4}.\frac{N_{active,nh4}}{N_{active,nh4}+N_{nonmyc,nh4}} + .. math:: + + N_{nonmyc,nh4} = N_{nonmyc,nh4} + N_{unmet,nh4}.\frac{N_{nonmyc,nh4}}{N_{active,nh4}+N_{nonmyc,nh4}} + + +and then update the C spent to account for hte new lower N acquisition in that layer/pool. + + .. math:: + + C_{active,nh4} = N_{active,nh4}.N_{cost,active,nh4}\\ + C_{active,no3} = N_{active,no3}.N_{cost,active,no3}\\ + C_{nonmyc,no3} = N_{nonmyc,no3}.N_{cost,nonmyc,no3}\\ + C_{nonmyc,no3} = N_{nonmyc,no3}.N_{cost,nonmyc,no3}\\ + + +Following this, we determine how much carbon is accounted for for each soil layer. + + .. math:: + + C_{accounted,x,j} = C_{spent,j,x} - (N_{acquired,j,x}.CN_{plant}.(1.0+ gr_{frac})) + + + +Types of N uptake streams +-------------------------------------------------------- +Arbuscular mycorrhizal fungi: +Ectomycorrhizal fungi: +Nonmycorrhizal plants. + + +ECK_active (step 1) sets active components for Ectomycorrhizal fungi +ACK_active (step 2) sets active components for Arbuscular fungi +kc_nonmyc (step 1) sets nonmyc components for Ectomycorrhizal fungi +kc_nonmyc (step 2) sets active components for Arbuscular fungi +ACTIVE vs NONMYC +ECTO vs ARBU for ACTIVE. + +References +-------------------------------------------------------- +Houlton, B.Z., Wang, Y.P., Vitousek, P.M. and Field, C.B., 2008. A unifying framework for dinitrogen fixation in the terrestrial biosphere. Nature, 454(7202), p.327. From 8ace44030f052ed0a757b0584da9bce94326ad51 Mon Sep 17 00:00:00 2001 From: Charlie Koven Date: Thu, 31 Aug 2017 17:07:44 -0700 Subject: [PATCH 094/255] a few changes: replaced some graphics, moved some text from allocation to CN pools, updated text in a few places --- .../CLM50_Tech_Note_CN_Allocation.rst | 38 ------------ .../CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 47 +++++++++++++++ .../CLM50_Tech_Note_Decomposition.rst | 59 ++++++++++++++----- .../References/CLM50_Tech_Note_References.rst | 7 +++ 4 files changed, 97 insertions(+), 54 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index a63ec9ae3d..71eca6193a 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -6,44 +6,6 @@ Carbon and Nitrogen Allocation Introduction ----------------- -CLM includes a fully-prognostic treatment of the terrestrial carbon and -nitrogen cycles including interactions between these cycles as mediated -by biological mechanisms of plants and soil heterotrophs. The model is -fully prognostic with respect to all carbon and nitrogen state variables -in the vegetation, litter, and soil organic matter. The seasonal timing -of new vegetation growth and litterfall is also prognostic, responding -to soil and air temperature, soil water availability, and daylength, in -varying degrees depending on a specified phenology type for each PFT -(see Chapter 14). The prognostic LAI, SAI, and vegetation heights are -utilized by the biophysical model. - -Separate state variables for C and N are tracked for leaf, live stem, -dead stem, live coarse root, dead coarse root, and fine root pools -(Figure 13.1 and 13.2). Each of these pools has two corresponding -storage pools representing, respectively, short-term and long-term -storage of non-structural carbohydrates and labile nitrogen. There are -two additional carbon pools, one for the storage of growth respiration -reserves, and another used to meet excess demand for maintenance -respiration during periods with low photosynthesis. One additional -nitrogen pool tracks retranslocated nitrogen, mobilized from leaf tissue -prior to abscission and litterfall. Altogether there are 20 state -variables for vegetation carbon, and 19 for vegetation nitrogen. - -.. _Figure Vegetation fluxes and pools: - -.. figure:: image1.png - :width: 800px - :height: 800px - - Vegetation fluxes and pools. - -.. _Figure Carbon and nitrogen pools: - -.. figure:: image2.png - :width: 400px - :height: 400px - - Carbon and nitrogen pools. Carbon Allocation for Maintenance Respiration Costs -------------------------------------------------------- diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index 92903f02e0..a98069deaf 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -2,3 +2,50 @@ CN Pools =================== + +Introduction +----------------- + +CLM includes a prognostic treatment of the terrestrial carbon and +nitrogen cycles including natural vegetation, crops, and soil biogeochemistry. The model is +fully prognostic with respect to all carbon and nitrogen state variables +in the vegetation, litter, and soil organic matter. The seasonal timing +of new vegetation growth and litterfall is also prognostic, responding +to soil and air temperature, soil water availability, daylength, and +crop management practices in +varying degrees depending on a specified phenology type or management for each PFT +(Chapter +:numref:`rst_Vegetation Phenology and Turnover`). The +prognostic LAI, SAI, +tissue stoichiometry, and vegetation heights are +utilized by the biophysical model that couples carbon, water, and +energy cycles. + +Separate state variables for C and N are tracked for leaf, live stem, +dead stem, live coarse root, dead coarse root, fine root, and grain pools +(:numref:`Figure Vegetation fluxes and pools`). Each of these pools has two corresponding +storage pools representing, respectively, short-term and long-term +storage of non-structural carbohydrates and labile nitrogen. There are +two additional carbon pools, one for the storage of growth respiration +reserves, and another used to meet excess demand for maintenance +respiration during periods with low photosynthesis. One additional +nitrogen pool tracks retranslocated nitrogen, mobilized from leaf tissue +prior to abscission and litterfall. Altogether there are 23 state +variables for vegetation carbon, and 22 for vegetation nitrogen. + +.. _Figure Vegetation fluxes and pools: + +.. figure:: CLMCN_pool_structure_v2_lores.png + :width: 753px + :height: 513px + + Vegetation fluxes and pools for carbon cycle in CLM5. + +In addition to the vegetation pools, CLM includes a series of +decomposing carbon and nitrogen pools as vegetation successively +breaks down to CWD, and/or litter, and subsequently to soil organic +matter. Discussion of the decomposition model, alternate +specifications of decomposition rates, and methods to rapidly +equilibrate the decomposition model, is in Chapter +:numref:`rst_Decomposition`. + diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index d35feab5be..87f7f170bd 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -15,11 +15,12 @@ structure used in CLM4.0, or a second pool structure, characterized by slower decomposition rates, based on the Century model (Parton et al. 1988). In addition, the user can choose, at compile time, whether to allow :math:`{n}_{lev}` to equal 1, as in CLM4.0, or to equal the -number of soil levels used for the soil hydrology (default 10). +number of soil levels used for the soil hydrological and thermal +calculations (see Section :numref:`Soil Layers` for soil layering). .. _Figure Schematic of decomposition model in CLM: -.. figure:: image1.png +.. figure:: CLM4_vertsoil_soilstruct_drawing.png Schematic of decomposition model in CLM. @@ -60,11 +61,11 @@ pools. Further discussion of the vertical distribution of carbon inputs :math:`{R}_{i}`\ (z), vertical turnover times :math:`{k}_{j}`\ (z), and vertical transport *D(z)* is below. Discussion of the vertical model and analysis of both decomposition -structures is in Koven et al (2013). +structures is in :ref:`Koven et al. (2013) `. .. _Figure Pool structure: -.. figure:: image2.png +.. figure:: soil_C_pools_CN_century.png Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 @@ -271,7 +272,9 @@ unitless) is calculated using a relationship from Andrén and Paustian where :math:`{\Psi}_{j}` is the soil water potential in layer *j*, :math:`{\Psi}_{min}` is a lower limit for soil -water potential control on decomposition rate (set to -10 MPa). +water potential control on decomposition rate (in CLM5, this was +changed from a default value of -10 MPa in CLM4.5 and earlier to a +default value of -2.5 MPa). :math:`{\Psi}_{sat,j}` (MPa) is the saturated soil water potential, calculated using the multivariate regression model from Cosby et al. (1984): @@ -294,7 +297,7 @@ of Niu and Yang (2006), \psi \left(T\right)=-\frac{L_{f} \left(T-T_{f} \right)}{10^{3} T} An additional frozen decomposition limitation can be specified using a -‘frozen Q\ :sub:`10` following Koven et al. (2011), however the +‘frozen Q\ :sub:`10`' following :ref:`Koven et al. (2011) `, however the default value of this is the same as the unfrozen Q\ :sub:`10` value, and therefore the basic hypothesis is that frozen respiration is limited by liquid water availability, and can be modeled following the @@ -322,7 +325,7 @@ of decomposition was shown by Jenkinson and Coleman (2008) to be an important term in fitting total C and 14C profiles, and implies that unresolved processes, such as priming effects, microscale anoxia, soil mineral surface and/or aggregate stabilization may be important in -controlling the fate of carbon at depth (Koven et al. 2013). CLM +controlling the fate of carbon at depth :ref:`Koven et al. (2013) `. CLM includes these unresolved depth controls via an exponential decrease in the soil turnover time with depth: @@ -331,7 +334,10 @@ the soil turnover time with depth: r_{depth} =\exp \left(-\frac{z}{z_{\tau } } \right) -where :math:`{z}_{\tau}` is the e-folding depth for decomposition, set by default to 0.5m. +where :math:`{z}_{\tau}` is the e-folding depth for decomposition. For +CLM4.5, the default value of this was 0.5m. For CLM5, this has been +changed to a default value of 10m, which effectively means that +intrinsic decomposition rates may proceed as quickly at depth as at the surface. The combined decomposition rate scalar (:math:`{r}_{total}`,unitless) is: @@ -746,15 +752,22 @@ value of the advection term is 0 cm/yr, such that transport is purely diffusive. Diffusive transport differs in rate between permafrost soils (where cryoturbation is the dominant transport term) and non-permafrost soils (where bioturbation dominates). For permafrost soils, a -parameterization based on that of Koven et al. (2009) is used: the +parameterization based on that of :ref:`Koven et al. (2009) ` is used: the diffusivity parameter is constant through the active layer, and decreases linearly from the base of the active layer to zero at a set depth (default 3m); the default permafrost diffusivity is 5 cm\ :sup:`2`/yr. For non-permafrost soils, the default diffusivity is 1 cm\ :sup:`2`/yr. -Model Equilibration ------------------------- +Model Equilibration and its Acceleration +--------------------------------------- +For transient experiments, it is usually assumed that the carbon cycle +is starting from a point of relatively close equilibrium, i.e. that +productivity is balanced by ecosystem carbon losses through +respiratory and disturbance pathways. In order to satisfy this +assumption, the model is generally run until the productivity and loss +terms find a stable long-term equilibrium; at this point the model is +considered 'spun up'. Because of the coupling between the slowest SOM pools and productivity through N downregulation of photosynthesis, equilibration of the model @@ -762,14 +775,13 @@ for initialization purposes will take an extremely long time in the standard mode. This is particularly true for the CENTURY-based decomposition cascade, which includes a passive pool. In order to rapidly equilibrate the model, a modified version of the “accelerated -decomposition†(Thornton and Rosenbloom, 2005) is used. The fundamental +decomposition†:ref:`(Thornton and Rosenbloon, 2005) ` is used. The fundamental idea of this approach is to allow fluxes between the various pools (both turnover-defined and vertically-defined fluxes) adjust rapidly, while keeping the pool sizes themselves small so that they can fill quickly. To do this, the base decomposition rate :math:`{k}_{i}` for each pool *i* is accelerated by a term :math:`{a}_{i}` such that the slow -pools are collapsed onto an approximately annual timescale (Koven et al. -2013). Accelerating the pools beyond this timescale distorts the +pools are collapsed onto an approximately annual timescale :ref:`Koven et al. (2013) `. Accelerating the pools beyond this timescale distorts the seasonal and/or diurnal cycles of decomposition and N mineralization, thus leading to a substantially different ecosystem productivity than the full model. For the vertical model, the vertical transport terms are @@ -787,6 +799,21 @@ accelerated decomposition mode are handled automatically by CLM upon loading from restart files (which preserve information about the mode of the model when restart files were written). -The acceleration terms for the two decomposition cascades are shown in -Tables 15.1 and 15.3. +The base acceleration terms for the two decomposition cascades are shown in +Tables 15.1 and 15.3. In addition to the base terms, CLM5 also +includes a geographic term to the acceleration in order to apply +larger values to high-latitude systems, where decomposition rates are +particularly slow and thus equilibration can take significantly longer +than in temperate or tropical climates. This geographic term takes +the form of a logistic equation, where :math:`{a}_{i}` is equal to the +product of the base acceleration term and :math:`{a}_{l}` below: + +.. math:: + :label: 21.62) + + a_l = 1 + 50 / \left ( 1 + exp \left (-0.1 * (abs(latitude) - + 60 ) \right ) \right ) + + + diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index a419e14e80..d7a5887778 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -896,6 +896,13 @@ Koven, C.D. et al. 2013. The effect of vertically-resolved soil biogeochemistry and alternate soil C and N models on C dynamics of CLM4. Biogeosciences Discussions 10:7201-7256. +.. _Kovenetal2015: + +Koven, C.D. et al. 2015. Permafrost carbon-climate feedback is +sensitive to deep soil carbon decomposability but not deep soil +nitrogen dynamics. Proceedings of the National Academies of Science, +112, 12, 3752-3757, doi:10.1073/pnas.1415123112 + .. _Kuchariketal2000: Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., From bda8c43308dedf6e4a947ffce438a0332d713022 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 1 Sep 2017 09:03:35 -0600 Subject: [PATCH 095/255] Update html and fix build errors --- doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst | 9 ++++----- .../CLM50_Tech_Note_Transient_Landcover.rst | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index 94c9027a23..32d42b564c 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -1,7 +1,7 @@ .. _rst_FUN: Fixation and Uptake of Nitrogen (FUN) -=============================== +======================================= Introduction ----------------- @@ -286,7 +286,7 @@ the FUN equation above (**link equation**). Response of C expenditure to Nitrogen uptake cost -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The environmental cost of Nitrogen (:math:`N_{cost,tot}`) is used to determine :math:`\gamma_{FUN}`. .. math:: @@ -296,7 +296,7 @@ where :math:`a_{cnflex}` and :math:`b_{cnflex}` are parameters fitted to give fl Response of C expenditure to plant C:N ratios -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We first calculate a :math:`\delta_{CN}`, which is the difference between the target C:N (:math:`target_{CN}`) a model parameter, and the existing C:N ratio (:math:`CN_{plant}`) **This isn't strictly how it is worked out. Need to remember why we use c_allometry instead**. .. math:: @@ -311,7 +311,6 @@ and We then increase :math:`\gamma_{FUN}` to account for situations where (even if N is expensive) plant C:N ratios have increased too far from the target. Where :math:`\delta_{CN}` is negative, we reduce C spent on N uptake and retain more C for growth .. math:: - :label: 7.23 \gamma_{FUN} = \left\{\begin{array}{lr} @@ -326,7 +325,7 @@ We then restrict the degree to which C expenditure can be reduced (to prevent un Calculation of N uptake streams from active uptake and fixation --------------------------------------------------------- +---------------------------------------------------------------- Once the final :math:`C_{nuptake}` is known, the fluxes of C to the individual pools can be derived as diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index 16aaa120a8..e8edb60222 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -270,8 +270,8 @@ data files in the mksurfdata_map tool. Schematic of translation of annual LUH2 land units to CLM5 plant and crop functional types. - .. _Figure Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool +.. _Figure Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool: -.. figure :: image3.png +.. figure:: image3.png Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool From f75874ee3c22850be25c38f21406980a7e9cc499 Mon Sep 17 00:00:00 2001 From: Charlie Koven Date: Fri, 1 Sep 2017 11:10:41 -0700 Subject: [PATCH 096/255] more changes, mainly on allocation text --- .../CLM50_Tech_Note_CN_Allocation.rst | 173 ++++-------------- .../CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 14 ++ .../CLM50_Tech_Note_Decomposition.rst | 20 +- 3 files changed, 59 insertions(+), 148 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 71eca6193a..728ae142c1 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -7,18 +7,14 @@ Introduction ----------------- -Carbon Allocation for Maintenance Respiration Costs --------------------------------------------------------- - The carbon and nitrogen allocation routines in CLM determine the fate of newly assimilated carbon, coming from the calculation of photosynthesis, and available mineral nitrogen, coming from plant uptake of mineral -nitrogen in the soil or being drawn out of plant reserves. Allocation -fluxes are determined in three steps: first :math:`CF_{GPPpot}` is -used to evaluate the potential allocation of carbon and nitrogen -assuming an unlimited nitrogen supply, then the actual nitrogen supply -is compared against the demand, and finally allocation of carbon and -nitrogen are reduced, if necessary, to match nitrogen supply and demand. +nitrogen in the soil or being drawn out of plant reserves. A significant change to CLM5 relative to prior versions is that allocation of carbon and nitrogen proceed independently rather than in a sequential manner. + + +Carbon Allocation for Maintenance Respiration Costs +-------------------------------------------------------- Allocation of available carbon on each time step is prioritized, with first priority given to the demand for carbon to support maintenance @@ -49,15 +45,15 @@ s\ :sup:`-1`): .. math:: :label: 19.2 - CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. + CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPP} } \\ {CF_{GPP} \qquad {\rm for\; }CF_{mr} >CF_{GPP} } \end{array}\right. .. math:: :label: 19.3 - CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{mr} -CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. + CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPP} } \\ {CF_{mr} -CF_{GPP} \qquad {\rm for\; }CF_{mr} >CF_{GPP} } \end{array}\right. The storage pool that supplies carbon for maintenance respiration in -excess of current :math:`CF_{GPPpot}` ( :math:`CS_{xs}`, gC +excess of current :math:`CF_{GPP}` ( :math:`CS_{xs}`, gC m\ :sup:`-2`) is permitted to run a deficit (negative state), and the magnitude of this deficit determines an allocation demand which gradually replenishes :math:`CS_{xs}`. The logic for allowing a @@ -83,16 +79,14 @@ m\ :sup:`-2` s\ :sup:`-1`) is given as .. math:: :label: 19.5 - CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPPpot} -CF_{GPP,mr} } \\ {\max (CF_{GPPpot} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPPpot} -CF_{GPP,mr} } \end{array}\right. + CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPP} -CF_{GPP,mr} } \\ {\max (CF_{GPP} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPP} -CF_{GPP,mr} } \end{array}\right. where :math:`\tau_{xs}` is the time constant (currently set to 30 days) controlling the rate of replenishment of :math:`CS_{xs}`. Note that these two top-priority carbon allocation fluxes (:math:`CF_{GPP,mr}` and :math:`CF_{GPP,xs}`) are not -stoichiometrically associated with any nitrogen fluxes, and so this -initial allocation step can proceed without reference to (or limitation -from) the available mineral nitrogen supply. +stoichiometrically associated with any nitrogen fluxes. Carbon and Nitrogen Stoichiometry of New Growth ---------------------------------------------------- @@ -104,7 +98,7 @@ growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 19.6 - CF_{avail\_ alloc} =CF_{GPPpot} -CF_{GPP,mr} -CF_{GPP,xs} . + CF_{avail\_ alloc} =CF_{GPP} -CF_{GPP,mr} -CF_{GPP,xs} . Potential allocation to new growth is calculated for all of the plant carbon and nitrogen state variables based on specified C:N ratios for @@ -140,10 +134,10 @@ favorable growth environments (Allen et al., 2005; Vanninen and Makela, .. _Table Allocation and CN ratio parameters: -.. table:: Allocation and carbon\:nitrogen ratio parameters +.. table:: Allocation and target carbon\:nitrogen ratio parameters +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ - | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`CN_{leaf}` | :math:`CN_{fr}` | :math:`CN_{lw}` | :math:`CN_{dw}` | + | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`Target CN_{leaf}` | :math:`Target CN_{fr}` | :math:`Target CN_{lw}` | :math:`Target CN_{dw}` | +==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ | NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ @@ -240,111 +234,9 @@ gN m\ :sup:`-2` s\ :sup:`-1`) as: NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . -Deployment of retranslocated nitrogen ------------------------------------------- - -In many plants, some portion of the nitrogen used to construct new -tissues is mobilized from senescing tissues, especially leaves, and -retained within the plant when the tissues are lost as litter. This -store of retranslocated nitrogen is used to supply part of the nitrogen -demand for subsequent growth (Magill et al., 1997; Oikawa et al., 2005; -Son and Gower, 1991). CLM includes one pool of retranslocated nitrogen -(:math:`NS_{retrans}`, gN m\ :sup:`-2`), and the -availability of nitrogen from this pool to support new growth -(:math:`NF_{avail\_retrans}`, gN m\ :sup:`-2` -s\ :sup:`-1`) is proportional to the plant nitrogen demand, as: - -.. math:: - :label: 19.14 - - NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) - -where :math:`NF_{retrans\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of retranslocated -nitrogen extracted from senescing tissues, -:math:`NF_{plant\_demand\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of -:math:`NF_{plant\_demand}`, and :math:`\Delta`\ *t* (s) is the -model’s biogeochemistry time step. This formulation produces an annual -cycle in the extraction of nitrogen from :math:`NS_{retrans}` -which corresponds to the annual cycle of plant nitrogen demand, and -which is scaled to give :math:`NS_{retrans}` approximately a -one-year turnover time. The minimum function prevents extraction of more -than the remaining pool of retranslocated nitrogen, which can be an -important constraint under conditions where high rates of mortality are -modifying the size of the pool. During the first year of an initial -simulation, before :math:`NF_{plant\_demand\_ann}` and -:math:`NF_{retrans\_ann}` have valid values, -:math:`NF_{avail\_retrans}` is set to 0.0. - -The actual flux of nitrogen from the retranslocated N pool into -allocation of new growth (:math:`NF_{retrans,alloc}`, gN -m\ :sup:`-2` s\ :sup:`-1`) is never greater than the plant -demand for new nitrogen: - -.. math:: - :label: 19.15 - - NF_{retrans,alloc} =\min \left(NF_{plant\_ demand} ,NF_{avail\_ retrans} \right) - -Plant nitrogen uptake from soil mineral nitrogen pool ----------------------------------------------------------- - -The total plant nitrogen demand is reduced by the nitrogen flux from -:math:`NS_{retrans}` to give the plant demand for mineral nitrogen -from the soil (:math:`NF_{plant\_demand\_soil}`, gN -m\ :sup:`-2` s\ :sup:`-1`): - -.. math:: - :label: 19.16 - - NF_{plant\_ demand\_ soil} =NF_{plant\_ demand} -NF_{retrans,alloc} . - -The combined demand from all PFTs sharing space on a soil column and the -demand from the heterotrophic community in the soil (nitrogen -immobilization demand) compete for the available soil mineral nitrogen -pool. The result of this competition is passed back to the allocation -algorithm as :math:`f_{plant\_demand}`, the fraction (from 0 to 1) -of the plant nitrogen demand which can be met given the current soil -mineral nitrogen supply and competition with heterotrophs. Plant uptake -from the soil mineral nitrogen pool is then given as: - -.. math:: - :label: 19.17 - - NF_{sminn,alloc} =NF_{plant\_ demand\_ soil} f_{plant\_ demand} - -Final carbon and nitrogen allocation +Carbon Allocation to New Growth ----------------------------------------- -The total flux of allocated nitrogen is given as: - -.. math:: - :label: 19.18 - - NF_{alloc} =NF_{retrans,alloc} +NF_{sminn,alloc} - -From the stoichiometric relationship in Eq. , the associated carbon -allocation flux is: - -.. math:: - :label: 19.19 - - CF_{alloc} =NF_{alloc} \frac{C_{allom} }{N_{allom} } . - -The downregulation of photosynthesis can then be calculated as: - -.. math:: - :label: 19.20 - - f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . - -Total allocation to new leaf carbon -(:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as: - -.. math:: - :label: 19.21 - - CF_{alloc,leaf\_ tot} =\frac{CF_{alloc} }{C_{allom} } . - There are two carbon pools associated with each plant tissue – one which represents the currently displayed tissue, and another which represents carbon stored for display in a subsequent growth period. The nitrogen @@ -416,67 +308,78 @@ tissue types are given as: CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). -The corresponding nitrogen allocation fluxes are given as: + +Nitrogen allocation +----------------------------------------- + +The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{supply}`. The total N allocated for a given organ :math:`o` is the minimum between the supply and the demand: + +.. math:: + + NF_{alloc,o} = min \left( NF_{demand, o}, NF_{supply, o} \right) + +The demand for each tissue, calculated for the tissue to remain on stoichiometry during growth, is: + .. math:: :label: 19.34 - NF_{alloc,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} + NF_{demand,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} .. math:: :label: 19.35 - NF_{alloc,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) + NF_{demand,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) .. math:: :label: 19.36 - NF_{alloc,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} + NF_{demand,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} .. math:: :label: 19.37 - NF_{alloc,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) + NF_{demand,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) .. math:: :label: 19.38 - NF_{alloc,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} + NF_{demand,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: :label: 19.39 - NF_{alloc,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) + NF_{demand,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: :label: 19.40 - NF_{alloc,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} + NF_{demand,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: :label: 19.41 - NF_{alloc,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) + NF_{demand,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) .. math:: :label: 19.42 - NF_{alloc,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} + NF_{demand,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: :label: 19.43 - NF_{alloc,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) + NF_{demand,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: :label: 19.44 - NF_{alloc,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} + NF_{demand,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: :label: 19.45 - NF_{alloc,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). + NF_{demand,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). Autotrophic Respiration ---------------------------- diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index a98069deaf..9304f87634 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -49,3 +49,17 @@ specifications of decomposition rates, and methods to rapidly equilibrate the decomposition model, is in Chapter :numref:`rst_Decomposition`. +Tissue Stoichiometry +----------------------- + +As of CLM5, vegetation tissues have a flexible stoichiometry, as +described in :ref:`Ghimire et al. (2015) `. Each +tissue has a target C\:N ratio, and nitrogen is allocated at each +timestep in order to allow the plant to best match the target +stoichiometry. Nitrogen downregulation of productivity acts by +increasing the C\:N ratio of leaves when insufficient nitrogen is +available to meet stoichiometric demands of leaf growth, thereby +reducing the N available for photosynthesis and reducing the :math:`V_{\text{c,max25}}` and +:math:`J_{\text{max25}}` terms, as described in Chapter +:numref:`rst_Photosynthetic Capacity`. Details of the flexible tissue +stoichiometry are described in Chapter :numref:`rst_CN Allocation`. diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 87f7f170bd..6863012fda 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -273,19 +273,13 @@ unitless) is calculated using a relationship from Andrén and Paustian where :math:`{\Psi}_{j}` is the soil water potential in layer *j*, :math:`{\Psi}_{min}` is a lower limit for soil water potential control on decomposition rate (in CLM5, this was -changed from a default value of -10 MPa in CLM4.5 and earlier to a -default value of -2.5 MPa). -:math:`{\Psi}_{sat,j}` (MPa) is the saturated soil water -potential, calculated using the multivariate regression model from Cosby et al. (1984): - -.. math:: - :label: 21.7) - - \Psi _{sat,\, j} =-\left(9.8e-5\right)\exp \left(\left(1.54-0.0095P_{sand,\, j} +0.0063\left(100-P_{sand,\, j} -P_{clay,\, j} \right)\right)\log \left(10\right)\right) - -where :math:`{P}_{sand,j}` and :math:`{P}_{clay,j}` are the -volume percentages of sand and clay in soil layer *j*. - +changed from a default value of -10 MPa used in CLM4.5 and earlier to a +default value of -2.5 MPa). :math:`{\Psi}_{max,j}` (MPa) is the soil +moisture at which decomposition proceeds at a moisture-unlimited +rate. The default value of :math:`{\Psi}_{max,j}` for CLM5 is updated +from a saturated value used in CLM4.5 and earlier, to a value +nominally at field capacity, with a value of -0.002 MPa + For frozen soils, the bulk of the rapid dropoff in decomposition with decreasing temperature is due to the moisture limitation, since matric potential is limited by temperature in the supercooled water formulation From 683a3185eb150276d56f9911c4acd032c3e82184 Mon Sep 17 00:00:00 2001 From: Charlie Koven Date: Wed, 6 Sep 2017 13:28:37 -0700 Subject: [PATCH 097/255] updated text in CN allocation: added N supply term equations, deleted the code on plant respiration (which has its own chapter), a couple other things. --- .../CLM50_Tech_Note_CN_Allocation.rst | 138 +++++------------- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 2 +- 2 files changed, 34 insertions(+), 106 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 728ae142c1..4db8909b42 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -249,62 +249,62 @@ storage pools (where storage is indicated with *\_stor*) for the various tissue types are given as: .. math:: - :label: 19.22 + :label: 19.14 CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} .. math:: - :label: 19.23 + :label: 19.15 CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) .. math:: - :label: 19.24 + :label: 19.16 CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} .. math:: - :label: 19.25 + :label: 19.17 CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) .. math:: - :label: 19.26 + :label: 19.18 CF_{alloc,livestem} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} f_{cur} .. math:: - :label: 19.27 + :label: 19.19 CF_{alloc,livestem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} \left(1-f_{cur} \right) .. math:: - :label: 19.28 + :label: 19.20 CF_{alloc,deadstem} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)f_{cur} .. math:: - :label: 19.29 + :label: 19.21 CF_{alloc,deadstem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right) .. math:: - :label: 19.30 + :label: 19.22 CF_{alloc,livecroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} f_{cur} .. math:: - :label: 19.31 + :label: 19.23 CF_{alloc,livecroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} \left(1-f_{cur} \right) .. math:: - :label: 19.32 + :label: 19.24 CF_{alloc,deadcroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)f_{cur} .. math:: - :label: 19.33 + :label: 19.25 CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). @@ -313,160 +313,88 @@ tissue types are given as: Nitrogen allocation ----------------------------------------- -The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{supply}`. The total N allocated for a given organ :math:`o` is the minimum between the supply and the demand: +The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{supply}`. The total N allocated for a given tissue :math:`i` is the minimum between the supply and the demand: .. math:: + :label: 19.26 - NF_{alloc,o} = min \left( NF_{demand, o}, NF_{supply, o} \right) + NF_{alloc,i} = min \left( NF_{demand, i}, NF_{supply, i} \right) The demand for each tissue, calculated for the tissue to remain on stoichiometry during growth, is: .. math:: - :label: 19.34 + :label: 19.27 NF_{demand,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} .. math:: - :label: 19.35 + :label: 19.28 NF_{demand,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) .. math:: - :label: 19.36 + :label: 19.29 NF_{demand,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} .. math:: - :label: 19.37 + :label: 19.30 NF_{demand,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) .. math:: - :label: 19.38 + :label: 19.31 NF_{demand,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: - :label: 19.39 + :label: 19.32 NF_{demand,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: - :label: 19.40 + :label: 19.33 NF_{demand,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: - :label: 19.41 + :label: 19.34 NF_{demand,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) .. math:: - :label: 19.42 + :label: 19.35 NF_{demand,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} .. math:: - :label: 19.43 + :label: 19.36 NF_{demand,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) .. math:: - :label: 19.44 + :label: 19.37 NF_{demand,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} .. math:: - :label: 19.45 + :label: 19.38 NF_{demand,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). -Autotrophic Respiration ----------------------------- - -The model treats maintenance and growth respiration fluxes separately, -even though it is difficult to measure them as separate fluxes (Lavigne -and Ryan, 1997; Sprugel et al., 1995). Maintenance respiration is -defined as the carbon cost to support the metabolic activity of existing -live tissue, while growth respiration is defined as the additional -carbon cost for the synthesis of new growth. - -13.7.1 Maintenance Respiration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Under the assumption that tissue nitrogen content is a suitable index of -cellular metabolic rate, maintenance respiration costs for live tissues -(leaf, live stem, live coarse root, and fine root) are calculated as -functions tissue nitrogen content and the relevant temperature, -following the empirical relationship reported by Ryan (1991): - -.. math:: - :label: 19.46 - - CF_{mr\_ leaf} \_ =NS_{leaf} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} +After each pool's demand is calculated, the total plant N demand is then the sum of each individual pool :math: `i` corresponding to each tissue: .. math:: - :label: 19.47 - - CF_{mr\_ livestem} \_ =NS_{livestem} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} - -.. math:: - :label: 19.48 - - CF_{mr\_ livecroot} \_ =NS_{livecroot} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} - -.. math:: - :label: 19.49 - - CF_{mr\_ froot} \_ =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} - -where :math:`MR_{base}` (= 2.525e\ :sup:`-6` gC gN\ :sup:`-1` s\ :sup:`-1`) is the base rate of maintenance -respiration per unit nitrogen content, :math:`MR_{q10}` (= 2.0) is -the temperature sensitivity for maintenance respiration, -:math:`T_{2m}` (:sup:`o`\ C) is the air temperature at 2m -height, :math:`Ts_{j}`* (:sup:`o`\ C) is the soil -temperature at level *j*, and :math:`rootfr_{j}` is the fraction -of fine roots distributed in soil level *j*. + :label: 19.39 -Note that, for woody vegetation, maintenance respiration costs are not -calculated for the dead stem and dead coarse root components. These -components are assumed to consist of dead xylem cells, with no metabolic -function. By separating the small live component of the woody tissue -(ray parenchyma, phloem, and sheathing lateral meristem cells) from the -larger fraction of dead woody tissue, it is reasonable to assume a -common base maintenance respiration rate for all live tissue types. + NF_{demand,tot} = \sum _{i=tissues} NF_{demand,i} -The total maintenance respiration cost is then given as: +and the total supply for each tissue :math: `i` is the product of the fractional demand and the total available N, calculated as the term :math: `N_{uptake}` equal to the sum of the eight N uptake streams described in the FUN model (Chapter :numref:`rst_FUN`). .. math:: - :label: 19.50 - - CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . + :label: 19.40 -13.7.2 Growth Respiration -^^^^^^^^^^^^^^^^^^^^^^^^^ + NF_{alloc,i} = N_{uptake} NF_{demand,i} / NF_{demand,tot} -Growth respiration is calculated as a factor of 0.3 times the total -carbon in new growth on a given timestep, based on construction costs -for a range of woody and non-woody tissues (Larcher, 1995). For new -carbon and nitrogen allocation that enters storage pools for subsequent -display, it is not clear what fraction of the associated growth -respiration should occur at the time of initial allocation, and what -fraction should occur later, at the time of display of new growth from -storage. Eddy covariance estimates of carbon fluxes in forest ecosystems -suggest that the growth respiration associated with transfer of -allocated carbon and nitrogen from storage into displayed tissue is not -significant (Churkina et al., 2003), and so it is assumed in CLM that -all of the growth respiration cost is incurred at the time of initial -allocation, regardless of the fraction of allocation that is displayed -immediately (i.e. regardless of the value of :math:`f_{cur}`, -section 13.5). This behavior is parameterized in such a way that if -future research suggests that some fraction of the growth respiration -cost should be incurred at the time of display from storage, a simple -parameter modification will effect the change. [1]_ -.. [1] - Parameter :math:`\text{grpnow}` in routines CNGResp and CNAllocation, currently set to 1.0, could be changed to a smaller - value to transfer some portion (1 - :math:`\text{grpnow}` ) of the growth respiration forward in time to occur at the time of growth - display from storage. diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index 32d42b564c..c94c3556ef 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -276,7 +276,7 @@ Modifications to allow variation in C:N ratios -------------------------------------------------------- The original FUN model as developed by Fisher et al. (2008) and Brzostek et al. (2015) assumes a fixed plant tissue C:N ratio. This means that in the case where N is especially limiting, all excess carbon will be utilized in an attempt to take up more Nitrogen. It has been repeatedly observed, however, that in these circumstances in real life, plants have some flexibility in the C:N stoichiometry of their tissues, and therefore, this assumption may not be realistic. **lit review on CN ratios** -Thus, in CLM5, we introduce the capacity for tissue C:N ratios to be prognostic, rather than static. Overall N and C availability (:math:`N_uptake` and :math:`C_{growth}`) and hence tissue C:N ratios, are both determined by FUN. Allocation to individual tissues is discussed in the allocation chapter +Thus, in CLM5, we introduce the capacity for tissue C:N ratios to be prognostic, rather than static. Overall N and C availability (:math:`N_{uptake}` and :math:`C_{growth}`) and hence tissue C:N ratios, are both determined by FUN. Allocation to individual tissues is discussed in the allocation chapter Here we introduce an algorithm which adjusts the C expenditure on uptake to allow varying tissue C:N ratios. Increasing C spent on uptake will directly reduce the C:N ratio, and reducing C spent on uptake (retaining more for tissue growth) will increase it. C spent on uptake is impacted by both the N cost in the environment, and the existing tissue C:N ratio of the plant. The output of this algorithm is :math:`\gamma_{FUN}`, the fraction of the ideal :math:`C_{nuptake}` calculated from the FUN equation above (**link equation**). From 476bb4ebdbff08f31ab9e2004a33b98dac1c929c Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Mon, 11 Sep 2017 11:41:50 -0600 Subject: [PATCH 098/255] Update html and fix build errors --- .../CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst | 2 +- .../tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 2 +- .../Decomposition/CLM50_Tech_Note_Decomposition.rst | 2 +- .../Introduction/CLM50_Tech_Note_Introduction.rst | 8 ++++---- doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst | 2 +- .../CLM50_Tech_Note_Plant_Respiration.rst | 8 +------- 6 files changed, 9 insertions(+), 15 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 4db8909b42..50f47d92e0 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -137,7 +137,7 @@ favorable growth environments (Allen et al., 2005; Vanninen and Makela, .. table:: Allocation and target carbon\:nitrogen ratio parameters +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ - | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`Target CN_{leaf}` | :math:`Target CN_{fr}` | :math:`Target CN_{lw}` | :math:`Target CN_{dw}` | + | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`Target CN_{leaf}` | :math:`Target CN_{fr}` | :math:`Target CN_{lw}` | :math:`Target CN_{dw}` | +==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ | NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index 9304f87634..469bc96f33 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -53,7 +53,7 @@ Tissue Stoichiometry ----------------------- As of CLM5, vegetation tissues have a flexible stoichiometry, as -described in :ref:`Ghimire et al. (2015) `. Each +described in :ref:`Ghimire et al. (2016) `. Each tissue has a target C\:N ratio, and nitrogen is allocated at each timestep in order to allow the plant to best match the target stoichiometry. Nitrogen downregulation of productivity acts by diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 6863012fda..4d72bd357e 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -754,7 +754,7 @@ cm\ :sup:`2`/yr. For non-permafrost soils, the default diffusivity is 1 cm\ :sup:`2`/yr. Model Equilibration and its Acceleration ---------------------------------------- +----------------------------------------- For transient experiments, it is usually assumed that the carbon cycle is starting from a point of relatively close equilibrium, i.e. that productivity is balanced by ecosystem carbon losses through diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index f71aed9712..69139a35fe 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -77,7 +77,7 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure Schematic of land cover change` Schematic of land cover change impacts on CLM carbon pools and fluxes. -- :numref:`Figure Schematic of translation of annual UNH land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. +- :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. - :numref:`Figure Atmospheric Delta C14` Atmospheric :math:`\mathrm{\Delta}` 14C used to drive 14C model over the historical period. @@ -149,9 +149,9 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Crop plant functional types` Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. -- :numref:`Table Crop pfts` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. +- :numref:`Table Crop plant functional types` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. -- :numref:`Table Pre- and post-grain fill CN ratios` Pre- and post-grain fill C:N ratios for crop leaf, stem, fine root, and reproductive pools. +- :numref:`Table Crop allocation parameters` Crop allocation parameters for the active crop plant functional types (pfts) in CLM5BGCCROP. Numbers in the first row correspond to the list of pfts in :numref:`Table Crop plant functional types`. - :numref:`Table Plant functional type (PFT) biogeography rules` Plant functional type (PFT) biogeography rules with respect to climate. @@ -533,7 +533,7 @@ Nitrogen for Assimilation (LUNA, :ref:`(Xu et al., 2012` and :ref:`A photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that light capture, carboxylation, and respiration are co-limiting. Allocation changes ... Fixation ??? -Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. +Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. Fertilization rates and irrigation equipped area updated based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that vary by latitude for selected crop types, grain C and N is now removed at harvest to a 1-year product pool with the carbon for the next season's crop seed removed from the grain carbon at harvest. Through the introduction of diff --git a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst index 28cf52f8a1..40b1918f46 100644 --- a/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst +++ b/doc/source/tech_note/Lake/CLM50_Tech_Note_Lake.rst @@ -139,7 +139,7 @@ for the top snow layer. Otherwise, :math:`\beta` is set equal to the near infrared fraction of the shortwave radiation reaching the surface simulated by the atmospheric model or atmospheric data model used for offline -simulations (Chapter :numref:`rst_Offline Mode`). The remainder of the shortwave radiation +simulations (Chapter :numref:`rst_Land-only Mode`). The remainder of the shortwave radiation fraction (1 :math:`{-}` :math:`\beta`) is absorbed in the lake body or soil as described in section :numref:`Radiation Penetration`. diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 7fe7be9689..c2a665d8ac 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -29,13 +29,7 @@ nitrogen pool tracks retranslocated nitrogen, mobilized from leaf tissue prior to abscission and litterfall. Altogether there are 20 state variables for vegetation carbon, and 19 for vegetation nitrogen. -Figure 13.1. Vegetation fluxes and pools. - -.. image:: image1.png - :width: 800px - :height: 800px - -Figure 13.2: Carbon and nitrogen pools. +.. _Figure Carbon and nitrogen pools: .. image:: image2.png :width: 400px From e923b35211ef4f67c835608f358c7f63f03cd62b Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Thu, 5 Oct 2017 17:15:50 -0600 Subject: [PATCH 099/255] fixed a few typos in the Introduction --- .../CLM50_Tech_Note_Introduction.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index f71aed9712..b8a4d2c30f 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -505,7 +505,7 @@ Community Earth System Model version 1.2 (CESM1.2). CLM5.0 ^^^^^^^^^^^^ -Developments for CLM5.0 build on the progress made in CLM4.5. Most major components of the model have been udpated with particularly +Developments for CLM5.0 build on the progress made in CLM4.5. Most major components of the model have been updated with particularly notable changes made to soil and plant hydrology, snow density, river modeling, carbon and nitrogen cycling and coupling, and crop modeling. Much of the focus of development centered on a @@ -520,7 +520,7 @@ sheets. The fresh snow density parameterization is updated to more realisticall dynamically adjust landunit weights means that a glacier can initiate, grow, shrink, or disappear during a simulation when two-way coupling is active. Multiple elevation classes (10 elevation classes by default) and associated temperature, rain/snow partitioning, and downwelling longwave downscaling are used for glacier landunits to account for the strong topographic elevation heterogeneity over glaciers and ice sheets. -A plant hydraulic stress routine is introduced which explicitly models water transport through the vegetation according to a simple hydraulic framework (Kennedy et al., to be submitted). The water supply equations are used to solve for vegetation water potential forced by transpiration demand and a set of layer-by-layer soil water potentials. Stomatal conductance, therefore, is a function of prognostic leaf water potential. Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. An emergent feature of the plant hydraulics is soil hydraulic redistribution. In CLM5, maximum stomatal conductance is obtained from the Medlyn conductance model :ref:(Medlyn et al., 2011)`, rather than the Ball-Berry stomatal conductance model that was utilized in CLM4.5 and prior versions of the model. The Medlyn stomatal conductance model is preferred mainly for it's more realistic behavior at low humidity levels :ref:`(Rogers et al., 2017)`. The stress deciduous vegetation phenology trigger is augmented with a antecedent precipitation requirement :ref:`(Dahlin et al. 2015)`. +A plant hydraulic stress routine is introduced which explicitly models water transport through the vegetation according to a simple hydraulic framework (Kennedy et al., to be submitted). The water supply equations are used to solve for vegetation water potential forced by transpiration demand and a set of layer-by-layer soil water potentials. Stomatal conductance, therefore, is a function of prognostic leaf water potential. Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. An emergent feature of the plant hydraulics is soil hydraulic redistribution. In CLM5, maximum stomatal conductance is obtained from the Medlyn conductance model :ref:`(Medlyn et al., 2011)`, rather than the Ball-Berry stomatal conductance model that was utilized in CLM4.5 and prior versions of the model. The Medlyn stomatal conductance model is preferred mainly for it's more realistic behavior at low humidity levels :ref:`(Rogers et al., 2017)`. The stress deciduous vegetation phenology trigger is augmented with a antecedent precipitation requirement :ref:`(Dahlin et al. 2015)`. Plant nutrient dynamics are substantially updated to resolve several deficiencies with the CLM4 and CLM4.5 nutrient cycling representation. The Fixation and Update of Nitrogen (FUN) model (refs???) is adapted for CLM :ref:`(Shi et al., 2016)` to resolve the unrealistic feature that plants get nitrogen for free in CLM4 and CLM4.5. With FUN, the fact that plants typically spend a @@ -533,25 +533,25 @@ Nitrogen for Assimilation (LUNA, :ref:`(Xu et al., 2012` and :ref:`A photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that light capture, carboxylation, and respiration are co-limiting. Allocation changes ... Fixation ??? -Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. -Fertilization rates and irrigation equipped area updated based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that +Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016`). These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. +Fertilization rates and irrigation equipped area are updated annually based on crop type and geographic region through an input dataset. The irrigation trigger is revised. Additional minor changes include crop phenological triggers that vary by latitude for selected crop types, grain C and N is now removed at harvest to a 1-year product pool with the carbon for the next season's crop seed removed from the grain carbon at harvest. Through the introduction of the capability to dynamically adjust landunit weights during a simulation, the crop model can now be run coincidentally with prescribed land use, which significantly expands the capabilities of the model. Mass-based rather than area-based wood harvest is applied. Several heat stress indices for both urban and rural areas are calculated and output by default :ref:`(Buzan et al., 2015)`. A more sophisticated and realistic building space heating and air conditioning submodel that prognoses interior building air temperature and includes more realistic space heating and air conditioning wasteheat factors is incorporated. -The fire model is the same as utilized in CLM4.5 except that a modified scheme is used to estimate the dependence of fire occurrence and spread on fuel wetness for non-peat fires outside cropland and tropical closed forests :ref:`Li and Lawrence, 2017)` and the dependence of agricultural fires on fuel load is removed. +The fire model is the same as utilized in CLM4.5 except that a modified scheme is used to estimate the dependence of fire occurrence and spread on fuel wetness for non-peat fires outside cropland and tropical closed forests :ref:`(Li and Lawrence, 2017)` and the dependence of agricultural fires on fuel load is removed. Included with the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, :ref:`Fisher et al., 2015)`. A major motivation of this development is to allow the prediction of biome boundaries directly from plant physiological traits via their competitive interactions. The version of CLM5-FATES that is supported in this release is described here??? Short blurb on what FATES can do??? Note that the classical dynamic global vegetation model (DGVM) that has been available within CLM4 and CLM4.5 remains available, though it is largely untested. The technical description of the CLM-DGVM can be found within the CLM4.5 Technical Description (:ref:`Oleson et al. 2013)`. During the course of the development of CLM5.0, it became clear that the increasing complexity of the model combined with the increasing number and range of model development projects required updates to the underlying CLM infrastructure. Many such software improvements -are included in CLM5.0 including a partial transition to an object-oriented modular software structure, extraction of many hard coded model -parameters into either the parameter file or the CLM namelist, which allows users to more readily calibrate the model for use at +are included in CLM5.0 including a partial transition to an object-oriented modular software structure. Many hard coded model +parameters have been extracted into either the parameter file or the CLM namelist, which allows users to more readily calibrate the model for use at specific locations or to conduct parameter sensitivity studies. As part of the effort to increase the scientific utility of the code, in most instances older generation parameterizations (i.e., the parameterizations -available in CLM4 or CLM4.5) are retained under namelist switches, allowing the user to revert to CLM4.5 +available in CLM4 or CLM4.5) are retained under namelist switches, allowing the user to revert to CLM4.5 from the same code base or to revert individual parameterizations where the old parameterizations are compatible with the new code. Finally, multiple vertical soil layer structures are defined and it is relatively easy to add additional structures. From a6f35a5da50e3de8f986da3fb0142b31460a7295 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Thu, 12 Oct 2017 09:49:48 -0600 Subject: [PATCH 100/255] Edits to Vegetation Phenology chapter, minor edits to Intro --- .../CLM50_Tech_Note_Introduction.rst | 2 +- ...ech_Note_Vegetation_Phenology_Turnover.rst | 23 +++++++++++-------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index daca44e404..3f5473c9bf 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -174,7 +174,7 @@ Jiafu Mao, Lei Meng, Sheri Michelson, Guo-Yue Niu, Adam Phillips, Taotao Qian, Jon Radakovich, James Randerson, Nan Rosenbloom, Steve Running, Koichi Sakaguchi, Adam Schlosser, Andrew Slater, Reto Stöckli, Ying Sun, Quinn Thomas, Peter Thornton, Mariana Vertenstein, Nicholas Viovy, Aihui Wang, Guiling Wang, -Charlie Zender, Xiaodong Zeng, and Xubin Zeng. +Zong-Liang Yang, Charlie Zender, Xiaodong Zeng, and Xubin Zeng. .. _rst_Introduction: diff --git a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst index 251e1acfcd..7ede3405e0 100644 --- a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst +++ b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst @@ -116,7 +116,7 @@ out of the transfer pool: r_{xfer\_ on} =\left\{\begin{array}{l} {{2\mathord{\left/ {\vphantom {2 t_{onset} }} \right. \kern-\nulldelimiterspace} t_{onset} } \qquad {\rm for\; }t_{onset} \ne \Delta t} \\ {{1\mathord{\left/ {\vphantom {1 \Delta t}} \right. \kern-\nulldelimiterspace} \Delta t} \qquad {\rm for\; }t_{onset} =\Delta t} \end{array}\right. and *t*\ :sub:`onset` (s) is the number of seconds remaining in -the current phenology onset growth period (Figure 14.1). The form of Eq. +the current phenology onset growth period (Figure 14.1). The form of Eq. :eq:`ZEqnNum852972` produces a flux from the transfer pool which declines linearly over the onset growth period, approaching zero flux in the final timestep. @@ -580,13 +580,16 @@ previous offset period), an accumulated soil water index SWI_{sum}^{n} =\left\{\begin{array}{l} {SWI_{sum}^{n-1} +f_{day} \qquad {\rm for\; }\Psi _{s,3} \ge \Psi _{onset} } \\ {SWI_{sum}^{n-1} \qquad \qquad {\rm for\; }\Psi _{s,3} <\Psi _{onset} } \end{array}\right. where :math:`\Psi`\ :sub:`s,3` is the soil water potential (MPa) -in the third soil layer and :math:`{\Psi}_{onset} = -2 MPa` +in the third soil layer and :math:`{\Psi}_{onset} = -0.6 MPa` is the onset soil water potential threshold. Onset triggering is -possible once :math:`{SWI}_{sum} > 15`. If the cold climate -growing degree-day accumulator is not active at the time when this -threshold is reached (see below), and if the daylength is greater than 6 +possible once :math:`{SWI}_{sum} > 15`. To avoid spurious onset triggering due to +soil moisture in the third soil layer exceeding the threshold due only to +soil water suction of water from deeper in the soil column, an additional precipitation trigger is included which requires +at least 20 mm of rain over the previous 10 days :ref:`(Dahlin et al., 2015) `. If the cold climate +growing degree-day accumulator is not active at the time when the soil moisture and precipitation +thresholds are reached (see below), and if the daylength is greater than 6 hours, then onset is triggered. Except as noted below, -:math:`{SWI}_{sum}` continues to accumulate according to Eq. during +:math:`{SWI}_{sum}` continues to accumulate according to Eq. :eq:`ZEqnNum503826` during the dormant period if the daylength criterion prevents onset triggering, and onset is then triggered at the timestep when daylength exceeds 6 hours. @@ -604,8 +607,8 @@ with subsequent accumulation calculated as: If :math:`{FD}_{sum} > 15` during the dormant period, then a cold-climate onset triggering criterion is introduced, following exactly -the growing degree-day summation (:math:`{GDD}_{sum}`) logic of Eqs. -and . At that time :math:`{SWI}_{sum}` is reset +the growing degree-day summation (:math:`{GDD}_{sum}`) logic of Eqs. :eq:`ZEqnNum510730` +and :eq:`ZEqnNum598907`. At that time :math:`{SWI}_{sum}` is reset (:math:`{SWI}_{sum} = 0`). Onset triggering under these conditions depends on meeting all three of the following criteria: :math:`{SWI}_{sum} > 15`, :math:`{GDD}_{sum} > {GDD}_{sum\_crit}`, and daylength greater than 6 hrs. @@ -613,8 +616,8 @@ depends on meeting all three of the following criteria: The following control variables are set when a new onset growth period is initiated: :math:`{SWI}_{sum} = 0`, :math:`{FD}_{sum} = 0`, :math:`{GDD}_{sum} = 0`, :math:`{n}_{days\_active} = 0`, and :math:`t_{onset} = 86400\cdot n_{days\_ on}` , where :math:`{n}_{days\_on}` is set to a constant value of 30 days. Fluxes -from storage into transfer pools occur in the timestep when a new onset growth period is initiated, and are handled identically to Eqs. - for -carbon fluxes, and to Eqs. - for nitrogen fluxes. The onset counter is decremented on each time step after initiation of the onset period, +from storage into transfer pools occur in the timestep when a new onset growth period is initiated, and are handled identically to Eqs. :eq:`ZEqnNum904388` -:eq:`ZEqnNum195642` for +carbon fluxes, and to Eqs. :eq:`ZEqnNum812152` - :eq:`ZEqnNum605338` for nitrogen fluxes. The onset counter is decremented on each time step after initiation of the onset period, until it reaches zero, signaling the end of the onset period: .. math:: From c663ab8c96f10f64604154ba3b34b4e76db74783 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 12 Oct 2017 16:38:36 -0600 Subject: [PATCH 101/255] Fixes for lnd <-> atm coupling fields Added atmosphere model's surface height as a required input, and 10-m wind speed as an output. Also fixed some typos. --- .../tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 10315b7d98..e21c8e05d0 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -425,6 +425,8 @@ conditions from the current time step. +======================================================+================================================+=================================================+ | :sup:`1`\ Reference height | :math:`z'_{atm}` | m | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ + | Atmosphere model's surface height | :math:`z_{surf,atm}` | m | + +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Zonal wind at :math:`z_{atm}` | :math:`u_{atm}` | m s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Meridional wind at :math:`z_{atm}` | :math:`v_{atm}` | m s\ :sup:`-1` | @@ -451,7 +453,7 @@ conditions from the current time step. +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | Incident diffuse near-infrared solar radiation | :math:`S_{atm} \, \downarrow _{nir}` | W m\ :sup:`-2` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ - | Carbon dioxide (CO:sub:`2`) concentration | :math:`c_{a}` | ppmv | + | Carbon dioxide (CO\ :sub:`2`) concentration | :math:`c_{a}` | ppmv | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ | :sup:`3`\ Aerosol deposition rate | :math:`D_{sp}` | kg m\ :sup:`-2` s\ :sup:`-1` | +------------------------------------------------------+------------------------------------------------+-------------------------------------------------+ @@ -471,7 +473,7 @@ reference heights for temperature, wind, and specific humidity :math:`z_{atm,\, w}` ) are required. These are set equal to\ :math:`z_{atm}` . -:sup:`2`\ The placeCAM provides convective and large-scale liquid +:sup:`2`\ CAM provides convective and large-scale liquid and solid precipitation, which are added to yield total liquid precipitation :math:`q_{rain}` and solid precipitation :math:`q_{sno}` . @@ -566,6 +568,8 @@ calculated from molar ratio and the atmospheric pressure +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Specific humidity at 2 meter height | :math:`q_{2m}` | kg kg\ :sup:`-1` | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ + | Wind speed at 10 meter height | :math:`u_{10m}` | m s\ :sup:`-1` | + +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Snow water equivalent | :math:`W_{sno}` | m | +---------------------------------------+------------------------------------------------+--------------------------------------------------------------+ | Aerodynamic resistance | :math:`r_{am}` | s m\ :sup:`-1` | From 429985bf7716e1ecd287b0c206da98f38d3d5743 Mon Sep 17 00:00:00 2001 From: Charlie Koven Date: Fri, 10 Nov 2017 15:46:37 -0800 Subject: [PATCH 102/255] made some changes to the Allocation Chapter --- .../CLM50_Tech_Note_CN_Allocation.rst | 38 ++++++++----------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 50f47d92e0..37d3f0a10f 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -3,6 +3,13 @@ Carbon and Nitrogen Allocation ============================== +Summary of CLM5.0 updates relative to the CLM4.5 +----------------------------------------------------- +- CLM5 now defaults to a static allocation to woody biomass rather than the dynamic allocation term used in CLM4.5. The dynamic allocation is stil lkept as an option, for details, see the CLM4.5 Tech Note. + + - CLM5 now includes flexible C:N ratios of all plant tissues, which allows allocation of carbon to occur separately from allocation of nitrogen, thus removing the requirement to downregulate photosynthesis based on the instantaneous stoichiometric needs of allocation. + + Introduction ----------------- @@ -13,19 +20,19 @@ and available mineral nitrogen, coming from plant uptake of mineral nitrogen in the soil or being drawn out of plant reserves. A significant change to CLM5 relative to prior versions is that allocation of carbon and nitrogen proceed independently rather than in a sequential manner. -Carbon Allocation for Maintenance Respiration Costs --------------------------------------------------------- +Carbon Allocation to Cover Prior-Timestep Maintenance Respiration Costs +---------------------------------------------------------------------------- Allocation of available carbon on each time step is prioritized, with first priority given to the demand for carbon to support maintenance -respiration of live tissues (section 13.7). Second priority is to -replenish the internal plant carbon pool that supports maintenance -respiration during times when maintenance respiration exceeds +respiration of live tissues (Chapter :numref:`rst_Plant Respiration`) and Nitrogen acquisition costs (Chapter :numref:`rst_FUN`). Second priority is to +replenish the plant carbon deficit pool that balances maintenance +respiration that occurs during times when maintenance respiration exceeds photosynthesis (e.g. at night, during winter for perennial vegetation, or during periods of drought stress) (Sprugel et al., 1995). Third priority is to support growth of new tissues, including allocation to storage pools from which new growth will be displayed in subsequent time -steps. +steps, as well as growth respiration costs. The total maintenance respiration demand (:math:`CF_{mr}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as a function of @@ -116,21 +123,6 @@ Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined as consta constant for all PFTs, based on construction costs for a range of woody and non-woody tissues (Larcher, 1995). -The model includes a dynamic allocation scheme for woody vegetation -(parameter :math:`a_{3}` = -1, :numref:`Table Allocation and CN ratio parameters`), in which case the -ratio for carbon allocation between new stem and new leaf increases with -increasing net primary production (NPP), as - -.. math:: - :label: 19.8 - - a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 - -where :math:`NPP_{ann}` is the annual sum of NPP from the previous -year. This mechanism has the effect of increasing woody allocation in -favorable growth environments (Allen et al., 2005; Vanninen and Makela, -2005) and during the phase of stand growth prior to canopy closure -(Axelsson and Axelsson, 1986). .. _Table Allocation and CN ratio parameters: @@ -382,14 +374,14 @@ The demand for each tissue, calculated for the tissue to remain on stoichiometry NF_{demand,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). -After each pool's demand is calculated, the total plant N demand is then the sum of each individual pool :math: `i` corresponding to each tissue: +After each pool's demand is calculated, the total plant N demand is then the sum of each individual pool :math:`i` corresponding to each tissue: .. math:: :label: 19.39 NF_{demand,tot} = \sum _{i=tissues} NF_{demand,i} -and the total supply for each tissue :math: `i` is the product of the fractional demand and the total available N, calculated as the term :math: `N_{uptake}` equal to the sum of the eight N uptake streams described in the FUN model (Chapter :numref:`rst_FUN`). +and the total supply for each tissue :math:`i` is the product of the fractional demand and the total available N, calculated as the term :math:`N_{uptake}` equal to the sum of the eight N uptake streams described in the FUN model (Chapter :numref:`rst_FUN`). .. math:: :label: 19.40 From 8226193dd1dbba312165b4097d020379455a90c3 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Tue, 14 Nov 2017 09:41:39 -0700 Subject: [PATCH 103/255] Updates to Carbon isotopes chapter --- .../CLM50_Tech_Note_Introduction.rst | 2 - .../Isotopes/CLM50_Tech_Note_Isotopes.rst | 60 +++++-------------- .../References/CLM50_Tech_Note_References.rst | 26 +------- 3 files changed, 18 insertions(+), 70 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 3f5473c9bf..69ad12b91f 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -79,8 +79,6 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. -- :numref:`Figure Atmospheric Delta C14` Atmospheric :math:`\mathrm{\Delta}` 14C used to drive 14C model over the historical period. - **LIST OF TABLES** - :numref:`Table Plant functional types` Plant functional types diff --git a/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst b/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst index 093b7d7a37..43692205b8 100644 --- a/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst +++ b/doc/source/tech_note/Isotopes/CLM50_Tech_Note_Isotopes.rst @@ -22,13 +22,13 @@ General Form for Calculating :sup:`13`\ C and :sup:`14`\ C Flux -------------------------------------------------------------------------------- In general, the flux of :sup:`13`\ C and corresponding to a given -flux of total C (*CF\ :math:`{}_{13C}`* and *CF\ :math:`{}_{totC}`*, -respectively) is determined by *CF\ :math:`{}_{totC}`*, the masses of +flux of total C (:math:`{CF}_{13C}` and :math:`{CF}_{totC}`, +respectively) is determined by :math:`{CF}_{totC}`, the masses of :sup:`13`\ C and total C in the upstream pools -(*CS\ :math:`{}_{13C\_up}`* and *CS\ :math:`{}_{totC\_up}`*, +(:math:`{CS}_{13C\_up}` and :math:`{CS}_{totC\_up}`, respectively, i.e. the pools *from which* the fluxes of :sup:`13`\ C and total C originate), and a fractionation factor, -*f\ :math:`{}_{frac}`*: +:math:`{f}_{frac}`: .. math:: :label: ZEqnNum629812 @@ -36,7 +36,7 @@ respectively, i.e. the pools *from which* the fluxes of CF_{13C} =\left\{\begin{array}{l} {CF_{totC} \frac{CS_{13C\_ up} }{CS_{totC\_ up} } f_{frac} \qquad {\rm for\; }CS_{totC} \ne 0} \\ {0\qquad {\rm for\; }CS_{totC} =0} \end{array}\right\} If the :math:`{f}_{frac}` = 1.0 (no fractionation), then the fluxes -:math:`{CF}_{13C}` and :math:`{CF}_{totC}`* will be in simple +:math:`{CF}_{13C}` and :math:`{CF}_{totC}` will be in simple proportion to the masses :math:`{CS}_{13C\_up}` and :math:`{CS}_{totC\_up}`. Values of :math:`{f}_{frac} < 1.0` indicate a discrimination against the heavier isotope (:sup:`13`\ C) in the flux-generating process, while @@ -55,8 +55,8 @@ described in units that implicitly correct out the fractionation of Isotope Symbols, Units, and Reference Standards ---------------------------------------------------- -Carbon has two primary stable isotopes, :math:`{}^{12}`\ C and -:sup:`13`\ C. :math:`{}^{12}`\ C is the most abundant, comprising +Carbon has two primary stable isotopes, :sup:`12`\ C and +:sup:`13`\ C. :sup:`12`\ C is the most abundant, comprising about 99% of all carbon. The isotope ratio of a compound, :math:`{R}_{A}`, is the mass ratio of the rare isotope to the abundant isotope @@ -133,7 +133,7 @@ Carbon Isotope Discrimination During Photosynthesis Photosynthesis is modeled in CLM as a two-step process: diffusion of CO\ :sub:`2` into the stomatal cavity, followed by enzymatic -fixation (Chapter 8). Each step is associated with a kinetic isotope +fixation (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`). Each step is associated with a kinetic isotope effect. The kinetic isotope effect during diffusion of CO\ :sub:`2` through the stomatal opening is 4.4‰. The kinetic isotope effect during fixation of CO\ :sub:`2` with Rubisco is @@ -173,39 +173,17 @@ calculation as follows: c_{i} =pCO_{2} -a_{n} p\frac{\left(1.4g_{s} \right)+\left(1.6g_{b} \right)}{g_{b} g_{s} } -and - -.. math:: - :label: 30.11) - - c_{i}^{*} =pCO_{2} -a_{n} \left(1-d\right)p\frac{\left(1.4g_{s} \right)+\left(1.6g_{b} \right)}{g_{b} g_{s} } - -where :math:`a_n` is net carbon assimilation during photosynthesis, -:math:`d` is downscaling factor due to nitrogen limitation, :math:`p` is +where :math:`a_n` is net carbon assimilation during photosynthesis, :math:`p` is atmospheric pressure, :math:`g_b` is leaf boundary layer conductance, and :math:`g_s` is leaf stomatal conductance. -The fractionation factor :math:`{\alpha }_{psn}` and net assimilation -:math:`a_n` are calculated during the radiation time-step in -CanopyFluxesMod.F90, whereas the downscaling factor :math:`d` is not -calculated until after the nitrogen limitation is computed in -CNAllocationMod.F90. That results in a difference between the actual -photosynthesis, which is downscaled by :math:`d`, and the potential -photosynthesis. In order to overcome this mismatch, downscaling due to -nitrogen limitation is factored in the calculation of the kinetic -isotope effect during fixation by defining a downscaled version of -intracellular CO\ :sub:`2` (:math:`c^*_i`), as a first order -approximation. However, since nitrogen down-regulation is calculated -after the photosynthesis calculation, down-regulation coefficient -calculated in the previous time step needs to be used. - Isotopic fractionation code is compatible with multi-layered canopy parameterization; i.e., it is possible to calculate varying discrimination rates for each layer of a multi-layered canopy. However, as with the rest of the photosynthesis model, the number of canopy layers is currently set to one by default. -:sup:`14`\ C radioactive decay and historical atmospheric :sup:`14`\ C concentrations +:sup:`14`\ C radioactive decay and historical atmospheric :sup:`14`\ C and :sup:`13`\ C concentrations ------------------------------------------------------------------------------------------------------ In the preindustrial biosphere, radioactive decay of :sup:`14`\ C @@ -226,18 +204,10 @@ accelerated by the same degree as the decomposition, such that the :sup:`14`\ C value of these pools is in equilibrium when taken out of the spinup mode. -For variation of atmospheric :sup:`14`\ C over the historical -period, :math:`\mathrm{\Delta}`\ :sup:`14`\ C values can be set to -either fixed concentration (:math:`\mathrm{\Delta}`\ :sup:`14`\ C = 0‰) -or time-varying concentrations read in from a file. A default file -is provided that is based on a spline fit through several observational -datasets spanning the 20\ :math:`{}^{th}` century: (Levin and Kromer, -2004; Manning and Melhuish, 1994; Nydal and Lövseth, 1996; Turnbull et -al. 2007). This is shown in Figure 25.1. - -.. _Figure Atmospheric Delta C14: +For variation of atmospheric :sup:`14`\ C and :sup:`13`\ C over the historical +period, :math:`\mathrm{\Delta}`\ :sup:`14`\ C and :math:`\mathrm{\Delta}`\:sup:`13`\ C values can be set to +either fixed concentrations +or time-varying concentrations read in from a file. A default file is provided that spans the historical period (:ref:`Graven et al., 2017 `). For +:math:`\mathrm{\Delta}`\ :sup:`14`\ C, values are provided and read in for three latitude bands (30 :sup:`o`\ N-90 :sup:`o`\ N, 30 :sup:`o`\ S-30 :sup:`o`\ N, and 30 :sup:`o`\ S-90 :sup:`o`\ S). -.. figure:: image1.png - Atmospheric :math:`\mathrm{\Delta}`\ :sup:`14`\ C - used to drive :sup:`14`\ C model over the historical period. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index d7a5887778..048fa076c0 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -615,6 +615,9 @@ Graham, S.T., Famiglietti, J.S., and Maidment, D.R. 1999. Five-minute, use in regional and global hydrologic and climate system modeling studies. Water Resour. Res. 35:583-587. +.. _Gravenetal2017: + +Graven, H., C. E. Allison, D. M. Etheridge, S. Hammer, R. F. Keeling, I. Levin, H. A. J. Meijer, M. Rubino, P. P. Tans, C. M. Trudinger, B. H. Vaughn and J. W. C. White (2017) Compiled records of carbon isotopes in atmospheric CO2 for historical simulations in CMIP6, Geoscientific Model Development, in review. doi: 10.5194/gmd-2017-166. .. _GrenfellWarren1999: Grenfell, T.C., and Warren, S.G. 1999. Representation of a nonspherical @@ -1032,11 +1035,6 @@ Letts, M.G., Roulet, N.T., Comer, N.T., Skarupa, M.R., and Verseghy, D.L. 2000. Parametrization of peatland hydraulic properties for the Canadian Land Surface Scheme. Atmos.-Ocean 38:141-160. -.. _LevinKromer2004: - -Levin, I. and Kromer, B. 2004. The tropospheric 14CO2 level in -mid-latitudes of the Northern Hemisphere (1959-2003) Radiocarbon 46:1. - .. _Levisetal2003: Levis, S., Wiedinmyer, C., Bonan, G.B., and Guenther, A. 2003. @@ -1203,12 +1201,6 @@ DOI:10.1029/2005JD006653. Makela, A. 2002. Derivation of stem taper from the pipe model theory in a carbon balance framework. Tree Phys. 22:891-905. -.. _Manning, M.R. and Melhuish, W.H. 1994. Trends: A Compendium of Data on - -Manning, M.R. and Melhuish, W.H. 1994. Trends: A Compendium of Data on -Global Change. Carbon Dioxide Information Analysis Center,. Oak Ridge -National Laboratory, U.S. Department of Energy, Oak Ridge, Tenn., U.S.A. - .. _Maoetal2012: Mao, J., Thornton, P.E., Shi, X., Zhao, M., and Post, W.M. 2012. Remote @@ -1337,12 +1329,6 @@ Niu, G.-Y., and Yang, Z.-L. 2007. An observation-based formulation of snow cover fraction and its evaluation over large North American river basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674. -.. _NydalLovseth1996: - -Nydal, R. and Lövseth, K. 1996. Carbon-14 Measurements In Atmospheric -CO2 From Northern And Southern Hemisphere Sites, 1962-1993, Carbon -Dioxide Information Analysis Center. - .. _Oikawaetal2005: Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and @@ -1974,12 +1960,6 @@ burn area in western Canadian peatlands and its relationship to fire weather indices. Global Biogeochem. Cycles 18:GB4014. DOI:10.1029/2004GB002222. -.. _Turnbulletal2007: - -Turnbull, J.C. et al. 2007. A new high precision (CO2)-C-14 time series -for North American continental air. Journal of Geophysical -Research-Atmospheres 112(D11). - .. _Tyeetal2005: Tye, A.M., et al. 2005. The fate of N-15 added to high Arctic tundra to From 0c52f7524498e6031b6bfe1e86b66a40371c3628 Mon Sep 17 00:00:00 2001 From: William Wieder Date: Fri, 17 Nov 2017 11:07:58 -0700 Subject: [PATCH 104/255] updated External N cycle, Plant Respiration, refs --- ...LM50_Tech_Note_External_Nitrogen_Cycle.rst | 325 +++++++----------- .../CLM50_Tech_Note_Plant_Respiration.rst | 112 +++--- .../References/CLM50_Tech_Note_References.rst | 20 +- 3 files changed, 182 insertions(+), 275 deletions(-) diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst index 69959b0a8c..6a4ff5479d 100644 --- a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst @@ -3,8 +3,26 @@ External Nitrogen Cycle =========================== +.. _Summary of CLM5.0 updates relative to the CLM4.5: + +Summary of CLM5.0 updates relative to the CLM4.5 +----------------------------------------------------- + +We describe external inputs to the nitrogen cycle in CLM5.0.  Much of the following information appeared in the CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `) as well as :ref:`Koven et al. (2013) `. + +CLM5.0 includes the following changes to terrestrial nitrogen inputs: + +- Time varrying deposition of reactive nitrogen. In off-line runs this changes monthly. In coupled simulations N deposition is passed at the coupling timestep (e.g., half-hourly). + +- Asymbiotic (or free living) N fixation is a function of evapotranspiration and is added to the inorganic nitrogen (NH\ :sub:`4`\ :sup:`+`) pool (described below). + +- Symbiotic N fixation is handled by the FUN model (chapter :numref:`rst_FUN`) and is passed straight to the plant, not the mineral nitrogen pool. + +Overview +----------------------------------------------------- + In addition to the relatively rapid cycling of nitrogen within the plant -– litter – soil organic matter system, CLM also represents several slow +– litter – soil organic matter system, CLM also represents several processes which couple the internal nitrogen cycle to external sources and sinks. Inputs of new mineral nitrogen are from atmospheric deposition and biological nitrogen fixation. Losses of mineral nitrogen @@ -12,19 +30,12 @@ are due to nitrification, denitrification, leaching, and losses in fire. While the short-term dynamics of nitrogen limitation depend on the behavior of the internal nitrogen cycle, establishment of total ecosystem nitrogen stocks depends on the balance between sources and -sinks in the external nitrogen cycle. - -CLM includes two separate treatments of the slow nitrogen cycle. The -first is the original CLM-CN formulations, which includes a single soil -mineral nitrogen pool to represent both -NO\ :sub:`3`\ :sup:`-` and NH\ :sub:`4`\ :sup:`+`, and with nitrogen losses via -denitrification calculated as a constant fraction of mineralization plus -a fixed first-order loss of unutilized mineral nitrogen at the end of -every timestep. The second is based on the Century N-gas model; this +sinks in the external nitrogen cycle (:ref:`Thomas et al. 2015 `). + +As with CLM4.5, CLM5.0 represents inorganic N transformations based on the Century N-gas model; this includes separate NH\ :sub:`4`\ :sup:`+` and NO\ :sub:`3`\ :sup:`-` pools, as well as -environmentally controlled nitrification and denitrification rates. Both -are described below. +environmentally controlled nitrification and denitrification rates that is described below. Atmospheric Nitrogen Deposition ------------------------------------ @@ -32,7 +43,8 @@ Atmospheric Nitrogen Deposition CLM uses a single variable to represent the total deposition of mineral nitrogen onto the land surface, combining wet and dry deposition of NO\ :sub:`y` and NH\ :sub:`x` as a single flux -(:math:`{NF}_{ndep\_sminn}`, gN m\ :sup:`-2` s\ :sup:`-1`). This flux is intended to represent total reactive +(:math:`{NF}_{ndep\_sminn}`, gN m\ :sup:`-2` s\ :sup:`-1`). This flux +is intended to represent total reactive nitrogen deposited to the land surface which originates from the following natural and anthropogenic sources (Galloway et al. 2004): formation of NO\ :sub:`x` during lightning, @@ -49,18 +61,25 @@ agricultural soils, NH\ :sub:`3` emission from agricultural crops, NH\ :sub:`3` emission from agricultural animal waste, and NH\ :sub:`3` emission from human waste and waste water. The deposition flux is provided as a spatially and (potentially) temporally -varying dataset (see section 2.2.3 for a description of the default +varying dataset (see section :numref:`Atmospheric Coupling` for a description of the default input dataset). -In the CLM-CN mineral N pool model, the nitrogen deposition flux is -assumed to enter the soil mineral nitrogen pool -(:math:`{NS}_{sminn}`) directly; while in the Century-based model, -all of the nitrogen is assumed to enter the -NH\ :sub:`4`\ :sup:`+` pool. Real pathways for wet and dry +The nitrogen deposition flux is assumed to enter the NH\ :sub:`4`\ :sup:`+` pool, +and is vertically distributed throughout the soil profile. Although N deposition +inputs include both oxidized and reduced forms, CLM5 only reads in total +N deposition. This approach is held over from CLM4.0, which only represented a +single mineral nitrogen pool, however, real pathways for wet and dry nitrogen deposition can be more complex than currently represented in -the CLM-CN, including release from melting snowpack and direct foliar -uptake of deposited NO\ :sub:`y` (e.g. Tye et al. 2005; Vallano -and Sparks, 2007). +the CLM5.0, including release from melting snowpack and direct foliar +uptake of deposited NO\ :sub:`y` (:ref:`Tye et al. 2005 `; +:ref:`Vallano and Sparks, 2007 `). + +In offline (uncoupled) CLM5.0 simulations monthly +estimates of N deposition are provided, as opposed to decadal files +supplied with previous versions of the model. In coupled simulations, +N depositions fluxes are passed to the land model at the frequency of +the time step (every half hour) through the coupler. + Biological Nitrogen Fixation --------------------------------- @@ -69,56 +88,53 @@ The fixation of new reactive nitrogen from atmospheric N\ :sub:`2` by soil microorganisms is an important component of both preindustrial and modern-day nitrogen budgets, but a mechanistic understanding of global-scale controls on biological nitrogen fixation (BNF) is still -only poorly developed (Cleveland et al. 1999; Galloway et al. 2004). -Cleveland et al. (1999) suggested empirical relationships that predict -BNF as a function of either evapotranspiration rate or net primary -productivity for natural vegetation. CLM assumes that BNF is a function -of net primary production (:math:`{CF}_{ann\_NPP}`, gC m\ :sup:`-2` y\ :sup:`-1`). The rationale for choosing net -primary production over evapotranspiration as the predictor is that the -two are well-correlated (Parton et al. 1993; Running et al. 1989), and -the use of primary production also introduces a known dependence of BNF -on the carbon supply to nitrogen fixing microorganisms (Cleveland et al. -1999). The expression used is: +only poorly developed (:ref:`Cleveland et al. 1999 `; +:ref:`Galloway et al. 2004 `). CLM5.0 uses the FUN +model (chapter :numref:`rst_FUN`) to +calculate the carbon cost and nitrogen acquired through symbotic +nitrogen fixation. This nitrogen is immediately available to plants. + +:ref:`Cleveland et al. (1999) ` suggested +an empirical relationships that predicts BNF as a function of +either evapotranspiration rate or net primary productivity for +natural vegetation. CLM5.0 adopts the evapotranspiration approach +to calculate asymbiotic, or free-living, N fixation. This function +has been modified from the :ref:`Cleveland et al. (1999) +` estimates to provide lower estimate of +free-living nitrogen fixation in CLM5.0 +(:math:`{CF}_{ann\_ET}`, mm yr\ :sup:`-1`). +This moves away from the NPP approach used in CLM4.0 and 4.5 and +avoids unrealistically increasing freeliving rates of N fixation +under global change scenarios (:ref:`Wieder et al. 2015 +` The expression used is: .. math:: - :label: ZEqnNum802819: + :label: 22.1) - NF_{nfix,sminn} ={1.8\left(1-\exp \left(-0.003{\kern 1pt} CF_{ann\_ NPP} \right)\right)\mathord{\left/ {\vphantom {1.8\left(1-\exp \left(-0.003{\kern 1pt} CF_{ann\_ NPP} \right)\right) \left(86400\cdot 365\right)}} \right. \kern-\nulldelimiterspace} \left(86400\cdot 365\right)} + NF_{nfix,sminn} ={0.0006\left(0.0117+CF_{ann\_ ET}\right)\mathord{\left/ {\vphantom {0.0006\left(0.0117+ CF_{ann\_ ET}\right) \left(86400\cdot 365\right)}} \right. \kern-\nulldelimiterspace} \left(86400\cdot 365\right)} + +Where :math:`{NF}_{nfix,sminn}` (gN m\ :sup:`-2` s\ :sup:`-1`) is the rate of free-living nitrogen fixation in :numref:`Figure Biological nitrogen fixation`. -where :math:`{NF}_{nfix,sminn}` (gN m\ :sup:`-2` s\ :sup:`-1`) is the rate of BNF. Eq. is plotted over a range of -annual NPP in Figure 16.1. .. _Figure Biological nitrogen fixation: .. figure:: image1.png - Biological nitrogen fixation as a function of annual net - primary production. - -Because of the empirical nature of this NPP-BNF relationship, the -timescale for calculating NPP and thus BNF is unconstrained. Using -annual NPP, as in CLM4.0, introduces an error at high latitudes because -the aseasonal BNF inputs mean that much of the nitrogen is added when -the vegetation is dormant and may be lost before it is ever taken up by -vegetation. Thus an option was added to CLM to allow for an exponential -relaxation (with default e-folding time of 10 days) calculation of NPP, -and BNF calculated from that using equation 16.1. - -As with Atmospheric N deposition, BNF N inputs are added directly to the -mineral N pools. In the CLM-CN N model, this is the single mineral N -pool; in the Century-based model, this is the + Free-living nitrogen fixation as a function of annual evapotranspiration. Results here show annual N inputs from free-living N fixations, but the model actually calculates inputs on a per second basis. + +As with Atmospheric N deposition, free-living N inputs are added directly to the NH\ :sub:`4`\ :sup:`+` pool. Nitrification and Denitrification Losses of Nitrogen --------------------------------------------------------- -In order to better understand the structural uncertainty in -biogeochemical responses to climate change, CLM includes two alternate -representations of the mineral N transformations and losses that define -the slow N cycle. Each of these is described below. - -16.3.1 CLM-CN formulation -^^^^^^^^^^^^^^^^^^^^^^^^^ +Nitrification is an autotrophic process that converts less mobile ammonium +ions into nitrate, that can more easily be lost from soil systems by leaching +or denitrification. The process catalyzed by ammonia oxidizing archaea and +bacteria that convert ammonium (NH\ :sub:`4`\ :sup:`+`) into nitrite, which +is subsequently oxidized into nitrate (NO\ :sub:`3`\ :sup:`-`). Conditions +favoring nitrification include high NH\ :sub:`4`\ :sup:`+` concentrations, +well aerated soils, a neutral pH and warmer temperatures. Under aerobic conditions in the soil oxygen is the preferred electron acceptor supporting the metabolism of heterotrophs, but anaerobic @@ -127,153 +143,59 @@ an electron acceptor (e.g. *Pseudomonas* and *Clostridium*) supporting respiration. This process, known as denitrification, results in the transformation of nitrate to gaseous N\ :sub:`2`, with smaller associated production of NO\ :sub:`x` and N\ :sub:`2`\ O. It -is typically assumed that nitrogen fixation and denitrification were -approximately balanced in the preindustrial biosphere (Galloway et al. -2004). It is likely that denitrification can occur within anaerobic +is typically assumed that nitrogen fixation and denitrification +were approximately balanced in the preindustrial biosphere ( +:ref:`Galloway et al. 2004 `). It is likely +that denitrification can occur within anaerobic microsites within an otherwise aerobic soil environment, leading to large global denitrification fluxes even when fluxes per unit area are -rather low (Galloway et al. 2004). - -Because the vertical distribution of soil organic matter is not resolved -explicitly in CLM-CN, a simple denitrification parameterization is used -that treats denitrification as a constant fraction of gross nitrogen -mineralization. At each step in the decomposition cascade, if the -transformation from an upstream to a downstream pool is predicted to -mineralize (as opposed to immobilize) nitrogen, then a constant fraction -of the nitrogen mineralization flux is assumed to be lost via -denitrification. Due to large uncertainties in the mechanistic -understanding of the environmental controls on denitrification, no -modifications to the denitrification fraction are made for different -soil moisture conditions. This is identified as a high-priority area for -future model development. - -Denitrification fluxes associated with gross mineralization in the -decomposition cascade are calculated as follows: - -.. math:: - :label: 22.2) - - NF_{denit,Lit1\to SOM1} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} >0} \\ {-NF_{pot\_ min,Lit1\to SOM1} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit1\to SOM1} \le 0} \end{array}\right. - -.. math:: - :label: 22.3) - - NF_{denit,Lit2\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} >0} \\ {-NF_{pot\_ min,Lit2\to SOM2} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit2\to SOM2} \le 0} \end{array}\right. - -.. math:: - :label: 22.4) - - NF_{denit,Lit3\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} >0} \\ {-NF_{pot\_ min,Lit3\to SOM3} {\kern 1pt} f_{denit} \qquad \qquad {\rm for\; }NF_{pot\_ min,Lit3\to SOM3} \le 0} \end{array}\right. - -.. math:: - :label: 22.5) - - NF_{denit,SOM1\to SOM2} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} >0} \\ {-NF_{pot\_ min,SOM1\to SOM2} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM1\to SOM2} \le 0} \end{array}\right. - -.. math:: - :label: 22.6) - - NF_{denit,SOM2\to SOM3} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} >0} \\ {-NF_{pot\_ min,SOM2\to SOM3} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM2\to SOM3} \le 0} \end{array}\right. - -.. math:: - :label: 22.7) - - NF_{denit,SOM3\to SOM4} =\left\{\begin{array}{l} {0\qquad \qquad \qquad \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} >0} \\ {-NF_{pot\_ min,SOM3\to SOM4} {\kern 1pt} f_{denit} \qquad {\rm for\; }NF_{pot\_ min,SOM3\to SOM4} \le 0} \end{array}\right. - -.. math:: - :label: 22.8) - - NF_{denit,SOM4} =-NF_{pot\_ min,SOM4} - -where :math:`{f}_{denit} = 0.01` is the constant denitrification -fraction of gross mineralization, and the denitrification fluxes are -assumed to be leaving the soil mineral nitrogen pool -(:math:`{NS}_{sminn}`) and entering the atmosphere. The speciation -of gaseous nitrogen fluxes entering the atmosphere (e.g. -N\ :sub:`2` vs. NO\ :sub:`x` or N\ :sub:`2`\ O) is not -specified. Providing an explicit speciation of these nitrogen losses is -another high-priority area for future model development. - -The model includes one other denitrification pathway, intended to -represent the observed losses of mineral nitrogen in systems -experiencing nitrogen saturation. One reason this mechanism has been -included is in anticipation of an agricultural fertilization flux, -provided either through a prescribed dataset or through a prognostic -agricultural management routine. The model does not currently include an -explicit representation of the fertilization flux, but when it is -introduced, it will be necessary to account for the substantial -denitrification losses associated with high nitrate concentrations in -some heavily fertilized agricultural soils. Nitrogen saturation can also -occur in natural vegetation systems, especially under conditions of high -atmospheric nitrogen deposition, and so this mechanism plays a useful -role even prior to the introduction within the model of agricultural -fertilization. - -For the purpose of this calculation, nitrogen saturation is evaluated on -each timestep, by comparing the total demand for new mineral nitrogen -from plants and immobilization with the available soil mineral nitrogen -pool. The denitrification of excess soil mineral nitrogen is non-zero -whenever the supply of mineral nitrogen exceeds the demand: - -.. math:: - :label: 22.9) - - NF_{sminn,denit} =\left\{\begin{array}{l} {\left(\frac{NS_{sminn} }{\Delta t} \right)-NF_{total\_ demand} f_{dnx} \qquad {\rm for\; }NF_{total\_ demand} \Delta t`). CLM includes a detailed representation of nitrification and -denitrification based on the Century N model (Parton et al. 1996, 2001; -del Grosso et al. 2000). In this approach, nitrification of -NH\ :sub:`4`\ :sup:`+` to NO\ :sub:`3`\ :sup:`-`` +denitrification based on the Century N model (:ref:`Parton +et al. 1996 `, :ref:`2001 `; +:ref:`del Grosso et al. 2000 `). In this +approach, nitrification of NH\ :sub:`4`\ :sup:`+` to NO\ :sub:`3`\ :sup:`-` is a function of temperature, moisture, and pH: .. math:: - :label: 22.11) + :label: 22.2) f_{nitr,p} =\left[NH_{4} \right]k_{nitr} f\left(T\right)f\left(H_{2} O\right)f\left(pH\right) where :math:`{f}_{nitr,p}` is the potential nitrification rate (prior to competition for NH\ :sub:`4`\ :sup:`+` by plant uptake and N immobilization), :math:`{k}_{nitr}` is the maximum -nitrification rate (10 % day\ :math:`\mathrm{-}`\ 1, (Parton et al. -2001)), and *f(T)* and *f(H\)*\ :sub:`2`\ O) are rate modifiers for -temperature and moisture content. CLM uses the same rate modifiers as -are used in the decomposition routine. *f(pH)* is a rate modifier for -pH; however, because CLM does not calculate pH, instead a fixed pH value -of 6.5 is used in the pH function of Parton et al. (1996). +nitrification rate (10 % day\ :math:`\mathrm{-}`\ 1, +(:ref:`Parton et al. 2001 `), and *f(T)* and +*f(H\)*\ :sub:`2`\ O) are rate modifiers for temperature and +moisture content. CLM uses the same rate modifiers as +are used in the decomposition routine. *f(pH)* is a rate +modifier for pH; however, because CLM does not calculate pH, +instead a fixed pH value of 6.5 is used in the pH function of +:ref:`Parton et al. (1996) `. The potential denitrification rate is co-limited by NO\ :sup:`-3` concentration and C consumption rates, and occurs only in the anoxic fraction of soils: .. math:: - :label: 22.12) + :label: 22.3) f_{denitr,p} =\min \left(f(decomp),f\left(\left[NO_{3} ^{-} \right]\right)\right)frac_{anox} where :math:`{f}_{denitr,p}` is the potential denitrification rate and *f(decomp)* and *f([NO*\ :sub:`3`\ :sup:`-` *])* are the carbon- and nitrate- limited denitrification rate functions, -respectively, (del Grosso et al. 2000). Because the modified CLM -includes explicit treatment of soil biogeochemical vertical profiles, -including diffusion of the trace gases O\ :sub:`2` and -CH\ :sub:`4` (Riley et al. 2011a), the calculation of anoxic -fraction :math:`{frac}_{anox}` uses this information following the -anoxic microsite formulation of Arah and Vinten (1995): +respectively, (:ref:`del Grosso et al. 2000 `). +Because the modified CLM includes explicit treatment of soil +biogeochemical vertical profiles, including diffusion of the trace +gases O\ :sub:`2` and CH\ :sub:`4` (:ref:`Riley et al. 2011a +`), the calculation of anoxic fraction :math:`{frac}_{anox}` +uses this information following the anoxic microsite formulation +of :ref:`Arah and Vinten (1995) `. .. math:: - :label: 22.13) + :label: 22.4) frac_{anox} =\exp \left(-aR_{\psi }^{-\alpha } V^{-\beta } C^{\gamma } \left[\theta +\chi \varepsilon \right]^{\delta } \right) @@ -283,20 +205,21 @@ radius of a typical pore space at moisture content :math:`\psi`, *V* is the O\ :sub:`2` consumption rate, *C* is the O\ :sub:`2` concentration, :math:`\theta` is the water-filled pore space, :math:`\chi` is the ratio of diffusivity of oxygen in water to that in -air, and :math:`\epsilon` is the air-filled pore space (Arah and -Vinten, 1995). These parameters are all calculated separately at each +air, and :math:`\epsilon` is the air-filled pore space (:ref:`Arah and +Vinten (1995) `). These parameters are all calculated +separately at each layer to define a profile of anoxic porespace fraction in the soil. The nitrification/denitrification models used here also predict fluxes -of N\ :sub:`2`\ O via a “hole-in-the-pipe†approach (Firestone and -Davidson, 1989). A constant fraction (6 \* 10\ :math:`{}^{-4}`, Li et -al. 2000) of the nitrification flux is assumed to be -N\ :sub:`2`\ O, while the fraction of denitrification going to -N\ :sub:`2`\ O, P\ :math:`{P}_{N2:N2O}`, is variable, following -the Century (del Grosso et al. 2000) approach: +of N\ :sub:`2`\ O via a “hole-in-the-pipe†approach (:ref:`Firestone and +Davidson, 1989 `). A constant fraction +(6 \* 10\ :math:`{}^{-4}`, :ref:`Li et al. 2000 `) of the +nitrification flux is assumed to be N\ :sub:`2`\ O, while the fraction +of denitrification going to N\ :sub:`2`\ O, \ :math:`{P}_{N2:N2O}`, is variable, following +the Century (:ref:`del Grosso et al. 2000 `) approach: .. math:: - :label: 22.14) + :label: 22.5) P_{N_{2} :N_{2} O} =\max \left(0.16k_{1} ,k_{1} \exp \left(-0.8P_{NO_{3} :CO_{2} } \right)\right)f_{WFPS} @@ -307,7 +230,7 @@ a function of :math:`{d}_{g}`, the gas diffusivity through the soil matrix: .. math:: - :label: 22.15) + :label: 22.6) k_{1} =\max \left(1.7,38.4-350*d_{g} \right) @@ -329,7 +252,7 @@ depends on the concentration of dissolved mineral (inorganic) nitrogen in soil water solution (*DIN*, gN kgH\ :sub:`2`\ O), and the rate of hydrologic discharge from the soil column to streamflow (:math:`{Q}_{dis}`, kgH\ :sub:`2`\ O m\ :sup:`-2` -s\ :sup:`-1`, section 7.6), as +s\ :sup:`-1`, section :numref:`Lateral Sub-surface Runoff`), as .. math:: :label: 22.17) @@ -338,11 +261,8 @@ s\ :sup:`-1`, section 7.6), as *DIN* is calculated assuming that a constant fraction (*sf*, proportion) of the remaining soil mineral N pool is in soluble form, and that this -entire fraction is dissolved in the total soil water. For the CLM-CN -soil model, it is further assumed that *sf* = 0.1, representing an -estimated 10% of the total :math:`{NS}_{sminn}` pool as soluble -nitrate, with the remaining 90% as less soluble ammonia; for the -Century-based formulation, the leaching acts only on the +entire fraction is dissolved in the total soil water. For the Century- +based formulation in CLM5.0, the leaching acts only on the NO\ :sub:`3`\ :sup:`-`` pool (which is assumed to be 100% soluble), while the NH\ :sub:`4`\ :sup:`+` pool is assumed to be 100% adsorbed onto mineral surfaces and unaffected by leaching. @@ -362,25 +282,18 @@ each time step to not exceed the soluble fraction of :math:`{NS}_{sminn}` NF_{leached} =\min \left(NF_{leached} ,\frac{NS_{sminn} sf}{\Delta t} \right). -The CLM-CN parameterization of the soluble fraction is poorly -constrained by observations. Fraction of total soil mineral N pool -present as nitrate will vary spatially and temporally, depending on -oxygen status of soils and rates of nitrification. A calibration of this -parameterization against observations of dissolved nitrate in headwater -streams might be an effective method for imposing better observational -constraints at broad spatial scales. - Losses of Nitrogen Due to Fire ----------------------------------- The final pathway for nitrogen loss is through combustion, also known as pyrodenitrification. Detailed equations are provided, together with the -effects of fire on the carbon budget, in Chapter 18. It is assumed in +effects of fire on the carbon budget, in Chapter :numref:`rst_Fire`). It is assumed in CLM-CN that losses of N due to fire are restricted to vegetation and litter pools (including coarse woody debris). Loss rates of N are determined by the fraction of biomass lost to combustion, assuming that most of the nitrogen in the burned biomass is lost to the atmosphere -(Schlesinger, 1997; Smith et al. 2005). It is assumed that soil organic +(:ref:`Schlesinger, 1997 `; :ref:`Smith et al. 2005 +`). It is assumed that soil organic matter pools of carbon and nitrogen are not directly affected by fire -(Neff et al. 2005). +(:ref:`Neff et al. 2005 `). diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index c2a665d8ac..920bc2c1ba 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -145,15 +145,23 @@ follows: \begin{array}{l} {a_{1} ={\rm \; ratio\; of\; new\; fine\; root\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{2} ={\rm \; ratio\; of\; new\; coarse\; root\; :\; new\; stem\; carbon\; allocation}} \\ {a_{3} ={\rm \; ratio\; of\; new\; stem\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{4} ={\rm \; ratio\; new\; live\; wood\; :\; new\; total\; wood\; allocation}} \\ {g_{1} ={\rm ratio\; of\; growth\; respiration\; carbon\; :\; new\; growth\; carbon.\; }} \end{array} -Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined as constants for a given PFT (Table -13.1), while :math:`g_{l }` = 0.3 (unitless) is prescribed as a +Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined +as constants for a given PFT (:numref:`Table Allocation and carbon:nitrogen +ratio parameters`), while :math:`g_{l }` = 0.3 (unitless) is prescribed as a constant for all PFTs, based on construction costs for a range of woody -and non-woody tissues (Larcher, 1995). +and non-woody tissues (:ref:`Larcher, 1995 `). -The model includes a dynamic allocation scheme for woody vegetation -(parameter :math:`a_{3}` = -1, Table 13.1), in which case the -ratio for carbon allocation between new stem and new leaf increases with -increasing net primary production (NPP), as +CLM5.0 applies a fixed allocation scheme for woody vegetation. +The decision to use the fixed allocation scheme in CLM5.0 came +from biases in above-ground biomass illustrated by Negrón-Juárez +et al. (:ref:`2015 `). + +The model maintains the capacity to represent a dynamic allocation scheme +for woody vegetation (parameter :math:`a_{3}` = -1, :numref:`Table Allocation +and carbon:nitrogen ratio parameters`), but this is not the default +configuration. With dynamic allocation the ratio for carbon allocation +between new stem and new leaf increases with increasing net primary +production (NPP), as .. math:: :label: 17.8) @@ -162,63 +170,33 @@ increasing net primary production (NPP), as where :math:`NPP_{ann}` is the annual sum of NPP from the previous year. This mechanism has the effect of increasing woody allocation in -favorable growth environments (Allen et al., 2005; Vanninen and Makela, -2005) and during the phase of stand growth prior to canopy closure -(Axelsson and Axelsson, 1986). - -Table 13.1. Allocation and carbon:nitrogen ratio parameters - -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`CN_{leaf}` | :math:`CN_{fr}` | :math:`CN_{lw}` | :math:`CN_{dw}` | -+==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ -| NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| NET Boreal | 1 | 0.3 | -1 | 0.1 | 40 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| NDT Boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BET Tropical | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BET temperate | 1 | 0.3 | -1 | 0.1 | 30 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDT tropical | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDT temperate | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDT boreal | 1 | 0.3 | -1 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BES temperate | 1 | 0.3 | 0.2 | 0.5 | 30 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDS temperate | 1 | 0.3 | 0.2 | 0.5 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :sub:`3` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :sub:`3` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| C\ :sub:`4` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Crop R | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Crop I | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Corn R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Corn I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Temp Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Temp Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Winter Cereal R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Winter Cereal I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Soybean R | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ -| Soybean I | 2 | 0 | 0 | 1 | 25 | 42 | 50 | 500 | -+----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ +favorable growth environments (:ref:`Allen et al., 2005 `; +:ref:`Vanninen and Makela, 2005 `) and during +the phase of stand growth prior to canopy closure (:ref:`Axelsson and +Axelsson, 1986 `). + +.. _Table Allocation and carbon:nitrogen ratio parameters: + +.. table:: Allocation and carbon:nitrogen ratio parameters. + + ======================== ============= ============= ============= ============= ================= =============== =============== =============== + Plant functional type :math:`a_{1}` :math:`a_{2}` :math:`a_{3}` :math:`a_{4}` :math:`CN_{leaf}` :math:`CN_{fr}` :math:`CN_{lw}` :math:`CN_{dw}` + ======================== ============= ============= ============= ============= ================= =============== =============== =============== + NET Temperate 1.5 0.3 2.30 0.1 58.00 42 50 500 + NET Boreal 1.5 0.3 2.30 0.1 58.00 42 50 500 + NDT Boreal 1.5 0.3 1.00 0.1 25.81 42 50 500 + BET Tropical 1.5 0.3 2.30 0.1 29.60 42 50 500 + BET temperate 1.5 0.3 1.50 0.1 29.60 42 50 500 + BDT tropical 1.5 0.3 1.00 0.1 23.45 42 50 500 + BDT temperate 1.5 0.3 2.30 0.1 23.45 42 50 500 + BDT boreal 1.5 0.3 2.30 0.1 23.45 42 50 500 + BES temperate 1.5 0.3 1.40 0.5 36.42 42 50 500 + BDS temperate 1.5 0.3 0.24 0.5 23.26 42 50 500 + BDS boreal 1.5 0.3 0.24 0.1 23.26 42 50 500 + C\ :sub:`3` arctic grass 1.5 0.0 0.00 0.0 28.03 42 0 0 + C\ :sub:`3` grass 1.5 0.0 0.00 0.0 28.03 42 0 0 + C\ :sub:`4` grass 1.5 0.0 0.00 0.0 35.36 42 0 0 + ======================== ============= ============= ============= ============= ================= =============== =============== =============== Carbon to nitrogen ratios are defined for different tissue types as follows: @@ -226,10 +204,10 @@ follows: .. math:: :label: ZEqnNum413927 - \begin{array}{l} {CN_{leaf} =\_ {\rm \; C:N\; for\; leaf}} \\ {CN_{fr} =\_ {\rm \; C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \; C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\_ {\rm \; C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} + \begin{array}{l} {CN_{leaf} =\ {\rm \;C:N\; for\; leaf}} \\ {CN_{fr} =\ {\rm \;C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \;C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\ {\rm \;C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} -where all C:N parameters are defined as constants for a given PFT (Table -13.1). +where all C:N parameters are defined as constants for a given PFT +(:numref:`Table Allocation and carbon:nitrogen ratio parameters`). Given values for the parameters in and , total carbon and nitrogen allocation to new growth ( :math:`CF_{alloc}`, gC diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 048fa076c0..59fed6d91b 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1295,6 +1295,11 @@ and Water Assessment Tool, Theoretical Documentation: Version 2005. Temple, TX. USDA Agricultural Research Service and Texas A&M Blackland Research Center. +.. _Negrón-Juárezetal2015: + +Negrón-Juárez, R. Koven, C.D., Riley, W.J., Knox, R.G., Chambers, J.Q. +2015. Environmental Research Letters 10:064017. DOI:10.1088/1748-9326/10/6/064017. + .. _NemaniRunning1996: Nemani, R.R., and Running, S.W. 1996. Implementation of a hierarchical @@ -1648,7 +1653,7 @@ Strugnell, N.C., Zhang, X., Jin, Y., and Muller, J.-P. 2002. First operational BRDF, albedo nadir reflectance products from MODIS. Remote Sens. Environ. 83:135-148. -.. _Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. +.. _Schlesinger1997: Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. Academic Press, London, 588 pp. @@ -1884,6 +1889,10 @@ Taylor, B.R., Parkinson, D. and Parsons, W.F.J., 1989. Nitrogen and lignin content as predictors of litter decay rates: A microcosm test. Ecology, 70: 97-104. +.. _Thomasetal2015: + +Thomas R.Q., Brookshire E.N., Gerber S. 2015. Nitrogen limitation on land: how can it occur in Earth system models? Global Change Biology, 21, 1777-1793, doi:10.1111/gcb.12813. + .. _Thonickeetal2001: Thonicke, K., Venevsky, S., Sitch, S., and Cramer, W. 2001. The role of @@ -2012,7 +2021,7 @@ drivers of global environmental change: enabling use of global SRES scenarios at the national and grid levels, Report 550025001, Netherlands Environmental Assessment Agency, 45 pp. -.. _Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: +.. _VanninenMakela2005: Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: effects of size, competition and site fertility on growth allocation and @@ -2077,6 +2086,13 @@ Parameterization and sensitivity analysis of the Biome-BGC terrestrial ecosystem model: net primary production controls. Earth Interactions 4:1-85. +.. _Wiederetal2015: + +Wieder, W. R., Cleveland, C. C., Lawrence, D. M., and Bonan, G. B. 2015. +Effects of model structural uncertainty on carbon cycle projections: +biological nitrogen fixation as a case study. Environmental Research +Letters, 10(4), 044016. + .. _Williamsetal1996: Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., From e8b89e1f6cffb3d233ba2ba56f1d89b4c1d220ff Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 17 Nov 2017 16:58:45 -0700 Subject: [PATCH 105/255] Update html --- .../Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 920bc2c1ba..1dc02dd07c 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -31,10 +31,12 @@ variables for vegetation carbon, and 19 for vegetation nitrogen. .. _Figure Carbon and nitrogen pools: -.. image:: image2.png +.. figure:: image2.png :width: 400px :height: 400px + Carbon and nitrogen pools. + Carbon Allocation for Maintenance Respiration Costs -------------------------------------------------------- From 7e52cbd33fdc937a7c4b907d7664aee43c90c6ef Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Fri, 17 Nov 2017 17:32:53 -0700 Subject: [PATCH 106/255] Updates to Introduction, added some refs, fixed refs in FUN chapter --- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 14 ++++--------- .../CLM50_Tech_Note_Introduction.rst | 15 +++++++------- .../CLM50_Tech_Note_Plant_Respiration.rst | 2 +- .../References/CLM50_Tech_Note_References.rst | 20 +++++++++++++++++-- 4 files changed, 31 insertions(+), 20 deletions(-) diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index c94c3556ef..e10698858b 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -7,7 +7,7 @@ Introduction ----------------- -The Fixation and Uptake of Nitrogen model is based on work by Fisher (J.) et al., (2008), Brzostek et al. (2015) and Shi et al. (2016). The concept of FUN is that in most cases, Nitrogen uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of Nitrogen in the environment which a plant may exchange for carbon. The ratio of carbon expended to Nitrogen acquired is referred to here as the cost, or exchange rate, of N acquisition (:math:`E_{nacq}`, gC/gN)). There are eight pathways for N uptake: +The Fixation and Uptake of Nitrogen model is based on work by :ref:`Fisher et al. (2010)`, :ref:`Brzostek et al. (2014)`, and :ref:`Shi et al. (2016)`. The concept of FUN is that in most cases, Nitrogen uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of Nitrogen in the environment which a plant may exchange for carbon. The ratio of carbon expended to Nitrogen acquired is referred to here as the cost, or exchange rate, of N acquisition (:math:`E_{nacq}`, gC/gN)). There are eight pathways for N uptake: 1. Fixation by symbiotic bacteria in root nodules (for N fixing plants) (:math:`_{fix}`) 2. Retranslocation of N from senescing tissues (:math:`_{ret}`) @@ -47,7 +47,7 @@ Available Soil Nitrogen Cost of Nitrogen Fixation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The cost of fixation is derived from Houlton et al. (2008). +The cost of fixation is derived from :ref:`Houlton et al. (2008)`. .. math:: N_{cost,fix} = -s_{fix}/(1.25 e^{a_{fix} + b_{fix} . t_{soil} (1 - 0.5 t_{soil}/ c_{fix}) }) @@ -89,7 +89,7 @@ where m=1 pertains to the fraction of the PFT that is ecotmycorrhizal, as oppose Resolving N cost across simultaneous uptake streams -------------------------------------------------------- -The total cost of N uptake is calculated based on the assumption that carbon is partitioned to each stream in proportion to the inverse of the cost of uptake. So, more expensive pathways receive less carbon. Earlier versions of FUN (Fisher et al. 2008) utilized a scheme whereby plants only took up N from the cheapest pathway. Brzostek et al. introduced a scheme for the simultaneous uptake from different pathways. Here we calcualate a 'conductance' to N uptake (analagous to the inverse of the cost function conceptualized as a resistance term) :math:`N_{conductance}` ( gN/gC) as: +The total cost of N uptake is calculated based on the assumption that carbon is partitioned to each stream in proportion to the inverse of the cost of uptake. So, more expensive pathways receive less carbon. Earlier versions of FUN :ref:`(Fisher et al., 2010))` utilized a scheme whereby plants only took up N from the cheapest pathway. :ref:`Brzostek et al. (2014)` introduced a scheme for the simultaneous uptake from different pathways. Here we calcualate a 'conductance' to N uptake (analagous to the inverse of the cost function conceptualized as a resistance term) :math:`N_{conductance}` ( gN/gC) as: .. math:: @@ -274,7 +274,7 @@ and the other C and N fluxes can be determined following the logic above. Modifications to allow variation in C:N ratios -------------------------------------------------------- -The original FUN model as developed by Fisher et al. (2008) and Brzostek et al. (2015) assumes a fixed plant tissue C:N ratio. This means that in the case where N is especially limiting, all excess carbon will be utilized in an attempt to take up more Nitrogen. It has been repeatedly observed, however, that in these circumstances in real life, plants have some flexibility in the C:N stoichiometry of their tissues, and therefore, this assumption may not be realistic. **lit review on CN ratios** +The original FUN model as developed by :ref:`Fisher et al. (2010)` and :ref:`Brzostek et al. (2014)` assumes a fixed plant tissue C:N ratio. This means that in the case where N is especially limiting, all excess carbon will be utilized in an attempt to take up more Nitrogen. It has been repeatedly observed, however, that in these circumstances in real life, plants have some flexibility in the C:N stoichiometry of their tissues, and therefore, this assumption may not be realistic. **lit review on CN ratios** Thus, in CLM5, we introduce the capacity for tissue C:N ratios to be prognostic, rather than static. Overall N and C availability (:math:`N_{uptake}` and :math:`C_{growth}`) and hence tissue C:N ratios, are both determined by FUN. Allocation to individual tissues is discussed in the allocation chapter @@ -407,9 +407,3 @@ kc_nonmyc (step 2) sets active components for Arbuscular fungi ACTIVE vs NONMYC ECTO vs ARBU for ACTIVE. -References --------------------------------------------------------- - -Houlton, B.Z., Wang, Y.P., Vitousek, P.M. and Field, C.B., 2008. A unifying framework for dinitrogen fixation in the terrestrial biosphere. Nature, 454(7202), p.327. - - diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 69ad12b91f..ee53f94082 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -511,7 +511,7 @@ push towards more mechanistic treatment of key processes, in addition to more co of land use and land-cover change. Prior versions of CLM included relatively few options for physics parameterizations or structure. In CLM5, where new parameterizations or model decisions were made, in most cases, the CLM4.5 parameterization was maintained so that users could switch back and forth between different parameterizations via namelist control where appropriate or desirable. Throughout the CLM5 Technical Descpription, in general only the default parameterization for any given process is described. Readers are referred to the CLM4.5 or CLM4 Technical Descriptions for detailed descriptions of non-default parameterizations. -The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. +The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Rooting profiles were used inconsistently in CLM4.5 with :ref:`Zeng (2001)` profiles used for water and :ref: `Jackson et al. (1996)` profiles used for carbon inputs. For CLM5, the Jackson et al. (1996) rooting profiles are used for both water and carbon. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. Several changes are included that are mainly targeted at improving the simulation of surface mass balance over ice sheets. The fresh snow density parameterization is updated to more realistically capture the temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is active for Greenland by default with one-way coupling (surface mass balance impacts ice sheet dynamics, but ice sheet dynamics do not feedback onto surface elevation). Two-way coupling can be activated through a namelist switch. The introduction in CLM5 of the capability to @@ -520,16 +520,17 @@ a simulation when two-way coupling is active. Multiple elevation classes (10 el A plant hydraulic stress routine is introduced which explicitly models water transport through the vegetation according to a simple hydraulic framework (Kennedy et al., to be submitted). The water supply equations are used to solve for vegetation water potential forced by transpiration demand and a set of layer-by-layer soil water potentials. Stomatal conductance, therefore, is a function of prognostic leaf water potential. Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. An emergent feature of the plant hydraulics is soil hydraulic redistribution. In CLM5, maximum stomatal conductance is obtained from the Medlyn conductance model :ref:`(Medlyn et al., 2011)`, rather than the Ball-Berry stomatal conductance model that was utilized in CLM4.5 and prior versions of the model. The Medlyn stomatal conductance model is preferred mainly for it's more realistic behavior at low humidity levels :ref:`(Rogers et al., 2017)`. The stress deciduous vegetation phenology trigger is augmented with a antecedent precipitation requirement :ref:`(Dahlin et al. 2015)`. -Plant nutrient dynamics are substantially updated to resolve several deficiencies with the CLM4 and CLM4.5 nutrient cycling representation. The Fixation and Update of Nitrogen (FUN) model (refs???) is adapted for CLM :ref:`(Shi et al., 2016)` to resolve the -unrealistic feature that plants get nitrogen for free in CLM4 and CLM4.5. With FUN, the fact that plants typically spend a -significant fraction of their available carbon on nutrient aquisition is acounted for. The static plant carbon:nitrogen (C:N) ratios utilized in CLM4 and CLM4.5 are replaced with variable plant C:N ratios which +Plant nutrient dynamics are substantially updated to resolve several deficiencies with the CLM4 and CLM4.5 nutrient cycling representation. The Fixation and Update of Nitrogen (FUN) model based on the work of :ref:`Fisher et al. (2010)`, :ref:`Brzostek et al. (2014)`, and :ref:`Shi et al. (2016)` is incorporated. The concept of FUN is that in most cases, N uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of N in the environment which a plant may exchange for carbon. The ratio of carbon expended to N acquired is therefore the cost, or exchange rate, of N acquisition. FUN calculates the rate of symbiotic N fixation, with this N passed straight to the plant, not the mineral N pool. Separately, CLM5 also calculates rates of symbiotic (or free living) N fixation as a function of evapotranspiration (:ref:`Cleveland et al. 1999 `), which +is added to the soil inorganic ammonium (NH\ :sub:`4`\ :sup:`+`) pool. The static plant carbon:nitrogen (C:N) ratios utilized in CLM4 and CLM4.5 are replaced with variable plant C:N ratios which allows plants to adjust their C:N ratio, and therefore their leaf nitrogen content, with the cost of N uptake :ref:`(Ghimire et al. 2016)`. The implementation of a flexible C:N ratio means that the model no longer relies on instantaneous downregulation of potential photosynthesis rates based on soil mineral nitrogen availability to represent nutrient limitation. Furthermore, stomatal conductance is now based on the N-limited photosynthesis rather than on potential photosynthesis. Finally, the Leaf Use of -Nitrogen for Assimilation (LUNA, :ref:`(Xu et al., 2012` and :ref:`Ali et al., 2016)` model is incorporated. The LUNA model calculates +Nitrogen for Assimilation (LUNA, :ref:`Xu et al., 2012` and :ref:`Ali et al., 2016)` model is incorporated. The LUNA model calculates photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that -light capture, carboxylation, and respiration are co-limiting. Allocation changes ... Fixation ??? +light capture, carboxylation, and respiration are co-limiting. + +CLM5 applies a fixed allocation scheme for woody vegetation. The decision to use a fixed allocation scheme in CLM5, rather than a dynamic allocation scheme based on NPP as was used in CLM4 and CLM4.5, was driven by the fact that observations indicate that biomass saturates with increasing productivity, in contrast to the behavior in CLM4 and CLM4.5 where biomass continuously increases with increasing productivity (:ref:`Negron-Juarez et al., 2015`). Soil carbon decomposition processes are unchanged in CLM5, but a new metric for apparent soil carbon turnover times (:ref:`Koven et al., 2017 `) suggested parameter changes that produce a weak intrinsic depth limitation on soil carbon turnover rates (rather than the strong depth limitaiton in CLM4.5) and that the thresholds for soil moisture limitation on soil carbon turnover rates in dry soils should be set at a wetter soil moisture level than that used in CLM4.5. Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016)`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. Fertilization rates and irrigation equipped area updated annually based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that @@ -545,7 +546,7 @@ Included with the release of CLM5.0 is a functionally supported version of the F During the course of the development of CLM5.0, it became clear that the increasing complexity of the model combined with the increasing number and range of model development projects required updates to the underlying CLM infrastructure. Many such software improvements -are included in CLM5.0 including a partial transition to an object-oriented modular software structure. Many hard coded model +are included in CLM5 including a partial transition to an object-oriented modular software structure. Many hard coded model parameters have been extracted into either the parameter file or the CLM namelist, which allows users to more readily calibrate the model for use at specific locations or to conduct parameter sensitivity studies. As part of the effort to increase the scientific utility of the code, in most instances older generation parameterizations (i.e., the parameterizations diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 1dc02dd07c..c4fae1d7d9 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -156,7 +156,7 @@ and non-woody tissues (:ref:`Larcher, 1995 `). CLM5.0 applies a fixed allocation scheme for woody vegetation. The decision to use the fixed allocation scheme in CLM5.0 came from biases in above-ground biomass illustrated by Negrón-Juárez -et al. (:ref:`2015 `). +et al. (:ref:`2015 `). The model maintains the capacity to represent a dynamic allocation scheme for woody vegetation (parameter :math:`a_{3}` = -1, :numref:`Table Allocation diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 59fed6d91b..e613dce3b4 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -217,6 +217,10 @@ liquid water content. Ann. Glaciol. 13:22-26. Brunke, M. A., P. Broxton, J. Pelletier, D. Gochis, P. Hazenberg, D. M. Lawrence, L. R. Leung, G.-Y. Niu, P. A. Troch, and X. Zeng, 2016: Implementing and Evaluating Variable Soil Thickness in the Community Land Model, Version 4.5 (CLM4.5). J. Clim. 29:3441-3461. +.. _Brzosteketal2014: + +Brzostek, E. R., J. B. Fisher, and R. P. Phillips, 2014. Modeling the carbon cost of plant nitrogen acquisition: Mycorrhizal trade-offs and multipath resistance uptake improve predictions of retranslocation. J. Geophys. Res. Biogeosci., 119, 1684–1697, doi:10.1002/2014JG002660. + .. _BugmannSolomon2000: Bugmann, H., and Solomon, A.M. 2000. Explaining forest composition and @@ -487,6 +491,10 @@ Schimel (Editors). John Wiley and Sons, pp. 7-21. Fisher, R. A., S. Muszala, M. Verteinstein, P. Lawrence, C. Xu, N. G. McDowell, R. G. Knox, C. Koven, J. Holm, B. M. Rogers, A. Spessa, D. Lawrence, and G. Bonan, 2015: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED). Geosci. Model Dev., 8: 3593-3619, doi:10.5194/gmd-8-3593-2015. +.. _Fisheretal2010: + +Fisher, J. B., S. Sitch, Y. Malhi, R. A. Fisher, C. Huntingford, and S.-Y. Tan, 2010. Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation. Global Biogeochem. Cycles, 24, GB1014, doi:10.1029/2009GB003621. + .. _FlannerZender2005: Flanner, M.G., and Zender. C.S. 2005. Snowpack radiative heating: @@ -733,6 +741,10 @@ Sensitivity of surface flux simulations to hydrologic parameters based on an uncertainty quantification framework applied to the Community Land Model. J. Geophys. Res. 117:D15108. +.. _Houltonetal2008: + +Houlton, B.Z., Wang, Y.P., Vitousek, P.M. and Field, C.B., 2008. A unifying framework for dinitrogen fixation in the terrestrial biosphere. Nature, 454(7202), p.327. + .. _HuangLiang2006: Huang, M., and Liang, X. 2006. On the assessment of the impact of @@ -906,6 +918,10 @@ sensitive to deep soil carbon decomposability but not deep soil nitrogen dynamics. Proceedings of the National Academies of Science, 112, 12, 3752-3757, doi:10.1073/pnas.1415123112 +.. _Kovenetal2017: + +Koven, C.D., G. Hugelius, D.M. Lawrence, and W.R. Wieder, 2017: Higher climatological temperature sensitivity of soil carbon in cold than warm climates. Nature Clim. Change, 7, doi:10.1038/nclimate3421. + .. _Kuchariketal2000: Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., @@ -1295,9 +1311,9 @@ and Water Assessment Tool, Theoretical Documentation: Version 2005. Temple, TX. USDA Agricultural Research Service and Texas A&M Blackland Research Center. -.. _Negrón-Juárezetal2015: +.. _NegronJuarezetal2015: -Negrón-Juárez, R. Koven, C.D., Riley, W.J., Knox, R.G., Chambers, J.Q. +Negron-Juarez, R. Koven, C.D., Riley, W.J., Knox, R.G., Chambers, J.Q. 2015. Environmental Research Letters 10:064017. DOI:10.1088/1748-9326/10/6/064017. .. _NemaniRunning1996: From 88a17841ea4bce158a4060e1f8c9178f4478c295 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Mon, 20 Nov 2017 05:07:49 -0700 Subject: [PATCH 107/255] Removed allocation from respiration chapter. Moved image to CNPools --- .../CLM50_Tech_Note_Plant_Respiration.rst | 58 +------------------ 1 file changed, 3 insertions(+), 55 deletions(-) diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index c4fae1d7d9..7fac43551c 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -3,63 +3,11 @@ Plant Respiration ================= -Introduction ------------------ - -CLM includes a fully-prognostic treatment of the terrestrial carbon and -nitrogen cycles including interactions between these cycles as mediated -by biological mechanisms of plants and soil heterotrophs. The model is -fully prognostic with respect to all carbon and nitrogen state variables -in the vegetation, litter, and soil organic matter. The seasonal timing -of new vegetation growth and litterfall is also prognostic, responding -to soil and air temperature, soil water availability, and daylength, in -varying degrees depending on a specified phenology type for each PFT -(see Chapter 14). The prognostic LAI, SAI, and vegetation heights are -utilized by the biophysical model. - -Separate state variables for C and N are tracked for leaf, live stem, -dead stem, live coarse root, dead coarse root, and fine root pools -(Figure 13.1 and 13.2). Each of these pools has two corresponding -storage pools representing, respectively, short-term and long-term -storage of non-structural carbohydrates and labile nitrogen. There are -two additional carbon pools, one for the storage of growth respiration -reserves, and another used to meet excess demand for maintenance -respiration during periods with low photosynthesis. One additional -nitrogen pool tracks retranslocated nitrogen, mobilized from leaf tissue -prior to abscission and litterfall. Altogether there are 20 state -variables for vegetation carbon, and 19 for vegetation nitrogen. - -.. _Figure Carbon and nitrogen pools: - -.. figure:: image2.png - :width: 400px - :height: 400px - - Carbon and nitrogen pools. - -Carbon Allocation for Maintenance Respiration Costs + +Carbon Expenditure on Plant Maintenance Respiration -------------------------------------------------------- -The carbon and nitrogen allocation routines in CLM determine the fate of -newly assimilated carbon, coming from the calculation of photosynthesis, -and available mineral nitrogen, coming from plant uptake of mineral -nitrogen in the soil or being drawn out of plant reserves. Allocation -fluxes are determined in three steps: first :math:`CF_{GPPpot}` is -used to evaluate the potential allocation of carbon and nitrogen -assuming an unlimited nitrogen supply, then the actual nitrogen supply -is compared against the demand, and finally allocation of carbon and -nitrogen are reduced, if necessary, to match nitrogen supply and demand. - -Allocation of available carbon on each time step is prioritized, with -first priority given to the demand for carbon to support maintenance -respiration of live tissues (section 13.7). Second priority is to -replenish the internal plant carbon pool that supports maintenance -respiration during times when maintenance respiration exceeds -photosynthesis (e.g. at night, during winter for perennial vegetation, -or during periods of drought stress) (Sprugel et al., 1995). Third -priority is to support growth of new tissues, including allocation to -storage pools from which new growth will be displayed in subsequent time -steps. +After the assimilation of photsynthetic carbon, the first expenditure is on plant maintenance respiration (Chapter :numref:`rst_CN Allocation`) The total maintenance respiration demand (:math:`CF_{mr}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as a function of From f6b0c59a61d319c1237d4ec3bd9968c6ede99808 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Mon, 20 Nov 2017 15:42:02 -0700 Subject: [PATCH 108/255] Modified CN_Allocation to explain FUN interactions --- .../CLM50_Tech_Note_CN_Allocation.rst | 63 ++++++------------- 1 file changed, 19 insertions(+), 44 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 37d3f0a10f..3edb8fb857 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -7,32 +7,22 @@ Summary of CLM5.0 updates relative to the CLM4.5 ----------------------------------------------------- - CLM5 now defaults to a static allocation to woody biomass rather than the dynamic allocation term used in CLM4.5. The dynamic allocation is stil lkept as an option, for details, see the CLM4.5 Tech Note. - - CLM5 now includes flexible C:N ratios of all plant tissues, which allows allocation of carbon to occur separately from allocation of nitrogen, thus removing the requirement to downregulate photosynthesis based on the instantaneous stoichiometric needs of allocation. +- CLM5 now includes flexible C:N ratios of all plant tissues, which allows allocation of carbon to occur separately from allocation of nitrogen, thus removing the requirement to downregulate photosynthesis based on the instantaneous stoichiometric needs of allocation. + +- CLM5 accounts for the carbon expenditure on nitrogen aquisition, as determined by the FUN model, and the N uptake it determined by the environmental cost of Nitrogen from fixation, active uptake and retranslocation. Introduction ----------------- +The carbon and nitrogen allocation routines in CLM determine the fate of newly assimilated carbon, and absorbed nitrogen. The environmental cost of nitrogen estimated by the FUN model modulates the C:N ratios of the plant tissue pools around a target ratio, and absorbed nitrogen is allocated in proportion to the demand, as estimated by the ideal requirements of these target C:N ratios. -The carbon and nitrogen allocation routines in CLM determine the fate of -newly assimilated carbon, coming from the calculation of photosynthesis, -and available mineral nitrogen, coming from plant uptake of mineral -nitrogen in the soil or being drawn out of plant reserves. A significant change to CLM5 relative to prior versions is that allocation of carbon and nitrogen proceed independently rather than in a sequential manner. -Carbon Allocation to Cover Prior-Timestep Maintenance Respiration Costs +Carbon Allocation to Cover Prior-Timestep Maintenance Respiration Costs ("Excess" Respiration) ---------------------------------------------------------------------------- -Allocation of available carbon on each time step is prioritized, with -first priority given to the demand for carbon to support maintenance -respiration of live tissues (Chapter :numref:`rst_Plant Respiration`) and Nitrogen acquisition costs (Chapter :numref:`rst_FUN`). Second priority is to -replenish the plant carbon deficit pool that balances maintenance -respiration that occurs during times when maintenance respiration exceeds -photosynthesis (e.g. at night, during winter for perennial vegetation, -or during periods of drought stress) (Sprugel et al., 1995). Third -priority is to support growth of new tissues, including allocation to -storage pools from which new growth will be displayed in subsequent time -steps, as well as growth respiration costs. +After respiration of live tissues (Chapter :numref:`rst_Plant Respiration`), the next priority of the carbon allocation cascade is to replenish the plant carbon deficit pool that balances maintenance respiration that occurs during times when maintenance respiration exceeds photosynthesis (e.g. at night, during winter for perennial vegetation, or during periods of drought stress) (Sprugel et al., 1995). The total maintenance respiration demand (:math:`CF_{mr}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as a function of @@ -99,16 +89,19 @@ Carbon and Nitrogen Stoichiometry of New Growth ---------------------------------------------------- After accounting for the carbon cost of maintenance respiration, the -remaining carbon flux from photosynthesis which can be allocated to new -growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is +remaining carbon flux from photosynthesis which is allocated either to new +growth or to nitrogen acquisition processes (Chapter :numref:`rst_FUN`), (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 19.6 CF_{avail\_ alloc} =CF_{GPP} -CF_{GPP,mr} -CF_{GPP,xs} . -Potential allocation to new growth is calculated for all of the plant -carbon and nitrogen state variables based on specified C:N ratios for + +The FUN model requires an estimate of the C:N requirements of the existing plant structure, given that different relative quantities of wood, root and leaf biomass will result in different necessary C:N ratios for expansion. + +These C and N allocation ratios are calculated for all of the plant +carbon and nitrogen state variables based on target C:N ratios for each tissue type and allometric parameters that relate allocation between various tissue types. The allometric parameters are defined as follows: @@ -191,17 +184,14 @@ follows: where all C:N parameters are defined as constants for a given PFT (:numref:`Table Allocation and CN ratio parameters`). -Given values for the parameters in and , total carbon and nitrogen -allocation to new growth ( :math:`CF_{alloc}`, gC -m\ :sup:`-2` s\ :sup:`-1`, and :math:`NF_{alloc}`, gN -m\ :sup:`-2` s\ :sup:`-1`, respectively) can be expressed as -functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC -m\ :sup:`-2` s\ :sup:`-1`): + +The target C:N stoichiometry for new growth allocation can be calculated as .. math:: - :label: 19.10 + :label: 19.13 + + CN_{plant\_ target} =\frac{N_{allom} }{C_{allom} } . - \begin{array}{l} {CF_{alloc} =CF_{GPP,leaf} {\kern 1pt} C_{allom} } \\ {NF_{alloc} =CF_{GPP,leaf} {\kern 1pt} N_{allom} } \end{array} where @@ -215,16 +205,7 @@ where N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. -Since the C:N stoichiometry for new growth allocation is defined, from -Eq. , as :math:`C_{allom}`/ :math:`N_{allom}`, the total carbon available for new growth allocation -(:math:`CF_{avail\_alloc}`) can be used to calculate the total -plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, -gN m\ :sup:`-2` s\ :sup:`-1`) as: -.. math:: - :label: 19.13 - - NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . Carbon Allocation to New Growth ----------------------------------------- @@ -305,14 +286,8 @@ tissue types are given as: Nitrogen allocation ----------------------------------------- -The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{supply}`. The total N allocated for a given tissue :math:`i` is the minimum between the supply and the demand: - -.. math:: - :label: 19.26 - - NF_{alloc,i} = min \left( NF_{demand, i}, NF_{supply, i} \right) +The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{uptake}`. This is distribution in proportion to the demand for N from different tissues, calculated as: -The demand for each tissue, calculated for the tissue to remain on stoichiometry during growth, is: .. math:: :label: 19.27 From 407df8d4188a4b9bd2fda40d04a5a62c58a4efe0 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Thu, 30 Nov 2017 17:37:18 -0700 Subject: [PATCH 109/255] Updated parameter values in Decomposition chapter --- .../CLM50_Tech_Note_Decomposition.rst | 16 ++++++++-------- .../CLM50_Tech_Note_Introduction.rst | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 4d72bd357e..4f662988f6 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -200,19 +200,19 @@ those described in Parton et al. (1988) (:numref:`Table Turnover times`). +------------+------------------------+-------------+-------------------------------------------+ | | Turnover time (year) | C:N ratio | Acceleration term (:math:`{a}_{i}`) | +============+========================+=============+===========================================+ - | CWD | 4.1 | - | 1 | + | CWD | 3.3 | - | 1.65 | +------------+------------------------+-------------+-------------------------------------------+ - | Litter 1 | 0.066 | - | 1 | + | Litter 1 | 0.054 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | Litter 2 | 0.25 | - | 1 | + | Litter 2 | 0.20 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | Litter 3 | 0.25 | - | 1 | + | Litter 3 | 0.20 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | SOM 1 | 0.17 | 8 | 1 | + | SOM 1 | 0.14 | 12 | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | SOM 2 | 6.1 | 11 | 15 | + | SOM 2 | 5 | 12 | 5 | +------------+------------------------+-------------+-------------------------------------------+ - | SOM 3 | 270 | 11 | 675 | + | SOM 3 | 222 | 10 | 222 | +------------+------------------------+-------------+-------------------------------------------+ Likewise, values for the respiration fraction of Century-based structure are in :numref:`Table Respiration fractions for Century-based structure`. @@ -794,7 +794,7 @@ loading from restart files (which preserve information about the mode of the model when restart files were written). The base acceleration terms for the two decomposition cascades are shown in -Tables 15.1 and 15.3. In addition to the base terms, CLM5 also +Tables :numref:`Table Decomposition rate constants` and :numref:`Table Turnover times`. In addition to the base terms, CLM5 also includes a geographic term to the acceleration in order to apply larger values to high-latitude systems, where decomposition rates are particularly slow and thus equilibration can take significantly longer diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index ee53f94082..999e6cd30e 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -511,7 +511,7 @@ push towards more mechanistic treatment of key processes, in addition to more co of land use and land-cover change. Prior versions of CLM included relatively few options for physics parameterizations or structure. In CLM5, where new parameterizations or model decisions were made, in most cases, the CLM4.5 parameterization was maintained so that users could switch back and forth between different parameterizations via namelist control where appropriate or desirable. Throughout the CLM5 Technical Descpription, in general only the default parameterization for any given process is described. Readers are referred to the CLM4.5 or CLM4 Technical Descriptions for detailed descriptions of non-default parameterizations. -The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Rooting profiles were used inconsistently in CLM4.5 with :ref:`Zeng (2001)` profiles used for water and :ref: `Jackson et al. (1996)` profiles used for carbon inputs. For CLM5, the Jackson et al. (1996) rooting profiles are used for both water and carbon. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. +The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Rooting profiles were used inconsistently in CLM4.5 with :ref:`Zeng (2001)` profiles used for water and :ref:`Jackson et al. (1996)` profiles used for carbon inputs. For CLM5, the Jackson et al. (1996) rooting profiles are used for both water and carbon. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. Several changes are included that are mainly targeted at improving the simulation of surface mass balance over ice sheets. The fresh snow density parameterization is updated to more realistically capture the temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is active for Greenland by default with one-way coupling (surface mass balance impacts ice sheet dynamics, but ice sheet dynamics do not feedback onto surface elevation). Two-way coupling can be activated through a namelist switch. The introduction in CLM5 of the capability to From c019c6ebaac5fc8e221ce115707562118894f29a Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Fri, 1 Dec 2017 06:33:31 -0700 Subject: [PATCH 110/255] Modified Decomposition chapter discussion of N competition --- .../CLM50_Tech_Note_Decomposition.rst | 153 ++++++++++-------- 1 file changed, 85 insertions(+), 68 deletions(-) diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 4f662988f6..30c9b3988d 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -12,7 +12,7 @@ and soil organic matter (SOM) pools, each defined at compile time, between 2 contrasting hypotheses of decomposition as embodied by two separate decomposition submodels: the CLM-CN pool structure used in CLM4.0, or a second pool structure, characterized by -slower decomposition rates, based on the Century model (Parton et al. +slower decomposition rates, based on the fCentury model (Parton et al. 1988). In addition, the user can choose, at compile time, whether to allow :math:`{n}_{lev}` to equal 1, as in CLM4.0, or to equal the number of soil levels used for the soil hydrological and thermal @@ -200,19 +200,19 @@ those described in Parton et al. (1988) (:numref:`Table Turnover times`). +------------+------------------------+-------------+-------------------------------------------+ | | Turnover time (year) | C:N ratio | Acceleration term (:math:`{a}_{i}`) | +============+========================+=============+===========================================+ - | CWD | 3.3 | - | 1.65 | + | CWD | 4.1 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | Litter 1 | 0.054 | - | 1 | + | Litter 1 | 0.066 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | Litter 2 | 0.20 | - | 1 | + | Litter 2 | 0.25 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | Litter 3 | 0.20 | - | 1 | + | Litter 3 | 0.25 | - | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | SOM 1 | 0.14 | 12 | 1 | + | SOM 1 | 0.17 | 8 | 1 | +------------+------------------------+-------------+-------------------------------------------+ - | SOM 2 | 5 | 12 | 5 | + | SOM 2 | 6.1 | 11 | 15 | +------------+------------------------+-------------+-------------------------------------------+ - | SOM 3 | 222 | 10 | 222 | + | SOM 3 | 270 | 11 | 675 | +------------+------------------------+-------------+-------------------------------------------+ Likewise, values for the respiration fraction of Century-based structure are in :numref:`Table Respiration fractions for Century-based structure`. @@ -488,47 +488,64 @@ as opposed to a potential flux. N Competition between plant uptake and soil immobilization fluxes ---------------------------------------------------------------------- -Once :math:`{NF}_{immob\_demand }` is known, the competition between -plant and microbial nitrogen demand can be resolved. Mineral nitrogen in +Once :math:`{NF}_{immob\_demand }` and :math:`{NF}_{nit\_demand }` for each layer *j* are known, the competition between plant and microbial nitrogen demand can be resolved. Mineral nitrogen in the soil pool (:math:`{NS}_{sminn}`, gN m\ :sup:`-2`) at the -beginning of the timestep is considered the available supply. Total -demand for mineral nitrogen from this pool (:math:`{NF}_{total\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`) is: +beginning of the timestep is considered the available supply. + +Here, the :math:`{NF}_{plant\_demand}` is the theoretical maximum demand for nitrogen by plants to meet the entire carbon uptake given an N cost of zero (and therefore represents the upper bound on N requirements). N uptake costs that are +:math:`>` 0 imply that the plant will take up less N that it demands, ultimately. However, given the heuristic nature of the N competition algorithm, this discrepancy is not explicitly resolved here. + +The hypothetical plant nitrogen demand from the soil mineral pool is distributed between layers in proportion to the profile of available mineral N: + +.. math:: + :label: 21.291 + + NF_{plant\_ demand,j} = NF_{plant\_ demand} NS_{sminn\_ j} / \sum _{j=1}^{nj}NS_{sminn,j} + +Plants first compete for ammonia (NH4). For each soil layer (*j*), we calculate the total NH4 demand as: .. math:: - :label: 21.27) + :label: 21.292 - NF_{total\_ demand} =NF_{immob\_ demand} +NF_{plant\_ demand\_ soil} + NF_{total\_ demand_nh4,j} = NF_{immob\_ demand,j} + NF_{immob\_ demand,j} + NF_{nit\_ demand,j} -If :math:`{NF}_{total\_demand}`\ :math:`\Delta`\ *t* :math:`<` -:math:`{NS}_{sminn}`, then the available pool is large enough to -meet both plant and microbial demand, and neither plant growth nor -immobilization steps in the decomposition cascade are limited by -nitrogen availability in the timestep. In that case, the signaling -variables :math:`{f}_{plant\_demand}` and -:math:`{f}_{immob\_demand}` are both set to 1.0, where -:math:`{f}_{plant\_demand}` is defined and used in section 15.4, and -:math:`{f}_{immob\_demand}` is the fraction of potential -immobilization demand that can be met given current supply of mineral nitrogen. +where +If :math:`{NF}_{total\_demand,j}`\ :math:`\Delta`\ *t* :math:`<` +:math:`{NS}_{sminn,j}`, then the available pool is large enough to +meet both the maximum plant and microbial demand, then immobilization proceeds at the maximum rate. -If :math:`{NF}_{total\_demand}`\ :math:`\Delta`\ *t* -:math:`\mathrm{\ge}` :math:`{NS}_{sminn}`, then there is not enough +.. math:: + :label: 21.29) + + f_{immob\_demand,j} = 1.0 + +where :math:`{f}_{immob\_demand,j}` is the fraction of potential immobilization demand that can be met given current supply of mineral nitrogen in this layer. We also set the actual nitrification flux to be the same as the potential flux (:math:`NF_{nit}` = :math:`NF_{nit\_ demand}`). + +If :math:`{NF}_{total\_demand,j}`\ :math:`\Delta`\ *t* +:math:`\mathrm{\ge}` :math:`{NS}_{sminn,j}`, then there is not enough mineral nitrogen to meet the combined demands for plant growth and -heterotrophic immobilization, and both of these processes proceed at -lower-than-potential rates, defined by the fractions -:math:`{f}_{plant\_demand}` and :math:`{f}_{immob\_demand}`, -where: +heterotrophic immobilization, immobilization is reduced proportional to the discrepancy, by :math:`f_{immob\_ demand,j}`, where .. math:: - :label: 21.28) + :label: 21.30) + + f_{immob\_ demand,j} = \frac{NS_{sminn,j} }{\Delta t\, NF_{total\_ demand,j} } + +The N available to the FUN model for plant uptake (:math:`{NF}_ {plant\_ avail\_ sminn}` (gN m\ :sup:`-2`), which determines both the cost of N uptake, and the absolute limit on the N which is available for acquisition, is calculated as the total mineralized pool minus the actual immobilized flux: + +.. math:: + :label: 21.311) + + NF_{plant\_ avail\_ sminn,j} = NS_{sminn,j} - f_{immob\_demand} NF_{immob\_ demand,j} - f_{plant\_ demand} =f_{immob\_ demand} =\frac{NS_{sminn} }{\Delta t\, NF_{total\_ demand} } This treatment of competition for nitrogen as a limiting resource is referred to a demand-based competition, where the fraction of the available resource that eventually flows to a particular process depends on the demand from that process in comparison to the total demand from all processes. Processes expressing a greater demand acquire a larger -fraction of the available resource. +vfraction of the available resource. + Final Decomposition Fluxes ------------------------------- @@ -540,37 +557,37 @@ CENTURY structure will be similar but, again without the different terminal step), are calculated as: .. math:: - :label: 21.29) + :label: 21.32) CF_{Lit1} =\left\{\begin{array}{l} {CF_{pot,\, Lit1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {CF_{pot,\, Lit1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} .. math:: - :label: 21.30) + :label: 21.33) CF_{Lit2} =\left\{\begin{array}{l} {CF_{pot,\, Lit2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {CF_{pot,\, Lit2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 21.31) + :label: 21.34) CF_{Lit3} =\left\{\begin{array}{l} {CF_{pot,\, Lit3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {CF_{pot,\, Lit3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 21.32) + :label: 21.35) CF_{SOM1} =\left\{\begin{array}{l} {CF_{pot,\, SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {CF_{pot,\, SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 21.33) + :label: 21.36) CF_{SOM2} =\left\{\begin{array}{l} {CF_{pot,\, SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {CF_{pot,\, SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 21.34) + :label: 21.37) CF_{SOM3} =\left\{\begin{array}{l} {CF_{pot,\, SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {CF_{pot,\, SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} .. math:: - :label: 21.35) + :label: 21.38) CF_{SOM4} =CF_{pot,\, SOM4} @@ -578,37 +595,37 @@ Heterotrophic respiration fluxes (losses of carbon as CO\ :sub:`2` to the atmosphere) are: .. math:: - :label: 21.36) + :label: 21.39) CF_{Lit1,\, HR} =CF_{Lit1} rf_{Lit1} .. math:: - :label: 21.37) + :label: 21.40) CF_{Lit2,\, HR} =CF_{Lit2} rf_{Lit2} .. math:: - :label: 21.38) + :label: 21.41) CF_{Lit3,\, HR} =CF_{Lit3} rf_{Lit3} .. math:: - :label: 21.39) + :label: 21.42) CF_{SOM1,\, HR} =CF_{SOM1} rf_{SOM1} .. math:: - :label: 21.40) + :label: 21.43) CF_{SOM2,\, HR} =CF_{SOM2} rf_{SOM2} .. math:: - :label: 21.41) + :label: 21.44) CF_{SOM3,\, HR} =CF_{SOM3} rf_{SOM3} .. math:: - :label: 21.42) + :label: 21.45) CF_{SOM4,\, HR} =CF_{SOM4} rf_{SOM4} @@ -616,32 +633,32 @@ Transfers of carbon from upstream to downstream pools in the decomposition cascade are given as: .. math:: - :label: 21.43) + :label: 21.46) CF_{Lit1,\, SOM1} =CF_{Lit1} \left(1-rf_{Lit1} \right) .. math:: - :label: 21.44) + :label: 21.47) CF_{Lit2,\, SOM2} =CF_{Lit2} \left(1-rf_{Lit2} \right) .. math:: - :label: 21.45) + :label: 21.48) CF_{Lit3,\, SOM3} =CF_{Lit3} \left(1-rf_{Lit3} \right) .. math:: - :label: 21.46) + :label: 21.49) CF_{SOM1,\, SOM2} =CF_{SOM1} \left(1-rf_{SOM1} \right) .. math:: - :label: 21.47) + :label: 21.50) CF_{SOM2,\, SOM3} =CF_{SOM2} \left(1-rf_{SOM2} \right) .. math:: - :label: 21.48) + :label: 21.51) CF_{SOM3,\, SOM4} =CF_{SOM3} \left(1-rf_{SOM3} \right) @@ -655,32 +672,32 @@ or from the downstream pool to the soil mineral nitrogen pool pools in the decomposition cascade are given as: .. math:: - :label: 21.49) + :label: 21.52) NF_{Lit1,\, SOM1} ={CF_{Lit1} \mathord{\left/ {\vphantom {CF_{Lit1} CN_{Lit1} }} \right. \kern-\nulldelimiterspace} CN_{Lit1} } .. math:: - :label: 21.50) + :label: 21.53) NF_{Lit2,\, SOM2} ={CF_{Lit2} \mathord{\left/ {\vphantom {CF_{Lit2} CN_{Lit2} }} \right. \kern-\nulldelimiterspace} CN_{Lit2} } .. math:: - :label: 21.51) + :label: 21.54) NF_{Lit3,\, SOM3} ={CF_{Lit3} \mathord{\left/ {\vphantom {CF_{Lit3} CN_{Lit3} }} \right. \kern-\nulldelimiterspace} CN_{Lit3} } .. math:: - :label: 21.52) + :label: 21.55) NF_{SOM1,\, SOM2} ={CF_{SOM1} \mathord{\left/ {\vphantom {CF_{SOM1} CN_{SOM1} }} \right. \kern-\nulldelimiterspace} CN_{SOM1} } .. math:: - :label: 21.53) + :label: 21.56) NF_{SOM2,\, SOM3} ={CF_{SOM2} \mathord{\left/ {\vphantom {CF_{SOM2} CN_{SOM2} }} \right. \kern-\nulldelimiterspace} CN_{SOM2} } .. math:: - :label: 21.54) + :label: 21.57) NF_{SOM3,\, SOM4} ={CF_{SOM3} \mathord{\left/ {\vphantom {CF_{SOM3} CN_{SOM3} }} \right. \kern-\nulldelimiterspace} CN_{SOM3} } @@ -689,37 +706,37 @@ whether the decomposition step is an immobilization flux or a mineralization flux: .. math:: - :label: 21.55) + :label: 21.58) NF_{sminn,\, Lit1\to SOM1} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit1\to SOM1} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} >0} \\ {NF_{pot\_ min,\, Lit1\to SOM1} \qquad {\rm for\; }NF_{pot\_ min,\, Lit1\to SOM1} \le 0} \end{array}\right\} .. math:: - :label: 21.56) + :label: 21.59) NF_{sminn,\, Lit2\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit2\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} >0} \\ {NF_{pot\_ min,\, Lit2\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, Lit2\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 21.57) + :label: 21.60) NF_{sminn,\, Lit3\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, Lit3\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} >0} \\ {NF_{pot\_ min,\, Lit3\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, Lit3\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 21.58) + :label: 21.61) NF_{sminn,SOM1\to SOM2} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM1\to SOM2} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} >0} \\ {NF_{pot\_ min,\, SOM1\to SOM2} \qquad {\rm for\; }NF_{pot\_ min,\, SOM1\to SOM2} \le 0} \end{array}\right\} .. math:: - :label: 21.59) + :label: 21.62) NF_{sminn,SOM2\to SOM3} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM2\to SOM3} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} >0} \\ {NF_{pot\_ min,\, SOM2\to SOM3} \qquad {\rm for\; }NF_{pot\_ min,\, SOM2\to SOM3} \le 0} \end{array}\right\} .. math:: - :label: 21.60) + :label: 21.63) NF_{sminn,SOM3\to SOM4} =\left\{\begin{array}{l} {NF_{pot\_ min,\, SOM3\to SOM4} f_{immob\_ demand} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} >0} \\ {NF_{pot\_ min,\, SOM3\to SOM4} \qquad {\rm for\; }NF_{pot\_ min,\, SOM3\to SOM4} \le 0} \end{array}\right\} .. math:: - :label: 21.61) + :label: 21.64) NF_{sminn,\, SOM4} =NF_{pot\_ min,\, SOM4} @@ -794,7 +811,7 @@ loading from restart files (which preserve information about the mode of the model when restart files were written). The base acceleration terms for the two decomposition cascades are shown in -Tables :numref:`Table Decomposition rate constants` and :numref:`Table Turnover times`. In addition to the base terms, CLM5 also +Tables 15.1 and 15.3. In addition to the base terms, CLM5 also includes a geographic term to the acceleration in order to apply larger values to high-latitude systems, where decomposition rates are particularly slow and thus equilibration can take significantly longer @@ -803,7 +820,7 @@ the form of a logistic equation, where :math:`{a}_{i}` is equal to the product of the base acceleration term and :math:`{a}_{l}` below: .. math:: - :label: 21.62) + :label: 21.65) a_l = 1 + 50 / \left ( 1 + exp \left (-0.1 * (abs(latitude) - 60 ) \right ) \right ) From 59b6fa4f5a5f11f69c3f0ef431876735e516b586 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 1 Dec 2017 09:33:19 -0700 Subject: [PATCH 111/255] Update html --- .../tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 3edb8fb857..751c393535 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -20,7 +20,7 @@ The carbon and nitrogen allocation routines in CLM determine the fate of newly a Carbon Allocation to Cover Prior-Timestep Maintenance Respiration Costs ("Excess" Respiration) ----------------------------------------------------------------------------- +---------------------------------------------------------------------------------------------- After respiration of live tissues (Chapter :numref:`rst_Plant Respiration`), the next priority of the carbon allocation cascade is to replenish the plant carbon deficit pool that balances maintenance respiration that occurs during times when maintenance respiration exceeds photosynthesis (e.g. at night, during winter for perennial vegetation, or during periods of drought stress) (Sprugel et al., 1995). From 55c81baca6568810b2f78cd03d88dd2243458dc0 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Fri, 1 Dec 2017 12:15:09 -0700 Subject: [PATCH 112/255] modifications to respiration. Added Atkin model, removed allocation text --- .../CLM50_Tech_Note_Plant_Respiration.rst | 472 ++---------------- 1 file changed, 31 insertions(+), 441 deletions(-) diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 7fac43551c..0ec9d5e1d6 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -4,434 +4,6 @@ Plant Respiration ================= -Carbon Expenditure on Plant Maintenance Respiration --------------------------------------------------------- - -After the assimilation of photsynthetic carbon, the first expenditure is on plant maintenance respiration (Chapter :numref:`rst_CN Allocation`) - -The total maintenance respiration demand (:math:`CF_{mr}`, gC -m\ :sup:`-2` s\ :sup:`-1`) is calculated as a function of -tissue mass and nitrogen concentration, and temperature (section 13.7). -The carbon supply to support this demand is composed of fluxes allocated -from carbon assimilated in the current timestep -(:math:`CF_{GPP,mr}`, gC m\ :sup:`-2` s\ :sup:`-1`) -and from a storage pool that is drawn down when total demand exceeds -photosynthesis ( :math:`CF_{xs,mr}`, gC m\ :sup:`-2` -s\ :sup:`-1`): - -.. math:: - :label: 17.1) - - CF_{mr} =CF_{GPP,mr} +CF_{xs,mr} - -.. math:: - :label: 17.2) - - CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. - -.. math:: - :label: 17.3) - - CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPPpot} } \\ {CF_{mr} -CF_{GPPpot} \qquad {\rm for\; }CF_{mr} >CF_{GPPpot} } \end{array}\right. - -The storage pool that supplies carbon for maintenance respiration in -excess of current :math:`CF_{GPPpot}` ( :math:`CS_{xs}`, gC -m\ :sup:`-2`) is permitted to run a deficit (negative state), and -the magnitude of this deficit determines an allocation demand which -gradually replenishes :math:`CS_{xs}`. The logic for allowing a -negative state for this pool is to eliminate the need to know in advance -what the total maintenance respiration demand will be for a particular -combination of climate and plant type. Using the deficit approach, the -allocation to alleviate the deficit increases as the deficit increases, -until the supply of carbon into the pool balances the demand for carbon -leaving the pool in a quasi-steady state, with variability driven by the -seasonal cycle, climate variation, disturbance, and internal dynamics of -the plant-litter-soil system. In cases where the combination of climate -and plant type are not suitable to sustained growth, the deficit in this -pool increases until the available carbon is being allocated mostly to -alleviate the deficit, and new growth approaches zero. The allocation -flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC -m\ :sup:`-2` s\ :sup:`-1`) is given as - -.. math:: - :label: 17.4) - - CF_{GPP,xs,pot} =\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CS_{xs} \ge 0} \\ {-CS_{xs} /(86400\tau _{xs} )\qquad {\rm for\; }CS_{xs} <0} \end{array}\right. - -.. math:: - :label: 17.5) - - CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPPpot} -CF_{GPP,mr} } \\ {\max (CF_{GPPpot} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPPpot} -CF_{GPP,mr} } \end{array}\right. - -where :math:`\tau_{xs}` is the time constant (currently -set to 30 days) controlling the rate of replenishment of :math:`CS_{xs}`. - -Note that these two top-priority carbon allocation fluxes -(:math:`CF_{GPP,mr}` and :math:`CF_{GPP,xs}`) are not -stoichiometrically associated with any nitrogen fluxes, and so this -initial allocation step can proceed without reference to (or limitation -from) the available mineral nitrogen supply. - -Carbon and Nitrogen Stoichiometry of New Growth ----------------------------------------------------- - -After accounting for the carbon cost of maintenance respiration, the -remaining carbon flux from photosynthesis which can be allocated to new -growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is - -.. math:: - :label: 17.6) - - CF_{avail\_ alloc} =CF_{GPPpot} -CF_{GPP,mr} -CF_{GPP,xs} . - -Potential allocation to new growth is calculated for all of the plant -carbon and nitrogen state variables based on specified C:N ratios for -each tissue type and allometric parameters that relate allocation -between various tissue types. The allometric parameters are defined as -follows: - -.. math:: - :label: ZEqnNum650137 - - \begin{array}{l} {a_{1} ={\rm \; ratio\; of\; new\; fine\; root\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{2} ={\rm \; ratio\; of\; new\; coarse\; root\; :\; new\; stem\; carbon\; allocation}} \\ {a_{3} ={\rm \; ratio\; of\; new\; stem\; :\; new\; leaf\; carbon\; allocation}} \\ {a_{4} ={\rm \; ratio\; new\; live\; wood\; :\; new\; total\; wood\; allocation}} \\ {g_{1} ={\rm ratio\; of\; growth\; respiration\; carbon\; :\; new\; growth\; carbon.\; }} \end{array} - -Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined -as constants for a given PFT (:numref:`Table Allocation and carbon:nitrogen -ratio parameters`), while :math:`g_{l }` = 0.3 (unitless) is prescribed as a -constant for all PFTs, based on construction costs for a range of woody -and non-woody tissues (:ref:`Larcher, 1995 `). - -CLM5.0 applies a fixed allocation scheme for woody vegetation. -The decision to use the fixed allocation scheme in CLM5.0 came -from biases in above-ground biomass illustrated by Negrón-Juárez -et al. (:ref:`2015 `). - -The model maintains the capacity to represent a dynamic allocation scheme -for woody vegetation (parameter :math:`a_{3}` = -1, :numref:`Table Allocation -and carbon:nitrogen ratio parameters`), but this is not the default -configuration. With dynamic allocation the ratio for carbon allocation -between new stem and new leaf increases with increasing net primary -production (NPP), as - -.. math:: - :label: 17.8) - - a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 - -where :math:`NPP_{ann}` is the annual sum of NPP from the previous -year. This mechanism has the effect of increasing woody allocation in -favorable growth environments (:ref:`Allen et al., 2005 `; -:ref:`Vanninen and Makela, 2005 `) and during -the phase of stand growth prior to canopy closure (:ref:`Axelsson and -Axelsson, 1986 `). - -.. _Table Allocation and carbon:nitrogen ratio parameters: - -.. table:: Allocation and carbon:nitrogen ratio parameters. - - ======================== ============= ============= ============= ============= ================= =============== =============== =============== - Plant functional type :math:`a_{1}` :math:`a_{2}` :math:`a_{3}` :math:`a_{4}` :math:`CN_{leaf}` :math:`CN_{fr}` :math:`CN_{lw}` :math:`CN_{dw}` - ======================== ============= ============= ============= ============= ================= =============== =============== =============== - NET Temperate 1.5 0.3 2.30 0.1 58.00 42 50 500 - NET Boreal 1.5 0.3 2.30 0.1 58.00 42 50 500 - NDT Boreal 1.5 0.3 1.00 0.1 25.81 42 50 500 - BET Tropical 1.5 0.3 2.30 0.1 29.60 42 50 500 - BET temperate 1.5 0.3 1.50 0.1 29.60 42 50 500 - BDT tropical 1.5 0.3 1.00 0.1 23.45 42 50 500 - BDT temperate 1.5 0.3 2.30 0.1 23.45 42 50 500 - BDT boreal 1.5 0.3 2.30 0.1 23.45 42 50 500 - BES temperate 1.5 0.3 1.40 0.5 36.42 42 50 500 - BDS temperate 1.5 0.3 0.24 0.5 23.26 42 50 500 - BDS boreal 1.5 0.3 0.24 0.1 23.26 42 50 500 - C\ :sub:`3` arctic grass 1.5 0.0 0.00 0.0 28.03 42 0 0 - C\ :sub:`3` grass 1.5 0.0 0.00 0.0 28.03 42 0 0 - C\ :sub:`4` grass 1.5 0.0 0.00 0.0 35.36 42 0 0 - ======================== ============= ============= ============= ============= ================= =============== =============== =============== - -Carbon to nitrogen ratios are defined for different tissue types as -follows: - -.. math:: - :label: ZEqnNum413927 - - \begin{array}{l} {CN_{leaf} =\ {\rm \;C:N\; for\; leaf}} \\ {CN_{fr} =\ {\rm \;C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \;C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\ {\rm \;C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} - -where all C:N parameters are defined as constants for a given PFT -(:numref:`Table Allocation and carbon:nitrogen ratio parameters`). - -Given values for the parameters in and , total carbon and nitrogen -allocation to new growth ( :math:`CF_{alloc}`, gC -m\ :sup:`-2` s\ :sup:`-1`, and :math:`NF_{alloc}`, gN -m\ :sup:`-2` s\ :sup:`-1`, respectively) can be expressed as -functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC -m\ :sup:`-2` s\ :sup:`-1`): - -.. math:: - :label: ZEqnNum555154 - - \begin{array}{l} {CF_{alloc} =CF_{GPP,leaf} {\kern 1pt} C_{allom} } \\ {NF_{alloc} =CF_{GPP,leaf} {\kern 1pt} N_{allom} } \end{array} - -where - -.. math:: - :label: 17.11) - - \begin{array}{l} {C_{allom} =\left\{\begin{array}{l} {\left(1+g_{1} \right)\left(1+a_{1} +a_{3} \left(1+a_{2} \right)\right)\qquad {\rm for\; woody\; PFT}} \\ {1+g_{1} +a_{1} \left(1+g_{1} \right)\qquad \qquad {\rm for\; non-woody\; PFT}} \end{array}\right. } \\ {} \end{array} - -.. math:: - :label: 17.12) - - N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. - -Since the C:N stoichiometry for new growth allocation is defined, from -Eq. , as :math:`C_{allom}`/ :math:`N_{allom}`, the total carbon available for new growth allocation -(:math:`CF_{avail\_alloc}`) can be used to calculate the total -plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, -gN m\ :sup:`-2` s\ :sup:`-1`) as: - -.. math:: - :label: 17.13) - - NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . - -Deployment of retranslocated nitrogen ------------------------------------------- - -In many plants, some portion of the nitrogen used to construct new -tissues is mobilized from senescing tissues, especially leaves, and -retained within the plant when the tissues are lost as litter. This -store of retranslocated nitrogen is used to supply part of the nitrogen -demand for subsequent growth (Magill et al., 1997; Oikawa et al., 2005; -Son and Gower, 1991). CLM includes one pool of retranslocated nitrogen -(:math:`NS_{retrans}`, gN m\ :sup:`-2`), and the -availability of nitrogen from this pool to support new growth -(:math:`NF_{avail\_retrans}`, gN m\ :sup:`-2` -s\ :sup:`-1`) is proportional to the plant nitrogen demand, as: - -.. math:: - :label: 17.14) - - NF_{avail\_ retrans} =\min \left(\frac{NF_{retrans\_ ann} \frac{NF_{plant\_ demand} }{NF_{plant\_ demand\_ ann} } }{\Delta t} ,\; \frac{NS_{retrans} }{\Delta t} \right) - -where :math:`NF_{retrans\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of retranslocated -nitrogen extracted from senescing tissues, -:math:`NF_{plant\_demand\_ann}` (gN m\ :sup:`-2` y\ :sup:`-1`) is the previous year’s annual sum of -:math:`NF_{plant\_demand}`, and :math:`\Delta`\ *t* (s) is the -model’s biogeochemistry time step. This formulation produces an annual -cycle in the extraction of nitrogen from :math:`NS_{retrans}` -which corresponds to the annual cycle of plant nitrogen demand, and -which is scaled to give :math:`NS_{retrans}` approximately a -one-year turnover time. The minimum function prevents extraction of more -than the remaining pool of retranslocated nitrogen, which can be an -important constraint under conditions where high rates of mortality are -modifying the size of the pool. During the first year of an initial -simulation, before :math:`NF_{plant\_demand\_ann}` and -:math:`NF_{retrans\_ann}` have valid values, -:math:`NF_{avail\_retrans}` is set to 0.0. - -The actual flux of nitrogen from the retranslocated N pool into -allocation of new growth (:math:`NF_{retrans,alloc}`, gN -m\ :sup:`-2` s\ :sup:`-1`) is never greater than the plant -demand for new nitrogen: - -.. math:: - :label: 17.15) - - NF_{retrans,alloc} =\min \left(NF_{plant\_ demand} ,NF_{avail\_ retrans} \right) - -Plant nitrogen uptake from soil mineral nitrogen pool ----------------------------------------------------------- - -The total plant nitrogen demand is reduced by the nitrogen flux from -:math:`NS_{retrans}` to give the plant demand for mineral nitrogen -from the soil (:math:`NF_{plant\_demand\_soil}`, gN -m\ :sup:`-2` s\ :sup:`-1`): - -.. math:: - :label: ZEqnNum491412 - - NF_{plant\_ demand\_ soil} =NF_{plant\_ demand} -NF_{retrans,alloc} . - -The combined demand from all PFTs sharing space on a soil column and the -demand from the heterotrophic community in the soil (nitrogen -immobilization demand) compete for the available soil mineral nitrogen -pool. The result of this competition is passed back to the allocation -algorithm as :math:`f_{plant\_demand}`, the fraction (from 0 to 1) -of the plant nitrogen demand which can be met given the current soil -mineral nitrogen supply and competition with heterotrophs. Plant uptake -from the soil mineral nitrogen pool is then given as: - -.. math:: - :label: 17.17) - - NF_{sminn,alloc} =NF_{plant\_ demand\_ soil} f_{plant\_ demand} - -Final carbon and nitrogen allocation ------------------------------------------ - -The total flux of allocated nitrogen is given as: - -.. math:: - :label: 17.18) - - NF_{alloc} =NF_{retrans,alloc} +NF_{sminn,alloc} - -From the stoichiometric relationship in Eq. , the associated carbon -allocation flux is: - -.. math:: - :label: 17.19) - - CF_{alloc} =NF_{alloc} \frac{C_{allom} }{N_{allom} } . - -The downregulation of photosynthesis can then be calculated as: - -.. math:: - :label: 17.20) - - f_{dreg} =\frac{CF_{alloc} -CF_{avail\_ alloc} }{CF_{GPPpot} } . - -Total allocation to new leaf carbon -(:math:`CF_{alloc,leaf\_tot}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as: - -.. math:: - :label: 17.21) - - CF_{alloc,leaf\_ tot} =\frac{CF_{alloc} }{C_{allom} } . - -There are two carbon pools associated with each plant tissue – one which -represents the currently displayed tissue, and another which represents -carbon stored for display in a subsequent growth period. The nitrogen -pools follow this same organization. The model keeps track of stored -carbon according to which tissue type it will eventually be displayed -as, and the separation between display in the current timestep and -storage for later display depends on the parameter :math:`f_{cur}` -(values 0 to 1). Given :math:`CF_{alloc,leaf}` and :math:`f_{cur}`, the allocation fluxes of carbon to display and -storage pools (where storage is indicated with *\_stor*) for the various -tissue types are given as: - -.. math:: - :label: 17.22) - - CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} - -.. math:: - :label: 17.23) - - CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) - -.. math:: - :label: 17.24) - - CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} - -.. math:: - :label: 17.25) - - CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) - -.. math:: - :label: 17.26) - - CF_{alloc,livestem} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} f_{cur} - -.. math:: - :label: 17.27) - - CF_{alloc,livestem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} a_{4} \left(1-f_{cur} \right) - -.. math:: - :label: 17.28) - - CF_{alloc,deadstem} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)f_{cur} - -.. math:: - :label: 17.29) - - CF_{alloc,deadstem\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right) - -.. math:: - :label: 17.30) - - CF_{alloc,livecroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} f_{cur} - -.. math:: - :label: 17.31) - - CF_{alloc,livecroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} \left(1-f_{cur} \right) - -.. math:: - :label: 17.32) - - CF_{alloc,deadcroot} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)f_{cur} - -.. math:: - :label: 17.33) - - CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). - -The corresponding nitrogen allocation fluxes are given as: - -.. math:: - :label: 17.34) - - NF_{alloc,leaf} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } f_{cur} - -.. math:: - :label: 17.35) - - NF_{alloc,leaf\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} }{CN_{leaf} } \left(1-f_{cur} \right) - -.. math:: - :label: 17.36) - - NF_{alloc,froot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } f_{cur} - -.. math:: - :label: 17.37) - - NF_{alloc,froot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{1} }{CN_{fr} } \left(1-f_{cur} \right) - -.. math:: - :label: 17.38) - - NF_{alloc,livestem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } f_{cur} - -.. math:: - :label: 17.39) - - NF_{alloc,livestem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) - -.. math:: - :label: 17.40) - - NF_{alloc,deadstem} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} - -.. math:: - :label: 17.41) - - NF_{alloc,deadstem\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right) - -.. math:: - :label: 17.42) - - NF_{alloc,livecroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } f_{cur} - -.. math:: - :label: 17.43) - - NF_{alloc,livecroot\_ stor} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} a_{4} }{CN_{lw} } \left(1-f_{cur} \right) - -.. math:: - :label: 17.44) - - NF_{alloc,deadcroot} \_ =\frac{CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } f_{cur} - -.. math:: - :label: 17.45) - - NF_{alloc,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). - Autotrophic Respiration ---------------------------- @@ -442,19 +14,17 @@ defined as the carbon cost to support the metabolic activity of existing live tissue, while growth respiration is defined as the additional carbon cost for the synthesis of new growth. -13.7.1 Maintenance Respiration +Maintenance Respiration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Under the assumption that tissue nitrogen content is a suitable index of -cellular metabolic rate, maintenance respiration costs for live tissues -(leaf, live stem, live coarse root, and fine root) are calculated as -functions tissue nitrogen content and the relevant temperature, -following the empirical relationship reported by Ryan (1991): +Atkin et al. (2016) propose a model for respiration that is based on the leaf nitrogen content per unit area (:math:`NS_{narea}` (gN m :sup:`2` leaf), with an intercept parameter that is PFT dependant, and an acclimation term that depends upon the average temperature of the previous 10 day period :math:`t_{2m,10days}`, in Celsius. .. math:: - :label: 17.46) + :label: 17.46) - CF_{mr\_ leaf} \_ =NS_{leaf} MR_{base} MR_{Q10} ^{(T_{2m} -20)/10} + CF_{mr\_ leaf} = i_{atkin,pft} + (NS_{narea} 0.2061) - (0.0402 (t_{2m,10days})) + +The temperature dependance of leaf maintenance (dark) respiration is described in Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`. .. math:: :label: 17.47) @@ -471,14 +41,34 @@ following the empirical relationship reported by Ryan (1991): CF_{mr\_ froot} \_ =\sum _{j=1}^{nlevsoi}NS_{froot} rootfr_{j} MR_{base} MR_{Q10} ^{(Ts_{j} -20)/10} -where :math:`MR_{base}` (= 2.525e\ :sup:`-6` gC gN\ :sup:`-1` s\ :sup:`-1`) is the base rate of maintenance -respiration per unit nitrogen content, :math:`MR_{q10}` (= 2.0) is +where :math:`MR_{q10}` (= 2.0) is the temperature sensitivity for maintenance respiration, :math:`T_{2m}` (:sup:`o`\ C) is the air temperature at 2m height, :math:`Ts_{j}`* (:sup:`o`\ C) is the soil temperature at level *j*, and :math:`rootfr_{j}` is the fraction of fine roots distributed in soil level *j*. +.. table:: Atkin leaf respiration model intercept values. + + ======================== ============= + Plant functional type :math:`i_{atkin}` + ======================== ============= + NET Temperate 1.499 + NET Boreal 1.499 + NDT Boreal 1.499 + BET Tropical 1.756 + BET temperate 1.756 + BDT tropical 1.756 + BDT temperate 1.756 + BDT boreal 1.756 + BES temperate 2.075 + BDS temperate 2.075 + BDS boreal 2.075 + C\ :sub:`3` arctic grass 2.196 + C\ :sub:`3` grass 2.196 + C\ :sub:`4` grass 2.196 + ======================== ============= + Note that, for woody vegetation, maintenance respiration costs are not calculated for the dead stem and dead coarse root components. These components are assumed to consist of dead xylem cells, with no metabolic @@ -494,12 +84,12 @@ The total maintenance respiration cost is then given as: CF_{mr} =CF_{mr\_ leaf} +CF_{mr\_ froot} +CF_{mr\_ livestem} +CF_{mr\_ livecroot} . -13.7.2 Growth Respiration +Growth Respiration ^^^^^^^^^^^^^^^^^^^^^^^^^ -Growth respiration is calculated as a factor of 0.3 times the total +Growth respiration is calculated as a factor of 0.11 times the total carbon in new growth on a given timestep, based on construction costs -for a range of woody and non-woody tissues (Larcher, 1995). For new +for a range of woody and non-woody tissues (Atkin et al. in prep). For new carbon and nitrogen allocation that enters storage pools for subsequent display, it is not clear what fraction of the associated growth respiration should occur at the time of initial allocation, and what From 21daba770bede96ee552a88ecb5a8b7a4fe41849 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Fri, 1 Dec 2017 12:28:30 -0700 Subject: [PATCH 113/255] modifications to respiration. altered growth respiration description --- .../Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 0ec9d5e1d6..33b9477ed1 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -88,7 +88,8 @@ Growth Respiration ^^^^^^^^^^^^^^^^^^^^^^^^^ Growth respiration is calculated as a factor of 0.11 times the total -carbon in new growth on a given timestep, based on construction costs +carbon allocation to new growth (:math:`CF_{growth}`, after allocating carbon for N acquisition, +Chapter :numref:`rst_FUN`.)on a given timestep, based on construction costs for a range of woody and non-woody tissues (Atkin et al. in prep). For new carbon and nitrogen allocation that enters storage pools for subsequent display, it is not clear what fraction of the associated growth From 8a922b4caad36e64acd2df7b16770f6c3530bbd9 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Thu, 7 Dec 2017 11:20:00 -0700 Subject: [PATCH 114/255] added CLM(FATES) tech note to DGVM chapter. Refs still need formatting --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 3825 ++++++++++++++++- 1 file changed, 3676 insertions(+), 149 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 8608521802..72001f2827 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -1,157 +1,3684 @@ +====================================== +CLM(ED) model: Technical Documentation +====================================== + .. _rst_Dynamic Global Vegetation Model: -Dynamic Global Vegetation Model +Dynamic Global Vegetation =================================== -In CLM the user may choose to run the CN model as a dgvm (dynamic global -vegetation model) (CNDV). Note that CN must be active to run the dgvm in -CLM. In this section, a general description of the dgvm processes and -how they integrate with CN are provided. Further details are available -in the CLM3DGVM Technical Note (Levis et al. 2004). The focus here is on -the differences relative to the corresponding processes in the CLM3DGVM. - -As with the CLM3DGVM, CNDV can simulate biogeographical changes only for -natural vegetation. Although the vegetated land unit may be separated -into naturally vegetated and human managed land units to permit a -coexistence of natural and human managed vegetation, CNDV only works if -the human managed land units are fixed. CLM’s transient land cover and -land use change capability (see Chapter 21), which permits transitions -between natural and human managed plant functional types (PFTs), is -incompatible with the CNDV option at this time. - -CNDV was implemented by introducing CLM3DGVM code to the hourly CN -framework only to the extent necessary to simulate annual biogeography -updates. This includes the annual processes of light competition, -establishment, and survival [see sections 2.7 and 2.10, Levis et al. -(2004)] as they pertain to the calculations of PFT cover (FPC) and -population (P) but not processes related to carbon pools, leaf area -index (LAI), or canopy height. In CNDV we added complexity to the gap -mortality calculation with annual heat stress and growth efficiency -considerations from the corresponding CLM3DGVM algorithm [section 2.8, -Levis et al. (2004)]. All other ecosystem processes (allocation, -phenology, fire, etc.) are handled by CN modules. Unlike in the -CLM3DGVM, in CNDV, annual biogeography updates are interpolated to -hourly intervals. - -Establishment and survival -------------------------------- +What has changed +---------------- + +- Deprecation of the dynamic global vegetation model (DGVM): The CLM5.0 model contains the legancy 'CNDV' code, which runs the CLM4(CN) model in combination with the LPJ-derived dynamics vegetation model introduced in CLM3. While this capacity has not technically been removed from the model, the DGVM has not been tested in the development of CLM5 and is no longer scientifically supported. + +- Introduction of FATES: The Functionally Assembled Terrestrial Ecosystem Simulator (FATES) is the actively developed DGVM for the CLM5. + + +Technical Documentation for FATES +================================== + + +Preamble +======== + +| This document is a technical appendix to +| Fisher RA, Muszala S, Verteinstein M, Lawrence P, Xu C, McDowell NG, + Knox RG, Koven C, Holm J, Rogers BM, Lawrence D. Taking off the + training wheels: the properties of a dynamic vegetation model without + climate envelopes. Geoscientific Model Development Discussions. 2015 + Apr 1;8(4). +| https://pdfs.semanticscholar.org/396c/b9f172cb681421ed78325a2237bfb428eece.pdf + +Authors +======= + +Rosie Fisher, Stefan Muszala, Mariana Verteinstein, Peter Lawrence, Chonggang Xu,Nate McDowell, Ryan Knox, Charles Koven, Jennifer Holm, Brendan Rogers, David Lawrence, and Gordon Bonan. + +Acknowledgements +================ + +The development of the ideas in this document has benefitted from +conversation with many people, including William Bond, Peter Cox, Matthew Forest, Andrew Fox, William Hoffman, Peter Lawrence, Jeremy Lichstein, Heike Lischke, Mark Lomas, Nathan McDowell, Paul Moorcroft, Colin Prentice, Drew Purves, Naomi Tague, Benjamin Sanderson, Stephen Sitch, Abigail Swann, Anthony Walker, Mathew Williams, F.Ian Woodward \& S\"onke Zaehle. + + +Introduction +============ + +The CLM(ED) model is presented here as an option within the structure of +the Community Land Model (CLM). Ecosystem Demography (‘ED’), is a +concept derived from the work of :raw-latex:`\cite{mc_2001}` and is a +cohort model of vegetation competition and co-existence, allowing a +representation of the biosphere which accounts for the division of the +land surface into successional stages, and the competition for light +between height structured cohorts of representative trees of various +plant functional types. This implementation of the Ecosystem Demography +concept links the surface flux and canopy physiology concepts in the CLM +with numerous additional developments necessary to accommodate the new +model also documented here. These include a version of the SPITFIRE +(Spread and InTensity of Fire) model of +:raw-latex:`\parencite{thonicke2010}`, and an adoption of the concept of +‘perfect plasticity’ approach of +:raw-latex:`\parencite{purves2008,lichstein2011,weng2014}` in accounting +for the spatial arrangement of crowns. Novel algorithms accounting for +the fragmentation of coarse woody debris into chemical litter streams, +for the physiological optimisation of canopy thickness, for the +accumulation of seeds in the seed bank, for multi-layer multi-PFT +radiation transfer, for drought-deciduous and cold-deciduous phenology, +for carbon storage allocation, and for tree mortality under carbon +stress, are also included and presented here. + +This Document +------------- + +This document describes the implementation of the Ecosystem Demography +concept within the Community Land Model. It is intended as a +supplementary document to the main CLM technical note, which is at the +time of writing, the CLM4.5 technical note +:raw-latex:`\parencite{oleson2013}`. The material covered describes how +the Ecosystem Demography code is organized, how it interacts with the +pre-existing CLM routines, and the new aspects of plant physiology and +vegetation dynamics that are introduced further to those already +existing within the model. Numerous other implementations of the +Ecosystem Demography concept are in existence, in particular the ED2 +model, which is a fully operational land surface scheme +:raw-latex:`\parencite{medvigy2009}` which contains both the basic ED +concept and an array of physiological and ecological innovations +surrounding the basic concept. Therefore, to avoid confusion between the +concept of ‘Ecosystem Demography’ and the implementation of this concept +in different models, we refer our model as the ‘CLM(ED)’ throughout. + +The representation of ecosystem heterogeneity in the CLM(ED) +============================================================ + +The land surface of the Earth is heterogeneous for many reasons, driven +by variations in climate, edaphic history, ecological variability, +geological forcing and human interventions. Land surface models +represent this variability first by introducing a grid structure to the +land surface, allowing different atmospheric forcings to operate in each +grid cell, and subsequently by representing ‘sub-grid’ variability in +the surface properties. In the CLM, the land surface is divided into +numerous ‘landunits’ corresponding to the underlying condition of the +surface (e.g. soils, ice, lakes, bare ground) and then ‘columns’ +referring to elements of the surface that share below ground resources +(water & nutrients). Within the ‘soil’ landunit, for example, there are +separate columns for crops, and for natural vegetation, as these are +assumed to use separate resource pools. The CLM(ED) model at present +only operates on the naturally vegetated column. The ‘soil’ column is +sub-divided into numerous tiles, that correspond to statistical +fractions of the potentially vegetated land area. In the CLM 4.5 (and +all previous versions of the model), sub-grid tiling operates on the +basis of plant functional types (PFTs). That is, each piece of land is +assumed to be occupied by only one plant functional type, with multiple +PFT-specific tiles sharing a common soil water and nutrient pool. This +PFT-based tiling structure is the standard method used by most land +surface models deployed in climate prediction. + +The introduction of the Ecosystem Demography concept introduces +significant alterations to the representation of the land surface in the +CLM. In the CLM(ED), the tiling structure represents the disturbance +history of the ecosystem. Thus, some fraction of the land surface is +characterized as ‘recently disturbed’, some fraction has escaped +disturbance for a long time, and other areas will have intermediate +disturbances. Thus the ED concept essentially discretizes the trajectory +of succession from disturbed ground to ‘mature’ ecosystems. Within the +ED code, each ‘disturbance history class’ is referred to as a ‘patch’. +The word ‘patch’ has many possible interpretations, so it is important +to note that: **there is no spatial location associated with the concept +of a ‘patch’. It refers to a fraction of the potential vegetated area +consisting of all parts of the ecosystem with similar disturbance +history.** + +The ‘patch’ organizational structure in CLM thus replaces the previous +‘PFT’ structure in the organization heirarchy. The original hierarchical +land surface organizational structure of CLM as described in +:raw-latex:`\cite{oleson2013}` may be depicted as: + +.. math:: + + \mathbf{gridcell} \left\{ + \begin{array}{cc} + \mathbf{landunit} & \\ + \mathbf{landunit} &\left\{ + \begin{array}{ll} + \mathbf{column}&\\ + \mathbf{column}&\left\{ + \begin{array}{ll} + \mathbf{pft}&\\ + \mathbf{pft}&\\ + \mathbf{pft}&\\ + \end{array}\right.\\ + \mathbf{column}&\\ + \end{array}\right.\\ + \mathbf{landunit} & \\ + \end{array}\right. + +and the new structure is altered to the following: + +.. math:: + + \mathbf{gridcell} \left\{ + \begin{array}{cc} + \mathbf{landunit} & \\ + \mathbf{landunit} &\left\{ + \begin{array}{ll} + \mathbf{column}&\\ + \mathbf{column}&\left\{ + \begin{array}{ll} + \mathbf{patch}&\\ + \mathbf{patch}&\\ + \mathbf{patch}&\\ + \end{array}\right.\\ + \mathbf{column}&\\ + \end{array}\right.\\ + \mathbf{landunit} & \\ + \end{array}\right. + +Thus, each gridcell becomes a matrix of ‘patches’ that are +conceptualized by their ‘age since disturbance’ in years. This is the +equivalent of grouping together all those areas of a gridcell that are +‘canopy gaps’, into a single entity, and all those areas that are +‘mature forest’ into a single entity. + +Cohortized representation of tree populations +--------------------------------------------- + +Each common-disturbance-history patch is a notional ecosystem that might +in reality contain numerous individual plants which vary in their +physiological attributes, in height and in spatial position. One way of +addressing this heterogeneity is to simulate a forest of specific +individuals, and to monitor their behavior through time. This is the +approach taken by ‘gap’ and individual-based +:raw-latex:`\parencite{smith2001,sato2007,uriarte2009,fyllas2014}`. The +depiction of individuals typically implies that the outcome of the model +is stochastic. This is because we lack the necessary detailed knowledge +to simulate the individual plant’s fates. Thus gap models imply both +stochastic locations and mortality of plants. Thus, (with a genuinely +random seed) each model outcome is different, and an ensemble of model +runs is required to generate an average representative solution. Because +the random death of large individual trees can cause significant +deviations from the mean trajectory for a small plot (a typical +simulated plot size is 30m x 30 m) the number of runs required to +minimize these deviations is large and computationally expensive. For +this reason, models that resolve individual trees typically use a +physiological timestep of one day or longer (e.g. +:raw-latex:`\cite{smith2001,xiaodong2005,sato2007}` + +The approach introduced by the Ecosystem Demography model +:raw-latex:`\parencite{mc_2001}` is to group the hypothetical population +of plants into ‘cohorts’. In the notional ecosystem, after the +land-surface is divided into common-disturbance-history patches, the +population in each patch is divided first into plant functional types +(the standard approach to representing plant diversity in large scale +vegetation models), and then each plant type is represented as numerous +height classes. Importantly, **for each PFT/height class bin, we model +*one* representative individual plant, which tracks the average +properties of this ‘cohort’ of individual plants.** Thus, each +common-disturbance-history patch is typically occupied by a set of +cohorts of different plant functional types, and different height +classes within those plant functional types. Each cohort is associated +with a number of identical trees, :math:`n_{coh}` (where :math:`{coh}` +denotes the identification or index number for a given cohort).. + +The complete hierarchy of elements in the CLM(ED) is therefore now +described as follows: + +.. math:: + + \mathbf{gridcell}\left\{ + \begin{array}{cc} + \mathbf{landunit} & \\ + \mathbf{landunit} &\left\{ + \begin{array}{ll} + \mathbf{column}&\\ + \mathbf{column}&\left\{ + \begin{array}{ll} + \mathbf{patch}&\\ + \mathbf{patch}&\left\{ + \begin{array}{ll} + \mathbf{cohort}&\\ + \mathbf{cohort}&\\ + \mathbf{cohort}&\\ + \end{array}\right.\\ + \mathbf{patch}&\\ + \end{array}\right.\\ + \mathbf{column}&\\ + \end{array}\right.\\ + \mathbf{landunit} & \\ + \end{array}\right. + +Discretization of cohorts and patches +------------------------------------- + +Newly disturbed land and newly recruited seedlings can in theory be +generated at each new model timestep as the result of germination and +disturbance processes. If the new patches and cohorts established at +*every* timestep were tracked by the model structure, the computational +load would of course be extremely high (and thus equivalent to an +individual-based approach). A signature feature of the ED model is the +system by which ‘functionally equivalent’ patches and cohorts are fused +into single model entities to save memory and computational time. + +[1]_ This functionality requires that criteria are established for the +meaning of `functional equivalence’, which are by necessity slightly +subjective, as they represent ways of abstracting reality into a more +tractable mathematical representation. As an example of this, for +height-structured cohorts, we calculate the relativized differences in +height (:math:`h_{coh}`, m) between two cohorts of the same pft, +:math:`p` and :math:`q` as + +.. math:: d_{hite,p,q} = \frac{\mathrm{abs}.(h_{p-}h_{q})}{\frac{1}{2}(h_{p}+h_{q})} + +If :math:`d_{hite,p,q}` is smaller than some threshold :math:`t_{ch}`, +and they are of the same plant functional type, the two cohorts are +considered equivalent and merged to form a third cohort :math:`r`, with +the properties of cohort :math:`p` and :math:`q` averaged such that they +conserve mass. The model parameter :math:`t_{ch}` can be adjusted to +adjust the trade-off between simulation accuracy and computational load. +There is no theoretical optimal value for this threshold but it may be +altered to have finer or coarser model resolutions as needed. + +[2]_ Similarly, for common-disturbance-history patches, we again assign +a threshold criteria, which is then compared to the difference between +patches :math:`m` and :math:`n`, and if the difference is less than some +threshold value (:math:`t_{p}`) then patches are merged together, +otherwise they are kept separate. However, in contrast with +height-structured cohorts, where the meaning of the difference criteria +is relatively clear, how the landscape should be divided into +common-disturbance-history units is less clear. Several alternative +criteria are possible, including Leaf Area Index, total biomass and +total stem basal area. + +In this implementation of the CLM(ED) we assess the amount of +above-ground biomass in each PFT/plant diameter bin. Biomass is first +grouped into fixed diameter bins for each PFT (:math:`ft`) and a +significant difference in any bin will cause patches to remain +separated. This means that if two patches have similar total biomass, +but differ in the distribution of that biomass between diameter classes +or plant types, they remain as separate entities. Thus + +.. math:: B_{profile,m,dc,ft} = \sum_{d_{c,min}}^{d_{c,max}} (B_{ag,coh}n_{coh}) + +:math:`B_{profile,m,dc,ft}` is the binned above-ground biomass profile +for patch :math:`m`,\ :math:`d_{c}` is the diameter class. +:math:`d_{c,min}` and :math:`d_{c,max}` are the lower and upper +boundaries for the :math:`d_{c}` diameter class. :math:`B_{ag,coh}` and +:math:`n_{coh}` depict the biomass (KgC m\ :math:`^{-2}`) and the number +of individuals of each cohort respectively. A difference matrix between +patches :math:`m` and :math:`n` is thus calculated as + +.. math:: d_{biomass,mn,dc,ft} = \frac{\rm{abs}\it(B_{profile,m,hc,ft}-B_{profile,n,hc,ft})}{\frac{1}{2}(B_{profile,m,hc,ft}+B_{profile,n,hc,ft})} + +If all the values of :math:`d_{biomass,mn,hc,ft}` are smaller than the +threshold, :math:`t_{p}`, then the patches :math:`m` and :math:`n` are +fused together to form a new patch :math:`o`. + +To increase computational efficiency and to simplify the coding +structure of the model, the maximum number of patches is capped at +:math:`P_{no,max}`. To force the fusion of patches down to this number, +the simulation begins with a relatively sensitive discretization of +patches (:math:`t_{p}` = 0.2) but if the patch number exceeds the +maximum, the fusion routine is repeated iteratively until the two most +similar patches reach their fusion threshold. This approach maintains an +even discretization along the biomass gradient, in contrast to, for +example, simply fusing the oldest or youngest patches together. + +[3]_ The area of the new patch (:math:`A_{patch,o}`, m\ :math:`^{2}`) +is the sum of the area of the two existing patches, + +.. math:: A_{patch,o} = A_{patch,n} + A_{patch,m} + +and the cohorts ‘belonging’ to patches :math:`m` and :math:`n` now +co-occupy patch :math:`o`. The state properties of :math:`m` and +:math:`n` (litter, seed pools, etc. ) are also averaged in accordance +with mass conservation . + +Linked Lists: the general code structure of CLM(ED) +--------------------------------------------------- + +[4]_ The number of patches in each natural vegetation column and the +number of cohorts in any given patch are variable through time because +they are re-calculated for each daily timestep of the model. The more +complex an ecosystem, the larger the number of patches and cohorts. For +a slowly growing ecosystem, where maximum cohort size achieved between +disturbance intervals is low, the number of cohorts is also low. For +fast-growing ecosystems where many plant types are viable and maximum +heights are large, more cohorts are required to represent the ecosystem +with adequate complexity. + +In terms of variable structure, the creation of an array whose size +could accommodate every possible cohort would mean defining the maximum +potential number of cohorts for every potential patch, which would +result in very large amounts of wasted allocated memory, on account of +the heterogeneity in the number of cohorts between complex and simple +ecosystems (n.b. this does still happen for some variables at restart +timesteps). To resolve this, the cohort structure in the CLM(ED) model +does not use an array system for internal calculations. Instead it uses +a system of *linked lists* where each cohort structure is linked to the +cohorts larger than and smaller than itself using a system of pointers. +The shortest cohort in each patch has a ‘shorter’ pointer that points to +the *null* value, and the tallest cohort has a ‘taller’ pointer that +points to the null value. + +Instead of iterating along a vector indexed by :math:`coh`, the code +structures typically begin at the tallest cohort in a given patch, and +iterate until a null pointer is encountered. + +Using this structure, it is therefore possible to have an unbounded + upper limit on cohort number, and also to easily alter the ordering of + cohorts if, for example, a cohort of one functional type begins to + grow faster than a competitor of another functional type, and the + cohort list can easily be re-ordered by altering the pointer + structure. Each cohort has `pointers` indicating to which patch and + gridcell it belongs. The patch system is analogous to the cohort + system, except that patches are ordered in terms of their relative age, with + pointers to older and younger patches where cp\ :math:`_1` is the + oldest: + + +Indices used in CLM(ED) +----------------------- + +Some of the indices used in the CLM(ED) are similar to those used in the +standard CLM4.5 model; column (:math:`c`), land unit(\ :math:`l`), grid +cell(\ :math:`g`) and soil layer (:math:`j`). On account of the +additional complexity of the new representation of plant function, +several additional indices are introduced that describe the +discritization of plant type, fuel type, litter type, plant height, +canopy identity, leaf vertical structure and fuel moisture +characteristics. To provide a reference with which to interpret the +equations that follow, they are listed here. + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Table of subscripts used in this document } + ++------------------+-----------------------+ +| Parameter Symbol | Parameter Name | ++==================+=======================+ +| *ft* | Plant Functional Type | ++------------------+-----------------------+ +| *fc* | Fuel Class | ++------------------+-----------------------+ +| *lsc* | Litter Size Class | ++------------------+-----------------------+ +| *coh* | Cohort Index | ++------------------+-----------------------+ +| *patch* | Patch Index | ++------------------+-----------------------+ +| *Cl* | Canopy Layer | ++------------------+-----------------------+ +| *z* | Leaf Layer | ++------------------+-----------------------+ +| *mc* | Moisture Class | ++------------------+-----------------------+ + +.. raw:: latex + + \bigskip -The PFT distribution in the vegetated land unit is typically prescribed -in CLM (see section 2.1.2) except for the case when CNDV is active. In -CNDV the model begins with no PFT information per grid cell and -evaluates whether or not a PFT may establish or survive according to the -PFT’s bioclimatic limits (:numref:`Table Plant functional type (PFT) biogeography rules`). Shrub PFTs are treated as trees -at establishment. - -CNDV omits the CLM3DGVM’s annual introduction of saplings when a PFT can -establish. The CLM3DGVM merged sapling carbon pools with a PFT’s -existing carbon. The resultant leaf carbon (annual maximum value) would -update the FPC, i.e. the foliar projective cover or fraction of the -vegetated land unit occupied by the PFT [section 2.10, Levis et al. -(2004)]. Instead, CNDV updates the FPC using the PFT’s annual maximum -leaf carbon without an addition from saplings. For newly established -PFTs, CNDV assigns seed leaf carbon equal to 1 g C m\ :sup:`-2` of -land unit area and seed FPC equal to 0.05 for grasses and 0.000844 for -trees (values determined from CLM3DGVM simulations). The addition of -establishing individuals to *P*, a PFT’s population, is handled as in -the CLM3DGVM. - -*FPC* changes annually as in the CLM3DGVM but now is interpolated to an -hourly increment using the algorithms designed to conserve energy and -mass in the CLM’s dynamic land use option. - -Light competition +Cohort State Variables ---------------------- -In CNDV’s order of annual processes, light competition is invoked before -establishment and survival. However, light competition does not affect a -simulation starting from bare ground until the vegetation fills the land -unit (a few years at least). - -Light competition starts with a calculation updating *FPC*. For -reference, this update was included at the end of allocation in the -CLM3DGVM [section 2.6, Levis et al. (2004)]. - -Due to their height advantage, trees will cover up to 95% of the land -unit when their productivity permits, as in the CLM3DGVM, regardless of -grass and shrub productivity. Grasses get second priority, as in the -CLM3DGVM, even with shrubs included now. Shrubs, then, have access to -the remaining space and follow the tree algorithm for self thinning -[section 2.7, Levis et al. (2004)]. As a result, trees typically -dominate in the most productive regions, grasses in less productive -regions, and shrubs in the least productive non-desert regions (Zeng et -al. 2008). - -CN processes modified for the CNDV coupling ------------------------------------------------- - -Gap mortality and mortality from fire: Constant annual mortality rate of -0.02 is changed for trees and shrubs to an annual rate calculated as in -the CLM3DGVM accounting for background and stress mortality [section -2.8, Levis et al. (2004)]. The CN module converts the annual rate to -hourly. - -The CLM3DGVM used the concepts of average plant individual and PFT -population, *P*. CNDV retains these concepts in the light competition, -establishment, and survival calculations. In CNDV we account for the -individuals removed hourly from *P* in response to CN’s fire and gap -mortality, while the carbon pools per individual and FPC remain -constant. Ultimately, *P* updates should only affect the annual -processes of light competition, establishment, and survival, so the *P* -update may be moved to the end of the year in a future version of CNDV. - -Vegetation Structure Update: CN stocking is a constant, while in CNDV -stocking changes as P and FPC change. This affects the top-of-canopy -height calculation. CN specific leaf area and stem diameter calculations -are kept, while the height calculation is replaced with the CLM3DGVM’s -[section 2.6, Levis et al. (2004)]. CN stem area index (SAI) is kept. - -Allocation: CN calculates a PFT’s fraction of currently allocated carbon -relative to the total allocation instead of obtaining a constant value -from CLM’s PFT-physiology file. In CNDV, we returned to the constant -values in the old PFT-physiology file to get a reasonable simulation of -PFTs. For CNDV to use the calculated fraction, we will need to change -the algorithm for PFTs in early stages of growth. - -.. _Table Plant functional type (PFT) biogeography rules: - -.. table:: Plant functional type (PFT) biogeography rules with respect to climate. - - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | | Survival | | | | - +=============================================+==============================================+==============================================+=========================+========+ - | | :math:`{T}_{c,min}` (:math:`\circ`\ C) | :math:`{T}_{c,max}` (:math:`\circ`\ C) | :math:`{GDD}_{min}` | | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Tropical broadleaf evergreen tree (BET) | | 15.5 | No limit | 0 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Tropical broadleaf deciduous tree (BDT) | | 15.5 | No limit | 0 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Temperate needleleaf evergreen tree (NET) | | -2.0 | 22.0 | 900 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Temperate broadleaf evergreen tree (BET) | | 3.0 | 18.8 | 1200 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Temperate broadleaf deciduous tree (BDT) | | -17.0 | 15.5 | 1200 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Boreal needleleaf evergreen tree (NET) | | -32.5 | -2.0 | 600 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Boreal deciduous tree | | No limit | -2.0 | 350 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Temperate broadleaf deciduous shrub (BDS) | | -17.0 | No limit | 1200 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | Boreal broadleaf deciduous shrub (BDS) | | No limit | -2.0 | 350 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | C\ :sub:`4` | | 15.5 | No limit | 0 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | C\ :sub:`3` | | -17.0 | 15.5 | 0 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - | C\ :sub:`3` arctic | | No limit | -17.0 | 0 | - +---------------------------------------------+----------------------------------------------+----------------------------------------------+-------------------------+--------+ - -Adapted from Table 1 of Levis et al. (2004) to include shrub PFTs. -:math:`T_{c,\min }` , coldest minimum monthly air temperature for -survival of previously established PFTs; :math:`T_{c,\max }` , warmest -minimum monthly air temperature for establishment of new PFTs; -:math:`GDD_{\min }` , minimum annual growing degree-days above -5\ :math:`{}^\circ`\ C for establishment of new PFTs. Levis et al. -(2004) include an explanation of these variables and their use. +The unit of allometry in the ED model is the cohort. Each cohort +represents a group of plants with similar functional types and heights +that occupy portions of column with similar disturbance histories. The +state variables of each cohort therefore consist of several pieces of +information that fully describe the growth status of the plant and its +position in the ecosystem structure, and from which the model can be +restarted. The state variables of a cohort are as follows: + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{State Variables of `cohort' sructure} + ++-----------------+-----------------+-----------------+-----------------+ +| Quantity | Variable name | Units | Notes | ++=================+=================+=================+=================+ +| Plant | :math:`{\it{ft} | integer | | +| Functional Type | _{coh}}` | | | ++-----------------+-----------------+-----------------+-----------------+ +| Number of | :math:`n_{coh}` | n per | | +| Individuals | | 10000m\ :math:` | | +| | | ^{-2}` | | ++-----------------+-----------------+-----------------+-----------------+ +| Height | :math:`h_{coh}` | m | | ++-----------------+-----------------+-----------------+-----------------+ +| Diameter | :math:`\it{dbh_ | cm | | +| | {coh}}` | | | ++-----------------+-----------------+-----------------+-----------------+ +| Structural | :math:`{b_{stru | KgC | Stem wood | +| Biomass | c,coh}}` | plant\ :math:`^ | (above and | +| | | {-1}` | below ground) | ++-----------------+-----------------+-----------------+-----------------+ +| Alive Biomass | :math:`{b_{aliv | KgC | Leaf, fine root | +| | e,coh}}` | plant\ :math:`^ | and sapwood | +| | | {-1}` | | ++-----------------+-----------------+-----------------+-----------------+ +| Stored Biomass | :math:`{b_{stor | KgC | Labile carbon | +| | e,coh}}` | plant\ :math:`^ | reserve | +| | | {-1}` | | ++-----------------+-----------------+-----------------+-----------------+ +| Leaf memory | :math:`{l_{memo | KgC | Leaf mass when | +| | ry,coh}}` | plant\ :math:`^ | leaves are | +| | | {-1}` | dropped | ++-----------------+-----------------+-----------------+-----------------+ +| Canopy Layer | :math:`{C_{l,co | integer | 1 = top layer | +| | h}}` | | | ++-----------------+-----------------+-----------------+-----------------+ +| Phenological | :math:`{S_{phen | integer | 1=leaves off. | +| Status | ,coh}}` | | 2=leaves on | ++-----------------+-----------------+-----------------+-----------------+ +| Canopy trimming | :math:`C_{trim, | fraction | 1.0=max leaf | +| | coh}` | | area | ++-----------------+-----------------+-----------------+-----------------+ +| Patch Index | :math:`{p_{coh} | integer | To which patch | +| | }` | | does this | +| | | | cohort belong? | ++-----------------+-----------------+-----------------+-----------------+ + +Patch State Variables +--------------------- + +A patch, as discuss earlier, is a fraction of the landscape which +contains ecosystems with similar structure and disturbance history. A +patch has no spatial location. The state variables, which are +‘ecosystem’ rather than ‘tree’ scale properties, from which the model +can be restarted, are as follows + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{State variables of `patch' structure} + ++-------------+-------------+-------------+-------------+-------------+ +| Quantity | Variable | Units | Indexed By | | +| | name | | | | ++=============+=============+=============+=============+=============+ +| Area | :math:`\it{ | m\ :math:`^ | - | | +| | A_{patch}}` | {2}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| Age | :math:`age_ | years | - | | +| | {patch}` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Seed | :math:`seed_| KgC | :math:`ft` | | +| | {patch}` | m\ :math:`^ | | | +| | | {-2}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| Leaf Litter | :math:`l_{l | KgC | :math:`ft` | | +| | itter,patch | m\ :math:`^ | | | +| | }` | {-2}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| Root Litter | :math:`r_{l | KgC | :math:`ft` | | +| | itter,patch | m\ :math:`^ | | | +| | }` | {-2}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| AG Coarse | :math:` | KgC | Size Class | | +| Woody | {CWD}_{A | m\ :math:`^ | (lsc) | | +| Debris | G,patch}` | {-2}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| BG Coarse | :math:` | KgC | Size Class | | +| Woody | {CWD}_{B | m\ :math:`^ | (lsc) | | +| Debris | G,patch}` | {-2}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| Canopy | :math:`S_{c | - | Canopy | | +| Spread | ,patch}` | | Layer | | ++-------------+-------------+-------------+-------------+-------------+ +| Column | :math:`{l_{ | integer | - | | +| Index | patch}}` | | | | ++-------------+-------------+-------------+-------------+-------------+ + +.. raw:: latex + + \bigskip + +Model Structure +--------------- + +Code concerned with the Ecosystem Demography model interfaces with the +CLM model in four ways: i) During initialization, ii) During the +calculation of surface processes (albedo, radiation absorption, canopy +fluxes) each model time step (typically half-hourly), iii) During the +main invokation of the ED model code at the end of each day. Daily +cohort-level NPP is used to grow plants and alter the cohort structures, +disturbance processes (fire and mortality) operate to alter the patch +structures, and all fragmenting carbon pool dynamics are calculated. iv) +during restart reading and writing. The net assimilation (NPP) fluxes +attributed to each cohort are accumulated throughout each daily cycle +and passed into the ED code as the major driver of vegetation dynamics. + +Initialization of vegetation from bare ground +============================================= + +[5]_If the model is restarted from a bare ground state (as opposed to a +pre-existing vegetation state), the state variables above are +initialized as follows. First, the number of plants per PFT is allocated +according to the initial seeding density (:math:`S_{init}`, individuals +per m\ :math:`^{2}`) and the area of the patch :math:`A_{patch}`, which +in the first timestep is the same as the area of the notional ecosystem +:math:`A_{tot}`. The model has no meaningful spatial dimension, but we +assign a notional area such that the values of ‘:math:`n_{coh}`’ can be +attributed. The default value of :math:`A_{tot}` is one hectare (10,000 +m\ :math:`^{2}`), but the model will behave identically irrepective of +the value of this parameter. + +.. math:: n_{coh,0} = S_{init}A_{patch} + +Each cohort is initialized at the minimum canopy height +:math:`h_{min,ft}`, which is specified as a parameter for each plant +functional type and denotes the smallest size of plant which is tracked +by the model. Smaller plants are not considered, and their emergence +from the recruitment processes is unresolved and therefore implicitly +parameterized in the seedling establishment model.. The diameter of each +cohort is then specified using the log-linear allometry between stem +diameter and canopy height + +.. math:: \mathit{dbh}_{coh} = 10^{\frac{\log_{10}(h_{coh}) - c_{allom}}{m_{allom}} } + +where the slope of the log-log relationship, :math:`m_{allom}` is 0.64 +and the intercept :math:`c_{allom}` is 0.37. The structural biomass +associated with a plant of this diameter and height is given (as a +function of wood density, :math:`\rho`, g cm\ :math:`^{-3}`) + +.. math:: b_{struc,coh} =c_{str}h_{coh}^{e_{str,hite}} dbh_{coh}^{e_{str,dbh}} \rho_{ft}^{e_{str,dens}} + +taken from the original ED1.0 allometry +:raw-latex:`\parencite{mc_2001}` (values of the allometric constants in +Table `[table:allom] <#table:allom>`__. The maximum amount of leaf +biomass associated with this diameter of tree is calculated according to +the following allometry + +.. math:: b_{max,leaf,coh} =c_{leaf}\it{dbh}_{coh}^{e_{leaf,dbh}} \rho_{ft}^{e_{leaf,dens}} + +from this quantity, we calculate the active/fine root biomass +:math:`b_{root,coh}` as + +.. math:: b_{root,coh} = b_{max,leaf,coh}\cdot f_{frla} + +where :math:`f_{frla}` is the fraction of fine root biomass to leaf +biomass, assigned per PFT + +.. raw:: latex + + \captionof{table}{Parameters needed for model initialization.} + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | Default Value | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`h_{min}` | Minimum plant | m | 1.5 | +| | height | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`S_{init}`| Initial | Individuals | | +| | Planting | m\ :math:`^{-2}`| | +| | density | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`A_{tot}` | Model area | m\ :math:`^{2}` | 10,000 | ++-----------------+-----------------+-----------------+-----------------+ + +[table:init] + +Allocation of live biomass to leaves roots and sapwood +------------------------------------------------------ + +[6]_Total live biomass :math:`b_{alive}` is the state variable of the model +that describes the sum of the three live biomass pools leaf +:math:`b_{leaf}`, root :math:`b_{root}` and sapwood :math:`b_{sw}` (all +in kGC individual\ :math:`^{-1}`). The quantities are constrained by the +following + +.. math:: b_{alive} = b_{leaf} + b_{root} + b_{sw} + +Sapwood volume is a function of tree height and leaf biomass + +.. math:: b_{sw} = b_{leaf}\cdot h_{coh}\cdot f_{swh} + +where :math:`f_{swh}` is the ratio of sapwood mass (kgC) to leaf mass +per unit tree height (m). Also, root mass is a function of leaf mass + +.. math:: b_{root} = b_{leaf}\cdot f_{swh} + +Thus + +.. math:: b_{alive} = b_{leaf} + b_{leaf}\cdot f_{frla} + b_{leaf}\cdot h_{coh}\cdot f_{swh} + +Rearranging gives the fraction of biomass in the leaf pool +:math:`f_{leaf}` as + +.. math:: f_{leaf} = \frac{1}{1+h_{coh}\cdot f_{swh}+f_{frla} } + +Thus, we can determine the leaf fraction from the height at the tissue +ratios, and the phenological status of the cohort :math:`S_{phen,coh}`. + +.. math:: b_{leaf} = b_{alive} \cdot l _{frac} + +To divide the live biomass pool at restart, or whenever it is +recalculated, into its consituent parts, we first + +.. math:: + + b_{leaf} = \left\{ \begin{array}{ll} + b_{alive} \cdot l _{frac}&\textrm{for } S_{phen,coh} = 1\\ + &\\ + 0&\textrm{for } S_{phen,coh} = 0\\ + \end{array} \right. + +Because sometimes the leaves are dropped, using leaf biomass as a +predictor of root and sapwood would produce zero live biomass in the +winter. To account for this, we add the LAI memory variable +:math:`l_{memory}` to the live biomass pool to account for the need to +maintain root biomass when leaf biomass is zero. Thus, to calculated the +root biomass, we use + +.. math:: b_{root} = (b_{alive}+l_{memory})\cdot l_{frac} \cdot f_{frla} + +To calculated the sapwood biomass, we use + +.. math:: b_{sw} = (b_{alive}+l_{memory})\cdot l_{frac} \cdot f_{swh} \cdot h_{coh} + +.. raw:: latex + + \captionof{table}{Allometric Constants} + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | Default Value | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`c_{allom | Allometry | | 0.37 | +| }` | intercept | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`m_{allom | Allometry slope | | 0.64 | +| }` | | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`c_{str}` | Structural | | 0.06896 | +| | biomass | | | +| | multiplier | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`e_{str,d | Structural | | 1.94 | +| bh}` | Biomass dbh | | | +| | exponent | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`e_{str,h | Structural | | 0.572 | +| ite}` | Biomass height | | | +| | exponent | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`e_{str,d | Structural | | 0.931 | +| ens}` | Biomass density | | | +| | exponent | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`c_{leaf}`| Leaf biomass | | 0.0419 | +| | multiplier | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`e_{leaf, | Leaf biomass | | 1.56 | +| dbh}` | dbh exponent | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`e_{leaf, | Leaf biomass | | 0.55 | +| dens}` | density | | | +| | exponent | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{swh}` | Ratio of | m\ :math:`^{-1}`| | +| | sapwood mass to | | | +| | height | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{frla}`| Ratio of fine | - | 1.0 | +| | root mass to | | | +| | leaf mass | | | ++-----------------+-----------------+-----------------+-----------------+ + +[table:allom] + +Canopy Structure and the Perfect Plasticity Approximation +========================================================= + + [7]_ + +During initialization and every subsequent daily ED timestep, the canopy +structure model is called to determine how the leaf area of the +different cohorts is arranged relative to the incoming radiation, which +will then be used to drive the radiation and photosynthesis +calculations. This task requires that some assumptions are made about 1) +the shape and depth of the canopy within which the plant leaves are +arranged and 2) how the leaves of different cohorts are arranged +relative to each other. This set of assumptions are critical to model +performance in ED-like cohort based models, since they determine how +light resources are partitioned between competing plants of varying +heights, which has a very significant impact on how vegetation +distribution emerges from competition +:raw-latex:`\parencite{fisher2010}`. + +The standard ED1.0 model makes a simple ’flat disk’ assumption, that the +leaf area of each cohort is spread in an homogenous layer at one exact +height across entire the ground area represented by each patch. The +CLM(ED) model has diverged from this representation due to (at least) +two problematic emergent properties that we identified as generating +unrealistic behaviours espetially for large-area patches. + +1. Over-estimation of light competition . The vertical stacking of +cohorts which have all their leaf area at the same nominal height means +that when one cohort is only very slightly taller than it’s competitor, +it is completely shaded by it. This means that any small advantage in +terms of height growth translates into a large advantage in terms of +light competition, even at the seedling stage. This property of the +model artificially exaggerates the process of light competition. In +reality, trees do not compete for light until their canopies begin to +overlap and canopy closure is approached. + +2. Unrealistic over-crowding. The ‘flat-disk’ assumption has no +consideration of the spatial extent of tree crowns. Therefore it has no +control on the packing density of plants in the model. Given a mismatch +between production and mortality, entirely unrealistic tree densities +are thus possible for some combinations of recruitment, growth and +mortality rates. + +To account for the filling of space in three dimensions using the +one-dimensional representation of the canopy employed by CLM, we +implement a new scheme derived from that of +:raw-latex:`\cite{purves2008}`. Their argument follows the development +of an individual-based variant of the SORTIE model, called SHELL, which +allows the location of individual plant crowns to be highly flexible in +space. Ultimately, the solutions of this model possess an emergent +property whereby the crowns of the plants simply fill all of the +available space in the canopy before forming a distinct understorey. + +Purves et al. developed a model that uses this feature, called the +‘perfect plasticity approximation’, which assumes the plants are able to +perfectly fill all of the available canopy space. That is, at canopy +closure, all of the available horizontal space is filled, with +negligible gaps, owing to lateral tree growth and the ability of tree +canopies to grow into the available gaps (this is of course, an +over-simplified but potential useful ecosystem property). The ‘perfect +plasticity approximation’ (PPA) implies that the community of trees is +subdivided into discrete canopy layers, and by extension, each cohort +represented by the CLM(ED) model is assigned a canopy layer status flag, +:math:`C_L`. In this version, we set the maximum number of canopy layers +at 2 for simplicity, although is possible to have a larger number of +layers in theory. :math:`C_{L,coh}` = 1 means that all the trees of +cohort :math:`coh` are in the upper canopy (overstory), and +:math:`C_{L,coh}` = 2 means that all the trees of cohort :math:`coh` are +in the understorey. + +In this model, all the trees in the canopy experience full light on +their uppermost leaf layer, and all trees in the understorey experience +the same light (full sunlight attenuated by the average LAI of the upper +canopy) on their uppermost leaves, as described in the radiation +transfer section (more nuanced versions of this approach may be +investigated in future model versions). The canopy is assumed to be +cylindrical, the lower layers of which experience self-shading by the +upper layers. + +To determine whether a second canopy layer is required, the model needs +to know the spatial extent of tree crowns. Crown area, +:math:`A_{crown}`, m\ :math:`^{2}`, is defined as + +.. math:: A_{crown,coh} = \pi (dbh_{coh} S_{c,patch,Cl})^{1.56} + +where :math:`A_{crown}` is the crown area of a single tree canopy +(m:math:`^{-2}`) and :math:`S_{c,patch,Cl}` is the ‘canopy spread’ +parameter (m cm^-1) of this canopy layer, which is assigned as a +function of canopy space filling, discussed below. In contrast to +:raw-latex:`\cite{purves2008}` , we use an exponent, identical to that +for leaf biomass, of 1.56, not 2.0, such that tree leaf area index does +not change as a function of diameter. + +To determine whether the canopy is closed, we calculate the total canopy +area as: + +.. math:: A_{canopy} = \sum_{coh=1}^{nc,patch}{A_{crown,coh}.n_{coh}} + +where :math:`nc_{patch}` is the number of cohorts in a given patch. If +the area of all crowns :math:`A_{canopy}` (m:math:`^{-2}`) is larger +than the total ground area of a patch (:math:`A_{patch}`), then some +fraction of each cohort is demoted to the understorey. + +Under these circumstances, the ‘extra’ crown area :math:`A_{loss}` +(i.e., :math:`A_{canopy}` - :math:`A_p`) is moved into the understorey. +For each cohort already in the canopy, we determine a fraction of trees +that are moved from the canopy (:math:`L_c`) to the understorey. +:math:`L_c` is calculated as :raw-latex:`\cite{fisher2010}` + +.. math:: L_{c}= \frac{A_{loss,patch} w_{coh}}{\sum_{coh=1}^{nc,patch}{w_{coh}}} , + +where :math:`w_{coh}` is a weighting of each cohort determined by basal +diameter :math:`dbh` (cm) and the competitive exclusion coefficient +:math:`C_{e}` + +.. math:: w_{coh}=dbh_{coh}C_{e}. + +The higher the value of :math:`C_e` the greater the impact of tree +diameter on the probability of a given tree obtaining a position in the +canopy layer. That is, for high :math:`C_e` values, competition is +highly deterministic. The smaller the value of :math:`C_e`, the greater +the influence of random factors on the competitive exclusion process, +and the higher the probability that slower growing trees will get into +the canopy. Appropriate values of :math:`C_e` are poorly constrained but +alter the outcome of competitive processes. + +The process by which trees are moved between canopy layers is complex +because 1) the crown area predicted for a cohort to lose may be larger +than the total crown area of the cohort, which requires iterative +solutions, and 2) on some occasions (e.g. after fire), the canopy may +open up and require ‘promotion’ of cohorts from the understorey, and 3) +canopy area may change due to the variations of canopy spread values ( +:math:`S_{c,patch,Cl}`, see the section below for details) when +fractions of cohorts are demoted or promoted. Further details can be +found in the code references in the footnote. + +Horizontal Canopy Spread +------------------------ + + [8]_ + +:raw-latex:`\cite{purves2008}` estimated the ratio between canopy and +stem diameter :math:`c_{p}` as  0.1 m cm\ :math:`^{-1}` for canopy trees +in North American forests, but this estimate was made on trees in closed +canopies, whose shape is subject to space competition from other +individuals. Sapling trees have no constraints in their horizontal +spatial structure, and as such, are more likely to display their leaves +to full sunlight. Also, prior to canopy closure, light interception by +leaves on the sides of the canopy is also higher than it would be in a +closed canopy forest. If the ‘canopy spread’ parameter is constant for +all trees, then we simulate high levels of self-shading for plants in +unclosed canopies, which is arguably unrealistic and can lower the +productivity of trees in areas of unclosed canopy (e.g. low productivity +areas of boreal or semi-arid regions where LAI and canopy cover might +naturally be low). We here interpret the degree of canopy spread, +:math:`S_{c}` as a function of how much tree crowns interfere with each +other in space, or the total canopy area :math:`A_{canopy}`. However +:math:`A_{canopy}` itself is a function of :math:`S_{c}`, leading to a +circularity. :math:`S_{c}` is thus solved iteratively through time. + +Each daily model step, :math:`A_{canopy}` and the fraction of the +gridcell occupied by tree canopies in each canopy layer +(:math:`A_{f,Cl}` = :math:`A_{canopy,Cl}`/:math:`A_{patch}`) is +calculated based on :math:`S_{c}` from the previous timestep. If +:math:`A_{f}` is greater than a threshold value :math:`A_{t}`, +:math:`S_{c}` is increased by a small increment :math:`i`. The threshold +:math:`A_{t}` is, hypothetically, the canopy fraction at which light +competition begins to impact on tree growth. This is less than 1.0 owing +to the non-perfect spatial spacing of tree canopies. If :math:`A_{f,Cl}` +is greater than :math:`A_{t}`, then :math:`S_{c}` is reduced by an +increment :math:`i`, to reduce the spatial extent of the canopy, thus. + +.. math:: + + S_{c,patch,Cl,t+1} = \left\{ \begin{array}{ll} + S_{c,patch,Cl,t} + i& \textrm{for $A_{f,Cl} < A_{t}$}\\ + &\\ + S_{c,patch,Cl,t} - i& \textrm{for $A_{f,Cl} > A_{t}$}\\ + \end{array} \right. + +The values of :math:`S_{c}` are bounded to upper and lower limits. The +lower limit corresponds to the observed canopy spread parameter for +canopy trees :math:`S_{c,min}` and the upper limit corresponds to the +largest canopy extent :math:`S_{c,max}` + +.. math:: + + S_{c,patch,Cl} = \left\{ \begin{array}{ll} + S_{c,min}& \textrm{for } S_{c,patch,Cl}< S_{c,\rm{min}}\\ + &\\ + S_{c,max}& \textrm{for } S_{c,patch,Cl} > S_{c,\rm{max}}\\ + \end{array} \right. + +This iterative scheme requires two additional parameters (:math:`i` and +:math:`A_{t}`). :math:`i` affects the speed with which canopy spread +(and hence leaf are index) increase as canopy closure is neared. +However, the model is relatively insensitive to the choice of either +:math:`i` or :math:`A_{t}`. + +Definition of Leaf Area Profile +------------------------------- + + [9]_ + +Within each patch, the model defines and tracks cohorts of multiple +plant functional types that exist either in the canopy or understorey. +Light on the top leaf surface of each cohort in the canopy is the same, +and the rate of decay through the canopy is also the same for each PFT. +Therefore, we accumulate all the cohorts of a given PFT together for the +sake of the radiation and photosynthesis calculations (to avoid separate +calculations for every cohort). + +Therefore, the leaf area index for each patch is defined as a +three-dimensional array :math:`\mathit{lai}_{Cl,ft,z}` where :math:`C_l` +is the canopy layer, :math:`ft` is the functional type and :math:`z` is +the leaf layer within each canopy. This three-dimensional structure is +the basis of the radiation and photosynthetic models. In addition to a +leaf area profile matrix, we also define, for each patch, the area which +is covered by leaves at each layer as :math:`\mathit{carea}_{Cl,ft,z}`. + +Each plant cohort is already defined as a member of a single canopy +layer and functional type. This means that to generate the +:math:`x_{Cl,ft,z}` matrix, it only remains to divide the leaf area of +each cohort into leaf layers. First, we determine how many leaf layers +are occupied by a single cohort, by calculating the ‘tree LAI’ as the +total leaf area of each cohort divided by its crown area (both in +m\ :math:`^{2}`) + +.. math:: \mathit{tree}_{lai,coh} = \frac{b_{leaf,coh}\cdot\mathrm{sla}_{ft}}{A_{crown,coh}} + +where :math:`\mathrm{sla}_{ft}` is the specific leaf area in +m\ :math:`^{2}` KgC\ :math:`^{-1}` and :math:`b_{leaf}` is in kGC per +plant. + +Stem Area Index +~~~~~~~~~~~~~~~ + +Stem area index (SAI) is ratio of the total area of all woody stems on a +plant to the area of ground covered by the plant. During winter in +deciduous areas, the extra absorption by woody stems can have a +significant impact on the surface energy budget. However, in previous +‘big leaf’ versions of the CLM, computing the circumstances under which +stem area was visible in the absence of leaves was difficult and the +algorithm was largely heuristic as a result. Given the multi-layer +canopy introduced for CLM(ED), we can determine the leaves in the higher +canopy layers will likely shade stem area in the lower layers when +leaves are on, and therefore stem area index can be calculated as a +function of woody biomass directly. + +Literature on stem area index is particularly poor, as it’s estimation +is complex and not particularly amenable to the use of, for example, +assumptions of random distribution in space that are typically used to +calculate leaf area from light interception. +:raw-latex:`\cite{kucharik1998}` estimated that SAI visible from an +LAI2000 sensor was around 0.5 m^2 m^-2. :raw-latex:`\cite{low2001}` +estimate that the wood area index for Ponderosa Pine forest is +0.27-0.33. The existing CLM(CN) algorithm sets the minimum SAI at 0.25 +to match MODIS observations, but then allows SAI to rise as a function +of the LAI lost, meaning than in some places, predicted SAI can reach +value of 8 or more. Clearly, greater scientific input on this quantity +is badly needed. Here we determine that SAI is a linear function of +woody biomass, to at very least provide a mechanistic link between the +existence of wood and radiation absorbed by it. The non-linearity +between how much woody area exists and how much radiation is absorbed is +provided by the radiation absorption algorithm. Specifically, the SAI of +an individual cohort (:math:`\mathrm{tree}_{sai,coh}`, m\ :math:`^{2}` +m\ :math:`^{-2}`) is calculated as follows, + +.. math:: \mathrm{tree}_{sai,coh} = k_{sai}\cdot b_{struc,coh} , + +where :math:`k_{sai}` is the coefficient linking structural biomass to +SAI. The number of occupied leaf layers for cohort :math:`coh` +(:math:`n_{z,coh}`) is then equal to the rounded up integer value of the +tree SAI (:math:`{tree}_{sai,coh}`) and LAI (:math:`{tree}_{lai,coh}`) +divided by the layer thickness (i.e., the resolution of the canopy layer +model, in units of vegetation index (:math:`lai`\ +\ :math:`sai`) with a +default value of 1.0, :math:`\delta _{vai}` ), + +.. math:: n_{z,coh} = {\frac{\mathrm{tree}_{lai,coh}+\mathrm{tree}_{sai,coh}}{\delta_{vai}}}. + +The fraction of each layer that is leaf (as opposed to stem) can then be +calculated as + +.. math:: f_{leaf,coh} = \frac{\mathrm{tree}_{lai,coh}}{\mathrm{tree}_{sai,coh}+\mathrm{tree}_{lai,coh}}. + +Finally, the leaf area in each leaf layer pertaining to this cohort is +thus + +.. math:: + + \mathit{lai}_{z,coh} = \left\{ \begin{array}{ll} + \delta_{vai} \cdot f_{leaf,coh} \frac{A_{canopy,coh}}{A_{canopy,patch}}& \textrm{for $i=1,..., i=n_{z,coh}-1$}\\ + &\\ + \delta_{vai} \cdot f_{leaf,coh} \frac{A_{canopy,coh}}{A_{canopy,patch}}\cdot r_{vai}& \textrm{for $i=n_{z,coh}$}\\ + \end{array} \right. + + and the stem area index is + +.. math:: + + \mathit{sai}_{z,coh} = \left\{ \begin{array}{ll} + \delta_{vai} \cdot (1-f_{leaf,coh})\frac{A_{canopy,coh}}{A_{canopy,patch}}& \textrm{for $i=1,..., i=n_{z,coh}-1$}\\ + &\\ + \delta_{vai} \cdot (1-f_{leaf,coh}) \frac{A_{canopy,coh}}{A_{canopy,patch}}\cdot r_{vai}& \textrm{for $i=n_{z,coh}$}\\ + \end{array} \right. + +where :math:`r_{vai}` is the remainder of the canopy that is below the +last full leaf layer + +.. math:: r_{vai} =(\mathrm{tree}_{lai,coh} + \mathrm{tree}_{sai,coh}) - (\delta _{vai} \cdot (n_{z,coh} -1)). + +:math:`A_{canopy,patch}` is the total canopy area occupied by plants in +a given patch (m:math:`^{2}`) and is calculated as follows, + +.. math:: A_{canopy,patch} = \textrm{min}\left( \sum_{coh=1}^{coh = ncoh}A_{canopy,coh}, A_{patch} \right). + +The canopy is conceived as a cylinder, although this assumption could be +altered given sufficient evidence that canopy shape was an important +determinant of competitive outcomes, and the area of ground covered by +each leaf layer is the same through the cohort canopy. With the +calculated SAI and LAI, we are able to calculate the complete canopy +profile. Specifically, the relative canopy area for the cohort +:math:`{coh}` is calculated as + +.. math:: \mathit{area}_{1:nz,coh} = \frac{A_{crown,coh}}{A_{canopy,patch}}. + +The total occupied canopy area for each canopy layer (:math:`Cl`), plant +functional type (:math:`ft`) and leaf layer (:math:`z`) bin is thus + +.. math:: + + \mathit{c}_{area,Cl,ft,z} = \sum_{coh=1}^{coh=ncoh} area_{1:nz,coh} + +where :math:`ft_{coh}=ft` and :math:`Cl_{coh} = Cl.` + +All of these quantities are summed across cohorts to give the complete +leaf and stem area profiles, + +.. math:: + + \mathit{lai} _{Cl,ft,z} = \sum_{coh=1}^{coh=ncoh} \mathit{lai}_{z,coh} + +.. math:: + + \mathit{sai}_{Cl,ft,z} = \sum_{coh=1}^{coh=ncoh} \mathit{sai}_{z,coh} + + +Burial of leaf area by snow +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The calculations above all pertain to the total leaf and stem area +indices which charecterize the vegetation structure. In addition, the +model must know when the vegetation is covered by snow, and by how much, +so that the albedo and energy balance calculations can be adjusted +accordingly. Therefore, we calculated a ‘total’ and ‘exposed’ +:math:`lai` and :math:`sai` profile using a representation of the bottom +and top canopy heights, and the depth of the average snow pack. For each +leaf layer :math:`z` of each cohort, we calculate an ‘exposed fraction +:math:`f_{exp,z}` via consideration of the top and bottom heights of +that layer :math:`h_{top,z}` and :math:`h_{bot,z}` (m), + +.. math:: + + \begin{array}{ll} + h_{top,z} = h_{coh} - h_{coh}\cdot f_{crown,ft}\cdot\frac{z}{n_{z,coh}}& \\ + &\\ + h_{bot,z} = h_{coh} - h_{coh}\cdot f_{crown,ft}\cdot\frac{z+1}{n_{z,coh}}&\\ + \end{array} + +where :math:`f_{crown,ft}` is the plant functional type (:math:`ft`) +specific fraction of the cohort height that is occupied by the crown. +Specifically, the ‘exposed fraction :math:`f_{exp,z}` is calculated as +follows, + +.. math:: + + f_{exp,z}\left\{ \begin{array}{ll} + = 1.0 & h_{bot,z}> d_{snow}\\ + &\\ + = \frac{d_{snow} -h_{bot,z}}{h_{top,z}-h_{bot,z}} & h_{top,z}> d_{snow}, h_{bot,z}< d_{snow}\\ + &\\ + = 0.0 & h_{top,z}< d_{snow}\\ + \end{array} \right. + +The resulting exposed (:math:`elai, esai`) and total +(:math:`tlai, tsai`) leaf and stem area indicies are calculated as + +.. math:: + + \begin{array}{ll} + \mathit{elai} _{Cl,ft,z} &= \mathit{lai} _{Cl,ft,z} \cdot f_{exp,z}\\ + \mathit{esai} _{Cl,ft,z} &= \mathit{sai} _{Cl,ft,z} \cdot f_{exp,z}\\ + \mathit{tlai} _{Cl,ft,z} &= \mathit{lai} _{Cl,ft,z}\\ + \mathit{tsai} _{Cl,ft,z} &= \mathit{sai} _{Cl,ft,z} \ + \end{array} , + +and are used in the radiation interception and photosynthesis algorithms +described later. + ++-------------+-------------+-------------+-------------+-------------+ +| Parameter | Parameter | Units | Notes | Indexed by | +| Symbol | Name | | | | ++=============+=============+=============+=============+=============+ +| :math:` | Thickness | m\ :math:`^ | | | +| \delta_ | of single | {-2}`\ m\ : | | | +| {vai}` | canopy | math:`^{-2}`| | | +| | layer | | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`C_e` | Competitive | none | | | +| | Exclusion | | | | +| | Parameter | | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`c_{p | Minimum | m\ :math:`^ | | | +| ,min}` | canopy | {2}` | | | +| | spread | cm\ :math:` | | | +| | | ^{-1}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`c_{p | Competitive | m\ :math:`^ | | | +| ,max}` | Exclusion | {2}` | | | +| | Parameter | cm\ :math:` | | | +| | | ^{-1}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`i` | Incremental | m\ :math:`^ | | | +| | change in | {2}` | | | +| | :math:`c_p` | cm\ :math:` | | | +| | | ^{-1}` | | | +| | | y\ :math:`^ | | | +| | | {-1}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`A_t` | Threshold | none | | | +| | canopy | | | | +| | closure | | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`f_{c | Crown | none | | :math:`ft` | +| rown,ft}` | fraction | | | | ++-------------+-------------+-------------+-------------+-------------+ +| :math:`k_{s | Stem area | m^2 KgC^-1 | | | +| ai}` | per unit | | | | +| | woody | | | | +| | biomass | | | | ++-------------+-------------+-------------+-------------+-------------+ + +.. raw:: latex + + \bigskip + +Radiation Transfer +================== + +Fundamental Radiation Transfer Theory +------------------------------------- + +[10]_The first interaction of the land surface with the properties of +vegetation concerns the partitioning of energy into that which is +absorbed by vegetation, reflected back into the atmosphere, and absorbed +by the ground surface. Older versions of the CLM have utilized a +‘two-stream’ approximation +:raw-latex:`\parencite{sellers1985,sellers1996}` that provided an +empirical solution for the radiation partitioning of a multi-layer +canopy for two streams, of diffuse and direct light. However, +implementation of the Ecosystem Demography model requires a) the +adoption of an explicit multiple layer canopy b) the implementation of a +multiple plant type canopy and c) the distinction of canopy and +under-storey layers, in-between which the radiation streams are fully +mixed. The radiation mixing between canopy layers is necessary as the +position of different plants in the under-storey is not defined +spatially or relative to the canopy trees above. In this new scheme, we +thus implemented a one-dimensional scheme that traces the absorption, +transmittance and reflectance of each canopy layer and the soil, +iterating the upwards and downwards passes of radiation through the +canopy until a pre-defined accuracy tolerance is reached. This approach +is based on the work of :raw-latex:`\cite{norman1979}`. + +Here we describe the basic theory of the radiation transfer model for +the case of a single homogenous canopy, and in the next section we +discuss how this is applied to the multi layer multi PFT canopy in the +CLM(ED) implementation. The code considers the fractions of a single +unit of incoming direct and a single unit of incoming diffuse light, +that are absorbed at each layer of the canopy for a given solar angle +(:math:`\alpha_{s}`, radians). Direct radiation is extinguished through +the canopy according to the coefficient :math:`k_{dir}` that is +calculated from the incoming solar angle and the dimensionless leaf +angle distribution parameter (:math:`\chi`) as + +.. math:: k_{dir} = g_{dir} / \sin(\alpha_s)\\ + +where + +.. math:: g_{dir} = \phi_1 + \phi_2 \cdot \sin(\alpha_s)\\ + +and + +.. math:: + + \begin{array} {l} + \phi_1 = 0.5 - 0.633\chi_{l} - 0.33\chi_l ^2\\ + \phi_2 =0.877 (1 - 2\phi_1)\\ + + \end{array} + +The leaf angle distribution is a descriptor of how leaf surfaces are +arranged in space. Values approaching 1.0 indicate that (on average) the +majority of leaves are horizontally arranged with respect to the ground. +Values approaching -1.0 indicate that leaves are mostly vertically +arranged, and a value of 0.0 denotes a canopy where leaf angle is random +(a ‘spherical’ distribution). + +According to Beer’s Law, the fraction of light that is transferred +through a single layer of vegetation (leaves or stems) of thickness +:math:`\delta_{vai}`, without being intercepted by any surface, is + +.. math:: \mathit{tr}_{dir} = e^{-k_{dir} \delta_{vai}} + +and the incident direct radiation transmitted to each layer of the +canopy (:math:`dir_{tr,z}`) is thus calculated from the cumulative leaf +area ( :math:`L_{above}` ) shading each layer (:math:`z`): + +.. math:: \mathit{dir}_{tr,z} = e^{-k_{dir} L_{above,z}} + +The fraction of the leaves :math:`f_{sun}` that are exposed to direct +light is also calculated from the decay coefficient :math:`k_{dir}`. + +.. math:: + + \begin{array}{l} + f_{sun,z} = e^{-k_{dir} L_{above,z}}\\ + \rm{and} + \\ f_{shade,z} = 1-f_{sun,z} + \end{array} + +where :math:`f_{shade,z}` is the fraction of leaves that are shaded +from direct radiation and only receive diffuse light. + +Diffuse radiation, by definition, enters the canopy from a spectrum of +potential incident directions, therefore the un-intercepted transfer +(:math:`tr_{dif}`) through a leaf layer of thickness :math:`\delta_l` is +calculated as the mean of the transfer rate from each of 9 different +incident light directions (:math:`\alpha_{s}`) between 0 and 180 degrees +to the horizontal. + +.. math:: \mathit{tr}_{dif} = \frac{1}{9} \sum\limits_{\alpha_s=5\pi/180}^{\alpha_s=85\pi/180} e^{-k_{dir,l} \delta_{vai}} \\ \\ + +.. math:: tr_{dif}= \frac{1}{9} \pi \sum_{\alpha s=0}^{ \pi / 2} \frac{e^{-gdir} \alpha_s}{\delta_{vai} \cdot \rm{sin}(\alpha_s) \rm{sin}(\alpha_s) \rm{cos}(\alpha_s)} + +The fraction (1-:math:`tr_{dif}`) of the diffuse radiation is +intercepted by leaves as it passes through each leaf layer. Of this, +some fraction is reflected by the leaf surfaces and some is transmitted +through. The fractions of diffuse radiation reflected from +(:math:`\mathit{refl}_{dif}`) and transmitted though +(:math:`\mathit{tran}_{dif}`) each layer of leaves are thus, +respectively + +.. math:: + + \begin{array}{l} + \mathit{refl_{dif}} = (1 - tr_{dif}) \rho_{l,ft}\\ + \mathit{tran}_{dif} = (1 - tr_{dif}) \tau_{l,ft} + tr_{dif} + \end{array} + +where :math:`\rho_{l,ft}` and :math:`\tau_{l,ft}` are the fractions of +incident light reflected and transmitted by individual leaf surfaces. + +Once we know the fractions of light that are transmitted and reflected +by each leaf layer, we begin the process of distributing light through +the canopy. Starting with the first leaf layer (:math:`z`\ =1), where +the incident downwards diffuse radiation (:math:`\mathit{dif}_{down}`) +is 1.0, we work downwards for :math:`n_z` layers, calculating the +radiation in the next layer down (:math:`z+1`) as: + +.. math:: \mathit{dif}_{down,z+1} = \frac{\mathit{dif}_{down,z} \mathit{tran}_{dif} } {1 - \mathit{r}_{z+1} \mathit{refl}_{dif}} + +Here, :math:`\mathit{dif}_{down,z} \mathit{tran}_{dif}` calculates the +fraction of incoming energy transmitted downwards onto layer +:math:`z+1`. This flux is then increased by the additional radiation +:math:`r_z` that is reflected upwards from further down in the canopy to +layer :math:`z`, and then is reflected back downwards according to the +reflected fraction :math:`\mathit{refl_{dif}}`. The more radiation in +:math:`\mathit{r}_{z+1} \mathit{refl}_{dif}`, the smaller the +denominator and the larger the downwards flux. :math:`r` is also +calculated sequentially, starting this time at the soil surface layer +(where :math:`z = n_z+1`) + +.. math:: r_{nz+1} = alb_s + +where :math:`alb_s` is the soil albedo characteristic. The upwards +reflected fraction :math:`r_z` for each leaf layer, moving upwards, is +then :raw-latex:`\cite{norman1979}` + +.. math:: r_z = \frac{r_{z+1} \times \mathit{tran}_{dif} ^{2} }{ (1 - r_{z+1} \mathit{refl_{dif}}) + \mathit{refl_{dif}}}. + +The corresponding upwards diffuse radiation flux is therefore the +fraction of downwards radiation that is incident on a particular layer, +multiplied by the fraction that is reflected from all the lower layers: + +.. math:: \mathit{dif}_{up,z} = r_z \mathit{dif}_{down,z+1} + +Now we have initial conditions for the upwards and downwards diffuse +fluxes, these must be modified to account for the fact that, on +interception with leaves, direct radiation is transformed into diffuse +radiation. In addition, the initial solutions to the upwards and +downwards radiation only allow a single ‘bounce’ of radiation through +the canopy, so some radiation which might be intercepted by leaves +higher up is potentially lost. Therefore, the solution to this model is +iterative. The iterative solution has upwards and a downwards components +that calculate the upwards and downwards fluxes of total radiation at +each leaf layer (:math:`rad_{dn, z}` and :math:`rad_{up, z}`) . The +downwards component begins at the top canopy layer (:math:`z=1`). Here +we define the incoming solar diffuse and direct radiation +(:math:`\it{solar}_{dir}` and :math:`\it{solar}_{dir}` respectively). + +.. math:: + + \begin{array}{l} + \mathit{dif}_{dn,1} = \it{solar}_{dif} \\ + \mathit{rad}_{dn, z+1} = \mathit{dif}_{dn,z} \cdot \mathit{tran}_{dif} +\mathit{dif}_{up,z+1} \cdot \mathit{refl}_{dif} + \mathit{solar}_{dir} \cdot dir_{tr,z} (1- tr_{dir}) \tau_l. + \end{array} + +The first term of the right-hand side deals with the diffuse radiation +transmitted downwards, the second with the diffuse radiation travelling +upwards, and the third with the direct radiation incoming at each layer +(:math:`dir_{tr,z}`) that is intercepted by leaves +(:math:`1- tr_{dir}`) and then transmitted through through the leaf +matrix as diffuse radiation (:math:`\tau_l`). At the bottom of the +canopy, the light reflected off the soil surface is calculated as + +.. math:: rad _{up, nz} = \rm{\it{dif}}_{down,z} \cdot salb_{dif} +\it{solar}_{dir} \cdot dir_{tr,z} salb_{dir}. + +The upwards propagation of the reflected radiation is then + +.. math:: rad_{up, z} = \mathit{dif}_{up,z+1} \cdot \mathit{tran}_{dif} +\mathit{dif}_{dn,z} \cdot \mathit{refl}_{dif} + \it{solar}_{dir} \cdot dir_{tr,z} (1- tr_{dir}) \rho_l. + +Here the first two terms deal with the diffuse downwards and upwards +fluxes, as before, and the third deals direct beam light that is +intercepted by leaves and reflected upwards. These upwards and downwards +fluxes are computed for multiple iterations, and at each iteration, +:math:`rad_{up, z}` and :math:`rad_{down, z}` are compared to their +values in the previous iteration. The iteration scheme stops once the +differences between iterations for all layers is below a predefined +tolerance factor, (set here at :math:`10^{-4}`). Subsequently, the +fractions of absorbed direct (:math:`abs_{dir,z}`) and diffuse +(:math:`abs_{dif,z}`) radiation for each leaf layer then + +.. math:: abs_{dir,z} = \it{solar}_{dir} \cdot dir_{tr,z} \cdot (1- tr_{dir}) \cdot (1 - \rho_l-\tau_l) + +.. math:: abs_{dif,z} = (\mathit{dif}_{dn,z} + \mathit{dif}_{up,z+1} ) \cdot (1 - tr_{dif}) \cdot (1 - \rho_l-\tau_l). + +and, the radiation energy absorbed by the soil for the diffuse and +direct streams is is calculated as + +.. math:: \it{abs}_{soil} = \mathit{dif}_{down,nz+1} \cdot (1 - salb_{dif}) +\it{solar}_{dir} \cdot dir_{tr,nz+1} \cdot (1- salb_{dir}). + +Canopy level albedo is denoted as the upwards flux from the top leaf +layer + +.. math:: \it{alb}_{canopy}= \frac{\mathit{dif}_{up,z+1} }{ \it{solar}_{dir} + \it{solar}_{dif}} + +and the division of absorbed energy into sunlit and shaded leaf +fractions, (required by the photosynthesis calculations), is + +.. math:: abs_{sha,z} = abs_{dif,z} \cdot f_{sha} + +.. math:: abs_{sun,z} = abs_{dif,z} \cdot f_{sun}+ abs_{dir,z} + +Resolution of radiation transfer theory within the CLM(ED) canopy structure +--------------------------------------------------------------------------- + +The radiation transfer theory above, was described with reference to a +single canopy of one plant functional type, for the sake of clarity of +explanation. The CLM(ED) model, however, calculates radiative and +photosynthetic fluxes for a more complex hierarchical structure within +each patch/time-since-disturbance class, as described in the leaf area +profile section. Firstly, we denote two or more canopy layers (denoted +:math:`C_l`). The concept of a ‘canopy layer’ refers to the idea that +plants are organized into discrete over and under-stories, as predicted +by the Perfect Plasticity Approximation +:raw-latex:`\parencite{purves2008,fisher2010}`. Within each canopy layer +there potentially exist multiple cohorts of different plant functional +types and heights. Within each canopy layer, :math:`C_l`, and functional +type, :math:`ft`, the model resolves numerous leaf layers ‘:math:`z`’, +and, for some processes, notably photosynthesis, each leaf layer is +split into a fraction of sun and shade leaves, :math:`f_{sun}` and +:math:`f_{sha}`, respectively. + +The radiation scheme described in Section is solved explicitly for this +structure, for both the visible and near-infrared wavebands, according +to the following assumptions. + +- A ‘canopy layer’ (:math:`C_{L}`) refers to either the over or understorey + +- A ‘leaf layer’ (:math:`z`) refers to the discretization of the LAI + within the canopy of a given plant functional type. + +- All PFT’s in the same canopy layer have the same solar radiation + incident on the top layer of the canopy + +- Light is transmitted through the canopy of each plant functional type independently + +- Between canopy layers, the light streams from different plant + functional types are mixed, such that the (undefined) spatial + location of plants in lower canopy layers does not impact the amount + of light received. + +- Where understorey layers fill less area than the overstorey layers, + radiation is directly transferred to the soil surface. + +- All these calculations pertain to a single patch, so we omit the + ‘patch’ subscript for simplicity in the following discussion. + +Within this framework, the majority of the terms in the radiative +transfer scheme are calculated with indices of :math:`C_L`, +:math:`\it{ft}` and :math:`z`. In the following text, we revisit the +simplified version of the radiation model described above, and explain +how it is modified to account for the more complex canopy structure used +by the CLM(ED). + +Firstly, the light penetration functions, :math:`k_{dir}` and +:math:`g_{dir}` are described as functions of :math:`\it{ft}`, because +the leaf angle distribution, :math:`\chi_l`, is a pft-specific +parameter. Thus, the diffuse irradiance transfer rate, :math:`tr_{dif}` +is also :math:`\it{ft}` specific because :math:`g_{dir}`, on which it +depends, is a function of :math:`\chi_l`. + +The amount of direct light reaching each leaf layer is a function of the +leaves existing above the layer in question. If a leaf layer ‘:math:`z`’ +is in the top canopy layer (the over-storey), it is only shaded by +leaves of the same PFT so :math:`k_{dir}` is unchanged from equation. If +there is more than one canopy layer (:math:`C_{l,max}>1`), then the +amount of direct light reaching the top leaf surfaces of the +second/lower layer is the weighted average of the light attenuated by +all the parallel tree canopies in the canopy layer above, thus. + +.. math:: dir_{tr,Cl,:,1} =\sum_{ft=1}^{npft}{(dir_{tr,Cl,ft,z_{max}} \cdot c_{area,Cl-1,ft,z_{max}})} + +where :math:`\it{pft}_{wt}` is the areal fraction of each canopy layer +occupied by each functional type and :math:`z_{max}` is the index of the +bottom canopy layer of each pft in each canopy layer (the subscripts +:math:`C_l` and :math:`ft` are implied but omitted from all +:math:`z_{max}` references to avoid additional complications) + +Similarly, the sunlit fraction for a leaf layer ‘:math:`z`’ in the +second canopy layer (where :math:`C_l > 1`) is + +.. math:: f_{sun,Cl,ft,z} = W_{sun,Cl} \cdot e^{k_{dir,ft,laic,z}} + +where :math:`W_{sun,Cl}` is the weighted average sunlit fraction in the +bottom layer of a given canopy layer. + +.. math:: W_{sun,Cl} = \sum_{ft=1}^{npft}{(f_{sun,Cl-1,ft,zmax} \cdot c_{area,Cl-1,ft,zmax})} + +Following through the sequence of equations for the simple single pft +and canopy layer approach above, the :math:`\mathit{refl}_{dif}` and +:math:`\mathit{tran}_{dif}` fluxes are also indexed by :math:`C_l`, +:math:`\it{ft}`, and :math:`z`. The diffuse radiation reflectance ratio +:math:`r_z` is also calculated in a manner that homogenizes fluxes +between canopy layers. For the canopy layer nearest the soil +(:math:`C_l` = :math:`C_{l,max}`). For the top canopy layer +(:math:`C_l`\ =1), a weighted average reflectance from the lower layers +is used as the baseline, in lieu of the soil albedo. Thus: + +.. math:: r_{z,Cl,:,1} = \sum_{ft=1}^{npft}{(r_{z,Cl-1,ft,1} \it{pft}_{wt,Cl-1,ft,1})} + +For the iterative flux resolution, the upwards and downwards fluxes are +also averaged between canopy layers, thus where :math:`C_l>1` + +.. math:: rad_{dn, Cl,ft,1} = \sum_{ft=1}^{npft}{(rad_{dn, Cl-1,ft,zmax} \cdot \it{pft}_{wt,Cl-1,ft,zmax})} + +and where :math:`C_l` =1, and :math:`C_{l,max}>1` + +.. math:: rad_{up,Cl,ft,zmax} = \sum_{ft=1}^{npft}{(rad_{up, Cl+1,ft,1} \cdot \it{pft}_{wt,Cl+1,ft,1})} + +The remaining terms in the radiation calculations are all also indexed +by :math:`C_l`, :math:`ft` and :math:`z` so that the fraction of +absorbed radiation outputs are termed :math:`abs_{dir,Cl,ft,z}` and +:math:`abs_{dif,Cl,ft,z}`. The sunlit and shaded absorption rates are +therefore + +.. math:: abs_{sha,Cl,ft,z} = abs_{dif,Cl,ft,z}\cdot f_{sha,Cl,ft,z} + +and + +.. math:: abs_{sun,Cl,ft,z} = abs_{dif,Cl,ft,z} \cdot f_{sun,Cl,ft,z}+ abs_{dir,Cl,ft,z} + +The albedo of the mixed pft canopy is calculated as the weighted average +of the upwards radiation from the top leaf layer of each pft where +:math:`C_l`\ =1: + +.. math:: \it{alb}_{canopy}= \sum_{ft=1}^{npft}{\frac{\mathit{dif}_{up,1,ft,1} \it{pft}_{wt,1,ft,1}} {\it{solar}_{dir} + \it{solar}_{dif}}} + +The radiation absorbed by the soil after passing through through +under-storey vegetation is: + +.. math:: \it{abs}_{soil}= \sum_{ft=1}^{npft}{ \it{pft}_{wt,1,ft,1}( \mathit{dif}_{down,nz+1} (1 - salb_{dif}) +\it{solar}_{dir} dir_{tr,nz+1} (1- salb_{dir}))} + +to which is added the diffuse flux coming directly from the upper +canopy and hitting no understorey vegetation. + +.. math:: \it{abs}_{soil}= \it{abs}_{soil}+dif_{dn,2,1} (1- \sum_{ft=1}^{npft}{\it{pft}_{wt,1,ft,1}}) (1 - salb_{dif}) + +and the direct flux coming directly from the upper canopy and hitting +no understorey vegetation. + +.. math:: \it{abs}_{soil}= \it{abs}_{soil}+\it{solar}_{dir} dir_{tr,2,1}(1- \sum_{ft=1}^{npft}{\it{pft}_{wt,1,ft,1}}) (1 - salb_{dir}) + +These changes to the radiation code are designed to be structurally +flexible, and the scheme may be collapsed down to only include on canopy +layer, functional type and pft for testing if necessary. + +.. raw:: latex + + \captionof{table}{Parameters needed for radiation transfer model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`\chi` | Leaf angle | none | *ft* | +| | distribution | | | +| | parameter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\rho_l` | Fraction of | none | *ft* | +| | light reflected | | | +| | by leaf surface | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\tau_l` | Fraction of | none | *ft* | +| | light | | | +| | transmitted by | | | +| | leaf surface | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`alb_s` | Fraction of | none | direct vs | +| | light reflected | | diffuse | +| | by soil | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Photosynthesis +============== + +Fundamental photosynthetic physiology theory +-------------------------------------------- + + [11]_ + +In this section we describe the physiological basis of the +photosynthesis model before describing its application to the CLM(ED) +canopy structure. This description in this section is largely repeated +from the Oleson et al. CLM4.5 technical note but included here for +comparison with its implementation in CLM(ED). Photosynthesis in C3 +plants is based on the model of :raw-latex:`\cite{farquhar1980}` as +modified by :raw-latex:`\cite{collatz1991}`. Photosynthetic assimilation +in C4 plants is based on the model of :raw-latex:`\cite{collatz1992}`. +In both models, leaf photosynthesis, :math:`\textrm{gpp}` +(:math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`) is +calculated as the minimum of three potentially limiting fluxes, +described below: + +.. math:: \textrm{gpp} = \rm{min}(w_{j}, w_{c},w_{p}). + +The RuBP carboxylase (Rubisco) limited rate of carboxylation +:math:`w_{c}` (:math:`\mu`\ mol CO\ :math:`_{2}` m\ :math:`^{-2}` +s\ :math:`^{-1}`) is determined as + +.. math:: + + w_{c}= \left\{ \begin{array}{ll} + \frac{V_{c,max}(c_{i} - \Gamma_*)}{ci+K_{c}(1+o_{i}/K_{o})} & \textrm{for $C_{3}$ plants}\\ + &\\ + V_{c,max}& \textrm{for $C_{4}$ plants}\\ + \end{array} \right. + c_{i}-\Gamma_*\ge 0 + +where :math:`c_{i}` is the internal leaf CO\ :math:`_{2}` partial +pressure (Pa) and :math:`o_i (0.209P_{atm}`) is the O\ :math:`_{2}` +partial pressure (Pa). :math:`K_{c}` and :math:`K_{o}` are the +Michaelis-Menten constants (Pa) for CO\ :math:`_{2}` and +O\ :math:`_{2}`. These vary with vegetation temperature :math:`T_v` +(:math:`^{o}`\ C) according to an Arrhenious function described in +:raw-latex:`\cite{oleson2013}`. :math:`V_{c,max}` is the leaf layer +photosynthetic capacity (:math:`\mu` mol CO\ :math:`_2` m\ :math:`^{-2}` +s\ :math:`^{-1}`). + +The maximum rate of carboxylation allowed by the capacity to regenerate +RuBP (i.e., the light-limited rate) :math:`w_{j}` (:math:`\mu`\ mol +CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`) is + +.. math:: + + w_j= \left\{ \begin{array}{ll} + \frac{J(c_i - \Gamma_*)}{4ci+8\Gamma_*} & \textrm{for C$_3$ plants}\\ + &\\ + 4.6\phi\alpha & \textrm{for C$_4$ plants}\\ + \end{array} \right. + c_i-\Gamma_*\ge 0 + +To find :math:`J`, the electron transport rate (:math:`\mu` mol +CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`), we solve the +following quadratic term and take its smaller root, + +.. math:: \Theta_{psII}J^{2}-(I_{psII} +J_{max})J+I_{psII}J_{max} =0 + +where :math:`J_{max}` is the maximum potential rate of electron +transport (:math:`\mu`\ mol m\ :math:`_{-2}` s\ :math:`^{-1}`), +:math:`I_{PSII}` is the is the light utilized in electron transport by +photosystem II (:math:`\mu`\ mol m\ :math:`_{-2}` s\ :math:`^{-1}`) and +:math:`\Theta_{PSII}` is is curvature parameter. :math:`I_{PSII}` is +determined as + +.. math:: I_{PSII} =0.5 \Phi_{PSII}(4.6\phi) + +where :math:`\phi` is the absorbed photosynthetically active radiation +(Wm:math:`^{-2}`) for either sunlit or shaded leaves (:math:`abs_{sun}` +and :math:`abs_{sha}`). :math:`\phi` is converted to photosynthetic +photon flux assuming 4.6 :math:`\mu`\ mol photons per joule. Parameter +values are :math:`\Phi_{PSII}` = 0.7 for C3 and :math:`\Phi_{PSII}` = +0.85 for C4 plants. + +The export limited rate of carboxylation for C3 plants and the PEP +carboxylase limited rate of carboxylation for C4 plants :math:`w_e` +(also in :math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` +s\ :math:`^{-1}`) is + +.. math:: + + w_e= \left\{ \begin{array}{ll} + 3 T_{p,0} & \textrm{for $C_3$ plants}\\ + &\\ + k_{p} \frac{c_i}{P_{atm}}& \textrm{for $C_4$ plants}.\\ + \end{array} \right. + +:math:`T_{p}` is the triose-phosphate limited rate of photosynthesis, +which is equal to :math:`0.167 V_{c,max0}`. :math:`k_{p}` is the initial +slope of C4 CO\ :math:`_{2}` response curve. The Michaelis-Menten +constants :math:`K_{c}` and :math:`K_{o}` are modeled as follows, + +.. math:: K_{c} = K_{c,25}(a_{kc})^{\frac{T_v-25}{10}}, + +.. math:: K_{o} = K_{o,25}(a_{ko})^{\frac{T_v-25}{10}}, + +where :math:`K_{c,25}` = 30.0 and :math:`K_{o,25}` = 30000.0 are values +(Pa) at 25 :math:`^{o}`\ C, and :math:`a_{kc}` = 2.1 and :math:`a_{ko}` +=1.2 are the relative changes in :math:`K_{c,25}` and :math:`K_{o,25}` +respectively, for a 10\ :math:`^{o}`\ C change in temperature. The +CO\ :math:`_{2}` compensation point :math:`\Gamma_{*}` (Pa) is + +.. math:: \Gamma_* = \frac{1}{2} \frac{K_c}{K_o}0.21o_i + +where the term 0.21 represents the ratio of maximum rates of oxygenation +to carboxylation, which is virtually constant with temperature +:raw-latex:`\cite{farquhar1980}`. + +Resolution of the photosynthesis theory within the CLM(ED) canopy structure. +---------------------------------------------------------------------------- + +The photosynthesis scheme is modified from the CLM4.5 model to give +estimates of photosynthesis, respiration and stomatal conductance for a +three dimenstional matrix indexed by canopy level (:math:`C_l`), plant +functional type (:math:`ft`) and leaf layer (:math:`z`). We conduct the +photosynthesis calculations at each layer for both sunlit and shaded +leaves. Thus, the model also generates estimates of :math:`w_{c},w_{j}` +and :math:`w_{e}` indexed in the same three dimensional matrix. In this +implementation, some properties (stomatal conductance parameters, +top-of-canopy photosynthetic capacity) vary with plant functional type, +and some vary with both functional type and canopy depth (absorbed +photosynthetically active radiation, nitrogen-based variation in +photosynthetic properties). The remaining drivers of photosynthesis +(:math:`P_{atm}`, :math:`K_c`, :math:`o_i`, :math:`K_o`, temperature, +atmospheric CO\ :math:`_2`) remain the same throughout the canopy. The +rate of gross photosynthesis (:math:`gpp_{Cl,ft,z}`)is the smoothed +minimum of the three potentially limiting processes (carboxylation, +electron transport, export limitation), but calculated independently for +each leaf layer: + +.. math:: \textrm{gpp}_{Cl,ft,z} = \rm{min}(w_{c,Cl,ft,z},w_{j,Cl,ft,z},w_{e,Cl,ft,z}). + +For :math:`w_{c,Cl,ft,z},`, we use + +.. math:: + + w_{c,Cl,ft,z}= \left\{ \begin{array}{ll} + \frac{V_{c,max,Cl,ft,z}(c_{i,Cl,ft,z}- \Gamma_*)}{c_{i,Cl,ft,z}+K_c(1+o_i/K_o)} & \textrm{for $C_3$ plants}\\ + &\\ + V_{c,max,Cl,ft,z}& \textrm{for $C_4$ plants}\\ + \end{array} \right. + c_{i,Cl,ft,z}-\Gamma_*\ge 0 + +where :math:`V_{c,max}` now varies with PFT, canopy depth and layer +(see below). Internal leaf :math:`CO_{2}` (:math:`c_{i,Cl,ft,z})` is +tracked seperately for each leaf layer. For the light limited rate +:math:`w_j`, we use + +.. math:: + + w_j= \left\{ \begin{array}{ll} + \frac{J(c_i - \Gamma_*)4.6\phi\alpha}{4ci+8\Gamma_*} & \textrm{for C$_3$ plants}\\ + &\\ + 4.6\phi\alpha & \textrm{for C$_4$ plants}\\ + \end{array} \right. + +where :math:`J` is calculated as above but based on the absorbed +photosynthetically active radiation( :math:`\phi_{Cl,ft,z}`) for either +sunlit or shaded leaves in Wm\ :math:`^{-2}`. Specifically, + +.. math:: + + \phi_{Cl,ft,z}= \left\{ \begin{array}{ll} + abs_{sun,Cl,ft,z}& \textrm{for sunlit leaves}\\ + &\\ + abs_{sha,Cl,ft,z}& \textrm{for shaded leaves}\\ + \end{array} \right. + +The export limited rate of carboxylation for C3 plants and the PEP +carboxylase limited rate of carboxylation for C4 plants :math:`w_c` +(also in :math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` +s\ :math:`^{-1}`) is calculated in a similar fashion, + +.. math:: + + w_{e,Cl,ft,z}= \left\{ \begin{array}{ll} + 0.5V_{c,max,Cl,ft,z} & \textrm{for $C_3$ plants}\\ + &\\ + 4000 V_{c,max,Cl,ft,z} \frac{c_{i,Cl,ft,z}}{P_{atm}}& \textrm{for $C_4$ plants}.\\ + \end{array} \right. + +Variation in plant physiology with canopy depth +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Both :math:`V_{c,max}` and :math:`J_{max}` vary with vertical depth in +the canopy on account of the well-documented reduction in canopy +nitrogen through the leaf profile, see :raw-latex:`\cite{bonan2012}` for +details). Thus, both :math:`V_{c,max}` and :math:`J_{max}` are indexed +by by :math:`C_l`, :math:`ft` and :math:`z` according to the nitrogen +decay coefficient :math:`K_n` and the amount of vegetation area shading +each leaf layer :math:`V_{above}`, + +.. math:: + + \begin{array}{ll} + V_{c,max,Cl,ft,z} & = V_{c,max0,ft} e^{-K_{n,ft}V_{above,Cl,ft,z}},\\ + J_{max,Cl,ft,z} & = J_{max0,ft} e^{-K_{n,ft}V_{above,Cl,ft,z}},\\ + \end{array} + +where :math:`V_{c,max,0}` and :math:`J_{max,0}` are the top-of-canopy +photosynthetic rates. :math:`V_{above}` is the sum of exposed leaf area +index (:math:`\textrm{elai}_{Cl,ft,z}`) and the exposed stem area index +(:math:`\textrm{esai}_{Cl,ft,z}`)( m\ :math:`^{2}` m\ :math:`^{-2}` ). +Namely, + +.. math:: V_{Cl,ft,z} = \textrm{elai}_{Cl,ft,z} + \textrm{esai}_{Cl,ft,z}. + +The vegetation index shading a particular leaf layer in the top canopy +layer is equal to + +.. math:: + + \begin{array}{ll} + V_{above,Cl,ft,z}= \sum_{1}^{z} V_{Cl,ft,z} & \textrm{for $Cl= 1$. } + \end{array} + +For lower canopy layers, the weighted average vegetation index of the +canopy layer above (:math:`V_{canopy}`) is added to this within-canopy +shading. Thus, + +.. math:: + + \begin{array}{ll} + V_{above,Cl,ft,z}= \sum_{1}^{z} V_{Cl,ft,z} + V_{canopy,Cl-1} & \textrm{for $Cl >1$, }\\ + \end{array} + +where :math:`V_{canopy}` is calculated as + +.. math:: V_{canopy,Cl} = \sum_{ft=1}^{\emph{npft}} {\sum_{z=1}^{nz(ft)} (V_{Cl,ft,z} \cdot \it{pft}_{wt,Cl,ft,1}).} + +:math:`K_{n}` is the coefficient of nitrogen decay with canopy depth. +The value of this parameter is taken from the work of +:raw-latex:`\cite{lloyd2010}` who determined, from 204 vertical profiles +of leaf traits, that the decay rate of N through canopies of tropical +rainforests was a function of the :math:`V_{cmax}` at the top of the +canopy. They obtain the following term to predict :math:`K_{n}`, + +.. math:: K_{n,ft} = e^{0.00963 V_{c,max0,ft} - 2.43}, + +where :math:`V_{cmax}` is again in :math:`\mu`\ mol CO\ :math:`_2` +m\ :math:`^{-2}` s\ :math:`^{-1}`. + +Water Stress Function +~~~~~~~~~~~~~~~~~~~~~ + +[12]_ The top of canopy leaf photosynthetic capacity, :math:`V_{c,max0}`, is +also adjusted for the availability of water to plants as + +.. math:: V_{c,max0,25} = V_{c,max0,25} \beta_{sw}, + +where the adjusting factor :math:`\beta_{sw}` ranges from one when the +soil is wet to zero when the soil is dry. It depends on the soil water +potential of each soil layer, the root distribution of the plant +functional type, and a plant-dependent response to soil water stress, + +.. math:: \beta_{sw} = \sum_{j=1}^{nj}w_{j}r_{j}, + +where :math:`w_{j}` is a plant wilting factor for layer :math:`j` and +:math:`r_{j}` is the fraction of roots in layer :math:`j`.The plant +wilting factor :math:`w_{j}` is + +.. math:: + + w_{j}= \left\{ \begin{array}{ll} + \frac{\psi_c-\psi_{j}}{\psi_c - \psi_o} (\frac{\theta_{sat,j} - \theta_{ice,j}}{\theta_{sat,j}})& \textrm{for $T_i >$-2C}\\ + &\\ + 0 & \textrm{for $T_{j} \ge$-2C}\\ + \end{array} \right. + +where :math:`\psi_{i}` is the soil water matric potential (mm) and +:math:`\psi_{c}` and :math:`\psi_{o}` are the soil water potential (mm) +when stomata are fully closed or fully open, respectively. The term in +brackets scales :math:`w_{i}` the ratio of the effective porosity (after +accounting for the ice fraction) relative to the total porosity. +:math:`w_{i}` = 0 when the temperature of the soil layer (:math:`T_{i}` +) is below some threshold (-2:math:`^{o}`\ C) or when there is no liquid +water in the soil layer (:math:`\theta_{liq,i} \le 0`). For more details +on the calculation of soil matric potential, see the CLM4.5 technical +note. + +Variation of water stress and water uptake within tiles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The remaining drivers of the photosynthesis model remain constant +(atmospheric CO\ :math:`_2` and O\ :math:`^2` and canopy temperature) +throughout the canopy, except for the water stress index +:math:`\beta_{sw}`. :math:`\beta_{sw}` must be indexed by :math:`ft`, +because plants of differing functional types have the capacity to have +varying root depth, and thus access different soil moisture profile and +experience differing stress functions. Thus, the water stress function +applied to gas exchange calculation is now calculated as + +.. math:: \beta_{sw,ft} = \sum_{j=1}^{nj}w_{j,ft} r_{j,ft}, + +where :math:`w_{j}` is the water stress at each soil layer :math:`j` +and :math:`r_{j,ft}` is the root fraction of each PFT’s root mass in +layer :math:`j`. Note that this alteration of the :math:`\beta_{sw}` +parameter also necessitates recalculation of the vertical water +extraction profiles. In the original model, the fraction of extraction +from each layer (:math:`r_{e,j,patch}`) is the product of a single root +distribution, because each patch only has one plant functional type. In +the CLM(ED), we need to calculate a new weighted patch effective rooting +depth profile :math:`r_{e,j,patch}` as the weighted average of the +functional-type level stress functions and their relative contributions +to canopy conductance. Thus for each layer :math:`j`, the extraction +fraction is summed over all PFTs as + +.. math:: r_{e,j,patch} = \sum_{ft=1}^{ft=npft} \frac{w_{j,ft}}{\sum_{j=1}^{=nj} w_{j,ft} }\frac{G_{s,ft}}{G_{s,canopy}}, + +where :math:`nj` is the number of soil layers, :math:`G_{s,canopy}`\ is +the total canopy (see section 9 for details) and :math:`G_{s,ft}` is the +canopy conductance for plant functional type :math:`ft`, + +.. math:: G_{s,ft}= \sum_{1}w_{ncoh,ft} {gs_{can,coh} n_{coh} }. + +Aggregation of assimilated carbon into cohorts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The derivation of photosynthetic rates per leaf layer, as above, give us +the estimated rate of assimilation for a unit area of leaf at a given +point in the canopy in :math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` +s\ :math:`_{-1}`. To allow the integration of these rates into fluxes +per individual tree, or cohort of trees (gCO:math:`_2` +tree\ :math:`^{-1}` s\ :math:`^{-1}`), they must be multiplied by the +amount of leaf area placed in each layer by each cohort. Each cohort is +described by a single functional type, :math:`ft` and canopy layer +:math:`C_l` flag, so the problem is constrained to integrating these +fluxes through the vertical profile (:math:`z`). + +We fist make a weighted average of photosynthesis rates from sun +(:math:`\textrm{gpp}_{sun}`, :math:`\mu`\ mol CO\ :math:`_2` +m\ :math:`^{-2}` s\ :math:`^{-1}`) and shade leaves ( +:math:`\textrm{gpp}_{shade}`, :math:`\mu`\ mol CO\ :math:`_2` +m\ :math:`^{-2}` s\ :math:`^{-1}`) as + +.. math:: \textrm{gpp}_{Cl,ft,z} =\textrm{gpp}_{sun,Cl,ft,z} f_{sun,Cl,ft,z}+ \textrm{gpp}_{sha,Cl,ft,z}(1-f_{sun,Cl,ft,z}). + +The assimilation per leaf layer is then accumulated across all the leaf +layers in a given cohort (*coh*) to give the cohort-specific gross +primary productivity (:math:`\mathit{GPP}_{coh}`), + +.. math:: \textit{GPP}_{coh} = 12\times 10^{-9}\sum_{z=1}^{nz(coh)}gpp_{Cl,ft,z} A_{crown,coh} \textrm{elai}_{Cl,ft,z} + +The :math:`\textrm{elai}_{l,Cl,ft,z}` is the exposed leaf area which is +present in each leaf layer in m\ :math:`^{2}` m\ :math:`^{-2}`. (For all +the leaf layers that are completely occupied by a cohort, this is the +same as the leaf fraction of :math:`\delta_{vai}`). The fluxes are +converted from :math:`\mu`\ mol into mol and then multiplied by 12 (the +molecular weight of carbon) to give units for GPP\ :math:`_{coh}` of KgC +cohort\ :math:`^{-1}` s\ :math:`^{-1}`. These are integrated for each +timestep to give KgC cohort\ :math:`^{-1}` day\ :math:`^{-1}` + +.. raw:: latex + + \captionof{table}{Parameters needed for photosynthesis model.} + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`V_{c,max | Maximum | :math:`\mu` mol | *ft* | +| 0}` | carboxylation | CO :math:`_2` | | +| | capacity | m :math:`^{-2}` | | +| | | s :math:`^{-1}` | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`r_b` | Base Rate of | gC | | +| | Respiration | gN\ :math:`^{-1 | | +| | | } s^{-1}`) | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`q_{10}` | Temp. Response | | | +| | of stem and | | | +| | root | | | +| | respiration | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`R_{cn,le | CN ratio of | gC/gN | *ft* | +| af,ft}` | leaf matter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`R_{cn,ro | CN ratio of | gC/gN | *ft* | +| ot,ft}` | root matter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{gr}` | Growth | none | | +| | Respiration | | | +| | Fraction | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\psi_c` | Water content | Pa | *ft* | +| | when stomata | | | +| | close | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\psi_o` | Water content | Pa | *ft* | +| | above which | | | +| | stomata are | | | +| | open | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Plant respiration +================= + + [13]_ + +Plant respiration per individual :math:`R_{plant,coh}` (KgC individual +:math:`^{-1}` s\ :math:`^{-1}`) is the sum of two terms, growth and +maintenance respiration :math:`R_{g,coh}` and :math:`R_{m,coh}` + +.. math:: R_{plant} = R_{g,coh}+ R_{m,coh} + +Maintenance respiration is the sum of the respiration terms from four +different plant tissues, leaf, :math:`R_{m,leaf,coh}`, fine root +:math:`R_{m,froot,coh}`, coarse root :math:`R_{m,croot,coh}`\ and stem +:math:`R_{m,stem,coh}`, all also in (KgC individual :math:`^{-1}` +s\ :math:`^{-1}`) . + +.. math:: R_{m,coh} = R_{m,leaf,coh}+ R_{m,froot,coh}+R_{m,croot,coh}+R_{m,stem,coh} + +To calculate canopy leaf respiration, which varies through we canopy, we +first determine the top-of-canopy leaf respiration rate +(:math:`r_{m,leaf,ft,0}`, gC s\ :math:`^{-1}` m\ :math:`^{-2}`) is +calculated from a base rate of respiration per unit leaf nitrogen +derived from :raw-latex:`\cite{ryan1991}`. The base rate for leaf +respiration (:math:`r_{b}`) is 2.525 gC/gN s\ :math:`^{-1}`, + +.. math:: r_{m,leaf,ft,0} = r_{b} N_{a,ft}(1.5^{(25-20)/10}) + +where :math:`r_b` is the base rate of metabolism (2.525 x +10\ :math:`^6` gC/gN s\ :math:`^{-1}`. This base rate is adjusted +assuming a Q\ :math:`_{10}` of 1.5 to scale from the baseline of 20C to +the CLM default base rate temperature of 25C. For use in the +calculations of net photosynthesis and stomatal conductance, leaf +respiration is converted from gC s\ :math:`^{-1}` m\ :math:`^{-2}`, into +:math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}` +(:math:`/12\cdot 10^{-6}`). + +This top-of-canopy flux is scaled to account for variation in +:math:`N_a` through the vertical canopy, in the same manner as the +:math:`V_{c,max}` values are scaled using :math:`V_{above}`. + +.. math:: r_{leaf,Cl,ft,z} = r_{m,leaf,ft,0} e^{-K_{n,ft}V_{above,Cl,ft,z}}\beta_{ft}f(t) + +Leaf respiration is also adjusted such that it is reduced by drought +stress, :math:`\beta_{ft}`, and canopy temperature, :math:`f(t_{veg})`. +For details of the temperature functions affecting leaf respiration see +the CLM4 technical note, Section 8, Equations 8.13 and 8.14. The +adjusted leaf level fluxes are scaled to individual-level (gC individual +:math:`^{-1}` s\ :math:`^{-1}`) in the same fashion as the +:math:`\rm{GPP}_{coh}` calculations + +.. math:: \rm{R}_{m,leaf,coh} = 12\times 10^{-9}\sum_{z=1}^{nz(coh)}r_{leaf,Cl,ft,z} A_{crown} \textrm{elai}_{Cl,ft,z} + +The stem and the coarse-root respiration terms are derived using the +same base rate of respiration per unit of tissue Nitrogen. + +.. math:: R_{m,croot,coh} = 10^{-3}r_b t_c \beta_{ft} N_{\rm{livecroot,coh}} + +.. math:: R_{m,stem,coh} = 10^{-3}r_b t_c \beta_{ft} N_{\rm{stem,coh}} + +Here, :math:`t_c` is a temperature relationship based on a +:math:`q_{10}` value of 1.5, where :math:`t_v` is the vegetation +temperature. We use a base rate of 20 here as, again, this is the +baseline temperature used by :raw-latex:`\cite{ryan1991}`. The +10\ :math:`^{-3}` converts from gC invididual\ :math:`^{-1}` +s\ :math:`^{-1}` to KgC invididual\ :math:`^{-1}` s\ :math:`^{-1}` + +.. math:: t_c=q_{10}^{(t_{v} - 20)/10} + +The tissue N contents for live sapwood are derived from the leaf CN +ratios, and for fine roots from the root CN ratio as: + +.. math:: N_{\rm{stem,coh}} = \frac{B_{\rm{sapwood,coh}}}{ R_{cn,leaf,ft}} + +and + +.. math:: N_{\rm{livecroot,coh}} = \frac{ B_{\rm{root,coh}}w_{frac,ft}}{R_{cn,root,ft}} + +where :math:`B_{\rm{sapwood,coh}}` and :math:`B_{\rm{root,coh}}` are +the biomass pools of sapwood and live root biomass respectively (KgC +individual) and :math:`w_{frac,ft}` is the fraction of coarse root +tissue in the root pool (0.5 for woody plants, 0.0 for grasses and +crops). We assume here that stem CN ratio is the same as the leaf C:N +ratio, for simplicity. The final maintenance respiration term is derived +from the fine root respiration, which accounts for gradients of +temperature in the soil profile and thus calculated for each soil layer +:math:`j` as follows: + +.. math:: R_{m,froot,j } = \frac{(1 - w_{frac,ft})B_{\rm{root,coh}}b_r\beta_{ft}}{10^3R_{cn,leaf,ft}} \sum_{j=1}^{nj}t_{c,soi,j} r_{i,ft,j} + +:math:`t_{c,soi}` is a function of soil temperature in layer :math:`j` +that has the same form as that for stem respiration, but uses vertically +resolved soil temperature instead of canopy temperature. In the CLM4.5, +only coarse and not fine root respriation varies as a function of soil +depth, and we maintain this assumption here, although it may be altered +in later versions. The growth respiration, :math:`R_{g,coh}` is a fixed +fraction :math:`f_{gr}` of the carbon remaining after maintenance +respiration has occurred. + +.. math:: R_{g,coh}=\textrm{max}(0,GPP_{g,coh} - \it R\rm_{m,coh})f_{gr} + +.. raw:: latex + + \captionof{table}{Parameters needed for plant respiration model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`-K_{n,ft | Rate of | none | - | +| }` | reduction of N | | | +| | through the | | | +| | canopy | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`r_b` | Base Rate of | gC | | +| | Respiration | gN\ :math:`^{-1 | | +| | | } s^{-1}`) | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`q_{10}` | Temp. Response | | | +| | of stem and | | | +| | root | | | +| | respiration | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`R_{cn,le | CN ratio of | gC/gN | *ft* | +| af,ft}` | leaf matter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`R_{cn,ro | CN ratio of | gC/gN | *ft* | +| ot,ft}` | root matter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{gr}` | Growth | none | | +| | Respiration | | | +| | Fraction | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Stomatal Conductance +==================== + +Fundamental stomatal conductance theory +--------------------------------------- + + [14]_ + +Stomatal conductance is unchanged in concept from the CLM4.5 approach. +Leaf stomatal resistance is calculated from the Ball-Berry conductance +model as described by :raw-latex:`\cite{collatz1991}` and implemented in +a global climate model by :raw-latex:`\cite{sellers1996}`. The model +relates stomatal conductance (i.e., the inverse of resistance) to net +leaf photosynthesis, scaled by the relative humidity at the leaf surface +and the CO\ :math:`_2` concentration at the leaf surface. The primary +difference between the CLM implementation and that used by +:raw-latex:`\cite{collatz1991}` and :raw-latex:`\cite{sellers1996}` is +that they used net photosynthesis (i.e., leaf photosynthesis minus leaf +respiration) instead of gross photosynthesis. As implemented here, +stomatal conductance equals the minimum conductance (:math:`b`) when +gross photosynthesis (:math:`A`) is zero. Leaf stomatal resistance is + +.. math:: \frac{1}{r_{s}} = m_{ft} \frac{A}{c_s}\frac{e_s}{e_i}P_{atm}+b_{ft} \beta_{sw} + +where :math:`r_{s}` is leaf stomatal resistance (s m\ :math:`^2` +:math:`\mu`\ mol\ :math:`^{-1}`), :math:`b_{ft}` is a plant functional +type dependent parameter equivalent to :math:`g_{0}` in the Ball-Berry +model literature. This parameter is also scaled by the water stress +index :math:`\beta_{sw}`. Similarly, :math:`m_{ft}` is the slope of the +relationship between the assimilation, :math:`c_s` and humidty dependant +term and the stomatal conductance, and so is equivalent to the +:math:`g_{1}` term in the stomatal literature. :math:`A` is leaf +photosynthesis (:math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` +s\ :math:`^{-1}`), :math:`c_s` is the CO\ :math:`_2` partial pressure at +the leaf surface (Pa), :math:`e_s` is the vapor pressure at the leaf +surface (Pa), :math:`e_i` is the saturation vapor pressure (Pa) inside +the leaf at the vegetation temperature conductance (:math:`\mu`\ mol +m\ :math:`^{-2}` s\ :math:`^{-1}`) when :math:`A` = 0 . Typical values +are :math:`m_{ft}` = 9 for C\ :math:`_3` plants and :math:`m_{ft}` = 4 +for C\ :math:`_4` plants +:raw-latex:`\parencite{collatz1991,collatz1992,sellers1996}`. +:raw-latex:`\cite{sellers1996}` used :math:`b` = 10000 for C\ :math:`_3` +plants and :math:`b` = 40000 for C\ :math:`_4` plants. Here, :math:`b` +was chosen to give a maximum stomatal resistance of 20000 s +m\ :math:`^{-1}`. These terms are nevertheless plant strategy dependent, +and have been found to vary widely with plant type +:raw-latex:`\parencite{medlyn2011}`. + +Resistance is converted from units of s m\ :math:`^2 \mu` +mol\ :math:`^{-1}` to s m\ :math:`^{-1}` as: 1 s m\ :math:`^{-1}` = +:math:`1\times 10^{-9}`\ R\ :math:`_{\rm{gas}} \theta_{\rm{atm}}P_{\rm{atm}}` +(:math:`\mu`\ mol\ :math:`^{-1}` m\ :math:`^{2}` s), where +R\ :math:`_{gas}` is the universal gas constant (J K\ :math:`^{-1}` +kmol\ :math:`^{-1}`) and :math:`\theta_{atm}` is the atmospheric +potential temperature (K). + +Resolution of the stomatal conductance theory in the CLM(ED) canopy structure +----------------------------------------------------------------------------- + +The stomatal conductance is calculated, as with photosynthesis, for each +canopy, PFT and leaf layer. The CLM code requires a single canopy +conductance estimate to be generated from the multi-layer multi-PFT +array. In previous iterations of the CLM, sun and shade-leaf specific +values have been reported and then averaged by their respective leaf +areas. In this version, the total canopy condutance +:math:`G_{s,canopy}`, is calculated as the sum of the cohort-level +conductance values. + +.. math:: G_{s,canopy} = \sum{ \frac{gs_{can,coh} n_{coh} }{A_{patch}}} + +Cohort conductance is the sum of the inverse of the leaf resistances at +each canopy layer (:math:`r_{s,z}` ) multipled by the area of each +cohort. + +.. math:: gs_{can,coh} =\sum_{z=1}^{z=nv,coh}{\frac{ A_{crown,coh}}{r_{s,cl,ft,z}+r_{b}}} + + +.. raw:: latex + + \captionof{table}{Parameters needed for stomatal conductance model. } + ++------------------+--------------------------+-------+------------+ +| Parameter Symbol | Parameter Name | Units | indexed by | ++==================+==========================+=======+============+ +| :math:`b_{ft}` | Slope of Ball-Berry term | none | *ft* | ++------------------+--------------------------+-------+------------+ +| :math:`m_{ft}` | Slope of Ball-Berry term | none | *ft* | ++------------------+--------------------------+-------+------------+ + + +Allocation +========== + + [15]_ + +Total assimilation carbon enters the ED model each day as a +cohort-specific Net Primary Productivity :math:`\mathit{NPP}_{coh}`, +which is calculated as + +.. math:: \mathit{NPP}_{coh} = \mathit{GPP}_{coh} - R_{plant,coh} + +This flux of carbon is allocated between the demands of tissue turnover, +of carbohydrate storage and of growth (increase in size of one or many +plant organs). Priority is explicitly given to maintenance respiration, +followed by tissue maintenance and storage, then allocation to live +biomass and then to the expansion of structural and live biomass pools. +All fluxes here are first converted into in KgC +individual\ :math:`^{-1}` year\ :math:`^{-1}` and ultimately integrated +using a timesteps of 1/365 years for each day. + +Tissue maintenance demand +------------------------- + +We calculate a ‘tissue maintenance’ flux. The magnitude of this flux is +such that the quantity of biomass in each pool will remain constant, +given background turnover rates. For roots, this maintenenace demand is +simply + +.. math:: r_{md,coh} = b_{root}\cdot\alpha_{root,ft} + +Where :math:`\alpha_{root,ft}` is the root turnover rate in y^-1. Given +that, for deciduous trees, loss of leaves is assumed to happen only one +per growing season, the algorithm is dependent on phenological habit +(whether or not this PFT is evergreen), thus + +.. math:: + + l_{md,coh} = \left\{ \begin{array}{ll} + b_{leaf}\cdot\alpha_{leaf,ft}&\textrm{for } P_{evergreen}= 1\\ + &\\ + 0&\textrm{for } P_{evergreen}= 0\\ + \end{array} \right. + +Leaf litter resulting from deciduous senescence is handled in the +phenology section. The total quantity of maintenance demand +(:math:`t_{md,coh}`. KgC individual y\ :math:`^{-1}`) is therefore + +.. math:: t_{md,coh} = l_{md,coh} + r_{md,coh} + +Allocation to storage and turnover +---------------------------------- + +The model must now determine whether the NPP input is sufficient to meet +the maintenance demand and keep tissue levels constant. To determine +this, we introduce the idea of ‘carbon balance’ :math:`C_{bal,coh}` (KgC +individual\ :math:`^{-1}`) where + +.. math:: C_{bal,coh}= \mathit{NPP}_{coh} - t_{md,coh}\cdot f_{md,min,ft} + +where :math:`f_{md,min,ft}` is the minimum fraction of the maintenance +demand that the plant must meet each timestep, which is indexed by *ft* +and represents a life-history-strategy decision concerning whether +leaves should remain on in the case of low carbon uptake (a risky +strategy) or not be replaced (a conservative strategy). Subsequently, we +determine a flux to the storage pool, where the flux into the pool, as a +fraction of :math:`C_{bal,coh}`, is proportional to the discrepancy +between the target pool size and the actual pool size :math:`f_{tstore}` +where + +.. math:: f_{tstore} = \mathrm{max}\left(0,\frac{b_{store}}{b_{leaf}\cdot S_{cushion}}\right) + +The allocation to storage is a fourth power function of +:math:`f_{tstore}` to mimic the qualitative behaviour found for carbon +allocation in arabidopsis by :raw-latex:`\cite{smith2007}`. + +.. math:: + + \frac{\delta b_{store}}{\delta t} = \left\{ \begin{array}{ll} + C_{bal,coh} \cdot e^{-f_{tstore}^{4}} &\textrm{for }C_{bal,coh}>0\\ + &\\ + C_{bal,coh} &\textrm{for }C_{bal,coh}\leq0\\ + \end{array} \right. + +If the carbon remaining after the storage and minimum turnover fluxes +have been met, the next priority is the remaining flux to leaves +:math:`t_{md}\cdot(1-f_{md,min})`. If the quantity of carbon left +:math:`(C_{bal,coh}-\frac{\delta b_{store}}{\delta t})` is insufficient +to supply this amount of carbon, then the store of alive carbon is +depleted (to represent those leaves that have fallen off and not been +replaced) + +.. math:: + + \frac{\delta b_{alive}}{\delta t} = \left\{ \begin{array}{ll} + 0 &\textrm{ for } (C_{bal,coh}-\frac{\delta b_{store}}{\delta t}) > t_{md}\cdot(1-f_{md,min})\\ + &\\ + t_{md}\cdot(1-f_{md,min}) - \left(C_{bal,coh}-\frac{\delta b_{store}}{\delta t}\right)&\textrm{ for } (C_{bal,coh}-\frac{\delta b_{store}}{\delta t}) \leq t_{md}\cdot(1-f_{md,min})\\ + \end{array} \right. + +correspondingly, the carbon left over for growth (:math:`C_{growth}`: +(KgC individual\ :math:`^{-1}` year\ :math:`^{-1}`) is therefore + +.. math:: + + C_{growth} = \left\{ \begin{array}{ll} + C_{bal,coh}-\frac{\delta b_{store}}{\delta t} &\textrm{ for } (C_{bal,coh}-\frac{\delta b_{store}}{\delta t}) > 0\\ + &\\ + 0&\textrm{ for } (C_{bal,coh}-\frac{\delta b_{store}}{\delta t}) \leq 0\\ + \end{array} \right. + +to allocate the remaining carbon (if there is any), we first ascertain +whether the live biomass pool is at its target, or whether is has been +depleted by previous low carbon timesteps. Thus + +.. math:: + + \begin{array}{lll} + b_{alive,target}&= b_{leaf,target} (1+ f_{frla}+f_{swh}h_{coh}) &\textrm{for } S_{phen,coh} = 2\\ + b_{alive,target}&= b_{leaf,target} ( f_{frla}+f_{swh}h_{coh})&\textrm{for } S_{phen,coh} = 1\\ + \end{array} + +where the target leaf biomass :math:`b_{leaf.target}` ((Kg C +individual\ :math:`^{-1}`)) is the allometric relationship between dbh +and leaf biomass, ameliorated by the leaf trimming fraction (see +‘control of leaf area’ below) + +.. math:: b_{leaf.target} = c_{leaf}\cdot dbh_{coh}^{e_{leaf,dbh}} \rho_{ft} ^{e_{leaf,dens}}\cdot C_{trim,coh} + +:math:`\rho_{ft}` is the wood density, in g cm\ :math:`^{3}`. + +Allocation to Seeds +~~~~~~~~~~~~~~~~~~~ + +The fraction remaining for growth (expansion of live and structural +tissues) :math:`f_{growth}` is 1 minus that allocated to seeds. + +.. math:: f_{growth,coh} = 1 - f_{seed,coh} + +Allocation to seeds only occurs if the alive biomass is not below its +target, and then is a predefined fixed fraction of the carbon remaining +for growth. Allocation to clonal reproduction (primarily for grasses) +occurs when :math:`\textrm{max}_{dbh}` is achieved. + +.. math:: + + f_{seed,coh} = \left\{ \begin{array}{ll} + R_{frac,ft}&\textrm{ for } \textrm{max}_{dbh} < dbh_{coh} \\ + &\\ + \left( R_{frac,ft}+C_{frac,ft} \right) &\textrm{ for } \textrm{max}_{dbh} \geq dbh_{coh} \\ + \end{array} \right. + +the total amount allocated to seed production (:math:`p_{seed,coh}` in +KgC individual :math:`^{-1}` y\ :math:`^{-1}`) is thus + +.. math:: p_{seed,coh} = C_{growth}\cdot f_{seed,coh} + +Allocation to growing pools +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[16]_ The carbon is then partitioned into carbon available to grow the +:math:`b_{alive}` and :math:`b_{struc}` pools. A fraction :math:`v_{a}` +is available to live biomass pools, and a fraction :math:`v_{s}` is +available to structural pools. + +.. math:: \frac{\delta b_{alive}}{\delta t} = C_{growth}\cdot f_{growth} v_{a} + +.. math:: \frac{\delta b_{struc}}{\delta t} = C_{growth}\cdot f_{growth} v_{s} + +If the alive biomass is lower than its ideal target, all of the +available carbon is directed into that pool. Thus: + +.. math:: + + v_{a}= \left\{ \begin{array}{ll} + \frac{1}{1+u}&\textrm{ for } b_{alive} \geq b_{alive,target} \\ + &\\ + 1.0&\textrm{ for } b_{alive} < b_{alive,target} \\ + \end{array} \right. + +.. math:: + + v_{s}= \left\{ \begin{array}{ll} + \frac{u}{1+u}&\textrm{ for } b_{alive} \geq b_{alive,target} \\ + &\\ + 0.0&\textrm{ for } b_{alive} < b_{alive,target} \\ + \end{array} \right. + +In this case, the division of carbon between the live and structural +pools :math:`u` is derived as the inverse of the sum of the rates of +change in live biomass with respect to structural: + +.. math:: u = \frac{1}{\frac{\delta b_{leaf}}{ \delta b_{struc} } + \frac{\delta b_{root}}{ \delta b_{struc} } +\frac{\delta b_{sw}}{ \delta b_{struc} } } + +To calculate all these differentials, we first start with +:math:`\delta b_{leaf}/\delta b_{struc}`, where + +.. math:: \frac{\delta b_{leaf}}{ \delta b_{struc}}= \frac{\frac{\delta \mathrm{dbh}}{\delta b_{struc}}} {\frac{\delta \mathrm{dbh} }{\delta b_{leaf}} } + +The rates of change of dbh with respect to leaf and structural biomass +are the differentials of the allometric equations linking these terms to +each other. Hence, + +.. math:: \frac{\delta \mathrm{dbh} }{\delta b_{leaf}}=\frac{1}{b_{trim,coh}}\cdot (e_{leaf,dbh}-1)\exp {\big(c_{leaf} \mathrm{dbh}^{(e_{leaf,dbh})-1} \rho_{ft}^{e_{leaf,dens}} \big)} + +and where :math:`\mathrm{dbh}_{coh} > \mathrm{dbh}_{max}` + +.. math:: \frac{\delta b_{struc}}{\delta \mathrm{dbh}} = e_{str,dbh} \cdot c_{str}\cdot e_{str,hite} h_{coh}^{e_{str,dbh}-1} \mathrm{dbh}_{coh}^{e_{str,dbh}} \rho_{ft}^{e_{str,dens}} + +If :math:`\mathrm{dbh}_{coh} \leq \mathrm{dbh}_{max}` then we must +also account for allocation for growing taller as: + +.. math:: \frac{\delta b_{struc}}{\delta \mathrm{dbh}} = \frac{\delta b_{struc}}{\delta \mathrm{dbh}} + \frac{\delta h}{\delta \mathrm{dbh}} \cdot \frac{\delta b_{struc}}{\delta \mathrm{dbh} } + +where + +.. math:: \frac{\delta h}{\delta \mathrm{dbh}}= 1.4976 \mathrm{dbh}_{coh}^{m_{allom}-1} + +.. math:: \frac{\delta \mathrm{dbh} }{\delta b_{struc}} =\frac{1}{ \frac{\delta b_{struc}}{\delta \mathrm{dbh}} } + +Once we have the :math:`\delta b_{leaf}/\delta b_{struc}`, we calculate +:math:`\delta b_{root}/\delta b_{struc}` as + +.. math:: \frac{\delta b_{root}}{\delta b_{struc}} =\frac{\delta b_{leaf}}{\delta b_{struc}}\cdot f_{frla} + +and the sapwood differential as + +.. math:: \frac{\delta b_{sw}}{\delta b_{struc}} = f_{swh}\left( h_{coh} \frac{\delta b_{leaf}}{ \delta b_{struc}} + b_{leaf,coh}\frac{\delta h}{\delta b_{struc}} \right) + +where + +.. math:: \frac{\delta h}{\delta b_{struc}} = \frac{1}{c_{str}\times e_{str,hite} h_{coh}^{e_{str,dbh}-1} \mathrm{dbh}_{coh}^{e_{str,dbh}} \rho_{ft}^{e_{str,dens}}} + +In all of the above terms, height in in m, :math:`\mathrm{dbh}` is in +cm, and all biomass pools are in KgCm\ :math:`^{-2}`. The allometric +terms for the growth trajectory are all taken from the ED1.0 model, but +could in theory be altered to accomodate alternative allometric +relationships. Critically, the non-linear relationships between live and +structural biomass pools are maintained in this algorithm, which +diverges from the methodology currently deployed in the CLM4.5. + +Integration of allocated fluxes +------------------------------- + +All of the flux calculations generate differential of the biomass state +variables against time (in years). To integrate these differential rates +into changes in the state variables, we use a simple simple forward +Euler integration. Other methods exist (e.g. ODEINT solvers, Runge Kutta +methods etc.), but they are more prone to errors that become difficult +to diagnose, and the typically slow rates of change of carbon pools mean +that these are less important than they might be in strongly non-linear +systems (soil drainage, energy balance, etc.) + +.. math:: b_{alive,t+1} = \textrm{min}\left( 0,b_{alive,t} + \frac{\delta b_{alive}}{\delta t} \delta t \right) + +.. math:: b_{struc,t+1} = \textrm{min}\left(0, b_{struc,t} + \frac{\delta b_{struc}}{\delta t} \delta t \right) + +.. math:: b_{store,t+1} = \textrm{min}\left(0, b_{store,t} + \frac{\delta b_{store}}{\delta t} \delta t \right) + +In this case, :math:`\delta t` is set to be one day +(:math:`\frac{1}{365}` years). + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for allocation model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| S | Target stored | none | *ft* | +| | biomass as | | | +| | fraction of | | | +| | :math:`b_{leaf}`| | | +| | | | | ++-----------------+-----------------+-----------------+-----------------+ +| f | Minimum | none | *ft* | +| | fraction of | | | +| | turnover that | | | +| | must be met | | | ++-----------------+-----------------+-----------------+-----------------+ +| R | Fraction | none | *ft* | +| | allocated to | | | +| | seeds | | | ++-----------------+-----------------+-----------------+-----------------+ +| C | Fraction | none | *ft* | +| | allocated to | | | +| | clonal | | | +| | reproduction | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\textrm{ | Diameter at | m | *ft* | +| max}_{dbh}` | which maximum | | | +| | height is | | | +| | achieved | | | ++-----------------+-----------------+-----------------+-----------------+ +| P | Does this | 1=yes, 0=no | *ft* | +| | cohort have an | | | +| | evergreen | | | +| | phenological | | | +| | habit? | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Control of Leaf Area Index +========================== + + [17]_ + +The leaf area :math:`A_{leaf}` (m:math:`^{-2}`) of each cohort is +calculated from leaf biomass :math:`b_{leaf,coh}` (kgC +individual\ :math:`^{-1}`) and specific leaf area (SLA, m\ :math:`^2` kg +C\ :math:`^{-1}`) + +.. math:: A_{leaf,coh} = b_{leaf,coh} \cdot SLA_{ft} + +For a given tree allometry, leaf biomass is determined from basal area +using the function used by :raw-latex:`\cite{mc_2001}` where :math:`d_w` +is wood density in g cm\ :math:`^{-3}`. + +.. math:: b_{leaf,coh} = c_{leaf} \cdot dbh_{coh}^{e_{leaf,dbh}} \rho_{ft}^{e_{leaf,dens}} + +However, using this model, where leaf area and crown area are both +functions of diameter, the leaf area index of each tree in a closed +canopy forest is always the same (where :math:`S_{c,patch}` = +:math:`S_{c,min}` , irrespective of the growth conditions. To allow +greater plasticity in tree canopy structure, and for tree leaf area +index to adapt to prevailing conditions, we implemented a methodology +for removing those leaves in the canopy that exist in negative carbon +balance. That is, their total annual assimilation rate is insufficient +to pay for the turnover and maintenance costs associated with their +supportive root and stem tissue, plus the costs of growing the leaf. The +tissue turnover maintenance cost (KgC m\ :math:`^{-2} y^{-1}` of leaf is +the total maintenance demand divided by the leaf area: + +.. math:: L_{cost,coh} = \frac{t_{md,coh}} {b_{leaf,coh} \cdot \textrm{SLA}} + +The net uptake for each leaf layer :math:`U_{net,z}` in (KgC +m\ :math:`^{-2}` year\ :math:`^{-1}`) is + +.. math:: U_{net,coh,z} = g_{coh,z}-r_{m,leaf,coh,z} + +where :math:`g_{z}` is the GPP of each layer of leaves in each tree (KgC +m\ :math:`^{-2}` year\ :math:`^{-1}`), :math:`r_{m,leaf,z}` is the rate +of leaf dark respiration (also KgC m\ :math:`^{-2}` +year\ :math:`^{-1}`). We use an iterative scheme to define the cohort +specific canopy trimming fraction :math:`C_{trim,coh}`, on an annual +time-step, where + +.. math:: b_{leaf,coh} = C_{trim} \times 0.0419 dbh_{coh}^{1.56} d_w^{0.55} + +If the annual maintenance cost of the bottom layer of leaves (KgC m-2 +year-1) is less than then the canopy is trimmed by an increment :math:`\iota_l`\ (0.01), which is applied until the end of next calander year. Because this is an optimality model, there is an +issue of the timescale over which net assimilation is evaluated, the +timescale of response, and the plasticity of plants to respond to these +pressures. These properties should be investigated further in future +efforts. + +.. math:: + + C_{trim,y+1} = \left\{ \begin{array}{ll} + \rm{max}(C_{trim,y}-\iota_l,1.0)&\rm{for} (L_{cost,coh} > U_{net,coh,nz})\\ + &\\ + \rm{min}(C_{trim,y}+\iota_l,L_{trim,min})&\rm{for} (L_{cost,coh} < U_{net,coh,nz})\\ + \end{array} \right. + +We impose an arbitrary minimum value on the scope of canopy trimming of +:math:`L_{trim,min}` (0.5). If plants are able simply to drop all of +their canopy in times of stress, with no consequences, then tree +mortality from carbon starvation is much less likely to occur because of +the greatly reduced maintenance and turnover requirements. + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for leaf area control model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`\iota_l` | Fraction by | none | - | +| | which leaf mass | | | +| | is reduced next | | | +| | year | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`L_{trim, | Minimum | - | | +| min}` | fraction to | | | +| | which leaf mass | | | +| | can be reduced | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Phenology +========= + +Cold Deciduous Phenology +------------------------ + +Cold Leaf-out timing +~~~~~~~~~~~~~~~~~~~~ + +[18]_. The phenology model of :raw-latex:`\cite{botta2000}` is used in +CLM(ED) to determine the leaf-on timing. The Botta et al. model was +verified against satellite data and is one of the only globally verified +and published models of leaf-out phenology. This model differs from the +phenology model in the CLM4.5. The model simulates leaf-on date as a +function of the number of growing degree days (GDD), defined by the sum +of mean daily temperatures (:math:`T_{day}` :math:`^{o}`\ C) above a +given threshold :math:`T_{g}` (0 :math:`^{o}`\ C). + +.. math:: GDD=\sum \textrm{max}(T_{day}-T_{g},0) + +Budburst occurs when :math:`GDD` exceeds a threshold +(:math:`GDD_{crit}`). The threshold is modulated by the number of +chilling days experienced (NCD) where the mean daily temperature falls +below a threshold determined by :raw-latex:`\cite{botta2000}` as +5\ :math:`^{o}`\ C. A greater number of chilling days means that fewer +growing degree days are required before budburst: + +.. math:: GDD_{crit}=a+be^{c.NCD} + +where a = -68, b= 638 and c=-0.01 :raw-latex:`\cite{botta2000}`. In the +Northern Hemisphere, counting of degree days begins on 1st January, and +of chilling days on 1st November. The calendar opposite of these dates +is used for points in the Southern Hemisphere. + +If the growing degree days exceed the critical threshold, leaf-on is +triggered by a change in the gridcell phenology status flag +:math:`S_{phen,grid}` where ‘2’ indicates that leaves should come on and +‘1’ indicates that they should fall. + +.. math:: + + \begin{array}{ll} + S_{phen,grid} = 2 + &\textrm{ if } S_{phen,grid} = 1\textrm{ and } GDD_{grid} \ge GDD_{crit} \\ + \end{array} + +Cold Leaf-off timing +~~~~~~~~~~~~~~~~~~~~ + +The leaf-off model is taken from the Sheffield Dynamic Vegetation Model +(SDGVM) and is similar to that for LPJ +:raw-latex:`\parencite{sitch2003}` and IBIS +:raw-latex:`\parencite{foley1996}` models. The average daily +temperatures of the previous 10 day period are stored. Senescence is +triggered when the number of days with an average temperature below +7.5\ :math:`^{o}` (:math:`n_{colddays}`) rises above a threshold values +:math:`n_{crit,cold}`, set at 5 days. + +.. math:: + + \begin{array}{ll} + S_{phen,grid} = 1 + &\textrm{ if } S_{phen,grid} = 2\textrm{ and } n_{colddays} \ge n_{crit,cold} \\ + \end{array} + +Global implementation modifications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Because of the global implementation of the cold-deciduous phenology +scheme, adjustments must be made to account for the possibility of +cold-deciduous plants experiencing situations where no chilling period +triggering leaf-off ever happens. If left unaccounted for, these leaves +will last indefinitely, resulting in highly unrealistic behaviour. +Therefore, we implement two additional rules. Firstly, if the number of +days since the last senescence event was triggered is larger than 364, +then leaf-off is triggered on that day. Secondly, if no chilling days +have occured during the winter accumulation period, then leaf-on is not +triggered. This means that in effect, where there are no cold periods, +leaves will fall off and not come back on, meaning that cold-deciduous +plants can only grow in places where there is a cold season. + +Further to this rule, we introduce a ‘buffer’ time periods after leaf-on +of 30 days, so that cold-snap periods in the spring cannot trigger a +leaf senescence. The 30 day limit is an arbitrary limit. In addition, we +constrain growing degree day accumulation to the second half of the year +(Jult onwards in the Northern hemisphere, or Jan-June in the Southern) +and only allow GDD accumulation while the leaves are off. + +Drought-deciduous Phenology +--------------------------- + +In the current version of the model, a drought deciduous algorithm +exists, but is not yet operational, due to issue detected in the exsting +CN and soil moisture modules, which also affect the behaviour of the +native ED drought deciduous model. This is a priority to address before +the science tag is released. + +Carbon Dynamics of deciduous plants +----------------------------------- + + [19]_ + +In the present version, leaf expansion and senescence happen over the +course of a single day. This is clearly not an empirically robust +representation of leaf behaviour, whereby leaf expansion occurs over a +period of 10-14 days, and senescence over a similar period. This will be +incorporated in later versions. When the cold or drought phenological +status of the gridcell status changes (:math:`S_{phen,grid}`) from ‘2’ +to ‘1’, and the leaves are still on (:math:`S_{phen,coh}` =2 ), the leaf +biomass at this timestep is ’remembered’ by the model state variable +:math:`l_{memory,coh}`. This provides a ‘target’ biomass for leaf onset +at the beginning of the next growing season (it is a target, since +depletion of stored carbon in the off season may render achieving the +target impossible). + +.. math:: l_{memory,coh} = b_{leaf,coh} + +Leaf carbon is then added to the leaf litter flux :math:`l_{leaf,coh}` +(KgC individual\ :math:`^{-1}`) + +.. math:: l_{leaf,coh} = b_{leaf,coh} + +The alive biomass is depleted by the quantity of leaf mass lost, and the +leaf biomass is set to zero + +.. math:: b_{alive,coh} = b_{alive,coh} - b_{leaf,coh} + +.. math:: b_{leaf,coh} = 0 + +Finally, the status :math:`S_{phen,coh}` is set to 1, indicating that +the leaves have fallen off. + +For bud burst, or leaf-on, the same occurs in reverse. If the leaves are +off (:math:`S_{phen,coh}`\ =1) and the phenological status triggers +budburst (:math:`S_{phen,grid}`\ =2) then the leaf mass is set the +maximum of the leaf memory and the available store + +.. math:: b_{leaf,coh} = \textrm{max}\left(l_{memory,coh}, b_{store,coh}\right.) + +this amount of carbon is removed from the store + +.. math:: b_{store,coh} = b_{store,coh} - b_{leaf,coh} + +and the new leaf biomass is added to the alive pool + +.. math:: b_{alive,coh} = b_{alive,coh} + b_{leaf,coh} + +Lastly, the leaf memory variable is set to zero and the phenological +status of the cohort back to ‘2’. No parameters are currently required +for this carbon accounting scheme. + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for phenology model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`n_{crit, | Threshold of | none | - | +| cold}` | cold days for | | | +| | senescence | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`T_{g}` | Threshold for | :math:`^{o}`\ C | | +| | counting | | | +| | growing degree | | | +| | days | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Seed Dynamics and Recruitment +============================= + + [20]_ + +The production of seeds and their subsequent germination is a process +that must be captured explicitly or implicitly in vegetation models. The +CLM(ED) contains a seed bank model designed to allow the dynamics of +seed production and germination to be simulated independently. In the +ED1.0 model, seed recruitment occurs in the same timestep as allocation +to seeds, which prohibits the survival of a viable seed bank through a +period of disturbance or low productivity (winter, drought). In the +CLM(ED) model, a plant functional type specific seed bank is tracked in +each patch (:math:`Seeds_{patch}` KgC m\ :math:`^{-2}`), whose rate of +change (KgC m\ :math:`^{-2}` y\ :math:`^{-1}`) is the balance of inputs, +germination and decay: + +.. math:: \frac{\delta Seeds_{FT}}{\delta t } = Seed_{in,ft} - Seed_{germ,ft} - Seed_{decay,ft} + +where :math:`Seed_{in}`, :math:`Seed_{germ}` and :math:`Seed_{decay}` +are the production, germination and decay (or onset of inviability) of +seeds, all in KgC m\ :math:`^{-2}` year\ :math:`^{-1}`. + +Seeds are assumed to be distributed evenly across the site (in this +version of the model), so the total input to the seed pool is therefore +the sum of all of the reproductive output of all the cohorts in each +patch of the correct PFT type. + +.. math:: Seed_{in,ft} = \frac{\sum_{p=1}^{n_{patch}}\sum_{i=1}^{n_{coh}}p_{seed,i}.n_{coh}}{area_{site}} + +Seed decay is the sum of all the processes that reduce the number of +seeds, taken from :raw-latex:`\cite{lischke2006}`. Firstly, the rate at +which seeds become inviable is described as a constant rate :math:`\phi` +(y:math:`^{-1}`) which is set to 0.51, the mean of the parameters used +by :raw-latex:`\cite{lischke2006}`. + +.. math:: Seed_{decay,ft} = Seeds_{FT}.\phi + +The seed germination flux is also prescribed as a fraction of the +existing pool (:math:`\alpha_{sgerm}`), but with a cap on maximum +germination rate :math:`\beta_{sgerm}`, to prevent excessive dominance +of one plant functional type over the seed pool. + +.. math:: Seed_{germ,ft} = \textrm{max}(Seeds_{FT}\cdot \alpha_{sgerm},\beta_{sgerm}) + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for seed model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`K_s` | Maximum seed | kgC m\ | | +| | mass | :math:`^{-2}` | | +| | | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\alpha_{ | Proportional | - | | +| sgerm}` | germination | | | +| | rate | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\beta_{s | Maximum | KgC | | +| germ}` | germination | m\ :math:`^{-2}`| | +| | rate | | | +| | | y\ :math:`^{-1}`| | +| | | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\phi` | Decay rate of | none | FT | +| | viable seeds | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`R_{frac, | Fraction of | none | FT | +| ft}` | :math:`C_{bal}` | | | +| | devoted to | | | +| | reproduction | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Fragmenting Litter Pool Production and Turnover +=============================================== + +| The original CLM4.5 model contains streams of carbon pertaining to + different chemical properties of litter (lignin, cellulose and labile + streams, specifically). In the CLM(ED) model, the fire simulation + scheme in the SPITFIRE model requires that the model tracks the pools + of litter pools that differ with respect to their propensity to burn + (surface area-volume ratio, bulk density etc.). Therefore, this model + contains more complexity in the representation of coarse woody debris. + We also introduce the concept of ’fragmenting’ pools, which are pools + that can be burned, but are not available for decomposition or + respiration. In this way, we can both maintain above-ground pools that + affect the rate of burning, and the lag between tree mortality and + availability of woody material for decomposition. +| The CLM(ED) recognizes four classes of litter. Above- and below-ground + coarse woody debris (:math:`CWD_{AG}`, :math:`CWD_{BG}`) and leaf + litter (:math:`l_{leaf}` and fine root litter :math:`l_{root}`). All + pools are represented per patch, and with units of kGC + m\ :math:`{^-2}`. Further to this, :math:`CWD_{AG}`, :math:`CWD_{BG}` + are split into four litter size classes (:math:`lsc`) for the purposes + of proscribing this to the SPITFIRE fire model (seed ’Fuel Load’ + section for more detail. 1-hour (twigs), 10-hour (small branches), + 100-hour (large branches) and 1000-hour(boles or trunks). 4.5 %, 7.5%, + 21 % and 67% of the woody biomass (:math:`b_{store,coh} + b_{sw,coh}`) + is partitioned into each class, respectively. + +:math:`l_{leaf}` and :math:`l_{root}` are indexed by plant functional +type (:math:`ft`). The rational for indexing leaf and fine root by PFT +is that leaf and fine root matter typically vary in their +carbon:nitrogen ratio, whereas woody pools typically do not. + +Rates of change of litter, all in kGC m\ :math:`{^-2}` +year\ :math:`^{-1}`, are calculated as + +.. math:: \frac{\delta CWD_{AG,out,lsc}}{ \delta t }= CWD_{AG,in,lsc} - CWD_{AG,out,lsc} + +.. math:: \frac{\delta CWD_{BG,out,lsc}}{ \delta t } = CWD_{BG,in,lsc} - CWD_{BG,in,lsc} + +.. math:: \frac{\delta l_{leaf,out,ft} }{ \delta t } = l_{leaf,in,ft} - l_{leaf,out,ft} + +.. math:: \frac{\delta l_{root,out,ft} }{ \delta t } = l_{root,in,ft} - l_{root,out,ft} + +Litter Inputs +------------- + +[21]_Inputs into the litter pools come from tissue turnover, mortality of +canopy trees, mortality of understorey trees, mortality of seeds, and +leaf senescence of deciduous plants. + +.. math:: l_{leaf,in,ft} =\Big(\sum_{i=1}^{n_{coh,ft}} n_{coh}(l_{md,coh} + l_{leaf,coh}) + M_{t,coh}.b_{leaf,coh}\Big)/\sum_{p=1}^{n_{pat}}A_{patch} + +where :math:`l_{md,coh}` is the leaf turnover rate for evergreen trees +and :math:`l_{leaf,coh}` is the leaf loss from phenology in that +timestep (KgC :math:`m^{-2}`. :math:`M_{t,coh}` is the total mortality +flux in that timestep (in individuals). For fine root input. +:math:`n_{coh,ft}` is the number of cohorts of functional type +‘:math:`FT`’ in the current patch. + +.. math:: l_{root,in,ft} =\Big(\sum_{i=1}^{n_{coh,ft}} n_{coh}(r_{md,coh} ) + M_{t,coh}.b_{root,coh}\Big)/\sum_{p=1}^{n_{pat}}A_p + +where :math:`r_{md,coh}` is the root turnover rate. For coarse woody +debris input (:math:`\mathit{CWD}_{AG,in,lsc}` , we first calculate the +sum of the mortality :math:`M_{t,coh}.(b_{struc,coh}+b_{sw,coh})` and +turnover :math:`n_{coh}(w_{md,coh}`) fluxes, then separate these into +size classes and above/below ground fractions using the fixed fractions +assigned to each (:math:`f_{lsc}` and :math:`f_{ag}`) + +.. math:: \mathit{CWD}_{AG,in,lsc} =\Big(f_{lsc}.f_{ag}\sum_{i=1}^{n_{coh,ft}}n_{coh}w_{md,coh} + M_{t,coh}.(b_{struc,coh}+b_{sw,coh})\Big)/\sum_{p=1}^{n_{pat}}A_p + +.. math:: \mathit{CWD}_{BG,in,lsc} =\Big(f_{lsc}.(1-f_{ag})\sum_{i=1}^{n_{coh,ft}}n_{coh}w_{md,coh} + M_{t,coh}.(b_{struc,coh}+b_{sw,coh})\Big)/\sum_{p=1}^{n_{pat}}A_p + +Litter Outputs +-------------- + + [22]_ + +The fragmenting litter pool is available for burning but not for +respiration or decomposition. Fragmentation rates are calculated +according to a maximum fragmentation rate (:math:`\alpha_{cwd,lsc}` or +:math:`\alpha_{litter}`) which is ameliorated by a temperature and water +dependent scalar :math:`S_{tw}`. The form of the temperature scalar is +taken from the existing CLM4.5BGC decomposition cascade calculations). +The water scaler is equal to the water limitation on photosynthesis +(since the CLM4.5BGC water scaler pertains to the water potential of +individual soil layers, which it is difficult to meaningfully average, +given the non-linearities in the impact of soil moisture). The scaler +code is modular, and new functions may be implemented trivially. Rate +constants for the decay of the litter pools are extremely uncertain in +literature, as few studies either separate litter into size classes, nor +examine its decomposition under non-limiting moisture and temperature +conditions. Thus, these parameters should be considered as part of +sensitivity analyses of the model outputs. + +.. math:: \mathit{CWD}_{AG,out,lsc} = CWD_{AG,lsc}. \alpha_{cwd,lsc}.S_{tw} + +.. math:: \mathit{CWD}_{BG,out,lsc} = CWD_{BG,lsc} .\alpha_{cwd,lsc}.S_{tw} + +.. math:: l_{leaf,out,ft} = l_{leaf,ft}.\alpha_{litter}.S_{tw} + +.. math:: l_{root,out,ft} = l_{root,ft}.\alpha_{root,ft}.S_{tw} + +Flux into decompsition cascade +------------------------------ + + [23]_ + +Upon fragmentation and release from the litter pool, carbon is +transferred into the labile, lignin and cellulose decomposition pools. +These pools are vertically resolved in the biogeochemistry model. The +movement of carbon into each vertical layer is obviously different for +above- and below-ground fragmenting pools. For each layer :math:`z` and +chemical litter type :math:`i`, we derive a flux from ED into the +decomposition cascade as :math:`ED_{lit,i,z}` (kGC m\ :math:`^{-2}` +s\ :math:`^{-1}`) + +where :math:`t_c` is the time conversion factor from years to seconds, +:math:`f_{lab,l}`, :math:`f_{cel,l}` and :math:`f_{lig,l}` are the +fractions of labile, cellulose and lignin in leaf litter, and +:math:`f_{lab,r}`, :math:`f_{cel,r}` and :math:`f_{lig,r}` are their +counterparts for root matter. Similarly, :math:`l_{prof}`, +:math:`r_{f,prof}`\ and :math:`r_{c,prof}` are the fractions of leaf, +coarse root and fine root matter that are passed into each vertical soil +layer :math:`z`, derived from the CLM(BGC) model. + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for litter model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`\alpha_{ | Maximum | y\ :math:`^{-1}`| | +| cwd,lsc}` | fragmentation | | | +| | rate of CWD | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\alpha_{ | Maximum | y\ :math:`^{-1}`| | +| litter}` | fragmentation | | | +| | rate of leaf | | | +| | litter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\alpha_{ | Maximum | y\ :math:`^{-1}`| | +| root}` | fragmentation | | | +| | rate of fine | | | +| | root litter | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{lab,l | Fraction of | none | | +| }` | leaf mass in | | | +| | labile carbon | | | +| | pool | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{cel,l | Fraction of | none | | +| }` | leaf mass in | | | +| | cellulose | | | +| | carbon pool | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{lig,l | Fraction of | none | | +| }` | leaf mass in | | | +| | lignin carbon | | | +| | pool | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{lab,r | Fraction of | none | | +| }` | root mass in | | | +| | labile carbon | | | +| | pool | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{cel,r | Fraction of | none | | +| }` | root mass in | | | +| | cellulose | | | +| | carbon pool | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{lig,r | Fraction of | none | | +| }` | root mass in | | | +| | lignin carbon | | | +| | pool | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`l_{prof, | Fraction of | none | soil layer | +| z}` | leaf matter | | | +| | directed to | | | +| | soil layer z | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`r_{c,pro | Fraction of | none | soil layer | +| f,z}` | coarse root | | | +| | matter directed | | | +| | to soil layer z | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`r_{f,pro | Fraction of | none | soil layer | +| f,z}` | fine root | | | +| | matter directed | | | +| | to soil layer z | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +Plant Mortality +=============== + +Total plant mortality per cohort :math:`M_{t,coh}`, (fraction +year\ :math:`^{-1}`) is simulated as the sum of four additive terms, + +.. math:: M_{t,coh}= M_{b,coh} + M_{cs,coh} + M_{hf,coh} + M_{f,coh}, + +where :math:`M_b` is the background mortality that is unaccounted by +any of the other mortality rates and is fixed at 0.014. :math:`M_{cs}` +is the carbon starvation derived mortality, which is a function of the +non-structural carbon storage term :math:`b_{store,coh}` and the +PFT-specific ‘target’ carbon storage, :math:`l_{targ,ft}`, as follows: + +.. math:: M_{cs,coh}= \rm{max} \left(0.0, S_{m,ft} \left(0.5 - \frac{b_{store,coh}}{l_{targ,ft}b_{leaf}}\right)\right) + +where :math:`S_{m,ft}` is the ‘stress mortality’ parameter, or the +fraction of trees in a landscape that die when the mean condition of a +given cohort triggers mortality. This parameter is needed to scale from +individual-level mortality simulation to grid-cell average conditions. + +Mechanistic simulation of hydraulic failure is not undertaken on account +of it’s mechanistic complexity (see :raw-latex:`\cite{mcdowell2013}`for +details). Instead, we use a proxy for hydraulic failure induced +mortality (:math:`M_{hf,coh}`) that uses a water potential threshold +beyond mortality is triggered, such that the tolerance of low water +potentials is a function of plant functional type (as expressed via the +:math:`\psi_c` parameter). For each day that the aggregate water +potential falls below a threshold value, a set fraction of the trees are +killed. The aggregation of soil moisture potential across the root zone +is expressed using the :math:`\beta` function. We thus determine plant +mortality caused by extremely low water potentials as + +.. math:: + + M_{hf,coh} = \left\{ \begin{array}{ll} + S_{m,ft}& \textrm{for } \beta_{ft} < 10^{-6}\\ + &\\ + 0.0& \textrm{for } \beta_{ft}>= 10^{-6}.\\ + \end{array} \right. + +The threshold value of 10\ :math:`^{-6}` represents a state where the +average soil moisture potential is within 10\ :math:`^{-6}` of the +wilting point (a PFT specific parameter :math:`\theta_{w,ft}`). + +:math:`M_{hf,coh}` is the fire-induced mortality, as described in the +fire modelling section. + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for mortality model. } + ++---------------------+--------------------------------+-------+------------+ +| Parameter Symbol | Parameter Name | Units | indexed by | ++=====================+================================+=======+============+ +| :math:`S_{m,ft}` | Stress Mortality Scaler | none | | ++---------------------+--------------------------------+-------+------------+ +| :math:`l_{targ,ft}` | Target carbon storage fraction | none | ft | ++---------------------+--------------------------------+-------+------------+ + +.. raw:: latex + + \bigskip + +Fire +==== + + [24]_ + +The influence of fire on vegetation is estimated using the SPITFIRE +model, which has been modified for use in ED following it’s original +implementation in the LPJ-SPITFIRE model +(:raw-latex:`\parencite{thonicke2010,pfeiffer2013}`. This model as +described is substantially different from the existing CLM4.5 fire model +:raw-latex:`\parencite{li2012}`, however, further developments are +intended to increase the merging of SPITFIRE’s natural vegetation fire +scheme with the fire suppression, forest-clearing and peat fire +estimations in the existing model. The coupling to the ED model allows +fires to interact with vegetation in a ‘size-structured’ manner, so +small fires can burn only understorey vegetation. Also, the patch +structure and representation of succession in the ED model allows the +model to track the impacts of fire on different forest stands, therefore +removing the problem of area-averaging implicit in area-based DGVMs. The +SPITFIRE approach has also been coupled to the LPJ-GUESS +individual-based model (Forrest et al. in prep) and so this is not the +only implementation of this type of scheme in existence. + +The SPITFIRE model operates at a daily timestep and at the patch level, +meaning that different litter pools and vegetation charecteristics of +open and closed forests can be represented effectively (we omit the +‘patch’ subscript throughout for simplicity). + +Properties of fuel load +----------------------- + +Many fire processes are impacted by the properties of the litter pool in +the SPITFIRE model. There are one live (live grasses) and five dead fuel +categories (dead leaf litter and four pools of coarse woody debris). +Coarse woody debris is classified into 1h, 10h, 100h, and 1000h fuels, +defined by “\ *the order of magnitude of time required for fuel to lose +(or gain) 63% of the difference between its current moisture content and +the equilibrium moisture content under defined atmospheric conditions.*" +:raw-latex:`\parencite{thonicke2010}`. For the purposes of describing +the behaviour of fire, we introduce a new index ‘fuel class’ *fc*, the +values of which correspond to each of the six possible fuel categories +as follows. + ++------------+------------------+-------------+ +| *fc* index | Fuel type | Drying Time | ++============+==================+=============+ +| 1 | dead grass | n/a | ++------------+------------------+-------------+ +| 2 | twigs | 1h fuels | ++------------+------------------+-------------+ +| 3 | small branches | 10h fuel | ++------------+------------------+-------------+ +| 4 | large branches | 100h fuel | ++------------+------------------+-------------+ +| 5 | stems and trunks | 1000h fuel | ++------------+------------------+-------------+ +| 6 | live grasses | n/a | ++------------+------------------+-------------+ + +.. raw:: latex + + \bigskip + +Fuel load +~~~~~~~~~ + +Total fuel load :math:`F_{tot,patch}` for a given patch is the sum of +the above ground coarse woody debris and the leaf litter, plus the alive +grass leaf biomass :math:`b_{l,grass}` multiplied by the non-mineral +fraction (1-:math:`M_{f}`). + +.. math:: F_{tot,patch}=\left(\sum_{fc=1}^{fc=5} CWD_{AG,fc}+l_{litter}+b_{l,grass}\right)(1-M_{f}) + +Many of the model behaviours are affected by the patch-level weighted +average properties of the fuel load. Typically, these are calculated in +the absence of 1000-h fuels because these do not contribute greatly to +fire spread properties. + +Nesterov Index +~~~~~~~~~~~~~~ + +Dead fuel moisture (:math:`\emph{moist}_{df,fc}`), and several other +properties of fire behaviour, are a function of the ‘Nesterov Index’ +(:math:`N_{I}`) which is an accumulation over time of a function of +temperature and humidity (Eqn 5, :raw-latex:`\cite{thonicke2010}`). + +.. math:: N_{I}=\sum{\textrm{max}(T_{d}(T_{d}-D),0)} + +where :math:`T_{d}` is the daily mean temperature in :math:`^{o}`\ C and +:math:`D` is the dew point calculated as . + +.. math:: + + \begin{aligned} + \upsilon&=&\frac{17.27T_{d}}{237.70+T_{d}}+\log(RH/100)\\ + D&=&\frac{237.70\upsilon}{17.27-\upsilon}\end{aligned} + +where :math:`RH` is the relative humidity (%). + +Dead Fuel Moisture Content +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dead fuel moisture is calculated as + +.. math:: \emph{moist}_{df,fc}=e^{-\alpha_{fmc,fc}N_{I}} + +where :math:`\alpha_{fmc,fc}` is a parameter defining how fuel moisture +content varies between the first four dead fuel classes. + +Live grass moisture Content +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The live grass fractional moisture content(\ :math:`\emph{moist}_{lg}`) +is a function of the soil moisture content. (Equation B2 in +:raw-latex:`\cite{thonicke2010}`) + +.. math:: \emph{moist}_{lg}=\textrm{max}(0.0,\frac{10}{9}\theta_{30}-\frac{1}{9}) + +where :math:`\theta_{30}` is the fractional moisture content of the top +30cm of soil. + +Patch Fuel Moisture +~~~~~~~~~~~~~~~~~~~ + +The total patch fuel moisture is based on the weighted average of the +different moisture contents associated with each of the different live +grass and dead fuel types available (except 1000-h fuels). + +.. math:: F_{m,patch}=\sum_{fc=1}^{fc=4} \frac{F_{fc}}{F_{tot}}\emph{moist}_{df,fc}+\frac{b_{l,grass}}{F_{tot}}\emph{moist}_{lg} + +Effective Fuel Moisture Content +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Effective Fuel Moisture Content is used for calculations of fuel +consumed, and is a function of the ratio of dead fuel moisture content +:math:`M_{df,fc}` and the moisture of extinction factor, +:math:`m_{ef,fc}` + +.. math:: E_{moist,fc}=\frac{\emph{moist}_{fc}}{m_{ef,fc}} + +where the :math:`m_{ef}` is a function of surface-area to volume ratio. + +.. math:: m_{ef,fc}=0.524-0.066\log_{10}{\sigma_{fc}} + +Patch Fuel Moisture of Extinction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The patch ‘moisture of extinction’ factor (:math:`F_{mef}`) is the +weighted average of the :math:`m_{ef}` of the different fuel classes + +.. math:: F_{mef,patch}=\sum_{fc=1}^{fc=5} \frac{F_{fc}}{F_{tot}}m_{ef,fc}+\frac{b_{l,grass}}{F_{tot}}m_{ef,grass} + +Patch Fuel Bulk Density +~~~~~~~~~~~~~~~~~~~~~~~ + +The patch fuel bulk density is the weighted average of the bulk density +of the different fuel classes (except 1000-h fuels). + +.. math:: F_{bd,patch}=\sum_{fc=1}^{fc=4} \frac{F_{fc}}{F_{tot}}\beta_{fuel,fc}+\frac{b_{l,grass}}{F_{tot}}\beta_{fuel,lgrass} + +where :math:`\beta_{fuel,fc}` is the bulk density of each fuel size +class (kG m\ :math:`^{-3}`) + +Patch Fuel Surface Area to Volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The patch surface area to volume ratio (:math:`F_{\sigma}`) is the +weighted average of the surface area to volume ratios +(:math:`\sigma_{fuel}`) of the different fuel classes (except 1000-h +fuels). + +.. math:: F_{\sigma}=\sum_{fc=1}^{fc=4} \frac{F_{fc}}{F_{tot}}\sigma_{fuel,fc}+\frac{b_{l,grass}}{F_{tot}}\sigma_{fuel,grass} + +Forward rate of spread +---------------------- + +For each patch and each day, we calculate the rate of forward spread of +the fire *ros*\ :math:`_{f}` (nominally in the direction of the wind). + +.. math:: \emph{ros}_{f}=\frac{i_{r}x_{i}(1-\phi_{w})}{F_{bd,patch}e_{ps}q_{ig}} + +:math:`e_{ps}` is the effective heating number +(:math:`e^{\frac{-4.528}{F_{\sigma,patch}}}`). :math:`q_{ig}` is the +heat of pre-ignition (:math:`581+2594F_{m}`). :math:`x_{i}` is the +propagating flux calculated as (see :raw-latex:`\cite{thonicke2010}` +Appendix A). + +.. math:: + + x_{i}= \left\{ \begin{array}{ll} + 0.0& \textrm{for $F_{\sigma,patch}<0.00001$}\\ + \frac{e^{0.792+3.7597F_{\sigma,patch}^{0.5}(\frac{F_{bd,patch}}{p_{d}}+0.1)}}{192+7.9095F_{\sigma,patch}} & \textrm{for $F_{\sigma,patch}\geq 0.00001$}\\ + \end{array} \right. + +:math:`\phi_{w}` is the influence of windspeed on rate of spread. + +.. math:: \phi_{w}=cb_{w}^{b}.\beta^{-e} + +Where :math:`b`, :math:`c` and :math:`e` are all functions of +surface-area-volume ratio :math:`F_{\sigma,patch}`: +:math:`b=0.15988F_{\sigma,patch}^{0.54}`, +:math:`c=7.47e^{-0.8711F_{\sigma,patch}^{0.55}}`, +:math:`e=0.715e^{-0.01094F_{\sigma,patch}}`. :math:`b_{w}=196.86W` where +:math:`W` is the the windspeed in ms\ :math:`^{-1}`, and +:math:`\beta=\frac{F_{bd}/p_{d}}{0.200395F_{\sigma,patch}^{-0.8189}}` +where :math:`p_{d}` is the particle density (513). + +:math:`i_{r}` is the reaction intensity, calculated using the following +set of expressions (from :raw-latex:`\cite{thonicke2010}` Appendix A).: + +.. math:: + + \begin{aligned} + i_{r}&=&\Gamma_{opt}F_{tot}Hd_{moist}d_{miner}\\ + d_{moist}&=&\textrm{max}\Big(0.0,(1-2.59m_{w}+5.11m_{w}^{2}-3.52m_{w}^{3})\Big)\\ + m_{w}&=&\frac{F_{m,patch}}{F_{mef,patch}}\\ + \Gamma _{opt}&=&\Gamma_{max}\beta^{a}\lambda\\ + \Gamma _{max}&=&\frac{1}{0.0591+2.926F_{\sigma,patch}^{-1.5}}\\ + \lambda&=&e^{a(1-\beta)}\\ + a&=&8.9033F_{\sigma,patch}^{-0.7913}\end{aligned} + +:math:`\Gamma_{opt}` is the residence time of the fire, and +:math:`d_{miner}` is the mineral damping coefficient +(=0.174:math:`S_e^{-0.19}` , where :math:`S_e` is 0.01 and so = +:math:`d_{miner}` 0.41739). + +Fuel Consumption +---------------- + +The fuel consumption (fraction of biomass pools) of each dead biomass +pool in the area affected by fire on a given day (:math:`f_{c,dead,fc}`) +is a function of effective fuel moisture :math:`E_{moist,fc}` and size +class *fc* (Eqn B1, B4 and B5, :raw-latex:`\cite{thonicke2010}`). The +fraction of each fuel class that is consumed decreases as its moisture +content relative to its moisture of extinction (:math:`E_{moist,fc}`) +increases. + +.. math:: f_{cdead,fc}=\textrm{max}\left(0,\textrm{min}(1,m_{int,mc,fc}-m_{slope,mc,fc}E_{moist,fc})\Big)\right. + +:math:`m_{int}` and :math:`m_{slope}` are parameters, the value of which +is modulated by both size class :math:`fc` and by the effective fuel +moisture class :math:`mc`, defined by :math:`E_{moist,fc}`. +:math:`m_{int}` and :math:`m_{slope}` are defined for low-, mid-, and +high-moisture conditions, the boundaries of which are also functions of +the litter size class following :raw-latex:`\cite{peterson1986}` (page +802). The fuel burned, :math:`f_{cground,fc}` (Kg m\ :math:`^{-2}` +day\ :math:`^{-1}`) iscalculated from :math:`f_{cdead,fc}` for each fuel +class: + +.. math:: f_{cground,fc}=f_{c,dead,fc}(1-M_{f})\frac{F_{fc}}{0.45} + +Where 0.45 converts from carbon to biomass. The total fuel consumption, +:math:`f_{ctot,patch}`\ (Kg m\ :math:`^{-2}`), used to calculate fire +intensity, is then given by + +.. math:: f_{ctot,patch}=\sum_{fc=1}^{fc=4} f_{c,ground,fc} + f_{c,ground,lgrass} + +There is no contribution from the 1000 hour fuels to the patch-level +:math:`f_{ctot,patch}` used in the fire intensity calculation. + +Fire Intensity +-------------- + +Fire intensity at the front of the burning area (:math:`I_{surface}`, kW +m\ :math:`^{-2}`) is a function of the total fuel consumed +(:math:`f_{ctot,patch}`) and the rate of spread at the front of the +fire, :math:`\mathit{ros}_{f}` (m min\ :math:`^{-1}`) (Eqn 15 +:raw-latex:`\cite{thonicke2010}`) + +.. math:: I_{surface}=\frac{0.001}{60}f_{energy} f_{ctot,patch}\mathit{ros}_{f} + +where :math:`f_{energy}` is the energy content of fuel (kJ/kG - the +same for alll fuel classes). Fire intensity is used to define whether an +ignition is successful. If the fire intensity is greater than 50kw/m +then the ignition is successful. + +Fire Duration +------------- + +Fire duration is a function of the fire danger index with a maximum +length of :math:`F_{dur,max}` (240 minutes in +:raw-latex:`\cite{thonicke2010}` Eqn 14, derived from Canadian Forest +Fire Behaviour Predictions Systems) + +.. math:: D_{f}=\textrm{min}\Big(F_{dur,max},\frac{F_{dur,max}}{1+F_{dur,max}e^{-11.06fdi}}\Big) + +Fire Danger Index +----------------- + +Fire danger index (*fdi*) is a representation of the effect of +meteorological conditions on the likelihood of a fire. It is calculated +for each gridcell as a function of the Nesterov Index . +:math:`\emph{fdi}` is calculated from :math:`NI` as + +.. math:: \emph{fdi}=1-e^{\alpha N_{I}} + +where :math:`\alpha` = 0.00037 following +:raw-latex:`\cite{venevsky2002}`. + +Area Burned +----------- + +Total area burnt is assumed to be in the shape of an ellipse, whose +major axis :math:`f_{length}` (m) is determined by the forward and +backward rates of spread (:math:`ros_{f}` and :math:`ros_{b}` +respectively). + +.. math:: f_{length}=F_{d}(ros_{b}+ros_{f}) + +:math:`ros_{b}` is a function of :math:`ros_{f}` and windspeed (Eqn 10 +:raw-latex:`\cite{thonicke2010}`) + +.. math:: ros_{b}=ros_{f}e^{-0.72W} + +The minor axis to major axis ratio :math:`l_{b}` of the ellipse is +determined by the windspeed. If the windspeed (:math:`W`) is less than +16.67 ms\ :math:`^{-1}` then :math:`l_{b}=1`. Otherwise (Eqn 12 and 13, +:raw-latex:`\cite{thonicke2010}`) + +.. math:: l_{b}=\textrm{min}\Big(8,f_{tree}(1.0+8.729(1.0-e^{-0.108W})^{2.155})+(f_{grass}(1.1+3.6W^{0.0464}))\Big) + +:math:`f_{grass}` and :math:`f_{tree}` are the fractions of the patch +surface covered by grass and trees respectively. + +The total area burned (:math:`A_{burn}` in m\ :math:`^{2}`) is therefore +(Eqn 11, :raw-latex:`\cite{thonicke2010}`) + +.. math:: A_{burn}=\frac{n_{f}\frac{3.1416}{4l_{b}}(f_{length}^{2}))}{10000} + +where :math:`n_{f}` is the number of fires. + +Crown Damage +------------ + +:math:`c_{k}` is the fraction of the crown which is consumed by the +fire. This is calculated from scorch height :math:`H_{s}`, tree height +:math:`h` and the crown fraction parameter :math:`F_{crown}` (Eqn 17 +:raw-latex:`\cite{thonicke2010}`): + +.. math:: + + c_{k} = \left\{ \begin{array}{ll} + 0 & \textrm{for $H_{s}<(h-hF_{crown})$}\\ + 1-\frac{h-H_{s}}{h-F_{crown}}& \textrm{for $h>H_{s}>(h-hF_{crown})$}\\ + 1 & \textrm{for $H_{s}>h$ } + \end{array} \right. + +The scorch height :math:`H_{s}` (m) is a function of the fire intensity, +following :raw-latex:`\cite{byram1959}`, and is proportional to a plant +functional type specific parameter :math:`\alpha_{s,ft}` (Eqn 16 +:raw-latex:`\cite{thonicke2010}`): + +.. math:: H_{s}=\sum_{FT=1}^{NPFT}{\alpha_{s,p}\cdot f_{biomass,ft}} I_{surface}^{0.667} + +where :math:`f_{biomass,ft}` is the fraction of the above-ground +biomass in each plant functional type. + +Cambial Damage and Kill +----------------------- + +The cambial kill is a function of the fuel consumed :math:`f_{c,tot}`, +the bark thickness :math:`t_{b}`, and :math:`\tau_{l}`, the duration of +cambial heating (minutes) (Eqn 8, :raw-latex:`\cite{peterson1986}`): + +.. math:: \tau_{l}=\sum_{fc=1}^{fc=5}39.4F_{p,c}\frac{10000}{0.45}(1-(1-f_{c,dead,fc})^{0.5}) + +Bark thickness is a linear function of tree diameter :math:`dbh_{coh}`, +defined by PFT-specific parameters :math:`\beta_{1,bt}` and +:math:`\beta_{2,bt}` (Eqn 21 :raw-latex:`\cite{thonicke2010}`): + +.. math:: t_{b,coh}=\beta_{1,bt,ft}+\beta_{2,bt,ft}dbh_{coh} + +The critical time for cambial kill, :math:`\tau_{c}` (minutes) is given +as (Eqn 20 :raw-latex:`\cite{thonicke2010}`): + +.. math:: \tau_{c}=2.9t_{b}^{2} + +The mortality rate caused by cambial heating :math:`\tau_{pm}` of trees +within the area affected by fire is a function of the ratio between +:math:`\tau_{l}` and :math:`\tau_{c}` (Eqn 19, +:raw-latex:`\cite{thonicke2010}`): + +.. math:: + + \tau_{pm} = \left\{ \begin{array}{ll} + 1.0 & \textrm{for } \tau_{1}/\tau_{c}\geq \textrm{2.0}\\ + 0.563(\tau_{l}/\tau_{c}))-0.125 & \textrm{for } \textrm{2.0} > \tau_{1}/\tau_{c}\ge \textrm{0.22}\\ + 0.0 & \textrm{for } \tau_{1}/\tau_{c}< \textrm{0.22}\\ + \end{array} \right. + +.. raw:: latex + + \bigskip + +.. raw:: latex + + \captionof{table}{Parameters needed for fire model. } + ++-----------------+-----------------+-----------------+-----------------+ +| Parameter | Parameter Name | Units | indexed by | +| Symbol | | | | ++=================+=================+=================+=================+ +| :math:`\beta_{1 | Intercept of | mm | *FT* | +| ,bt}` | bark thickness | | | +| | function | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\beta_{2 | Slope of bark | mm | *FT* | +| ,bt}` | thickness | cm\ :math:`^{-1 | | +| | function | }` | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`F_{crown | Ratio of crown | none | *FT* | +| }` | height to total | | | +| | height | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\alpha_{ | Fuel moisture | :math:`{^o}`\ C | *fc* | +| fmc}` | parameter | \ :math:`^{-2}` | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\beta_{f | Fuel Bulk | kG | *fc* | +| uel}` | Density | m\ :math:`^{-3}`| | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\sigma_{ | Surface area to | cm | *fc* | +| fuel,fc}` | volume ratio | :math:`^{-1}` | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`m_{int}` | Intercept of | none | :math:`fc`, | +| | fuel burned | | moisture class | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`m_{slope | Slope of fuel | none | :math:`fc`, | +| }` | burned | | moisture class | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`M_f` | Fuel Mineral | | | +| | Fraction | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`F_{dur,m | Maximum | Minutes | | +| ax}` | Duration of | | | +| | Fire | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`f_{energ | Energy content | kJ/kG | | +| y}` | of fuel | | | ++-----------------+-----------------+-----------------+-----------------+ +| :math:`\alpha_{ | Flame height | | *FT* | +| s}` | parameter | | | ++-----------------+-----------------+-----------------+-----------------+ + +.. raw:: latex + + \bigskip + +| + +.. raw:: latex + + \printbibliography + +.. [1] + This description covers algorithms in the ‘fuse_cohorts’ subroutine. + +.. [2] + This description covers algorithms in the ‘fuse_patches’ subroutine. + +.. [3] + This description covers algorithms in the ‘fuse_2_patches’ + subroutine. + +.. [4] + This description covers the structure of code in all modules in + clm4_5 that are located in ‘ED’ subdirectories + +.. [5] + This description covers algorithms in the ‘init_cohorts’ subroutine + +.. [6] + This description relates to algorithms in the allocate_live_biomass + subroutine + +.. [7] + This description relates to algorithms in the EDCanopyStructure + subroutine + +.. [8] + This description relates to algorithms in the canopy_spread + subroutine + +.. [9] + This description relates to algorithms in the + canopy_leaf_area_profile subroutine + +.. [10] + This description relates to algorithms in the ED_norman_radiation + subroutine + +.. [11] + This description relates to algorithms in the ED_photosynthesis + subroutine + +.. [12] + This description relates to algorithms in the ED_btran subroutine + +.. [13] + This description relates to algorithms in the ED_photosynthesis + subroutine + +.. [14] + This description relates to algorithms in the ED_photosynthesis + subroutine + +.. [15] + This description relates to algorithms in the Growth_Derivatives + subroutine + +.. [16] + This description relates to algorithms in the ED_GrowthFunctions + subroutine + +.. [17] + This description relates to algorithms in the trim_canopy subroutine + +.. [18] + This description relates to algorithms in the phenology subroutine + +.. [19] + This description relates to algorithms in the phenology_leafoff + subroutine + +.. [20] + This description relates to algorithms in the seed_in, seed_decay and + seed_germination subroutines + +.. [21] + This description relates to algorithms in the CWD_input, + mortality_litter_fluxes and fire_litter_fluxes subroutines + +.. [22] + This description relates to algorithms in the CWD_out subroutine + +.. [23] + This description relates to algorithms in the flux_into_litter_pools + subroutine +.. [24] + This description relates to algorithms in the ’SFMainMod’ subroutines From 3f5bfd8a5aef75763075d85af2ca02f29d2ca691 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Thu, 7 Dec 2017 11:21:40 -0700 Subject: [PATCH 115/255] modified author section of FATES tech note --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 72001f2827..beb93f3ac0 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -1,7 +1,3 @@ -====================================== -CLM(ED) model: Technical Documentation -====================================== - .. _rst_Dynamic Global Vegetation Model: Dynamic Global Vegetation @@ -30,17 +26,6 @@ Preamble Apr 1;8(4). | https://pdfs.semanticscholar.org/396c/b9f172cb681421ed78325a2237bfb428eece.pdf -Authors -======= - -Rosie Fisher, Stefan Muszala, Mariana Verteinstein, Peter Lawrence, Chonggang Xu,Nate McDowell, Ryan Knox, Charles Koven, Jennifer Holm, Brendan Rogers, David Lawrence, and Gordon Bonan. - -Acknowledgements -================ - -The development of the ideas in this document has benefitted from -conversation with many people, including William Bond, Peter Cox, Matthew Forest, Andrew Fox, William Hoffman, Peter Lawrence, Jeremy Lichstein, Heike Lischke, Mark Lomas, Nathan McDowell, Paul Moorcroft, Colin Prentice, Drew Purves, Naomi Tague, Benjamin Sanderson, Stephen Sitch, Abigail Swann, Anthony Walker, Mathew Williams, F.Ian Woodward \& S\"onke Zaehle. - Introduction ============ From 23a4006ea26fd41c155cf14ff663df443deeff9e Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Thu, 7 Dec 2017 14:14:49 -0700 Subject: [PATCH 116/255] altered headings on FATES chapter --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 277 ++++++++---------- 1 file changed, 120 insertions(+), 157 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index beb93f3ac0..c6f0558b6b 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -4,7 +4,7 @@ Dynamic Global Vegetation =================================== What has changed ----------------- +^^^^^^^^^^^^^^^^^^^^ - Deprecation of the dynamic global vegetation model (DGVM): The CLM5.0 model contains the legancy 'CNDV' code, which runs the CLM4(CN) model in combination with the LPJ-derived dynamics vegetation model introduced in CLM3. While this capacity has not technically been removed from the model, the DGVM has not been tested in the development of CLM5 and is no longer scientifically supported. @@ -12,25 +12,22 @@ What has changed Technical Documentation for FATES -================================== +=================================== -Preamble -======== +Introduction +^^^^^^^^^^^^^^^^^^^^ -| This document is a technical appendix to -| Fisher RA, Muszala S, Verteinstein M, Lawrence P, Xu C, McDowell NG, + This document is a technical appendix to + Fisher RA, Muszala S, Verteinstein M, Lawrence P, Xu C, McDowell NG, Knox RG, Koven C, Holm J, Rogers BM, Lawrence D. Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes. Geoscientific Model Development Discussions. 2015 Apr 1;8(4). -| https://pdfs.semanticscholar.org/396c/b9f172cb681421ed78325a2237bfb428eece.pdf + https://pdfs.semanticscholar.org/396c/b9f172cb681421ed78325a2237bfb428eece.pdf -Introduction -============ - -The CLM(ED) model is presented here as an option within the structure of +FATES is presented here as an option within the structure of the Community Land Model (CLM). Ecosystem Demography (‘ED’), is a concept derived from the work of :raw-latex:`\cite{mc_2001}` and is a cohort model of vegetation competition and co-existence, allowing a @@ -53,14 +50,11 @@ radiation transfer, for drought-deciduous and cold-deciduous phenology, for carbon storage allocation, and for tree mortality under carbon stress, are also included and presented here. -This Document -------------- +This Document UPDATE +---------------- This document describes the implementation of the Ecosystem Demography -concept within the Community Land Model. It is intended as a -supplementary document to the main CLM technical note, which is at the -time of writing, the CLM4.5 technical note -:raw-latex:`\parencite{oleson2013}`. The material covered describes how +concept within the Community Land Model. The material covered describes how the Ecosystem Demography code is organized, how it interacts with the pre-existing CLM routines, and the new aspects of plant physiology and vegetation dynamics that are introduced further to those already @@ -71,10 +65,10 @@ model, which is a fully operational land surface scheme concept and an array of physiological and ecological innovations surrounding the basic concept. Therefore, to avoid confusion between the concept of ‘Ecosystem Demography’ and the implementation of this concept -in different models, we refer our model as the ‘CLM(ED)’ throughout. +in different models, we refer our model as the ‘FATES’ (the functionally Assembled Terrestrial Ecosystem Simulator) throughout. -The representation of ecosystem heterogeneity in the CLM(ED) -============================================================ +The representation of ecosystem heterogeneity in FATES +^^^^^^^^^^^^^^^ The land surface of the Earth is heterogeneous for many reasons, driven by variations in climate, edaphic history, ecological variability, @@ -88,7 +82,7 @@ surface (e.g. soils, ice, lakes, bare ground) and then ‘columns’ referring to elements of the surface that share below ground resources (water & nutrients). Within the ‘soil’ landunit, for example, there are separate columns for crops, and for natural vegetation, as these are -assumed to use separate resource pools. The CLM(ED) model at present +assumed to use separate resource pools. The FATES model at present only operates on the naturally vegetated column. The ‘soil’ column is sub-divided into numerous tiles, that correspond to statistical fractions of the potentially vegetated land area. In the CLM 4.5 (and @@ -101,7 +95,7 @@ surface models deployed in climate prediction. The introduction of the Ecosystem Demography concept introduces significant alterations to the representation of the land surface in the -CLM. In the CLM(ED), the tiling structure represents the disturbance +CLM. In FATES, the tiling structure represents the disturbance history of the ecosystem. Thus, some fraction of the land surface is characterized as ‘recently disturbed’, some fraction has escaped disturbance for a long time, and other areas will have intermediate @@ -205,7 +199,7 @@ classes within those plant functional types. Each cohort is associated with a number of identical trees, :math:`n_{coh}` (where :math:`{coh}` denotes the identification or index number for a given cohort).. -The complete hierarchy of elements in the CLM(ED) is therefore now +The complete hierarchy of elements in FATES is therefore now described as follows: .. math:: @@ -274,7 +268,7 @@ common-disturbance-history units is less clear. Several alternative criteria are possible, including Leaf Area Index, total biomass and total stem basal area. -In this implementation of the CLM(ED) we assess the amount of +In this implementation of FATES we assess the amount of above-ground biomass in each PFT/plant diameter bin. Biomass is first grouped into fixed diameter bins for each PFT (:math:`ft`) and a significant difference in any bin will cause patches to remain @@ -318,7 +312,7 @@ co-occupy patch :math:`o`. The state properties of :math:`m` and :math:`n` (litter, seed pools, etc. ) are also averaged in accordance with mass conservation . -Linked Lists: the general code structure of CLM(ED) +Linked Lists: the general code structure of FATES --------------------------------------------------- [4]_ The number of patches in each natural vegetation column and the @@ -337,7 +331,7 @@ potential number of cohorts for every potential patch, which would result in very large amounts of wasted allocated memory, on account of the heterogeneity in the number of cohorts between complex and simple ecosystems (n.b. this does still happen for some variables at restart -timesteps). To resolve this, the cohort structure in the CLM(ED) model +timesteps). To resolve this, the cohort structure in FATES model does not use an array system for internal calculations. Instead it uses a system of *linked lists* where each cohort structure is linked to the cohorts larger than and smaller than itself using a system of pointers. @@ -361,10 +355,10 @@ Using this structure, it is therefore possible to have an unbounded oldest: -Indices used in CLM(ED) +Indices used in FATES ----------------------- -Some of the indices used in the CLM(ED) are similar to those used in the +Some of the indices used in FATES are similar to those used in the standard CLM4.5 model; column (:math:`c`), land unit(\ :math:`l`), grid cell(\ :math:`g`) and soil layer (:math:`j`). On account of the additional complexity of the new representation of plant function, @@ -471,7 +465,7 @@ restarted. The state variables of a cohort are as follows: +-----------------+-----------------+-----------------+-----------------+ Patch State Variables ---------------------- +------------------ A patch, as discuss earlier, is a fraction of the landscape which contains ecosystems with similar structure and disturbance history. A @@ -544,7 +538,7 @@ attributed to each cohort are accumulated throughout each daily cycle and passed into the ED code as the major driver of vegetation dynamics. Initialization of vegetation from bare ground -============================================= +^^^^^^^^^^^^^^^^ [5]_If the model is restarted from a bare ground state (as opposed to a pre-existing vegetation state), the state variables above are @@ -614,8 +608,8 @@ biomass, assigned per PFT [table:init] -Allocation of live biomass to leaves roots and sapwood ------------------------------------------------------- +Allocation of biomass +^^^^^^^^^^^^^^^^^^^^ [6]_Total live biomass :math:`b_{alive}` is the state variable of the model that describes the sum of the three live biomass pools leaf @@ -724,11 +718,9 @@ To calculated the sapwood biomass, we use [table:allom] Canopy Structure and the Perfect Plasticity Approximation -========================================================= +^^^^^^^^^^^^^^^^ - [7]_ - -During initialization and every subsequent daily ED timestep, the canopy +[7]_During initialization and every subsequent daily ED timestep, the canopy structure model is called to determine how the leaf area of the different cohorts is arranged relative to the incoming radiation, which will then be used to drive the radiation and photosynthesis @@ -744,10 +736,7 @@ distribution emerges from competition The standard ED1.0 model makes a simple ’flat disk’ assumption, that the leaf area of each cohort is spread in an homogenous layer at one exact -height across entire the ground area represented by each patch. The -CLM(ED) model has diverged from this representation due to (at least) -two problematic emergent properties that we identified as generating -unrealistic behaviours espetially for large-area patches. +height across entire the ground area represented by each patch. FATES has diverged from this representation due to (at least) two problematic emergent properties that we identified as generating unrealistic behaviours espetially for large-area patches. 1. Over-estimation of light competition . The vertical stacking of cohorts which have all their leaf area at the same nominal height means @@ -785,7 +774,7 @@ canopies to grow into the available gaps (this is of course, an over-simplified but potential useful ecosystem property). The ‘perfect plasticity approximation’ (PPA) implies that the community of trees is subdivided into discrete canopy layers, and by extension, each cohort -represented by the CLM(ED) model is assigned a canopy layer status flag, +represented by FATES model is assigned a canopy layer status flag, :math:`C_L`. In this version, we set the maximum number of canopy layers at 2 for simplicity, although is possible to have a larger number of layers in theory. :math:`C_{L,coh}` = 1 means that all the trees of @@ -860,11 +849,9 @@ fractions of cohorts are demoted or promoted. Further details can be found in the code references in the footnote. Horizontal Canopy Spread ------------------------- - - [8]_ +----------------- -:raw-latex:`\cite{purves2008}` estimated the ratio between canopy and +[8]_:raw-latex:`\cite{purves2008}` estimated the ratio between canopy and stem diameter :math:`c_{p}` as  0.1 m cm\ :math:`^{-1}` for canopy trees in North American forests, but this estimate was made on trees in closed canopies, whose shape is subject to space competition from other @@ -922,12 +909,10 @@ This iterative scheme requires two additional parameters (:math:`i` and However, the model is relatively insensitive to the choice of either :math:`i` or :math:`A_{t}`. -Definition of Leaf Area Profile -------------------------------- - - [9]_ +Definition of Leaf and Stem Area Profile +------------------- -Within each patch, the model defines and tracks cohorts of multiple +[9]_Within each patch, the model defines and tracks cohorts of multiple plant functional types that exist either in the canopy or understorey. Light on the top leaf surface of each cohort in the canopy is the same, and the rate of decay through the canopy is also the same for each PFT. @@ -957,9 +942,6 @@ where :math:`\mathrm{sla}_{ft}` is the specific leaf area in m\ :math:`^{2}` KgC\ :math:`^{-1}` and :math:`b_{leaf}` is in kGC per plant. -Stem Area Index -~~~~~~~~~~~~~~~ - Stem area index (SAI) is ratio of the total area of all woody stems on a plant to the area of ground covered by the plant. During winter in deciduous areas, the extra absorption by woody stems can have a @@ -967,7 +949,7 @@ significant impact on the surface energy budget. However, in previous ‘big leaf’ versions of the CLM, computing the circumstances under which stem area was visible in the absence of leaves was difficult and the algorithm was largely heuristic as a result. Given the multi-layer -canopy introduced for CLM(ED), we can determine the leaves in the higher +canopy introduced for FATES, we can determine the leaves in the higher canopy layers will likely shade stem area in the lower layers when leaves are on, and therefore stem area index can be calculated as a function of woody biomass directly. @@ -1071,7 +1053,7 @@ leaf and stem area profiles, Burial of leaf area by snow -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------- The calculations above all pertain to the total leaf and stem area indices which charecterize the vegetation structure. In addition, the @@ -1170,10 +1152,10 @@ described later. \bigskip Radiation Transfer -================== +^^^^^^^^^^^^^^^^^^^ Fundamental Radiation Transfer Theory -------------------------------------- +------------------ [10]_The first interaction of the land surface with the properties of vegetation concerns the partitioning of energy into that which is @@ -1199,7 +1181,7 @@ is based on the work of :raw-latex:`\cite{norman1979}`. Here we describe the basic theory of the radiation transfer model for the case of a single homogenous canopy, and in the next section we discuss how this is applied to the multi layer multi PFT canopy in the -CLM(ED) implementation. The code considers the fractions of a single +FATES implementation. The code considers the fractions of a single unit of incoming direct and a single unit of incoming diffuse light, that are absorbed at each layer of the canopy for a given solar angle (:math:`\alpha_{s}`, radians). Direct radiation is extinguished through @@ -1386,12 +1368,12 @@ fractions, (required by the photosynthesis calculations), is .. math:: abs_{sun,z} = abs_{dif,z} \cdot f_{sun}+ abs_{dir,z} -Resolution of radiation transfer theory within the CLM(ED) canopy structure ---------------------------------------------------------------------------- +Resolution of radiation transfer theory within the FATES canopy structure +------------------ The radiation transfer theory above, was described with reference to a single canopy of one plant functional type, for the sake of clarity of -explanation. The CLM(ED) model, however, calculates radiative and +explanation. The FATES model, however, calculates radiative and photosynthetic fluxes for a more complex hierarchical structure within each patch/time-since-disturbance class, as described in the leaf area profile section. Firstly, we denote two or more canopy layers (denoted @@ -1436,7 +1418,7 @@ transfer scheme are calculated with indices of :math:`C_L`, :math:`\it{ft}` and :math:`z`. In the following text, we revisit the simplified version of the radiation model described above, and explain how it is modified to account for the more complex canopy structure used -by the CLM(ED). +by FATES. Firstly, the light penetration functions, :math:`k_{dir}` and :math:`g_{dir}` are described as functions of :math:`\it{ft}`, because @@ -1561,18 +1543,16 @@ layer, functional type and pft for testing if necessary. \bigskip Photosynthesis -============== +^^^^^^^^^^^^^^^^^^^^ Fundamental photosynthetic physiology theory --------------------------------------------- +------------------ - [11]_ - -In this section we describe the physiological basis of the -photosynthesis model before describing its application to the CLM(ED) +[11]_In this section we describe the physiological basis of the +photosynthesis model before describing its application to the FATES canopy structure. This description in this section is largely repeated from the Oleson et al. CLM4.5 technical note but included here for -comparison with its implementation in CLM(ED). Photosynthesis in C3 +comparison with its implementation in FATES. Photosynthesis in C3 plants is based on the model of :raw-latex:`\cite{farquhar1980}` as modified by :raw-latex:`\cite{collatz1991}`. Photosynthetic assimilation in C4 plants is based on the model of :raw-latex:`\cite{collatz1992}`. @@ -1675,8 +1655,8 @@ where the term 0.21 represents the ratio of maximum rates of oxygenation to carboxylation, which is virtually constant with temperature :raw-latex:`\cite{farquhar1980}`. -Resolution of the photosynthesis theory within the CLM(ED) canopy structure. ----------------------------------------------------------------------------- +Resolution of the photosynthesis theory within the FATES canopy structure. +------------------ The photosynthesis scheme is modified from the CLM4.5 model to give estimates of photosynthesis, respiration and stomatal conductance for a @@ -1749,7 +1729,7 @@ s\ :math:`^{-1}`) is calculated in a similar fashion, \end{array} \right. Variation in plant physiology with canopy depth -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------ Both :math:`V_{c,max}` and :math:`J_{max}` vary with vertical depth in the canopy on account of the well-documented reduction in canopy @@ -1809,8 +1789,8 @@ canopy. They obtain the following term to predict :math:`K_{n}`, where :math:`V_{cmax}` is again in :math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`. -Water Stress Function -~~~~~~~~~~~~~~~~~~~~~ +Water Stress on gas exchange +------------------ [12]_ The top of canopy leaf photosynthetic capacity, :math:`V_{c,max0}`, is also adjusted for the availability of water to plants as @@ -1848,7 +1828,7 @@ on the calculation of soil matric potential, see the CLM4.5 technical note. Variation of water stress and water uptake within tiles -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ The remaining drivers of the photosynthesis model remain constant (atmospheric CO\ :math:`_2` and O\ :math:`^2` and canopy temperature) @@ -1868,7 +1848,7 @@ parameter also necessitates recalculation of the vertical water extraction profiles. In the original model, the fraction of extraction from each layer (:math:`r_{e,j,patch}`) is the product of a single root distribution, because each patch only has one plant functional type. In -the CLM(ED), we need to calculate a new weighted patch effective rooting +FATES, we need to calculate a new weighted patch effective rooting depth profile :math:`r_{e,j,patch}` as the weighted average of the functional-type level stress functions and their relative contributions to canopy conductance. Thus for each layer :math:`j`, the extraction @@ -1883,7 +1863,7 @@ canopy conductance for plant functional type :math:`ft`, .. math:: G_{s,ft}= \sum_{1}w_{ncoh,ft} {gs_{can,coh} n_{coh} }. Aggregation of assimilated carbon into cohorts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------ The derivation of photosynthetic rates per leaf layer, as above, give us the estimated rate of assimilation for a unit area of leaf at a given @@ -1966,11 +1946,9 @@ timestep to give KgC cohort\ :math:`^{-1}` day\ :math:`^{-1}` \bigskip Plant respiration -================= +^^^^^^^^^^^^^^^^^^ - [13]_ - -Plant respiration per individual :math:`R_{plant,coh}` (KgC individual +[13]_Plant respiration per individual :math:`R_{plant,coh}` (KgC individual :math:`^{-1}` s\ :math:`^{-1}`) is the sum of two terms, growth and maintenance respiration :math:`R_{g,coh}` and :math:`R_{m,coh}` @@ -2104,14 +2082,12 @@ respiration has occurred. \bigskip Stomatal Conductance -==================== +^^^^^^^^^^^^^^^^^^ Fundamental stomatal conductance theory ---------------------------------------- - - [14]_ +------------------ -Stomatal conductance is unchanged in concept from the CLM4.5 approach. +[14]_Stomatal conductance is unchanged in concept from the CLM4.5 approach. Leaf stomatal resistance is calculated from the Ball-Berry conductance model as described by :raw-latex:`\cite{collatz1991}` and implemented in a global climate model by :raw-latex:`\cite{sellers1996}`. The model @@ -2159,8 +2135,8 @@ R\ :math:`_{gas}` is the universal gas constant (J K\ :math:`^{-1}` kmol\ :math:`^{-1}`) and :math:`\theta_{atm}` is the atmospheric potential temperature (K). -Resolution of the stomatal conductance theory in the CLM(ED) canopy structure ------------------------------------------------------------------------------ +Resolution of stomatal conductance theory in the FATES canopy structure +-------------- The stomatal conductance is calculated, as with photosynthesis, for each canopy, PFT and leaf layer. The CLM code requires a single canopy @@ -2193,12 +2169,10 @@ cohort. +------------------+--------------------------+-------+------------+ -Allocation -========== - - [15]_ +Allocation and Growth +^^^^^^^^^^^^^^^^ -Total assimilation carbon enters the ED model each day as a +[15]_Total assimilation carbon enters the ED model each day as a cohort-specific Net Primary Productivity :math:`\mathit{NPP}_{coh}`, which is calculated as @@ -2214,7 +2188,7 @@ individual\ :math:`^{-1}` year\ :math:`^{-1}` and ultimately integrated using a timesteps of 1/365 years for each day. Tissue maintenance demand -------------------------- +--------------- We calculate a ‘tissue maintenance’ flux. The magnitude of this flux is such that the quantity of biomass in each pool will remain constant, @@ -2243,7 +2217,7 @@ phenology section. The total quantity of maintenance demand .. math:: t_{md,coh} = l_{md,coh} + r_{md,coh} Allocation to storage and turnover ----------------------------------- +----------------- The model must now determine whether the NPP input is sufficient to meet the maintenance demand and keep tissue levels constant. To determine @@ -2324,7 +2298,7 @@ and leaf biomass, ameliorated by the leaf trimming fraction (see :math:`\rho_{ft}` is the wood density, in g cm\ :math:`^{3}`. Allocation to Seeds -~~~~~~~~~~~~~~~~~~~ +--------------- The fraction remaining for growth (expansion of live and structural tissues) :math:`f_{growth}` is 1 minus that allocated to seeds. @@ -2350,7 +2324,7 @@ KgC individual :math:`^{-1}` y\ :math:`^{-1}`) is thus .. math:: p_{seed,coh} = C_{growth}\cdot f_{seed,coh} Allocation to growing pools -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------- [16]_ The carbon is then partitioned into carbon available to grow the :math:`b_{alive}` and :math:`b_{struc}` pools. A fraction :math:`v_{a}` @@ -2434,7 +2408,7 @@ structural biomass pools are maintained in this algorithm, which diverges from the methodology currently deployed in the CLM4.5. Integration of allocated fluxes -------------------------------- +---------------- All of the flux calculations generate differential of the biomass state variables against time (in years). To integrate these differential rates @@ -2503,11 +2477,9 @@ In this case, :math:`\delta t` is set to be one day \bigskip Control of Leaf Area Index -========================== +^^^^^^^^^^^^^^ - [17]_ - -The leaf area :math:`A_{leaf}` (m:math:`^{-2}`) of each cohort is +[17]_The leaf area :math:`A_{leaf}` (m:math:`^{-2}`) of each cohort is calculated from leaf biomass :math:`b_{leaf,coh}` (kgC individual\ :math:`^{-1}`) and specific leaf area (SLA, m\ :math:`^2` kg C\ :math:`^{-1}`) @@ -2598,16 +2570,16 @@ the greatly reduced maintenance and turnover requirements. \bigskip Phenology -========= +^^^^^^^^^^^^^^^^^^^^ Cold Deciduous Phenology ------------------------- +------------------ Cold Leaf-out timing ~~~~~~~~~~~~~~~~~~~~ [18]_. The phenology model of :raw-latex:`\cite{botta2000}` is used in -CLM(ED) to determine the leaf-on timing. The Botta et al. model was +FATES to determine the leaf-on timing. The Botta et al. model was verified against satellite data and is one of the only globally verified and published models of leaf-out phenology. This model differs from the phenology model in the CLM4.5. The model simulates leaf-on date as a @@ -2685,21 +2657,19 @@ constrain growing degree day accumulation to the second half of the year (Jult onwards in the Northern hemisphere, or Jan-June in the Southern) and only allow GDD accumulation while the leaves are off. -Drought-deciduous Phenology ---------------------------- +Drought-deciduous Phenology: TBD +------------------ In the current version of the model, a drought deciduous algorithm -exists, but is not yet operational, due to issue detected in the exsting +exists, but is not yet operational, due to issue detected in the existing CN and soil moisture modules, which also affect the behaviour of the native ED drought deciduous model. This is a priority to address before the science tag is released. Carbon Dynamics of deciduous plants ------------------------------------ - - [19]_ +------------------ -In the present version, leaf expansion and senescence happen over the +[19]_In the present version, leaf expansion and senescence happen over the course of a single day. This is clearly not an empirically robust representation of leaf behaviour, whereby leaf expansion occurs over a period of 10-14 days, and senescence over a similar period. This will be @@ -2775,18 +2745,15 @@ for this carbon accounting scheme. \bigskip Seed Dynamics and Recruitment -============================= +^^^^^^^^^^^^^^^^^^ - [20]_ -The production of seeds and their subsequent germination is a process -that must be captured explicitly or implicitly in vegetation models. The -CLM(ED) contains a seed bank model designed to allow the dynamics of +[20]_The production of seeds and their subsequent germination is a process +that must be captured explicitly or implicitly in vegetation models. FATES contains a seed bank model designed to allow the dynamics of seed production and germination to be simulated independently. In the ED1.0 model, seed recruitment occurs in the same timestep as allocation to seeds, which prohibits the survival of a viable seed bank through a -period of disturbance or low productivity (winter, drought). In the -CLM(ED) model, a plant functional type specific seed bank is tracked in +period of disturbance or low productivity (winter, drought). In FATES, a plant functional type specific seed bank is tracked in each patch (:math:`Seeds_{patch}` KgC m\ :math:`^{-2}`), whose rate of change (KgC m\ :math:`^{-2}` y\ :math:`^{-1}`) is the balance of inputs, germination and decay: @@ -2858,12 +2825,12 @@ of one plant functional type over the seed pool. \bigskip -Fragmenting Litter Pool Production and Turnover -=============================================== +Litter Production and Fragmentation +^^^^^^^^^^^^^^ | The original CLM4.5 model contains streams of carbon pertaining to different chemical properties of litter (lignin, cellulose and labile - streams, specifically). In the CLM(ED) model, the fire simulation + streams, specifically). In FATES model, the fire simulation scheme in the SPITFIRE model requires that the model tracks the pools of litter pools that differ with respect to their propensity to burn (surface area-volume ratio, bulk density etc.). Therefore, this model @@ -2873,7 +2840,7 @@ Fragmenting Litter Pool Production and Turnover respiration. In this way, we can both maintain above-ground pools that affect the rate of burning, and the lag between tree mortality and availability of woody material for decomposition. -| The CLM(ED) recognizes four classes of litter. Above- and below-ground +| FATES recognizes four classes of litter. Above- and below-ground coarse woody debris (:math:`CWD_{AG}`, :math:`CWD_{BG}`) and leaf litter (:math:`l_{leaf}` and fine root litter :math:`l_{root}`). All pools are represented per patch, and with units of kGC @@ -2933,9 +2900,7 @@ assigned to each (:math:`f_{lsc}` and :math:`f_{ag}`) Litter Outputs -------------- - [22]_ - -The fragmenting litter pool is available for burning but not for +[22]_The fragmenting litter pool is available for burning but not for respiration or decomposition. Fragmentation rates are calculated according to a maximum fragmentation rate (:math:`\alpha_{cwd,lsc}` or :math:`\alpha_{litter}`) which is ameliorated by a temperature and water @@ -2961,11 +2926,9 @@ sensitivity analyses of the model outputs. .. math:: l_{root,out,ft} = l_{root,ft}.\alpha_{root,ft}.S_{tw} Flux into decompsition cascade ------------------------------- - - [23]_ +-------------- -Upon fragmentation and release from the litter pool, carbon is +[23]_Upon fragmentation and release from the litter pool, carbon is transferred into the labile, lignin and cellulose decomposition pools. These pools are vertically resolved in the biogeochemistry model. The movement of carbon into each vertical layer is obviously different for @@ -3060,7 +3023,7 @@ layer :math:`z`, derived from the CLM(BGC) model. \bigskip Plant Mortality -=============== +^^^^^^^^^^^^^^^^ Total plant mortality per cohort :math:`M_{t,coh}`, (fraction year\ :math:`^{-1}`) is simulated as the sum of four additive terms, @@ -3127,12 +3090,10 @@ fire modelling section. \bigskip -Fire -==== +Fire (SPITFIRE) +^^^^^^^^^^^^^^^^^ - [24]_ - -The influence of fire on vegetation is estimated using the SPITFIRE +[24]_The influence of fire on vegetation is estimated using the SPITFIRE model, which has been modified for use in ED following it’s original implementation in the LPJ-SPITFIRE model (:raw-latex:`\parencite{thonicke2010,pfeiffer2013}`. This model as @@ -3156,7 +3117,7 @@ open and closed forests can be represented effectively (we omit the ‘patch’ subscript throughout for simplicity). Properties of fuel load ------------------------ +--------------- Many fire processes are impacted by the properties of the litter pool in the SPITFIRE model. There are one live (live grasses) and five dead fuel @@ -3190,23 +3151,8 @@ as follows. \bigskip -Fuel load -~~~~~~~~~ - -Total fuel load :math:`F_{tot,patch}` for a given patch is the sum of -the above ground coarse woody debris and the leaf litter, plus the alive -grass leaf biomass :math:`b_{l,grass}` multiplied by the non-mineral -fraction (1-:math:`M_{f}`). - -.. math:: F_{tot,patch}=\left(\sum_{fc=1}^{fc=5} CWD_{AG,fc}+l_{litter}+b_{l,grass}\right)(1-M_{f}) - -Many of the model behaviours are affected by the patch-level weighted -average properties of the fuel load. Typically, these are calculated in -the absence of 1000-h fuels because these do not contribute greatly to -fire spread properties. - Nesterov Index -~~~~~~~~~~~~~~ +--------------- Dead fuel moisture (:math:`\emph{moist}_{df,fc}`), and several other properties of fire behaviour, are a function of the ‘Nesterov Index’ @@ -3226,6 +3172,23 @@ where :math:`T_{d}` is the daily mean temperature in :math:`^{o}`\ C and where :math:`RH` is the relative humidity (%). + +Fuel properties +--------------- + +Total fuel load :math:`F_{tot,patch}` for a given patch is the sum of +the above ground coarse woody debris and the leaf litter, plus the alive +grass leaf biomass :math:`b_{l,grass}` multiplied by the non-mineral +fraction (1-:math:`M_{f}`). + +.. math:: F_{tot,patch}=\left(\sum_{fc=1}^{fc=5} CWD_{AG,fc}+l_{litter}+b_{l,grass}\right)(1-M_{f}) + +Many of the model behaviours are affected by the patch-level weighted +average properties of the fuel load. Typically, these are calculated in +the absence of 1000-h fuels because these do not contribute greatly to +fire spread properties. + + Dead Fuel Moisture Content ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3301,7 +3264,7 @@ fuels). .. math:: F_{\sigma}=\sum_{fc=1}^{fc=4} \frac{F_{fc}}{F_{tot}}\sigma_{fuel,fc}+\frac{b_{l,grass}}{F_{tot}}\sigma_{fuel,grass} Forward rate of spread ----------------------- +----------------- For each patch and each day, we calculate the rate of forward spread of the fire *ros*\ :math:`_{f}` (nominally in the direction of the wind). @@ -3414,7 +3377,7 @@ Fire Behaviour Predictions Systems) .. math:: D_{f}=\textrm{min}\Big(F_{dur,max},\frac{F_{dur,max}}{1+F_{dur,max}e^{-11.06fdi}}\Big) Fire Danger Index ------------------ +-------------- Fire danger index (*fdi*) is a representation of the effect of meteorological conditions on the likelihood of a fire. It is calculated @@ -3459,7 +3422,7 @@ The total area burned (:math:`A_{burn}` in m\ :math:`^{2}`) is therefore where :math:`n_{f}` is the number of fires. Crown Damage ------------- +------------- :math:`c_{k}` is the fraction of the crown which is consumed by the fire. This is calculated from scorch height :math:`H_{s}`, tree height @@ -3485,7 +3448,7 @@ where :math:`f_{biomass,ft}` is the fraction of the above-ground biomass in each plant functional type. Cambial Damage and Kill ------------------------ +------------- The cambial kill is a function of the fuel consumed :math:`f_{c,tot}`, the bark thickness :math:`t_{b}`, and :math:`\tau_{l}`, the duration of From 1b44cdbee18adcc88bb40d3050bdf4443eaa2da5 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Tue, 12 Dec 2017 14:47:06 -0700 Subject: [PATCH 117/255] fixed the references for the FATES tech note --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 290 ++++++++---------- .../References/CLM50_Tech_Note_References.rst | 131 ++++++++ 2 files changed, 263 insertions(+), 158 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index c6f0558b6b..3a0bfcdbb2 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -8,40 +8,42 @@ What has changed - Deprecation of the dynamic global vegetation model (DGVM): The CLM5.0 model contains the legancy 'CNDV' code, which runs the CLM4(CN) model in combination with the LPJ-derived dynamics vegetation model introduced in CLM3. While this capacity has not technically been removed from the model, the DGVM has not been tested in the development of CLM5 and is no longer scientifically supported. -- Introduction of FATES: The Functionally Assembled Terrestrial Ecosystem Simulator (FATES) is the actively developed DGVM for the CLM5. +- Introduction of FATES: The Functionally Assembled Terrestrial Ecosystem Simulator (FATES) is the actively developed DGVM for the CLM5. See +.. _rst_FATES: + Technical Documentation for FATES =================================== +FATES is the "Functionally Assembled Terrestrial Ecosystem Simulator". It is an external module which can run within a given "Host Land Model" (HLM). Currently (November 2017) implementations are supported in both the Community Land Model(CLM) and in the land model of the E3SM Dept. of Energy Earth System Model. -Introduction -^^^^^^^^^^^^^^^^^^^^ +FATES was derived from the CLM Ecosystem Demography model (CLM(ED)), which was documented in: - This document is a technical appendix to - Fisher RA, Muszala S, Verteinstein M, Lawrence P, Xu C, McDowell NG, +Fisher RA, Muszala S, Verteinstein M, Lawrence P, Xu C, McDowell NG, Knox RG, Koven C, Holm J, Rogers BM, Lawrence D. Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes. Geoscientific Model Development Discussions. 2015 Apr 1;8(4). - https://pdfs.semanticscholar.org/396c/b9f172cb681421ed78325a2237bfb428eece.pdf - - -FATES is presented here as an option within the structure of -the Community Land Model (CLM). Ecosystem Demography (‘ED’), is a -concept derived from the work of :raw-latex:`\cite{mc_2001}` and is a -cohort model of vegetation competition and co-existence, allowing a -representation of the biosphere which accounts for the division of the -land surface into successional stages, and the competition for light -between height structured cohorts of representative trees of various -plant functional types. This implementation of the Ecosystem Demography -concept links the surface flux and canopy physiology concepts in the CLM + +and this technical note was first published as an appendix to that paper. + +https://pdfs.semanticscholar.org/396c/b9f172cb681421ed78325a2237bfb428eece.pdf + +Introduction +^^^^^^^^^^^^^^^^^^^ + +The Ecosystem Demography ('ED'), concept within FATES is derived from the work of :ref:`Moorcroft et al. (2001)` + +and is a cohort model of vegetation competition and co-existence, allowing a representation of the biosphere which accounts for the division of the land surface into successional stages, and for competition for light between height structured cohorts of representative trees of various plant functional types. + +The implementation of the Ecosystem Demography +concept within FATES links the surface flux and canopy physiology concepts in the CLM/E3SM with numerous additional developments necessary to accommodate the new model also documented here. These include a version of the SPITFIRE -(Spread and InTensity of Fire) model of -:raw-latex:`\parencite{thonicke2010}`, and an adoption of the concept of -‘perfect plasticity’ approach of -:raw-latex:`\parencite{purves2008,lichstein2011,weng2014}` in accounting +(Spread and InTensity of Fire) model of :ref:`Thonicke et al. (2010)`, and an adoption of the concept of +`Perfect Plasticity Approximation` approach of +:ref:`Purves et al. 2008`, :ref:`Lichstein et al. 2011` and :ref:`Weng et al. 2014`, in accounting for the spatial arrangement of crowns. Novel algorithms accounting for the fragmentation of coarse woody debris into chemical litter streams, for the physiological optimisation of canopy thickness, for the @@ -50,40 +52,28 @@ radiation transfer, for drought-deciduous and cold-deciduous phenology, for carbon storage allocation, and for tree mortality under carbon stress, are also included and presented here. -This Document UPDATE ----------------- - -This document describes the implementation of the Ecosystem Demography -concept within the Community Land Model. The material covered describes how -the Ecosystem Demography code is organized, how it interacts with the -pre-existing CLM routines, and the new aspects of plant physiology and -vegetation dynamics that are introduced further to those already -existing within the model. Numerous other implementations of the -Ecosystem Demography concept are in existence, in particular the ED2 -model, which is a fully operational land surface scheme -:raw-latex:`\parencite{medvigy2009}` which contains both the basic ED -concept and an array of physiological and ecological innovations -surrounding the basic concept. Therefore, to avoid confusion between the -concept of ‘Ecosystem Demography’ and the implementation of this concept -in different models, we refer our model as the ‘FATES’ (the functionally Assembled Terrestrial Ecosystem Simulator) throughout. +Numerous other implementations of the +Ecosystem Demography concept exist (See Fisher et al. 2017 for a review of these) Therefore, to avoid confusion between the +concept of 'Ecosystem Demography' and the implementation of this concept +in different models, the CLM(ED) implementation described by Fisher et al. (2015) will hereafter be called 'FATES' (the Functionally Assembled Terrestrial Ecosystem Simulator). The representation of ecosystem heterogeneity in FATES ^^^^^^^^^^^^^^^ -The land surface of the Earth is heterogeneous for many reasons, driven +The terrestrial surface of the Earth is heterogeneous for many reasons, driven by variations in climate, edaphic history, ecological variability, geological forcing and human interventions. Land surface models represent this variability first by introducing a grid structure to the land surface, allowing different atmospheric forcings to operate in each -grid cell, and subsequently by representing ‘sub-grid’ variability in +grid cell, and subsequently by representing 'sub-grid' variability in the surface properties. In the CLM, the land surface is divided into -numerous ‘landunits’ corresponding to the underlying condition of the -surface (e.g. soils, ice, lakes, bare ground) and then ‘columns’ +numerous 'landunits' corresponding to the underlying condition of the +surface (e.g. soils, ice, lakes, bare ground) and then 'columns' referring to elements of the surface that share below ground resources -(water & nutrients). Within the ‘soil’ landunit, for example, there are +(water & nutrients). Within the soil landunit, for example, there are separate columns for crops, and for natural vegetation, as these are assumed to use separate resource pools. The FATES model at present -only operates on the naturally vegetated column. The ‘soil’ column is +only operates on the naturally vegetated column. The soil column is sub-divided into numerous tiles, that correspond to statistical fractions of the potentially vegetated land area. In the CLM 4.5 (and all previous versions of the model), sub-grid tiling operates on the @@ -97,21 +87,21 @@ The introduction of the Ecosystem Demography concept introduces significant alterations to the representation of the land surface in the CLM. In FATES, the tiling structure represents the disturbance history of the ecosystem. Thus, some fraction of the land surface is -characterized as ‘recently disturbed’, some fraction has escaped +characterized as 'recently disturbed', some fraction has escaped disturbance for a long time, and other areas will have intermediate disturbances. Thus the ED concept essentially discretizes the trajectory -of succession from disturbed ground to ‘mature’ ecosystems. Within the -ED code, each ‘disturbance history class’ is referred to as a ‘patch’. -The word ‘patch’ has many possible interpretations, so it is important +of succession from disturbed ground to 'mature' ecosystems. Within +FATES, each "disturbance history class" is referred to as a ‘patch’. +The word "patch" has many possible interpretations, so it is important to note that: **there is no spatial location associated with the concept -of a ‘patch’. It refers to a fraction of the potential vegetated area +of a 'patch' . It refers to a fraction of the potential vegetated area consisting of all parts of the ecosystem with similar disturbance history.** -The ‘patch’ organizational structure in CLM thus replaces the previous -‘PFT’ structure in the organization heirarchy. The original hierarchical +The 'patch' organizational structure in CLM thus replaces the previous +'PFT' structure in the organization heirarchy. The original hierarchical land surface organizational structure of CLM as described in -:raw-latex:`\cite{oleson2013}` may be depicted as: +:ref:`Oleson et al. 2013` may be depicted as: .. math:: @@ -153,11 +143,11 @@ and the new structure is altered to the following: \mathbf{landunit} & \\ \end{array}\right. -Thus, each gridcell becomes a matrix of ‘patches’ that are -conceptualized by their ‘age since disturbance’ in years. This is the +Thus, each gridcell becomes a matrix of 'patches' that are +conceptualized by their 'age since disturbance' in years. This is the equivalent of grouping together all those areas of a gridcell that are -‘canopy gaps’, into a single entity, and all those areas that are -‘mature forest’ into a single entity. +'canopy gaps', into a single entity, and all those areas that are +'mature forest' into a single entity. Cohortized representation of tree populations --------------------------------------------- @@ -167,11 +157,11 @@ in reality contain numerous individual plants which vary in their physiological attributes, in height and in spatial position. One way of addressing this heterogeneity is to simulate a forest of specific individuals, and to monitor their behavior through time. This is the -approach taken by ‘gap’ and individual-based -:raw-latex:`\parencite{smith2001,sato2007,uriarte2009,fyllas2014}`. The +approach taken by "gap" and individual-based models +(:ref:`Smith et al. 2001`, :ref:`Sato et al. 2007`, :ref:`Uriarte et al. 2009`, :ref:`Fyllas et al. 2014 `). The depiction of individuals typically implies that the outcome of the model is stochastic. This is because we lack the necessary detailed knowledge -to simulate the individual plant’s fates. Thus gap models imply both +to simulate the individual plant's fates. Thus gap models imply both stochastic locations and mortality of plants. Thus, (with a genuinely random seed) each model outcome is different, and an ensemble of model runs is required to generate an average representative solution. Because @@ -180,19 +170,18 @@ deviations from the mean trajectory for a small plot (a typical simulated plot size is 30m x 30 m) the number of runs required to minimize these deviations is large and computationally expensive. For this reason, models that resolve individual trees typically use a -physiological timestep of one day or longer (e.g. -:raw-latex:`\cite{smith2001,xiaodong2005,sato2007}` +physiological timestep of one day or longer (e.g. :ref:`Smith et al. 2001`, :ref:`Xiaidong et al. 2005 `, :ref:`Sato et al. 2007` The approach introduced by the Ecosystem Demography model -:raw-latex:`\parencite{mc_2001}` is to group the hypothetical population -of plants into ‘cohorts’. In the notional ecosystem, after the +:ref:`Moorcroft et al. 2001` is to group the hypothetical population +of plants into "cohorts". In the notional ecosystem, after the land-surface is divided into common-disturbance-history patches, the population in each patch is divided first into plant functional types (the standard approach to representing plant diversity in large scale vegetation models), and then each plant type is represented as numerous height classes. Importantly, **for each PFT/height class bin, we model *one* representative individual plant, which tracks the average -properties of this ‘cohort’ of individual plants.** Thus, each +properties of this `cohort` of individual plants.** Thus, each common-disturbance-history patch is typically occupied by a set of cohorts of different plant functional types, and different height classes within those plant functional types. Each cohort is associated @@ -235,11 +224,11 @@ disturbance processes. If the new patches and cohorts established at *every* timestep were tracked by the model structure, the computational load would of course be extremely high (and thus equivalent to an individual-based approach). A signature feature of the ED model is the -system by which ‘functionally equivalent’ patches and cohorts are fused +system by which `functionally equivalent` patches and cohorts are fused into single model entities to save memory and computational time. [1]_ This functionality requires that criteria are established for the -meaning of `functional equivalence’, which are by necessity slightly +meaning of `functional equivalence`, which are by necessity slightly subjective, as they represent ways of abstracting reality into a more tractable mathematical representation. As an example of this, for height-structured cohorts, we calculate the relativized differences in @@ -343,16 +332,7 @@ Instead of iterating along a vector indexed by :math:`coh`, the code structures typically begin at the tallest cohort in a given patch, and iterate until a null pointer is encountered. -Using this structure, it is therefore possible to have an unbounded - upper limit on cohort number, and also to easily alter the ordering of - cohorts if, for example, a cohort of one functional type begins to - grow faster than a competitor of another functional type, and the - cohort list can easily be re-ordered by altering the pointer - structure. Each cohort has `pointers` indicating to which patch and - gridcell it belongs. The patch system is analogous to the cohort - system, except that patches are ordered in terms of their relative age, with - pointers to older and younger patches where cp\ :math:`_1` is the - oldest: +Using this structure, it is therefore possible to have an unbounded upper limit on cohort number, and also to easily alter the ordering of cohorts if, for example, a cohort of one functional type begins to grow faster than a competitor of another functional type, and the cohort list can easily be re-ordered by altering the pointer structure. Each cohort has `pointers` indicating to which patch and gridcell it belongs. The patch system is analogous to the cohort system, except that patches are ordered in terms of their relative age, with pointers to older and younger patches where cp\ :math:`_1` is the oldest: Indices used in FATES @@ -518,9 +498,6 @@ can be restarted, are as follows | Index | patch}}` | | | | +-------------+-------------+-------------+-------------+-------------+ -.. raw:: latex - - \bigskip Model Structure --------------- @@ -573,7 +550,7 @@ function of wood density, :math:`\rho`, g cm\ :math:`^{-3}`) .. math:: b_{struc,coh} =c_{str}h_{coh}^{e_{str,hite}} dbh_{coh}^{e_{str,dbh}} \rho_{ft}^{e_{str,dens}} taken from the original ED1.0 allometry -:raw-latex:`\parencite{mc_2001}` (values of the allometric constants in +:ref:`Moorcroft et al. 2001` (values of the allometric constants in Table `[table:allom] <#table:allom>`__. The maximum amount of leaf biomass associated with this diameter of tree is calculated according to the following allometry @@ -732,9 +709,9 @@ performance in ED-like cohort based models, since they determine how light resources are partitioned between competing plants of varying heights, which has a very significant impact on how vegetation distribution emerges from competition -:raw-latex:`\parencite{fisher2010}`. +:ref:`Fisher et al. 2010`. -The standard ED1.0 model makes a simple ’flat disk’ assumption, that the +The standard ED1.0 model makes a simple `flat disk' assumption, that the leaf area of each cohort is spread in an homogenous layer at one exact height across entire the ground area represented by each patch. FATES has diverged from this representation due to (at least) two problematic emergent properties that we identified as generating unrealistic behaviours espetially for large-area patches. @@ -748,7 +725,7 @@ model artificially exaggerates the process of light competition. In reality, trees do not compete for light until their canopies begin to overlap and canopy closure is approached. -2. Unrealistic over-crowding. The ‘flat-disk’ assumption has no +2. Unrealistic over-crowding. The 'flat-disk' assumption has no consideration of the spatial extent of tree crowns. Therefore it has no control on the packing density of plants in the model. Given a mismatch between production and mortality, entirely unrealistic tree densities @@ -758,7 +735,7 @@ mortality rates. To account for the filling of space in three dimensions using the one-dimensional representation of the canopy employed by CLM, we implement a new scheme derived from that of -:raw-latex:`\cite{purves2008}`. Their argument follows the development +:ref:`Purves et al. 2008`. Their argument follows the development of an individual-based variant of the SORTIE model, called SHELL, which allows the location of individual plant crowns to be highly flexible in space. Ultimately, the solutions of this model possess an emergent @@ -801,7 +778,7 @@ where :math:`A_{crown}` is the crown area of a single tree canopy (m:math:`^{-2}`) and :math:`S_{c,patch,Cl}` is the ‘canopy spread’ parameter (m cm^-1) of this canopy layer, which is assigned as a function of canopy space filling, discussed below. In contrast to -:raw-latex:`\cite{purves2008}` , we use an exponent, identical to that +:ref:`Purves et al. 2008` , we use an exponent, identical to that for leaf biomass, of 1.56, not 2.0, such that tree leaf area index does not change as a function of diameter. @@ -815,11 +792,11 @@ the area of all crowns :math:`A_{canopy}` (m:math:`^{-2}`) is larger than the total ground area of a patch (:math:`A_{patch}`), then some fraction of each cohort is demoted to the understorey. -Under these circumstances, the ‘extra’ crown area :math:`A_{loss}` +Under these circumstances, the `extra` crown area :math:`A_{loss}` (i.e., :math:`A_{canopy}` - :math:`A_p`) is moved into the understorey. For each cohort already in the canopy, we determine a fraction of trees that are moved from the canopy (:math:`L_c`) to the understorey. -:math:`L_c` is calculated as :raw-latex:`\cite{fisher2010}` +:math:`L_c` is calculated as :ref:`Fisher et al. 2010` .. math:: L_{c}= \frac{A_{loss,patch} w_{coh}}{\sum_{coh=1}^{nc,patch}{w_{coh}}} , @@ -851,8 +828,8 @@ found in the code references in the footnote. Horizontal Canopy Spread ----------------- -[8]_:raw-latex:`\cite{purves2008}` estimated the ratio between canopy and -stem diameter :math:`c_{p}` as  0.1 m cm\ :math:`^{-1}` for canopy trees +[8]_:ref:`Purves et al. 2008` estimated the ratio between canopy and +stem diameter :math:`c_{p}` as 0.1 m cm\ :math:`^{-1}` for canopy trees in North American forests, but this estimate was made on trees in closed canopies, whose shape is subject to space competition from other individuals. Sapling trees have no constraints in their horizontal @@ -946,7 +923,7 @@ Stem area index (SAI) is ratio of the total area of all woody stems on a plant to the area of ground covered by the plant. During winter in deciduous areas, the extra absorption by woody stems can have a significant impact on the surface energy budget. However, in previous -‘big leaf’ versions of the CLM, computing the circumstances under which +`big leaf` versions of the CLM, computing the circumstances under which stem area was visible in the absence of leaves was difficult and the algorithm was largely heuristic as a result. Given the multi-layer canopy introduced for FATES, we can determine the leaves in the higher @@ -958,8 +935,8 @@ Literature on stem area index is particularly poor, as it’s estimation is complex and not particularly amenable to the use of, for example, assumptions of random distribution in space that are typically used to calculate leaf area from light interception. -:raw-latex:`\cite{kucharik1998}` estimated that SAI visible from an -LAI2000 sensor was around 0.5 m^2 m^-2. :raw-latex:`\cite{low2001}` +:ref:`Kucharik et al. 1998` estimated that SAI visible from an +LAI2000 sensor was around 0.5 m^2 m^-2. :ref:`Low et al. 2001` estimate that the wood area index for Ponderosa Pine forest is 0.27-0.33. The existing CLM(CN) algorithm sets the minimum SAI at 0.25 to match MODIS observations, but then allows SAI to rise as a function @@ -1147,9 +1124,6 @@ described later. | | biomass | | | | +-------------+-------------+-------------+-------------+-------------+ -.. raw:: latex - - \bigskip Radiation Transfer ^^^^^^^^^^^^^^^^^^^ @@ -1161,8 +1135,8 @@ Fundamental Radiation Transfer Theory vegetation concerns the partitioning of energy into that which is absorbed by vegetation, reflected back into the atmosphere, and absorbed by the ground surface. Older versions of the CLM have utilized a -‘two-stream’ approximation -:raw-latex:`\parencite{sellers1985,sellers1996}` that provided an +"two-stream" approximation +:ref:`Sellers 1985`, :ref:`Sellers et al. 1986` that provided an empirical solution for the radiation partitioning of a multi-layer canopy for two streams, of diffuse and direct light. However, implementation of the Ecosystem Demography model requires a) the @@ -1176,7 +1150,7 @@ thus implemented a one-dimensional scheme that traces the absorption, transmittance and reflectance of each canopy layer and the soil, iterating the upwards and downwards passes of radiation through the canopy until a pre-defined accuracy tolerance is reached. This approach -is based on the work of :raw-latex:`\cite{norman1979}`. +is based on the work of :ref:`Norman 1979`. Here we describe the basic theory of the radiation transfer model for the case of a single homogenous canopy, and in the next section we @@ -1291,7 +1265,7 @@ calculated sequentially, starting this time at the soil surface layer where :math:`alb_s` is the soil albedo characteristic. The upwards reflected fraction :math:`r_z` for each leaf layer, moving upwards, is -then :raw-latex:`\cite{norman1979}` +then :ref:`Norman 1979` .. math:: r_z = \frac{r_{z+1} \times \mathit{tran}_{dif} ^{2} }{ (1 - r_{z+1} \mathit{refl_{dif}}) + \mathit{refl_{dif}}}. @@ -1380,10 +1354,10 @@ profile section. Firstly, we denote two or more canopy layers (denoted :math:`C_l`). The concept of a ‘canopy layer’ refers to the idea that plants are organized into discrete over and under-stories, as predicted by the Perfect Plasticity Approximation -:raw-latex:`\parencite{purves2008,fisher2010}`. Within each canopy layer +(:ref:`Purves et al. 2008`, :ref:`Fisher et al. 2010`). Within each canopy layer there potentially exist multiple cohorts of different plant functional types and heights. Within each canopy layer, :math:`C_l`, and functional -type, :math:`ft`, the model resolves numerous leaf layers ‘:math:`z`’, +type, :math:`ft`, the model resolves numerous leaf layers :math:`z`, and, for some processes, notably photosynthesis, each leaf layer is split into a fraction of sun and shade leaves, :math:`f_{sun}` and :math:`f_{sha}`, respectively. @@ -1392,12 +1366,12 @@ The radiation scheme described in Section is solved explicitly for this structure, for both the visible and near-infrared wavebands, according to the following assumptions. -- A ‘canopy layer’ (:math:`C_{L}`) refers to either the over or understorey +- A *canopy layer* (:math:`C_{L}`) refers to either the over or understorey -- A ‘leaf layer’ (:math:`z`) refers to the discretization of the LAI +- A *leaf layer* (:math:`z`) refers to the discretization of the LAI within the canopy of a given plant functional type. -- All PFT’s in the same canopy layer have the same solar radiation +- All PFTs in the same canopy layer have the same solar radiation incident on the top layer of the canopy - Light is transmitted through the canopy of each plant functional type independently @@ -1411,7 +1385,7 @@ to the following assumptions. radiation is directly transferred to the soil surface. - All these calculations pertain to a single patch, so we omit the - ‘patch’ subscript for simplicity in the following discussion. + `patch` subscript for simplicity in the following discussion. Within this framework, the majority of the terms in the radiative transfer scheme are calculated with indices of :math:`C_L`, @@ -1553,9 +1527,9 @@ photosynthesis model before describing its application to the FATES canopy structure. This description in this section is largely repeated from the Oleson et al. CLM4.5 technical note but included here for comparison with its implementation in FATES. Photosynthesis in C3 -plants is based on the model of :raw-latex:`\cite{farquhar1980}` as -modified by :raw-latex:`\cite{collatz1991}`. Photosynthetic assimilation -in C4 plants is based on the model of :raw-latex:`\cite{collatz1992}`. +plants is based on the model of :ref:`Farquhar 1980` as +modified by :ref:`Collatz et al. 1991`. Photosynthetic assimilation +in C4 plants is based on the model of :ref:`Collatz et al. 1991`. In both models, leaf photosynthesis, :math:`\textrm{gpp}` (:math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`) is calculated as the minimum of three potentially limiting fluxes, @@ -1582,7 +1556,7 @@ partial pressure (Pa). :math:`K_{c}` and :math:`K_{o}` are the Michaelis-Menten constants (Pa) for CO\ :math:`_{2}` and O\ :math:`_{2}`. These vary with vegetation temperature :math:`T_v` (:math:`^{o}`\ C) according to an Arrhenious function described in -:raw-latex:`\cite{oleson2013}`. :math:`V_{c,max}` is the leaf layer +:ref:`Oleson et al. 2013`. :math:`V_{c,max}` is the leaf layer photosynthetic capacity (:math:`\mu` mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`). @@ -1653,7 +1627,7 @@ CO\ :math:`_{2}` compensation point :math:`\Gamma_{*}` (Pa) is where the term 0.21 represents the ratio of maximum rates of oxygenation to carboxylation, which is virtually constant with temperature -:raw-latex:`\cite{farquhar1980}`. +:ref:`Farquhar, 1980`. Resolution of the photosynthesis theory within the FATES canopy structure. ------------------ @@ -1733,7 +1707,7 @@ Variation in plant physiology with canopy depth Both :math:`V_{c,max}` and :math:`J_{max}` vary with vertical depth in the canopy on account of the well-documented reduction in canopy -nitrogen through the leaf profile, see :raw-latex:`\cite{bonan2012}` for +nitrogen through the leaf profile, see :ref:`Bonan et al. 2012` for details). Thus, both :math:`V_{c,max}` and :math:`J_{max}` are indexed by by :math:`C_l`, :math:`ft` and :math:`z` according to the nitrogen decay coefficient :math:`K_n` and the amount of vegetation area shading @@ -1779,7 +1753,7 @@ where :math:`V_{canopy}` is calculated as :math:`K_{n}` is the coefficient of nitrogen decay with canopy depth. The value of this parameter is taken from the work of -:raw-latex:`\cite{lloyd2010}` who determined, from 204 vertical profiles +:ref:`Lloyd et al. 2010` who determined, from 204 vertical profiles of leaf traits, that the decay rate of N through canopies of tropical rainforests was a function of the :math:`V_{cmax}` at the top of the canopy. They obtain the following term to predict :math:`K_{n}`, @@ -1966,7 +1940,7 @@ To calculate canopy leaf respiration, which varies through we canopy, we first determine the top-of-canopy leaf respiration rate (:math:`r_{m,leaf,ft,0}`, gC s\ :math:`^{-1}` m\ :math:`^{-2}`) is calculated from a base rate of respiration per unit leaf nitrogen -derived from :raw-latex:`\cite{ryan1991}`. The base rate for leaf +derived from :ref:`Ryan et al. 1991`. The base rate for leaf respiration (:math:`r_{b}`) is 2.525 gC/gN s\ :math:`^{-1}`, .. math:: r_{m,leaf,ft,0} = r_{b} N_{a,ft}(1.5^{(25-20)/10}) @@ -2006,7 +1980,7 @@ same base rate of respiration per unit of tissue Nitrogen. Here, :math:`t_c` is a temperature relationship based on a :math:`q_{10}` value of 1.5, where :math:`t_v` is the vegetation temperature. We use a base rate of 20 here as, again, this is the -baseline temperature used by :raw-latex:`\cite{ryan1991}`. The +baseline temperature used by :ref:`Ryan et al. 1991`. The 10\ :math:`^{-3}` converts from gC invididual\ :math:`^{-1}` s\ :math:`^{-1}` to KgC invididual\ :math:`^{-1}` s\ :math:`^{-1}` @@ -2089,13 +2063,13 @@ Fundamental stomatal conductance theory [14]_Stomatal conductance is unchanged in concept from the CLM4.5 approach. Leaf stomatal resistance is calculated from the Ball-Berry conductance -model as described by :raw-latex:`\cite{collatz1991}` and implemented in -a global climate model by :raw-latex:`\cite{sellers1996}`. The model +model as described by :ref:`Collatz et al. 1991` and implemented in +a global climate model by :ref:`Sellers et al. 1996`. The model relates stomatal conductance (i.e., the inverse of resistance) to net leaf photosynthesis, scaled by the relative humidity at the leaf surface and the CO\ :math:`_2` concentration at the leaf surface. The primary difference between the CLM implementation and that used by -:raw-latex:`\cite{collatz1991}` and :raw-latex:`\cite{sellers1996}` is +:ref:`Collatz et al. 1991` and :ref:`Sellers et al. 1996` is that they used net photosynthesis (i.e., leaf photosynthesis minus leaf respiration) instead of gross photosynthesis. As implemented here, stomatal conductance equals the minimum conductance (:math:`b`) when @@ -2118,14 +2092,14 @@ surface (Pa), :math:`e_i` is the saturation vapor pressure (Pa) inside the leaf at the vegetation temperature conductance (:math:`\mu`\ mol m\ :math:`^{-2}` s\ :math:`^{-1}`) when :math:`A` = 0 . Typical values are :math:`m_{ft}` = 9 for C\ :math:`_3` plants and :math:`m_{ft}` = 4 -for C\ :math:`_4` plants -:raw-latex:`\parencite{collatz1991,collatz1992,sellers1996}`. -:raw-latex:`\cite{sellers1996}` used :math:`b` = 10000 for C\ :math:`_3` +for C\ :math:`_4` plants ( +:ref:`Collatz et al. 1991`, :ref:`Collatz, 1992`, :ref:`Sellers et al 1996)`. +:ref:`Sellers et al. 1996` used :math:`b` = 10000 for C\ :math:`_3` plants and :math:`b` = 40000 for C\ :math:`_4` plants. Here, :math:`b` was chosen to give a maximum stomatal resistance of 20000 s m\ :math:`^{-1}`. These terms are nevertheless plant strategy dependent, and have been found to vary widely with plant type -:raw-latex:`\parencite{medlyn2011}`. +:ref:`Medlyn et al. 2001`. Resistance is converted from units of s m\ :math:`^2 \mu` mol\ :math:`^{-1}` to s m\ :math:`^{-1}` as: 1 s m\ :math:`^{-1}` = @@ -2240,7 +2214,7 @@ where The allocation to storage is a fourth power function of :math:`f_{tstore}` to mimic the qualitative behaviour found for carbon -allocation in arabidopsis by :raw-latex:`\cite{smith2007}`. +allocation in arabidopsis by :ref:`Smith et al. 2007`. .. math:: @@ -2487,7 +2461,7 @@ C\ :math:`^{-1}`) .. math:: A_{leaf,coh} = b_{leaf,coh} \cdot SLA_{ft} For a given tree allometry, leaf biomass is determined from basal area -using the function used by :raw-latex:`\cite{mc_2001}` where :math:`d_w` +using the function used by :ref:`Moorcroft et al. 2001` where :math:`d_w` is wood density in g cm\ :math:`^{-3}`. .. math:: b_{leaf,coh} = c_{leaf} \cdot dbh_{coh}^{e_{leaf,dbh}} \rho_{ft}^{e_{leaf,dens}} @@ -2578,7 +2552,7 @@ Cold Deciduous Phenology Cold Leaf-out timing ~~~~~~~~~~~~~~~~~~~~ -[18]_. The phenology model of :raw-latex:`\cite{botta2000}` is used in +[18]_. The phenology model of :ref:`Botta et al. 2000` is used in FATES to determine the leaf-on timing. The Botta et al. model was verified against satellite data and is one of the only globally verified and published models of leaf-out phenology. This model differs from the @@ -2592,13 +2566,13 @@ given threshold :math:`T_{g}` (0 :math:`^{o}`\ C). Budburst occurs when :math:`GDD` exceeds a threshold (:math:`GDD_{crit}`). The threshold is modulated by the number of chilling days experienced (NCD) where the mean daily temperature falls -below a threshold determined by :raw-latex:`\cite{botta2000}` as +below a threshold determined by `Botta et al. 2000` as 5\ :math:`^{o}`\ C. A greater number of chilling days means that fewer growing degree days are required before budburst: .. math:: GDD_{crit}=a+be^{c.NCD} -where a = -68, b= 638 and c=-0.01 :raw-latex:`\cite{botta2000}`. In the +where a = -68, b= 638 and c=-0.01 `Botta et al. 2000`. In the Northern Hemisphere, counting of degree days begins on 1st January, and of chilling days on 1st November. The calendar opposite of these dates is used for points in the Southern Hemisphere. @@ -2620,8 +2594,8 @@ Cold Leaf-off timing The leaf-off model is taken from the Sheffield Dynamic Vegetation Model (SDGVM) and is similar to that for LPJ -:raw-latex:`\parencite{sitch2003}` and IBIS -:raw-latex:`\parencite{foley1996}` models. The average daily +:ref:`Sitch et al. 2003` and IBIS +:ref:`Foley et al. 1996` models. The average daily temperatures of the previous 10 day period are stored. Senescence is triggered when the number of days with an average temperature below 7.5\ :math:`^{o}` (:math:`n_{colddays}`) rises above a threshold values @@ -2772,10 +2746,10 @@ patch of the correct PFT type. .. math:: Seed_{in,ft} = \frac{\sum_{p=1}^{n_{patch}}\sum_{i=1}^{n_{coh}}p_{seed,i}.n_{coh}}{area_{site}} Seed decay is the sum of all the processes that reduce the number of -seeds, taken from :raw-latex:`\cite{lischke2006}`. Firstly, the rate at +seeds, taken from :ref:`Lischke et al. 2006`. Firstly, the rate at which seeds become inviable is described as a constant rate :math:`\phi` (y:math:`^{-1}`) which is set to 0.51, the mean of the parameters used -by :raw-latex:`\cite{lischke2006}`. +by :ref:`Lischke et al. 2006`. .. math:: Seed_{decay,ft} = Seeds_{FT}.\phi @@ -3038,13 +3012,13 @@ PFT-specific ‘target’ carbon storage, :math:`l_{targ,ft}`, as follows: .. math:: M_{cs,coh}= \rm{max} \left(0.0, S_{m,ft} \left(0.5 - \frac{b_{store,coh}}{l_{targ,ft}b_{leaf}}\right)\right) -where :math:`S_{m,ft}` is the ‘stress mortality’ parameter, or the +where :math:`S_{m,ft}` is the `stress mortality` parameter, or the fraction of trees in a landscape that die when the mean condition of a given cohort triggers mortality. This parameter is needed to scale from individual-level mortality simulation to grid-cell average conditions. Mechanistic simulation of hydraulic failure is not undertaken on account -of it’s mechanistic complexity (see :raw-latex:`\cite{mcdowell2013}`for +of it’s mechanistic complexity (see :ref:`McDowell et al. 2013`for details). Instead, we use a proxy for hydraulic failure induced mortality (:math:`M_{hf,coh}`) that uses a water potential threshold beyond mortality is triggered, such that the tolerance of low water @@ -3096,13 +3070,13 @@ Fire (SPITFIRE) [24]_The influence of fire on vegetation is estimated using the SPITFIRE model, which has been modified for use in ED following it’s original implementation in the LPJ-SPITFIRE model -(:raw-latex:`\parencite{thonicke2010,pfeiffer2013}`. This model as +(:ref:`Thonicke et al. 2010, :ref:`Pfeiffer et al. 2013`). This model as described is substantially different from the existing CLM4.5 fire model -:raw-latex:`\parencite{li2012}`, however, further developments are +:ref:`Li et al. 2012`, however, further developments are intended to increase the merging of SPITFIRE’s natural vegetation fire scheme with the fire suppression, forest-clearing and peat fire estimations in the existing model. The coupling to the ED model allows -fires to interact with vegetation in a ‘size-structured’ manner, so +fires to interact with vegetation in a size-structured manner, so small fires can burn only understorey vegetation. Also, the patch structure and representation of succession in the ED model allows the model to track the impacts of fire on different forest stands, therefore @@ -3114,7 +3088,7 @@ only implementation of this type of scheme in existence. The SPITFIRE model operates at a daily timestep and at the patch level, meaning that different litter pools and vegetation charecteristics of open and closed forests can be represented effectively (we omit the -‘patch’ subscript throughout for simplicity). +`patch` subscript throughout for simplicity). Properties of fuel load --------------- @@ -3123,11 +3097,11 @@ Many fire processes are impacted by the properties of the litter pool in the SPITFIRE model. There are one live (live grasses) and five dead fuel categories (dead leaf litter and four pools of coarse woody debris). Coarse woody debris is classified into 1h, 10h, 100h, and 1000h fuels, -defined by “\ *the order of magnitude of time required for fuel to lose +defined by the order of magnitude of time required for fuel to lose (or gain) 63% of the difference between its current moisture content and -the equilibrium moisture content under defined atmospheric conditions.*" -:raw-latex:`\parencite{thonicke2010}`. For the purposes of describing -the behaviour of fire, we introduce a new index ‘fuel class’ *fc*, the +the equilibrium moisture content under defined atmospheric conditions. +:ref:`Thonicke et al. 2010`. For the purposes of describing +the behaviour of fire, we introduce a new index 'fuel class' *fc*, the values of which correspond to each of the six possible fuel categories as follows. @@ -3157,7 +3131,7 @@ Nesterov Index Dead fuel moisture (:math:`\emph{moist}_{df,fc}`), and several other properties of fire behaviour, are a function of the ‘Nesterov Index’ (:math:`N_{I}`) which is an accumulation over time of a function of -temperature and humidity (Eqn 5, :raw-latex:`\cite{thonicke2010}`). +temperature and humidity (Eqn 5, :ref:`Thonicke et al. 2010`). .. math:: N_{I}=\sum{\textrm{max}(T_{d}(T_{d}-D),0)} @@ -3204,7 +3178,7 @@ Live grass moisture Content The live grass fractional moisture content(\ :math:`\emph{moist}_{lg}`) is a function of the soil moisture content. (Equation B2 in -:raw-latex:`\cite{thonicke2010}`) +:ref:`Thonicke et al. 2010`) .. math:: \emph{moist}_{lg}=\textrm{max}(0.0,\frac{10}{9}\theta_{30}-\frac{1}{9}) @@ -3274,7 +3248,7 @@ the fire *ros*\ :math:`_{f}` (nominally in the direction of the wind). :math:`e_{ps}` is the effective heating number (:math:`e^{\frac{-4.528}{F_{\sigma,patch}}}`). :math:`q_{ig}` is the heat of pre-ignition (:math:`581+2594F_{m}`). :math:`x_{i}` is the -propagating flux calculated as (see :raw-latex:`\cite{thonicke2010}` +propagating flux calculated as (see :ref:`Thonicke et al. 2010` Appendix A). .. math:: @@ -3298,7 +3272,7 @@ surface-area-volume ratio :math:`F_{\sigma,patch}`: where :math:`p_{d}` is the particle density (513). :math:`i_{r}` is the reaction intensity, calculated using the following -set of expressions (from :raw-latex:`\cite{thonicke2010}` Appendix A).: +set of expressions (from :ref:`Thonicke et al. 2010` Appendix A).: .. math:: @@ -3322,7 +3296,7 @@ Fuel Consumption The fuel consumption (fraction of biomass pools) of each dead biomass pool in the area affected by fire on a given day (:math:`f_{c,dead,fc}`) is a function of effective fuel moisture :math:`E_{moist,fc}` and size -class *fc* (Eqn B1, B4 and B5, :raw-latex:`\cite{thonicke2010}`). The +class *fc* (Eqn B1, B4 and B5, :ref:`Thonicke et al. 2010`). The fraction of each fuel class that is consumed decreases as its moisture content relative to its moisture of extinction (:math:`E_{moist,fc}`) increases. @@ -3334,7 +3308,7 @@ is modulated by both size class :math:`fc` and by the effective fuel moisture class :math:`mc`, defined by :math:`E_{moist,fc}`. :math:`m_{int}` and :math:`m_{slope}` are defined for low-, mid-, and high-moisture conditions, the boundaries of which are also functions of -the litter size class following :raw-latex:`\cite{peterson1986}` (page +the litter size class following :ref:`Peterson and Ryan 1986 ` (page 802). The fuel burned, :math:`f_{cground,fc}` (Kg m\ :math:`^{-2}` day\ :math:`^{-1}`) iscalculated from :math:`f_{cdead,fc}` for each fuel class: @@ -3357,7 +3331,7 @@ Fire intensity at the front of the burning area (:math:`I_{surface}`, kW m\ :math:`^{-2}`) is a function of the total fuel consumed (:math:`f_{ctot,patch}`) and the rate of spread at the front of the fire, :math:`\mathit{ros}_{f}` (m min\ :math:`^{-1}`) (Eqn 15 -:raw-latex:`\cite{thonicke2010}`) +:ref:`Thonicke et al. 2010`) .. math:: I_{surface}=\frac{0.001}{60}f_{energy} f_{ctot,patch}\mathit{ros}_{f} @@ -3371,7 +3345,7 @@ Fire Duration Fire duration is a function of the fire danger index with a maximum length of :math:`F_{dur,max}` (240 minutes in -:raw-latex:`\cite{thonicke2010}` Eqn 14, derived from Canadian Forest +:ref:`Thonicke et al. 2010` Eqn 14, derived from Canadian Forest Fire Behaviour Predictions Systems) .. math:: D_{f}=\textrm{min}\Big(F_{dur,max},\frac{F_{dur,max}}{1+F_{dur,max}e^{-11.06fdi}}\Big) @@ -3387,7 +3361,7 @@ for each gridcell as a function of the Nesterov Index . .. math:: \emph{fdi}=1-e^{\alpha N_{I}} where :math:`\alpha` = 0.00037 following -:raw-latex:`\cite{venevsky2002}`. +:ref:`Venevsky et al. 2002`. Area Burned ----------- @@ -3400,14 +3374,14 @@ respectively). .. math:: f_{length}=F_{d}(ros_{b}+ros_{f}) :math:`ros_{b}` is a function of :math:`ros_{f}` and windspeed (Eqn 10 -:raw-latex:`\cite{thonicke2010}`) +:ref:`Thonicke et al. 2010`) .. math:: ros_{b}=ros_{f}e^{-0.72W} The minor axis to major axis ratio :math:`l_{b}` of the ellipse is determined by the windspeed. If the windspeed (:math:`W`) is less than 16.67 ms\ :math:`^{-1}` then :math:`l_{b}=1`. Otherwise (Eqn 12 and 13, -:raw-latex:`\cite{thonicke2010}`) +:ref:`Thonicke et al. 2010`) .. math:: l_{b}=\textrm{min}\Big(8,f_{tree}(1.0+8.729(1.0-e^{-0.108W})^{2.155})+(f_{grass}(1.1+3.6W^{0.0464}))\Big) @@ -3415,7 +3389,7 @@ determined by the windspeed. If the windspeed (:math:`W`) is less than surface covered by grass and trees respectively. The total area burned (:math:`A_{burn}` in m\ :math:`^{2}`) is therefore -(Eqn 11, :raw-latex:`\cite{thonicke2010}`) +(Eqn 11, :ref:`Thonicke et al. 2010`) .. math:: A_{burn}=\frac{n_{f}\frac{3.1416}{4l_{b}}(f_{length}^{2}))}{10000} @@ -3427,7 +3401,7 @@ Crown Damage :math:`c_{k}` is the fraction of the crown which is consumed by the fire. This is calculated from scorch height :math:`H_{s}`, tree height :math:`h` and the crown fraction parameter :math:`F_{crown}` (Eqn 17 -:raw-latex:`\cite{thonicke2010}`): +:ref:`Thonicke et al. 2010`): .. math:: @@ -3438,9 +3412,9 @@ fire. This is calculated from scorch height :math:`H_{s}`, tree height \end{array} \right. The scorch height :math:`H_{s}` (m) is a function of the fire intensity, -following :raw-latex:`\cite{byram1959}`, and is proportional to a plant +following :ref:`Byram, 1959`, and is proportional to a plant functional type specific parameter :math:`\alpha_{s,ft}` (Eqn 16 -:raw-latex:`\cite{thonicke2010}`): +:ref:`Thonicke et al. 2010`): .. math:: H_{s}=\sum_{FT=1}^{NPFT}{\alpha_{s,p}\cdot f_{biomass,ft}} I_{surface}^{0.667} @@ -3452,25 +3426,25 @@ Cambial Damage and Kill The cambial kill is a function of the fuel consumed :math:`f_{c,tot}`, the bark thickness :math:`t_{b}`, and :math:`\tau_{l}`, the duration of -cambial heating (minutes) (Eqn 8, :raw-latex:`\cite{peterson1986}`): +cambial heating (minutes) (Eqn 8, :ref:`Peterson and Ryan 1986`): .. math:: \tau_{l}=\sum_{fc=1}^{fc=5}39.4F_{p,c}\frac{10000}{0.45}(1-(1-f_{c,dead,fc})^{0.5}) Bark thickness is a linear function of tree diameter :math:`dbh_{coh}`, defined by PFT-specific parameters :math:`\beta_{1,bt}` and -:math:`\beta_{2,bt}` (Eqn 21 :raw-latex:`\cite{thonicke2010}`): +:math:`\beta_{2,bt}` (Eqn 21 :ref:`Thonicke et al. 2010`): .. math:: t_{b,coh}=\beta_{1,bt,ft}+\beta_{2,bt,ft}dbh_{coh} The critical time for cambial kill, :math:`\tau_{c}` (minutes) is given -as (Eqn 20 :raw-latex:`\cite{thonicke2010}`): +as (Eqn 20 :ref:`Thonicke et al. 2010`): .. math:: \tau_{c}=2.9t_{b}^{2} The mortality rate caused by cambial heating :math:`\tau_{pm}` of trees within the area affected by fire is a function of the ratio between :math:`\tau_{l}` and :math:`\tau_{c}` (Eqn 19, -:raw-latex:`\cite{thonicke2010}`): +:ref:`Thonicke et al. 2010`): .. math:: diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index e613dce3b4..4d0883ac14 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -2226,3 +2226,134 @@ Global Biogeochemical Cycles 18. DOI:10.1029/2004GB002239. Zilitinkevich, S.S. 1970. Dynamics of the Atmospheric Boundary Layer. Leningrad Gidrometeor. + +.. _bonan2012: + +Bonan, Gordon B et al. (2012). `Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4`. Journal of Geophysical Research: Biogeosciences (2005-2012) 117.G2. + +.. _botta2000: + +Botta, A et al. (2000). `A global prognostic scheme of leaf onset using satellite data`. Global Change Biology 6.7, pp. 709-725. + +.. _byram1959: + +Byram, GM (1959). Combustion of forest fuels. In Forest fire: control and use.(Ed. KP Davis) pp. 61-89. + +.. _collatz1991: + +Collatz, G James 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 54.2, pp. 107-136. + +.. _collatz1992: + +Collatz, Go J, M Ribas-Carbo, and JA Berry (1992). `Coupled photosynthesis-stomatal conductance model for leaves of C4 plants`. Functional Plant Biology 19.5, pp. 519-538.
 + +.. _farquhar1980: + +Farquhar, GD, S von von Caemmerer, and JA Berry (1980). `A biochemical model of photosynthetic CO2 assimilation in leaves of C3 species`. Planta 149.1, pp. 780-90. + +.. _fisher2010: + +Fisher, JB et al. (2010). `Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation`. Global Biogeochemical Cycles 24.1. + +.. _foley1996: + +Foley, Jonathan A et al. (1996). `An integrated biosphere model of land surface processes, terrestrial carbon balance, and vegetation dynamics`. Global Biogeochemical Cycles 10.4, pp. 603-628. + +.. _fyllas2014: + +Fyllas, NM et al. (2014). `Analysing Amazonian forest productivity using a new individual and trait- based model (TFS v. 1)`. Geoscientific Model Development 7.4, pp. 1251-1269. + +.. _kucharik1998: + +Kucharik, Christopher J, John M Norman, and Stith T Gower (1998). `Measurements of branch area and adjusting leaf area index indirect measurements`. Agricultural and Forest Meteorology 91.1, pp. 69-88. + +.. _li2012: + +Li, F, XD Zeng, and S Levis (2012). `A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model`. Biogeosciences 9.7, pp. 2761-2780. + +.. _lichstein2011: + +Lichstein, Jeremy W and Stephen W Pacala (2011). `Local diversity in heterogeneous landscapes: quantitative assessment with a height-structured forest metacommunity model`. Theoretical Ecology 4.2, pp. 269-281. + +.. _lischke2006: + +Lischke, Heike et al. (2006). `TreeMig: a forest-landscape model for simulating spatio-temporal patterns from stand to landscape scale`. Ecological Modelling 199.4, pp. 409-420. 41 + +.. _lloyd2010: + +Lloyd, J et al. (2010). `Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees`. Biogeosciences 7.6, pp. 1833-1859. + +.. _mcdowell2013: + +McDowell, Nate G et al. (2013). `Evaluating theories of drought-induced vegetation mortality using a multimodel experiment framework`. New Phytologist 200.2, pp. 304-321. + +.. _medlyn2011: + +Medlyn, Belinda E et al. (2011). `Reconciling the optimal and empirical approaches to modelling stom- atal conductance`. Global Change Biology 17.6, pp. 2134-2144. + + +.. _mc_2001: + +Moorcroft, PR, GC Hurtt, and Stephen W Pacala (2001). `A method for scaling vegetation dynamics: the ecosystem demography model ED`. Ecological monographs 71.4, pp. 557-586. + +.. _norman1979: + +Norman, JM (1979). `Modeling the complete crop canopy`. Modification of the Aerial Environment of Crops, pp. 249-280. + +.. _oleson2013: + +Oleson, KW et al. (2013). `Technical description of version 4.5 of the Community Land Model (CLM)`. + +.. _peterson1986: + +Peterson, David L and Kevin C Ryan (1986). `Modeling postfire conifer mortality for long-range planning`. Environmental Management 10.6, pp. 797-808. + +.. _pfeiffer2013: + +Pfeiffer, M, A Spessa, and JO Kaplan (2013). `A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0)`. Geoscientific Model Development 6.3, pp. 643-685. + +.. _purves2008: + +Purves, Drew W et al. (2008). `Predicting and understanding forest dynamics using a simple tractable model`. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. + +.. _sato2007: + +Sato, Hisashi, Akihiko Itoh, and Takashi Kohyama (2007). `SEIB–DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach`. Ecological Modelling 200.3, pp. 2793307. + +.. _sellers1996: + +Sellers, Piers J et al. (1996). `A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data`. Journal of climate 9.4, pp. 706-737. + +.. _sitch2003: + +Sitch, S et al. (2003). `Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model`. Global Change Biology 9.2, pp. 161-185. + +.. _smith2007: + +Smith, Alison M and Mark Stitt (2007). `Coordination of carbon supply and plant growth`. Plant, cell & environment 30.9, pp. 1126-1149. + +.. _smith2001: + +Smith, Benjamin, I Colin Prentice, and Martin T Sykes (2001). `Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space`. Global Ecology and Biogeography 10.6, pp. 621-637. + +.. _thonicke2010: + +Thonicke, K et al. (2010). `The influence of vegetation, fire spread and fire behaviour on biomass burning and trace gas emissions: results from a process-based model`. Biogeosciences 7.6, pp. 1991-2011. + +.. _uriarte2009: + +Uriarte, Maria et al. (2009). `Natural disturbance and human land use as determinants of tropical forest dynamics: results from a forest simulator`. Ecological Monographs 79.3, pp. 423-443. + +.. _venevsky2002: + +Venevsky, Sergey et al. (2002). `Simulating fire regimes in human-dominated ecosystems: Iberian Peninsula case study`. Global Change Biology 8.10, pp. 984-998. + +.. _weng2014: + +Weng, ES et al. (2014). `Scaling from individuals to ecosystems in an Earth System Model using a mathematically tractable model of height-structured competition for light`. Biogeosciences Discussions 11.12, pp. 17757-17860. + +.. _xiaodong2005: + +Xiaodong, Yan and HH Shugart (2005). `FAREAST: a forest gap model to simulate dynamics and patterns of eastern Eurasian forests`. Journal of Biogeography 32.9, pp. 1641-1658. +42 + From 97e56aa0500ddcee5ef9d4231a32136f88e4debf Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Wed, 13 Dec 2017 09:28:24 -0700 Subject: [PATCH 118/255] Update html and fix build errors --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 76 +++++++++---------- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 67 +--------------- ...LM50_Tech_Note_External_Nitrogen_Cycle.rst | 4 +- .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 3 +- .../References/CLM50_Tech_Note_References.rst | 7 ++ .../CLM50_Tech_Note_Surface_Albedos.rst | 5 +- 6 files changed, 55 insertions(+), 107 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 3a0bfcdbb2..45953fdca8 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -58,7 +58,7 @@ concept of 'Ecosystem Demography' and the implementation of this concept in different models, the CLM(ED) implementation described by Fisher et al. (2015) will hereafter be called 'FATES' (the Functionally Assembled Terrestrial Ecosystem Simulator). The representation of ecosystem heterogeneity in FATES -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The terrestrial surface of the Earth is heterogeneous for many reasons, driven by variations in climate, edaphic history, ecological variability, @@ -445,7 +445,7 @@ restarted. The state variables of a cohort are as follows: +-----------------+-----------------+-----------------+-----------------+ Patch State Variables ------------------- +--------------------- A patch, as discuss earlier, is a fraction of the landscape which contains ecosystems with similar structure and disturbance history. A @@ -515,7 +515,7 @@ attributed to each cohort are accumulated throughout each daily cycle and passed into the ED code as the major driver of vegetation dynamics. Initialization of vegetation from bare ground -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ [5]_If the model is restarted from a bare ground state (as opposed to a pre-existing vegetation state), the state variables above are @@ -586,7 +586,7 @@ biomass, assigned per PFT [table:init] Allocation of biomass -^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^ [6]_Total live biomass :math:`b_{alive}` is the state variable of the model that describes the sum of the three live biomass pools leaf @@ -695,7 +695,7 @@ To calculated the sapwood biomass, we use [table:allom] Canopy Structure and the Perfect Plasticity Approximation -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ [7]_During initialization and every subsequent daily ED timestep, the canopy structure model is called to determine how the leaf area of the @@ -711,7 +711,7 @@ heights, which has a very significant impact on how vegetation distribution emerges from competition :ref:`Fisher et al. 2010`. -The standard ED1.0 model makes a simple `flat disk' assumption, that the +The standard ED1.0 model makes a simple 'flat disk' assumption, that the leaf area of each cohort is spread in an homogenous layer at one exact height across entire the ground area represented by each patch. FATES has diverged from this representation due to (at least) two problematic emergent properties that we identified as generating unrealistic behaviours espetially for large-area patches. @@ -826,10 +826,10 @@ fractions of cohorts are demoted or promoted. Further details can be found in the code references in the footnote. Horizontal Canopy Spread ------------------ +------------------------- [8]_:ref:`Purves et al. 2008` estimated the ratio between canopy and -stem diameter :math:`c_{p}` as 0.1 m cm\ :math:`^{-1}` for canopy trees +stem diameter :math:`c_{p}` as 0.1 m cm\ :math:`^{-1}` for canopy trees in North American forests, but this estimate was made on trees in closed canopies, whose shape is subject to space competition from other individuals. Sapling trees have no constraints in their horizontal @@ -887,7 +887,7 @@ However, the model is relatively insensitive to the choice of either :math:`i` or :math:`A_{t}`. Definition of Leaf and Stem Area Profile -------------------- +---------------------------------------- [9]_Within each patch, the model defines and tracks cohorts of multiple plant functional types that exist either in the canopy or understorey. @@ -1030,7 +1030,7 @@ leaf and stem area profiles, Burial of leaf area by snow --------------------- +--------------------------- The calculations above all pertain to the total leaf and stem area indices which charecterize the vegetation structure. In addition, the @@ -1129,7 +1129,7 @@ Radiation Transfer ^^^^^^^^^^^^^^^^^^^ Fundamental Radiation Transfer Theory ------------------- +------------------------------------- [10]_The first interaction of the land surface with the properties of vegetation concerns the partitioning of energy into that which is @@ -1343,7 +1343,7 @@ fractions, (required by the photosynthesis calculations), is .. math:: abs_{sun,z} = abs_{dif,z} \cdot f_{sun}+ abs_{dir,z} Resolution of radiation transfer theory within the FATES canopy structure ------------------- +------------------------------------------------------------------------- The radiation transfer theory above, was described with reference to a single canopy of one plant functional type, for the sake of clarity of @@ -1520,7 +1520,7 @@ Photosynthesis ^^^^^^^^^^^^^^^^^^^^ Fundamental photosynthetic physiology theory ------------------- +-------------------------------------------- [11]_In this section we describe the physiological basis of the photosynthesis model before describing its application to the FATES @@ -1630,7 +1630,7 @@ to carboxylation, which is virtually constant with temperature :ref:`Farquhar, 1980`. Resolution of the photosynthesis theory within the FATES canopy structure. ------------------- +-------------------------------------------------------------------------- The photosynthesis scheme is modified from the CLM4.5 model to give estimates of photosynthesis, respiration and stomatal conductance for a @@ -1703,7 +1703,7 @@ s\ :math:`^{-1}`) is calculated in a similar fashion, \end{array} \right. Variation in plant physiology with canopy depth ------------------- +----------------------------------------------- Both :math:`V_{c,max}` and :math:`J_{max}` vary with vertical depth in the canopy on account of the well-documented reduction in canopy @@ -1764,7 +1764,7 @@ where :math:`V_{cmax}` is again in :math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`. Water Stress on gas exchange ------------------- +---------------------------- [12]_ The top of canopy leaf photosynthetic capacity, :math:`V_{c,max0}`, is also adjusted for the availability of water to plants as @@ -1802,7 +1802,7 @@ on the calculation of soil matric potential, see the CLM4.5 technical note. Variation of water stress and water uptake within tiles -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The remaining drivers of the photosynthesis model remain constant (atmospheric CO\ :math:`_2` and O\ :math:`^2` and canopy temperature) @@ -1837,7 +1837,7 @@ canopy conductance for plant functional type :math:`ft`, .. math:: G_{s,ft}= \sum_{1}w_{ncoh,ft} {gs_{can,coh} n_{coh} }. Aggregation of assimilated carbon into cohorts ------------------- +---------------------------------------------- The derivation of photosynthetic rates per leaf layer, as above, give us the estimated rate of assimilation for a unit area of leaf at a given @@ -2056,10 +2056,10 @@ respiration has occurred. \bigskip Stomatal Conductance -^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^ Fundamental stomatal conductance theory ------------------- +--------------------------------------- [14]_Stomatal conductance is unchanged in concept from the CLM4.5 approach. Leaf stomatal resistance is calculated from the Ball-Berry conductance @@ -2110,7 +2110,7 @@ kmol\ :math:`^{-1}`) and :math:`\theta_{atm}` is the atmospheric potential temperature (K). Resolution of stomatal conductance theory in the FATES canopy structure --------------- +----------------------------------------------------------------------- The stomatal conductance is calculated, as with photosynthesis, for each canopy, PFT and leaf layer. The CLM code requires a single canopy @@ -2144,7 +2144,7 @@ cohort. Allocation and Growth -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^ [15]_Total assimilation carbon enters the ED model each day as a cohort-specific Net Primary Productivity :math:`\mathit{NPP}_{coh}`, @@ -2162,7 +2162,7 @@ individual\ :math:`^{-1}` year\ :math:`^{-1}` and ultimately integrated using a timesteps of 1/365 years for each day. Tissue maintenance demand ---------------- +------------------------- We calculate a ‘tissue maintenance’ flux. The magnitude of this flux is such that the quantity of biomass in each pool will remain constant, @@ -2191,7 +2191,7 @@ phenology section. The total quantity of maintenance demand .. math:: t_{md,coh} = l_{md,coh} + r_{md,coh} Allocation to storage and turnover ------------------ +---------------------------------- The model must now determine whether the NPP input is sufficient to meet the maintenance demand and keep tissue levels constant. To determine @@ -2272,7 +2272,7 @@ and leaf biomass, ameliorated by the leaf trimming fraction (see :math:`\rho_{ft}` is the wood density, in g cm\ :math:`^{3}`. Allocation to Seeds ---------------- +------------------- The fraction remaining for growth (expansion of live and structural tissues) :math:`f_{growth}` is 1 minus that allocated to seeds. @@ -2298,7 +2298,7 @@ KgC individual :math:`^{-1}` y\ :math:`^{-1}`) is thus .. math:: p_{seed,coh} = C_{growth}\cdot f_{seed,coh} Allocation to growing pools ----------------- +--------------------------- [16]_ The carbon is then partitioned into carbon available to grow the :math:`b_{alive}` and :math:`b_{struc}` pools. A fraction :math:`v_{a}` @@ -2382,7 +2382,7 @@ structural biomass pools are maintained in this algorithm, which diverges from the methodology currently deployed in the CLM4.5. Integration of allocated fluxes ----------------- +------------------------------- All of the flux calculations generate differential of the biomass state variables against time (in years). To integrate these differential rates @@ -2451,7 +2451,7 @@ In this case, :math:`\delta t` is set to be one day \bigskip Control of Leaf Area Index -^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^ [17]_The leaf area :math:`A_{leaf}` (m:math:`^{-2}`) of each cohort is calculated from leaf biomass :math:`b_{leaf,coh}` (kgC @@ -2547,7 +2547,7 @@ Phenology ^^^^^^^^^^^^^^^^^^^^ Cold Deciduous Phenology ------------------- +------------------------ Cold Leaf-out timing ~~~~~~~~~~~~~~~~~~~~ @@ -2632,7 +2632,7 @@ constrain growing degree day accumulation to the second half of the year and only allow GDD accumulation while the leaves are off. Drought-deciduous Phenology: TBD ------------------- +-------------------------------- In the current version of the model, a drought deciduous algorithm exists, but is not yet operational, due to issue detected in the existing @@ -2641,7 +2641,7 @@ native ED drought deciduous model. This is a priority to address before the science tag is released. Carbon Dynamics of deciduous plants ------------------- +----------------------------------- [19]_In the present version, leaf expansion and senescence happen over the course of a single day. This is clearly not an empirically robust @@ -2719,7 +2719,7 @@ for this carbon accounting scheme. \bigskip Seed Dynamics and Recruitment -^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ [20]_The production of seeds and their subsequent germination is a process @@ -2800,7 +2800,7 @@ of one plant functional type over the seed pool. \bigskip Litter Production and Fragmentation -^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | The original CLM4.5 model contains streams of carbon pertaining to different chemical properties of litter (lignin, cellulose and labile @@ -2900,7 +2900,7 @@ sensitivity analyses of the model outputs. .. math:: l_{root,out,ft} = l_{root,ft}.\alpha_{root,ft}.S_{tw} Flux into decompsition cascade --------------- +------------------------------ [23]_Upon fragmentation and release from the litter pool, carbon is transferred into the labile, lignin and cellulose decomposition pools. @@ -3091,7 +3091,7 @@ open and closed forests can be represented effectively (we omit the `patch` subscript throughout for simplicity). Properties of fuel load ---------------- +----------------------- Many fire processes are impacted by the properties of the litter pool in the SPITFIRE model. There are one live (live grasses) and five dead fuel @@ -3238,7 +3238,7 @@ fuels). .. math:: F_{\sigma}=\sum_{fc=1}^{fc=4} \frac{F_{fc}}{F_{tot}}\sigma_{fuel,fc}+\frac{b_{l,grass}}{F_{tot}}\sigma_{fuel,grass} Forward rate of spread ------------------ +---------------------- For each patch and each day, we calculate the rate of forward spread of the fire *ros*\ :math:`_{f}` (nominally in the direction of the wind). @@ -3351,7 +3351,7 @@ Fire Behaviour Predictions Systems) .. math:: D_{f}=\textrm{min}\Big(F_{dur,max},\frac{F_{dur,max}}{1+F_{dur,max}e^{-11.06fdi}}\Big) Fire Danger Index --------------- +----------------- Fire danger index (*fdi*) is a representation of the effect of meteorological conditions on the likelihood of a fire. It is calculated @@ -3422,7 +3422,7 @@ where :math:`f_{biomass,ft}` is the fraction of the above-ground biomass in each plant functional type. Cambial Damage and Kill -------------- +----------------------- The cambial kill is a function of the fuel consumed :math:`f_{c,tot}`, the bark thickness :math:`t_{b}`, and :math:`\tau_{l}`, the duration of diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index e21c8e05d0..6d36046e41 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -187,74 +187,15 @@ Vegetation Structure ^^^^^^^^^^^^^^^^^^^^^^^^^^ Vegetation structure is defined by leaf and stem area indices -(:math:`L,\, S`) and canopy top and bottom heights (:math:`z_{top}`,\ :math:`z_{bot}` ) -(:numref:`Table Prescribed plant functional type heights`). Separate leaf and +(:math:`L,\, S`) and canopy top and bottom heights (:math:`z_{top}`,\ :math:`z_{bot}` ). +Separate leaf and stem area indices and canopy heights are prescribed or calculated for each PFT. Daily leaf and stem area indices are obtained from griddeddatasets of monthly values (section -:numref:`Surface Data`). Canopy top and bottom heights are also obtained from gridded datasets. -However, these are currently invariant in space and time and were obtained from PFT-specific -values (:ref:`Bonan et al. 2002a `). When the biogeochemistry model is active, +:numref:`Surface Data`). Canopy top and bottom heights are from ICESat (:ref:`Simard et al. (2011) `. +When the biogeochemistry model is active, vegetation state (LAI, SAI, canopy top and bottom heights) are calculated prognostically (see Chapter :numref:`rst_Vegetation Phenology and Turnover`). -.. _Table Prescribed plant functional type heights: - -.. table:: Prescribed plant functional type heights - - +-----------------------------------+------------------------+------------------------+ - | Plant functional type | :math:`z_{top}` (m) | :math:`z_{bot}` (m) | - +===================================+========================+========================+ - | NET Temperate | 17 | 8.5 | - +-----------------------------------+------------------------+------------------------+ - | NET Boreal | 17 | 8.5 | - +-----------------------------------+------------------------+------------------------+ - | NDT Boreal | 14 | 7 | - +-----------------------------------+------------------------+------------------------+ - | BET Tropical | 35 | 1 | - +-----------------------------------+------------------------+------------------------+ - | BET temperate | 35 | 1 | - +-----------------------------------+------------------------+------------------------+ - | BDT tropical | 18 | 10 | - +-----------------------------------+------------------------+------------------------+ - | BDT temperate | 20 | 11.5 | - +-----------------------------------+------------------------+------------------------+ - | BDT boreal | 20 | 11.5 | - +-----------------------------------+------------------------+------------------------+ - | BES temperate | 0.5 | 0.1 | - +-----------------------------------+------------------------+------------------------+ - | BDS temperate | 0.5 | 0.1 | - +-----------------------------------+------------------------+------------------------+ - | BDS boreal | 0.5 | 0.1 | - +-----------------------------------+------------------------+------------------------+ - | C\ :math:`{}_{3}` arctic grass | 0.5 | 0.01 | - +-----------------------------------+------------------------+------------------------+ - | C\ :math:`{}_{3}` grass | 0.5 | 0.01 | - +-----------------------------------+------------------------+------------------------+ - | C\ :math:`{}_{4}` grass | 0.5 | 0.01 | - +-----------------------------------+------------------------+------------------------+ - | Crop R | 0.5 | 0.01 | - +-----------------------------------+------------------------+------------------------+ - | Crop I | 0.5 | 0.01 | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Corn R | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Corn I | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Temp Cereal R | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Temp Cereal I | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Winter Cereal R | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Winter Cereal I | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Soybean R | - | - | - +-----------------------------------+------------------------+------------------------+ - | :sup:`1`\ Soybean I | - | - | - +-----------------------------------+------------------------+------------------------+ - -:sup:`1`\ Determined by the crop model (Chapter :numref:`rst_Crops and Irrigation`) - .. _Phenology and vegetation burial by snow: Phenology and vegetation burial by snow diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst index 6a4ff5479d..ca7a4a9d2c 100644 --- a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst @@ -3,9 +3,9 @@ External Nitrogen Cycle =========================== -.. _Summary of CLM5.0 updates relative to the CLM4.5: +.. _Summary of CLM5.0 updates relative to CLM4.5: -Summary of CLM5.0 updates relative to the CLM4.5 +Summary of CLM5.0 updates relative to CLM4.5 ----------------------------------------------------- We describe external inputs to the nitrogen cycle in CLM5.0.  Much of the following information appeared in the CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `) as well as :ref:`Koven et al. (2013) `. diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 04d0a6a83c..626ac7ea56 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1278,8 +1278,7 @@ adjusted for canopy density following :ref:`Zeng and Wang (2007) ` d = z_{top} R_{d} V -where :math:`z_{top}` is canopy top height (m) -(:numref:`Table Prescribed plant functional type heights`), +where :math:`z_{top}` is canopy top height (m), :math:`R_{z0m}` and :math:`R_{d}` are the ratio of momentum roughness length and displacement height to canopy top height, respectively (:numref:`Table Plant functional type aerodynamic parameters`), and :math:`z_{0m,\, g}` diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 4d0883ac14..db3498f4e5 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -626,6 +626,7 @@ studies. Water Resour. Res. 35:583-587. .. _Gravenetal2017: Graven, H., C. E. Allison, D. M. Etheridge, S. Hammer, R. F. Keeling, I. Levin, H. A. J. Meijer, M. Rubino, P. P. Tans, C. M. Trudinger, B. H. Vaughn and J. W. C. White (2017) Compiled records of carbon isotopes in atmospheric CO2 for historical simulations in CMIP6, Geoscientific Model Development, in review. doi: 10.5194/gmd-2017-166. + .. _GrenfellWarren1999: Grenfell, T.C., and Warren, S.G. 1999. Representation of a nonspherical @@ -1745,6 +1746,12 @@ Siebert, S., Döll, P., Hoogeveen, J., Faures, J.M., Frenken, K., Feick, S., 2005. Development and validation of the global map of irrigation areas. Hydrol Earth Syst Sc 9:535–547 +.. _Simardetal2011: + +Simard, M., Pinto, N., Fisher, J.B., and Baccini, A. (2011), Mapping +forest canopy height globally with spaceborne lidar. +J. Geophys. Res., 116, G04021, doi:10.1029/2011JG001708. + .. _Simpsonetal1983: Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 2548b228fa..386cf77bd2 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -919,8 +919,9 @@ Snow aging is represented as evolution of the ice effective grain size (:math:`r_{e}`). Previous studies have shown that use of spheres which conserve the surface area-to-volume ratio (or specific surface area) of ice media composed of more complex shapes produces relatively -small errors in simulated hemispheric fluxes (e.g., :ref:`Grenfell and Warren -1999 `). Effective radius is the surface area-weighted mean +small errors in simulated hemispheric fluxes +(e.g., :ref:`Grenfell and Warren 1999 `). +Effective radius is the surface area-weighted mean radius of an ensemble of spherical particles and is directly related to specific surface area (*SSA*) as :math:`r_{e} ={3\mathord{\left/ {\vphantom {3 \left(\rho _{ice} SSA\right)}} \right. \kern-\nulldelimiterspace} \left(\rho _{ice} SSA\right)}` , From d3f1812297569444adb72ba1fb743f7c75ba18ba Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 20 Dec 2017 10:54:39 -0700 Subject: [PATCH 119/255] fix rsoil / canmx --- .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 2 +- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 46 ++++++++++++------- .../CLM50_Tech_Note_Introduction.rst | 2 +- 3 files changed, 32 insertions(+), 18 deletions(-) diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 04d0a6a83c..b7ee11cdc9 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1252,7 +1252,7 @@ and to update the soil surface fluxes (section .. math:: :label: 5.124 - \frac{\partial E_{g} }{\partial T_{g} } =\frac{\beta _{soi} \rho _{atm} }{r'_{aw} +r_{litter} } \frac{c_{a}^{w} +c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{g} }{dT_{g} } . + \frac{\partial E_{g} }{\partial T_{g} } = \rho _{atm} }{r'_{aw} +r_{soil} } \frac{c_{a}^{w} +c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{g} }{dT_{g} } . The partial derivatives :math:`\frac{\partial r'_{ah} }{\partial T_{g} }` and diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 8b9a9df144..a6c9936245 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -47,41 +47,54 @@ al. 2008) ` and :math:`\Delta t` is the time step (s). Canopy Water ---------------- -Liquid precipitation is either intercepted by the canopy, falls directly to the -snow/soil surface (throughfall), or drips off the vegetation (canopy -drip). Solid precipitation is treated similiar, with the addition of unloading of previously intercepted snow. +Liquid precipitation is either intercepted by the canopy, falls +directly to the snow/soil surface (throughfall), or drips off the +vegetation (canopy drip). Solid precipitation is treated similarly, +with the addition of unloading of previously intercepted snow. Interception by vegetation is divided between liquid and solid phases -:math:`q_{intr,\,liq}` and :math:`q_{intr,\,ice}` (kg m\ :sup:`-2` s\ :sup:`-1`) +:math:`q_{intr,\,liq}` and :math:`q_{intr,\,ice}` +(kg m\ :sup:`-2` s\ :sup:`-1`) .. math:: :label: 7.2 - q_{intr,\,liq} =\alpha_{liq} q_{rain} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + q_{intr,\,liq} = f_{pi,\,liq} q_{rain} .. math:: :label: 7.3 - q_{intr,\,ice} =\alpha_{sno} q_{sno} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} + q_{intr,\,ice} = f_{pi,\,ice} q_{sno} - -where :math:`L` and :math:`S` are the exposed leaf and stem area index, +where :math:`f_{pi,\,liq}` and :math:`f_{pi,\,ice}` are the +fractions of intercepted precipitation of rain and snow, +respectively + +.. math:: + :label: 7.2b + + f_{pi,\,liq} = \alpha_{liq} \ tanh \left(L+S\right) + +.. math:: + :label: 7.3b + + f_{pi,\,ice} =\alpha_{sno} \ \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} \ , +and :math:`L` and :math:`S` are the exposed leaf and stem area index, respectively (section :numref:`Phenology and vegetation burial by snow`), and the :math:`\alpha`\'s scale the fractional area of a leaf that collects water -(:ref:`Lawrence et al. 2007 `). Values of -:math:`\alpha_{liq} = 0.25` and :math:`\alpha_{sno} = 1` reflect the increased -capacity one side of a leaf has for snow than liquid water. +(:ref:`Lawrence et al. 2007 `). Default values of +:math:`\alpha_{liq}` and :math:`\alpha_{sno}` are set to 1. Throughfall (kg m\ :sup:`-2` s\ :sup:`-1`) is also divided into liquid and solid phases, reaching the ground (soil or snow surface) as .. math:: :label: 7.4 - q_{thru,\, liq} =q_{rain} \left[1-\alpha_{liq} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right] + q_{thru,\, liq} = q_{rain} \left(1 - f_{pi,\,liq}\right) .. math:: :label: 7.5 - q_{thru,\, ice} =q_{sno} \left[1-\alpha_{sno} \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\}\right]. + q_{thru,\, ice} = q_{sno} \left(1 - f_{pi,\,ice}\right) Similarly, the liquid and solid canopy drip fluxes are @@ -126,8 +139,9 @@ They are defined by W_{can,\,sno}^{max } =p_{ice}\left(L+S\right). -The maximum storage of liquid water is :math:`p_{liq}=0.1` kg m\ :sup:`-2` (:ref:`Dickinson et al. -1993 `), and that of snow is :math:`p_{sno}=6`, consistent with reported +The maximum storage of liquid water is :math:`p_{liq}=0.1` kg m\ :sup:`-2` +(:ref:`Dickinson et al. 1993 `), and that of snow +is :math:`p_{sno}=6` kg m\ :sup:`-2`, consistent with reported field measurements (:ref:`Pomeroy et al. 1998 `). Canopy snow unloading from wind speed :math:`u` and above-freezing temperatures are modeled from linear @@ -1143,7 +1157,7 @@ exist within the soil column. Sub-surface runoff is .. math:: :label: 7.168 - q_{subsurface} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) + q_{drai} = \Theta_{ice} K_{baseflow} tan \left( \beta \right) \Delta z_{sat}^{N_{baseflow}} \ , where :math:`K_{baseflow}` is a calibration parameter, :math:`\beta` is the diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index f71aed9712..794a829005 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -592,7 +592,7 @@ processes simulated include (:numref:`Figure Land processes`): #. Stomatal physiology, photosythetic capacity, and photosynthesis (Chapters :numref:`rst_Stomatal Resistance and Photosynthesis` and :numref:`rst_Photosynthetic Capacity`) -#. Plant hydraulics (Chapter :numref: `rst_Plant Hydraulics`) +#. Plant hydraulics (Chapter :numref:`rst_Plant Hydraulics`) #. Lake temperatures and fluxes (Chapter :numref:`rst_Lake Model`) From 6204b1aa0f9ef96c6e3add59e97f05256cc6008a Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 20 Dec 2017 10:57:30 -0700 Subject: [PATCH 120/255] fix rsoil / canmx --- .../tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst | 3 +-- doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst | 4 ++-- doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 4 ++-- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 4db8909b42..f3613a78a6 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -137,7 +137,7 @@ favorable growth environments (Allen et al., 2005; Vanninen and Makela, .. table:: Allocation and target carbon\:nitrogen ratio parameters +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ - | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`Target CN_{leaf}` | :math:`Target CN_{fr}` | :math:`Target CN_{lw}` | :math:`Target CN_{dw}` | + | Plant functional type | :math:`a_{1}` | :math:`a_{2}` | :math:`a_{3}` | :math:`a_{4}` | :math:`Target CN_{leaf}` | :math:`Target CN_{fr}` | :math:`Target CN_{lw}` | :math:`Target CN_{dw}` | +==================================+=======================+=======================+=======================+=======================+===========================+=========================+=========================+=========================+ | NET Temperate | 1 | 0.3 | -1 | 0.1 | 35 | 42 | 50 | 500 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ @@ -160,7 +160,6 @@ favorable growth environments (Allen et al., 2005; Vanninen and Makela, | BDS temperate | 1 | 0.3 | 0.2 | 0.5 | 25 | 42 | 50 | 500 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ | BDS boreal | 1 | 0.3 | 0.2 | 0.1 | 25 | 42 | 50 | 500 | - +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ | C\ :sub:`3` arctic grass | 1 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | +----------------------------------+-----------------------+-----------------------+-----------------------+-----------------------+---------------------------+-------------------------+-------------------------+-------------------------+ | C\ :sub:`3` grass | 2 | 0 | 0 | 0 | 25 | 42 | 0 | 0 | diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index b7ee11cdc9..95214580b4 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1247,12 +1247,12 @@ and to update the soil surface fluxes (section .. math:: :label: 5.123 - \frac{\partial H_{g} }{\partial T_{g} } =\frac{\rho _{atm} C_{p} }{r'_{ah} } \frac{c_{a}^{h} +c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } + \frac{\partial H_{g} }{\partial T_{g} } = \frac{\rho _{atm} C_{p} }{r'_{ah} } \frac{c_{a}^{h} +c_{v}^{h} }{c_{a}^{h} +c_{v}^{h} +c_{g}^{h} } .. math:: :label: 5.124 - \frac{\partial E_{g} }{\partial T_{g} } = \rho _{atm} }{r'_{aw} +r_{soil} } \frac{c_{a}^{w} +c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{g} }{dT_{g} } . + \frac{\partial E_{g} }{\partial T_{g} } = \frac{\rho _{atm} }{r'_{aw} +r_{soil} } \frac{c_{a}^{w} +c_{v}^{w} }{c_{a}^{w} +c_{v}^{w} +c_{g}^{w} } \frac{dq_{g} }{dT_{g} } . The partial derivatives :math:`\frac{\partial r'_{ah} }{\partial T_{g} }` and diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index a6c9936245..2ca572ee9e 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -58,12 +58,12 @@ Interception by vegetation is divided between liquid and solid phases .. math:: :label: 7.2 - q_{intr,\,liq} = f_{pi,\,liq} q_{rain} + q_{intr,\,liq} = f_{pi,\,liq} \ q_{rain} .. math:: :label: 7.3 - q_{intr,\,ice} = f_{pi,\,ice} q_{sno} + q_{intr,\,ice} = f_{pi,\,ice} \ q_{sno} where :math:`f_{pi,\,liq}` and :math:`f_{pi,\,ice}` are the fractions of intercepted precipitation of rain and snow, From e7cc6e3c7030df7989cc9f6e74b199893e5cd760 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 20 Dec 2017 11:02:59 -0700 Subject: [PATCH 121/255] fix rsoil / canmx --- .../CLM50_Tech_Note_CN_Allocation.rst | 89 +++++++++++++------ .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 3 +- 2 files changed, 63 insertions(+), 29 deletions(-) diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index 8bc3991dea..f3613a78a6 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -3,26 +3,29 @@ Carbon and Nitrogen Allocation ============================== -Summary of CLM5.0 updates relative to the CLM4.5 ------------------------------------------------------ -- CLM5 now defaults to a static allocation to woody biomass rather than the dynamic allocation term used in CLM4.5. The dynamic allocation is stil lkept as an option, for details, see the CLM4.5 Tech Note. - -- CLM5 now includes flexible C:N ratios of all plant tissues, which allows allocation of carbon to occur separately from allocation of nitrogen, thus removing the requirement to downregulate photosynthesis based on the instantaneous stoichiometric needs of allocation. - -- CLM5 accounts for the carbon expenditure on nitrogen aquisition, as determined by the FUN model, and the N uptake it determined by the environmental cost of Nitrogen from fixation, active uptake and retranslocation. - - Introduction ----------------- -The carbon and nitrogen allocation routines in CLM determine the fate of newly assimilated carbon, and absorbed nitrogen. The environmental cost of nitrogen estimated by the FUN model modulates the C:N ratios of the plant tissue pools around a target ratio, and absorbed nitrogen is allocated in proportion to the demand, as estimated by the ideal requirements of these target C:N ratios. +The carbon and nitrogen allocation routines in CLM determine the fate of +newly assimilated carbon, coming from the calculation of photosynthesis, +and available mineral nitrogen, coming from plant uptake of mineral +nitrogen in the soil or being drawn out of plant reserves. A significant change to CLM5 relative to prior versions is that allocation of carbon and nitrogen proceed independently rather than in a sequential manner. -Carbon Allocation to Cover Prior-Timestep Maintenance Respiration Costs ("Excess" Respiration) ----------------------------------------------------------------------------------------------- +Carbon Allocation for Maintenance Respiration Costs +-------------------------------------------------------- -After respiration of live tissues (Chapter :numref:`rst_Plant Respiration`), the next priority of the carbon allocation cascade is to replenish the plant carbon deficit pool that balances maintenance respiration that occurs during times when maintenance respiration exceeds photosynthesis (e.g. at night, during winter for perennial vegetation, or during periods of drought stress) (Sprugel et al., 1995). +Allocation of available carbon on each time step is prioritized, with +first priority given to the demand for carbon to support maintenance +respiration of live tissues (section 13.7). Second priority is to +replenish the internal plant carbon pool that supports maintenance +respiration during times when maintenance respiration exceeds +photosynthesis (e.g. at night, during winter for perennial vegetation, +or during periods of drought stress) (Sprugel et al., 1995). Third +priority is to support growth of new tissues, including allocation to +storage pools from which new growth will be displayed in subsequent time +steps. The total maintenance respiration demand (:math:`CF_{mr}`, gC m\ :sup:`-2` s\ :sup:`-1`) is calculated as a function of @@ -89,19 +92,16 @@ Carbon and Nitrogen Stoichiometry of New Growth ---------------------------------------------------- After accounting for the carbon cost of maintenance respiration, the -remaining carbon flux from photosynthesis which is allocated either to new -growth or to nitrogen acquisition processes (Chapter :numref:`rst_FUN`), (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is +remaining carbon flux from photosynthesis which can be allocated to new +growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: :label: 19.6 CF_{avail\_ alloc} =CF_{GPP} -CF_{GPP,mr} -CF_{GPP,xs} . - -The FUN model requires an estimate of the C:N requirements of the existing plant structure, given that different relative quantities of wood, root and leaf biomass will result in different necessary C:N ratios for expansion. - -These C and N allocation ratios are calculated for all of the plant -carbon and nitrogen state variables based on target C:N ratios for +Potential allocation to new growth is calculated for all of the plant +carbon and nitrogen state variables based on specified C:N ratios for each tissue type and allometric parameters that relate allocation between various tissue types. The allometric parameters are defined as follows: @@ -116,6 +116,21 @@ Parameters :math:`a_{1}`, :math:`a_{2}`, and :math:`a_{4}` are defined as consta constant for all PFTs, based on construction costs for a range of woody and non-woody tissues (Larcher, 1995). +The model includes a dynamic allocation scheme for woody vegetation +(parameter :math:`a_{3}` = -1, :numref:`Table Allocation and CN ratio parameters`), in which case the +ratio for carbon allocation between new stem and new leaf increases with +increasing net primary production (NPP), as + +.. math:: + :label: 19.8 + + a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 + +where :math:`NPP_{ann}` is the annual sum of NPP from the previous +year. This mechanism has the effect of increasing woody allocation in +favorable growth environments (Allen et al., 2005; Vanninen and Makela, +2005) and during the phase of stand growth prior to canopy closure +(Axelsson and Axelsson, 1986). .. _Table Allocation and CN ratio parameters: @@ -183,14 +198,17 @@ follows: where all C:N parameters are defined as constants for a given PFT (:numref:`Table Allocation and CN ratio parameters`). - -The target C:N stoichiometry for new growth allocation can be calculated as +Given values for the parameters in and , total carbon and nitrogen +allocation to new growth ( :math:`CF_{alloc}`, gC +m\ :sup:`-2` s\ :sup:`-1`, and :math:`NF_{alloc}`, gN +m\ :sup:`-2` s\ :sup:`-1`, respectively) can be expressed as +functions of new leaf carbon allocation (:math:`CF_{GPP,leaf}`, gC +m\ :sup:`-2` s\ :sup:`-1`): .. math:: - :label: 19.13 - - CN_{plant\_ target} =\frac{N_{allom} }{C_{allom} } . + :label: 19.10 + \begin{array}{l} {CF_{alloc} =CF_{GPP,leaf} {\kern 1pt} C_{allom} } \\ {NF_{alloc} =CF_{GPP,leaf} {\kern 1pt} N_{allom} } \end{array} where @@ -204,7 +222,16 @@ where N_{allom} =\left\{\begin{array}{l} {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } +\frac{a_{3} a_{4} \left(1+a_{2} \right)}{CN_{lw} } +} \\ {\qquad \frac{a_{3} \left(1-a_{4} \right)\left(1+a_{2} \right)}{CN_{dw} } \qquad {\rm for\; woody\; PFT}} \\ {\frac{1}{CN_{leaf} } +\frac{a_{1} }{CN_{fr} } \qquad \qquad \qquad {\rm for\; non-woody\; PFT.}} \end{array}\right. +Since the C:N stoichiometry for new growth allocation is defined, from +Eq. , as :math:`C_{allom}`/ :math:`N_{allom}`, the total carbon available for new growth allocation +(:math:`CF_{avail\_alloc}`) can be used to calculate the total +plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, +gN m\ :sup:`-2` s\ :sup:`-1`) as: + +.. math:: + :label: 19.13 + NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . Carbon Allocation to New Growth ----------------------------------------- @@ -285,8 +312,14 @@ tissue types are given as: Nitrogen allocation ----------------------------------------- -The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{uptake}`. This is distribution in proportion to the demand for N from different tissues, calculated as: +The total flux of nitrogen to be allocated is given by the FUN model (Chapter :numref:`rst_FUN`). This gives a total N to be allocated within a given timestep, :math:`N_{supply}`. The total N allocated for a given tissue :math:`i` is the minimum between the supply and the demand: + +.. math:: + :label: 19.26 + + NF_{alloc,i} = min \left( NF_{demand, i}, NF_{supply, i} \right) +The demand for each tissue, calculated for the tissue to remain on stoichiometry during growth, is: .. math:: :label: 19.27 @@ -348,14 +381,14 @@ The total flux of nitrogen to be allocated is given by the FUN model (Chapter :n NF_{demand,deadcroot\_ stor} \_ =\frac{CF_{alloc,leaf} a_{2} a_{3} \left(1-a_{4} \right)}{CN_{dw} } \left(1-f_{cur} \right). -After each pool's demand is calculated, the total plant N demand is then the sum of each individual pool :math:`i` corresponding to each tissue: +After each pool's demand is calculated, the total plant N demand is then the sum of each individual pool :math: `i` corresponding to each tissue: .. math:: :label: 19.39 NF_{demand,tot} = \sum _{i=tissues} NF_{demand,i} -and the total supply for each tissue :math:`i` is the product of the fractional demand and the total available N, calculated as the term :math:`N_{uptake}` equal to the sum of the eight N uptake streams described in the FUN model (Chapter :numref:`rst_FUN`). +and the total supply for each tissue :math: `i` is the product of the fractional demand and the total available N, calculated as the term :math: `N_{uptake}` equal to the sum of the eight N uptake streams described in the FUN model (Chapter :numref:`rst_FUN`). .. math:: :label: 19.40 diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 9eb2b19ba2..95214580b4 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1278,7 +1278,8 @@ adjusted for canopy density following :ref:`Zeng and Wang (2007) ` d = z_{top} R_{d} V -where :math:`z_{top}` is canopy top height (m), +where :math:`z_{top}` is canopy top height (m) +(:numref:`Table Prescribed plant functional type heights`), :math:`R_{z0m}` and :math:`R_{d}` are the ratio of momentum roughness length and displacement height to canopy top height, respectively (:numref:`Table Plant functional type aerodynamic parameters`), and :math:`z_{0m,\, g}` From e4abfbc48fd3cf30c055fbc536d0221811406a61 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Wed, 20 Dec 2017 11:37:10 -0700 Subject: [PATCH 122/255] Update html --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 -- doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 2c11d56ba5..723e8bf032 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -83,8 +83,6 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Plant functional types` Plant functional types -- :numref:`Table Prescribed plant functional type heights` Prescribed plant functional type heights - - :numref:`Table Soil layer structure` Soil layer structure - :numref:`Table Atmospheric input to land model` Atmospheric input to land model diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 4a6192aacb..e24ac723ea 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -120,7 +120,7 @@ resolution. Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section :numref:`Atmospheric Coupling`). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. -The urban model that was first lreleased as a component of CLM4.0 is separately +The urban model that was first released as a component of CLM4.0 is separately described in the urban technical note (:ref:`Oleson et al. (2010b) `). The main changes in the urban model from CLM4.0 to CLM4.5 were 1) an expansion of the single urban landunit to up to three landunits per From 841b2d947983bb1d3b89e62477c8a71a93ebc7b2 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Wed, 3 Jan 2018 17:18:51 -0700 Subject: [PATCH 123/255] Updates to Introduction and Chapter 2 --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 45 ++++++------------- .../CLM50_Tech_Note_Introduction.rst | 6 ++- 2 files changed, 18 insertions(+), 33 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 6d36046e41..8a6d9890b0 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -31,9 +31,9 @@ The second subgrid level, the column, is intended to capture potential variability in the soil and snow state variables within a single land unit. For example, the vegetated land unit could contain several columns with independently evolving vertical profiles of soil water and -temperature. Similarly, the managed vegetation land unit could be -divided into two columns, irrigated and non-irrigated. The snow/soil -column is represented by fifteen layers for soil and up to five layers +temperature. Similarly, the managed vegetation land unit can be +divided into two columns, irrigated and non-irrigated. The default snow/soil +column is represented by 25 layers for ground (with up to 20 of these layers classified as soil layers and the remaining layers classified as bedrock layers) and up to 10 layers for snow, depending on snow depth. The central characteristic of the column subgrid level is that this is where the state variables for water and energy in the soil and snow are defined, as well as the fluxes of @@ -52,23 +52,19 @@ impervious canyon floor) (Oleson et al. 2010b). .. Figure:: image1.png - Configuration of the CLM subgrid hierarchy. + Configuration of the CLM subgrid hierarchy. Box in upper right shows hypothetical subgrid distribution for a single grid cell. Note that the Crop land unit is only used when the model is run with the crop model active. Abbreviations: TBD – Tall Building District; HD – High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – Crop, V – Vegetated, PFT – Plant Functional Type, Irr – Irrigated, UIrr – Unirrigated. Red arrows indicate allowed land unit transitions. Purple arrows indicate allowed patch-level transitions. -Note that the Crop land unit is only used when the model is run with the -crop model active. Abbreviations: TBD – Tall Building District; HD – -High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – -Crop, V – Vegetated, PFT – Plant Functional Type, I – Irrigated, U – -Unirrigated . - -The third subgrid level is referred to as the PFT level, but it also -includes the treatment for bare ground. It is intended to capture the +The third subgrid level is referred to as the patch level. Patches can be PFTs or bare ground on the vegetated land unit +and crop functional types (CFTs) on the crop land unit. +The patch level is intended to capture the biogeophysical and biogeochemical differences between broad categories of plants in terms of their functional characteristics. On the vegetated land unit, up to 16 possible PFTs that differ in physiology and structure may coexist on a single column. All fluxes to and from the surface are defined at the PFT level, as are the vegetation state variables (e.g. vegetation temperature and canopy water storage). On the -crop land unit, several different crop types can be represented on each +crop land unit, typically, different crop types can be represented on each + crop land unit column (see Chapter :numref:`rst_Crops and Irrigation` for details). In addition to state and flux variable data structures for conserved @@ -156,30 +152,17 @@ evolve with time if the model is run in transient landcover mode +--------------------------------------------------------------+-------------------+ | C\ :sub:`4` grass | - | +--------------------------------------------------------------+-------------------+ - | C\ :sub:`3` Unmanaged Rainfed Crop | Crop R | - +--------------------------------------------------------------+-------------------+ - | :sup:`1`\ C\ :sub:`3` Unmanaged Irrigated Crop | Crop I | - +--------------------------------------------------------------+-------------------+ - | :sup:`2`\ Rainfed Corn | Corn R | - +--------------------------------------------------------------+-------------------+ - | :sup:`2`\ Irrigated Corn | Corn I | - +--------------------------------------------------------------+-------------------+ - | :sup:`2`\ Rainfed Temperate Cereals | Temp Cereal R | - +--------------------------------------------------------------+-------------------+ - | :sup:`2`\ Irrigated Temperate Cereals | Temp Cereal I | - +--------------------------------------------------------------+-------------------+ - | :sup:`3`\ Rainfed Winter Cereals | Winter Cereal R | + | C\ :sub:`3` Unmanaged Rainfed Crop | UCrop UIrr | +--------------------------------------------------------------+-------------------+ - | :sup:`3`\ Irrigated Winter Cereals | Winter Cereal I | + | :sup:`1`\ C\ :sub:`3` Unmanaged Irrigated Crop | UCrop Irr | +--------------------------------------------------------------+-------------------+ - | :sup:`2`\ Rainfed Soybean | Soybean R | + | :sup:`2`\ Managed Rainfed Unirrigated Crops | Crop UIrr | +--------------------------------------------------------------+-------------------+ - | :sup:`2`\ Irrigated Soybean | Soybean I | + | :sup:`2`\ Managed Irrigated Crops | Crop Irr | +--------------------------------------------------------------+-------------------+ :sup:`1`\ Only used if irrigation is active (Chapter :numref:`rst_Crops and Irrigation`). -:sup:`2`\ Only used if crop model is active (Chapter :numref:`rst_Crops and Irrigation`). -:sup:`3`\ Reserved for future implementations of crop model (Chapter :numref:`rst_Crops and Irrigation`). +:sup:`2`\ Only used if crop model is active (see Chapter :numref:`rst_Crops and Irrigation` for list of represented crops). .. _Vegetation Structure: diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 723e8bf032..3892e7729a 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -528,7 +528,7 @@ Nitrogen for Assimilation (LUNA, :ref:`Xu et al., 2012` and :ref:`Al photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that light capture, carboxylation, and respiration are co-limiting. -CLM5 applies a fixed allocation scheme for woody vegetation. The decision to use a fixed allocation scheme in CLM5, rather than a dynamic allocation scheme based on NPP as was used in CLM4 and CLM4.5, was driven by the fact that observations indicate that biomass saturates with increasing productivity, in contrast to the behavior in CLM4 and CLM4.5 where biomass continuously increases with increasing productivity (:ref:`Negron-Juarez et al., 2015`). Soil carbon decomposition processes are unchanged in CLM5, but a new metric for apparent soil carbon turnover times (:ref:`Koven et al., 2017 `) suggested parameter changes that produce a weak intrinsic depth limitation on soil carbon turnover rates (rather than the strong depth limitaiton in CLM4.5) and that the thresholds for soil moisture limitation on soil carbon turnover rates in dry soils should be set at a wetter soil moisture level than that used in CLM4.5. +CLM5 applies a fixed allocation scheme for woody vegetation. The decision to use a fixed allocation scheme in CLM5, rather than a dynamic NPP-based allocation scheme, as was used in CLM4 and CLM4.5, was driven by the fact that observations indicate that biomass saturates with increasing productivity, in contrast to the behavior in CLM4 and CLM4.5 where biomass continuously increases with increasing productivity (:ref:`Negron-Juarez et al., 2015`). Soil carbon decomposition processes are unchanged in CLM5, but a new metric for apparent soil carbon turnover times (:ref:`Koven et al., 2017 `) suggested parameter changes that produce a weak intrinsic depth limitation on soil carbon turnover rates (rather than the strong depth limitaiton in CLM4.5) and that the thresholds for soil moisture limitation on soil carbon turnover rates in dry soils should be set at a wetter soil moisture level than that used in CLM4.5. Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016)`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. Fertilization rates and irrigation equipped area updated annually based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that @@ -540,7 +540,9 @@ is incorporated. The fire model is the same as utilized in CLM4.5 except that a modified scheme is used to estimate the dependence of fire occurrence and spread on fuel wetness for non-peat fires outside cropland and tropical closed forests :ref:`(Li and Lawrence, 2017)` and the dependence of agricultural fires on fuel load is removed. -Included with the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, :ref:`Fisher et al., 2015)`. A major motivation of this development is to allow the prediction of biome boundaries directly from plant physiological traits via their competitive interactions. The version of CLM5-FATES that is supported in this release is described here??? Short blurb on what FATES can do??? Note that the classical dynamic global vegetation model (DGVM) that has been available within CLM4 and CLM4.5 remains available, though it is largely untested. The technical description of the CLM-DGVM can be found within the CLM4.5 Technical Description (:ref:`Oleson et al. 2013)`. +Included with the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, :ref:`Fisher et al., 2015)`. A major motivation of FATES is to allow the prediction of biome boundaries directly from plant physiological traits via their competitive interactions. FATES is a cohort model of vegetation competition and co-existence, allowing a representation of the biosphere which accounts for the division of the land surface into successional stages, and for competition for light between height structured cohorts of representative trees of various plant functional types. FATES is not active by default in CLM5.0. + +Note that the classical dynamic global vegetation model (CLM-DGVM) that has been available within CLM4 and CLM4.5 remains available, though it is largely untested. The technical description of the CLM-DGVM can be found within the CLM4.5 Technical Description (:ref:`Oleson et al. 2013)`. During the course of the development of CLM5.0, it became clear that the increasing complexity of the model combined with the increasing number and range of model development projects required updates to the underlying CLM infrastructure. Many such software improvements From 67b529bda1d4eba92769b3f0700cf4b3bfe28559 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 11 Jan 2018 16:37:12 -0700 Subject: [PATCH 124/255] Canopy top and bottom heights --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 32 ++++++++++++++++++- .../CLM50_Tech_Note_Introduction.rst | 2 ++ 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 8a6d9890b0..6463e9d255 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -174,11 +174,41 @@ Vegetation structure is defined by leaf and stem area indices Separate leaf and stem area indices and canopy heights are prescribed or calculated for each PFT. Daily leaf and stem area indices are obtained from griddeddatasets of monthly values (section -:numref:`Surface Data`). Canopy top and bottom heights are from ICESat (:ref:`Simard et al. (2011) `. +:numref:`Surface Data`). Canopy top and bottom heights for trees are from ICESat (:ref:`Simard et al. (2011) `). +Canopy top and bottom heights for short vegetation are obtained from gridded datasets but are invariant in space +and time and were obtained from PFT-specific values (:ref:`Bonan et al. (2002a) `) (:numref:`Table Plant functional type canopy top and bottom heights`). When the biogeochemistry model is active, vegetation state (LAI, SAI, canopy top and bottom heights) are calculated prognostically (see Chapter :numref:`rst_Vegetation Phenology and Turnover`). +.. _Table Plant functional type canopy top and bottom heights: + +.. table:: Plant functional type canopy top and bottom heights + + +--------------------------------------------------------------+-------------------+-------------------+ + | Plant functional type | :math:`z_{top}` | :math:`z_{bot}` | + +==============================================================+===================+===================+ + | BES Temperate | 0.5 | 0.1 | + +--------------------------------------------------------------+-------------------+-------------------+ + | BDS Temperate | 0.5 | 0.1 | + +--------------------------------------------------------------+-------------------+-------------------+ + | BDS Boreal | 0.5 | 0.1 | + +--------------------------------------------------------------+-------------------+-------------------+ + | C\ :sub:`3` arctic grass | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + | C\ :sub:`3` grass | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + | C\ :sub:`4` grass | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + | UCrop UIrr | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + | UCrop Irr | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + | Crop UIrr | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + | Crop Irr | 0.5 | 0.01 | + +--------------------------------------------------------------+-------------------+-------------------+ + .. _Phenology and vegetation burial by snow: Phenology and vegetation burial by snow diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 3892e7729a..3024441363 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -83,6 +83,8 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Plant functional types` Plant functional types +- :numref:`Table Plant functional type canopy top and bottom heights` Plant functional type canopy top and bottom heights + - :numref:`Table Soil layer structure` Soil layer structure - :numref:`Table Atmospheric input to land model` Atmospheric input to land model From a5ae98e2f9cd0254db5241a30e8617817cbdf5ff Mon Sep 17 00:00:00 2001 From: mvertens Date: Tue, 16 Jan 2018 11:27:54 -0700 Subject: [PATCH 125/255] changes for getting a pdf file to work correctly --- doc/source/conf.py | 9 +- doc/source/index.rst | 12 +- .../CLM50_Tech_Note_CN_Allocation.rst | 35 +- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 1 - .../tech_note/Fire/CLM50_Tech_Note_Fire.rst | 2 +- .../CLM50_Tech_Note_Introduction.rst | 164 ++- .../References/CLM50_Tech_Note_References.rst | 941 ++++++++++++++++-- doc/source/tech_note/index.rst | 1 - doc/source/users_guide/index.rst | 1 - .../users_guide/overview/introduction.rst | 129 +-- 10 files changed, 1041 insertions(+), 254 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 2d69cb46bd..a866c7f3fb 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -120,7 +120,9 @@ # Additional stuff for the LaTeX preamble. # - # 'preamble': '', + 'preamble': '\\usepackage{hyperref}', + + 'fncychap': '\\usepackage[Conny]{fncychap}', # Latex figure (float) alignment # @@ -130,10 +132,7 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'clmdoc.tex', u'clmdoc Documentation', - u'Erik Kluzek, Bill Sacks, Ben Andre', 'manual'), -] +latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),] # -- Options for manual page output --------------------------------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index cc7ec3c27c..f7f35abeda 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,16 +6,12 @@ Welcome to the CLM documentation ================================== -This document has one major sections. - -The :ref:`CLM user's guide ` is a basic guide in utilizing CLM. - -Table of contents ------------------ +This document has two major sections. .. toctree:: - :maxdepth: 1 - + :maxdepth: 2 + :numbered: + users_guide/index.rst tech_note/index.rst diff --git a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst index f3613a78a6..25b2215e81 100644 --- a/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst +++ b/doc/source/tech_note/CN_Allocation/CLM50_Tech_Note_CN_Allocation.rst @@ -38,17 +38,17 @@ photosynthesis ( :math:`CF_{xs,mr}`, gC m\ :sup:`-2` s\ :sup:`-1`): .. math:: - :label: 19.1 + :label: 19.1 CF_{mr} =CF_{GPP,mr} +CF_{xs,mr} .. math:: - :label: 19.2 + :label: 19.2 CF_{GPP,mr} =\_ \left\{\begin{array}{l} {CF_{mr} \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPP} } \\ {CF_{GPP} \qquad {\rm for\; }CF_{mr} >CF_{GPP} } \end{array}\right. .. math:: - :label: 19.3 + :label: 19.3 CF_{xs,mr} =\_ \left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CF_{mr} \le CF_{GPP} } \\ {CF_{mr} -CF_{GPP} \qquad {\rm for\; }CF_{mr} >CF_{GPP} } \end{array}\right. @@ -72,12 +72,12 @@ flux to :math:`CS_{xs}` (:math:`CF_{GPP,xs}`, gC m\ :sup:`-2` s\ :sup:`-1`) is given as .. math:: - :label: 19.4 + :label: 19.4 CF_{GPP,xs,pot} =\left\{\begin{array}{l} {0\qquad \qquad \qquad {\rm for\; }CS_{xs} \ge 0} \\ {-CS_{xs} /(86400\tau _{xs} )\qquad {\rm for\; }CS_{xs} <0} \end{array}\right. .. math:: - :label: 19.5 + :label: 19.5 CF_{GPP,xs} =\left\{\begin{array}{l} {CF_{GPP,xs,pot} \qquad \qquad \qquad {\rm for\; }CF_{GPP,xs,pot} \le CF_{GPP} -CF_{GPP,mr} } \\ {\max (CF_{GPP} -CF_{GPP,mr} ,0)\qquad {\rm for\; }CF_{GPP,xs,pot} >CF_{GPP} -CF_{GPP,mr} } \end{array}\right. @@ -96,7 +96,7 @@ remaining carbon flux from photosynthesis which can be allocated to new growth (:math:`CF_{avail}`, gC m\ :sup:`-2` s\ :sup:`-1`) is .. math:: - :label: 19.6 + :label: 19.6 CF_{avail\_ alloc} =CF_{GPP} -CF_{GPP,mr} -CF_{GPP,xs} . @@ -122,7 +122,7 @@ ratio for carbon allocation between new stem and new leaf increases with increasing net primary production (NPP), as .. math:: - :label: 19.8 + :label: 19.8 a_{3} =\frac{2.7}{1+e^{-0.004NPP_{ann} -300} } -0.4 @@ -195,7 +195,7 @@ follows: \begin{array}{l} {CN_{leaf} =\_ {\rm \; C:N\; for\; leaf}} \\ {CN_{fr} =\_ {\rm \; C:N\; for\; fine\; root}} \\ {CN_{lw} =\_ {\rm \; C:N\; for\; live\; wood\; (in\; stem\; and\; coarse\; root)}} \\ {CN_{dw} =\_ {\rm \; C:N\; for\; dead\; wood\; (in\; stem\; and\; coarse\; root)}} \end{array} -where all C:N parameters are defined as constants for a given PFT +where all C:N parameters are defined as constants for a given PFT (:numref:`Table Allocation and CN ratio parameters`). Given values for the parameters in and , total carbon and nitrogen @@ -213,7 +213,7 @@ m\ :sup:`-2` s\ :sup:`-1`): where .. math:: - :label: 19.11 + :label: 19.11 \begin{array}{l} {C_{allom} =\left\{\begin{array}{l} {\left(1+g_{1} \right)\left(1+a_{1} +a_{3} \left(1+a_{2} \right)\right)\qquad {\rm for\; woody\; PFT}} \\ {1+g_{1} +a_{1} \left(1+g_{1} \right)\qquad \qquad {\rm for\; non-woody\; PFT}} \end{array}\right. } \\ {} \end{array} @@ -229,7 +229,7 @@ plant nitrogen demand for new growth ( :math:`NF_{plant\_demand}`, gN m\ :sup:`-2` s\ :sup:`-1`) as: .. math:: - :label: 19.13 + :label: 19.13 NF_{plant\_ demand} =CF_{avail\_ alloc} \frac{N_{allom} }{C_{allom} } . @@ -248,22 +248,22 @@ storage pools (where storage is indicated with *\_stor*) for the various tissue types are given as: .. math:: - :label: 19.14 + :label: 19.14 CF_{alloc,leaf} \_ =CF_{alloc,leaf\_ tot} f_{cur} .. math:: - :label: 19.15 + :label: 19.15 CF_{alloc,leaf\_ stor} \_ =CF_{alloc,leaf\_ tot} \left(1-f_{cur} \right) .. math:: - :label: 19.16 + :label: 19.16 CF_{alloc,froot} \_ =CF_{alloc,leaf\_ tot} a_{1} f_{cur} .. math:: - :label: 19.17 + :label: 19.17 CF_{alloc,froot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{1} \left(1-f_{cur} \right) @@ -308,7 +308,7 @@ tissue types are given as: CF_{alloc,deadcroot\_ stor} \_ =CF_{alloc,leaf\_ tot} a_{2} a_{3} \left(1-a_{4} \right)\left(1-f_{cur} \right). - + Nitrogen allocation ----------------------------------------- @@ -320,7 +320,7 @@ The total flux of nitrogen to be allocated is given by the FUN model (Chapter :n NF_{alloc,i} = min \left( NF_{demand, i}, NF_{supply, i} \right) The demand for each tissue, calculated for the tissue to remain on stoichiometry during growth, is: - + .. math:: :label: 19.27 @@ -394,6 +394,3 @@ and the total supply for each tissue :math: `i` is the product of the fractional :label: 19.40 NF_{alloc,i} = N_{uptake} NF_{demand,i} / NF_{demand,tot} - - - diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 45953fdca8..170d44eb7a 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -3515,7 +3515,6 @@ within the area affected by fire is a function of the ratio between .. raw:: latex - \printbibliography .. [1] This description covers algorithms in the ‘fuse_cohorts’ subroutine. diff --git a/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst b/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst index caef87c2b3..912bc7e378 100644 --- a/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst +++ b/doc/source/tech_note/Fire/CLM50_Tech_Note_Fire.rst @@ -192,7 +192,7 @@ Average spread area of a fire Fire fighting capacity depends on socioeconomic conditions and affects fire spread area. Due to a lack of observations, we consider the socioeconomic impact on the average burned area rather than separately -on fire spread rate and fire duration： +on fire spread rate and fire duration: .. math:: :label: 23.14 diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 3024441363..339ec3d05f 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -1,5 +1,3 @@ - - **July 2017** **Technical Description of version 5.0 of the Community Land Model @@ -15,7 +13,7 @@ ***Contributing Authors*** -**Ben Andre, Ali Ashehad, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, +**Ben Andre, Ali Ashehad, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Andrew Slater, Zachary M. Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** @@ -35,21 +33,21 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). -- :numref:`Figure CLM subgrid hierarchy` Configuration of the CLM subgrid hierarchy. +- :numref:`Figure CLM subgrid hierarchy` Configuration of the CLM subgrid hierarchy. -- :numref:`Figure Radiation Schematic` Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. +- :numref:`Figure Radiation Schematic` Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and reflected by vegetation and ground. -- :numref:`Figure Schematic diagram of sensible heat fluxes` Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. +- :numref:`Figure Schematic diagram of sensible heat fluxes` Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. -- :numref:`Figure Schematic diagram of latent heat fluxes` Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. +- :numref:`Figure Schematic diagram of latent heat fluxes` Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. -- :numref:`Figure Soil Temperature Schematic`. Schematic diagram of numerical scheme used to solve for soil temperature. +- :numref:`Figure Soil Temperature Schematic`. Schematic diagram of numerical scheme used to solve for soil temperature. - :numref:`Figure Hydrologic processes` Hydrologic processes represented in CLM. -- :numref:`Figure Water flux schematic` Schematic diagram of numerical scheme used to solve for soil water fluxes. +- :numref:`Figure Water flux schematic` Schematic diagram of numerical scheme used to solve for soil water fluxes. -- :numref:`Figure three layer snow pack` Example of three layer snow pack (snl=-3). +- :numref:`Figure three layer snow pack` Example of three layer snow pack (snl=-3). - :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. @@ -57,31 +55,31 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure Schematic of urban and atmospheric model coupling` Schematic of urban and atmospheric model coupling. -- :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. +- :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. -- :numref:`Figure Carbon and nitrogen pools` Carbon and nitrogen pools. +- :numref:`Figure Carbon and nitrogen pools` Carbon and nitrogen pools. -- :numref:`Figure annual phenology cycle` Example of annual phenology cycle for seasonal deciduous. +- :numref:`Figure annual phenology cycle` Example of annual phenology cycle for seasonal deciduous. - 14.2. Example fluxes and pools sizes for an onset growth period of 15 days, with initial transfer pool size of 100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool (e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). -- 14.3. Example fluxes and pool sizes for an offset (litterfall) period of 15 days, with initial display pool size of 100 gC m-2 and a timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon content of display pool and litter pool through the litterfall period, ignoring the losses from litter pool due to decomposition during this period. +- 14.3. Example fluxes and pool sizes for an offset (litterfall) period of 15 days, with initial display pool size of 100 gC m-2 and a timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon content of display pool and litter pool through the litterfall period, ignoring the losses from litter pool due to decomposition during this period. - :numref:`Figure Schematic of decomposition model in CLM` Schematic of decomposition model in CLM. -- :numref:`Figure Pool structure` Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. +- :numref:`Figure Pool structure` Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. -- :numref:`Figure Biological nitrogen fixation` Biological nitrogen fixation as a function of annual net primary production. +- :numref:`Figure Biological nitrogen fixation` Biological nitrogen fixation as a function of annual net primary production. -- :numref:`Figure Methane Schematic` Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. +- :numref:`Figure Methane Schematic` Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. -- :numref:`Figure Schematic of land cover change` Schematic of land cover change impacts on CLM carbon pools and fluxes. +- :numref:`Figure Schematic of land cover change` Schematic of land cover change impacts on CLM carbon pools and fluxes. -- :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. +- :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. **LIST OF TABLES** -- :numref:`Table Plant functional types` Plant functional types +- :numref:`Table Plant functional types` Plant functional types - :numref:`Table Plant functional type canopy top and bottom heights` Plant functional type canopy top and bottom heights @@ -89,73 +87,73 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Atmospheric input to land model` Atmospheric input to land model -- :numref:`Table Land model output to atmospheric model` Land model output to atmospheric model +- :numref:`Table Land model output to atmospheric model` Land model output to atmospheric model -- :numref:`Table Surface data required for CLM and their base spatial resolution` Surface data required for CLM4.5 and their base spatial resolution +- :numref:`Table Surface data required for CLM and their base spatial resolution` Surface data required for CLM4.5 and their base spatial resolution -- :numref:`Table Physical constants` Physical constants +- :numref:`Table Physical constants` Physical constants - :numref:`Table Plant functional type optical properties` Plant functional type optical properties -- :numref:`Table Intercepted snow optical properties` Intercepted snow optical properties +- :numref:`Table Intercepted snow optical properties` Intercepted snow optical properties -- :numref:`Table Dry and saturated soil albedos` Dry and saturated soil albedos +- :numref:`Table Dry and saturated soil albedos` Dry and saturated soil albedos -- :numref:`Table Spectral bands and weights used for snow radiative transfer` Spectral bands and weights used for snow radiative transfer +- :numref:`Table Spectral bands and weights used for snow radiative transfer` Spectral bands and weights used for snow radiative transfer -- :numref:`Table Single-scatter albedo values used for snowpack impurities and ice` Single-scatter albedo values used for snowpack impurities and ice +- :numref:`Table Single-scatter albedo values used for snowpack impurities and ice` Single-scatter albedo values used for snowpack impurities and ice -- :numref:`Table Mass extinction values` Mass extinction values (m2 kg-1) used for snowpack impurities and ice. +- :numref:`Table Mass extinction values` Mass extinction values (m2 kg-1) used for snowpack impurities and ice. -- :numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice` Asymmetry scattering parameters used for snowpack impurities and ice. +- :numref:`Table Asymmetry scattering parameters used for snowpack impurities and ice` Asymmetry scattering parameters used for snowpack impurities and ice. -- :numref:`Table Orbital parameters` Orbital parameters +- :numref:`Table Orbital parameters` Orbital parameters -- :numref:`Table Plant functional type aerodynamic parameters` Plant functional type aerodynamic parameters +- :numref:`Table Plant functional type aerodynamic parameters` Plant functional type aerodynamic parameters -- :numref:`Table Coefficients for saturation vapor pressure` Coefficients for e\ :sub:`sat`\ :sup:`T` +- :numref:`Table Coefficients for saturation vapor pressure` Coefficients for e\ :sub:`sat`\ :sup:`T` - :numref:`Table Coefficients for derivative of esat` Coefficients for 112:numref:`` 6.1. Soil layer structure. - :numref:`Table Meltwater scavenging` Meltwater scavenging efficiency for particles within snow -- :numref:`Table snow layer thickness` Minimum and maximum thickness of snow layers (m) +- :numref:`Table snow layer thickness` Minimum and maximum thickness of snow layers (m) -- :numref:`Table Plant functional type (PFT) stomatal conductance parameters` Plant functional type (PFT) stomatal conductance parameters. +- :numref:`Table Plant functional type (PFT) stomatal conductance parameters` Plant functional type (PFT) stomatal conductance parameters. -- :numref:`Table Temperature dependence parameters for C3 photosynthesis` Temperature dependence parameters for C3 photosynthesis. +- :numref:`Table Temperature dependence parameters for C3 photosynthesis` Temperature dependence parameters for C3 photosynthesis. -- :numref:`Table Plant functional type root distribution parameters` Plant functional type root distribution parameters. +- :numref:`Table Plant functional type root distribution parameters` Plant functional type root distribution parameters. - :numref:`Table MOSART Parameters` List of parameters in the global hydrography dataset. -- :numref:`Table Allocation and CN ratio parameters` Allocation and carbon:nitrogen ratio parameters +- :numref:`Table Allocation and CN ratio parameters` Allocation and carbon:nitrogen ratio parameters -- :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. +- :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. -- :numref:`Table Respiration fractions for litter and SOM pools` Respiration fractions for litter and SOM pools +- :numref:`Table Respiration fractions for litter and SOM pools` Respiration fractions for litter and SOM pools -- :numref:`Table Turnover times` Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. +- :numref:`Table Turnover times` Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. -- :numref:`Table Respiration fractions for Century-based structure` Respiration fractions for litter and SOM pools for Century-based structure +- :numref:`Table Respiration fractions for Century-based structure` Respiration fractions for litter and SOM pools for Century-based structure -- :numref:`Table PFT-specific combustion completeness and fire mortality factors` PFT-specific combustion completeness and fire mortality factors. +- :numref:`Table PFT-specific combustion completeness and fire mortality factors` PFT-specific combustion completeness and fire mortality factors. -- :numref:`Table Methane Parameter descriptions` Parameter descriptions and sensitivity analysis ranges applied in the methane model. +- :numref:`Table Methane Parameter descriptions` Parameter descriptions and sensitivity analysis ranges applied in the methane model. - :numref:`Table Temperature dependence of aqueous and gaseous diffusion` Temperature dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. -- :numref:`Table Crop plant functional types` Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. +- :numref:`Table Crop plant functional types` Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. - :numref:`Table Crop plant functional types` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. - :numref:`Table Crop allocation parameters` Crop allocation parameters for the active crop plant functional types (pfts) in CLM5BGCCROP. Numbers in the first row correspond to the list of pfts in :numref:`Table Crop plant functional types`. -- :numref:`Table Plant functional type (PFT) biogeography rules` Plant functional type (PFT) biogeography rules with respect to climate. +- :numref:`Table Plant functional type (PFT) biogeography rules` Plant functional type (PFT) biogeography rules with respect to climate. -- :numref:`Table Dust Mass fraction` Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i +- :numref:`Table Dust Mass fraction` Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i -- :numref:`Table Dust Minimum and maximum particle diameters` Minimum and maximum particle diameters in each dust transport bin j +- :numref:`Table Dust Minimum and maximum particle diameters` Minimum and maximum particle diameters in each dust transport bin j **ACKNOWLEDGEMENTS** @@ -187,7 +185,7 @@ scientific papers (:ref:`rst_References`). This document and the CLM5.0 User’s Guide together provide the user with the scientific description and operating instructions for CLM. -Model History +Model History --------------- Inception of CLM @@ -315,11 +313,11 @@ added stability corrections to the diagnostic 2-m air temperature calculation which reduced biases in this temperature. Competition between PFTs for water, in which PFTs share a single soil column, is the default mode of operation in this model version. CLM3 was released to -the community in June 2004. :ref:`Dickinson et al. (2006)` -describe the climate statistics of CLM3 when coupled to CCSM3.0. -:ref:`Hack et al. (2006)` provide an analysis of selected +the community in June 2004. :ref:`Dickinson et al. (2006)` +describe the climate statistics of CLM3 when coupled to CCSM3.0. +:ref:`Hack et al. (2006)` provide an analysis of selected features of the land hydrological cycle. -:ref:`Lawrence et al. (2007)` examine the impact of +:ref:`Lawrence et al. (2007)` examine the impact of changes in CLM3 hydrological parameterizations on partitioning of evapotranspiration (ET) and its effect on the timescales of ET response to precipitation @@ -490,11 +488,11 @@ remains long. Finally, the predominantly low resolution input data for provided with CLM4 to create CLM4 surface datasets is replaced with newer and higher -resolution input datasets where possible (see section :numref:`Surface Data` +resolution input datasets where possible (see section :numref:`Surface Data` for details). The default meteorological forcing dataset provided with CLM4 -(:ref:`Qian et al. 2006)` is replaced with the 1901-2010 -CRUNCEP forcing dataset (see Chapter :numref:`rst_Land-Only Mode`) for CLM4.5, -though users can also still use the :ref:`Qian et al. (2006)` +(:ref:`Qian et al. 2006)` is replaced with the 1901-2010 +CRUNCEP forcing dataset (see Chapter :numref:`rst_Land-Only Mode`) for CLM4.5, +though users can also still use the :ref:`Qian et al. (2006)` dataset or other alternative forcing datasets. CLM4.5 was released to the community in June 2013 along with the @@ -504,55 +502,55 @@ CLM5.0 ^^^^^^^^^^^^ Developments for CLM5.0 build on the progress made in CLM4.5. Most major components of the model have been updated with particularly -notable changes made to soil and plant hydrology, snow density, river modeling, carbon and nitrogen cycling and coupling, -and crop modeling. -Much of the focus of development centered on a +notable changes made to soil and plant hydrology, snow density, river modeling, carbon and nitrogen cycling and coupling, +and crop modeling. +Much of the focus of development centered on a push towards more mechanistic treatment of key processes, in addition to more comprehensive and explicit representation -of land use and land-cover change. Prior versions of CLM included relatively few options for physics parameterizations or structure. +of land use and land-cover change. Prior versions of CLM included relatively few options for physics parameterizations or structure. In CLM5, where new parameterizations or model decisions were made, in most cases, the CLM4.5 parameterization was maintained so that users could switch back and forth between different parameterizations via namelist control where appropriate or desirable. Throughout the CLM5 Technical Descpription, in general only the default parameterization for any given process is described. Readers are referred to the CLM4.5 or CLM4 Technical Descriptions for detailed descriptions of non-default parameterizations. The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Rooting profiles were used inconsistently in CLM4.5 with :ref:`Zeng (2001)` profiles used for water and :ref:`Jackson et al. (1996)` profiles used for carbon inputs. For CLM5, the Jackson et al. (1996) rooting profiles are used for both water and carbon. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. Several changes are included that are mainly targeted at improving the simulation of surface mass balance over ice -sheets. The fresh snow density parameterization is updated to more realistically capture the temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is active for Greenland by default with one-way coupling (surface mass balance impacts ice sheet dynamics, but ice sheet dynamics do not feedback onto surface elevation). Two-way coupling can be activated through a namelist switch. The introduction in CLM5 of the capability to +sheets. The fresh snow density parameterization is updated to more realistically capture the temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is active for Greenland by default with one-way coupling (surface mass balance impacts ice sheet dynamics, but ice sheet dynamics do not feedback onto surface elevation). Two-way coupling can be activated through a namelist switch. The introduction in CLM5 of the capability to dynamically adjust landunit weights means that a glacier can initiate, grow, shrink, or disappear during -a simulation when two-way coupling is active. Multiple elevation classes (10 elevation classes by default) and associated temperature, rain/snow partitioning, and downwelling longwave downscaling are used for glacier landunits to account for the strong topographic elevation heterogeneity over glaciers and ice sheets. +a simulation when two-way coupling is active. Multiple elevation classes (10 elevation classes by default) and associated temperature, rain/snow partitioning, and downwelling longwave downscaling are used for glacier landunits to account for the strong topographic elevation heterogeneity over glaciers and ice sheets. A plant hydraulic stress routine is introduced which explicitly models water transport through the vegetation according to a simple hydraulic framework (Kennedy et al., to be submitted). The water supply equations are used to solve for vegetation water potential forced by transpiration demand and a set of layer-by-layer soil water potentials. Stomatal conductance, therefore, is a function of prognostic leaf water potential. Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. An emergent feature of the plant hydraulics is soil hydraulic redistribution. In CLM5, maximum stomatal conductance is obtained from the Medlyn conductance model :ref:`(Medlyn et al., 2011)`, rather than the Ball-Berry stomatal conductance model that was utilized in CLM4.5 and prior versions of the model. The Medlyn stomatal conductance model is preferred mainly for it's more realistic behavior at low humidity levels :ref:`(Rogers et al., 2017)`. The stress deciduous vegetation phenology trigger is augmented with a antecedent precipitation requirement :ref:`(Dahlin et al. 2015)`. -Plant nutrient dynamics are substantially updated to resolve several deficiencies with the CLM4 and CLM4.5 nutrient cycling representation. The Fixation and Update of Nitrogen (FUN) model based on the work of :ref:`Fisher et al. (2010)`, :ref:`Brzostek et al. (2014)`, and :ref:`Shi et al. (2016)` is incorporated. The concept of FUN is that in most cases, N uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of N in the environment which a plant may exchange for carbon. The ratio of carbon expended to N acquired is therefore the cost, or exchange rate, of N acquisition. FUN calculates the rate of symbiotic N fixation, with this N passed straight to the plant, not the mineral N pool. Separately, CLM5 also calculates rates of symbiotic (or free living) N fixation as a function of evapotranspiration (:ref:`Cleveland et al. 1999 `), which -is added to the soil inorganic ammonium (NH\ :sub:`4`\ :sup:`+`) pool. The static plant carbon:nitrogen (C:N) ratios utilized in CLM4 and CLM4.5 are replaced with variable plant C:N ratios which -allows plants to adjust their C:N ratio, and therefore their leaf nitrogen content, with the cost of N uptake :ref:`(Ghimire et al. 2016)`. -The implementation of a flexible C:N ratio means that the model no longer relies on instantaneous downregulation -of potential photosynthesis rates based on soil mineral nitrogen availability to represent nutrient limitation. Furthermore, stomatal conductance -is now based on the N-limited photosynthesis rather than on potential photosynthesis. Finally, the Leaf Use of +Plant nutrient dynamics are substantially updated to resolve several deficiencies with the CLM4 and CLM4.5 nutrient cycling representation. The Fixation and Update of Nitrogen (FUN) model based on the work of :ref:`Fisher et al. (2010)`, :ref:`Brzostek et al. (2014)`, and :ref:`Shi et al. (2016)` is incorporated. The concept of FUN is that in most cases, N uptake requires the expenditure of energy in the form of carbon, and further, that there are numerous potential sources of N in the environment which a plant may exchange for carbon. The ratio of carbon expended to N acquired is therefore the cost, or exchange rate, of N acquisition. FUN calculates the rate of symbiotic N fixation, with this N passed straight to the plant, not the mineral N pool. Separately, CLM5 also calculates rates of symbiotic (or free living) N fixation as a function of evapotranspiration (:ref:`Cleveland et al. 1999 `), which +is added to the soil inorganic ammonium (NH\ :sub:`4`\ :sup:`+`) pool. The static plant carbon:nitrogen (C:N) ratios utilized in CLM4 and CLM4.5 are replaced with variable plant C:N ratios which +allows plants to adjust their C:N ratio, and therefore their leaf nitrogen content, with the cost of N uptake :ref:`(Ghimire et al. 2016)`. +The implementation of a flexible C:N ratio means that the model no longer relies on instantaneous downregulation +of potential photosynthesis rates based on soil mineral nitrogen availability to represent nutrient limitation. Furthermore, stomatal conductance +is now based on the N-limited photosynthesis rather than on potential photosynthesis. Finally, the Leaf Use of Nitrogen for Assimilation (LUNA, :ref:`Xu et al., 2012` and :ref:`Ali et al., 2016)` model is incorporated. The LUNA model calculates -photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that -light capture, carboxylation, and respiration are co-limiting. +photosynthetic capacity based on optimization of the use of leaf nitrogen under different environmental conditions such that +light capture, carboxylation, and respiration are co-limiting. -CLM5 applies a fixed allocation scheme for woody vegetation. The decision to use a fixed allocation scheme in CLM5, rather than a dynamic NPP-based allocation scheme, as was used in CLM4 and CLM4.5, was driven by the fact that observations indicate that biomass saturates with increasing productivity, in contrast to the behavior in CLM4 and CLM4.5 where biomass continuously increases with increasing productivity (:ref:`Negron-Juarez et al., 2015`). Soil carbon decomposition processes are unchanged in CLM5, but a new metric for apparent soil carbon turnover times (:ref:`Koven et al., 2017 `) suggested parameter changes that produce a weak intrinsic depth limitation on soil carbon turnover rates (rather than the strong depth limitaiton in CLM4.5) and that the thresholds for soil moisture limitation on soil carbon turnover rates in dry soils should be set at a wetter soil moisture level than that used in CLM4.5. +CLM5 applies a fixed allocation scheme for woody vegetation. The decision to use a fixed allocation scheme in CLM5, rather than a dynamic NPP-based allocation scheme, as was used in CLM4 and CLM4.5, was driven by the fact that observations indicate that biomass saturates with increasing productivity, in contrast to the behavior in CLM4 and CLM4.5 where biomass continuously increases with increasing productivity (:ref:`Negron-Juarez et al., 2015`). Soil carbon decomposition processes are unchanged in CLM5, but a new metric for apparent soil carbon turnover times (:ref:`Koven et al., 2017 `) suggested parameter changes that produce a weak intrinsic depth limitation on soil carbon turnover rates (rather than the strong depth limitaiton in CLM4.5) and that the thresholds for soil moisture limitation on soil carbon turnover rates in dry soils should be set at a wetter soil moisture level than that used in CLM4.5. -Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016)`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. -Fertilization rates and irrigation equipped area updated annually based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that +Representation of human management of the land (agriculture, wood harvest) is augmented in several ways. The CLM4.5 crop model is extended to operate globally through the addition of rice and sugarcane as well as tropical varieties of corn and soybean :ref:`(Badger and Dirmeyer, 2015` and :ref:`Levis et al., 2016)`. These crop types are added to the existing temperate corn, temperature soybean, spring wheat, and cotton crop types. +Fertilization rates and irrigation equipped area updated annually based on crop type and geographic region through an input dataset. The irrigation trigger is updated. Additional minor changes include crop phenological triggers that vary by latitude for selected crop types, grain C and N is now removed at harvest to a 1-year product pool with -the carbon for the next season's crop seed removed from the grain carbon at harvest. Through the introduction of +the carbon for the next season's crop seed removed from the grain carbon at harvest. Through the introduction of the capability to dynamically adjust landunit weights during a simulation, the crop model can now be run coincidentally with prescribed land use, which significantly expands the capabilities of the model. Mass-based rather than area-based wood harvest is applied. Several heat stress indices for both urban and rural areas are calculated and output by default :ref:`(Buzan et al., 2015)`. A more sophisticated and realistic building space heating and air conditioning submodel that prognoses interior building air temperature and includes more realistic space heating and air conditioning wasteheat factors -is incorporated. +is incorporated. The fire model is the same as utilized in CLM4.5 except that a modified scheme is used to estimate the dependence of fire occurrence and spread on fuel wetness for non-peat fires outside cropland and tropical closed forests :ref:`(Li and Lawrence, 2017)` and the dependence of agricultural fires on fuel load is removed. Included with the release of CLM5.0 is a functionally supported version of the Functionally-Assembled Terrestrial Ecosystem Simulator (FATES, :ref:`Fisher et al., 2015)`. A major motivation of FATES is to allow the prediction of biome boundaries directly from plant physiological traits via their competitive interactions. FATES is a cohort model of vegetation competition and co-existence, allowing a representation of the biosphere which accounts for the division of the land surface into successional stages, and for competition for light between height structured cohorts of representative trees of various plant functional types. FATES is not active by default in CLM5.0. -Note that the classical dynamic global vegetation model (CLM-DGVM) that has been available within CLM4 and CLM4.5 remains available, though it is largely untested. The technical description of the CLM-DGVM can be found within the CLM4.5 Technical Description (:ref:`Oleson et al. 2013)`. +Note that the classical dynamic global vegetation model (CLM-DGVM) that has been available within CLM4 and CLM4.5 remains available, though it is largely untested. The technical description of the CLM-DGVM can be found within the CLM4.5 Technical Description (:ref:`Oleson et al. 2013)`. During the course of the development of CLM5.0, it became clear that the increasing complexity of the model combined with the increasing number and range of model development projects required updates to the underlying CLM infrastructure. Many such software improvements -are included in CLM5 including a partial transition to an object-oriented modular software structure. Many hard coded model -parameters have been extracted into either the parameter file or the CLM namelist, which allows users to more readily calibrate the model for use at -specific locations or to conduct parameter sensitivity studies. As part of the effort to increase -the scientific utility of the code, in most instances older generation parameterizations (i.e., the parameterizations -available in CLM4 or CLM4.5) are retained under namelist switches, allowing the user to revert to CLM4.5 +are included in CLM5 including a partial transition to an object-oriented modular software structure. Many hard coded model +parameters have been extracted into either the parameter file or the CLM namelist, which allows users to more readily calibrate the model for use at +specific locations or to conduct parameter sensitivity studies. As part of the effort to increase +the scientific utility of the code, in most instances older generation parameterizations (i.e., the parameterizations +available in CLM4 or CLM4.5) are retained under namelist switches, allowing the user to revert to CLM4.5 from the same code base or to revert individual parameterizations where the old parameterizations are compatible with the new code. Finally, multiple vertical soil layer structures are defined and it is relatively easy to add additional structures. @@ -562,7 +560,7 @@ Biogeophysical and Biogeochemical Processes Biogeophysical and biogeochemical processes are simulated for each subgrid land unit, column, and plant functional type (PFT) independently and each subgrid unit maintains its own prognostic variables (see -section :numref:`Surface Heterogeneity and Data Structure` for definitions +section :numref:`Surface Heterogeneity and Data Structure` for definitions of subgrid units). The same atmospheric forcing is used to force all subgrid units within a grid cell. The surface variables and fluxes required by the atmosphere are obtained by @@ -590,7 +588,7 @@ processes simulated include (:numref:`Figure Land processes`): #. Snow hydrology (snow accumulation and melt, compaction, water transfer between snow layers) (Chapter :numref:`rst_Snow Hydrology`) -#. Stomatal physiology, photosythetic capacity, and photosynthesis (Chapters :numref:`rst_Stomatal Resistance and Photosynthesis` and +#. Stomatal physiology, photosythetic capacity, and photosynthesis (Chapters :numref:`rst_Stomatal Resistance and Photosynthesis` and :numref:`rst_Photosynthetic Capacity`) #. Plant hydraulics (Chapter :numref:`rst_Plant Hydraulics`) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index db3498f4e5..5168284551 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1,10 +1,17 @@ .. _rst_References: + +.. |br| raw:: latex + + \\ + References ============== .. _Aberetal1990: +|br| + Aber, J.D., Melillo, J.M. and McClaugherty, C.A., 1990. Predicting long-term patterns of mass loss, nitrogen dynamics, and soil organic matter formation from initial fime litter chemistry in temperate forest @@ -12,6 +19,8 @@ ecosystems. Canadian Journal of Botany, 68: 2201-2208. .. _Aberetal2003: +|br| + Aber, J.D., Goodale, C.L., Ollinger, S.V., Smith, M.-L., Magill, A.H., Martin, M.E., Hallett, R.A., and Stoddard, J.L. 2003. Is nitrogen deposition altering the nitrogen status of northeastern forests? @@ -19,22 +28,32 @@ BioScience 53:375-389. .. _Alietal2016: -Ali, A. A., C. Xu, A. Rogers, R. A. Fisher, S. D. Wullschleger, E. Massoud, J. A. Vrugt, J. D. Muss, N. McDowell, and J. Fisher, 2016: A global scale mechanistic model of photosynthetic capacity (LUNA V1. 0). Geosci. Mod. Dev., 9:587-606. +|br| + +Ali, A. A., C. Xu, A. Rogers, R. A. Fisher, S. D. Wullschleger, E. Massoud, J. A. Vrugt, J. D. Muss, N. McDowell, +and J. Fisher, 2016: A global scale mechanistic model of +photosynthetic capacity (LUNA V1. 0). Geosci. Mod. Dev., 9:587-606. .. _Allenetal2005: +|br| + Allen, C.B., Will, R.E., and Jacobson, M.A. 2005. Production efficiency and radiation use efficiency of four tree species receiving irrigation and fertilization. Forest Science 51:556-569. .. _Anderson1976: +|br| + Anderson, E.A. 1976. A point energy and mass balance model of a snow cover. NOAA Technical Report NWS 19, Office of Hydrology, National Weather Service, Silver Spring, MD. .. _Andréetal1986: +|br| + André, J.-C., Goutorbe, J.-P., and Perrier, A. 1986. HAPEX-MOBILHY: A hydrologic atmosphere experiment for the study of water budget and evaporation flux at the climatic scale. Bull. Amer. Meteor. Soc. @@ -42,39 +61,53 @@ evaporation flux at the climatic scale. Bull. Amer. Meteor. Soc. .. _AndrénPaustian1987: +|br| + Andrén, O. and Paustian, K., 1987. Barley straw decomposition in the field: a comparison of models. Ecology 68:1190-1200. .. _ArahStephen1998: +|br| + Arah, J.R.M. and Stephen, K.D., 1998. A model of the processes leading to methane emission from peatland. Atmos. Environ. 32:3257-3264. .. _ArahVinten1995: +|br| + Arah, J. and Vinten, A., 1995. Simplified models of anoxia and denitrification in aggregated and simple-structured soils. European Journal of Soil Science 46:507-517. .. _Arendtetal2012: +|br| + Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global Glacier Outlines Version: 1.0, Global Land Ice Measurements from Space, Boulder Colorado, USA. Digital Media. .. _AroraBoer2005: +|br| + Arora, V.K. and Boer, G.J. 2005. Fire as an interactive component of dynamic vegetation models. J. Geophys. Res. 110:G02008. DOI:10.1029/2005JG000042. .. _Arya2001: +|br| + Arya, S.P. 2001. Introduction to Meteorology. Academic Press, San Diego, CA. .. _Asneretal1998: +|br| + Asner, G.P., Wessman, C.A., Schimel, D.S., and Archer, S. 1998. Variability in leaf and litter optical properties: implications for BRDF model inversions using AVHRR, MODIS, and MISR. Remote Sens. Environ. @@ -82,47 +115,63 @@ model inversions using AVHRR, MODIS, and MISR. Remote Sens. Environ. .. _AxelssonAxelsson1986: +|br| + Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation patterns in spruce and pine trees following irrigation and fertilization. Tree Phys. 2:189-204. .. _BadgerandDirmeyer2015: +|br| + Badger, A.M., and Dirmeyer, P.A., 2015. Climate response to Amazon forest replacement by heterogeneous crop cover. Hydrol. Earth. Syst. Sci. 19:4547- -4557. +4557. .. _Bairdetal2004: +|br| + Baird, A.J., Beckwith, C.W., Waldron, S. and Waddington, J.M., 2004. Ebullition of methane-containing gas bubbles from near-surface Sphagnum peat. Geophys. Res. Lett. 31. DOI:10.1029/2004GL021157. .. _Baldocchietal2001: +|br| + Baldocchi, D., et al. 2001. FLUXNET: A new tool to study the temporal and spatial variability of ecosystem-scale carbon dioxide, water vapor, and energy flux densities. Bull. Amer. Meteor. Soc. 82:2415-2433. .. _Barbottinetal2005: +|br| + Barbottin, A., Lecomte, C., Bouchard, C., and Jeuffroy, M.-H. 2005. Nitrogen remobilization during grain filling in wheat: Genotypic and environmental effects. Crop Sci. 45:1141-1150. .. _Batjes2006: +|br| + Batjes, N.H., 2006. ISRIC-WISE derived soil properties on a 5 by 5 arc-minutes global grid. Report 2006/02 (available through : http://www.isric.org) .. _Berger1978a: +|br| + Berger, A.L. 1978a. Long-term variations of daily insolation and quaternary climatic changes. J. Atmos. Sci. 35:2362-2367. .. _Berger1978b: +|br| + Berger, A.L. 1978b. A simple algorithm to compute long-term variations of daily or monthly insolation. Contribution de l’Institut d’Astronomie et de Géophysique, Université Catholique de Louvain, Louvain-la-Neuve, @@ -130,27 +179,37 @@ No. 18. .. _Bergeretal1993: +|br| + Berger, A., Loutre, M.-F., and Tricot, C. 1993. Insolation and Earth’s orbital periods. J. Geophys. Res. 98:10341-10362. .. _BerkowitzBalberg1992: +|br| + Berkowitz, B., and Balberg, I. 1992. Percolation approach to the problem of hydraulic conductivity in porous media. Transport in Porous Media 9:275–286. .. _BevenKirkby1979: +|br| + Beven, K.J., and Kirkby, M.J. 1979. A physically based variable contributing area model of basin hydrology. Hydrol. Sci. Bull. 24:43-69. .. _BohrenHuffman1983: +|br| + Bohren, C. F., and Huffman, D. R. 1983. Absorption and scattering of light by small particles. John Wiley & Sons, New York, NY. .. _Bonan1996: +|br| + Bonan, G.B. 1996. A land surface model (LSM version 1.0) for ecological, hydrological, and atmospheric studies: Technical description and user’s guide. NCAR Technical Note NCAR/TN-417+STR, National Center for @@ -158,17 +217,23 @@ Atmospheric Research, Boulder, CO, 150 pp. .. _Bonan1998: +|br| + Bonan, G.B. 1998. The land surface climatology of the NCAR Land Surface Model coupled to the NCAR Community Climate Model. J. Climate 11:1307-1326. .. _Bonan2002: +|br| + Bonan, G.B. 2002. Ecological Climatology: Concepts and Applications. Cambridge University Press. .. _Bonanetal2002a: +|br| + Bonan, G.B., Oleson, K.W., Vertenstein, M., Levis, S., Zeng, X., Dai, Y., Dickinson, R.E., and Yang, Z.-L. 2002a. The land surface climatology of the Community Land Model coupled to the NCAR Community Climate Model. @@ -176,18 +241,24 @@ J. Climate 15: 3123-3149. .. _Bonanetal2002b: +|br| + Bonan, G.B., Levis, S., Kergoat, L., and Oleson, K.W. 2002b. Landscapes as patches of plant functional types: An integrating concept for climate and ecosystem models. Global Biogeochem. Cycles 16: 5.1-5.23. .. _BonanLevis2006: +|br| + Bonan, G.B., and Levis, S. 2006. Evaluating aspects of the Community Land and Atmosphere Models (CLM3 and CAM3) using a dynamic global vegetation model. J. Climate 19:2290-2301. .. _Bonanetal2011: +|br| + Bonan, G.B., Lawrence P.J., Oleson K.W., Levis S., Jung M., Reichstein M., Lawrence, D.M., and Swenson, S.C. 2011. Improving canopy processes in the Community Land Model (CLM4) using global flux fields empirically @@ -196,6 +267,8 @@ DOI:10.1029/2010JG001593. .. _Bonanetal2012: +|br| + Bonan, G. B., Oleson, K.W., Fisher, R.A., Lasslop, G., and Reichstein, M. 2012. Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4, @@ -203,47 +276,65 @@ J. Geophys. Res., 117, G02026. DOI:10.1029/2011JG001913. .. _Bonanetal2014: -Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling -stomatal conductance in the earth system: linking leaf water-use -efficiency and water transport along the soil–plant–atmosphere continuum, +|br| + +Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling +stomatal conductance in the earth system: linking leaf water-use +efficiency and water transport along the soil–plant–atmosphere continuum, Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. .. _Brun1989: +|br| + Brun, E. 1989. Investigation of wet-snow metamorphism in respect of liquid water content. Ann. Glaciol. 13:22-26. .. _Brunkeetal2016: +|br| + Brunke, M. A., P. Broxton, J. Pelletier, D. Gochis, P. Hazenberg, D. M. Lawrence, L. R. Leung, G.-Y. Niu, P. A. Troch, and X. Zeng, 2016: Implementing and Evaluating Variable Soil Thickness in the Community Land Model, Version 4.5 (CLM4.5). J. Clim. 29:3441-3461. .. _Brzosteketal2014: +|br| + Brzostek, E. R., J. B. Fisher, and R. P. Phillips, 2014. Modeling the carbon cost of plant nitrogen acquisition: Mycorrhizal trade-offs and multipath resistance uptake improve predictions of retranslocation. J. Geophys. Res. Biogeosci., 119, 1684–1697, doi:10.1002/2014JG002660. .. _BugmannSolomon2000: +|br| + Bugmann, H., and Solomon, A.M. 2000. Explaining forest composition and biomass across multiple biogeographical regions. Ecol. Appl. 10:95-114. .. _Busing2005: +|br| + Busing, R.T. 2005. Tree mortality, canopy turnover, and woody detritus in old cove forests of the southern Appalachians. Ecology 86:73-84. .. _Buzanetal2015: -Buzan, J.R., Oleson, K., and Huber, M. 2015: Implementation and -comparison of a suite of heat stress metrics within the Community Land +|br| + +Buzan, J.R., Oleson, K., and Huber, M. 2015: Implementation and +comparison of a suite of heat stress metrics within the Community Land Model version 4.5, Geosci. Model Dev., 8, 151-170, doi:10.5194/gmd-8-151-2015. .. _CampbellNorman1998: +|br| + Campbell, G.S., and Norman, J.M. 1998. An Introduction to Environmental Biophysics (2:math:`{}^{nd}` edition). Springer-Verlag, New York. .. _Castilloetal2012: +|br| + Castillo, G., Kendra, C., Levis, S., and Thornton, P. 2012. Evaluation of the new CNDV option of the Community Land Model: effects of dynamic vegetation and interactive nitrogen on CLM4 means and variability. J. @@ -251,25 +342,33 @@ Climate 25:3702–3714. .. _Caoetal1996: +|br| + Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and methane emissions from natural wetlands: Application of a process-based model. J. Geophys. Res. 101(D9):14,399-14,414. .. _Chuangetal2006: -Chuang Y.L., Oren R., Bertozzi A.L, Phillips N., Katul G.G. 2006. The -porous media model for the hydraulic system of a conifer tree: Linking -sap flux data to transpiration rate, Ecological Modelling, 191, 447-468, +|br| + +Chuang Y.L., Oren R., Bertozzi A.L, Phillips N., Katul G.G. 2006. The +porous media model for the hydraulic system of a conifer tree: Linking +sap flux data to transpiration rate, Ecological Modelling, 191, 447-468, doi:10.1016/j.ecolmodel.2005.03.027. .. _Churkinaetal2003: +|br| + Churkina, G. et al., 2003. Analyzing the ecosystem carbon dynamics of four European coniferous forests using a biogeochemistry model. Ecosystems, 6: 168-184. .. _CIESIN2005: +|br| + CIESIN: Gridded population of the world version 3 (GPWv3), 2005. Population density grids, Technical report, Socioeconomic Data and Applications Center (SEDAC), Columbia University, Palisades, New York, @@ -277,17 +376,23 @@ USA. .. _ClappHornberger1978: +|br| + Clapp, R.B., and Hornberger, G.M. 1978. Empirical equations for some soil hydraulic properties. Water Resour. Res. 14:601-604. .. _ClauserHuenges1995: +|br| + Clauser, C., and Huenges, E. 1995. Thermal conductivity of rocks and minerals. pp. 105-126. In: T. J. Ahrens (editor) Rock Physics and Phase Relations: A Handbook of Physical Constants. Washington, D.C. .. _Clevelandetal1999: +|br| + Cleveland, C.C., Townsend, A.R., Schimel, D.S., Fisher, H., Howarth, R.W., Hedin, L.O., Perakis, S.S., Latty, E.F., Von Fischer, J.C., Elseroad, A., and Wasson, M.F. 1999. Global patterns of terrestrial @@ -296,6 +401,8 @@ Biogeochem. Cycles 13:623-645. .. _Collatzetal1991: +|br| + Collatz, G.J., Ball, J.T., Grivet, C., and Berry, J.A. 1991. Physiological and environmental regulation of stomatal conductance, photosynthesis, and transpiration: A model that includes a laminar @@ -303,23 +410,31 @@ boundary layer. Agric. For. Meteor. 54:107-136. .. _Collatzetal1992: +|br| + Collatz, G.J., Ribas-Carbo, M., and Berry, J.A. 1992. Coupled photosynthesis-stomatal conductance model for leaves of C\ :math:`{}_{4}` plants. Aust. J. Plant Physiol. 19:519-538. .. _Colmer2003: +|br| + Colmer, T.D., 2003. Long-distance transport of gases in plants: a perspective on internal aeration and radial oxygen loss from roots. Plant Cell and Environment 26:17-36. .. _Conwayetal1996: +|br| + Conway, H., Gades, A., and Raymond, C.F. 1996. Albedo of dirty snow during conditions of melt. Water Resour. Res. 32:1713-1718. .. _Cosbyetal1984: +|br| + Cosby, B.J., Hornberger, G.M., Clapp, R.B., and Ginn, T.R. 1984. A statistical exploration of the relationships of soil moisture characteristics to the physical properties of soils. Water Resour. Res. @@ -327,28 +442,38 @@ characteristics to the physical properties of soils. Water Resour. Res. .. _Crawfordetal1982: +|br| + Crawford, T. W., Rendig, V. V., and Broadent, F. E. 1982. Sources, fluxes, and sinks of nitrogen during early reproductive growth of maize (Zea mays L.). Plant Physiol. 70:1645-1660. .. _Dahlinetal2015: +|br| + Dahlin, K., R. Fisher, and P. Lawrence, 2015: Environmental drivers of drought deciduous phenology in the Community Land Model. Biogeosciences, 12:5061-5074. .. _DaiZeng1997: +|br| + Dai, Y., and Zeng, Q. 1997. A land surface model (IAP94) for climate studies. Part I: formulation and validation in off-line experiments. Adv. Atmos. Sci. 14:433-460. .. _Daietal2001: +|br| + Dai, Y., et al. 2001. Common Land Model: Technical documentation and user’s guide [Available online at http://climate.eas.gatech.edu/dai/clmdoc.pdf]. .. _Daietal2003: +|br| + Dai, Y., Zeng, X., Dickinson, R.E., Baker, I., Bonan, G.B., Bosilovich, M.G., Denning, A.S., Dirmeyer, P.A., Houser, P.R., Niu, G., Oleson, K.W., Schlosser, C.A., and Yang, Z.-L. 2003. The Common Land Model. @@ -356,24 +481,32 @@ Bull. Amer. Meteor. Soc. 84:1013-1023. .. _Daietal2004: +|br| + Dai, Y., Dickinson, R.E., and Wang, Y.-P. 2004. A two-big-leaf model for canopy temperature, photosynthesis, and stomatal conductance. J. Climate 17:2281-2299. .. _DaiTrenberth2002: +|br| + Dai, A., and Trenberth, K.E. 2002. Estimates of freshwater discharge from continents: Latitudinal and seasonal variations. J. Hydrometeor. 3:660-687. .. _DeFriesetal2000: +|br| + DeFries, R.S., Hansen, M.C., Townshend, J.R.G., Janetos, A.C., and Loveland, T.R. 2000. A new global 1-km dataset of percentage tree cover derived from remote sensing. Global Change Biol. 6:247-254. .. _DegensSparling1996: +|br| + Degens, B. and Sparling, G., 1996. Changes in aggregation do not correspond with changes in labile organic C fractions in soil amended with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): @@ -381,16 +514,22 @@ with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): .. _deVries1963: +|br| + de Vries, D.A. 1963. Thermal Properties of Soils. In: W.R. van Wijk (editor) Physics of the Plant Environment. North-Holland, Amsterdam. .. _Dickinson1983: +|br| + Dickinson, R.E. 1983. Land surface processes and climate-surface albedos and energy balance. Adv. Geophys. 25:305-353. .. _Dickinsonetal1993: +|br| + Dickinson, R.E., Henderson-Sellers, A., and Kennedy, P.J. 1993. Biosphere-Atmosphere Transfer Scheme (BATS) version 1e as coupled to the NCAR Community Climate Model. NCAR Technical Note NCAR/TN-387+STR. @@ -398,6 +537,8 @@ National Center for Atmospheric Research, Boulder, CO. .. _Dickinsonetal2006: +|br| + Dickinson, R.E., Oleson, K.W., Bonan, G., Hoffman, F., Thornton, P., Vertenstein, M., Yang, Z.-L., and Zeng, X. 2006. The Community Land Model and its climate statistics as a component of the Community Climate @@ -405,22 +546,30 @@ System Model. J. Climate 19:2302-2324. .. _Dingman2002: +|br| + Dingman, S.L. 2002. Physical Hydrology. Second Edition. Prentice Hall, NJ. .. _Dirmeyeretal1999: +|br| + Dirmeyer, P.A., Dolman, A.J., and Sato, N. 1999. The pilot phase of the Global Soil Wetness Project. Bull. Amer. Meteor. Soc. 80:851-878. .. _Dobsonetal2000: +|br| + Dobson, J.E., Bright, E.A., Coleman, P.R., Durfee, R.C., and Worley, B.A. 2000. LandScan: A global population database for estimating populations at risk. Photogramm. Eng. Rem. Sens. 66:849-857. .. _DormanSellers1989: +|br| + Dorman, J.L., and Sellers, P.J. 1989. A global climatology of albedo, roughness length and stomatal resistance for atmospheric general circulation models as represented by the simple biosphere model (SiB). @@ -428,47 +577,63 @@ J. Appl. Meteor. 28:833-855. .. _Doughertyetal1994: +|br| + Dougherty, R.L., Bradford, J.A., Coyne, P.I., and Sims, P.L. 1994. Applying an empirical model of stomatal conductance to three C4 grasses. Agric. For. Meteor. 67:269-290. .. _Drewniaketal2013: +|br| + Drewniak, B., Song, J., Prell, J., Kotamarthi, V.R., and Jacob, R. 2013. Modeling agriculture in the Community Land Model. Geosci. Model Dev. 6:495-515. DOI:10.5194/gmd-6-495-2013. .. _Dunfieldetal1993: +|br| + Dunfield, P., Knowles, R., Dumont, R. and Moore, T.R., 1993. Methane Production and Consumption in Temperate and Sub-Arctic Peat Soils - Response to Temperature and Ph. Soil Biology & Biochemistry 25:321-326. .. _EntekhabiEagleson1989: +|br| + Entekhabi, D., and Eagleson, P.S. 1989. Land surface hydrology parameterization for atmospheric general circulation models including subgrid scale spatial variability. J. Climate 2:816-831. .. _FangStefan1996: +|br| + Fang, X. and Stefan, H.G., 1996. Long-term lake water temperature and ice cover simulations/measurements. Cold Regions Science and Technology 24:289-304. .. _Farouki1981: +|br| + Farouki, O.T. 1981. The thermal properties of soils in cold regions. Cold Regions Sci. and Tech. 5:67-75. .. _Farquharetal1980: +|br| + Farquhar, G.D., von Caemmerer, S., and Berry, J.A. 1980. A biochemical model of photosynthetic CO\ :sub:`2` assimilation in leaves of C\ :math:`{}_{3}` species. Planta 149:78-90. .. _FarquharvonCaemmerer1982: +|br| + Farquhar, G.D., and von Caemmerer, S. 1982. Modeling of photosynthetic response to environmental conditions. pp. 549-587. In: O.L. Lange, P.S. Nobel, C.B. Osmond, and H. Zeigler (editors) Encyclopedia of Plant @@ -477,48 +642,66 @@ and Carbon Assimilation. Springer-Verlag, New York. .. _Ferrari1999: +|br| + Ferrari, J.B., 1999. Fine-scale patterns of leaf litterfall and nitrogen cycling in an old-growth forest. Canadian Journal of Forest Research, 29: 291-302. .. _FirestoneDavidson1989: +|br| + Firestone, M.K. and Davidson, E.A. 1989. Exchange of Trace Gases between Terrestrial Ecosystems and the Atmosphere. In: M.O. Andreae and D.S. Schimel (Editors). John Wiley and Sons, pp. 7-21. .. _Fisheretal2015: +|br| + Fisher, R. A., S. Muszala, M. Verteinstein, P. Lawrence, C. Xu, N. G. McDowell, R. G. Knox, C. Koven, J. Holm, B. M. Rogers, A. Spessa, D. Lawrence, and G. Bonan, 2015: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED). Geosci. Model Dev., 8: 3593-3619, doi:10.5194/gmd-8-3593-2015. .. _Fisheretal2010: +|br| + Fisher, J. B., S. Sitch, Y. Malhi, R. A. Fisher, C. Huntingford, and S.-Y. Tan, 2010. Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation. Global Biogeochem. Cycles, 24, GB1014, doi:10.1029/2009GB003621. .. _FlannerZender2005: +|br| + Flanner, M.G., and Zender. C.S. 2005. Snowpack radiative heating: Influence on Tibetan Plateau climate. Geophys. Res. Lett. 32:L06501. DOI:10.1029/2004GL022076. .. _FlannerZender2006: +|br| + Flanner, M.G., and Zender, C.S. 2006. Linking snowpack microphysics and albedo evolution. J. Geophys. Res. 111:D12208. DOI:10.1029/2005JD006834. .. _Flanneretal2007: +|br| + Flanner, M.G., Zender, C.S., Randerson, J.T., and Rasch, P.J. 2007. Present day climate forcing and response from black carbon in snow. J. Geophys. Res. 112:D11202. DOI:10.1029/2006JD008003. .. _Flatauetal1992: +|br| + Flatau, P.J., Walko, R.L., and Cotton, W.R. 1992. Polynomial fits to saturation vapor pressure. J. Appl. Meteor. 31:1507-1513. .. _Friedl,etal2002: +|br| + Friedl, M.A., McIver, D.K., Hodges, J.C.F., Zhang, X.Y., Muchoney, D., Strahler, A.H., Woodcock, C.E., Gopal, S., Schneider, A., Cooper, A., Baccini, A., Gao, F., and Schaaf, C. 2002. Global land cover mapping @@ -527,17 +710,23 @@ from MODIS: algorithms and early results. Remote Sens. Environ. .. _Frolkingetal2001: +|br| + Frolking, S., et al. 2001. Modeling Northern Peatland Decomposition and Peat Accumulation. Ecosystems. 4:479-498. .. _Gallaisetal2006: +|br| + Gallais, A., Coque, M. Quillere, I., Prioul, J., and Hirel, B. 2006. Modeling postsilking nitrogen fluxes in maize (Zea mays) using 15N-labeling field experiments. New Phytologist 172:696-707. .. _Gallaisetal2007: +|br| + Gallais, A., Coque, M., Gouis, J. L., Prioul, J. L., Hirel, B., and Quillere, I. 2007. Estimating the proportion of nitrogen remobilization and of postsilking nitrogen uptake allocated to maize kernels by @@ -545,11 +734,15 @@ Nitrogen-15 labeling. Crop Sci. 47:685-693. .. _Gallowayetal2004: +|br| + Galloway, J.N., et al. 2004. Nitrogen cycles: past, present, and future. Biogeochem. 70:153-226. .. _Garciaetal1988: +|br| + Garcia, R.L., Kanemasu, E.T., Blad, B.L., Bauer, A., Hatfield, J.L., Major, D.A., Reginato, R.J., and Hubbard, K.G. 1988. Interception and use efficiency of light in winter wheat under different nitrogen @@ -557,11 +750,15 @@ regimes. Agric. For. Meteor. 44:175-186. .. _Gardner1960: -Gardner, W. R. 1960. Dynamic aspects of water availability to plants, +|br| + +Gardner, W. R. 1960. Dynamic aspects of water availability to plants, Soil Sci., 89, 63–73. .. _Gashetal1996: +|br| + Gash, J.H.C., Nobre, C.A., Roberts, J.M., and Victoria, R.L. 1996. An overview of ABRACOS. pp. 1-14. In: J.H.C. Gash, C.A. Nobre, J.M. Roberts, and R.L. Victoria (editors) Amazonian Deforestation and @@ -569,16 +766,22 @@ Climate. John Wiley and Sons, Chichester, England. .. _Getiranaetal2012: +|br| + Getirana, A. C. V., A. Boone, D. Yamazaki, B. Decharme, F. Papa, and N. Mognard. 2012. The hydrological modeling and analysis platform (HyMAP): Evaluation in the Amazon basin, J. Hydrometeorol., 13, 1641-1665. .. _Ghimireetal2016: +|br| + Ghimire, B., W. J. Riley, C. D. Koven, M. Mu, and J. T. Randerson, 2016: Representing leaf and root physiological traits in CLM improves global carbon and nitrogen cycling predictions. J. Adv. Mod. Earth Sys. 8: 598-613. .. _Gholzetal1985: +|br| + Gholz, H.L., Perry, C.S., Cropper, W.P., Jr. and Hendry, L.C., 1985. Litterfall, decomposition, and nitrogen and phosphorous dynamics in a chronosequence of slash pine (*Pinus elliottii*) plantations. Forest @@ -586,6 +789,8 @@ Science, 31: 463-478. .. _Giglioetal2006: +|br| + Giglio, L., Csiszar, I., and Justice, C.O. 2006. Global distribution and seasonality of active fires as observed with the Terra and Aqua Moderate Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. @@ -593,24 +798,32 @@ Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. .. _GlobalSoilDataTask2000: +|br| + Global Soil Data Task 2000. Global soil data products CD-ROM (IGBP-DIS). International Geosphere-Biosphere Programme-Data and Information Available Services [Available online at http://www.daac.ornl.gov]. .. _Gomesetal2003: +|br| + Gomes, E.P.C., Mantovani, W., and Kageyama, P.Y. 2003. Mortality and recruitment of trees in a secondary montane rain forest in southeastern Brazil. Brazilian Journal of Biology 63:47-60. .. _Goszetal1973: +|br| + Gosz, J.R., Likens, G.E., and Bormann, F.H. 1973. Nutrient release from decomposing leaf and branch litter in the Hubbard Brook Forest, New Hampshire. Ecological Monographs 43:173-191. .. _GotangcoCastilloetal2012: +|br| + Gotangco Castillo C., Levis S., and Thornton P. 2012. Evaluation of the new CNDV option of the Community Land Model: Effects of dynamic vegetation and interactive nitrogen on CLM4 means and variability. J. @@ -618,29 +831,39 @@ Climate 25:3702-3714. DOI:10.1175/JCLID-11-00372.1. .. _Grahametal1999: +|br| + Graham, S.T., Famiglietti, J.S., and Maidment, D.R. 1999. Five-minute, 1/2º, and 1º data sets of continental watersheds and river networks for use in regional and global hydrologic and climate system modeling studies. Water Resour. Res. 35:583-587. -.. _Gravenetal2017: +.. _Gravenetal2017: + +|br| Graven, H., C. E. Allison, D. M. Etheridge, S. Hammer, R. F. Keeling, I. Levin, H. A. J. Meijer, M. Rubino, P. P. Tans, C. M. Trudinger, B. H. Vaughn and J. W. C. White (2017) Compiled records of carbon isotopes in atmospheric CO2 for historical simulations in CMIP6, Geoscientific Model Development, in review. doi: 10.5194/gmd-2017-166. .. _GrenfellWarren1999: +|br| + Grenfell, T.C., and Warren, S.G. 1999. Representation of a nonspherical ice particle by a collection of independent spheres for scattering and absorption of radiation. J. Geophys. Res. 104(D24):37697-37709. .. _delGrossoetal2000: +|br| + del Grosso, S.J., et al. 2000. General model for N2O and N2 gas emissions from soils due to dentrification. Global Biogeochem. Cycles 14:1045-1060. .. _Guentheretal1995: +|br| + Guenther, A., Hewitt, C.N., Erickson, D., Fall, R., Geron, C., Graedel, T., Harley, P., Klinger, L., Lerdau, M., McKay, W.A., Pierce, T., Scholes, B., Steinbrecher, R., Tallamraju, R., Taylor, J., and @@ -649,6 +872,8 @@ emissions. J. Geophys. Res. 100:8873-8892. .. _Guentheretal2006: +|br| + Guenther, A., Karl, T., Harley, P., Wiedinmyer, C., Palmer. P.I., and Geron, C. 2006. Estimates of global terrestrial isoprene emissions using MEGAN (Model of Emissions of Gases and Aerosols from Nature). Atmos. @@ -656,6 +881,8 @@ Chem. Phys. 6:3181–3210. .. _Guentheretal2012: +|br| + Guenther, A. B., Jiang, X., Heald, C. L., Sakulyanontvittaya, T., Duhl, T., Emmons, L. K., & Wang, X., 2012. The Model of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1): an extended and updated @@ -664,6 +891,8 @@ framework for modeling biogenic emissions, Geosci. Model Dev., 5, .. _Hacketal2006: +|br| + Hack, J.J., Caron, J.M., Yeager, S.G., Oleson, K.W., Holland, M.M., Truesdale, J.E., and Rasch, P.J. 2006. Simulation of the global hydrological cycle in the CCSM Community Atmosphere Model version 3 @@ -671,6 +900,8 @@ hydrological cycle in the CCSM Community Atmosphere Model version 3 .. _Hansenetal2003: +|br| + Hansen, M., DeFries, R.S., Townshend, J.R.G., Carroll, M., Dimiceli, C., and Sohlberg, R.A. 2003. Global percent tree cover at a spatial resolution of 500 meters: first results of the MODIS vegetation @@ -678,6 +909,8 @@ continuous fields algorithm. Earth Interactions 7:1-15. .. _Hastingsetal1999: +|br| + Hastings, D.A., Dunbar, P.K., Elphingstone, G.M., Bootz, M., Murakami, H., Maruyama, H., Masaharu, H., Holland, P., Payne, J., Bryant, N.A., Logan, T.L., Muller, J.-P., Schreier, G., and MacDonald, J.S., eds., @@ -688,6 +921,8 @@ Colorado 80305-3328, U.S.A. .. _Healdetal2008: +|br| + Heald, C.L., Henze, D.K., Horowitz, L.W., Feddema, J., Lamarque, J.-F., Guenther, A., Hess, P.G., Vitt, F., Seinfeld, J.H., Goldstein, A.H., and Fung, I. 2008. Predicted change in global secondary organic aerosol @@ -696,6 +931,8 @@ change. J. Geophys. Res. 113:D05211. DOI:10.1029/2007JD009092. .. _Healdetal2009: +|br| + Heald, C.L., Wilkinson, M.J., Monson, R.K., Alo, C.A., Wang, G.L., and Guenther, A. 2009. Response of isoprene emission to ambient CO\ :sub:`2` changes and implications for global budgets. Global @@ -703,40 +940,54 @@ Change Biol. 15:1127-1140. DOI:10.1111/j.1365-2486.2008.01802.x .. _Henderson-Sellers1985: +|br| + Henderson-Sellers, B. 1985. New formulation of eddy diffusion thermocline models. Appl. Math. Modelling 9:441-446. .. _Henderson-Sellers1986: +|br| + Henderson-Sellers, B. 1986. Calculating the surface energy balance for lake and reservoir modeling: A review. Rev. Geophys. 24:625-649. .. _Henderson-Sellersetal1993: +|br| + Henderson-Sellers, A., Yang, Z.-L., and Dickinson, R.E. 1993. The project for intercomparison of land-surface parameterization schemes. Bull. Amer. Meteor. Soc. 74: 1335-1349. .. _HostetlerBartlein1990: +|br| + Hostetler, S.W., and Bartlein, P.J. 1990. Simulation of lake evaporation with application to modeling lake level variations of Harney-Malheur Lake, Oregon. Water Resour. Res. 26:2603-2612. .. _Hostetleretal1993: +|br| + Hostetler, S.W., Bates, G.T., and Giorgi, F. 1993. Interactive coupling of a lake thermal model with a regional climate model. J. Geophys. Res. 98:5045-5057. .. _Hostetleretal1994: +|br| + Hostetler, S.W., Giorgi, F., Bates, G.T., and Bartlein, P.J. 1994. Lake-atmosphere feedbacks associated with paleolakes Bonneville and Lahontan. Science 263:665-668. .. _Houetal2012: +|br| + Hou, Z., Huang, M., Leung, L.R., Lin, G., and Ricciuto, D.M. 2012. Sensitivity of surface flux simulations to hydrologic parameters based on an uncertainty quantification framework applied to the Community Land @@ -744,10 +995,14 @@ Model. J. Geophys. Res. 117:D15108. .. _Houltonetal2008: +|br| + Houlton, B.Z., Wang, Y.P., Vitousek, P.M. and Field, C.B., 2008. A unifying framework for dinitrogen fixation in the terrestrial biosphere. Nature, 454(7202), p.327. .. _HuangLiang2006: +|br| + Huang, M., and Liang, X. 2006. On the assessment of the impact of reducing parameters and identification of parameter uncertainties for a hydrologic model with applications to ungauged basins. J. Hydrol. @@ -755,6 +1010,8 @@ hydrologic model with applications to ungauged basins. J. Hydrol. .. _Hugeliusetal2012: +|br| + Hugelius, G., C. Tarnocai, G. Broll, J.G. Canadell, P. Kuhry, adn D.K. Swanson, 2012. The Northern Circumpolar Soil Carbon Database: spatially distributed datasets of soil coverage and soil carbon storage in the @@ -763,18 +1020,24 @@ northern permafrost regions. Earth Syst. Sci. Data Discuss., 5, 707-733 .. _Huntetal1988: +|br| + Hunt, H.W., Ingham, E.R., Coleman, D.C., Elliott, E.T., and Reid, C.P.P. 1988. Nitrogen limitation of production and decomposition in prairie, mountain meadow, and pine forest. Ecology 69:1009-1016. .. _HuntRunning1992: +|br| + Hunt, E.R., Jr. and Running, S.W., 1992. Simulated dry matter yields for aspen and spruce stands in the north american boreal forest. Canadian Journal of Remote Sensing, 18: 126-133. .. _Huntetal1996: +|br| + Hunt, E.R., Jr. et al., 1996. Global net carbon exchange and intra-annual atmospheric CO\ :sub:`2` concentrations predicted by an ecosystem process model and three-dimensional atmospheric transport @@ -782,6 +1045,8 @@ model. Global Biogeochemical Cycles, 10: 431-456. .. _Hurttetal2006: +|br| + Hurtt, G.C., Frolking, S., Fearon, M.G., Moore, B., Shevliakova, E., Malyshev, S., Pacala, S.W., and Houghton, R.A. 2006. The underpinnings of land-use history: three centuries of global gridded land-use @@ -790,6 +1055,8 @@ Global Change Biol. 12:1208-1229. .. _Hurttetal2011: +|br| + Hurtt, G.C., et al. 2011. Harmonization of land-use scenarios for the period 1500-2100: 600 years of global gridded annual land-use transitions, wood harvest, and resulting secondary lands. Climatic @@ -797,23 +1064,31 @@ Change 109:117-161. DOI:10.1007/s10584-011-0153-2. .. _Idso1981: +|br| + Idso, S.B. 1981. A set of equations for full spectrum and 8- to 14-\ :math:`\mu` \ m and 10.5- to 12.5-\ :math:`\mu` \ m thermal radiation from cloudless skies. Water Resour. Res. 17:295-304. .. _IiyamaHasegawa2005: +|br| + Iiyama, I. and Hasegawa, S., 2005. Gas diffusion coefficient of undisturbed peat soils. Soil Science and Plant Nutrition 51:431-435. .. _Jacksonetal1996: +|br| + Jacksonetal1996: E., and Schulze, E. D. 1996. A global analysis of root distributions for terrestrial biomes Oecologia 108:389–411. DOI:10.1007/BF00333714. .. _Jacksonetal2010: +|br| + Jackson, T.L., Feddema, J.J., Oleson, K.W., Bonan, G.B., and Bauer, J.T. 2010. Parameterization of urban characteristics for global climate modeling. Annals of the Association of American Geographers. @@ -821,24 +1096,32 @@ modeling. Annals of the Association of American Geographers. .. _JenkinsonColeman2008: +|br| + Jenkinson, D. and Coleman, K. 2008. The turnover of organic carbon in subsoils. Part 2. Modelling carbon turnover. European Journal of Soil Science 59:400-413. .. _Jordan1991: +|br| + Jordan, R. 1991. A One-dimensional Temperature Model for a Snow Cover: Technical Documentation for SNTHERM.89. U.S. Army Cold Regions Research and Engineering Laboratory, Special Report 91-16. .. _KattgeKnorr2007: +|br| + Kattge, J., and Knorr, W. 2007. Temperature acclimation in a biochemical model of photosynthesis: a reanalysis of data from 36 species. Plant Cell Environ. 30:1176-1190. DOI:10.1111/j.1365-3040.2007.01690.x. .. _Kattgeetal2009: +|br| + 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 Biol. @@ -846,18 +1129,24 @@ for global–scale terrestrial biosphere models. Global Change Biol. .. _Kavetskietal2002: -Kavetski, D., Binning, P. and Sloan, S.W., 2002. Noniterative time -stepping schemes with adaptive truncation error control for the +|br| + +Kavetski, D., Binning, P. and Sloan, S.W., 2002. Noniterative time +stepping schemes with adaptive truncation error control for the solution of Richards equation. Water Resources Research, 38(10). .. _Kelleretal2004: +|br| + Keller, M., Palace, M., Asner, G.P., Pereira, R., Jr. and Silva, J.N.M., 2004. Coarse woody debris in undisturbed and logged forests in the eastern Brazilian Amazon. Global Change Biology, 10: 784-795. .. _Kellneretal2006: +|br| + Kellner, E., Baird, A.J., Oosterwoud, M., Harrison, K. and Waddington, J.M., 2006. Effect of temperature and atmospheric pressure on methane (CH4) ebullition from near-surface peats. Geophys. Res. Lett. 33. @@ -865,24 +1154,32 @@ DOI:10.1029/2006GL027509. .. _Kimballetal1997: +|br| + Kimball, J.S., Thornton, P.E., White, M.A. and Running, S.W. 1997. Simulating forest productivity and surface-atmosphere exchange in the BOREAS study region. Tree Physiology 17:589-599. .. _Kohyamaetal2001: +|br| + Kohyama, T., Suzuki, E., Partomihardjo, T., and Yamada, T. 2001. Dynamic steady state of patch-mosaic tree size structure of a mixed diptocarp forest regulated by local crowding. Ecological Research 16:85-98. .. _Kourzeneva2009: +|br| + Kourzeneva, E., 2009. Global dataset for the parameterization of lakes in Numerical Weather Prediction and Climate modeling. ALADIN Newsletter, No 37, July-December, 2009, F. Bouttier and C. Fischer, Eds., Meteo-France, Toulouse, France, 46-53. -.. _Kourzeneva2010: +.. _Kourzeneva2010: + +|br| Kourzeneva, E., 2010: External data for lake parameterization in Numerical Weather Prediction and climate modeling. Boreal Environment @@ -890,30 +1187,40 @@ Research, 15, 165-177. .. _Kourzenevaetal2012: +|br| + Kourzeneva, E., Asensio, H., Martin, E. and Faroux, S., 2012. Global gridded dataset of lake coverage and lake depth for use in numerical weather prediction and climate modelling. Tellus A 64. .. _Kovenetal2009: +|br| + Koven, C., et al. 2009. On the formation of high-latitude soil carbon stocks: The effects of cryoturbation and insulation by organic matter in a land surface model. Geophys. Res. Lett. 36: L21501. .. _Kovenetal2011: +|br| + Koven, C.D., et al. 2011. Permafrost carbon-climate feedbacks accelerate global warming. Proceedings of the National Academy of Sciences 108:14769-14774. .. _Kovenetal2013: +|br| + Koven, C.D. et al. 2013. The effect of vertically-resolved soil biogeochemistry and alternate soil C and N models on C dynamics of CLM4. Biogeosciences Discussions 10:7201-7256. .. _Kovenetal2015: +|br| + Koven, C.D. et al. 2015. Permafrost carbon-climate feedback is sensitive to deep soil carbon decomposability but not deep soil nitrogen dynamics. Proceedings of the National Academies of Science, @@ -921,10 +1228,14 @@ nitrogen dynamics. Proceedings of the National Academies of Science, .. _Kovenetal2017: +|br| + Koven, C.D., G. Hugelius, D.M. Lawrence, and W.R. Wieder, 2017: Higher climatological temperature sensitivity of soil carbon in cold than warm climates. Nature Clim. Change, 7, doi:10.1038/nclimate3421. .. _Kuchariketal2000: +|br| + Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., Lenters, J.D., Young-Molling, C., and Ramankutty, N. 2000. Testing the performance of a dynamic global ecosystem model: water balance, carbon @@ -933,6 +1244,8 @@ balance, and vegetation structure. Global Biogeochem. Cycles 14: .. _KucharikBrye2003: +|br| + Kucharik, C.J., and Brye, K.R. 2003. Integrated BIosphere Simulator (IBIS) yield and nitrate loss predictions for Wisconsin maize receiving varied amounts of nitrogen fertilizer. Journal of Environmental Quality @@ -940,6 +1253,8 @@ varied amounts of nitrogen fertilizer. Journal of Environmental Quality .. _Laddetal2992: +|br| + Ladd, J.N., Jocteur-Monrozier, L. and Amato, M., 1992. Carbon turnover and nitrogen transformations in an alfisol and vertisol amended with [U-:math:`{}^{14}`\ C] glucose and [:math:`{}^{15}`\ N] ammonium @@ -947,6 +1262,8 @@ sulfate. Soil Biology and Biochemistry, 24: 359-371. .. _Lamarqueetal2010: +|br| + Lamarque, J.-F., et al. 2010. Historical (1850-2000) gridded anthropogenic and biomass burning emissions of reactive gases and aerosols: methodology and application. Atmos. Chem. Phys. Discuss. @@ -954,23 +1271,31 @@ aerosols: methodology and application. Atmos. Chem. Phys. Discuss. .. _Larcher1995: +|br| + Larcher, W. 1995. Physiological Plant Ecology, Springer-Verlag, Berlin Heidelberg. .. _LavigneRyan1997: +|br| + Lavigne, M.B., and Ryan, M.G. 1997. Growth and maintenance respiration rates of aspen, black spruce, and jack pine stems at northern and southern BOREAS sites. Tree Phys. 17:543-551. .. _Lawetal2003: +|br| + Law, B.E., Sun, O.J., Campbell, J., Van Tuyl, S. and Thornton, P.E. 2003. Changes in carbon storage and fluxes in a chronosequence of ponderosa pine. Global Change Biology, 9: 510-514. .. _Lawrenceetal2007: +|br| + Lawrence, D.M., Thornton, P.E., Oleson, K.W., and Bonan, G.B. 2007. The partitioning of evapotranspiration into transpiration, soil evaporation, and canopy evaporation in a GCM: Impacts on land-atmosphere interaction. @@ -978,11 +1303,15 @@ J. Hydrometeor. 8:862-880. .. _LawrenceSlater2008: +|br| + Lawrence, D.M., and Slater, A.G. 2008. Incorporating organic soil into a global climate model. Clim. Dyn. 30. DOI:10.1007/s00382-007-0278-1. .. _Lawrenceetal2008: +|br| + Lawrence, D.M., Slater, A.G., Romanovsky, V.E., and Nicolsky, D.J. 2008. The sensitivity of a model projection of near-surface permafrost degradation to soil column depth and inclusion of soil organic matter. @@ -990,6 +1319,8 @@ J. Geophys. Res. 113:F02011. DOI:10.1029/2007JF000883. .. _Lawrenceetal2011: +|br| + Lawrence, D.M., K.W. Oleson, M.G. Flanner, P.E. Thornton, S.C. Swenson, P.J. Lawrence, X. Zeng, Z.-L. Yang, S. Levis, K. Sakaguchi, G.B. Bonan, and A.G. Slater, 2011. Parameterization improvements and functional and @@ -998,27 +1329,35 @@ Model. Earth Sys. 3. DOI:10.1029/2011MS000045. .. _Lawrenceetal2016: -Lawrence, D.M., Hurtt, G.C., Arneth, A., Brovkin, V., Calvin, K.V., +|br| + +Lawrence, D.M., Hurtt, G.C., Arneth, A., Brovkin, V., Calvin, K.V., Jones, A.D., Jones, C.D., Lawrence, P.J., de Noblet-Ducoudré, N., Pongratz, -J., Seneviratne, S.I., and Shevliakova, E. 2016. The Land Use Model +J., Seneviratne, S.I., and Shevliakova, E. 2016. The Land Use Model Intercomparison Project (LUMIP) contribution to CMIP6: rationale and experimental design. Geosci. Model Dev. 9:2973-2998. -DOI:10.5194/gmd-9-2973-2016. +DOI:10.5194/gmd-9-2973-2016. .. _LawrenceChase2007: +|br| + Lawrence, P.J., and Chase, T.N. 2007. Representing a MODIS consistent land surface in the Community Land Model (CLM 3.0). J. Geophys. Res. 112:G01023. DOI:10.1029/2006JG000168. .. _LawrenceChase2010: +|br| + Lawrence, P.J., and Chase, T.N. 2010. Investigating the climate impacts of global land cover change in the Community Climate System Model. Int. J. Climatol. 30:2066-2087. DOI:10.1002/joc.2061. .. _Lawrenceetal2012: +|br| + Lawrence, P.J., et al. 2012. Simulating the biogeochemical and biogeophysical impacts of transient land cover change and wood harvest in the Community Climate System Model (CCSM4) from 1850 to 2100. J. @@ -1026,16 +1365,22 @@ Climate 25:3071-3095. DOI:10.1175/JCLI-D-11-00256.1. .. _LehnerDoll2004: +|br| + Lehner, B. and Döll, P., 2004. Development and validation of a global database of lakes, reservoirs and wetlands, J. Hydrol., 296, 1–22. .. _Lehneretal2008: +|br| + Lehner, B., Verdin, K. and Jarvis, A., 2008. New global hydrograhy derived from spaceborne elevation data. Eos Trans., AGU, 89, 93 – 94. .. _LePageetal2010: +|br| + Le Page, Y., van der Werf, G.R., Morton, D.C., and Pereira, J.M.C. 2010. Modeling fire-driven deforestation potential in Amazonia under current and projected climate conditions. J. Geophys. Res. 115:G03012. @@ -1043,17 +1388,23 @@ DOI:10.1029/2009JG001190. .. _Lerman1979: +|br| + Lerman, A., 1979. Geochemical processes: Water and sediment environments. John Wiley and Sons, New York, N.Y. .. _Lettsetal2000: +|br| + Letts, M.G., Roulet, N.T., Comer, N.T., Skarupa, M.R., and Verseghy, D.L. 2000. Parametrization of peatland hydraulic properties for the Canadian Land Surface Scheme. Atmos.-Ocean 38:141-160. .. _Levisetal2003: +|br| + Levis, S., Wiedinmyer, C., Bonan, G.B., and Guenther, A. 2003. Simulating biogenic volatile organic compound emissions in the Community Climate System Model. J. Geophys. Res. 108:4659. @@ -1061,6 +1412,8 @@ DOI:10.1029/2002JD003203. .. _Levisetal2004: +|br| + Levis, S., Bonan, G.B., Vertenstein, M., and Oleson, K.W. 2004. The community land model’s dynamic global vegetation model (CLM-DGVM): technical description and user’s guide. NCAR Technical Note @@ -1069,12 +1422,16 @@ Colorado. 50 pp. .. _Levisetal2009: +|br| + Levis, S., Thornton, P., Bonan, G., and Kucharik, C. 2009. Modeling land use and land management with the Community Land Model. iLeaps newsletter, No. 7. .. _Levisetal2012: +|br| + Levis, S., Bonan, G., Kluzek, E., Thornton, P., Jones, A., Sacks, W., and Kucharik, C 2012. Interactive crop management in the Community Earth System Model (CESM1): Seasonal influences on land-atmosphere fluxes. J. @@ -1082,24 +1439,32 @@ Climate 25: 4839-4859. DOI:10.1175/JCLI-D-11-00446.1. .. _Levisetal2016: +|br| + Levis, S., Badger, A., Drewniak, B., Nevison, C., Ren, X. 2016. CLMcrop yields and water requirements: avoided impacts by choosing RCP 4.5 over 8.5. -Climatic Change. DOI:10.1007/s10584-016-1654-9. +Climatic Change. DOI:10.1007/s10584-016-1654-9. .. _Lietal2000: +|br| + Li, C., Aber, J., Stange, F., Butterbach-Bahl, K. and Papen, H. 2000. A process-oriented model of N2O and NO emissions from forest soils: 1. Model development. J. Geophys. Res. 105(D4):4369-4384. .. _Lietal2012a: +|br| + Li, F., Zeng, X.-D., and Levis, S. 2012a. A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model. Biogeosciences 9:2761-2780. .. _Lietal2012b: +|br| + Li, F., Zeng, X. D., and Levis, S. 2012b. Corrigendum to “A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model†published in Biogeosciences, 9, @@ -1107,18 +1472,24 @@ Dynamic Global Vegetation Model†published in Biogeosciences, 9, .. _Lietal2013a: +|br| + Li, F., Levis, S., and Ward, D. S. 2013a. Quantifying the role of fire in the Earth system – Part 1: Improved global fire modeling in the Community Earth System Model (CESM1). Biogeosciences 10:2293-2314. .. _LiLawrence2017: -Li, F., and Lawrence, D. 2017. Role of fire in the global land water -budget during the 20th century through changing ecosystems. +|br| + +Li, F., and Lawrence, D. 2017. Role of fire in the global land water +budget during the 20th century through changing ecosystems. J. Clim. 30: 1894-1908. .. _Lietal2013b: +|br| + Li, H.-Y., Huang, M., Tesfa, T., Ke, Y., Sun, Y., Liu, Y., and Leung, L. R. 2013b. A subbasin-based framework to represent land surface processes in an Earth System Model, Geosci. Model Dev. Discuss. 6:2699-2730. @@ -1126,6 +1497,8 @@ DOI:10.5194/gmdd-6-2699-2013. .. _Lietal2011: +|br| + Li, H., Huang, M., Wigmosta, M.S., Ke, Y., Coleman, A.M., Leung, L.R., Wang, A., and Ricciuto, D.M. 2011. Evaluating runoff simulations from the Community Land Model 4.0 using observations from flux towers and a @@ -1134,13 +1507,17 @@ DOI:10.1029/2011JD016276. .. _Lietal2015a: -Li, H., L. Leung, A. Getirana, M. Huang, H. Wu, Y. Xu, J. Guo and -N. Voisin. 2015a. Evaluating global streamflow simulations by a -physically-based routing model coupled with the Community Land Model, +|br| + +Li, H., L. Leung, A. Getirana, M. Huang, H. Wu, Y. Xu, J. Guo and +N. Voisin. 2015a. Evaluating global streamflow simulations by a +physically-based routing model coupled with the Community Land Model, J. of Hydromet., 16(2):948-971, doi: 10.1175/JHM-D-14-0079.1 .. _Lietal2015b: +|br| + Li, H., L. Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang. 2015. Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. @@ -1148,41 +1525,55 @@ Earth Syst., 7, doi:10.1002/2015MS000471. .. _Liangetal1994: +|br| + Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A simple hydrologically based model of land surface water and energy fluxes for GSMs. J. Geophys. Res. 99(D7):14,415–14,428. .. _LipscombSacks2012: +|br| + Lipscomb, W., and Sacks, W. 2012. The CESM land ice model documentation and user’s guide. 46 pp. [Available online at http://www.cesm.ucar.edu/models/cesm1.1/cism/]. .. _LloydTaylor1994: +|br| + Lloyd, J. and Taylor, J.A., 1994. On the temperature dependence of soil respiration. Functional Ecology, 8: 315-323. .. _Lloydetal2010: +|br| + Lloyd, J., et al. 2010. Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees. Biogeosci. 7:1833-1859. DOI:10.5194/bg-7-1833-2010. .. _Lobelletal2006: +|br| + Lobell, D.B., Bala, G., and Duffy, P.B. 2006. Biogeophysical impacts of cropland management changes on climate. Geophys. Res. Lett. 33:L06708. DOI:10.1029/2005GL025492. .. _Lombardozzietal2015: +|br| + Lombardozzi, D.L., Bonan, G.B., Smith, N.G., Dukes, J.S. 2015. Temperature -acclimation of photosynthesis and respiration: A key uncertainty in the +acclimation of photosynthesis and respiration: A key uncertainty in the carbon cycle-climate feedback. Geophys. Res. Lett. 42:8624-8631. .. _Lovelandetal2000: +|br| + Loveland, T.R., Reed, B.C., Brown, J.F., Ohlen, D.O., Zhu, Z., Yang, L., and Merchant, J.W. 2000. Development of a global land cover characteristics database and IGBP DISCover from 1 km AVHRR data. Int. J. @@ -1190,23 +1581,31 @@ Remote Sens. 21:1303-1330. .. _Lowe1977: +|br| + Lowe, P.R. 1977. An approximating polynomial for the computation of saturation vapor pressure. J. Appl. Meteor. 16:100-103. .. _Luoetal2006: +|br| + Luo, Y., Hui, D., and Zhang, D. 2006. Elevated CO2 stimulates net accumulations of carbon and nitrogen in land ecosystems: a meta-analysis. Ecology 87:53-63. .. _Magilletal1997: +|br| + Magill, A.H. et al., 1997. Biogeochemical response of forest ecosystems to simulated chronic nitrogen deposition. Ecological Applications, 7: 402-415. .. _Mahowaldetal2006: +|br| + Mahowald, N.M., Muhs, D.R., Levis, S., Rasch, P.J., Yoshioka, M., Zender, C.S., and Luo, C. 2006. Change in atmospheric mineral aerosols in response to climate: last glacial period, pre-industrial, modern and @@ -1215,17 +1614,23 @@ DOI:10.1029/2005JD006653. .. _Makela2002: +|br| + Makela, A. 2002. Derivation of stem taper from the pipe model theory in a carbon balance framework. Tree Phys. 22:891-905. .. _Maoetal2012: +|br| + Mao, J., Thornton, P.E., Shi, X., Zhao, M., and Post, W.M. 2012. Remote sensing evaluation of CLM4 GPP for the period 2000 to 2009. J. Climate 25:5327-5342. .. _Maoetal2013: +|br| + Mao, J., Shi, X., Thornton, P.E., Hoffman, F.M., Zhu, Z., and Ranga B. Myneni, R.B. 2013. Global latitudinal-asymmetric vegetation growth trends and their driving mechanisms: 1982-2009. Remote Sensing @@ -1233,18 +1638,24 @@ trends and their driving mechanisms: 1982-2009. Remote Sensing .. _Martinetal1980: +|br| + Martin, J.P., Haider, K. and Kassim, G., 1980. Biodegradation and stabilization after 2 years of specific crop, lignin, and polysaccharide carbons in soils. Soil Science Society of America Journal 44:1250-1255. .. _Maryetal1993: +|br| + Mary, B., Fresneau, C., Morel, J.L. and Mariotti, A., 1993. C and N cycling during decomposition of root mucilage, roots and glucose in soil. Soil Biology and Biochemistry 25:1005-1014. .. _McGuireetal1992: +|br| + McGuire, A.D., Melillo, J.M., Joyce, L.A., Kicklighter, D.W., Grace, A.L., Moore III, B., and Vorosmarty, C.J. 1992. Interactions between carbon and nitrogen dynamics in estimating net primary productivity for @@ -1253,53 +1664,71 @@ potential vegetation in North America. Global Biogeochem. Cycles .. _Medlynetal2011: -Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., -Barton, C.V.M., 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. +|br| + +Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., +Barton, C.V.M., 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. doi:10.1111/j.1365-2486.2010.02375.x .. _MelzerOLeary1987: +|br| + Melzer, E., and O’Leary, M.H. 1987. Anapleurotic CO2 Fixation by Phosphoenolpyruvate Carboxylase in C3 Plants. Plant. Physiol. 84:58. .. _Milleretal1994: +|br| + Miller, J.R., Russell, G.L., and Caliri, G. 1994. Continental-scale river flow in climate models. J. Climate 7:914-928. .. _MillingtonQuirk1961: +|br| + Millington, R. and Quirk, J.P., 1961. Permeability of Porous Solids. Transactions of the Faraday Society 57:1200-1207. .. _Mironovetal2010: +|br| + Mironov, D. et al., 2010. Implementation of the lake parameterisation scheme FLake into the numerical weather prediction model COSMO. Boreal Environment Research 15:218-230. .. _MitchellJones2005: +|br| + Mitchell, T.D., and Jones, P.D. 2005. An improved method of constructing a database of monthly climate observations and associated high-resolution grids. Int. J. Climatol. 25:693-712. .. _Moldrupetal2003: +|br| + Moldrup, P. et al. 2003. Modeling diffusion and reaction in soils: X. A unifying model for solute and gas diffusivity in unsaturated soil. Soil Science 168:321-337. .. _Mynenietal2002: +|br| + Myneni, R.B., et al. 2002. Global products of vegetation leaf area and fraction absorbed PAR from year one of MODIS data. Remote Sens. Environ. 83:214-231. .. _Neffetal2005: +|br| + Neff, J.C., Harden, J.W. and Gleixner, G. 2005. Fire effects on soil organic matter content, composition, and nutrients in boreal interior Alaska. Canadian Journal of Forest Research-Revue Canadienne De @@ -1307,6 +1736,8 @@ Recherche Forestiere 35:2178-2187. .. _Neitschetal2005: +|br| + Neitsch, S.L., Arnold, J.G., Kiniry, J.R., and Williams J.R. 2005. Soil and Water Assessment Tool, Theoretical Documentation: Version 2005. Temple, TX. USDA Agricultural Research Service and Texas A&M Blackland @@ -1314,17 +1745,23 @@ Research Center. .. _NegronJuarezetal2015: +|br| + Negron-Juarez, R. Koven, C.D., Riley, W.J., Knox, R.G., Chambers, J.Q. 2015. Environmental Research Letters 10:064017. DOI:10.1088/1748-9326/10/6/064017. .. _NemaniRunning1996: +|br| + Nemani, R.R., and Running, S.W. 1996. Implementation of a hierarchical global vegetation classification in ecosystem function models. J. Veg. Sci. 7:337-346. .. _Niinemetstal1998: +|br| + Niinemets, U., Kull, O., and Tenhunen, J.D. 1998. An analysis of light effects on foliar morphology, physiology, and light interception in temperate deciduous woody species of contrasting shade tolerance. Tree @@ -1332,12 +1769,16 @@ Phys. 18:681-696. .. _Niuetal2005: +|br| + Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. .. _NiuYang2006: +|br| + Niu, G.-Y., and Yang, Z.-L. 2006. Effects of frozen soil on snowmelt runoff and soil water storage at a continental scale. J. Hydrometeor. 7:937-952. @@ -1353,17 +1794,23 @@ basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674. .. _Oikawaetal2005: +|br| + Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and nitrogen in the canopy of an annual herb, Xanthium canadense. Oecologia, 143: 517-526. .. _Oke1987: +|br| + Oke, T. 1987. Boundary Layer Climates (2:math:`{}^{nd}` edition). Routledge, London and New York. .. _OlesonBonan2000: +|br| + Oleson, K.W., and Bonan, G.B. 2000. The effects of remotely-sensed plant functional type and leaf area index on simulations of boreal forest surface fluxes by the NCAR land surface model. J. Hydrometeor. @@ -1371,6 +1818,8 @@ surface fluxes by the NCAR land surface model. J. Hydrometeor. .. _Olesonetal2004: +|br| + Oleson, K.W., Dai, Y., Bonan, G., Bosilovich, M., Dickinson, R., Dirmeyer, P., Hoffman, F., Houser, P., Levis, S., Niu, G.-Y., Thornton, P., Vertenstein, M., Yang, Z.-L., and Zeng. X. 2004. Technical @@ -1380,6 +1829,8 @@ Colorado. 173 pp. .. _Olesonetal2008a: +|br| + Oleson, K.W., Niu, G.-Y., Yang, Z.-L., Lawrence, D.M., Thornton, P.E., Lawrence, P.J., Stöckli, R., Dickinson, R.E., Bonan, G.B., Levis, S., Dai, A., and Qian, T. 2008a. Improvements to the Community Land Model @@ -1388,6 +1839,8 @@ DOI:10.1029/2007JG000563. .. _Olesonetal2008b: +|br| + Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Grimmond, C.S.B. 2008b. An urban parameterization for a global climate model. 1. Formulation and evaluation for two cities. J. Appl. Meteor. Clim. @@ -1395,6 +1848,8 @@ Formulation and evaluation for two cities. J. Appl. Meteor. Clim. .. _Olesonetal2008c: +|br| + Oleson, K.W., Bonan, G.B., Feddema, J., and Vertenstein, M. 2008c. An urban parameterization for a global climate model. 2. Sensitivity to input parameters and the simulated urban heat island in offline @@ -1402,12 +1857,16 @@ simulations. J. Appl. Meteor. Clim. 47:1061-1076. .. _Olesonetal2010a: +|br| + Oleson, K.W., et al. 2010a. Technical description of version 4.0 of the Community Land model (CLM). NCAR Technical Note NCAR/TN-478+STR, National Center for Atmospheric Research, Boulder, CO, 257 pp. .. _Olesonetal2010b: +|br| + Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Kluzek, E. 2010b. Technical description of an urban parameterization for the Community Land Model (CLMU). NCAR Technical Note NCAR/TN-480+STR, @@ -1415,17 +1874,23 @@ National Center for Atmospheric Research, Boulder, CO, 169 pp. .. _Olesonetal2013: -Oleson, K.W., et al. 2013. Technical description of version 4.5 of the +|br| + +Oleson, K.W., et al. 2013. Technical description of version 4.5 of the Community Land Model (CLM). NCAR Technical Note NCAR/TN-503+STR, National Center for Atmospheric Research, Boulder, CO, 420 pp. .. _Olson1963: +|br| + Olson, J.S., 1963. Energy storage and the balance of producers and decomposers in ecological systems. Ecology 44:322-331. .. _Olsonetal2001: +|br| + Olson, D.M., Dinerstein, E., Wikramanayake, E.D., Burgess, N.D., Powell, G.V.N., Underwood, E.C., D’Amico, J.A., Itoua, I., Strand, H. E., Morrison, J. C., Loucks, C. J., Allnutt, T. F., Ricketts, T. H., Kura, @@ -1435,17 +1900,23 @@ Bioscience, 51, 933–938. .. _OrchardCook1983: +|br| + Orchard, V.A. and Cook, F.J., 1983. Relationship between soil respiration and soil moisture. Soil Biology and Biochemistry, 15: 447-453. .. _Owen1964: +|br| + Owen, P.R. 1964. Saltation of uniform grains in air. J. Fluid Mech\ *.* 20:225-242. .. _Ozdoganetal2010: +|br| + Ozdogan, M., Rodell, M., Beaudoing, H.K., and Toll, D.L. 2010. Simulating the effects of irrigation over the United States in a land surface model based on satellite-derived agricultural data. Journal of @@ -1453,80 +1924,110 @@ Hydrometeorology 11:171-184. .. _Pageetal2002: +|br| + Page, S.E., Siegert, F., Rieley, J.O., Boehm, H-D.V., Jaya, A., and Limin, S. 2002. The amount of carbon released from peat and forest fires in Indonesia in 1997. Nature 420:61-65. .. _PanofskyDutton1984: +|br| + Panofsky, H.A., and Dutton, J.A. 1984. Atmospheric Turbulence: Models and Methods for Engineering Applications. John Wiley and Sons, New York. .. _Partonetal1988: +|br| + Parton, W., Stewart, J. and Cole, C., 1988. Dynamics of C, N, P And S in Grassland Soils - A Model. Biogeochemistry 5:109-131. .. _Partonetal1993: +|br| + Parton, W.J., et al. 1993. Observations and modeling of biomass and soil organic matter dynamics for the grassland biome worlwide. Global Biogeochemical Cycles 7:785-809. .. _Partonetal1996: +|br| + Parton, W. et al. 1996. Generalized model for N2 and N2O production from nitrification and denitrification. Global Biogeochemical Cycles 10:401-412. .. _Partonetal2001: +|br| + Parton, W.J. et al. 2001. Generalized model for NOx and N2O emissions from soils. J. Geophys. Res. 106(D15):17403-17419. .. _Paterson1994: +|br| + Paterson, W.S.B., 1994. The Physics of Glaciers. Elsevier Science Inc., New York, 480 pp. .. _Pelletieretal2016: +|br| + Pelletier, J. D., P. D. Broxton, P. Hazenberg, X. Zeng, P. A. Troch, G. Y. Niu, Z. Williams, M. A. Brunke, and D. Gochis, 2016: A gridded global data set of soil, intact regolith, and sedimentary deposit thicknesses for regional and global land surface modeling. J. Adv. Mod. Earth Sys. 8:41-65. .. _Petrescuetal2010: +|br| + Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions of boreal and arctic wetlands. Global Biogeochemical Cycles, 24(GB4009). .. _Philip1957: +|br| + Philip, J.R. 1957. Evaporation, and moisture and heat fields in the soil. J. Meteor. 14:354-366. .. _Piaoetal2012: +|br| + Piao, S.L., et al. 2012. The carbon budget of terrestrial ecosystems in East Asia over the last two decades. Biogeosciences 9:3571-3586. .. _Pivovarov1972: +|br| + Pivovarov, A.A., 1972. Thermal Conditions in Freezing Lakes and Reservoirs. John Wiley, New York. .. _Pollmeretal1979: +|br| + Pollmer, W.G., Eberhard, D., Klein, D., and Dhillon, B.S. 1979. Genetic control of nitrogen uptake and translocation in maize. Crop Sci. 19:82-86. .. _Pomeroyetal1998: +|br| + Pomeroy, J. W., D. M. Gray, K. R. Shook, B. Toth, R. L. H. Essery, A. Pietroniro, and N. Hedstrom. 1998. An evaluation of snow accumulation and ablation processes for land surface modelling. Hydrol. Process. 12:2339–2367. .. _Portmannetal2010: +|br| + Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global monthly irrigated and rainfed crop areas around the year 2000: A new high-resolution data set for agricultural and hydrological modeling. @@ -1534,18 +2035,24 @@ Global Biogeochem. Cycles. 24, GB1011. DOI:10.1029/2008GB003435. .. _Pressetal1992: +|br| + Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P. 1992. Numerical Recipes in FORTRAN: The Art of Scientific Computing. Cambridge University Press, New York. .. _Prigentetal2007: +|br| + Prigent, C., Papa, F., Aires, F., Rossow, W.B. and Matthews, E. 2007. Global inundation dynamics inferred from multiple satellite observations, 1993-2000. J. Geophys. Res. 112(D12). .. _Pritchardetal2008: +|br| + Pritchard, M.S., Bush, A.B.G., and Marshall, S.J. 2008. Neglecting ice-atmosphere interactions underestimates ice sheet melt in millennial-scale deglaciation simulations. Geophys. Res. Lett. ** @@ -1553,18 +2060,24 @@ millennial-scale deglaciation simulations. Geophys. Res. Lett. ** .. _Qianetal2006: +|br| + Qian, T., Dai, A., Trenberth, K.E., and Oleson, K.W. 2006. Simulation of global land surface conditions from 1948 to 2004: Part I: Forcing data and evaluations. J. Hydrometeor. 7:953-975. .. _RamankuttyFoley1998: +|br| + Ramankutty, N., and Foley, J. A., 1998. Characterizing patterns of global land use: An analysis of global croplands data. Global Biogeochemical Cycles, 12, 667-685. .. _Ramankuttyetal2008: +|br| + Ramankutty, N., Evan, A., Monfreda, C., and Foley, J.A. 2008. Farming the Planet. Part 1: The Geographic Distribution of Global Agricultural Lands in the Year 2000. Global Biogeochem. Cycles. 22:GB1003. @@ -1572,6 +2085,8 @@ DOI:10.1029/2007GB002952. .. _Randlettetal1996: +|br| + Randlett, D.L., Zak, D.R., Pregitzer, K.S., and Curtis, P.S. 1996. Elevated atmospheric carbon dioxide and leaf litter chemistry: Influences on microbial respiration and net nitrogen mineralization. @@ -1579,6 +2094,8 @@ Soil Sci. Soc. Am. J. 60:1571-1577. .. _Rastetteretal1991: +|br| + Rastetter, E.B., Ryan, M.G., Shaver, G.R., Melillo, J.M., Nadelhoffer, K.J., Hobbie, J.E., and Aber, J.D. 1991. A general biogeochemical model describing the responses of the C and N cycles in terrestrial ecosystems @@ -1586,12 +2103,16 @@ to changes in CO2, climate and N deposition. Tree Phys. 9:101-126. .. _Rastneretal2012: +|br| + Rastner, P., Bolch, T., Mölg, N., Machguth, H., and Paul, F., 2012. The first complete glacier inventory for the whole of Greenland, The Cryosphere Discuss., 6, 2399-2436, 10.5194/tcd-6-2399-2012. .. _Rileyetal2011a: +|br| + Riley, W. J., Z. M. Subin, D. M. Lawrence, S. C. Swenson, M. S. Torn, L. Meng, N. Mahowald, and P. Hess, 2011a. Barriers to predicting global terrestrial methane fluxes: Analyses using a methane biogeochemistry @@ -1600,26 +2121,36 @@ DOI:10.5194/bg-8-1925-2011. .. _Rileyetal2011b: +|br| + Riley, W.J. et al. 2011b. CLM4Me, a Methane Biogeochemistry Model Integrated in CESM, Land and Biogeochemistry Model Working Group Meeting, Boulder, CO. .. _Roeschetal2001: +|br| + Roesch, A., M. Wild, H. Gilgen, and A. Ohmura. 2001. A new snow cover fraction parametrization for the ECHAM4 GCM, Clim. Dyn., 17:933–946. .. _Rogersetal2017: +|br| + Rogers, A., B. E. Medlyn, J. S. Dukes, G. Bonan, S. Caemmerer, M. C. Dietze, J. Kattge, A. D. Leakey, L. M. Mercado, and U. Niinemets, 2017: A roadmap for improving the representation of photosynthesis in Earth system models. New Phytologist, 213:22-42. .. _Ryan1991: +|br| + Ryan, M. G. 1991. A simple method for estimating gross carbon budgets for vegetation in forest ecosystems. Tree Phys. 9:255-266. .. _RunningCoughlan1988: +|br| + Running, S.W. and Coughlan, J.C., 1988. A general model of forest ecosystem processes for regional applications. I. Hydrological balance, canopy gas exchange and primary production processes. Ecological @@ -1627,18 +2158,24 @@ Modelling, 42: 125-154. .. _Runningetal1989: +|br| + Running, S.W. et al., 1989. Mapping regional forest evapotranspiration and photosynthesis by coupling satellite data with ecosystem simlation. Ecology, 70: 1090-1101. .. _RunningGower1991: +|br| + Running, S.W. and Gower, S.T., 1991. FOREST BGC, A general model of forest ecosystem processes for regional applications. II. Dynamic carbon allocation and nitrogen budgets. Tree Physiology, 9: 147-160. .. _RunningHunt1993: +|br| + Running, S.W. and Hunt, E.R., Jr., 1993. Generalization of a forest ecosystem process model for other biomes, BIOME-BGC, and an applicationfor global-scale models. In: J.R. Ehleringer and C. Field @@ -1647,12 +2184,16 @@ Press, San Diego, CA, pp. 141-158. .. _Sacksetal2009: -Sacks, W. J., Cook, B. I., Buenning, N., Levis, S., and Helkowski, J. H. +|br| + +Sacks, W. J., Cook, B. I., Buenning, N., Levis, S., and Helkowski, J. H. 2009. Effects of global irrigation on the near-surface climate. Climate Dyn., 33, 159–175. DOI:10.1007/s00382-008-0445-z. .. _Saggaretal1994: +|br| + Saggar, S., Tate, K.R., Feltham, C.W., Childs, C.W. and Parshotam, A., 1994. Carbon turnover in a range of allophanic soils amended with :math:`{}^{14}`\ C-labelled glucose. Soil Biology and Biochemistry, 26: @@ -1665,6 +2206,8 @@ DOI:10.1029/2008JD010834. .. _Schaafetal2002: +|br| + Schaaf, C.B., Gao, F., Strahler, A.H., Lucht, W., Li, X., Tsang, T., Strugnell, N.C., Zhang, X., Jin, Y., and Muller, J.-P. 2002. First operational BRDF, albedo nadir reflectance products from MODIS. Remote @@ -1672,40 +2215,54 @@ Sens. Environ. 83:135-148. .. _Schlesinger1997: +|br| + Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. Academic Press, London, 588 pp. .. _SchnellKing1996: +|br| + Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity in soils and cultures to water stress. Applied and Environmental Microbiology 62:3203-3209. .. _Segers1998: +|br| + Segers, R., 1998. Methane production and methane consumption: a review of processes underlying wetland methane fluxes. Biogeochemistry 41:23-51. .. _Sellers1985: +|br| + Sellers, P.J. 1985. Canopy reflectance, photosynthesis and transpiration. Int. J. Remote Sens. 6:1335-1372. .. _Sellersetal1986: +|br| + Sellers, P.J., Mintz, Y., Sud, Y.C., and Dalcher, A. 1986. A simple biosphere model (SiB) for use within general circulation models. J. Atmos. Sci. 43:505-531. .. _Sellersetal1988: +|br| + Sellers, P.J., Hall, F.G., Asrar, G., Strebel, D.E., and Murphy, R.E. 1988. The First ISLSCP Field Experiment (FIFE). Bull. Amer. Meteor. Soc. 69:22-27. .. _Sellersetal1992: +|br| + Sellers, P.J., Berry, J.A., Collatz, G.J., Field, C.B., and Hall, F.G. 1992. Canopy reflectance, photosynthesis, and transpiration. III. A reanalysis using improved leaf models and a new canopy integration @@ -1713,12 +2270,16 @@ scheme. Remote Sens. Environ. 42:187-216. .. _Sellersetal1995: +|br| + Sellers, P.J., et al. 1995. The Boreal Ecosystem-Atmosphere Study (BOREAS): An overview and early results from the 1994 field year. Bull. Amer. Meteor. Soc. 76:1549-1577. .. _Sellersetal1996: +|br| + Sellers, P.J., Randall, D.A., Collatz, G.J., Berry, J.A., Field, C.B., Dazlich, D.A., Zhang, C., Collelo, G.D., and Bounoua, L. 1996. A revised land surface parameterization (SiB2) for atmospheric GCMs. Part I: Model @@ -1726,6 +2287,8 @@ formulation. J. Climate 9:676-705. .. _Shietal2013: +|br| + Shi, X., Mao, J., Thornton, P.E., and Huang, M. 2013. Spatiotemporal patterns of evapotranspiration in response to multiple environmental factors simulated by the Community Land Model. Environ. Res. Lett. @@ -1733,39 +2296,53 @@ factors simulated by the Community Land Model. Environ. Res. Lett. .. _Shietal2016: +|br| + Shi, M., J. B. Fisher, E. R. Brzostek, and R. P. Phillips, 2016: Carbon cost of plant nitrogen acquisition: global carbon cycle impact from an improved plant nitrogen cycle in the Community Land Model. Glob. Change Biol., 22:1299-1314. .. _Shiklomanov2000: +|br| + Shiklomanov, I.A. 2000. Appraisal and assessment of world water resources. Water International 25:11-32. .. _Siebertetal2005: +|br| + Siebert, S., Döll, P., Hoogeveen, J., Faures, J.M., Frenken, K., Feick, S., 2005. Development and validation of the global map of irrigation areas. Hydrol Earth Syst Sc 9:535–547 .. _Simardetal2011: -Simard, M., Pinto, N., Fisher, J.B., and Baccini, A. (2011), Mapping +|br| + +Simard, M., Pinto, N., Fisher, J.B., and Baccini, A. (2011), Mapping forest canopy height globally with spaceborne lidar. J. Geophys. Res., 116, G04021, doi:10.1029/2011JG001708. .. _Simpsonetal1983: +|br| + Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen redistribution during grain growth in wheat (Triticum avestivum L.). Plant Physiol. 71:7-14. .. _Sivak2013: +|br| + Sivak, M. 2013. Air conditioning versus heating: climate control is more -energy demanding in Minneapolis than in Miami. Environ. Res. Lett., 8, +energy demanding in Minneapolis than in Miami. Environ. Res. Lett., 8, doi:10.1088/1748-9326/8/1/014050. .. _Smithetal2005: +|br| + Smith, A.M.S., Wooster, M.J., Drake, N.A., Dipotso, F.M. and Perry, G.L.W., 2005. Fire in African savanna: Testing the impact of incomplete combustion on pyrogenic emissions estimates. Ecological Applications, @@ -1773,37 +2350,49 @@ combustion on pyrogenic emissions estimates. Ecological Applications, .. _Sollins1982: +|br| + Sollins, P., 1982. Input and decay of coarse woody debris in coniferous stands in western Oregon and Washington. Canadian Journal of Forest Research, 12: 18-28. .. _SonGower1991: +|br| + Son, Y. and Gower, S.T., 1991. Aboveground nitrogen and phosphorus use by five plantation-grown trees with different leaf longevities. Biogeochemistry, 14: 167-191. .. _Sorensen1981: +|br| + Sørensen, L.H., 1981. Carbon-nitrogen relationships during the humification of cellulose in soils containing different amounts of clay. Soil Biology and Biochemistry, 13: 313-321. .. _Sperryetal1998: -Sperry, J.S., Adler, F.R., Campbell, G.S. and Comstock, J.P. 1998. -Limitation of plant water use by rhizosphere and xylem conductance: -results from a model. Plant, Cell & Environment, 21: 347–359. +|br| + +Sperry, J.S., Adler, F.R., Campbell, G.S. and Comstock, J.P. 1998. +Limitation of plant water use by rhizosphere and xylem conductance: +results from a model. Plant, Cell & Environment, 21: 347–359. doi:10.1046/j.1365-3040.1998.00287.x .. _SperryandLove2015: -Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us -about responses to climate-change droughts. New Phytol, 207: 14–27. +|br| + +Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us +about responses to climate-change droughts. New Phytol, 207: 14–27. doi:10.1111/nph.13354 .. _Sprugeletal1995: +|br| + Sprugel, D.G., Ryan, M.G., Brooks, J.R., Vogt, K.A., and Martin, T.A. 1995. Respiration from the organ level to stand level. pp. 255-299. In: W. K. Smith and T. M. Hinkley (editors) Resource Physiology of Conifers. @@ -1811,17 +2400,23 @@ Academic Press, San Diego,CA. .. _StaufferAharony1994: +|br| + Stauffer, D., and Aharony, A. 1994. Introduction to Percolation Theory. Taylor and Francis, London. .. _Stilletal2003: +|br| + Still, C.J., Berry, J.A., Collatz, G.J., and DeFries, R.S. 2003. Global distribution of C3 and C4 vegetation: carbon cycle implications. Global Biogeochem. Cycles 17:1006. DOI:10.1029/2001GB001807. .. _Stocklietal2008: +|br| + Stöckli, R., Lawrence, D.M., Niu, G.-Y., Oleson, K.W., Thornton, P.E., Yang, Z.-L., Bonan, G.B., Denning, A.S., and Running, S.W. 2008. Use of FLUXNET in the Community Land Model development. J. Geophys. Res. @@ -1829,29 +2424,39 @@ FLUXNET in the Community Land Model development. J. Geophys. Res. .. _Stracketal2006: +|br| + Strack, M., Kellner, E. and Waddington, J.M., 2006. Effect of entrapped gas on peatland surface level fluctuations. Hydrological Processes 20:3611-3622. .. _Strahleretal1999: +|br| + Strahler, A.H., Muchoney, D., Borak, J., Friedl, M., Gopal, S., Lambin, E., and Moody. A. 1999. MODIS Land Cover Product: Algorithm Theoretical Basis Document (Version 5.0). Boston University, Boston. .. _Stull1988: +|br| + Stull, R.B. 1988. An Introduction to Boundary Layer Meteorology. Kluwer Academic Publishers, Dordrecht. .. _Subinetal2012a: +|br| + Subin, Z.M., Riley, W.J. and Mironov, D. 2012a. Improved lake model for climate simulations, J. Adv. Model. Earth Syst., 4, M02001. DOI:10.1029/2011MS000072. .. _Subinetal2012b: +|br| + Subin, Z.M., Murphy, L.N., Li, F., Bonfils, C. and Riley, W.J., 2012b. Boreal lakes moderate seasonal and diurnal temperature variation and perturb atmospheric circulation: analyses in the Community Earth System @@ -1859,42 +2464,56 @@ Model 1 (CESM1). Tellus A, North America, 64. .. _Sunetal2012: +|br| + Sun, Y., Gu, L., and Dickinson, R. E. 2012. A numerical issue in calculating the coupled carbon and water fluxes in a climate model, J. Geophys. Res., 117, D22103. DOI:10.1029/2012JD018059. .. _Swensonetal2012: +|br| + Swenson, S.C., Lawrence, D.M., and Lee, H. 2012. Improved Simulation of the Terrestrial Hydrological Cycle in Permafrost Regions by the Community Land Model. JAMES, 4, M08002. DOI:10.1029/2012MS000165. .. _SwensonLawrence2012: +|br| + Swenson, S.C. and Lawrence, D.M. 2012. A New Fractional Snow Covered Area Parameterization for the Community Land Model and its Effect on the Surface Energy Balance. JGR, 117, D21107. DOI:10.1029/2012JD018178. .. _SwensonLawrence2014: -Swenson, S.C., and D. M. Lawrence. 2014. Assessing a dry surface -layer-based soil resistance parameterization for the Community Land Model -using GRACE and FLUXNET-MTE data. JGR, 119, 10, 299–10,312, +|br| + +Swenson, S.C., and D. M. Lawrence. 2014. Assessing a dry surface +layer-based soil resistance parameterization for the Community Land Model +using GRACE and FLUXNET-MTE data. JGR, 119, 10, 299–10,312, DOI:10.1002/2014JD022314. .. _SwensonLawrence2015: -Swenson, S.C., and D. M. Lawrence. 2015. A GRACE-based assessment of -interannual groundwater dynamics in the Community Land Model. WRR, 51, +|br| + +Swenson, S.C., and D. M. Lawrence. 2015. A GRACE-based assessment of +interannual groundwater dynamics in the Community Land Model. WRR, 51, doi:10.1002/2015WR017582. .. _TaWeiland1992: +|br| + Ta, C.T. and Weiland, R.T. 1992. Nitrogen partitioning in maize during ear development. Crop Sci. 32:443-451. .. _TangRiley2013: +|br| + Tang, J.Y. and Riley, W.J. 2013. A new top boundary condition for modeling surface diffusive exchange of a generic volatile tracer: Theoretical analysis and application to soil evaporation. Hydrol. Earth @@ -1902,22 +2521,30 @@ Syst. Sci. 17:873-893. .. _Tarnocaietal2011: +|br| + Tarnocai, C., Kettles, I. M., and Lacelle, B., 2011. Peatlands of Canada, Geological Survey of Canada, Open File 6561, CD-ROM. DOI:10.495/288786. .. _Tayloretal1989: +|br| + Taylor, B.R., Parkinson, D. and Parsons, W.F.J., 1989. Nitrogen and lignin content as predictors of litter decay rates: A microcosm test. Ecology, 70: 97-104. .. _Thomasetal2015: +|br| + Thomas R.Q., Brookshire E.N., Gerber S. 2015. Nitrogen limitation on land: how can it occur in Earth system models? Global Change Biology, 21, 1777-1793, doi:10.1111/gcb.12813. .. _Thonickeetal2001: +|br| + Thonicke, K., Venevsky, S., Sitch, S., and Cramer, W. 2001. The role of fire disturbance for global vegetation dynamics: coupling fire into a Dynamic Global Vegetation Model. Global Ecology and Biogeography @@ -1925,6 +2552,8 @@ Dynamic Global Vegetation Model. Global Ecology and Biogeography .. _Thornton1998: +|br| + Thornton, P.E., 1998. Regional ecosystem simulation: combining surface- and satellite-based observations to study linkages between terrestrial energy and mass budgets. Ph.D. Thesis, The University of Montana, @@ -1932,6 +2561,8 @@ Missoula, 280 pp. .. _Thorntonetal2002: +|br| + Thornton, P.E., Law, B.E., Gholz, H.L., Clark, K.L., Falge, E., Ellsworth, D.S., Goldstein, A.H., Monson, R.K., Hollinger, D., Falk, M., Chen, J., and Sparks, J.P. 2002. Modeling and measuring the effects of @@ -1940,18 +2571,24 @@ needleleaf forests. Agric. For. Meteor. 113:185-222. .. _ThorntonRosenbloom2005: +|br| + Thornton, P.E., and Rosenbloom, N.A. 2005. Ecosystem model spin-up: estimating steady state conditions in a coupled terrestrial carbon and nitrogen cycle model. Ecological Modelling 189:25-48. .. _ThorntonZimmermann2007: +|br| + Thornton, P.E., and Zimmermann, N.E. 2007. An improved canopy integration scheme for a land surface model with prognostic canopy structure. J. Climate 20:3902-3923. .. _Thorntonetal2007: +|br| + Thornton, P.E., Lamarque, J.-F., Rosenbloom, N.A., and Mahowald, N.M. 2007. Influence of carbon-nitrogen cycle coupling on land model response to CO\ :sub:`2` fertilization and climate variability. Global @@ -1959,6 +2596,8 @@ Biogeochem. Cycles 21:GB4018. .. _Thorntonetal2009: +|br| + Thornton, P.E., Doney, S.C., Lindsay, K., Moore, J.K., Mahowald, N., Randerson, J.T., Fung, I., Lamarque, J.F., Feddema, J.J., and Lee, Y.H. 2009. Carbon-nitrogen interactions regulate climate-carbon cycle @@ -1967,6 +2606,8 @@ Biogeosci. 6:2099-2120. .. _Tianetal2010: +|br| + Tian, H. et al. 2010. Spatial and temporal patterns of CH4 and N2O fluxes in terrestrial ecosystems of North America during 1979-2008: application of a global biogeochemistry model. Biogeosciences @@ -1974,6 +2615,8 @@ application of a global biogeochemistry model. Biogeosciences .. _Toonetal1989: +|br| + Toon, O.B., McKay, C.P., Ackerman, T.P., and Santhanam, K. 1989. Rapid calculation of radiative heating rates and photodissociation rates in inhomogeneous multiple scattering atmospheres. J. Geophys. Res. @@ -1981,12 +2624,16 @@ inhomogeneous multiple scattering atmospheres. J. Geophys. Res. .. _Turetskyetal2002: +|br| + Turetsky, M.R., Wieder, R.K., Halsey, L.A., and Vitt, D.H. 2002. Current disturbance and the diminishing peatland carbon sink. Geophys. Res. Lett. 29:1526. DOI:10.1029/2001GL014000. .. _Turetskyetal2004: +|br| + Turetsky, M.R., Amiro, B.D., Bosch, E., and Bhatti, J.S. 2004. Historical burn area in western Canadian peatlands and its relationship to fire weather indices. Global Biogeochem. Cycles 18:GB4014. @@ -1994,23 +2641,31 @@ DOI:10.1029/2004GB002222. .. _Tyeetal2005: +|br| + Tye, A.M., et al. 2005. The fate of N-15 added to high Arctic tundra to mimic increased inputs of atmospheric nitrogen released from a melting snowpack. Global Change Biology 11:1640-1654. .. _Unlandetal1996: +|br| + Unland, H.E., Houser, P.R., Shuttleworth, W.J., and Yang, Z.-L. 1996. Surface flux measurement and modeling at a semi-arid Sonoran Desert site. Agric. For. Meteor. 82:119-153. .. _UNSTAT2005: +|br| + UNSTAT, 2005. National Accounts Main Aggregates Database, United Nations Statistics Division. .. _VallanoSparks2007: +|br| + Vallano, D.M. and Sparks, J.P. 2007. Quantifying foliar uptake of gaseous itrogen dioxide using enriched foliar :math:`\delta^{15}`\ N values. New Phytologist @@ -2018,6 +2673,8 @@ gaseous itrogen dioxide using enriched foliar .. _vanderWerfetal2010: +|br| + van der Werf, G.R., Randerson, J.T., Giglio, L., Collatz, G.J., Mu, M., Kasibhatla, S.P., Morton, D.C., DeFries, R.S., Jin, Y., van Leeuwen, T.T. 2010. Global fire emissions and the contribution of deforestation, @@ -2026,19 +2683,25 @@ Phys. 10:11707-11735. .. _van Veenetal1984: +|br| + van Veen, J.A., Ladd, J.N. and Frissel, M.J., 1984. Modelling C and N turnover through the microbial biomass in soil. Plant and Soil, 76: 257-274. .. _vanKampenhoutetal2017: -van Kampenhout, L., J.T.M. Lenaerts, W.H. Lipscomb, W.J. Sacks, D.M. -Lawrence, A.G. Slater, and M.R. van den Broeke, 2017. -Improving the representation of polar snow and firn in the +|br| + +van Kampenhout, L., J.T.M. Lenaerts, W.H. Lipscomb, W.J. Sacks, D.M. +Lawrence, A.G. Slater, and M.R. van den Broeke, 2017. +Improving the representation of polar snow and firn in the Community Earth System Model, submitted. .. _VanVuurenetal2006: +|br| + Van Vuuren, D.P., Lucas, P.S., and Hilderink, H.B.M., 2006. Downscaling drivers of global environmental change: enabling use of global SRES scenarios at the national and grid levels, Report 550025001, Netherlands @@ -2046,12 +2709,16 @@ Environmental Assessment Agency, 45 pp. .. _VanninenMakela2005: +|br| + Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: effects of size, competition and site fertility on growth allocation and production. Tree Phys. 25:17-30. .. _VerdinGreenlee1996: +|br| + Verdin, K. L., and S. K. Greenlee, 1996. Development of continental scale digital elevation models and extraction of hydrographic features, paper presented at the Third International Conference/Workshop on @@ -2060,6 +2727,8 @@ January, Natl. Cent. for Geogr. Inf. and Anal., Santa Barbara, Calif. .. _Viovy2011: +|br| + Viovy, N. 2011. CRUNCEP dataset. [Description available at http://dods.extra.cea.fr/data/p529viov/cruncep/readme.htm. Data available at @@ -2067,17 +2736,23 @@ http://dods.extra.cea.fr/store/p529viov/cruncep/V4\_1901\_2011/]. .. _VitousekHowarth1991: +|br| + Vitousek, P.M., and Howarth, R.W. 1991. Nitrogen limitation on land and in the sea: How can it occur? Biogeochem. 13:87-115. .. _Walteretal2001: +|br| + Walter, B.P., Heimann, M. and Matthews, E., 2001. Modeling modern methane emissions from natural wetlands 1. Model description and results. J. Geophys. Res. 106(D24):34189-34206. .. _Waniaetal2009: +|br| + Wania, R., Ross, I. and Prentice, I.C. 2009. Integrating peatlands and permafrost into a dynamic global vegetation model: 2. Evaluation and sensitivity of vegetation and carbon cycle processes. Global Biogeochem. @@ -2085,6 +2760,8 @@ Cycles 23. .. _Waniaetal2010: +|br| + Wania, R., Ross, I. and Prentice, I.C. 2010. Implementation and evaluation of a new methane model within a dynamic global vegetation model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions @@ -2092,18 +2769,24 @@ model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions .. _WangZeng2009: +|br| + Wang, A., and Zeng, X. 2009. Improving the treatment of vertical snow burial fraction over short vegetation in the NCAR CLM3. Adv. Atmos. Sci. 26:877-886. DOI:10.1007/s00376-009-8098-3. .. _Whiteetal1997: +|br| + White, M.A., Thornton, P.E., and Running, S.W. 1997. A continental phenology model for monitoring vegetation responses to interannual climatic variability. Global Biogeochem. Cycles 11:217-234. .. _Whiteetal2000: +|br| + White, M.A., Thornton, P.E., Running, S.W., and Nemani, R.R. 2000. Parameterization and sensitivity analysis of the Biome-BGC terrestrial ecosystem model: net primary production controls. Earth Interactions @@ -2111,28 +2794,36 @@ ecosystem model: net primary production controls. Earth Interactions .. _Wiederetal2015: -Wieder, W. R., Cleveland, C. C., Lawrence, D. M., and Bonan, G. B. 2015. -Effects of model structural uncertainty on carbon cycle projections: -biological nitrogen fixation as a case study. Environmental Research +|br| + +Wieder, W. R., Cleveland, C. C., Lawrence, D. M., and Bonan, G. B. 2015. +Effects of model structural uncertainty on carbon cycle projections: +biological nitrogen fixation as a case study. Environmental Research Letters, 10(4), 044016. .. _Williamsetal1996: -Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., -Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. -and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere -continuum in a Quercus–Acer stand at Harvard Forest: the regulation -of stomatal conductance by light, nitrogen and soil/plant hydraulic -properties. Plant, Cell & Environment, 19: 911–927. +|br| + +Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., +Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. +and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere +continuum in a Quercus–Acer stand at Harvard Forest: the regulation +of stomatal conductance by light, nitrogen and soil/plant hydraulic +properties. Plant, Cell & Environment, 19: 911–927. doi:10.1111/j.1365-3040.1996.tb00456.x .. _WiscombeWarren1980: +|br| + Wiscombe, W.J., and Warren, S.G. 1980. A model for the spectral albedo of snow. I. Pure snow. J. Atmos. Sci. 37:2712-2733. .. _Woodetal1992: +|br| + Wood, E.F., Lettenmaier, D.P., and Zartarian, V.G. 1992. A land-surface hydrology parameterization with subgrid variability for general circulation models. J. Geophys. Res. 97(D3):2717–2728. @@ -2140,66 +2831,90 @@ DOI:10.1029/91JD01786. .. _WorldBank2004: +|br| + World Bank, 2004. World development indicators 2004, Oxford University Press, New York, 416 pp. .. _Wuetal2011: +|br| + Wu, H., J. S. Kimball, N. Mantua, and J. Stanford, 2011: Automated upscaling of river networks for macroscale hydrological modeling. Water Resour. Res., 47, W03517, doi:10.1029/2009WR008871. .. _Wuetal2012: +|br| + Wu, H., J. S. Kimball, H. Li, M. Huang, L. R. Leung, and R. F. Adler (2012), A New Global River Network Database for Macroscale Hydrologic modeling, Water Resour. Res., 48, W09701, doi:10.1029/2012WR012313. .. _Xuetal2012: +|br| + Xu, C., R. Fisher, S. D. Wullschleger, C. J. Wilson, M. Cai, and N. G. McDowell, 2012: Toward a mechanistic modeling of nitrogen limitation on vegetation dynamics. PloS one, 7:e37914. .. _Yang1998: +|br| + Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and temperature model. Unpublished manuscript. .. _Zenderetal2003: +|br| + Zender, C.S., Bian, H., and Newman, D. 2003. Mineral dust entrainment and deposition (DEAD) model: Description and 1990s dust climatology. ** J. Geophys. Res\ *.* 108(D14):4416. DOI:10.1029/2002JD002775. .. _ZengDickinson1998: +|br| + Zeng, X., and Dickinson, R.E. 1998. Effect of surface sublayer on surface skin temperature and fluxes. J.Climate 11:537-550. .. _Zengetal1998: +|br| + Zeng, X., Zhao, M., and Dickinson, R.E. 1998. Intercomparison of bulk aerodynamic algorithms for the computation of sea surface fluxes using the TOGA COARE and TAO data. J. Climate 11:2628-2644. .. _Zeng2001: +|br| + Zeng, X. 2001. Global vegetation root distribution for land modeling. J. Hydrometeor. 2:525-530. .. _Zengetal2002: +|br| + Zeng, X., Shaikh, M., Dai, Y., Dickinson, R.E., and Myneni, R. 2002. Coupling of the Common Land Model to the NCAR Community Climate Model. J. Climate 15:1832-1854. .. _Zengetal2005: +|br| + Zeng, X., Dickinson, R.E., Barlage, M., Dai, Y., Wang, G., and Oleson, K. 2005. Treatment of under-canopy turbulence in land models. J. Climate 18:5086-5094. .. _ZengWang2007: +|br| + Zeng, X., and Wang, A. 2007. Consistent parameterization of roughness length and displacement height for sparse and dense canopies in land models. J. Hydrometeor. 8:730-737. @@ -2210,6 +2925,8 @@ water table. J. Hydrometeor. 10:308-319. .. _Zengetal2008: +|br| + Zeng, X., Zeng, X., and Barlage, M. 2008. Growing temperate shrubs over arid and semiarid regions in the Community Land Model - Dynamic Global Vegetation Model. Global Biogeochem. Cycles 22:GB3003. @@ -2217,6 +2934,8 @@ DOI:10.1029/2007GB003014. .. _Zhangetal2002: +|br| + Zhang, Y., Li, C.S., Trettin, C.C., Li, H. and Sun, G., 2002. An integrated model of soil, hydrology, and vegetation for carbon dynamics in wetland ecosystems. Global Biogeochemical Cycles 16. @@ -2224,6 +2943,8 @@ DOI:10.1029/2001GB001838. .. _Zhuangetal2004: +|br| + Zhuang, Q., et al. 2004. Methane fluxes between terrestrial ecosystems and the atmosphere at northern high latitudes during the past century: A retrospective analysis with a process-based biogeochemistry model. @@ -2231,136 +2952,200 @@ Global Biogeochemical Cycles 18. DOI:10.1029/2004GB002239. .. _Zilitinkevich1970: +|br| + Zilitinkevich, S.S. 1970. Dynamics of the Atmospheric Boundary Layer. Leningrad Gidrometeor. .. _bonan2012: -Bonan, Gordon B et al. (2012). `Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4`. Journal of Geophysical Research: Biogeosciences (2005-2012) 117.G2. +|br| + +Bonan, Gordon B et al. (2012). `Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4`. Journal of Geophysical Research: Biogeosciences (2005-2012) 117.G2. .. _botta2000: -Botta, A et al. (2000). `A global prognostic scheme of leaf onset using satellite data`. Global Change Biology 6.7, pp. 709-725. +|br| + +Botta, A et al. (2000). `A global prognostic scheme of leaf onset using satellite data`. Global Change Biology 6.7, pp. 709-725. .. _byram1959: -Byram, GM (1959). Combustion of forest fuels. In Forest fire: control and use.(Ed. KP Davis) pp. 61-89. +|br| + +Byram, GM (1959). Combustion of forest fuels. In Forest fire: control and use.(Ed. KP Davis) pp. 61-89. .. _collatz1991: +|br| + Collatz, G James 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 54.2, pp. 107-136. .. _collatz1992: +|br| + Collatz, Go J, M Ribas-Carbo, and JA Berry (1992). `Coupled photosynthesis-stomatal conductance model for leaves of C4 plants`. Functional Plant Biology 19.5, pp. 519-538.
 .. _farquhar1980: +|br| + Farquhar, GD, S von von Caemmerer, and JA Berry (1980). `A biochemical model of photosynthetic CO2 assimilation in leaves of C3 species`. Planta 149.1, pp. 780-90. .. _fisher2010: -Fisher, JB et al. (2010). `Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation`. Global Biogeochemical Cycles 24.1. +|br| + +Fisher, JB et al. (2010). `Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation`. Global Biogeochemical Cycles 24.1. .. _foley1996: -Foley, Jonathan A et al. (1996). `An integrated biosphere model of land surface processes, terrestrial carbon balance, and vegetation dynamics`. Global Biogeochemical Cycles 10.4, pp. 603-628. +|br| + +Foley, Jonathan A et al. (1996). `An integrated biosphere model of land surface processes, terrestrial carbon balance, and vegetation dynamics`. Global Biogeochemical Cycles 10.4, pp. 603-628. .. _fyllas2014: +|br| + Fyllas, NM et al. (2014). `Analysing Amazonian forest productivity using a new individual and trait- based model (TFS v. 1)`. Geoscientific Model Development 7.4, pp. 1251-1269. .. _kucharik1998: +|br| + Kucharik, Christopher J, John M Norman, and Stith T Gower (1998). `Measurements of branch area and adjusting leaf area index indirect measurements`. Agricultural and Forest Meteorology 91.1, pp. 69-88. .. _li2012: +|br| + Li, F, XD Zeng, and S Levis (2012). `A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model`. Biogeosciences 9.7, pp. 2761-2780. .. _lichstein2011: +|br| + Lichstein, Jeremy W and Stephen W Pacala (2011). `Local diversity in heterogeneous landscapes: quantitative assessment with a height-structured forest metacommunity model`. Theoretical Ecology 4.2, pp. 269-281. .. _lischke2006: +|br| + Lischke, Heike et al. (2006). `TreeMig: a forest-landscape model for simulating spatio-temporal patterns from stand to landscape scale`. Ecological Modelling 199.4, pp. 409-420. 41 .. _lloyd2010: - -Lloyd, J et al. (2010). `Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees`. Biogeosciences 7.6, pp. 1833-1859. + +|br| + +Lloyd, J et al. (2010). `Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees`. Biogeosciences 7.6, pp. 1833-1859. .. _mcdowell2013: -McDowell, Nate G et al. (2013). `Evaluating theories of drought-induced vegetation mortality using a multimodel experiment framework`. New Phytologist 200.2, pp. 304-321. +|br| + +McDowell, Nate G et al. (2013). `Evaluating theories of drought-induced vegetation mortality using a multimodel experiment framework`. New Phytologist 200.2, pp. 304-321. .. _medlyn2011: -Medlyn, Belinda E et al. (2011). `Reconciling the optimal and empirical approaches to modelling stom- atal conductance`. Global Change Biology 17.6, pp. 2134-2144. +|br| + +Medlyn, Belinda E et al. (2011). `Reconciling the optimal and empirical approaches to modelling stom- atal conductance`. Global Change Biology 17.6, pp. 2134-2144. .. _mc_2001: +|br| + Moorcroft, PR, GC Hurtt, and Stephen W Pacala (2001). `A method for scaling vegetation dynamics: the ecosystem demography model ED`. Ecological monographs 71.4, pp. 557-586. .. _norman1979: - -Norman, JM (1979). `Modeling the complete crop canopy`. Modification of the Aerial Environment of Crops, pp. 249-280. + +|br| + +Norman, JM (1979). `Modeling the complete crop canopy`. Modification of the Aerial Environment of Crops, pp. 249-280. .. _oleson2013: -Oleson, KW et al. (2013). `Technical description of version 4.5 of the Community Land Model (CLM)`. +|br| + +Oleson, KW et al. (2013). `Technical description of version 4.5 of the Community Land Model (CLM)`. .. _peterson1986: -Peterson, David L and Kevin C Ryan (1986). `Modeling postfire conifer mortality for long-range planning`. Environmental Management 10.6, pp. 797-808. +|br| + +Peterson, David L and Kevin C Ryan (1986). `Modeling postfire conifer mortality for long-range planning`. Environmental Management 10.6, pp. 797-808. .. _pfeiffer2013: -Pfeiffer, M, A Spessa, and JO Kaplan (2013). `A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0)`. Geoscientific Model Development 6.3, pp. 643-685. +|br| + +Pfeiffer, M, A Spessa, and JO Kaplan (2013). `A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0)`. Geoscientific Model Development 6.3, pp. 643-685. .. _purves2008: -Purves, Drew W et al. (2008). `Predicting and understanding forest dynamics using a simple tractable model`. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. +|br| + +Purves, Drew W et al. (2008). `Predicting and understanding forest dynamics using a simple tractable model`. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. .. _sato2007: -Sato, Hisashi, Akihiko Itoh, and Takashi Kohyama (2007). `SEIB–DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach`. Ecological Modelling 200.3, pp. 2793307. +|br| + +Sato, Hisashi, Akihiko Itoh, and Takashi Kohyama (2007). `SEIB–DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach`. Ecological Modelling 200.3, pp. 2793307. .. _sellers1996: -Sellers, Piers J et al. (1996). `A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data`. Journal of climate 9.4, pp. 706-737. +|br| + +Sellers, Piers J et al. (1996). `A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data`. Journal of climate 9.4, pp. 706-737. .. _sitch2003: -Sitch, S et al. (2003). `Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model`. Global Change Biology 9.2, pp. 161-185. +|br| + +Sitch, S et al. (2003). `Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model`. Global Change Biology 9.2, pp. 161-185. .. _smith2007: -Smith, Alison M and Mark Stitt (2007). `Coordination of carbon supply and plant growth`. Plant, cell & environment 30.9, pp. 1126-1149. +|br| + +Smith, Alison M and Mark Stitt (2007). `Coordination of carbon supply and plant growth`. Plant, cell & environment 30.9, pp. 1126-1149. .. _smith2001: -Smith, Benjamin, I Colin Prentice, and Martin T Sykes (2001). `Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space`. Global Ecology and Biogeography 10.6, pp. 621-637. +|br| + +Smith, Benjamin, I Colin Prentice, and Martin T Sykes (2001). `Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space`. Global Ecology and Biogeography 10.6, pp. 621-637. .. _thonicke2010: -Thonicke, K et al. (2010). `The influence of vegetation, fire spread and fire behaviour on biomass burning and trace gas emissions: results from a process-based model`. Biogeosciences 7.6, pp. 1991-2011. +|br| + +Thonicke, K et al. (2010). `The influence of vegetation, fire spread and fire behaviour on biomass burning and trace gas emissions: results from a process-based model`. Biogeosciences 7.6, pp. 1991-2011. .. _uriarte2009: +|br| + Uriarte, Maria et al. (2009). `Natural disturbance and human land use as determinants of tropical forest dynamics: results from a forest simulator`. Ecological Monographs 79.3, pp. 423-443. .. _venevsky2002: +|br| + Venevsky, Sergey et al. (2002). `Simulating fire regimes in human-dominated ecosystems: Iberian Peninsula case study`. Global Change Biology 8.10, pp. 984-998. .. _weng2014: +|br| + Weng, ES et al. (2014). `Scaling from individuals to ecosystems in an Earth System Model using a mathematically tractable model of height-structured competition for light`. Biogeosciences Discussions 11.12, pp. 17757-17860. .. _xiaodong2005: -Xiaodong, Yan and HH Shugart (2005). `FAREAST: a forest gap model to simulate dynamics and patterns of eastern Eurasian forests`. Journal of Biogeography 32.9, pp. 1641-1658. -42 +|br| +Xiaodong, Yan and HH Shugart (2005). `FAREAST: a forest gap model to simulate dynamics and patterns of eastern Eurasian forests`. Journal of Biogeography 32.9, pp. 1641-1658. diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index 3f60029854..d54e70f1e9 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -11,7 +11,6 @@ CLM Technical Note .. toctree:: :maxdepth: 2 - :numbered: Introduction/CLM50_Tech_Note_Introduction.rst Ecosystem/CLM50_Tech_Note_Ecosystem.rst diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index 510d4b22a2..bdb52253a1 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -11,7 +11,6 @@ CLM User's Guide .. toctree:: :maxdepth: 2 - :numbered: overview/index.rst setting-up-and-running-a-case/index.rst diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index de8dcc25fa..d6c5781a17 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -1,5 +1,21 @@ .. _introduction: +**User's Guide to version 5.0 of the Community Land Model (CLM)** + +**Authors: Benjamin Andre, Erik Kluzek, William Sacks** + +The National Center for Atmospheric Research (NCAR) is operated by the +nonprofit University Corporation for Atmospheric Research (UCAR) under +the sponsorship of the National Science Foundation. Any opinions, +findings, conclusions, or recommendations expressed in this publication +are those of the author(s) and do not necessarily reflect the views of +the National Science Foundation. + +National Center for Atmospheric Research +P. O. Box 3000, Boulder, Colorado 80307-300 + +.. _rst_Users_Guide_Introduction: + ============== Introduction ============== @@ -69,10 +85,10 @@ machine is working correctly. What is New with CLM4.5 ========================= -The CESM1.2.0 `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. +The CESM1.2.0 `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. More details are given in the `CLM ChangeLog file `_. -Previous release pages give similar list of changes for previous versions of the model. +Previous release pages give similar list of changes for previous versions of the model. The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates for versions up to CLM4 in CESM1.0.5. .. _users-guide-overview: @@ -81,51 +97,51 @@ The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates Overview of User's Guide ========================== -In this introduction we first give a simple guide to understand the document conventions in `How to Use This Document `_. -The next section `What is new with CLM4.5 in CESM1.2.0 since previous public releases? `_ gives references to describe the differences between CLM4.5 in CESM1.2.0 and previous CESM releases both from a scientific as well as a software engineering point of view. -For information on previous releases of CLM4.5 before CLM4.5 in CESM1.2.0 see the CESM1.1.1 documentation. -The next section `Quickstart to using CLM4.5 `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use CLM4.5. -The next `What is scientifically validated and functional in CLM4.5 in CESM1.2.0? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. -`What are the UNIX utilities required to use CLM4.5? `_ lists the UNIX utilities required to use CLM4.5 and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. -Next we have `Important Notes and Best Practices for Usage of CLM4.5 `_ to detail some of the best practices for using CLM4.5 for science. +In this introduction we first give a simple guide to understand the document conventions in `How to Use This Document `_. +The next section `What is new with CLM4.5 in CESM1.2.0 since previous public releases? `_ gives references to describe the differences between CLM4.5 in CESM1.2.0 and previous CESM releases both from a scientific as well as a software engineering point of view. +For information on previous releases of CLM4.5 before CLM4.5 in CESM1.2.0 see the CESM1.1.1 documentation. +The next section `Quickstart to using CLM4.5 `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use CLM4.5. +The next `What is scientifically validated and functional in CLM4.5 in CESM1.2.0? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. +`What are the UNIX utilities required to use CLM4.5? `_ lists the UNIX utilities required to use CLM4.5 and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. +Next we have `Important Notes and Best Practices for Usage of CLM4.5 `_ to detail some of the best practices for using CLM4.5 for science. The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and CLM4.5. -`Chapter 1 `_ goes into detail on how to setup and run simulations with CLM4.5 and especially how to customize cases. +`Chapter 1 `_ goes into detail on how to setup and run simulations with CLM4.5 and especially how to customize cases. Details of cesm_setup modes and build-namelist options as well as namelist options are given in this chapter. -`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or CLM4.5 physics for creating input datasets for use by CLM, for the expert user. -There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. -Then each tool is described in detail along with different ways in which the tool might be used. +`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or CLM4.5 physics for creating input datasets for use by CLM, for the expert user. +There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. +Then each tool is described in detail along with different ways in which the tool might be used. A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. -As a followup to the tools chapter, `Chapter 3 `_ tells how to add files to the XML database for build-namelist to use. +As a followup to the tools chapter, `Chapter 3 `_ tells how to add files to the XML database for build-namelist to use. This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and CLM4.5 physics). -In `Chapter 4 `_, again for the expert user, we give details on how to do some particularly difficult special cases. -For example, we give the protocol for spinning up the CLM4.5-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). -We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. -We also give instructions on running both the prognostic crop and irrigation models. +In `Chapter 4 `_, again for the expert user, we give details on how to do some particularly difficult special cases. +For example, we give the protocol for spinning up the CLM4.5-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). +We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. +We also give instructions on running both the prognostic crop and irrigation models. Lastly we tell the user how to use the DATM model to send historical CO2 data to CLM. -`Chapter 5 `_ outlines how to do single-point or regional simulations using CLM4.5. -This is useful to either compare CLM4.5 simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. -There are several different ways given on how to perform single-point simulations which range from simple PTS_MODE to more complex where you create all your own datasets, tying into `Chapter 2 `_ and also `Chapter 3 `_ to add the files into the build-namelist XML database. -The PTCLM python script to run single-point simulations was added back in for this release (but it has bugs that don't allow it to work out of the box). +`Chapter 5 `_ outlines how to do single-point or regional simulations using CLM4.5. +This is useful to either compare CLM4.5 simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. +There are several different ways given on how to perform single-point simulations which range from simple PTS_MODE to more complex where you create all your own datasets, tying into `Chapter 2 `_ and also `Chapter 3 `_ to add the files into the build-namelist XML database. +The PTCLM python script to run single-point simulations was added back in for this release (but it has bugs that don't allow it to work out of the box). CLM4 in CESM1.0.5 has a fully working versions of PTCLM. Need `Chapter 6 `_ blurb... -`Chapter 7 `_ gives some guidance on trouble-shooting problems when using CLM4.5. +`Chapter 7 `_ gives some guidance on trouble-shooting problems when using CLM4.5. It doesn't cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems. -`Chapter 8 `_ goes over the automated testing scripts for validating that the CLM is working correctly. -The test scripts run many different configurations and options with CLM4.0 physics as well and CLM4.5 physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. +`Chapter 8 `_ goes over the automated testing scripts for validating that the CLM is working correctly. +The test scripts run many different configurations and options with CLM4.0 physics as well and CLM4.5 physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. In general this is an activity important only for a developer of CLM4.5, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. In the appendices we talk about some issues that are useful for advanced users and developers of CLM4.5. -Finally in `Appendix A `_ we give instructions on how to build the documentation associated with CLM4.5 (i.e. how to build this document). -This document is included in every CLM distribution and can be built so that you can view a local copy rather than having to go to the CESM website. +Finally in `Appendix A `_ we give instructions on how to build the documentation associated with CLM4.5 (i.e. how to build this document). +This document is included in every CLM distribution and can be built so that you can view a local copy rather than having to go to the CESM website. This also could be useful for developers who need to update the documentation due to changes they have made. .. _best-practices-for-usage: @@ -134,40 +150,40 @@ This also could be useful for developers who need to update the documentation du Best Practices ================ -- CLM4.5 includes BOTH the old CLM4.0 physics AND the new CLM4.5 physics and you can toggle between two. - The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. - While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. +- CLM4.5 includes BOTH the old CLM4.0 physics AND the new CLM4.5 physics and you can toggle between two. + The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. + While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. "BGC" is the new CLM4.5 biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). -- When running with CLMCN (either CLM4.0 or CLM4.5 physics) or CLM4.5-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the CLM4.5 biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for CLM4.5 or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). - Simulations without a proper spinup will effectively be starting from an unvegetated world. +- When running with CLMCN (either CLM4.0 or CLM4.5 physics) or CLM4.5-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the CLM4.5 biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for CLM4.5 or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). + Simulations without a proper spinup will effectively be starting from an unvegetated world. See `the Section called Setting Your Initial Conditions File in Chapter 1 `_ for information on how to provide initial conditions for your simulation. -- Initial condition files are provided for CLM4.0-CN as before, for fully coupled BCN and offline ICN cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. - We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). - There's also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with CLMSP for 2000 at 2deg resolution. - We also have initial conditions for offline CNDV for 1850. - The 1850 initial condition files are in 'reasonable' equilibrium. - The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. - Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. +- Initial condition files are provided for CLM4.0-CN as before, for fully coupled BCN and offline ICN cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. + We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). + There's also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with CLMSP for 2000 at 2deg resolution. + We also have initial conditions for offline CNDV for 1850. + The 1850 initial condition files are in 'reasonable' equilibrium. + The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. + Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. - -- Initial condition files are also provided for CLM4.5 for several configurations and resolutions. - For CLM4.5-SP and CLM4.5-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. - The CLM4.5-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. + +- Initial condition files are also provided for CLM4.5 for several configurations and resolutions. + For CLM4.5-SP and CLM4.5-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. + The CLM4.5-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. Also the CLM4.5-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg CLM4.5-BGC-DV and 2deg CLM4.5-BGC-Crop. - -- Users can generate initial condition files at different resolutions by using the CLM tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. + +- Users can generate initial condition files at different resolutions by using the CLM tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. -- In CLM4.5 for both CLM4.5-CN and CLM4.5-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). - By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2010 for population density. - Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. +- In CLM4.5 for both CLM4.5-CN and CLM4.5-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). + By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2010 for population density. + Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. - -- Aerosol deposition is a required field to both CLM4.0 and CLM4.5 physics, sent from the atmosphere model. - Simulations without aerosol deposition will exhibit unreasonably high snow albedos. - The model sends aerosol deposition from the atmospheric model (either CAM or DATM). + +- Aerosol deposition is a required field to both CLM4.0 and CLM4.5 physics, sent from the atmosphere model. + Simulations without aerosol deposition will exhibit unreasonably high snow albedos. + The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. .. _how-to-use-this-document: @@ -185,15 +201,14 @@ Links to descriptions and definitions have been provided in the code below. We u Where examples from an interactive shell session are presented, lines starting with > indicate the shell prompt. A backslash "\" at the end of a line means the line continues onto the next one (as it does in - standard UNIX shell). Note that $EDITOR" is used to refer to the - text editor of your choice. $EDITOR is a standard UNIX environment - variable and should be set on most UNIX systems. Comment lines are + standard UNIX shell). Note that $EDITOR" is used to refer to the + text editor of your choice. $EDITOR is a standard UNIX environment + variable and should be set on most UNIX systems. Comment lines are signaled with a "#" sign, which is the standard UNIX comment sign as well. $CSMDATA is used to denote the path to the inputdata directory for - your CESM data. + your CESM data. > This is a shell prompt with commands \ that continues to the following line. > $EDITOR filename # means you are using a text editor to edit "filename" # This is a comment line - From 4a4604b93962339cc7c9ed06aa8bf76f2925b299 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Mon, 29 Jan 2018 14:50:22 -0700 Subject: [PATCH 126/255] Updated Stomatal Resistance chapter based on comments from Gordon --- .../CLM50_Tech_Note_Photosynthesis.rst | 69 ++++++++----------- 1 file changed, 28 insertions(+), 41 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index b8e443f10a..8dad4faf3e 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -40,9 +40,6 @@ area indices (section :numref:`Solar Fluxes`). Canopy conductance is :math:`\frac{1}{r_{b} +r_{s}^{sun} } L^{sun} +\frac{1}{r_{b} +r_{s}^{sha} } L^{sha}` , where :math:`r_{b}` is the leaf boundary layer resistance (section :numref:`Sensible and Latent Heat Fluxes and Temperature for Vegetated Surfaces`). -The implementation is described by Bonan et al. (:ref:`2011 `), though different -methods of calculating stomatal conductance, :math:`J_{max}`, and the nitrogen variables -used to calculate :math:`V_{cmax25}` are used in CLM5. .. _Stomatal resistance: @@ -60,7 +57,7 @@ Leaf stomatal resistance is: .. math:: :label: 9.1 - \frac{1}{r_{s} } =g_{s} = g_{o} + (1 + \frac{g_{1} }{\sqrt{D}}) \frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } } + \frac{1}{r_{s} } =g_{s} = g_{o} + 1.6(1 + \frac{g_{1} }{\sqrt{D}}) \frac{A_{n} }{{c_{s} \mathord{\left/ {\vphantom {c_{s} P_{atm} }} \right. \kern-\nulldelimiterspace} P_{atm} } } where :math:`r_{s}` is leaf stomatal resistance (s m\ :sup:`2` :math:`\mu`\ mol\ :sup:`-1`), :math:`g_{o}` is the minimum stomatal conductance @@ -68,20 +65,9 @@ where :math:`r_{s}` is leaf stomatal resistance (s m\ :sup:`2` photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric -pressure (Pa), and :math:`D` is the vapor pressure deficit at the leaf surface (Pa). -:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`) -and can be calculated as +pressure (Pa), and :math:`D` is the vapor pressure deficit at the leaf surface (kPa). +:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`). -.. math:: - :label: 9.2 - - g_{1} = {\sqrt{\frac{3\Gamma\lambda}{1.6}}} - -where :math:`\Gamma` (mol mol\ :sup:`-1`) is the CO\ :sub:`2` compensation point -for photosynthesis without dark respiration, -1.6 is the ratio of diffusivity of CO\ :sub:`2` to H\ :sub:`2` O and :math:`\lambda` -(mol H\ :sub:`2` O mol\ :sup:`-1`) is a parameter -describing the marginal water cost of carbon gain. The value for :math:`g_{o}=100` :math:`\mu` mol m :sup:`-2` s\ :sup:`-1` for C\ :sub:`3` and C\ :sub:`4` plants. Photosynthesis is calculated for sunlit (:math:`A^{sun}`) and shaded @@ -93,7 +79,7 @@ the :ref:`rst_Plant Hydraulics` chapter. Resistance is converted from units of s m\ :sup:`2` :math:`\mu` mol\ :sup:`-1` to s m\ :sup:`-1` as: 1 s m\ :sup:`-1` = :math:`1\times 10^{-9} R_{gas} \frac{\theta _{atm} }{P_{atm} }` -:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, [same as 4.5, but units seem off. check that units are correct] +:math:`\mu` mol\ :sup:`-1` m\ :sup:`2` s, where :math:`R_{gas}` is the universal gas constant (J K\ :sup:`-1` kmol\ :sup:`-1`) (:numref:`Table Physical constants`) and :math:`\theta _{atm}` is the atmospheric potential temperature (K). @@ -270,6 +256,7 @@ depend on temperature. Values at 25 :sup:`o` \ C are :math:`\Gamma _{25} {\rm =42}.75\times 10^{-6} P_{atm}`. :math:`V_{c\max }`, :math:`J_{\max }`, :math:`T_{p}`, :math:`k_{p}`, and :math:`R_{d}` also vary with temperature. Parameter values at 25 +[verify with Rosie that LUNA doesn't do this otherwise] :sup:`o`\ C are calculated from :math:`V_{c\max }` \ at 25 :sup:`\o`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}`, :math:`T_{p25} =0.167V_{c\max 25}`, and @@ -293,7 +280,7 @@ The parameters :math:`V_{c\max 25}`, \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma } & {=} & {\Gamma _{25} \; f\left(T_{v} \right)} \end{array} -with +[check with Rosie about Rd equation above and below (eq. 14)] with .. math:: :label: 9.11 @@ -522,14 +509,33 @@ resistance (:math:`r_{s}` ) as a function of photosynthesis .. math:: :label: 9.36 - c_{s} g_{s}^{2} +\left[c_{s} \left(g_{b} -b\right)-m{\it A}_{n} P_{atm} \right]g_{s} -g_{b} \left[c_{s} b+mA_{n} P_{atm} {e_{a} \mathord{\left/ {\vphantom {e_{a} e_{\*} \left(T_{v} \right)}} \right. \kern-\nulldelimiterspace} e_{\*} \left(T_{v} \right)} \right]=0. + g_{s}^{2} + bg_{s} + c = 0 -Stomatal conductance is the larger of the two roots that satisfy the -quadratic equation. Values for :math:`c_{i}` are given by +where .. math:: :label: 9.37 + b = 2(g_{o} * 10^{-6} + d) + \frac{(g_{1}d)^{2}}{g_{b}*10^{-6}D} + + c = (g_{o}*10^{-6})^{2} + [2g_{o}*10^{-6} + d \frac{1-g_{1}^{2}} {D}]d + +and + +.. math:: + :label: 9.38 + + d = \frac {1.6 A_{n}} {c_{s} / P_{atm} * 10^{6}} + + D = \frac {e_{i} - e_{a}} {1000} + + +Stomatal conductance, as solved by equation :eq:`9.36` (mol m :sup:`-2` s :sup:`-1`), is the larger of the two roots that satisfy the +quadratic equation. Values for :math:`c_{i}` are given by + +.. math:: + :label: 9.39 + c_{i} =c_{a} -\left(1.4r_{b} +1.6r_{s} \right)P_{atm} A{}_{n} The equations for :math:`c_{i}` , :math:`c_{s}` , :math:`r_{s}` , and @@ -541,23 +547,4 @@ combines the secant method and Brent’s method to solve for (:math:`A_{n}^{sun}` , :math:`r_{s}^{sun}` ) and shaded (:math:`A_{n}^{sha}` , :math:`r_{s}^{sha}` ) leaves. -The model has an optional (though not supported) multi-layer canopy, as -described by :ref:`Bonan et al. (2012)`. The multi-layer model is only intended -to address the non-linearity of light profiles, photosynthesis, and -stomatal conductance in the plant canopy. In the multi-layer canopy, -sunlit (:math:`A_{n}^{sun}` , :math:`r_{s}^{sun}` ) and shaded -(:math:`A_{n}^{sha}` , :math:`r_{s}^{sha}` ) leaves are explicitly -resolved at depths in the canopy using a light profile (Chapter :numref:`rst_Radiative Fluxes`). In -this case, :math:`V_{c\max 25}` is not integrated over the canopy, but -is instead given explicitly for each canopy layer using equation :eq:`9.18`. This -also uses the :ref:`Lloyd et al. (2010)` relationship whereby -K\ :sub:`n` scales with V\ :sub:`cmax` as - -.. math:: - :label: 9.38 - - K_{n} =\exp \left(0.00963V_{c\max } -2.43\right) -such that higher values of V\ :sub:`cmax` imply steeper declines -in photosynthetic capacity through the canopy with respect to cumulative -leaf area. From f52ce6c93555d6bec7f0436893dc78fe759556ea Mon Sep 17 00:00:00 2001 From: mvertens Date: Mon, 29 Jan 2018 20:03:36 -0700 Subject: [PATCH 127/255] new Makefiles introduced: to build pdf issue "make -f Makefile.tech_note latexpdf" TWICE and then open the file build/tech_note/latex/clmdoc.pdf --- doc/Makefile.tech_note | 20 ++++ doc/Makefile.users_guide | 20 ++++ doc/source/tech_note/conf.py | 170 +++++++++++++++++++++++++++++++++ doc/source/users_guide/conf.py | 170 +++++++++++++++++++++++++++++++++ 4 files changed, 380 insertions(+) create mode 100644 doc/Makefile.tech_note create mode 100644 doc/Makefile.users_guide create mode 100644 doc/source/tech_note/conf.py create mode 100644 doc/source/users_guide/conf.py diff --git a/doc/Makefile.tech_note b/doc/Makefile.tech_note new file mode 100644 index 0000000000..07ebab36e6 --- /dev/null +++ b/doc/Makefile.tech_note @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = clmdoc +SOURCEDIR = source/tech_note +BUILDDIR = build/tech_note + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile.tech_note + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/doc/Makefile.users_guide b/doc/Makefile.users_guide new file mode 100644 index 0000000000..08562d18ca --- /dev/null +++ b/doc/Makefile.users_guide @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = clmdoc +SOURCEDIR = source/users_guide +BUILDDIR = build/users_guide + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile.users_guide + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/doc/source/tech_note/conf.py b/doc/source/tech_note/conf.py new file mode 100644 index 0000000000..a866c7f3fb --- /dev/null +++ b/doc/source/tech_note/conf.py @@ -0,0 +1,170 @@ +# -*- coding: utf-8 -*- +# +# clmdoc documentation build configuration file, created by +# sphinx-quickstart on Thu Feb 23 17:14:30 2017. +# +# 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. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- 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.ext.intersphinx', + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.imgmath', + 'sphinx.ext.githubpages'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'clmdoc' +copyright = u'2017, Erik Kluzek, Bill Sacks, Ben Andre' +author = u'Erik Kluzek, Bill Sacks, Ben Andre' + +# 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 = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- 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 = 'bizstyle' + +# 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 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'clmdocdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + 'preamble': '\\usepackage{hyperref}', + + 'fncychap': '\\usepackage[Conny]{fncychap}', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'clmdoc', u'clmdoc Documentation', + [author], 1) +] + + +# -- 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 = [ + (master_doc, 'clmdoc', u'clmdoc Documentation', + author, 'clmdoc', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +numfig = True +numfig_format = {'figure': 'Figure %s', + 'table': 'Table %s', + 'code-block': 'Code %s', + 'section': '%s', + } diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py new file mode 100644 index 0000000000..a866c7f3fb --- /dev/null +++ b/doc/source/users_guide/conf.py @@ -0,0 +1,170 @@ +# -*- coding: utf-8 -*- +# +# clmdoc documentation build configuration file, created by +# sphinx-quickstart on Thu Feb 23 17:14:30 2017. +# +# 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. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- 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.ext.intersphinx', + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.imgmath', + 'sphinx.ext.githubpages'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'clmdoc' +copyright = u'2017, Erik Kluzek, Bill Sacks, Ben Andre' +author = u'Erik Kluzek, Bill Sacks, Ben Andre' + +# 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 = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- 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 = 'bizstyle' + +# 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 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'clmdocdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + 'preamble': '\\usepackage{hyperref}', + + 'fncychap': '\\usepackage[Conny]{fncychap}', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'clmdoc', u'clmdoc Documentation', + [author], 1) +] + + +# -- 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 = [ + (master_doc, 'clmdoc', u'clmdoc Documentation', + author, 'clmdoc', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +numfig = True +numfig_format = {'figure': 'Figure %s', + 'table': 'Table %s', + 'code-block': 'Code %s', + 'section': '%s', + } From 9564f466a4f1de4079f3add4d8ba1fa00383f629 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Wed, 31 Jan 2018 11:46:32 -0700 Subject: [PATCH 128/255] Updated figure 1, fixed Figure and Table descriptions and links --- .../CLM50_Tech_Note_Decomposition.rst | 4 +-- .../CLM50_Tech_Note_Introduction.rst | 36 ++++++++----------- 2 files changed, 16 insertions(+), 24 deletions(-) diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 30c9b3988d..0d2ad98687 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -101,7 +101,7 @@ for the coarse woody debris pool (CWD). .. _Table Decomposition rate constants: -.. table:: Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. +.. table:: Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters for the CLM-CN decomposition pool structure. +--------------------------+------------------------------------------------+-----------------------------------------------+---------------+-----------------------------------------+ | | Biome-BGC | CLM-CN | | | @@ -195,7 +195,7 @@ those described in Parton et al. (1988) (:numref:`Table Turnover times`). .. _Table Turnover times: -.. table:: Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. +.. table:: Turnover times, C:N ratios, and acceleration parameters for the Century-based decomposition cascade. +------------+------------------------+-------------+-------------------------------------------+ | | Turnover time (year) | C:N ratio | Acceleration term (:math:`{a}_{i}`) | diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 339ec3d05f..a887e5d9fc 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -1,4 +1,4 @@ -**July 2017** +**February 2018** **Technical Description of version 5.0 of the Community Land Model (CLM)** @@ -31,7 +31,7 @@ P. O. Box 3000, Boulder, Colorado 80307-300 **LIST OF FIGURES** -- :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM4.5). +- :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM5.0). - :numref:`Figure CLM subgrid hierarchy` Configuration of the CLM subgrid hierarchy. @@ -57,25 +57,19 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. -- :numref:`Figure Carbon and nitrogen pools` Carbon and nitrogen pools. - - :numref:`Figure annual phenology cycle` Example of annual phenology cycle for seasonal deciduous. -- 14.2. Example fluxes and pools sizes for an onset growth period of 15 days, with initial transfer pool size of 100 gC m-2 and a timestep of one hour. a) Flux leaving transfer pool (e.g. CFleaf\_xfer,leaf). b) Carbon content of transfer pool and its associated display pool (e.g. CSleaf\_xfer and CSleaf, respectively). - -- 14.3. Example fluxes and pool sizes for an offset (litterfall) period of 15 days, with initial display pool size of 100 gC m-2 and a timestep of one hour. a) Litterfall flux (e.g CFleaf,litter). b) Carbon content of display pool and litter pool through the litterfall period, ignoring the losses from litter pool due to decomposition during this period. - - :numref:`Figure Schematic of decomposition model in CLM` Schematic of decomposition model in CLM. -- :numref:`Figure Pool structure` Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 alternate soil decomposition models included in CLM. +- :numref:`Figure Pool structure` Pool structure, transitions, respired fractions, and turnover times for the 2 alternate soil decomposition models included in CLM. - :numref:`Figure Biological nitrogen fixation` Biological nitrogen fixation as a function of annual net primary production. -- :numref:`Figure Methane Schematic` Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. (left) Fully inundated portion of a CLM gridcell and (right) variably saturated portion of a gridcell. +- :numref:`Figure Methane Schematic` Schematic representation of biological and physical processes integrated in CLM that affect the net CH4 surface flux. - :numref:`Figure Schematic of land cover change` Schematic of land cover change impacts on CLM carbon pools and fluxes. -- :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM4 plant functional types. +- :numref:`Figure Schematic of translation of annual LUH2 land units` Schematic of translation of annual UNH land units to CLM plant functional types. **LIST OF TABLES** @@ -89,7 +83,7 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Land model output to atmospheric model` Land model output to atmospheric model -- :numref:`Table Surface data required for CLM and their base spatial resolution` Surface data required for CLM4.5 and their base spatial resolution +- :numref:`Table Surface data required for CLM and their base spatial resolution` Surface data required for CLM and their base spatial resolution - :numref:`Table Physical constants` Physical constants @@ -113,7 +107,7 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Coefficients for saturation vapor pressure` Coefficients for e\ :sub:`sat`\ :sup:`T` -- :numref:`Table Coefficients for derivative of esat` Coefficients for 112:numref:`` 6.1. Soil layer structure. +- :numref:`Table Coefficients for derivative of esat` Coefficients for the derivative of e\ :sub:`sat`\ :sup:`T` - :numref:`Table Meltwater scavenging` Meltwater scavenging efficiency for particles within snow @@ -129,11 +123,11 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Allocation and CN ratio parameters` Allocation and carbon:nitrogen ratio parameters -- :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the CLM-CN decomposition pool structure. +- :numref:`Table Decomposition rate constants` Decomposition rate constants for litter and SOM pools, C:N ratios, and acceleration parameters for the CLM-CN decomposition pool structure. - :numref:`Table Respiration fractions for litter and SOM pools` Respiration fractions for litter and SOM pools -- :numref:`Table Turnover times` Turnover times, C:N ratios, and acceleration parameters (see section 15.8 for explanation) for the Century-based decomposition cascade. +- :numref:`Table Turnover times` Turnover times, C:N ratios, and acceleration parameters for the Century-based decomposition cascade. - :numref:`Table Respiration fractions for Century-based structure` Respiration fractions for litter and SOM pools for Century-based structure @@ -143,13 +137,11 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Table Temperature dependence of aqueous and gaseous diffusion` Temperature dependence of aqueous and gaseous diffusion coefficients for CH4 and O2. -- :numref:`Table Crop plant functional types` Crop plant functional types (pfts) in CLM4.5CNcrop and their parameters relating to phenology and morphology. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. - -- :numref:`Table Crop plant functional types` Crop pfts in CLM4.5CNcrop and their parameters relating to allocation. Numbers in the first column correspond to the list of pfts in :numref:`Table Plant functional types`. +- :numref:`Table Crop plant functional types` Crop plant functional types (PFTs). -- :numref:`Table Crop allocation parameters` Crop allocation parameters for the active crop plant functional types (pfts) in CLM5BGCCROP. Numbers in the first row correspond to the list of pfts in :numref:`Table Crop plant functional types`. +- :numref:`Table Crop phenology parameters` Crop phenology and morphology parameters. -- :numref:`Table Plant functional type (PFT) biogeography rules` Plant functional type (PFT) biogeography rules with respect to climate. +- :numref:`Table Crop allocation parameters` Crop allocation parameters. - :numref:`Table Dust Mass fraction` Mass fraction m\ :sub:`i` , mass median diameter :sub:`v, i` , and geometric standard deviation :sub:`g, i` , per dust source mode i @@ -614,7 +606,7 @@ processes simulated include (:numref:`Figure Land processes`): #. External nitrogen cycling including deposition, denitrification, leaching, and losses due to fire (Chapter :numref:`rst_External Nitrogen Cycle`) -#. Plant mortality (Chapter :numref:`rst_Plant_Mortality`) +#. Plant mortality (Chapter :numref:`rst_Plant Mortality`) #. Fire ignition, suppression, spread, and emissions, including natural, deforestation, and agricultural fire (Chapter :numref:`rst_Fire`) @@ -635,4 +627,4 @@ processes simulated include (:numref:`Figure Land processes`): .. figure:: image1.png - Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM4.5). + Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM5.0). From 617a481ac2350376a9dd5a5c1405e83d54efd562 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Wed, 31 Jan 2018 13:32:17 -0700 Subject: [PATCH 129/255] Use svn rather than the default png for math images This makes the images appear much more crisp - less blurry. I did a quick visual inspection of the resulting html, and found a few problems with the svg images that I needed to fix: - CLM50_Tech_Note_Soil_Snow_Temperatures.rst There was a long array equation that didn't get rendered properly. I fixed this by breaking it into a bunch of separate equations. (Breaking it into two arrays worked, too, but it seemed cleaner just to break it into all of its pieces.) - CLM50_Tech_Note_Transient_Landcover.rst There were a few buggy math equations. I also cleaned this up a bit by removing some unnecessary '\' characters. --- doc/source/conf.py | 1 + ...CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 22 ++++++++++++++----- .../CLM50_Tech_Note_Transient_Landcover.rst | 18 +++++++-------- doc/source/tech_note/conf.py | 1 + doc/source/users_guide/conf.py | 1 + 5 files changed, 29 insertions(+), 14 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index a866c7f3fb..5c5b1d86ad 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -81,6 +81,7 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +imgmath_image_format = 'svg' # -- Options for HTML output ---------------------------------------------- diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index 780ccb4752..10c00ae1e5 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -71,24 +71,29 @@ and the thickness of each layer is a function of snow depth .. math:: - \begin{array}{lr} - \left\{ \begin{array}{l} snl=-1 \\ \Delta z_{0} = z_{sno} \end{array} \right\} & \qquad {\rm for\; 0.01}\le {\rm z}_{{\rm sno}} \le 0.03 \\ +.. math:: + \left\{ \begin{array}{l} snl=-2 \\ \Delta z_{-1} ={z_{sno} \mathord{\left/ {\vphantom {z_{sno} 2}} \right. \kern-\nulldelimiterspace} 2} \\ \Delta z_{0} = \Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.03}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.04 \\ +.. math:: + \left\{ \begin{array}{l} snl=-2 \\ \Delta z_{-1} = 0.02 \\ \Delta z_{0} = z_{sno} -\Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.04}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.07 \\ + +.. math:: + \left\{ \begin{array}{l} snl=-3 \\ \Delta z_{-2} = 0.02 \\ @@ -96,6 +101,8 @@ and the thickness of each layer is a function of snow depth \Delta z_{0} = \Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.07}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.12 \\ +.. math:: + \left\{ \begin{array}{l} snl=-3 \\ \Delta z_{-2} = 0.02 \\ @@ -103,6 +110,8 @@ and the thickness of each layer is a function of snow depth \Delta z_{0} = z_{sno} -\Delta z_{-2} -\Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.12}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.18 \\ +.. math:: + \left\{ \begin{array}{l} snl=-4 \\ \Delta z_{-3} = 0.02 \\ @@ -111,6 +120,8 @@ and the thickness of each layer is a function of snow depth \Delta z_{0} =\Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.18}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.29 \\ +.. math:: + \left\{ \begin{array}{l} snl=-4 \\ \Delta z_{-3} = 0.02 \\ @@ -119,6 +130,8 @@ and the thickness of each layer is a function of snow depth \Delta z_{0} = z_{sno} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.29}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.41 \\ +.. math:: + \left\{ \begin{array}{l} snl=-5 \\ \Delta z_{-4} = 0.02 \\ @@ -126,9 +139,10 @@ and the thickness of each layer is a function of snow depth \Delta z_{-2} = 0.11 \\ \Delta z_{-1} = {\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right)\mathord{\left/ {\vphantom {\left(z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} \right) 2}} \right. \kern-\nulldelimiterspace} 2} \\ \Delta z_{0} = \Delta z_{-1} - \end{array} \right\} & \qquad {\rm for\; 0.41}\, {\rm <}\, {\rm z}_{{\rm sno}} \le 0.64 \\ +.. math:: + \left\{ \begin{array}{l} snl=-5 \\ \Delta z_{-4} = 0.02 \\ @@ -138,8 +152,6 @@ and the thickness of each layer is a function of snow depth \Delta z_{0} = z_{sno} -\Delta z_{-4} -\Delta z_{-3} -\Delta z_{-2} -\Delta z_{-1} \end{array} \right\} & \qquad {\rm for\; 0.64}\, {\rm <}\, {\rm z}_{{\rm sno}} - \end{array} - The node depths, which are located at the midpoint of the snow layers, and the layer interfaces are both referenced from the soil surface and are defined as negative values diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index e8edb60222..493cfb2829 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -55,7 +55,7 @@ the calendar year for the current timestep, :math:`landuse.timeseries\_ year(nyears)` are the first and last calendar years in the *landuse.timeseries* dataset, respectively, :math:`nyears` is the number of years in the *landuse.timeseries* dataset, :math:`nt_{1}` and :math:`nt_{2}` -:math:`{}_{ }`\ are the two bracketing years used in the interpolation +are the two bracketing years used in the interpolation algorithm, and :math:`n` is the index value for the :math:`landuse.timeseries\_ year` array corresponding to :math:`landuse.timeseries\_ year(n)=year_{cur}` : @@ -75,7 +75,7 @@ dataset uses a simple linear algorithm, based on the conversion of the current time step information into a floating-point value for the number of calendar days since January 1 of the current model year (:math:`cday`). The interpolation weight for the current time step -:math:`tw_{cday}` \ :math:`{}_{ }`\ is +:math:`tw_{cday}` is .. math:: :label: 26.3) @@ -85,9 +85,9 @@ of calendar days since January 1 of the current model year where the numerator is 366 instead of 365 because the time manager function for CLM returns a value of :math:`cday=1.0` for midnight Greenwich mean time on January 1. With weights :math:`w_{p} (nt_{1} )` -and :math:`w_{p} (nt_{2} )`\ obtained from the *landuse.timeseries* dataset for fertilizer and wood harvest +and :math:`w_{p} (nt_{2} )` obtained from the *landuse.timeseries* dataset for fertilizer and wood harvest *p* at the bracketing annual time slices -:math:`nt_{1}` \ :math:`{}_{ }`\ and :math:`nt_{2}` , the interpolated +:math:`nt_{1}` and :math:`nt_{2}` , the interpolated application rate for the current time step (:math:`w_{p,t}` ) is .. math:: @@ -98,7 +98,7 @@ application rate for the current time step (:math:`w_{p,t}` ) is The form of this equation is designed to improve roundoff accuracy performance, and guarantees :math:`w_{p,t}` stays in the range [0,1]. Note that values for :math:`w_{p} (nt_{1} )`, :math:`w_{p} (nt_{2} )`, -and :math:`w_{p,t}` \ :math:`{}_{ }`\ are fractional weights at the +and :math:`w_{p,t}` are fractional weights at the column level of the subgrid hierarchy. The change in weight for a fertilizer or wood harvest rate between the current and previous time @@ -130,14 +130,14 @@ balance is calculated, W_{tot,1} =W_{a} +W_{sno} +\sum _{i=1}^{N_{levgrnd} }\left(w_{liq,i} +w_{ice,i} \right) +\sum _{j=1}^{npft}\left(W_{can,j} wt_{j,1} \right) where :math:`W_{a}` is the aquifer water, :math:`W_{sno}` is the snow -water, :math:`w_{liq,i}` and :math:`w_{ice,i}` \ are the liquid and ice -soil water contents, :math:`W_{can,j}` \ is the canopy water content for +water, :math:`w_{liq,i}` and :math:`w_{ice,i}` are the liquid and ice +soil water contents, :math:`W_{can,j}` is the canopy water content for PFT and CFT :math:`j`, and :math:`wt_{j,1}` is the PFT or CFT weight for :math:`j`. For the situation where PFT and CFT weights are changing, any difference -between :math:`W_{tot,1}` and :math:`W_{tot,2}` \ are due to +between :math:`W_{tot,1}` and :math:`W_{tot,2}` are due to differences in the total canopy water before and after the PFT and CFT weight change. To ensure conservation, the typically very small -difference between :math:`W_{tot,2}` \ and :math:`W_{tot,1}` is +difference between :math:`W_{tot,2}` and :math:`W_{tot,1}` is subtracted from the grid cell runoff .. math:: diff --git a/doc/source/tech_note/conf.py b/doc/source/tech_note/conf.py index a866c7f3fb..5c5b1d86ad 100644 --- a/doc/source/tech_note/conf.py +++ b/doc/source/tech_note/conf.py @@ -81,6 +81,7 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +imgmath_image_format = 'svg' # -- Options for HTML output ---------------------------------------------- diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index a866c7f3fb..5c5b1d86ad 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -81,6 +81,7 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +imgmath_image_format = 'svg' # -- Options for HTML output ---------------------------------------------- From 7b61cfddaf0e8b1304665b76e7400e21c4e2e199 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Wed, 31 Jan 2018 22:10:30 -0700 Subject: [PATCH 130/255] Work on glacier and ice sheet section and related documentation elsewhere --- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 69 ++-- .../Glacier/CLM50_Tech_Note_Glacier.rst | 306 ++++++++++++------ .../CLM50_Tech_Note_Introduction.rst | 4 +- .../References/CLM50_Tech_Note_References.rst | 9 + 4 files changed, 262 insertions(+), 126 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 6463e9d255..139aea37df 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -31,22 +31,25 @@ The second subgrid level, the column, is intended to capture potential variability in the soil and snow state variables within a single land unit. For example, the vegetated land unit could contain several columns with independently evolving vertical profiles of soil water and -temperature. Similarly, the managed vegetation land unit can be -divided into two columns, irrigated and non-irrigated. The default snow/soil -column is represented by 25 layers for ground (with up to 20 of these layers classified as soil layers and the remaining layers classified as bedrock layers) and up to 10 layers -for snow, depending on snow depth. The central characteristic of the -column subgrid level is that this is where the state variables for water -and energy in the soil and snow are defined, as well as the fluxes of -these components within the soil and snow. Regardless of the number and -type of PFTs occupying space on the column, the column physics operates -with a single set of upper boundary fluxes, as well as a single set of -transpiration fluxes from multiple soil levels. These boundary fluxes -are weighted averages over all PFTs. Currently, for glacier, lake, and -vegetated land units, a single column is assigned to each land unit. The -crop land unit is split into irrigated and unirrigated columns with a -single crop occupying each column. The urban land units have five -columns (roof, sunlit walls and shaded walls, and pervious and -impervious canyon floor) (Oleson et al. 2010b). +temperature. Similarly, the managed vegetation land unit can be divided +into two columns, irrigated and non-irrigated. The default snow/soil +column is represented by 25 layers for ground (with up to 20 of these +layers classified as soil layers and the remaining layers classified as +bedrock layers) and up to 10 layers for snow, depending on snow +depth. The central characteristic of the column subgrid level is that +this is where the state variables for water and energy in the soil and +snow are defined, as well as the fluxes of these components within the +soil and snow. Regardless of the number and type of PFTs occupying space +on the column, the column physics operates with a single set of upper +boundary fluxes, as well as a single set of transpiration fluxes from +multiple soil levels. These boundary fluxes are weighted averages over +all PFTs. Currently, for lake and vegetated land units, a single column +is assigned to each land unit. The crop land unit is split into +irrigated and unirrigated columns with a single crop occupying each +column. The urban land units have five columns (roof, sunlit walls and +shaded walls, and pervious and impervious canyon floor) (Oleson et +al. 2010b). The glacier land unit is separated into up to 10 elevation +classes. .. _Figure CLM subgrid hierarchy: @@ -431,6 +434,15 @@ to\ :math:`z_{atm}` . and solid precipitation, which are added to yield total liquid precipitation :math:`q_{rain}` and solid precipitation :math:`q_{sno}` . +However, in CLM5, the atmosphere's partitioning into liquid and solid +precipitation is ignored. Instead, CLM repartitions total precipitation +using a linear ramp. For most landunits, this ramp generates all snow +below :math:`0 \textdegree C`, all rain above :math:`2 \textdegree C`, +and a mix of rain and snow for intermediate temperatures. For glaciers, +the end points of the ramp are :math:`-2 \textdegree C` and :math:`0 +\textdegree C`, respectively. Changes to the phase of precipitation are +accompanied by a sensible heat flux (positive or negative) to conserve +energy. :sup:`3`\ There are 14 aerosol deposition rates required depending on species and affinity for bonding with water; 8 of these are dust @@ -680,14 +692,14 @@ The percentage glacier mask was derived from vector data of global glacier and ice sheet spatial coverage. Vector data for glaciers (ice caps, icefields and mountain glaciers) were taken from the first globally complete glacier inventory, the Randolph Glacier Inventory -version 1.0 (RGIv1.0: :ref:`Arendt et al. 2012 `). -Vector data for the Greenland Ice Sheet were provided by Frank Paul and -Tobias Bolch (University of Zurich: :ref:`Rastner et al. 2012 `). -Antarctic Ice Sheet data were provided by -Andrew Bliss (University of Alaska) and were extracted from the -Scientific Committee on Antarctic Research (SCAR) Antarctic Digital -Database version 5.0. Floating ice is only provided for the Antarctic -and does not include the small area of Arctic ice shelves. High spatial +version 1.0 (RGIv1.0: :ref:`Arendt et al. 2012 `). +Vector data for the Greenland Ice Sheet were provided by Frank Paul and +Tobias Bolch (University of Zurich: :ref:`Rastner et al. 2012 +`). Antarctic Ice Sheet data were provided by Andrew +Bliss (University of Alaska) and were extracted from the Scientific +Committee on Antarctic Research (SCAR) Antarctic Digital Database +version 5.0. Floating ice is only provided for the Antarctic and does +not include the small area of Arctic ice shelves. High spatial resolution vector data were then processed to determine the area of glacier, ice sheet and floating ice within 30-second grid cells globally. The 30-second glacier, ice sheet and Antarctic ice shelf masks @@ -704,8 +716,13 @@ by elevation and areal ice sheet fractional coverage by elevation. Ice fractions were binned at 100 meter intervals, with bin edges defined from 0 to 6000 meters (plus one top bin encompassing all remaining high-elevation ice, primarily in the Himalaya). These distributions by -elevation are needed when running CLM4 with multiple glacier elevation -classes. +elevation are used to divide each glacier land unit into columns based +on elevation class. + +When running with the CISM ice sheet model, CISM dictates glacier areas +and elevations in its domain, overriding the values specified by CLM's +datasets. In typical CLM5 configurations, this means that CISM dictates +glacier areas and elevations over Greenland. Percent lake and lake depth are area-averaged from the 90-second resolution data of :ref:`Kourzeneva (2009, 2010) ` to the 0.05\ :sup:`o` diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index 84752b5429..28d4f9cc15 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -4,134 +4,241 @@ Glaciers ============ This chapter describes features of CLM that are specific to coupling to -an ice sheet model (in the CESM context, this is the Glimmer-CISM model; -:ref:`Lipscomb and Sacks (2012)` provide documentation -and user’s guide for Glimmer-CISM). General information about glacier -land units can be found elsewhere in this document (see Chapter -:numref:`rst_Surface Characterization, Vertical Discretization, and -Model Input Requirements` for an overview). +an ice sheet model (in the CESM context, this is the CISM model; +:ref:`Lipscomb and Sacks (2012)` provide +documentation and user’s guide for CISM). General information +about glacier land units can be found elsewhere in this document (see +Chapter :numref:`rst_Surface Characterization, Vertical Discretization, +and Model Input Requirements` for an overview). .. _Overview Glaciers: Overview -------------- +-------- -CLM is responsible for computing three quantities that are passed to the +CLM is responsible for computing two quantities that are passed to the ice sheet model: -#. Surface mass balance (SMB) – the net annual accumulation/ablation of +#. Surface mass balance (SMB) - the net annual accumulation/ablation of mass at the upper surface (section :numref:`Computation of the surface mass balance`) #. Ground surface temperature, which serves as an upper boundary - condition for Glimmer-CISM’s temperature calculation - -#. Surface topography, which currently is fixed in time, and is provided - on CLM’s surface dataset + condition for CISM's temperature calculation The ice sheet model is typically run at much higher resolution than CLM (e.g., :math:`\sim`\ 5 km rather than :math:`\sim`\ 100 km). To improve the downscaling from CLM’s grid to the ice sheet grid, the glaciated portion of each grid cell is divided into multiple elevation classes -(section 10.2). The above quantities are computed separately in each -elevation class. Glimmer-CISM then computes high-resolution quantities -via horizontal and vertical interpolation. +(section :numref:`Multiple elevation class scheme`). The above +quantities are computed separately in each elevation class. The CESM +coupler then computes high-resolution quantities via horizontal and +vertical interpolation, and passes these high-resolution quantities to +CISM. There are several reasons for computing the SMB in CLM rather than in -Glimmer-CISM: +CISM: #. It is much cheaper to compute the SMB in CLM for :math:`\sim`\ 10 - elevation classes than in Glimmer-CISM. For example, suppose we are - running CLM at a resolution of :math:`\sim`\ 50 km and Glimmer at + elevation classes than in CISM. For example, suppose we are + running CLM at a resolution of :math:`\sim`\ 50 km and CISM at :math:`\sim`\ 5 km. Greenland has dimensions of about 1000 x 2000 km. For CLM we would have 20 x 40 x 10 = 8,000 columns, whereas for - Glimmer we would have 200 x 400 = 80,000 columns. + CISM we would have 200 x 400 = 80,000 columns. #. We can use the sophisticated snow physics parameterization already in - CLM instead of implementing a separate scheme for Glimmer-CISM. Any + CLM instead of implementing a separate scheme for CISM. Any improvements to the CLM are applied to ice sheets automatically. #. The atmosphere model can respond during runtime to ice-sheet surface - changes. As shown by :ref:`Pritchard et al. (2008)`, - runtime albedo feedback - from the ice sheet is critical for simulating ice-sheet retreat on - paleoclimate time scales. Without this feedback the atmosphere warms - much less, and the retreat is delayed. - -#. Mass is more nearly conserved, given that the rate of surface ice - growth or melting computed in CLM is equal to the rate seen by the - dynamic ice sheet model. (Mass conservation is not exact, however, - because of approximations made in interpolating from the CLM grid to - the ice-sheet grid.) + changes (even in the absence of two-way feedbacks with CISM). As + shown by :ref:`Pritchard et al. (2008)`, runtime + albedo feedback from the ice sheet is critical for simulating + ice-sheet retreat on paleoclimate time scales. Without this feedback + the atmosphere warms much less, and the retreat is delayed. #. The improved SMB is available in CLM for all glaciated grid cells (e.g., in the Alps, Rockies, Andes, and Himalayas), not just those which are part of ice sheets. -The current coupling between CLM and Glimmer-CISM is one-way only. That -is, CLM sends the SMB and surface temperature to Glimmer-CISM but does -not do anything with the fields that are returned. The CLM glacier -fraction and surface topography are therefore fixed in time. One-way -coupling is reasonable for runs of :math:`\sim`\ 100 years or less, in -which ice-sheet elevation changes are modest. For longer runs with -larger elevation changes, two-way coupling is highly desirable. A -two-way coupling scheme is under development. +In typical runs, CLM computes the SMB and sends it to CISM, but CISM's +ice sheet geometry remains fixed over the course of the run. In these +runs, CISM serves two roles in the system: + +#. Over the CISM domain (typically Greenland in CESM2), CISM dictates + glacier areas and topographic elevations, overriding the values on + CLM's surface dataset. CISM also dictates the elevation of + non-glacier land units in its domain, and atmospheric fields are + downscaled to non-glacier land units only in this domain. (So if you + run with a stub glacier model - SGLC - then glacier areas and + elevations will be taken entirely from CLM's surface dataset, and no + downscaling will be done over non-glacier land units.) + +#. CISM provides the grid onto which SMB is downscaled. (If you run with + SGLC then SMB will still be computed in CLM, but it won't be + downscaled to a high-resolution ice sheet grid.) + +However, it is also possible to run CESM with an evolving ice sheet. In +this case, CLM responds to CISM's evolution by adjusting the areas of +the glacier landunit and each elevation class within this landunit, as +well as the mean topographic heights of each elevation class. Thus, +CLM's glacier areas and elevations remain in sync with +CISM's. Conservation of mass and energy is done as for other landcover +change (see Chapter :numref:`rst_Transient Landcover Change`). + +.. _Glacier regions: + +Glacier regions and their behaviors +----------------------------------- + +The world's glaciers and ice sheets are broken down into a number of +different regions (four by default) that differ in three respects: + +#. Whether the gridcell's glacier landunit contains: + + a. Multiple elevation classes (section :numref:`Multiple elevation + class scheme`) + + b. Multiple elevation classes plus virtual elevation classes + + c. Just a single elevation class whose elevation matches the + atmosphere's topographic height (so there is no adjustment in + atmospheric forcings due to downscaling). + +#. Treatment of glacial melt water: + + a. Glacial melt water runs off and is replaced by ice, thus keeping + the column always frozen. This behavior is discussed in more + detail in section :numref:`Computation of the surface mass + balance`. + + b. Glacial melt water remains in place until it refreezes - possibly + remaining in place indefinitely if the glacier column is in a warm + climate. With this behavior, ice melt does not result in any + runoff. Regions with this behavior cannot compute SMB, because + negative SMB would be meaningless (due to the liquid water on top + of the ice column). This behavior produces less realistic glacier + physics. However, it avoids the negative ice runoff that is needed + for the "replaced by ice" behavior to conserve mass and energy (as + described in section :numref:`Computation of the surface mass + balance`). Thus, in regions where CLM has glaciers but the + atmospheric forcings are too warm to sustain those glaciers, this + behavior avoids persistent negative ice runoff. This situation can + often occur for mountain glaciers, where topographic smoothing in + the atmosphere results in a too-warm climate. There, avoiding + persistent negative ice runoff can be more important than getting + the right glacier ice physics. + +#. Treatment of ice runoff from snow capping (as described in section + :numref:`Runoff from glaciers and snow-capped surfaces`). Note that this + is irrelevant in regions with an evolving, two-way-coupled ice sheet + (where the snow capping term is sent to CISM rather than running off): + + a. Ice runoff from snow capping remains ice. This is a crude + parameterization of iceberg calving, and so is appropriate in + regions where there is substantial iceberg calving in reality. + + b. Ice runoff from snow capping is melted (generating a negative + sensible heat flux) and runs off as liquid. This matches the + behavior for non-glacier columns. This is appropriate in regions + that have little iceberg calving in reality. This can be important + to avoid unrealistic cooling of the ocean and consequent runaway + sea ice growth. + +The default behaviors for the world's glacier and ice sheet regions are +described in :numref:`Table Glacier region behaviors`. Note that the +standard CISM grid covers Greenland plus enough surrounding area to +allow for ice sheet growth and to have a regular rectangular grid. We +need to have the "replaced by ice" melt behavior within the CISM domain +in order to compute SMB there, and we need virtual elevation classes in +that domain in order to compute SMB for all elevation classes and to +facilitate glacial advance and retreat in the two-way-coupled +case. However, this domain is split into Greenland itself and areas +outside Greenland so that ice runoff in the Canadian archipelago (which +is inside the CISM domain) is melted before reaching the ocean, to avoid +runaway sea ice growth in that region. + +.. _Table Glacier region behaviors: + +.. table:: Glacier region behaviors + + +---------------+---------------+---------------+---------------+ + | Region | Elevation | Glacial melt | Ice runoff | + | | classes | | | + +===============+===============+===============+===============+ + | Greenland | Virtual | Replaced by | Remains ice | + | | | ice | | + +---------------+---------------+---------------+---------------+ + | Inside | Virtual | Replaced by | Melted | + | standard CISM | | ice | | + | grid but | | | | + | outside | | | | + | Greenland | | | | + | itself | | | | + +---------------+---------------+---------------+---------------+ + | Antarctica | Multiple | Replaced by | Remains ice | + | | | ice | | + +---------------+---------------+---------------+---------------+ + | All others | Single | Remains in | Melted | + | | | place | | + +---------------+---------------+---------------+---------------+ + .. _Multiple elevation class scheme: Multiple elevation class scheme ------------------------------------- - -In the typical operation of CLM, the glacier land unit contains a single -column (section :numref:`Surface Heterogeneity and Data Structure`). -However, when running CESM with an active ice -sheet model, the glacier land unit is replaced by a glacier\_mec land -unit, where “mec†denotes “multiple elevation classesâ€. In most ways, -glacier\_mec land units behave the same as standard glacier land units. -However, each glacier\_mec land unit is divided into a user-defined set -of columns based on surface elevation. The default is 10 elevation -classes whose lower limits are 0, 200, 400, 700, 1000, 1300, 1600, 2000, -2500, and 3000 m. Each column is characterized by a fractional area and -surface elevation that are read in during model initialization. Each -glacier\_mec column within a grid cell has distinct ice and snow -temperatures, snow water content, surface fluxes, and SMB. - -Glacier\_mec columns, like glacier columns, are initialized with a -temperature of 250 K. While glacier columns are initialized with a snow -liquid water equivalent (LWE) equal to the maximum allowed value of 1 m, -glacier\_mec columns begin with a snow LWE of 0.5 m so that they will -reach their equilibrium mean snow depth sooner. Glacier\_mec columns -typically require several decades of spin-up to equilibrate with a given -climate. +------------------------------- + +The glacier landunit contains multiple columns based on surface +elevation. These are known as elevation classes, and the land unit is +referred to as glacier\_mec. (As described in section :numref:`Glacier +regions`, some regions have only a single elevation class, but they are +still referred to as glacier\_mec landunits.) The default is to have 10 +elevation classes whose lower limits are 0, 200, 400, 700, 1000, 1300, +1600, 2000, 2500, and 3000 m. Each column is characterized by a +fractional area and surface elevation that are read in during model +initialization, and then possibly overridden by CISM as the run +progresses. Each glacier\_mec column within a grid cell has distinct ice +and snow temperatures, snow water content, surface fluxes, and SMB. The atmospheric surface temperature, potential temperature, specific -humidity, density, and pressure are downscaled from the mean grid cell -elevation to the glacier\_mec column elevation using a specified lapse -rate (typically 6.0 deg/km) and an assumption of uniform relative -humidity. At a given time, lower-elevation columns can undergo surface +humidity, density, and pressure are downscaled from the atmosphere's +mean grid cell elevation to the glacier\_mec column elevation using a +specified lapse rate (typically 6.0 deg/km) and an assumption of uniform +relative humidity. Longwave radiation is downscaled by assuming a linear +decrease in downwelling longwave radiation with increasing elevation +(0.032 W m :sup:`-2` m :sup:`-1`, limited to 0.5 - 1.5 times the +gridcell mean value, then normalized to conserve gridcell total energy) +:ref:`(Van Tricht et al., 2016)`. Total precipitation +is partitioned into rain vs. snow as described in Chapter +:numref:`rst_Surface Characterization, Vertical Discretization, and +Model Input Requirements`. The partitioning of precipitation is based on +the downscaled temperature, allowing rain to fall at lower elevations +while snow falls at higher elevations. + +This downscaling allows lower-elevation columns to undergo surface melting while columns at higher elevations remain frozen. This gives a more accurate simulation of summer melting, which is a highly nonlinear -function of air temperature. The precipitation rate and radiative fluxes -are not currently downscaled, but could be in the future if care were -taken to preserve the cell-integrated values. +function of air temperature. + +Within the CISM domain, this same downscaling procedure is also applied +to all non-urban land units. The elevation of non-glacier land units is +taken from the mean elevation of ice-free grid cells in CISM. This is +done in order to keep the glaciated and non-glaciated portions of the +CISM domain as consistent as possible. In contrast to most CLM subgrid units, glacier\_mec columns can be active (i.e., have model calculations run there) even if their area is -zero. This is done because the ice sheet model may require a SMB even -for some grid cells where CLM does not have glacier land units. To allow -for this, grid overlap files have been pre-computed. For given -resolutions of CLM and Glimmer-CISM, these files identify all -land-covered grid cells that overlap any part of the ice sheet grid. In -these overlapping cells, glacier\_mec columns are defined in all -elevation classes. Some columns may have zero area and are called -“virtual†columns. These columns do not affect energy exchange between -the land and the atmosphere, but are included for potential forcing of -Glimmer-CISM. +zero. These are known as "virtual" columns. This is done because the ice +sheet model may require a SMB even for some grid cells where CLM does +not have glacier land units. Virtual columns do not affect energy +exchange between the land and the atmosphere, but are included for +potential forcing of CISM. .. _Computation of the surface mass balance: Computation of the surface mass balance --------------------------------------------- +--------------------------------------- The SMB of a glacier or ice sheet is the net annual accumulation/ablation of mass at the upper surface. Ablation is defined @@ -144,17 +251,6 @@ the melting depends on the sum of the radiative, turbulent, and conductive fluxes reaching the surface, as described elsewhere in this document. -CLM has a somewhat unrealistic treatment of accumulation and melting for -standard glacier land units. The snow depth is limited to a prescribed -depth of 1 m liquid water equivalent, with any additional snow assumed -to run off to the ocean. (This amounts to a crude parameterization of -iceberg calving.) Snow melting is treated in a realistic fashion, with -meltwater percolating downward through snow layers as long as the snow -is unsaturated. Once the underlying snow is saturated, any additional -meltwater runs off. When glacier ice melts, however, the meltwater is -assumed to remain in place until it refreezes. In warm parts of the ice -sheet, the meltwater does not refreeze, but stays in place indefinitely. - In the modified glacier\_mec columns, the treatment of melting and freezing depends on the logical variable *glc\_dyntopo*. This variable controls whether CLM surface topography changes dynamically as the ice @@ -171,12 +267,26 @@ for glacier\_mec land units is computed as for glacier land units: Any snow in excess of 1 m LWE runs off to the ocean, and Melted ice remains in place until it refreezes. Excess snow and melted ice still contribute to positive and negative values, respectively, of *qice*, but only for -the purpose of forcing Glimmer-CISM. Currently, *glc\_dyntopo* = false +the purpose of forcing CISM. Currently, *glc\_dyntopo* = false is the default, and the only supported option. Note that the SMB typically is defined as the total accumulation of ice -and snow, minus the total ablation. The *qice* flux passed to -Glimmer-CISM is the mass balance for ice alone, not snow. We can think -of CLM as owning the snow, whereas Glimmer-CISM owns the underlying ice. -Fluctuations in snow depth between 0 and 1 m LWE are not reflected in -the SMB passed to Glimmer-CISM. +and snow, minus the total ablation. The *qice* flux passed to CISM is +the mass balance for ice alone, not snow. We can think of CLM as owning +the snow, whereas CISM owns the underlying ice. Fluctuations in snow +depth between 0 and 10 m water equivalent are not reflected in the SMB +passed to CISM. In transient runs, this can lead to delays of a few +decades in the onset of accumulation or ablation in a given glacier +column. + +In regions where SMB is computed for glaciers, SMB is also computed for +the natural vegetated land unit. Because there is no ice to melt in this +land unit, it can only generate a zero or positive SMB. A positive SMB +is generated once the snow pack reaches its maximum depth. When running +with an evolving ice sheet, this condition triggers glacial inception. + +FIXME: Make sure I talk about the positive liquid runoff and negative +ice runoff that result from melted ice. + +FIXME: With interactive CISM, snow capping is applied to the surface +mass balance, not ice runoff. diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index a887e5d9fc..853385f36b 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -504,9 +504,9 @@ In CLM5, where new parameterizations or model decisions were made, in most cases The hydrology updates include the introduction of a dry surface layer-based soil evaporation resistance parameterization :ref:`(Swenson and Lawrence, 2014)` and a revised canopy interception parameterization. Canopy interception is now divided into liquid and solid phases, with the intercepted snow subject to unloading events due to wind or above-freezing temperatures. The snow-covered fraction of the canopy is used within the canopy radiation and surface albedo calculation. Instead of applying a spatially uniform soil thickness, soil thickness can vary in space :ref:`(Brunke et al. 2016` and :ref:`Swenson and Lawrence, 2015)` and is set to values within a range of 0.4m to 8.5m depth, derived from a spatially explicit soil thickness data product :ref:`(Pelletier et al., 2016)`. The explicit treatment of soil thickness allows for the deprecation of the unconfined aquifer parameterization used in CLM4.5, which is replaced with a zero flux boundary condition and explicit modeling of both the saturated and unsaturated zones. The default model soil layer resolution is increased, especially within the top 3m, to more explicitly represent active layer thickness within the permafrost zone. Rooting profiles were used inconsistently in CLM4.5 with :ref:`Zeng (2001)` profiles used for water and :ref:`Jackson et al. (1996)` profiles used for carbon inputs. For CLM5, the Jackson et al. (1996) rooting profiles are used for both water and carbon. Roots are deepened for the broadleaf evergreen tropical tree and broadleaf deciduous tropical tree types. Finally, an adaptive time-stepping solution to the Richard's equation is introduced, which improves the accuracy and stability of the numerical soil water solution. The River Transport Model (RTM) is replaced with the Model for Scale Adaptive River Transport (MOSART, :ref:`Li et al., 2013b)` in which surface runoff is routed across hillslopes and then discharged along with subsurface runoff into a tributary subnetwork before entering the main channel. Several changes are included that are mainly targeted at improving the simulation of surface mass balance over ice -sheets. The fresh snow density parameterization is updated to more realistically capture the temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is active for Greenland by default with one-way coupling (surface mass balance impacts ice sheet dynamics, but ice sheet dynamics do not feedback onto surface elevation). Two-way coupling can be activated through a namelist switch. The introduction in CLM5 of the capability to +sheets. The fresh snow density parameterization is updated to more realistically capture temperature effects and to additionally account for wind effects on new snow density :ref:`(van Kampenhout et al., 2017)`. The maximum number of snow layers and snow amount is increased from 5 layers and 1m snow water equivalent to 12 layers and 10m snow water equivalent to allow for the formation of firn in regions of persistent snow-cover (e.g., glaciers and ice sheets) :ref:`(van Kampenhout et al., 2017)`. The CISM2 ice sheet model is included for Greenland by default. The ice sheet does not evolve for typical configurations, but ice sheet evolution can be turned on by choosing an appropriate compset. The introduction in CLM5 of the capability to dynamically adjust landunit weights means that a glacier can initiate, grow, shrink, or disappear during -a simulation when two-way coupling is active. Multiple elevation classes (10 elevation classes by default) and associated temperature, rain/snow partitioning, and downwelling longwave downscaling are used for glacier landunits to account for the strong topographic elevation heterogeneity over glaciers and ice sheets. +a simulation when ice evolution is active. That is, there are two-way feedbacks between CLM and CISM. Multiple elevation classes (10 elevation classes by default) and associated temperature, rain/snow partitioning, and downwelling longwave downscaling are used for glacier landunits to account for the strong topographic elevation heterogeneity over glaciers and ice sheets. A plant hydraulic stress routine is introduced which explicitly models water transport through the vegetation according to a simple hydraulic framework (Kennedy et al., to be submitted). The water supply equations are used to solve for vegetation water potential forced by transpiration demand and a set of layer-by-layer soil water potentials. Stomatal conductance, therefore, is a function of prognostic leaf water potential. Water stress is calculated as the ratio of attenuated stomatal conductance to maximum stomatal conductance. An emergent feature of the plant hydraulics is soil hydraulic redistribution. In CLM5, maximum stomatal conductance is obtained from the Medlyn conductance model :ref:`(Medlyn et al., 2011)`, rather than the Ball-Berry stomatal conductance model that was utilized in CLM4.5 and prior versions of the model. The Medlyn stomatal conductance model is preferred mainly for it's more realistic behavior at low humidity levels :ref:`(Rogers et al., 2017)`. The stress deciduous vegetation phenology trigger is augmented with a antecedent precipitation requirement :ref:`(Dahlin et al. 2015)`. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 5168284551..ba331704d0 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -2698,6 +2698,15 @@ Lawrence, A.G. Slater, and M.R. van den Broeke, 2017. Improving the representation of polar snow and firn in the Community Earth System Model, submitted. +.. _VanTrichtetal2016: + +|br| + +Van Tricht, K., Lhermitte, S., Gorodetskaya, I.V. and van Lipzig, +N.P.M., 2016. Improving satellite-retrieved surface radiative fluxes in +polar regions using a smart sampling approach. The Cryosphere +10:2379-2397. doi:10.5194/tc-10-2379-2016 + .. _VanVuurenetal2006: |br| From 74b2220c084a1d888639fe894e2581c0ca885fef Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 1 Feb 2018 06:27:09 -0700 Subject: [PATCH 131/255] add information on glc_dyn_runoff_routing --- .../Glacier/CLM50_Tech_Note_Glacier.rst | 32 ++++++++++++++++--- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index 28d4f9cc15..e125a1141e 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -240,6 +240,13 @@ potential forcing of CISM. Computation of the surface mass balance --------------------------------------- +This section describes the computation of surface mass balance and +associated runoff terms. The description here only applies to regions +where glacial melt runs off and is replaced by ice, not to regions where +glacial melt remains in place. Thus, by default, this only applies to +Greenland and Antarctica, not to mountain glaciers elsewhere in the +world. (See also :numref:`Glacier regions`.) + The SMB of a glacier or ice sheet is the net annual accumulation/ablation of mass at the upper surface. Ablation is defined as the mass of water that runs off to the ocean. Not all the surface @@ -251,6 +258,26 @@ the melting depends on the sum of the radiative, turbulent, and conductive fluxes reaching the surface, as described elsewhere in this document. +SMB is computed and sent to the CESM coupler regardless of whether and +where CISM is operating. However, the effect of SMB terms on runoff +fluxes differs depending on whether and where CISM is evolving in +two-way-coupled mode. This is described by the variable +*glc\_dyn\_runoff\_routing*. (This is real-valued in the code to handle +the edge case where a CLM grid cell partially overlaps with the CISM +grid, but we describe it as a logical variable here for simplicity.) In +typical cases where CISM is not evolving, *glc\_dyn\_runoff\_routing* +will be false everywhere. In cases where CISM is evolving and sending +its own calving flux to the coupler, *glc\_dyn\_runoff\_routing* will be +true over the CISM domain and false elsewhere. + +FIXME: Rewrite the following paragraph + +FIXME: Make sure I talk about the positive liquid runoff and negative +ice runoff that result from melted ice. + +FIXME: With interactive CISM, snow capping is applied to the surface +mass balance, not ice runoff. + In the modified glacier\_mec columns, the treatment of melting and freezing depends on the logical variable *glc\_dyntopo*. This variable controls whether CLM surface topography changes dynamically as the ice @@ -285,8 +312,3 @@ land unit, it can only generate a zero or positive SMB. A positive SMB is generated once the snow pack reaches its maximum depth. When running with an evolving ice sheet, this condition triggers glacial inception. -FIXME: Make sure I talk about the positive liquid runoff and negative -ice runoff that result from melted ice. - -FIXME: With interactive CISM, snow capping is applied to the surface -mass balance, not ice runoff. From 3311d37fa59e748db552f074fca1ce942c9cff78 Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Thu, 1 Feb 2018 07:55:18 -0700 Subject: [PATCH 132/255] changed snow layers --- .../CLM50_Tech_Note_Snow_Hydrology.rst | 24 +++++++++++++++---- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index a97e161526..14ceeaa968 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -6,10 +6,10 @@ Snow Hydrology The parameterizations for snow are based primarily on :ref:`Anderson (1976) `, :ref:`Jordan (1991) `, and :ref:`Dai and Zeng (1997) `. The snowpack -can have up to five layers. These layers are indexed in the Fortran code -as :math:`i=-4,-3,-2,-1,0` where layer :math:`i=0` is the snow layer -next to the top soil layer and layer :math:`i=-4` is the top layer of a -five-layer snow pack. Since the number of snow layers varies according +can have up to twelve layers. These layers are indexed in the Fortran code +as :math:`i=-11,-10,...,-1,0` where layer :math:`i=0` is the snow layer +next to the top soil layer and layer :math:`i=-11` is the top layer of a +twelve-layer snow pack. Since the number of snow layers varies according to the snow depth, we use the notation :math:`snl+1` to describe the top layer of snow for the variable layer snow pack, where :math:`snl` is the negative of the number of snow layers. Refer to :numref:`Figure three layer @@ -697,7 +697,21 @@ where :math:`\Delta z_{i}` is the layer thickness. +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ | 4 | 0.055 | 4 | :math:`>`\ 4 | 0.41 | 0.23 | +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ - | 5 (bottom) | 0.115 | 5 | - | - | - | + | 5 | 0.115 | 5 | :math:`>`\ 5 | 0.88 | 0.47 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 6 | 0.235 | 6 | :math:`>`\ 6 | 1.83 | 0.95 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 7 | 0.475 | 7 | :math:`>`\ 7 | 3.74 | 1.91 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 8 | 0.955 | 8 | :math:`>`\ 8 | 7.57 | 3.83 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 9 | 1.915 | 9 | :math:`>`\ 9 | 15.24 | 7.67 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 10 | 3.835 | 10 | :math:`>`\ 10 | 30.59 | 15.35 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 11 | 7.675 | 11 | :math:`>`\ 11 | 61.30 | 30.71 | + +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ + | 12 (bottom) | 15.355 | 12 | - | - | - | +--------------+-----------------------------+------------------+------------------+-----------------------------------------------+---------------------------------------------------------+ The maximum snow layer thickness, :math:`\Delta z_{\max }` , depends on From c894f733684bc21083f6b5abe91b0357a62e3cff Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Thu, 1 Feb 2018 15:37:41 +0100 Subject: [PATCH 133/255] Update CLM50_Tech_Note_References.rst --- .../tech_note/References/CLM50_Tech_Note_References.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index ba331704d0..06dfb22835 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -2695,8 +2695,8 @@ turnover through the microbial biomass in soil. Plant and Soil, 76: van Kampenhout, L., J.T.M. Lenaerts, W.H. Lipscomb, W.J. Sacks, D.M. Lawrence, A.G. Slater, and M.R. van den Broeke, 2017. -Improving the representation of polar snow and firn in the -Community Earth System Model, submitted. +Improving the Representation of Polar Snow and Firn in the +Community Earth System Model. Journal of Advances in Modeling Earth Systems 9, no. 7: 2583–2600. https://doi.org/10.1002/2017MS000988. .. _VanTrichtetal2016: From 4d7440c8eab951b07150f2c6e87de6f64884085a Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Thu, 1 Feb 2018 16:05:20 +0100 Subject: [PATCH 134/255] Update CLM50_Tech_Note_Hydrology.rst Update the most obvious things that have changed in 2.7.6. Runoff from glaciers and snow-capped surface --- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 27 +++++++------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 2ca572ee9e..fb0dff13ab 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -1240,22 +1240,15 @@ Runoff from glaciers and snow-capped surfaces ------------------------------------------------- All surfaces are constrained to have a snow water equivalent -:math:`W_{sno} \le 1000` kg m\ :sup:`-2`. For snow-capped -surfaces, the solid and liquid precipitation reaching the snow surface -and dew in solid or liquid form, is separated into solid -:math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms - -.. math:: - :label: 7.178 - - q_{snwcp,ice} =q_{grnd,ice} +q_{frost} - -.. math:: - :label: 7.179 - - q_{snwcp,liq} =q_{grnd,liq} +q_{dew} - -and snow pack properties are unchanged. The :math:`q_{snwcp,ice}` +:math:`W_{sno} \le W_{cap} = 10,000` kg m\ :sup:`-2`. For snow-capped +columns, any addition of mass at the top (precipitation, dew/riping) is +balanced by an equally large mass flux at the bottom of the snow column. +This so-called capping flux is separated into solid +:math:`q_{snwcp,ice}` \ and liquid :math:`q_{snwcp,liq}` runoff terms. +The partitioning of these phases is based on the phase ratio in the bottom snow +layer at the time of the capping, such that phase ratio in this layer is unaltered. + +The :math:`q_{snwcp,ice}` runoff is sent to the River Transport Model (RTM) (Chapter 11) where it is routed to the ocean as an ice stream and, if applicable, the ice is melted there. @@ -1284,5 +1277,3 @@ The contribution of lake runoff to :math:`q_{rgwl}` is described in section :numref:`Precipitation, Evaporation, and Runoff Lake`. The runoff term :math:`q_{rgwl}` may be negative for glaciers and lakes, which reduces the total amount of runoff available to the river routing model (Chapter :numref:`rst_River Transport Model (RTM)`). - -> From 0b7b34d5af4735805996018f91889cdb0375342a Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Thu, 1 Feb 2018 17:01:20 +0100 Subject: [PATCH 135/255] fresh snow grain size is temperature dependent in CLM5 --- .../Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 386cf77bd2..3ecf53e0f2 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -956,8 +956,13 @@ each time step *t* as r_{e} \left(t\right)=\left[r_{e} \left(t-1\right)+dr_{e,\, dry} +dr_{e,\, wet} \right]f_{old} +r_{e,\, 0} f_{new} +r_{e,\, rfz} f_{rfrz} Here, the effective radius of freshly-fallen snow -(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sup:`-1`), and the effective -radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. +(:math:`r_{e,0}`) is based on a simple linear temperature-relationship. +Below -30 degrees Celcius, a minimum value is enforced of 54.5 :math:`\mu` m +(corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sup:`-1`). +Above 0 degrees Celcius, a maximum value is enforced of 204.5 :math:`\mu` m. +Between -30 and 0 a linear ramp is used. + +The effective radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. Dry snow aging is based on a microphysical model described by :ref:`Flanner and Zender (2006) `. This model simulates diffusive vapor flux From c23747d2b0d6a01ec43c2f0e83c11808d3365582 Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Thu, 1 Feb 2018 17:01:20 +0100 Subject: [PATCH 136/255] fresh snow grain size is temperature dependent in CLM5 --- .../Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 386cf77bd2..3ecf53e0f2 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -956,8 +956,13 @@ each time step *t* as r_{e} \left(t\right)=\left[r_{e} \left(t-1\right)+dr_{e,\, dry} +dr_{e,\, wet} \right]f_{old} +r_{e,\, 0} f_{new} +r_{e,\, rfz} f_{rfrz} Here, the effective radius of freshly-fallen snow -(:math:`r_{e,0}`) is fixed globally at 54.5 :math:`\mu` m (corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sup:`-1`), and the effective -radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. +(:math:`r_{e,0}`) is based on a simple linear temperature-relationship. +Below -30 degrees Celcius, a minimum value is enforced of 54.5 :math:`\mu` m +(corresponding to a specific surface area of 60 m\ :sup:`2` kg\ :sup:`-1`). +Above 0 degrees Celcius, a maximum value is enforced of 204.5 :math:`\mu` m. +Between -30 and 0 a linear ramp is used. + +The effective radius of refrozen liquid water (:math:`r_{e,rfz}`) is set to 1000\ :math:`\mu` m. Dry snow aging is based on a microphysical model described by :ref:`Flanner and Zender (2006) `. This model simulates diffusive vapor flux From e030158745504eeeb3a6773be2bcfc0e46cb5d77 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Thu, 1 Feb 2018 09:36:05 -0700 Subject: [PATCH 137/255] Reordered and edited references and minor fixes in FATES/DGVM chapters --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 44 +-- .../CLM50_Tech_Note_Introduction.rst | 2 +- .../References/CLM50_Tech_Note_References.rst | 354 ++++++++---------- 3 files changed, 173 insertions(+), 227 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 170d44eb7a..4c3ae84448 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -6,9 +6,9 @@ Dynamic Global Vegetation What has changed ^^^^^^^^^^^^^^^^^^^^ -- Deprecation of the dynamic global vegetation model (DGVM): The CLM5.0 model contains the legancy 'CNDV' code, which runs the CLM4(CN) model in combination with the LPJ-derived dynamics vegetation model introduced in CLM3. While this capacity has not technically been removed from the model, the DGVM has not been tested in the development of CLM5 and is no longer scientifically supported. +- Deprecation of the dynamic global vegetation model (DGVM): The CLM5.0 model contains the legacy 'CNDV' code, which runs the CLM biogeochemistry model in combination with the LPJ-derived dynamics vegetation model introduced in CLM3. While this capacity has not technically been removed from the model, the DGVM has not been tested in the development of CLM5 and is no longer scientifically supported. -- Introduction of FATES: The Functionally Assembled Terrestrial Ecosystem Simulator (FATES) is the actively developed DGVM for the CLM5. See +- Introduction of FATES: The Functionally Assembled Terrestrial Ecosystem Simulator (FATES) is the actively developed DGVM for the CLM5. .. _rst_FATES: @@ -20,11 +20,7 @@ FATES is the "Functionally Assembled Terrestrial Ecosystem Simulator". It is an FATES was derived from the CLM Ecosystem Demography model (CLM(ED)), which was documented in: -Fisher RA, Muszala S, Verteinstein M, Lawrence P, Xu C, McDowell NG, - Knox RG, Koven C, Holm J, Rogers BM, Lawrence D. Taking off the - training wheels: the properties of a dynamic vegetation model without - climate envelopes. Geoscientific Model Development Discussions. 2015 - Apr 1;8(4). +Fisher, R. A., Muszala, S., Verteinstein, M., Lawrence, P., Xu, C., McDowell, N. G., Knox, R. G., Koven, C., Holm, J., Rogers, B. M., Spessa, A., Lawrence, D., and Bonan, G.: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED), Geosci. Model Dev., 8, 3593-3619, https://doi.org/10.5194/gmd-8-3593-2015, 2015. and this technical note was first published as an appendix to that paper. @@ -53,9 +49,9 @@ for carbon storage allocation, and for tree mortality under carbon stress, are also included and presented here. Numerous other implementations of the -Ecosystem Demography concept exist (See Fisher et al. 2017 for a review of these) Therefore, to avoid confusion between the +Ecosystem Demography concept exist (See :ref:`Fisher et al. (2018)` for a review of these) Therefore, to avoid confusion between the concept of 'Ecosystem Demography' and the implementation of this concept -in different models, the CLM(ED) implementation described by Fisher et al. (2015) will hereafter be called 'FATES' (the Functionally Assembled Terrestrial Ecosystem Simulator). +in different models, the CLM(ED) implementation described by :ref:`Fisher et al. (2015)` will hereafter be called 'FATES' (the Functionally Assembled Terrestrial Ecosystem Simulator). The representation of ecosystem heterogeneity in FATES ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -101,7 +97,7 @@ history.** The 'patch' organizational structure in CLM thus replaces the previous 'PFT' structure in the organization heirarchy. The original hierarchical land surface organizational structure of CLM as described in -:ref:`Oleson et al. 2013` may be depicted as: +:ref:`Oleson et al. 2013` may be depicted as: .. math:: @@ -709,7 +705,7 @@ performance in ED-like cohort based models, since they determine how light resources are partitioned between competing plants of varying heights, which has a very significant impact on how vegetation distribution emerges from competition -:ref:`Fisher et al. 2010`. +:ref:`Fisher et al. 2010`. The standard ED1.0 model makes a simple 'flat disk' assumption, that the leaf area of each cohort is spread in an homogenous layer at one exact @@ -796,7 +792,7 @@ Under these circumstances, the `extra` crown area :math:`A_{loss}` (i.e., :math:`A_{canopy}` - :math:`A_p`) is moved into the understorey. For each cohort already in the canopy, we determine a fraction of trees that are moved from the canopy (:math:`L_c`) to the understorey. -:math:`L_c` is calculated as :ref:`Fisher et al. 2010` +:math:`L_c` is calculated as :ref:`Fisher et al. 2010` .. math:: L_{c}= \frac{A_{loss,patch} w_{coh}}{\sum_{coh=1}^{nc,patch}{w_{coh}}} , @@ -1354,7 +1350,7 @@ profile section. Firstly, we denote two or more canopy layers (denoted :math:`C_l`). The concept of a ‘canopy layer’ refers to the idea that plants are organized into discrete over and under-stories, as predicted by the Perfect Plasticity Approximation -(:ref:`Purves et al. 2008`, :ref:`Fisher et al. 2010`). Within each canopy layer +(:ref:`Purves et al. 2008`, :ref:`Fisher et al. 2010`). Within each canopy layer there potentially exist multiple cohorts of different plant functional types and heights. Within each canopy layer, :math:`C_l`, and functional type, :math:`ft`, the model resolves numerous leaf layers :math:`z`, @@ -1527,9 +1523,9 @@ photosynthesis model before describing its application to the FATES canopy structure. This description in this section is largely repeated from the Oleson et al. CLM4.5 technical note but included here for comparison with its implementation in FATES. Photosynthesis in C3 -plants is based on the model of :ref:`Farquhar 1980` as -modified by :ref:`Collatz et al. 1991`. Photosynthetic assimilation -in C4 plants is based on the model of :ref:`Collatz et al. 1991`. +plants is based on the model of :ref:`Farquhar 1980` as +modified by :ref:`Collatz et al. (1991)`. Photosynthetic assimilation +in C4 plants is based on the model of :ref:`Collatz et al. (1991)`. In both models, leaf photosynthesis, :math:`\textrm{gpp}` (:math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`) is calculated as the minimum of three potentially limiting fluxes, @@ -1556,7 +1552,7 @@ partial pressure (Pa). :math:`K_{c}` and :math:`K_{o}` are the Michaelis-Menten constants (Pa) for CO\ :math:`_{2}` and O\ :math:`_{2}`. These vary with vegetation temperature :math:`T_v` (:math:`^{o}`\ C) according to an Arrhenious function described in -:ref:`Oleson et al. 2013`. :math:`V_{c,max}` is the leaf layer +:ref:`Oleson et al. 2013`. :math:`V_{c,max}` is the leaf layer photosynthetic capacity (:math:`\mu` mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`). @@ -1627,7 +1623,7 @@ CO\ :math:`_{2}` compensation point :math:`\Gamma_{*}` (Pa) is where the term 0.21 represents the ratio of maximum rates of oxygenation to carboxylation, which is virtually constant with temperature -:ref:`Farquhar, 1980`. +:ref:`Farquhar, 1980`. Resolution of the photosynthesis theory within the FATES canopy structure. -------------------------------------------------------------------------- @@ -1753,7 +1749,7 @@ where :math:`V_{canopy}` is calculated as :math:`K_{n}` is the coefficient of nitrogen decay with canopy depth. The value of this parameter is taken from the work of -:ref:`Lloyd et al. 2010` who determined, from 204 vertical profiles +:ref:`Lloyd et al. 2010` who determined, from 204 vertical profiles of leaf traits, that the decay rate of N through canopies of tropical rainforests was a function of the :math:`V_{cmax}` at the top of the canopy. They obtain the following term to predict :math:`K_{n}`, @@ -2063,13 +2059,13 @@ Fundamental stomatal conductance theory [14]_Stomatal conductance is unchanged in concept from the CLM4.5 approach. Leaf stomatal resistance is calculated from the Ball-Berry conductance -model as described by :ref:`Collatz et al. 1991` and implemented in +model as described by :ref:`Collatz et al. (1991)` and implemented in a global climate model by :ref:`Sellers et al. 1996`. The model relates stomatal conductance (i.e., the inverse of resistance) to net leaf photosynthesis, scaled by the relative humidity at the leaf surface and the CO\ :math:`_2` concentration at the leaf surface. The primary difference between the CLM implementation and that used by -:ref:`Collatz et al. 1991` and :ref:`Sellers et al. 1996` is +:ref:`Collatz et al. (1991)` and :ref:`Sellers et al. (1996)` is that they used net photosynthesis (i.e., leaf photosynthesis minus leaf respiration) instead of gross photosynthesis. As implemented here, stomatal conductance equals the minimum conductance (:math:`b`) when @@ -2093,13 +2089,13 @@ the leaf at the vegetation temperature conductance (:math:`\mu`\ mol m\ :math:`^{-2}` s\ :math:`^{-1}`) when :math:`A` = 0 . Typical values are :math:`m_{ft}` = 9 for C\ :math:`_3` plants and :math:`m_{ft}` = 4 for C\ :math:`_4` plants ( -:ref:`Collatz et al. 1991`, :ref:`Collatz, 1992`, :ref:`Sellers et al 1996)`. +:ref:`Collatz et al. 1991`, :ref:`Collatz, 1992`, :ref:`Sellers et al 1996)`. :ref:`Sellers et al. 1996` used :math:`b` = 10000 for C\ :math:`_3` plants and :math:`b` = 40000 for C\ :math:`_4` plants. Here, :math:`b` was chosen to give a maximum stomatal resistance of 20000 s m\ :math:`^{-1}`. These terms are nevertheless plant strategy dependent, and have been found to vary widely with plant type -:ref:`Medlyn et al. 2001`. +:ref:`Medlyn et al. 2011`. Resistance is converted from units of s m\ :math:`^2 \mu` mol\ :math:`^{-1}` to s m\ :math:`^{-1}` as: 1 s m\ :math:`^{-1}` = @@ -3072,7 +3068,7 @@ model, which has been modified for use in ED following it’s original implementation in the LPJ-SPITFIRE model (:ref:`Thonicke et al. 2010, :ref:`Pfeiffer et al. 2013`). This model as described is substantially different from the existing CLM4.5 fire model -:ref:`Li et al. 2012`, however, further developments are +:ref:`Li et al. 2012`, however, further developments are intended to increase the merging of SPITFIRE’s natural vegetation fire scheme with the fire suppression, forest-clearing and peat fire estimations in the existing model. The coupling to the ED model allows diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 853385f36b..562b772c51 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -13,7 +13,7 @@ ***Contributing Authors*** -**Ben Andre, Ali Ashehad, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, +**Ashehad Ali, Ben Andre, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Ryan Knox, Jan Lenaerts, Sam Levis, L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Andrew Slater, Zachary M. Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index ba331704d0..74223d2887 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -283,6 +283,12 @@ stomatal conductance in the earth system: linking leaf water-use efficiency and water transport along the soil–plant–atmosphere continuum, Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. +.. _botta2000: + +|br| + +Botta, A et al., 2000. A global prognostic scheme of leaf onset using satellite data. Global Change Biology 6.7, pp. 709-725. + .. _Brun1989: |br| @@ -324,6 +330,12 @@ Buzan, J.R., Oleson, K., and Huber, M. 2015: Implementation and comparison of a suite of heat stress metrics within the Community Land Model version 4.5, Geosci. Model Dev., 8, 151-170, doi:10.5194/gmd-8-151-2015. +.. _byram1959: + +|br| + +Byram, G.M., 1959. Combustion of forest fuels. In Forest fire: control and use.(Ed. KP Davis) pp. 61-89. + .. _CampbellNorman1998: |br| @@ -656,17 +668,23 @@ Firestone, M.K. and Davidson, E.A. 1989. Exchange of Trace Gases between Terrestrial Ecosystems and the Atmosphere. In: M.O. Andreae and D.S. Schimel (Editors). John Wiley and Sons, pp. 7-21. +.. _Fisheretal2010: + +|br| + +Fisher, J. B., S. Sitch, Y. Malhi, R. A. Fisher, C. Huntingford, and S.-Y. Tan, 2010. Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation. Global Biogeochem. Cycles, 24, GB1014, doi:10.1029/2009GB003621. + .. _Fisheretal2015: |br| Fisher, R. A., S. Muszala, M. Verteinstein, P. Lawrence, C. Xu, N. G. McDowell, R. G. Knox, C. Koven, J. Holm, B. M. Rogers, A. Spessa, D. Lawrence, and G. Bonan, 2015: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED). Geosci. Model Dev., 8: 3593-3619, doi:10.5194/gmd-8-3593-2015. -.. _Fisheretal2010: +.. _Fisheretal2017: |br| -Fisher, J. B., S. Sitch, Y. Malhi, R. A. Fisher, C. Huntingford, and S.-Y. Tan, 2010. Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation. Global Biogeochem. Cycles, 24, GB1014, doi:10.1029/2009GB003621. +Fisher, R.A., C.D. Koven, W.R.L. Anderegg, et al., 2018: Vegetation demographics in Earth System Models: A review of progress and priorities. Glob Change Biol. 2018;24:35–54. https://doi.org/10.1111/gcb.13910 .. _FlannerZender2005: @@ -698,6 +716,12 @@ Geophys. Res. 112:D11202. DOI:10.1029/2006JD008003. Flatau, P.J., Walko, R.L., and Cotton, W.R. 1992. Polynomial fits to saturation vapor pressure. J. Appl. Meteor. 31:1507-1513. +.. _foley1996: + +|br| + +Foley, J.A. et al., 1996. An integrated biosphere model of land surface processes, terrestrial carbon balance, and vegetation dynamics. Global Biogeochemical Cycles 10.4, pp. 603-628. + .. _Friedl,etal2002: |br| @@ -715,6 +739,12 @@ from MODIS: algorithms and early results. Remote Sens. Environ. Frolking, S., et al. 2001. Modeling Northern Peatland Decomposition and Peat Accumulation. Ecosystems. 4:479-498. +.. _fyllas2014: + +|br| + +Fyllas, N.M. et al., 2014. Analysing Amazonian forest productivity using a new individual and trait- based model (TFS v. 1). Geoscientific Model Development 7.4, pp. 1251-1269. + .. _Gallaisetal2006: |br| @@ -842,7 +872,7 @@ studies. Water Resour. Res. 35:583-587. |br| -Graven, H., C. E. Allison, D. M. Etheridge, S. Hammer, R. F. Keeling, I. Levin, H. A. J. Meijer, M. Rubino, P. P. Tans, C. M. Trudinger, B. H. Vaughn and J. W. C. White (2017) Compiled records of carbon isotopes in atmospheric CO2 for historical simulations in CMIP6, Geoscientific Model Development, in review. doi: 10.5194/gmd-2017-166. +Graven, H., C. E. Allison, D. M. Etheridge, S. Hammer, R. F. Keeling, I. Levin, H. A. J. Meijer, M. Rubino, P. P. Tans, C. M. Trudinger, B. H. Vaughn and J. W. C. White, 2017. Compiled records of carbon isotopes in atmospheric CO2 for historical simulations in CMIP6, Geoscientific Model Development, in review. doi: 10.5194/gmd-2017-166. .. _GrenfellWarren1999: @@ -1232,6 +1262,12 @@ nitrogen dynamics. Proceedings of the National Academies of Science, Koven, C.D., G. Hugelius, D.M. Lawrence, and W.R. Wieder, 2017: Higher climatological temperature sensitivity of soil carbon in cold than warm climates. Nature Clim. Change, 7, doi:10.1038/nclimate3421. +.. _kucharik1998: + +|br| + +Kucharik, C.J., J.M. Norman, and S.T. Gower, 1998. Measurements of branch area and adjusting leaf area index indirect measurements. Agricultural and Forest Meteorology 91.1, pp. 69-88. + .. _Kuchariketal2000: |br| @@ -1531,6 +1567,12 @@ Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A simple hydrologically based model of land surface water and energy fluxes for GSMs. J. Geophys. Res. 99(D7):14,415–14,428. +.. _lichstein2011: + +|br| + +Lichstein, J.W. and S.W. Pacala, 2011. Local diversity in heterogeneous landscapes: quantitative assessment with a height-structured forest metacommunity model`. Theoretical Ecology 4.2, pp. 269-281. + .. _LipscombSacks2012: |br| @@ -1539,6 +1581,13 @@ Lipscomb, W., and Sacks, W. 2012. The CESM land ice model documentation and user’s guide. 46 pp. [Available online at http://www.cesm.ucar.edu/models/cesm1.1/cism/]. +.. _lischke2006: + +|br| + +Lischke, H. et al., 2006. TreeMig: a forest-landscape model for simulating spatio-temporal patterns from stand to landscape scale. Ecological Modelling 199.4, pp. 409-420. 41 + + .. _LloydTaylor1994: |br| @@ -1652,6 +1701,12 @@ Mary, B., Fresneau, C., Morel, J.L. and Mariotti, A., 1993. C and N cycling during decomposition of root mucilage, roots and glucose in soil. Soil Biology and Biochemistry 25:1005-1014. +.. _mcdowell2013: + +|br| + +McDowell, N.G. et al., 2013. Evaluating theories of drought-induced vegetation mortality using a multimodel experiment framework. New Phytologist 200.2, pp. 304-321. + .. _McGuireetal1992: |br| @@ -1668,7 +1723,7 @@ potential vegetation in North America. Global Biogeochem. Cycles Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., Barton, C.V.M., Crous, K.Y., De Angelis, P., Freeman, M., and -Wingate, L. (2011), Reconciling the optimal and empirical approaches to +Wingate, L., 2011. Reconciling the optimal and empirical approaches to modelling stomatal conductance. Global Change Biology, 17: 2134–2144. doi:10.1111/j.1365-2486.2010.02375.x @@ -1717,6 +1772,12 @@ Moldrup, P. et al. 2003. Modeling diffusion and reaction in soils: X. A unifying model for solute and gas diffusivity in unsaturated soil. Soil Science 168:321-337. +.. _mc_2001: + +|br| + +Moorcroft, P.R., G.C. Hurtt, and S.W. Pacala, 2001. A method for scaling vegetation dynamics: the ecosystem demography model ED. Ecological monographs 71.4, pp. 557-586. + .. _Mynenietal2002: |br| @@ -1792,6 +1853,12 @@ Niu, G.-Y., and Yang, Z.-L. 2007. An observation-based formulation of snow cover fraction and its evaluation over large North American river basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674. +.. _norman1979: + +|br| + +Norman, J.M., 1979. Modeling the complete crop canopy. Modification of the Aerial Environment of Crops, pp. 249-280. + .. _Oikawaetal2005: |br| @@ -1980,6 +2047,12 @@ New York, 480 pp. Pelletier, J. D., P. D. Broxton, P. Hazenberg, X. Zeng, P. A. Troch, G. Y. Niu, Z. Williams, M. A. Brunke, and D. Gochis, 2016: A gridded global data set of soil, intact regolith, and sedimentary deposit thicknesses for regional and global land surface modeling. J. Adv. Mod. Earth Sys. 8:41-65. +.. _peterson1986: + +|br| + +Peterson, D.L. and K.C. Ryan, 1986. Modeling postfire conifer mortality for long-range planning. Environmental Management 10.6, pp. 797-808. + .. _Petrescuetal2010: |br| @@ -1987,6 +2060,12 @@ Pelletier, J. D., P. D. Broxton, P. Hazenberg, X. Zeng, P. A. Troch, G. Y. Niu, Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions of boreal and arctic wetlands. Global Biogeochemical Cycles, 24(GB4009). +.. _pfeiffer2013: + +|br| + +Pfeiffer, M., A. Spessa, and J.O. Kaplan, 2013. A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0). Geoscientific Model Development 6.3, pp. 643-685. + .. _Philip1957: |br| @@ -2058,13 +2137,11 @@ ice-atmosphere interactions underestimates ice sheet melt in millennial-scale deglaciation simulations. Geophys. Res. Lett. ** 35:L01503. DOI:10.1029/2007GL031738. -.. _Qianetal2006: +.. _purves2008: |br| -Qian, T., Dai, A., Trenberth, K.E., and Oleson, K.W. 2006. Simulation of -global land surface conditions from 1948 to 2004: Part I: Forcing data -and evaluations. J. Hydrometeor. 7:953-975. +Purves, D.W. et al., 2008. Predicting and understanding forest dynamics using a simple tractable model. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. .. _RamankuttyFoley1998: @@ -2199,11 +2276,21 @@ Saggar, S., Tate, K.R., Feltham, C.W., Childs, C.W. and Parshotam, A., :math:`{}^{14}`\ C-labelled glucose. Soil Biology and Biochemistry, 26: 1263-1271. +.. _Sakaguchietal2009: + +|br| + Sakaguchi, K., and Zeng, X. 2009. Effects of soil wetness, plant litter, and under-canopy atmospheric stability on ground evaporation in the Community Land Model (CLM3.5). J. Geophys. Res. 114:D01107. DOI:10.1029/2008JD010834. +.. _sato2007: + +|br| + +Sato, H., A. Itoh, and T. Kohyama, 2007. SEIB-DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach. Ecological Modelling 200.3, pp. 2793307. + .. _Schaafetal2002: |br| @@ -2285,6 +2372,12 @@ Dazlich, D.A., Zhang, C., Collelo, G.D., and Bounoua, L. 1996. A revised land surface parameterization (SiB2) for atmospheric GCMs. Part I: Model formulation. J. Climate 9:676-705. +.. _sellers1996: + +|br| + +Sellers, Piers J et al. (1996). A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data. Journal of climate 9.4, pp. 706-737. + .. _Shietal2013: |br| @@ -2331,6 +2424,12 @@ Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen redistribution during grain growth in wheat (Triticum avestivum L.). Plant Physiol. 71:7-14. +.. _sitch2003: + +|br| + +Sitch, S et al. (2003). Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model. Global Change Biology 9.2, pp. 161-185. + .. _Sivak2013: |br| @@ -2339,6 +2438,12 @@ Sivak, M. 2013. Air conditioning versus heating: climate control is more energy demanding in Minneapolis than in Miami. Environ. Res. Lett., 8, doi:10.1088/1748-9326/8/1/014050. +.. _smith2001: + +|br| + +Smith, B., I.C. Prentice, and M.T. Sykes, 2001. Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space. Global Ecology and Biogeography 10.6, pp. 621-637. + .. _Smithetal2005: |br| @@ -2348,6 +2453,12 @@ G.L.W., 2005. Fire in African savanna: Testing the impact of incomplete combustion on pyrogenic emissions estimates. Ecological Applications, 15: 1074-1082. +.. _smith2007: + +|br| + +Smith, A.M. and M. Stitt, 2007. Coordination of carbon supply and plant growth. Plant, cell & environment 30.9, pp. 1126-1149. + .. _Sollins1982: |br| @@ -2550,6 +2661,13 @@ fire disturbance for global vegetation dynamics: coupling fire into a Dynamic Global Vegetation Model. Global Ecology and Biogeography 10:661-667. +.. _thonicke2010: + +|br| + +Thonicke, K. et al., 2010. The influence of vegetation, fire spread and fire behaviour on biomass burning and trace gas emissions: results from a process-based model. Biogeosciences 7.6, pp. 1991-2011. + + .. _Thornton1998: |br| @@ -2662,6 +2780,12 @@ site. Agric. For. Meteor. 82:119-153. UNSTAT, 2005. National Accounts Main Aggregates Database, United Nations Statistics Division. +.. _uriarte2009: + +|br| + +Uriarte, M. et al., 2009. Natural disturbance and human land use as determinants of tropical forest dynamics: results from a forest simulator. Ecological Monographs 79.3, pp. 423-443. + .. _VallanoSparks2007: |br| @@ -2724,6 +2848,12 @@ Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: effects of size, competition and site fertility on growth allocation and production. Tree Phys. 25:17-30. +.. _venevsky2002: + +|br| + +Venevsky, S. et al., 2002. Simulating fire regimes in human-dominated ecosystems: Iberian Peninsula case study. Global Change Biology 8.10, pp. 984-998. + .. _VerdinGreenlee1996: |br| @@ -2784,6 +2914,12 @@ Wang, A., and Zeng, X. 2009. Improving the treatment of vertical snow burial fraction over short vegetation in the NCAR CLM3. Adv. Atmos. Sci. 26:877-886. DOI:10.1007/s00376-009-8098-3. +.. _weng2014: + +|br| + +Weng, E.S. et al., 2014. Scaling from individuals to ecosystems in an Earth System Model using a mathematically tractable model of height-structured competition for light. Biogeosciences Discussions 11.12, pp. 17757-17860. + .. _Whiteetal1997: |br| @@ -2857,10 +2993,16 @@ Water Resour. Res., 47, W03517, doi:10.1029/2009WR008871. |br| -Wu, H., J. S. Kimball, H. Li, M. Huang, L. R. Leung, and R. F. Adler -(2012), A New Global River Network Database for Macroscale Hydrologic +Wu, H., J. S. Kimball, H. Li, M. Huang, L. R. Leung, and R. F. Adler, +2012. A New Global River Network Database for Macroscale Hydrologic modeling, Water Resour. Res., 48, W09701, doi:10.1029/2012WR012313. +.. _xiaodong2005: + +|br| + +Xiaodong, Y. and H.H. Shugart, 2005. FAREAST: a forest gap model to simulate dynamics and patterns of eastern Eurasian forests. Journal of Biogeography 32.9, pp. 1641-1658. + .. _Xuetal2012: |br| @@ -2966,195 +3108,3 @@ Global Biogeochemical Cycles 18. DOI:10.1029/2004GB002239. Zilitinkevich, S.S. 1970. Dynamics of the Atmospheric Boundary Layer. Leningrad Gidrometeor. -.. _bonan2012: - -|br| - -Bonan, Gordon B et al. (2012). `Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4`. Journal of Geophysical Research: Biogeosciences (2005-2012) 117.G2. - -.. _botta2000: - -|br| - -Botta, A et al. (2000). `A global prognostic scheme of leaf onset using satellite data`. Global Change Biology 6.7, pp. 709-725. - -.. _byram1959: - -|br| - -Byram, GM (1959). Combustion of forest fuels. In Forest fire: control and use.(Ed. KP Davis) pp. 61-89. - -.. _collatz1991: - -|br| - -Collatz, G James 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 54.2, pp. 107-136. - -.. _collatz1992: - -|br| - -Collatz, Go J, M Ribas-Carbo, and JA Berry (1992). `Coupled photosynthesis-stomatal conductance model for leaves of C4 plants`. Functional Plant Biology 19.5, pp. 519-538.
 - -.. _farquhar1980: - -|br| - -Farquhar, GD, S von von Caemmerer, and JA Berry (1980). `A biochemical model of photosynthetic CO2 assimilation in leaves of C3 species`. Planta 149.1, pp. 780-90. - -.. _fisher2010: - -|br| - -Fisher, JB et al. (2010). `Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation`. Global Biogeochemical Cycles 24.1. - -.. _foley1996: - -|br| - -Foley, Jonathan A et al. (1996). `An integrated biosphere model of land surface processes, terrestrial carbon balance, and vegetation dynamics`. Global Biogeochemical Cycles 10.4, pp. 603-628. - -.. _fyllas2014: - -|br| - -Fyllas, NM et al. (2014). `Analysing Amazonian forest productivity using a new individual and trait- based model (TFS v. 1)`. Geoscientific Model Development 7.4, pp. 1251-1269. - -.. _kucharik1998: - -|br| - -Kucharik, Christopher J, John M Norman, and Stith T Gower (1998). `Measurements of branch area and adjusting leaf area index indirect measurements`. Agricultural and Forest Meteorology 91.1, pp. 69-88. - -.. _li2012: - -|br| - -Li, F, XD Zeng, and S Levis (2012). `A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model`. Biogeosciences 9.7, pp. 2761-2780. - -.. _lichstein2011: - -|br| - -Lichstein, Jeremy W and Stephen W Pacala (2011). `Local diversity in heterogeneous landscapes: quantitative assessment with a height-structured forest metacommunity model`. Theoretical Ecology 4.2, pp. 269-281. - -.. _lischke2006: - -|br| - -Lischke, Heike et al. (2006). `TreeMig: a forest-landscape model for simulating spatio-temporal patterns from stand to landscape scale`. Ecological Modelling 199.4, pp. 409-420. 41 - -.. _lloyd2010: - -|br| - -Lloyd, J et al. (2010). `Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees`. Biogeosciences 7.6, pp. 1833-1859. - -.. _mcdowell2013: - -|br| - -McDowell, Nate G et al. (2013). `Evaluating theories of drought-induced vegetation mortality using a multimodel experiment framework`. New Phytologist 200.2, pp. 304-321. - -.. _medlyn2011: - -|br| - -Medlyn, Belinda E et al. (2011). `Reconciling the optimal and empirical approaches to modelling stom- atal conductance`. Global Change Biology 17.6, pp. 2134-2144. - - -.. _mc_2001: - -|br| - -Moorcroft, PR, GC Hurtt, and Stephen W Pacala (2001). `A method for scaling vegetation dynamics: the ecosystem demography model ED`. Ecological monographs 71.4, pp. 557-586. - -.. _norman1979: - -|br| - -Norman, JM (1979). `Modeling the complete crop canopy`. Modification of the Aerial Environment of Crops, pp. 249-280. - -.. _oleson2013: - -|br| - -Oleson, KW et al. (2013). `Technical description of version 4.5 of the Community Land Model (CLM)`. - -.. _peterson1986: - -|br| - -Peterson, David L and Kevin C Ryan (1986). `Modeling postfire conifer mortality for long-range planning`. Environmental Management 10.6, pp. 797-808. - -.. _pfeiffer2013: - -|br| - -Pfeiffer, M, A Spessa, and JO Kaplan (2013). `A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0)`. Geoscientific Model Development 6.3, pp. 643-685. - -.. _purves2008: - -|br| - -Purves, Drew W et al. (2008). `Predicting and understanding forest dynamics using a simple tractable model`. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. - -.. _sato2007: - -|br| - -Sato, Hisashi, Akihiko Itoh, and Takashi Kohyama (2007). `SEIB–DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach`. Ecological Modelling 200.3, pp. 2793307. - -.. _sellers1996: - -|br| - -Sellers, Piers J et al. (1996). `A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data`. Journal of climate 9.4, pp. 706-737. - -.. _sitch2003: - -|br| - -Sitch, S et al. (2003). `Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model`. Global Change Biology 9.2, pp. 161-185. - -.. _smith2007: - -|br| - -Smith, Alison M and Mark Stitt (2007). `Coordination of carbon supply and plant growth`. Plant, cell & environment 30.9, pp. 1126-1149. - -.. _smith2001: - -|br| - -Smith, Benjamin, I Colin Prentice, and Martin T Sykes (2001). `Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space`. Global Ecology and Biogeography 10.6, pp. 621-637. - -.. _thonicke2010: - -|br| - -Thonicke, K et al. (2010). `The influence of vegetation, fire spread and fire behaviour on biomass burning and trace gas emissions: results from a process-based model`. Biogeosciences 7.6, pp. 1991-2011. - -.. _uriarte2009: - -|br| - -Uriarte, Maria et al. (2009). `Natural disturbance and human land use as determinants of tropical forest dynamics: results from a forest simulator`. Ecological Monographs 79.3, pp. 423-443. - -.. _venevsky2002: - -|br| - -Venevsky, Sergey et al. (2002). `Simulating fire regimes in human-dominated ecosystems: Iberian Peninsula case study`. Global Change Biology 8.10, pp. 984-998. - -.. _weng2014: - -|br| - -Weng, ES et al. (2014). `Scaling from individuals to ecosystems in an Earth System Model using a mathematically tractable model of height-structured competition for light`. Biogeosciences Discussions 11.12, pp. 17757-17860. - -.. _xiaodong2005: - -|br| - -Xiaodong, Yan and HH Shugart (2005). `FAREAST: a forest gap model to simulate dynamics and patterns of eastern Eurasian forests`. Journal of Biogeography 32.9, pp. 1641-1658. From 180ed91cf10893e222a4858e0a0e0f340651a288 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 1 Feb 2018 13:59:54 -0700 Subject: [PATCH 138/255] Rewrite portions of the SMB section --- .../Glacier/CLM50_Tech_Note_Glacier.rst | 115 +++++++++++------- 1 file changed, 73 insertions(+), 42 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index e125a1141e..a7f2100478 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -61,9 +61,9 @@ CISM: (e.g., in the Alps, Rockies, Andes, and Himalayas), not just those which are part of ice sheets. -In typical runs, CLM computes the SMB and sends it to CISM, but CISM's -ice sheet geometry remains fixed over the course of the run. In these -runs, CISM serves two roles in the system: +In typical runs, CISM is not evolving; CLM computes the SMB and sends it +to CISM, but CISM's ice sheet geometry remains fixed over the course of +the run. In these runs, CISM serves two roles in the system: #. Over the CISM domain (typically Greenland in CESM2), CISM dictates glacier areas and topographic elevations, overriding the values on @@ -258,6 +258,14 @@ the melting depends on the sum of the radiative, turbulent, and conductive fluxes reaching the surface, as described elsewhere in this document. +Note that the SMB typically is defined as the total accumulation of ice +and snow, minus the total ablation. The SMB flux passed to CISM is the +mass balance for ice alone, not snow. We can think of CLM as owning the +snow, whereas CISM owns the underlying ice. Fluctuations in snow depth +between 0 and 10 m water equivalent are not reflected in the SMB passed +to CISM. In transient runs, this can lead to delays of a few decades in +the onset of accumulation or ablation in a given glacier column. + SMB is computed and sent to the CESM coupler regardless of whether and where CISM is operating. However, the effect of SMB terms on runoff fluxes differs depending on whether and where CISM is evolving in @@ -266,45 +274,68 @@ two-way-coupled mode. This is described by the variable the edge case where a CLM grid cell partially overlaps with the CISM grid, but we describe it as a logical variable here for simplicity.) In typical cases where CISM is not evolving, *glc\_dyn\_runoff\_routing* -will be false everywhere. In cases where CISM is evolving and sending -its own calving flux to the coupler, *glc\_dyn\_runoff\_routing* will be -true over the CISM domain and false elsewhere. - -FIXME: Rewrite the following paragraph - -FIXME: Make sure I talk about the positive liquid runoff and negative -ice runoff that result from melted ice. - -FIXME: With interactive CISM, snow capping is applied to the surface -mass balance, not ice runoff. - -In the modified glacier\_mec columns, the treatment of melting and -freezing depends on the logical variable *glc\_dyntopo*. This variable -controls whether CLM surface topography changes dynamically as the ice -sheet evolves (i.e., whether the coupling is one-way or two-way). If -*glc\_dyntopo* is true, then CLM receives updated topographic -information from the ice sheet model. In this case, snow in excess of -the prescribed maximum depth is assumed to turn into ice, contributing a -positive SMB to the ice sheet model. Melting ice is assumed to run off -to the ocean, giving a negative SMB. The net SMB associated with ice -formation (by conversion from snow) and melting/runoff is computed for -each column, averaged over the coupling interval, and sent to the -coupler (*qice, mm/s*). If *glc\_dyntopo* is false, then surface runoff -for glacier\_mec land units is computed as for glacier land units: Any -snow in excess of 1 m LWE runs off to the ocean, and Melted ice remains -in place until it refreezes. Excess snow and melted ice still contribute -to positive and negative values, respectively, of *qice*, but only for -the purpose of forcing CISM. Currently, *glc\_dyntopo* = false -is the default, and the only supported option. - -Note that the SMB typically is defined as the total accumulation of ice -and snow, minus the total ablation. The *qice* flux passed to CISM is -the mass balance for ice alone, not snow. We can think of CLM as owning -the snow, whereas CISM owns the underlying ice. Fluctuations in snow -depth between 0 and 10 m water equivalent are not reflected in the SMB -passed to CISM. In transient runs, this can lead to delays of a few -decades in the onset of accumulation or ablation in a given glacier -column. +will be false everywhere; in these cases, CISM's mass is not considered +to be part of the coupled system. In cases where CISM is evolving and +sending its own calving flux to the coupler, *glc\_dyn\_runoff\_routing* +will be true over the CISM domain and false elsewhere. + +Any snow capping (section :numref:`Runoff from glaciers and snow-capped +surfaces`) is added to :math:`q_{ice,frz}`. Any liquid water (i.e., +melted ice) below the snow pack in the glacier column is added to +:math:`q_{ice,melt}`, then is converted back to ice to maintain a +pure-ice column. Then the total SMB is given by :math:`q_{ice,tot}`: + +.. math:: + :label: 13.1 + + q_{ice,tot} = q_{ice,frz} - q_{ice,melt} + +CLM is responsible for generating glacial surface melt, even when +running with an evolving ice sheet. Thus, :math:`q_{ice,melt}` is always +added to liquid runoff (:math:`q_{rgwl}`), regardless of +*glc\_dyn\_runoff\_routing*. However, the ice runoff flux depends on +*glc\_dyn\_runoff\_routing*. If *glc\_dyn\_runoff\_routing* is true, +then CISM controls the fate of the snow capping mass in +:math:`q_{ice,frz}` (e.g., eventually transporting it to lower +elevations where it can be melted or calved). Since CISM will now own +this mass, the snow capping flux does *not* contribute to any runoff +fluxes generated by CLM. + +If *glc\_dyn\_runoff\_routing* is false, then CLM sends the snow capping +flux as runoff, as a crude representation of ice calving (see also +sections :numref:`Runoff from glaciers and snow-capped surfaces` and +:numref:`Glacier regions`). However, this ice runoff flux is reduced by +:math:`q_{ice,melt}`. This reduction is needed for conservation; its +need is subtle, but can be understood with either of these explanations: + +- When ice melts, we let the liquid run off and replace it with new + ice. That new ice needs to come from somewhere to keep the coupled + system in water balance. We "request" the new ice from the ocean by + generating a negative ice runoff equivalent to the amount we have + melted. + +- Ice melt removes mass from the system, as it should. But the snow + capping flux also removes mass from the system. The latter is a crude + parameterization of calving, assuming steady state - i.e., all ice + gain is balanced by ice loss. This removal of mass due to both + accumulation and melt represents a double-counting. Each unit of melt + indicates that one unit of accumulation should not have made it to the + ocean as ice, but instead melted before it got there. So we need to + correct for this double-counting by removing one unit of ice runoff + for each unit of melt. + +For a given point in space or time, this reduction can result in +negative ice runoff. However, when integrated over time and space, for +an ice sheet that is near equilibrium, this just serves to decrease the +too-high positive ice runoff from snow capping. (This near-equilibrium +assumption is a key point in the treatment of snow capping with +*glc\_dyn\_runoff\_routing* false. For glaciers and ice sheets that +violate this assumption, either because they are far out of equilibrium +with the climate or because the model is being run for hundreds of +years, there are two ways to avoid the unrealistic ice runoff from snow +capping: by running with an evolving, two-way-coupled ice sheet or by +changing a glacier region's ice runoff behavior as described in section +:numref:`Glacier regions`.) In regions where SMB is computed for glaciers, SMB is also computed for the natural vegetated land unit. Because there is no ice to melt in this From 1d062cbc0616a9c13776d01d9c572a9baec17972 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 1 Feb 2018 15:40:50 -0700 Subject: [PATCH 139/255] fix formatting of mosart page --- doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index b844b4a433..eabdb50763 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -228,14 +228,17 @@ Difference between CLM5.0 and CLM4.5 1. Routing methods: RTM, a linear reservoir method, is used in CLM4.5 for river routing, whilst in CLM5.0, MOSART is an added option for river routing -based on the more physically-based kinematic wave method. +based on the more physically-based kinematic wave method. + 2. Runoff treatment: In RTM runoff is routed regardless of its sign so negative streamflow can be simulated at times. MOSART routes only nonnegative runoff and always produces positive streamflow, which is important for future extension for modeling riverine heat and biogeochemical fluxes. + 3. Input parameters: RTM in CLM4.5 only requires one layer of spatial variable of channel velocity, whilst MOSART in CLM5.0 requires 13 parameters that -are all available globally at 0.5 :sup:`o` resolution. +are all available globally at 0.5 :sup:`o` resolution. + 4. Outputs: RTM only produces streamflow simulation, whilst MOSART additionally simulates the time-varying channel velocities and channel water depth and channel surface water variation. From e2edd92eddb2b8a74729479c5d0b01d674a5baae Mon Sep 17 00:00:00 2001 From: Katie Dagon Date: Thu, 1 Feb 2018 16:30:49 -0700 Subject: [PATCH 140/255] Fixed some typos and errors --- .../Fluxes/CLM50_Tech_Note_Fluxes.rst | 4 +- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 2 +- .../CLM50_Tech_Note_Introduction.rst | 2 +- .../CLM50_Tech_Note_Photosynthesis.rst | 2 +- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 38 +++++++-------- .../CLM50_Tech_Note_Plant_Hydraulics.rst | 48 +++++++++---------- .../CLM50_Tech_Note_Plant_Mortality.rst | 8 ++-- doc/source/tech_note/index.rst | 1 + 8 files changed, 53 insertions(+), 52 deletions(-) diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 95214580b4..fdd6873346 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1236,7 +1236,7 @@ The leaf boundary layer resistance :math:`r_{b}` is where :math:`C_{v} =0.01` m\ s\ :sup:`-1/2` is the turbulent transfer coefficient between the canopy surface and canopy air, and :math:`d_{leaf}` is the characteristic dimension of the leaves in the -direction of wind flow (:numref:`Table Coefficients for saturation vapor pressure`). +direction of wind flow (:numref:`Table Plant functional type aerodynamic parameters`). The partial derivatives of the fluxes from the soil beneath the canopy with respect to ground temperature, which are needed for the soil @@ -1279,7 +1279,7 @@ adjusted for canopy density following :ref:`Zeng and Wang (2007) ` d = z_{top} R_{d} V where :math:`z_{top}` is canopy top height (m) -(:numref:`Table Prescribed plant functional type heights`), +(:numref:`Table Plant functional type canopy top and bottom heights`), :math:`R_{z0m}` and :math:`R_{d}` are the ratio of momentum roughness length and displacement height to canopy top height, respectively (:numref:`Table Plant functional type aerodynamic parameters`), and :math:`z_{0m,\, g}` diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index fb0dff13ab..b1153c3a5d 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -137,7 +137,7 @@ They are defined by .. math:: :label: 7.11 - W_{can,\,sno}^{max } =p_{ice}\left(L+S\right). + W_{can,\,sno}^{max } =p_{sno}\left(L+S\right). The maximum storage of liquid water is :math:`p_{liq}=0.1` kg m\ :sup:`-2` (:ref:`Dickinson et al. 1993 `), and that of snow diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 562b772c51..0993904323 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -31,7 +31,7 @@ P. O. Box 3000, Boulder, Colorado 80307-300 **LIST OF FIGURES** -- :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from Lawrence et al. (2011) for CLM5.0). +- :numref:`Figure Land processes` Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM5.0). - :numref:`Figure CLM subgrid hierarchy` Configuration of the CLM subgrid hierarchy. diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index 8dad4faf3e..258fa3f182 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -89,7 +89,7 @@ atmospheric potential temperature (K). .. table:: Plant functional type (PFT) stomatal conductance parameters. +----------------------------------+-------------------+ - | PFT | g\ :sub:`1` (Pa) | + | PFT | g\ :sub:`1` | +==================================+===================+ | NET Temperate | 2.35 | +----------------------------------+-------------------+ diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index 0c99101fa0..c47ce0e624 100755 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -6,7 +6,7 @@ Photosynthetic Capacity The photosynthetic capacity is represented by two key parameters: 1) the maximum rate of carboxylation at 25 :sup:`o`\ C, :math:`V_{\text{c,max25}}`; and 2) the maximum rate of electron transport at 25 :sup:`o`\ C, :math:`J_{\text{max25}}` . They are predicted by a mechanistic model of leaf -utilization of nitrogen for assimilation (LUNA V1.0) (Ali et al. 2016) based on an optimality hypothesis to nitrogen allocation +utilization of nitrogen for assimilation (LUNA V1.0) (:ref:`Ali et al. 2016`) based on an optimality hypothesis to nitrogen allocation among light capture, electron transport, carboxylation, respiration and storage. Specifically, the model allocates the nitrogen by maximizing the daily net photosynthetic carbon gain under following two key assumptions: @@ -30,7 +30,7 @@ The LUNA model includes the following four unitless parameters: - :math:`H` , which determines the response of electron transport rate to relative humidity. The above four parameters are estimated by fitting the LUNA model to a global compilation of >800 obervations -located at different biomes, canopy locations, and time of the year from 1993-2013 (Ali et al 2015). The model inputs +located at different biomes, canopy locations, and time of the year from 1993-2013 (Ali et al. 2015). The model inputs are area-based leaf nitrogen content, leaf mass per unit leaf area and the driving environmental conditions (average of past 10 days) including temperature, CO :sub:`2` concentrations, daily mean and maximum radiation, relative humidity and day length. The estimated values in CLM5 for the listed parameters are 0.0311, 0.1745, 0.8054, and 6.0999, repectively. In LUNA V1.0, the estimated @@ -51,9 +51,9 @@ Model structure Plant Nitrogen '''''''''''''''''''''''''' -The structure of the LUNA model is adapted from Xu et al.(2012), where the plant nitrogen at the leaf level ( :math:`\text{LNC}_{a}`; gN/ m :sup:`2` leaf) is divided into +The structure of the LUNA model is adapted from :ref:`Xu et al. (2012)`, where the plant nitrogen at the leaf level ( :math:`\text{LNC}_{a}`; gN/ m :sup:`2` leaf) is divided into four pools: structural nitrogen( :math:`N_{\text{str}}`; gN/m :sup:`2` leaf), -photosynthetic nitrogen ( :math:`N_{\text{psn}}`; gN/ m:sup:`2` leaf), +photosynthetic nitrogen ( :math:`N_{\text{psn}}`; gN/m :sup:`2` leaf), storage nitrogen( :math:`N_{\text{store}}`; gN/m :sup:`2` leaf), and respiratory nitrogen ( :math:`N_{\text{resp}}`; gN/m :sup:`2` leaf). Namely, @@ -75,14 +75,14 @@ Namely, N_{\text{psn}} =N_{\text{et}} + N_{\text{cb}} + N_{\text{lc}}. The structural nitrogen, :math:`N_{\text{str}}`, is calculated as the -multiplication of leaf mass per unit area (LMA: g biomass/m :sup:`2` leaf), and the structural nitrogen content (SNC; gN/g biomass). Namely, +multiplication of leaf mass per unit area (:math:`\text{LMA}`; g biomass/m :sup:`2` leaf), and the structural nitrogen content (:math:`\text{SNC}`; gN/g biomass). Namely, .. math:: :label: 10.3) N_{\text{str}} = \text{SNC} \cdot \text{LMA} -where SNC is set to be fixed at 0.002 (gN/g biomass), based on data on C:N ratio from dead wood (White etal.,2000). +where :math:`\text{SNC}` is set to be fixed at 0.002 (gN/g biomass), based on data on C:N ratio from dead wood (White etal.,2000). We assume that plants optimize their nitrogen allocations (i.e., :math:`N_{\text{store}}`, :math:`N_{\text{resp}}`, :math:`N_{\text{lc}}`, :math:`N_{\text{et}}`, :math:`N_{\text{cb}}`) to maximize the photosynthetic carbon gain, defined as the gross photosynthesis ( :math:`A` ) minus the maintenance respiration for @@ -99,18 +99,18 @@ use. Namely, the solutions of nitrogen allocations \{ :math:`N_{\text{store}}`, where :math:`\text{FNC}_{a}` is the functional nitrogen content defined as the total leaf nitrogen content ( :math:`\text{LNC}_{a}`) minus the structural nitrogen content ( :math:`N_{\text{str}}` ). -The gross photosynthesis, :math:`A`, was calculated with a coupled leaf gas exchange model based on the Farquhar et al. (1980) model of -photosynthesis and Ball--Berry-type stomatal conductance model (Ball et al., 1987). The maintenance respiration for photosynthetic enzymes, :math:`R_{\text{psn}}`, is +The gross photosynthesis, :math:`A`, was calculated with a coupled leaf gas exchange model based on the :ref:`Farquhar et al. (1980)` model of +photosynthesis and Ball--Berry-type stomatal conductance model (Ball et al. 1987). The maintenance respiration for photosynthetic enzymes, :math:`R_{\text{psn}}`, is calculated by the multiplication of total photosynthetic nitrogen ( :math:`N_{\text{psn}}` ) and the maintenance respiration cost for photosynthetic enzymes. Maximum electron transport rate ''''''''''''''''''''''''''''''''' In the LUNA model, the maximum electron transport rate -( :math:`J_{\text{max}}`; :math:`{\mu} mol` electron / m :sup:`-2`/s) +( :math:`J_{\text{max}}`; :math:`{\mu} mol` electron / m :sup:`2`/s) is simulated to have a baseline allocation of nitrogen and additional nitrogen allocation to change depending on the average daytime -photosynthetic active radiation (PAR; :math:`{\mu} mol` electron / m :sup:`-2`/s), day length (hours) and air humidity. +photosynthetic active radiation (PAR; :math:`{\mu} mol` electron / m :sup:`2`/s), day length (hours) and air humidity. Specifically, the LUNA model has .. math:: @@ -134,7 +134,7 @@ is the nitrogen use efficiency of :math:`J_{\text{{max}}}`. :math:`J_{\text{max} transport rate to amount of absorbed light (i.e., :math:`\alpha \text{PAR}`). :math:`f\left(\text{day length} \right)` is a function specifies the impact of day length (hours) on :math:`J_{\text{max}}` in view that longer day length has been demonstrated by previous studies to alter :math:`V_{\mathrm{c}\text{max}25}` and -:math:`J_{\text{max}25}` (Bauerle et al., 2012; Comstock and Ehleringer, 1986) through photoperiod sensing and regulation (e.g. Song et al., 2013). +:math:`J_{\text{max}25}` (Bauerle et al. 2012; Comstock and Ehleringer 1986) through photoperiod sensing and regulation (e.g., Song et al. 2013). Following Bauerle et al. (2012), :math:`f\left(\text{day length} \right)` is simulated as follows, .. math:: @@ -193,7 +193,7 @@ Maximum rate of carboxylation The maximum rate of carboxylation at 25 :sup:`o`\ C varies with foliage nitrogen concentration and specific leaf area and is calculated -as in Thornton and Zimmermann (2007). At 25ºC, +as in :ref:`Thornton and Zimmermann (2007)`. At 25ºC, .. math:: :label: 10.11) @@ -235,7 +235,7 @@ Hemisphere). Implementation of Photosynthetic Capacity '''''''''''''''''''''''''''''''''''''''''' -Based on Farquhar et al. (1980) and Wullschleger (1993), we can calculate the +Based on :ref:`Farquhar et al. (1980)` and Wullschleger (1993), we can calculate the electron-limited photosynthetic rate under daily maximum radiation ( :math:`W_{jx}`) and the Rubisco-limited photosynthetic rate ( :math:`W_{\mathrm{c}}`) as follows, @@ -254,7 +254,7 @@ and the Rubisco-limited photosynthetic rate ( :math:`W_{\mathrm{c}}`) as follows where :math:`K_{j}` and :math:`K_{\mathrm{c}}` as the conversion factors for :math:`J_{x}` and :math:`V_{{\mathrm{c}, \text{max}}}` ( :math:`V_{{\mathrm{c}, \text{max}}}` to :math:`W_{\mathrm{c}}` and :math:`J_{x}` to :math:`W_{J_{x}}`), respectively. Based on -Xu et al. (2012), Maire et al. (2012) and Walker et al. (2014), we +:ref:`Xu et al. (2012)`, Maire et al. (2012) and Walker et al. (2014), we assume that :math:`W_{\mathrm{c}}` is proportional to :math:`W_{J_{x}}`. Specifically, we have @@ -266,14 +266,14 @@ assume that :math:`W_{\mathrm{c}}` is proportional to where :math:`t_{\mathrm{c}, j0}` is the baseline ratio of :math:`W_{\mathrm{c}}` to :math:`W_{J_{x}}`. We recognize that this ratio may change depending on the -nitrogen use efficiency of carboxylation and electron transport (Ainsworth and Rogers, 2007), +nitrogen use efficiency of carboxylation and electron transport (Ainsworth and Rogers 2007), therefore the LUNA model has the modification factor, :math:`t_{\alpha}`, to adjust baseline -the ratio depending on the nitrogen use efficiency for electron vs carboxylation (Ali et al 2016). +the ratio depending on the nitrogen use efficiency for electron vs carboxylation (:ref:`Ali et al. 2016`). Total Respiration ''''''''''''''''''' -Following Collatz et al.(1991a), the total respiration ( :math:`R_{\mathrm{t}}`) is +Following :ref:`Collatz et al. (1991)`, the total respiration ( :math:`R_{\mathrm{t}}`) is calculated in proportion to :math:`V_{\text{c,max}}`, .. math:: @@ -295,7 +295,7 @@ Accounting for the daytime and nighttime temperature, the daily respirations is where :math:`D_{\text{day}}` and :math:`D_{\text{night}}` are daytime and nighttime durations in seconds. :math:`f_{\mathrm{r}}(T_{\text{night}})` and :math:`f_{\mathrm{r}}(T_{\text{day}})` are the temperature response functions for -respiration [see Appendix B in Ali et al (2016) for details ]. +respiration (see Appendix B in :ref:`Ali et al. (2016)` for details). .. _Numerical scheme: @@ -304,7 +304,7 @@ Numerical scheme --------------------------------------------------------- The LUNA model searches for the "optimal" nitrogen allocations for maximum net photosynthetic carbon gain -by incrementally increase the nitrogen allocated for light capture (i.e., :math:`N_{\text{lc}}`) (see Ali et al 2016 for details) . +by incrementally increase the nitrogen allocated for light capture (i.e., :math:`N_{\text{lc}}`) (see :ref:`Ali et al. (2016)` for details). We assume that plants only optimize the nitrogen allocation when they can grow (i.e., GPP>0.0). If GPP become zero under stress, then the LUNA model assume a certain amount of enzyme will decay at daily rates of 0.1, in view that the half-life time for photosynthetic enzymes are short (~7 days) (Suzuki et al. 2001). diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index 0a0e2ff370..b2afa06646 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -183,7 +183,7 @@ modeled according to Darcy's Law for porous media flow as: q = kA\left( \psi_1 - \psi_2 \right) -:math:`q` is the flux of water (mmH\ :sub:`2`\ O) spanning the segment +:math:`q` is the flux of water (mmH\ :sub:`2`\ O/s) spanning the segment between :math:`\psi_1` and :math:`\psi_2` :math:`k` is the hydraulic conductance (s\ :sup:`-1`\ ) @@ -206,11 +206,11 @@ conductivity (:math:`p50`) and a shape fitting parameter (:math:`c_k`). k=k_{max}\cdot 2^{-\left(\dfrac{\psi_1}{p50}\right)^{c_k}} -:math:`k_{max}` is the maximum segment conductance (s-1) +:math:`k_{max}` is the maximum segment conductance (s\ :sup:`-1`\ ) -:math:`p50` is the water potential at 50% loss of conductivity (mmH2O) +:math:`p50` is the water potential at 50% loss of conductivity (mmH\ :sub:`2`\ O) -:math:`\psi_1` is the water potential of the lower segment terminus (mmH2O) +:math:`\psi_1` is the water potential of the lower segment terminus (mmH\ :sub:`2`\ O) .. _Stem-to-leaf: @@ -255,27 +255,27 @@ basis is the leaf area index (either sunlit or shaded). Variables: -:math:`q_{1a}` = flux of water (mmH2O/s) from stem to sunlit leaf +:math:`q_{1a}` = flux of water (mmH\ :sub:`2`\ O/s) from stem to sunlit leaf -:math:`q_{1b}` = flux of water (mmH2O/s) from stem to shaded leaf +:math:`q_{1b}` = flux of water (mmH\ :sub:`2`\ O/s) from stem to shaded leaf :math:`LAI_{sun}` = sunlit leaf area index (m2/m2) :math:`LAI_{shade}` = shaded leaf area index (m2/m2) -:math:`\psi_{stem}` = stem water potential (mmH2O) +:math:`\psi_{stem}` = stem water potential (mmH\ :sub:`2`\ O) -:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH2O) +:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH\ :sub:`2`\ O) -:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH2O) +:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH\ :sub:`2`\ O) Parameters: -:math:`k_{1a,max}` = maximum leaf conductance (s-1) +:math:`k_{1a,max}` = maximum leaf conductance (s\ :sup:`-1`\ ) -:math:`k_{1b,max}` = maximum leaf conductance (s-1) +:math:`k_{1b,max}` = maximum leaf conductance (s\ :sup:`-1`\ ) -:math:`p50_{1}` = water potential at 50% loss of conductance (mmH2O) +:math:`p50_{1}` = water potential at 50% loss of conductance (mmH\ :sub:`2`\ O) :math:`c_{k}` = vulnerability curve shape-fitting parameter (-) @@ -309,21 +309,21 @@ gravitational potential. Variables: -:math:`q_2` = flux of water (mmH2O/s) from root to stem +:math:`q_2` = flux of water (mmH\ :sub:`2`\ O/s) from root to stem :math:`SAI` = stem area index (m2/m2) -:math:`\Delta\psi_z` = gravitational potential (mmH2O) +:math:`\Delta\psi_z` = gravitational potential (mmH\ :sub:`2`\ O) -:math:`\psi_{root}` = root water potential (mmH2O) +:math:`\psi_{root}` = root water potential (mmH\ :sub:`2`\ O) -:math:`\psi_{stem}` = stem water potential (mmH2O) +:math:`\psi_{stem}` = stem water potential (mmH\ :sub:`2`\ O) Parameters: :math:`k_{2,max}` = maximum stem conductivity (m/s) -:math:`p50_2` = water potential at 50% loss of conductivity (mmH2O) +:math:`p50_2` = water potential at 50% loss of conductivity (mmH\ :sub:`2`\ O) :math:`z_2` = vegetation height (m) @@ -392,17 +392,17 @@ from the characteristic root spacing (section :numref:`Root Spacing`). Variables: -:math:`q_{3,i}` = flux of water (mmH2O/s) from soil layer :math:`i` to root +:math:`q_{3,i}` = flux of water (mmH\ :sub:`2`\ O/s) from soil layer :math:`i` to root -:math:`\Delta\psi_{z,i}` = change in gravitational potential from soil layer :math:`i` to surface (mmH2O) +:math:`\Delta\psi_{z,i}` = change in gravitational potential from soil layer :math:`i` to surface (mmH\ :sub:`2`\ O) :math:`LAI` = total leaf area index (m2/m2) :math:`SAI` = stem area index (m2/m2) -:math:`\psi_{soil,i}` = water potential in soil layer :math:`i` (mmH2O) +:math:`\psi_{soil,i}` = water potential in soil layer :math:`i` (mmH\ :sub:`2`\ O) -:math:`\psi_{root}` = root water potential (mmH2O) +:math:`\psi_{root}` = root water potential (mmH\ :sub:`2`\ O) :math:`z_{3,i}` = length of root tissue conducting path = soil layer depth + root lateral length (m) @@ -414,7 +414,7 @@ Parameters: :math:`f_{root-leaf}` = root-to-shoot ratio (-) -:math:`p50_3` = water potential at 50% loss of root tissue conductance (mmH2O) +:math:`p50_3` = water potential at 50% loss of root tissue conductance (mmH\ :sub:`2`\ O) :math:`ck` = shape-fitting parameter for vulnerability curve (-) @@ -461,9 +461,9 @@ Vegetation water stress is calculated based on leaf water potential and is used :math:`E_{shade,max}` = shaded leaf transpiration absent water stress (mm/s) -:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH2O) +:math:`\psi_{sunleaf}` = sunlit leaf water potential (mmH\ :sub:`2`\ O) -:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH2O) +:math:`\psi_{shadeleaf}` = shaded leaf water potential (mmH\ :sub:`2`\ O) :math:`\beta_{t,sun}` = sunlit transpiration water stress (-) diff --git a/doc/source/tech_note/Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst b/doc/source/tech_note/Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst index d087e1d06a..4c2cb71a26 100644 --- a/doc/source/tech_note/Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst +++ b/doc/source/tech_note/Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst @@ -9,7 +9,7 @@ plants due to the aggregate of processes such as wind throw, insect attack, disease, extreme temperatures or drought, and age-related decline in vigor. These processes are referred to in aggregate as “gap-phase†mortality. Mortality due to fire and anthropogenic land -cover change are treated separately (see Chapters 18 and 21, +cover change are treated separately (see Chapters :numref:`rst_Fire` and :numref:`rst_Transient Landcover Change`, respectively). Mortality Fluxes Leaving Vegetation Pools @@ -19,9 +19,9 @@ Whole-plant mortality is parameterized very simply, assuming a mortality rate of 2% yr\ :sup:`-1` for all vegetation types. This is clearly a gross oversimplification of an important process, and additional work is required to better constrain this process in different climate zones -(Keller et al. 2004; Sollins 1982), for different species mixtures -(Gomes et al. 2003), and for different size and age classes (Busing -2005; Law et al. 2003). Literature values for forest mortality rates +(:ref:`Keller et al. 2004`; :ref:`Sollins 1982`), for different species mixtures +(:ref:`Gomes et al. 2003`), and for different size and age classes (:ref:`Busing +2005`; :ref:`Law et al. 2003`). Literature values for forest mortality rates range from at least 0.7% to 3.0% yr\ :sup:`-1`. Taking the annual rate of mortality (*am*, proportion yr\ :sup:`-1`) as 0.02, a mortality rate per second (*m*) is calculated as diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index d54e70f1e9..5f72de7d9b 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -34,6 +34,7 @@ CLM Technical Note Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst Decomposition/CLM50_Tech_Note_Decomposition.rst External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst + Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst Fire/CLM50_Tech_Note_Fire.rst Methane/CLM50_Tech_Note_Methane.rst Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst From b5c0ae92aeb43ca4cd2159723227707c39dae0ff Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 1 Feb 2018 16:58:47 -0700 Subject: [PATCH 141/255] Add what's new with glaciers, and some minor edits --- .../Glacier/CLM50_Tech_Note_Glacier.rst | 97 +++++++++++++------ 1 file changed, 67 insertions(+), 30 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index a7f2100478..7c9d98bcd6 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -1,7 +1,7 @@ .. _rst_Glaciers: Glaciers -============ +======== This chapter describes features of CLM that are specific to coupling to an ice sheet model (in the CESM context, this is the CISM model; @@ -11,6 +11,42 @@ about glacier land units can be found elsewhere in this document (see Chapter :numref:`rst_Surface Characterization, Vertical Discretization, and Model Input Requirements` for an overview). +.. _Glaciers summary of CLM5.0 updates relative to CLM4.5: + +Summary of CLM5.0 updates relative to CLM4.5 +-------------------------------------------- + +Compared with CLM4.5 (:ref:`Oleson et al. 2013 `), +CLM5.0 contains substantial improvements in its capabilities for +land-ice science. This section summarizes these improvements, and the +following sections provide more details. + +- All runs include multiple glacier elevation classes over Greenland and + Antarctica and compute ice sheet surface mass balance in those + regions. + +- A number of namelist parameters offer fine-grained control over + glacier behavior in different regions of the world (section + :numref:`Glacier regions`). (The options used outside of Greenland and + Antarctica reproduce the standard CLM4.5 glacier behavior.) + +- CLM can now keep its glacier areas and elevations in sync with CISM + when running with an evolving ice sheet. (However, in typical + configurations, the ice sheet geometry still remains fixed throughout + the run.) + +- The downscaling to elevation classes now includes downwelling longwave + radiation and partitioning of precipitation into rain vs. snow + (section :numref:`Multiple elevation class scheme`). + +- Other land units within the CISM domain undergo the same downscaling + as the glacier land unit, and surface mass balance is computed for the + natural vegetated land unit. This allows CLM to produce glacial + inception when running with an evolving ice sheet model. + +- There have also been substantial improvements to CLM's snow physics, + as described in other chapters of this document. + .. _Overview Glaciers: Overview @@ -48,7 +84,7 @@ CISM: #. We can use the sophisticated snow physics parameterization already in CLM instead of implementing a separate scheme for CISM. Any - improvements to the CLM are applied to ice sheets automatically. + improvements to CLM are applied to ice sheets automatically. #. The atmosphere model can respond during runtime to ice-sheet surface changes (even in the absence of two-way feedbacks with CISM). As @@ -78,13 +114,13 @@ the run. In these runs, CISM serves two roles in the system: SGLC then SMB will still be computed in CLM, but it won't be downscaled to a high-resolution ice sheet grid.) -However, it is also possible to run CESM with an evolving ice sheet. In -this case, CLM responds to CISM's evolution by adjusting the areas of -the glacier landunit and each elevation class within this landunit, as -well as the mean topographic heights of each elevation class. Thus, -CLM's glacier areas and elevations remain in sync with -CISM's. Conservation of mass and energy is done as for other landcover -change (see Chapter :numref:`rst_Transient Landcover Change`). +It is also possible to run CESM with an evolving ice sheet. In this +case, CLM responds to CISM's evolution by adjusting the areas of the +glacier land unit and each elevation class within this land unit, as well +as the mean topographic heights of each elevation class. Thus, CLM's +glacier areas and elevations remain in sync with CISM's. Conservation of +mass and energy is done as for other landcover change (see Chapter +:numref:`rst_Transient Landcover Change`). .. _Glacier regions: @@ -94,7 +130,7 @@ Glacier regions and their behaviors The world's glaciers and ice sheets are broken down into a number of different regions (four by default) that differ in three respects: -#. Whether the gridcell's glacier landunit contains: +#. Whether the gridcell's glacier land unit contains: a. Multiple elevation classes (section :numref:`Multiple elevation class scheme`) @@ -189,21 +225,21 @@ runaway sea ice growth in that region. Multiple elevation class scheme ------------------------------- -The glacier landunit contains multiple columns based on surface +The glacier land unit contains multiple columns based on surface elevation. These are known as elevation classes, and the land unit is -referred to as glacier\_mec. (As described in section :numref:`Glacier +referred to as *glacier\_mec*. (As described in section :numref:`Glacier regions`, some regions have only a single elevation class, but they are -still referred to as glacier\_mec landunits.) The default is to have 10 +still referred to as *glacier\_mec* land units.) The default is to have 10 elevation classes whose lower limits are 0, 200, 400, 700, 1000, 1300, 1600, 2000, 2500, and 3000 m. Each column is characterized by a fractional area and surface elevation that are read in during model initialization, and then possibly overridden by CISM as the run -progresses. Each glacier\_mec column within a grid cell has distinct ice +progresses. Each *glacier\_mec* column within a grid cell has distinct ice and snow temperatures, snow water content, surface fluxes, and SMB. The atmospheric surface temperature, potential temperature, specific humidity, density, and pressure are downscaled from the atmosphere's -mean grid cell elevation to the glacier\_mec column elevation using a +mean grid cell elevation to the *glacier\_mec* column elevation using a specified lapse rate (typically 6.0 deg/km) and an assumption of uniform relative humidity. Longwave radiation is downscaled by assuming a linear decrease in downwelling longwave radiation with increasing elevation @@ -231,9 +267,9 @@ In contrast to most CLM subgrid units, glacier\_mec columns can be active (i.e., have model calculations run there) even if their area is zero. These are known as "virtual" columns. This is done because the ice sheet model may require a SMB even for some grid cells where CLM does -not have glacier land units. Virtual columns do not affect energy -exchange between the land and the atmosphere, but are included for -potential forcing of CISM. +not have glacier land units. Virtual columns also facilitate glacial +advance and retreat in the two-way coupled case. Virtual columns do not +affect energy exchange between the land and the atmosphere. .. _Computation of the surface mass balance: @@ -245,7 +281,7 @@ associated runoff terms. The description here only applies to regions where glacial melt runs off and is replaced by ice, not to regions where glacial melt remains in place. Thus, by default, this only applies to Greenland and Antarctica, not to mountain glaciers elsewhere in the -world. (See also :numref:`Glacier regions`.) +world. (See also section :numref:`Glacier regions`.) The SMB of a glacier or ice sheet is the net annual accumulation/ablation of mass at the upper surface. Ablation is defined @@ -299,7 +335,7 @@ then CISM controls the fate of the snow capping mass in :math:`q_{ice,frz}` (e.g., eventually transporting it to lower elevations where it can be melted or calved). Since CISM will now own this mass, the snow capping flux does *not* contribute to any runoff -fluxes generated by CLM. +fluxes generated by CLM in this case. If *glc\_dyn\_runoff\_routing* is false, then CLM sends the snow capping flux as runoff, as a crude representation of ice calving (see also @@ -325,17 +361,18 @@ need is subtle, but can be understood with either of these explanations: for each unit of melt. For a given point in space or time, this reduction can result in -negative ice runoff. However, when integrated over time and space, for +negative ice runoff. However, when integrated over space and time, for an ice sheet that is near equilibrium, this just serves to decrease the -too-high positive ice runoff from snow capping. (This near-equilibrium -assumption is a key point in the treatment of snow capping with -*glc\_dyn\_runoff\_routing* false. For glaciers and ice sheets that -violate this assumption, either because they are far out of equilibrium -with the climate or because the model is being run for hundreds of -years, there are two ways to avoid the unrealistic ice runoff from snow -capping: by running with an evolving, two-way-coupled ice sheet or by -changing a glacier region's ice runoff behavior as described in section -:numref:`Glacier regions`.) +too-high positive ice runoff from snow capping. (The treatment of snow +capping with *glc\_dyn\_runoff\_routing* false is based on this +near-equilibrium assumption - i.e., that ice accumulation is roughly +balanced by :math:`calving + melt`, integrated across space and time. +For glaciers and ice sheets that violate this assumption, either because +they are far out of equilibrium with the climate or because the model is +being run for hundreds of years, there are two ways to avoid the +unrealistic ice runoff from snow capping: by running with an evolving, +two-way-coupled ice sheet or by changing a glacier region's ice runoff +behavior as described in section :numref:`Glacier regions`.) In regions where SMB is computed for glaciers, SMB is also computed for the natural vegetated land unit. Because there is no ice to melt in this From d572279fc56d35cbe9861fbdc65ebbd7c2713704 Mon Sep 17 00:00:00 2001 From: Katie Dagon Date: Thu, 1 Feb 2018 22:04:34 -0700 Subject: [PATCH 142/255] A few more typos --- doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 5 ++--- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- .../Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst | 2 +- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 139aea37df..ddca9ed4ca 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -67,7 +67,6 @@ structure may coexist on a single column. All fluxes to and from the surface are defined at the PFT level, as are the vegetation state variables (e.g. vegetation temperature and canopy water storage). On the crop land unit, typically, different crop types can be represented on each - crop land unit column (see Chapter :numref:`rst_Crops and Irrigation` for details). In addition to state and flux variable data structures for conserved @@ -462,11 +461,11 @@ file defined in the namelist (see the CLM4.5 User’s Guide). Aerosol deposition rates were calculated in a transient 1850-2009 CAM simulation (at a resolution of 1.9x2.5x26L) with interactive chemistry (troposphere and stratosphere) driven by CCSM3 20\ :sup:`th` century -sea-surface temperatures and emissions (Lamarque et al. 2010) for +sea-surface temperatures and emissions (:ref:`Lamarque et al. 2010`) for short-lived gases and aerosols; observed concentrations were specified for methane, N\ :sub:`2`\ O, the ozone-depleting substances (CFCs) ,and CO\ :sub:`2`. The fluxes are used by the snow-related -parameterizations (Chapters :numref:`rst_Surface Albedos` and numref:`rst_Snow Hydrology`). +parameterizations (Chapters :numref:`rst_Surface Albedos` and :numref:`rst_Snow Hydrology`). :sup:`4`\ The nitrogen deposition rate is required by the biogeochemistry model when active and represents the total deposition of diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 0993904323..d08f3e87db 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -173,7 +173,7 @@ The purpose of this document is to fully describe the biogeophysical and biogeochemical parameterizations and numerical implementation of version 5.0 of the Community Land Model (CLM5.0). Scientific justification and evaluation of these parameterizations can be found in the referenced -scientific papers (:ref:`rst_References`). This document and the CLM5.0 +scientific papers (Chapter :numref:`rst_References`). This document and the CLM5.0 User’s Guide together provide the user with the scientific description and operating instructions for CLM. diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index 14ceeaa968..d9dee6581a 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -725,7 +725,7 @@ Subdivision The snow layers are subdivided when the layer thickness exceeds the prescribed maximum thickness :math:`\Delta z_{\max }` with lower and -upper bounds that depend on the number of snow layers (numref:`Table snow layer thickness`). For +upper bounds that depend on the number of snow layers (:numref:`Table snow layer thickness`). For example, if there is only one layer, then the maximum thickness of that layer is 0.03 m, however, if there is more than one layer, then the maximum thickness of the top layer is 0.02 m. Layers are checked From 8b21b15e923d953cfc7c5fe70c5febbdcbdf3fe0 Mon Sep 17 00:00:00 2001 From: Katie Dagon Date: Thu, 1 Feb 2018 22:29:09 -0700 Subject: [PATCH 143/255] Still trying to fix References link --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index d08f3e87db..0993904323 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -173,7 +173,7 @@ The purpose of this document is to fully describe the biogeophysical and biogeochemical parameterizations and numerical implementation of version 5.0 of the Community Land Model (CLM5.0). Scientific justification and evaluation of these parameterizations can be found in the referenced -scientific papers (Chapter :numref:`rst_References`). This document and the CLM5.0 +scientific papers (:ref:`rst_References`). This document and the CLM5.0 User’s Guide together provide the user with the scientific description and operating instructions for CLM. From 9c1dc25e7fc189f2c353e47b900b1941adcecd19 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Fri, 2 Feb 2018 06:00:25 -0700 Subject: [PATCH 144/255] Minor edits from Bill Lipscomb --- .../Glacier/CLM50_Tech_Note_Glacier.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index 7c9d98bcd6..cb11d05c76 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -93,9 +93,9 @@ CISM: ice-sheet retreat on paleoclimate time scales. Without this feedback the atmosphere warms much less, and the retreat is delayed. -#. The improved SMB is available in CLM for all glaciated grid cells - (e.g., in the Alps, Rockies, Andes, and Himalayas), not just those - which are part of ice sheets. +#. The improved SMB is potentially available in CLM for all glaciated + grid cells (e.g., in the Alps, Rockies, Andes, and Himalayas), not + just those which are part of ice sheets. In typical runs, CISM is not evolving; CLM computes the SMB and sends it to CISM, but CISM's ice sheet geometry remains fixed over the course of @@ -104,8 +104,8 @@ the run. In these runs, CISM serves two roles in the system: #. Over the CISM domain (typically Greenland in CESM2), CISM dictates glacier areas and topographic elevations, overriding the values on CLM's surface dataset. CISM also dictates the elevation of - non-glacier land units in its domain, and atmospheric fields are - downscaled to non-glacier land units only in this domain. (So if you + non-glacier land units in its domain, and only in this domain are + atmospheric fields downscaled to non-glacier land units. (So if you run with a stub glacier model - SGLC - then glacier areas and elevations will be taken entirely from CLM's surface dataset, and no downscaling will be done over non-glacier land units.) @@ -266,10 +266,10 @@ CISM domain as consistent as possible. In contrast to most CLM subgrid units, glacier\_mec columns can be active (i.e., have model calculations run there) even if their area is zero. These are known as "virtual" columns. This is done because the ice -sheet model may require a SMB even for some grid cells where CLM does -not have glacier land units. Virtual columns also facilitate glacial -advance and retreat in the two-way coupled case. Virtual columns do not -affect energy exchange between the land and the atmosphere. +sheet model may require a SMB for some grid cells where CLM has zero +glacier area in that elevation range. Virtual columns also facilitate +glacial advance and retreat in the two-way coupled case. Virtual columns +do not affect energy exchange between the land and the atmosphere. .. _Computation of the surface mass balance: From 05a5eb7f2646bef8ab920bd1d47ae327ff4b737f Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Fri, 2 Feb 2018 15:52:55 +0100 Subject: [PATCH 145/255] update portions of the Snow Hydrology chapter --- .../CLM50_Tech_Note_Snow_Hydrology.rst | 182 +++++++++++++----- 1 file changed, 137 insertions(+), 45 deletions(-) diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index d9dee6581a..44bf0ac9c7 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -37,7 +37,7 @@ the state variable is the mass of snow :math:`W_{sno}` (kg m\ :sup:`-2`). Section :numref:`Snow Covered Area Fraction` describes the calculation of fractional snow covered area, which is used in the surface albedo -calculation (Chapter :numref:`rst_Surface Albedos`) and thesurface flux +calculation (Chapter :numref:`rst_Surface Albedos`) and the surface flux calculations (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes`). The following two sections (:numref:`Ice Content` and :numref:`Water Content`) describe the ice and water content of the snow @@ -90,7 +90,12 @@ reset to zero. The depletion curve shape parameter is defined as The standard deviation of the elevation within a grid cell, :math:`\sigma _{topo}` , is calculated from a high resolution DEM (a -1km DEM is used for CLM). +1km DEM is used for CLM). +Note that *glacier\_mec* columns (section :numref:`Multiple elevation class scheme`) +are treated differently in this respect, as they already account for the +subgrid topography in a grid cell in their own way. +Therefore, in each *glacier\_mec* column very flat terrain is assumed, +implemented as :math:`N_{melt}=10`. .. _Ice Content: @@ -141,13 +146,20 @@ where \Delta z_{sno} =\frac{q_{grnd,\, ice} \Delta t}{f_{sno} \rho _{sno} } and :math:`\rho _{sno}` is the bulk density of newly fallen snow (kg -m\ :sup:`-3`) (:ref:`van Kampenhout et al. (2017) `, -:ref:`Anderson (1976) `) +m\ :sup:`-3`), which parameterized by a temperature-dependent and a +wind-dependent term: .. math:: - :label: 8.21 + :label: 8.21a - \rho_{sno} = + \rho_{sno} = \rho_{T} + \rho_{w}. + +The temperature dependent term is given by (:ref:`van Kampenhout et al. (2017) `) + +.. math:: + :label: 8.21b + + \rho_{T} = \left\{\begin{array}{lr} 50 + 1.7 \left(17\right)^{1.5} & \qquad T_{atm} >T_{f} +2 \ \\ 50+1.7 \left(T_{atm} -T_{f} + 15\right)^{1.5} & \qquad T_{f} - 15 < T_{atm} \le T_{f} + 2 \ \\ @@ -158,21 +170,21 @@ m\ :sup:`-3`) (:ref:`van Kampenhout et al. (2017) `, .. bifall(c) = -(50._r8/15._r8 + 0.0333_r8*15_r8)*(forc_t(c)-tfrz) - 0.0333_r8*(forc_t(c)-tfrz)**2 where :math:`T_{atm}` is the atmospheric temperature (K), and :math:`T_{f}` is -the freezing temperature of water (K) (:numref:`Table Physical Constants`). When -wind speed :math:`W_{atm}` is greater than 0.1 m :sub:`-1`, snow density +the freezing temperature of water (K) (:numref:`Table Physical Constants`). +When 10 m wind speed :math:`W_{atm}` is greater than 0.1 m\ :sup:`-1`, snow density increases due to wind-driven compaction according to -:ref:`(van Kampenhout et al. 2017) ` +:ref:`van Kampenhout et al. 2017 ` .. math:: - :label: 8.21b - - \Delta \rho_{sno} = 266.861 \left(\frac{1 + tanh(\frac{W_{atm}}{5})}{2}\right)^{8.8} + :label: 8.21c -where :math:`\Delta \rho_{sno}` (kg m\ :sup:`-3`) is the increase in snow -density relative to :eq:`8.21`. + \rho_{w} = 266.861 \left(\frac{1 + \tanh(\frac{W_{atm}}{5})}{2}\right)^{8.8} .. bifall(c) = bifall(c) + (266.861_r8 * ((1._r8 + TANH(forc_wind(g)/5.0_r8))/2._r8)**8.8_r8) +which is added to the temperature-dependent term (cf. equation :eq:`8.21a`). + + The mass of snow :math:`W_{sno}` is .. math:: @@ -213,9 +225,9 @@ content is reset to zero and the liquid water content :math:`w_{liq,\, snl+1}` is reduced by the amount required to bring :math:`w_{ice,\, snl+1}^{n+1}` up to zero. -The snow water equivalent :math:`W_{sno}` is capped to not exceed 1000 +The snow water equivalent :math:`W_{sno}` is capped to not exceed 10,000 kg m\ :sup:`-2`. If the addition of :math:`q_{frost}` were to -result in :math:`W_{sno} >1000` kg m\ :sup:`-2`, the frost term +result in :math:`W_{sno} > 10,000` kg m\ :sup:`-2`, the frost term :math:`q_{frost}` is instead added to the ice runoff term :math:`q_{snwcp,\, ice}` (section :numref:`Runoff from glaciers and snow-capped surfaces`). @@ -447,18 +459,22 @@ Snow Compaction Snow compaction is initiated after the soil hydrology calculations [surface runoff (section :numref:`Surface Runoff`), infiltration (section :numref:`Infiltration`), soil water (section :numref:`Soil Water`)] are -complete. Compaction of snow includes three types of processes: -destructive metamorphism of new snow (crystal breakdown due to wind or -thermodynamic stress); snow load or overburden (pressure); and melting -(changes in snow structure due to melt-freeze cycles plus changes in -crystals due to liquid water). The total fractional compaction rate for +complete. Currently, there are four processes included that lead to snow +compaction: + + #. destructive metamorphism of new snow (crystal breakdown due to wind or thermodynamic stress) + #. snow load or compaction by overburden pressure + #. melting (changes in snow structure due to melt-freeze cycles plus changes in crystals due to liquid water) + #. drifting snow compaction. + +The total fractional compaction rate for each snow layer :math:`C_{R,\, i}` (s\ :sup:`-1`) is the sum of the three compaction processes .. math:: :label: 8.41 - C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} . + C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} +C_{R4,\, i} . Compaction is not allowed if the layer is saturated @@ -469,8 +485,21 @@ Compaction is not allowed if the layer is saturated or if the ice content is below a minimum value (:math:`w_{ice,\, i} \le 0.1`). +The snow layer thickness after compaction is -Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sub:`-1`) is temperature dependent (:ref:`Anderson (1976) `) +.. math:: + :label: 8.50 + + \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). + + + +.. _Destructive metamorphism: + +Destructive metamorphism +'''''''''''''''''''''''' + +Compaction as a result of destructive metamorphism :math:`C_{R1,\; i}` (s\ :sup:`-1`) is temperature dependent (:ref:`Anderson (1976) `) .. math:: :label: 8.43 @@ -483,36 +512,34 @@ where :math:`c_{3} =2.777\times 10^{-6}` (s\ :sup:`-1`) is the fractional compa :label: 8.44 \begin{array}{lr} - c_{1} = 1 & \qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 100{\rm \; kg\; m}^{{\rm -3}} \\ - c_{1} = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -100\right)\right] & \qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >100{\rm \; kg\; m}^{{\rm -3}} \\ + c_{1} = 1 & \qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \le 175{\rm \; kg\; m}^{{\rm -3}} \\ + c_{1} = \exp \left[-0.046\left(\frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } -175\right)\right] & \qquad \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } >175{\rm \; kg\; m}^{{\rm -3}} \\ c_{2} = 2 & \qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } >0.01 \\ c_{2} = 1 & \qquad \frac{w_{liq,\, i} }{f_{sno} \Delta z_{i} } \le 0.01 \end{array} +.. upper limit (upplim_destruct_metamorph) used to be 100 but was changed to 175 for CLM5 (Van Kampenhout et al., 2017) + where :math:`{w_{ice,\, i} \mathord{\left/ {\vphantom {w_{ice,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` and :math:`{w_{liq,\, i} \mathord{\left/ {\vphantom {w_{liq,\, i} \left(f_{sno} \Delta z_{i} \right)}} \right. \kern-\nulldelimiterspace} \left(f_{sno} \Delta z_{i} \right)}` are the bulk densities of liquid water and ice (kg m\ :sup:`-3`). -The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (:ref:`Anderson (1976) `) -.. math:: - :label: 8.45 +.. _Overburden pressure compaction: - C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } +Overburden pressure compaction +'''''''''''''''''''''''''''''' -where :math:`\eta` is a viscosity coefficient (kg s m\ :sup:`-2`) that varies with density and temperature as +The compaction rate as a result of overburden :math:`C_{R2,\; i}` (s\ :sup:`-1`) is a linear function of the snow load pressure :math:`P_{s,\, i}` (kg m\ :sup:`-2`) (:ref:`Anderson (1976) `): .. math:: - :label: 8.46 + :label: 8.45 - \eta =\eta _{0} \exp \left[c_{5} \left(T_{f} -T_{i} \right)+c_{6} \frac{w_{ice,\, i} }{f_{sno} \Delta z_{i} } \right] + C_{R2,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{overburden} =-\frac{P_{s,\, i} }{\eta } -where :math:`\eta _{0} =9\times 10^{5}` kg s m\ :sup:`-2`, and -:math:`c_{5} =0.08` K\ :sup:`-1`, :math:`c_{6} =0.023` -m\ :sup:`3` kg\ :sup:`-1` are constants. The snow load -pressure :math:`P_{s,\, i}` is calculated for each layer as the sum of +The snow load pressure :math:`P_{s,\, i}` is calculated for each layer as the sum of the ice :math:`w_{ice,\, i}` and liquid water contents :math:`w_{liq,\, i}` of the layers above plus half the ice and liquid water contents of the layer being compacted @@ -522,6 +549,32 @@ water contents of the layer being compacted P_{s,\, i} =\frac{w_{ice,\, i} +w_{liq,\, i} }{2} +\sum _{j=snl+1}^{j=i-1}\left(w_{ice,\, j} +w_{liq,\, j} \right) . + +Variable :math:`\eta` in :eq:`8.45` is a viscosity coefficient (kg s m\ :sup:`-2`) that varies with density and +temperature as + +.. math:: + :label: 8.46 + + \eta = f_{1} f_{2} \eta_{0} \frac{\rho_{i}}{c_{\eta}} \exp \left[ a_{\eta} \left(T_{f} -T_{i} \right) + b_{\eta} \rho_{i} \right] + +with constant factors :math:`\eta _{0} = 7.62237 \times 10^{6}` kg s\ :sup:`-1` m\ :sup:`-2`, +:math:`a_{\eta} = 0.1` K\ :sup:`-1`, :math:`b_{\eta} = 0.023` m\ :sup:`-3` kg\ :sup:`-1`, +and :math:`c_{\eta} = 358` kg m\ :sup:`-3` (:ref:`van Kampenhout et al. (2017) `). +Further, factor :math:`f_1` accounts for the presence of liquid water (:ref:`Vionnet et al. (2012) `): + +.. math:: + :label: 8.46b + + f_{1} = \frac{1}{1+ 60 \frac{w_{\mathrm{liq},\, i}}{\rho_{\mathrm{liq}} \Delta z_{i} }}. + +Factor :math:`f_2` originally accounts for the presence of angular grains, but since grain shape is not modelled +:math:`f_2` is fixed to the value 4. + +.. _Compaction by melt: + +Compaction by melt +'''''''''''''''''' The compaction rate due to melting :math:`C_{R3,\; i}` (s\ :sup:`-1`) is taken to be the ratio of the change in snow ice mass after the melting to the mass before melting @@ -531,21 +584,60 @@ mass after the melting to the mass before melting C_{R3,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} =-\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) and melting is identified during the phase change calculations (section -:numref:`Phase Change`). Because snow depth is defined as the average depth of the snow -covered area, the snow depth must also be updated for changes in -:math:`f_{sno}` . +:numref:`Phase Change`). + + +.. _Compaction by drifting snow: + +Compaction by drifting snow +''''''''''''''''''''''''''' +Crystal breaking by drifting snow leads to higher snow densities at the surface. +This process is particularly important on ice sheets, where destructive metamorphism is slow due to low temperatures +but high wind speeds (katabatic winds) are prevailing. +Therefore a drifting snow compaction parametrization was introduced, based on (:ref:`Vionnet et al. (2012) `). .. math:: :label: 8.49 - C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) + C_{R4,\, i} = \left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{drift} = - \frac{\rho_{\max} - \rho_i}{\tau_{i}}. -The snow layer thickness after compaction is then +Here, :math:`\rho_{\max} = 350` kg m\ :sup:`-3` is the upper limit to which this process is active, and +:math:`\tau_{i}` is a timescale which is depth dependent: .. math:: - :label: 8.50 + :label: 8.49b + + \tau_i = \frac{\tau}{\Gamma_{\mathrm{drift}}^i} \quad \mathrm{,} \:\; \Gamma^i_\mathrm{drift} = \max\left[ 0, S_\mathrm{I}^i \exp(-z_i / 0.1) \right]. + +Here, :math:`\tau` is a characteristic time scale for drifting snow compaction and is empirically set to 48 h, and +:math:`z_i` is a pseudo-depth which takes into account previous hardening of snow layers above the current layer: +:math:`z_i = \sum_j \Delta z_j \cdot (3.25 - S_\mathrm{I}^j)`. +The driftability index :math:`S_\mathrm{I}` reflects how well snow can be drifted and depends on the mobility of the snow +as well as the 10 m wind speed: + +.. math:: + :label: 8.49c + + \begin{array}{rcl} + S_\mathrm{I} & = & -2.868 \exp(-0.085 U) + 1 + M_{\mathrm{O}} \\ + M_\mathrm{O} & = & -0.069 + 0.66 F(\rho) + \end{array} + +The latter equation (for the mobility index :math:`M_\mathrm{O}`) is a simplification from the original paper +by removing the dependency on grain size and assuming spherical grains +(see :ref:`van Kampenhout et al. (2017) `). + +.. Because snow depth is defined as the average depth of the snow +.. covered area, the snow depth must also be updated for changes in +.. :math:`f_{sno}` . +.. +.. .. math:: +.. :label: 8.49 +.. +.. C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) + + - \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). .. _Snow Layer Combination and Subdivision: @@ -725,8 +817,8 @@ Subdivision The snow layers are subdivided when the layer thickness exceeds the prescribed maximum thickness :math:`\Delta z_{\max }` with lower and -upper bounds that depend on the number of snow layers (:numref:`Table snow layer thickness`). For -example, if there is only one layer, then the maximum thickness of that +upper bounds that depend on the number of snow layers (:numref:`Table snow layer thickness`). +For example, if there is only one layer, then the maximum thickness of that layer is 0.03 m, however, if there is more than one layer, then the maximum thickness of the top layer is 0.02 m. Layers are checked sequentially from top to bottom for this limit. If there is only one From bcf7f9e9a5a39ac71da73611ee7644be2b09c391 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Fri, 2 Feb 2018 08:50:37 -0700 Subject: [PATCH 146/255] Removed old references to wetland land unit --- doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst | 6 +++--- .../tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 2 +- doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst | 4 ++-- .../tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 4 ++-- .../Introduction/CLM50_Tech_Note_Introduction.rst | 8 ++++---- .../Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst | 4 ++-- .../Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst | 6 ------ .../CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 4 ++-- .../Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst | 6 +++--- .../CLM50_Tech_Note_Transient_Landcover.rst | 2 +- 10 files changed, 20 insertions(+), 26 deletions(-) diff --git a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst index c40ac583f7..2b3064c921 100644 --- a/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst +++ b/doc/source/tech_note/Dust/CLM50_Tech_Note_Dust.rst @@ -34,10 +34,10 @@ mobilization :math:`f_{m}` is given by .. math:: :label: 29.2 - f_{m} =\left(1-f_{lake} -f_{wetl} \right)\left(1-f_{sno} \right)\left(1-f_{v} \right)\frac{w_{liq,1} }{w_{liq,1} +w_{ice,1} } + f_{m} =\left(1-f_{lake} \right)\left(1-f_{sno} \right)\left(1-f_{v} \right)\frac{w_{liq,1} }{w_{liq,1} +w_{ice,1} } -where :math:`f_{lake}` and :math:`f_{wetl}` and :math:`f_{sno}` -are the CLM grid cell fractions of lake and wetland (section +where :math:`f_{lake}` and :math:`f_{sno}` +are the CLM grid cell fractions of lake (section :numref:`Surface Data`) and snow cover (section :numref:`Snow Covered Area Fraction`), all ranging from zero to one. Not mentioned by :ref:`Zender et al. (2003)`, :math:`w_{liq,\, 1}` and diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index ddca9ed4ca..86b3bbb5a9 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -680,7 +680,7 @@ are obtained from a variety of sources described below. At the base spatial resolution of 0.05\ :sup:`o`, the percentage of each PFT is defined with respect to the vegetated portion of the grid -cell and the sum of the PFTs is 100%. The percent lake, wetland, +cell and the sum of the PFTs is 100%. The percent lake, glacier, and urban at their base resolution are specified with respect to the entire grid cell. The surface dataset creation routines re-adjust the PFT percentages to ensure that the sum of all land cover types in diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index fdd6873346..7abed081fd 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -583,7 +583,7 @@ Sensible and Latent Heat Fluxes for Non-Vegetated Surfaces Surfaces are considered non-vegetated for the surface flux calculations if leaf plus stem area index :math:`L+S<0.05` (section :numref:`Phenology and vegetation burial by snow`). By -definition, this includes bare soil, wetlands, and glaciers. The +definition, this includes bare soil and glaciers. The solution for lakes is described in Chapter :numref:`rst_Lake Model`. For these surfaces, the surface may be exposed to the atmosphere, snow covered, and/or surface water covered, so that the sensible heat flux :math:`H_{g}` (W @@ -785,7 +785,7 @@ The roughness lengths used to calculate :math:`r_{am}` , :math:`r_{ah}` , and :math:`r_{aw}` are :math:`z_{0m} =z_{0m,\, g}` , :math:`z_{0h} =z_{0h,\, g}` , and :math:`z_{0w} =z_{0w,\, g}` . The displacement height :math:`d=0`. The momentum roughness length is -:math:`z_{0m,\, g} =0.01` for soil, glaciers, and wetland, and +:math:`z_{0m,\, g} =0.01` for soil, glaciers, and :math:`z_{0m,\, g} =0.0024` for snow-covered surfaces (:math:`f_{sno} >0`). In general, :math:`z_{0m}` is different from :math:`z_{0h}` because the transfer of momentum is affected by pressure diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index b1153c3a5d..2bcd8f24b0 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -28,7 +28,7 @@ ET from vegetation (Chapter :numref:`rst_Momentum, Sensible Heat, and Latent Hea :math:`q_{h2osfc}` is runoff from surface water storage (section :numref:`Surface Runoff`), :math:`q_{drai}` is sub-surface drainage (section :numref:`Lateral Sub-surface Runoff`), :math:`q_{rgwl}` and :math:`q_{snwcp,ice}` are liquid and solid runoff -from glaciers, wetlands, and lakes, and runoff from other surface types +from glaciers and lakes, and runoff from other surface types due to snow capping (section :numref:`Runoff from glaciers and snow-capped surfaces`) (all in kg m\ :sup:`-2` s\ :sup:`-1`), :math:`N_{levsoi}` is the number of soil layers (note that hydrology calculations are only done over soil layers 1 to @@ -334,7 +334,7 @@ Surface Water Storage A surface water store has been added to the model to represent wetlands and small, sub-grid scale water bodies. As a result, the wetland land -unit has been removed. The state variables for surface water are the +unit has been removed as of CLM4.5. The state variables for surface water are the mass of water :math:`W_{sfc}` (kg m\ :sup:`-2`) and temperature :math:`T_{h2osfc}` (Chapter :numref:`rst_Soil and Snow Temperatures`). Surface water storage and outflow are diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 0993904323..3fc79b5e09 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -5,16 +5,16 @@ ***Coordinating Lead Authors*** -**David M. Lawrence, Rosie Fisher, Charles D. Koven, Keith W. Oleson, Sean Swenson** +**David Lawrence, Rosie Fisher, Charles Koven, Keith Oleson, Sean Swenson** ***Lead Authors*** -**Gordon Bonan, Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Peter J. Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William J. Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu** +**Ben Andre, Gordon Bonan, Bardan Ghimire, Leo van Kampenhout, Daniel Kennedy, Erik Kluzek, Ryan Knox, Peter Lawrence, Fang Li, Hongyi Li, Danica Lombardozzi, Yaqiong Lu, Justin Perket, William Riley, William Sacks, Mingjie Shi, Will Wieder, Chonggang Xu** ***Contributing Authors*** -**Ashehad Ali, Ben Andre, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Ryan Knox, Jan Lenaerts, Sam Levis, -L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Andrew Slater, Zachary M. Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** +**Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, +L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** The National Center for Atmospheric Research (NCAR) is operated by the diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index cc32f0c1f3..5e09da13c5 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -288,8 +288,8 @@ emissivity of the ground is \varepsilon _{g} =\varepsilon _{soi} \left(1-f_{sno} \right)+\varepsilon _{sno} f_{sno} -where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, and -0.96 for wetland, :math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` +where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, + :math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` is the fraction of ground covered by snow (section :numref:`Snow Covered Area Fraction`). The vegetation emissivity is diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index 44bf0ac9c7..5cef68f618 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -204,12 +204,6 @@ The ice content of the top layer and the layer thickness are updated as \Delta z_{snl+1}^{n+1} =\Delta z_{snl+1}^{n} +\Delta z_{sno} . -Since wetlands are modeled as columns of water (no soil), snow is not -allowed to accumulate if the surface temperature is above freezing -(:math:`T_{g} >T_{f}` ). In this case, the incoming solid precipitation -is assigned to the runoff term :math:`q_{rgwl}` (section -:numref:`Runoff from glaciers and snow-capped surfaces`). - In the second step, after surface fluxes and snow/soil temperatures have been determined (Chapters :numref:`rst_Momentum, Sensible Heat, and Latent Heat Fluxes` and :numref:`rst_Soil and Snow Temperatures`), diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index 10c00ae1e5..56b6adff3f 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -835,7 +835,7 @@ conductivity, :math:`K_{e,\, i}` is the Kersten number, saturation, and :math:`\lambda _{bedrock} =3` W m\ :sup:`-1` K\ :sup:`-1` is the thermal conductivity assumed for the deep ground layers (typical of saturated granitic rock; -:ref:`Clauser and Huenges 1995 `). For glaciers and wetlands, +:ref:`Clauser and Huenges 1995 `). For glaciers, .. math:: :label: 6.79 @@ -962,7 +962,7 @@ where :math:`c_{s,bedrock} =2\times 10^{6}` J m\ :sup:`-3` K\ :sup:`-1` is the heat capacity of bedrock and :math:`c_{s,om} =2.5\times 10^{6}` \ J m\ :sup:`-3` K\ :sup:`-1` (:ref:`Farouki 1981 `) is the heat capacity of organic -matter. For glaciers, wetlands, and snow +matter. For glaciers and snow .. math:: :label: 6.92 diff --git a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst index 55323eabf5..2770917358 100644 --- a/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst +++ b/doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst @@ -523,14 +523,14 @@ where :math:`f_{sno}` is the fraction of the ground covered with snow (section :numref:`Snow Covered Area Fraction`). :math:`\alpha _{soi,\, \Lambda }^{\mu }` and -:math:`\alpha _{soi,\, \Lambda }` vary with glacier, lake, wetland, and +:math:`\alpha _{soi,\, \Lambda }` vary with glacier, lake, and soil surfaces. Glacier albedos are from :ref:`Paterson (1994) ` .. math:: \alpha _{soi,\, vis}^{\mu } =\alpha _{soi,\, vis} =0.6 .. math:: \alpha _{soi,\, nir}^{\mu } =\alpha _{soi,\, nir} =0.4. -Unfrozen lake and wetland albedos depend on the cosine of the solar +Unfrozen lake albedos depend on the cosine of the solar zenith angle :math:`\mu` .. math:: @@ -538,7 +538,7 @@ zenith angle :math:`\mu` \alpha _{soi,\, \Lambda }^{\mu } =\alpha _{soi,\, \Lambda } =0.05\left(\mu +0.15\right)^{-1} . -Frozen lake and wetland albedos are from NCAR LSM (:ref:`Bonan 1996 `) +Frozen lake albedos are from NCAR LSM (:ref:`Bonan 1996 `) .. math:: \alpha _{soi,\, vis}^{\mu } =\alpha _{soi,\, vis} =0.60 diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index 493cfb2829..ebb6d3762b 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -227,7 +227,7 @@ To represent the LUH2 transient LULCC dataset in CLM5, the annual fractional composition of the twelve land units specified in the dataset needs to be faithfully represented with a corresponding PFT and CFT mosaics of CLM. CLM5 represents the land surface as a hierarchy of sub-grid types: -glacier; lake; wetland; urban; vegetated land; and crop land. The vegetated land is +glacier; lake; urban; vegetated land; and crop land. The vegetated land is further divided into a mosaic of Plant Functional Types (PFTs), while the crop land is divided into a mosaic of Crop Functional Types (CFTs). From 8fb004c2bbfc5ddc3078f47ba6bf9cb47c916157 Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Fri, 2 Feb 2018 17:06:21 +0100 Subject: [PATCH 147/255] add reference Vionnetetal 2012 --- .../tech_note/References/CLM50_Tech_Note_References.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 9e2277cdff..924e265b0a 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -2864,6 +2864,14 @@ paper presented at the Third International Conference/Workshop on Integrating GIS and Environmental Modeling, Santa Fe, New Mexico, 21–26 January, Natl. Cent. for Geogr. Inf. and Anal., Santa Barbara, Calif. +.. _Vionnetetal2012: + +|br| + +Vionnet, V., E. Brun, S. Morin, A. Boone, S. Faroux, P. Le Moigne, E. Martin, and J.-M. Willemet. +The Detailed Snowpack Scheme Crocus and Its Implementation in SURFEX v7.2. +GMD 5, no. 3 (May 24, 2012): 773-91. https://doi.org/10.5194/gmd-5-773-2012. + .. _Viovy2011: |br| From 9c0e0c5ce1976bf44c3a928fad5226d3519edf0b Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 2 Feb 2018 10:29:30 -0700 Subject: [PATCH 148/255] minor edits --- doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 1 + .../Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 2bcd8f24b0..fb387d25c2 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -78,6 +78,7 @@ respectively :label: 7.3b f_{pi,\,ice} =\alpha_{sno} \ \left\{1-\exp \left[-0.5\left(L+S\right)\right]\right\} \ , + and :math:`L` and :math:`S` are the exposed leaf and stem area index, respectively (section :numref:`Phenology and vegetation burial by snow`), and the :math:`\alpha`\'s scale the fractional area of a leaf that collects water diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index 5e09da13c5..5e368456ba 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -288,8 +288,8 @@ emissivity of the ground is \varepsilon _{g} =\varepsilon _{soi} \left(1-f_{sno} \right)+\varepsilon _{sno} f_{sno} -where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, - :math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` +where :math:`\varepsilon _{soi} =0.96` for soil, 0.97 for glacier, +:math:`\varepsilon _{sno} =0.97`, and :math:`f_{sno}` is the fraction of ground covered by snow (section :numref:`Snow Covered Area Fraction`). The vegetation emissivity is From 3c4d72891340a08bad4442343ddc0a8db6491fad Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Fri, 2 Feb 2018 11:24:45 -0700 Subject: [PATCH 149/255] fix snow hydrology compaction --- .../CLM50_Tech_Note_Snow_Hydrology.rst | 43 ++++++++----------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index 5cef68f618..d0022225b0 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -461,14 +461,13 @@ compaction: #. melting (changes in snow structure due to melt-freeze cycles plus changes in crystals due to liquid water) #. drifting snow compaction. -The total fractional compaction rate for -each snow layer :math:`C_{R,\, i}` (s\ :sup:`-1`) is the sum of the -three compaction processes +The total fractional compaction rate for each snow layer :math:`C_{R,\, i}` +(s\ :sup:`-1`) is the sum of multiple compaction processes .. math:: :label: 8.41 - C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} +C_{R4,\, i} . + C_{R,\, i} =\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} =C_{R1,\, i} +C_{R2,\, i} +C_{R3,\, i} +C_{R4,\, i} +C_{R5,\, i} . Compaction is not allowed if the layer is saturated @@ -479,10 +478,11 @@ Compaction is not allowed if the layer is saturated or if the ice content is below a minimum value (:math:`w_{ice,\, i} \le 0.1`). + The snow layer thickness after compaction is .. math:: - :label: 8.50 + :label: 8.42b \Delta z_{i}^{n+1} =\Delta z_{i}^{n} \left(1+C_{R,\, i} \Delta t\right). @@ -575,11 +575,18 @@ mass after the melting to the mass before melting .. math:: :label: 8.48 - C_{R3,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} =-\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) + C_{R3,\, i} = \left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{melt} + = -\frac{1}{\Delta t} \max \left(0,\frac{W_{sno,\, i}^{n} -W_{sno,\, i}^{n+1} }{W_{sno,\, i}^{n} } \right) and melting is identified during the phase change calculations (section -:numref:`Phase Change`). - +:numref:`Phase Change`). Because snow depth is defined as the average +depth of the snow covered area, the snow depth must also be updated for +changes in :math:`f_{sno}` when :math:`W_{sno}` has changed. + + .. math:: + :label: 8.49 + + C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) .. _Compaction by drifting snow: @@ -591,15 +598,15 @@ but high wind speeds (katabatic winds) are prevailing. Therefore a drifting snow compaction parametrization was introduced, based on (:ref:`Vionnet et al. (2012) `). .. math:: - :label: 8.49 + :label: 8.50 - C_{R4,\, i} = \left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{drift} = - \frac{\rho_{\max} - \rho_i}{\tau_{i}}. + C_{R5,\, i} = \left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{drift} = - \frac{\rho_{\max} - \rho_i}{\tau_{i}}. Here, :math:`\rho_{\max} = 350` kg m\ :sup:`-3` is the upper limit to which this process is active, and :math:`\tau_{i}` is a timescale which is depth dependent: .. math:: - :label: 8.49b + :label: 8.50b \tau_i = \frac{\tau}{\Gamma_{\mathrm{drift}}^i} \quad \mathrm{,} \:\; \Gamma^i_\mathrm{drift} = \max\left[ 0, S_\mathrm{I}^i \exp(-z_i / 0.1) \right]. @@ -610,7 +617,7 @@ The driftability index :math:`S_\mathrm{I}` reflects how well snow can be drifte as well as the 10 m wind speed: .. math:: - :label: 8.49c + :label: 8.50c \begin{array}{rcl} S_\mathrm{I} & = & -2.868 \exp(-0.085 U) + 1 + M_{\mathrm{O}} \\ @@ -621,18 +628,6 @@ The latter equation (for the mobility index :math:`M_\mathrm{O}`) is a simplific by removing the dependency on grain size and assuming spherical grains (see :ref:`van Kampenhout et al. (2017) `). -.. Because snow depth is defined as the average depth of the snow -.. covered area, the snow depth must also be updated for changes in -.. :math:`f_{sno}` . -.. -.. .. math:: -.. :label: 8.49 -.. -.. C_{R4,\, i} =\left[\frac{1}{\Delta z_{i} } \frac{\partial \Delta z_{i} }{\partial t} \right]_{fsno} =-\frac{1}{\Delta t} \max \left(0,\frac{f_{sno,\, i}^{n} -f_{sno,\, i}^{n+1} }{f_{sno,\, i}^{n} } \right) - - - - .. _Snow Layer Combination and Subdivision: Snow Layer Combination and Subdivision From 10d9daf47b4e0a53dd0df1436bcac0610750d888 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Fri, 2 Feb 2018 13:56:36 -0700 Subject: [PATCH 150/255] Fix errors and update html --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 44 +++++++++---------- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 2 +- .../References/CLM50_Tech_Note_References.rst | 17 ++++--- 3 files changed, 34 insertions(+), 29 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 4c3ae84448..8d44f55216 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -37,7 +37,7 @@ The implementation of the Ecosystem Demography concept within FATES links the surface flux and canopy physiology concepts in the CLM/E3SM with numerous additional developments necessary to accommodate the new model also documented here. These include a version of the SPITFIRE -(Spread and InTensity of Fire) model of :ref:`Thonicke et al. (2010)`, and an adoption of the concept of +(Spread and InTensity of Fire) model of :ref:`Thonicke et al. (2010)`, and an adoption of the concept of `Perfect Plasticity Approximation` approach of :ref:`Purves et al. 2008`, :ref:`Lichstein et al. 2011` and :ref:`Weng et al. 2014`, in accounting for the spatial arrangement of crowns. Novel algorithms accounting for @@ -1524,7 +1524,7 @@ canopy structure. This description in this section is largely repeated from the Oleson et al. CLM4.5 technical note but included here for comparison with its implementation in FATES. Photosynthesis in C3 plants is based on the model of :ref:`Farquhar 1980` as -modified by :ref:`Collatz et al. (1991)`. Photosynthetic assimilation +modified by :ref:`Collatz et al. (1991)`. Photosynthetic assimilation in C4 plants is based on the model of :ref:`Collatz et al. (1991)`. In both models, leaf photosynthesis, :math:`\textrm{gpp}` (:math:`\mu`\ mol CO\ :math:`_2` m\ :math:`^{-2}` s\ :math:`^{-1}`) is @@ -1703,7 +1703,7 @@ Variation in plant physiology with canopy depth Both :math:`V_{c,max}` and :math:`J_{max}` vary with vertical depth in the canopy on account of the well-documented reduction in canopy -nitrogen through the leaf profile, see :ref:`Bonan et al. 2012` for +nitrogen through the leaf profile, see :ref:`Bonan et al. 2012` for details). Thus, both :math:`V_{c,max}` and :math:`J_{max}` are indexed by by :math:`C_l`, :math:`ft` and :math:`z` according to the nitrogen decay coefficient :math:`K_n` and the amount of vegetation area shading @@ -2089,7 +2089,7 @@ the leaf at the vegetation temperature conductance (:math:`\mu`\ mol m\ :math:`^{-2}` s\ :math:`^{-1}`) when :math:`A` = 0 . Typical values are :math:`m_{ft}` = 9 for C\ :math:`_3` plants and :math:`m_{ft}` = 4 for C\ :math:`_4` plants ( -:ref:`Collatz et al. 1991`, :ref:`Collatz, 1992`, :ref:`Sellers et al 1996)`. +:ref:`Collatz et al. 1991`, :ref:`Collatz, 1992`, :ref:`Sellers et al 1996`). :ref:`Sellers et al. 1996` used :math:`b` = 10000 for C\ :math:`_3` plants and :math:`b` = 40000 for C\ :math:`_4` plants. Here, :math:`b` was chosen to give a maximum stomatal resistance of 20000 s @@ -3014,7 +3014,7 @@ given cohort triggers mortality. This parameter is needed to scale from individual-level mortality simulation to grid-cell average conditions. Mechanistic simulation of hydraulic failure is not undertaken on account -of it’s mechanistic complexity (see :ref:`McDowell et al. 2013`for +of it’s mechanistic complexity (see :ref:`McDowell et al. 2013` for details). Instead, we use a proxy for hydraulic failure induced mortality (:math:`M_{hf,coh}`) that uses a water potential threshold beyond mortality is triggered, such that the tolerance of low water @@ -3066,7 +3066,7 @@ Fire (SPITFIRE) [24]_The influence of fire on vegetation is estimated using the SPITFIRE model, which has been modified for use in ED following it’s original implementation in the LPJ-SPITFIRE model -(:ref:`Thonicke et al. 2010, :ref:`Pfeiffer et al. 2013`). This model as +(:ref:`Thonicke et al. 2010`, :ref:`Pfeiffer et al. 2013`). This model as described is substantially different from the existing CLM4.5 fire model :ref:`Li et al. 2012`, however, further developments are intended to increase the merging of SPITFIRE’s natural vegetation fire @@ -3096,7 +3096,7 @@ Coarse woody debris is classified into 1h, 10h, 100h, and 1000h fuels, defined by the order of magnitude of time required for fuel to lose (or gain) 63% of the difference between its current moisture content and the equilibrium moisture content under defined atmospheric conditions. -:ref:`Thonicke et al. 2010`. For the purposes of describing +:ref:`Thonicke et al. 2010`. For the purposes of describing the behaviour of fire, we introduce a new index 'fuel class' *fc*, the values of which correspond to each of the six possible fuel categories as follows. @@ -3127,7 +3127,7 @@ Nesterov Index Dead fuel moisture (:math:`\emph{moist}_{df,fc}`), and several other properties of fire behaviour, are a function of the ‘Nesterov Index’ (:math:`N_{I}`) which is an accumulation over time of a function of -temperature and humidity (Eqn 5, :ref:`Thonicke et al. 2010`). +temperature and humidity (Eqn 5, :ref:`Thonicke et al. 2010`). .. math:: N_{I}=\sum{\textrm{max}(T_{d}(T_{d}-D),0)} @@ -3174,7 +3174,7 @@ Live grass moisture Content The live grass fractional moisture content(\ :math:`\emph{moist}_{lg}`) is a function of the soil moisture content. (Equation B2 in -:ref:`Thonicke et al. 2010`) +:ref:`Thonicke et al. 2010`) .. math:: \emph{moist}_{lg}=\textrm{max}(0.0,\frac{10}{9}\theta_{30}-\frac{1}{9}) @@ -3244,7 +3244,7 @@ the fire *ros*\ :math:`_{f}` (nominally in the direction of the wind). :math:`e_{ps}` is the effective heating number (:math:`e^{\frac{-4.528}{F_{\sigma,patch}}}`). :math:`q_{ig}` is the heat of pre-ignition (:math:`581+2594F_{m}`). :math:`x_{i}` is the -propagating flux calculated as (see :ref:`Thonicke et al. 2010` +propagating flux calculated as (see :ref:`Thonicke et al. 2010` Appendix A). .. math:: @@ -3268,7 +3268,7 @@ surface-area-volume ratio :math:`F_{\sigma,patch}`: where :math:`p_{d}` is the particle density (513). :math:`i_{r}` is the reaction intensity, calculated using the following -set of expressions (from :ref:`Thonicke et al. 2010` Appendix A).: +set of expressions (from :ref:`Thonicke et al. 2010` Appendix A).: .. math:: @@ -3292,7 +3292,7 @@ Fuel Consumption The fuel consumption (fraction of biomass pools) of each dead biomass pool in the area affected by fire on a given day (:math:`f_{c,dead,fc}`) is a function of effective fuel moisture :math:`E_{moist,fc}` and size -class *fc* (Eqn B1, B4 and B5, :ref:`Thonicke et al. 2010`). The +class *fc* (Eqn B1, B4 and B5, :ref:`Thonicke et al. 2010`). The fraction of each fuel class that is consumed decreases as its moisture content relative to its moisture of extinction (:math:`E_{moist,fc}`) increases. @@ -3327,7 +3327,7 @@ Fire intensity at the front of the burning area (:math:`I_{surface}`, kW m\ :math:`^{-2}`) is a function of the total fuel consumed (:math:`f_{ctot,patch}`) and the rate of spread at the front of the fire, :math:`\mathit{ros}_{f}` (m min\ :math:`^{-1}`) (Eqn 15 -:ref:`Thonicke et al. 2010`) +:ref:`Thonicke et al. 2010`) .. math:: I_{surface}=\frac{0.001}{60}f_{energy} f_{ctot,patch}\mathit{ros}_{f} @@ -3341,7 +3341,7 @@ Fire Duration Fire duration is a function of the fire danger index with a maximum length of :math:`F_{dur,max}` (240 minutes in -:ref:`Thonicke et al. 2010` Eqn 14, derived from Canadian Forest +:ref:`Thonicke et al. 2010` Eqn 14, derived from Canadian Forest Fire Behaviour Predictions Systems) .. math:: D_{f}=\textrm{min}\Big(F_{dur,max},\frac{F_{dur,max}}{1+F_{dur,max}e^{-11.06fdi}}\Big) @@ -3370,14 +3370,14 @@ respectively). .. math:: f_{length}=F_{d}(ros_{b}+ros_{f}) :math:`ros_{b}` is a function of :math:`ros_{f}` and windspeed (Eqn 10 -:ref:`Thonicke et al. 2010`) +:ref:`Thonicke et al. 2010`) .. math:: ros_{b}=ros_{f}e^{-0.72W} The minor axis to major axis ratio :math:`l_{b}` of the ellipse is determined by the windspeed. If the windspeed (:math:`W`) is less than 16.67 ms\ :math:`^{-1}` then :math:`l_{b}=1`. Otherwise (Eqn 12 and 13, -:ref:`Thonicke et al. 2010`) +:ref:`Thonicke et al. 2010`) .. math:: l_{b}=\textrm{min}\Big(8,f_{tree}(1.0+8.729(1.0-e^{-0.108W})^{2.155})+(f_{grass}(1.1+3.6W^{0.0464}))\Big) @@ -3385,7 +3385,7 @@ determined by the windspeed. If the windspeed (:math:`W`) is less than surface covered by grass and trees respectively. The total area burned (:math:`A_{burn}` in m\ :math:`^{2}`) is therefore -(Eqn 11, :ref:`Thonicke et al. 2010`) +(Eqn 11, :ref:`Thonicke et al. 2010`) .. math:: A_{burn}=\frac{n_{f}\frac{3.1416}{4l_{b}}(f_{length}^{2}))}{10000} @@ -3397,7 +3397,7 @@ Crown Damage :math:`c_{k}` is the fraction of the crown which is consumed by the fire. This is calculated from scorch height :math:`H_{s}`, tree height :math:`h` and the crown fraction parameter :math:`F_{crown}` (Eqn 17 -:ref:`Thonicke et al. 2010`): +:ref:`Thonicke et al. 2010`): .. math:: @@ -3410,7 +3410,7 @@ fire. This is calculated from scorch height :math:`H_{s}`, tree height The scorch height :math:`H_{s}` (m) is a function of the fire intensity, following :ref:`Byram, 1959`, and is proportional to a plant functional type specific parameter :math:`\alpha_{s,ft}` (Eqn 16 -:ref:`Thonicke et al. 2010`): +:ref:`Thonicke et al. 2010`): .. math:: H_{s}=\sum_{FT=1}^{NPFT}{\alpha_{s,p}\cdot f_{biomass,ft}} I_{surface}^{0.667} @@ -3428,19 +3428,19 @@ cambial heating (minutes) (Eqn 8, :ref:`Peterson and Ryan 1986`): Bark thickness is a linear function of tree diameter :math:`dbh_{coh}`, defined by PFT-specific parameters :math:`\beta_{1,bt}` and -:math:`\beta_{2,bt}` (Eqn 21 :ref:`Thonicke et al. 2010`): +:math:`\beta_{2,bt}` (Eqn 21 :ref:`Thonicke et al. 2010`): .. math:: t_{b,coh}=\beta_{1,bt,ft}+\beta_{2,bt,ft}dbh_{coh} The critical time for cambial kill, :math:`\tau_{c}` (minutes) is given -as (Eqn 20 :ref:`Thonicke et al. 2010`): +as (Eqn 20 :ref:`Thonicke et al. 2010`): .. math:: \tau_{c}=2.9t_{b}^{2} The mortality rate caused by cambial heating :math:`\tau_{pm}` of trees within the area affected by fire is a function of the ratio between :math:`\tau_{l}` and :math:`\tau_{c}` (Eqn 19, -:ref:`Thonicke et al. 2010`): +:ref:`Thonicke et al. 2010`): .. math:: diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index e10698858b..74dc2cf6dd 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -89,7 +89,7 @@ where m=1 pertains to the fraction of the PFT that is ecotmycorrhizal, as oppose Resolving N cost across simultaneous uptake streams -------------------------------------------------------- -The total cost of N uptake is calculated based on the assumption that carbon is partitioned to each stream in proportion to the inverse of the cost of uptake. So, more expensive pathways receive less carbon. Earlier versions of FUN :ref:`(Fisher et al., 2010))` utilized a scheme whereby plants only took up N from the cheapest pathway. :ref:`Brzostek et al. (2014)` introduced a scheme for the simultaneous uptake from different pathways. Here we calcualate a 'conductance' to N uptake (analagous to the inverse of the cost function conceptualized as a resistance term) :math:`N_{conductance}` ( gN/gC) as: +The total cost of N uptake is calculated based on the assumption that carbon is partitioned to each stream in proportion to the inverse of the cost of uptake. So, more expensive pathways receive less carbon. Earlier versions of FUN :ref:`(Fisher et al., 2010)`) utilized a scheme whereby plants only took up N from the cheapest pathway. :ref:`Brzostek et al. (2014)` introduced a scheme for the simultaneous uptake from different pathways. Here we calcualate a 'conductance' to N uptake (analagous to the inverse of the cost function conceptualized as a resistance term) :math:`N_{conductance}` ( gN/gC) as: .. math:: diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 924e265b0a..35c50dc038 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -1,13 +1,12 @@ .. _rst_References: +References +============== .. |br| raw:: latex \\ -References -============== - .. _Aberetal1990: |br| @@ -680,7 +679,7 @@ Fisher, J. B., S. Sitch, Y. Malhi, R. A. Fisher, C. Huntingford, and S.-Y. Tan, Fisher, R. A., S. Muszala, M. Verteinstein, P. Lawrence, C. Xu, N. G. McDowell, R. G. Knox, C. Koven, J. Holm, B. M. Rogers, A. Spessa, D. Lawrence, and G. Bonan, 2015: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED). Geosci. Model Dev., 8: 3593-3619, doi:10.5194/gmd-8-3593-2015. -.. _Fisheretal2017: +.. _Fisheretal2018: |br| @@ -1701,7 +1700,7 @@ Mary, B., Fresneau, C., Morel, J.L. and Mariotti, A., 1993. C and N cycling during decomposition of root mucilage, roots and glucose in soil. Soil Biology and Biochemistry 25:1005-1014. -.. _mcdowell2013: +.. _Mcdowelletal2013: |br| @@ -2143,6 +2142,12 @@ millennial-scale deglaciation simulations. Geophys. Res. Lett. ** Purves, D.W. et al., 2008. Predicting and understanding forest dynamics using a simple tractable model. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. +.. _Qianetal2006: + +|br| + +Qian, T et al., 2006. Simulation of global land surface conditions from 1948 to 2004: Part I: Forcing data and evaluations. J. Hydrometeorology 7, pp. 953-975. + .. _RamankuttyFoley1998: |br| @@ -2661,7 +2666,7 @@ fire disturbance for global vegetation dynamics: coupling fire into a Dynamic Global Vegetation Model. Global Ecology and Biogeography 10:661-667. -.. _thonicke2010: +.. _thonickeetal2010: |br| From 15c1d946d2b2e291606fcba917cf729a73c69924 Mon Sep 17 00:00:00 2001 From: Leo van Kampenhout Date: Mon, 5 Feb 2018 10:33:02 +0100 Subject: [PATCH 151/255] make snow doc consistent with code overburden compaction parameter c_eta = 450 kg/m3 in the code. This should have been 358 kg/m3 but it's too late to make that change now, this is post-CESM2. This commit updates the doc to make the doc consistent with the code. also see: https://github.com/ESCOMP/ctsm/pull/250 --- .../tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index d0022225b0..8d22a19bc9 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -554,7 +554,7 @@ temperature as with constant factors :math:`\eta _{0} = 7.62237 \times 10^{6}` kg s\ :sup:`-1` m\ :sup:`-2`, :math:`a_{\eta} = 0.1` K\ :sup:`-1`, :math:`b_{\eta} = 0.023` m\ :sup:`-3` kg\ :sup:`-1`, -and :math:`c_{\eta} = 358` kg m\ :sup:`-3` (:ref:`van Kampenhout et al. (2017) `). +and :math:`c_{\eta} = 450` kg m\ :sup:`-3` (:ref:`van Kampenhout et al. (2017) `). Further, factor :math:`f_1` accounts for the presence of liquid water (:ref:`Vionnet et al. (2012) `): .. math:: From f56195fa5cb5661b186fb69d36cbdf5b15b95cd1 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 6 Feb 2018 08:14:28 -0700 Subject: [PATCH 152/255] Edit authors and update html --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 3fc79b5e09..08bdf4ec29 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -5,7 +5,7 @@ ***Coordinating Lead Authors*** -**David Lawrence, Rosie Fisher, Charles Koven, Keith Oleson, Sean Swenson** +**David Lawrence, Rosie Fisher, Charles Koven, Keith Oleson, Sean Swenson, Mariana Vertenstein** ***Lead Authors*** @@ -14,7 +14,7 @@ ***Contributing Authors*** **Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, -L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Mariana Vertenstein, Francis Vitt, Xubin Zeng** +L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** The National Center for Atmospheric Research (NCAR) is operated by the From 4b60d25e5782c2392ef591b4cec7e27d74ad464d Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 8 Feb 2018 14:23:47 -0700 Subject: [PATCH 153/255] Add disclaimer for Users Guide --- doc/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index f7f35abeda..517f62e8eb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,7 +6,7 @@ Welcome to the CLM documentation ================================== -This document has two major sections. +This document has two major sections. NOTE THAT THE USER'S GUIDE CURRENTLY PROVIDES INSTRUCTIONS FOR CLM4.5 AND IS A WORK IN PROGRESS. .. toctree:: :maxdepth: 2 From 9691ce7d15e40b938227f1763d952b4a0decee37 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 26 Feb 2018 09:11:44 -0700 Subject: [PATCH 154/255] Update Transient Landcover chapter for CLM5 Much of the information there was no longer correct for CLM5, so I have rewritten much of this chapter. Also, small tweaks to the Glacier chapter. --- .../Glacier/CLM50_Tech_Note_Glacier.rst | 11 +- .../CLM50_Tech_Note_Transient_Landcover.rst | 379 +++++++++++------- 2 files changed, 240 insertions(+), 150 deletions(-) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index cb11d05c76..9f6c79ff98 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -144,9 +144,12 @@ different regions (four by default) that differ in three respects: #. Treatment of glacial melt water: a. Glacial melt water runs off and is replaced by ice, thus keeping - the column always frozen. This behavior is discussed in more - detail in section :numref:`Computation of the surface mass - balance`. + the column always frozen. In the absence of a dynamic ice sheet + model, this behavior implicitly assumes an infinite store of + glacial ice that can be melted (with appropriate adjustments made + to ensure mass and energy conservation). This behavior is + discussed in more detail in section :numref:`Computation of the + surface mass balance`. b. Glacial melt water remains in place until it refreezes - possibly remaining in place indefinitely if the glacier column is in a warm @@ -243,7 +246,7 @@ mean grid cell elevation to the *glacier\_mec* column elevation using a specified lapse rate (typically 6.0 deg/km) and an assumption of uniform relative humidity. Longwave radiation is downscaled by assuming a linear decrease in downwelling longwave radiation with increasing elevation -(0.032 W m :sup:`-2` m :sup:`-1`, limited to 0.5 - 1.5 times the +(0.032 W m\ :sup:`-2` m\ :sup:`-1`, limited to 0.5 - 1.5 times the gridcell mean value, then normalized to conserve gridcell total energy) :ref:`(Van Tricht et al., 2016)`. Total precipitation is partitioned into rain vs. snow as described in Chapter diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index ebb6d3762b..de7ef86173 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -1,156 +1,243 @@ .. _rst_Transient Landcover Change: Transient Land Use and Land Cover Change -=========================================== +======================================== CLM includes a treatment of mass and energy fluxes associated with -prescribed temporal land use and land cover change (LULCC). The model uses an annual -time series of the spatial distribution of the natural and crop land units -of each grid cell, in combination with the distribution of PFTs and CFTs -that exist in those land units. Additional land use is prescribed through annual -crop specific management of nitrogen fertilizer and irrigation described further -in Chapter 25, and through wood harvest on tree PFTs. For changes in the distributions -of natural and crop vegetation CLM diagnoses the change in area of the PFTs and CFTs -on January 1st of each model year and then performs mass and energy balance accounting -necessary to represent the expansion and contraction of the PFT and CFT areas. The -biogeophysical impacts of LULCC are simulated through changes -in surface properties which in turn impact the surface albedo, hydrology, and roughness -which then impact fluxes of energy, moisture and momentum to the atmosphere under the -altered properties. Additionally changes in energy and moisture associated with changes -in the natural and crop vegetation distribution are accounted for through small -fluxes to the atmosphere. The biogeochemical impacts of LULCC -are simulated through changes in CLM carbon pools and fluxes as shown in Figure xx.x and -described further in Chapter 16. - -Annual Transient Land Use and Land Cover Data and Time Interpolation ------------------------------------------------------------------------ - -The changes in area over time associated with changes in natural and crop -vegetation and the land use on that vegetation are prescribed through a forcing dataset, -referred to here as the *landuse.timeseries* dataset. The *landuse.timeseries* dataset -consists of an annual time series of global grids, where each annual time slice describes -the fractional area occupied by all PFTs and CFTs along with the nitrogen fertilizer and -irrigation fraction of each crop CFT, and the annual wood harvest applied to tree PFTs. -Changes in area of PFTs and CFTs are performed annually on the first time step of January -1st of the year. Fertilizer application, irrigation and wood harvest for each PFT and CFT -are performed at each model time step depending on rules from the crop and natural vegetation -phenology models. The irrigation fraction is set annually however fertlizer application and -wood harvest are set from a time-interpolation of the application rates from the two bracketing -annual time slices in the *landuse.timeseries* dataset. - -As a special case, when the time dimension of the *landuse.timeseries* dataset -starts at a later year than the current model time step, the first time -slice from the *landuse.timeseries* dataset is used to represent the current time -step PFT and CFT fractional area distributions. Similarly, when the time -dimension of the *landuse.timeseries* dataset stops at an earlier year than the -current model time step, the last time slice of the *landuse.timeseries* dataset is -used. Thus, the simulation will have invariant representations of PFT and CFT -distributions through time for the periods prior to and following the -time duration of the *landuse.timeseries* dataset, with transient PFT and CFT distributions -during the period covered by the *landuse.timeseries* dataset. - -The following equations capture this logic, where :math:`year_{cur}` is -the calendar year for the current timestep, -:math:`landuse.timeseries\_ year(1)` and -:math:`landuse.timeseries\_ year(nyears)` are the first and last calendar years in -the *landuse.timeseries* dataset, respectively, :math:`nyears` is the number of -years in the *landuse.timeseries* dataset, :math:`nt_{1}` and :math:`nt_{2}` -are the two bracketing years used in the interpolation -algorithm, and :math:`n` is the index value for the -:math:`landuse.timeseries\_ year` array corresponding to -:math:`landuse.timeseries\_ year(n)=year_{cur}` : - -.. math:: - :label: 26.1) - - nt_{1} =\left\{\begin{array}{l} {1\qquad {\rm for}\qquad year_{cur} 0` and decreases for -:math:`\Delta w_{p} <0`. +prescribed temporal land use and land cover change (LULCC). The model +uses an annual time series of the spatial distribution of the natural +and crop land units of each grid cell, in combination with the +distribution of PFTs and CFTs that exist in those land units. Additional +land use is prescribed through annual crop-specific management of +nitrogen fertilizer and irrigation (described further in +:numref:`rst_Crops and Irrigation`), and through wood harvest on tree +PFTs. For changes in the distributions of natural and crop vegetation, +CLM diagnoses the change in area of the PFTs and CFTs on January 1 of +each model year and then performs mass and energy balance accounting +necessary to represent the expansion and contraction of the PFT and CFT +areas. The biogeophysical impacts of LULCC are simulated through changes +in surface properties which in turn impact the surface albedo, +hydrology, and roughness which then impact fluxes of energy, moisture +and momentum to the atmosphere under the altered +properties. Additionally, changes in energy and moisture associated with +changes in the natural and crop vegetation distribution are accounted +for through small fluxes to the river and atmosphere. The biogeochemical +impacts of LULCC are simulated through changes in CLM carbon pools and +fluxes (see also Chapter :numref:`rst_CN Pools`). + +CLM can also respond to changes in ice sheet areas and elevations when +it is coupled to an evolving ice sheet model (in the CESM context, this +is the Community Ice Sheet Model, CISM; see also Chapter +:numref:`rst_Glaciers`). Conservation of water, energy, carbon and +nitrogen is handled similarly for glacier-vegetation transitions as for +natural vegetation-crop transitions. + +.. _Transient land use and land cover data: + +Annual Transient Land Use and Land Cover Data +--------------------------------------------- + +The changes in area over time associated with changes in natural and crop vegetation and +the land use on that vegetation are prescribed through a forcing dataset, referred to here +as the *landuse.timeseries* dataset. The *landuse.timeseries* dataset consists of an +annual time series of global grids, where each annual time slice describes the fractional +area occupied by all PFTs and CFTs along with the nitrogen fertilizer and irrigation +fraction of each crop CFT, and the annual wood harvest applied to tree PFTs. Changes in +area of PFTs and CFTs are performed annually on the first time step of January 1 of the +year. Wood harvest for each PFT is also performed on the first time step of the +year. Fertilizer application and irrigation for each CFT are performed at each model time +step depending on rules from the crop model. Fertilizer application rates are set +annually. The irrigation fraction is also set annually; irrigated crops are placed on +separate columns from their unirrigated counterparts, so changes in irrigated fraction +triggers the changes in subgrid areas discussed below (sections :numref:`Transient +landcover reconciling changes in area` and :numref:`Transient landcover mass and energy +conservation`). + +As a special case, when the time dimension of the *landuse.timeseries* dataset starts at a +later year than the current model time step, the first time slice from the +*landuse.timeseries* dataset is used to represent the current time step PFT and CFT +fractional area distributions. Similarly, when the time dimension of the +*landuse.timeseries* dataset stops at an earlier year than the current model time step, +the last time slice of the *landuse.timeseries* dataset is used. Thus, the simulation will +have invariant representations of PFT and CFT distributions through time for the periods +prior to and following the time duration of the *landuse.timeseries* dataset, with +transient PFT and CFT distributions during the period covered by the *landuse.timeseries* +dataset. + +.. _Transient landcover reconciling changes in area: + +Reconciling Changes in Area +--------------------------- + +In the first time step of January 1, changes in land unit weights can +potentially come from two sources: Changes in the area of the crop land +unit come from the *landuse.timeseries* dataset (section +:numref:`Transient land use and land cover data`), and changes in the +area of the glacier land unit come from the ice sheet model. The areas +of other land units are then adjusted so that the total land unit area +remains 100%. + +If the total land unit area of glaciers and crops has decreased, then +the natural vegetated landunit is increased to fill in the abandoned +land. If the total land unit area of glaciers and crops has increased, +then other land unit areas are decreased in a specified order until the +total is once again 100%. The order of decrease is: natural vegetation, +crop, urban medium density, urban high density, urban tall building +district, wetland, lake. + +These rules have two important implications: + +1. We always match CISM's glacier areas exactly, even if that means a + disagreement with prescribed crop areas. This is needed for + conservation when CISM is evolving in two-way-coupled mode. + +2. For land units other than crop, glacier and natural vegetation, their + areas can decrease (due to encroaching crops or glaciers), but can + never increase. So, for example, if a grid cell starts as 5% lake, + crops expand to fill the entire grid cell, then later crop area + decreases, the lake area will not return: instead, the abandoned + cropland will become entirely natural vegetation. + +For all levels of the subgrid hierarchy (land unit, column and patch), +we only track net changes in area, not gross transitions. So, for +example, if part of a gridcell experiences an increase in glacier area +while another part of that gridcell experiences an equal decrease in +glacier area (in the same glacier elevation class), CLM acts as if there +were no changes. As another example, consider a gridcell containing +natural vegetation, crop and glacier. If there is a decrease in glacier +area and an equal increase in crop area, CLM will assume that the crop +expands into the old glacier area, and nothing happened to the natural +vegetation area. A more realistic alternative would be that the crop +expanded into natural vegetation, and natural vegetation expanded into +glacier. The final areas will be correct in these cases, but the +adjustments of carbon and nitrogen states (section :numref:`Transient +landcover carbon and nitrogen conservation`) will be less accurate than what +would be obtained with a full tracking of gross transitions. + +.. _Transient landcover mass and energy conservation: Mass and Energy Conservation ---------------------------------- - -Mass conservation is maintained across PFT and CFT weight transitions by -summing up all the carbon, nitrogen, water and energy state variables to get the total vegetated land -units value before (:math:`W_{tot,1}` ) and after -(:math:`W_{tot,2}` ) the new PFT and CFT weights are calculated. Transitions are performed on above ground -variables first and then at the land unit level for below ground variables second. For example the hydrological -balance is calculated, -:math:`W_{tot,1}` is - -.. math:: - :label: 26.6) - - W_{tot,1} =W_{a} +W_{sno} +\sum _{i=1}^{N_{levgrnd} }\left(w_{liq,i} +w_{ice,i} \right) +\sum _{j=1}^{npft}\left(W_{can,j} wt_{j,1} \right) - -where :math:`W_{a}` is the aquifer water, :math:`W_{sno}` is the snow -water, :math:`w_{liq,i}` and :math:`w_{ice,i}` are the liquid and ice -soil water contents, :math:`W_{can,j}` is the canopy water content for -PFT and CFT :math:`j`, and :math:`wt_{j,1}` is the PFT or CFT weight for -:math:`j`. For the situation where PFT and CFT weights are changing, any difference -between :math:`W_{tot,1}` and :math:`W_{tot,2}` are due to -differences in the total canopy water before and after the PFT and CFT weight -change. To ensure conservation, the typically very small -difference between :math:`W_{tot,2}` and :math:`W_{tot,1}` is -subtracted from the grid cell runoff - -.. math:: - :label: 26.7) - - R_{liq} =R_{liq} +W_{tot,2} -W_{tot,1} . - -Total energy is unperturbed in this case and therefore an energy -conservation treatment is not required. Changing the area of natural and crop land units -in association with the change in PFTs and CFTs results in changes in the soil/snow columns -and land unit area. To address these additional changes, conservation of mass and -energy among the soil/snow columns and land units is performed as a secondary calculation once -all above ground PFT and CFT changes have been done. +---------------------------- + +.. _Transient landcover water and energy conservation: + +Water and Energy Conservation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When subgrid areas change, the water and energy states remain unchanged +on a per-area basis. This can lead to changes in the total gridcell +water and energy content. + +For example, consider a gridcell with two columns: column 1 has a water +mass of 1 kg m\ :sup:`-2` and column 2 has a water mass of 2 kg m\ +:sup:`-2` for a given water state variable, where these are expressed +per unit column area. If column 1 increases in area at the expense of +column 2, then column 1 will still have a water mass of 1 kg m\ +:sup:`-2`, but now expressed over the new column area. This results in a +decrease in the total gridcell water content. + +Water and energy are conserved by summing up the total water and energy +content of each gridcell before and after a change in area. Differences +in liquid and ice water content are balanced by liquid and ice runoff +terms, which can be either positive or negative. (Negative runoff is +effectively a withdrawal of water from the ocean.) Differences in energy +content are balanced by a sensible heat flux term, which again can be +either positive or negative. These balancing fluxes are spread evenly +throughout the following year. + +There is a special case when a given crop column type newly comes into +existence - for example, when temperate corn first comes into existence +in a gridcell. In this case, the column's below-ground temperature and +water states are copied from the natural vegetated column in its +gridcell, so that these state variables begin in a close-to-spun-up +state. Other state variables (most of which spin up relatively quickly) +begin at their cold start initialization values. This initialization is +not necessary for the two other land unit types that currently can +grow - natural vegetation and glacier: Those land unit types are always +active, even when they have zero area on the gridcell, so their state +variables will be spun up immediately when they come into +existence. After this initialization, the conservation code described +above takes effect. + +.. _Transient landcover carbon and nitrogen conservation: + +Carbon and Nitrogen Conservation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Because of the long timescales involved with below-ground carbon and +nitrogen dynamics, it is more important that these state variables be +adjusted properly when subgrid areas change. Carbon and nitrogen +variables are adjusted with the following three-step process: + +(1) Patch-level (i.e., vegetation) state variables are adjusted for any + changes in patch areas; this may lead to fluxes into column-level + (i.e., soil) state variables + +(2) Column-level (i.e., soil) state variables are updated based on the + fluxes generated in (1) + +(3) Column-level (i.e., soil) state variables are adjusted for any + changes in column areas + +First, patch-level (i.e., vegetation) state variables are adjusted for +any changes in patch areas. This includes changes in column or land unit +areas, even if the relative proportions of each patch remain constant: +the relevant quantities are the patch weights relative to the +gridcell. + +For a patch that decreases in area, the carbon and nitrogen density on +the remaining patch area remains the same as before (i.e., expressed as +g per m\ :sup:`2` patch area). Because the area has decreased, this +represents a decrease in total carbon or nitrogen mass (i.e., expressed +as g per m\ :sup:`2` gridcell area). The lost mass meets a variety of +fates: some is immediately lost to the atmosphere, some is sent to +product pools (which are lost to the atmosphere over longer time +scales), and some is sent to litter pools. + +For a patch that increases in area, the carbon and nitrogen density on +the new patch area is decreased in order to conserve mass. This decrease +is basically proportional to the relative increase in patch +area. However, a small amount of seed carbon and nitrogen is added to +the leaf and dead stem pools in the new patch area. + +Next, column-level (i.e., soil) state variables are updated based on any +fluxes to soil pools due to decreases in patch areas. This step is +needed so that any lost vegetation carbon and nitrogen is conserved when +column areas are changing. + +Finally, column-level state variables are adjusted for any changes in +column areas. Similarly to patches, for a column that decreases in area, +the carbon and nitrogen density on the remaining column area remains the +same as before (i.e., expressed as g per m\ :sup:`2` column area). This +represents a decrease in total carbon or nitrogen mass on the gridcell, +and this lost mass is tracked for each gridcell. After these mass losses +are summed for all shrinking columns, they are distributed amongst the +growing columns in order to conserve mass. Thus, a growing column's new +carbon density will be a weighted sum of its original carbon density and +the carbon densities of all shrinking columns in its gridcell. + +This operation makes some simplifying assumptions. First, as described +in section :numref:`Transient landcover reconciling changes in area`, we +only track net area changes, not gross changes. Second, we assume that +growing columns all grow proportionally into each of the shrinking +columns. + +Non-vegetated land units (e.g., glacier) do not typically track soil +carbon and nitrogen. When columns from these land units initially +shrink, they are assumed to contribute zero carbon and +nitrogen. However, when they grow into previously-vegetated areas, they +store any pre-existing soil carbon and nitrogen from the shrinking +columns. This stored carbon and nitrogen will remain unchanged until the +column later shrinks, at which point it will contribute to the carbon +and nitrogen in the growing columns (exactly as would happen for a +vegetated column). + +In contrast to water and energy (section :numref:`Transient landcover +water and energy conservation`), no special treatment is needed for +carbon and nitrogen states in columns that newly come into +existence. The state of a new column is derived from a weighted average +of the states of shrinking columns. This behavior falls out from the +above general rules. Annual Transient Land Cover Dataset Development ---------------------------------------------------- From 48c80453b445172de984e5b0eeffa7f08be935dc Mon Sep 17 00:00:00 2001 From: Sean Swenson Date: Wed, 28 Feb 2018 12:14:34 -0700 Subject: [PATCH 155/255] add bedrock reference --- doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 86b3bbb5a9..d90c8cab40 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -345,7 +345,9 @@ The hydrologically and biogeochemically active portion of the soil column can be restricted to a thickness less than that of the maximum soil depth. By providing a depth-to-bedrock dataset, which may vary spatially, the number of layers used in the hydrologic and biogeochemical calculations, :math:`N_{bedrock}`, may be -specified, subject to the constraint :math:`N_{bedrock} \le N_{levsoi}` +specified, subject to the constraint :math:`N_{bedrock} \le N_{levsoi}`. +The default depth-to-bedrock values are from +:ref:`Pelletier et al. [2016]`. .. _Model Input Requirements: From 21361da3d5c99e2c1f70b16da0415c8a6e3b9db0 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Wed, 28 Feb 2018 14:46:10 -0700 Subject: [PATCH 156/255] Modifications to photosynthesis tech note to remove 'ask rosie' references --- .../CLM50_Tech_Note_Photosynthesis.rst | 91 ++++++------------- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 2 +- 2 files changed, 29 insertions(+), 64 deletions(-) diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index 258fa3f182..84136f7868 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -14,7 +14,7 @@ CLM5 includes the following new changes to photosynthesis and stomatal conductan - Default stomatal conductance calculation uses the Medlyn conductance model -- :math:`J_{max}` is predicted by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) +- :math:`V_{c,max}` and :math:`J_{max}` at 25 :sup:`\o`\ C: are now prognostic, and predicted via optimality by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) - Leaf N concentration and the fraction of leaf N in Rubisco used to calculate :math:`V_{cmax25}` are determined by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) @@ -255,20 +255,21 @@ depend on temperature. Values at 25 :sup:`o` \ C are :math:`K_{o25} =278.4\times 10^{-3} P_{atm}`, and :math:`\Gamma _{25} {\rm =42}.75\times 10^{-6} P_{atm}`. :math:`V_{c\max }`, :math:`J_{\max }`, :math:`T_{p}`, :math:`k_{p}`, -and :math:`R_{d}` also vary with temperature. Parameter values at 25 -[verify with Rosie that LUNA doesn't do this otherwise] -:sup:`o`\ C are calculated from :math:`V_{c\max }` \ at 25 -:sup:`\o`\ C: :math:`J_{\max 25} =1.97V_{c\max 25}`, +and :math:`R_{d}` also vary with temperature. + +:math:`J_{\max 25}` at 25 :sup:`\o`\ C: is calculated by the LUNA model (Chapter :numref:`rst_Photosynthetic Capacity`) + +Parameter values at 25 :sup:`\o`\ C are calculated from :math:`V_{c\max }` \ at 25 +:sup:`\o`\ C:, including: :math:`T_{p25} =0.167V_{c\max 25}`, and :math:`R_{d25} =0.015V_{c\max 25}` (C\ :sub:`3`) and -:math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). For -C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}`. -However, when the biogeochemistry is active, :math:`R_{d25}` is -calculated from leaf nitrogen as :math:`R_{d25} = 0.2577LNC_{a}`, -where :math:`LNC_{a}` is the area-based leaf nitrogen concentration -(g N m\ :sup:`-2` leaf area, Chapter :numref:`rst_Photosynthetic Capacity`), -and 0.2577 :math:`\mu`\ mol CO\ :sub:`2` g\ :sup:`-1` N s\ :sup:`-1` is the base respiration rate. -[this doesn't look correct based on the code, which lists two options; verify with Rosie] +:math:`R_{d25} =0.025V_{c\max 25}` (C\ :sub:`4`). + +For C\ :sub:`4` plants, :math:`k_{p25} =20000\; V_{c\max 25}`. + +However, when the biogeochemistry is active (the default mode), :math:`R_{d25}` is +calculated from leaf nitrogen as described in (Chapter :numref:`rst_Plant Respiration`) + The parameters :math:`V_{c\max 25}`, :math:`J_{\max 25}`, :math:`T_{p25}`, :math:`k_{p25}`, and :math:`R_{d25}` are scaled over the canopy for sunlit and shaded leaves @@ -280,8 +281,6 @@ The parameters :math:`V_{c\max 25}`, \begin{array}{rcl} {V_{c\max } } & {=} & {V_{c\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {J_{\max } } & {=} & {J_{\max 25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {T_{p} } & {=} & {T_{p25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {R_{d} } & {=} & {R_{d25} \; f\left(T_{v} \right)f_{H} \left(T_{v} \right)} \\ {K_{c} } & {=} & {K_{c25} \; f\left(T_{v} \right)} \\ {K_{o} } & {=} & {K_{o25} \; f\left(T_{v} \right)} \\ {\Gamma } & {=} & {\Gamma _{25} \; f\left(T_{v} \right)} \end{array} -[check with Rosie about Rd equation above and below (eq. 14)] with - .. math:: :label: 9.11 @@ -384,64 +383,30 @@ range :math:`T_{10} -T_{f} \ge 11`\ :sup:`o`\ C and :math:`T_{10} -T_{f} \le 35` Canopy scaling -------------------------------------------- -:math:`V_{c\max 25}` is calculated separately for sunlit and shaded -leaves using an exponential profile to area-based leaf nitrogen -(:math:`LNC_{a}`, see Chapter :numref:`rst_Photosynthetic Capacity` ), -as in :ref:`Bonan et al. (2011)`. :math:`V_{c\max 25}` at -cumulative leaf area index :math:`x` from the canopy top scales directly -with :math:`LNC_{a}` , which decreases exponentially with greater -cumulative leaf area, so that [Verify with Rosie- different based on Vcmax option 0, 3, & 4] - -.. math:: - :label: 9.18 - - V_{c\; \max 25}^{} \left(x\right)=V_{c\; \max 25}^{} \left(0\right)e^{-K_{n} x} - -where :math:`V_{c\; \max 25}^{} \left(0\right)` is defined at the top of -the canopy using :math:`SLA_{0}`, which is the specific leaf area at -the canopy top and :math:`K_{n}` is the decay -coefficient for nitrogen. The canopy integrated value for sunlit and -shaded leaves is - -.. math:: - :label: 9.20 +When LUNA is on, the :math:`V_{c\max 25}` for sun leaves is scaled to the shaded leaves +:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}`, and +:math:`R_{d25}` scale similarly. - \begin{array}{rcl} {V_{c\; \max 25}^{sun} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)f_{sun} \left(x\right)\, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} } \end{array} .. math:: - :label: 9.21 - - \begin{array}{rcl} {V_{c\; \max 25}^{sha} } & {=} & {\int _{0}^{L}V_{c\; \max 25}^{} \left(x\right)\left[1-f_{sun} \left(x\right)\right] \, dx} \\ {} & {=} & {V_{c\; \max 25}^{} \left(0\right)\left\{\left[1-e^{-K_{n} L} \right]\frac{1}{K_{n} } -\left[1-e^{-\left(K_{n} +K\right)L} \right]\frac{1}{K_{n} +K} \right\}} \end{array} + :label: 9.18 -and the average value for the sunlit and shaded leaves is + \begin{array}{rcl} + {V_{c\max 25 sha}} & {=} & {V_{c\max 25 sha} \frac{i_{v,sha}}{i_{v,sun}}} \\ + {J_{\max 25 sha}} & {=} & {J_{\max 25 sun} \frac{i_{v,sha}}{i_{v,sun}}} \\ + {T_{p sha}} & {=} & {T_{p sun} \frac{i_{v,sha}}{i_{v,sun}}} \end{array} -.. math:: - :label: 9.22 - - \bar{V}_{c\; \max 25}^{sun} ={V_{c\; \max 25}^{sun} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sun} L^{sun} }} \right. \kern-\nulldelimiterspace} L^{sun} } +Where :math:`i_{v,sun}` and :math:`i_{v,sha}` are the leaf-to-canopy scaling coefficients of the twostream radiation model, calculated as .. math:: - :label: 9.23 - - \bar{V}_{c\; \max 25}^{sha} ={V_{c\; \max 25}^{sha} \mathord{\left/ {\vphantom {V_{c\; \max 25}^{sha} L^{sha} }} \right. \kern-\nulldelimiterspace} L^{sha} } . + :label: 9.19 -This integration is over all leaf area (:math:`L`) with -:math:`f_{sun} (x)=\exp \left(-Kx\right)` and :math:`K` the direct beam -extinction coefficient (equation :eq:`4.8` in chapter :numref:`rst_Radiative Fluxes`). Photosynthetic parameters -:math:`J_{\max 25}` , :math:`T_{p25}` , :math:`k_{p25}`, and -:math:`R_{d25}` scale similarly. + i_{v,sun} = \frac{(1 - e^{-(k_{n,ext}+k_{b,ext})*lai_e)} / (k_{n,ext}+k_{b,ext})}{f_{sun}*lai_e}\\ + i_{v,sha} = \frac{(1 - e^{-(k_{n,ext}+k_{b,ext})*lai_e)} / (k_{n,ext}+k_{b,ext})}{(1 - f_{sun})*lai_e} -The model uses :math:`K_{n} =0.30` to match an explicit multi-layer canopy, as in -:ref:`Bonan et al. (2012)`. -The value :math:`K_{n} = 0.11` chosen by :ref:`Bonan et al. (2011)` is -consistent with observationally-derived estimates for forests, mostly -tropical, and provides a gradient in V\ :sub:`cmax` similar to -the original CLM4 specific leaf area scaling. However, -:ref:`Bonan et al. (2012)` showed that the sunlit/shaded canopy parameterization does not -match an explicit multi-layer canopy parameterization. The discrepancy -arises from absorption of scattered radiation by shaded leaves and can -be tuned out with higher :math:`K_{n}`. +k_{n,ext} is the extinction coefficient for N through the canopy (0.3). k_{b,ext} is the direct beam extinction coefficient calculated in the surface albedo routine, and :math:`f_{sun}` is the fraction of sunlit leaves, both derived from Chapter :numref:`rst_Surface Albedos`. +When LUNA is off, scaling defaults to the mechanism used in CLM4.5. .. _Numerical implementation photosynthesis: diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index c47ce0e624..4c3e857ade 100755 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -142,7 +142,7 @@ Following Bauerle et al. (2012), :math:`f\left(\text{day length} \right)` is sim f\left(\text{day length} \right) = \left(\frac{\text{day length}}{12} \right)^{2}. -:math:`f\left(\text{humidity} \right)` represents the impact of air humitidy on +:math:`f\left(\text{humidity} \right)` represents the impact of air humidity on :math:`J_{\text{{max}}}`. We assume that higher humidity leads to higher :math:`J_{\text{{max}}}` with less water limiation on stomta opening and that low relative humidity has a stronger impact on nitrogen allocation due to greater From b7cc3082250b578ac12784554790fb64427757c4 Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Wed, 28 Feb 2018 15:15:35 -0700 Subject: [PATCH 157/255] Modifications to FATES fire documentation --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 8d44f55216..01442e5eb9 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -974,7 +974,7 @@ thus \delta_{vai} \cdot f_{leaf,coh} \frac{A_{canopy,coh}}{A_{canopy,patch}}\cdot r_{vai}& \textrm{for $i=n_{z,coh}$}\\ \end{array} \right. - and the stem area index is +and the stem area index is .. math:: @@ -3127,7 +3127,7 @@ Nesterov Index Dead fuel moisture (:math:`\emph{moist}_{df,fc}`), and several other properties of fire behaviour, are a function of the ‘Nesterov Index’ (:math:`N_{I}`) which is an accumulation over time of a function of -temperature and humidity (Eqn 5, :ref:`Thonicke et al. 2010`). +temperature and humidity (Eqn 5, :ref:`Thonicke et al. 2010`), .. math:: N_{I}=\sum{\textrm{max}(T_{d}(T_{d}-D),0)} @@ -3142,6 +3142,7 @@ where :math:`T_{d}` is the daily mean temperature in :math:`^{o}`\ C and where :math:`RH` is the relative humidity (%). +On days when the total precipitation exceeds 3.0mm, the Nesterov index accumulator is reset back to zero. Fuel properties --------------- @@ -3239,7 +3240,7 @@ Forward rate of spread For each patch and each day, we calculate the rate of forward spread of the fire *ros*\ :math:`_{f}` (nominally in the direction of the wind). -.. math:: \emph{ros}_{f}=\frac{i_{r}x_{i}(1-\phi_{w})}{F_{bd,patch}e_{ps}q_{ig}} +.. math:: \emph{ros}_{f}=\frac{i_{r}x_{i}(1+\phi_{w})}{F_{bd,patch}e_{ps}q_{ig}} :math:`e_{ps}` is the effective heating number (:math:`e^{\frac{-4.528}{F_{\sigma,patch}}}`). :math:`q_{ig}` is the @@ -3249,10 +3250,7 @@ Appendix A). .. math:: - x_{i}= \left\{ \begin{array}{ll} - 0.0& \textrm{for $F_{\sigma,patch}<0.00001$}\\ - \frac{e^{0.792+3.7597F_{\sigma,patch}^{0.5}(\frac{F_{bd,patch}}{p_{d}}+0.1)}}{192+7.9095F_{\sigma,patch}} & \textrm{for $F_{\sigma,patch}\geq 0.00001$}\\ - \end{array} \right. + x_{i}= \frac{e^{0.792+3.7597F_{\sigma,patch}^{0.5}(\frac{F_{bd,patch}}{p_{d}}+0.1)}}{192+7.9095F_{\sigma,patch}} :math:`\phi_{w}` is the influence of windspeed on rate of spread. @@ -3331,9 +3329,9 @@ fire, :math:`\mathit{ros}_{f}` (m min\ :math:`^{-1}`) (Eqn 15 .. math:: I_{surface}=\frac{0.001}{60}f_{energy} f_{ctot,patch}\mathit{ros}_{f} -where :math:`f_{energy}` is the energy content of fuel (kJ/kG - the -same for alll fuel classes). Fire intensity is used to define whether an -ignition is successful. If the fire intensity is greater than 50kw/m +where :math:`f_{energy}` is the energy content of fuel (Kj/Kg - the +same, 18000 Kj/Kg for all fuel classes). Fire intensity is used to define whether an +ignition is successful. If the fire intensity is greater than 50Kw/m then the ignition is successful. Fire Duration @@ -3372,7 +3370,7 @@ respectively). :math:`ros_{b}` is a function of :math:`ros_{f}` and windspeed (Eqn 10 :ref:`Thonicke et al. 2010`) -.. math:: ros_{b}=ros_{f}e^{-0.72W} +.. math:: ros_{b}=ros_{f}e^{-0.012W} The minor axis to major axis ratio :math:`l_{b}` of the ellipse is determined by the windspeed. If the windspeed (:math:`W`) is less than From 025d7de236febfbb47d2fcbe5b6477ab68dd969d Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Mon, 5 Mar 2018 16:23:39 -0700 Subject: [PATCH 158/255] modified error notices in FUN tech note --- .../tech_note/DGVM/CLM50_Tech_Note_DGVM.rst | 144 +++--------------- .../tech_note/FUN/CLM50_Tech_Note_FUN.rst | 8 +- .../CLM50_Tech_Note_Plant_Respiration.rst | 11 +- .../References/CLM50_Tech_Note_References.rst | 13 ++ 4 files changed, 49 insertions(+), 127 deletions(-) diff --git a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst index 01442e5eb9..eb6d3370d9 100644 --- a/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst +++ b/doc/source/tech_note/DGVM/CLM50_Tech_Note_DGVM.rst @@ -223,7 +223,7 @@ individual-based approach). A signature feature of the ED model is the system by which `functionally equivalent` patches and cohorts are fused into single model entities to save memory and computational time. -[1]_ This functionality requires that criteria are established for the +This functionality requires that criteria are established for the meaning of `functional equivalence`, which are by necessity slightly subjective, as they represent ways of abstracting reality into a more tractable mathematical representation. As an example of this, for @@ -242,7 +242,7 @@ adjust the trade-off between simulation accuracy and computational load. There is no theoretical optimal value for this threshold but it may be altered to have finer or coarser model resolutions as needed. -[2]_ Similarly, for common-disturbance-history patches, we again assign +Similarly, for common-disturbance-history patches, we again assign a threshold criteria, which is then compared to the difference between patches :math:`m` and :math:`n`, and if the difference is less than some threshold value (:math:`t_{p}`) then patches are merged together, @@ -287,7 +287,7 @@ similar patches reach their fusion threshold. This approach maintains an even discretization along the biomass gradient, in contrast to, for example, simply fusing the oldest or youngest patches together. -[3]_ The area of the new patch (:math:`A_{patch,o}`, m\ :math:`^{2}`) +The area of the new patch (:math:`A_{patch,o}`, m\ :math:`^{2}`) is the sum of the area of the two existing patches, .. math:: A_{patch,o} = A_{patch,n} + A_{patch,m} @@ -300,7 +300,7 @@ with mass conservation . Linked Lists: the general code structure of FATES --------------------------------------------------- -[4]_ The number of patches in each natural vegetation column and the +The number of patches in each natural vegetation column and the number of cohorts in any given patch are variable through time because they are re-calculated for each daily timestep of the model. The more complex an ecosystem, the larger the number of patches and cohorts. For @@ -513,7 +513,7 @@ and passed into the ED code as the major driver of vegetation dynamics. Initialization of vegetation from bare ground ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -[5]_If the model is restarted from a bare ground state (as opposed to a +If the model is restarted from a bare ground state (as opposed to a pre-existing vegetation state), the state variables above are initialized as follows. First, the number of plants per PFT is allocated according to the initial seeding density (:math:`S_{init}`, individuals @@ -584,7 +584,7 @@ biomass, assigned per PFT Allocation of biomass ^^^^^^^^^^^^^^^^^^^^^ -[6]_Total live biomass :math:`b_{alive}` is the state variable of the model +Total live biomass :math:`b_{alive}` is the state variable of the model that describes the sum of the three live biomass pools leaf :math:`b_{leaf}`, root :math:`b_{root}` and sapwood :math:`b_{sw}` (all in kGC individual\ :math:`^{-1}`). The quantities are constrained by the @@ -693,7 +693,7 @@ To calculated the sapwood biomass, we use Canopy Structure and the Perfect Plasticity Approximation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -[7]_During initialization and every subsequent daily ED timestep, the canopy +During initialization and every subsequent daily ED timestep, the canopy structure model is called to determine how the leaf area of the different cohorts is arranged relative to the incoming radiation, which will then be used to drive the radiation and photosynthesis @@ -824,7 +824,7 @@ found in the code references in the footnote. Horizontal Canopy Spread ------------------------- -[8]_:ref:`Purves et al. 2008` estimated the ratio between canopy and +:ref:`Purves et al. 2008` estimated the ratio between canopy and stem diameter :math:`c_{p}` as 0.1 m cm\ :math:`^{-1}` for canopy trees in North American forests, but this estimate was made on trees in closed canopies, whose shape is subject to space competition from other @@ -885,7 +885,7 @@ However, the model is relatively insensitive to the choice of either Definition of Leaf and Stem Area Profile ---------------------------------------- -[9]_Within each patch, the model defines and tracks cohorts of multiple +Within each patch, the model defines and tracks cohorts of multiple plant functional types that exist either in the canopy or understorey. Light on the top leaf surface of each cohort in the canopy is the same, and the rate of decay through the canopy is also the same for each PFT. @@ -932,7 +932,7 @@ is complex and not particularly amenable to the use of, for example, assumptions of random distribution in space that are typically used to calculate leaf area from light interception. :ref:`Kucharik et al. 1998` estimated that SAI visible from an -LAI2000 sensor was around 0.5 m^2 m^-2. :ref:`Low et al. 2001` +LAI2000 sensor was around 0.5 m^2 m^-2. Low et al. 2001 estimate that the wood area index for Ponderosa Pine forest is 0.27-0.33. The existing CLM(CN) algorithm sets the minimum SAI at 0.25 to match MODIS observations, but then allows SAI to rise as a function @@ -1127,7 +1127,7 @@ Radiation Transfer Fundamental Radiation Transfer Theory ------------------------------------- -[10]_The first interaction of the land surface with the properties of +The first interaction of the land surface with the properties of vegetation concerns the partitioning of energy into that which is absorbed by vegetation, reflected back into the atmosphere, and absorbed by the ground surface. Older versions of the CLM have utilized a @@ -1518,7 +1518,7 @@ Photosynthesis Fundamental photosynthetic physiology theory -------------------------------------------- -[11]_In this section we describe the physiological basis of the +In this section we describe the physiological basis of the photosynthesis model before describing its application to the FATES canopy structure. This description in this section is largely repeated from the Oleson et al. CLM4.5 technical note but included here for @@ -1762,7 +1762,7 @@ m\ :math:`^{-2}` s\ :math:`^{-1}`. Water Stress on gas exchange ---------------------------- -[12]_ The top of canopy leaf photosynthetic capacity, :math:`V_{c,max0}`, is +The top of canopy leaf photosynthetic capacity, :math:`V_{c,max0}`, is also adjusted for the availability of water to plants as .. math:: V_{c,max0,25} = V_{c,max0,25} \beta_{sw}, @@ -1918,7 +1918,7 @@ timestep to give KgC cohort\ :math:`^{-1}` day\ :math:`^{-1}` Plant respiration ^^^^^^^^^^^^^^^^^^ -[13]_Plant respiration per individual :math:`R_{plant,coh}` (KgC individual +Plant respiration per individual :math:`R_{plant,coh}` (KgC individual :math:`^{-1}` s\ :math:`^{-1}`) is the sum of two terms, growth and maintenance respiration :math:`R_{g,coh}` and :math:`R_{m,coh}` @@ -2057,7 +2057,7 @@ Stomatal Conductance Fundamental stomatal conductance theory --------------------------------------- -[14]_Stomatal conductance is unchanged in concept from the CLM4.5 approach. +Stomatal conductance is unchanged in concept from the CLM4.5 approach. Leaf stomatal resistance is calculated from the Ball-Berry conductance model as described by :ref:`Collatz et al. (1991)` and implemented in a global climate model by :ref:`Sellers et al. 1996`. The model @@ -2142,7 +2142,7 @@ cohort. Allocation and Growth ^^^^^^^^^^^^^^^^^^^^^ -[15]_Total assimilation carbon enters the ED model each day as a +Total assimilation carbon enters the ED model each day as a cohort-specific Net Primary Productivity :math:`\mathit{NPP}_{coh}`, which is calculated as @@ -2296,7 +2296,7 @@ KgC individual :math:`^{-1}` y\ :math:`^{-1}`) is thus Allocation to growing pools --------------------------- -[16]_ The carbon is then partitioned into carbon available to grow the +The carbon is then partitioned into carbon available to grow the :math:`b_{alive}` and :math:`b_{struc}` pools. A fraction :math:`v_{a}` is available to live biomass pools, and a fraction :math:`v_{s}` is available to structural pools. @@ -2449,7 +2449,7 @@ In this case, :math:`\delta t` is set to be one day Control of Leaf Area Index ^^^^^^^^^^^^^^^^^^^^^^^^^^ -[17]_The leaf area :math:`A_{leaf}` (m:math:`^{-2}`) of each cohort is +The leaf area :math:`A_{leaf}` (m:math:`^{-2}`) of each cohort is calculated from leaf biomass :math:`b_{leaf,coh}` (kgC individual\ :math:`^{-1}`) and specific leaf area (SLA, m\ :math:`^2` kg C\ :math:`^{-1}`) @@ -2548,7 +2548,7 @@ Cold Deciduous Phenology Cold Leaf-out timing ~~~~~~~~~~~~~~~~~~~~ -[18]_. The phenology model of :ref:`Botta et al. 2000` is used in +The phenology model of :ref:`Botta et al. 2000` is used in FATES to determine the leaf-on timing. The Botta et al. model was verified against satellite data and is one of the only globally verified and published models of leaf-out phenology. This model differs from the @@ -2639,7 +2639,7 @@ the science tag is released. Carbon Dynamics of deciduous plants ----------------------------------- -[19]_In the present version, leaf expansion and senescence happen over the +In the present version, leaf expansion and senescence happen over the course of a single day. This is clearly not an empirically robust representation of leaf behaviour, whereby leaf expansion occurs over a period of 10-14 days, and senescence over a similar period. This will be @@ -2718,7 +2718,7 @@ Seed Dynamics and Recruitment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -[20]_The production of seeds and their subsequent germination is a process +The production of seeds and their subsequent germination is a process that must be captured explicitly or implicitly in vegetation models. FATES contains a seed bank model designed to allow the dynamics of seed production and germination to be simulated independently. In the ED1.0 model, seed recruitment occurs in the same timestep as allocation @@ -2841,7 +2841,7 @@ year\ :math:`^{-1}`, are calculated as Litter Inputs ------------- -[21]_Inputs into the litter pools come from tissue turnover, mortality of +Inputs into the litter pools come from tissue turnover, mortality of canopy trees, mortality of understorey trees, mortality of seeds, and leaf senescence of deciduous plants. @@ -2870,7 +2870,7 @@ assigned to each (:math:`f_{lsc}` and :math:`f_{ag}`) Litter Outputs -------------- -[22]_The fragmenting litter pool is available for burning but not for +The fragmenting litter pool is available for burning but not for respiration or decomposition. Fragmentation rates are calculated according to a maximum fragmentation rate (:math:`\alpha_{cwd,lsc}` or :math:`\alpha_{litter}`) which is ameliorated by a temperature and water @@ -2898,7 +2898,7 @@ sensitivity analyses of the model outputs. Flux into decompsition cascade ------------------------------ -[23]_Upon fragmentation and release from the litter pool, carbon is +Upon fragmentation and release from the litter pool, carbon is transferred into the labile, lignin and cellulose decomposition pools. These pools are vertically resolved in the biogeochemistry model. The movement of carbon into each vertical layer is obviously different for @@ -3063,7 +3063,7 @@ fire modelling section. Fire (SPITFIRE) ^^^^^^^^^^^^^^^^^ -[24]_The influence of fire on vegetation is estimated using the SPITFIRE +The influence of fire on vegetation is estimated using the SPITFIRE model, which has been modified for use in ED following it’s original implementation in the LPJ-SPITFIRE model (:ref:`Thonicke et al. 2010`, :ref:`Pfeiffer et al. 2013`). This model as @@ -3501,99 +3501,5 @@ within the area affected by fire is a function of the ratio between | s}` | parameter | | | +-----------------+-----------------+-----------------+-----------------+ -.. raw:: latex - - \bigskip - -| - -.. raw:: latex - - -.. [1] - This description covers algorithms in the ‘fuse_cohorts’ subroutine. - -.. [2] - This description covers algorithms in the ‘fuse_patches’ subroutine. - -.. [3] - This description covers algorithms in the ‘fuse_2_patches’ - subroutine. - -.. [4] - This description covers the structure of code in all modules in - clm4_5 that are located in ‘ED’ subdirectories - -.. [5] - This description covers algorithms in the ‘init_cohorts’ subroutine - -.. [6] - This description relates to algorithms in the allocate_live_biomass - subroutine - -.. [7] - This description relates to algorithms in the EDCanopyStructure - subroutine - -.. [8] - This description relates to algorithms in the canopy_spread - subroutine - -.. [9] - This description relates to algorithms in the - canopy_leaf_area_profile subroutine - -.. [10] - This description relates to algorithms in the ED_norman_radiation - subroutine - -.. [11] - This description relates to algorithms in the ED_photosynthesis - subroutine - -.. [12] - This description relates to algorithms in the ED_btran subroutine - -.. [13] - This description relates to algorithms in the ED_photosynthesis - subroutine - -.. [14] - This description relates to algorithms in the ED_photosynthesis - subroutine - -.. [15] - This description relates to algorithms in the Growth_Derivatives - subroutine - -.. [16] - This description relates to algorithms in the ED_GrowthFunctions - subroutine - -.. [17] - This description relates to algorithms in the trim_canopy subroutine - -.. [18] - This description relates to algorithms in the phenology subroutine - -.. [19] - This description relates to algorithms in the phenology_leafoff - subroutine - -.. [20] - This description relates to algorithms in the seed_in, seed_decay and - seed_germination subroutines - -.. [21] - This description relates to algorithms in the CWD_input, - mortality_litter_fluxes and fire_litter_fluxes subroutines - -.. [22] - This description relates to algorithms in the CWD_out subroutine -.. [23] - This description relates to algorithms in the flux_into_litter_pools - subroutine -.. [24] - This description relates to algorithms in the ’SFMainMod’ subroutines diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index 74dc2cf6dd..1b769042f7 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -175,7 +175,7 @@ First we calculate the cost of extraction (:math:`cost_{retrans}`, gC/gN) for th cost_{retrans}= k_{retrans} / (1/CN_{fallingleaf})^{1.3} -where :math:`k_{retrans}` is a parameter controlling the overall cost of resorption, which also increases exponentially as the C:N ratio increases **Say something about 1.3 exponent**). +where :math:`k_{retrans}` is a parameter controlling the overall cost of resorption, which also increases exponentially as the C:N ratio increases Next, we calculate the amount of C needed to be spent to increase the falling leaf C:N ratio by 1.0 in this iteration :math:`i` (:math:`C_{retrans_spent,i}`, gC m\ :sup:`-2`) as: .. math:: @@ -274,12 +274,12 @@ and the other C and N fluxes can be determined following the logic above. Modifications to allow variation in C:N ratios -------------------------------------------------------- -The original FUN model as developed by :ref:`Fisher et al. (2010)` and :ref:`Brzostek et al. (2014)` assumes a fixed plant tissue C:N ratio. This means that in the case where N is especially limiting, all excess carbon will be utilized in an attempt to take up more Nitrogen. It has been repeatedly observed, however, that in these circumstances in real life, plants have some flexibility in the C:N stoichiometry of their tissues, and therefore, this assumption may not be realistic. **lit review on CN ratios** +The original FUN model as developed by :ref:`Fisher et al. (2010)` and :ref:`Brzostek et al. (2014)` assumes a fixed plant tissue C:N ratio. This means that in the case where N is especially limiting, all excess carbon will be utilized in an attempt to take up more Nitrogen. It has been repeatedly observed, however, that in these circumstances in real life, plants have some flexibility in the C:N stoichiometry of their tissues, and therefore, this assumption may not be realistic. However, the degree to which the C:N ratio varies with N availability is poorly documented, and existing global nitrogen models use a variety of heuristic methods by which to incorporate changing C:N ratios (Zaehle and Friend 2010; Ghimire et al. 2016). This algorithm exists as a placeholder to allow variable C:N ratios to occur, and to allow exploration of how much the parameters controlling their flexibility has on model outcomes. Incorporation of emerging understanding of the controls on tissue stoichiometry should ultimately replace this scheme. Thus, in CLM5, we introduce the capacity for tissue C:N ratios to be prognostic, rather than static. Overall N and C availability (:math:`N_{uptake}` and :math:`C_{growth}`) and hence tissue C:N ratios, are both determined by FUN. Allocation to individual tissues is discussed in the allocation chapter Here we introduce an algorithm which adjusts the C expenditure on uptake to allow varying tissue C:N ratios. Increasing C spent on uptake will directly reduce the C:N ratio, and reducing C spent on uptake (retaining more for tissue growth) will increase it. C spent on uptake is impacted by both the N cost in the environment, and the existing tissue C:N ratio of the plant. The output of this algorithm is :math:`\gamma_{FUN}`, the fraction of the ideal :math:`C_{nuptake}` calculated from -the FUN equation above (**link equation**). +the FUN equation above .. math:: C_{nuptake} = C_{nuptake}.\gamma_{FUN} @@ -297,7 +297,7 @@ where :math:`a_{cnflex}` and :math:`b_{cnflex}` are parameters fitted to give fl Response of C expenditure to plant C:N ratios ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We first calculate a :math:`\delta_{CN}`, which is the difference between the target C:N (:math:`target_{CN}`) a model parameter, and the existing C:N ratio (:math:`CN_{plant}`) **This isn't strictly how it is worked out. Need to remember why we use c_allometry instead**. +We first calculate a :math:`\delta_{CN}`, which is the difference between the target C:N (:math:`target_{CN}`) a model parameter, and the existing C:N ratio (:math:`CN_{plant}`) .. math:: diff --git a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst index 33b9477ed1..8ec6f1d1fb 100644 --- a/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst +++ b/doc/source/tech_note/Plant_Respiration/CLM50_Tech_Note_Plant_Respiration.rst @@ -2,7 +2,9 @@ Plant Respiration ================= - +CLM5 includes changes to plant respiration including + - A new leaf respiration algorithm based on Atkin et al. (2016) + - A lower growth respiration coefficient, based on Atkin et al. (2017) Autotrophic Respiration ---------------------------- @@ -17,7 +19,7 @@ carbon cost for the synthesis of new growth. Maintenance Respiration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Atkin et al. (2016) propose a model for respiration that is based on the leaf nitrogen content per unit area (:math:`NS_{narea}` (gN m :sup:`2` leaf), with an intercept parameter that is PFT dependant, and an acclimation term that depends upon the average temperature of the previous 10 day period :math:`t_{2m,10days}`, in Celsius. +Atkin et al. (2016) propose a model for leaf respiration that is based on the leaf nitrogen content per unit area (:math:`NS_{narea}` (gN m :sup:`2` leaf), with an intercept parameter that is PFT dependant, and an acclimation term that depends upon the average temperature of the previous 10 day period :math:`t_{2m,10days}`, in Celsius. .. math:: :label: 17.46) @@ -89,8 +91,9 @@ Growth Respiration Growth respiration is calculated as a factor of 0.11 times the total carbon allocation to new growth (:math:`CF_{growth}`, after allocating carbon for N acquisition, -Chapter :numref:`rst_FUN`.)on a given timestep, based on construction costs -for a range of woody and non-woody tissues (Atkin et al. in prep). For new +Chapter :numref:`rst_FUN`.) on a given timestep, based on construction costs +for a range of woody and non-woody tissues, with estimates of the growth +respiration flux revised downswards following (Atkin et al. 2017). For new carbon and nitrogen allocation that enters storage pools for subsequent display, it is not clear what fraction of the associated growth respiration should occur at the time of initial allocation, and what diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 35c50dc038..cafba90dc3 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -120,6 +120,19 @@ Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation patterns in spruce and pine trees following irrigation and fertilization. Tree Phys. 2:189-204. +.. _Atkin2016: + +|br| + +Atkin OK, Bloomfield KJ, Reich PB, Tjoelker MG, Asner GP, Bonal D et al (2015) Global variability in leaf respiration in relation to climate, plant functional types and leaf traits. New Phytologist 206:614–636 + +.. _Atkin2017: + +|br| + +Leaf Respiration in Terrestrial Biosphere Models. In Plant Respiration: Metabolic Fluxes and Carbon Balance, Advances +in Photosynthesis and Respiration 43, G. Tcherkez, J. Ghashghaie (eds.) Springer International Publishing AG 2017 + .. _BadgerandDirmeyer2015: |br| From 3b5434e4f5014f3d40dc655af6673664669f8c0a Mon Sep 17 00:00:00 2001 From: Rosemary Fisher Date: Thu, 8 Mar 2018 11:16:15 -0700 Subject: [PATCH 159/255] removed nonsense text from end of FUN chapter --- doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst index 1b769042f7..658653da48 100644 --- a/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst +++ b/doc/source/tech_note/FUN/CLM50_Tech_Note_FUN.rst @@ -391,19 +391,3 @@ Following this, we determine how much carbon is accounted for for each soil laye -Types of N uptake streams --------------------------------------------------------- -Arbuscular mycorrhizal fungi: -Ectomycorrhizal fungi: -Nonmycorrhizal plants. - - -ECK_active (step 1) sets active components for Ectomycorrhizal fungi -ACK_active (step 2) sets active components for Arbuscular fungi - -kc_nonmyc (step 1) sets nonmyc components for Ectomycorrhizal fungi -kc_nonmyc (step 2) sets active components for Arbuscular fungi - -ACTIVE vs NONMYC -ECTO vs ARBU for ACTIVE. - From 1feb5bf46f586c6f4cf5e99ec048cc5ea4aac91c Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 12 Apr 2018 07:27:16 -0600 Subject: [PATCH 160/255] Fix co-author name --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 08bdf4ec29..e5a075cca5 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -13,7 +13,7 @@ ***Contributing Authors*** -**Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathon Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, +**Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathan Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** From f1cbb8a0c46f93a1dbfe2407d3f760dc1d05f69d Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 5 Jun 2018 14:45:52 -0600 Subject: [PATCH 161/255] Fixed some MOSART chapter typos --- .../MOSART/CLM50_Tech_Note_MOSART.rst | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index eabdb50763..e9f07d7752 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -11,9 +11,9 @@ Overview MOSART is a river transport model designed for applications across local, regional and global scales :ref:`(Li et al., 2013b) `. A major purpose of MOSART is to provide freshwater input for the ocean -model in coupled Earth system model. MOSART also provides an effective +model in coupled Earth System Models. MOSART also provides an effective way of evaluating and diagnosing the soil hydrology simulated by land -surface models through direction comparison of the simulated river flow +surface models through direct comparison of the simulated river flow with observations of natural streamflow at gauging stations :ref:`(Li et al., 2015a)`. Moreover, MOSART provides a modeling framework for representing riverine transport and transformation @@ -28,9 +28,9 @@ Routing Processes MOSART divides each spatial unit such as a lat/lon grid or watershed into three categories of hydrologic units (as shown in :numref:`Figure MOSART conceptual diagram`): hillslopes -that contribute both surface and subsurface runoff into tributaries, +that convert both surface and subsurface runoff into tributaries, tributaries that discharge into a single main channel, and the main channel -connects the local spatial unit with upstream/downstream units through the +that connects the local spatial unit with upstream/downstream units through the river network. MOSART assumes that all the tributaries within a spatial unit can be treated as a single hypothetical sub-network channel with a transport capacity equivalent to all the tributaries combined. Correspondingly, three @@ -50,14 +50,14 @@ and discharges the water to its downstream spatial unit or the ocean. :height: 400px -MOSART only route positive runoff, although negative runoff could be generated +MOSART only routes positive runoff, although negative runoff can be generated occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any runoff component including :math:`q_{sur}`, :math:`q_{sub}`, :math:`q_{gwl}` is not routed through MOSART, but instead is mapped directly from the spatial unit where it is generated at any time step to the coupler. In MOSART, the travel velocities of water across hillslopes, sub-network and main -channel are all estimated using the Manning’s equation with different levels of +channel are all estimated using Manning’s equation with different levels of simplifications. Generally the Manning’s equation is in the form of .. math:: @@ -65,9 +65,9 @@ simplifications. Generally the Manning’s equation is in the form of V = \frac{R^{\frac{2}{3}} S_{f}}{n} -where :math: `V` is the travel velocity (m s :sup:`-1` ), :math:`R` is the hydraulic -radius (m). :math:`S_{f}` is the friction slope, and accounting for the effects -of gravity, friction, inertia and other forces onthe water. If the channel slope +where :math:`V` is the travel velocity (m s :sup:`-1` ), :math:`R` is the hydraulic +radius (m). :math:`S_{f}` is the friction slope that accounts for the effects +of gravity, friction, inertia and other forces on the water. If the channel slope is steep enough, the gravity force dominates over the others so one can approximate :math:`S_{f}` by the channel bed slope :math:`S` , which is the key assumption underpinning the kinematic wave method. :math:`n` is the Manning’s roughness @@ -97,7 +97,7 @@ For the main channel, the hydraulic radius is given by where :math:`A_{r}` (m :sup:`2` ) is the wetted area defined as the part of the channel cross-section area below the water surface, :math:`P_{r}` (m) is the -wetted perimeter (m), the perimeter confines in the wetted area. +wetted perimeter, the perimeter confined in the wetted area. For hillslopes, sub-network and main channels, a common continuity equation can be written as @@ -134,14 +134,14 @@ scheme and a local time-stepping algorithm. There are two levels of subcycling. For convenience, we denote :math:`T_{inputs}` (s), :math:`T_{mosart}` (s), :math:`T_{hillslope}` (s) and :math:`T_{channel}` (s) as the time steps of runoff inputs (from CLM -to MOSART via the flux coupler), MOSART routing, hillslope routing and -channel routing respectively. The first level of subcycling is between +to MOSART via the flux coupler), MOSART routing, hillslope routing, and +channel routing, respectively. The first level of subcycling is between the runoff inputs and MOSART routing. If :math:`T_{inputs}` is 10800s and :math:`T_{mosart}` is 3600s, three MOSART time steps will be invoked each time the runoff inputs are updated. The second level of subcycling is between the hillslope routing and channel routing. This is to account for the fact that the travel velocity of water across -hillslope is usually much slower than that in the channels. +hillslopes is usually much slower than that in the channels. :math:`T_{hillslope}` is usually set as the same as :math:`T_{mosart}`, but within each time step of hillslope routing there are a few time steps for channel routing, i.e., @@ -154,7 +154,7 @@ step of local channel routing is given as :math:`T_{local}=T_{channel}/D_{local}`. :math:`D_{local}` is currently estimated empirically as a function of local channel slope, width, length and upstream drainage area. If MOSART crashes due to a -numerical issue, we recommend to increase :math:`D_{levelH2R}` and, if +numerical issue, we recommend increasing :math:`D_{levelH2R}` and, if the issue remains, reducing :math:`T_{mosart}`. .. _Parameters and Input Data: @@ -165,7 +165,7 @@ Parameters and Input Data MOSART is supported by a comprehensive, global hydrography dataset at 0.5 :sup:`o` resolution. As such, the fundamental spatial unit of MOSART is a 0.5 :sup:`o` lat/lon grid. The topographic parameters (such as flow direction, -channel length, topographic and channel slopes etc.) were derived using the +channel length, topographic and channel slopes, etc.) were derived using the Dominant River Tracing (DRT) algorithm (:ref:`Wu et al., 2011` ; :ref:`Wu et al. 2012 `). The DRT algorithm produces the topographic parameters in a scale-consistent way to preserve/upscale the key features of @@ -183,7 +183,7 @@ on the methodology to derive channel geometry and the Manning’s roughness coefficients, please refer to :ref:`Getirana et al. (2012) ` . The full list of parameters included in this global hydrography dataset is provided in -the :numref:`Table MOSART Parameters`. Evaluation of global simulations +:numref:`Table MOSART Parameters`. Evaluation of global simulations by MOSART using the aforementioned parameters is described in :ref:`Li et al. (2015b) ` . @@ -231,16 +231,16 @@ river routing, whilst in CLM5.0, MOSART is an added option for river routing based on the more physically-based kinematic wave method. 2. Runoff treatment: In RTM runoff is routed regardless of its sign so -negative streamflow can be simulated at times. MOSART routes only nonnegative +negative streamflow can be simulated at times. MOSART routes only non-negative runoff and always produces positive streamflow, which is important for -future extension for modeling riverine heat and biogeochemical fluxes. +future extensions to model riverine heat and biogeochemical fluxes. -3. Input parameters: RTM in CLM4.5 only requires one layer of spatial variable -of channel velocity, whilst MOSART in CLM5.0 requires 13 parameters that +3. Input parameters: RTM in CLM4.5 only requires one layer of a spatially varying +variable of channel velocity, whilst MOSART in CLM5.0 requires 13 parameters that are all available globally at 0.5 :sup:`o` resolution. 4. Outputs: RTM only produces streamflow simulation, whilst MOSART -additionally simulates the time-varying channel velocities and channel -water depth and channel surface water variation. +additionally simulates the time-varying channel velocities, channel water depth, and +channel surface water variations. From cf94e258ff1321ae78a0331479beecc1aa14afd5 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Tue, 12 Jun 2018 23:02:13 -0600 Subject: [PATCH 162/255] Include README file directly, rather than repeat it --- .../users_guide/overview/quickstart.rst | 80 +------------------ 1 file changed, 1 insertion(+), 79 deletions(-) diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index f6784da2ef..93c9b5b7cd 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -32,83 +32,5 @@ The ChangeLog/ChangeSum talk about advances in different versions of CLM. The co Note other directories have README files that explain different components and tools used when running CLM and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with CLM see `Chapter 1 `_. The Quickstart.GUIDE (which can be found in ``models/lnd/clm/doc``) is repeated here. -:: - - Quick-Start to Using cpl7 Scripts for clm4_5 - - Assumptions: You want to use yellowstone with clm4_5 BGC - to do a clm simulation with data atmosphere and the - latest CRUNCEP atm forcing files and settings. You also want to cycle - the CRUNCEP atm data between 1901 to 1920 and you want to run at - 0.9x1.25 degree resolution. - - Process: - - # Create the case - - cd scripts - - ./create_newcase -case -mach yellowstone_intel -res f09_g16 -compset I1850CRUCLM45BGC - (./create_newcase -help -- to get help on the script) - - # Setup the case - - cd - ./xmlchange id1=val1,id2=val2 # to make changes to any settings in the env_*.xml files - ./cesm_setup - (./cesm_setup -help -- to get help on the script, this creates the ./.run \ - script) - - # Add any namelist changes to the user_nl_* files - - $EDITOR user_nl_* - - # Compile the code - - ./.build - - # Submit the run - - ./.submit - -Information on Compsets: - - "I" compsets are the ones with clm and datm7 without ice and ocean. They - specify either CLM4.0 physics or CLM4.5 physics. - Most of the "I" compsets for CLM4.0 use the CLM_QIAN data with solar following - the cosine of solar zenith angle, precipitation constant, and other - variables linear interpolated in time (and with appropriate time-stamps on - the date). Useful "I" compsets for CLM4.5 use the CRUNCEP data in place - of the CLM_QIAN data. - - To list all the compsets use: - ./create_newcase -list compsets - - Some of the CLM4.5 I compsets are: - - Alias Description - 1850CRUCLM45 CLM4.5 to simulate year=1850 with CLMN45SP (Satellite Phenology) - I1850CRUCLM45BGC CLM4.5 to simulate year=1850 with CLM45BGC biogeophysics model (BGC) - I20TRCRUCLM45BGC CLM4.5 with BGC on with transient PFT over 1850-2000 - - While some of the CLM4 I compsets are: - - Alias Description - ICN CLM4.0 to simulate year=2000 with Carbon-Nitrogen BGC model (CN) - I1850CN CLM4.0 to simulate year=1850 with Carbon-Nitrogen BGC model (CN) - I20TRCN CLM4.0 with CN on with transient PFT over 1850-2000 - IRCP26CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=2.6 scenario - IRCP45CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=4.5 scenario - IRCP60CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=6.0 scenario - IRCP85CN CLM4.0 with CN on with transient PFT over 1850-2100 for RCP=8.5 scenario - -Automatically resubmitting jobs: - - After doing a short simulation that you believe is correct - - ./xmlchange CONTINUE_RUN=TRUE - - # Change RESUBMIT to number greater than 0, and CONTINUE_RUN to TRUE... - - ./.submit +.. include:: ../../clm5.0/doc/Quickstart.GUIDE From 94a19acc63557a8eb395e35372bc20cf5ba04697 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 14 Jun 2018 10:17:33 -0600 Subject: [PATCH 163/255] Add a top level README file. Setup version and release in configure files. Start using versiona and release. Rather than repeat README text files, actually include them from a clm5.0 checkout, so the updated version from the code can be used. --- doc/source/conf.py | 10 +- doc/source/tech_note/conf.py | 6 +- doc/source/users_guide/conf.py | 14 +- doc/source/users_guide/index.rst | 3 +- .../users_guide/overview/introduction.rst | 10 +- .../users_guide/overview/quickstart.rst | 1 + doc/source/users_guide/testing/index.rst | 3 +- .../building-the-clm-tools.rst | 54 +-- .../creating-surface-datasets.rst | 313 +----------------- .../users_guide/using-clm-tools/index.rst | 1 + 10 files changed, 35 insertions(+), 380 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 5c5b1d86ad..a573b2a1d0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -59,9 +59,9 @@ # built documents. # # The short X.Y version. -version = u'' +version = u'clm5.0' # The full version, including alpha/beta/rc tags. -release = u'' +release = u'release-clm5.0.01' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -73,7 +73,11 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +exclude_patterns = [ + "clm5.0/manage_externals", + "**/README_EXTERNALS.rst", + "clm5.0/README.rst" +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/source/tech_note/conf.py b/doc/source/tech_note/conf.py index 5c5b1d86ad..a1827c71c5 100644 --- a/doc/source/tech_note/conf.py +++ b/doc/source/tech_note/conf.py @@ -73,7 +73,11 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +exclude_patterns = [ + "manage_externals/*", + "README_EXTERNALS.rst", + "clm5.0//README.rs" +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index 5c5b1d86ad..c717685979 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -51,17 +51,17 @@ # General information about the project. project = u'clmdoc' -copyright = u'2017, Erik Kluzek, Bill Sacks, Ben Andre' -author = u'Erik Kluzek, Bill Sacks, Ben Andre' +copyright = u'2018, Erik Kluzek, Bill Sacks, Ben Andre, Alice Bertini' +author = u'Erik Kluzek, Bill Sacks, Ben Andre, Alice Bertini' # 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 = u'' +version = u'clm5.0' # The full version, including alpha/beta/rc tags. -release = u'' +release = u'release-clm5.0.01' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -73,7 +73,11 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +exclude_patterns = [ + "clm5.0/manage_externals", + "**/README_EXTERNALS.rst", + "clm5.0/README.rst" +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index bdb52253a1..f3160a30ed 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -6,7 +6,7 @@ .. _users-guide: ##################################### -CLM User's Guide +|version| User's Guide ##################################### .. toctree:: @@ -20,3 +20,4 @@ CLM User's Guide running-single-points/index.rst running-PTCLM/index.rst trouble-shooting/index.rst + testing/index.rst diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index d6c5781a17..80b2b1e0c3 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -1,6 +1,6 @@ .. _introduction: -**User's Guide to version 5.0 of the Community Land Model (CLM)** +**User's Guide to version +|version| of the Community Land Model (CLM)** **Authors: Benjamin Andre, Erik Kluzek, William Sacks** @@ -20,18 +20,18 @@ P. O. Box 3000, Boulder, Colorado 80307-300 Introduction ============== -The Community Land Model (CLM5.0 in CESM2.0) is the latest in a -series of global land models developed by t he CESM Land Model Working +The Community Land Model (+|release| in CESM2.0) is the latest in a +series of global land models developed by the CESM Land Model Working Group (LMWG) and maintained at the National Center for Atmospheric Research (NCAR). This guide is intended to instruct both the novice and experienced user on running CLM. This guide pertains to the latest -version CLM5.0 in CESM2.0 available for download from the public +version +|version| in CESM2.0 available for download from the public release subversion repository as a part of CESM1.2.0. Documentation may be different if you are using an older version, you should either use the documentation for that release version, update to the latest version, or use the documentation inside your own source tree. There is information in the ChangeLog file and in the `What is new with -CLM5.0 in CESM2.0 since previous public releases? `_ ++|version| in CESM2.0 since previous public releases? `_ regarding the changes from previous versions of CESM. .. note:: This release of CLM5.0 in CESM1.2.0 includes BOTH CLM4.0 diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index 93c9b5b7cd..edcd0bc2fe 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -34,3 +34,4 @@ Note other directories have README files that explain different components and t The Quickstart.GUIDE (which can be found in ``models/lnd/clm/doc``) is repeated here. .. include:: ../../clm5.0/doc/Quickstart.GUIDE + :literal: diff --git a/doc/source/users_guide/testing/index.rst b/doc/source/users_guide/testing/index.rst index 18c418fca4..09575a1442 100644 --- a/doc/source/users_guide/testing/index.rst +++ b/doc/source/users_guide/testing/index.rst @@ -3,7 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _testing: +.. _testing_section: ##################################### Testing @@ -11,7 +11,6 @@ Testing .. toctree:: :maxdepth: 2 - :numbered: testing.rst diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst index c2633e6522..ec626641e5 100644 --- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -107,56 +107,6 @@ More details on each environment variable. .. note:: There are several files that are copies of the original files from either models``/lnd/clm/src/util_share``, ``models/csm_share/shr``, or copies from other tool directories. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well. The *README.filecopies* (which can be found in ``models/lnd/clm/tools``) is repeated here. -:: - - models/lnd/clm/tools/README.filecopies Jun/04/2013 - - There are several files that are copies of the original files from - either models/lnd/clm/src/main, models/csm_share/shr, - models/csm_share/unit_testers, or copies from other tool - directories. By having copies the tools can all be made stand-alone, - but any changes to the originals will have to be put into the tool - directories as well. - - I. Files that are IDENTICAL: - - 1. csm_share files copied that should be identical to models/csm_share/shr: - - shr_const_mod.F90 - shr_log_mod.F90 - shr_timer_mod.F90 - - 2. csm_share files copied that should be identical to models/csm_share/unit_testers: - - test_mod.F90 - - 3. clm/src files copied that should be identical to models/lnd/clm/src/util_share: - - nanMod.F90 - - II. Files with differences - - 1. csm_share files copied with differences: - - shr_kind_mod.F90 --- SHR_KIND_CXX is new - shr_sys_mod.F90 ---- Remove mpi abort and reference to shr_mpi_mod.F90. - shr_infnan_mod.F90 - Earlier version - shr_string_mod.F90 - Earlier version - shr_file_mod.F90 --- mkprocdata_map version is stripped down - clm_varctl.F90 ----- Earlier version - - 2. clm/src files with differences: - - fileutils.F90 --- Remove use of masterproc and spmdMod and endrun in abortutils. - - 4. Files in mkmapgrids - - domainMod.F90 ---- Highly customized based off an earlier version of clm code. - Remove use of abortutils, spmdMod. clm version uses latlon - this version uses domain in names. Distributed memory - parallelism is removed. - - 5. Files in mksurfdata_map - - mkvarpar.F90 --- clm4_0 and clm4_5 versions are different and different from main clm versions. +.. include:: ../../clm5.0/tools/README.filecopies + :literal: diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index e42a46f81f..d1ab21e2b7 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -61,316 +61,7 @@ Creating a Complete Set of Files for Input to CLM The last optional thing to do is to enter the new datasets into the build-namelist XML database. See Chapter 3 for more information on doing this. This is optional because the user may enter these files into their namelists manually. The advantage of entering them into the database is so that they automatically come up when you create new cases. The ``models/lnd/clm/tools/README`` goes through the complete process for creating input files needed to run CLM. We repeat that file here: -:: - models/lnd/clm/tools/README Jun/04/2013 - - CLM tools for analysis of CLM history files -- or for creation or - modification of CLM input files. - - I. General directory structure: - - clm4_0 - mksurfdata_map --- Create surface datasets. - interpinic ------- Interpolate initial datasets to a different resolution. - (has optimized and OMP options) - clm4_5 - mksurfdata_map --- Create surface datasets. - interpinic ------- Interpolate initial datasets to a different resolution. - (has optimized and OMP options) - - shared - mkmapgrids ------- Create SCRIP grid files needed by mkmapdata - [input is CLM grid files] - (deprecated) - mkmapdata -------- Create SCRIP mapping data from SCRIP grid files (uses ESMF) - gen_domain ------- Create data model domain datasets from SCRIP mapping datasets. - (also in the top level mapping directory [../../../../tools/mapping]) - mkprocdata_map --- Convert output unstructured grids into a 2D format that - can be plotted easily - ncl_scripts ------ NCL post or pre processing scripts. - - - Note that there are different versions of mksurfdata_map and interpinic for - CLM4.0 vs. CLM4.5. Other tools are shared between the two model - versions. - - However, note that mkmapdata makes mapping files for CLM4.5 by default; to - make mapping files for CLM4.0, run the tool with the option: - -p clm4_0 - - II. Notes on building/running for each of the above tools: - - Each tool that has FORTRAN source code has the following files: - - README -------------- Specific help for using the specific tool and help on specific - files in that directory. - src/Filepath -------- List of directories needed to build the tool - (some files in ../src directories are required). - src/Makefile -------- Customization of the make for the particular tool in question - src/Makefile.common - General GNU Makefile for creating FORTRAN tools - (these are identical between tools). - src/Srcfiles -------- List of source files that are needed. - src/Mkdepends ------- Dependency generator program - - mkmapdata and ncl_scripts only contain scripts so don't have the above build files. - - Most tools have copies of files from other directories -- see the README.filecopies - file for more information on this. - - Tools may also have files with the directory name followed by: namelist, or runoptions. - - .namelist ------ Namelist to create a global file. - .runoptions ---- Command line options to use the given tool. - - These files are also used by the test scripts to test the tools (see the - README.testing) file. - - NOTE: Be sure to change the path of the datasets references by these namelists to - point to where you have exported your CESM inputdata datasets. - - To build: - - cd - setenv INC_NETCDF - setenv LIB_NETCDF - gmake - - The process will create a file called "Depends" which has the dependencies - for the build of each file on other files. - - By default some codes may be compiled non-optimized - so that you can use the debugger, and with bounds-checking, and float trapping on. - To speed up do the following... - - gmake OPT=TRUE (by default already on for interpinic and mksurfdata_map) - - Also some of the tools allow for OpenMP shared memory parallelism - (such as interpinic) with - - gmake SMP=TRUE - - To run a program with a namelist: - - ./program < namelist - - To get help on running a program with command line options (e.g., interpinic): - - ./program - - To run a program built with SMP=TRUE: - - setenv OMP_NUM_THREADS= - - run normally as above - - III. Process sequence to create input datasets needed to run CLM - - NOTE: The following assumes you want to create files for CLM4.5. If you want to - use CLM4.0, you will need to do the following: - - In the following commands, change references to the clm4_5 directory to clm4_0 - - Add the option '-p clm4_0' to the mkmapdata.sh command. - - 1.) Create SCRIP grid files (if needed) - - a.) For standard resolutions these files will already be created. (done) - - b.) To create regular lat-lon regional/single-point grids run mknoocnmap.pl - - This will create both SCRIP grid files and a mapping file that will - be valid if the region includes NO ocean whatsoever (so you can skip step 2). - You can also use this script to create SCRIP grid files for a region - (or even a global grid) that DOES include ocean if you use step 2 to - create mapping files for it (simply discard the non-ocean map created by - this script). - - Example, for single-point over Boulder Colorado. - - cd shared/mkmapdata - ./mknoocnmap.pl -p 40,255 -n 1x1_boulderCO - - c.) General case - - You'll need to convert or create SCRIP grid files on your own (using scripts - or other tools) for the general case where you have an unstructured grid, or - a grid that is not regular in latitude and longitude. - - example format - ================== - netcdf fv1.9x2.5_090205 { - dimensions: - grid_size = 13824 ; - grid_corners = 4 ; - grid_rank = 2 ; - variables: - double grid_center_lat(grid_size) ; - grid_center_lat:units = "degrees" ; - double grid_center_lon(grid_size) ; - grid_center_lon:units = "degrees" ; - double grid_corner_lat(grid_size, grid_corners) ; - grid_corner_lat:units = "degrees" ; - double grid_corner_lon(grid_size, grid_corners) ; - grid_corner_lon:units = "degrees" ; - int grid_dims(grid_rank) ; - int grid_imask(grid_size) ; - grid_imask:units = "unitless" ; - - 2.) Create ocean to atmosphere mapping file (if needed) - - a.) Standard resolutions (done) - - If this is a standard resolution with a standard ocean resolution -- this - step is already done, the files already exist. - - b.) Region without Ocean (done in step 1.b) - - IF YOU RAN mknoocnmap.pl FOR A REGION WITHOUT OCEAN THIS STEP IS ALREADY DONE. - - c.) New atmosphere or ocean resolution - - If the region DOES include ocean, use gen_domain to create a - mapping file for it. - - Example: - - cd ../../../../tools/mapping/gen_domain_files/src - ./gen_domain -m $MAPFILE -o $OCNGRIDNAME -l $ATMGRIDNAME - - - 3.) Add SCRIP grid file(s) created in (1) into XML database in CLM (optional) - - See the "Adding New Resolutions or New Files to the build-namelist Database" - Chapter in the CLM User's Guide - - http://www.cesm.ucar.edu/models/cesm1.0/clm/models/lnd/clm/doc/UsersGuide/book1.html - - If you don't do this step, you'll need to specify the file to mkmapdata - in step (3) using the "-f" option. - - 4.) Create mapping files for use by mksurfdata_map with mkmapdata - (See mkmapdata/README for more help on doing this) - - - this step uses the results of (1) that were entered into the XML database - by step (3). If you don't enter datasets in, you need to specify the - SCRIP grid file using the "-f" option to mkmapdata.sh. - - - note that mkmapdata generates maps for CLM4.5 by default; to generate - mapping files for CLM4.0, add the option '-p clm4_0' - - Example: to generate all necessary mapping files for the ne30np4 grid - - cd shared/mkmapdata - ./mkmapdata.sh -r ne30np4 - - 5.) Add mapping file(s) created in step (4) into XML database in CLM (optional) - - See notes on doing this in step (3) above. - Edit ../bld/namelist_files/namelist_defaults_clm.xml to incorporate new - mapping files. - - If you don't do this step, you'll need to specify the grid resolution name - and file creation dates to mksurfdata_map in step (5) below. - - 6.) Convert map of ocean to atm for use by DATM and CLM with gen_domain - (See tools/mapping/README for more help on doing this) - - - gen_domain uses the map from step (2) (or previously created CESM maps) - - Example: - - cd ../../../../tools/mapping/gen_domain_files/src - gmake - cd .. - setenv CDATE 090206 - setenv OCNGRIDNAME gx1v6 - setenv ATMGRIDNAME fv1.9x2.5 - setenv MAPFILE $CSMDATA/cpl/cpl6/map_${OCNGRIDNAME}_to_${ATMGRIDNAME}_aave_da_${CDATE}.nc - ./gen_domain -m $MAPFILE -o $OCNGRIDNAME -l $ATMGRIDNAME - - Normally for I compsets running CLM only you will discard the ocean domain - file, and only use the atmosphere domain file for datm and as the fatmlndfrc - file for CLM. Output domain files will be named according to the input OCN/LND - gridnames. - - 7.) Create surface datasets with mksurfdata_map - (See mksurfdata_map/README for more help on doing this) - - - Run clm4_5/mksurfdata_map/mksurfdata.pl - - This step uses the results of step (4) entered into the XML database - in step (5). - - If datasets were NOT entered into the XML database, set the resolution - to "usrspec" and use the "-usr_gname", and "-usr_gdate" options. - - Example: for 0.9x1.25 resolution - - cd clm4_5/mksurfdata_map/src - gmake - cd .. - ./mksurfdata.pl -r 0.9x1.25 - - NOTE that surface dataset will be used by default for fatmgrid - and it will - contain the lat,lon,edges and area values for the atm grid - ASSUMING that - the atm and land grid are the same - - 8.) Interpolate initial conditions using interpinic (optional) - (See interpinic/README for more help on doing this) - IMPORTANT NOTE on interpinic!!!:: BE SURE TO USE NetCDF4.3 WHEN BUILDING! - If your template file was written using pnetcdf -- interpinic will corrupt - the resulting file and make it unusable! - - 9.) Add new files to XML data or using user_nl_clm (optional) - - See notes on doing this in step (3) above. - - IV. Example of creating single-point datasets without entering into XML database. - - Here we apply the process described in III. for a single-point dataset - where we don't enter the datasets into the XML database (thus skipping - steps 3, 5 and 9), but use the needed command line options to specify where the - files are. This also skips step (2) since step 1 creates the needed mapping file. - We also skip step (8) and do NOT create a finidat file. - - 0.) Set name of grid to use and the creation date to be used later... - setenv GRIDNAME 1x1_boulderCO - setenv CDATE `date +%y%m%d` - 1.) SCRIP grid and atm to ocn mapping file - cd shared/mkmapdata - ./mknoocnmap.pl -p 40,255 -n $GRIDNAME - # Set pointer to MAPFILE that will be used in step (6) - setenv MAPFILE `pwd`/map_${GRIDNAME}_noocean_to_${GRIDNAME}_nomask_aave_da_${CDATE}.nc - cd ../.. - 2.) skip - 3.) skip - 4.) Mapping files needed for mksurfdata_map - cd shared/mkmapdata - setenv GRIDFILE ../mkmapgrids/SCRIPgrid_${GRIDNAME}_nomask_${CDATE}.nc - ./mkmapdata.sh -r $GRIDNAME -f $GRIDFILE -t regional - cd .. - 5.) skip - 6.) Generate domain file for datm and CLM - cd ../../../../tools/mapping/gen_domain_files/src - gmake - cd .. - setenv OCNDOM domain.ocn_noocean.nc - setenv ATMDOM domain.lnd.{$GRIDNAME}_noocean.nc - ./gen_domain -m $MAPFILE -o $OCNDOM -l $ATMDOM - cd ../../../../lnd/clm/tools - 7.) Create surface dataset for CLM - cd clm4_5/mksurfdata_map/src - gmake - cd .. - ./mksurfdata.pl -r usrspec -usr_gname $GRIDNAME -usr_gdate $CDATE - 8.) skip - 9.) skip - - V. Notes on which input datasets are needed for CLM - - global or regional/single-point grids - - need fsurdata and fatmlndfrc - - fsurdata ---- from mksurfdata_map in step (III.7) - fatmlndfrc -- use the domain.lnd file from gen_domain in step (III.6) - (NOTE: THIS FILE IS POINTED TO USING ATM_DOMAIN_PATH/ATM_DOMAIN_FILE/LND_DOMAIN_PATH/ \ - LND_DOMAIN_FILE - env_run.xml variables -- do NOT simply add this to your user_nl_clm as it will fail) +.. include:: ../../clm5.0/tools/README + :literal: diff --git a/doc/source/users_guide/using-clm-tools/index.rst b/doc/source/users_guide/using-clm-tools/index.rst index 583122cdcd..030cda7495 100644 --- a/doc/source/users_guide/using-clm-tools/index.rst +++ b/doc/source/users_guide/using-clm-tools/index.rst @@ -18,4 +18,5 @@ Using CLM tools creating-surface-datasets.rst datasts-for-observational-sites.rst creating-domain-files.rst + observational-sites-datasets.rst cprnc.rst From 173d208bc79f5962bee2a39011540037c20d22c1 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 14 Jun 2018 13:00:26 -0600 Subject: [PATCH 164/255] Change some of the hardcoded versions into using the variable --- doc/source/users_guide/conf.py | 2 ++ doc/source/users_guide/overview/getting-help.rst | 6 +++--- doc/source/users_guide/overview/introduction.rst | 11 ++++++----- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index c717685979..0294e7cef8 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -63,6 +63,8 @@ # The full version, including alpha/beta/rc tags. release = u'release-clm5.0.01' +cesmrelease = u'release-cesm2.0.00' + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 8d45c71bcb..5f9c63ab26 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -8,10 +8,10 @@ In addition to this users-guide there are several other resources that are avail --------------------------- The CESM User's-Guide --------------------------- ++|release| ++|release| in +|cesmrelease| is always run from within the standard +|cesmrelease| build and run scripts. Therefore, the user of CLM4.5 should familiarize themselves with the +|cesmrelease| scripts and understand how to work with them. User's-Guide documentation on the +|cesmrelease| scripts are available from the following web-page. The purpose of this +|version| in +|cesmrelease| User's Guide is to give the +|version| user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the +|cesmrelease| Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. -CLM5.0 in CESM2.0 is always run from within the standard CESM2.0 build and run scripts. Therefore, the user of CLM4.5 should familiarize themselves with the CESM1.2.0 scripts and understand how to work with them. User's-Guide documentation on the CESM1.2.0 scripts are available from the following web-page. The purpose of this CLM4.5 in CESM1.2.0 User's Guide is to give the CLM4.5 user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the CESM1.2.0 Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. - -`cesmrel; Scripts User's-Guide (http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/usersguide/book1.html) `_ +`+|cesmrelease| Quickstart Guide `_ ----------------------- The CESM Bulletin Board diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 80b2b1e0c3..02e6237e2b 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -20,18 +20,18 @@ P. O. Box 3000, Boulder, Colorado 80307-300 Introduction ============== -The Community Land Model (+|release| in CESM2.0) is the latest in a +The Community Land Model (+|release| in +|cesmrelease|) is the latest in a series of global land models developed by the CESM Land Model Working Group (LMWG) and maintained at the National Center for Atmospheric Research (NCAR). This guide is intended to instruct both the novice and experienced user on running CLM. This guide pertains to the latest -version +|version| in CESM2.0 available for download from the public +version +|version| in +|cesmrelease| available for download from the public release subversion repository as a part of CESM1.2.0. Documentation may be different if you are using an older version, you should either use the documentation for that release version, update to the latest version, or use the documentation inside your own source tree. There is information in the ChangeLog file and in the `What is new with -+|version| in CESM2.0 since previous public releases? `_ ++|version| in +|cesmrelease| since previous public releases? `_ regarding the changes from previous versions of CESM. .. note:: This release of CLM5.0 in CESM1.2.0 includes BOTH CLM4.0 @@ -79,12 +79,13 @@ and then finally do it by hand. If you are using non supported machines you may also want to use the test scripts to make sure your machine is working correctly. -.. _what-is-new-with-clm4.5: +.. _what-is-new-with-+|version|: ========================= - What is New with CLM4.5 + What is New with +|version| ========================= +`What's new with +|version| science `_ The CESM1.2.0 `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. More details are given in the `CLM ChangeLog file `_. From bc6fa69978dcbdfa173ee8a1469c2d4359080f41 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 14 Jun 2018 14:26:05 -0600 Subject: [PATCH 165/255] Run the sed script to make a bunch of global changes --- ...w-Files-to-the-build-namelist-Database.rst | 4 +- .../CLM-3.1-Managing-Your-Own-Data-files.rst | 4 +- .../CLM-3.2-Adding-Resolution-Names.rst | 4 +- ...3-Adding-or-Changing-Default-Filenames.rst | 8 +- .../users_guide/overview/getting-help.rst | 40 ++++----- .../users_guide/overview/introduction.rst | 84 +++++++++---------- .../users_guide/overview/quickstart.rst | 18 ++-- .../overview/scientific_validation.rst | 18 ++-- .../running-PTCLM/adding-ptclm-site-data.rst | 2 +- .../running-PTCLM/introduction-to-ptclm.rst | 10 +-- .../running-PTCLM/ptclm-examples.rst | 6 +- .../users_guide/running-PTCLM/using-ptclm.rst | 10 +-- .../running-pts_mode-configurations.rst | 6 +- .../running-single-point-configurations.rst | 18 ++-- ...CLM4.5-biogeochemistry-(CLMBGC-spinup).rst | 18 ++-- ...tmospheric-forcing-to-spinup-the-model.rst | 10 +-- ...tmospheric-forcing-to-spinup-the-model.rst | 12 +-- ...transient-historical-CO2-concentration.rst | 12 +-- .../running-special-cases/index.rst | 2 +- .../running-the-prognostic-crop-model.rst | 4 +- .../running-with-irrigation.rst | 6 +- doc/source/users_guide/runsed.csh | 6 ++ doc/source/users_guide/sedscript.txt | 17 ++++ .../choosing-a-compset.rst | 18 ++-- .../customizing-the-clm-configuration.rst | 48 +++++------ .../customizing-the-clm-namelist.rst | 10 +-- doc/source/users_guide/testing/testing.rst | 20 ++--- .../trouble-shooting/trouble-shooting.rst | 16 ++-- .../building-the-clm-tools.rst | 4 +- .../users_guide/using-clm-tools/cprnc.rst | 2 +- ...g-input-for-surface-dataset-generation.rst | 16 ++-- .../creating-surface-datasets.rst | 14 ++-- .../what-are-the-clm-tools.rst | 26 +++--- 33 files changed, 258 insertions(+), 235 deletions(-) create mode 100755 doc/source/users_guide/runsed.csh create mode 100644 doc/source/users_guide/sedscript.txt diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst index de13570b3d..8854d9e4d9 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst @@ -14,11 +14,11 @@ If you have a LOT of files to keep track of it also might be easier than keeping If you just have a few quick experiments to try, for a short time period you might be best off using the other methods mentioned above. There are two parts to adding files to the build-namelist database. -The first part is adding new resolution names which is done in the ``models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml`` file (and in the ``models/lnd/clm/bld/config_files/config_definition.xml`` file when adding supported single-point datasets). +The first part is adding new resolution names which is done in the ``$CTSMROOT/bld/namelist_files/namelist_definition_+|version|.xml`` file (and in the ``$CTSMROOT/bld/config_files/config_definition.xml`` file when adding supported single-point datasets). You can then use the new resolution by using ``CLM_USRDAT_NAME``. If you also want to be able to give the resolution into **create_newcase** -- you'll need to add the grid to the ``scripts/ccsm_utils/Case.template/config_grid.xml`` file. -The second part is actually adding the new filenames which is done in the ``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml`` file (``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5_tools.xml`` file for CLM tools). +The second part is actually adding the new filenames which is done in the ``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|.xml`` file (``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|_tools.xml`` file for CLM tools). If you aren't adding any new resolutions, and you are just changing the files for existing resolutions, you don't need to edit the namelist_definition file. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst index a8ebc81ac8..558c877157 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst @@ -4,7 +4,7 @@ Managing Your Data Own Files ============================== -If you are running on a supported machine (such as yellowstone or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `CESM1.2.0 Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. +If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `+|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. @@ -39,7 +39,7 @@ You can also use **find** to list files that have a particular pattern in the na -If you are running on a supported machine (such as yellowstone or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `CESM1.2.0 Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. +If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `+|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst index 6d44f73b5b..e7896e1206 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst @@ -5,7 +5,7 @@ ========================= If you are adding files for new resolutions which aren't covered in the namelist_definition file -- you'll need to add them in. -The list of valid resolutions is in the id="res" entry in the ``models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml`` file. +The list of valid resolutions is in the id="res" entry in the ``$CTSMROOT/bld/namelist_files/namelist_definition_+|version|.xml`` file. You need to choose a name for your new resolution and simply add it to the comma delimited list of valid_values for the id="res" entry. The convention for global Gaussian grids is number_of_latitudes x number_of_longitudes. The convention for global finite volume grids is latitude_grid_size x longitude_grid_size where latitude and longitude is measured in degrees. @@ -29,7 +29,7 @@ The only hard requirement is that names be unique for different grid files. Here As you can see you just add your new resolution names to the end of the valid_values list. -When using PTCLM and adding supported single-point resolutions, you'll also want to add these resolutions to the ``models/lnd/clm/bld/config_files/config_definition.xml`` under the ``sitespf_pt`` name. +When using PTCLM and adding supported single-point resolutions, you'll also want to add these resolutions to the ``$CTSMROOT/bld/config_files/config_definition.xml`` under the ``sitespf_pt`` name. The entry in that file looks like: :: diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst index c539d0fd8c..6393a74ce3 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst @@ -4,7 +4,7 @@ Changing Default Filenames ============================ -To add or change the default filenames you edit the ``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml`` and either change an existing filename or add a new one. +To add or change the default filenames you edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|.xml`` and either change an existing filename or add a new one. Most entries in the default namelist files, include different attributes that describe the different properties that describe the differences in the datasets. Attributes include the: resolution, year to simulation, range of years to simulate for transient datafiles, the land-mask, the representative concentration pathway (rcp) for future scenarios, and the type of biogeochemistry (bgc) model used. For example the fatmgrid for the 1.9x2.5 resolution is as follows: @@ -18,8 +18,8 @@ lnd/clm2/surfdata_map/surfdata_0.9x1.25_simyr1850_c130415.nc Other ``fsurdat`` files are distinguished from this one by their resolution (hgrid), simulation year (sim_year) and prognostic crop (crop) attributes. -To add or change the default filenames for CLM tools edit the ``models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5_tools.xml`` and either change an existing filename or add a new one. -Editing this file is similar to the ``namelist_defaults_clm4_5.xml`` talked about above. +To add or change the default filenames for CLM tools edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|_tools.xml`` and either change an existing filename or add a new one. +Editing this file is similar to the ``namelist_defaults_+|version|.xml`` talked about above. ---------------------------- @@ -27,7 +27,7 @@ What are the required files? ---------------------------- Different types of simulations and different types of configurations for CLM require different lists of files. -The CLM4.5-BGC or Carbon Nitrogen (cn) Biogeochemistry model for example requires ``stream_fldfilename_ndep`` files, which are NOT required by CLMSP. +The +|version|-BGC or Carbon Nitrogen (cn) Biogeochemistry model for example requires ``stream_fldfilename_ndep`` files, which are NOT required by CLMSP. Transient simulations also require transient datasets, and the names of these datasets are sometimes different from the static versions (sometimes both are required as in the dynamic PFT cases). diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 5f9c63ab26..42df1b989a 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -3,13 +3,13 @@ ============== Getting Help ============== -In addition to this users-guide there are several other resources that are available to help you use CLM5.0. The first one is the CESM1.2.0 User's-Guide, which documents the entire process of creating cases with CESM1.2.0. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in CESM1.2.0. +In addition to this users-guide there are several other resources that are available to help you use +|version|. The first one is the +|cesmrelease| User's-Guide, which documents the entire process of creating cases with +|cesmrelease|. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in +|cesmrelease|. --------------------------- The CESM User's-Guide --------------------------- +|release| -+|release| in +|cesmrelease| is always run from within the standard +|cesmrelease| build and run scripts. Therefore, the user of CLM4.5 should familiarize themselves with the +|cesmrelease| scripts and understand how to work with them. User's-Guide documentation on the +|cesmrelease| scripts are available from the following web-page. The purpose of this +|version| in +|cesmrelease| User's Guide is to give the +|version| user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the +|cesmrelease| Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. ++|release| in +|cesmrelease| is always run from within the standard +|cesmrelease| build and run scripts. Therefore, the user of +|version| should familiarize themselves with the +|cesmrelease| scripts and understand how to work with them. User's-Guide documentation on the +|cesmrelease| scripts are available from the following web-page. The purpose of this +|version| in +|cesmrelease| User's Guide is to give the +|version| user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the +|cesmrelease| Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. `+|cesmrelease| Quickstart Guide `_ @@ -25,28 +25,28 @@ There is a rich and diverse set of people that use the CESM, and often it is use The CLM web pages ----------------- -The main CLM web page contains information on the CLM, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the models/lnd/clm/doc directory that give some quick information on using CLM. +The main CLM web page contains information on the CLM, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the $CTSMROOT/doc directory that give some quick information on using CLM. `CLM web page `_ `CLM Documentation Text Files `_ Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files: -- `models/lnd/clm/bld/namelist_files/namelist_definition_clm4_0.xml `_ -- definition of CLM4.0 namelist items. -- `models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml `_ -- definition of CLM4.0 namelist items. -- `models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_0.xml `_ -- default values for CLM4.0 namelist items. -- `models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml `_ -- default values for CLM4.5 namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_0.xml `_ -- definition of CLM4.0 namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_definition_+|version|.xml `_ -- definition of CLM4.0 namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_0.xml `_ -- default values for CLM4.0 namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|.xml `_ -- default values for +|version| namelist items. - `scripts/ccsm_utils/Case.template/config_definition.xml `_ -- definition of all env_*.xml items. - `scripts/ccsm_utils/Case.template/config_compsets.xml `_ -- definition of all the compsets. -- `models/lnd/clm/bld/namelist_files/history_fields_clm4_0.xml `_ -- definition of CLM4.0 history fields. -- `models/lnd/clm/bld/namelist_files/history_fields_clm4_5.xml `_ -- definition of CLM4.5 history fields. +- `$CTSMROOT/bld/namelist_files/history_fields_clm4_0.xml `_ -- definition of CLM4.0 history fields. +- `$CTSMROOT/bld/namelist_files/history_fields_+|version|.xml `_ -- definition of +|version| history fields. ------------------------ -Reporting bugs in CLM4.5 +Reporting bugs in +|version| ------------------------ -If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for CLM4.5 in CESM1.2.0 is in the models/lnd/clm/doc/KnownBugs file, and the list of issues for CESM1.2.0 is at... -`http://www.cesm.ucar.edu/models/cesm1.2//tags/cesm1_2_0/#PROBLEMS `_. +If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for +|version| in +|cesmrelease| is in the $CTSMROOT/doc/KnownBugs file, and the list of issues for +|cesmrelease| is at... +`http://www.cesm.ucar.edu/models/cesm1.2//tags/+|cesmrelease|/#PROBLEMS `_. --------------------------------------- Some Acronym's and Terms We'll be Using @@ -62,22 +62,22 @@ CLM Community Land Model (CLM). The prognostically active land model component of CESM. CLMBGC - Community Land Model (CLM4.5) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is + Community Land Model (+|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is - ``./xmlchange CLM_CONFIG_OPTS="phys clm4_5 -bgc cn -vsoilc_centbgc on -clm4me on"`` + ``./xmlchange CLM_CONFIG_OPTS="phys +|version| -bgc cn -vsoilc_centbgc on -clm4me on"`` CLMCN - Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or CLM4.5) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or +|version|) The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc cn" -append`` CLMSP - Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0 or CLM4.5) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0 or +|version|) The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc none" -append`` CLMU - Community Land Model (CLM) Urban Model (either CLM4.0 or CLM4.5). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). + Community Land Model (CLM) Urban Model (either CLM4.0 or +|version|). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). CRUNCEP The Climate Research Unit (CRU) analysis of the NCEP atmosphere reanalysis atmosphere forcing data. This can be used to drive CLM with atmosphere forcing from 1901 to 2010. We also DO expect to be able to update this dataset beyond 2010 as newer data becomes available. @@ -86,7 +86,7 @@ DATM Data Atmosphere Model (DATM) the prescribed data atmosphere component for CESM. Forcing data that we provide are either the Qian or CRUNCEP forcing datasets (see below). DV - Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either CLM4.5-BGC or CLMCN for either CLM4.0 or CLM4.5). The CLM_CONFIG_OPTS option for this is + Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either +|version|-BGC or CLMCN for either CLM4.0 or +|version|). The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc cndv" -append`` @@ -103,7 +103,7 @@ PFT Plant Function Type (PFT). A type of vegetation that CLM parameterizes. PTCLM - PoinT CLM (PTCLM) a python script that operates on top of CLM for CLM4.5 to run single point simulations for CLM. + PoinT CLM (PTCLM) a python script that operates on top of CLM for +|version| to run single point simulations for CLM. Qian The Qian et. al. analysis of the NCEP forcing data. This can be used to drive CLM with atmosphere forcing from 1948 to 2004. We do NOT expect to be able to update this dataset beyond 2004. @@ -112,6 +112,6 @@ SCRIP Spherical Coordinate Remapping and Interpolation Package (SCRIP). We use it's file format for specifying both grid coordinates as well as mapping between different grids. VIC - Variable Infiltration Capacity (VIC) model for hydrology. This is an option to CLM4.5 in place of the standard CLM4.5 hydrology. The CLM_CONFIG_OPTS option for this is + Variable Infiltration Capacity (VIC) model for hydrology. This is an option to +|version| in place of the standard +|version| hydrology. The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-vichydro on" -append`` diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 02e6237e2b..b65e622b45 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -26,7 +26,7 @@ Group (LMWG) and maintained at the National Center for Atmospheric Research (NCAR). This guide is intended to instruct both the novice and experienced user on running CLM. This guide pertains to the latest version +|version| in +|cesmrelease| available for download from the public -release subversion repository as a part of CESM1.2.0. Documentation +release subversion repository as a part of +|cesmrelease|. Documentation may be different if you are using an older version, you should either use the documentation for that release version, update to the latest version, or use the documentation inside your own source tree. There @@ -34,19 +34,19 @@ is information in the ChangeLog file and in the `What is new with +|version| in +|cesmrelease| since previous public releases? `_ regarding the changes from previous versions of CESM. -.. note:: This release of CLM5.0 in CESM1.2.0 includes BOTH CLM4.0 - physics used in previous releases as well as the updated CLM4.5 +.. note:: This release of +|version| in +|cesmrelease| includes BOTH CLM4.0 + physics used in previous releases as well as the updated +|version| physics. Both CLM as well as CLM support tools allow you to trigger between the two physics modes. Most often when we refer to CLM4.0 we - are referring to the CLM4.0 physics in CLM4.5 in CESM1.2.0 rather + are referring to the CLM4.0 physics in +|version| in +|cesmrelease| rather than to a specific version of CLM4.0 (where we would give the exact - version). Likewise, when referring to CLM4.5 we are referring to the - CLM4.5 physics in CLM4.5 in CESM1.2.0. + version). Likewise, when referring to +|version| we are referring to the + +|version| physics in +|version| in +|cesmrelease|. The novice user should read `Chapter 1 `_ in detail before beginning work, while the expert user should read `What is new with -CLM4.5 in CESM1.2.0 since previous public releases? `_ and -`Quickstart to using CLM4.5 `_ chapters, and then use the ++|version| in +|cesmrelease| since previous public releases? `_ and +`Quickstart to using +|version| `_ chapters, and then use the more detailed chapters as reference. Before novice users go onto more technical problems covered in `Chapter 2 `_, `Chapter 3 `_, `Chapter 4 `_, or `Chapter 5 `_ they @@ -56,12 +56,12 @@ to replicate some of the examples given there. All users should read the `How to Use This Document `_ and `Other resources to get help from `_ sections to understand the document conventions and the various ways of getting help on using -CLM4.5. Users should also read the `What is scientifically validated -and functional in CLM4.5 in CESM1.2.0? `_ section to see if ++|version|. Users should also read the `What is scientifically validated +and functional in +|version| in +|cesmrelease|? `_ section to see if their planned use of the model is something that has been scientifically validated and well tested. Users that are NOT using NCAR machines or our list of well tested machines should also read the -What are the UNIX utilities required to use CLM4.5? section to make +What are the UNIX utilities required to use +|version|? section to make sure they have all the required UNIX utilities on the system they want to do their work. @@ -85,8 +85,8 @@ machine is working correctly. What is New with +|version| ========================= -`What's new with +|version| science `_ -The CESM1.2.0 `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. +`What's new with +|version| science `_ +The +|cesmrelease| `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. More details are given in the `CLM ChangeLog file `_. Previous release pages give similar list of changes for previous versions of the model. @@ -99,49 +99,49 @@ The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates ========================== In this introduction we first give a simple guide to understand the document conventions in `How to Use This Document `_. -The next section `What is new with CLM4.5 in CESM1.2.0 since previous public releases? `_ gives references to describe the differences between CLM4.5 in CESM1.2.0 and previous CESM releases both from a scientific as well as a software engineering point of view. -For information on previous releases of CLM4.5 before CLM4.5 in CESM1.2.0 see the CESM1.1.1 documentation. -The next section `Quickstart to using CLM4.5 `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use CLM4.5. -The next `What is scientifically validated and functional in CLM4.5 in CESM1.2.0? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. -`What are the UNIX utilities required to use CLM4.5? `_ lists the UNIX utilities required to use CLM4.5 and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. -Next we have `Important Notes and Best Practices for Usage of CLM4.5 `_ to detail some of the best practices for using CLM4.5 for science. -The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and CLM4.5. - -`Chapter 1 `_ goes into detail on how to setup and run simulations with CLM4.5 and especially how to customize cases. +The next section `What is new with +|version| in +|cesmrelease| since previous public releases? `_ gives references to describe the differences between +|version| in +|cesmrelease| and previous CESM releases both from a scientific as well as a software engineering point of view. +For information on previous releases of +|version| before +|version| in +|cesmrelease| see the CESM1.1.1 documentation. +The next section `Quickstart to using +|version| `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use +|version|. +The next `What is scientifically validated and functional in +|version| in +|cesmrelease|? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. +`What are the UNIX utilities required to use +|version|? `_ lists the UNIX utilities required to use +|version| and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. +Next we have `Important Notes and Best Practices for Usage of +|version| `_ to detail some of the best practices for using +|version| for science. +The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and +|version|. + +`Chapter 1 `_ goes into detail on how to setup and run simulations with +|version| and especially how to customize cases. Details of cesm_setup modes and build-namelist options as well as namelist options are given in this chapter. -`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or CLM4.5 physics for creating input datasets for use by CLM, for the expert user. +`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or +|version| physics for creating input datasets for use by CLM, for the expert user. There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. Then each tool is described in detail along with different ways in which the tool might be used. A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. As a followup to the tools chapter, `Chapter 3 `_ tells how to add files to the XML database for build-namelist to use. -This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and CLM4.5 physics). +This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and +|version| physics). In `Chapter 4 `_, again for the expert user, we give details on how to do some particularly difficult special cases. -For example, we give the protocol for spinning up the CLM4.5-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). +For example, we give the protocol for spinning up the +|version|-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. We also give instructions on running both the prognostic crop and irrigation models. Lastly we tell the user how to use the DATM model to send historical CO2 data to CLM. -`Chapter 5 `_ outlines how to do single-point or regional simulations using CLM4.5. -This is useful to either compare CLM4.5 simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. +`Chapter 5 `_ outlines how to do single-point or regional simulations using +|version|. +This is useful to either compare +|version| simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. There are several different ways given on how to perform single-point simulations which range from simple PTS_MODE to more complex where you create all your own datasets, tying into `Chapter 2 `_ and also `Chapter 3 `_ to add the files into the build-namelist XML database. The PTCLM python script to run single-point simulations was added back in for this release (but it has bugs that don't allow it to work out of the box). CLM4 in CESM1.0.5 has a fully working versions of PTCLM. Need `Chapter 6 `_ blurb... -`Chapter 7 `_ gives some guidance on trouble-shooting problems when using CLM4.5. +`Chapter 7 `_ gives some guidance on trouble-shooting problems when using +|version|. It doesn't cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems. `Chapter 8 `_ goes over the automated testing scripts for validating that the CLM is working correctly. -The test scripts run many different configurations and options with CLM4.0 physics as well and CLM4.5 physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. -In general this is an activity important only for a developer of CLM4.5, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. +The test scripts run many different configurations and options with CLM4.0 physics as well and +|version| physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. +In general this is an activity important only for a developer of +|version|, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. -In the appendices we talk about some issues that are useful for advanced users and developers of CLM4.5. +In the appendices we talk about some issues that are useful for advanced users and developers of +|version|. -Finally in `Appendix A `_ we give instructions on how to build the documentation associated with CLM4.5 (i.e. how to build this document). +Finally in `Appendix A `_ we give instructions on how to build the documentation associated with +|version| (i.e. how to build this document). This document is included in every CLM distribution and can be built so that you can view a local copy rather than having to go to the CESM website. This also could be useful for developers who need to update the documentation due to changes they have made. @@ -151,12 +151,12 @@ This also could be useful for developers who need to update the documentation du Best Practices ================ -- CLM4.5 includes BOTH the old CLM4.0 physics AND the new CLM4.5 physics and you can toggle between two. +- +|version| includes BOTH the old CLM4.0 physics AND the new +|version| physics and you can toggle between two. The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. - While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. - "BGC" is the new CLM4.5 biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). + While the "standard" practice for +|version| is to run with BGC on, and CRUNCEP atmospheric forcing. + "BGC" is the new +|version| biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). -- When running with CLMCN (either CLM4.0 or CLM4.5 physics) or CLM4.5-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the CLM4.5 biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for CLM4.5 or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). +- When running with CLMCN (either CLM4.0 or +|version| physics) or +|version|-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the +|version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for +|version| or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). Simulations without a proper spinup will effectively be starting from an unvegetated world. See `the Section called Setting Your Initial Conditions File in Chapter 1 `_ for information on how to provide initial conditions for your simulation. @@ -169,20 +169,20 @@ This also could be useful for developers who need to update the documentation du Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. -- Initial condition files are also provided for CLM4.5 for several configurations and resolutions. - For CLM4.5-SP and CLM4.5-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. - The CLM4.5-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. - Also the CLM4.5-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg CLM4.5-BGC-DV and 2deg CLM4.5-BGC-Crop. +- Initial condition files are also provided for +|version| for several configurations and resolutions. + For +|version|-SP and +|version|-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. + The +|version|-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. + Also the +|version|-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg +|version|-BGC-DV and 2deg +|version|-BGC-Crop. - Users can generate initial condition files at different resolutions by using the CLM tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. -- In CLM4.5 for both CLM4.5-CN and CLM4.5-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). +- In +|version| for both +|version|-CN and +|version|-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2010 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. -- Aerosol deposition is a required field to both CLM4.0 and CLM4.5 physics, sent from the atmosphere model. +- Aerosol deposition is a required field to both CLM4.0 and +|version| physics, sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index edcd0bc2fe..3091595c68 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -7,31 +7,31 @@ Running the CLM requires a suite of UNIX utilities and programs and you should make sure you have all of these available before trying to go forward with using it. If you are missing one of these you should contact the systems administrator for the machine you wish to run on and make sure they are installed. -List of utilities required for CESM in the "CESM1.2.0 Software/Operating System Prerequisites" section in `http://www.cesm.ucar.edu/models/cesm1.2//cesm/doc/usersguide/book1.html `_ +List of utilities required for CESM in the "+|cesmrelease| Software/Operating System Prerequisites" section in `http://www.cesm.ucar.edu/models/cesm1.2//cesm/doc/usersguide/book1.html `_ - UNIX bash shell (for some of the CLM tools scripts) - NCL (for some of the offline tools for creating/modifying CLM input datasets see `Chapter 2 `_ for more information on NCL) - Python (optional, needed for PTCLM) - xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide) -Before working with CLM4.5 read the QuickStart Guide in the `CESM1.2.0 Scripts User's Guide `_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM. +Before working with +|version| read the QuickStart Guide in the `+|cesmrelease| Scripts User's Guide `_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM. -For some of the details of setting up cases for CLM4.5 read the README and text files available from the "models/lnd/clm/doc" directory (see the "CLM Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. +For some of the details of setting up cases for +|version| read the README and text files available from the "$CTSMROOT/doc" directory (see the "CLM Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. 1. `README file `_ describing the directory structure. 2. `Quickstart.userdatasets `_ file describing how to use your own datasets in the model (also see `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_). -3. `models/lnd/clm/doc/KnownBugs `_ file describing known problems in CLM4.5 (that we expect to eventually fix). +3. `$CTSMROOT/doc/KnownBugs `_ file describing known problems in +|version| (that we expect to eventually fix). -4. `models/lnd/clm/doc/KnownLimitationss `_ file describing known limitations in CLM4.5 and workarounds that we do NOT expect to fix. +4. `$CTSMROOT/doc/KnownLimitationss `_ file describing known limitations in +|version| and workarounds that we do NOT expect to fix. -The IMPORTANT_NOTES file talks about important things for users to know about using the model scientifically. It content is given in the next chapter on `"What is scientifically validated and functional in CLM4.5 in CESM1.2.0?" `_. +The IMPORTANT_NOTES file talks about important things for users to know about using the model scientifically. It content is given in the next chapter on `"What is scientifically validated and functional in +|version| in +|cesmrelease|?" `_. -The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on `"What is new with CLM4.5 in CESM1.2.0 since previous public releases?" `_. +The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on `"What is new with +|version| in +|cesmrelease| since previous public releases?" `_. Note other directories have README files that explain different components and tools used when running CLM and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with CLM see `Chapter 1 `_. -The Quickstart.GUIDE (which can be found in ``models/lnd/clm/doc``) is repeated here. +The Quickstart.GUIDE (which can be found in ``$CTSMROOT/doc``) is repeated here. -.. include:: ../../clm5.0/doc/Quickstart.GUIDE +.. include:: ../../+|version|/doc/Quickstart.GUIDE :literal: diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index 7d4408bcc8..a238bee4a6 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -4,16 +4,16 @@ Scientific Validation ======================== -In this section we go over what has been extensively tested and scientifically validated with CLM4.5, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of CLM, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. +In this section we go over what has been extensively tested and scientifically validated with +|version|, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of CLM, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. -------------------------------------------------------------- Standard Configuration and Namelist Options that are Validated -------------------------------------------------------------- See -`http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for CLM4.5. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. +`http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for +|version|. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. -In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for CLM4.5 while others are for both CLM4.0 AND CLM4.5 we explicitly say which they apply to. +In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for +|version| while others are for both CLM4.0 AND +|version| we explicitly say which they apply to. --------------------------------------------------------------------------------------------------------------- Configure Modes NOT scientifically validated, documented, supported or, in some cases, even advised to be used: @@ -21,13 +21,13 @@ Configure Modes NOT scientifically validated, documented, supported or, in some These are options that you would add to ``CLM_CONFIG_OPTS``. -1. exlaklayers on[CLM4.5 only] This mode is NOT tested and may NOT be even functional. +1. exlaklayers on[+|version| only] This mode is NOT tested and may NOT be even functional. -2. snicar_frc on[CLM4.0 AND CLM4.5] This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. +2. snicar_frc on[CLM4.0 AND +|version|] This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. -3. vichydro on[CLM4.5 only] This mode is tested and functional, but does NOT have long scientific validation simulations run with it so, should be considered experimental. +3. vichydro on[+|version| only] This mode is tested and functional, but does NOT have long scientific validation simulations run with it so, should be considered experimental. -4. vsoilc_centbgc[CLM4.5 only] This option is extensively tested for both "on" and "off". The "no-vert" option has limited testing performed on it, but isn't scientifically validated (and it currently has a bug -- see 1746 and 1672 in `models/lnd/clm/doc/KnownBugs `_). The "no-cent" and "no-nitrif" options are NOT tested and as such may NOT ben even functional. +4. vsoilc_centbgc[+|version| only] This option is extensively tested for both "on" and "off". The "no-vert" option has limited testing performed on it, but isn't scientifically validated (and it currently has a bug -- see 1746 and 1672 in `$CTSMROOT/doc/KnownBugs `_). The "no-cent" and "no-nitrif" options are NOT tested and as such may NOT ben even functional. ---------------------------------------------- Namelist options that should NOT be exercised: @@ -36,10 +36,10 @@ Namelist options that should NOT be exercised: ---------------------------------------------------- Build-Namelist options that should NOT be exercised: ---------------------------------------------------- -1. -irrig with -bgc cn and -phys clm4_0 We have only run the irrigation model with CLMSP (i.e. without the CN model). We recommend that if you want to run the irrigation model with CN, that you do a spinup. But, more than that you may need to make adjustments to irrig_factor in models/lnd/clm/src/biogeophys/CanopyFluxesMod.F90. See the notes on this in the description of the irrigation model in the +1. -irrig with -bgc cn and -phys clm4_0 We have only run the irrigation model with CLMSP (i.e. without the CN model). We recommend that if you want to run the irrigation model with CN, that you do a spinup. But, more than that you may need to make adjustments to irrig_factor in $CTSMROOT/src/biogeophys/CanopyFluxesMod.F90. See the notes on this in the description of the irrigation model in the `Technical Descriptions of the Interactive Crop Management and Interactive Irrigation Models `_. -2. -irrig with -crop on and -phys clm4_0 Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to generic crop currently, which negates it's practical usage. We also have a known problem when both are on (see bug 1326 in the `models/lnd/clm/doc/KnownBugs `_ file). If you try to run in this mode, the CLM build-namelist will return with an error. +2. -irrig with -crop on and -phys clm4_0 Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to generic crop currently, which negates it's practical usage. We also have a known problem when both are on (see bug 1326 in the `$CTSMROOT/doc/KnownBugs `_ file). If you try to run in this mode, the CLM build-namelist will return with an error. -------------------------------------------- Namelist items that should NOT be exercised: diff --git a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst index 81f45a038f..1e7a5437eb 100644 --- a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst +++ b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst @@ -89,7 +89,7 @@ Also note that this site has a site-specific dynamic land-use change file for it # Note: When creating the fpftdyn dataset for this site it will use the # PTCLM_sitedata/US-Ha1_dynpftdata.txt # file for land-use change and harvesting - > ./PTCLM.py -m yellowstone_intel -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux -c I20TRCRUCLM45BGC + > ./PTCLM.py -m cheyenne_intel -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux -c I20TRCRUCLM45BGC > mkdir $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 > cd $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 # Copy data in NetCDF format to this directory, filenames should be YYYY-MM.nc diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst index f710ed0bb4..30068b600c 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -104,10 +104,10 @@ The output to the above command is as follows: Main Script Version Id: $Id: PTCLM.py 47576 2013-05-29 19:11:16Z erik $ Scripts URL: $HeadURL: https://svn-ccsm-models.cgd.ucar.edu/PTCLM/trunk_tags/PTCLM1_130529/PTCLM.py $: -Here we give a simple example of using PTCLM1 for a straightforward case of running at the US-UMB Fluxnet site on yellowstone where we already have the meteorology data on the machine. +Here we give a simple example of using PTCLM1 for a straightforward case of running at the US-UMB Fluxnet site on cheyenne where we already have the meteorology data on the machine. Note, see `the Section called Converting AmeriFlux Data for use by PTCLM `_ for permission information to use this data. -Example 6-1. Example of running PTCLM1 for US-UMB on yellowstone +Example 6-1. Example of running PTCLM1 for US-UMB on cheyenne ---------------------------------------------------------------- :: @@ -115,18 +115,18 @@ Example 6-1. Example of running PTCLM1 for US-UMB on yellowstone > setenv CSMDATA $CESMDATAROOT/inputdata > setenv MYCSMDATA $HOME/inputdata > setenv SITE US-UMB - > setenv MYMACH yellowstone_intel + > setenv MYMACH cheyenne_intel > setenv MYCASE testPTCLM # First link the standard input files to a location you have write access > cd scripts > ./link_dirtree $CSMDATA $MYCSMDATA # Next build all of the clm tools you will need - > cd ../models/lnd/clm/tools/clm4_5/mksurfdata_map + > cd ../$CTSMROOT/tools/+|version|/mksurfdata_map > gmake > gmake clean > cd ../../../../../../tools/mapping/gen_domain_files/src - > ../../../../scripts/ccsm_utils/Machines/configure -mach yellowstone -compiler intel + > ../../../../scripts/ccsm_utils/Machines/configure -mach cheyenne -compiler intel > gmake > gmake clean # next run PTCLM (NOTE -- MAKE SURE python IS IN YOUR PATH) diff --git a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst index e9a887e89c..172f041420 100644 --- a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst +++ b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst @@ -13,7 +13,7 @@ Example: Running PTCLM for the Mexicocity supported single point dataset :: > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py -m yellowstone_intel -s 1x1_mexicocityMEX -d $CSMDATA --nopointdata \ + > ./PTCLM.py -m cheyenne_intel -s 1x1_mexicocityMEX -d $CSMDATA --nopointdata \ --stdurbpt -c ICRUCLM45 --caseidprefix `pwd`/myPTCLMcases/site > cd myPTCLMcases/site_1x1_mexicocityMEX_I > ./cesm_setup @@ -29,7 +29,7 @@ Example: Running PTCLM for a spinup simulation with Qian data for tower years. :: > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py -m yellowstone_intel -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux --useQIAN --QIAN_tower_yrs + > ./PTCLM.py -m cheyenne_intel -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux --useQIAN --QIAN_tower_yrs > cd ../../../../../US-Ha1_ICRUCLM45BGC_QIAN > ./cesm_setup # Now build and run normally @@ -67,4 +67,4 @@ Example: Running PTCLM on a user-defined machine with global PFT and soil types # Here we show running interactively > ./US-UMB_ICRUCLM45BGC.userdefined_intel.run -.. warning: Because of Bug 1364, when running this case as above we get a floating point error after reaching time-step 124 for the example exactly as above. Other machines or compilers probably won't have this problem. See the `models/lnd/clm/doc/KnownBugs `_ file for more information on this problem. +.. warning: Because of Bug 1364, when running this case as above we get a floating point error after reaching time-step 124 for the example exactly as above. Other machines or compilers probably won't have this problem. See the `$CTSMROOT/doc/KnownBugs `_ file for more information on this problem. diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst index b644337239..73cf45ff88 100644 --- a/doc/source/users_guide/running-PTCLM/using-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/using-ptclm.rst @@ -8,7 +8,7 @@ There are three types of options to PTCLM1: required, setup/run-time, and datase The three required options are the three settings that MUST be specified for PTCLM to work at all. The other settings have default values that will default to something useful. The setup/run-time options control how the simulation will be setup and run. The dataset generation options control the generation of datasets needed when PTCLM is run. Most options use a double dash "--" "longname" such as "--list", but the most common options also have a short-name with a single dash (such as -m instead of --machine). The required options to PTCLM are: inputdata directory (-d), machine (-m) and site-name (-s). -Inputdata directory is the directory where you have the CESM inputdata files, you need to have write access to this directory, so if you are running on a machine that you do NOT have write access to the standard inputdata location (such as NCAR yellowstone or LBNL hopper) you need to link the standard files to a location you do have control over. We recommend using the ``scripts/link_dirtree`` tool to do that. "machine" is the scripts name for the machine/compiler you will be using for your case. And finally site-name is the name of the site that you want to run for. Site-name can either be a valid supported dataset name or a Fluxnet site name from the list of sites you are running on (see the --sitegroupname for more information about the site lists). +Inputdata directory is the directory where you have the CESM inputdata files, you need to have write access to this directory, so if you are running on a machine that you do NOT have write access to the standard inputdata location (such as NCAR cheyenne or LBNL hopper) you need to link the standard files to a location you do have control over. We recommend using the ``scripts/link_dirtree`` tool to do that. "machine" is the scripts name for the machine/compiler you will be using for your case. And finally site-name is the name of the site that you want to run for. Site-name can either be a valid supported dataset name or a Fluxnet site name from the list of sites you are running on (see the --sitegroupname for more information about the site lists). After PTCLM is run a case directory where you can then setup, build and run your CESM case as normal. It also creates a ``README.PTCLM`` in that directory that documents the commandline options to PTCLM that were used to create it. @@ -33,7 +33,7 @@ Steps in running PTCLM You need to setup an inputdata directory where you have write access to it. Normally, for NCAR machines the data is on an inputdata where the user does NOT have write access to it. A way that you can get around this is to use the **link_dirtree** script to create softlinks from the normal location to a location you have write access to. - So for example on yellowstone: + So for example on cheyenne: :: > setenv CSMDATA $CESMDATAROOT/inputdata @@ -48,11 +48,11 @@ Steps in running PTCLM Next you need to make sure all the CLM FORTRAN tools are built. :: - > cd models/lnd/clm/tools/clm4_5/mksurfdata_map + > cd $CTSMROOT/tools/+|version|/mksurfdata_map > gmake > gmake clean > cd ../../../../../../tools/mapping/gen_domain_files/src - > ../../../../scripts/ccsm_utils/Machines/configure -mach yellowstone -compiler intel + > ../../../../scripts/ccsm_utils/Machines/configure -mach cheyenne -compiler intel > gmake > gmake clean @@ -77,7 +77,7 @@ Steps in running PTCLM :: > cd scripts - > ./PTCLM.py -m yellowstone_intel -s US-UMB -d $MYCSMDATA -c ICRUCLM45BGC --use QIAN "US-UMB_I_2000_CN_QIAN" + > ./PTCLM.py -m cheyenne_intel -s US-UMB -d $MYCSMDATA -c ICRUCLM45BGC --use QIAN "US-UMB_I_2000_CN_QIAN" b. PTCLM creates datasets for you It will populate $MYCSMDATA with new datasets it creates using the CLM tools. diff --git a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst index 56d70b1d7d..ca794ac326 100644 --- a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst @@ -11,7 +11,7 @@ To setup a ``PTS_MODE`` simulation you use the "-pts_lat" and "-pts_lon" argumen :: > cd scripts - > ./create_newcase -case testPTS_MODE -res f19_g16 -compset I1850CRUCLM45BGC -pts_lat 40.0 -pts_lon -105 + > ./create_newcase -case testPTS_MODE -res f19_g17_gl4 -compset I1850Clm50BgcCropCru -pts_lat 40.0 -pts_lon -105 > cd testPTS_MODE # We make sure the model will start up cold rather than using initial conditions @@ -21,7 +21,7 @@ Then setup, build and run as normal. We make sure initial conditions are NOT use .. note:: By default it sets up to run with MPILIB=mpi-serial (in the env_build.xml file) turned on, which allows you to run the model interactively. On some machines this mode is NOT supported and you may need to change it to FALSE before you are able to build. -.. warning:: ``PTS_MODE`` currently does NOT restart nor is it able to startup from global initial condition files. See bugs "1017 and 1025" in the `models/lnd/clm/doc/KnownLimitationss `_ file. +.. warning:: ``PTS_MODE`` currently does NOT restart nor is it able to startup from global initial condition files. See bugs "1017 and 1025" in the `$CTSMROOT/doc/KnownLimitationss `_ file. .. note:: You can change the point you are simulating for at run-time by changing the values of ``PTS_LAT`` and ``PTS_LON`` in the ``env_run.xml`` file. @@ -35,6 +35,6 @@ You might also want to set the ``env_build.xml`` variable: ``MPILIB=mpi-serial`` On many machines, batch queues have a minimum number of nodes or processors that can be used. On these machines you may have to change the queue and possibly the time-limits of the job, to get it to run in the batch queue. -On the NCAR machine, yellowstone, this is done for you automatically, and the "caldera" queue is used for such single-processor simulations. +On the NCAR machine, cheyenne, this is done for you automatically, and the "caldera" queue is used for such single-processor simulations. Another way to get around this problem is to run the job interactively using ``MPILIB=mpi-serial`` so that you don't submit the job to the batch queue. For single point mode you also may want to consider using a smaller workstation or cluster, rather than a super-computer, because you can't take advantage of the multi-processing power of the super-computer anyway. diff --git a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst index 3445b0cab7..accc5381a7 100644 --- a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst @@ -11,7 +11,7 @@ However, users can create their own dataset. To get the list of supported dataset resolutions do this: :: - > cd models/lnd/clm/doc + > cd $CTSMROOT/doc > ../bld/build-namelist -res list @@ -120,7 +120,7 @@ Example: Running CLM over the single-point of Vancouver Canada with supplied atm > ./case.setup -.. warning:: If you don't set the start-year and run-length carefully as shown above the model will abort with a "dtlimit error" in the atmosphere model (see bug 1110 in the `models/lnd/clm/doc/KnownLimitationss `_ file for documentation on this). Since, the forcing data for this site (and the MexicoCity site) is less than a year, the model won't be able to run for a full year. The ``1x1_urbanc_alpha`` site has data for more than a full year, but neither year is complete hence, it has the same problem (see the problem for this site above). +.. warning:: If you don't set the start-year and run-length carefully as shown above the model will abort with a "dtlimit error" in the atmosphere model (see bug 1110 in the `$CTSMROOT/doc/KnownLimitationss `_ file for documentation on this). Since, the forcing data for this site (and the MexicoCity site) is less than a year, the model won't be able to run for a full year. The ``1x1_urbanc_alpha`` site has data for more than a full year, but neither year is complete hence, it has the same problem (see the problem for this site above). .. note:: Just like ``PTS_MODE`` above, By default it sets up to run with ``MPILIB=mpi-serial`` (in the env_build.xml file) turned on, which allows you to run the model interactively. @@ -164,17 +164,17 @@ Example: Creating a surface dataset for a single point > setenv GRIDNAME 1x1_boulderCO > setenv CDATE `date +%y%m%d` # Create the SCRIP grid file for the location and create a unity mapping file for it. - > cd models/lnd/clm/tools/shared/mkmapdata + > cd $CTSMROOT/tools/mkmapdata > ./mknoocnmap.pl -p 40,255 -n $GRIDNAME # Set pointer to MAPFILE just created that will be used later > setenv MAPFILE `pwd`/map_${GRIDNAME}_noocean_to_${GRIDNAME}_nomask_aave_da_${CDATE}.nc # create the mapping files needed by mksurfdata_map. - > cd ../../shared/mkmapdata + > cd ../.././mkmapdata > setenv GRIDFILE ../mkmapgrids/SCRIPgrid_${GRIDNAME}_nomask_${CDATE}.nc > ./mkmapdata.sh -r $GRIDNAME -f $GRIDFILE -t regional # create the domain file > cd ../../../../tools/mapping/gen_domain_files/src - > ../../../scripts/ccsm_utils/Machines/configure -mach yellowstone -compiler intel + > ../../../scripts/ccsm_utils/Machines/configure -mach cheyenne -compiler intel > gmake > cd .. > setenv OCNDOM domain.ocn_noocean.nc @@ -183,7 +183,7 @@ Example: Creating a surface dataset for a single point # Save the location where the domain file was created > setenv GENDOM_PATH `pwd` # Finally create the surface dataset - > cd ../../../../lnd/clm/tools/clm4_5/mksurfdata_map/src + > cd ../../../../lnd/clm/tools/+|version|/mksurfdata_map/src > gmake > cd .. > ./mksurfdata.pl -r usrspec -usr_gname $GRIDNAME -usr_gdate $CDATE @@ -202,11 +202,11 @@ Example: Setting up a case from the single-point surface dataset just created > ./link_dirtree $CSMDATA $MYCSMDATA # Copy the file you created above to your new $MYCSMDATA location following the CLMUSRDAT # naming convention (leave off the creation date) - > cp $CESMROOT/models/lnd/clm/tools/clm4_5/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ + > cp $CESMROOT/$CTSMROOT/tools/+|version|/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ $MYCSMDATA/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr1850.nc > cd $CESMROOT/scripts - > ./create_newcase -case my_usernldatasets_test -res CLM_USRDAT -compset I1850CRUCLM45BGC \ - -mach yellowstone_intel + > ./create_newcase -case my_usernldatasets_test -res CLM_USRDAT -compset I1850Clm50BgcCropCru \ + -mach cheyenne_intel > cd my_usernldatasets_test > ./xmlchange DIN_LOC_ROOT=$MYCSMDATA # Set the path to the location of gen_domain set in the creation step above diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst index efb2f6b4aa..c92892ba8d 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst @@ -1,21 +1,21 @@ .. _spinning-up-clm45-bgc: ====================== - Spinup of CLM4.5-BGC + Spinup of +|version|-BGC ====================== -To get the CLM4.5-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. +To get the +|version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). **1. 45_AD_SPINUP** For the first step of running 1000+ years in "-bgc_spinup on" mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: -Example:: AD_SPINUP Simulation for CLM4.5-BGC +Example:: AD_SPINUP Simulation for +|version|-BGC -------------------------------------------------------- :: > cd scripts - > ./create_newcase -case BGC_spinup -res f19_g16 -compset I1850CRUCLM45BGC -mach yellowstone_intel + > ./create_newcase -case BGC_spinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru -mach cheyenne_intel > cd BGC_spinup # Append "-spinup on" to CLM_BLDNML_OPTS > ./xmlchange CLM_BLDNML_OPTS="-bgc_spinup on" -append @@ -33,19 +33,19 @@ Example:: AD_SPINUP Simulation for CLM4.5-BGC # Now run normally > ./BGC_spinup.submit -.. note:: This same procedure works for CLM4.5-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. +.. note:: This same procedure works for +|version|-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. Afterwards save the last restart file from this simulation to use in the next step. -**2. Final spinup for CLM4.5-BGC** +**2. Final spinup for +|version|-BGC** Next save the last restart file from this step and use it as the "finidat" file to use for one more spinup for at least 200+ years in normal mode. So do the following: -Example: Final CLMBGC Spinup Simulation for CLM4.5-BGC +Example: Final CLMBGC Spinup Simulation for +|version|-BGC ------------------------------------------------------------------ :: > cd scripts - > ./create_newcase -case BGC_finalspinup -res f19_g16 -compset I1850CRUCLM45BGC -mach yellowstone_intel + > ./create_newcase -case BGC_finalspinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru -mach cheyenne_intel > cd BGC_finalspinup # Now, Copy the last CLM restart file from the earlier case into your run directory > cp /ptmp/$LOGIN/archive/BGC_spinup/rest/BGC_spinup.clm*.r*.1002-01-01-00000.nc \ @@ -69,7 +69,7 @@ Example: Final CLMBGC Spinup Simulation for CLM4.5-BGC To assess if the model is spunup plot trends of CLMBGC variables of interest. If you see a trend, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. -.. note:: This same final spinup procedure works for CLM4.5-CN as well, you can typically shorten the spinup time from 200 years to 50 though. +.. note:: This same final spinup procedure works for +|version|-CN as well, you can typically shorten the spinup time from 200 years to 50 though. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst index 709a1b26a6..36f2266493 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst @@ -7,15 +7,15 @@ Because it takes so long to spinup the CN model (as we just saw previously), if you are doing fully coupled simulations with active atmosphere and ocean, you will want to do the spinup portion of this "offline". So instead of doing expensive fully coupled simulations for the spinup duration, you run CLM in a very cheap "I" compset using atmospheric forcing from a shorter fully coupled simulation (or a simulation run previously by someone else). -In this example we will use the ``I1850SPINUPCN compset`` to setup CLM to run with atmospheric forcing from a previous fully coupled simulation with data that is already stored on disk on yellowstone. -There are several simulations that have high frequency data for which we can do this. You can also do this on a machine other than yellowstone, but would need to download the data from the Earth System Grid and change the datapath similar to `Example 4-11 `_. +In this example we will use the ``I1850Clm50BgcSpinup compset`` to setup CLM to run with atmospheric forcing from a previous fully coupled simulation with data that is already stored on disk on cheyenne. +There are several simulations that have high frequency data for which we can do this. You can also do this on a machine other than cheyenne, but would need to download the data from the Earth System Grid and change the datapath similar to `Example 4-11 `_. -Example: Simulation with MOAR Data on yellowstone +Example: Simulation with MOAR Data on cheyenne ------------------------------------------------------------- :: > cd scripts - > ./create_newcase -case MOARforce1850 -res f19_g16 -compset I1850SPINUPCN -mach yellowstone_intel + > ./create_newcase -case MOARforce1850 -res f19_g17_gl4 -compset I1850Clm50BgcSpinup -mach cheyenne_intel > cd MOARforce1850 # The following sets the casename to point to for atm forcing (you could also use an editor) > ./xmlchange DATM_CPL_CASE=b40.1850.track1.1deg.006a @@ -28,4 +28,4 @@ Example: Simulation with MOAR Data on yellowstone > ./MOARforce1850.submit -.. warning: Because of bug 1339 (see the `models/lnd/clm/doc/KnownBugs `_ file on this) you can't run with 83 or more years of forcing. If you do need to run with more years of forcing, you'll need to address the issue as outlined in the `models/lnd/clm/doc/KnownBugs `_ file. +.. warning: Because of bug 1339 (see the `$CTSMROOT/doc/KnownBugs `_ file on this) you can't run with 83 or more years of forcing. If you do need to run with more years of forcing, you'll need to address the issue as outlined in the `$CTSMROOT/doc/KnownBugs `_ file. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst index 7d523f7324..5cad7c1c5e 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst @@ -7,14 +7,14 @@ Another way that you might want to spinup the model is to run your own simulation for a relatively short period (either a B, E, or F compset) and then use it as forcing for your "I" case later. By only running 20 to 50 years for the fully coupled case, you'll save a substantial amount of computer time rather than running the entire spinup period with a fully coupled model. -The first thing we need to do is to run a fully coupled case and save the atmospheric coupling fields on a three hourly basis. In this example, we will run on yellowstone and archive the data to a local disk that we can then use in the next simulation. +The first thing we need to do is to run a fully coupled case and save the atmospheric coupling fields on a three hourly basis. In this example, we will run on cheyenne and archive the data to a local disk that we can then use in the next simulation. Example: Fully Coupled Simulation to Create Data to Force Next Example Simulation ---------------------------------------------------------------------------------------------- :: > cd scripts - > ./create_newcase -case myBCN1850 -res f09_g16 -compset B1850CN -mach yellowstone_intel + > ./create_newcase -case myBCN1850 -res f09_g17_gl4 -compset B1850CN -mach cheyenne_intel > cd myBCN1850 > ./cesm_setup # Set histaux_a2x3hr to .true. in your user_nl_cpl output from the atmosphere model @@ -35,7 +35,7 @@ Example: Fully Coupled Simulation to Create Data to Force Next Example Simulatio # Now run as normal > ./myBCN1850.submit -.. warning:: Because of bug 1733 (see the `models/lnd/clm/doc/KnownBugs `_ file on this) you'll need to edit the driver code in order for it to produce the correct list of fields needed to run the model later. +.. warning:: Because of bug 1733 (see the `$CTSMROOT/doc/KnownBugs `_ file on this) you'll need to edit the driver code in order for it to produce the correct list of fields needed to run the model later. Now we run an I compset forced with the data from the previous simulation using the ``CPLHIST3HrWx`` option to DATM_MODE. See `the Section called CPLHIST3HrWx mode and it's DATM settings in Chapter 1 `_ for more information on the DATM settings for ``CPLHIST3HrWx`` mode. @@ -44,7 +44,7 @@ Example: Simulation Forced with Data from the Previous Simulation :: > cd scripts - > ./create_newcase -case frcwmyBCN1850 -res f09_g16 -compset I1850SPINUPCN -mach yellowstone_intel + > ./create_newcase -case frcwmyBCN1850 -res f09_g17_gl4 -compset I1850Clm50BgcSpinup -mach cheyenne_intel > cd frcWmyBCN1850 # The following sets the casename to point to for atm forcing (you could also use an editor) > ./xmlchange DATM_CPLHIST_CASE="myBCN1850" @@ -53,7 +53,7 @@ Example: Simulation Forced with Data from the Previous Simulation > ./xmlchange DATM_CPLHIST_YR_ALIGN="1",DATM_CPLHIST_YR_START=1,DATM_CPLHIST_YR_END=20 # Set the strm_datdir in the namelist_defaults_datm.xml # file to the archival path of the case above in the form of: /glade/home/achive/$USER/$DATM_CPLHIST_CASE/cpl/hist - # NOTE: THIS WILL CHANGE THE PATH FOR ALL I1850SPINUPCN COMPSET CASES MADE AFTER THIS! + # NOTE: THIS WILL CHANGE THE PATH FOR ALL I1850Clm50BgcSpinup COMPSET CASES MADE AFTER THIS! > $EDITOR ../../models/atm/datm/bld/namelist_files/namelist_defaults_datm.xml > ./cesm_setup # Now build and run as normal @@ -61,7 +61,7 @@ Example: Simulation Forced with Data from the Previous Simulation > ./frcwmyBCN1850.submit -.. note:: We did this by editing the "namelist_defaults_datm.xml" which will change the settings for ALL future ``I1850SPINUPCN`` cases you run. You could also do this by editing the path in the resulting streams text files in the CaseDocs directory, and then create a "user\_" streams file with the correct path. This would change the streams file JUST for this case. The steps do it this way are: +.. note:: We did this by editing the "namelist_defaults_datm.xml" which will change the settings for ALL future ``I1850Clm50BgcSpinup`` cases you run. You could also do this by editing the path in the resulting streams text files in the CaseDocs directory, and then create a "user\_" streams file with the correct path. This would change the streams file JUST for this case. The steps do it this way are: :: diff --git a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst index 854450ff12..f81634d456 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst @@ -27,7 +27,7 @@ The datafile is a CF-compliant NetCDF file with the data that will be mapped. The streams text file is the XML-like file that tells datm how to find the files and how to map the variables datm knows about to the variable names on the NetCDF files. Note, that in our case the domain file and the data file are the same file. In other cases, the domain file may be separate from the data file. First we are going to create a case, and we will edit the ``user_nl_datm`` so that we add a CO2 data stream in. -There is a streams text file available in ``models/lnd/clm/doc/UsersGuide/co2_streams.txt``, that includes file with a CO2 time-series from 1765 to 2007. +There is a streams text file available in ``$CTSMROOT/doc/UsersGuide/co2_streams.txt``, that includes file with a CO2 time-series from 1765 to 2007. Example: Transient Simulation with Historical CO2 @@ -35,7 +35,7 @@ Example: Transient Simulation with Historical CO2 :: > cd scripts - > ./create_newcase -case DATM_CO2_TSERIES -res f19_g16 -compset I20TRCRUCLM45BGC + > ./create_newcase -case DATM_CO2_TSERIES -res f19_g17_gl4 -compset I20TRCRUCLM45BGC > cd DATM_CO2_TSERIES # Set CCSM_BGC to CO2A so that CO2 will be passed from atmosphere to land @@ -50,7 +50,7 @@ Example: Transient Simulation with Historical CO2 This is a streams file to pass historical CO2 from datm8 to the other surface models. It reads in a historical dataset derived from data used - by CAM. The getco2_historical.ncl script in models/lnd/clm2/tools/ncl_scripts + by CAM. The getco2_historical.ncl script in $CTSMROOT2/tools/ncl_scripts was used to convert the CAM file to a streams compatible format (adding domain information and making CO2 have latitude/longitude even if only for a single point. @@ -106,7 +106,7 @@ Example: Transient Simulation with Historical CO2 > ./preview_namelists The first thing we will do is to edit the ``user_nl_datm`` file to add a CO2 file stream in. -To do this we will copy a ``user_nl_datm`` in with the changes needed. The file ``addco2_user_nl_datm.user_nl`` is in ``models/lnd/clm/doc/UsersGuide`` and looks like this... +To do this we will copy a ``user_nl_datm`` in with the changes needed. The file ``addco2_user_nl_datm.user_nl`` is in ``$CTSMROOT/doc/UsersGuide`` and looks like this... :: dtlimit = 1.5,1.5,1.5,1.5,1.5 @@ -123,12 +123,12 @@ To do this we will copy a ``user_nl_datm`` in with the changes needed. The file You just copy this into your case directory. But, also compare it to the version in ``CaseDocs`` to make sure the changes are just to add in the new CO2 stream. Check to see that filenames, and start, end and align years are correct. :: - > cp ../../models/lnd/clm/doc/UsersGuide/addco2_user_nl_datm.user_nl user_nl_datm + > cp ../../$CTSMROOT/doc/UsersGuide/addco2_user_nl_datm.user_nl user_nl_datm > diff user_nl_datm CaseDocs/datm_atm_in Once, you've done that you can build and run your case normally. -.. warning:: This procedure assumes you are using a ``I20TRCRUCLM45BGC`` compset out of the box, with ``DATM_PRESAERO`` equal to trans_1850-2000. So it assumes standard CLM4.5 CRUNCEP atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here your ``user_nl_datm`` file will need to be adjusted to work with it. +.. warning:: This procedure assumes you are using a ``I20TRCRUCLM45BGC`` compset out of the box, with ``DATM_PRESAERO`` equal to trans_1850-2000. So it assumes standard +|version| CRUNCEP atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here your ``user_nl_datm`` file will need to be adjusted to work with it. .. note:: The intent of the ``user_nl_datm`` is to add an extra streams file for CO2 to the end of the streams variable, and other arrays associated with streams (adding mapalgo as a new array with bilinear for everything, but the CO2 file which should be "nn" for nearest neighbor). Other variables should be the same as the other stream values. diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst index af69b010da..95231e9041 100644 --- a/doc/source/users_guide/running-special-cases/index.rst +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -16,7 +16,7 @@ Running Special Cases running-the-prognostic-crop-model.rst running-with-irrigation.rst CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst - CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst + CLM-4.4-Spinning-up-the-+|version|-biogeochemistry-(CLMBGC-spinup).rst CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst diff --git a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst index 31691e721d..3ed3b3f0f1 100644 --- a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst +++ b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst @@ -4,7 +4,7 @@ Running the prognostic crop model =================================== -The prognostic crop model is setup to work with CLM4.5-BGC or CLM4.0-CN (with or without DV) for present day conditions and we have surface and initial condition datasets at f19 resolution. +The prognostic crop model is setup to work with +|version|-BGC or CLM4.0-CN (with or without DV) for present day conditions and we have surface and initial condition datasets at f19 resolution. In order to use the initial condition file, we need to set the ``RUN_TYPE`` to startup rather than ``hybrid`` since the compset for f19 sets up to use an initial condition file without crop active. To activate the crop model you can choose a compset that has "CROP" in the name such as "ICRUCLM45BGCCROP" or simply add "-crop on" to ``CLM_CONFIG_OPTS``. @@ -13,7 +13,7 @@ Example: Crop Simulation :: > cd scripts - > ./create_newcase -case CROP -res f19_g16 -compset I1850CRUCLM45BGC + > ./create_newcase -case CROP -res f19_g17_gl4 -compset I1850Clm50BgcCropCru > cd CROP # Append "-crop on" to CLM_CONFIG_OPTS in env_build.xml (you could also use an editor) diff --git a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst index 4a39f6ec5f..feef7d0bd4 100644 --- a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst +++ b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst @@ -4,8 +4,8 @@ Running with irrigation =================================== -In CLM4.5 irrigation can ONLY be used WITH crop. -To turn on irrigation in CLM4.5 we simply add "-irrig on" to ``CLM_BLDNML_OPTS``. +In +|version| irrigation can ONLY be used WITH crop. +To turn on irrigation in +|version| we simply add "-irrig on" to ``CLM_BLDNML_OPTS``. Just as in the crop example we also change ``RUN_TYPE`` to ``startup`` so that we don't use an initial condition file that is incompatible with irrigation. Example: Irrigation Simulation @@ -14,7 +14,7 @@ Example: Irrigation Simulation # Note here we do a CLMSP simulation as that is what has been validated > cd scripts - > ./create_newcase -case IRRIG -res f19_g16 -compset I + > ./create_newcase -case IRRIG -res f19_g17_gl4 -compset I > cd IRRIG # Append "-irrig" to CLM_BLDNML_OPTS in env_run.xml (you could also use an editor) diff --git a/doc/source/users_guide/runsed.csh b/doc/source/users_guide/runsed.csh new file mode 100755 index 0000000000..56e3445397 --- /dev/null +++ b/doc/source/users_guide/runsed.csh @@ -0,0 +1,6 @@ +#!/bin/csh + +foreach file ( */*.rst ) + sed -f sedscript.txt $file > $file.tmp + mv $file.tmp $file +end diff --git a/doc/source/users_guide/sedscript.txt b/doc/source/users_guide/sedscript.txt new file mode 100644 index 0000000000..ca537f84a6 --- /dev/null +++ b/doc/source/users_guide/sedscript.txt @@ -0,0 +1,17 @@ +s/CLM4.5/+|version|/g +s/clm4.5/+|version|/g +s/CLM5.0/+|version|/g +s/clm5.0/+|version|/g +s/CESM2.0/+|cesmrelease|/g +s/cesm2.0/+|cesmrelease|/g +s/CESM1.2.0/+|cesmrelease|/g +s/cesm1.2.0/+|cesmrelease|/g +s#models/lnd/clm#$CTSMROOT#g +s#tools/shared/#tools/#g +s#shared/#./#g +s/yellowstone/cheyenne/g +s/I1850SPINUPCN/I1850Clm50BgcSpinup/g +s/I1850CRUCLM45BGC/I1850Clm50BgcCropCru/g +s/I1850CRUCLM45BGC/I1850Clm50BgcCrop/g +s/f19_g16/f19_g17_gl4/g +s/f09_g16/f09_g17_gl4/g diff --git a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst index 806d76d966..e108901b27 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst @@ -25,12 +25,12 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) | Short Name | Description | Atm. | Compset Alias | Period | | | | Forcing | Name | | +============+==============+===========+=================+================+ -| CLM4.5SP | Satellite | CRUNCEP | 1850CRUCLM45 | 1850 | +| +|version|SP | Satellite | CRUNCEP | 1850CRUCLM45 | 1850 | | | phenology | | | | | | with new | | | | | | biogeophys | | | | +------------+--------------+-----------+-----------------+----------------+ -| CLM4.5SP | New | CRUNCEP | I1850CRUCLM45BGC| 1850 | +| +|version|SP | New | CRUNCEP | I1850Clm50BgcCropCru| 1850 | | | biogeophys | +-----------------+----------------+ | | + CENTURY- | | I20TRCRUCLM45BGC| 20th Century | | | like | | | | @@ -42,7 +42,7 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) | | nitrogen | | | | | | updates | | | | +------------+--------------+-----------+-----------------+----------------+ -| CLM4.5CN | New | CRUNCEP | I1850CRUCLM45CN | 1850 | +| +|version|CN | New | CRUNCEP | I1850CRUCLM45CN | 1850 | | | biogeophys | | | | | | + CN soil | | | | | | BGC, updates | | | | @@ -74,7 +74,7 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) | Short Name | Description | Atm. | Compset Alias | Period | | | | Forcing | Name | | +============+===================+===================+=================+========+ -| CLM4.5BGC- | ICRUCLM45BGCCROP | New biogeophys + | CRUNCEP | 2000 | +| +|version|BGC- | ICRUCLM45BGCCROP | New biogeophys + | CRUNCEP | 2000 | | CROP | | CENTURY-like | | | | | | vertically | | | | | | resolved soil | | | @@ -85,7 +85,7 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) | | | CROP | | | | | | | | | +------------+-------------------+-------------------+-----------------+--------+ -| CLM4.5BGC- | I1850CRUCLM45BGCDV| New biogeophys | CRUNCEP | 1850 | +| +|version|BGC- | I1850Clm50BgcCropCruDV| New biogeophys | CRUNCEP | 1850 | | DV | | + CENTURY-like | | | | | | vertically | | | | | | resolved soil | | | @@ -97,7 +97,7 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) | | | | | | | | | | | | +------------+-------------------+-------------------+-----------------+--------+ -| CLM4.5SP- | ICLM45VIC | Satellite | Qian | 2000 | +| +|version|SP- | ICLM45VIC | Satellite | Qian | 2000 | | VIC | | phenology with new| | | | | | biogeophys with | | | | | | VIC hydrology | | | @@ -132,9 +132,9 @@ Alias (Long-name with time-period and each component) #. ``I1850CRUCLM45`` (1850_DATM%CRU_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) -#. ``I1850CRUCLM45BGC`` (1850_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) +#. ``I1850Clm50BgcCropCru`` (1850_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) -#. ``I1850CRUCLM45BGCDV`` (1850_DATM%CRU_CLM45%BGCDV_SICE_SOCN_RTM_SGLC_SWAV) +#. ``I1850Clm50BgcCropCruDV`` (1850_DATM%CRU_CLM45%BGCDV_SICE_SOCN_RTM_SGLC_SWAV) #. ``I1850CRUCLM45CN`` (1850_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) @@ -142,7 +142,7 @@ Alias (Long-name with time-period and each component) #. ``I1850SPINUPCLM45BGC`` (1850_DATM%S1850_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) -#. ``I1850SPINUPCN`` (1850_DATM%S1850_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) +#. ``I1850Clm50BgcSpinup`` (1850_DATM%S1850_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) #. ``I1PT`` (2000_DATM%1PT_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index e4cafcf046..4e211894d6 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -4,7 +4,7 @@ Customizing CLM's Configuration ******************************* -The "Creating a Case" section of the `CESM1.2.0 Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. +The "Creating a Case" section of the `+|cesmrelease| Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called there are two steps that take place: @@ -12,9 +12,9 @@ For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called 2. The CLM "**build-namelist**" script is called to generate the run-time namelist for CLM (more information on **build-namelist** is given below in `the Section called Definition of Namelist items and their default values `_. -When customizing your case at the *8cesm_setup** step you are able to modify the process by effecting either one or both of these steps. The CLM "**configure**" and "**build-namelist**" scripts are both available in the "models/lnd/clm/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. +When customizing your case at the *8cesm_setup** step you are able to modify the process by effecting either one or both of these steps. The CLM "**configure**" and "**build-namelist**" scripts are both available in the "$CTSMROOT/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. -There are five different types of customization for the configuration that we will discuss: CLM4.5 in CESM1.2.0 build-time options, CLM4.5 in CESM1.2.0 run-time options, User Namelist, other noteworthy CESM1.2.0 configuration items, the CLM **configure** script options, and the CLM **build-namelist** script options. +There are five different types of customization for the configuration that we will discuss: +|version| in +|cesmrelease| build-time options, +|version| in +|cesmrelease| run-time options, User Namelist, other noteworthy +|cesmrelease| configuration items, the CLM **configure** script options, and the CLM **build-namelist** script options. Information on all of the script, configuration, build and run items is found under ``scripts/ccsm_utils/Case.template`` in the `config_definition.xml `_ file. @@ -51,7 +51,7 @@ CLM_NML_USE_CASE ``CLM_NML_USE_CASE`` is used to set a particular set of conditions that set multiple namelist items, all centering around a particular usage of the model. To list the valid options do the following: :: - > cd models/lnd/clm/doc + > cd $CTSMROOT/doc > ../bld/build-namelist -use_case list The output of the above command is: @@ -109,7 +109,7 @@ CLM_BLDNML_OPTS As with the CLM "configure" script the CLM clm.buildnml.csh may already invoke certain options and as such those options will NOT be available to be set here. The best way to see what options can be sent to the "build-namelist" script is to do :: - > cd models/lnd/clm/bld + > cd $CTSMROOT/bld > ./build-namelist -help Here is the output from the above. @@ -179,7 +179,7 @@ CLM_BLDNML_OPTS -inputdata "filepath" Writes out a list containing pathnames for required input datasets in file specified. - -irrig "value" If .true. turn irrigation on with namelist logical irrigate (for CLM4.5 physics) + -irrig "value" If .true. turn irrigation on with namelist logical irrigate (for +|version| physics) (requires crop to be on in the clm configuration) Seek surface datasets with irrigation turned on. (for CLM4.0 physics) Default: .false. @@ -284,7 +284,7 @@ Hence only the following different options can be set: #. -verbose -"-bgc_spinup" is an option only available for CLM4.5 for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See `the Section called Spinning up the CLM4.5 biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for an example using this option. +"-bgc_spinup" is an option only available for +|version| for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See `the Section called Spinning up the +|version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for an example using this option. "-chk_res" ensures that the resolution chosen is supported by CLM. If the resolution is NOT supported it will cause the CLM **build-namelist** to abort when run. So when either **preview_namelist**, **$CASE.build** or **$CASE.run** is executed it will abort early. Since, the CESM scripts only support certain resolutions anyway, in general this option is NOT needed in the context of running CESM cases. @@ -296,7 +296,7 @@ Hence only the following different options can be set: To see a list of valid variables that you could set do this: :: - > cd models/lnd/clm/doc + > cd $CTSMROOT/doc > ../bld/build-namelist -clm_demand list @@ -317,13 +317,13 @@ When "-irrig" is used **build-namelist** will try to find surface datasets that "-rcp" is used to set the representative concentration pathway for the future scenarios you want the data-sets to simulate conditions for, in the input datasets. To list the valid options do the following: :: - > cd models/lnd/clm/doc + > cd $CTSMROOT/doc > ../bld/build-namelist -rcp list "-sim_year" is used to set the simulation year you want the data-sets to simulate conditions for in the input datasets. The simulation "year" can also be a range of years in order to do simulations with changes in the dataset values as the simulation progresses. To list the valid options do the following: :: - > cd models/lnd/clm/doc + > cd $CTSMROOT/doc > ../bld/build-namelist -sim_year list ``CLM_NAMELIST_OPTS`` @@ -355,7 +355,7 @@ When "-irrig" is used **build-namelist** will try to find surface datasets that For example if your ``CLM_USRDAT_NAME`` will be "1x1_boulderCO", with a "navy" land-mask, constant simulation year range, for 1850, the following will list what your filenames should be: :: - > cd models/lnd/clm/bld + > cd $CTSMROOT/bld > queryDefaultNamelist.pl -usrname "1x1_boulderCO" -options mask=navy,sim_year=1850,sim_year_range="constant" -csmdata $CSMDATA An example of using ``CLM_USRDAT_NAME`` for a simulation is given in `Example 5-4 `_. @@ -464,11 +464,11 @@ Especially with CLMBGC and CLMCN starting from initial conditions is very import Doing a hybrid simulation to provide initial conditions ------------------------------------------------------- -The first option is to setup a hybrid simulation and give a ``RUN_REFCASE`` and ``RUN_REFDATE`` to specify the reference case simulation name to use. When you setup most cases, at the standard resolutions of "f09" or "f19" it will already do this for you. For example, if you run an "I2000CN" compset at "f09_g16" resolution the following settings will already be done for you. +The first option is to setup a hybrid simulation and give a ``RUN_REFCASE`` and ``RUN_REFDATE`` to specify the reference case simulation name to use. When you setup most cases, at the standard resolutions of "f09" or "f19" it will already do this for you. For example, if you run an "I2000CN" compset at "f09_g17_gl4" resolution the following settings will already be done for you. -``./xmlchange RUN_TYPE=hybrid,RUN_REFCASE=I2000CN_f09_g16_c100503,RUN_REFDATE=0001-01-01,GET_REFCASE=TRUE`` +``./xmlchange RUN_TYPE=hybrid,RUN_REFCASE=I2000CN_f09_g17_gl4_c100503,RUN_REFDATE=0001-01-01,GET_REFCASE=TRUE`` -Setting the ``GET_REFCASE`` option to ``TRUE means`` it will copy the files from the: ``$DIN_LOC_ROOT/ccsm4_init/I2000CN_f09_g16_c100503/0001-01-01`` directory. Note, that the ``RUN_REFCASE`` and ``RUN_REFDATE`` variables are expanded to get the directory name above. If you do NOT set ``GET_REFCASE`` to ``TRUE`` then you will need to have placed the file in your run directory yourself. In either case, the file is expected to be named: ``$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc`` with the variables expanded of course. +Setting the ``GET_REFCASE`` option to ``TRUE means`` it will copy the files from the: ``$DIN_LOC_ROOT/ccsm4_init/I2000CN_f09_g17_gl4_c100503/0001-01-01`` directory. Note, that the ``RUN_REFCASE`` and ``RUN_REFDATE`` variables are expanded to get the directory name above. If you do NOT set ``GET_REFCASE`` to ``TRUE`` then you will need to have placed the file in your run directory yourself. In either case, the file is expected to be named: ``$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc`` with the variables expanded of course. ------------------------------------------------------- Doing a branch simulation to provide initial conditions @@ -483,7 +483,7 @@ Providing a finidat file in your user_nl_clm file Setting up a branch or hybrid simulation requires the initial condition file to follow a standard naming convention, and a standard input directory if you use the ``GET_REFCASE`` option. If you want to name your file willy nilly and place it anywhere, you can set it in your ``user_nl_clm`` file as in this example. :: - finidat = '/glade/home/$USER/myinitdata/clmi_I1850CN_f09_g16_0182-01-01.c120329.nc' + finidat = '/glade/home/$USER/myinitdata/clmi_I1850CN_f09_g17_gl4_0182-01-01.c120329.nc' Note, if you provide an initial condition file -- you can NOT set ``CLM_FORCE_COLDSTART`` to ``TRUE``. @@ -530,7 +530,7 @@ If you are running an B, E, or F case that doesn't use the DATM obviously the DA CPLHIST3HrWx ``CLMCRUNCEP`` - The standard mode for CLM4.5 of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010. + The standard mode for +|version| of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010. See `the Section called CLMCRUNCEP mode and it's DATM settings `_ for more information on the DATM settings for ``CLMCRUNCEP`` mode. ``CLM_QIAN`` @@ -582,9 +582,9 @@ Downloading DATM Forcing Data In Chapter One of the `CESM User's Guide `_ there is a section on "Downloading input data". The normal process of setting up cases will use the "scripts/ccsm_utils/Tools/check_input_data" script to retrieve data from the CESM subversion inputdata repository. This is true for the standard `CLM_QIAN` forcing as well. -The `CLMCRUNCEP` data is uploaded into the subversion inputdata repository as well -- but as it is 1.1 Terabytes of data downloading it is problematic (*IT WILL TAKE SEVERAL DAYS TO DOWNLOAD THE ENTIRE DATASET USING SUBVERSION*). Because of it's size you may also need to download it onto a separate disk space. We have done that on yellowstone for example where it resides in ``$ENV{CESMROOT}/lmwg`` while the rest of the input data resides in ``$ENV{CESMDATAROOT}/inputdata``. The data is also already available on: janus, franklin, and hopper. If you download the data, we recommend that you break your download into several chunks, by setting up a case and setting the year range for ``DATM_CPL_YR_START`` and ``DATM_CPL_YR_END`` in say 20 year sections over 1901 to 2010, and then use **check_input_data** to export the data. +The `CLMCRUNCEP` data is uploaded into the subversion inputdata repository as well -- but as it is 1.1 Terabytes of data downloading it is problematic (*IT WILL TAKE SEVERAL DAYS TO DOWNLOAD THE ENTIRE DATASET USING SUBVERSION*). Because of it's size you may also need to download it onto a separate disk space. We have done that on cheyenne for example where it resides in ``$ENV{CESMROOT}/lmwg`` while the rest of the input data resides in ``$ENV{CESMDATAROOT}/inputdata``. The data is also already available on: janus, franklin, and hopper. If you download the data, we recommend that you break your download into several chunks, by setting up a case and setting the year range for ``DATM_CPL_YR_START`` and ``DATM_CPL_YR_END`` in say 20 year sections over 1901 to 2010, and then use **check_input_data** to export the data. -The ``CPLHIST3HrWx`` DATM forcing data is unique -- because it is large compared to the rest of the input data, and we only have a disk copy on yellowstone. The DATM assumes the path for the previous NCAR machine yellowstone of ``/glade/p/cesm/shared_outputdata/cases/ccsm4/$DATM_CPLHIST_CASE`` for the data. So you will need to change this path in order to run on any other machine. You can download the data itself from NCAR HPSS from ``/CCSM/csm/$DATM_CPLHIST_CASE``. +The ``CPLHIST3HrWx`` DATM forcing data is unique -- because it is large compared to the rest of the input data, and we only have a disk copy on cheyenne. The DATM assumes the path for the previous NCAR machine cheyenne of ``/glade/p/cesm/shared_outputdata/cases/ccsm4/$DATM_CPLHIST_CASE`` for the data. So you will need to change this path in order to run on any other machine. You can download the data itself from NCAR HPSS from ``/CCSM/csm/$DATM_CPLHIST_CASE``. -------------------------------------- Customizing via the build script files @@ -601,7 +601,7 @@ The final thing that the user may wish to do before **cesm_setup** is run is to More information on the CLM configure script -------------------------------------------- -The CLM **configure** script defines the details of a clm configuration and summarizes it into a ``config_cache.xml`` file. The ``config_cache.xml`` will be placed in your case directory under ``Buildconf/clmconf``. The `config_definition.xml `_ in ``models/lnd/clm/bld/config_files`` gives a definition of each CLM configuration item, it is viewable in a web-browser. Many of these items are things that you would NOT change, but looking through the list gives you the valid options, and a good description of each. Below we repeat the ``config_definition.xml`` files contents: +The CLM **configure** script defines the details of a clm configuration and summarizes it into a ``config_cache.xml`` file. The ``config_cache.xml`` will be placed in your case directory under ``Buildconf/clmconf``. The `config_definition.xml `_ in ``$CTSMROOT/bld/config_files`` gives a definition of each CLM configuration item, it is viewable in a web-browser. Many of these items are things that you would NOT change, but looking through the list gives you the valid options, and a good description of each. Below we repeat the ``config_definition.xml`` files contents: Help on CLM configure --------------------- @@ -609,7 +609,7 @@ Help on CLM configure Coupling this with looking at the options to CLM **configure** with "-help" as below will enable you to understand how to set the different options. :: - > cd models/lnd/clm/bld + > cd $CTSMROOT/bld > configure -help The output to the above command is as follows: @@ -632,7 +632,7 @@ The output to the above command is as follows: (default: CLM build directory). -clm4me Turn Methane model: [on | off] Requires bgc=cn/cndv (Carbon Nitrogen model) - (ONLY valid for CLM4.5!) + (ONLY valid for +|version|!) -clm_root Root directory of clm source code (default: directory above location of this script) -cppdefs A string of user specified CPP defines. Appended to @@ -647,12 +647,12 @@ The output to the above command is as follows: Parameters relating to the build which are system dependent will be ignored. -exlaklayers Turn on extra lake layers (25 layers instead of 10) [on | off] - (ONLY valid for CLM4.5!) + (ONLY valid for +|version|!) -help [or -h] Print usage to STDOUT. -nofire Turn off wildfires for BGC setting of CN (default includes fire for CN) -noio Turn history output completely off (typically for testing). - -phys Value of clm4_0 or clm4_5 (default is clm4_0) + -phys Value of clm4_0 or +|version| (default is clm4_0) -silent [or -s] Turns on silent mode - only fatal messages issued. -sitespf_pt Setup for the given site specific single-point resolution. -snicar_frc Turn on SNICAR radiative forcing calculation. [on | off] @@ -676,7 +676,7 @@ The output to the above command is as follows: eliminate inconsistent duplicate soil hydraulic parameters used in soil biogeochem. (requires either CN or CNDV) - (ONLY valid for CLM4.5!) + (ONLY valid for +|version|!) [on,off or colon delimited list of no options] (default off) no-vert Turn vertical soil Carbon profile off no-cent Turn CENTURY off diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst index 131078c648..2300c8ad60 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst @@ -16,16 +16,16 @@ Definition of Namelist items and their default values Here we point to you where you can find the definition of each namelist item and separately the default values for them. The default values may change depending on the resolution, land-mask, simulation-year and other attributes. Both of these files are viewable in your web browser, and then expand each in turn. -1. `Definition of Namelists Relevant for CLM4.5 `_ +1. `Definition of Namelists Relevant for +|version| `_ 2. `Default values of each CLM4.0 Namelist Item `_ -3. `Default values of each CLM4.5 Namelist Item `_ +3. `Default values of each +|version| Namelist Item `_ List of fields that can be added to your output history files by namelist ------------------------------------------------------------------------- -One set of the namelist items allows you to add fields to the output history files: ``hist_fincl1``, ``hist_fincl2``, ``hist_fincl3``, ``hist_fincl4``, ``hist_fincl5``, and ``hist_fincl6``. The following links for `CLM4.0 History Fields `_ and `CLM4.5 History Fields `_ documents all of the history fields available and gives the long-name and units for each. The table below lists all the CLM4.5 history fields. +One set of the namelist items allows you to add fields to the output history files: ``hist_fincl1``, ``hist_fincl2``, ``hist_fincl3``, ``hist_fincl4``, ``hist_fincl5``, and ``hist_fincl6``. The following links for `CLM4.0 History Fields `_ and `+|version| History Fields `_ documents all of the history fields available and gives the long-name and units for each. The table below lists all the +|version| history fields. Definition of CLM history variables ----------------------------------- @@ -53,7 +53,7 @@ Below we will give examples of user namelists that activate different commonly u The default namelist -------------------- -Here we give the default namelist as it would be created for an "I1850CRUCLM45BGC" compset at 0.9x1.25 resolution with a gx1v6 land-mask on yellowstone. To edit the namelist you would edit the ``user_nl_clm`` user namelist with just the items you want to change. For simplicity we will just show the CLM namelist and NOT the entire file. In the sections below, for simplicity we will just show the user namelist (``user_nl_clm``) that will add (or modify existing) namelist items to the namelist. +Here we give the default namelist as it would be created for an "I1850Clm50BgcCropCru" compset at 0.9x1.25 resolution with a gx1v6 land-mask on cheyenne. To edit the namelist you would edit the ``user_nl_clm`` user namelist with just the items you want to change. For simplicity we will just show the CLM namelist and NOT the entire file. In the sections below, for simplicity we will just show the user namelist (``user_nl_clm``) that will add (or modify existing) namelist items to the namelist. Example 1-2. Default CLM Namelist --------------------------------- @@ -66,7 +66,7 @@ Example 1-2. Default CLM Namelist create_crop_landunit = .false. dtime = 1800 fatmlndfrc = '/glade/p/cesm/cseg/inputdata/share/domains/domain.lnd.fv0.9x1.25_gx1v6.090309.nc' - finidat = '$DIN_LOC_ROOT/lnd/clm2/initdata_map/clmi.I1850CRUCLM45BGC.0241-01-01.0.9x1.25_g1v6_simyr1850_c130531.nc' + finidat = '$DIN_LOC_ROOT/lnd/clm2/initdata_map/clmi.I1850Clm50BgcCropCru.0241-01-01.0.9x1.25_g1v6_simyr1850_c130531.nc' fpftcon = '/glade/p/cesm/cseg/inputdata/lnd/clm2/pftdata/pft-physiology.c130503.nc' fsnowaging = '/glade/p/cesm/cseg/inputdata/lnd/clm2/snicardata/snicar_drdt_bst_fit_60_c070416.nc' fsnowoptics = '/glade/p/cesm/cseg/inputdata/lnd/clm2/snicardata/snicar_optics_5bnd_c090915.nc' diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index 91db57fc70..d41124f8ba 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -20,37 +20,37 @@ CIME Testing scripts We first introduce the test scripts that work for all CESM components. The CIME script **create_test** runs a specific type of test, at a given resolution, for a given compset using a given machine. There is a list of different tests, but the "ERI" tests do several things at once, running from startup, as well as doing exact branch and restart tests. -So to run "ERI" testing at 2-degree with the I1850CRUCLM45 compset on yellowstone_intel you do the following. +So to run "ERI" testing at 2-degree with the I1850CRUCLM45 compset on cheyenne_intel you do the following. :: > cd scripts - > ./create_test -testname ERI.f19_g16.I1850CRUCLM45.yellowstone_intel - > cd ERI.f19_g16.I1850CRUCLM45.yellowstone_intel.$id - > ./ERI.f19_g16.I1850CRUCLM45.yellowstone_intel.$id.build - > ERI.f19_g16.I1850CRUCLM45.yellowstone_intel.$id.submit + > ./create_test -testname ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel + > cd ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel.$id + > ./ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel.$id.build + > ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel.$id.submit When the test is done it will update the file TestStatus with either a PASS or FAIL message. -We already have a standard list of tests for clm (the "aux_clm" list of tests). To run the CLM yellowstone intel compiler test list, for the same machine and compiler you would do the following: +We already have a standard list of tests for clm (the "aux_clm" list of tests). To run the CLM cheyenne intel compiler test list, for the same machine and compiler you would do the following: :: > cd scripts - > ./create_test -xml_mach yellowstone -xml_compiler intel -xml_category aux_clm -mach yellowstone -compiler intel + > ./create_test -xml_mach cheyenne -xml_compiler intel -xml_category aux_clm -mach cheyenne -compiler intel # Normally it will submit the jobs as they are ready, but if it's interrupted you # may need to submit by hand as follows... # Submit the suite of tests (note $id refers to the integer job number for this job) - > ./cs.submit.$id.yellowstone + > ./cs.submit.$id.cheyenne # Later check the tests with... > ./cs.status.$id # The above will give a PASS or FAIL message for each test. -For more information on doing testing with the CESM scripts see the `CESM1.2.0 User's Guide `_ on testing. +For more information on doing testing with the CESM scripts see the `+|cesmrelease| User's Guide `_ on testing. Testing PTCLM ============= There is a simple test script for PTCLM called ``testcases.csh`` in the PTCLM directory (``scripts/ccsm_utils/Tools/lnd/clm/PTCLM``). -The test script is setup to run on the machines: yellowstone, frankfurt, yong, and titan. +The test script is setup to run on the machines: cheyenne, frankfurt, yong, and titan. You simply run the script interactively. The script will write out the status of tests to a file called: ``tc.job#.status``. diff --git a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst index 5a2fb07192..625865b7c1 100644 --- a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst +++ b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst @@ -18,7 +18,7 @@ Setup Problems The first type of problem happens when you invoke the **case.setup** command. This indicates there is something wrong with your input datasets, or the details of what you are trying to setup the model to do. -There's also a trouble-shooting chapter in the `CESM1.2.0 Scripts User's Guide `_. +There's also a trouble-shooting chapter in the `+|cesmrelease| Scripts User's Guide `_. Many of the problems with configuration can be resolved with the guidelines given there. Here we will restrict ourselves to problems from the input files. @@ -27,7 +27,7 @@ Example: Missing datasets :: > ./create_newcase -case ne60rcp6 -res ne60_g16 -compset IRCP60CN \ - -mach yellowstone_intel + -mach cheyenne_intel > ./case.setup The following is what is displayed to the screen. @@ -100,7 +100,7 @@ Below we show the log file results of a job that aborted while running. Sun Jun 20 18:24:35 MDT 2010 -- CSM EXECUTION HAS FINISHED Model did not complete - see /ptmp/erik/test_run/run/cpl.log.100620-182358 -In the next section we will talk about using the different log files to track down problems, and find out where the problem is coming from. In the section after that we give some general advice on debugging problems and some suggestions on ideas that may be helpful to track the problem down. Some of the examples below are from the `models/lnd/clm/doc/KnownBugs `_ file. +In the next section we will talk about using the different log files to track down problems, and find out where the problem is coming from. In the section after that we give some general advice on debugging problems and some suggestions on ideas that may be helpful to track the problem down. Some of the examples below are from the `$CTSMROOT/doc/KnownBugs `_ file. Tracking Problems by Querying Log Files --------------------------------------- @@ -146,10 +146,10 @@ For example, here is some output from an older version of CESM (CESM1.0.2) where NODE# NAME ( 0) be1105en.ucar.edu - "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/lnd/clm/src/riverroute/RtmMod.F90", line + "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/$CTSMROOT/src/riverroute/RtmMod.F90", line 239: 1525-155 The file name provided in the OPEN statement for unit 1 has zero length or contains all blanks. The program will recover by ignoring the OPEN statement. - "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/lnd/clm/src/riverroute/RtmMod.F90", line + "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/$CTSMROOT/src/riverroute/RtmMod.F90", line 241: 1525-001 The READ statement on the file fort.1 cannot be completed because the end of the file was reached. The program will stop. @@ -291,12 +291,12 @@ The CLM log file Of course when you are working with and making changes to CLM, most of your focus will be on the CLM log file and the errors it shows. As already pointed out if you don't see errors in the ``lnd.log.*`` file you should look in the ``cesm.log.*`` to see if any errors showed up there. -Here's an example of the ``lnd.log.*`` file when running ``PTS_MODE`` with initial conditions (this is bug 1025 in the `models/lnd/clm/doc/KnownLimitationss `_ file). +Here's an example of the ``lnd.log.*`` file when running ``PTS_MODE`` with initial conditions (this is bug 1025 in the `$CTSMROOT/doc/KnownLimitationss `_ file). :: Successfully initialized variables for accumulation - reading restart file I2000CN_f09_g16_c100503.clm2.r.0001-01-01-00000.nc + reading restart file I2000CN_f09_g17_gl4_c100503.clm2.r.0001-01-01-00000.nc Reading restart dataset ERROR - setlatlon.F:Cant get variable dim for lat or lsmlat ENDRUN: called without a message string @@ -319,7 +319,7 @@ Here's an example of a problem that occurs when the wrong prescribed aerosol fil The batch log files ------------------- -The names of the batch log files will depend on the batch system of the machine that is being used. They will normally be in the script directory. Usually, they don't contain important information, but they are a last resort place to look for error messages. On the NCAR system "yellowstone" the batch files are called with names that start with the batch submission script and then either "stderr.o" or "stdout.o", with the job number at the end. +The names of the batch log files will depend on the batch system of the machine that is being used. They will normally be in the script directory. Usually, they don't contain important information, but they are a last resort place to look for error messages. On the NCAR system "cheyenne" the batch files are called with names that start with the batch submission script and then either "stderr.o" or "stdout.o", with the job number at the end. General Advice on Debugging Run time Problems ============================================= diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst index ec626641e5..774e4651e6 100644 --- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -106,7 +106,7 @@ More details on each environment variable. .. note:: There are several files that are copies of the original files from either models``/lnd/clm/src/util_share``, ``models/csm_share/shr``, or copies from other tool directories. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well. -The *README.filecopies* (which can be found in ``models/lnd/clm/tools``) is repeated here. +The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here. -.. include:: ../../clm5.0/tools/README.filecopies +.. include:: ../../+|version|/tools/README.filecopies :literal: diff --git a/doc/source/users_guide/using-clm-tools/cprnc.rst b/doc/source/users_guide/using-clm-tools/cprnc.rst index e921858b4c..53169513f0 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.rst +++ b/doc/source/users_guide/using-clm-tools/cprnc.rst @@ -26,4 +26,4 @@ Options: See the **cprnc** `README `_ file for more details. -.. note:: To compare files with OUT a time axis you can use the **cprnc.ncl** NCL script in ``models/lnd/clm/tools/shared/ncl_scripts``. It won't give you the details on the differences but will report if the files are identical or different. +.. note:: To compare files with OUT a time axis you can use the **cprnc.ncl** NCL script in ``$CTSMROOT/tools/ncl_scripts``. It won't give you the details on the differences but will report if the files are identical or different. diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index 332aa5bd65..006c6b679b 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -15,7 +15,7 @@ SCRIP grid files for all the standard model resolutions and the raw surface data Using mknocnmap.pl to create grid and maps for single-point regional grids -------------------------------------------------------------------------- -If you want to create a regular latitude/longitude single-point or regional grid, we suggest you use **mknoocnmap.pl** in ``models/lnd/clm/tools/shared/mkmapdata`` which will create both the SCRIP grid file you need (using ``models/lnd/clm/tools/shared/mkmapgrids/mkscripgrid.ncl`` AND an identity mapping file assuming there is NO ocean in your grid domain. If you HAVE ocean in your domain you could modify the mask in the SCRIP grid file for ocean, and then use **ESMF_RegridWeightGen** to create the mapping file, and **gen_domain** to create the domain file. Like other tools, ``shared/mkmapdata/mknoocnmap.pl`` has a help option with the following: +If you want to create a regular latitude/longitude single-point or regional grid, we suggest you use **mknoocnmap.pl** in ``$CTSMROOT/tools/mkmapdata`` which will create both the SCRIP grid file you need (using ``$CTSMROOT/tools/mkmapgrids/mkscripgrid.ncl`` AND an identity mapping file assuming there is NO ocean in your grid domain. If you HAVE ocean in your domain you could modify the mask in the SCRIP grid file for ocean, and then use **ESMF_RegridWeightGen** to create the mapping file, and **gen_domain** to create the domain file. Like other tools, ``./mkmapdata/mknoocnmap.pl`` has a help option with the following: :: SYNOPSIS @@ -43,20 +43,20 @@ See `Figure 2-5 `_ for a visual representation of this process. ``mkmapdata.sh`` uses the above SCRIP grid input files to create SCRIP mapping data files (uses ESMF). -The bash shell script ``models/lnd/clm/tools/shared/mkmapgrids/mkmapdata.sh`` uses **ESMF_RegridWeightGen** to create a list of maps from the raw datasets that are input to **mksurfdata_map**. +The bash shell script ``$CTSMROOT/tools/mkmapgrids/mkmapdata.sh`` uses **ESMF_RegridWeightGen** to create a list of maps from the raw datasets that are input to **mksurfdata_map**. Each dataset that has a different grid, or land-mask needs a different mapping file for it, but many different raw datasets share the same grid/land-mask as other files. Hence, there doesn't need to be a different mapping file for EACH raw dataset -- just for each DIFFERENT raw dataset. See `Figure 2-3 `_ for a visual representation of how this works. The bash script figures out which mapping files it needs to create and then runs **ESMF_RegridWeightGen** for each one. You can then either enter the datasets into the XML database (see `Chapter 3 `_ or leave the files in place, and use the "-res usrspec -usr_gname -usr_gdate" options to **mksurfdata_map** (see `the Section called Running mksurfdata.pl `_ below). -Use the "-phys" option to specify if you are creating mapping files for clm4_0 or clm4_5 (the list of raw datafiles is somewhat different between the two). +Use the "-phys" option to specify if you are creating mapping files for clm4_0 or +|version| (the list of raw datafiles is somewhat different between the two). mkmapdata.sh has a help option with the following :: - ../../tools/shared/mkmapdata/mkmapdata.sh + ../../tools/mkmapdata/mkmapdata.sh ********************** - usage on yellowstone: + usage on cheyenne: ./mkmapdata.sh valid arguments: @@ -74,8 +74,8 @@ mkmapdata.sh has a help option with the following Model output grid type supported values are [regional,global], (default is global) [-p|--phys ] - Whether to generate mapping files for clm4_0 or clm4_5 - supported values are [clm4_0,clm4_5], (default is clm4_5) + Whether to generate mapping files for clm4_0 or +|version| + supported values are [clm4_0,+|version|], (default is +|version|) [-b|--batch] Toggles batch mode usage. If you want to run in batch mode @@ -107,7 +107,7 @@ mkmapdata.sh has a help option with the following ********************** -.. warning:: Make sure you specify with the "-phys" option if you are creating files for CLM4.0! The default is CLM4.5. +.. warning:: Make sure you specify with the "-phys" option if you are creating files for CLM4.0! The default is +|version|. Figure 2-3. Details of running mkmapdata.sh ------------------------------------------- diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index d1ab21e2b7..8f43d8ac0a 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -25,7 +25,7 @@ Creating a Complete Set of Files for Input to CLM 1. Create SCRIP grid datasets (if NOT already done) - First you need to create a descriptor file for your grid, that includes the locations of cell centers and cell corners. There is also a "mask" field, but in this case the mask is set to one everywhere (i.e. all of the masks for the output model grid are "nomask"). An example SCRIP grid file is: $CSMDATA/lnd/clm2/mappingdata/grids/SCRIPgrid_10x15_nomask_c110308.nc. The mkmapgrids and mkscripgrid.ncl NCL script in the models/lnd/clm/tools/shared/mkmapgrids directory can help you with this. SCRIP grid files for all the standard CLM grids are already created for you. See the Section called Creating an output SCRIP grid file at a resolution to run the model on for more information on this. + First you need to create a descriptor file for your grid, that includes the locations of cell centers and cell corners. There is also a "mask" field, but in this case the mask is set to one everywhere (i.e. all of the masks for the output model grid are "nomask"). An example SCRIP grid file is: $CSMDATA/lnd/clm2/mappingdata/grids/SCRIPgrid_10x15_nomask_c110308.nc. The mkmapgrids and mkscripgrid.ncl NCL script in the $CTSMROOT/tools/mkmapgrids directory can help you with this. SCRIP grid files for all the standard CLM grids are already created for you. See the Section called Creating an output SCRIP grid file at a resolution to run the model on for more information on this. 2. Create domain dataset (if NOT already done) @@ -33,11 +33,11 @@ Creating a Complete Set of Files for Input to CLM 3. Create mapping files for mksurfdata_map (if NOT already done) - Create mapping files for mksurfdata_map with mkmapdata.sh in models/lnd/clm/tools/shared/mkmapdata. See the Section called Creating mapping files that mksurfdata_map will use for more information on this. + Create mapping files for mksurfdata_map with mkmapdata.sh in $CTSMROOT/tools/mkmapdata. See the Section called Creating mapping files that mksurfdata_map will use for more information on this. 4. Create surface datasets - Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or clm4_5 for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this. + Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or +|version| for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this. 5. Create some sort of initial condition dataset @@ -49,19 +49,19 @@ Creating a Complete Set of Files for Input to CLM b. Use interpinic to interpolate existing initial condition datasets - The next option is to interpolate from spunup datasets at a different resolution, using interpinic. There is a version for either clm4_0 or clm4_5 for this program. See the Section called Using interpinic to interpolate initial conditions to different resolutions for more information on this. + The next option is to interpolate from spunup datasets at a different resolution, using interpinic. There is a version for either clm4_0 or +|version| for this program. See the Section called Using interpinic to interpolate initial conditions to different resolutions for more information on this. c. Start up from arbitrary initial conditions - The last alternative is to run from arbitrary initial conditions without using any spun-up datasets. This is inappropriate when using CLM4.5-BGC or CLMCN (bgc=cn or cndv) as it takes a long time to spinup Carbon pools. + The last alternative is to run from arbitrary initial conditions without using any spun-up datasets. This is inappropriate when using +|version|-BGC or CLMCN (bgc=cn or cndv) as it takes a long time to spinup Carbon pools. .. warning:: This is NOT recommended as many fields in CLM take a long time to equilibrate. 6. Enter the new datasets into the build-namelist XML database The last optional thing to do is to enter the new datasets into the build-namelist XML database. See Chapter 3 for more information on doing this. This is optional because the user may enter these files into their namelists manually. The advantage of entering them into the database is so that they automatically come up when you create new cases. -The ``models/lnd/clm/tools/README`` goes through the complete process for creating input files needed to run CLM. We repeat that file here: +The ``$CTSMROOT/tools/README`` goes through the complete process for creating input files needed to run CLM. We repeat that file here: -.. include:: ../../clm5.0/tools/README +.. include:: ../../+|version|/tools/README :literal: diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst index e71c97cf3d..4bb40f21c6 100644 --- a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst @@ -5,28 +5,28 @@ ======================== There are several tools provided with CLM that allow you to create your own input datasets at resolutions you choose, or to interpolate initial conditions to a different resolution, or used to compare CLM history files between different cases. -The tools are all available in the ``models/lnd/clm/tools`` directory. -Most of the tools are FORTRAN stand-alone programs in their own directory, but there is also a suite of NCL scripts in the ``shared/ncl_scripts`` directory, and some of the tools are scripts that may also call the ESMF regridding program. +The tools are all available in the ``$CTSMROOT/tools`` directory. +Most of the tools are FORTRAN stand-alone programs in their own directory, but there is also a suite of NCL scripts in the ``./ncl_scripts`` directory, and some of the tools are scripts that may also call the ESMF regridding program. Some of the NCL scripts are very specialized and not meant for general use, and we won't document them here. They still contain documentation in the script itself and the README file in the tools directory. -The tools are divided into three directories for three categories: clm4_0, clm4_5, and shared. -The first two are of course for tools that are designed to work with either the CLM4.0 or CLM4.5 versions of the model. +The tools are divided into three directories for three categories: clm4_0, +|version|, and shared. +The first two are of course for tools that are designed to work with either the CLM4.0 or +|version| versions of the model. The last one are shared utilities that can be used by either, or have a "-phys" option so you can specify which version you want to use. The list of generally important scripts and programs are as follows. 1. *tools/cprnc* (relative to top level directory) to compare NetCDF files with a time axis. -#. *shared/mkmapgrids* to create SCRIP grid data files from old CLM format grid files that can then be used to create new CLM datasets (deprecated). There is also a NCL script (``shared/mkmapgrids/mkscripgrid.ncl`` to create SCRIP grid files for regular latitude/longitude grids. +#. *./mkmapgrids* to create SCRIP grid data files from old CLM format grid files that can then be used to create new CLM datasets (deprecated). There is also a NCL script (``./mkmapgrids/mkscripgrid.ncl`` to create SCRIP grid files for regular latitude/longitude grids. -#. *shared/mkmapdata* to create SCRIP mapping data file from SCRIP grid files (uses ESMF). +#. *./mkmapdata* to create SCRIP mapping data file from SCRIP grid files (uses ESMF). -#. *shared/gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. +#. *./gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. -#. *mksurfdata_map* to create surface datasets from grid datasets (clm4_0 and clm4_5 versions). +#. *mksurfdata_map* to create surface datasets from grid datasets (clm4_0 and +|version| versions). -#. *shared/mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or clm4_5. +#. *./mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or +|version|. In the sections to come we will go into detailed description of how to use each of these tools in turn. First, however we will discuss the common environment variables and options that are used by all of the FORTRAN tools. @@ -56,9 +56,9 @@ Namelists that you create should be similar to the example namelist. The namelist values are also documented along with the other namelists in the: :: - models/lnd/clm/bld/namelist_files/namelist_definition.xml`` file + $CTSMROOT/bld/namelist_files/namelist_definition.xml`` file and default values in the: - models/lnd/clm/bld/namelist_files/namelist_defaults_clm_tools.xml`` file. + $CTSMROOT/bld/namelist_files/namelist_defaults_clm_tools.xml`` file. ----------------------------------------------- Running FORTRAN tools with command line options @@ -75,14 +75,14 @@ Running FORTRAN tools built with SMP=TRUE When you enable ``SMP=TRUE`` on your build of one of the tools that make use of it, you are using OpenMP for shared memory parallelism (SMP). In SMP loops are run in parallel with different threads run on different processors all of which access the same memory (called on-node). Thus you can only usefully run up to the number of processors that are available on a single-node of the machine you are running on. -For example, on the NCAR machine yellowstone there are 16 processors per node, but the SMT hardware on the machine allows you to submit twice as many threads or 32 threads. +For example, on the NCAR machine cheyenne there are 16 processors per node, but the SMT hardware on the machine allows you to submit twice as many threads or 32 threads. --------- Using NCL --------- -In the tools directory ``models/lnd/clm/tools/shared/ncl_scripts`` and in a few other locations there are scripts that use NCAR Command Language (NCL). +In the tools directory ``$CTSMROOT/tools/ncl_scripts`` and in a few other locations there are scripts that use NCAR Command Language (NCL). Unlike the FORTRAN tools, you will need to get a copy of NCL in order to use them. You also won't have to build an executable in order to use them, hence no Makefile is provided. NCL is provided for free download as either binaries or source code from: `http://www.ncl.ucar.edu/ `_. From 518d92c09fcfc7ad85eaa37715bf2d804ea09097 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 14 Jun 2018 15:08:14 -0600 Subject: [PATCH 166/255] Straighten out some of the issues from the global sed script --- .../users_guide/overview/getting-help.rst | 12 +- .../users_guide/overview/quickstart.rst | 2 +- ...LM5.0-biogeochemistry-(CLMBGC-spinup).rst} | 0 .../running-special-cases/index.rst | 2 +- .../choosing-a-compset.rst | 282 ------------------ .../building-the-clm-tools.rst | 2 +- .../creating-surface-datasets.rst | 2 +- 7 files changed, 10 insertions(+), 292 deletions(-) rename doc/source/users_guide/running-special-cases/{CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst => CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst} (100%) diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 42df1b989a..f78349e1ff 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -33,17 +33,17 @@ The main CLM web page contains information on the CLM, it's history, developers, Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files: - `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_0.xml `_ -- definition of CLM4.0 namelist items. -- `$CTSMROOT/bld/namelist_files/namelist_definition_+|version|.xml `_ -- definition of CLM4.0 namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_5.xml `_ -- definition of CLM4.5/CLM5.0 namelist items. - `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_0.xml `_ -- default values for CLM4.0 namelist items. -- `$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|.xml `_ -- default values for +|version| namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_5.xml `_ -- default values for CLM4.5/CLM5.0 namelist items. - `scripts/ccsm_utils/Case.template/config_definition.xml `_ -- definition of all env_*.xml items. - `scripts/ccsm_utils/Case.template/config_compsets.xml `_ -- definition of all the compsets. - `$CTSMROOT/bld/namelist_files/history_fields_clm4_0.xml `_ -- definition of CLM4.0 history fields. -- `$CTSMROOT/bld/namelist_files/history_fields_+|version|.xml `_ -- definition of +|version| history fields. +- `$CTSMROOT/bld/namelist_files/history_fields_clm4_5.xml `_ -- definition of CLM4.5/CLM5.0 history fields. ------------------------- +---------------------------- Reporting bugs in +|version| ------------------------- +---------------------------- If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for +|version| in +|cesmrelease| is in the $CTSMROOT/doc/KnownBugs file, and the list of issues for +|cesmrelease| is at... `http://www.cesm.ucar.edu/models/cesm1.2//tags/+|cesmrelease|/#PROBLEMS `_. @@ -64,7 +64,7 @@ CLM CLMBGC Community Land Model (+|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is - ``./xmlchange CLM_CONFIG_OPTS="phys +|version| -bgc cn -vsoilc_centbgc on -clm4me on"`` + ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc cn -vsoilc_centbgc on -clm4me on"`` CLMCN Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or +|version|) The CLM_CONFIG_OPTS option for this is diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index 3091595c68..fa62be5422 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -33,5 +33,5 @@ Note other directories have README files that explain different components and t The Quickstart.GUIDE (which can be found in ``$CTSMROOT/doc``) is repeated here. -.. include:: ../../+|version|/doc/Quickstart.GUIDE +.. include:: ../../clm5.0/doc/Quickstart.GUIDE :literal: diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst similarity index 100% rename from doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM4.5-biogeochemistry-(CLMBGC-spinup).rst rename to doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst index 95231e9041..693c83d550 100644 --- a/doc/source/users_guide/running-special-cases/index.rst +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -16,7 +16,7 @@ Running Special Cases running-the-prognostic-crop-model.rst running-with-irrigation.rst CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst - CLM-4.4-Spinning-up-the-+|version|-biogeochemistry-(CLMBGC-spinup).rst + CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst diff --git a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst index e108901b27..38bfcd7da1 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst @@ -19,293 +19,11 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) `Supported CLM Configurations `_ are listed in `Table 1-1 `_ for the Scientifically Supported compsets (have been scientifically validated with long simulations) and in `Table 1-2 `_ for the Functionally Supported compsets (we've only checked that they function). -**Scientifically Supported I Compsets:** - -+------------+--------------+-----------+-----------------+----------------+ -| Short Name | Description | Atm. | Compset Alias | Period | -| | | Forcing | Name | | -+============+==============+===========+=================+================+ -| +|version|SP | Satellite | CRUNCEP | 1850CRUCLM45 | 1850 | -| | phenology | | | | -| | with new | | | | -| | biogeophys | | | | -+------------+--------------+-----------+-----------------+----------------+ -| +|version|SP | New | CRUNCEP | I1850Clm50BgcCropCru| 1850 | -| | biogeophys | +-----------------+----------------+ -| | + CENTURY- | | I20TRCRUCLM45BGC| 20th Century | -| | like | | | | -| | vertically | | | | -| | resolved | | | | -| | soil | | | | -| | BGC + CH4 | | | | -| | emissions, | | | | -| | nitrogen | | | | -| | updates | | | | -+------------+--------------+-----------+-----------------+----------------+ -| +|version|CN | New | CRUNCEP | I1850CRUCLM45CN | 1850 | -| | biogeophys | | | | -| | + CN soil | | | | -| | BGC, updates | | | | -+------------+--------------+-----------+-----------------+----------------+ -| CLM4SP | As in | Qian | I1850 | 1850 | -| | CCSM4/CESM1 | +-----------------+----------------+ -| | release | | I | 2000 | -| | | +-----------------+----------------+ -| | | | I20TR | 20th Century | -+------------+--------------+-----------+-----------------+----------------+ -| CLM4CN | As in | Qian | I1850CN | 1850 | -| | CCSM4/CESM1 | +-----------------+----------------+ -| | release | | ICN | 2000 | -| | | +-----------------+----------------+ -| | | | I20TRCN | 20th Century | -| | | +-----------------+----------------+ -| | | | IRCP26CN | RCP 2.6 to 2100| -| | | +-----------------+----------------+ -| | | | IRCP45CN | RCP 4.5 to 2100| -| | | +-----------------+----------------+ -| | | | IRCP60CN | RCP 6.0 to 2100| -| | | +-----------------+----------------+ -| | | | IRCP85CN | RCP 8.5 to 2100| -+------------+--------------+-----------+-----------------+----------------+ - -**Functionally Supported I Compsets:** - -+------------+-------------------+-------------------+-----------------+--------+ -| Short Name | Description | Atm. | Compset Alias | Period | -| | | Forcing | Name | | -+============+===================+===================+=================+========+ -| +|version|BGC- | ICRUCLM45BGCCROP | New biogeophys + | CRUNCEP | 2000 | -| CROP | | CENTURY-like | | | -| | | vertically | | | -| | | resolved soil | | | -| | | BGC + CH4 | | | -| | | emissions, | | | -| | | nitrogen updates | | | -| | | with prognostic | | | -| | | CROP | | | -| | | | | | -+------------+-------------------+-------------------+-----------------+--------+ -| +|version|BGC- | I1850Clm50BgcCropCruDV| New biogeophys | CRUNCEP | 1850 | -| DV | | + CENTURY-like | | | -| | | vertically | | | -| | | resolved soil | | | -| | | BGC + CH4 | | | -| | | emissions, | | | -| | | nitrogen updates | | | -| | | with DV | | | -| | | | | | -| | | | | | -| | | | | | -+------------+-------------------+-------------------+-----------------+--------+ -| +|version|SP- | ICLM45VIC | Satellite | Qian | 2000 | -| VIC | | phenology with new| | | -| | | biogeophys with | | | -| | | VIC hydrology | | | -+------------+-------------------+-------------------+-----------------+--------+ -|CLM4CN-CROP | ICNCROP | As in CCSM4/CESM1 | Qian | 2000 | -| | | release | | | -+------------+-------------------+-------------------+-----------------+--------+ -|CLM4CN-DV | ICNDV | As in CCSM4/CESM1 | Qian | 1850 | -| | | release | | | -+------------+-------------------+-------------------+-----------------+--------+ - Here is the entire list of compsets available. Note that using the "-user_compset" option even more combinations are possible. In the list below we give the alias name and then the long name which describes each component in parenthesis. Alias (Long-name with time-period and each component) -1. ``I`` (2000_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850`` (1850_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CLM45`` (1850_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CLM45BGC`` (1850_DATM%QIA_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CLM45CN`` (1850_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CLM45CNF`` (1850_DATM%QIA_CLM45%CN_SICE_SOCN_RTM%FLOOD_SGLC_SWAV) - -#. ``I1850CN`` (1850_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CRU`` (1850_DATM%CRU_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CRUCLM45`` (1850_DATM%CRU_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850Clm50BgcCropCru`` (1850_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850Clm50BgcCropCruDV`` (1850_DATM%CRU_CLM45%BGCDV_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CRUCLM45CN`` (1850_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850CRUCN`` (1850_DATM%CRU_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850SPINUPCLM45BGC`` (1850_DATM%S1850_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1850Clm50BgcSpinup`` (1850_DATM%S1850_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1PT`` (2000_DATM%1PT_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I1PTCLM45`` (2000_DATM%1PT_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TR`` (20TR_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCLM45`` (20TR_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCLM45CN`` (20TR_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCN`` (20TR_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCRU`` (20TR_DATM%CRU_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCRUCLM45`` (20TR_DATM%CRU_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCRUCLM45BGC`` (20TR_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCRUCLM45CN`` (20TR_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I20TRCRUCN`` (20TR_DATM%CRU_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I4804`` (4804_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I4804CLM45`` (4804_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I4804CLM45CN`` (4804_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``I4804CN`` (4804_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45`` (2000_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45BGC`` (2000_DATM%QIA_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45BGCCROP`` (2000_DATM%QIA_CLM45%BGC-CROP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45BGCDV`` (2000_DATM%QIA_CLM45%BGCDV_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45BGCDVCROP`` (2000_DATM%QIA_CLM45%BGCDV-CROP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45BGCNoVS`` (2000_DATM%QIA_CLM45%NoVS_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45CN`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45CNCROP`` (2000_DATM%QIA_CLM45%CN-CROP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45CNDV`` (2000_DATM%QIA_CLM45%CNDV_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45CNTEST`` (2003_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV_TEST) - -#. ``ICLM45CRUBGC`` (2000_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45GLCMEC`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV_TEST) - -#. ``ICLM45SNCRFRC`` (2000_DATM%QIA_CLM45%SP-SNCR_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45USUMB`` (2000_DATM%1PT_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%1x1_US-UMB) - -#. ``ICLM45VIC`` (2000_DATM%QIA_CLM45%SP-VIC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICLM45alaskaCN`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%13x12pt_f19_alaskaUSA) - -#. ``ICN`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICNCROP`` (2000_DATM%QIA_CLM40%CN-CROP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICNDV`` (2000_DATM%QIA_CLM40%CNDV_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICNDVCROP`` (2000_DATM%QIA_CLM40%CNDV-CROP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICNTEST`` (2003_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV_TEST) - -#. ``ICRU`` (2000_DATM%CRU_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICRUCLM45`` (2000_DATM%CRU_CLM45_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICRUCLM45BGC`` (2000_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICRUCLM45BGCCROP`` (2000_DATM%CRU_CLM45%BGC-CROP_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICRUCLM45BGCTEST`` (2003_DATM%CRU_CLM45%BGC_SICE_SOCN_RTM_SGLC_SWAV_TEST) - -#. ``ICRUCLM45CN`` (2000_DATM%CRU_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ICRUCN`` (2000_DATM%CRU_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IG`` (2000_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG1850`` (1850_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG1850CLM45`` (1850_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG1850CLM45CN`` (1850_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG1850CN`` (1850_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG20TR`` (20TR_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG20TRCLM45`` (20TR_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG20TRCLM45CN`` (20TR_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG20TRCN`` (20TR_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG4804`` (4804_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG4804CLM45`` (4804_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG4804CLM45CN`` (4804_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IG4804CN`` (4804_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGCLM45`` (2000_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGCLM45CN`` (2000_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGCN`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGLCMEC`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV_TEST) - -#. ``IGRCP26CLM45CN`` (RCP2_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP26CN`` (RCP2_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP45CLM45CN`` (RCP4_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP45CN`` (RCP4_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP60CLM45CN`` (RCP6_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP60CN`` (RCP6_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP85CLM45CN`` (RCP8_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IGRCP85CN`` (RCP8_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_CISM1_SWAV) - -#. ``IRCP26CLM45CN`` (RCP2_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP26CN`` (RCP2_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP45CLM45CN`` (RCP4_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP45CN`` (RCP4_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP60CLM45CN`` (RCP6_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP60CN`` (RCP6_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP85CLM45CN`` (RCP8_DATM%QIA_CLM45%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``IRCP85CN`` (RCP8_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ISNCRFRC`` (2000_DATM%QIA_CLM40%SP-SNCR_SICE_SOCN_RTM_SGLC_SWAV) - -#. ``ITEST`` (2003_DATM%QIA_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV_TEST) - -#. ``ITESTCLM45`` (2003_DATM%QIA_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV_TEST) - -#. ``IUSUMB`` (2000_DATM%1PT_CLM40%SP_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%1x1_US-UMB) - -#. ``IalaskaCN`` (2000_DATM%QIA_CLM40%CN_SICE_SOCN_RTM_SGLC_SWAV_CLMUSRDAT%13x12pt_f19_alaskaUSA) - Compsets coupled to active atmosphere with data ocean ----------------------------------------------------- CAM compsets are compsets that start with "E" or "F" in the name. They are described more fully in the scripts documentation or the CAM documentation. "E" compsets have a slab ocean model while "F" compsets have a data ocean model. diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst index 774e4651e6..4f51314d48 100644 --- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -108,5 +108,5 @@ More details on each environment variable. The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here. -.. include:: ../../+|version|/tools/README.filecopies +.. include:: ../../clm5.0/tools/README.filecopies :literal: diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index 8f43d8ac0a..ae90a3609b 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -62,6 +62,6 @@ Creating a Complete Set of Files for Input to CLM The ``$CTSMROOT/tools/README`` goes through the complete process for creating input files needed to run CLM. We repeat that file here: -.. include:: ../../+|version|/tools/README +.. include:: ../../clm5.0/tools/README :literal: From 4372fd30e4fced8a665071085ccef50320d97a24 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 14 Jun 2018 15:11:08 -0600 Subject: [PATCH 167/255] Fix a warning about header --- ...Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst index c92892ba8d..50437d56b5 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst @@ -1,8 +1,8 @@ .. _spinning-up-clm45-bgc: -====================== +========================= Spinup of +|version|-BGC -====================== +========================= To get the +|version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). From 29fb4e4f03d7a10b8259f3d8a30f9d5bcb801a79 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 14 Jun 2018 16:14:27 -0600 Subject: [PATCH 168/255] Fix a couple issues --- doc/source/conf.py | 2 +- doc/source/users_guide/overview/introduction.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index a573b2a1d0..9a112db91b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -51,7 +51,7 @@ # General information about the project. project = u'clmdoc' -copyright = u'2017, Erik Kluzek, Bill Sacks, Ben Andre' +copyright = u'2018, Erik Kluzek, Bill Sacks, Ben Andre' author = u'Erik Kluzek, Bill Sacks, Ben Andre' # The version info for the project you're documenting, acts as replacement for diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index b65e622b45..706c4f5628 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -79,11 +79,11 @@ and then finally do it by hand. If you are using non supported machines you may also want to use the test scripts to make sure your machine is working correctly. -.. _what-is-new-with-+|version|: +.. _what-is-new-with-clm5_0: -========================= +============================ What is New with +|version| -========================= +============================ `What's new with +|version| science `_ The +|cesmrelease| `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. From e1063a221b6f8b9e0b8d12bf07126978ff863928 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 15 Jun 2018 10:45:35 -0600 Subject: [PATCH 169/255] Write out clm version in title, rather than use variable substitution --- ...inning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst index 50437d56b5..9065869bb4 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst @@ -1,8 +1,8 @@ .. _spinning-up-clm45-bgc: -========================= - Spinup of +|version|-BGC -========================= +===================== + Spinup of CLM5.0-BGC +===================== To get the +|version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). From 7a687480f6bcd5f91a3674c86f3d75681e758a6c Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 15 Jun 2018 12:01:37 -0600 Subject: [PATCH 170/255] Get version/release substitutions working correctly, and add subs for cesmrelease and cesmversion --- ...w-Files-to-the-build-namelist-Database.rst | 4 +- .../CLM-3.1-Managing-Your-Own-Data-files.rst | 4 +- .../CLM-3.2-Adding-Resolution-Names.rst | 2 +- ...3-Adding-or-Changing-Default-Filenames.rst | 8 +- doc/source/users_guide/conf.py | 2 - doc/source/users_guide/index.rst | 2 + .../users_guide/overview/getting-help.rst | 28 +++--- .../users_guide/overview/introduction.rst | 94 +++++++++---------- .../users_guide/overview/quickstart.rst | 14 +-- .../overview/scientific_validation.rst | 14 +-- .../running-PTCLM/introduction-to-ptclm.rst | 2 +- .../users_guide/running-PTCLM/using-ptclm.rst | 2 +- .../running-single-point-configurations.rst | 4 +- ...CLM5.0-biogeochemistry-(CLMBGC-spinup).rst | 12 +-- ...transient-historical-CO2-concentration.rst | 2 +- .../running-the-prognostic-crop-model.rst | 2 +- .../running-with-irrigation.rst | 4 +- .../customizing-the-clm-configuration.rst | 18 ++-- .../customizing-the-clm-namelist.rst | 6 +- doc/source/users_guide/testing/testing.rst | 2 +- .../trouble-shooting/trouble-shooting.rst | 2 +- ...g-input-for-surface-dataset-generation.rst | 8 +- .../creating-surface-datasets.rst | 6 +- .../what-are-the-clm-tools.rst | 8 +- 24 files changed, 125 insertions(+), 125 deletions(-) diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst index 8854d9e4d9..60137563db 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst @@ -14,11 +14,11 @@ If you have a LOT of files to keep track of it also might be easier than keeping If you just have a few quick experiments to try, for a short time period you might be best off using the other methods mentioned above. There are two parts to adding files to the build-namelist database. -The first part is adding new resolution names which is done in the ``$CTSMROOT/bld/namelist_files/namelist_definition_+|version|.xml`` file (and in the ``$CTSMROOT/bld/config_files/config_definition.xml`` file when adding supported single-point datasets). +The first part is adding new resolution names which is done in the ``$CTSMROOT/bld/namelist_files/namelist_definition_|version|.xml`` file (and in the ``$CTSMROOT/bld/config_files/config_definition.xml`` file when adding supported single-point datasets). You can then use the new resolution by using ``CLM_USRDAT_NAME``. If you also want to be able to give the resolution into **create_newcase** -- you'll need to add the grid to the ``scripts/ccsm_utils/Case.template/config_grid.xml`` file. -The second part is actually adding the new filenames which is done in the ``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|.xml`` file (``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|_tools.xml`` file for CLM tools). +The second part is actually adding the new filenames which is done in the ``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|.xml`` file (``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|_tools.xml`` file for CLM tools). If you aren't adding any new resolutions, and you are just changing the files for existing resolutions, you don't need to edit the namelist_definition file. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst index 558c877157..6d4a65657e 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst @@ -4,7 +4,7 @@ Managing Your Data Own Files ============================== -If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `+|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. +If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. @@ -39,7 +39,7 @@ You can also use **find** to list files that have a particular pattern in the na -If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `+|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. +If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst index e7896e1206..b9b767ca06 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst @@ -5,7 +5,7 @@ ========================= If you are adding files for new resolutions which aren't covered in the namelist_definition file -- you'll need to add them in. -The list of valid resolutions is in the id="res" entry in the ``$CTSMROOT/bld/namelist_files/namelist_definition_+|version|.xml`` file. +The list of valid resolutions is in the id="res" entry in the ``$CTSMROOT/bld/namelist_files/namelist_definition_|version|.xml`` file. You need to choose a name for your new resolution and simply add it to the comma delimited list of valid_values for the id="res" entry. The convention for global Gaussian grids is number_of_latitudes x number_of_longitudes. The convention for global finite volume grids is latitude_grid_size x longitude_grid_size where latitude and longitude is measured in degrees. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst index 6393a74ce3..4c8c9884de 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst @@ -4,7 +4,7 @@ Changing Default Filenames ============================ -To add or change the default filenames you edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|.xml`` and either change an existing filename or add a new one. +To add or change the default filenames you edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|.xml`` and either change an existing filename or add a new one. Most entries in the default namelist files, include different attributes that describe the different properties that describe the differences in the datasets. Attributes include the: resolution, year to simulation, range of years to simulate for transient datafiles, the land-mask, the representative concentration pathway (rcp) for future scenarios, and the type of biogeochemistry (bgc) model used. For example the fatmgrid for the 1.9x2.5 resolution is as follows: @@ -18,8 +18,8 @@ lnd/clm2/surfdata_map/surfdata_0.9x1.25_simyr1850_c130415.nc Other ``fsurdat`` files are distinguished from this one by their resolution (hgrid), simulation year (sim_year) and prognostic crop (crop) attributes. -To add or change the default filenames for CLM tools edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_+|version|_tools.xml`` and either change an existing filename or add a new one. -Editing this file is similar to the ``namelist_defaults_+|version|.xml`` talked about above. +To add or change the default filenames for CLM tools edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|_tools.xml`` and either change an existing filename or add a new one. +Editing this file is similar to the ``namelist_defaults_|version|.xml`` talked about above. ---------------------------- @@ -27,7 +27,7 @@ What are the required files? ---------------------------- Different types of simulations and different types of configurations for CLM require different lists of files. -The +|version|-BGC or Carbon Nitrogen (cn) Biogeochemistry model for example requires ``stream_fldfilename_ndep`` files, which are NOT required by CLMSP. +The |version|-BGC or Carbon Nitrogen (cn) Biogeochemistry model for example requires ``stream_fldfilename_ndep`` files, which are NOT required by CLMSP. Transient simulations also require transient datasets, and the names of these datasets are sometimes different from the static versions (sometimes both are required as in the dynamic PFT cases). diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index 0294e7cef8..c717685979 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -63,8 +63,6 @@ # The full version, including alpha/beta/rc tags. release = u'release-clm5.0.01' -cesmrelease = u'release-cesm2.0.00' - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index f3160a30ed..625bd84107 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -5,6 +5,8 @@ .. _users-guide: +.. |cesmrelease| replace:: CESM2.0.0 + ##################################### |version| User's Guide ##################################### diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index f78349e1ff..f5e5a0f059 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -3,15 +3,15 @@ ============== Getting Help ============== -In addition to this users-guide there are several other resources that are available to help you use +|version|. The first one is the +|cesmrelease| User's-Guide, which documents the entire process of creating cases with +|cesmrelease|. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in +|cesmrelease|. +In addition to this users-guide there are several other resources that are available to help you use |version|. The first one is the |cesmrelease| User's-Guide, which documents the entire process of creating cases with |cesmrelease|. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in |cesmrelease|. --------------------------- The CESM User's-Guide --------------------------- -+|release| -+|release| in +|cesmrelease| is always run from within the standard +|cesmrelease| build and run scripts. Therefore, the user of +|version| should familiarize themselves with the +|cesmrelease| scripts and understand how to work with them. User's-Guide documentation on the +|cesmrelease| scripts are available from the following web-page. The purpose of this +|version| in +|cesmrelease| User's Guide is to give the +|version| user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the +|cesmrelease| Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. +|release| +|release| in |cesmrelease| is always run from within the standard |cesmrelease| build and run scripts. Therefore, the user of |version| should familiarize themselves with the |cesmrelease| scripts and understand how to work with them. User's-Guide documentation on the |cesmrelease| scripts are available from the following web-page. The purpose of this |version| in |cesmrelease| User's Guide is to give the |version| user more complete details on how to work with CLM and the set of tools that support CLM, as well as to give examples that are unique to the use of CLM. However, the |cesmrelease| Scripts User's-Guide remains the primary source to get detailed information on how to build and run the CESM system. -`+|cesmrelease| Quickstart Guide `_ +`|cesmrelease| Quickstart Guide `_ ----------------------- The CESM Bulletin Board @@ -42,11 +42,11 @@ Also note that several of the XML database files can be viewed in a web browser - `$CTSMROOT/bld/namelist_files/history_fields_clm4_5.xml `_ -- definition of CLM4.5/CLM5.0 history fields. ---------------------------- -Reporting bugs in +|version| +Reporting bugs in |version| ---------------------------- -If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for +|version| in +|cesmrelease| is in the $CTSMROOT/doc/KnownBugs file, and the list of issues for +|cesmrelease| is at... -`http://www.cesm.ucar.edu/models/cesm1.2//tags/+|cesmrelease|/#PROBLEMS `_. +If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for |version| in |cesmrelease| is in the $CTSMROOT/doc/KnownBugs file, and the list of issues for |cesmrelease| is at... +`http://www.cesm.ucar.edu/models/cesm1.2//tags/|cesmrelease|/#PROBLEMS `_. --------------------------------------- Some Acronym's and Terms We'll be Using @@ -62,22 +62,22 @@ CLM Community Land Model (CLM). The prognostically active land model component of CESM. CLMBGC - Community Land Model (+|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is + Community Land Model (|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc cn -vsoilc_centbgc on -clm4me on"`` CLMCN - Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or +|version|) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or |version|) The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc cn" -append`` CLMSP - Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0 or +|version|) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0 or |version|) The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc none" -append`` CLMU - Community Land Model (CLM) Urban Model (either CLM4.0 or +|version|). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). + Community Land Model (CLM) Urban Model (either CLM4.0 or |version|). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). CRUNCEP The Climate Research Unit (CRU) analysis of the NCEP atmosphere reanalysis atmosphere forcing data. This can be used to drive CLM with atmosphere forcing from 1901 to 2010. We also DO expect to be able to update this dataset beyond 2010 as newer data becomes available. @@ -86,7 +86,7 @@ DATM Data Atmosphere Model (DATM) the prescribed data atmosphere component for CESM. Forcing data that we provide are either the Qian or CRUNCEP forcing datasets (see below). DV - Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either +|version|-BGC or CLMCN for either CLM4.0 or +|version|). The CLM_CONFIG_OPTS option for this is + Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either |version|-BGC or CLMCN for either CLM4.0 or |version|). The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc cndv" -append`` @@ -103,7 +103,7 @@ PFT Plant Function Type (PFT). A type of vegetation that CLM parameterizes. PTCLM - PoinT CLM (PTCLM) a python script that operates on top of CLM for +|version| to run single point simulations for CLM. + PoinT CLM (PTCLM) a python script that operates on top of CLM for |version| to run single point simulations for CLM. Qian The Qian et. al. analysis of the NCEP forcing data. This can be used to drive CLM with atmosphere forcing from 1948 to 2004. We do NOT expect to be able to update this dataset beyond 2004. @@ -112,6 +112,6 @@ SCRIP Spherical Coordinate Remapping and Interpolation Package (SCRIP). We use it's file format for specifying both grid coordinates as well as mapping between different grids. VIC - Variable Infiltration Capacity (VIC) model for hydrology. This is an option to +|version| in place of the standard +|version| hydrology. The CLM_CONFIG_OPTS option for this is + Variable Infiltration Capacity (VIC) model for hydrology. This is an option to |version| in place of the standard |version| hydrology. The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-vichydro on" -append`` diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 706c4f5628..a7e1f6c050 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -1,6 +1,6 @@ .. _introduction: -**User's Guide to version +|version| of the Community Land Model (CLM)** +**User's Guide to version |version| of the Community Land Model (CLM)** **Authors: Benjamin Andre, Erik Kluzek, William Sacks** @@ -20,33 +20,33 @@ P. O. Box 3000, Boulder, Colorado 80307-300 Introduction ============== -The Community Land Model (+|release| in +|cesmrelease|) is the latest in a +The Community Land Model (|release| in |cesmrelease|) is the latest in a series of global land models developed by the CESM Land Model Working Group (LMWG) and maintained at the National Center for Atmospheric Research (NCAR). This guide is intended to instruct both the novice and experienced user on running CLM. This guide pertains to the latest -version +|version| in +|cesmrelease| available for download from the public -release subversion repository as a part of +|cesmrelease|. Documentation +version |version| in |cesmrelease| available for download from the public +release subversion repository as a part of |cesmrelease|. Documentation may be different if you are using an older version, you should either use the documentation for that release version, update to the latest version, or use the documentation inside your own source tree. There is information in the ChangeLog file and in the `What is new with -+|version| in +|cesmrelease| since previous public releases? `_ +|version| in |cesmrelease| since previous public releases? `_ regarding the changes from previous versions of CESM. -.. note:: This release of +|version| in +|cesmrelease| includes BOTH CLM4.0 - physics used in previous releases as well as the updated +|version| +.. note:: This release of |version| in |cesmrelease| includes BOTH CLM4.0 + physics used in previous releases as well as the updated |version| physics. Both CLM as well as CLM support tools allow you to trigger between the two physics modes. Most often when we refer to CLM4.0 we - are referring to the CLM4.0 physics in +|version| in +|cesmrelease| rather + are referring to the CLM4.0 physics in |version| in |cesmrelease| rather than to a specific version of CLM4.0 (where we would give the exact - version). Likewise, when referring to +|version| we are referring to the - +|version| physics in +|version| in +|cesmrelease|. + version). Likewise, when referring to |version| we are referring to the + |version| physics in |version| in |cesmrelease|. The novice user should read `Chapter 1 `_ in detail before beginning work, while the expert user should read `What is new with -+|version| in +|cesmrelease| since previous public releases? `_ and -`Quickstart to using +|version| `_ chapters, and then use the +|version| in |cesmrelease| since previous public releases? `_ and +`Quickstart to using |version| `_ chapters, and then use the more detailed chapters as reference. Before novice users go onto more technical problems covered in `Chapter 2 `_, `Chapter 3 `_, `Chapter 4 `_, or `Chapter 5 `_ they @@ -56,12 +56,12 @@ to replicate some of the examples given there. All users should read the `How to Use This Document `_ and `Other resources to get help from `_ sections to understand the document conventions and the various ways of getting help on using -+|version|. Users should also read the `What is scientifically validated -and functional in +|version| in +|cesmrelease|? `_ section to see if +|version|. Users should also read the `What is scientifically validated +and functional in |version| in |cesmrelease|? `_ section to see if their planned use of the model is something that has been scientifically validated and well tested. Users that are NOT using NCAR machines or our list of well tested machines should also read the -What are the UNIX utilities required to use +|version|? section to make +What are the UNIX utilities required to use |version|? section to make sure they have all the required UNIX utilities on the system they want to do their work. @@ -82,11 +82,11 @@ machine is working correctly. .. _what-is-new-with-clm5_0: ============================ - What is New with +|version| + What is New with |version| ============================ -`What's new with +|version| science `_ -The +|cesmrelease| `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. +`What's new with |version| science `_ +The |cesmrelease| `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. More details are given in the `CLM ChangeLog file `_. Previous release pages give similar list of changes for previous versions of the model. @@ -99,49 +99,49 @@ The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates ========================== In this introduction we first give a simple guide to understand the document conventions in `How to Use This Document `_. -The next section `What is new with +|version| in +|cesmrelease| since previous public releases? `_ gives references to describe the differences between +|version| in +|cesmrelease| and previous CESM releases both from a scientific as well as a software engineering point of view. -For information on previous releases of +|version| before +|version| in +|cesmrelease| see the CESM1.1.1 documentation. -The next section `Quickstart to using +|version| `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use +|version|. -The next `What is scientifically validated and functional in +|version| in +|cesmrelease|? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. -`What are the UNIX utilities required to use +|version|? `_ lists the UNIX utilities required to use +|version| and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. -Next we have `Important Notes and Best Practices for Usage of +|version| `_ to detail some of the best practices for using +|version| for science. -The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and +|version|. - -`Chapter 1 `_ goes into detail on how to setup and run simulations with +|version| and especially how to customize cases. +The next section `What is new with |version| in |cesmrelease| since previous public releases? `_ gives references to describe the differences between |version| in |cesmrelease| and previous CESM releases both from a scientific as well as a software engineering point of view. +For information on previous releases of |version| before |version| in |cesmrelease| see the CESM1.1.1 documentation. +The next section `Quickstart to using |version| `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use |version|. +The next `What is scientifically validated and functional in |version| in |cesmrelease|? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. +`What are the UNIX utilities required to use |version|? `_ lists the UNIX utilities required to use |version| and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. +Next we have `Important Notes and Best Practices for Usage of |version| `_ to detail some of the best practices for using |version| for science. +The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and |version|. + +`Chapter 1 `_ goes into detail on how to setup and run simulations with |version| and especially how to customize cases. Details of cesm_setup modes and build-namelist options as well as namelist options are given in this chapter. -`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or +|version| physics for creating input datasets for use by CLM, for the expert user. +`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or |version| physics for creating input datasets for use by CLM, for the expert user. There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. Then each tool is described in detail along with different ways in which the tool might be used. A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. As a followup to the tools chapter, `Chapter 3 `_ tells how to add files to the XML database for build-namelist to use. -This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and +|version| physics). +This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and |version| physics). In `Chapter 4 `_, again for the expert user, we give details on how to do some particularly difficult special cases. -For example, we give the protocol for spinning up the +|version|-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). +For example, we give the protocol for spinning up the |version|-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. We also give instructions on running both the prognostic crop and irrigation models. Lastly we tell the user how to use the DATM model to send historical CO2 data to CLM. -`Chapter 5 `_ outlines how to do single-point or regional simulations using +|version|. -This is useful to either compare +|version| simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. +`Chapter 5 `_ outlines how to do single-point or regional simulations using |version|. +This is useful to either compare |version| simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. There are several different ways given on how to perform single-point simulations which range from simple PTS_MODE to more complex where you create all your own datasets, tying into `Chapter 2 `_ and also `Chapter 3 `_ to add the files into the build-namelist XML database. The PTCLM python script to run single-point simulations was added back in for this release (but it has bugs that don't allow it to work out of the box). CLM4 in CESM1.0.5 has a fully working versions of PTCLM. Need `Chapter 6 `_ blurb... -`Chapter 7 `_ gives some guidance on trouble-shooting problems when using +|version|. +`Chapter 7 `_ gives some guidance on trouble-shooting problems when using |version|. It doesn't cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems. `Chapter 8 `_ goes over the automated testing scripts for validating that the CLM is working correctly. -The test scripts run many different configurations and options with CLM4.0 physics as well and +|version| physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. -In general this is an activity important only for a developer of +|version|, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. +The test scripts run many different configurations and options with CLM4.0 physics as well and |version| physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. +In general this is an activity important only for a developer of |version|, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. -In the appendices we talk about some issues that are useful for advanced users and developers of +|version|. +In the appendices we talk about some issues that are useful for advanced users and developers of |version|. -Finally in `Appendix A `_ we give instructions on how to build the documentation associated with +|version| (i.e. how to build this document). +Finally in `Appendix A `_ we give instructions on how to build the documentation associated with |version| (i.e. how to build this document). This document is included in every CLM distribution and can be built so that you can view a local copy rather than having to go to the CESM website. This also could be useful for developers who need to update the documentation due to changes they have made. @@ -151,12 +151,12 @@ This also could be useful for developers who need to update the documentation du Best Practices ================ -- +|version| includes BOTH the old CLM4.0 physics AND the new +|version| physics and you can toggle between two. +- |version| includes BOTH the old CLM4.0 physics AND the new |version| physics and you can toggle between two. The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. - While the "standard" practice for +|version| is to run with BGC on, and CRUNCEP atmospheric forcing. - "BGC" is the new +|version| biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). + While the "standard" practice for |version| is to run with BGC on, and CRUNCEP atmospheric forcing. + "BGC" is the new |version| biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). -- When running with CLMCN (either CLM4.0 or +|version| physics) or +|version|-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the +|version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for +|version| or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). +- When running with CLMCN (either CLM4.0 or |version| physics) or |version|-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the |version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for |version| or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). Simulations without a proper spinup will effectively be starting from an unvegetated world. See `the Section called Setting Your Initial Conditions File in Chapter 1 `_ for information on how to provide initial conditions for your simulation. @@ -169,20 +169,20 @@ This also could be useful for developers who need to update the documentation du Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. -- Initial condition files are also provided for +|version| for several configurations and resolutions. - For +|version|-SP and +|version|-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. - The +|version|-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. - Also the +|version|-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg +|version|-BGC-DV and 2deg +|version|-BGC-Crop. +- Initial condition files are also provided for |version| for several configurations and resolutions. + For |version|-SP and |version|-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. + The |version|-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. + Also the |version|-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg |version|-BGC-DV and 2deg |version|-BGC-Crop. - Users can generate initial condition files at different resolutions by using the CLM tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. -- In +|version| for both +|version|-CN and +|version|-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). +- In |version| for both |version|-CN and |version|-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2010 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. -- Aerosol deposition is a required field to both CLM4.0 and +|version| physics, sent from the atmosphere model. +- Aerosol deposition is a required field to both CLM4.0 and |version| physics, sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index fa62be5422..935934f6c5 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -7,27 +7,27 @@ Running the CLM requires a suite of UNIX utilities and programs and you should make sure you have all of these available before trying to go forward with using it. If you are missing one of these you should contact the systems administrator for the machine you wish to run on and make sure they are installed. -List of utilities required for CESM in the "+|cesmrelease| Software/Operating System Prerequisites" section in `http://www.cesm.ucar.edu/models/cesm1.2//cesm/doc/usersguide/book1.html `_ +List of utilities required for CESM in the "|cesmrelease| Software/Operating System Prerequisites" section in `http://www.cesm.ucar.edu/models/cesm1.2//cesm/doc/usersguide/book1.html `_ - UNIX bash shell (for some of the CLM tools scripts) - NCL (for some of the offline tools for creating/modifying CLM input datasets see `Chapter 2 `_ for more information on NCL) - Python (optional, needed for PTCLM) - xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide) -Before working with +|version| read the QuickStart Guide in the `+|cesmrelease| Scripts User's Guide `_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM. +Before working with |version| read the QuickStart Guide in the `|cesmrelease| Scripts User's Guide `_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM. -For some of the details of setting up cases for +|version| read the README and text files available from the "$CTSMROOT/doc" directory (see the "CLM Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. +For some of the details of setting up cases for |version| read the README and text files available from the "$CTSMROOT/doc" directory (see the "CLM Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. 1. `README file `_ describing the directory structure. 2. `Quickstart.userdatasets `_ file describing how to use your own datasets in the model (also see `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_). -3. `$CTSMROOT/doc/KnownBugs `_ file describing known problems in +|version| (that we expect to eventually fix). +3. `$CTSMROOT/doc/KnownBugs `_ file describing known problems in |version| (that we expect to eventually fix). -4. `$CTSMROOT/doc/KnownLimitationss `_ file describing known limitations in +|version| and workarounds that we do NOT expect to fix. +4. `$CTSMROOT/doc/KnownLimitationss `_ file describing known limitations in |version| and workarounds that we do NOT expect to fix. -The IMPORTANT_NOTES file talks about important things for users to know about using the model scientifically. It content is given in the next chapter on `"What is scientifically validated and functional in +|version| in +|cesmrelease|?" `_. +The IMPORTANT_NOTES file talks about important things for users to know about using the model scientifically. It content is given in the next chapter on `"What is scientifically validated and functional in |version| in |cesmrelease|?" `_. -The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on `"What is new with +|version| in +|cesmrelease| since previous public releases?" `_. +The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on `"What is new with |version| in |cesmrelease| since previous public releases?" `_. Note other directories have README files that explain different components and tools used when running CLM and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with CLM see `Chapter 1 `_. diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index a238bee4a6..d96eb29bf4 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -4,16 +4,16 @@ Scientific Validation ======================== -In this section we go over what has been extensively tested and scientifically validated with +|version|, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of CLM, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. +In this section we go over what has been extensively tested and scientifically validated with |version|, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of CLM, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. -------------------------------------------------------------- Standard Configuration and Namelist Options that are Validated -------------------------------------------------------------- See -`http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for +|version|. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. +`http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for |version|. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. -In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for +|version| while others are for both CLM4.0 AND +|version| we explicitly say which they apply to. +In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for |version| while others are for both CLM4.0 AND |version| we explicitly say which they apply to. --------------------------------------------------------------------------------------------------------------- Configure Modes NOT scientifically validated, documented, supported or, in some cases, even advised to be used: @@ -21,13 +21,13 @@ Configure Modes NOT scientifically validated, documented, supported or, in some These are options that you would add to ``CLM_CONFIG_OPTS``. -1. exlaklayers on[+|version| only] This mode is NOT tested and may NOT be even functional. +1. exlaklayers on[|version| only] This mode is NOT tested and may NOT be even functional. -2. snicar_frc on[CLM4.0 AND +|version|] This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. +2. snicar_frc on[CLM4.0 AND |version|] This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. -3. vichydro on[+|version| only] This mode is tested and functional, but does NOT have long scientific validation simulations run with it so, should be considered experimental. +3. vichydro on[|version| only] This mode is tested and functional, but does NOT have long scientific validation simulations run with it so, should be considered experimental. -4. vsoilc_centbgc[+|version| only] This option is extensively tested for both "on" and "off". The "no-vert" option has limited testing performed on it, but isn't scientifically validated (and it currently has a bug -- see 1746 and 1672 in `$CTSMROOT/doc/KnownBugs `_). The "no-cent" and "no-nitrif" options are NOT tested and as such may NOT ben even functional. +4. vsoilc_centbgc[|version| only] This option is extensively tested for both "on" and "off". The "no-vert" option has limited testing performed on it, but isn't scientifically validated (and it currently has a bug -- see 1746 and 1672 in `$CTSMROOT/doc/KnownBugs `_). The "no-cent" and "no-nitrif" options are NOT tested and as such may NOT ben even functional. ---------------------------------------------- Namelist options that should NOT be exercised: diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst index 30068b600c..bca036a8e9 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -122,7 +122,7 @@ Example 6-1. Example of running PTCLM1 for US-UMB on cheyenne > ./link_dirtree $CSMDATA $MYCSMDATA # Next build all of the clm tools you will need - > cd ../$CTSMROOT/tools/+|version|/mksurfdata_map + > cd ../$CTSMROOT/tools/|version|/mksurfdata_map > gmake > gmake clean > cd ../../../../../../tools/mapping/gen_domain_files/src diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst index 73cf45ff88..fbdd258bbf 100644 --- a/doc/source/users_guide/running-PTCLM/using-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/using-ptclm.rst @@ -48,7 +48,7 @@ Steps in running PTCLM Next you need to make sure all the CLM FORTRAN tools are built. :: - > cd $CTSMROOT/tools/+|version|/mksurfdata_map + > cd $CTSMROOT/tools/|version|/mksurfdata_map > gmake > gmake clean > cd ../../../../../../tools/mapping/gen_domain_files/src diff --git a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst index accc5381a7..e5735a1453 100644 --- a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst @@ -183,7 +183,7 @@ Example: Creating a surface dataset for a single point # Save the location where the domain file was created > setenv GENDOM_PATH `pwd` # Finally create the surface dataset - > cd ../../../../lnd/clm/tools/+|version|/mksurfdata_map/src + > cd ../../../../lnd/clm/tools/|version|/mksurfdata_map/src > gmake > cd .. > ./mksurfdata.pl -r usrspec -usr_gname $GRIDNAME -usr_gdate $CDATE @@ -202,7 +202,7 @@ Example: Setting up a case from the single-point surface dataset just created > ./link_dirtree $CSMDATA $MYCSMDATA # Copy the file you created above to your new $MYCSMDATA location following the CLMUSRDAT # naming convention (leave off the creation date) - > cp $CESMROOT/$CTSMROOT/tools/+|version|/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ + > cp $CESMROOT/$CTSMROOT/tools/|version|/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ $MYCSMDATA/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr1850.nc > cd $CESMROOT/scripts > ./create_newcase -case my_usernldatasets_test -res CLM_USRDAT -compset I1850Clm50BgcCropCru \ diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst index 9065869bb4..5876c2bca2 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst @@ -4,13 +4,13 @@ Spinup of CLM5.0-BGC ===================== -To get the +|version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. +To get the |version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). **1. 45_AD_SPINUP** For the first step of running 1000+ years in "-bgc_spinup on" mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: -Example:: AD_SPINUP Simulation for +|version|-BGC +Example:: AD_SPINUP Simulation for |version|-BGC -------------------------------------------------------- :: @@ -33,14 +33,14 @@ Example:: AD_SPINUP Simulation for +|version|-BGC # Now run normally > ./BGC_spinup.submit -.. note:: This same procedure works for +|version|-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. +.. note:: This same procedure works for |version|-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. Afterwards save the last restart file from this simulation to use in the next step. -**2. Final spinup for +|version|-BGC** +**2. Final spinup for |version|-BGC** Next save the last restart file from this step and use it as the "finidat" file to use for one more spinup for at least 200+ years in normal mode. So do the following: -Example: Final CLMBGC Spinup Simulation for +|version|-BGC +Example: Final CLMBGC Spinup Simulation for |version|-BGC ------------------------------------------------------------------ :: @@ -69,7 +69,7 @@ Example: Final CLMBGC Spinup Simulation for +|version|-BGC To assess if the model is spunup plot trends of CLMBGC variables of interest. If you see a trend, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. -.. note:: This same final spinup procedure works for +|version|-CN as well, you can typically shorten the spinup time from 200 years to 50 though. +.. note:: This same final spinup procedure works for |version|-CN as well, you can typically shorten the spinup time from 200 years to 50 though. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst index f81634d456..d00509e301 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst @@ -128,7 +128,7 @@ You just copy this into your case directory. But, also compare it to the version Once, you've done that you can build and run your case normally. -.. warning:: This procedure assumes you are using a ``I20TRCRUCLM45BGC`` compset out of the box, with ``DATM_PRESAERO`` equal to trans_1850-2000. So it assumes standard +|version| CRUNCEP atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here your ``user_nl_datm`` file will need to be adjusted to work with it. +.. warning:: This procedure assumes you are using a ``I20TRCRUCLM45BGC`` compset out of the box, with ``DATM_PRESAERO`` equal to trans_1850-2000. So it assumes standard |version| CRUNCEP atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here your ``user_nl_datm`` file will need to be adjusted to work with it. .. note:: The intent of the ``user_nl_datm`` is to add an extra streams file for CO2 to the end of the streams variable, and other arrays associated with streams (adding mapalgo as a new array with bilinear for everything, but the CO2 file which should be "nn" for nearest neighbor). Other variables should be the same as the other stream values. diff --git a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst index 3ed3b3f0f1..944a4a93f0 100644 --- a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst +++ b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst @@ -4,7 +4,7 @@ Running the prognostic crop model =================================== -The prognostic crop model is setup to work with +|version|-BGC or CLM4.0-CN (with or without DV) for present day conditions and we have surface and initial condition datasets at f19 resolution. +The prognostic crop model is setup to work with |version|-BGC or CLM4.0-CN (with or without DV) for present day conditions and we have surface and initial condition datasets at f19 resolution. In order to use the initial condition file, we need to set the ``RUN_TYPE`` to startup rather than ``hybrid`` since the compset for f19 sets up to use an initial condition file without crop active. To activate the crop model you can choose a compset that has "CROP" in the name such as "ICRUCLM45BGCCROP" or simply add "-crop on" to ``CLM_CONFIG_OPTS``. diff --git a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst index feef7d0bd4..767836c180 100644 --- a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst +++ b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst @@ -4,8 +4,8 @@ Running with irrigation =================================== -In +|version| irrigation can ONLY be used WITH crop. -To turn on irrigation in +|version| we simply add "-irrig on" to ``CLM_BLDNML_OPTS``. +In |version| irrigation can ONLY be used WITH crop. +To turn on irrigation in |version| we simply add "-irrig on" to ``CLM_BLDNML_OPTS``. Just as in the crop example we also change ``RUN_TYPE`` to ``startup`` so that we don't use an initial condition file that is incompatible with irrigation. Example: Irrigation Simulation diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index 4e211894d6..23845b1da7 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -4,7 +4,7 @@ Customizing CLM's Configuration ******************************* -The "Creating a Case" section of the `+|cesmrelease| Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. +The "Creating a Case" section of the `|cesmrelease| Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called there are two steps that take place: @@ -14,7 +14,7 @@ For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called When customizing your case at the *8cesm_setup** step you are able to modify the process by effecting either one or both of these steps. The CLM "**configure**" and "**build-namelist**" scripts are both available in the "$CTSMROOT/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. -There are five different types of customization for the configuration that we will discuss: +|version| in +|cesmrelease| build-time options, +|version| in +|cesmrelease| run-time options, User Namelist, other noteworthy +|cesmrelease| configuration items, the CLM **configure** script options, and the CLM **build-namelist** script options. +There are five different types of customization for the configuration that we will discuss: |version| in |cesmrelease| build-time options, |version| in |cesmrelease| run-time options, User Namelist, other noteworthy |cesmrelease| configuration items, the CLM **configure** script options, and the CLM **build-namelist** script options. Information on all of the script, configuration, build and run items is found under ``scripts/ccsm_utils/Case.template`` in the `config_definition.xml `_ file. @@ -179,7 +179,7 @@ CLM_BLDNML_OPTS -inputdata "filepath" Writes out a list containing pathnames for required input datasets in file specified. - -irrig "value" If .true. turn irrigation on with namelist logical irrigate (for +|version| physics) + -irrig "value" If .true. turn irrigation on with namelist logical irrigate (for |version| physics) (requires crop to be on in the clm configuration) Seek surface datasets with irrigation turned on. (for CLM4.0 physics) Default: .false. @@ -284,7 +284,7 @@ Hence only the following different options can be set: #. -verbose -"-bgc_spinup" is an option only available for +|version| for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See `the Section called Spinning up the +|version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for an example using this option. +"-bgc_spinup" is an option only available for |version| for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See `the Section called Spinning up the |version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for an example using this option. "-chk_res" ensures that the resolution chosen is supported by CLM. If the resolution is NOT supported it will cause the CLM **build-namelist** to abort when run. So when either **preview_namelist**, **$CASE.build** or **$CASE.run** is executed it will abort early. Since, the CESM scripts only support certain resolutions anyway, in general this option is NOT needed in the context of running CESM cases. @@ -530,7 +530,7 @@ If you are running an B, E, or F case that doesn't use the DATM obviously the DA CPLHIST3HrWx ``CLMCRUNCEP`` - The standard mode for +|version| of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010. + The standard mode for |version| of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010. See `the Section called CLMCRUNCEP mode and it's DATM settings `_ for more information on the DATM settings for ``CLMCRUNCEP`` mode. ``CLM_QIAN`` @@ -632,7 +632,7 @@ The output to the above command is as follows: (default: CLM build directory). -clm4me Turn Methane model: [on | off] Requires bgc=cn/cndv (Carbon Nitrogen model) - (ONLY valid for +|version|!) + (ONLY valid for |version|!) -clm_root Root directory of clm source code (default: directory above location of this script) -cppdefs A string of user specified CPP defines. Appended to @@ -647,12 +647,12 @@ The output to the above command is as follows: Parameters relating to the build which are system dependent will be ignored. -exlaklayers Turn on extra lake layers (25 layers instead of 10) [on | off] - (ONLY valid for +|version|!) + (ONLY valid for |version|!) -help [or -h] Print usage to STDOUT. -nofire Turn off wildfires for BGC setting of CN (default includes fire for CN) -noio Turn history output completely off (typically for testing). - -phys Value of clm4_0 or +|version| (default is clm4_0) + -phys Value of clm4_0 or |version| (default is clm4_0) -silent [or -s] Turns on silent mode - only fatal messages issued. -sitespf_pt Setup for the given site specific single-point resolution. -snicar_frc Turn on SNICAR radiative forcing calculation. [on | off] @@ -676,7 +676,7 @@ The output to the above command is as follows: eliminate inconsistent duplicate soil hydraulic parameters used in soil biogeochem. (requires either CN or CNDV) - (ONLY valid for +|version|!) + (ONLY valid for |version|!) [on,off or colon delimited list of no options] (default off) no-vert Turn vertical soil Carbon profile off no-cent Turn CENTURY off diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst index 2300c8ad60..256397329e 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst @@ -16,16 +16,16 @@ Definition of Namelist items and their default values Here we point to you where you can find the definition of each namelist item and separately the default values for them. The default values may change depending on the resolution, land-mask, simulation-year and other attributes. Both of these files are viewable in your web browser, and then expand each in turn. -1. `Definition of Namelists Relevant for +|version| `_ +1. `Definition of Namelists Relevant for |version| `_ 2. `Default values of each CLM4.0 Namelist Item `_ -3. `Default values of each +|version| Namelist Item `_ +3. `Default values of each |version| Namelist Item `_ List of fields that can be added to your output history files by namelist ------------------------------------------------------------------------- -One set of the namelist items allows you to add fields to the output history files: ``hist_fincl1``, ``hist_fincl2``, ``hist_fincl3``, ``hist_fincl4``, ``hist_fincl5``, and ``hist_fincl6``. The following links for `CLM4.0 History Fields `_ and `+|version| History Fields `_ documents all of the history fields available and gives the long-name and units for each. The table below lists all the +|version| history fields. +One set of the namelist items allows you to add fields to the output history files: ``hist_fincl1``, ``hist_fincl2``, ``hist_fincl3``, ``hist_fincl4``, ``hist_fincl5``, and ``hist_fincl6``. The following links for `CLM4.0 History Fields `_ and `|version| History Fields `_ documents all of the history fields available and gives the long-name and units for each. The table below lists all the |version| history fields. Definition of CLM history variables ----------------------------------- diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index d41124f8ba..55f5ad2ed7 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -44,7 +44,7 @@ We already have a standard list of tests for clm (the "aux_clm" list of tests). > ./cs.status.$id # The above will give a PASS or FAIL message for each test. -For more information on doing testing with the CESM scripts see the `+|cesmrelease| User's Guide `_ on testing. +For more information on doing testing with the CESM scripts see the `|cesmrelease| User's Guide `_ on testing. Testing PTCLM ============= diff --git a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst index 625865b7c1..3a30659752 100644 --- a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst +++ b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst @@ -18,7 +18,7 @@ Setup Problems The first type of problem happens when you invoke the **case.setup** command. This indicates there is something wrong with your input datasets, or the details of what you are trying to setup the model to do. -There's also a trouble-shooting chapter in the `+|cesmrelease| Scripts User's Guide `_. +There's also a trouble-shooting chapter in the `|cesmrelease| Scripts User's Guide `_. Many of the problems with configuration can be resolved with the guidelines given there. Here we will restrict ourselves to problems from the input files. diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index 006c6b679b..848b96131f 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -49,7 +49,7 @@ Hence, there doesn't need to be a different mapping file for EACH raw dataset -- See `Figure 2-3 `_ for a visual representation of how this works. The bash script figures out which mapping files it needs to create and then runs **ESMF_RegridWeightGen** for each one. You can then either enter the datasets into the XML database (see `Chapter 3 `_ or leave the files in place, and use the "-res usrspec -usr_gname -usr_gdate" options to **mksurfdata_map** (see `the Section called Running mksurfdata.pl `_ below). -Use the "-phys" option to specify if you are creating mapping files for clm4_0 or +|version| (the list of raw datafiles is somewhat different between the two). +Use the "-phys" option to specify if you are creating mapping files for clm4_0 or |version| (the list of raw datafiles is somewhat different between the two). mkmapdata.sh has a help option with the following :: @@ -74,8 +74,8 @@ mkmapdata.sh has a help option with the following Model output grid type supported values are [regional,global], (default is global) [-p|--phys ] - Whether to generate mapping files for clm4_0 or +|version| - supported values are [clm4_0,+|version|], (default is +|version|) + Whether to generate mapping files for clm4_0 or |version| + supported values are [clm4_0,|version|], (default is |version|) [-b|--batch] Toggles batch mode usage. If you want to run in batch mode @@ -107,7 +107,7 @@ mkmapdata.sh has a help option with the following ********************** -.. warning:: Make sure you specify with the "-phys" option if you are creating files for CLM4.0! The default is +|version|. +.. warning:: Make sure you specify with the "-phys" option if you are creating files for CLM4.0! The default is |version|. Figure 2-3. Details of running mkmapdata.sh ------------------------------------------- diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index ae90a3609b..4675720af1 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -37,7 +37,7 @@ Creating a Complete Set of Files for Input to CLM 4. Create surface datasets - Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or +|version| for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this. + Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or |version| for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this. 5. Create some sort of initial condition dataset @@ -49,11 +49,11 @@ Creating a Complete Set of Files for Input to CLM b. Use interpinic to interpolate existing initial condition datasets - The next option is to interpolate from spunup datasets at a different resolution, using interpinic. There is a version for either clm4_0 or +|version| for this program. See the Section called Using interpinic to interpolate initial conditions to different resolutions for more information on this. + The next option is to interpolate from spunup datasets at a different resolution, using interpinic. There is a version for either clm4_0 or |version| for this program. See the Section called Using interpinic to interpolate initial conditions to different resolutions for more information on this. c. Start up from arbitrary initial conditions - The last alternative is to run from arbitrary initial conditions without using any spun-up datasets. This is inappropriate when using +|version|-BGC or CLMCN (bgc=cn or cndv) as it takes a long time to spinup Carbon pools. + The last alternative is to run from arbitrary initial conditions without using any spun-up datasets. This is inappropriate when using |version|-BGC or CLMCN (bgc=cn or cndv) as it takes a long time to spinup Carbon pools. .. warning:: This is NOT recommended as many fields in CLM take a long time to equilibrate. diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst index 4bb40f21c6..59d7776016 100644 --- a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst @@ -10,8 +10,8 @@ Most of the tools are FORTRAN stand-alone programs in their own directory, but t Some of the NCL scripts are very specialized and not meant for general use, and we won't document them here. They still contain documentation in the script itself and the README file in the tools directory. -The tools are divided into three directories for three categories: clm4_0, +|version|, and shared. -The first two are of course for tools that are designed to work with either the CLM4.0 or +|version| versions of the model. +The tools are divided into three directories for three categories: clm4_0, |version|, and shared. +The first two are of course for tools that are designed to work with either the CLM4.0 or |version| versions of the model. The last one are shared utilities that can be used by either, or have a "-phys" option so you can specify which version you want to use. The list of generally important scripts and programs are as follows. @@ -24,9 +24,9 @@ The list of generally important scripts and programs are as follows. #. *./gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. -#. *mksurfdata_map* to create surface datasets from grid datasets (clm4_0 and +|version| versions). +#. *mksurfdata_map* to create surface datasets from grid datasets (clm4_0 and |version| versions). -#. *./mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or +|version|. +#. *./mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or |version|. In the sections to come we will go into detailed description of how to use each of these tools in turn. First, however we will discuss the common environment variables and options that are used by all of the FORTRAN tools. From 9dfe4bd350ca1cf3d0f957d28642ef4e001937e1 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 15 Jun 2018 12:21:59 -0600 Subject: [PATCH 171/255] Add substitution file to get substitutions properly working for UG, checkin of new UG html --- ...esolutions-or-New-Files-to-the-build-namelist-Database.rst | 2 ++ .../CLM-3.1-Managing-Your-Own-Data-files.rst | 2 ++ .../CLM-3.2-Adding-Resolution-Names.rst | 2 ++ .../CLM-3.3-Adding-or-Changing-Default-Filenames.rst | 2 ++ doc/source/users_guide/adding-new-resolutions/index.rst | 2 ++ doc/source/users_guide/index.rst | 2 +- doc/source/users_guide/overview/getting-help.rst | 2 ++ doc/source/users_guide/overview/index.rst | 2 ++ doc/source/users_guide/overview/introduction.rst | 2 ++ doc/source/users_guide/overview/quickstart.rst | 2 ++ doc/source/users_guide/overview/scientific_validation.rst | 2 ++ .../users_guide/running-PTCLM/adding-ptclm-site-data.rst | 2 ++ doc/source/users_guide/running-PTCLM/index.rst | 2 ++ .../users_guide/running-PTCLM/introduction-to-ptclm.rst | 2 ++ doc/source/users_guide/running-PTCLM/ptclm-examples.rst | 2 ++ doc/source/users_guide/running-PTCLM/using-ptclm.rst | 2 ++ doc/source/users_guide/running-single-points/index.rst | 2 ++ .../running-single-points/running-pts_mode-configurations.rst | 2 ++ .../running-single-point-configurations.rst | 2 ++ .../single-point-and-regional-grid-configurations.rst | 2 ++ ...inning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst | 2 ++ ...Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst | 2 ++ ...h-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst | 2 ++ ...-simulation-as-atmospheric-forcing-to-spinup-the-model.rst | 2 ++ ...-alone-CLM-with-transient-historical-CO2-concentration.rst | 2 ++ doc/source/users_guide/running-special-cases/index.rst | 2 ++ .../running-the-prognostic-crop-model.rst | 2 ++ .../running-special-cases/running-with-irrigation.rst | 2 ++ .../running-special-cases/what-is-a-special-case.rst | 2 ++ .../setting-up-and-running-a-case/choosing-a-compset.rst | 2 ++ .../customizing-the-clm-configuration.rst | 4 +++- .../customizing-the-clm-namelist.rst | 2 ++ .../customizing-the-datm-namelist.rst | 2 ++ .../users_guide/setting-up-and-running-a-case/index.rst | 2 ++ doc/source/users_guide/substitutions.rst | 2 ++ doc/source/users_guide/testing/index.rst | 2 ++ doc/source/users_guide/testing/testing.rst | 2 ++ doc/source/users_guide/trouble-shooting/index.rst | 2 ++ doc/source/users_guide/trouble-shooting/trouble-shooting.rst | 2 ++ .../users_guide/using-clm-tools/building-the-clm-tools.rst | 2 ++ doc/source/users_guide/using-clm-tools/cprnc.rst | 2 ++ .../users_guide/using-clm-tools/creating-domain-files.rst | 2 ++ .../creating-input-for-surface-dataset-generation.rst | 2 ++ .../users_guide/using-clm-tools/creating-surface-datasets.rst | 2 ++ .../using-clm-tools/datasts-for-observational-sites.rst | 2 ++ doc/source/users_guide/using-clm-tools/index.rst | 2 ++ .../using-clm-tools/observational-sites-datasets.rst | 2 ++ .../users_guide/using-clm-tools/what-are-the-clm-tools.rst | 2 ++ 48 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 doc/source/users_guide/substitutions.rst diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst index 60137563db..76d8a7aef1 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst @@ -1,5 +1,7 @@ .. _adding-resolutions: +.. include:: ../substitutions.rst + ======================== Adding New Resolutions ======================== diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst index 6d4a65657e..41ccdde35b 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst @@ -1,5 +1,7 @@ .. _managing-your-data-files: +.. include:: ../substitutions.rst + ============================== Managing Your Data Own Files ============================== diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst index b9b767ca06..aa8265e8a9 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst @@ -1,5 +1,7 @@ .. _adding-resolution-names: +.. include:: ../substitutions.rst + ========================= Adding Resolution Names ========================= diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst index 4c8c9884de..52344bd5a0 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst @@ -1,5 +1,7 @@ .. _changing-default-filenames: +.. include:: ../substitutions.rst + ============================ Changing Default Filenames ============================ diff --git a/doc/source/users_guide/adding-new-resolutions/index.rst b/doc/source/users_guide/adding-new-resolutions/index.rst index c01aa36ca0..fded236989 100644 --- a/doc/source/users_guide/adding-new-resolutions/index.rst +++ b/doc/source/users_guide/adding-new-resolutions/index.rst @@ -5,6 +5,8 @@ .. _adding-new-resolutions-section: +.. include:: ../substitutions.rst + ##################################### Adding New Resolutions ##################################### diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index 625bd84107..31d00bcb38 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -5,7 +5,7 @@ .. _users-guide: -.. |cesmrelease| replace:: CESM2.0.0 +.. include:: substitutions.rst ##################################### |version| User's Guide diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index f5e5a0f059..aafeb057f5 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -1,5 +1,7 @@ .. _getting-help: +.. include:: ../substitutions.rst + ============== Getting Help ============== diff --git a/doc/source/users_guide/overview/index.rst b/doc/source/users_guide/overview/index.rst index 1f31037460..b03eae4034 100644 --- a/doc/source/users_guide/overview/index.rst +++ b/doc/source/users_guide/overview/index.rst @@ -5,6 +5,8 @@ .. _overview_section: +.. include:: ../substitutions.rst + ##################################### Overview ##################################### diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index a7e1f6c050..7dd868b3f7 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -1,5 +1,7 @@ .. _introduction: +.. include:: ../substitutions.rst + **User's Guide to version |version| of the Community Land Model (CLM)** **Authors: Benjamin Andre, Erik Kluzek, William Sacks** diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index 935934f6c5..3c9964ee38 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -1,5 +1,7 @@ .. _quickstart: +.. include:: ../substitutions.rst + ============ Quickstart ============ diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index d96eb29bf4..b7e80c4b37 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -1,5 +1,7 @@ .. _scientific-validiation: +.. include:: ../substitutions.rst + ======================== Scientific Validation ======================== diff --git a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst index 1e7a5437eb..425e6d9c25 100644 --- a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst +++ b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst @@ -1,5 +1,7 @@ .. _adding-ptclm-site-data: +.. include:: ../substitutions.rst + ====================== Adding PTCLM Site Data ====================== diff --git a/doc/source/users_guide/running-PTCLM/index.rst b/doc/source/users_guide/running-PTCLM/index.rst index d82b7f9624..26e18d3a73 100644 --- a/doc/source/users_guide/running-PTCLM/index.rst +++ b/doc/source/users_guide/running-PTCLM/index.rst @@ -5,6 +5,8 @@ .. _running-PTCLM: +.. include:: ../substitutions.rst + ##################################### Running PTCLM ##################################### diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst index bca036a8e9..0c49f6ad78 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -1,5 +1,7 @@ .. _introduction-to-ptclm.rst: +.. include:: ../substitutions.rst + .. _what-is-ptclm: =============== diff --git a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst index 172f041420..d3d85da0b1 100644 --- a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst +++ b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst @@ -1,5 +1,7 @@ .. _ptclm-examples: +.. include:: ../substitutions.rst + ========================= Examples of using PTCLM ========================= diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst index fbdd258bbf..2055cc81a1 100644 --- a/doc/source/users_guide/running-PTCLM/using-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/using-ptclm.rst @@ -1,5 +1,7 @@ .. _using-ptclm.rst: +.. include:: ../substitutions.rst + ************************** Using PTCLM ************************** diff --git a/doc/source/users_guide/running-single-points/index.rst b/doc/source/users_guide/running-single-points/index.rst index 2c4ea71bdb..e1d955ac0a 100644 --- a/doc/source/users_guide/running-single-points/index.rst +++ b/doc/source/users_guide/running-single-points/index.rst @@ -5,6 +5,8 @@ .. _running-single-points: +.. include:: ../substitutions.rst + ##################################### Running Single Point Regional Cases ##################################### diff --git a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst index ca794ac326..c7a1ed0def 100644 --- a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst @@ -1,5 +1,7 @@ .. _pts_mode: +.. include:: ../substitutions.rst + **************************************************** Running a single point using global data - PTS_MODE **************************************************** diff --git a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst index e5735a1453..6a2dc4e44d 100644 --- a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst @@ -1,5 +1,7 @@ .. _running-single-point-datasets: +.. include:: ../substitutions.rst + ****************************************** Running Single Point Configurations ****************************************** diff --git a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst index a1514768ee..41f55e38f1 100644 --- a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst +++ b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst @@ -1,5 +1,7 @@ .. _single-point-configurations: +.. include:: ../substitutions.rst + ***************************************** Single and Regional Grid Configurations ***************************************** diff --git a/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst index 7c8bd313c5..a017c42ae0 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst @@ -1,5 +1,7 @@ .. _spinning-up-sp: +.. include:: ../substitutions.rst + =========================================== Spinning up the Satellite Phenology Model =========================================== diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst index 5876c2bca2..99fa3fdd47 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst @@ -1,5 +1,7 @@ .. _spinning-up-clm45-bgc: +.. include:: ../substitutions.rst + ===================== Spinup of CLM5.0-BGC ===================== diff --git a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst index 36f2266493..deb5fa1238 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst @@ -1,5 +1,7 @@ .. _running-with-moar-data: +.. include:: ../substitutions.rst + ======================== Running with MOAR data ======================== diff --git a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst index 5cad7c1c5e..0999f7b366 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst @@ -1,5 +1,7 @@ .. _running-with-previous-simulation-forcing: +.. include:: ../substitutions.rst + ============================================================= Running with atmospheric forcing from a previous simulation ============================================================= diff --git a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst index d00509e301..b7d063a2a2 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst @@ -1,5 +1,7 @@ .. _running-with-historical-co2-forcing: +.. include:: ../substitutions.rst + ===================================== Running with historical CO2 forcing ===================================== diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst index 693c83d550..18ef7a96b0 100644 --- a/doc/source/users_guide/running-special-cases/index.rst +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -5,6 +5,8 @@ .. _running-special-cases-section: +.. include:: ../substitutions.rst + ##################################### Running Special Cases ##################################### diff --git a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst index 944a4a93f0..308c749adc 100644 --- a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst +++ b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst @@ -1,5 +1,7 @@ .. running-prognostic-crop-model: +.. include:: ../substitutions.rst + =================================== Running the prognostic crop model =================================== diff --git a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst index 767836c180..3a7b0e3ccf 100644 --- a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst +++ b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst @@ -1,5 +1,7 @@ .. running-with-irrigation: +.. include:: ../substitutions.rst + =================================== Running with irrigation =================================== diff --git a/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst b/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst index 32daabafc6..5a42858818 100644 --- a/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst +++ b/doc/source/users_guide/running-special-cases/what-is-a-special-case.rst @@ -1,5 +1,7 @@ .. _what is a special case: +.. include:: ../substitutions.rst + ========================= What is a special case? ========================= diff --git a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst index 38bfcd7da1..df702e0185 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst @@ -1,5 +1,7 @@ .. _choosing-a-compset: +.. include:: ../substitutions.rst + ==================== Choosing a compset ==================== diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index 23845b1da7..38f61c2c4d 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -1,10 +1,12 @@ .. _configuring-clm: +.. include:: ../substitutions.rst + ******************************* Customizing CLM's Configuration ******************************* -The "Creating a Case" section of the `|cesmrelease| Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. +The "Creating a Case" section of the |cesmrelease| `Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called there are two steps that take place: diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst index 256397329e..41eec17598 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst @@ -1,5 +1,7 @@ .. _customizing-a-case: +.. include:: ../substitutions.rst + ============================ Customizing CLM's namelist ============================ diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst index 8cf0916717..4140dad87a 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst @@ -1,5 +1,7 @@ .. customizing-the-datm-namelist: +.. include:: ../substitutions.rst + =============================== Customizing the DATM namelist =============================== diff --git a/doc/source/users_guide/setting-up-and-running-a-case/index.rst b/doc/source/users_guide/setting-up-and-running-a-case/index.rst index a9c1cb7d13..3fb9a41391 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/index.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/index.rst @@ -5,6 +5,8 @@ .. _customizing_section: +.. include:: ../substitutions.rst + ##################################### Setting Up and Running a Case ##################################### diff --git a/doc/source/users_guide/substitutions.rst b/doc/source/users_guide/substitutions.rst new file mode 100644 index 0000000000..821ebb071e --- /dev/null +++ b/doc/source/users_guide/substitutions.rst @@ -0,0 +1,2 @@ +.. |cesmrelease| replace:: CESM2.0.0 + diff --git a/doc/source/users_guide/testing/index.rst b/doc/source/users_guide/testing/index.rst index 09575a1442..b9e99506e1 100644 --- a/doc/source/users_guide/testing/index.rst +++ b/doc/source/users_guide/testing/index.rst @@ -5,6 +5,8 @@ .. _testing_section: +.. include:: ../substitutions.rst + ##################################### Testing ##################################### diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index 55f5ad2ed7..0594bc9157 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -1,5 +1,7 @@ .. _testing: +.. include:: ../substitutions.rst + ******* Testing ******* diff --git a/doc/source/users_guide/trouble-shooting/index.rst b/doc/source/users_guide/trouble-shooting/index.rst index f4c6d813fc..64b0cecee3 100644 --- a/doc/source/users_guide/trouble-shooting/index.rst +++ b/doc/source/users_guide/trouble-shooting/index.rst @@ -5,6 +5,8 @@ .. _troubleshooting: +.. include:: ../substitutions.rst + ##################################### Troubleshooting ##################################### diff --git a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst index 3a30659752..c7e38cf645 100644 --- a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst +++ b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst @@ -1,5 +1,7 @@ .. _trouble-shooting: +.. include:: ../substitutions.rst + ********************* Trouble Shooting ********************* diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst index 4f51314d48..1dd1129b6c 100644 --- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -2,6 +2,8 @@ Building the CLM tools ======================== +.. include:: ../substitutions.rst + The FORTRAN tools all have similar makefiles, and similar options for building. All of the Makefiles use GNU Make extensions and thus require that you use GNU make to use them. They also auto detect the type of platform you are on, using "uname -s" and set the compiler, compiler flags and such accordingly. diff --git a/doc/source/users_guide/using-clm-tools/cprnc.rst b/doc/source/users_guide/using-clm-tools/cprnc.rst index 53169513f0..de90f7a88e 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.rst +++ b/doc/source/users_guide/using-clm-tools/cprnc.rst @@ -1,5 +1,7 @@ .. comparing-history-files: +.. include:: ../substitutions.rst + ========================= Comparing History Files ========================= diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst index 6d4ec7bc12..d72427d3d5 100644 --- a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -1,5 +1,7 @@ .. _creating-domain-files: +.. include:: ../substitutions.rst + ***************************** Creating CLM domain files ***************************** diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index 848b96131f..dcfcbbbdff 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -1,5 +1,7 @@ .. _creating-maps-for-mksurfdata: +.. include:: ../substitutions.rst + ********************************************* Creating input for surface dataset generation ********************************************* diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index 4675720af1..f2cb8eed4d 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -1,5 +1,7 @@ .. _creating-surface-datasets: +.. include:: ../substitutions.rst + =========================== Creating Surface Datasets =========================== diff --git a/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst b/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst index d1824d432e..7fb915a6ed 100644 --- a/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst +++ b/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst @@ -1,3 +1,5 @@ +.. include:: ../substitutions.rst + ================================== Datasets for Observational Sites ================================== diff --git a/doc/source/users_guide/using-clm-tools/index.rst b/doc/source/users_guide/using-clm-tools/index.rst index 030cda7495..58435f92aa 100644 --- a/doc/source/users_guide/using-clm-tools/index.rst +++ b/doc/source/users_guide/using-clm-tools/index.rst @@ -5,6 +5,8 @@ .. _using-clm-tools-section: +.. include:: ../substitutions.rst + ##################################### Using CLM tools ##################################### diff --git a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst index b5e47e861f..b5cc2efad9 100644 --- a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst @@ -1,5 +1,7 @@ .. _observational-sites-datasets: +.. include:: ../substitutions.rst + ******************************* Observational Sites Datasets ******************************* diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst index 59d7776016..3c67965e73 100644 --- a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst @@ -1,5 +1,7 @@ .. _what-are-the-clm-tools: +.. include:: ../substitutions.rst + ======================== What are the CLM tools ======================== From 565a93f7f55744b41e685f40279fbb4ae9e17343 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 15 Jun 2018 15:32:10 -0600 Subject: [PATCH 172/255] More updates, add today's date under UG index --- doc/source/users_guide/conf.py | 3 + doc/source/users_guide/index.rst | 2 + .../users_guide/overview/introduction.rst | 55 ++++++++++------ .../users_guide/overview/quickstart.rst | 14 ++--- .../overview/scientific_validation.rst | 62 ------------------- doc/source/users_guide/substitutions.rst | 3 + 6 files changed, 48 insertions(+), 91 deletions(-) diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index c717685979..b8e187efd5 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -63,6 +63,9 @@ # The full version, including alpha/beta/rc tags. release = u'release-clm5.0.01' +# The format to print out today in +today_fmt = u'%Y-%m-%D %H:%M' + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index 31d00bcb38..f4cf0e5123 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -23,3 +23,5 @@ running-PTCLM/index.rst trouble-shooting/index.rst testing/index.rst + +Documentation was built: |today| diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 7dd868b3f7..9705057439 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -14,7 +14,7 @@ are those of the author(s) and do not necessarily reflect the views of the National Science Foundation. National Center for Atmospheric Research -P. O. Box 3000, Boulder, Colorado 80307-300 +P. O. Box 3000, Boulder, Colorado 80307-3000 .. _rst_Users_Guide_Introduction: @@ -37,12 +37,13 @@ is information in the ChangeLog file and in the `What is new with regarding the changes from previous versions of CESM. .. note:: This release of |version| in |cesmrelease| includes BOTH CLM4.0 - physics used in previous releases as well as the updated |version| - physics. Both CLM as well as CLM support tools allow you to trigger - between the two physics modes. Most often when we refer to CLM4.0 we + physics and CLM4.5 physics used in previous releases as well as the updated |version| + physics. CLM allow you to trigger between the three physics modes. Most often when we refer to CLM4.0 we are referring to the CLM4.0 physics in |version| in |cesmrelease| rather than to a specific version of CLM4.0 (where we would give the exact - version). Likewise, when referring to |version| we are referring to the + version). And when we refer to CLM4.5 we are referring to the CLM4.5 + physics in |version| in |cesmrelease| rather + than to a specific version of CLM4.5. Likewise, when referring to |version| we are referring to the |version| physics in |version| in |cesmrelease|. The novice user should read `Chapter 1 `_ in detail before @@ -88,11 +89,10 @@ machine is working correctly. ============================ `What's new with |version| science `_ -The |cesmrelease| `What's New Science `_ and `What's New Software `_ pages gives a synopsis of the changes to all CESM components since the CESM1.1.1 release. +gives a synopsis of the changes to CLM since the CLM4.5 release. More details are given in the `CLM ChangeLog file `_. Previous release pages give similar list of changes for previous versions of the model. -The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates for versions up to CLM4 in CESM1.0.5. .. _users-guide-overview: @@ -102,23 +102,23 @@ The `CLM4 in CESM1.0.5 User's Guide `_ gives information on the updates In this introduction we first give a simple guide to understand the document conventions in `How to Use This Document `_. The next section `What is new with |version| in |cesmrelease| since previous public releases? `_ gives references to describe the differences between |version| in |cesmrelease| and previous CESM releases both from a scientific as well as a software engineering point of view. -For information on previous releases of |version| before |version| in |cesmrelease| see the CESM1.1.1 documentation. +For information on previous releases of |version| before |version| in |cesmrelease| see the CESM1.2.2 documentation. The next section `Quickstart to using |version| `_ is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use |version|. The next `What is scientifically validated and functional in |version| in |cesmrelease|? `_ tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. `What are the UNIX utilities required to use |version|? `_ lists the UNIX utilities required to use |version| and is important if you are running on non-NCAR machines, generic local machines, or machines NOT as well tested by us at NCAR. Next we have `Important Notes and Best Practices for Usage of |version| `_ to detail some of the best practices for using |version| for science. -The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with CESM1.0 and |version|. +The last introductory section is `Other resources `_ to get help from which lists different resources for getting help with |version| and |cesmrelease|. `Chapter 1 `_ goes into detail on how to setup and run simulations with |version| and especially how to customize cases. Details of cesm_setup modes and build-namelist options as well as namelist options are given in this chapter. -`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.0 or |version| physics for creating input datasets for use by CLM, for the expert user. +`Chapter 2 `_ gives instructions on the CLM tools for either CLM4.5 or |version| physics for creating input datasets for use by CLM, for the expert user. There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. Then each tool is described in detail along with different ways in which the tool might be used. A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. As a followup to the tools chapter, `Chapter 3 `_ tells how to add files to the XML database for build-namelist to use. -This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (both CLM4.0 and |version| physics). +This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (CLM4.0, CLM4.5 and |version| physics). In `Chapter 4 `_, again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up the |version|-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). @@ -153,9 +153,11 @@ This also could be useful for developers who need to update the documentation du Best Practices ================ -- |version| includes BOTH the old CLM4.0 physics AND the new |version| physics and you can toggle between two. +- |version| includes BOTH the old CLM4.0, CLM4.5 physics AND the new |version| physics and you can toggle between those three. The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. - While the "standard" practice for |version| is to run with BGC on, and CRUNCEP atmospheric forcing. + While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. + And finally the "standard" practice for |version| is to run with BGC and Prognostic Crop on, with the MOSART model for river routing, as well as the CISM + ice sheet model, and using GSWP3 atmospheric forcing. "BGC" is the new |version| biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see `the Section called Some Acronym's and Terms We'll be Using in Other resources to get help from `_ ). - When running with CLMCN (either CLM4.0 or |version| physics) or |version|-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see `the Section called Spinning up the |version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for |version| or `the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4 `_ for CLM4.0). @@ -172,23 +174,34 @@ This also could be useful for developers who need to update the documentation du Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. - Initial condition files are also provided for |version| for several configurations and resolutions. - For |version|-SP and |version|-BGC with CRUNCEP forcing we have initial conditions at 1deg resolution for both 1850 and 2000. - The |version|-BGC initial conditions for 1850 (again with CRUNCEP forcing) were also interpolated to 2deg, CRUNCEP half degree (360x720cru), and ne30np4 resolutions. - Also the |version|-BGC initial conditions for 1850 (with CRUNCEP forcing) were interpolated to 1deg |version|-BGC-DV and 2deg |version|-BGC-Crop. + For CLM4.5-SP and CLM4.5-BGC with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. + For |version|-SP and |version|-BGC-Crop with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. + Normally, these files are interpolated to any other resolution that you run at. -- Users can generate initial condition files at different resolutions by using the CLM tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. +- Users can interpolate initial condition files at different resolutions at startup of a CLM4.5 or |version| simulation. And the file created can be stored for later use. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. -- In |version| for both |version|-CN and |version|-BGC the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). - By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2010 for population density. +- In |version| for both |version|-CN, |version|-BGC, and |version|-BGC-Crop the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). + By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2014 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. -- Aerosol deposition is a required field to both CLM4.0 and |version| physics, sent from the atmosphere model. +- Aerosol deposition is a required field to both CLM4.0, CLM4.5 and |version| physics, sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. +.. _CTSM_vs_CESM_checkout: + +============================= +A CTSM versus a CESM checkout +============================= + +The directory structure for |version| is different depending on if it's checked out from |release| or |cesmrelease|. +If |version| is checked out from |ctsm_gh| the CLM source code is directly under the top level directory. If |cesmrelease| +is checkout out from |cesm_gh| then the CLM source directories are under "components/clm" from the top level directory. We +will refer to this directory for the CLM source directories in the User's Guide as "$CTSMROOT". + .. _how-to-use-this-document: ======================================================== @@ -215,3 +228,5 @@ Links to descriptions and definitions have been provided in the code below. We u that continues to the following line. > $EDITOR filename # means you are using a text editor to edit "filename" # This is a comment line + + $CTSMROOT means the path to the root of the CTSM model diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index 3c9964ee38..9160666051 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -12,25 +12,21 @@ If you are missing one of these you should contact the systems administrator for List of utilities required for CESM in the "|cesmrelease| Software/Operating System Prerequisites" section in `http://www.cesm.ucar.edu/models/cesm1.2//cesm/doc/usersguide/book1.html `_ - UNIX bash shell (for some of the CLM tools scripts) - NCL (for some of the offline tools for creating/modifying CLM input datasets see `Chapter 2 `_ for more information on NCL) -- Python (optional, needed for PTCLM) -- xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide) +- Python Before working with |version| read the QuickStart Guide in the `|cesmrelease| Scripts User's Guide `_. Once you are familiar with how to setup cases for any type of simulation with CESM you will want to direct your attention to the specifics of using CLM. For some of the details of setting up cases for |version| read the README and text files available from the "$CTSMROOT/doc" directory (see the "CLM Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. -1. `README file `_ describing the directory structure. - -2. `Quickstart.userdatasets `_ file describing how to use your own datasets in the model (also see `the Section called Creating your own single-point/regional surface datasets in Chapter 5 `_). - -3. `$CTSMROOT/doc/KnownBugs `_ file describing known problems in |version| (that we expect to eventually fix). - -4. `$CTSMROOT/doc/KnownLimitationss `_ file describing known limitations in |version| and workarounds that we do NOT expect to fix. +`README file `_ describing the directory structure. The IMPORTANT_NOTES file talks about important things for users to know about using the model scientifically. It content is given in the next chapter on `"What is scientifically validated and functional in |version| in |cesmrelease|?" `_. The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on `"What is new with |version| in |cesmrelease| since previous public releases?" `_. +The release-clm5.0.ChangeLog gives the specific changes that have gone on the release-clm5.0 branch. clm3_0_ChangeLog, clm4_0_ChangeLog, clm4_5_ChangeLog gives the changes that +culimated in that given version of the CLM. + Note other directories have README files that explain different components and tools used when running CLM and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with CLM see `Chapter 1 `_. The Quickstart.GUIDE (which can be found in ``$CTSMROOT/doc``) is repeated here. diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index b7e80c4b37..12afe4bbf5 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -16,65 +16,3 @@ See `http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for |version|. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for |version| while others are for both CLM4.0 AND |version| we explicitly say which they apply to. - ---------------------------------------------------------------------------------------------------------------- -Configure Modes NOT scientifically validated, documented, supported or, in some cases, even advised to be used: ---------------------------------------------------------------------------------------------------------------- - -These are options that you would add to ``CLM_CONFIG_OPTS``. - -1. exlaklayers on[|version| only] This mode is NOT tested and may NOT be even functional. - -2. snicar_frc on[CLM4.0 AND |version|] This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. - -3. vichydro on[|version| only] This mode is tested and functional, but does NOT have long scientific validation simulations run with it so, should be considered experimental. - -4. vsoilc_centbgc[|version| only] This option is extensively tested for both "on" and "off". The "no-vert" option has limited testing performed on it, but isn't scientifically validated (and it currently has a bug -- see 1746 and 1672 in `$CTSMROOT/doc/KnownBugs `_). The "no-cent" and "no-nitrif" options are NOT tested and as such may NOT ben even functional. - ----------------------------------------------- -Namelist options that should NOT be exercised: ----------------------------------------------- - ----------------------------------------------------- -Build-Namelist options that should NOT be exercised: ----------------------------------------------------- -1. -irrig with -bgc cn and -phys clm4_0 We have only run the irrigation model with CLMSP (i.e. without the CN model). We recommend that if you want to run the irrigation model with CN, that you do a spinup. But, more than that you may need to make adjustments to irrig_factor in $CTSMROOT/src/biogeophys/CanopyFluxesMod.F90. See the notes on this in the description of the irrigation model in the -`Technical Descriptions of the Interactive Crop Management and Interactive Irrigation Models `_. - -2. -irrig with -crop on and -phys clm4_0 Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to generic crop currently, which negates it's practical usage. We also have a known problem when both are on (see bug 1326 in the `$CTSMROOT/doc/KnownBugs `_ file). If you try to run in this mode, the CLM build-namelist will return with an error. - --------------------------------------------- -Namelist items that should NOT be exercised: --------------------------------------------- - -suplnitro='ALL' The suplnitro namelist option to the CN Biogeochemistry model supplies unlimited nitrogen and therefore vegetation is over-productive in this mode. - -urban_traffic:Not currently functional - -allowlakeprod:Considered experimental. - -anoxia_wtsat:Considered experimental (deprecated will be removed). - -atm_c14_filename:Considered experimental (dataset not provided). - -exponential_rooting_profile:Considered experimental. - -fin_use_fsat:Considered experimental. - -glc_dyntopo:Not currently functional. - -lake_decomp_fact:Considered experimental. - -more_vertlayers:Considered experimental. - -no_frozen_nitrif_denitrif:Considered experimental. - -perchroot:Considered experimental. - -perchroot_alt:Considered experimental. - -replenishlakec:Considered experimental. - -use_c14_bombspike:Considered experimental (dataset not provided). - -usefrootc:Considered experimental. diff --git a/doc/source/users_guide/substitutions.rst b/doc/source/users_guide/substitutions.rst index 821ebb071e..c5406a4d4e 100644 --- a/doc/source/users_guide/substitutions.rst +++ b/doc/source/users_guide/substitutions.rst @@ -1,2 +1,5 @@ .. |cesmrelease| replace:: CESM2.0.0 +.. |ctsm_gh| replace:: https://github.com/ESCOMP/ctsm + +.. |cesm_gh| replace:: https://github.com/ESCOMP/cesm From 9a1167db2f54fb8256aab9e3a7655d84cf7aa3e1 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Mon, 18 Jun 2018 22:35:48 -0600 Subject: [PATCH 173/255] More work on overview and add README to the UG --- .../users_guide/overview/getting-help.rst | 80 +++++++++++++++---- .../users_guide/overview/introduction.rst | 9 +++ .../overview/scientific_validation.rst | 13 +++ 3 files changed, 87 insertions(+), 15 deletions(-) diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index aafeb057f5..cf45bc79a4 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -5,7 +5,9 @@ ============== Getting Help ============== -In addition to this users-guide there are several other resources that are available to help you use |version|. The first one is the |cesmrelease| User's-Guide, which documents the entire process of creating cases with |cesmrelease|. The next is the CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in |cesmrelease|. +In addition to this users-guide there are several other resources that are available to help you use |version|. The first one is the |cesmrelease| User's-Guide, which documents the entire process of creating cases with |cesmrelease|. +And next is the CIME User's Guide which goes over the scripts and infrastructure used for running |version| in |cesmrelease|. +The CESM bulletin board which is a web-site for exchanging information between users of CESM. There are also CLM web-pages specific for CLM, and finally there is an email address to report bugs that you find in |cesmrelease|. --------------------------- The CESM User's-Guide @@ -15,6 +17,13 @@ The CESM User's-Guide `|cesmrelease| Quickstart Guide `_ +--------------------------- +The CIME User's-Guide +--------------------------- + +The CIME Users'-Guide goes into the how to use the scripts and infrastructure of the CESM. +`CIME Users Guide `_ + ----------------------- The CESM Bulletin Board ----------------------- @@ -30,6 +39,7 @@ The CLM web pages The main CLM web page contains information on the CLM, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the $CTSMROOT/doc directory that give some quick information on using CLM. `CLM web page `_ +`|cesmrelease| |version| web page `_ `CLM Documentation Text Files `_ Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files: @@ -38,8 +48,8 @@ Also note that several of the XML database files can be viewed in a web browser - `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_5.xml `_ -- definition of CLM4.5/CLM5.0 namelist items. - `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_0.xml `_ -- default values for CLM4.0 namelist items. - `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_5.xml `_ -- default values for CLM4.5/CLM5.0 namelist items. -- `scripts/ccsm_utils/Case.template/config_definition.xml `_ -- definition of all env_*.xml items. -- `scripts/ccsm_utils/Case.template/config_compsets.xml `_ -- definition of all the compsets. +- `$CTSMROOT/cime_config/config_component.xml `_ -- definition of all the CLM specific XML variables. +- `$CTSMROOT/cime_config/config_compsets.xml `_ -- definition of all the CLM compsets. - `$CTSMROOT/bld/namelist_files/history_fields_clm4_0.xml `_ -- definition of CLM4.0 history fields. - `$CTSMROOT/bld/namelist_files/history_fields_clm4_5.xml `_ -- definition of CLM4.5/CLM5.0 history fields. @@ -47,8 +57,11 @@ Also note that several of the XML database files can be viewed in a web browser Reporting bugs in |version| ---------------------------- -If you have any problems, additional questions, bug reports, or any other feedback, please send an email to <`cesmhelp@cgd.ucar.edu `_>. If you find bad, wrong, or misleading information in this users guide send an email to <`erik@ucar.edu `_>. The current list of known issues for |version| in |cesmrelease| is in the $CTSMROOT/doc/KnownBugs file, and the list of issues for |cesmrelease| is at... -`http://www.cesm.ucar.edu/models/cesm1.2//tags/|cesmrelease|/#PROBLEMS `_. +If you have any problems, additional questions, bug reports, or any other feedback, please report it as an issue +on GitHub https://github.com/ESCOMP/ctsm/issues or for CIME scripts and infrastructure to https://github.com/ESMCI/CIME/issues. +Or send an email to +<`cesmhelp@cgd.ucar.edu `_> or <`ctsm-software@ucar.edu `_>. +If you find bad, wrong, or misleading information in this users guide report it as an issue on CTSM. --------------------------------------- Some Acronym's and Terms We'll be Using @@ -60,55 +73,92 @@ CAM CESM Community Earth System Model (CESM). The coupled earth system model that CLM is a component of. +CIME + The Common Infrastructure for Modeling the Earth (CIME - pronounced “SEAMâ€) provides a Case Control System for configuring, compiling and executing Earth system models, data and stub model components, a driver and associated tools and libraries. + CLM Community Land Model (CLM). The prognostically active land model component of CESM. CLMBGC Community Land Model (|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is - ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc cn -vsoilc_centbgc on -clm4me on"`` + ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc bgc`` + +CLMBGC-Crop + Community Land Model (|version|) with BGC Biogeochemistry and prognotic crop. The CLM_CONFIG_OPTS option for this is + + ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc bgc -crop`` CLMCN - Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0 or |version|) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Carbon Nitrogen (CN) Biogeochemistry (either CLM4.0, CLM4.5 or |version|) The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc cn" -append`` CLMSP - Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0 or |version|) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0, CLM4.5 or |version|) The CLM_CONFIG_OPTS option for this is - ``./xmlchange CLM_CONFIG_OPTS="-bgc none" -append`` + ``./xmlchange CLM_CONFIG_OPTS="-bgc sp" -append`` CLMU - Community Land Model (CLM) Urban Model (either CLM4.0 or |version|). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). + Community Land Model (CLM) Urban Model (either CLM4.0, CLM4.5 or |version|). The urban model component of CLM is ALWAYS active (unless you create special surface datasets that have zero urban percent, or for regional/single-point simulations for a non-urban area). CRUNCEP - The Climate Research Unit (CRU) analysis of the NCEP atmosphere reanalysis atmosphere forcing data. This can be used to drive CLM with atmosphere forcing from 1901 to 2010. We also DO expect to be able to update this dataset beyond 2010 as newer data becomes available. + The Climate Research Unit (CRU) analysis of the NCEP atmosphere reanalysis atmosphere forcing data. This can be used to drive CLM with atmosphere forcing from 1901 to 2016. This data is updated every year, the version we are currently using is Version-7. The las CESM1.2.2 release used Version-4 data. + +CTSM + The Community Terrestrial Systems Model, of which |version| and CLM4.5 are namelist option sets of. CTSM is a wider community + that includes using CTSM for Numerical Weather Prediction (NWP) as well as climate. DATM - Data Atmosphere Model (DATM) the prescribed data atmosphere component for CESM. Forcing data that we provide are either the Qian or CRUNCEP forcing datasets (see below). + Data Atmosphere Model (DATM) the prescribed data atmosphere component for CESM. Forcing data that we provide are either the CRUNCEP, Qian, or GSWP3 forcing datasets (see below). DV - Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either |version|-BGC or CLMCN for either CLM4.0 or |version|). The CLM_CONFIG_OPTS option for this is + Dynamic global vegetation, where fractional PFT (see PFT below) changes in time prognostically. Can NOT be used with prescribed transient PFT (requires either CLMBGC or CLMCN for either CLM4.0, CLM4.5 or |version|). The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc cndv" -append`` + This option is being phased out for the different methodology of FATES (see below). DV is not currently scientifically validated + and as such should be considered experimental. + ESMF Earth System Modeling Framework (ESMF). They are a software project that provides a software library to support Earth System modeling. We provide interfaces for ESMF as well as use their regridding capabilities for offline CLM tools. +FATES + Functionally Assembled Terrestrial Ecosystem Simulator. This is being developed by the Next Generation Ecosystem Experiment Tropics’ (NGEE-T) + project and uses both |version| and the land model component of E3SM (Energy Exascale Earth System Model). + +FUN + Fixation and Uptake of Nitrogen model, a parameter option of |version|. + +GSWP3 + Global Soil Wetness Project (GSPW3) atmospheric forcing data. It is a 3-hourly 0.5° global forcing product (1901-2014) that is based on the NCEP 20th Century Reanalysis, with additional bias corrections added by GSWP3. + +LUNA + Leaf Utilization of Nitrogen for Assimilation parameterization option as part of |version|. + NCAR National Center for Atmospheric Research (NCAR). This is the research facility that maintains CLM with contributions from other national labs and Universities. NCEP The National Center for Environmental Prediction (NCEP). In this document this normally refers to the reanalysis atmosphere data produced by NCEP. +MOSART + Model for Scale Adaptive River Transport, ROF model component option added as part of |version|. It is the standard + ROF model used in |version| compsets. + PFT Plant Function Type (PFT). A type of vegetation that CLM parameterizes. PTCLM PoinT CLM (PTCLM) a python script that operates on top of CLM for |version| to run single point simulations for CLM. -Qian - The Qian et. al. analysis of the NCEP forcing data. This can be used to drive CLM with atmosphere forcing from 1948 to 2004. We do NOT expect to be able to update this dataset beyond 2004. +ROF + River runOff Model to route flow of surface water over land out to the ocean. |cesmrelease| has two components options for this + the new model MOSART and previous model RTM. + +RTM + River Transport Model, ROF model component option that has been a part of all versions of CESM. It is the standard ROF + model used in CLM4.5 and CLM4.0 compsets. SCRIP Spherical Coordinate Remapping and Interpolation Package (SCRIP). We use it's file format for specifying both grid coordinates as well as mapping between different grids. diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 9705057439..075462d35f 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -147,6 +147,15 @@ Finally in `Appendix A `_ we give instructions on how to build the docu This document is included in every CLM distribution and can be built so that you can view a local copy rather than having to go to the CESM website. This also could be useful for developers who need to update the documentation due to changes they have made. +================================ +README file describing |version| +================================ + +The README (which can be found in ``$CTSMROOT/doc``) is repeated here. + +.. include:: ../../clm5.0/README + :literal: + .. _best-practices-for-usage: ================ diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index 12afe4bbf5..9b38be4808 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -16,3 +16,16 @@ See `http://www.cesm.ucar.edu/models/cesm1.2/clm/CLM_configurations_CESM1.2.pdf `_ for an explanation of what configurations are scientifically validated for |version|. For CLM4.0 changes to the science of the model are minimal since CESM1.1.1 so we expect answers to be very similar to using it. In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. Some of these options are only for |version| while others are for both CLM4.0 AND |version| we explicitly say which they apply to. + +----------------------------------------------- +Configurations that should be used with caution +----------------------------------------------- + +There are some options in |version| that are available but either not tested extensively, or not scientifically evaluated. These +options should be used with caution. And any options that deviate from the scientifically supported configurations can have issues. +The IMPORTANT_NODES file goes into more details on this. + +The IMPORTANT_NOTES (which can be found in ``$CTSMROOT/doc``) is repeated here. + +.. include:: ../../clm5.0/doc/IMPORTANT_NOTES + :literal: From b7b3fd3ab5194fb143887afa8d2ea4d03d2c489f Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Tue, 19 Jun 2018 22:16:21 -0600 Subject: [PATCH 174/255] Work on the setting up a case section --- .../users_guide/overview/introduction.rst | 2 +- .../choosing-a-compset.rst | 17 +++- .../customizing-the-clm-configuration.rst | 97 +++++++++++-------- .../customizing-the-clm-namelist.rst | 8 +- .../customizing-the-datm-namelist.rst | 30 ++++-- 5 files changed, 95 insertions(+), 59 deletions(-) diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 075462d35f..c3d29ab83b 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -200,7 +200,7 @@ The README (which can be found in ``$CTSMROOT/doc``) is repeated here. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. -.. _CTSM_vs_CESM_checkout: +.. _ctsm_vs_cesm_checkout: ============================= A CTSM versus a CESM checkout diff --git a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst index df702e0185..c2bb0b606b 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/choosing-a-compset.rst @@ -3,7 +3,7 @@ .. include:: ../substitutions.rst ==================== - Choosing a compset +Choosing a compset ==================== When setting up a new case one of the first choices to make is which "component set" (or compset) to use. @@ -12,6 +12,8 @@ We label the different types of compsets with a different letter of the alphabet The compsets of interest when working with CLM are the "I" compsets (which contain CLM with a data atmosphere model and a stub ocean, and stub sea-ice models), "E" and "F" compsets (which contain CLM with the active atmosphere model (CAM), prescribed sea-ice model, and a data ocean model), and "B" compsets which have all active components. Below we go into details on the "I" compsets which emphasize CLM as the only active model, and just mention the two other categories. +To run CLM coupled to CAM ("E" or "F" compsets) or fully coupled ("B compsets) you need to be running CLM from a CESM checkout rather than a CTSM checkout (see :ref:`ctsm_vs_cesm_checkout`). + When working with CLM you usually want to start with a relevant "I" compset before moving to the more complex cases that involve other active model components. The "I" compsets can exercise CLM in a way that is similar to the coupled modes, but with much lower computational cost and faster turnaround times. @@ -22,9 +24,14 @@ Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) Here is the entire list of compsets available. -Note that using the "-user_compset" option even more combinations are possible. -In the list below we give the alias name and then the long name which describes each component in parenthesis. -Alias (Long-name with time-period and each component) + +`CESM compsets `_ + +Note that using the "-user_compset" option even more combinations are possible. To get a list of the compsets use the "query_config" +command as follows: +:: + + $CTSMROOT/cime/scripts/query_config --compsets clm Compsets coupled to active atmosphere with data ocean ----------------------------------------------------- @@ -37,5 +44,5 @@ Fully coupled compsets are compsets that start with "B" in the name. They are de Conclusion to choosing a compset -------------------------------- We've introduced the basic type of compsets that use CLM and given some further details for the "standalone CLM" (or "I" compsets). -The `config_compsets.xml `_ lists all of the compsets and gives a full description of each of them. +The `$CTSMROOT/cime_config/config_compsets.xml `_ lists all of the compsets and gives a full description of each of them. In the next section we look into customizing the setup time options for compsets using CLM. diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index 38f61c2c4d..f752b1a766 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -2,23 +2,26 @@ .. include:: ../substitutions.rst -******************************* -Customizing CLM's Configuration -******************************* +******************************** + Customizing CLM's Configuration +******************************** -The "Creating a Case" section of the |cesmrelease| `Scripts User's-Guide `_ gives instructions on creating a case. What is of interest here is how to customize your use of CLM for the case that you created. +The section of the |cesmrelease| Quickstart `CESM Create a Case `_ gives instructions on creating a case. +Also see a similar section in the CIME User's-Guide `CIME Create a case `_. +What is of interest here is how to customize your use of CLM for the case that you created. -For CLM when **preview_namelist**, **$CASE.build**, or **$CASE.run** are called there are two steps that take place: +For CLM when **preview_namelist**, **case.build**, or **case.run** are called there are two steps that take place: -1. The CLM "**configure**" script is called to setup the build-time configuration for CLM (more information on **configure** is given in `the Section called More information on the CLM configure script `_). The env variables for **configure** are locked after the **$CASE.build** step. So the results of the CLM **configure** are locked after the build has taken place. +1. The CLM "**configure**" script is called to setup the build-time configuration for CLM (more information on **configure** is given in `the Section called More information on the CLM configure script `_). The env variables for **configure** are locked after the **case.build** step. So the results of the CLM **configure** are locked after the build has taken place. 2. The CLM "**build-namelist**" script is called to generate the run-time namelist for CLM (more information on **build-namelist** is given below in `the Section called Definition of Namelist items and their default values `_. -When customizing your case at the *8cesm_setup** step you are able to modify the process by effecting either one or both of these steps. The CLM "**configure**" and "**build-namelist**" scripts are both available in the "$CTSMROOT/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. +When customizing your case at the **case.setup** step you are able to modify the process by effecting either one or both of these steps. The CLM "**configure**" and "**build-namelist**" scripts are both available in the "$CTSMROOT/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. There are five different types of customization for the configuration that we will discuss: |version| in |cesmrelease| build-time options, |version| in |cesmrelease| run-time options, User Namelist, other noteworthy |cesmrelease| configuration items, the CLM **configure** script options, and the CLM **build-namelist** script options. -Information on all of the script, configuration, build and run items is found under ``scripts/ccsm_utils/Case.template`` in the `config_definition.xml `_ file. +Information on all of the CLM script, configuration, build and run items is found under ``$CTSMROOT/cime_config/config_component.xml``. +See `CLM CASEROOT Variable Definitions `_. ================================ CLM Script configuration items @@ -27,13 +30,16 @@ Information on all of the script, configuration, build and run items is found un Below we list each of the CESM configuration items that are specific to CLM. All of these are available in your: ``env_build.xml`` and ``env_run.xml`` files. :: - CLM_CONFIG_OPTS + CLM_ACCELERATED_SPINUP CLM_BLDNML_OPTS - CLM_NAMELIST_OPTS + CLM_CO2_TYPE + CLM_CONFIG_OPTS + CLM_CPPDEFS CLM_FORCE_COLDSTART + CLM_NAMELIST_OPTS CLM_NML_USE_CASE CLM_USRDAT_NAME - CLM_CO2_TYPE + COMP_LND For the precedence of the different options to **build-namelist** see the section on precedence below. @@ -45,16 +51,16 @@ CLM_CONFIG_OPTS You can still add more options to your ``CLM_CONFIG_OPTS`` but make sure you add to what is already there rather than replacing it. Hence, we recommend using the "-append" option to the xmlchange script. In `the Section called More information on the CLM configure script `_ below we will go into more details on options that can be customized in the CLM "**configure**" script. - It's also important to note that the **clm.buildnml.csh** script may already invoke certain CLM **configure** options and as such those command line options are NOT going to be available to change at this step (nor would you want to change them). + It's also important to note that the **$CTSMROOT/cime_config/buildnml** script may already invoke certain CLM **configure** options and as such those command line options are NOT going to be available to change at this step (nor would you want to change them). The options to CLM **configure** are given with the "-help" option which is given in `the Section called More information on the CLM configure script `_. - .. note:: ``CLM_CONFIG_OPTS`` is locked after the **$CASE.build** script is run. If you want to change something in ``CLM_CONFIG_OPTS`` you'll need to clean the build and rerun **$CASE.build**. The other env variables can be changed at run-time so are never locked. + .. note:: ``CLM_CONFIG_OPTS`` is locked after the **case.build** script is run. If you want to change something in ``CLM_CONFIG_OPTS`` you'll need to clean the build and rerun **case.build**. The other env variables can be changed at run-time so are never locked. CLM_NML_USE_CASE ``CLM_NML_USE_CASE`` is used to set a particular set of conditions that set multiple namelist items, all centering around a particular usage of the model. To list the valid options do the following: :: - > cd $CTSMROOT/doc - > ../bld/build-namelist -use_case list + > cd $CTSMROOT + > ./bld/build-namelist -use_case list The output of the above command is: :: @@ -108,7 +114,7 @@ CLM_NML_USE_CASE CLM_BLDNML_OPTS The option CLM_BLDNML_OPTS is for passing options to the CLM "build-namelist" script. - As with the CLM "configure" script the CLM clm.buildnml.csh may already invoke certain options and as such those options will NOT be available to be set here. The best way to see what options can be sent to the "build-namelist" script is to do + As with the CLM "configure" script the CLM $CTSMROOT/cime_config/buildnml may already invoke certain options and as such those options will NOT be available to be set here. The best way to see what options can be sent to the "build-namelist" script is to do :: > cd $CTSMROOT/bld @@ -257,7 +263,7 @@ CLM_BLDNML_OPTS 5. values from the namelist defaults file. -The **clm.buildnml.csh** script already sets the resolution and mask as well as the CLM **configure** file, and defines an input namelist and namelist input file, and the output namelist directory, and sets the start-type (from ``RUN_TYPE``), namelist options (from ``CLM_NAMELIST_OPTS``), co2_ppmv (from ``CCSM_CO2_PPMV``, co2_type (from ``CLM_CO2_TYPE``), lnd_frac (from ``LND_DOMAIN_PATH`` and ``LND_DOMAIN_FILE``), l_ncpl (from ``LND_NCPL``, glc_grid, glc_smb, glc_nec (from ``GLC_GRID``, ``GLC_SMB``, and ``GLC_NEC``), and "clm_usr_name" is set (to ``CLM_USRDAT_NAME >``when the grid is set to ``CLM_USRDAT_NAME``. +The **$CTSMROOT/cime_config/buildnml** script already sets the resolution and mask as well as the CLM **configure** file, and defines an input namelist and namelist input file, and the output namelist directory, and sets the start-type (from ``RUN_TYPE``), namelist options (from ``CLM_NAMELIST_OPTS``), co2_ppmv (from ``CCSM_CO2_PPMV``, co2_type (from ``CLM_CO2_TYPE``), lnd_frac (from ``LND_DOMAIN_PATH`` and ``LND_DOMAIN_FILE``), l_ncpl (from ``LND_NCPL``, glc_grid, glc_smb, glc_nec (from ``GLC_GRID``, ``GLC_SMB``, and ``GLC_NEC``), and "clm_usr_name" is set (to ``CLM_USRDAT_NAME >``when the grid is set to ``CLM_USRDAT_NAME``. Hence only the following different options can be set: 1. @@ -288,7 +294,7 @@ Hence only the following different options can be set: "-bgc_spinup" is an option only available for |version| for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See `the Section called Spinning up the |version| biogeochemistry (CLMBGC spinup) in Chapter 4 `_ for an example using this option. -"-chk_res" ensures that the resolution chosen is supported by CLM. If the resolution is NOT supported it will cause the CLM **build-namelist** to abort when run. So when either **preview_namelist**, **$CASE.build** or **$CASE.run** is executed it will abort early. Since, the CESM scripts only support certain resolutions anyway, in general this option is NOT needed in the context of running CESM cases. +"-chk_res" ensures that the resolution chosen is supported by CLM. If the resolution is NOT supported it will cause the CLM **build-namelist** to abort when run. So when either **preview_namelist**, **case.build** or **case.run** is executed it will abort early. Since, the CESM scripts only support certain resolutions anyway, in general this option is NOT needed in the context of running CESM cases. "-clm_demand" asks the **build-namelist** step to require that the list of variables entered be set. Typically, this is used to require that optional filenames be used and ensure they are set before continuing. For example, you may want to require that fpftdyn be set to get dynamically changing vegetation types. To do this you would do the following. :: @@ -310,7 +316,9 @@ To see a list of valid variables that you could set do this: "-ignore_ic_year" ignores the Initial Conditions (IC) year for finding initial condition files to startup from. The date is used, but the year is ignored. Without this option or the "-ignore_ic_date" option below, the date and year of the file comes into play. -When "-irrig" is used **build-namelist** will try to find surface datasets that have the irrigation model enabled. +When "-irrig on" is used **build-namelist** will try to find surface datasets that have the irrigation model enabled (when running +with Sattellitte Phenology). When running with the prognostic crop model on, "-irrig on" will turn irrigate crops on, while "-irrig off" +will manage all crop areas as rain-fed without irrigation. "no-megan" means do NOT add the MEGAN model Biogenic Volatile Organic Compounds (BVOC) namelist to the driver. This namelist is created by default, so normally this WILL be done. This is a driver namelist, so unless "no-megan" is specified the CLM **build-namelist** will create the ``drv_flds_in`` file that the driver will copy over and use (if you are running with CAM and CAM produces this file as well, it's file will have precedence). @@ -374,7 +382,7 @@ When "-irrig" is used **build-namelist** will try to find surface datasets that User Namelist =============== -``CLM_NAMELIST_OPTS`` as described above allows you to set any extra namelist items you would like to appear in your namelist. However, it only allows you a single line to enter namelist items, and strings must be quoted with ' which is a bit awkward. If you have a long list of namelist items you want to set (such as a long list of history fields) a convenient way to do it is to add to the ``user_nl_clm`` that is created after the **cesm_setup** command runs. The file needs to be in valid FORTRAN namelist format (with the exception that the namelist name &namelist and the end of namelist marker "/" are excluded". The **preview_namelist** or **$CASE.run** step will abort if there are syntax errors. All the variable names must be valid and the values must be valid for the datatype and any restrictions for valid values for that variable. Here's an example ``user_nl_clm`` namelist that sets a bunch of history file related items, to create output history files monthly, daily, every six and 1 hours. +``CLM_NAMELIST_OPTS`` as described above allows you to set any extra namelist items you would like to appear in your namelist. However, it only allows you a single line to enter namelist items, and strings must be quoted with ' which is a bit awkward. If you have a long list of namelist items you want to set (such as a long list of history fields) a convenient way to do it is to add to the ``user_nl_clm`` that is created after the **case.setup** command runs. The file needs to be in valid FORTRAN namelist format (with the exception that the namelist name &namelist and the end of namelist marker "/" are excluded". The **preview_namelist** or **case.run** step will abort if there are syntax errors. All the variable names must be valid and the values must be valid for the datatype and any restrictions for valid values for that variable. Here's an example ``user_nl_clm`` namelist that sets a bunch of history file related items, to create output history files monthly, daily, every six and 1 hours. ---------------------------------- Example: user_nl_clm namelist file @@ -460,17 +468,17 @@ Especially with CLMBGC and CLMCN starting from initial conditions is very import - `the Section called Providing a finidat file in your user_nl_clm file `_ - `the Section called Adding a finidat file to the XML database `_ - **Note:** Your initial condition file MUST agree with the surface dataset you are using to run the simulation. If the two files do NOT agree you will get a run-time about a mis-match in PFT weights, or in the number of PFT's or columns. To get around this you'll need to use the `Section called Using interpinic to interpolate initial conditions to different resolutions in Chapter 2 `_ to interpolate your initial condition dataset. + **Note:** Your initial condition file MUST agree with the surface dataset you are using to run the simulation. If the two files do NOT agree you will get a run-time about a mis-match in PFT weights, or in the number of PFT's or columns. To get around this you'll need to add the "use_init_interp=T" namelist flag in your namelist so that the initial conditions will be interpolated on startup.** ------------------------------------------------------- Doing a hybrid simulation to provide initial conditions ------------------------------------------------------- -The first option is to setup a hybrid simulation and give a ``RUN_REFCASE`` and ``RUN_REFDATE`` to specify the reference case simulation name to use. When you setup most cases, at the standard resolutions of "f09" or "f19" it will already do this for you. For example, if you run an "I2000CN" compset at "f09_g17_gl4" resolution the following settings will already be done for you. +The first option is to setup a hybrid simulation and give a ``RUN_REFCASE`` and ``RUN_REFDATE`` to specify the reference case simulation name to use. When you setup coupled cases (assuming a CESM checkout), at the standard resolution of "f09" it will already do this for you. For example, if you run an "B1850" compset at "f09_g17_gl4" resolution the following settings will already be done for you. -``./xmlchange RUN_TYPE=hybrid,RUN_REFCASE=I2000CN_f09_g17_gl4_c100503,RUN_REFDATE=0001-01-01,GET_REFCASE=TRUE`` +``./xmlchange RUN_TYPE=hybrid,RUN_REFCASE=b.e20.B1850.f09_g17.pi_control.all.297,RUN_REFDATE=0130-01-01,GET_REFCASE=TRUE`` -Setting the ``GET_REFCASE`` option to ``TRUE means`` it will copy the files from the: ``$DIN_LOC_ROOT/ccsm4_init/I2000CN_f09_g17_gl4_c100503/0001-01-01`` directory. Note, that the ``RUN_REFCASE`` and ``RUN_REFDATE`` variables are expanded to get the directory name above. If you do NOT set ``GET_REFCASE`` to ``TRUE`` then you will need to have placed the file in your run directory yourself. In either case, the file is expected to be named: ``$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc`` with the variables expanded of course. +Setting the ``GET_REFCASE`` option to ``TRUE means`` it will copy the files from the RUN_REFDIR usually under: ``$DIN_LOC_ROOT/cesm2_init/$RUN_REFCASE/$RUN_REFDATE`` directory. Note, that the ``RUN_REFCASE`` and ``RUN_REFDATE`` variables are expanded to get the directory name above. If you do NOT set ``GET_REFCASE`` to ``TRUE`` then you will need to have placed the file in your run directory yourself. In either case, the file is expected to be named: ``$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc`` with the variables expanded of course. ------------------------------------------------------- Doing a branch simulation to provide initial conditions @@ -500,12 +508,13 @@ Other noteworthy configuration items ------------------------------------ For running "I" cases there are several other noteworthy configuration items that you may want to work with. -Most of these involve settings for the DATM, but one ``CCSM_CO2_PPMV`` applies to all models. +Most of these involve settings for the DATM, but one ``CCSM_CO2_PPMV`` applies to all models. The list of DATM +settings is `here `_. If you are running an B, E, or F case that doesn't use the DATM obviously the DATM_* settings will not be used. All of the settings below are in your ``env_build.xml`` and ``env_run.xml`` files :: CCSM_CO2_PPMV - CCSM_VOC + CCSM_BGC DATM_MODE DATM_PRESAERO DATM_CLMNCEP_YR_ALIGN @@ -519,24 +528,30 @@ If you are running an B, E, or F case that doesn't use the DATM obviously the DA ``CCSM_CO2_PPMV`` Sets the mixing ratio of CO2 in parts per million by volume for ALL CESM components to use. Note that most compsets already set this value to something reasonable. Also note that some compsets may tell the atmosphere model to override this value with either historic or ramped values. If the CCSM_BGC variable is set to something other than "none" the atmosphere model will determine CO2, and CLM will listen and use what the atmosphere sends it. On the CLM side the namelist item co2_type tells CLM to use the value sent from the atmosphere rather than a value set on it's own namelist. -``CCSM_VOC`` - Enables passing of the Volatile Organic Compounds (VOC) from CLM to the atmospheric model. This of course is only important if the atmosphere model is a fully active model that can use these fields in it's chemistry calculations. - ``DATM_MODE`` - Sets the mode that the DATM model should run in this determines how data is handled as well as what the source of the data will be. Many of the modes are setup specifically to be used for ocean and/or sea-ice modeling. The modes that are designed for use by CLM are: + Sets the mode that the DATM model should run in this determines how data is handled as well as what the source of the data will be. Many of the modes are setup specifically to be used for ocean and/or sea-ice modeling. The modes that are designed for use by CLM are (CLM_QIAN, CLMCRUNCEP, CLMCRUNCEPv7, CLMGSWP3v1 and CLM1PT): :: CLMCRUNCEP + CLMCRUNCEPv7 + CLMGSWP3v1 CLM_QIAN - CLM1PT> - CPLHIST3HrWx + CLM1PT + CPLHISTForcing ``CLMCRUNCEP`` - The standard mode for |version| of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010. + The standard mode for CLM4.5 of using global atmospheric data that was developed by CRU using NCEP data from 1901 to 2010 (version 4 of this series). See `the Section called CLMCRUNCEP mode and it's DATM settings `_ for more information on the DATM settings for ``CLMCRUNCEP`` mode. +``CLMCRUNCEPv7`` + Version 7 of the CRUNCEP data from 1901 to 2016. + See `the Section called CLMCRUNCEPv7 mode and it's DATM settings `_ for more information on the DATM settings for ``CLMCRUNCEP`` mode. + +``CLMGSWP3v1`` + GSWP3 version 1 forcing data based on NCEP reanalysis with bias corrections by GSWP3 from 1901 to 2010. + ``CLM_QIAN`` - The standard mode for CLM4.0 of using global atmospheric data that was developed by Qian et. al. for CLM using NCEP data from 1948 to 2004. See the `Section called CLM_QIAN mode and it's DATM settings `_ for more information on the DATM settings for ``CLM_QIAN`` mode. ``CLM1PT`` is for the special cases where we have single-point tower data for particular sites. Right now we only have data for three urban locations: MexicoCity Mexico, Vancouver Canada, and the urban-c alpha site. And we have data for the US-UMB AmeriFlux tower site for University of Michigan Biological Station. See `the Section called CLM1PT mode and it's DATM settings `_ for more information on the DATM settings for ``CLM1PT`` mode. ``CPLHIST3HrWx`` is for running with atmospheric forcing from a previous CESM simulation. See `the Section called CPLHIST3HrWx mode and it's DATM settings `_ for more information on the DATM settings for ``CPLHIST3HrWx`` mode. + The standard mode for CLM4.0 of using global atmospheric data that was developed by Qian et. al. for CLM using NCEP data from 1948 to 2004. See the `Section called CLM_QIAN mode and it's DATM settings `_ for more information on the DATM settings for ``CLM_QIAN`` mode. ``CLM1PT`` is for the special cases where we have single-point tower data for particular sites. Right now we only have data for three urban locations: MexicoCity Mexico, Vancouver Canada, and the urban-c alpha site. And we have data for the US-UMB AmeriFlux tower site for University of Michigan Biological Station. See `the Section called CLM1PT mode and it's DATM settings `_ for more information on the DATM settings for ``CLM1PT`` mode. ``CPLHISTForcing`` is for running with atmospheric forcing from a previous CESM simulation. See `the Section called CPLHISTForcing mode and it's DATM settings `_ for more information on the DATM settings for ``CPLHISTForcing`` mode. ``DATM_PRESAERO`` sets the prescribed aerosol mode for the data atmosphere model. The list of valid options include: @@ -567,13 +582,13 @@ DATM_CLMNCEP_YR_ALIGN ``DATM_CLMNCEP_YR_START`` and ``DATM_CLMNCEP_YR_END`` determine the range of years to cycle the atmospheric data over, and ``DATM_CLMNCEP_YR_ALIGN`` determines which year in that range of years the simulation will start with. DATM_CPL_CASE - ``DATM_CPL_CASE`` sets the casename to use for the ``CPLHIST3HrWx`` mode. + ``DATM_CPL_CASE`` sets the casename to use for the ``CPLHISTForcing`` mode. DATM_CPL_YR_START - ``DATM_CPL_YR_START`` sets the beginning year to cycle the atmospheric data over for the ``CPLHIST3HrWx`` mode. + ``DATM_CPL_YR_START`` sets the beginning year to cycle the atmospheric data over for the ``CPLHISTForcing`` mode. DATM_CPL_YR_END - ``DATM_CPL_YR_END`` sets the ending year to cycle the atmospheric data over for the ``CPLHIST3HrWx`` mode. + ``DATM_CPL_YR_END`` sets the ending year to cycle the atmospheric data over for the ``CPLHISTForcing`` mode. DATM_CPL_YR_ALIGN ``DATM_CPL_YR_START`` and ``DATM_CPL_YR_END`` determine the range of years to cycle the atmospheric data over, and ``DATM_CPL_YR_ALIGN`` determines which year in that range of years the simulation will start with. @@ -586,16 +601,16 @@ In Chapter One of the `CESM User's Guide `_ there is a section The `CLMCRUNCEP` data is uploaded into the subversion inputdata repository as well -- but as it is 1.1 Terabytes of data downloading it is problematic (*IT WILL TAKE SEVERAL DAYS TO DOWNLOAD THE ENTIRE DATASET USING SUBVERSION*). Because of it's size you may also need to download it onto a separate disk space. We have done that on cheyenne for example where it resides in ``$ENV{CESMROOT}/lmwg`` while the rest of the input data resides in ``$ENV{CESMDATAROOT}/inputdata``. The data is also already available on: janus, franklin, and hopper. If you download the data, we recommend that you break your download into several chunks, by setting up a case and setting the year range for ``DATM_CPL_YR_START`` and ``DATM_CPL_YR_END`` in say 20 year sections over 1901 to 2010, and then use **check_input_data** to export the data. -The ``CPLHIST3HrWx`` DATM forcing data is unique -- because it is large compared to the rest of the input data, and we only have a disk copy on cheyenne. The DATM assumes the path for the previous NCAR machine cheyenne of ``/glade/p/cesm/shared_outputdata/cases/ccsm4/$DATM_CPLHIST_CASE`` for the data. So you will need to change this path in order to run on any other machine. You can download the data itself from NCAR HPSS from ``/CCSM/csm/$DATM_CPLHIST_CASE``. +The ``CPLHISTForcing`` DATM forcing data is unique -- because it is large compared to the rest of the input data, and we only have a disk copy on cheyenne. The DATM assumes the path for the previous NCAR machine cheyenne of ``/glade/p/cesm/shared_outputdata/cases/ccsm4/$DATM_CPLHIST_CASE`` for the data. So you will need to change this path in order to run on any other machine. You can download the data itself from NCAR HPSS from ``/CCSM/csm/$DATM_CPLHIST_CASE``. -------------------------------------- Customizing via the build script files -------------------------------------- -The final thing that the user may wish to do before **cesm_setup** is run is to edit the build script files which determine the configuration and namelist. The variables in ``env_build.xml`` or ``env_run.xml`` typically mean you will NOT have to edit build script files. But, there are rare instances where it is useful to do so. The build script files are copied to your case directory and are available under Buildconf. The list of build script files you might wish to edit are: +The final thing that the user may wish to do before **case.setup** is run is to edit the build script files which determine the configuration and namelist. The variables in ``env_build.xml`` or ``env_run.xml`` typically mean you will NOT have to edit build script files. But, there are rare instances where it is useful to do so. The build script files are copied to your case directory and are available under Buildconf. The list of build script files you might wish to edit are: **clm.buildexe.csh** -**clm.buildnml.csh** +**$CTSMROOT/cime_config/buildnml** **datm.buildexe.csh** **datm.buildnml.csh** @@ -687,4 +702,4 @@ The output to the above command is as follows: We've given details on how to use the options in env_build.xml and env_run.xml to interact with the CLM "configure" and "build-namelist" scripts, as well as giving a good understanding of how these scripts work and the options to them. -In the next section we give further details on the CLM namelist. You could customize the namelist for these options after "cesm_setup" is run. +In the next section we give further details on the CLM namelist. You could customize the namelist for these options after "case.setup" is run. diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst index 41eec17598..93f30f8a29 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst @@ -6,7 +6,7 @@ Customizing CLM's namelist ============================ -Once a case is **cesm_setup**, we can then customize the case further, by editing the run-time namelist for CLM. First let's list the definition of each namelist item and their valid values, and then we'll list the default values for them. Next for some of the most used or tricky namelist items we'll give examples of their use, and give you example namelists that highlight these features. +Once a case has run **case.setup**, we can then customize the case further, by editing the run-time namelist for CLM. First let's list the definition of each namelist item and their valid values, and then we'll list the default values for them. Next for some of the most used or tricky namelist items we'll give examples of their use, and give you example namelists that highlight these features. In the following, various examples of namelists are provided that feature the use of different namelist options to customize a case for particular uses. Most the examples revolve around how to customize the output history fields. @@ -55,7 +55,7 @@ Below we will give examples of user namelists that activate different commonly u The default namelist -------------------- -Here we give the default namelist as it would be created for an "I1850Clm50BgcCropCru" compset at 0.9x1.25 resolution with a gx1v6 land-mask on cheyenne. To edit the namelist you would edit the ``user_nl_clm`` user namelist with just the items you want to change. For simplicity we will just show the CLM namelist and NOT the entire file. In the sections below, for simplicity we will just show the user namelist (``user_nl_clm``) that will add (or modify existing) namelist items to the namelist. +Here we give the default namelist as it would be created for an "I1850Clm50BgcCropCru" compset at 0.9x1.25 resolution with a gx1v7 land-mask on cheyenne. To edit the namelist you would edit the ``user_nl_clm`` user namelist with just the items you want to change. For simplicity we will just show the CLM namelist and NOT the entire file. In the sections below, for simplicity we will just show the user namelist (``user_nl_clm``) that will add (or modify existing) namelist items to the namelist. Example 1-2. Default CLM Namelist --------------------------------- @@ -141,7 +141,7 @@ The number of samples on each history file stream is given by the namelist varia A sample user namelist ``user_nl_clm`` turning on four extra file streams for output: daily, six-hourly, hourly, and every time-step, leaving the primary history files as monthly, and changing the number of samples on the streams to: yearly (12), thirty, weekly (28), daily (24), and daily (48) is: Example: user_nl_clm namelist adding auxiliary history files and changing output frequency ------------------------------------------------------------------------------------------------------- +------------------------------------------------------------------------------------------ :: hist_fincl2 = 'TG', 'TV' @@ -242,8 +242,6 @@ Example: user_nl_clm namelist outputting some files in 1D Vector format .. note:: Technically the default for hist_nhtfrq is for primary files output monthly and the other auxiliary tapes for daily, so we don't actually have to include hist_nhtfrq, we could use the default for it. Here we specify it for clarity. -.. caution:: LAND and COLS are also options to the pertape averaging, but currently there is a bug with them and they fail to work. - Visualizing global 1D vector files will take effort. You'll probably want to do some post-processing and possibly just extract out single points of interest to see what is going on. Since, the output is a 1D vector, of only land-points traditional plots won't be helpful. diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst index 4140dad87a..dcc7fa3cbb 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-datm-namelist.rst @@ -11,7 +11,7 @@ When running "I" compsets with CLM you use the DATM model to give atmospheric fo 1. **DATM Main Namelist and Stream Namlist gorup** (``datm_in``) 2. **DATM stream files** -The `Data Model Documentation `_ gives the details of all the options for the data models and for DATM specifically. +The `Data Model Documentation `_ gives the details of all the options for the data models and for DATM specifically. It goes into detail on all namelist items both for DATM and for DATM streams. So here we won't list ALL of the DATM namelist options, nor go into great details about stream files. But, we will talk about a few of the different options that are relevant for running with CLM. @@ -51,10 +51,20 @@ tintalgo In the sections below we go over each of the relevant ``DATM_MODE`` options and what the above DATM settings are for each. This gives you examples of actual usage for the settings. We also describe in what ways you might want to customize them for your own case. -------------------------------------- -CLMCRUNCEP mode and it's DATM settings +CLMGSWP3v1 mode and it's DATM settings -------------------------------------- -In ``CLMCRUNCEP`` mode the CRUNCEP dataset is used and all of it's data is on a 6-hourly interval. +In ``CLMGSWP3v1`` mode the GSWP3 NCEP forcing dataset is used and all of it's data is on a 3-hourly interval. +Like ``CLM_QIAN`` the dataset is divided into those three data streams: solar, precipitation, and everything else (temperature, pressure, humidity, Long-Wave down and wind). +The time-stamps of the data were also adjusted so that they are the beginning of the interval for solar, and the middle for the other two. +Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is: ``coszen``, ``nearest``, and ``linear`` for the solar, precipitation and other data respectively. +``taxmode`` is set to ``cycle`` and ``mapalgo`` is set to ``bilinear`` so that the data is spatially interpolated from the input exact half degree grid to the grid the atmosphere model is being run at (to run at this same model resolution use the 360x720cru_360x720cru resolution). + +---------------------------------------- +CLMCRUNCEPv7 mode and it's DATM settings +---------------------------------------- + +In ``CLMCRUNCEPv7`` mode the CRUNCEP dataset is used and all of it's data is on a 6-hourly interval. Like ``CLM_QIAN`` the dataset is divided into those three data streams: solar, precipitation, and everything else (temperature, pressure, humidity and wind). The time-stamps of the data were also adjusted so that they are the beginning of the interval for solar, and the middle for the other two. Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is: ``coszen``, ``nearest``, and ``linear`` for the solar, precipitation and other data respectively. @@ -64,6 +74,12 @@ Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is: ``cosze For more information on CRUNCEP forcing see `http://dods.extra.cea.fr/data/p529viov/cruncep/ `_. +-------------------------------------- +CLMCRUNCEP mode and it's DATM settings +-------------------------------------- + +``CLMCRUNCEP`` is similar to the ``CLMCRUNCEPv7`` mode above, except it uses Version 4 of the CRUNCEP data rather than version 7. + ------------------------------------ CLM_QIAN mode and it's DATM settings ------------------------------------ @@ -92,11 +108,11 @@ Because, of this the ``offset`` is set to zero, and the ``tintalgo`` is set to ` If you are using your own data for this mode and it's not at least hourly you'll want to adjust the DATM settings for it. If the data is three or six hourly, you'll need to divide it up into separate streams like in ``CLM_QIAN`` mode which will require fairly extensive changes to the DATM namelist and streams files. For an example of doing this see `Example 5-8 `_. ----------------------------------------- -CPLHIST3HrWx mode and it's DATM settings ----------------------------------------- +------------------------------------------ +CPLHISTForcing mode and it's DATM settings +------------------------------------------ -In ``CPLHIST3HrWx`` mode the model is assumed to have 3-hourly for a global grid from a previous CESM simulation. +In ``CPLHISTForcing`` mode the model is assumed to have 3-hourly for a global grid from a previous CESM simulation. Like ``CLM_QIAN`` mode the data is divided into three streams: one for precipitation, one for solar, and one for everything else. The time-stamps for Coupler history files for CESM is at the end of the interval, so the ``offset`` needs to be set in order to adjust the time-stamps to what it needs to be for the ``tintalgo`` settings. For precipitation ``taxmode`` is set to ``nearest`` so the ``offset`` is set to ``-5400`` seconds so that the ending time-step is adjusted by an hour and half to the middle of the interval. From 6e59daa67289608b4595c59c7e5e2ccfc16e289d Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Wed, 20 Jun 2018 15:23:57 -0600 Subject: [PATCH 175/255] Work on the tools chapter --- .../building-the-clm-tools.rst | 42 +++++++++---------- .../users_guide/using-clm-tools/cprnc.rst | 5 +-- .../using-clm-tools/creating-domain-files.rst | 6 +-- ...g-input-for-surface-dataset-generation.rst | 10 +---- .../creating-surface-datasets.rst | 20 +-------- .../what-are-the-clm-tools.rst | 31 +++++++------- 6 files changed, 43 insertions(+), 71 deletions(-) diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst index 1dd1129b6c..1b64786d99 100644 --- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -4,24 +4,24 @@ .. include:: ../substitutions.rst -The FORTRAN tools all have similar makefiles, and similar options for building. -All of the Makefiles use GNU Make extensions and thus require that you use GNU make to use them. +The CLM FORTRAN tools all have similar makefiles, and similar options for building. The tools +**cprnc** and **gen_domain** use the CIME configure/build system which is described in the next section. + +The Makefiles (for **mksurfdata_map** and **mkprocdata_map**) use GNU Make extensions and thus require that you use GNU make to use them. They also auto detect the type of platform you are on, using "uname -s" and set the compiler, compiler flags and such accordingly. There are also environment variables that can be set to set things that must be customized. All the tools use NetCDF and hence require the path to the NetCDF libraries and include files. On some platforms (such as Linux) multiple compilers can be used, and hence there are env variables that can be set to change the FORTRAN and/or "C" compilers used. -The tools other than cprnc also allow finer control, by also allowing the user to add compiler flags they choose, for both FORTRAN and "C", as well as picking the compiler, linker and and add linker options. -Finally the tools other than **cprnc** allow you to turn optimization on (which is off by default but on for the **mksurfdata_map** and **interpinic** programs) with the OPT flag so that the tool will run faster. -To get even faster performance, the **interpinic**, program allows you to also use the SMP to turn on multiple shared memory processors. -When ``SMP=TRUE`` you set the number of threads used by the program with the ``OMP_NUM_THREADS`` environment variable. +The tools also allow finer control, by also allowing the user to add compiler flags they choose, for both FORTRAN and "C", as well as picking the compiler, linker and and add linker options. +Finally the tools allow you to turn optimization on (which is off by default but on for **mksurfdata_map**) with the OPT flag so that the tool will run faster. -Options used by all: **cprnc**, **interpinic**, and **mksurfdata_map** +Options used by all: **mksurfdata_map** - ``LIB_NETCDF`` -- sets the location of the NetCDF library. - ``INC_NETCDF`` -- sets the location of the NetCDF include files. - ``USER_FC`` -- sets the name of the FORTRAN compiler. -Options used by: **interpinic**, **mkprocdata_map**, **mkmapgrids**, and **mksurfdata_map** +Options used by: **mkprocdata_map**, and **mksurfdata_map** - ``MOD_NETCDF`` -- sets the location of the NetCDF FORTRAN module. - ``USER_LINKER`` -- sets the name of the linker to use. @@ -38,11 +38,6 @@ Options used by: **interpinic**, **mkprocdata_map**, **mkmapgrids**, and **mksur - ``mkDepends`` -- figure out dependencies between source files, so make can compile in order.. - ``Makefile.common`` -- General tool Makefile that should be the same between all tools. -Options used only by **cprnc**: - -- ``EXEDIR`` -- sets the location where the executable will be built. -- ``VPATH`` -- colon delimited path list to find the source files. - More details on each environment variable. ``LIB_NETCDF`` @@ -81,7 +76,7 @@ More details on each environment variable. .. warning:: Note, that depending on the compiler answers may be different when SMP is activated. ``OPT`` - This variable flags if compiler optimization should be used when compiling the tool. It can be set to either ``TRUE`` or ``FALSE``, by default it is set to ``FALSE`` for **mkmapgrids** and ``TRUE`` for **mksurfdata_map**, **mkprocdata_map** and **interpinic**. Turning this on should make the tool run much faster. + This variable flags if compiler optimization should be used when compiling the tool. It can be set to either ``TRUE`` or ``FALSE``, by default it is set to for both **mksurfdata_map** and **mkprocdata_map**. Turning this on should make the tool run much faster. .. warning:: Note, you should expect that answers will be different when ``OPT`` is activated. @@ -100,15 +95,20 @@ More details on each environment variable. ``mkDepends`` The ``mkDepends`` is the copy of the perl script used by the ``Makefile.common`` to figure out the dependencies between the source files so that it can compile in the necessary order. This file should be identical between the different tools. -``EXEDIR`` - The cprnc tool uses this variable to set the location of where the executable will be built. The default is the current directory. - -``VPATH`` - The **cprnc** tool uses this variable to set the colon delimited pathnames of where the source code exists. The default is the current directory. - -.. note:: There are several files that are copies of the original files from either models``/lnd/clm/src/util_share``, ``models/csm_share/shr``, or copies from other tool directories. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well. +.. note:: There are several files that are copies of the original files. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well. The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here. .. include:: ../../clm5.0/tools/README.filecopies :literal: + +================================================================ + Building the CLM tools that use the CIME configure/build system +================================================================ + +**cprnc** and *gen_domain** both use the CIME configure/build system rather than the CLM specific version described above. + +See `CIME documentation on adding grids `_ for +more information on adding grids, creating mapping files, and running **gen_domain**. Also see the CIME file: +``$CTSMROOT/tools/mapping/gen_domain_files/INSTALL`` for how to build **gen_domain**. + diff --git a/doc/source/users_guide/using-clm-tools/cprnc.rst b/doc/source/users_guide/using-clm-tools/cprnc.rst index de90f7a88e..050e059296 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.rst +++ b/doc/source/users_guide/using-clm-tools/cprnc.rst @@ -6,8 +6,8 @@ Comparing History Files ========================= -**cprnc** is a tool shared by both CAM and CLM to compare two NetCDF history files. -It differences every field that has a time-axis that is also shared on both files, and reports a summary of the difference. +**cprnc** is a tool shared by |cesmrelease| to compare two NetCDF history files. +It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. @@ -28,4 +28,3 @@ Options: See the **cprnc** `README `_ file for more details. -.. note:: To compare files with OUT a time axis you can use the **cprnc.ncl** NCL script in ``$CTSMROOT/tools/ncl_scripts``. It won't give you the details on the differences but will report if the files are identical or different. diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst index d72427d3d5..c804a7bea7 100644 --- a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -6,8 +6,8 @@ Creating CLM domain files ***************************** -*gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH DATM AND CLM to define the grid and land-mask. The general data flow is shown in two figures. `Figure 2-4 `_ shows the general flow for a general global case (or for a regional grid that DOES include ocean). `Figure 2-5 `_ shows the use of **mknoocnmap.pl** (see `the Section called Using mknocnmap.pl to create grid and maps for single-point regional grids `_) to create a regional or single-point map file that is then run through **gen_domain** to create the domain file for it. As stated before `Figure 2-2 `_ is the legend for both of these figures. See `the -tools/mapping/gen_domain_files/README `_ file for more help on **gen_domain**. +*gen_domain* to create a domain file for datm from a mapping file. **gen_domain** is a tool that is a part of CIME. The domain file is then used by BOTH DATM AND CLM to define the grid and land-mask. The general data flow is shown in two figures. `Figure 2-4 `_ shows the general flow for a general global case (or for a regional grid that DOES include ocean). `Figure 2-5 `_ shows the use of **mknoocnmap.pl** (see `the Section called Using mknocnmap.pl to create grid and maps for single-point regional grids `_) to create a regional or single-point map file that is then run through **gen_domain** to create the domain file for it. As stated before `Figure 2-2 `_ is the legend for both of these figures. See `the +$CIMEROOT/tools/mapping/gen_domain_files/README `_ file for more help on **gen_domain**. Here we create domain files for a regular global domain. @@ -16,7 +16,7 @@ Figure 2-4. Global Domain file creation Insert figure 2-4 -Starting from SCRIP grid files for both your atmosphere and ocean, you use **tools/mapping/gen_mapping_files/gen_cesm_maps.sh** to create a mapping file between the atmosphere and ocean. That mapping file is then used as input to **gen_domain** to create output domain files for both atmosphere and ocean. The atmosphere domain file is then used by both CLM and DATM for I compsets, while the ocean domain file is ignored. For this process you have to define your SCRIP grid files on your own. For a regional or single-point case that doesn't include ocean see `Figure 2-5 `_. (See `Figure 2-2 `_ for the legend for this figure.) +Starting from SCRIP grid files for both your atmosphere and ocean, you use **$CIMEROOT/tools/mapping/gen_mapping_files/gen_cesm_maps.sh** to create a mapping file between the atmosphere and ocean. That mapping file is then used as input to **gen_domain** to create output domain files for both atmosphere and ocean. The atmosphere domain file is then used by both CLM and DATM for I compsets, while the ocean domain file is ignored. For this process you have to define your SCRIP grid files on your own. For a regional or single-point case that doesn't include ocean see `Figure 2-5 `_. (See `Figure 2-2 `_ for the legend for this figure.) Note, that the SCRIP grid file used to start this process, is also used in **mkmapdata.sh** (see `the Section called Creating mapping files that mksurfdata_map will use `_). Next we create domain files for a single-point or regional domain. diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index dcfcbbbdff..c044c283af 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -12,7 +12,7 @@ Creating input for surface dataset generation The utility ``mkmapdata.sh`` requires SCRIP format input files to describe the input and output grids that maps are generated for. CLM provides a utility, ``mkmapgrids`` that generates those files. The program converts old formats of CAM or CLM grid files to SCRIP grid format. There is also a NCL script (``mkscripgrid.ncl``) to create regular latitude longitude regional or single-point grids at the resolution the user desires. -SCRIP grid files for all the standard model resolutions and the raw surface datasets have already been done and the files are in the XML database. Hence, this step doesn't need to be done -- EXCEPT WHEN YOU ARE CREATING YOUR OWN GRIDS. If you have a CLM grid or CAM file from previous versions and you want to convert it you can use **mkmapgrids**. +SCRIP grid files for all the standard model resolutions and the raw surface datasets have already been done and the files are in the XML database. Hence, this step doesn't need to be done -- EXCEPT WHEN YOU ARE CREATING YOUR OWN GRIDS. Using mknocnmap.pl to create grid and maps for single-point regional grids -------------------------------------------------------------------------- @@ -47,11 +47,10 @@ See `Figure 2-5 `_ for a visual representation of this process. The bash shell script ``$CTSMROOT/tools/mkmapgrids/mkmapdata.sh`` uses **ESMF_RegridWeightGen** to create a list of maps from the raw datasets that are input to **mksurfdata_map**. Each dataset that has a different grid, or land-mask needs a different mapping file for it, but many different raw datasets share the same grid/land-mask as other files. -Hence, there doesn't need to be a different mapping file for EACH raw dataset -- just for each DIFFERENT raw dataset. +Hence, there doesn't need to be a different mapping file for EACH raw dataset -- just for each raw dataset that has a DIFFERENT grid or land-mask.. See `Figure 2-3 `_ for a visual representation of how this works. The bash script figures out which mapping files it needs to create and then runs **ESMF_RegridWeightGen** for each one. You can then either enter the datasets into the XML database (see `Chapter 3 `_ or leave the files in place, and use the "-res usrspec -usr_gname -usr_gdate" options to **mksurfdata_map** (see `the Section called Running mksurfdata.pl `_ below). -Use the "-phys" option to specify if you are creating mapping files for clm4_0 or |version| (the list of raw datafiles is somewhat different between the two). mkmapdata.sh has a help option with the following :: @@ -75,9 +74,6 @@ mkmapdata.sh has a help option with the following [-t|--gridtype ] Model output grid type supported values are [regional,global], (default is global) - [-p|--phys ] - Whether to generate mapping files for clm4_0 or |version| - supported values are [clm4_0,|version|], (default is |version|) [-b|--batch] Toggles batch mode usage. If you want to run in batch mode @@ -109,8 +105,6 @@ mkmapdata.sh has a help option with the following ********************** -.. warning:: Make sure you specify with the "-phys" option if you are creating files for CLM4.0! The default is |version|. - Figure 2-3. Details of running mkmapdata.sh ------------------------------------------- Insert figure 2-3 diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index f2cb8eed4d..c5a5644034 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -41,25 +41,7 @@ Creating a Complete Set of Files for Input to CLM Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or |version| for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this. -5. Create some sort of initial condition dataset - - You then need to do one of the following three options to have an initial dataset to start from. - - a. Use spinup-procedures to create initial condition datasets - - The first option is to do the spinup procedures from arbitrary initial conditions to get good initial datasets. This is the most robust method to use. See the Section called Spinning up the Satellite Phenology Model (CLMSP spinup) in Chapter 4, the Section called Spinning up the CLM4.0 biogeochemistry Carbon-Nitrogen Model (CN spinup) in Chapter 4, or the Section called Spinning up the CLM4.0 Carbon-Nitrogen Dynamic Global Vegetation Model (CNDV spinup) in Chapter 4 for more information on this. - - b. Use interpinic to interpolate existing initial condition datasets - - The next option is to interpolate from spunup datasets at a different resolution, using interpinic. There is a version for either clm4_0 or |version| for this program. See the Section called Using interpinic to interpolate initial conditions to different resolutions for more information on this. - - c. Start up from arbitrary initial conditions - - The last alternative is to run from arbitrary initial conditions without using any spun-up datasets. This is inappropriate when using |version|-BGC or CLMCN (bgc=cn or cndv) as it takes a long time to spinup Carbon pools. - -.. warning:: This is NOT recommended as many fields in CLM take a long time to equilibrate. - -6. Enter the new datasets into the build-namelist XML database +5. Enter the new datasets into the build-namelist XML database The last optional thing to do is to enter the new datasets into the build-namelist XML database. See Chapter 3 for more information on doing this. This is optional because the user may enter these files into their namelists manually. The advantage of entering them into the database is so that they automatically come up when you create new cases. The ``$CTSMROOT/tools/README`` goes through the complete process for creating input files needed to run CLM. We repeat that file here: diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst index 3c67965e73..a8663176e1 100644 --- a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst @@ -8,35 +8,33 @@ There are several tools provided with CLM that allow you to create your own input datasets at resolutions you choose, or to interpolate initial conditions to a different resolution, or used to compare CLM history files between different cases. The tools are all available in the ``$CTSMROOT/tools`` directory. -Most of the tools are FORTRAN stand-alone programs in their own directory, but there is also a suite of NCL scripts in the ``./ncl_scripts`` directory, and some of the tools are scripts that may also call the ESMF regridding program. +Most of the tools are FORTRAN stand-alone programs in their own directory, but there is also a suite of NCL scripts in the ``$CTSMROOT/tools//ncl_scripts`` directory, and some of the tools are scripts that may also call the ESMF regridding program. Some of the NCL scripts are very specialized and not meant for general use, and we won't document them here. They still contain documentation in the script itself and the README file in the tools directory. -The tools are divided into three directories for three categories: clm4_0, |version|, and shared. -The first two are of course for tools that are designed to work with either the CLM4.0 or |version| versions of the model. -The last one are shared utilities that can be used by either, or have a "-phys" option so you can specify which version you want to use. +The tools produce files that can be used for CLM4.5 and |version|. They do **NOT** produce files that can be used for CLM4.0. +If you need files for CLM4.0, you'll need to use a previous version of CLM. The list of generally important scripts and programs are as follows. -1. *tools/cprnc* (relative to top level directory) to compare NetCDF files with a time axis. - -#. *./mkmapgrids* to create SCRIP grid data files from old CLM format grid files that can then be used to create new CLM datasets (deprecated). There is also a NCL script (``./mkmapgrids/mkscripgrid.ncl`` to create SCRIP grid files for regular latitude/longitude grids. +1. *./mkmapgrids* to create SCRIP grid data files from old CLM format grid files that can then be used to create new CLM datasets (deprecated). There is also a NCL script (``./mkmapgrids/mkscripgrid.ncl`` to create SCRIP grid files for regular latitude/longitude grids. #. *./mkmapdata* to create SCRIP mapping data file from SCRIP grid files (uses ESMF). -#. *./gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. - #. *mksurfdata_map* to create surface datasets from grid datasets (clm4_0 and |version| versions). #. *./mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or |version|. +#. *$CIMEROOT/tools/mapping/gen_domain_files/gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. + +#. *$CIMEROOT/tools/cprnc* to compare two NetCDF files. + In the sections to come we will go into detailed description of how to use each of these tools in turn. First, however we will discuss the common environment variables and options that are used by all of the FORTRAN tools. Second, we go over the outline of the entire file creation process for all input files needed by CLM for a new resolution, then we turn to each tool. In the last section we will discuss how to customize files for particular observational sites. -The tools run either one of two ways, with a namelist to provide options, or with command line arguments (and NOT both). -**gen_domain** and **cprnc** run with command line arguments, and the other tools run with namelists. +The FORTRAN tools (mksurfdata_map and mkprocdata_map) run, with a namelist (mksurfdata_map) to provide options, or with command line arguments (mkprocdata_map). In the following sections, we will outline how to make these files available for build-namelist so that you can easily create simulations that include them. In the chapter on single-point and regional datasets we also give an alternative way to enter new datasets without having to edit files. @@ -45,15 +43,14 @@ In the chapter on single-point and regional datasets we also give an alternative Running FORTRAN tools with namelists ------------------------------------ -**mksurfdata_map** and **mkmapgrids** run with namelists that are read from standard input. +**mksurfdata_map** runs with a namelist that is read from standard input. Hence, you create a namelist and then run them by redirecting the namelist file into standard input as follows: :: ./program < namelist -For programs with namelists there is at least one sample namelist with the name "program".namelist (i.e. -``mksurfdata_map.namelist`` for the **mksurfdata_map** program). -There may also be other sample namelists that end in a different name besides "namelist". +There is a sample namelist called ``$CTSMROOT/tools/mksurfdata_map/mksurfdata_map.namleist`` that shows you what the +namelist should look like. **mksurfdata_map** also has a script that creates the namelist and runs the program for you. Namelists that you create should be similar to the example namelist. The namelist values are also documented along with the other namelists in the: :: @@ -66,7 +63,7 @@ The namelist values are also documented along with the other namelists in the: Running FORTRAN tools with command line options ----------------------------------------------- -**gen_domain**, and **cprnc** run with command line arguments. +**gen_domain**, mkprocdata_map, and **cprnc** run with command line arguments. The detailed sections below will give you more information on the command line arguments specific to each tool. Also running the tool without any arguments will give you a general synopsis on how to run the tool. @@ -77,7 +74,7 @@ Running FORTRAN tools built with SMP=TRUE When you enable ``SMP=TRUE`` on your build of one of the tools that make use of it, you are using OpenMP for shared memory parallelism (SMP). In SMP loops are run in parallel with different threads run on different processors all of which access the same memory (called on-node). Thus you can only usefully run up to the number of processors that are available on a single-node of the machine you are running on. -For example, on the NCAR machine cheyenne there are 16 processors per node, but the SMT hardware on the machine allows you to submit twice as many threads or 32 threads. +For example, on the NCAR machine cheyenne there are 36 processors per node, so you can use up to 36 processors. --------- From efb91653f886d26b947b3246ef293153f556a857 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Wed, 20 Jun 2018 20:06:11 -0600 Subject: [PATCH 176/255] Add a note about a subtle interaction This refers to https://github.com/ESCOMP/ctsm/issues/423 --- .../tech_note/Glacier/CLM50_Tech_Note_Glacier.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst index 9f6c79ff98..52313b9a5c 100644 --- a/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst +++ b/doc/source/tech_note/Glacier/CLM50_Tech_Note_Glacier.rst @@ -222,6 +222,16 @@ runaway sea ice growth in that region. | | | place | | +---------------+---------------+---------------+---------------+ +.. note:: + + In regions that have both the ``Glacial melt = Replaced by ice`` and the ``Ice runoff = + Melted`` behaviors (by default, this is just the region inside the standard CISM grid + but outside Greenland itself): During periods of glacial melt, a negative ice runoff is + generated (due to the ``Glacial melt = Replaced by ice`` behavior); this negative ice + runoff is converted to a negative liquid runoff plus a positive sensible heat flux (due + to the ``Ice runoff = Melted`` behavior). We recommend that you limit the portion of + the globe with both of these behaviors combined, in order to avoid having too large of + an impact of this non-physical behavior. .. _Multiple elevation class scheme: From ccc98566fb9463625cfe79d17df99d3cae3c644d Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Wed, 20 Jun 2018 23:11:43 -0600 Subject: [PATCH 177/255] Work on adding-new-resolutions chapter and exclude cime directories --- doc/source/conf.py | 5 +- doc/source/tech_note/conf.py | 4 +- ...w-Files-to-the-build-namelist-Database.rst | 6 +- .../CLM-3.1-Managing-Your-Own-Data-files.rst | 75 ------------------- .../CLM-3.2-Adding-Resolution-Names.rst | 17 +---- ...3-Adding-or-Changing-Default-Filenames.rst | 12 +-- .../adding-new-resolutions/index.rst | 1 - doc/source/users_guide/conf.py | 7 ++ 8 files changed, 20 insertions(+), 107 deletions(-) delete mode 100644 doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 9a112db91b..27c0df6e3c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -74,9 +74,8 @@ # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = [ - "clm5.0/manage_externals", - "**/README_EXTERNALS.rst", - "clm5.0/README.rst" + "clm5.0", + "**/README_EXTERNALS.rst" ] # The name of the Pygments (syntax highlighting) style to use. diff --git a/doc/source/tech_note/conf.py b/doc/source/tech_note/conf.py index a1827c71c5..69d97bf9eb 100644 --- a/doc/source/tech_note/conf.py +++ b/doc/source/tech_note/conf.py @@ -74,9 +74,7 @@ # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = [ - "manage_externals/*", - "README_EXTERNALS.rst", - "clm5.0//README.rs" + "clm5.0/*" ] # The name of the Pygments (syntax highlighting) style to use. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst index 76d8a7aef1..a828c37e98 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst @@ -16,11 +16,11 @@ If you have a LOT of files to keep track of it also might be easier than keeping If you just have a few quick experiments to try, for a short time period you might be best off using the other methods mentioned above. There are two parts to adding files to the build-namelist database. -The first part is adding new resolution names which is done in the ``$CTSMROOT/bld/namelist_files/namelist_definition_|version|.xml`` file (and in the ``$CTSMROOT/bld/config_files/config_definition.xml`` file when adding supported single-point datasets). +The first part is adding new resolution names which is done in the ``$CTSMROOT/bld/namelist_files/namelist_definition_clm4_5.xml`` file. You can then use the new resolution by using ``CLM_USRDAT_NAME``. -If you also want to be able to give the resolution into **create_newcase** -- you'll need to add the grid to the ``scripts/ccsm_utils/Case.template/config_grid.xml`` file. +If you also want to be able to give the resolution into **create_newcase** -- you'll need to add the grid to the ``$CIMEROOT/config/cesm/config_grid.xml`` file. -The second part is actually adding the new filenames which is done in the ``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|.xml`` file (``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|_tools.xml`` file for CLM tools). +The second part is actually adding the new filenames which is done in the ``$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_5.xml`` file (``$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_5_tools.xml`` file for CLM tools). If you aren't adding any new resolutions, and you are just changing the files for existing resolutions, you don't need to edit the namelist_definition file. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst deleted file mode 100644 index 41ccdde35b..0000000000 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.1-Managing-Your-Own-Data-files.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _managing-your-data-files: - -.. include:: ../substitutions.rst - -============================== - Managing Your Data Own Files -============================== - -If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. - -Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. - -``` -> cd scripts -# First make sure you have a inputdata location that you can write to -# You only need to do this step once, so you won't need to do this in the future -# (except to bring in any updated files in the original $CSMDATA location). -> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data -> ./link_dirtree $CSMDATA $MYCSMDATA -``` - -Then when you create a case you will change ``DIN_LOC_ROOT_CSMDATA`` to point to the location you linked to rather than the default location. - -``> ./xmlchange DIN_LOC_ROOT_CSMDATA=$MYCSMDATA`` - -In order to list the files that you have created you merely need to use the UNIX command find to find the files that are NOT softlinks. So for example executing the following command: - -``> find $MYCSMDATA -type f -print`` - -for me gives the following truncated list of CLM_USRDAT_NAME files that I have created. - -``` -/glade/p/work/erik/inputdata/lnd/clm2/pftdata/pft-physiology.c130503.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-01.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-02.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-03.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-04.nc -``` - -You can also use **find** to list files that have a particular pattern in the name as well (using the -name option with wildcards). Also you can always rerun the **link_dirtree** command if any new files are added that you need to be linked into your directory tree. Since, the files are soft-links -- it doesn't take up much space other than the files that you add there. This way all of the files are kept in one place, they are organized by usage according to CESM standards, and you can easily find your own files, and CLM can find them as well. - - - -If you are running on a supported machine (such as cheyenne or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use ``CLM_USRDAT_NAME`` you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the **link_dirtree** tool in the CESM scripts. Some information on **link_dirtree** is available in the `|cesmrelease| Scripts User's Guide `_. We also have some examples of it's use here and in other sections of this User's Guide. - -Using **link_dirtree** is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data. - -``` -> cd scripts -# First make sure you have a inputdata location that you can write to -# You only need to do this step once, so you won't need to do this in the future -# (except to bring in any updated files in the original $CSMDATA location). -> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data -> ./link_dirtree $CSMDATA $MYCSMDATA -``` - -Then when you create a case you will change ``DIN_LOC_ROOT_CSMDATA`` to point to the location you linked to rather than the default location. - -``> ./xmlchange DIN_LOC_ROOT_CSMDATA=$MYCSMDATA`` - -In order to list the files that you have created you merely need to use the UNIX command find to find the files that are NOT softlinks. So for example executing the following command: - -``> find $MYCSMDATA -type f -print`` - -for me gives the following truncated list of CLM_USRDAT_NAME files that I have created. - -``` -/glade/p/work/erik/inputdata/lnd/clm2/pftdata/pft-physiology.c130503.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-01.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-02.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-03.nc -/glade/p/work/erik/inputdata/atm/datm7/CLM1PT_data/1x1pt_BE-Vie/1997-04.nc -``` - -You can also use **find** to list files that have a particular pattern in the name as well (using the -name option with wildcards). Also you can always rerun the **link_dirtree** command if any new files are added that you need to be linked into your directory tree. Since, the files are soft-links -- it doesn't take up much space other than the files that you add there. This way all of the files are kept in one place, they are organized by usage according to CESM standards, and you can easily find your own files, and CLM can find them as well. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst index aa8265e8a9..1bc7810021 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst @@ -7,7 +7,7 @@ ========================= If you are adding files for new resolutions which aren't covered in the namelist_definition file -- you'll need to add them in. -The list of valid resolutions is in the id="res" entry in the ``$CTSMROOT/bld/namelist_files/namelist_definition_|version|.xml`` file. +The list of valid resolutions is in the id="res" entry in the ``$CTSMROOT/bld/namelist_files/namelist_definition_clm4_5.xml`` file. You need to choose a name for your new resolution and simply add it to the comma delimited list of valid_values for the id="res" entry. The convention for global Gaussian grids is number_of_latitudes x number_of_longitudes. The convention for global finite volume grids is latitude_grid_size x longitude_grid_size where latitude and longitude is measured in degrees. @@ -30,18 +30,3 @@ The only hard requirement is that names be unique for different grid files. Here As you can see you just add your new resolution names to the end of the valid_values list. - -When using PTCLM and adding supported single-point resolutions, you'll also want to add these resolutions to the ``$CTSMROOT/bld/config_files/config_definition.xml`` under the ``sitespf_pt`` name. -The entry in that file looks like: -:: - - - Flag to turn on site specific special configuration flags for supported single - point resolutions. See the specific config_defaults_*.xml file for the special - settings that are set for a particular site. - - -PTCLM assumes that any supported single-point resolutions are valid settings for ``sitespf_pt``. diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst index 52344bd5a0..cc360fba47 100644 --- a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst +++ b/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst @@ -6,22 +6,22 @@ Changing Default Filenames ============================ -To add or change the default filenames you edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|.xml`` and either change an existing filename or add a new one. +To add or change the default filenames you edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_5.xml`` and either change an existing filename or add a new one. Most entries in the default namelist files, include different attributes that describe the different properties that describe the differences in the datasets. Attributes include the: resolution, year to simulation, range of years to simulate for transient datafiles, the land-mask, the representative concentration pathway (rcp) for future scenarios, and the type of biogeochemistry (bgc) model used. -For example the fatmgrid for the 1.9x2.5 resolution is as follows: +For example the fsurdat for the 1.9x2.5 resolution is as follows: ``` - -lnd/clm2/surfdata_map/surfdata_0.9x1.25_simyr1850_c130415.nc + +lnd/clm2/surfdata_map/surfdata_0.9x1.25_78pfts_CMIP6_simyr1850_c170824.nc ``` -Other ``fsurdat`` files are distinguished from this one by their resolution (hgrid), simulation year (sim_year) and prognostic crop (crop) attributes. +Other ``fsurdat`` files are distinguished from this one by their resolution (hgrid), simulation year (sim_year) and prognostic crop (use_crop) attributes. To add or change the default filenames for CLM tools edit the ``$CTSMROOT/bld/namelist_files/namelist_defaults_|version|_tools.xml`` and either change an existing filename or add a new one. -Editing this file is similar to the ``namelist_defaults_|version|.xml`` talked about above. +Editing this file is similar to the ``namelist_defaults_clm4_5.xml`` talked about above. ---------------------------- diff --git a/doc/source/users_guide/adding-new-resolutions/index.rst b/doc/source/users_guide/adding-new-resolutions/index.rst index fded236989..97d97b0cc0 100644 --- a/doc/source/users_guide/adding-new-resolutions/index.rst +++ b/doc/source/users_guide/adding-new-resolutions/index.rst @@ -15,6 +15,5 @@ Adding New Resolutions :maxdepth: 2 CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst - CLM-3.1-Managing-Your-Own-Data-files.rst CLM-3.2-Adding-Resolution-Names.rst CLM-3.3-Adding-or-Changing-Default-Filenames.rst diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index b8e187efd5..687732893a 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -78,6 +78,13 @@ # This patterns also effect to html_static_path and html_extra_path exclude_patterns = [ "clm5.0/manage_externals", + "clm5.0/components", + "clm5.0/cime/scripts", + "clm5.0/cime/doc", + "clm5.0/cime/config", + "clm5.0/cime/tools/statistical_ensemble_test", + "clm5.0/cime/src", + "clm5.0/cime/utils", "**/README_EXTERNALS.rst", "clm5.0/README.rst" ] From 1013e1c7451d0503102b651d9f6a7f971756934d Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 21 Jun 2018 16:12:37 -0600 Subject: [PATCH 178/255] Update special cases chapter --- ...CLM5.0-biogeochemistry-(CLMBGC-spinup).rst | 34 +++---- ...tmospheric-forcing-to-spinup-the-model.rst | 10 +- ...tmospheric-forcing-to-spinup-the-model.rst | 26 +++-- ...transient-historical-CO2-concentration.rst | 97 +------------------ .../running-the-prognostic-crop-model.rst | 13 +-- .../running-with-irrigation.rst | 17 ++-- 6 files changed, 47 insertions(+), 150 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst index 99fa3fdd47..0bbeda8e41 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst @@ -1,15 +1,15 @@ -.. _spinning-up-clm45-bgc: +.. _spinning-up-clm50-bgc: .. include:: ../substitutions.rst -===================== - Spinup of CLM5.0-BGC -===================== +========================== + Spinup of CLM5.0-BGC-Crop +========================== To get the |version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). -**1. 45_AD_SPINUP** +**1. 50_AD_SPINUP** For the first step of running 1000+ years in "-bgc_spinup on" mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: Example:: AD_SPINUP Simulation for |version|-BGC @@ -17,23 +17,19 @@ Example:: AD_SPINUP Simulation for |version|-BGC :: > cd scripts - > ./create_newcase -case BGC_spinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru -mach cheyenne_intel + > ./create_newcase -case BGC_spinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru > cd BGC_spinup - # Append "-spinup on" to CLM_BLDNML_OPTS - > ./xmlchange CLM_BLDNML_OPTS="-bgc_spinup on" -append - # The following sets CLM_FORCE_COLDSTART to "on", and run-type to startup (you could also use an editor) - > ./xmlchange CLM_FORCE_COLDSTART=on,RUN_TYPE=startup - # Make the output history files only annual, by adding the following to the user_nl_clm namelist - > echo 'hist_nhtfrq = -8760' >> user_nl_clm + # Change accelerated spinup mode + > ./xmlchange CLM_ACCELERATED_SPINUP="on" # Now setup - > ./cesm_setup -case + > ./case.setup -case # Now build - > ./BGC_spinup.build + > ./case.build # The following sets RESUBMIT to 30 times in env_run.xml (you could also use an editor) # The following sets STOP_DATE,STOP_N and STOP_OPTION to Jan/1/1001, 20, "nyears" in env_run.xml (you could also use an editor) > ./xmlchange RESUBMIT=20,STOP_N=50,STOP_OPTION=nyears,STOP_DATE=10010101 # Now run normally - > ./BGC_spinup.submit + > ./case.submit .. note:: This same procedure works for |version|-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. @@ -47,7 +43,7 @@ Example: Final CLMBGC Spinup Simulation for |version|-BGC :: > cd scripts - > ./create_newcase -case BGC_finalspinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru -mach cheyenne_intel + > ./create_newcase -case BGC_finalspinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru > cd BGC_finalspinup # Now, Copy the last CLM restart file from the earlier case into your run directory > cp /ptmp/$LOGIN/archive/BGC_spinup/rest/BGC_spinup.clm*.r*.1002-01-01-00000.nc \ @@ -60,14 +56,14 @@ Example: Final CLMBGC Spinup Simulation for |version|-BGC # Set the finidat file to the last restart file saved in previous step > echo ' finidat = "BGC_spinup.clm2.r.1002-01-01-00000.nc"' > user_nl_clm # Now setup - > ./cesm_setup + > ./case.setup > Now build - > ./BGC_finalspinup.build + > ./case.build # The following sets RESUBMIT to 4 times in env_run.xml (you could also use an editor) # The following sets STOP_N and STOP_OPTION to 50 and "nyears" in env_run.xml (you could also use an editor) > ./xmlchange RESUBMIT=4,STOP_OPTION=nyears,STOP_N=50 > Now run as normal - > ./BGC_finalspinup.submit + > ./case.submit To assess if the model is spunup plot trends of CLMBGC variables of interest. If you see a trend, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst index deb5fa1238..12903a18b5 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst @@ -17,17 +17,15 @@ Example: Simulation with MOAR Data on cheyenne :: > cd scripts - > ./create_newcase -case MOARforce1850 -res f19_g17_gl4 -compset I1850Clm50BgcSpinup -mach cheyenne_intel + > ./create_newcase -case MOARforce1850 -res f19_g17_gl4 -compset I1850Clm50BgcSpinup > cd MOARforce1850 # The following sets the casename to point to for atm forcing (you could also use an editor) > ./xmlchange DATM_CPL_CASE=b40.1850.track1.1deg.006a # The following sets the align year and years to run over for atm forcing # (you could also use an editor) > ./xmlchange DATM_CPL_YR_ALIGN=1,DATM_CPL_YR_START=960,DATM_CPL_YR_END=1030 - > ./cesm_setup + > ./case.setup # Now build and run as normal - > ./MOARforce1850.build - > ./MOARforce1850.submit + > ./case.build + > ./case.submit - -.. warning: Because of bug 1339 (see the `$CTSMROOT/doc/KnownBugs `_ file on this) you can't run with 83 or more years of forcing. If you do need to run with more years of forcing, you'll need to address the issue as outlined in the `$CTSMROOT/doc/KnownBugs `_ file. diff --git a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst index 0999f7b366..34bb12ab49 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst @@ -16,9 +16,9 @@ Example: Fully Coupled Simulation to Create Data to Force Next Example Simulatio :: > cd scripts - > ./create_newcase -case myBCN1850 -res f09_g17_gl4 -compset B1850CN -mach cheyenne_intel - > cd myBCN1850 - > ./cesm_setup + > ./create_newcase -case myB1850 -res f09_g17_gl4 -compset B1850 + > cd myB1850 + > ./case.setup # Set histaux_a2x3hr to .true. in your user_nl_cpl output from the atmosphere model # will be saved 3 hourly echo "histaux_a2x3hr=.true." >> user_nl_cpl @@ -26,7 +26,7 @@ Example: Fully Coupled Simulation to Create Data to Force Next Example Simulatio > cp ../../models/drv/driver/ccsm_comp_mod.F90 SourceMods/src.cpl > $EDITOR SourceMods/src.cpl # Now build - > ./myBCN1850.build + > ./case.build # The following sets the archival disk space (you could also use an editor) > ./xmlchange DOUT_S_ROOT='/glade/home/$USER/$CASE' # Make sure files are archived to disk, but NOT to long term storage @@ -35,21 +35,19 @@ Example: Fully Coupled Simulation to Create Data to Force Next Example Simulatio # Set the run length to run a total of 20 years (you could also use an editor) > ./xmlchange RESUBMIT=9,STOP_OPTION=nyears,STOP_N=2 # Now run as normal - > ./myBCN1850.submit + > ./case.submit -.. warning:: Because of bug 1733 (see the `$CTSMROOT/doc/KnownBugs `_ file on this) you'll need to edit the driver code in order for it to produce the correct list of fields needed to run the model later. - -Now we run an I compset forced with the data from the previous simulation using the ``CPLHIST3HrWx`` option to DATM_MODE. See `the Section called CPLHIST3HrWx mode and it's DATM settings in Chapter 1 `_ for more information on the DATM settings for ``CPLHIST3HrWx`` mode. +Now we run an I compset forced with the data from the previous simulation using the CPLHISTForcing`` option to DATM_MODE. See `the Section called CPLHISTForcing mode and it's DATM settings in Chapter 1 `_ for more information on the DATM settings for ``CPLHISTForcing`` mode. Example: Simulation Forced with Data from the Previous Simulation ------------------------------------------------------------------------------ :: > cd scripts - > ./create_newcase -case frcwmyBCN1850 -res f09_g17_gl4 -compset I1850Clm50BgcSpinup -mach cheyenne_intel - > cd frcWmyBCN1850 + > ./create_newcase -case frcwmyB1850 -res f09_g17_gl4 -compset I1850Clm50BgcSpinup + > cd frcWmyB1850 # The following sets the casename to point to for atm forcing (you could also use an editor) - > ./xmlchange DATM_CPLHIST_CASE="myBCN1850" + > ./xmlchange DATM_CPLHIST_CASE="myB1850" # The following sets the align year and years to run over for atm forcing # (you could also use an editor) > ./xmlchange DATM_CPLHIST_YR_ALIGN="1",DATM_CPLHIST_YR_START=1,DATM_CPLHIST_YR_END=20 @@ -57,10 +55,10 @@ Example: Simulation Forced with Data from the Previous Simulation # file to the archival path of the case above in the form of: /glade/home/achive/$USER/$DATM_CPLHIST_CASE/cpl/hist # NOTE: THIS WILL CHANGE THE PATH FOR ALL I1850Clm50BgcSpinup COMPSET CASES MADE AFTER THIS! > $EDITOR ../../models/atm/datm/bld/namelist_files/namelist_defaults_datm.xml - > ./cesm_setup + > ./case.setup # Now build and run as normal - > ./frcwmyBCN1850.build - > ./frcwmyBCN1850.submit + > ./case.build + > ./case.submit .. note:: We did this by editing the "namelist_defaults_datm.xml" which will change the settings for ALL future ``I1850Clm50BgcSpinup`` cases you run. You could also do this by editing the path in the resulting streams text files in the CaseDocs directory, and then create a "user\_" streams file with the correct path. This would change the streams file JUST for this case. The steps do it this way are: diff --git a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst index b7d063a2a2..9883662a4b 100644 --- a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst +++ b/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst @@ -37,104 +37,17 @@ Example: Transient Simulation with Historical CO2 :: > cd scripts - > ./create_newcase -case DATM_CO2_TSERIES -res f19_g17_gl4 -compset I20TRCRUCLM45BGC + > ./create_newcase -case DATM_CO2_TSERIES -res f19_g17_gl4 -compset IHistClm50BgcCrop > cd DATM_CO2_TSERIES - # Set CCSM_BGC to CO2A so that CO2 will be passed from atmosphere to land - # Set CLM_CO2_TYPE to diagnostic so that the land will use the value sent from the atmosphere - > ./xmlchange CCSM_BGC=CO2A,CLM_CO2_TYPE=diagnostic + # Historical CO2 will already be setup correctly for this compset + # to check that look at the variables: CCSM_BGC,CLM_CO2_TYPE, and DATM_CO2_TSERIES + > ./xmlquery CCSM_BGC,CLM_CO2_TYPE,DATM_CO2_TSERIES + # Expect: CCSM_BGC=CO2A,CLM_CO2_TYPE=diagnostic,DATM_CO2_TSERIES=20tr > ./case.setup - # Create the streams file for CO2 - > cat << EOF >> datm.streams.txt.co2tseries - - - - This is a streams file to pass historical CO2 from datm8 to the other - surface models. It reads in a historical dataset derived from data used - by CAM. The getco2_historical.ncl script in $CTSMROOT2/tools/ncl_scripts - was used to convert the CAM file to a streams compatible format (adding domain - information and making CO2 have latitude/longitude even if only for a single - point. - - - - Input stream description file for historical CO2 reconstruction data - - 04 March 2010: Converted to form that can be used by datm8 by Erik Kluzek - 18 December 2009: Prepared by B. Eaton using data provided by - Jean-Francois Lamarque. All variables except f11 are directly from - PRE2005_MIDYR_CONC.DAT. Data from 1765 to 2007 with 2006/2007 just - a repeat of 2005. - - - CLMNCEP - - - - time time - lonc lon - latc lat - area area - mask mask - - - $CSMDATA/atm/datm7/CO2 - - - fco2_datm_1765-2007_c100614.nc - - - - - CO2 co2diag - - - $CSMDATA/atm/datm7/CO2 - - - fco2_datm_1765-2007_c100614.nc - - - - - - EOF - - # And copy it to the run directory - > cp datm.streams.txt.co2tseries $RUNDIR - # Run preview namelist so we have the namelist in CaseDocs > ./preview_namelists -The first thing we will do is to edit the ``user_nl_datm`` file to add a CO2 file stream in. -To do this we will copy a ``user_nl_datm`` in with the changes needed. The file ``addco2_user_nl_datm.user_nl`` is in ``$CTSMROOT/doc/UsersGuide`` and looks like this... -:: - - dtlimit = 1.5,1.5,1.5,1.5,1.5 - fillalgo = 'nn','nn','nn','nn','nn' - fillmask = 'nomask','nomask','nomask','nomask','nomask' - mapalgo = 'bilinear','bilinear','bilinear','bilinear','nn' - mapmask = 'nomask','nomask','nomask','nomask',nomask' - streams = "datm.streams.txt.CLM_QIAN.Solar 1895 1948 1972 ", "datm.streams.txt.CLM_QIAN.Precip 1895 1948 1972 ", - "datm.streams.txt.CLM_QIAN.TPQW 1895 1948 1972 ", "datm.streams.txt.presaero.trans_1850-2000 1849 1849 2006", - "datm.streams.txt.co2tseries 1766 1766 2005 " - taxmode = 'cycle','cycle','cycle','cycle','extend' - tintalgo = 'coszen','nearest','linear','linear','linear' - -You just copy this into your case directory. But, also compare it to the version in ``CaseDocs`` to make sure the changes are just to add in the new CO2 stream. Check to see that filenames, and start, end and align years are correct. -:: - - > cp ../../$CTSMROOT/doc/UsersGuide/addco2_user_nl_datm.user_nl user_nl_datm - > diff user_nl_datm CaseDocs/datm_atm_in - Once, you've done that you can build and run your case normally. -.. warning:: This procedure assumes you are using a ``I20TRCRUCLM45BGC`` compset out of the box, with ``DATM_PRESAERO`` equal to trans_1850-2000. So it assumes standard |version| CRUNCEP atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here your ``user_nl_datm`` file will need to be adjusted to work with it. - -.. note:: The intent of the ``user_nl_datm`` is to add an extra streams file for CO2 to the end of the streams variable, and other arrays associated with streams (adding mapalgo as a new array with bilinear for everything, but the CO2 file which should be "nn" for nearest neighbor). Other variables should be the same as the other stream values. - -.. warning:: The streams file above is hard-coded for the path of the file on NCAR computers. To use it on an outside machine you'll need to edit the filepath in the streams file to point to the location where you have the file. - -After going through these steps, you will have a case where you have datm reading in an extra streams text file that points to a data file with CO2 data on it that will send that data to the CLM. - diff --git a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst index 308c749adc..20ea12e91f 100644 --- a/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst +++ b/doc/source/users_guide/running-special-cases/running-the-prognostic-crop-model.rst @@ -6,9 +6,10 @@ Running the prognostic crop model =================================== -The prognostic crop model is setup to work with |version|-BGC or CLM4.0-CN (with or without DV) for present day conditions and we have surface and initial condition datasets at f19 resolution. +The prognostic crop model is setup to work with CLM4.0, CLM4.5 or |version| with either BGC or CN (with or without DV). In order to use the initial condition file, we need to set the ``RUN_TYPE`` to startup rather than ``hybrid`` since the compset for f19 sets up to use an initial condition file without crop active. -To activate the crop model you can choose a compset that has "CROP" in the name such as "ICRUCLM45BGCCROP" or simply add "-crop on" to ``CLM_CONFIG_OPTS``. +To activate the crop model you can choose a compset that has "Crop" in the name such as "I1850Clm50BgcCropCru" or simply add +"-crop" to ``CLM_BLDNML_OPTS`` (or for CLM4.0 add "-crop on" to ``CLM_CONFIG_OPTS``). Example: Crop Simulation ------------------------------------ @@ -18,14 +19,6 @@ Example: Crop Simulation > ./create_newcase -case CROP -res f19_g17_gl4 -compset I1850Clm50BgcCropCru > cd CROP - # Append "-crop on" to CLM_CONFIG_OPTS in env_build.xml (you could also use an editor) - > ./xmlchange CLM_CONFIG_OPTS="-crop on" -append - - # Change to startup type so uses spunup initial conditions file for crop if it exists - # By default the model will do a hybrid startup with an initial condition file - # incompatible with the crop surface dataset. - - > ./xmlchange RUN_TYPE=startup > ./case.setup # Now build and run normally diff --git a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst index 3a7b0e3ccf..aa99179971 100644 --- a/doc/source/users_guide/running-special-cases/running-with-irrigation.rst +++ b/doc/source/users_guide/running-special-cases/running-with-irrigation.rst @@ -6,9 +6,12 @@ Running with irrigation =================================== -In |version| irrigation can ONLY be used WITH crop. +In CLM4.0 irrigation isn't an allowed option. +In CLM4.5 irrigation can ONLY be used WITH crop. With CLM5.0 irrigation can be used whether crop is on or not -- **BUT** +if crop is off, your surface datasets **HAVE** to have irrigation defined appropriately. Right now *ALL* surface +datasets without crop enabled have irrigation hard-wired on. In order to create datasets with irrigation off, you'd need +to make changes to ``mksurfdata_map`` in order to have all generic crops to be non-irrigated. To turn on irrigation in |version| we simply add "-irrig on" to ``CLM_BLDNML_OPTS``. -Just as in the crop example we also change ``RUN_TYPE`` to ``startup`` so that we don't use an initial condition file that is incompatible with irrigation. Example: Irrigation Simulation ------------------------------------------ @@ -16,16 +19,12 @@ Example: Irrigation Simulation # Note here we do a CLMSP simulation as that is what has been validated > cd scripts - > ./create_newcase -case IRRIG -res f19_g17_gl4 -compset I + > ./create_newcase -case IRRIG -res f19_g17_gl4 -compset I1850Clm50BgcCrop > cd IRRIG - # Append "-irrig" to CLM_BLDNML_OPTS in env_run.xml (you could also use an editor) - > ./xmlchange CLM_BLDNML_OPTS="-irrig" -append + # Append "-irrig on" to CLM_BLDNML_OPTS in env_run.xml (you could also use an editor) + > ./xmlchange CLM_BLDNML_OPTS="-irrig on" -append - # Change to startup type so uses spunup initial conditions file for irrigation if it exists - # By default the model will do a hybrid startup with an initial condition file - # incompatible with the irrigation surface dataset. - > ./xmlchange RUN_TYPE=startup > ./case.setup # Now build and run normally From 12905cdce7746c96f85d868e0151a2c20ff446e0 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Wed, 27 Jun 2018 14:24:02 -0600 Subject: [PATCH 179/255] Pass over the running-single-points chapter --- .../running-pts_mode-configurations.rst | 5 +--- .../running-single-point-configurations.rst | 29 +++++++------------ ...point-and-regional-grid-configurations.rst | 10 +++---- 3 files changed, 16 insertions(+), 28 deletions(-) diff --git a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst index c7a1ed0def..a75f18b977 100644 --- a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst @@ -21,8 +21,6 @@ To setup a ``PTS_MODE`` simulation you use the "-pts_lat" and "-pts_lon" argumen Then setup, build and run as normal. We make sure initial conditions are NOT used since ``PTS_MODE`` currently CAN NOT run with initial conditions. -.. note:: By default it sets up to run with MPILIB=mpi-serial (in the env_build.xml file) turned on, which allows you to run the model interactively. On some machines this mode is NOT supported and you may need to change it to FALSE before you are able to build. - .. warning:: ``PTS_MODE`` currently does NOT restart nor is it able to startup from global initial condition files. See bugs "1017 and 1025" in the `$CTSMROOT/doc/KnownLimitationss `_ file. .. note:: You can change the point you are simulating for at run-time by changing the values of ``PTS_LAT`` and ``PTS_LON`` in the ``env_run.xml`` file. @@ -37,6 +35,5 @@ You might also want to set the ``env_build.xml`` variable: ``MPILIB=mpi-serial`` On many machines, batch queues have a minimum number of nodes or processors that can be used. On these machines you may have to change the queue and possibly the time-limits of the job, to get it to run in the batch queue. -On the NCAR machine, cheyenne, this is done for you automatically, and the "caldera" queue is used for such single-processor simulations. -Another way to get around this problem is to run the job interactively using ``MPILIB=mpi-serial`` so that you don't submit the job to the batch queue. +On the NCAR machine, cheyenne, this is done for you automatically, and the "share" or "caldera" queue is used for such single-processor simulations. For single point mode you also may want to consider using a smaller workstation or cluster, rather than a super-computer, because you can't take advantage of the multi-processing power of the super-computer anyway. diff --git a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst index 6a2dc4e44d..02a7345e79 100644 --- a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst @@ -34,13 +34,13 @@ The resolution names that have an underscore in them ("_") are all single-point To run for the Brazil test site do the following: -Example: Running CLM over a single-point test site in Brazil with the default Qian atmosphere data forcing. --------------------------------------------------------------------------------------------------------------------------- +Example: Running CLM over a single-point test site in Brazil +------------------------------------------------------------ :: > cd scripts > set SITE=1x1_brazil - > ./create_newcase -case testSPDATASET -res $SITE -compset I + > ./create_newcase -case testSPDATASET -res $SITE -compset I2000Clm50SpGs > cd testSPDATASET Then setup, build and run normally. @@ -54,11 +54,8 @@ Example: Running CLM over the single-point of Mexicocity Mexico with the default > cd scripts # Set a variable to the site you want to use (as it's used several times below) > set SITE=1x1_mexicocityMEX - > ./create_newcase -case testSPDATASET -res $SITE -compset I + > ./create_newcase -case testSPDATASET -res $SITE -compset I1PtClm50SpGs > cd testSPDATASET - # Set DATM prescribed aerosols to single-point dataset - # Will then use the dataset with just the point for this $SITE - > ./xmlchange DATM_PRESAERO=pt1_pt1 Then setup, build and run normally. @@ -72,9 +69,9 @@ Using Supported Single-point Datasets that have their own Atmospheric Forcing ================================================================================ Of the supported single-point datasets we have three that also have atmospheric forcing data that go with them: Mexico City (Mexico), Vancouver, (Canada, British Columbia), and ``urbanc_alpha`` (test data for an Urban inter-comparison project). -Mexico city and Vancouver also have "#ifdef" in the source code for them to work with modified urban data parameters that are particular to these locations. -They can be turned on by using the ``CLM_CONFIG_OPTS env_build.xml`` variable to set the "-sitespf_pt" option in the CLM **configure**. +Mexico city and Vancouver also have namelist options in the source code for them to work with modified urban data parameters that are particular to these locations. To turn on the atmospheric forcing for these datasets, you set the ``env_run.xml DATM_MODE`` variable to ``CLM1PT``, and then the atmospheric forcing datasets will be used for the point picked. +If you use one of the compsets that has "I1Pt" in the name that will be set automatically. When running with datasets that have their own atmospheric forcing you need to be careful to run over the period that data is available. If you have at least one year of forcing it will cycle over the available data over and over again no matter how long of a simulation you run. @@ -94,12 +91,9 @@ Example: Running CLM over the single-point of Vancouver Canada with supplied atm > set SITE=1x1_vancouverCAN # Create a case at the single-point resolutions with their forcing - > ./create_newcase -case testSPDATASETnAtmForcing -res $SITE -compset I1PTCLM45 + > ./create_newcase -case testSPDATASETnAtmForcing -res $SITE -compset I1PtClm50SpGs > cd testSPDATASETnAtmForcing - # Set namelist options for urban test site - > ./xmlchange CLM_NML_USE_CASE=stdurbpt_pd - # Figure out the start and end date for this dataset # You can do this by examining the datafile. > set STOP_N=330 @@ -116,13 +110,10 @@ Example: Running CLM over the single-point of Vancouver Canada with supplied atm hist_nhtfrq = -1,1,1 EOF - # Set DATM prescribed aerosols to single-point dataset - # Will then use the dataset with just the point for this site - > ./xmlchange DATM_PRESAERO=pt1_pt1 > ./case.setup -.. warning:: If you don't set the start-year and run-length carefully as shown above the model will abort with a "dtlimit error" in the atmosphere model (see bug 1110 in the `$CTSMROOT/doc/KnownLimitationss `_ file for documentation on this). Since, the forcing data for this site (and the MexicoCity site) is less than a year, the model won't be able to run for a full year. The ``1x1_urbanc_alpha`` site has data for more than a full year, but neither year is complete hence, it has the same problem (see the problem for this site above). +.. warning:: If you don't set the start-year and run-length carefully as shown above the model will abort with a "dtlimit error" in the atmosphere model. Since, the forcing data for this site (and the MexicoCity site) is less than a year, the model won't be able to run for a full year. The ``1x1_urbanc_alpha`` site has data for more than a full year, but neither year is complete hence, it has the same problem (see the problem for this site above). .. note:: Just like ``PTS_MODE`` above, By default it sets up to run with ``MPILIB=mpi-serial`` (in the env_build.xml file) turned on, which allows you to run the model interactively. @@ -140,7 +131,7 @@ Example: Using CLM_USRDAT_NAME to run a simulation using user datasets for a spe :: > cd scripts - > ./create_newcase -case my_userdataset_test -res CLM_USRDAT -compset ICRUCLM45 + > ./create_newcase -case my_userdataset_test -res CLM_USRDAT -compset I2000Clm50BgcCruGs > cd my_userdataset_test/ > set GRIDNAME=13x12pt_f19_alaskaUSA > set LMASK=gx1v6 @@ -204,7 +195,7 @@ Example: Setting up a case from the single-point surface dataset just created > ./link_dirtree $CSMDATA $MYCSMDATA # Copy the file you created above to your new $MYCSMDATA location following the CLMUSRDAT # naming convention (leave off the creation date) - > cp $CESMROOT/$CTSMROOT/tools/|version|/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ + > cp $CESMROOT/$CTSMROOT/tools/mksurfdata_map/surfdata_${GRIDNAME}_simyr1850_$CDATE.nc \ $MYCSMDATA/lnd/clm2/surfdata_map/surfdata_${GRIDNAME}_simyr1850.nc > cd $CESMROOT/scripts > ./create_newcase -case my_usernldatasets_test -res CLM_USRDAT -compset I1850Clm50BgcCropCru \ diff --git a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst index 41f55e38f1..9564b1649c 100644 --- a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst +++ b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst @@ -17,10 +17,10 @@ There are three different ways to do this for normal-supported site ``CLM_USRDAT_NAME`` runs using your own datasets (single-point or regional). -``PTCLM`` +``PTCLMmkdata`` easily setup simulations to run for tower sites.. -.. note:: ``PTS_MODE`` and ``PTCLM`` only works for a single point, while the other two options can also work for regional datasets as well. +.. note:: ``PTS_MODE`` and ``PTCLMmkdata`` only works for a single point, while the other two options can also work for regional datasets as well. .. _options-for-single-points: @@ -42,12 +42,12 @@ With this method you don't have to change DATM or add files to the XML database However, once the files are named and in the proper location, you can easily setup new cases that use these datasets. This is good for treating all the required datasets as a "group" and for a particular model version. For advanced CLM developers who need to track dataset changes with different model versions you would be best off adding these datasets as supported datasets with the "normal supported datasets" method. -Lastly *PTCLM* is a great way to easily create datasets, setup simulations and run simulations for tower sites. +Lastly *PTCLMmkdata* is a great way to easily create datasets, setup simulations and run simulations for tower sites. It takes advantage of both normal supported site functionality and CLM_USRDAT_NAME internally. -A big advantage to it, is that it's one-stop shopping, it runs tools to create datasets, and runs **create_newcase** and sets the appropriate env variables for you. So you only have to learn how to run one tool, rather than work with many different ones. PTCLM is described in the next chapter `Chapter 6 `_. +A big advantage to it, is that it's one-stop shopping, it runs tools to create datasets, and runs **create_newcase** and sets the appropriate env variables for you. So you only have to learn how to run one tool, rather than work with many different ones. PTCLMmkdata is described in the next chapter `Chapter 6 `_. Finally, if you also have meteorology data that you want to force your CLM simulations with you'll need to setup cases as described in `the Section called Running with your own atmosphere forcing `_. You'll need to create CLM datasets either according to ``CLM_USRDAT_NAME``. You may also need to modify DATM to use your forcing data. -And you'll need to change your forcing data to be in a format that DATM can use. In the PTCLM chapter `the Section called Converting AmeriFlux Data for use by PTCLM in Chapter 6 `_ section tells you how to use AmeriFlux data for atmospheric forcing. +And you'll need to change your forcing data to be in a format that DATM can use. In the PTCLMmkdata chapter `the Section called Converting AmeriFlux Data for use by PTCLMmkdata in Chapter 6 `_ section tells you how to use AmeriFlux data for atmospheric forcing. From 6f4998024b845263d0910791b334bc74b596bdfe Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Wed, 27 Jun 2018 15:11:17 -0600 Subject: [PATCH 180/255] Remove pointing to KnownLimitations file, correct some grammar and remove mention of linkdirtree that is now gone --- .../running-pts_mode-configurations.rst | 8 ++++---- .../running-single-point-configurations.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst index a75f18b977..b5ce4eadb7 100644 --- a/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst @@ -21,13 +21,13 @@ To setup a ``PTS_MODE`` simulation you use the "-pts_lat" and "-pts_lon" argumen Then setup, build and run as normal. We make sure initial conditions are NOT used since ``PTS_MODE`` currently CAN NOT run with initial conditions. -.. warning:: ``PTS_MODE`` currently does NOT restart nor is it able to startup from global initial condition files. See bugs "1017 and 1025" in the `$CTSMROOT/doc/KnownLimitationss `_ file. +.. warning:: ``PTS_MODE`` currently does NOT restart nor is it able to startup from global initial condition files. This is a known issue we are unlikely to fix. .. note:: You can change the point you are simulating for at run-time by changing the values of ``PTS_LAT`` and ``PTS_LON`` in the ``env_run.xml`` file. -================================== - Running on in a single processor -================================== +============================== + Running in a single processor +============================== Note, that when running with ``PTS_MODE`` the number of processors is automatically set to one. When running a single grid point you can only use a single processor. diff --git a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst index 02a7345e79..fd71d44de5 100644 --- a/doc/source/users_guide/running-single-points/running-single-point-configurations.rst +++ b/doc/source/users_guide/running-single-points/running-single-point-configurations.rst @@ -208,4 +208,4 @@ Example: Setting up a case from the single-point surface dataset just created > ./xmlchange CLM_USRDAT_NAME=$GRIDNAME > ./case.setup -.. note:: With this and previous versions of the model we recommended using ``CLM_USRDAT_NAME`` as a way to identify your own datasets without having to enter them into the XML database. This has two down-sides. First you can't include creation dates in your filenames, which means you can't keep track of different versions by date. It also means you HAVE to rename the files after you created them with **mksurfdata.pl**. And secondly, you have to use **linkdirtree** in order to place the files in a location outside of the usual ``DIN_LOC_ROOT`` (assuming you don't have write access to adding new files to the standard location on the machine you are using). Now, since ``user_nl`` files are supported for ALL model components, and the same domain files are read by both CLM and DATM and set using the envxml variables: ``ATM_DOMAIN_PATH``, ``ATM_DOMAIN_FILE``, ``LND_DOMAIN_PATH``, and ``LND_DOMAIN_FILE`` -- you can use this mechanism (``user_nl_clm`` and ``user_nl_datm`` and those envxml variables) to point to your datasets in any location. In the future we will deprecate ``CLM_USRDAT_NAME`` and recommend ``user_nl_clm`` and ``user_nl_datm`` and the ``DOMAIN`` envxml variables. +.. note:: With this and previous versions of the model we recommended using ``CLM_USRDAT_NAME`` as a way to identify your own datasets without having to enter them into the XML database. This has the down-side that you can't include creation dates in your filenames, which means you can't keep track of different versions by date. It also means you HAVE to rename the files after you created them with **mksurfdata.pl**. Now, since ``user_nl`` files are supported for ALL model components, and the same domain files are read by both CLM and DATM and set using the envxml variables: ``ATM_DOMAIN_PATH``, ``ATM_DOMAIN_FILE``, ``LND_DOMAIN_PATH``, and ``LND_DOMAIN_FILE`` -- you can use this mechanism (``user_nl_clm`` and ``user_nl_datm`` and those envxml variables) to point to your datasets in any location. In the future we will deprecate ``CLM_USRDAT_NAME`` and recommend ``user_nl_clm`` and ``user_nl_datm`` and the ``DOMAIN`` envxml variables. From a956812b6e4417d4cd63da739368cea62a554fc2 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 28 Jun 2018 14:28:55 -0600 Subject: [PATCH 181/255] Work on PTCLMmkdata chapter --- .../running-PTCLM/adding-ptclm-site-data.rst | 44 +++-- .../running-PTCLM/introduction-to-ptclm.rst | 71 ++++---- .../running-PTCLM/ptclm-examples.rst | 63 ++----- .../users_guide/running-PTCLM/using-ptclm.rst | 168 +++++------------- 4 files changed, 108 insertions(+), 238 deletions(-) diff --git a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst index 425e6d9c25..b643e79a28 100644 --- a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst +++ b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst @@ -2,13 +2,13 @@ .. include:: ../substitutions.rst -====================== -Adding PTCLM Site Data -====================== +============================ +Adding PTCLMmkdata Site Data +============================ -The "sitegroupname" option to PTCLM1.110726 looks for groups of sites in the files in the ``PTCLM_sitedata`` directory under the PTCLM directory. +The "sitegroupname" option to PTCLMmkdata looks for groups of sites in the files in the ``PTCLM_sitedata`` directory under the PTCLMmkdata directory. You can add new names available for this option including your own lists of sites, by adding more files in this directory. -There are three files for each "sitegroupname": ``$SITEGROUP_sitedata.txt``, ``$SITEGROUP_soildata.txt`` and ``$SITEGROUP_pftdata.txt`` (where ``$SITEGROUP`` is the name that would be entered as "sitegroupname" to PTCLM). +There are three files for each "sitegroupname": ``$SITEGROUP_sitedata.txt``, ``$SITEGROUP_soildata.txt`` and ``$SITEGROUP_pftdata.txt`` (where ``$SITEGROUP`` is the name that would be entered as "sitegroupname" to PTCLMmkdata). Each file needs to have the same list of sites, but gives different information: site data, PFT data, and soil data respectively. Although the site codes need to be the same between the three files, the files do NOT have to be in the same order. Each file has a one-line header that lists the contents of each column which are separated by commas. @@ -36,20 +36,20 @@ PFT data file: ``$SITEGROUP_pftdata.txt```): The header for this file is: This file gives the vegetation coverage for the different vegetation types for the site. The file only supports up to five PFT's at the same time. The columns with "pft_f" are the fractions for each PFT, and the columns with "pft_c" is the integer index of the given PFT. Look at the pft-physiology file to see what the PFT index for each PFT type is. ----------------------------------------------- -Dynamic Land-Use Change Files for use by PTCLM ----------------------------------------------- +---------------------------------------------------- +Dynamic Land-Use Change Files for use by PTCLMmkdata +---------------------------------------------------- -There is a mechanism for giving site-specific land-use change in PTCLM. Adding site specific files to the ``PTCLM_sitedata`` directory under PTCLM allows you to specify the change in vegetation and change in harvesting (for the CN model) for that site. Files are named: ``$SITE_dynpftdata.txt``. There is a sample file for the US-Ha1 site called: ``US-Ha1_dynpftdata.txt``. The file has a one-line header with the information that the file has, and then one-line for each year with a transition. The header line is as follows: +There is a mechanism for giving site-specific land-use change in PTCLMmkdata. Adding site specific files to the ``PTCLM_sitedata`` directory under PTCLMmkdata allows you to specify the change in vegetation and change in harvesting (for the CN model) for that site. Files are named: ``$SITE_dynpftdata.txt``. There is a sample file for the US-Ha1 site called: ``US-Ha1_dynpftdata.txt``. The file has a one-line header with the information that the file has, and then one-line for each year with a transition. The header line is as follows: :: trans_year,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5,har_vh1,har_vh2,har_sh1,har_sh2,har_sh3,graze,hold_harv,hold_graze -This file only requires a line for each year where a transition or harvest happens. As in the "pftdata" file above "pft_f" refers to the fraction and "pft_c" refers to the PFT index, and only up to five vegetation types are allowed to co-exist. The last eight columns have to do with harvesting and grazing. The last two columns are whether to hold harvesting and/or grazing constant until the next transition year and will just be either 1 or 0. This file will be converted by the **PTCLM_sitedata/cnvrt_trnsyrs2_pftdyntxtfile.pl** script in the PTCLM directory to a format that **mksurfdata_map** can read that has an entry for each year for the range of years valid for the compset in question. +This file only requires a line for each year where a transition or harvest happens. As in the "pftdata" file above "pft_f" refers to the fraction and "pft_c" refers to the PFT index, and only up to five vegetation types are allowed to co-exist. The last eight columns have to do with harvesting and grazing. The last two columns are whether to hold harvesting and/or grazing constant until the next transition year and will just be either 1 or 0. This file will be converted by the **PTCLM_sitedata/cnvrt_trnsyrs2_pftdyntxtfile.pl** script in the PTCLMmkdata directory to a format that **mksurfdata_map** can read that has an entry for each year for the range of years valid for the compset in question. ------------------------------------------- -Converting AmeriFlux Data for use by PTCLM ------------------------------------------- +------------------------------------------------ +Converting AmeriFlux Data for use by PTCLMmkdata +------------------------------------------------ AmeriFlux data comes in comma separated format and is available from: `http://public.ornl.gov/ameriflux/dataproducts.shtml `_. Before you download the data you need to agree to the usage terms. @@ -75,23 +75,23 @@ The units of Temperature need to be converted from "Celsius" to "Kelvin" (use th The units of Pressure also need to be converted from "kPa" to "Pa". LATIXY, and LONGXY should also be set to the latitude and longitude of the site. ------------------------------------------------------------ -Example: PTCLM transient example over a shorter time period ------------------------------------------------------------ +----------------------------------------------------------------- +Example: PTCLMmkdata transient example over a shorter time period +----------------------------------------------------------------- -This is an example of using PTCLM for Harvard Forest (AmeriFlux site code US-Ha1) for transient land use 1991-2006. -In order to do this we would've needed to have converted the AmeriFlux data into NetCDF format as show in the `the Section called Converting AmeriFlux Data for use by PTCLM `_ section above. -Also note that this site has a site-specific dynamic land-use change file for it ``PTCLM_sitedata/US-Ha1_dynpftdata.txt`` in the PTCLM directory and this file will be used for land-use change and harvesting rather than the global dataset. +This is an example of using PTCLMmkdata for Harvard Forest (AmeriFlux site code US-Ha1) for transient land use 1991-2006. +In order to do this we would've needed to have converted the AmeriFlux data into NetCDF format as show in the `the Section called Converting AmeriFlux Data for use by PTCLMmkdata `_ section above. +Also note that this site has a site-specific dynamic land-use change file for it ``PTCLM_sitedata/US-Ha1_dynpftdata.txt`` in the PTCLMmkdata directory and this file will be used for land-use change and harvesting rather than the global dataset. :: - > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM + > cd $CTSMROOT/tools/PTCLM # We are going to use forcing data over 1991 to 2006, but we need to start with # a transient compset to do so, so we use the 20th Century transient: 1850-2000 # Note: When creating the fpftdyn dataset for this site it will use the # PTCLM_sitedata/US-Ha1_dynpftdata.txt # file for land-use change and harvesting - > ./PTCLM.py -m cheyenne_intel -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux -c I20TRCRUCLM45BGC + > ./PTCLMmkdata -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux > mkdir $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 > cd $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 # Copy data in NetCDF format to this directory, filenames should be YYYY-MM.nc @@ -107,5 +107,3 @@ Also note that this site has a site-specific dynamic land-use change file for it > cat << EOF >> user_nl_clm model_year_align_ndep=1991,stream_year_first_ndep=1991,stream_year_last_ndep=2006 EOF - # Now setup the case, and we'll edit the datm namelist for prescribed aerosols - > ./cesm_setup diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst index 0c49f6ad78..50476e0261 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -4,38 +4,39 @@ .. _what-is-ptclm: -=============== - What is PTCLM -=============== +===================== + What is PTCLMmkdata? +===================== -PTCLM (pronounced either as point clime or Pee-Tee clime) is a Python script to help you set up PoinT CLM simulations. +PTCLMmkdata (pronounced Pee-Tee Cee-L-M make data is a Python script to help you set up PoinT CLM simulations. -It runs the CLM tools for you to get datasets set up, and copies them to a location you can use them according to the ``CLM_USRDAT_NAME`` naming convention. +It runs the CLM tools for you to get datasets set up, and copies them to a location you can use them including the changes +needed for a case to use the dataset with namelist and XML changes. -Then it runs **create_newcase** for you and modifies the env settings and namelist appropriately. +Then you run **create_newcase** and point to the directory so that the namelist and XML changes are automatically applied. -PTCLM has a simple ASCII text file for storing basic information for your sites. +PTCLMmkdata has a simple ASCII text file for storing basic information for your sites. We also have complete lists for AmeriFlux and Fluxnet-Canada sites, although we only have the meteorology data for one site. For other sites you will need to obtain the meteorology data and translate it to a format that the CESM datm model can use. -But, even without meteorology data PTCLM is useful to setup datasets to run with standard ``CLM_QIAN`` data. +But, even without meteorology data PTCLMmkdata is useful to setup datasets to run with standard ``CLM_QIAN`` data. -The original authors of PTCLM are: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, Wilfred M. Post all at Environmental Sciences Division, Oak Ridge National Laboratory (ORNL) and R. Quinn Thomas at Cornell University. It was then modified fairly extensively by Erik Kluzek at NCAR. We want to thank all of these individuals for this contribution to the CESM effort. We also want to thank the folks at University of Michigan Biological Stations (US-UMB) who allowed us to use their Fluxnet station data and import it into our inputdata repository, especially Gil Bohrer the PI on record for this site. +The original authors of PTCLMmkdata are: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, Wilfred M. Post all at Environmental Sciences Division, Oak Ridge National Laboratory (ORNL) and R. Quinn Thomas at Cornell University. It was then modified fairly extensively by Erik Kluzek at NCAR. We want to thank all of these individuals for this contribution to the CESM effort. We also want to thank the folks at University of Michigan Biological Stations (US-UMB) who allowed us to use their Fluxnet station data and import it into our inputdata repository, especially Gil Bohrer the PI on record for this site. .. _details-of-ptclm: -================== - Details of PTCLM -================== +======================= + Details of PTCLMmkdata +======================= -To get help on PTCLM1.110726 use the "--help" option as follows. +To get help on PTCLM2_180611 use the "--help" option as follows. :: - > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py --help + > cd $CTSMROOT/tools/PTCLM + > ./PTCLMmkdata --help The output to the above command is as follows: :: @@ -106,36 +107,34 @@ The output to the above command is as follows: Main Script Version Id: $Id: PTCLM.py 47576 2013-05-29 19:11:16Z erik $ Scripts URL: $HeadURL: https://svn-ccsm-models.cgd.ucar.edu/PTCLM/trunk_tags/PTCLM1_130529/PTCLM.py $: -Here we give a simple example of using PTCLM1 for a straightforward case of running at the US-UMB Fluxnet site on cheyenne where we already have the meteorology data on the machine. -Note, see `the Section called Converting AmeriFlux Data for use by PTCLM `_ for permission information to use this data. +Here we give a simple example of using PTCLMmkdata for a straightforward case of running at the US-UMB Fluxnet site on cheyenne where we already have the meteorology data on the machine. +Note, see `the Section called Converting AmeriFlux Data for use by PTCLMmkdata `_ for permission information to use this data. -Example 6-1. Example of running PTCLM1 for US-UMB on cheyenne +Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne ---------------------------------------------------------------- :: > setenv CSMDATA $CESMDATAROOT/inputdata - > setenv MYCSMDATA $HOME/inputdata + > setenv MYDATAFILES `pwd`/mydatafiles > setenv SITE US-UMB - > setenv MYMACH cheyenne_intel > setenv MYCASE testPTCLM - # First link the standard input files to a location you have write access - > cd scripts - > ./link_dirtree $CSMDATA $MYCSMDATA # Next build all of the clm tools you will need - > cd ../$CTSMROOT/tools/|version|/mksurfdata_map - > gmake - > gmake clean - > cd ../../../../../../tools/mapping/gen_domain_files/src - > ../../../../scripts/ccsm_utils/Machines/configure -mach cheyenne -compiler intel - > gmake - > gmake clean + > cd $CTSMROOT/tools/PTCLM + > buildtools # next run PTCLM (NOTE -- MAKE SURE python IS IN YOUR PATH) - > cd ../../../../../scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py -m $MYMACH --case=$MYCASE --site=$SITE --csmdata=$MYCSMDATA --aerdepgrid --ndepgrid - # NOTE: we use --aerdepgrid --ndepgrid so that you use the global - # aerosol and Nitrogen deposition files rather than site-specific ones. - > cd ../../../../../$MYCASE - # Finally setup, build, and run the case as normal + > cd $CTSMROOT/tools/PTCLM + # Here we run it using qcmd so that it will be run on a batch node + > qcmd -- ./PTCLMmkdata --site=$SITE --csmdata=$CSMDATA --mydatadir=$MYDATAFILES >& ptclmrun.log & + > cd $CIMEROOT/scripts + > ./create_newcase --user-mods-dir $MYDATAFILES/1x1pt_$SITE --case $MYCASE --res CLM_USRDAT --compset I1PtClm50SpGs + # Next setup, build and run as normal + > cd $MYCASE + > ./case.setup + +PTCLMmkdata includes a README file that gives some extra details and a simple example. + +.. include:: ../../clm5.0/tools/PTCLM/README + :literal: diff --git a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst index d3d85da0b1..e36b1e686a 100644 --- a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst +++ b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst @@ -2,71 +2,32 @@ .. include:: ../substitutions.rst -========================= - Examples of using PTCLM -========================= +============================== + Examples of using PTCLMmkdata +============================== Now let's give a few more complex examples using some of the options we have discussed above. -In this first example, we'll demonstrate using a supported single point dataset, which then requires using the "nopointdata". We'll also demonstrate the compset option, "stdurbpt" and "caseidprefix" options. - -Example: Running PTCLM for the Mexicocity supported single point dataset ------------------------------------------------------------------------- -:: - - > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py -m cheyenne_intel -s 1x1_mexicocityMEX -d $CSMDATA --nopointdata \ - --stdurbpt -c ICRUCLM45 --caseidprefix `pwd`/myPTCLMcases/site - > cd myPTCLMcases/site_1x1_mexicocityMEX_I - > ./cesm_setup - # Now build and run normally - > ./site_1x1_mexicocityMEX_I.build - # Here we show running interactively - > ./site_1x1_mexicocityMEX_I.run - Now, let's demonstrate using a different group list, doing a spinup, running with Qian global forcing data, but using tower years to set the years to run over. This uses the options: sitegroupname, useQIAN, and QIANtower_years. -Example: Running PTCLM for a spinup simulation with Qian data for tower years. ------------------------------------------------------------------------------- +Example: Running PTCLMmkdata without tower years +------------------------------------------------ :: - > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py -m cheyenne_intel -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux --useQIAN --QIAN_tower_yrs + > cd $CTSMROOT/tools/PTCLM + > ./PTCLMmkdata -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux --donot_use_tower_yrs > cd ../../../../../US-Ha1_ICRUCLM45BGC_QIAN - > ./cesm_setup # Now build and run normally - > ./US-Ha1_ICRUCLM45BGC_QIAN.build - # Here we show running interactively - > ./US-Ha1_ICRUCLM45BGC_QIAN.run ``` Finally, let's demonstrate using a generic machine (which then requires the scratchroot option), using the global grid for PFT and soil types, and setting the run length to two months. -Example: Running PTCLM on a user-defined machine with global PFT and soil types dataset ---------------------------------------------------------------------------------------- +Example: Running PTCLMmkdata with global PFT and soil types dataset +------------------------------------------------------------------- :: - > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - # Note, see the the Section called Converting AmeriFlux Data for use by PTCLM with permission information + > cd $CTSMROOT/tools/PTCLM + # Note, see the the Section called Converting AmeriFlux Data for use by PTCLMmkdata with permission information # to use the US-UMB data. - > ./PTCLM.py -m userdefined_intel -s US-UMB -d $CSMDATA --pftgrid --soilgrid \ - --scratchroot $HOME --run_n 2 --run_units nmonths + > ./PTCLMmkdata -s US-UMB -d $CSMDATA --pftgrid --soilgrid > cd ../../../../../US-UMB_ICRUCLM45BGC - # If userdefined is NOT set up for you Uncomment the following and set OS, NTASKS_PER_NODE, TMPDIR - # > ./xmlchange OS=$OS,MAX_TASKS_PER_NODE=$NTASKS_PER_NODE,MPILIB=mpi-serial - # > ./xmlchange RUNDIR=$TMPDIR/$USER/\$CASE/run,DIN_LOC_ROOT=$CSMDATA,COMPILER=intel - # > ./xmlchange EXEROOT=$TMPDIR/$USER/\$CASE - > ./cesm_setup - # Now build - > ./US-UMB_ICRUCLM45BGC.userdefined_intel.build - # To get the files from the svn server... - # First list the files from the streams text file - > ../ccsm_utils/Tools/listfilesin_streams \ - -t $HOME/US-UMB_ICRUCLM45BGC/run/clm1PT.1x1pt_US-UMB.stream.txt -l \ - > Buildconf/datm.input_data_list - # And now run the script to export data to your machine - > ../ccsm_utils/Tools/check_input_data -export - # Here we show running interactively - > ./US-UMB_ICRUCLM45BGC.userdefined_intel.run - -.. warning: Because of Bug 1364, when running this case as above we get a floating point error after reaching time-step 124 for the example exactly as above. Other machines or compilers probably won't have this problem. See the `$CTSMROOT/doc/KnownBugs `_ file for more information on this problem. diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst index 2055cc81a1..e657608b67 100644 --- a/doc/source/users_guide/running-PTCLM/using-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/using-ptclm.rst @@ -3,144 +3,98 @@ .. include:: ../substitutions.rst ************************** -Using PTCLM +Using PTCLMmkdata ************************** -There are three types of options to PTCLM1: required, setup/run-time, and dataset generation options. -The three required options are the three settings that MUST be specified for PTCLM to work at all. The other settings have default values that will default to something useful. The setup/run-time options control how the simulation will be setup and run. The dataset generation options control the generation of datasets needed when PTCLM is run. Most options use a double dash "--" "longname" such as "--list", but the most common options also have a short-name with a single dash (such as -m instead of --machine). +There are two types of options to PTCLMmkdata: required and optional. +The three required options are the three settings that MUST be specified for PTCLMmkdata to work at all. The other settings have default values that will default to something useful. Most options use a double dash "--" "longname" such as "--list", but the most common options also have a short-name with a single dash. -The required options to PTCLM are: inputdata directory (-d), machine (-m) and site-name (-s). -Inputdata directory is the directory where you have the CESM inputdata files, you need to have write access to this directory, so if you are running on a machine that you do NOT have write access to the standard inputdata location (such as NCAR cheyenne or LBNL hopper) you need to link the standard files to a location you do have control over. We recommend using the ``scripts/link_dirtree`` tool to do that. "machine" is the scripts name for the machine/compiler you will be using for your case. And finally site-name is the name of the site that you want to run for. Site-name can either be a valid supported dataset name or a Fluxnet site name from the list of sites you are running on (see the --sitegroupname for more information about the site lists). +The required options to PTCLMmkdata are: inputdata directory (-d) and site-name (-s). +Inputdata directory is the directory where you have the CESM inputdata files. Finally site-name is the name of the site that you want to run for. Site-name is a Fluxnet site name from the list of sites you are running on (see the --sitegroupname for more information about the site lists). -After PTCLM is run a case directory where you can then setup, build and run your CESM case as normal. -It also creates a ``README.PTCLM`` in that directory that documents the commandline options to PTCLM that were used to create it. +After PTCLMmkdata is run you can run **create_newcase** to setup a case to use the datasets created. +It also creates a ``README.PTCLM`` in that directory that documents the commandline options to PTCLMmkdata that were used to create it. -After "help" the "list" option is one of the most useful options for getting help on using PTCLM. -This option gives you information about some of the other options to PTCLM. To get a list of the machine, sites, and compsets that can be used for PTCLM use the "--list" option as follows. +After "help" the "list" option is one of the most useful options for getting help on using PTCLMmkdata. +This option gives you information about some of the other options to PTCLMmkdata. To get a list of the sites that can be used for PTCLMmkdata use the "--list" option as follows. :: - > cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM - > ./PTCLM.py --list + > cd $CTSMROOT/tools/PTCLM + > ./PTCLMmkdata --list The output to the above command is as follows: :: - /bin/sh: line 1: PTCLM.py: command not found + /bin/sh: line 1: PTCLMmkdata: command not found -Steps in running PTCLM -========================= - -1. Setup Inputdata directory with write access (use link_dirtree script) - - You need to setup an inputdata directory where you have write access to it. - Normally, for NCAR machines the data is on an inputdata where the user does NOT have write access to it. - A way that you can get around this is to use the **link_dirtree** script to create softlinks from the normal location to a location you have write access to. - So for example on cheyenne: - :: +Steps in running PTCLMmkdata +============================ - > setenv CSMDATA $CESMDATAROOT/inputdata - > setenv MYCSMDATA $HOME/inputdata - > mkdir $MYCSMDATA - > cd scripts - > ./link_dirtree $CSMDATA $MYCSMDATA - - See `the Section called Managing Your Own Data-files in Chapter 3 `_ for more information on this. - -2. Build the CLM tools +1. Build the CLM tools Next you need to make sure all the CLM FORTRAN tools are built. :: - > cd $CTSMROOT/tools/|version|/mksurfdata_map - > gmake - > gmake clean - > cd ../../../../../../tools/mapping/gen_domain_files/src - > ../../../../scripts/ccsm_utils/Machines/configure -mach cheyenne -compiler intel - > gmake + > cd $CTSMROOT/tools/PTCLM + > ./buildtools > gmake clean -3. Run PTCLM - Next you actually run PTCLM1 which does the different things listed below: +2. Run PTCLMmkdata + Next you actually run PTCLMmkdata which does the different things listed below: - a. PTCLM names your case based on your input + a. PTCLMmkdata names your output file directory based on your input :: - [Prefix_]SiteCode_Compset[_QIAN] + [Prefix_]SiteCode Where: ``Prefix`` is from the caseidprefix option (or blank if not used). ``SiteCode`` is the site name you entered with the -s option. - ``Compset`` is the compset name you entered with the -c option. - - ``_QIAN`` is part of the name only if the useQIAN is used. - For example, the casename for the following will be: :: > cd scripts - > ./PTCLM.py -m cheyenne_intel -s US-UMB -d $MYCSMDATA -c ICRUCLM45BGC --use QIAN "US-UMB_I_2000_CN_QIAN" + > ./PTCLMmkdata -s US-UMB -d $MYCSMDATA - b. PTCLM creates datasets for you + b. PTCLMmkdata creates datasets for you It will populate $MYCSMDATA with new datasets it creates using the CLM tools. - c. If a transient compset and PTCLM1 finds a _dynpftdata.txt file - If you are running a transient compset (such as the "I_1850-2000_CN" compset) AND you there is a file in the PTCLM_sitedata directory under the PTCLM directory called $SITE_dynpftdata.txt it will use this file for the land-use changes. + c. If a transient compset and PTCLMmkdata finds a _dynpftdata.txt file + If you are running a transient compset (such as the "I_1850-2000_CN" compset) AND you there is a file in the PTCLM_sitedata directory under the PTCLMmkdata directory called $SITE_dynpftdata.txt it will use this file for the land-use changes. Otherwise it will leave land-use constant, unless you use the pftgrid option so it uses the global dataset for landuse changes. - See the Section called Dynamic Land-Use Change Files for use by PTCLM for more information on this. + See the Section called Dynamic Land-Use Change Files for use by PTCLMmkdata for more information on this. There is a sample transient dataset called US-Ha1_dynpftdata.txt. Transient compsets, are compsets that create transient land-use change and forcing conditions such as: 'I_1850-2000', 'I_1850-2000_CN', 'I_RCP8.5_CN', 'I_RCP6.0_CN', 'I_RCP4.5_CN', or 'I_RCP2.6_CN'. - d. PTCLM creates a pft-physiology for you - PTCLM1 will create a local copy of the pft-physiology specific for your site that you could then customize with changes specific for that site. + d. PTCLMmkdata creates a pft-physiology for you + PTCLMmkdata will create a local copy of the pft-physiology specific for your site that you could then customize with changes specific for that site. + + e. PTCLMmkdata creates a README.PTCLM for you + PTCLMmkdata will create a simple text file with the command line for it in a file called README.PTCLM in the case directory it creates for you. - e. PTCLM creates a README.PTCLM for you - PTCLM1 will create a simple text file with the command line for it in a file called README.PTCLM in the case directory it creates for you. +3. Run create_newcase pointing to the directory created 4. Customize, setup, build and run case as normal You then customize your case as you would normally. See the Chapter 1 chapter for more information on doing this. -PTCLM options +PTCLMmkdata options ========================= Next we discuss the setup and run-time options, dividing them up into setup, initial condition (IC), and run-time options. Configure options include: -- --compset=MYCOMPSET -- --caseidprefix=MYCASEID - --cesm_root=BASE_CESM -- --namelist=NAMELIST -- --rmold -- --scratchroot=SCRATCHROOT - --sitegroupname=SITEGROUP -- --QIAN_tower_yrs -- --useQIAN - -``--compset`` - The "-c" option is the most commonly used option after the required options, as it specifies the CESM scripts component set to use with PTCLM1. - The default compset is the "ICN" compset with CN on for present day conditions. - -``--caseidprefix`` - This option gives a prefix to include in the casename when the case is created, in case you want to customize your casenames a bit. - By default, casenames are figured out based on the other options. The argument to this option can either be a name to prefix casenames with and/or a pathname to include. - Hence, if you want cases to appear in a specific directory you can give the pathname to that directory with this option. +- --donot_use_tower_yrs ``--cesm_root`` - This option is for running PTCLM1 with a different root directory to CESM than the version PTCLM exists in. Normally you do NOT need to use this option. - -``--namelist`` - This option adds any items given into the CLM user_nl_clm namelist. This allows you to add customizations to the namelist before the clm.buildnml.csh file is created for the case. - -``--rmold`` - This option will remove an old case directory of the same name if one exists. Otherwise, if an old case directory already exists and you try to run PTCLM it will return with an error. - -``--scratchroot`` - This option is ONLY valid when using one of the generic machines (the -m option). This passed onto **create_newcase** and gives the location where cases will be built and run. + This option is for running PTCLMmkdata with a different root directory to CESM than the version PTCLMmkdata exists in. Normally you do NOT need to use this option. ``--sitegroupname`` - In the PTCLM directory there is a subdirectory "PTCLM_sitedata" that contains files with the site, PFT and soil data information for groups of sites. - These site groups are all separate ASCII files with the same prefix followed by a "_*data.txt" name. See `the Section called PTCLM Group Site Lists `_ for more information on these files. By default we have provided three different valid group names: + In the PTCLMmkdata directory there is a subdirectory "PTCLM_sitedata" that contains files with the site, PFT and soil data information for groups of sites. + These site groups are all separate ASCII files with the same prefix followed by a "_*data.txt" name. See `the Section called PTCLMmkdata Group Site Lists `_ for more information on these files. By default we have provided three different valid group names: EXAMPLE ------- @@ -152,52 +106,21 @@ The EXAMPLE is the group used by default and ONLY includes the US-UMB site as th The other two site groups include the site information for all of both the AmeriFlux and Fluxnet-Canada sites. You can use the "sitegroupname" option to use one of the other lists, or you can create your own lists using the EXAMPLE file as an example. Your list of sites could be real world locations or could be theoretical "virtual" sites given to exercise CLM on differing biomes for example. -Note, see `the Section called Converting AmeriFlux Data for use by PTCLM `_ with permission information to use the US-UMB data. +Note, see `the Section called Converting AmeriFlux Data for use by PTCLMmkdata `_ with permission information to use the US-UMB data. -``--useQIAN`` - This option says to use the standard CLM global Qian T62 atmospheric forcing rather than any tower site forcing data available. Otherwise, PTCLM will try to find tower forcing data for the specific site entered. - -``--QIAN_tower_yrs`` +``--donot_use_tower_yrs`` This option is used with the "useQIAN" option to set the years to cycle over for the Qian data. In this case Qian atmospheric forcing will be used, but the simulation will run over the same years that tower site is available for this site. -**IC options include:** - -- --coldstart -- --finidat=FINIDAT - -The coldstart option says to startup with OUT an initial condition file, while the finidat option explicitly gives the initial condition file to use. Obviously, the coldstart and finidat options can NOT be used together. - -``--coldstart`` - This option ensures that a cold-start will be done with arbitrary initial conditions. - -``--finidat`` - This option sets the initial condition file to startup the simulation from. - **Run-time options include:** -- --debug -- --run_n=MYRUN_N -- --run_units=MYRUN_UNITS -- --stdurbpt - --debug -This option tells PTCLM to echo what it would do if it were run, but NOT actually run anything. So it will show you the dataset creation commands it would use. It does however, run **create_newcase**, but then it only displays the **xmlchange** commands and changes that it would do. Also note that if you give the "--rmold" option it won't delete the case directory beforehand. Primarily this is intended for debugging the operation of PTCLM. - -``--run_n`` - This option along with run_units is used to set the length for the simulation. "run_n" is the number of units to use. The default run length depends on the site, compset, and configuration. - -``--run_units`` - This option is the units of time to use for the length of the simulation. It is used along with "run_n" to set the length of the simulation. The default run length depends on the site, compset, and configuration. - -``--stdurbpt`` - This option turns on the "stdurbpt_pd" use-case for CLM_NML_USE_CASE. This option can NOT be used for compsets that set the use-case to something besides present-day. +This option tells PTCLMmkdata to echo what it would do if it were run, but NOT actually run anything. So it will show you the dataset creation commands it would use. It does however, run **create_newcase**, but then it only displays the **xmlchange** commands and changes that it would do. Also note that if you give the "--rmold" option it won't delete the case directory beforehand. Primarily this is intended for debugging the operation of PTCLMmkdata. **The dataset generation options are:** - --pftgrid - --soilgrid -- --nopointdata -- --owritesrfaer The options that with a "grid" suffix all mean to create datasets using the global gridded information rather than using the site specific point data. By default the site specific point data is used. The "nopointdata" and "owritesrfaer" options have to do with file creation. @@ -211,14 +134,3 @@ Because supported single-point datasets already have the data created for them, This option says to use the soil values provided on the global dataset rather than using the specific site based values from the PTCLM_sitedata/\*_soildata.txt file when creating the surface dataset. This option must NOT be used when you you are using a site that is a supported single point dataset. -``--nopointdata`` - This option says to NOT create any input datasets -- assume this step has already been done. - If datasets weren't already created, your case will fail when you try to run it. - In general the first time you run PTCLM for a new site you want it to generate new datasets, but the next time and future times you want to use this option so that it doesn't waste a lot of time rebuilding datasets over again. - - .. note:: This option is required when you you are using a site that is a supported single point dataset. - -``--owritesrfaer`` - This option says to overwrite any surface and/or aerosol deposition datasets that were already created. - Otherwise, the creation of these files will be skipped if a file is already found (but it WILL create files if they don't exist). - This option must NOT be used when you you are using a site that is a supported single point dataset. From e2bb9b23d2128b80a753dd7849d88aba9e5ad37e Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 28 Jun 2018 14:30:30 -0600 Subject: [PATCH 182/255] Update build --- doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst index 50476e0261..1eaf471739 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -111,8 +111,7 @@ Here we give a simple example of using PTCLMmkdata for a straightforward case of Note, see `the Section called Converting AmeriFlux Data for use by PTCLMmkdata `_ for permission information to use this data. Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne ----------------------------------------------------------------- - +------------------------------------------------------------------ :: > setenv CSMDATA $CESMDATAROOT/inputdata From 29943cc54e605d4a22e5a5330f18d2c95b1ff8fc Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 29 Jun 2018 14:58:25 -0600 Subject: [PATCH 183/255] Work on trouble-shooting and testing chapters --- doc/source/users_guide/testing/testing.rst | 57 ++-- .../trouble-shooting/trouble-shooting.rst | 313 +----------------- 2 files changed, 31 insertions(+), 339 deletions(-) diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index 0594bc9157..04f90fc3d3 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -21,44 +21,41 @@ CIME Testing scripts We first introduce the test scripts that work for all CESM components. The CIME script **create_test** runs a specific type of test, at a given resolution, for a given compset using a given machine. -There is a list of different tests, but the "ERI" tests do several things at once, running from startup, as well as doing exact branch and restart tests. -So to run "ERI" testing at 2-degree with the I1850CRUCLM45 compset on cheyenne_intel you do the following. -:: +See `CIME Chapter on Testing `_ for how to use it to run single +tests as well as lists of tests. The standard testname for CLM is "aux_clm" for cheyenne with intel and gnu compilers as +well as the CGD machine hobart for intel, nag, and pgi compilers. There's also a shorter test list called "clm_short". Also +see the `CTSM Wiki on Testing `_. - > cd scripts - > ./create_test -testname ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel - > cd ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel.$id - > ./ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel.$id.build - > ERI.f19_g17_gl4.I1850CRUCLM45.cheyenne_intel.$id.submit +CTSM Tools Testing +================== -When the test is done it will update the file TestStatus with either a PASS or FAIL message. +.. include:: ../../clm5.0/test/tools/README + :literal: -We already have a standard list of tests for clm (the "aux_clm" list of tests). To run the CLM cheyenne intel compiler test list, for the same machine and compiler you would do the following: -:: +CTSM Fortran Unit Tests +======================= - > cd scripts - > ./create_test -xml_mach cheyenne -xml_compiler intel -xml_category aux_clm -mach cheyenne -compiler intel - # Normally it will submit the jobs as they are ready, but if it's interrupted you - # may need to submit by hand as follows... - # Submit the suite of tests (note $id refers to the integer job number for this job) - > ./cs.submit.$id.cheyenne - # Later check the tests with... - > ./cs.status.$id - # The above will give a PASS or FAIL message for each test. +.. include:: ../../clm5.0/src/README.unit_testing + :literal: + +CTSM Build-namelist Tests +========================= + +Run the following perl tester that + +:: + > cd bld/unit_testers + > ./build-namelist_test.pl -For more information on doing testing with the CESM scripts see the `|cesmrelease| User's Guide `_ on testing. Testing PTCLM ============= -There is a simple test script for PTCLM called ``testcases.csh`` in the PTCLM directory (``scripts/ccsm_utils/Tools/lnd/clm/PTCLM``). -The test script is setup to run on the machines: cheyenne, frankfurt, yong, and titan. -You simply run the script interactively. -The script will write out the status of tests to a file called: ``tc.job#.status``. +.. include:: ../../clm5.0/tools/PTCLM/README + :literal: + +To run on cheyenne, you do the following: -There are a few environment variables that can be used with ``testcases.csh`` to change it's operation. -``CESM_ROOT``: To test with a separate root to CESM code set this env variable to the root directory to use. -``CLM_SOFF``: If set to ``TRUE`` - stop on first failed test rather than continuing to run. -``CLM_RETAIN_FILES``: If set to ``FALSE`` - cleanup tools build first. -``DEBUG``: If set to ``TRUE`` - setup cases, but do not build or run. +.. include:: ../../clm5.0/tools/PTCLM/test/README.run_cheyenne + :literal: diff --git a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst index c7e38cf645..9af807041f 100644 --- a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst +++ b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst @@ -10,318 +10,13 @@ In this chapter we give some guidance on what to do when you encounter some of t In general you will run into one of three type of problems: -1. *setup-time* +1. *case-creation* +#. *setup-time* #. *build-time* #. *run-time* +See the `CIME Trouble Shooting Guide `_ for some help on the first three. -Setup Problems -============== - -The first type of problem happens when you invoke the **case.setup** command. -This indicates there is something wrong with your input datasets, or the details of what you are trying to setup the model to do. -There's also a trouble-shooting chapter in the `|cesmrelease| Scripts User's Guide `_. -Many of the problems with configuration can be resolved with the guidelines given there. -Here we will restrict ourselves to problems from the input files. - -Example: Missing datasets ----------------------------------------------------------------- -:: - - > ./create_newcase -case ne60rcp6 -res ne60_g16 -compset IRCP60CN \ - -mach cheyenne_intel - > ./case.setup - -The following is what is displayed to the screen. -:: - - . - . - . - Running preview_namelist script - CLM configure done. - CLM adding use_case 1850-2100_rcp6_transient defaults for var clm_demand with val fpftdyn - CLM adding use_case 1850-2100_rcp6_transient defaults for var clm_start_type with val startup - CLM adding use_case 1850-2100_rcp6_transient defaults for var model_year_align_ndep with val 1850 - CLM adding use_case 1850-2100_rcp6_transient defaults for var rcp with val 6 - CLM adding use_case 1850-2100_rcp6_transient defaults for var sim_year with val 1850 - CLM adding use_case 1850-2100_rcp6_transient defaults for var sim_year_range with val 1850-2100 - CLM adding use_case 1850-2100_rcp6_transient defaults for var stream_year_first_ndep with val 1850 - CLM adding use_case 1850-2100_rcp6_transient defaults for var stream_year_last_ndep with val 2100 - CLM adding use_case 1850-2100_rcp6_transient defaults for var use_case_desc with val Simulate transient land-use, aerosol and Nitrogen deposition changes - with historical data from 1850 to 2005 and then with the RCP6 scenario from AIM - - build-namelist - No default value found for fpftdyn. - Are defaults provided for this resolution and land mask? - ERROR: clm.buildnml.csh failed - ERROR: /Users/erik/clm_cesm1_1_1_rel/scripts/ne60rcp6/preview_namelists failed: 25344 - -The important thing to note here is the line: -:: - - ERROR: clm.buildnml.csh failed - -which tells us that the problem is in the land **clm.buildnml.csh**. It may also indicate problems in one of the other buildnml.csh files (atm, cesm, cpl, glc, ice, or ocn), in which case you should consult the appropriate model user's guide. - -In the example, the error is that the CLM XML database does NOT have a ``finidat`` for the given resolution, rcp scenario and ocean mask. That means you will need to create the file and then supply the file into your case. See `Chapter 2 `_ for more information on creating files, and see `Chapter 3 `_ for more information on adding files to the XML database. Alternatively, you can provide the file to your case by creating a user namelist as shown in `the Section called User Namelist in Chapter 1 `_. - -.. note:: The two most common problems from your **clm.buildnml.csh** will be errors from the CLM **configure** or **build-namelist**. For more information on these scripts see: `the Section called More information on the CLM configure script in Chapter 1 `_ and `the section on CLM_BLDNML_OPTS `_. - - -Build problems -================ - -The following is an example of running the build for a case and having it fail in the land model build. -As you can see it lists which model component is being built and the build log for that component. -:: - - CCSM BUILDEXE SCRIPT STARTING - - Build Libraries: mct pio csm_share - Sat Jun 19 21:21:19 MDT 2010 /ptmp/erik/test_build/mct/mct.bldlog.100619-212107 - Sat Jun 19 21:22:18 MDT 2010 /ptmp/erik/test_build/pio/pio.bldlog.100619-212107 - Sat Jun 19 21:23:18 MDT 2010 - /ptmp/erik/test_build/csm_share/csm_share.bldlog.100619-212107 - Sat Jun 19 21:24:00 MDT 2010 /ptmp/erik/test_build/run/cpl.bldlog.100619-212107 - Sat Jun 19 21:24:00 MDT 2010 /ptmp/erik/test_build/run/atm.bldlog.100619-212107 - Sat Jun 19 21:24:06 MDT 2010 /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 - ERROR: clm.buildexe.csh failed, see /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 - ERROR: cat /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 - -You can then examine the build log that failed and see what went wrong. Most compilers will give the full filepath and line number for the file that filed to compile. - -Run Time Problems -================= - -Tracking down problems while the model is running is much more difficult to do than setup or build problems. -In this section we will give some suggestions on how to find run time problems. -Below we show the log file results of a job that aborted while running. -:: - - CCSM PRESTAGE SCRIPT HAS FINISHED SUCCESSFULLY - Sun Jun 20 18:24:06 MDT 2010 -- CSM EXECUTION BEGINS HERE - Sun Jun 20 18:24:35 MDT 2010 -- CSM EXECUTION HAS FINISHED - Model did not complete - see /ptmp/erik/test_run/run/cpl.log.100620-182358 - -In the next section we will talk about using the different log files to track down problems, and find out where the problem is coming from. In the section after that we give some general advice on debugging problems and some suggestions on ideas that may be helpful to track the problem down. Some of the examples below are from the `$CTSMROOT/doc/KnownBugs `_ file. - -Tracking Problems by Querying Log Files ---------------------------------------- - -The first thing to do when tracking down problems is to query the different log files to see if you can discover where the problem occurs, and any error messages about it. -It's important to figure out if the problem comes in at initialization or in the run phase of the model, and in which model component the problem happens. -There are different log files for the different major components, and they all end with the date and time in YYMMDD-HHMMSS format (2-digit: year, month, day, hour minute and second). -When the model runs to completion the log files will be copied to the logs directory in the script directory, but when the model fails they will remain in the run directory. -Here's an example list of log files from an "I" case where the model dies in the land model initialization. -For "I" cases the sea-ice and ocean components are just stubs and don't create log files (and unless running with the active land-ice model "glc" log files won't be created either). -:: - - atm.log.100620-182358 - cesm.log.100620-182358 - cpl.log.100620-182358 - lnd.log.100620-182358 - -The coupler log file --------------------- - -The first log file to check is the coupler log file so that you can see where the model dies and which model component it fails in. When the model dies at initialization the last model component listed is the component that failed. - -Example of a case that fails in the CLM land model initialization. -:: - - (seq_timemgr_clockPrint) Prev Time = 00001201 00000 - (seq_timemgr_clockPrint) Next Time = 99991201 00000 - (seq_timemgr_clockPrint) Intervl yms = 9999 0 0 - - (seq_mct_drv) : Initialize each component: atm, lnd, ocn, and ice - (seq_mct_drv) : Initialize atm component - (seq_mct_drv) : Initialize lnd component - -The cesm log file ------------------ - -The cesm log files are to some extent the "garbage collection" of log output. -The CLM sends it's output from it's master processor, but sends other output and possibly errors to the cesm log file. -Because, of this, often error messages are somewhere in the cesm log file. -However, since there is so much other output it may be difficult to find. -For example, here is some output from an older version of CESM (CESM1.0.2) where the RTM river routing file (before it was converted to NetCDF) was not provided and the error on the open statement for the file was embedded near the end of the cesm log file. -:: - - NODE# NAME - ( 0) be1105en.ucar.edu - "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/$CTSMROOT/src/riverroute/RtmMod.F90", line - 239: 1525-155 The file name provided in the OPEN statement for unit 1 has zero length or - contains all blanks. The program will recover by ignoring the OPEN statement. - "/gpfs/proj2/fis/cgd/home/erik/clm_trunk/$CTSMROOT/src/riverroute/RtmMod.F90", line - 241: 1525-001 The READ statement on the file fort.1 cannot be completed because the end - of the file was reached. The program will stop. - - Running: ./cesm.exe - Please wait... - - Memory usage for ./cesm.exe (task # 0) is: 51696 KB. Exit status: 1. Signal: 0 - -Although the example is from an earlier version of the model it still serves to illustrate finding problems from the cesm log file. - -When working with the cesm log file, for a run-time problem, you will need to be able to separate it's output into three categories: pre-crash, crash, and post-crash. -The pre-crash section is everything that is normal output for good operation of the model. -The crash section is the section where the model dies and reports on the actual problem. -the post-crash section is the cleanup and finalization after the model dies. -The most important part of this of course is the crash section. -The tricky part is distinguishing it from the other sections. -Also because the cesm log file most likely has duplicated output from multiple processors it is even more difficult to distinguish the different sections and to some extent the sections may be intertwined, as different processors reach the different sections at different times. -Because, of this reducing the number of processors for your simulation may help you sort out the output in the file (see `the Section called Run with a smaller set of processors `_). -Also much of the output from the cesm log file are system level information having to do with MPI multiprocessing. -Usually you can ignore this information, but it makes it more difficult to trudge through. - - -Sometimes the cesm log file is the ONLY file available, because the model terminates early in initialization. -In this case understanding the output in the cesm log file becomes even more important. -This also indicates the model did NOT advance far enough to reach the initialization of the individual model components. -This may mean that the initialization of the multiprocessing for MPI and/or OpenMP failed, or that the reading of the driver namelist file "drv_in" failed. - - -Here we show those three sections for a cesm log file where a two task job failed on reading the namelist file. -For a typical job with many tasks similar sections of this will be repeated not just twice but for each task and hence make it harder to read. - - -*Pre-crash section of the cesm log file* -:: - - ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. - - ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. - ATTENTION: 0031-378 MP_EUIDEVICE setting ignored when LoadLeveler is not being used. - ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. - 0:INFO: 0031-724 Executing program: - 1:INFO: 0031-724 Executing program: - 0:/contrib/bin/cesm_launch: process 401894 bound to logical CPU 0 on host be0310en.ucar.edu ... - 1:/contrib/bin/cesm_launch: process 439264 bound to logical CPU 1 on host be0310en.ucar.edu ... - 0:INFO: 0031-619 64bit(us, Packet striping on) ppe_rmas MPCI_MSG: MPI/MPCI library was compiled on Wed Aug 5 13:36:06 2009 - 0: - 1:LAPI version #14.26 2008/11/23 11:02:30 1.296 src/rsct/lapi/lapi.c, lapi, rsct_rpt53, rpt53s004a 09/04/29 64bit(us) library compiled on Wed Apr 29 15:30:42 2009 - 1:. - 1:LAPI is using lightweight lock. - 0:LAPI version #14.26 2008/11/23 11:02:30 1.296 src/rsct/lapi/lapi.c, lapi, rsct_rpt53, rpt53s004a 09/04/29 64bit(us) library compiled on Wed Apr 29 15:30:42 2009 - 0:. - 0:LAPI is using lightweight lock. - 0:Use health ping for failover/recovery - 1:Use health ping for failover/recovery - 0:Initial communication over instance 2. - 1:Initial communication over instance 0. - 1:IB RDMA initialization completed successfully - 1:The MPI shared memory protocol is used for the job - 0:IB RDMA initialization completed successfully - 0:LAPI job ID for this job is: 1684890719 - 0:The MPI shared memory protocol is used for the job - 0:(seq_comm_setcomm) initialize ID ( 7 GLOBAL ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 2 ATM ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 1 LND ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 4 ICE ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 5 GLC ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 3 OCN ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 6 CPL ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 8 CPLATM ) join IDs = 6 2 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 9 CPLLND ) join IDs = 6 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 10 CPLICE ) join IDs = 6 4 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 11 CPLOCN ) join IDs = 6 3 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 12 CPLGLC ) join IDs = 6 5 ( npes = 2) ( nthreads = 1) - 0: - 0: (seq_comm_printcomms) ID layout : global pes vs local pe for each ID - 0: gpe LND ATM OCN ICE GLC CPL GLOBAL CPLATM CPLLND CPLICE CPLOCN CPLGLC nthrds - 0: --- ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ - 0: 0 : 0 0 0 0 0 0 0 0 0 0 0 0 1 - 1: 1 : 1 1 1 1 1 1 1 1 1 1 1 1 1 - 1: - 0: (t_initf) Read in prof_inparm namelist from: drv_in - 1: (seq_io_init) cpl_io_stride, iotasks or root out of bounds - resetting to defaults 4 0 1 - 0: piolib_mod.f90 1353 1 2 1 2 - 1: piolib_mod.f90 1353 1 2 1 2 - 0: pio_support::pio_die:: myrank= 0 : ERROR: piolib_mod.f90: 1354 : not enough procs for the stride - 1: pio_support::pio_die:: myrank= 1 : ERROR: piolib_mod.f90: 1354 : not enough procs for the stride - -*Crash section of the cesm log file* -:: - - 0: - 0: Traceback: - 1: - 1: Traceback: - 0: Offset 0x00000c4c in procedure __pio_support_NMOD_piodie, near line 88 in file pio_support.F90.in - 1: Offset 0x00000c4c in procedure __pio_support_NMOD_piodie, near line 88 in file pio_support.F90.in - 0: Offset 0x00000fd0 in procedure __piolib_mod_NMOD_init, near line 1354 in file piolib_mod.F90 - 1: Offset 0x00000fd0 in procedure __piolib_mod_NMOD_init, near line 1354 in file piolib_mod.F90 - 1: Offset 0x00000398 in procedure __seq_io_mod_NMOD_seq_io_init, near line 247 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/shr/seq_io_mod.F90 - 0: Offset 0x00000398 in procedure __seq_io_mod_NMOD_seq_io_init, near line 247 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/shr/seq_io_mod.F90 - 0: Offset 0x0001aa88 in procedure ccsm_driver, near line 465 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/driver/ccsm_driver.F90 - 0: --- End of call chain --- - 1: Offset 0x0001aa88 in procedure ccsm_driver, near line 465 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/driver/ccsm_driver.F90 - 1: --- End of call chain --- - -*Post-crash section of the cesm log file* -:: - - 1:Communication statistics of task 1 is associated with task key: 1684890719_1 - 0:Communication statistics of task 0 is associated with task key: 1684890719_0 - 0: - 0:Running: ./cesm.exe - 0:Please wait... - 0: - 0:Memory usage for ./cesm.exe (task # 0) is: 198892 KB. Exit status: 134. Signal: 0 - 1: - 1:Running: ./cesm.exe - 1:Please wait... - 1: - 1:Memory usage for ./cesm.exe (task # 0) is: 198572 KB. Exit status: 134. Signal: 0 - INFO: 0031-656 I/O file STDOUT closed by task 0 - INFO: 0031-656 I/O file STDERR closed by task 0 - ERROR: 0031-250 task 0: IOT/Abort trap - INFO: 0031-656 I/O file STDOUT closed by task 1 - INFO: 0031-656 I/O file STDERR closed by task 1 - ERROR: 0031-250 task 1: IOT/Abort trap - INFO: 0031-639 Exit status from pm_respond = 0 - ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. - Job /usr/local/lsf/7.0/aix5-64/bin/poejob /contrib/bin/ccsm_launch /contrib/bin/job_memusage.exe ./cesm.exe - - TID HOST_NAME COMMAND_LINE STATUS TERMINATION_TIME - ===== ========== ================ ======================= =================== - 00000 be0310en /contrib/bin/ccs Exit (134) 08/31/2010 12:32:57 - 00001 be0310en /contrib/bin/ccs Exit (134) 08/31/2010 12:32:57 - -The CLM log file ----------------- - -Of course when you are working with and making changes to CLM, most of your focus will be on the CLM log file and the errors it shows. -As already pointed out if you don't see errors in the ``lnd.log.*`` file you should look in the ``cesm.log.*`` to see if any errors showed up there. - -Here's an example of the ``lnd.log.*`` file when running ``PTS_MODE`` with initial conditions (this is bug 1025 in the `$CTSMROOT/doc/KnownLimitationss `_ file). -:: - - Successfully initialized variables for accumulation - - reading restart file I2000CN_f09_g17_gl4_c100503.clm2.r.0001-01-01-00000.nc - Reading restart dataset - ERROR - setlatlon.F:Cant get variable dim for lat or lsmlat - ENDRUN: called without a message string - -The DATM log file ------------------ - -When working with "I cases" the second most common problems after CLM problems are problems with the data atmosphere model. So examining the ``atm.log.*`` is important. - -Here's an example of a problem that occurs when the wrong prescribed aerosol file is given to a ``pt1_pt1`` simulation. -:: - - (datm_comp_init) atm mode = CLMNCEP - (shr_strdata_init) calling shr_dmodel_mapSet for fill - (shr_strdata_init) calling shr_dmodel_mapSet for remap - ('shr_map_getWts') ERROR: yd outside bounds 19.5000000000000000 - (shr_sys_abort) ERROR: ('shr_map_getWts') ERROR yd outside 90 degree bounds - (shr_sys_abort) WARNING: calling shr_mpi_abort() and stopping - -The batch log files -------------------- - -The names of the batch log files will depend on the batch system of the machine that is being used. They will normally be in the script directory. Usually, they don't contain important information, but they are a last resort place to look for error messages. On the NCAR system "cheyenne" the batch files are called with names that start with the batch submission script and then either "stderr.o" or "stdout.o", with the job number at the end. General Advice on Debugging Run time Problems ============================================= @@ -389,7 +84,7 @@ Along the same lines, you might try running a simpler case, trying another comps Run with a debugger ------------------- -Another suggestion is to run the model with a debugger such as: **dbx**, **gdb**, or **totalview**. +Another suggestion is to run the model with a debugger such as: **ddt**, **dbx**, **gdb**, or **totalview**. Often to run with a debugger you will need to reduce the number of processors as outlined above. Some debuggers such as **dbx** will only work with one processor, while more advanced debuggers such as **totalview** can work with both MPI tasks and OMP threads. Even simple debuggers though can be used to query core files, to see where the code was at when it died (for example using the **where** in **dbx** for a core file can be very helpful. From 910793f522db57edb85fd3fa5866ed2d17c694e5 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Sat, 30 Jun 2018 14:28:51 -0600 Subject: [PATCH 184/255] Do a fresh new build of everything --- doc/Makefile | 2 +- doc/Makefile.tech_note | 2 +- doc/Makefile.users_guide | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 6d3ce5f50d..6e8d96d485 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -17,4 +17,4 @@ help: # 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) \ No newline at end of file + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/Makefile.tech_note b/doc/Makefile.tech_note index 07ebab36e6..3ba843c70e 100644 --- a/doc/Makefile.tech_note +++ b/doc/Makefile.tech_note @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile.tech_note - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/Makefile.users_guide b/doc/Makefile.users_guide index 08562d18ca..babfffa52c 100644 --- a/doc/Makefile.users_guide +++ b/doc/Makefile.users_guide @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile.users_guide - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 2aabc98bef5307b599c84242ff2ad60c0ba0d0b7 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Sat, 30 Jun 2018 15:42:12 -0600 Subject: [PATCH 185/255] Renames to get rid of hardwired chapter names and rebuild --- ...ns-or-New-Files-to-the-build-namelist-Database.rst} | 0 ...esolution-Names.rst => Adding-Resolution-Names.rst} | 0 ...es.rst => Adding-or-Changing-Default-Filenames.rst} | 0 .../users_guide/adding-new-resolutions/index.rst | 6 +++--- ...LM-with-transient-historical-CO2-concentration.rst} | 0 ...ata-as-atmospheric-forcing-to-spinup-the-model.rst} | 0 ...ion-as-atmospheric-forcing-to-spinup-the-model.rst} | 0 ...-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst} | 0 ... => Spinning-up-the-biogeochemistry-BGC-spinup.rst} | 0 doc/source/users_guide/running-special-cases/index.rst | 10 +++++----- 10 files changed, 8 insertions(+), 8 deletions(-) rename doc/source/users_guide/adding-new-resolutions/{CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst => Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst} (100%) rename doc/source/users_guide/adding-new-resolutions/{CLM-3.2-Adding-Resolution-Names.rst => Adding-Resolution-Names.rst} (100%) rename doc/source/users_guide/adding-new-resolutions/{CLM-3.3-Adding-or-Changing-Default-Filenames.rst => Adding-or-Changing-Default-Filenames.rst} (100%) rename doc/source/users_guide/running-special-cases/{CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst => Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst} (100%) rename doc/source/users_guide/running-special-cases/{CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst => Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst} (100%) rename doc/source/users_guide/running-special-cases/{CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst => Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst} (100%) rename doc/source/users_guide/running-special-cases/{CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst => Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst} (100%) rename doc/source/users_guide/running-special-cases/{CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst => Spinning-up-the-biogeochemistry-BGC-spinup.rst} (100%) diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst b/doc/source/users_guide/adding-new-resolutions/Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst similarity index 100% rename from doc/source/users_guide/adding-new-resolutions/CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst rename to doc/source/users_guide/adding-new-resolutions/Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst similarity index 100% rename from doc/source/users_guide/adding-new-resolutions/CLM-3.2-Adding-Resolution-Names.rst rename to doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst diff --git a/doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst similarity index 100% rename from doc/source/users_guide/adding-new-resolutions/CLM-3.3-Adding-or-Changing-Default-Filenames.rst rename to doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst diff --git a/doc/source/users_guide/adding-new-resolutions/index.rst b/doc/source/users_guide/adding-new-resolutions/index.rst index 97d97b0cc0..88bbda3f5b 100644 --- a/doc/source/users_guide/adding-new-resolutions/index.rst +++ b/doc/source/users_guide/adding-new-resolutions/index.rst @@ -14,6 +14,6 @@ Adding New Resolutions .. toctree:: :maxdepth: 2 - CLM-3.0-Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst - CLM-3.2-Adding-Resolution-Names.rst - CLM-3.3-Adding-or-Changing-Default-Filenames.rst + Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst + Adding-Resolution-Names.rst + Adding-or-Changing-Default-Filenames.rst diff --git a/doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst b/doc/source/users_guide/running-special-cases/Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst similarity index 100% rename from doc/source/users_guide/running-special-cases/CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst rename to doc/source/users_guide/running-special-cases/Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst diff --git a/doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst similarity index 100% rename from doc/source/users_guide/running-special-cases/CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst rename to doc/source/users_guide/running-special-cases/Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst diff --git a/doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst b/doc/source/users_guide/running-special-cases/Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst similarity index 100% rename from doc/source/users_guide/running-special-cases/CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst rename to doc/source/users_guide/running-special-cases/Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst diff --git a/doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst similarity index 100% rename from doc/source/users_guide/running-special-cases/CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst rename to doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst diff --git a/doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst similarity index 100% rename from doc/source/users_guide/running-special-cases/CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst rename to doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst index 18ef7a96b0..f063992c67 100644 --- a/doc/source/users_guide/running-special-cases/index.rst +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -17,8 +17,8 @@ Running Special Cases what-is-a-special-case.rst running-the-prognostic-crop-model.rst running-with-irrigation.rst - CLM-4.3-Spinning-up-the-Satellite-Phenology-Model-(CLMSP-spinup).rst - CLM-4.4-Spinning-up-the-CLM5.0-biogeochemistry-(CLMBGC-spinup).rst - CLM-4.7-Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst - CLM-4.8-Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst - CLM-4.9-Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst + Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst + Spinning-up-the-biogeochemistry-BGC-spinup.rst + Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst + Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst + Running-stand-alone-CLM-with-transient-historical-CO2-concentration.rst From 9558e7844814d10335ab13c4d4920876d60aae41 Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Thu, 12 Jul 2018 15:29:26 -0600 Subject: [PATCH 186/255] Added a reference for g1 values and two tables, one with target leaf CN, another with SLAtop and flnr --- .../CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 56 ++++++++++++++++- .../CLM50_Tech_Note_Crop_Irrigation.rst | 2 +- .../CLM50_Tech_Note_Photosynthesis.rst | 3 +- ...LM50_Tech_Note_Photosynthetic_Capacity.rst | 61 ++++++++++++++++++- .../References/CLM50_Tech_Note_References.rst | 9 +++ 5 files changed, 126 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index 469bc96f33..14704b0b5f 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -54,7 +54,7 @@ Tissue Stoichiometry As of CLM5, vegetation tissues have a flexible stoichiometry, as described in :ref:`Ghimire et al. (2016) `. Each -tissue has a target C\:N ratio, and nitrogen is allocated at each +tissue has a target C\:N ratio (see :numref:`Table Plant functional type (PFT) target CN parameters`), and nitrogen is allocated at each timestep in order to allow the plant to best match the target stoichiometry. Nitrogen downregulation of productivity acts by increasing the C\:N ratio of leaves when insufficient nitrogen is @@ -63,3 +63,57 @@ reducing the N available for photosynthesis and reducing the :math:`V_{\text{c,m :math:`J_{\text{max25}}` terms, as described in Chapter :numref:`rst_Photosynthetic Capacity`. Details of the flexible tissue stoichiometry are described in Chapter :numref:`rst_CN Allocation`. + +.. _Table Plant functional type (PFT) target CN parameters: + +.. table:: Plant functional type (PFT) target C:N parameters. + + +----------------------------------+-------------------+ + | PFT | target leaf C:N | + +==================================+===================+ + | NET Temperate | 58.00 | + +----------------------------------+-------------------+ + | NET Boreal | 58.00 | + +----------------------------------+-------------------+ + | NDT Boreal | 25.81 | + +----------------------------------+-------------------+ + | BET Tropical | 29.60 | + +----------------------------------+-------------------+ + | BET temperate | 29.60 | + +----------------------------------+-------------------+ + | BDT tropical | 23.45 | + +----------------------------------+-------------------+ + | BDT temperate | 23.45 | + +----------------------------------+-------------------+ + | BDT boreal | 23.45 | + +----------------------------------+-------------------+ + | BES temperate | 36.42 | + +----------------------------------+-------------------+ + | BDS temperate | 23.26 | + +----------------------------------+-------------------+ + | BDS boreal | 23.26 | + +----------------------------------+-------------------+ + | C\ :sub:`3` arctic grass | 28.03 | + +----------------------------------+-------------------+ + | C\ :sub:`3` grass | 28.03 | + +----------------------------------+-------------------+ + | C\ :sub:`4` grass | 35.36 | + +----------------------------------+-------------------+ + | Temperate Corn | 25.00 | + +----------------------------------+-------------------+ + | Spring Wheat | 20.00 | + +----------------------------------+-------------------+ + | Temperate Soybean | 20.00 | + +----------------------------------+-------------------+ + | Cotton | 20.00 | + +----------------------------------+-------------------+ + | Rice | 20.00 | + +----------------------------------+-------------------+ + | Sugarcane | 25.00 | + +----------------------------------+-------------------+ + | Tropical Corn | 25.00 | + +----------------------------------+-------------------+ + | Tropical Soybean | 20.00 | + +----------------------------------+-------------------+ + + diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index fb6a180edd..8f0b975fce 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -372,7 +372,7 @@ Harvest occurs in one time step using the BGC leaf offset algorithm. Notes: :math:`Date_{planting}^{min}` and :math:`Date_{planting}^{max}` are the minimum and maximum planting date in the Northern Hemisphere, the corresponding dates in the Southern Hemisphere apply 6 months later. -:math:`T_{p}` and :math:`T_{p}^{ min }` are crop-specific coldest planting temperatures. +:math:`T_{p}` and :math:`T_{p}^{ min }` are crop-specific average and coldest planting temperatures, respectively. :math:`{GDD}_{min}` is the lowest (for planting) 20-year running mean growing degree-days based on the base temperature threshold in the 7\ :sup:`th` row, tracked from April to September (NH). :math:`{GDD}_{mat}` is a crop’s 20-year running mean growing diff --git a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst index 84136f7868..f7171f1a10 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -66,7 +66,8 @@ photosynthesis (:math:`\mu`\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`), :math:`c_{s}` is the CO\ :sub:`2` partial pressure at the leaf surface (Pa), :math:`P_{atm}` is the atmospheric pressure (Pa), and :math:`D` is the vapor pressure deficit at the leaf surface (kPa). -:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`). +:math:`g_{1}` is a plant functional type dependent parameter (:numref:`Table Plant functional type (PFT) stomatal conductance parameters`) +and are the same as those used in the CABLE model (:ref:`de Kauwe et al. 2015 `). The value for :math:`g_{o}=100` :math:`\mu` mol m :sup:`-2` s\ :sup:`-1` for C\ :sub:`3` and C\ :sub:`4` plants. diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index 4c3e857ade..c75c9f2b39 100755 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -82,7 +82,64 @@ multiplication of leaf mass per unit area (:math:`\text{LMA}`; g biomass/m :sup: N_{\text{str}} = \text{SNC} \cdot \text{LMA} -where :math:`\text{SNC}` is set to be fixed at 0.002 (gN/g biomass), based on data on C:N ratio from dead wood (White etal.,2000). +where :math:`\text{SNC}` is set to be fixed at 0.002 (gN/g biomass), based on data on C:N ratio from dead wood (White etal.,2000), +and :math:`\text{LMA}` is the inverse of specific leaf area at the canopy top (:math:`SLA_{\text{0}}`), a PFT-level parameter (:numref:`Table Plant functional type (PFT) leaf N parameters`). + +.. _Table Plant functional type (PFT) leaf N parameters: + +.. table:: Plant functional type (PFT) leaf N parameters. + + +----------------------------------+--------------------------+--------------------------+ + | PFT | :math:`SLA_{\text{0}}` | :math:`N_{\text{cb}}` | + +==================================+==========================+==========================+ + | NET Temperate | 0.0100 | 0.0509 | + +----------------------------------+--------------------------+--------------------------+ + | NET Boreal | 0.0100 | 0.0466 | + +----------------------------------+--------------------------+--------------------------+ + | NDT Boreal | 0.0202 | 0.0546 | + +----------------------------------+--------------------------+--------------------------+ + | BET Tropical | 0.0190 | 0.0461 | + +----------------------------------+--------------------------+--------------------------+ + | BET temperate | 0.0190 | 0.0515 | + +----------------------------------+--------------------------+--------------------------+ + | BDT tropical | 0.0308 | 0.0716 | + +----------------------------------+--------------------------+--------------------------+ + | BDT temperate | 0.0308 | 0.1007 | + +----------------------------------+--------------------------+--------------------------+ + | BDT boreal | 0.0308 | 0.1007 | + +----------------------------------+--------------------------+--------------------------+ + | BES temperate | 0.0180 | 0.0517 | + +----------------------------------+--------------------------+--------------------------+ + | BDS temperate | 0.0307 | 0.0943 | + +----------------------------------+--------------------------+--------------------------+ + | BDS boreal | 0.0307 | 0.0943 | + +----------------------------------+--------------------------+--------------------------+ + | C\ :sub:`3` arctic grass | 0.0402 | 0.1365 | + +----------------------------------+--------------------------+--------------------------+ + | C\ :sub:`3` grass | 0.0402 | 0.1365 | + +----------------------------------+--------------------------+--------------------------+ + | C\ :sub:`4` grass | 0.0385 | 0.0900 | + +----------------------------------+--------------------------+--------------------------+ + | Temperate Corn | 0.0500 | 0.2930 | + +----------------------------------+--------------------------+--------------------------+ + | Spring Wheat | 0.0350 | 0.4102 | + +----------------------------------+--------------------------+--------------------------+ + | Temperate Soybean | 0.0350 | 0.4102 | + +----------------------------------+--------------------------+--------------------------+ + | Cotton | 0.0350 | 0.4102 | + +----------------------------------+--------------------------+--------------------------+ + | Rice | 0.0350 | 0.4102 | + +----------------------------------+--------------------------+--------------------------+ + | Sugarcane | 0.0500 | 0.2930 | + +----------------------------------+--------------------------+--------------------------+ + | Tropical Corn | 0.0500 | 0.2930 | + +----------------------------------+--------------------------+--------------------------+ + | Tropical Soybean | 0.0350 | 0.4102 | + +----------------------------------+--------------------------+--------------------------+ + +Notes: :math:`SLA_{\text{0}}` is the specific leaf area at the canopy top (m :sup:`2` leaf/g biomass), +and :math:`N_{\text{cb}}` is the fraction of leaf nitrogen in Rubisco (g N in Rubisco g :sup:`-1` N) + We assume that plants optimize their nitrogen allocations (i.e., :math:`N_{\text{store}}`, :math:`N_{\text{resp}}`, :math:`N_{\text{lc}}`, :math:`N_{\text{et}}`, :math:`N_{\text{cb}}`) to maximize the photosynthetic carbon gain, defined as the gross photosynthesis ( :math:`A` ) minus the maintenance respiration for @@ -202,7 +259,7 @@ as in :ref:`Thornton and Zimmermann (2007)`. At 25ºC, where :math:`N_{str}` is the area-based leaf nitrogen concentration (g N m\ :sup:`-2` leaf area), :math:`N_{cb}` is the fraction of leaf -nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N), +nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N, :numref:`Table Plant functional type (PFT) leaf N parameters`), :math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and :math:`a_{R25} =60` is the specific activity of Rubisco (µmol diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index cafba90dc3..e6b2222c75 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -536,6 +536,15 @@ correspond with changes in labile organic C fractions in soil amended with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): 453-462. +.. _deKauwe2015: + +|br| + +de Kauwe, D.A., Kala, J., Lin, Y.-S., Pitman, A.J., Medlyn, B.E., Duursma, R.A., +Abramowitz, G., Wang, Y.-P., Miralles, D.G. 2015. A test of an optimal stomatal +conductance scheme within the CABLE land surface model. Geosci. Model Dev. +8(2):431-452. + .. _deVries1963: |br| From 91bdfba827a3b701877ed17e2b1ef5312fa5389d Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Mon, 16 Jul 2018 11:12:42 -0600 Subject: [PATCH 187/255] Updated the parameter values in Table 3 of the crop chapter, and adding clarifying text to the CN pools chapter --- doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 3 ++- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index 14704b0b5f..9bddee21ca 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -54,7 +54,8 @@ Tissue Stoichiometry As of CLM5, vegetation tissues have a flexible stoichiometry, as described in :ref:`Ghimire et al. (2016) `. Each -tissue has a target C\:N ratio (see :numref:`Table Plant functional type (PFT) target CN parameters`), and nitrogen is allocated at each +tissue has a target C\:N ratio, with the target leaf C\:N varying by plant functional type +(see :numref:`Table Plant functional type (PFT) target CN parameters`), and nitrogen is allocated at each timestep in order to allow the plant to best match the target stoichiometry. Nitrogen downregulation of productivity acts by increasing the C\:N ratio of leaves when insufficient nitrogen is diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 8f0b975fce..3b8f07f44c 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -565,9 +565,9 @@ efficiency of 85%. \ temperate corn spring wheat temperatue soybean cotton rice sugarcane tropical corn tropical soybean =========================================== ============== ============ ================== ====== ====== ========= ============= ================ IVT 17, 18 19, 20 23, 24 41, 42 61, 62 67, 68 75, 76 77, 78 - :math:`a_{leaf}^{i}` 0.8 0.9 0.85 0.85 0.75 0.8 0.8 0.85 + :math:`a_{leaf}^{i}` 0.6 0.9 0.85 0.85 0.75 0.6 0.6 0.85 :math:`{L}_{max}` (m :sup:`2` m :sup:`-2`) 5 7 6 6 7 5 5 6 - :math:`a_{froot}^{i}` 0.4 0.1 0.2 0.2 0.1 0.4 0.4 0.2 + :math:`a_{froot}^{i}` 0.1 0.05 0.2 0.2 0.1 0.1 0.1 0.2 :math:`a_{froot}^{f}` 0.05 0 0.2 0.2 0 0.05 0.05 0.2 :math:`a_{leaf}^{f}` 0 0 0 0 0 0 0 0 :math:`a_{livestem}^{f}` 0 0.05 0.3 0.3 0.05 0 0 0.3 From 634f4b3cbd55393b04ae6514dc45024815b18db7 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Mon, 10 Dec 2018 12:00:15 -0700 Subject: [PATCH 188/255] Update urban chapter and html --- .../References/CLM50_Tech_Note_References.rst | 16 +++++++++ .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 34 +++++++++++++++++-- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index e6b2222c75..fc807dd395 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -673,6 +673,14 @@ Nobel, C.B. Osmond, and H. Zeigler (editors) Encyclopedia of Plant Physiology. Vol. 12B. Physiological Plant Ecology. II. Water Relations and Carbon Assimilation. Springer-Verlag, New York. +.. _FeddemaKauffman2016: + +|br| + +Feddema, J., Kauffman, B. 2016. Urban Properties Tool (Version 1.2). +NCAR THESIS Tools Library. Retrieved from: https://svn-iam-thesis-release.cgd.ucar.edu/urban_properties/. +doi:10.5065/D6R78CMT. + .. _Ferrari1999: |br| @@ -1968,6 +1976,14 @@ Oleson, K.W., et al. 2013. Technical description of version 4.5 of the Community Land Model (CLM). NCAR Technical Note NCAR/TN-503+STR, National Center for Atmospheric Research, Boulder, CO, 420 pp. +.. _OlesonFeddema2018: + +|br| + +Oleson, K.W., and Feddema, J. 2018. Parameterization and surface data +improvements and new capabilities for the Community Land Model +Urban (CLMU). JAMES, submitted. + .. _Olson1963: |br| diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index e24ac723ea..e9d9261b0d 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -104,6 +104,26 @@ climate and socioeconomic considerations. The surface dataset creation routines (see CLM5.0 User’s Guide) aggregate the data to the desired resolution. +An optional urban properties dataset, including a tool that allows for generating future +urban development scenarios is also available (:ref:`Oleson and Feddema (2018) `). +This will become the default dataset in future model versions. +As described in :ref:`Oleson and Feddema (2018) ` the urban properties dataset +in :ref:`Jackson et al. (2010) ` was modified with respect to wall and roof thermal +properties to correct for biases in heat transfer due to layer and building type averaging. +Further changes to the dataset reflect the need for scenario development, thus allowing for +the creation of hypothetical wall types, and the easier interchange of wall facets. +The new urban properties tool is available as part of the Toolbox for Human-Earth System +Integration & Scaling (THESIS) tool set +(http://www.cgd.ucar.edu/iam/projects/thesis/thesis-urbanproperties-tool.html; +:ref:`Feddema and Kauffman (2016) `). The driver script (urban_prop.csh) +specifies three input csv files (by default, mat_prop.csv, +lam_spec.csv, and city_spec.csv; (:numref:`Figure schematic of THESIS urban properties tool`)) +that describe the morphological, radiative, and thermal properties of urban areas, and +generates a global dataset at 0.05° latitude by longitude in NetCDF format (urban_properties_data.05deg.nc). +A standalone NCL routine (gen_data_clm.ncl) can be run separately after the mksurfdata_map tool creates +the CLM surface dataset. This creates a supplementary streams file of setpoints for the maximum +interior building temperature at yearly time resolution. + .. Figure 12.1. Schematic representation of the urban land unit .. _Figure schematic representation of the urban landunit: @@ -120,6 +140,15 @@ resolution. Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section :numref:`Atmospheric Coupling`). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. +.. Figure 12.3. Schematic of THESIS urban properties tool + +.. _Figure schematic of THESIS urban properties tool: + +.. Figure:: image3.gif + + Schematic of THESIS urban properties tool. Executable scripts are in orange, input files are blue, and output files are green. Items within the black box outline are either read in as input, executed, or output by the driver script (urban_prop.csh). + + The urban model that was first released as a component of CLM4.0 is separately described in the urban technical note (:ref:`Oleson et al. (2010b) `). The main changes in the urban model from CLM4.0 to CLM4.5 were 1) @@ -143,8 +172,9 @@ variable. The maximum building temperatures that are defined in :ref:`Jackson et al. (2010) ` are implemented in year 1950 (thus air conditioning is off in prior years) and air conditioning is turned off in year 2100 (because the buildings are not suitable for air conditioning in some extreme -global warming scenarios). These feature will be described in more detail in -a forthcoming paper. In addition, a module of heat stress indices calculated online +global warming scenarios), 3) an optional updated urban properties dataset and new +scenario tool. These features are described in more detail in :ref:`Oleson and Feddema (2018) `. +In addition, a module of heat stress indices calculated online in the model that can be used to assess human thermal comfort for rural and urban areas has been added. This last development is described and evaluated by :ref:`Buzan et al. (2015) `. From 865da855e3840419e82fe2c26d1fe115aa18edba Mon Sep 17 00:00:00 2001 From: Danica Lombardozzi Date: Tue, 18 Dec 2018 16:05:06 -0700 Subject: [PATCH 189/255] Updated Vcmax equation in Photosynthetic_Capacity chapter based on notes from Chonggang, and added new Rogers 2014 reference --- ...CLM50_Tech_Note_Photosynthetic_Capacity.rst | 18 ++++++++---------- .../References/CLM50_Tech_Note_References.rst | 6 ++++++ 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst index c75c9f2b39..c4dd5b03f9 100755 --- a/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst +++ b/doc/source/tech_note/Photosynthetic_Capacity/CLM50_Tech_Note_Photosynthetic_Capacity.rst @@ -140,7 +140,6 @@ and :math:`\text{LMA}` is the inverse of specific leaf area at the canopy top (: Notes: :math:`SLA_{\text{0}}` is the specific leaf area at the canopy top (m :sup:`2` leaf/g biomass), and :math:`N_{\text{cb}}` is the fraction of leaf nitrogen in Rubisco (g N in Rubisco g :sup:`-1` N) - We assume that plants optimize their nitrogen allocations (i.e., :math:`N_{\text{store}}`, :math:`N_{\text{resp}}`, :math:`N_{\text{lc}}`, :math:`N_{\text{et}}`, :math:`N_{\text{cb}}`) to maximize the photosynthetic carbon gain, defined as the gross photosynthesis ( :math:`A` ) minus the maintenance respiration for photosynthetic enzymes ( :math:`R_{\text{psn}}` ), under specific @@ -248,22 +247,21 @@ maximum photosynthetically active radiation during the day. Maximum rate of carboxylation '''''''''''''''''''''''''''''' -The maximum rate of carboxylation at 25 :sup:`o`\ C varies with +The maximum rate of carboxylation at 25\ :sup:`o`\ C varies with foliage nitrogen concentration and specific leaf area and is calculated as in :ref:`Thornton and Zimmermann (2007)`. At 25ºC, .. math:: :label: 10.11) - V_{c\max 25} =N_{str} N_{cb} F_{NR} a_{R25} + V_{c\max 25} = N_{cb} NUE_{V_{c\max 25}} -where :math:`N_{str}` is the area-based leaf nitrogen concentration (g N -m\ :sup:`-2` leaf area), :math:`N_{cb}` is the fraction of leaf -nitrogen in Rubisco (g N in Rubisco g\ :sup:`-1` N, :numref:`Table Plant functional type (PFT) leaf N parameters`), -:math:`F_{NR} =7.16` is the mass ratio of total Rubisco molecular mass -to nitrogen in Rubisco (g Rubisco g\ :sup:`-1` N in Rubisco), and -:math:`a_{R25} =60` is the specific activity of Rubisco (µmol -CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`). +where :math:`N_{cb}` is nitrogen for carboxylation (g N m\ :sup:`-2` leaf, +:numref:`Table Plant functional type (PFT) leaf N parameters`), +and :math:`NUE_{V_{c\max 25}}` = 47.3 x 6.25 and is the nitrogen use efficiency for :math:`V_{c\max 25}`. +The constant 47.3 is the specific Rubisco activity ( :math:`\mu` mol CO\ :sub:`2` g\ :sup:`-1` Rubisco s\ :sup:`-1`) +measured at 25\ :sup:`o`\ C, and the constant 6.25 is the nitrogen binding factor for Rubisco +(g Rubisco g\ :sup:`-1` N; :ref:`Rogers 2014`). :math:`V_{c\max 25}` additionally varies with daylength (:math:`DYL`) using the function :math:`f(DYL)`, which introduces seasonal variation diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index fc807dd395..c0fe7cc556 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -2254,6 +2254,12 @@ Meeting, Boulder, CO. Roesch, A., M. Wild, H. Gilgen, and A. Ohmura. 2001. A new snow cover fraction parametrization for the ECHAM4 GCM, Clim. Dyn., 17:933–946. +.. _Rogers2014: + +|br| + +Rogers, A., 2014: The use and misuse of Vcmax in Earth system models. Photosynt. Res., 119:1-15. + .. _Rogersetal2017: |br| From 8262c936047914e511d40512b1d469177f746f9b Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 31 Jan 2019 15:21:52 -0700 Subject: [PATCH 190/255] Fix Jackie's name and update html --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index e5a075cca5..ed4fcb234c 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -14,7 +14,7 @@ ***Contributing Authors*** **Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathan Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, -L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** +L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacquelyn Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** The National Center for Atmospheric Research (NCAR) is operated by the From ca1e160e4eb3f5ec21efd9c30bbca051a172392c Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 31 Jan 2019 15:31:18 -0700 Subject: [PATCH 191/255] Revert "Fix Jackie's name and update html" This reverts commit 8262c936047914e511d40512b1d469177f746f9b. --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index ed4fcb234c..e5a075cca5 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -14,7 +14,7 @@ ***Contributing Authors*** **Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathan Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, -L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacquelyn Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** +L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** The National Center for Atmospheric Research (NCAR) is operated by the From d070bd320b2ce6b3be5aea23a76dfc3c669e1726 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 12 Feb 2019 09:48:56 -0700 Subject: [PATCH 192/255] Fix Shuman's name, remove user's guide disclaimer, fix equation numbers --- doc/source/conf.py | 1 + doc/source/index.rst | 2 +- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 27c0df6e3c..a561207501 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -172,3 +172,4 @@ 'code-block': 'Code %s', 'section': '%s', } +numfig_secnum_depth = 2 diff --git a/doc/source/index.rst b/doc/source/index.rst index 517f62e8eb..f7f35abeda 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,7 +6,7 @@ Welcome to the CLM documentation ================================== -This document has two major sections. NOTE THAT THE USER'S GUIDE CURRENTLY PROVIDES INSTRUCTIONS FOR CLM4.5 AND IS A WORK IN PROGRESS. +This document has two major sections. .. toctree:: :maxdepth: 2 diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index e5a075cca5..ed4fcb234c 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -14,7 +14,7 @@ ***Contributing Authors*** **Ashehad Ali, Andrew Badger, Gautam Bisht, Patrick Broxton, Michael Brunke, Jonathan Buzan, Martyn Clark, Tony Craig, Kyla Dahlin, Beth Drewniak, Louisa Emmons, Josh Fisher, Mark Flanner, Pierre Gentine, Jan Lenaerts, Sam Levis, -L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacqueline Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** +L. Ruby Leung, William Lipscomb, Jon Pelletier, Daniel M. Ricciuto, Ben Sanderson, Jacquelyn Shuman, Andrew Slater, Zachary Subin, Jinyun Tang, Ahmed Tawfik, Quinn Thomas, Simone Tilmes, Francis Vitt, Xubin Zeng** The National Center for Atmospheric Research (NCAR) is operated by the From 6599ac994a401bda495904ac890cd3a5da9dddb9 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Tue, 12 Feb 2019 10:30:05 -0700 Subject: [PATCH 193/255] Fix MOSART and urban figure captions --- .../tech_note/Introduction/CLM50_Tech_Note_Introduction.rst | 6 ++++-- doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 5 +++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index ed4fcb234c..7240dfa8d9 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -49,12 +49,14 @@ P. O. Box 3000, Boulder, Colorado 80307-300 - :numref:`Figure three layer snow pack` Example of three layer snow pack (snl=-3). -- :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. - - :numref:`Figure MOSART conceptual diagram` MOSART conceptual diagram. +- :numref:`Figure Schematic representation of the urban landunit` Schematic representation of the urban land unit. + - :numref:`Figure Schematic of urban and atmospheric model coupling` Schematic of urban and atmospheric model coupling. +- :numref:`Figure Schematic of THESIS urban properties tool` Schematic of THESIS urban properties tool. + - :numref:`Figure Vegetation fluxes and pools` Vegetation fluxes and pools. - :numref:`Figure annual phenology cycle` Example of annual phenology cycle for seasonal deciduous. diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index e9f07d7752..439de8a7a1 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -43,13 +43,14 @@ it into the main channel; 3) main channel routing: the main channel receives wat from the sub-network channel and/or inflow, if any, from the upstream spatial units, and discharges the water to its downstream spatial unit or the ocean. +.. Figure 14.1. MOSART conceptual diagram + .. _Figure MOSART conceptual diagram: .. figure:: mosart_diagram.png :width: 800px :height: 400px - - + MOSART only routes positive runoff, although negative runoff can be generated occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any runoff component including :math:`q_{sur}`, :math:`q_{sub}`, :math:`q_{gwl}` From 96d4b5a986732df29ca2844469ba43a25c31d384 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Thu, 14 Feb 2019 09:48:40 -0700 Subject: [PATCH 194/255] Add more detail to BGC and SP spinup in User's Guide --- ...Satellite-Phenology-Model-CLMSP-spinup.rst | 23 +++++- ...ning-up-the-biogeochemistry-BGC-spinup.rst | 72 +++++++++++++++---- 2 files changed, 80 insertions(+), 15 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst index a017c42ae0..d6b6c74d91 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst @@ -6,7 +6,28 @@ Spinning up the Satellite Phenology Model =========================================== -To spin-up the CLMSP model you merely need to run CLMSP for 50 simulation years starting from arbitrary initial conditions. +To spin-up the CLMSP model you merely need to run CLMSP for about 50 simulation years starting from arbitrary initial conditions. You then use the final restart file for initial conditions in other simulations. Because, this is a straight forward operation we will NOT give the details on how to do that here, but leave it as an exercise for the reader. See the `Example 4-7 `_ as an example of doing this as the last step for CLMCN. + +You can also start from a default initial file that is setup as part of the selected compset. :numref:`Figure SP spinup plot for 1850` shows +spinup behavior for an 1850 SP case that loops over one year of coupler history output for atmospheric forcing (generated from the fully coupled model), +initialized with an initial file generated from a GSWP3 atmospheric forcing case. Note that it takes less than 10 years for state variables +such as FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), H2OSOI (soil water), and TSOI (soil temperature) to reach +a specified equilibrium state (denoted by the dotted lines) due to the different atmospheric forcing. TWS (total water storage) may take a bit longer. + +.. _Figure SP spinup plot for 1850: + +.. figure:: image1.png + + SP spinup plot for year 1850. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl. + +:numref:`Figure SP spinup plot for 2000 CO2` shows spinup behavior for the same case but also changes CO2 to present-day conditions (379ppmv). +Again, it takes about 10 years to reach equilibrium. + +.. _Figure SP spinup plot for 2000 CO2: + +.. figure:: image2.png + + SP spinup plot for year 2000 CO2. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl. diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst index 0bbeda8e41..9808ceb05b 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst @@ -6,11 +6,55 @@ Spinup of CLM5.0-BGC-Crop ========================== -To get the |version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**) mode for 1000 simulation years. -After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**), and run for (at least 200+ simulation years). +To get the |version|-BGC model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-bgc_spinup on in CLM **configure**, see example below) mode for about 200 simulation years. :numref:`Figure BGC AD spinup plot for 1850 GSWP3` shows spinup behavior for an 1850 +BGC accelerated decomposition (AD) case using GSWP3 atmospheric forcing. Generally, the criteria that less than 3% of the land surface be in +total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. + +.. _Figure BGC AD spinup plot for 1850 GSWP3: + +.. figure:: image3.png + + BGC AD spinup plot for a year 1850 case with GSWP3 atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + +After this you branch from this mode in the "final spinup" (-bgc_spinup off in CLM **configure**, see example below), and run for several hundred simulation years. +:numref:`Figure BGC pAD spinup plot for 1850 GSWP3` shows spinup behavior for an 1850 +BGC post accelerated decomposition (pAD) case using GSWP3 atmospheric forcing. As before, the criteria that less than 3% of the land surface be in +total ecosystem carbon disequilibrium takes the longest to satisfy. It can be difficult to meet this strict criteria in less than 1000 years and users may want to relax this +criteria depending on their application. + +.. _Figure BGC pAD spinup plot for 1850 GSWP3: + +.. figure:: image4.png + + BGC pAD spinup plot for a year 1850 case with GSWP3 atmospheric forcing and initialization from the end of the BGC AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + +You can also start from a default initial file that is setup as part of the selected compset. :numref:`Figure BGC initialized spinup plot for 1850` shows +spinup behavior for an 1850 pAD BGC case that loops over one year of coupler history output for atmospheric forcing (generated from the fully coupled model), +initialized with a BGC initial file generated from a GSWP3 atmospheric forcing case. Note that it takes about 10 years for variables +such as TLAI (total leaf area index), GPP (gross primary production), and TWS (total water storage) to reach a specified equilibrium state (denoted by the dotted lines) due to the different atmospheric forcing. + +.. _Figure BGC initialized spinup plot for 1850: + +.. figure:: image5.png + + BGC initialized spinup plot for year 1850. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + +:numref:`Figure BGC initialized spinup plot for 2000 CO2` shows spinup behavior for the same case but also changes CO2 to present-day conditions (379ppmv). +Again, it takes about 10 years to reach equilibrium for TLAI, GPP, and TWS. + +.. _Figure BGC initialized spinup plot for 2000 CO2: + +.. figure:: image6.png + + BGC initialized spinup plot for year 2000 CO2. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. + +If you use the default initial file and you signficantly change model behavior or atmospheric forcing, and you are concerned about the carbon +equilibrium (e.g., TOTECOSYSC, TOTSOMC, TOTVEGC), particularly at high latitudes, then we recommend you put the model back into AD mode to +reach a new equilibrium. In this configuration, this will also automatically reseed "dead" plant functional types in the initial file with a +bit of leaf carbon to give those plant functional types another chance to grow under the new atmospheric forcing or model conditions. **1. 50_AD_SPINUP** - For the first step of running 1000+ years in "-bgc_spinup on" mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: + For the first step of running 200+ years in "-bgc_spinup on" mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following: Example:: AD_SPINUP Simulation for |version|-BGC -------------------------------------------------------- @@ -25,18 +69,18 @@ Example:: AD_SPINUP Simulation for |version|-BGC > ./case.setup -case # Now build > ./case.build - # The following sets RESUBMIT to 30 times in env_run.xml (you could also use an editor) - # The following sets STOP_DATE,STOP_N and STOP_OPTION to Jan/1/1001, 20, "nyears" in env_run.xml (you could also use an editor) - > ./xmlchange RESUBMIT=20,STOP_N=50,STOP_OPTION=nyears,STOP_DATE=10010101 + # The following sets RESUBMIT to 3 times in env_run.xml (you could also use an editor) + # The following sets STOP_DATE,STOP_N and STOP_OPTION to Jan/1/0201, 20, "nyears" in env_run.xml (you could also use an editor) + > ./xmlchange RESUBMIT=3,STOP_N=50,STOP_OPTION=nyears,STOP_DATE=02010101 # Now run normally > ./case.submit -.. note:: This same procedure works for |version|-CN as well, you can typically shorten the spinup time from 1000 years to 600 though. +.. note:: This same procedure works for |version|-CN as well. Afterwards save the last restart file from this simulation to use in the next step. **2. Final spinup for |version|-BGC** - Next save the last restart file from this step and use it as the "finidat" file to use for one more spinup for at least 200+ years in normal mode. So do the following: + Next save the last restart file from this step and use it as the "finidat" file to use for one more spinup for at least 400+ years in normal mode. So do the following: Example: Final CLMBGC Spinup Simulation for |version|-BGC ------------------------------------------------------------------ @@ -46,7 +90,7 @@ Example: Final CLMBGC Spinup Simulation for |version|-BGC > ./create_newcase -case BGC_finalspinup -res f19_g17_gl4 -compset I1850Clm50BgcCropCru > cd BGC_finalspinup # Now, Copy the last CLM restart file from the earlier case into your run directory - > cp /ptmp/$LOGIN/archive/BGC_spinup/rest/BGC_spinup.clm*.r*.1002-01-01-00000.nc \ + > cp /ptmp/$LOGIN/archive/BGC_spinup/rest/BGC_spinup.clm*.r*.0201-01-01-00000.nc \ /glade/scratch/$LOGIN/CN_finalspinup # Set the runtype to startup > ./xmlchange RUN_TYPE=startup @@ -54,20 +98,20 @@ Example: Final CLMBGC Spinup Simulation for |version|-BGC > cp /glade/scratch/$LOGIN/archive/BGC_spinup/rest/rpointer.atm /ptmp/$LOGIN/CN_finalspinup > cp /glade/scratch/$LOGIN/archive/BGC_spinup/rest/rpointer.drv /ptmp/$LOGIN/CN_finalspinup # Set the finidat file to the last restart file saved in previous step - > echo ' finidat = "BGC_spinup.clm2.r.1002-01-01-00000.nc"' > user_nl_clm + > echo ' finidat = "BGC_spinup.clm2.r.0201-01-01-00000.nc"' > user_nl_clm # Now setup > ./case.setup > Now build > ./case.build - # The following sets RESUBMIT to 4 times in env_run.xml (you could also use an editor) + # The following sets RESUBMIT to 7 times in env_run.xml (you could also use an editor) # The following sets STOP_N and STOP_OPTION to 50 and "nyears" in env_run.xml (you could also use an editor) - > ./xmlchange RESUBMIT=4,STOP_OPTION=nyears,STOP_N=50 + > ./xmlchange RESUBMIT=7,STOP_OPTION=nyears,STOP_N=50 > Now run as normal > ./case.submit -To assess if the model is spunup plot trends of CLMBGC variables of interest. If you see a trend, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. +To assess if the model is spunup, plot trends for CLMBGC variables of interest using .../tools/contrib/SpinupStability.ncl. If you don't meet the equilibrium criteria, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations. -.. note:: This same final spinup procedure works for |version|-CN as well, you can typically shorten the spinup time from 200 years to 50 though. +.. note:: This same final spinup procedure works for |version|-CN as well. From e957144383f10f824e5779f70ca189326c28a9a6 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Wed, 3 Apr 2019 09:20:31 -0600 Subject: [PATCH 195/255] Fix equation 2.5.135 reference --- doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index 7abed081fd..d967cd5ff0 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -1531,7 +1531,7 @@ where :math:`\Delta T_{v} =1{\rm \; or\; }-1`. The error The error :math:`\lambda \Delta _{3}` is added to the sensible heat flux later. -#. Sensible heat flux :math:`H_{v}` (:eq:`` ). The three energy error +#. Sensible heat flux :math:`H_{v}` (:eq:`5.135` ). The three energy error terms, :math:`\Delta _{1}` , :math:`\Delta _{2}` , and :math:`\lambda \Delta _{3}` are also added to the sensible heat flux. From e9ccd6b5b31268ade075409f5207804296b089f1 Mon Sep 17 00:00:00 2001 From: Keith Oleson Date: Wed, 9 Oct 2019 11:04:07 -0600 Subject: [PATCH 196/255] Update soil organic matter properties in Hydrology chapter --- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 34 ++++++++++++++++--- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index fb387d25c2..c4e0824ea7 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -620,9 +620,8 @@ organic components. The water content at saturation (i.e. porosity) is \theta_{sat,i} =(1-f_{om,i} )\theta_{sat,\min ,i} +f_{om,i} \theta_{sat,om} where :math:`f_{om,i}` is the soil organic matter fraction, -:math:`\theta_{sat,om} =0.9` (:ref:`Farouki 1981 `; -:ref:`Letts et al. 2000 `) is the -porosity of organic matter and the porosity of the mineral soil +:math:`\theta_{sat,om}` is the +porosity of organic matter, and the porosity of the mineral soil :math:`\theta_{sat,\min ,i}` is .. math:: @@ -637,7 +636,7 @@ The exponent :math:`B_{i}` is B_{i} =(1-f_{om,i} )B_{\min ,i} +f_{om,i} B_{om} -where :math:`B_{om} = 2.7` \ (:ref:`Letts et al. 2000 `) and +where :math:`B_{om}` is for organic matter and .. math:: :label: 7.93 @@ -659,7 +658,7 @@ where the saturated soil matric potential (mm) is \psi _{sat,i} =(1-f_{om,i} )\psi _{sat,\min ,i} +f_{om,i} \psi _{sat,om} -where :math:`\psi _{sat,om} = -10.3` \ mm (:ref:`Letts et al. 2000 `) is the +where :math:`\psi _{sat,om}` \ is the saturated organic matter matric potential and the saturated mineral soil matric potential :math:`\psi _{sat,\min ,i}` \ is @@ -723,6 +722,31 @@ as k_{sat} \left[z_{h,\, i} \right]=f_{uncon,\, i} k_{sat,\, uncon} \left[z_{h,\, i} \right]+(1-f_{uncon,\, i} )k_{sat,\, om} \left[z_{h,\, i} \right]. +The soil organic matter properties implicitly account for the standard observed profile of organic matter +properties as + +.. math:: + :label: 1.101 + + \theta_{sat,om} = max(0.93 - 0.1\times z_{i} / zsapric, 0.83). + +.. math:: + :label: 1.102 + + B_{om} = min(2.7 + 9.3\times z_{i} / zsapric, 12.0). + +.. math:: + :label: 1.103 + + \psi_{sat,om} = min(10.3 - 0.2\times z_{i} / zsapric, 10.1). + +.. math:: + :label: 1.104 + + k_{sat,om} = max(0.28 - 0.2799\times z_{i} / zsapric, k_{sat,\, \min } \left[z_{h,\, i} \right]). + +where :math:`zsapric =0.5` \m is the depth that organic matter takes on the characteristics of sapric peat. + .. _Numerical Solution Hydrology: Numerical Solution From 893f9efe187f85ef0c1152479544fb75eaf0d3a6 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Tue, 19 Nov 2019 13:47:20 -0700 Subject: [PATCH 197/255] removed DEBUG write statement --- src/cpl/nuopc/lnd_import_export.F90 | 1 - 1 file changed, 1 deletion(-) diff --git a/src/cpl/nuopc/lnd_import_export.F90 b/src/cpl/nuopc/lnd_import_export.F90 index eb1b06663a..6fcc84ab80 100644 --- a/src/cpl/nuopc/lnd_import_export.F90 +++ b/src/cpl/nuopc/lnd_import_export.F90 @@ -197,7 +197,6 @@ subroutine advertise_fields(gcomp, flds_scalar_name, glc_present, rof_prognostic ! Fire emissions fluxes from land call shr_fire_emis_readnl('drv_flds_in', emis_nflds) - write(6,*)'DEBUG: emis_nflds= ',emis_nflds if (emis_nflds > 0) then call fldlist_add(fldsFrLnd_num, fldsFrLnd, 'Fall_fire', ungridded_lbound=1, ungridded_ubound=emis_nflds) call fldlist_add(fldsFrLnd_num, fldsFrLnd, 'Sl_fztop') From 93c898437ea1eec314b321c8ed063d5ff019cc51 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Sun, 22 Dec 2019 19:10:32 -0700 Subject: [PATCH 198/255] updates for single point and regional ctsm/datm --- cime_config/config_compsets.xml | 20 ++- cime_config/testdefs/testlist_clm.xml | 38 +++--- src/cpl/nuopc/lnd_comp_nuopc.F90 | 190 +++++++++++++++++++++----- src/cpl/nuopc/lnd_import_export.F90 | 5 +- 4 files changed, 191 insertions(+), 62 deletions(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index a1954b5dde..c3d9d0a3ec 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -37,13 +37,13 @@ - I1PtClm50SpGs - 2000_DATM%1PT_CLM50%SP_SICE_SOCN_MOSART_SGLC_SWAV + I1PtClm50SpRsGs + 2000_DATM%1PT_CLM50%SP_SICE_SOCN_SROF_SGLC_SWAV - I1PtClm45SpGs - 2000_DATM%1PT_CLM45%SP_SICE_SOCN_RTM_SGLC_SWAV + I1PtClm45SpRsGs + 2000_DATM%1PT_CLM45%SP_SICE_SOCN_SROF_SGLC_SWAV @@ -160,6 +160,11 @@ 2000_DATM%QIA_CLM45%BGC-CROP_SICE_SOCN_SROF_SGLC_SWAV + + I2000Clm50BgcCruRsGs + 2000_DATM%CRUv7_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV + + I2000Clm50BgcCruGs 2000_DATM%CRUv7_CLM50%BGC_SICE_SOCN_MOSART_SGLC_SWAV @@ -326,7 +331,12 @@ 2000_DATM%GSWP3v1_CLM45%FATES_SICE_SOCN_RTM_CISM2%NOEVOLVE_SWAV - + + + I2000Clm45FatesRsGs + 2000_DATM%GSWP3v1_CLM45%FATES_SICE_SOCN_SROF_SGLC_SWAV + + I2000Clm45FatesGs 2000_DATM%GSWP3v1_CLM45%FATES_SICE_SOCN_RTM_SGLC_SWAV diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index 73c04e27f9..5920b85901 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -8,7 +8,7 @@ - + @@ -842,7 +842,7 @@ - + @@ -876,7 +876,7 @@ - + @@ -884,7 +884,7 @@ - + @@ -892,7 +892,7 @@ - + @@ -1125,7 +1125,7 @@ - + @@ -1133,7 +1133,7 @@ - + @@ -1141,7 +1141,7 @@ - + @@ -1234,7 +1234,7 @@ - + @@ -1243,7 +1243,7 @@ - + @@ -1305,7 +1305,7 @@ - + @@ -1468,7 +1468,7 @@ - + @@ -1477,7 +1477,7 @@ - + @@ -1514,7 +1514,7 @@ - + @@ -1523,7 +1523,7 @@ - + @@ -1531,7 +1531,7 @@ - + @@ -1541,7 +1541,7 @@ - + @@ -1849,7 +1849,7 @@ - + @@ -1886,7 +1886,7 @@ - + diff --git a/src/cpl/nuopc/lnd_comp_nuopc.F90 b/src/cpl/nuopc/lnd_comp_nuopc.F90 index e5a1174868..5854e7b2cf 100644 --- a/src/cpl/nuopc/lnd_comp_nuopc.F90 +++ b/src/cpl/nuopc/lnd_comp_nuopc.F90 @@ -26,17 +26,21 @@ module lnd_comp_nuopc use clm_varctl , only : inst_index, inst_suffix, inst_name use clm_varctl , only : single_column, clm_varctl_set, iulog use clm_varctl , only : nsrStartup, nsrContinue, nsrBranch + use clm_varcon , only : re use clm_time_manager , only : set_timemgr_init, advance_timestep use clm_time_manager , only : set_nextsw_cday, update_rad_dtime use clm_time_manager , only : get_nstep, get_step_size use clm_time_manager , only : get_curr_date, get_curr_calday use clm_initializeMod , only : initialize1, initialize2 use clm_driver , only : clm_drv - use perf_mod , only : t_startf, t_stopf, t_barrierf use lnd_import_export , only : advertise_fields, realize_fields use lnd_import_export , only : import_fields, export_fields use lnd_shr_methods , only : chkerr, state_setscalar, state_getscalar, state_diagnose, alarmInit use lnd_shr_methods , only : set_component_logging, get_component_instance, log_clock_advance + use perf_mod , only : t_startf, t_stopf, t_barrierf + use netcdf , only : nf90_open, nf90_nowrite, nf90_noerr, nf90_close, nf90_strerror + use netcdf , only : nf90_inq_dimid, nf90_inq_varid, nf90_get_var + use netcdf , only : nf90_inquire_dimension, nf90_inquire_variable implicit none private ! except @@ -159,6 +163,7 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc) character(len=CL) :: cvalue character(len=CL) :: logmsg logical :: isPresent, isSet + logical :: cism_evolve character(len=*), parameter :: subname=trim(modName)//':(InitializeAdvertise) ' character(len=*), parameter :: format = "('("//trim(subname)//") :',A)" !------------------------------------------------------------------------------- @@ -277,13 +282,25 @@ subroutine InitializeAdvertise(gcomp, importState, exportState, clock, rc) if (trim(cvalue) == 'sglc') then glc_present = .false. else - glc_present = .true. + glc_present = .true. + cism_evolve = .true. + call NUOPC_CompAttributeGet(gcomp, name="cism_evolve", value=cvalue, isPresent=isPresent, isSet=isSet, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + if (isPresent .and. isSet) then + call ESMF_LogWrite(trim(subname)//' cism_evolve = '//trim(cvalue), ESMF_LOGMSG_INFO) + write (cism_evolve,*) cvalue + else + call shr_sys_abort(subname//'Need to set cism_evolve if glc is present') + endif end if - write(iulog,*)' rof_prognostic = ',rof_prognostic - write(iulog,*)' glc_present = ',glc_present + if (masterproc) then + write(iulog,*)' rof_prognostic = ',rof_prognostic + write(iulog,*)' glc_present = ',glc_present + if (glc_present) write(iulog,*)' cism_evolve = ',cism_evolve + end if - call advertise_fields(gcomp, flds_scalar_name, glc_present, rof_prognostic, rc) + call advertise_fields(gcomp, flds_scalar_name, glc_present, cism_evolve, rof_prognostic, rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return !---------------------------------------------------------------------------- @@ -309,7 +326,7 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) integer, intent(out) :: rc ! local variables - type(ESMF_Mesh) :: Emesh, EMeshTemp ! esmf meshes + type(ESMF_Mesh) :: mesh ! esmf mesh type(ESMF_DistGrid) :: DistGrid ! esmf global index space descriptor type(ESMF_Time) :: currTime ! Current time type(ESMF_Time) :: startTime ! Start time @@ -349,8 +366,24 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) logical :: brnch_retain_casename ! flag if should retain the case name on a branch start type integer :: lbnum ! input to memory diagnostic type(bounds_type) :: bounds ! bounds - integer :: shrlogunit ! original log unit - character(ESMF_MAXSTR) :: convCIM, purpComp + integer :: shrlogunit ! original log unit + real(r8) :: mesh_lon, mesh_lat, mesh_area + real(r8) :: tolerance_latlon = 1.e-5 + real(r8) :: tolerance_area = 1.e-3 + integer :: spatialDim + integer :: numOwnedElements + real(R8), pointer :: ownedElemCoords(:) + real(r8), pointer :: areaPtr(:) + type(ESMF_Field) :: areaField + integer :: dimid_ni, dimid_nj, dimid_nv + integer :: ncid, ierr + integer :: ni, nj, nv + integer :: varid_xv, varid_yv + real(r8), allocatable :: xv(:,:,:), yv(:,:,:) + integer :: maxIndex(2) + real(r8) :: mincornerCoord(2) + real(r8) :: maxcornerCoord(2) + type(ESMF_Grid) :: lgrid character(len=*),parameter :: subname=trim(modName)//':(InitializeRealize) ' !------------------------------------------------------------------------------- @@ -396,13 +429,7 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) call NUOPC_CompAttributeGet(gcomp, name='case_name', value=cvalue, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return read(cvalue,*) caseid - - !TODO: case_desc does not appear in the esm_AddAttributes in esm.F90 - ! just hard-wire from now - is this even needed? - ! call NUOPC_CompAttributeGet(gcomp, name='case_desc', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - ! read(cvalue,*) ctitle - ctitle='UNSET' + ctitle= trim(caseid) call NUOPC_CompAttributeGet(gcomp, name='scmlon', value=cvalue, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return @@ -552,18 +579,78 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) call NUOPC_CompAttributeGet(gcomp, name='mesh_lnd', value=cvalue, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return - EMeshTemp = ESMF_MeshCreate(filename=trim(cvalue), fileformat=ESMF_FILEFORMAT_ESMFMESH, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - if (masterproc) then - write(iulog,*)'mesh file for domain is ',trim(cvalue) + if (cvalue == 'create_mesh') then + ! get the datm grid from the domain file + call NUOPC_CompAttributeGet(gcomp, name='domain_lnd', value=cvalue, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + ! open file + ierr = nf90_open(cvalue, NF90_NOWRITE, ncid) + call nc_check_err(ierr, 'nf90_open', trim(cvalue)) + ! get dimension ids + ierr = nf90_inq_dimid(ncid, 'ni', dimid_ni) + call nc_check_err(ierr, 'nf90_inq_dimid for ni', trim(cvalue)) + ierr = nf90_inq_dimid(ncid, 'nj', dimid_nj) + call nc_check_err(ierr, 'nf90_inq_dimid for nj', trim(cvalue)) + ierr = nf90_inq_dimid(ncid, 'nv', dimid_nv) + call nc_check_err(ierr, 'nf90_inq_dimid for nv', trim(cvalue)) + ! get dimension values + ierr = nf90_inquire_dimension(ncid, dimid_ni, len=ni) + call nc_check_err(ierr, 'nf90_inq_dimension for ni', trim(cvalue)) + ierr = nf90_inquire_dimension(ncid, dimid_nj, len=nj) + call nc_check_err(ierr, 'nf90_inq_dimension for nj', trim(cvalue)) + ierr = nf90_inquire_dimension(ncid, dimid_nv, len=nv) + call nc_check_err(ierr, 'nf90_inq_dimension for nv', trim(cvalue)) + ! get variable ids + ierr = nf90_inq_varid(ncid, 'xv', varid_xv) + call nc_check_err(ierr, 'nf90_inq_varid for xv', trim(cvalue)) + ierr = nf90_inq_varid(ncid, 'yv', varid_yv) + call nc_check_err(ierr, 'nf90_inq_varid for yv', trim(cvalue)) + ! allocate memory for variables and get variable values + allocate(xv(nv,ni,nj), yv(nv,ni,nj)) + ierr = nf90_get_var(ncid, varid_xv, xv) + call nc_check_err(ierr, 'nf90_get_var for xv', trim(cvalue)) + ierr = nf90_get_var(ncid, varid_yv, yv) + call nc_check_err(ierr, 'nf90_get_var for yv', trim(cvalue)) + ! close file + ierr = nf90_close(ncid) + call nc_check_err(ierr, 'nf90_close', trim(cvalue)) + ! create the grid + maxIndex(1) = ni ! number of lons + maxIndex(2) = nj ! number of lats + mincornerCoord(1) = xv(1,1,1) ! min lon + mincornerCoord(2) = yv(1,1,1) ! min lat + maxcornerCoord(1) = xv(3,ni,nj) ! max lon + maxcornerCoord(2) = yv(3,ni,nj) ! max lat + deallocate(xv,yv) + write(6,*)'DEBUG: maxcornerCoord = ',maxcornerCoord + lgrid = ESMF_GridCreateNoPeriDimUfrm (maxindex=maxindex, & + mincornercoord=mincornercoord, maxcornercoord= maxcornercoord, & + staggerloclist=(/ESMF_STAGGERLOC_CENTER, ESMF_STAGGERLOC_CORNER/), rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + + ! create the mesh from the grid + mesh = ESMF_MeshCreate(lgrid, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + else + ! read in the mesh from the file + mesh = ESMF_MeshCreate(filename=trim(cvalue), fileformat=ESMF_FILEFORMAT_ESMFMESH, & + elementDistgrid=Distgrid, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + if (masterproc) then + write(iulog,*)'mesh file for domain is ',trim(cvalue) + end if end if - ! recreate the mesh using the above distGrid - EMesh = ESMF_MeshCreate(EMeshTemp, elementDistgrid=Distgrid, rc=rc) + ! Determine the areas on the mesh + areaField = ESMF_FieldCreate(mesh, ESMF_TYPEKIND_R8, name='mesh_areas', meshloc=ESMF_MESHLOC_ELEMENT, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + call ESMF_FieldRegridGetArea(areaField, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + call ESMF_FieldGet(areaField, farrayPtr=areaPtr, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return ! realize the actively coupled fields - call realize_fields(gcomp, Emesh, flds_scalar_name, flds_scalar_num, rc) + call realize_fields(gcomp, mesh, flds_scalar_name, flds_scalar_num, rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return !-------------------------------- @@ -572,6 +659,39 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) call initialize2() + !-------------------------------- + ! Check that lats, lons and areas on mesh are the same as those internal to ctsm + ! obtain mesh lats and lons + !-------------------------------- + + call ESMF_MeshGet(mesh, spatialDim=spatialDim, numOwnedElements=numOwnedElements, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + allocate(ownedElemCoords(spatialDim*numOwnedElements)) + call ESMF_MeshGet(mesh, ownedElemCoords=ownedElemCoords) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + do g = bounds%begg,bounds%endg + n = 1 + (g - bounds%begg) + mesh_lon = ownedElemCoords(2*n-1) + mesh_lat = ownedElemCoords(2*n) + mesh_area = areaPtr(n) + if (abs(mesh_lon - ldomain%lonc(g)) > tolerance_latlon) then + write(6,100)'ERROR: clm_lon, mesh_lon, diff_lon = ',& + ldomain%lonc(g), mesh_lon, abs(mesh_lon - ldomain%lonc(g)) + !call shr_sys_abort() + end if + if (abs(mesh_lat - ldomain%latc(g)) > tolerance_latlon) then + write(6,100)'ERROR: clm_lat, mesh_lat, diff_lat = ',& + ldomain%latc(g), mesh_lat, abs(mesh_lat - ldomain%latc(g)) + !call shr_sys_abort() + end if + if (abs(mesh_area - ldomain%area(g)/(re*re)) > tolerance_area) then + write(6,100)'ERROR: clm_area, mesh_area, diff_area = ',& + ldomain%area(g)/(re*re), mesh_area, abs(mesh_area - ldomain%area(g)/(re*re)) + !call shr_sys_abort() + end if + end do +100 format(a,3(d13.5,2x)) + !-------------------------------- ! Check that ctsm internal dtime aligns with ctsm coupling interval !-------------------------------- @@ -631,20 +751,6 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) call shr_file_setLogUnit (shrlogunit) -#ifdef USE_ESMF_METADATA - convCIM = "CIM" - purpComp = "Model Component Simulation Description" - call ESMF_AttributeAdd(comp, convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "ShortName", "CTSM", convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "LongName", "Community Land Model", convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "Description", "Community Land Model", convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "ReleaseDate", "2017", convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "ModelType", "Terrestrial", convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "Name", "TBD", convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "EmailAddress", TBD, convention=convCIM, purpose=purpComp, rc=rc) - call ESMF_AttributeSet(comp, "ResponsiblePartyRole", "contact", convention=convCIM, purpose=purpComp, rc=rc) -#endif - #if (defined _MEMTRACE) if(masterproc) then write(iulog,*) TRIM(Sub) // ':end::' @@ -1091,4 +1197,16 @@ end subroutine ModelFinalize !=============================================================================== + subroutine nc_check_err(ierror, description, filename) + integer , intent(in) :: ierror + character(*), intent(in) :: description + character(*), intent(in) :: filename + + if (ierror /= nf90_noerr) then + write (*,'(6a)') 'ERROR ', trim(description),'. NetCDF file : "', trim(filename),& + '". Error message:', trim(nf90_strerror(ierror)) + call shr_sys_abort() + endif + end subroutine nc_check_err + end module lnd_comp_nuopc diff --git a/src/cpl/nuopc/lnd_import_export.F90 b/src/cpl/nuopc/lnd_import_export.F90 index 6fcc84ab80..715fa9ed09 100644 --- a/src/cpl/nuopc/lnd_import_export.F90 +++ b/src/cpl/nuopc/lnd_import_export.F90 @@ -78,7 +78,7 @@ module lnd_import_export contains !=============================================================================== - subroutine advertise_fields(gcomp, flds_scalar_name, glc_present, rof_prognostic, rc) + subroutine advertise_fields(gcomp, flds_scalar_name, glc_present, cism_evolve, rof_prognostic, rc) use clm_varctl, only : ndep_from_cpl @@ -86,6 +86,7 @@ subroutine advertise_fields(gcomp, flds_scalar_name, glc_present, rof_prognostic type(ESMF_GridComp) :: gcomp character(len=*) , intent(in) :: flds_scalar_name logical , intent(in) :: glc_present + logical , intent(in) :: cism_evolve logical , intent(in) :: rof_prognostic integer , intent(out) :: rc @@ -208,7 +209,7 @@ subroutine advertise_fields(gcomp, flds_scalar_name, glc_present, rof_prognostic call fldlist_add(fldsFrLnd_num, fldsFrlnd, 'Sl_soilw') ! optional for carma end if - if (glc_present) then + if (glc_present .and. cism_evolve) then ! lnd->glc states from land all lnd->glc elevation classes (1:glc_nec) plus bare land (index 0). ! The following puts all of the elevation class fields as an ! undidstributed dimension in the export state field From ae9f24be371d0006a0d6764d2c3581d338ef1325 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Fri, 27 Dec 2019 10:48:32 -0700 Subject: [PATCH 199/255] updates to get aux_clm test working --- cime_config/config_compsets.xml | 5 + cime_config/testdefs/testlist_clm_nuopc.xml | 1919 +++++++++++++++++++ src/cpl/nuopc/lnd_comp_nuopc.F90 | 1 - src/cpl/nuopc/lnd_import_export.F90 | 121 +- 4 files changed, 1980 insertions(+), 66 deletions(-) create mode 100644 cime_config/testdefs/testlist_clm_nuopc.xml diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index c3d9d0a3ec..bf0cb94221 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -192,6 +192,11 @@ 2000_DATM%GSWP3v1_CLM50%FATES_SICE_SOCN_MOSART_SGLC_SWAV + + I2000Clm50FatesRsGs + 2000_DATM%GSWP3v1_CLM50%FATES_SICE_SOCN_SROF_SGLC_SWAV + + I1850Clm50Bgc 1850_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_MOSART_CISM2%NOEVOLVE_SWAV diff --git a/cime_config/testdefs/testlist_clm_nuopc.xml b/cime_config/testdefs/testlist_clm_nuopc.xml new file mode 100644 index 0000000000..00ab21d38e --- /dev/null +++ b/cime_config/testdefs/testlist_clm_nuopc.xml @@ -0,0 +1,1919 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/cpl/nuopc/lnd_comp_nuopc.F90 b/src/cpl/nuopc/lnd_comp_nuopc.F90 index 5854e7b2cf..f11b7014c1 100644 --- a/src/cpl/nuopc/lnd_comp_nuopc.F90 +++ b/src/cpl/nuopc/lnd_comp_nuopc.F90 @@ -109,7 +109,6 @@ subroutine SetServices(gcomp, rc) call ESMF_MethodRemove(gcomp, label=model_label_SetRunClock, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return - call NUOPC_CompSpecialize(gcomp, specLabel=model_label_SetRunClock, & specRoutine=ModelSetRunClock, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return diff --git a/src/cpl/nuopc/lnd_import_export.F90 b/src/cpl/nuopc/lnd_import_export.F90 index 715fa9ed09..e4928f37a1 100644 --- a/src/cpl/nuopc/lnd_import_export.F90 +++ b/src/cpl/nuopc/lnd_import_export.F90 @@ -386,25 +386,23 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & real(r8), pointer :: dataPtr(:) character(len=128) :: fldname integer :: num - integer :: begg, endg ! bounds - integer :: g,i,k ! indices - real(r8) :: e ! vapor pressure (Pa) - real(r8) :: qsat ! saturation specific humidity (kg/kg) - real(r8) :: co2_ppmv_diag(bounds%begg:bounds%endg) ! temporary - real(r8) :: co2_ppmv_prog(bounds%begg:bounds%endg) ! temporary - real(r8) :: co2_ppmv_val ! temporary - real(r8) :: esatw ! saturation vapor pressure over water (Pa) - real(r8) :: esati ! saturation vapor pressure over ice (Pa) - real(r8) :: a0,a1,a2,a3,a4,a5,a6 ! coefficients for esat over water - real(r8) :: b0,b1,b2,b3,b4,b5,b6 ! coefficients for esat over ice - real(r8) :: tdc, t ! Kelvins to Celcius function and its input - real(r8) :: forc_t ! atmospheric temperature (Kelvin) - real(r8) :: forc_q ! atmospheric specific humidity (kg/kg) - real(r8) :: forc_pbot ! atmospheric pressure (Pa) - real(r8) :: forc_rainc(bounds%begg:bounds%endg) ! rainxy Atm flux mm/s - real(r8) :: forc_rainl(bounds%begg:bounds%endg) ! rainxy Atm flux mm/s - real(r8) :: forc_snowc(bounds%begg:bounds%endg) ! snowfxy Atm flux mm/s - real(r8) :: forc_snowl(bounds%begg:bounds%endg) ! snowfxl Atm flux mm/s + integer :: begg, endg ! bounds + integer :: g,i,k ! indices + real(r8) :: e ! vapor pressure (Pa) + real(r8) :: qsat ! saturation specific humidity (kg/kg) + real(r8) :: esatw ! saturation vapor pressure over water (Pa) + real(r8) :: esati ! saturation vapor pressure over ice (Pa) + real(r8) :: a0,a1,a2,a3,a4,a5,a6 ! coefficients for esat over water + real(r8) :: b0,b1,b2,b3,b4,b5,b6 ! coefficients for esat over ice + real(r8) :: tdc, t ! Kelvins to Celcius function and its input + real(r8) :: forc_t ! atmospheric temperature (Kelvin) + real(r8) :: forc_q ! atmospheric specific humidity (kg/kg) + real(r8) :: forc_pbot ! atmospheric pressure (Pa) + real(r8) :: co2_ppmv_input(bounds%begg:bounds%endg) ! temporary + real(r8) :: forc_rainc(bounds%begg:bounds%endg) ! rainxy Atm flux mm/s + real(r8) :: forc_rainl(bounds%begg:bounds%endg) ! rainxy Atm flux mm/s + real(r8) :: forc_snowc(bounds%begg:bounds%endg) ! snowfxy Atm flux mm/s + real(r8) :: forc_snowl(bounds%begg:bounds%endg) ! snowfxl Atm flux mm/s real(r8) :: forc_noy(bounds%begg:bounds%endg) real(r8) :: forc_nhx(bounds%begg:bounds%endg) real(r8) :: frac_grc(bounds%begg:bounds%endg, 0:glc_nec) @@ -521,11 +519,11 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & call state_getimport(importState, 'Faxa_ocph', bounds, output=atm2lnd_inst%forc_aer_grc(:,4), & ungridded_index=1, rc=rc ) if (ChkErr(rc,__LINE__,u_FILE_u)) return - ! bcphodry + ! ocphodry call state_getimport(importState, 'Faxa_ocph', bounds, output=atm2lnd_inst%forc_aer_grc(:,5), & ungridded_index=2, rc=rc ) if (ChkErr(rc,__LINE__,u_FILE_u)) return - ! bcphiwet + ! ocphiwet call state_getimport(importState, 'Faxa_ocph', bounds, output=atm2lnd_inst%forc_aer_grc(:,6), & ungridded_index=3, rc=rc ) if (ChkErr(rc,__LINE__,u_FILE_u)) return @@ -576,56 +574,47 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & ! Atmosphere co2 !-------------------------- - fldName = 'Sa_co2prog' - call ESMF_StateGet(importState, trim(fldname), itemFlag, rc=rc) - if ( ChkErr(rc,__LINE__,u_FILE_u)) return - if (itemflag == ESMF_STATEITEM_NOTFOUND .and. co2_type == 'prognostic') then - call shr_sys_abort( subname//' ERROR: must have nonzero Sa_co2prog for co2_type equal to prognostic' ) - end if - if (itemflag /= ESMF_STATEITEM_NOTFOUND) then - call state_getfldptr(importState, trim(fldname), dataPtr, rc=rc ) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - do g = begg,endg - co2_ppmv_prog(g) = dataPtr(g-begg+1) ! co2 atm prognostic - end do - else - do g = begg,endg - co2_ppmv_prog(g) = co2_ppmv - end do - end if - - fldName = 'Sa_co2diag' - call ESMF_StateGet(importState, trim(fldname), itemFlag, rc=rc) - if ( ChkErr(rc,__LINE__,u_FILE_u)) return - if (itemflag == ESMF_STATEITEM_NOTFOUND .and. co2_type == 'diagnostic') then - call shr_sys_abort( subname//' ERROR: must have nonzero Sa_co2prog for co2_type equal to prognostic' ) - end if - if (itemflag /= ESMF_STATEITEM_NOTFOUND) then - call state_getfldptr(importState, trim(fldname), dataPtr, rc=rc ) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - do g = begg,endg - co2_ppmv_diag(g) = dataPtr(g-begg+1) ! co2 atm diagnostic - end do - else - do g = begg,endg - co2_ppmv_diag(g) = co2_ppmv - end do + ! Set default value to a constant and overwrite for prognostic and diagnostic + do g = begg,endg + co2_ppmv_input(g) = co2_ppmv + end do + if (co2_type == 'prognostic') then + fldName = 'Sa_co2prog' + call ESMF_StateGet(importState, trim(fldname), itemFlag, rc=rc) + if ( ChkErr(rc,__LINE__,u_FILE_u)) return + if (itemflag == ESMF_STATEITEM_NOTFOUND .and. co2_type == 'prognostic') then + call shr_sys_abort( subname//' ERROR: must have Sa_co2prog in import state if co2_type is prognostic' ) + end if + if (itemflag /= ESMF_STATEITEM_NOTFOUND) then + call state_getfldptr(importState, trim(fldname), dataPtr, rc=rc ) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + do g = begg,endg + co2_ppmv_input(g) = dataPtr(g-begg+1) ! co2 atm prognostic + end do + end if + else if (co2_type == 'diagnostic') then + fldName = 'Sa_co2diag' + call ESMF_StateGet(importState, trim(fldname), itemFlag, rc=rc) + if ( ChkErr(rc,__LINE__,u_FILE_u)) return + if (itemflag == ESMF_STATEITEM_NOTFOUND .and. co2_type == 'diagnostic') then + call shr_sys_abort( subname//' ERROR: must have Sa_co2diag in import state if co2_type equal diagnostic') + end if + if (itemflag /= ESMF_STATEITEM_NOTFOUND) then + call state_getfldptr(importState, trim(fldname), dataPtr, rc=rc ) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + do g = begg,endg + co2_ppmv_input(g) = dataPtr(g-begg+1) ! co2 atm diagnostic + end do + end if end if ! Note that the following does unit conversions from ppmv to partial pressures (Pa) ! Note that forc_pbot is in Pa do g = begg,endg - if (co2_type == 'prognostic') then - co2_ppmv_val = co2_ppmv_prog(g) - else if (co2_type == 'diagnostic') then - co2_ppmv_val = co2_ppmv_diag(g) - else - co2_ppmv_val = co2_ppmv - end if forc_pbot = atm2lnd_inst%forc_pbot_not_downscaled_grc(g) - atm2lnd_inst%forc_pco2_grc(g) = co2_ppmv_val * 1.e-6_r8 * forc_pbot + atm2lnd_inst%forc_pco2_grc(g) = co2_ppmv_input(g) * 1.e-6_r8 * forc_pbot if (use_c13) then - atm2lnd_inst%forc_pc13o2_grc(g) = co2_ppmv_val * c13ratio * 1.e-6_r8 * forc_pbot + atm2lnd_inst%forc_pc13o2_grc(g) = co2_ppmv_input(g) * c13ratio * 1.e-6_r8 * forc_pbot end if end do @@ -1239,11 +1228,12 @@ subroutine state_setexport(state, fldname, bounds, input, minus, ungridded_index ! TODO: if fillvalue = shr_const_spval the snowhl sent to the atm will have the spval over some points ! rather than 0 - this is very odd and needs to be understood - ! fldptr(:) = fillvalue + !fldptr1d(:) = fillvalue ! determine output array if (present(ungridded_index)) then fldptr2d(ungridded_index,:) = 0._r8 + !fldptr2d(ungridded_index,:) = fillvalue do g = bounds%begg, bounds%endg n = g - bounds%begg + 1 fldptr2d(ungridded_index,n) = input(g) @@ -1253,6 +1243,7 @@ subroutine state_setexport(state, fldname, bounds, input, minus, ungridded_index end if else fldptr1d(:) = 0._r8 + !fldptr1d(:) = fillvalue do g = bounds%begg, bounds%endg n = g - bounds%begg + 1 fldptr1d(n) = input(g) From 1d9bd3e7bdc59df96f2f4eef228658afb0d582dd Mon Sep 17 00:00:00 2001 From: Jim Edwards Date: Mon, 30 Dec 2019 13:01:54 -0700 Subject: [PATCH 200/255] dont rely on netcdf for type conversion --- src/main/histFileMod.F90 | 183 +++++++++++++++++++------------------- src/main/ncdio_pio.F90.in | 56 ++++++------ 2 files changed, 122 insertions(+), 117 deletions(-) diff --git a/src/main/histFileMod.F90 b/src/main/histFileMod.F90 index 23690ad51f..c3898e67c9 100644 --- a/src/main/histFileMod.F90 +++ b/src/main/histFileMod.F90 @@ -13,20 +13,20 @@ module histFileMod use spmdMod , only : masterproc use abortutils , only : endrun use clm_varctl , only : iulog, use_vertsoilc, use_fates - use clm_varcon , only : spval, ispval, dzsoi_decomp + use clm_varcon , only : spval, ispval, dzsoi_decomp use clm_varcon , only : grlnd, nameg, namel, namec, namep, nameCohort use decompMod , only : get_proc_bounds, get_proc_global, bounds_type use GetGlobalValuesMod , only : GetGlobalIndex - use GridcellType , only : grc - use LandunitType , only : lun - use ColumnType , only : col - use PatchType , only : patch + use GridcellType , only : grc + use LandunitType , only : lun + use ColumnType , only : col + use PatchType , only : patch use EDTypesMod , only : nclmax use EDTypesMod , only : nlevleaf use FatesInterfaceMod , only : nlevsclass, nlevage use EDTypesMod , only : nfsc, ncwd use FatesInterfaceMod , only : maxveg_fates => numpft - use ncdio_pio + use ncdio_pio ! implicit none @@ -160,7 +160,7 @@ module histFileMod private :: hfields_write ! Write a variable to a history tape private :: hfields_1dinfo ! Define/output 1d subgrid info if appropriate private :: hist_update_hbuf_field_1d ! Updates history buffer for specific field and tape - private :: hist_update_hbuf_field_2d ! Updates history buffer for specific field and tape + private :: hist_update_hbuf_field_2d ! Updates history buffer for specific field and tape private :: hist_set_snow_field_2d ! Set values in history field dimensioned by levsno private :: list_index ! Find index of field in exclude list private :: set_hist_filename ! Determine history dataset filenames @@ -196,7 +196,7 @@ module histFileMod integer :: end1d_out ! on-node 1d hbuf pointer end index integer :: num1d_out ! size of hbuf first dimension (all nodes) integer :: num2d ! size of hbuf second dimension (e.g. number of vertical levels) - integer :: hpindex ! history pointer index + integer :: hpindex ! history pointer index character(len=scale_type_strlen) :: p2c_scale_type ! scale factor when averaging patch to column character(len=scale_type_strlen) :: c2l_scale_type ! scale factor when averaging column to landunit character(len=scale_type_strlen) :: l2g_scale_type ! scale factor when averaging landunit to gridcell @@ -352,7 +352,7 @@ subroutine masterlist_addfld (fname, type1d, type1d_out, & integer :: numl ! total number of landunits across all processors integer :: numc ! total number of columns across all processors integer :: nump ! total number of pfts across all processors - type(bounds_type) :: bounds + type(bounds_type) :: bounds character(len=*),parameter :: subname = 'masterlist_addfld' !------------------------------------------------------------------------ @@ -673,7 +673,7 @@ subroutine htapes_fieldlist() fexcl(:,8) = hist_fexcl8(:) fexcl(:,9) = hist_fexcl9(:) fexcl(:,10) = hist_fexcl10(:) - + ! First ensure contents of fincl and fexcl are valid names @@ -853,7 +853,7 @@ end subroutine htapes_fieldlist logical function is_mapping_upto_subgrid( type1d, type1d_out ) result ( mapping) ! ! !DESCRIPTION: - ! + ! ! Return true if this field will be mapped into a higher subgrid level ! If false it will be output on it's native grid ! @@ -909,7 +909,7 @@ subroutine htape_addfld (t, f, avgflag) integer :: beg1d_out,end1d_out ! history output per-proc 1d beginning and ending indices integer :: beg1d,end1d ! beginning and ending indices for this field (assume already set) integer :: num1d_out ! history output 1d size - type(bounds_type) :: bounds + type(bounds_type) :: bounds character(len=*),parameter :: subname = 'htape_addfld' !----------------------------------------------------------------------- @@ -1012,7 +1012,7 @@ subroutine htape_addfld (t, f, avgflag) ! Fields native bounds beg1d = masterlist(f)%field%beg1d end1d = masterlist(f)%field%end1d - + ! Alloccate and initialize history buffer and related info num2d = tape(t)%hlist(n)%field%num2d @@ -1050,7 +1050,7 @@ subroutine hist_update_hbuf(bounds) ! into its history buffer for appropriate tapes. ! ! !ARGUMENTS: - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds ! ! !LOCAL VARIABLES: integer :: t ! tape index @@ -1064,7 +1064,7 @@ subroutine hist_update_hbuf(bounds) !$OMP PARALLEL DO PRIVATE (f, num2d) do f = 1,tape(t)%nflds num2d = tape(t)%hlist(f)%field%num2d - if ( num2d == 1) then + if ( num2d == 1) then call hist_update_hbuf_field_1d (t, f, bounds) else call hist_update_hbuf_field_2d (t, f, bounds, num2d) @@ -1092,7 +1092,7 @@ subroutine hist_update_hbuf_field_1d (t, f, bounds) ! !ARGUMENTS: integer, intent(in) :: t ! tape index integer, intent(in) :: f ! field index - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds ! ! !LOCAL VARIABLES: integer :: hpindex ! history pointer index @@ -1306,7 +1306,7 @@ subroutine hist_update_hbuf_field_1d (t, f, bounds) if ( end1d .eq. ubound(field,1) ) then k_offset = 0 else - k_offset = 1 - beg1d + k_offset = 1 - beg1d endif do k = beg1d,end1d valid = .true. @@ -1386,7 +1386,7 @@ subroutine hist_update_hbuf_field_2d (t, f, bounds, num2d) ! !ARGUMENTS: integer, intent(in) :: t ! tape index integer, intent(in) :: f ! field index - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds integer, intent(in) :: num2d ! size of second dimension ! ! !LOCAL VARIABLES: @@ -1409,7 +1409,7 @@ subroutine hist_update_hbuf_field_2d (t, f, bounds, num2d) integer , pointer :: nacs(:,:) ! accumulation counter real(r8), pointer :: field(:,:) ! clm 2d pointer field logical :: field_allocated! whether 'field' was allocated here - logical , pointer :: active(:) ! flag saying whether each point is active (used for type1d = landunit/column/pft) + logical , pointer :: active(:) ! flag saying whether each point is active (used for type1d = landunit/column/pft) !(this refers to a point being active, NOT a history field being active) real(r8), allocatable :: field_gcell(:,:) ! gridcell level field (used if mapping to gridcell is done) character(len=*),parameter :: subname = 'hist_update_hbuf_field_2d' @@ -1709,7 +1709,7 @@ end subroutine hist_update_hbuf_field_2d subroutine hist_set_snow_field_2d (field_out, field_in, no_snow_behavior, type1d, beg1d, end1d) ! ! !DESCRIPTION: - ! Set values in history field dimensioned by levsno. + ! Set values in history field dimensioned by levsno. ! ! This routine handles what to do when a given snow layer doesn't exist for a given ! point, based on the no_snow_behavior argument. Options are: @@ -1779,7 +1779,7 @@ subroutine hist_set_snow_field_2d (field_out, field_in, no_snow_behavior, type1d num_snow_layers = abs(snl(c)) num_nonexistent_layers = num_levels - num_snow_layers - + ! Fill output field appropriately for each layer ! When only a subset of snow layers exist, it is the LAST num_snow_layers that exist ! Levels are rearranged such that the top snow layer (surface layer) becomes level 1, etc. @@ -1790,7 +1790,7 @@ subroutine hist_set_snow_field_2d (field_out, field_in, no_snow_behavior, type1d do level = (num_levels-num_nonexistent_layers), 1, -1 field_out(point, level) = field_in(point, level+num_nonexistent_layers) end do - + end do end associate @@ -1942,7 +1942,7 @@ subroutine htape_create (t, histrest) else lnfid => nfid(t) endif - + ! BUG(wjs, 2014-10-20, bugz 1730) Workaround for ! http://bugs.cgd.ucar.edu/show_bug.cgi?id=1730 ! - 1-d hist files have problems with pnetcdf. A better workaround in terms of @@ -2055,7 +2055,7 @@ subroutine htape_create (t, histrest) call ncd_defdim(lnfid, 'string_length', hist_dim_name_length, strlen_dimid) call ncd_defdim(lnfid, 'scale_type_string_length', scale_type_strlen, dimid) call ncd_defdim( lnfid, 'levdcmp', nlevdecomp_full, dimid) - + if(use_fates)then call ncd_defdim(lnfid, 'fates_levscag', nlevsclass * nlevage, dimid) call ncd_defdim(lnfid, 'fates_levscls', nlevsclass, dimid) @@ -2106,7 +2106,7 @@ subroutine htape_add_ltype_metadata(lnfid) character(len=*), parameter :: subname = 'htape_add_ltype_metadata' !----------------------------------------------------------------------- - + do ltype = 1, max_lunit attname = att_prefix // landunit_names(ltype) call ncd_putatt(lnfid, ncd_global, attname, ltype) @@ -2157,7 +2157,7 @@ subroutine htape_add_natpft_metadata(lnfid) character(len=*), parameter :: subname = 'htape_add_natpft_metadata' !----------------------------------------------------------------------- - + do ptype = natpft_lb, natpft_ub ptype_1_indexing = ptype + (1 - natpft_lb) attname = att_prefix // pftname(ptype) @@ -2187,7 +2187,7 @@ subroutine htape_add_cft_metadata(lnfid) character(len=*), parameter :: subname = 'htape_add_cft_metadata' !----------------------------------------------------------------------- - + do ptype = cft_lb, cft_ub ptype_1_indexing = ptype + (1 - cft_lb) attname = att_prefix // pftname(ptype) @@ -2215,11 +2215,11 @@ subroutine htape_timeconst3D(t, & ! ! !ARGUMENTS: integer , intent(in) :: t ! tape index - type(bounds_type) , intent(in) :: bounds - real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) - real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) + type(bounds_type) , intent(in) :: bounds + real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) + real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) character(len=*) , intent(in) :: mode ! 'define' or 'write' ! ! !LOCAL VARIABLES: @@ -2435,7 +2435,7 @@ subroutine htape_timeconst3D(t, & l = col%landunit(c) if (lun%lakpoi(l)) then ! Field indices MUST match varnamesl array order above! - if (ifld ==1) histil(c,lev) = col%z_lake(c,lev) + if (ifld ==1) histil(c,lev) = col%z_lake(c,lev) if (ifld ==2) histil(c,lev) = col%dz_lake(c,lev) end if end do @@ -2546,9 +2546,9 @@ subroutine htape_timeconst(t, mode) long_name='coordinate lake levels', units='m', ncid=nfid(t)) call ncd_defvar(varname='levdcmp', xtype=tape(t)%ncprec, dim1name='levdcmp', & long_name='coordinate soil levels', units='m', ncid=nfid(t)) - + if(use_fates)then - + call ncd_defvar(varname='fates_levscls', xtype=tape(t)%ncprec, dim1name='fates_levscls', & long_name='FATES diameter size class lower bound', units='cm', ncid=nfid(t)) call ncd_defvar(varname='fates_scmap_levscag', xtype=ncd_int, dim1name='fates_levscag', & @@ -2632,7 +2632,7 @@ subroutine htape_timeconst(t, mode) dim1id(1) = time_dimid str = 'days since ' // basedate // " " // basesec call ncd_defvar(nfid(t), 'time', tape(t)%ncprec, 1, dim1id, varid, & - long_name='time',units=str) + long_name='time',units=str) cal = get_calendar() if ( trim(cal) == NO_LEAP_C )then caldesc = "noleap" @@ -2653,7 +2653,7 @@ subroutine htape_timeconst(t, mode) else sec_hist_nhtfrq = hist_nhtfrq(t) end if - + dtime = get_step_size() if (sec_hist_nhtfrq == 0) then !month time_period_freq = 'month_1' @@ -3021,7 +3021,7 @@ subroutine hfields_1dinfo(t, mode) integer , pointer :: ilarr(:) ! temporary integer , pointer :: iparr(:) ! temporary type(file_desc_t), pointer :: ncid ! netcdf file - type(bounds_type) :: bounds + type(bounds_type) :: bounds character(len=*),parameter :: subname = 'hfields_1dinfo' !----------------------------------------------------------------------- @@ -3342,11 +3342,11 @@ subroutine hist_htapes_wrapup( rstwr, nlend, bounds, & ! !ARGUMENTS: logical, intent(in) :: rstwr ! true => write restart file this step logical, intent(in) :: nlend ! true => end of run on this step - type(bounds_type) , intent(in) :: bounds - real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) - real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) + type(bounds_type) , intent(in) :: bounds + real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) + real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) ! ! !LOCAL VARIABLES: integer :: t ! tape index @@ -3530,8 +3530,8 @@ subroutine hist_htapes_wrapup( rstwr, nlend, bounds, & endif end do - ! Reset number of time samples to zero if file is full - + ! Reset number of time samples to zero if file is full + do t = 1, ntapes if (.not. history_tape_in_use(t)) then cycle @@ -3541,7 +3541,7 @@ subroutine hist_htapes_wrapup( rstwr, nlend, bounds, & tape(t)%ntimes = 0 end if end do - + end subroutine hist_htapes_wrapup !----------------------------------------------------------------------- @@ -3563,7 +3563,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) use pio ! ! !ARGUMENTS: - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds type(file_desc_t), intent(inout) :: ncid ! netcdf file character(len=*) , intent(in) :: flag !'read' or 'write' character(len=*) , intent(in), optional :: rdate ! restart file time stamp for name @@ -3693,7 +3693,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) ier = PIO_put_att(ncid, vardesc%varid, 'interpinic_flag', iflag_skip) ! max_nflds is the maximum number of fields on any tape - ! max_flds is the maximum number possible number of fields + ! max_flds is the maximum number possible number of fields max_nflds = max_nFields() @@ -3726,7 +3726,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) num2d = tape(t)%hlist(f)%field%num2d nacs => tape(t)%hlist(f)%nacs hbuf => tape(t)%hlist(f)%hbuf - + if (type1d_out == grlnd) then if (ldomain%isgrid2d) then dim1name = 'lon' ; dim2name = 'lat' @@ -3736,10 +3736,10 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) else dim1name = type1d_out ; dim2name = 'undefined' endif - + if (dim2name == 'undefined') then if (num2d == 1) then - call ncd_defvar(ncid=ncid_hist(t), varname=trim(name), xtype=ncd_double, & + call ncd_defvar(ncid=ncid_hist(t), varname=trim(name), xtype=ncd_double, & dim1name=dim1name, & long_name=trim(long_name), units=trim(units)) call ncd_defvar(ncid=ncid_hist(t), varname=trim(name_acc), xtype=ncd_int, & @@ -3781,9 +3781,9 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_defdim( ncid_hist(t), 'avgflag_len' , avgflag_strlen, dimid) call ncd_defdim( ncid_hist(t), 'scalar' , 1 , dimid) call ncd_defdim( ncid_hist(t), 'max_chars' , max_chars , dimid) - call ncd_defdim( ncid_hist(t), 'max_nflds' , max_nflds , dimid) - call ncd_defdim( ncid_hist(t), 'max_flds' , max_flds , dimid) - + call ncd_defdim( ncid_hist(t), 'max_nflds' , max_nflds , dimid) + call ncd_defdim( ncid_hist(t), 'max_flds' , max_flds , dimid) + call ncd_defvar(ncid=ncid_hist(t), varname='nhtfrq', xtype=ncd_int, & long_name="Frequency of history writes", & comment="Namelist item", & @@ -3823,7 +3823,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_defvar(ncid=ncid_hist(t), varname='begtime', xtype=ncd_double, & long_name="Beginning time", units="time units", & dim1name='scalar') - + call ncd_defvar(ncid=ncid_hist(t), varname='num2d', xtype=ncd_int, & long_name="Size of second dimension", units="unitless", & dim1name='max_nflds' ) @@ -3865,7 +3865,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_enddef(ncid_hist(t)) - end do ! end of ntapes loop + end do ! end of ntapes loop RETURN @@ -3889,7 +3889,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_io('locfnh', my_locfnh, 'write', ncid, nt=t) call ncd_io('locfnhr', my_locfnhr, 'write', ncid, nt=t) end do - + fincl(:,1) = hist_fincl1(:) fincl(:,2) = hist_fincl2(:) fincl(:,3) = hist_fincl3(:) @@ -3938,7 +3938,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) itemp(:) = 0 do f=1,tape(t)%nflds itemp(f) = tape(t)%hlist(f)%field%num2d - end do + end do call ncd_io(varname='num2d', data=itemp(:), ncid=ncid_hist(t), flag='write') itemp(:) = 0 @@ -3981,7 +3981,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_io('l2g_scale_type', l2g_scale_type, 'write', ncid_hist(t)) deallocate(tname,tlongname,tunits,tmpstr,tavgflag) deallocate(p2c_scale_type, c2l_scale_type, l2g_scale_type) - enddo + enddo deallocate(itemp) ! @@ -4035,7 +4035,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) end if ! Determine necessary indices - the following is needed if model decomposition is different on restart - + start(1)=1 if ( is_restart() )then @@ -4050,7 +4050,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) if ( t == 1 )then call ncd_inqdlen(ncid_hist(1),dimid,max_nflds,name='max_nflds') - + allocate(itemp(max_nflds)) end if @@ -4233,7 +4233,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) hist_fexcl10(:) = fexcl(:,10) end if - + if ( allocated(itemp) ) deallocate(itemp) end if @@ -4244,8 +4244,8 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) ! so that subsequent time samples are added until the file is full. ! A new history file is used on a branch run. !====================================================================== - - if (flag == 'write') then + + if (flag == 'write') then do t = 1,ntapes if (.not. history_tape_in_use(t)) then @@ -4272,7 +4272,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) write(iulog,*) trim(subname),' ERROR: allocation' call endrun(msg=errMsg(sourcefile, __LINE__)) end if - + hbuf1d(beg1d_out:end1d_out) = hbuf(beg1d_out:end1d_out,1) nacs1d(beg1d_out:end1d_out) = nacs(beg1d_out:end1d_out,1) @@ -4296,9 +4296,9 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_pio_closefile(ncid_hist(t)) - end do ! end of ntapes loop + end do ! end of ntapes loop - else if (flag == 'read') then + else if (flag == 'read') then ! Read history restart information if history files are not full @@ -4319,7 +4319,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) end1d_out = tape(t)%hlist(f)%field%end1d_out nacs => tape(t)%hlist(f)%nacs hbuf => tape(t)%hlist(f)%hbuf - + if (num2d == 1) then allocate(hbuf1d(beg1d_out:end1d_out), & nacs1d(beg1d_out:end1d_out), stat=status) @@ -4327,15 +4327,15 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) write(iulog,*) trim(subname),' ERROR: allocation' call endrun(msg=errMsg(sourcefile, __LINE__)) end if - + call ncd_io(ncid=ncid_hist(t), flag='read', varname=trim(name), & dim1name=type1d_out, data=hbuf1d) call ncd_io(ncid=ncid_hist(t), flag='read', varname=trim(name_acc), & dim1name=type1d_out, data=nacs1d) - + hbuf(beg1d_out:end1d_out,1) = hbuf1d(beg1d_out:end1d_out) nacs(beg1d_out:end1d_out,1) = nacs1d(beg1d_out:end1d_out) - + deallocate(hbuf1d) deallocate(nacs1d) else @@ -4347,13 +4347,13 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) end do end if - + call ncd_pio_closefile(ncid_hist(t)) - + end do - + end if - + end subroutine hist_restart_ncd !----------------------------------------------------------------------- @@ -4375,7 +4375,7 @@ integer function max_nFields() end do return end function max_nFields - + !----------------------------------------------------------------------- character(len=max_namlen) function getname (inname) ! @@ -4572,7 +4572,7 @@ subroutine hist_addfld1d (fname, units, avgflag, long_name, type1d_out, & character(len=scale_type_strlen) :: scale_type_p2c ! scale type for subgrid averaging of pfts to column character(len=scale_type_strlen) :: scale_type_c2l ! scale type for subgrid averaging of columns to landunits character(len=scale_type_strlen) :: scale_type_l2g ! scale type for subgrid averaging of landunits to gridcells - type(bounds_type):: bounds ! boudns + type(bounds_type):: bounds ! boudns character(len=16):: l_default ! local version of 'default' character(len=*),parameter :: subname = 'hist_addfld1d' !------------------------------------------------------------------------ @@ -4798,13 +4798,13 @@ subroutine hist_addfld2d (fname, type2d, units, avgflag, long_name, type1d_out, character(len=scale_type_strlen) :: scale_type_p2c ! scale type for subgrid averaging of pfts to column character(len=scale_type_strlen) :: scale_type_c2l ! scale type for subgrid averaging of columns to landunits character(len=scale_type_strlen) :: scale_type_l2g ! scale type for subgrid averaging of landunits to gridcells - type(bounds_type):: bounds + type(bounds_type):: bounds character(len=16):: l_default ! local version of 'default' character(len=*),parameter :: subname = 'hist_addfld2d' !------------------------------------------------------------------------ call get_proc_bounds(bounds) - + ! Error-check no_snow_behavior optional argument: It should be present if and only if ! type2d is 'levsno', and its value should be one of the public no_snow_* parameters ! defined above. @@ -4883,7 +4883,7 @@ subroutine hist_addfld2d (fname, type2d, units, avgflag, long_name, type1d_out, case ('levsno') num2d = nlevsno case ('nlevcan') - num2d = nlevcan + num2d = nlevcan case ('nvegwcs') num2d = nvegwcs case default @@ -5184,12 +5184,12 @@ end subroutine hist_add_subscript subroutine strip_null(str) character(len=*), intent(inout) :: str - integer :: i + integer :: i do i=1,len(str) if(ichar(str(i:i))==0) str(i:i)=' ' end do end subroutine strip_null - + !------------------------------------------------------------------------ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, rstwr, nlend) ! @@ -5209,7 +5209,7 @@ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, logical, intent(out) :: if_stop !true => last time step of run logical, intent(out) :: if_disphist(ntapes) !true => save and dispose history file logical, intent(in) :: rstwr - logical, intent(in) :: nlend + logical, intent(in) :: nlend ! ! !LOCAL VARIABLES: integer :: t ! history tape index @@ -5219,26 +5219,26 @@ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, rest_now = .false. stop_now = .false. - + if (nlend) stop_now = .true. if (rstwr) rest_now = .true. - + if_stop = stop_now - + if (stop_now) then ! End of run - dispose all history files - + if_disphist(1:ntapes) = .true. - + else if (rest_now) then ! Restart - dispose all history files - + do t = 1,ntapes if_disphist(t) = .true. end do else ! Dispose - + if_disphist(1:ntapes) = .false. do t = 1,ntapes if (hist_ntimes(t) == hist_mfilt(t)) then @@ -5246,7 +5246,7 @@ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, endif end do endif - + end subroutine hist_do_disp !----------------------------------------------------------------------- @@ -5286,4 +5286,3 @@ end function avgflag_valid end module histFileMod - diff --git a/src/main/ncdio_pio.F90.in b/src/main/ncdio_pio.F90.in index f4a8dcfad1..0e3469ebbd 100644 --- a/src/main/ncdio_pio.F90.in +++ b/src/main/ncdio_pio.F90.in @@ -9,7 +9,7 @@ module ncdio_pio ! Generic interfaces to write fields to netcdf files for CLM ! ! !USES: - use shr_kind_mod , only : r8 => shr_kind_r8, i4=>shr_kind_i4, shr_kind_cl + use shr_kind_mod , only : r8 => shr_kind_r8, i4=>shr_kind_i4, shr_kind_cl, r4 => shr_kind_r4 use shr_infnan_mod , only : nan => shr_infnan_nan, isnan => shr_infnan_isnan, assignment(=) use shr_sys_mod , only : shr_sys_abort use shr_file_mod , only : shr_file_getunit, shr_file_freeunit @@ -33,6 +33,7 @@ module ncdio_pio use pio , only : pio_put_att, pio_put_var, pio_read_darray, pio_real, pio_seterrorhandling use pio , only : pio_setframe, pio_unlimited, pio_write, pio_write_darray, var_desc_t use pio , only : pio_iotask_rank, PIO_REARR_SUBSET, PIO_REARR_BOX + use pio , only : pio_set_log_level, pio_inq_vartype ! ! !PUBLIC TYPES: implicit none @@ -217,7 +218,7 @@ contains ! !ARGUMENTS: class(file_desc_t), intent(inout) :: file ! PIO file handle to close !----------------------------------------------------------------------- - + integer :: ierr call pio_closefile(file) end subroutine ncd_pio_closefile @@ -1457,13 +1458,13 @@ contains if(present(nt)) ndims=ndims+1 call ncd_inqvid (ncid, varname, varid, vardesc) #if ({DIMS}==0) - temp(1) = data if (present(nt)) then + temp(1) = data start(1) = nt count(1) = 1 status = pio_put_var(ncid, varid, start(1:1), count(1:1), temp) else - status = pio_put_var(ncid, varid, temp) + status = pio_put_var(ncid, varid, data) end if #elif ({DIMS}==1) start(1) = 1 ; count(1) = size(data) @@ -1611,6 +1612,7 @@ contains integer :: count(3) ! netcdf count index integer :: status ! error code logical :: varpresent ! if true, variable is on tape + integer :: xtype ! type of var in file integer , pointer :: idata(:) ! Temporary integer data to send to file type(iodesc_plus_type) , pointer :: iodesc_plus type(var_desc_t) :: vardesc @@ -1683,13 +1685,11 @@ contains do n = 1,ndims_iod status = pio_inq_dimlen(ncid,dids(n),dims(n)) enddo -#if ({ITYPE}==TYPELOGICAL) - call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_INT, iodnum) -#else + status = pio_inq_vartype(ncid, vardesc, xtype) + call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum) -#endif + xtype, iodnum) + iodesc_plus => iodesc_list(iodnum) if (present(nt)) then call pio_setframe(ncid, vardesc, int(nt,kind=Pio_Offset_Kind)) @@ -1729,13 +1729,9 @@ contains do n = 1,ndims_iod status = pio_inq_dimlen(ncid,dids(n),dims(n)) enddo -#if ({ITYPE}==TYPELOGICAL) - call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_INT, iodnum) -#else + status = pio_inq_vartype(ncid, vardesc, xtype) call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum) -#endif + xtype, iodnum) iodesc_plus => iodesc_list(iodnum) if (present(nt)) then call pio_setframe(ncid, vardesc, int(nt,kind=Pio_Offset_Kind)) @@ -1752,7 +1748,11 @@ contains #elif ({ITYPE}==TYPEINT) call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, data, status, fillval=ispval) #elif ({ITYPE}==TYPEDOUBLE) - call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, data, status, fillval=spval) + if (iodesc_plus%type == pio_double) then + call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, data, status, fillval=spval) + else + call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, real(data,kind=r4), status, fillval=real(spval,kind=r4)) + endif #endif else @@ -1808,6 +1808,7 @@ contains logical :: varpresent ! if true, variable is on tape integer :: lb1,lb2 integer :: ub1,ub2 + integer :: xtype ! netcdf type of variable on file type(iodesc_plus_type) , pointer :: iodesc_plus type(var_desc_t) :: vardesc character(len=*),parameter :: subname='ncd_io_2d_{TYPE}' ! subroutine name @@ -1890,12 +1891,13 @@ contains do n = 1,ndims_iod status = pio_inq_dimlen(ncid,dids(n),dims(n)) enddo + status = pio_inq_vartype(ncid, vardesc, xtype) if (present(switchdim)) then call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum, switchdim=.true.) + xtype, iodnum, switchdim=.true.) else call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum) + xtype, iodnum) end if iodesc_plus => iodesc_list(iodnum) if (present(nt)) then @@ -1944,12 +1946,13 @@ contains do n = 1,ndims_iod status = pio_inq_dimlen(ncid,dids(n),dims(n)) enddo + status = pio_inq_vartype(ncid, vardesc, xtype) if (present(switchdim)) then call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum, switchdim=.true.) + xtype, iodnum, switchdim=.true.) else call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum) + xtype, iodnum) end if iodesc_plus => iodesc_list(iodnum) if (present(nt)) then @@ -2031,6 +2034,7 @@ contains integer :: iodnum ! iodesc num in list integer :: start(5) ! netcdf start index integer :: count(5) ! netcdf count index + integer :: xtype ! netcdf type of variable on file logical :: varpresent ! if true, variable is on tape type(iodesc_plus_type) , pointer :: iodesc_plus type(var_desc_t) :: vardesc @@ -2087,8 +2091,9 @@ contains do n = 1,ndims_iod status = pio_inq_dimlen(ncid,dids(n),dims(n)) enddo + status = pio_inq_vartype(ncid, vardesc, xtype) call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum) + xtype, iodnum) iodesc_plus => iodesc_list(iodnum) if (present(nt)) then call pio_setframe(ncid, vardesc, int(nt,kind=Pio_Offset_Kind)) @@ -2116,8 +2121,9 @@ contains do n = 1,ndims_iod status = pio_inq_dimlen(ncid,dids(n),dims(n)) enddo + status = pio_inq_vartype(ncid, vardesc, xtype) call ncd_getiodesc(ncid, clmlevel, ndims_iod, dims(1:ndims_iod), dids(1:ndims_iod), & - PIO_{TYPE}, iodnum) + xtype, iodnum) iodesc_plus => iodesc_list(iodnum) if (present(nt)) then call pio_setframe(ncid, vardesc, int(nt,kind=Pio_Offset_Kind)) @@ -2516,10 +2522,10 @@ contains deallocate(gsmOP) - call pio_initdecomp(pio_subsystem, baseTYPE, dims(1:ndims), compDOF, iodesc_list(iodnum)%iodesc) +! call pio_initdecomp(pio_subsystem, baseTYPE, dims(1:ndims), compDOF, iodesc_list(iodnum)%iodesc) + call pio_initdecomp(pio_subsystem, xTYPE, dims(1:ndims), compDOF, iodesc_list(iodnum)%iodesc) deallocate(compDOF) - iodesc_list(iodnum)%type = xtype iodesc_list(iodnum)%ndims = ndims iodesc_list(iodnum)%dims = 0 From 814e8809a2d3464c7741a07279861abc02905f10 Mon Sep 17 00:00:00 2001 From: Jim Edwards Date: Mon, 30 Dec 2019 13:31:52 -0700 Subject: [PATCH 201/255] follow through --- src/main/ncdio_pio.F90.in | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/src/main/ncdio_pio.F90.in b/src/main/ncdio_pio.F90.in index 0e3469ebbd..3ccc9f19a4 100644 --- a/src/main/ncdio_pio.F90.in +++ b/src/main/ncdio_pio.F90.in @@ -33,7 +33,7 @@ module ncdio_pio use pio , only : pio_put_att, pio_put_var, pio_read_darray, pio_real, pio_seterrorhandling use pio , only : pio_setframe, pio_unlimited, pio_write, pio_write_darray, var_desc_t use pio , only : pio_iotask_rank, PIO_REARR_SUBSET, PIO_REARR_BOX - use pio , only : pio_set_log_level, pio_inq_vartype + use pio , only : pio_inq_vartype ! ! !PUBLIC TYPES: implicit none @@ -1809,6 +1809,7 @@ contains integer :: lb1,lb2 integer :: ub1,ub2 integer :: xtype ! netcdf type of variable on file + type(iodesc_plus_type) , pointer :: iodesc_plus type(var_desc_t) :: vardesc character(len=*),parameter :: subname='ncd_io_2d_{TYPE}' ! subroutine name @@ -1972,11 +1973,19 @@ contains call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, data, status, fillval=ispval) end if #else - if (present(switchdim)) then - call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, temp, status, fillval=spval) + if (iodesc_plus%type == pio_double) then + if (present(switchdim)) then + call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, temp, status, fillval=spval) + else + call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, data, status, fillval=spval) + end if else - call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, data, status, fillval=spval) - end if + if (present(switchdim)) then + call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, real(temp, kind=r4), status, fillval=real(spval, kind=r4)) + else + call pio_write_darray(ncid, vardesc, iodesc_plus%iodesc, real(data, kind=r4), status, fillval=real(spval, kind=r4)) + end if + endif if ( present(cnvrtnan2fill) )then do j = lb2,ub2 do i = lb1,ub1 From 54f009f714f7ce5af54c4ef090c983c0eb276891 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Mon, 30 Dec 2019 13:45:28 -0700 Subject: [PATCH 202/255] updates for aux_clm testing --- cime_config/testdefs/testlist_clm.xml | 250 ++++++++++---------- cime_config/testdefs/testlist_clm_nuopc.xml | 38 +-- src/cpl/nuopc/lnd_comp_nuopc.F90 | 11 +- 3 files changed, 152 insertions(+), 147 deletions(-) diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index 5920b85901..ed5c675f3e 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -100,7 +100,7 @@ - + @@ -108,7 +108,7 @@ - + @@ -116,7 +116,7 @@ - + @@ -157,7 +157,7 @@ - + @@ -165,7 +165,7 @@ - + @@ -174,7 +174,7 @@ - + @@ -183,7 +183,7 @@ - + @@ -191,7 +191,7 @@ - + @@ -199,7 +199,7 @@ - + @@ -207,16 +207,16 @@ - + - + - + @@ -224,7 +224,7 @@ - + @@ -232,7 +232,7 @@ - + @@ -240,7 +240,7 @@ - + @@ -248,7 +248,7 @@ - + @@ -256,7 +256,7 @@ - + @@ -265,7 +265,7 @@ - + @@ -273,7 +273,7 @@ - + @@ -282,7 +282,7 @@ - + @@ -290,7 +290,7 @@ - + @@ -298,7 +298,7 @@ - + @@ -306,7 +306,7 @@ - + @@ -314,7 +314,7 @@ - + @@ -324,7 +324,7 @@ - + @@ -332,7 +332,7 @@ - + @@ -340,7 +340,7 @@ - + @@ -348,7 +348,7 @@ - + @@ -359,7 +359,7 @@ - + @@ -367,7 +367,7 @@ - + @@ -375,7 +375,7 @@ - + @@ -383,7 +383,7 @@ - + @@ -391,7 +391,7 @@ - + @@ -400,7 +400,7 @@ - + @@ -409,16 +409,16 @@ - + - + - + @@ -436,7 +436,7 @@ - + @@ -444,7 +444,7 @@ - + @@ -460,7 +460,7 @@ - + @@ -469,7 +469,7 @@ - + @@ -477,7 +477,7 @@ - + @@ -485,7 +485,7 @@ - + @@ -494,7 +494,7 @@ - + @@ -502,7 +502,7 @@ - + @@ -510,7 +510,7 @@ - + @@ -518,7 +518,7 @@ - + @@ -526,7 +526,7 @@ - + @@ -534,7 +534,7 @@ - + @@ -542,7 +542,7 @@ - + @@ -550,7 +550,7 @@ - + @@ -558,7 +558,7 @@ - + @@ -566,16 +566,16 @@ - + - + - + @@ -593,7 +593,7 @@ - + @@ -601,7 +601,7 @@ - + @@ -609,7 +609,7 @@ - + @@ -617,7 +617,7 @@ - + @@ -627,7 +627,7 @@ - + @@ -637,7 +637,7 @@ - + @@ -646,7 +646,7 @@ - + @@ -656,7 +656,7 @@ - + @@ -665,7 +665,7 @@ - + @@ -673,7 +673,7 @@ - + @@ -682,7 +682,7 @@ - + @@ -690,16 +690,16 @@ - + - + - + @@ -709,7 +709,7 @@ - + @@ -717,7 +717,7 @@ - + @@ -726,7 +726,7 @@ - + @@ -736,12 +736,12 @@ - + - + @@ -754,7 +754,7 @@ - + @@ -786,11 +786,11 @@ - + - + @@ -842,7 +842,7 @@ - + @@ -859,7 +859,7 @@ - + @@ -876,7 +876,7 @@ - + @@ -884,7 +884,7 @@ - + @@ -892,7 +892,7 @@ - + @@ -900,7 +900,7 @@ - + @@ -909,7 +909,7 @@ - + @@ -918,7 +918,7 @@ - + @@ -927,7 +927,7 @@ - + @@ -946,7 +946,7 @@ - + @@ -955,7 +955,7 @@ - + @@ -964,7 +964,7 @@ - + @@ -978,7 +978,7 @@ - + @@ -990,7 +990,7 @@ - + @@ -1009,7 +1009,7 @@ - + @@ -1068,14 +1068,14 @@ - + - + @@ -1125,7 +1125,7 @@ - + @@ -1133,7 +1133,7 @@ - + @@ -1141,7 +1141,7 @@ - + @@ -1151,7 +1151,7 @@ - + @@ -1172,7 +1172,7 @@ - + @@ -1234,7 +1234,7 @@ - + @@ -1243,7 +1243,7 @@ - + @@ -1262,7 +1262,7 @@ - + @@ -1305,7 +1305,7 @@ - + @@ -1313,7 +1313,7 @@ - + @@ -1323,7 +1323,7 @@ - + @@ -1331,7 +1331,7 @@ - + @@ -1417,7 +1417,7 @@ - + @@ -1425,7 +1425,7 @@ - + @@ -1468,7 +1468,7 @@ - + @@ -1477,7 +1477,7 @@ - + @@ -1514,7 +1514,7 @@ - + @@ -1523,7 +1523,7 @@ - + @@ -1531,7 +1531,7 @@ - + @@ -1541,7 +1541,7 @@ - + @@ -1664,13 +1664,13 @@ - + - + @@ -1686,13 +1686,13 @@ - + - + @@ -1722,7 +1722,7 @@ - + @@ -1730,7 +1730,7 @@ - + @@ -1738,7 +1738,7 @@ - + @@ -1746,7 +1746,7 @@ - + @@ -1781,7 +1781,7 @@ - + @@ -1876,7 +1876,7 @@ - + @@ -1886,7 +1886,7 @@ - + diff --git a/cime_config/testdefs/testlist_clm_nuopc.xml b/cime_config/testdefs/testlist_clm_nuopc.xml index 00ab21d38e..0578ecd5f4 100644 --- a/cime_config/testdefs/testlist_clm_nuopc.xml +++ b/cime_config/testdefs/testlist_clm_nuopc.xml @@ -1,3 +1,5 @@ +PET_P36x1_D_Vnuopc.f10_f10_musgs.I1850Clm50BgcCrop.cheyenne_intel.clm-default + @@ -100,7 +102,7 @@ - + @@ -256,7 +258,7 @@ - + @@ -432,7 +434,7 @@ - + @@ -740,7 +742,7 @@ - + @@ -859,7 +861,7 @@ - + @@ -900,7 +902,7 @@ - + @@ -909,7 +911,7 @@ - + @@ -918,7 +920,7 @@ - + @@ -927,7 +929,7 @@ - + @@ -946,7 +948,7 @@ - + @@ -964,7 +966,7 @@ - + @@ -990,7 +992,7 @@ - + @@ -1074,7 +1076,7 @@ - + @@ -1262,7 +1264,7 @@ - + @@ -1417,7 +1419,7 @@ - + @@ -1425,7 +1427,7 @@ - + @@ -1781,7 +1783,7 @@ - + @@ -1876,7 +1878,7 @@ - + diff --git a/src/cpl/nuopc/lnd_comp_nuopc.F90 b/src/cpl/nuopc/lnd_comp_nuopc.F90 index f11b7014c1..4c26b42205 100644 --- a/src/cpl/nuopc/lnd_comp_nuopc.F90 +++ b/src/cpl/nuopc/lnd_comp_nuopc.F90 @@ -325,7 +325,7 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) integer, intent(out) :: rc ! local variables - type(ESMF_Mesh) :: mesh ! esmf mesh + type(ESMF_Mesh) :: mesh, gridmesh ! esmf mesh type(ESMF_DistGrid) :: DistGrid ! esmf global index space descriptor type(ESMF_Time) :: currTime ! Current time type(ESMF_Time) :: startTime ! Start time @@ -574,7 +574,7 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) ! generate the mesh and realize fields !-------------------------------- - ! read in the mesh + ! determine if the mesh will be created or read in call NUOPC_CompAttributeGet(gcomp, name='mesh_lnd', value=cvalue, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return @@ -621,14 +621,17 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) maxcornerCoord(1) = xv(3,ni,nj) ! max lon maxcornerCoord(2) = yv(3,ni,nj) ! max lat deallocate(xv,yv) - write(6,*)'DEBUG: maxcornerCoord = ',maxcornerCoord lgrid = ESMF_GridCreateNoPeriDimUfrm (maxindex=maxindex, & mincornercoord=mincornercoord, maxcornercoord= maxcornercoord, & staggerloclist=(/ESMF_STAGGERLOC_CENTER, ESMF_STAGGERLOC_CORNER/), rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return ! create the mesh from the grid - mesh = ESMF_MeshCreate(lgrid, rc=rc) + gridmesh = ESMF_MeshCreate(lgrid, rc=rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + + ! Now redistribute the mesh to use the internal distrid + mesh = ESMF_MeshCreate(gridmesh, elementDistgrid=Distgrid, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return else ! read in the mesh from the file From 913c4476c4991397270474148b2697d9006527fe Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 2 Jan 2020 14:21:52 -0700 Subject: [PATCH 203/255] Add figures for tools chapter, the section on the details of running mksurfdata_map seems to be missing --- .../using-clm-tools/creating-domain-files.rst | 27 ++++++++++++------- ...g-input-for-surface-dataset-generation.rst | 14 +++++----- .../creating-surface-datasets.rst | 22 +++++++++------ 3 files changed, 40 insertions(+), 23 deletions(-) diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst index c804a7bea7..eb4f19471d 100644 --- a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -6,24 +6,33 @@ Creating CLM domain files ***************************** -*gen_domain* to create a domain file for datm from a mapping file. **gen_domain** is a tool that is a part of CIME. The domain file is then used by BOTH DATM AND CLM to define the grid and land-mask. The general data flow is shown in two figures. `Figure 2-4 `_ shows the general flow for a general global case (or for a regional grid that DOES include ocean). `Figure 2-5 `_ shows the use of **mknoocnmap.pl** (see `the Section called Using mknocnmap.pl to create grid and maps for single-point regional grids `_) to create a regional or single-point map file that is then run through **gen_domain** to create the domain file for it. As stated before `Figure 2-2 `_ is the legend for both of these figures. See `the +*gen_domain* to create a domain file for datm from a mapping file. **gen_domain** is a tool that is a part of CIME. The domain file is then used by BOTH DATM AND CLM to define the grid and land-mask. The general data flow is shown in two figures. :numref:`Figure mkmapdata.sh` shows the general flow for a general global case (or for a regional grid that DOES include ocean). :numref:`Figure mknoocnmap.pl` shows the use of **mknoocnmap.pl** (see `the Section called Using mknocnmap.pl to create grid and maps for single-point regional grids `_) to create a regional or single-point map file that is then run through **gen_domain** to create the domain file for it. As stated before :numref:`Figure Data_Flow_Legend` is the legend for both of these figures. See `the $CIMEROOT/tools/mapping/gen_domain_files/README `_ file for more help on **gen_domain**. Here we create domain files for a regular global domain. -Figure 2-4. Global Domain file creation -======================================= +Global Domain file creation +=========================== -Insert figure 2-4 +.. _Figure Global-Domain -Starting from SCRIP grid files for both your atmosphere and ocean, you use **$CIMEROOT/tools/mapping/gen_mapping_files/gen_cesm_maps.sh** to create a mapping file between the atmosphere and ocean. That mapping file is then used as input to **gen_domain** to create output domain files for both atmosphere and ocean. The atmosphere domain file is then used by both CLM and DATM for I compsets, while the ocean domain file is ignored. For this process you have to define your SCRIP grid files on your own. For a regional or single-point case that doesn't include ocean see `Figure 2-5 `_. (See `Figure 2-2 `_ for the legend for this figure.) +.. figure:: GlobalDomain.jpeg + +Global Domain file creation + +Starting from SCRIP grid files for both your atmosphere and ocean, you use **$CIMEROOT/tools/mapping/gen_mapping_files/gen_cesm_maps.sh** to create a mapping file between the atmosphere and ocean. That mapping file is then used as input to **gen_domain** to create output domain files for both atmosphere and ocean. The atmosphere domain file is then used by both CLM and DATM for I compsets, while the ocean domain file is ignored. For this process you have to define your SCRIP grid files on your own. For a regional or single-point case that doesn't include ocean see :numref:`Figure mknoocnmap.pl`. (See :numref:`Figure Global-Domain` for the legend for this figure.) Note, that the SCRIP grid file used to start this process, is also used in **mkmapdata.sh** (see `the Section called Creating mapping files that mksurfdata_map will use `_). Next we create domain files for a single-point or regional domain. -Figure 2-5. Domain file creation using mknoocnmap.pl -==================================================== -Insert figure 2-5 +Domain file creation using mknoocnmap.pl +======================================== + +.. _Figure mknoocnmap.pl + +.. figure:: mknoocnmap.jpeg + +Domain file creation using mknoocnmap.pl -For a regular latitude/longitude grid that can be used for regional or single point simulations -- you can use **mknoocnmap.pl**. It creates a SCRIP grid file that can then be used as input to **mkmapdata.sh** as well as a SCRIP mapping file that is then input to **gen_domain**. The output of **gen_domain** is a atmosphere domain file used by both CLM and DATM and a ocean domain file that is ignored. (See `Figure 2-2 `_ for the legend for this figure.) +For a regular latitude/longitude grid that can be used for regional or single point simulations -- you can use **mknoocnmap.pl**. It creates a SCRIP grid file that can then be used as input to **mkmapdata.sh** as well as a SCRIP mapping file that is then input to **gen_domain**. The output of **gen_domain** is a atmosphere domain file used by both CLM and DATM and a ocean domain file that is ignored. (See :numref:`Figure mknoocnmap.pl` for the legend for this figure.) In this case the process creates both SCRIP grid files to be used by **mkmapdata.sh** as well as the domain files that will be used by both CLM and DATM. diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index c044c283af..c1a2f1e637 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -37,7 +37,7 @@ If you want to create a regular latitude/longitude single-point or regional grid -nx Number of longitudes (default is 1) -ny Number of latitudes (default is 1) -See `Figure 2-5 `_ for a visual representation of this process. +See :numref:`Figure mknoocnmap.pl` for a visual representation of this process. 2. Creating mapping files for mksurfdata_map @@ -48,7 +48,7 @@ See `Figure 2-5 `_ for a visual representation of this process. The bash shell script ``$CTSMROOT/tools/mkmapgrids/mkmapdata.sh`` uses **ESMF_RegridWeightGen** to create a list of maps from the raw datasets that are input to **mksurfdata_map**. Each dataset that has a different grid, or land-mask needs a different mapping file for it, but many different raw datasets share the same grid/land-mask as other files. Hence, there doesn't need to be a different mapping file for EACH raw dataset -- just for each raw dataset that has a DIFFERENT grid or land-mask.. -See `Figure 2-3 `_ for a visual representation of how this works. +See :numref:`Figure mkmapdata.sh` for a visual representation of how this works. The bash script figures out which mapping files it needs to create and then runs **ESMF_RegridWeightGen** for each one. You can then either enter the datasets into the XML database (see `Chapter 3 `_ or leave the files in place, and use the "-res usrspec -usr_gname -usr_gdate" options to **mksurfdata_map** (see `the Section called Running mksurfdata.pl `_ below). mkmapdata.sh has a help option with the following @@ -105,8 +105,10 @@ mkmapdata.sh has a help option with the following ********************** -Figure 2-3. Details of running mkmapdata.sh -------------------------------------------- -Insert figure 2-3 +.. _Figure mkmapdata.sh -Each of the raw datasets for **mksurfdata_map** needs a mapping file to map from the output grid you are running on to the grid and land-mask for that dataset. This is what **mkmapdata.sh** does. To create the mapping files you need a SCRIP grid file to correspond with each resolution and land mask that you have a raw data file in **mksurfdata_map**. Some raw datasets share the same grid and land mask -- hence they can share the same SCRIP grid file. The output maps created here go into **mksurfdata_map** see `Figure 2-6 `_. +.. figure:: mkmapdata_details.jpeg + +Details of running mkmapdata.sh + +Each of the raw datasets for **mksurfdata_map** needs a mapping file to map from the output grid you are running on to the grid and land-mask for that dataset. This is what **mkmapdata.sh** does. To create the mapping files you need a SCRIP grid file to correspond with each resolution and land mask that you have a raw data file in **mksurfdata_map**. Some raw datasets share the same grid and land mask -- hence they can share the same SCRIP grid file. The output maps created here go into **mksurfdata_map** see :numref:`Figure mksurfdatamap`. diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index c5a5644034..bc9469a4ad 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -6,17 +6,23 @@ Creating Surface Datasets =========================== -When just creating a replacement file for an existing one, the relevant tool should be used directly to create the file. When you are creating a set of files for a new resolution there are some dependencies between the tools that you need to keep in mind when creating them. The main dependency is that you MUST create a SCRIP grid file first as the SCRIP grid dataset is then input into the other tools. Also look at `Table 3-1 `_ which gives information on the files required and when. `Figure 2-1 `_ shows an overview of the general data-flow for creation of the fsurdat datasets. +When just creating a replacement file for an existing one, the relevant tool should be used directly to create the file. When you are creating a set of files for a new resolution there are some dependencies between the tools that you need to keep in mind when creating them. The main dependency is that you MUST create a SCRIP grid file first as the SCRIP grid dataset is then input into the other tools. Also look at `Table 3-1 `_ which gives information on the files required and when. :numref:`Figure Data_Flow` shows an overview of the general data-flow for creation of the fsurdat datasets. -Figure 2-1. Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files --------------------------------------------------------------------------------- -Insert figure 2-1 +.. _Figure Data_Flow -Starting from a SCRIP grid file that describes the grid you will run the model on, you first run **mkmapdata.sh** to create a list of mapping files. See `Figure 2-3 `_ for a more detailed view of how **mkmapdata.sh** works. The mapping files tell **mksurfdata_map** how to map between the output grid and the raw datasets that it uses as input. The output of **mksurfdata_map** is a surface dataset that you then use for running the model. See `Figure 2-6 `_ for a more detailed view of how **mksurfdata_map** works. +.. figure:: mkmapdata_mksurfdata.jpeg -`Figure 2-2 `_ is the legend for this figure (`Figure 2-1 `_) and other figures in this chapter (`Figure 2-4 `_, `Figure 2-5 `_, and `Figure 2-6 `_). -Figure 2-2. Legend for Data Flow Figures -Insert figure 2-2 +Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files + +Starting from a SCRIP grid file that describes the grid you will run the model on, you first run **mkmapdata.sh** to create a list of mapping files. See :numref:`Figure mkmapdata.sh` for a more detailed view of how **mkmapdata.sh** works. The mapping files tell **mksurfdata_map** how to map between the output grid and the raw datasets that it uses as input. The output of **mksurfdata_map** is a surface dataset that you then use for running the model. See `Figure :numref:`Figure mksurfdatamap` for a more detailed view of how **mksurfdata_map** works. + +:numref:`Figure Data_Flow_Legend` is the legend for this figure (:numref:`Figure Data_Flow`) and other figures in this chapter (:numref:`Figure Global_Domain`, :numref:`Figure mknoocnmap.pl` and :numref:`Figure mksurfdatamap`). + +.. _Figure Data_Flow_Legend + +.. figure:: LegendCLMToolDataFlow.jpeg + +Legend for Data Flow Figures Green arrows define the input to a program, while red arrows define the output. Cylinders define files that are either created by a program or used as input for a program. Boxes are programs. From 48be76a4cc0fa9853eae7ecfbdbbba5f9f941c29 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 2 Jan 2020 15:33:21 -0700 Subject: [PATCH 204/255] Add figures to tools for users guide --- .../users_guide/using-clm-tools/creating-domain-files.rst | 4 ++-- .../creating-input-for-surface-dataset-generation.rst | 2 +- .../users_guide/using-clm-tools/creating-surface-datasets.rst | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst index eb4f19471d..9e61bfce7f 100644 --- a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -18,7 +18,7 @@ Global Domain file creation .. figure:: GlobalDomain.jpeg -Global Domain file creation + Global Domain file creation Starting from SCRIP grid files for both your atmosphere and ocean, you use **$CIMEROOT/tools/mapping/gen_mapping_files/gen_cesm_maps.sh** to create a mapping file between the atmosphere and ocean. That mapping file is then used as input to **gen_domain** to create output domain files for both atmosphere and ocean. The atmosphere domain file is then used by both CLM and DATM for I compsets, while the ocean domain file is ignored. For this process you have to define your SCRIP grid files on your own. For a regional or single-point case that doesn't include ocean see :numref:`Figure mknoocnmap.pl`. (See :numref:`Figure Global-Domain` for the legend for this figure.) @@ -31,7 +31,7 @@ Domain file creation using mknoocnmap.pl .. figure:: mknoocnmap.jpeg -Domain file creation using mknoocnmap.pl + Domain file creation using mknoocnmap.pl For a regular latitude/longitude grid that can be used for regional or single point simulations -- you can use **mknoocnmap.pl**. It creates a SCRIP grid file that can then be used as input to **mkmapdata.sh** as well as a SCRIP mapping file that is then input to **gen_domain**. The output of **gen_domain** is a atmosphere domain file used by both CLM and DATM and a ocean domain file that is ignored. (See :numref:`Figure mknoocnmap.pl` for the legend for this figure.) diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index c1a2f1e637..6877a1f1e5 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -109,6 +109,6 @@ mkmapdata.sh has a help option with the following .. figure:: mkmapdata_details.jpeg -Details of running mkmapdata.sh + Details of running mkmapdata.sh Each of the raw datasets for **mksurfdata_map** needs a mapping file to map from the output grid you are running on to the grid and land-mask for that dataset. This is what **mkmapdata.sh** does. To create the mapping files you need a SCRIP grid file to correspond with each resolution and land mask that you have a raw data file in **mksurfdata_map**. Some raw datasets share the same grid and land mask -- hence they can share the same SCRIP grid file. The output maps created here go into **mksurfdata_map** see :numref:`Figure mksurfdatamap`. diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index bc9469a4ad..7db5817adf 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -12,7 +12,7 @@ When just creating a replacement file for an existing one, the relevant tool sho .. figure:: mkmapdata_mksurfdata.jpeg -Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files + Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files Starting from a SCRIP grid file that describes the grid you will run the model on, you first run **mkmapdata.sh** to create a list of mapping files. See :numref:`Figure mkmapdata.sh` for a more detailed view of how **mkmapdata.sh** works. The mapping files tell **mksurfdata_map** how to map between the output grid and the raw datasets that it uses as input. The output of **mksurfdata_map** is a surface dataset that you then use for running the model. See `Figure :numref:`Figure mksurfdatamap` for a more detailed view of how **mksurfdata_map** works. @@ -22,7 +22,7 @@ Starting from a SCRIP grid file that describes the grid you will run the model o .. figure:: LegendCLMToolDataFlow.jpeg -Legend for Data Flow Figures + Legend for Data Flow Figures Green arrows define the input to a program, while red arrows define the output. Cylinders define files that are either created by a program or used as input for a program. Boxes are programs. From bc307472162ac8393ef5bb06e68013341fe89025 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Thu, 2 Jan 2020 16:59:24 -0700 Subject: [PATCH 205/255] Add missing colons to figure targets --- .../users_guide/using-clm-tools/creating-domain-files.rst | 4 ++-- .../creating-input-for-surface-dataset-generation.rst | 2 +- .../users_guide/using-clm-tools/creating-surface-datasets.rst | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst index 9e61bfce7f..972967da0c 100644 --- a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -14,7 +14,7 @@ Here we create domain files for a regular global domain. Global Domain file creation =========================== -.. _Figure Global-Domain +.. _Figure Global-Domain: .. figure:: GlobalDomain.jpeg @@ -27,7 +27,7 @@ Note, that the SCRIP grid file used to start this process, is also used in **mkm Domain file creation using mknoocnmap.pl ======================================== -.. _Figure mknoocnmap.pl +.. _Figure mknoocnmap.pl: .. figure:: mknoocnmap.jpeg diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index 6877a1f1e5..6048baa98c 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -105,7 +105,7 @@ mkmapdata.sh has a help option with the following ********************** -.. _Figure mkmapdata.sh +.. _Figure mkmapdata.sh: .. figure:: mkmapdata_details.jpeg diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index 7db5817adf..ce02fec2f6 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -8,7 +8,7 @@ When just creating a replacement file for an existing one, the relevant tool should be used directly to create the file. When you are creating a set of files for a new resolution there are some dependencies between the tools that you need to keep in mind when creating them. The main dependency is that you MUST create a SCRIP grid file first as the SCRIP grid dataset is then input into the other tools. Also look at `Table 3-1 `_ which gives information on the files required and when. :numref:`Figure Data_Flow` shows an overview of the general data-flow for creation of the fsurdat datasets. -.. _Figure Data_Flow +.. _Figure Data_Flow: .. figure:: mkmapdata_mksurfdata.jpeg @@ -18,7 +18,7 @@ Starting from a SCRIP grid file that describes the grid you will run the model o :numref:`Figure Data_Flow_Legend` is the legend for this figure (:numref:`Figure Data_Flow`) and other figures in this chapter (:numref:`Figure Global_Domain`, :numref:`Figure mknoocnmap.pl` and :numref:`Figure mksurfdatamap`). -.. _Figure Data_Flow_Legend +.. _Figure Data_Flow_Legend: .. figure:: LegendCLMToolDataFlow.jpeg From 1fb57761e33c701863330f549a09458b016a77cb Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Thu, 9 Jan 2020 16:32:25 -0700 Subject: [PATCH 206/255] updates to have single point runs not have to change compsets --- cime_config/config_compsets.xml | 14 +++- cime_config/testdefs/testlist_clm.xml | 96 +++++++++++++-------------- src/cpl/nuopc/lnd_comp_nuopc.F90 | 2 +- 3 files changed, 61 insertions(+), 51 deletions(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index bf0cb94221..f3e1448df3 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -37,12 +37,12 @@ - I1PtClm50SpRsGs + I1PtClm50SpGs 2000_DATM%1PT_CLM50%SP_SICE_SOCN_SROF_SGLC_SWAV - I1PtClm45SpRsGs + I1PtClm45SpGs 2000_DATM%1PT_CLM45%SP_SICE_SOCN_SROF_SGLC_SWAV @@ -53,6 +53,16 @@ 2000_DATM%GSWP3v1_CLM50%SP_SICE_SOCN_MOSART_CISM2%NOEVOLVE_SWAV + + + IHistClm50BgcRsGs + HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV + + + IHistClm50SpRsGs + HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV + + I2000Clm50SpRsGs diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index ed5c675f3e..16d16853a3 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -8,7 +8,7 @@ - + @@ -100,7 +100,7 @@ - + @@ -212,7 +212,7 @@ - + @@ -415,7 +415,7 @@ - + @@ -432,7 +432,7 @@ - + @@ -572,7 +572,7 @@ - + @@ -696,7 +696,7 @@ - + @@ -741,7 +741,7 @@ - + @@ -786,7 +786,7 @@ - + @@ -842,7 +842,7 @@ - + @@ -859,7 +859,7 @@ - + @@ -876,7 +876,7 @@ - + @@ -884,7 +884,7 @@ - + @@ -892,7 +892,7 @@ - + @@ -900,7 +900,7 @@ - + @@ -909,7 +909,7 @@ - + @@ -918,7 +918,7 @@ - + @@ -927,7 +927,7 @@ - + @@ -946,7 +946,7 @@ - + @@ -964,7 +964,7 @@ - + @@ -978,7 +978,7 @@ - + @@ -990,7 +990,7 @@ - + @@ -1075,7 +1075,7 @@ - + @@ -1125,7 +1125,7 @@ - + @@ -1133,7 +1133,7 @@ - + @@ -1141,7 +1141,7 @@ - + @@ -1151,7 +1151,7 @@ - + @@ -1234,7 +1234,7 @@ - + @@ -1243,7 +1243,7 @@ - + @@ -1262,7 +1262,7 @@ - + @@ -1305,7 +1305,7 @@ - + @@ -1313,7 +1313,7 @@ - + @@ -1323,7 +1323,7 @@ - + @@ -1331,7 +1331,7 @@ - + @@ -1417,7 +1417,7 @@ - + @@ -1425,7 +1425,7 @@ - + @@ -1468,7 +1468,7 @@ - + @@ -1477,7 +1477,7 @@ - + @@ -1514,7 +1514,7 @@ - + @@ -1523,7 +1523,7 @@ - + @@ -1531,7 +1531,7 @@ - + @@ -1541,7 +1541,7 @@ - + @@ -1670,7 +1670,7 @@ - + @@ -1692,7 +1692,7 @@ - + @@ -1781,7 +1781,7 @@ - + @@ -1849,7 +1849,7 @@ - + @@ -1876,7 +1876,7 @@ - + @@ -1886,7 +1886,7 @@ - + diff --git a/src/cpl/nuopc/lnd_comp_nuopc.F90 b/src/cpl/nuopc/lnd_comp_nuopc.F90 index 4c26b42205..c15677fd9c 100644 --- a/src/cpl/nuopc/lnd_comp_nuopc.F90 +++ b/src/cpl/nuopc/lnd_comp_nuopc.F90 @@ -66,7 +66,7 @@ module lnd_comp_nuopc logical :: glc_present logical :: rof_prognostic - integer, parameter :: dbug = 1 + integer, parameter :: dbug = 0 character(*),parameter :: modName = "(lnd_comp_nuopc)" character(*),parameter :: u_FILE_u = & __FILE__ From 48864209fe4a1bbd15a011595c5072164460c288 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Thu, 9 Jan 2020 16:33:25 -0700 Subject: [PATCH 207/255] changes to have orbital calculation done in cap --- cime_config/config_compsets.xml | 10 + src/cpl/mct/lnd_comp_mct.F90 | 7 + src/cpl/nuopc/lnd_comp_nuopc.F90 | 292 +++++++++++++++++++++------- src/cpl/nuopc/lnd_import_export.F90 | 6 + src/main/clm_initializeMod.F90 | 11 +- src/main/surfrdMod.F90 | 2 +- 6 files changed, 246 insertions(+), 82 deletions(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index f3e1448df3..7ca17cf1cf 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -63,6 +63,16 @@ HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV + + + IHistClm50BgcRsGs + HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV + + + IHistClm50SpRsGs + HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV + + I2000Clm50SpRsGs diff --git a/src/cpl/mct/lnd_comp_mct.F90 b/src/cpl/mct/lnd_comp_mct.F90 index 8a8f86342b..f1d385cc30 100644 --- a/src/cpl/mct/lnd_comp_mct.F90 +++ b/src/cpl/mct/lnd_comp_mct.F90 @@ -156,6 +156,13 @@ subroutine lnd_init_mct( EClock, cdata_l, x2l_l, l2x_l, NLFilename ) call seq_infodata_GetData( infodata, orb_eccen=eccen, orb_mvelpp=mvelpp, & orb_lambm0=lambm0, orb_obliqr=obliqr ) + if (masterproc) then + write(iulog,*)' orb_eccen = ',eccen + write(iulog,*)' orb_obliqr = ',obliqr + write(iulog,*)' orb_lambm0 = ',lambm0 + write(iulog,*)' orb_mvelpp = ',mvelpp + end if + ! Consistency check on namelist filename call control_setNL("lnd_in"//trim(inst_suffix)) diff --git a/src/cpl/nuopc/lnd_comp_nuopc.F90 b/src/cpl/nuopc/lnd_comp_nuopc.F90 index c15677fd9c..4b94aad763 100644 --- a/src/cpl/nuopc/lnd_comp_nuopc.F90 +++ b/src/cpl/nuopc/lnd_comp_nuopc.F90 @@ -5,42 +5,42 @@ module lnd_comp_nuopc !---------------------------------------------------------------------------- use ESMF - use NUOPC , only : NUOPC_CompDerive, NUOPC_CompSetEntryPoint, NUOPC_CompSpecialize - use NUOPC , only : NUOPC_CompFilterPhaseMap, NUOPC_CompAttributeGet, NUOPC_CompAttributeSet - use NUOPC_Model , only : model_routine_SS => SetServices - use NUOPC_Model , only : model_label_Advance => label_Advance - use NUOPC_Model , only : model_label_DataInitialize => label_DataInitialize - use NUOPC_Model , only : model_label_SetRunClock => label_SetRunClock - use NUOPC_Model , only : model_label_Finalize => label_Finalize - use NUOPC_Model , only : NUOPC_ModelGet - use shr_kind_mod , only : r8 => shr_kind_r8, cl=>shr_kind_cl - use shr_sys_mod , only : shr_sys_abort - use shr_file_mod , only : shr_file_getlogunit, shr_file_setlogunit - use shr_orb_mod , only : shr_orb_decl - use shr_cal_mod , only : shr_cal_noleap, shr_cal_gregorian, shr_cal_ymd2date - use spmdMod , only : masterproc, mpicom, spmd_init - use decompMod , only : bounds_type, ldecomp, get_proc_bounds - use domainMod , only : ldomain - use controlMod , only : control_setNL - use clm_varorb , only : eccen, obliqr, lambm0, mvelpp - use clm_varctl , only : inst_index, inst_suffix, inst_name - use clm_varctl , only : single_column, clm_varctl_set, iulog - use clm_varctl , only : nsrStartup, nsrContinue, nsrBranch - use clm_varcon , only : re - use clm_time_manager , only : set_timemgr_init, advance_timestep - use clm_time_manager , only : set_nextsw_cday, update_rad_dtime - use clm_time_manager , only : get_nstep, get_step_size - use clm_time_manager , only : get_curr_date, get_curr_calday - use clm_initializeMod , only : initialize1, initialize2 - use clm_driver , only : clm_drv - use lnd_import_export , only : advertise_fields, realize_fields - use lnd_import_export , only : import_fields, export_fields - use lnd_shr_methods , only : chkerr, state_setscalar, state_getscalar, state_diagnose, alarmInit - use lnd_shr_methods , only : set_component_logging, get_component_instance, log_clock_advance - use perf_mod , only : t_startf, t_stopf, t_barrierf - use netcdf , only : nf90_open, nf90_nowrite, nf90_noerr, nf90_close, nf90_strerror - use netcdf , only : nf90_inq_dimid, nf90_inq_varid, nf90_get_var - use netcdf , only : nf90_inquire_dimension, nf90_inquire_variable + use NUOPC , only : NUOPC_CompDerive, NUOPC_CompSetEntryPoint, NUOPC_CompSpecialize + use NUOPC , only : NUOPC_CompFilterPhaseMap, NUOPC_CompAttributeGet, NUOPC_CompAttributeSet + use NUOPC_Model , only : model_routine_SS => SetServices + use NUOPC_Model , only : model_label_Advance => label_Advance + use NUOPC_Model , only : model_label_DataInitialize => label_DataInitialize + use NUOPC_Model , only : model_label_SetRunClock => label_SetRunClock + use NUOPC_Model , only : model_label_Finalize => label_Finalize + use NUOPC_Model , only : NUOPC_ModelGet + use shr_kind_mod , only : r8 => shr_kind_r8, cl=>shr_kind_cl + use shr_sys_mod , only : shr_sys_abort + use shr_file_mod , only : shr_file_getlogunit, shr_file_setlogunit + use shr_orb_mod , only : shr_orb_decl, shr_orb_params, SHR_ORB_UNDEF_REAL, SHR_ORB_UNDEF_INT + use shr_cal_mod , only : shr_cal_noleap, shr_cal_gregorian, shr_cal_ymd2date + use spmdMod , only : masterproc, mpicom, spmd_init + use decompMod , only : bounds_type, ldecomp, get_proc_bounds + use domainMod , only : ldomain + use controlMod , only : control_setNL + use clm_varorb , only : eccen, obliqr, lambm0, mvelpp + use clm_varctl , only : inst_index, inst_suffix, inst_name + use clm_varctl , only : single_column, clm_varctl_set, iulog + use clm_varctl , only : nsrStartup, nsrContinue, nsrBranch + use clm_varcon , only : re + use clm_time_manager , only : set_timemgr_init, advance_timestep + use clm_time_manager , only : set_nextsw_cday, update_rad_dtime + use clm_time_manager , only : get_nstep, get_step_size + use clm_time_manager , only : get_curr_date, get_curr_calday + use clm_initializeMod , only : initialize1, initialize2 + use clm_driver , only : clm_drv + use lnd_import_export , only : advertise_fields, realize_fields + use lnd_import_export , only : import_fields, export_fields + use lnd_shr_methods , only : chkerr, state_setscalar, state_getscalar, state_diagnose, alarmInit + use lnd_shr_methods , only : set_component_logging, get_component_instance, log_clock_advance + use perf_mod , only : t_startf, t_stopf, t_barrierf + use netcdf , only : nf90_open, nf90_nowrite, nf90_noerr, nf90_close, nf90_strerror + use netcdf , only : nf90_inq_dimid, nf90_inq_varid, nf90_get_var + use netcdf , only : nf90_inquire_dimension, nf90_inquire_variable implicit none private ! except @@ -53,6 +53,8 @@ module lnd_comp_nuopc private :: ModelSetRunClock private :: ModelAdvance private :: ModelFinalize + private :: clm_orbital_init + private :: clm_orbital_update !-------------------------------------------------------------------------- ! Private module data @@ -71,6 +73,17 @@ module lnd_comp_nuopc character(*),parameter :: u_FILE_u = & __FILE__ + character(len=CL) :: orb_mode ! attribute - orbital mode + integer :: orb_iyear ! attribute - orbital year + integer :: orb_iyear_align ! attribute - associated with model year + real(R8) :: orb_obliq ! attribute - obliquity in degrees + real(R8) :: orb_mvelp ! attribute - moving vernal equinox longitude + real(R8) :: orb_eccen ! attribute and update- orbital eccentricity + + character(len=*) , parameter :: orb_fixed_year = 'fixed_year' + character(len=*) , parameter :: orb_variable_year = 'variable_year' + character(len=*) , parameter :: orb_fixed_parameters = 'fixed_parameters' + !=============================================================================== contains !=============================================================================== @@ -407,24 +420,6 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) ! Obtain attribute values !---------------------- - ! Note - the orbital inquiries set the values in clm_varorb via the module use statements - - call NUOPC_CompAttributeGet(gcomp, name='orb_eccen', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) eccen - - call NUOPC_CompAttributeGet(gcomp, name='orb_obliqr', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) obliqr - - call NUOPC_CompAttributeGet(gcomp, name='orb_lambm0', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) lambm0 - - call NUOPC_CompAttributeGet(gcomp, name='orb_mvelpp', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) mvelpp - call NUOPC_CompAttributeGet(gcomp, name='case_name', value=cvalue, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return read(cvalue,*) caseid @@ -515,6 +510,16 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) call shr_sys_abort( subname//'ERROR:: bad calendar for ESMF' ) end if + !---------------------- + ! Initialize module orbital values and update orbital + !---------------------- + + call clm_orbital_init(gcomp, iulog, masterproc, rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + + call clm_orbital_update(clock, iulog, masterproc, eccen, obliqr, lambm0, mvelpp, rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + !---------------------- ! Initialize CTSM time manager !---------------------- @@ -545,6 +550,12 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) ! note that the memory for gindex_ocn will be allocated in the following call call initialize1(gindex_ocn) + ! If no land then abort for now + ! TODO: need to handle the case of noland with CMEPS + ! if ( noland ) then + ! call shr_sys_abort(trim(subname)//"ERROR: Currently cannot handle case of single column with non-land") + ! end if + ! obtain global index array for just land points which includes mask=0 or ocean points call get_proc_bounds( bounds ) nlnd = bounds%endg - bounds%begg + 1 @@ -577,6 +588,7 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) ! determine if the mesh will be created or read in call NUOPC_CompAttributeGet(gcomp, name='mesh_lnd', value=cvalue, rc=rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return + if (single_column) cvalue = 'create_mesh' if (cvalue == 'create_mesh') then ! get the datm grid from the domain file @@ -774,7 +786,7 @@ subroutine ModelAdvance(gcomp, rc) ! Run CTSM !------------------------ - use clm_instMod , only : water_inst, atm2lnd_inst, glc2lnd_inst, lnd2atm_inst, lnd2glc_inst + use clm_instMod, only : water_inst, atm2lnd_inst, glc2lnd_inst, lnd2atm_inst, lnd2glc_inst ! input/output variables type(ESMF_GridComp) :: gcomp @@ -848,24 +860,9 @@ subroutine ModelAdvance(gcomp, rc) call set_nextsw_cday( nextsw_cday ) !---------------------- - ! Obtain orbital values + ! Get orbital values !---------------------- - call NUOPC_CompAttributeGet(gcomp, name='orb_eccen', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) eccen - - call NUOPC_CompAttributeGet(gcomp, name='orb_obliqr', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) obliqr - - call NUOPC_CompAttributeGet(gcomp, name='orb_lambm0', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) lambm0 - - call NUOPC_CompAttributeGet(gcomp, name='orb_mvelpp', value=cvalue, rc=rc) - if (ChkErr(rc,__LINE__,u_FILE_u)) return - read(cvalue,*) mvelpp !-------------------------------- ! Unpack import state @@ -949,6 +946,11 @@ subroutine ModelAdvance(gcomp, rc) call t_barrierf('sync_ctsm_run1', mpicom) call t_startf ('shr_orb_decl') + + ! Note - the orbital inquiries set the values in clm_varorb via the module use statements + call clm_orbital_update(clock, iulog, masterproc, eccen, obliqr, lambm0, mvelpp, rc) + if (ChkErr(rc,__LINE__,u_FILE_u)) return + calday = get_curr_calday() call shr_orb_decl( calday , eccen, mvelpp, lambm0, obliqr, declin , eccf ) call shr_orb_decl( nextsw_cday, eccen, mvelpp, lambm0, obliqr, declinp1, eccf ) @@ -1199,6 +1201,154 @@ end subroutine ModelFinalize !=============================================================================== + subroutine clm_orbital_init(gcomp, logunit, mastertask, rc) + + !---------------------------------------------------------- + ! Initialize orbital related values + !---------------------------------------------------------- + + ! input/output variables + type(ESMF_GridComp) , intent(in) :: gcomp + integer , intent(in) :: logunit + logical , intent(in) :: mastertask + integer , intent(out) :: rc ! output error + + ! local variables + character(len=CL) :: msgstr ! temporary + character(len=CL) :: cvalue ! temporary + character(len=*) , parameter :: subname = "(clm_orbital_init)" + !------------------------------------------------------------------------------- + + rc = ESMF_SUCCESS + + ! Determine orbital attributes from input + call NUOPC_CompAttributeGet(gcomp, name="orb_mode", value=cvalue, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + read(cvalue,*) orb_mode + + call NUOPC_CompAttributeGet(gcomp, name="orb_iyear", value=cvalue, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + read(cvalue,*) orb_iyear + + call NUOPC_CompAttributeGet(gcomp, name="orb_iyear_align", value=cvalue, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + read(cvalue,*) orb_iyear_align + + call NUOPC_CompAttributeGet(gcomp, name="orb_obliq", value=cvalue, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + read(cvalue,*) orb_obliq + + call NUOPC_CompAttributeGet(gcomp, name="orb_eccen", value=cvalue, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + read(cvalue,*) orb_eccen + + call NUOPC_CompAttributeGet(gcomp, name="orb_mvelp", value=cvalue, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + read(cvalue,*) orb_mvelp + + ! Error checks + if (trim(orb_mode) == trim(orb_fixed_year)) then + orb_obliq = SHR_ORB_UNDEF_REAL + orb_eccen = SHR_ORB_UNDEF_REAL + orb_mvelp = SHR_ORB_UNDEF_REAL + if (orb_iyear == SHR_ORB_UNDEF_INT) then + if (mastertask) then + write(logunit,*) trim(subname),' ERROR: invalid settings orb_mode =',trim(orb_mode) + write(logunit,*) trim(subname),' ERROR: fixed_year settings = ',orb_iyear + write (msgstr, *) ' ERROR: invalid settings for orb_mode '//trim(orb_mode) + end if + call ESMF_LogSetError(ESMF_RC_NOT_VALID, msg=msgstr, line=__LINE__, file=__FILE__, rcToReturn=rc) + return ! bail out + endif + elseif (trim(orb_mode) == trim(orb_variable_year)) then + orb_obliq = SHR_ORB_UNDEF_REAL + orb_eccen = SHR_ORB_UNDEF_REAL + orb_mvelp = SHR_ORB_UNDEF_REAL + if (orb_iyear == SHR_ORB_UNDEF_INT .or. orb_iyear_align == SHR_ORB_UNDEF_INT) then + if (mastertask) then + write(logunit,*) trim(subname),' ERROR: invalid settings orb_mode =',trim(orb_mode) + write(logunit,*) trim(subname),' ERROR: variable_year settings = ',orb_iyear, orb_iyear_align + write (msgstr, *) subname//' ERROR: invalid settings for orb_mode '//trim(orb_mode) + end if + call ESMF_LogSetError(ESMF_RC_NOT_VALID, msg=msgstr, line=__LINE__, file=__FILE__, rcToReturn=rc) + return ! bail out + endif + elseif (trim(orb_mode) == trim(orb_fixed_parameters)) then + !-- force orb_iyear to undef to make sure shr_orb_params works properly + orb_iyear = SHR_ORB_UNDEF_INT + orb_iyear_align = SHR_ORB_UNDEF_INT + if (orb_eccen == SHR_ORB_UNDEF_REAL .or. & + orb_obliq == SHR_ORB_UNDEF_REAL .or. & + orb_mvelp == SHR_ORB_UNDEF_REAL) then + if (mastertask) then + write(logunit,*) trim(subname),' ERROR: invalid settings orb_mode =',trim(orb_mode) + write(logunit,*) trim(subname),' ERROR: orb_eccen = ',orb_eccen + write(logunit,*) trim(subname),' ERROR: orb_obliq = ',orb_obliq + write(logunit,*) trim(subname),' ERROR: orb_mvelp = ',orb_mvelp + write (msgstr, *) subname//' ERROR: invalid settings for orb_mode '//trim(orb_mode) + end if + call ESMF_LogSetError(ESMF_RC_NOT_VALID, msg=msgstr, line=__LINE__, file=__FILE__, rcToReturn=rc) + return ! bail out + endif + else + write (msgstr, *) subname//' ERROR: invalid orb_mode '//trim(orb_mode) + call ESMF_LogSetError(ESMF_RC_NOT_VALID, msg=msgstr, line=__LINE__, file=__FILE__, rcToReturn=rc) + rc = ESMF_FAILURE + return ! bail out + endif + + end subroutine clm_orbital_init + + !=============================================================================== + + subroutine clm_orbital_update(clock, logunit, mastertask, eccen, obliqr, lambm0, mvelpp, rc) + + !---------------------------------------------------------- + ! Update orbital settings + !---------------------------------------------------------- + + ! input/output variables + type(ESMF_Clock) , intent(in) :: clock + integer , intent(in) :: logunit + logical , intent(in) :: mastertask + real(R8) , intent(inout) :: eccen ! orbital eccentricity + real(R8) , intent(inout) :: obliqr ! Earths obliquity in rad + real(R8) , intent(inout) :: lambm0 ! Mean long of perihelion at vernal equinox (radians) + real(R8) , intent(inout) :: mvelpp ! moving vernal equinox longitude of perihelion plus pi (radians) + integer , intent(out) :: rc ! output error + + ! local variables + type(ESMF_Time) :: CurrTime ! current time + integer :: year ! model year at current time + integer :: orb_year ! orbital year for current orbital computation + character(len=CL) :: msgstr ! temporary + character(len=*) , parameter :: subname = "(clm_orbital_update)" + !------------------------------------------- + + if (trim(orb_mode) == trim(orb_variable_year)) then + call ESMF_ClockGet(clock, CurrTime=CurrTime, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + call ESMF_TimeGet(CurrTime, yy=year, rc=rc) + if (chkerr(rc,__LINE__,u_FILE_u)) return + orb_year = orb_iyear + (year - orb_iyear_align) + else + orb_year = orb_iyear + end if + + eccen = orb_eccen + call shr_orb_params(orb_year, eccen, orb_obliq, orb_mvelp, obliqr, lambm0, mvelpp, mastertask) + + if ( eccen == SHR_ORB_UNDEF_REAL .or. obliqr == SHR_ORB_UNDEF_REAL .or. & + mvelpp == SHR_ORB_UNDEF_REAL .or. lambm0 == SHR_ORB_UNDEF_REAL) then + write (msgstr, *) subname//' ERROR: orb params incorrect' + call ESMF_LogSetError(ESMF_RC_NOT_VALID, msg=msgstr, line=__LINE__, file=__FILE__, rcToReturn=rc) + return ! bail out + endif + + end subroutine clm_orbital_update + + !=============================================================================== + subroutine nc_check_err(ierror, description, filename) integer , intent(in) :: ierror character(*), intent(in) :: description diff --git a/src/cpl/nuopc/lnd_import_export.F90 b/src/cpl/nuopc/lnd_import_export.F90 index e4928f37a1..ae0dd12788 100644 --- a/src/cpl/nuopc/lnd_import_export.F90 +++ b/src/cpl/nuopc/lnd_import_export.F90 @@ -592,6 +592,9 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & co2_ppmv_input(g) = dataPtr(g-begg+1) ! co2 atm prognostic end do end if + if (masterproc) then + write(iulog,*)'DEBUG: nstep, Sa_co2diag= ',get_nstep(),co2_ppmv_input(begg) + end if else if (co2_type == 'diagnostic') then fldName = 'Sa_co2diag' call ESMF_StateGet(importState, trim(fldname), itemFlag, rc=rc) @@ -606,6 +609,9 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & co2_ppmv_input(g) = dataPtr(g-begg+1) ! co2 atm diagnostic end do end if + if (masterproc) then + write(iulog,*)'DEBUG: nstep, Sa_co2prog= ',get_nstep(),co2_ppmv_input(begg) + end if end if ! Note that the following does unit conversions from ppmv to partial pressures (Pa) diff --git a/src/main/clm_initializeMod.F90 b/src/main/clm_initializeMod.F90 index b7549eb282..c2015113de 100644 --- a/src/main/clm_initializeMod.F90 +++ b/src/main/clm_initializeMod.F90 @@ -270,13 +270,12 @@ subroutine initialize2( ) ! ! !USES: use shr_orb_mod , only : shr_orb_decl - use shr_scam_mod , only : shr_scam_getCloseLatLon use seq_drydep_mod , only : n_drydep, drydep_method, DD_XLND use accumulMod , only : print_accum_fields use clm_varpar , only : nlevsno use clm_varcon , only : spval use clm_varctl , only : finidat, finidat_interp_source, finidat_interp_dest, fsurdat - use clm_varctl , only : use_century_decomp, single_column, scmlat, scmlon, use_cn, use_fates + use clm_varctl , only : use_century_decomp, use_cn, use_fates use clm_varctl , only : use_crop, ndep_from_cpl use clm_varorb , only : eccen, mvelpp, lambm0, obliqr use clm_time_manager , only : get_step_size_real, get_curr_calday @@ -427,14 +426,6 @@ subroutine initialize2( ) avgflag='A', long_name='convective boundary height', & ptr_col=col%zii, default='inactive') - ! If single-column determine closest latitude and longitude - - if (single_column) then - call getfil (fsurdat, locfn, 0) - call shr_scam_getCloseLatLon(locfn, scmlat, scmlon, & - closelat, closelon, closelatidx, closelonidx) - end if - ! Initialize instances of all derived types as well as time constant variables call clm_instInit(bounds_proc) diff --git a/src/main/surfrdMod.F90 b/src/main/surfrdMod.F90 index e2ea0a06ca..771165459d 100644 --- a/src/main/surfrdMod.F90 +++ b/src/main/surfrdMod.F90 @@ -13,7 +13,7 @@ module surfrdMod use clm_varpar , only : nlevsoifl use landunit_varcon , only : numurbl use clm_varcon , only : grlnd - use clm_varctl , only : iulog, scmlat, scmlon, single_column + use clm_varctl , only : iulog use clm_varctl , only : use_cndv, use_crop use surfrdUtilsMod , only : check_sums_equal_1, collapse_crop_types, collapse_to_dominant, collapse_crop_var, collapse_individual_lunits use ncdio_pio , only : file_desc_t, var_desc_t, ncd_pio_openfile, ncd_pio_closefile From 90ec6c34d6b97e5ad9c26e0b6462ccbf5a6d3eac Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Fri, 10 Jan 2020 22:58:19 -0700 Subject: [PATCH 208/255] updates to have orbital calculation done in cap rather than in driver --- src/cpl/nuopc/lnd_comp_nuopc.F90 | 13 +++++++++++-- src/cpl/nuopc/lnd_import_export.F90 | 10 ++-------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/src/cpl/nuopc/lnd_comp_nuopc.F90 b/src/cpl/nuopc/lnd_comp_nuopc.F90 index 4b94aad763..075c93c8ed 100644 --- a/src/cpl/nuopc/lnd_comp_nuopc.F90 +++ b/src/cpl/nuopc/lnd_comp_nuopc.F90 @@ -517,7 +517,7 @@ subroutine InitializeRealize(gcomp, importState, exportState, clock, rc) call clm_orbital_init(gcomp, iulog, masterproc, rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return - call clm_orbital_update(clock, iulog, masterproc, eccen, obliqr, lambm0, mvelpp, rc) + call clm_orbital_update(clock, iulog, masterproc, eccen, obliqr, lambm0, mvelpp, rc) if (ChkErr(rc,__LINE__,u_FILE_u)) return !---------------------- @@ -1322,6 +1322,8 @@ subroutine clm_orbital_update(clock, logunit, mastertask, eccen, obliqr, lambm0 integer :: year ! model year at current time integer :: orb_year ! orbital year for current orbital computation character(len=CL) :: msgstr ! temporary + logical :: lprint + logical :: first_time = .true. character(len=*) , parameter :: subname = "(clm_orbital_update)" !------------------------------------------- @@ -1331,12 +1333,19 @@ subroutine clm_orbital_update(clock, logunit, mastertask, eccen, obliqr, lambm0 call ESMF_TimeGet(CurrTime, yy=year, rc=rc) if (chkerr(rc,__LINE__,u_FILE_u)) return orb_year = orb_iyear + (year - orb_iyear_align) + lprint = mastertask else orb_year = orb_iyear + if (first_time) then + lprint = mastertask + first_time = .false. + else + lprint = .false. + end if end if eccen = orb_eccen - call shr_orb_params(orb_year, eccen, orb_obliq, orb_mvelp, obliqr, lambm0, mvelpp, mastertask) + call shr_orb_params(orb_year, eccen, orb_obliq, orb_mvelp, obliqr, lambm0, mvelpp, lprint) if ( eccen == SHR_ORB_UNDEF_REAL .or. obliqr == SHR_ORB_UNDEF_REAL .or. & mvelpp == SHR_ORB_UNDEF_REAL .or. lambm0 == SHR_ORB_UNDEF_REAL) then diff --git a/src/cpl/nuopc/lnd_import_export.F90 b/src/cpl/nuopc/lnd_import_export.F90 index ae0dd12788..564348854e 100644 --- a/src/cpl/nuopc/lnd_import_export.F90 +++ b/src/cpl/nuopc/lnd_import_export.F90 @@ -592,9 +592,6 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & co2_ppmv_input(g) = dataPtr(g-begg+1) ! co2 atm prognostic end do end if - if (masterproc) then - write(iulog,*)'DEBUG: nstep, Sa_co2diag= ',get_nstep(),co2_ppmv_input(begg) - end if else if (co2_type == 'diagnostic') then fldName = 'Sa_co2diag' call ESMF_StateGet(importState, trim(fldname), itemFlag, rc=rc) @@ -609,9 +606,6 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & co2_ppmv_input(g) = dataPtr(g-begg+1) ! co2 atm diagnostic end do end if - if (masterproc) then - write(iulog,*)'DEBUG: nstep, Sa_co2prog= ',get_nstep(),co2_ppmv_input(begg) - end if end if ! Note that the following does unit conversions from ppmv to partial pressures (Pa) @@ -1169,7 +1163,7 @@ subroutine state_getimport(state, fldname, bounds, output, ungridded_index, rc) end if ! write debug output if appropriate - if (masterproc .and. debug > 0 .and. get_nstep() < 5) then + if (masterproc .and. debug > 0 .and. get_nstep() < 48) then do g = bounds%begg,bounds%endg i = 1 + g - bounds%begg write(iulog,F01)'import: nstep, n, '//trim(fldname)//' = ',get_nstep(),i,output(g) @@ -1260,7 +1254,7 @@ subroutine state_setexport(state, fldname, bounds, input, minus, ungridded_index end if ! write debug output if appropriate - if (masterproc .and. debug > 0 .and. get_nstep() < 5) then + if (masterproc .and. debug > 0 .and. get_nstep() < 48) then do g = bounds%begg,bounds%endg i = 1 + g - bounds%begg write(iulog,F01)'export: nstep, n, '//trim(fldname)//' = ',get_nstep(),i,input(g) From 57ee75b898d1b321968e5260b8c2ef6680dbb66e Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Tue, 10 Mar 2020 18:43:51 -0600 Subject: [PATCH 209/255] merged to ctsm master --- cime_config/testdefs/testlist_clm.xml | 160 +++++++++++------------ src/cpl/mct/lnd_comp_mct.F90 | 7 -- src/main/clm_initializeMod.F90 | 11 +- src/main/histFileMod.F90 | 175 +++++++++++++------------- 4 files changed, 178 insertions(+), 175 deletions(-) diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index dac9c9d805..84e0145caf 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -100,7 +100,7 @@ - + @@ -108,7 +108,7 @@ - + @@ -116,7 +116,7 @@ - + @@ -157,7 +157,7 @@ - + @@ -165,7 +165,7 @@ - + @@ -174,7 +174,7 @@ - + @@ -183,7 +183,7 @@ - + @@ -191,7 +191,7 @@ - + @@ -199,7 +199,7 @@ - + @@ -207,7 +207,7 @@ - + @@ -216,7 +216,7 @@ - + @@ -224,7 +224,7 @@ - + @@ -232,7 +232,7 @@ - + @@ -240,7 +240,7 @@ - + @@ -248,7 +248,7 @@ - + @@ -265,7 +265,7 @@ - + @@ -273,7 +273,7 @@ - + @@ -282,7 +282,7 @@ - + @@ -290,7 +290,7 @@ - + @@ -298,7 +298,7 @@ - + @@ -306,7 +306,7 @@ - + @@ -314,7 +314,7 @@ - + @@ -324,7 +324,7 @@ - + @@ -332,7 +332,7 @@ - + @@ -340,7 +340,7 @@ - + @@ -348,7 +348,7 @@ - + @@ -359,7 +359,7 @@ - + @@ -367,7 +367,7 @@ - + @@ -375,7 +375,7 @@ - + @@ -383,7 +383,7 @@ - + @@ -391,7 +391,7 @@ - + @@ -400,7 +400,7 @@ - + @@ -409,7 +409,7 @@ - + @@ -418,7 +418,7 @@ - + @@ -436,7 +436,7 @@ - + @@ -444,7 +444,7 @@ - + @@ -460,7 +460,7 @@ - + @@ -469,7 +469,7 @@ - + @@ -477,7 +477,7 @@ - + @@ -485,7 +485,7 @@ - + @@ -494,7 +494,7 @@ - + @@ -502,7 +502,7 @@ - + @@ -510,7 +510,7 @@ - + @@ -518,7 +518,7 @@ - + @@ -526,7 +526,7 @@ - + @@ -534,7 +534,7 @@ - + @@ -542,7 +542,7 @@ - + @@ -550,7 +550,7 @@ - + @@ -558,7 +558,7 @@ - + @@ -566,7 +566,7 @@ - + @@ -575,7 +575,7 @@ - + @@ -593,7 +593,7 @@ - + @@ -601,7 +601,7 @@ - + @@ -609,7 +609,7 @@ - + @@ -617,7 +617,7 @@ - + @@ -627,7 +627,7 @@ - + @@ -637,7 +637,7 @@ - + @@ -646,7 +646,7 @@ - + @@ -656,7 +656,7 @@ - + @@ -665,7 +665,7 @@ - + @@ -673,7 +673,7 @@ - + @@ -682,7 +682,7 @@ - + @@ -690,7 +690,7 @@ - + @@ -699,7 +699,7 @@ - + @@ -709,7 +709,7 @@ - + @@ -717,7 +717,7 @@ - + @@ -726,7 +726,7 @@ - + @@ -736,7 +736,7 @@ - + @@ -754,7 +754,7 @@ - + @@ -790,7 +790,7 @@ - + @@ -955,7 +955,7 @@ - + @@ -1009,7 +1009,7 @@ - + @@ -1068,7 +1068,7 @@ - + @@ -1172,7 +1172,7 @@ - + @@ -1664,7 +1664,7 @@ - + @@ -1686,7 +1686,7 @@ - + @@ -1722,7 +1722,7 @@ - + @@ -1730,7 +1730,7 @@ - + @@ -1738,7 +1738,7 @@ - + @@ -1746,7 +1746,7 @@ - + diff --git a/src/cpl/mct/lnd_comp_mct.F90 b/src/cpl/mct/lnd_comp_mct.F90 index f1d385cc30..8a8f86342b 100644 --- a/src/cpl/mct/lnd_comp_mct.F90 +++ b/src/cpl/mct/lnd_comp_mct.F90 @@ -156,13 +156,6 @@ subroutine lnd_init_mct( EClock, cdata_l, x2l_l, l2x_l, NLFilename ) call seq_infodata_GetData( infodata, orb_eccen=eccen, orb_mvelpp=mvelpp, & orb_lambm0=lambm0, orb_obliqr=obliqr ) - if (masterproc) then - write(iulog,*)' orb_eccen = ',eccen - write(iulog,*)' orb_obliqr = ',obliqr - write(iulog,*)' orb_lambm0 = ',lambm0 - write(iulog,*)' orb_mvelpp = ',mvelpp - end if - ! Consistency check on namelist filename call control_setNL("lnd_in"//trim(inst_suffix)) diff --git a/src/main/clm_initializeMod.F90 b/src/main/clm_initializeMod.F90 index c2015113de..b7549eb282 100644 --- a/src/main/clm_initializeMod.F90 +++ b/src/main/clm_initializeMod.F90 @@ -270,12 +270,13 @@ subroutine initialize2( ) ! ! !USES: use shr_orb_mod , only : shr_orb_decl + use shr_scam_mod , only : shr_scam_getCloseLatLon use seq_drydep_mod , only : n_drydep, drydep_method, DD_XLND use accumulMod , only : print_accum_fields use clm_varpar , only : nlevsno use clm_varcon , only : spval use clm_varctl , only : finidat, finidat_interp_source, finidat_interp_dest, fsurdat - use clm_varctl , only : use_century_decomp, use_cn, use_fates + use clm_varctl , only : use_century_decomp, single_column, scmlat, scmlon, use_cn, use_fates use clm_varctl , only : use_crop, ndep_from_cpl use clm_varorb , only : eccen, mvelpp, lambm0, obliqr use clm_time_manager , only : get_step_size_real, get_curr_calday @@ -426,6 +427,14 @@ subroutine initialize2( ) avgflag='A', long_name='convective boundary height', & ptr_col=col%zii, default='inactive') + ! If single-column determine closest latitude and longitude + + if (single_column) then + call getfil (fsurdat, locfn, 0) + call shr_scam_getCloseLatLon(locfn, scmlat, scmlon, & + closelat, closelon, closelatidx, closelonidx) + end if + ! Initialize instances of all derived types as well as time constant variables call clm_instInit(bounds_proc) diff --git a/src/main/histFileMod.F90 b/src/main/histFileMod.F90 index 9245051da8..f0438a8e31 100644 --- a/src/main/histFileMod.F90 +++ b/src/main/histFileMod.F90 @@ -13,7 +13,7 @@ module histFileMod use spmdMod , only : masterproc use abortutils , only : endrun use clm_varctl , only : iulog, use_vertsoilc, use_fates - use clm_varcon , only : spval, ispval, dzsoi_decomp + use clm_varcon , only : spval, ispval, dzsoi_decomp use clm_varcon , only : grlnd, nameg, namel, namec, namep, nameCohort use decompMod , only : get_proc_bounds, get_proc_global, bounds_type use GetGlobalValuesMod , only : GetGlobalIndexArray @@ -26,7 +26,7 @@ module histFileMod use FatesInterfaceMod , only : nlevsclass, nlevage use EDTypesMod , only : nfsc, ncwd use FatesInterfaceMod , only : maxveg_fates => numpft - use ncdio_pio + use ncdio_pio ! implicit none @@ -160,7 +160,7 @@ module histFileMod private :: hfields_write ! Write a variable to a history tape private :: hfields_1dinfo ! Define/output 1d subgrid info if appropriate private :: hist_update_hbuf_field_1d ! Updates history buffer for specific field and tape - private :: hist_update_hbuf_field_2d ! Updates history buffer for specific field and tape + private :: hist_update_hbuf_field_2d ! Updates history buffer for specific field and tape private :: hist_set_snow_field_2d ! Set values in history field dimensioned by levsno private :: list_index ! Find index of field in exclude list private :: set_hist_filename ! Determine history dataset filenames @@ -196,7 +196,7 @@ module histFileMod integer :: end1d_out ! on-node 1d hbuf pointer end index integer :: num1d_out ! size of hbuf first dimension (all nodes) integer :: num2d ! size of hbuf second dimension (e.g. number of vertical levels) - integer :: hpindex ! history pointer index + integer :: hpindex ! history pointer index character(len=scale_type_strlen) :: p2c_scale_type ! scale factor when averaging patch to column character(len=scale_type_strlen) :: c2l_scale_type ! scale factor when averaging column to landunit character(len=scale_type_strlen) :: l2g_scale_type ! scale factor when averaging landunit to gridcell @@ -352,7 +352,7 @@ subroutine masterlist_addfld (fname, type1d, type1d_out, & integer :: numl ! total number of landunits across all processors integer :: numc ! total number of columns across all processors integer :: nump ! total number of pfts across all processors - type(bounds_type) :: bounds + type(bounds_type) :: bounds character(len=*),parameter :: subname = 'masterlist_addfld' !------------------------------------------------------------------------ @@ -673,7 +673,7 @@ subroutine htapes_fieldlist() fexcl(:,8) = hist_fexcl8(:) fexcl(:,9) = hist_fexcl9(:) fexcl(:,10) = hist_fexcl10(:) - + ! First ensure contents of fincl and fexcl are valid names @@ -853,7 +853,7 @@ end subroutine htapes_fieldlist logical function is_mapping_upto_subgrid( type1d, type1d_out ) result ( mapping) ! ! !DESCRIPTION: - ! + ! ! Return true if this field will be mapped into a higher subgrid level ! If false it will be output on it's native grid ! @@ -909,7 +909,7 @@ subroutine htape_addfld (t, f, avgflag) integer :: beg1d_out,end1d_out ! history output per-proc 1d beginning and ending indices integer :: beg1d,end1d ! beginning and ending indices for this field (assume already set) integer :: num1d_out ! history output 1d size - type(bounds_type) :: bounds + type(bounds_type) :: bounds character(len=*),parameter :: subname = 'htape_addfld' !----------------------------------------------------------------------- @@ -1012,7 +1012,7 @@ subroutine htape_addfld (t, f, avgflag) ! Fields native bounds beg1d = masterlist(f)%field%beg1d end1d = masterlist(f)%field%end1d - + ! Alloccate and initialize history buffer and related info num2d = tape(t)%hlist(n)%field%num2d @@ -1050,7 +1050,7 @@ subroutine hist_update_hbuf(bounds) ! into its history buffer for appropriate tapes. ! ! !ARGUMENTS: - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds ! ! !LOCAL VARIABLES: integer :: t ! tape index @@ -1064,7 +1064,7 @@ subroutine hist_update_hbuf(bounds) !$OMP PARALLEL DO PRIVATE (f, num2d) do f = 1,tape(t)%nflds num2d = tape(t)%hlist(f)%field%num2d - if ( num2d == 1) then + if ( num2d == 1) then call hist_update_hbuf_field_1d (t, f, bounds) else call hist_update_hbuf_field_2d (t, f, bounds, num2d) @@ -1092,7 +1092,7 @@ subroutine hist_update_hbuf_field_1d (t, f, bounds) ! !ARGUMENTS: integer, intent(in) :: t ! tape index integer, intent(in) :: f ! field index - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds ! ! !LOCAL VARIABLES: integer :: hpindex ! history pointer index @@ -1306,7 +1306,7 @@ subroutine hist_update_hbuf_field_1d (t, f, bounds) if ( end1d .eq. ubound(field,1) ) then k_offset = 0 else - k_offset = 1 - beg1d + k_offset = 1 - beg1d endif do k = beg1d,end1d valid = .true. @@ -1386,7 +1386,7 @@ subroutine hist_update_hbuf_field_2d (t, f, bounds, num2d) ! !ARGUMENTS: integer, intent(in) :: t ! tape index integer, intent(in) :: f ! field index - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds integer, intent(in) :: num2d ! size of second dimension ! ! !LOCAL VARIABLES: @@ -1409,7 +1409,7 @@ subroutine hist_update_hbuf_field_2d (t, f, bounds, num2d) integer , pointer :: nacs(:,:) ! accumulation counter real(r8), pointer :: field(:,:) ! clm 2d pointer field logical :: field_allocated! whether 'field' was allocated here - logical , pointer :: active(:) ! flag saying whether each point is active (used for type1d = landunit/column/pft) + logical , pointer :: active(:) ! flag saying whether each point is active (used for type1d = landunit/column/pft) !(this refers to a point being active, NOT a history field being active) real(r8), allocatable :: field_gcell(:,:) ! gridcell level field (used if mapping to gridcell is done) character(len=*),parameter :: subname = 'hist_update_hbuf_field_2d' @@ -1709,7 +1709,7 @@ end subroutine hist_update_hbuf_field_2d subroutine hist_set_snow_field_2d (field_out, field_in, no_snow_behavior, type1d, beg1d, end1d) ! ! !DESCRIPTION: - ! Set values in history field dimensioned by levsno. + ! Set values in history field dimensioned by levsno. ! ! This routine handles what to do when a given snow layer doesn't exist for a given ! point, based on the no_snow_behavior argument. Options are: @@ -1779,7 +1779,7 @@ subroutine hist_set_snow_field_2d (field_out, field_in, no_snow_behavior, type1d num_snow_layers = abs(snl(c)) num_nonexistent_layers = num_levels - num_snow_layers - + ! Fill output field appropriately for each layer ! When only a subset of snow layers exist, it is the LAST num_snow_layers that exist ! Levels are rearranged such that the top snow layer (surface layer) becomes level 1, etc. @@ -1790,7 +1790,7 @@ subroutine hist_set_snow_field_2d (field_out, field_in, no_snow_behavior, type1d do level = (num_levels-num_nonexistent_layers), 1, -1 field_out(point, level) = field_in(point, level+num_nonexistent_layers) end do - + end do end associate @@ -1942,7 +1942,7 @@ subroutine htape_create (t, histrest) else lnfid => nfid(t) endif - + ! BUG(wjs, 2014-10-20, bugz 1730) Workaround for ! http://bugs.cgd.ucar.edu/show_bug.cgi?id=1730 ! - 1-d hist files have problems with pnetcdf. A better workaround in terms of @@ -2055,7 +2055,7 @@ subroutine htape_create (t, histrest) call ncd_defdim(lnfid, 'string_length', hist_dim_name_length, strlen_dimid) call ncd_defdim(lnfid, 'scale_type_string_length', scale_type_strlen, dimid) call ncd_defdim( lnfid, 'levdcmp', nlevdecomp_full, dimid) - + if(use_fates)then call ncd_defdim(lnfid, 'fates_levscag', nlevsclass * nlevage, dimid) call ncd_defdim(lnfid, 'fates_levscls', nlevsclass, dimid) @@ -2106,7 +2106,7 @@ subroutine htape_add_ltype_metadata(lnfid) character(len=*), parameter :: subname = 'htape_add_ltype_metadata' !----------------------------------------------------------------------- - + do ltype = 1, max_lunit attname = att_prefix // landunit_names(ltype) call ncd_putatt(lnfid, ncd_global, attname, ltype) @@ -2157,7 +2157,7 @@ subroutine htape_add_natpft_metadata(lnfid) character(len=*), parameter :: subname = 'htape_add_natpft_metadata' !----------------------------------------------------------------------- - + do ptype = natpft_lb, natpft_ub ptype_1_indexing = ptype + (1 - natpft_lb) attname = att_prefix // pftname(ptype) @@ -2187,7 +2187,7 @@ subroutine htape_add_cft_metadata(lnfid) character(len=*), parameter :: subname = 'htape_add_cft_metadata' !----------------------------------------------------------------------- - + do ptype = cft_lb, cft_ub ptype_1_indexing = ptype + (1 - cft_lb) attname = att_prefix // pftname(ptype) @@ -2215,11 +2215,11 @@ subroutine htape_timeconst3D(t, & ! ! !ARGUMENTS: integer , intent(in) :: t ! tape index - type(bounds_type) , intent(in) :: bounds - real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) - real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) + type(bounds_type) , intent(in) :: bounds + real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) + real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) character(len=*) , intent(in) :: mode ! 'define' or 'write' ! ! !LOCAL VARIABLES: @@ -2435,7 +2435,7 @@ subroutine htape_timeconst3D(t, & l = col%landunit(c) if (lun%lakpoi(l)) then ! Field indices MUST match varnamesl array order above! - if (ifld ==1) histil(c,lev) = col%z_lake(c,lev) + if (ifld ==1) histil(c,lev) = col%z_lake(c,lev) if (ifld ==2) histil(c,lev) = col%dz_lake(c,lev) end if end do @@ -2546,9 +2546,9 @@ subroutine htape_timeconst(t, mode) long_name='coordinate lake levels', units='m', ncid=nfid(t)) call ncd_defvar(varname='levdcmp', xtype=tape(t)%ncprec, dim1name='levdcmp', & long_name='coordinate soil levels', units='m', ncid=nfid(t)) - + if(use_fates)then - + call ncd_defvar(varname='fates_levscls', xtype=tape(t)%ncprec, dim1name='fates_levscls', & long_name='FATES diameter size class lower bound', units='cm', ncid=nfid(t)) call ncd_defvar(varname='fates_scmap_levscag', xtype=ncd_int, dim1name='fates_levscag', & @@ -2632,7 +2632,7 @@ subroutine htape_timeconst(t, mode) dim1id(1) = time_dimid str = 'days since ' // basedate // " " // basesec call ncd_defvar(nfid(t), 'time', tape(t)%ncprec, 1, dim1id, varid, & - long_name='time',units=str) + long_name='time',units=str) cal = get_calendar() if ( trim(cal) == NO_LEAP_C )then caldesc = "noleap" @@ -2653,7 +2653,7 @@ subroutine htape_timeconst(t, mode) else sec_hist_nhtfrq = hist_nhtfrq(t) end if - + dtime = get_step_size() if (sec_hist_nhtfrq == 0) then !month time_period_freq = 'month_1' @@ -3021,7 +3021,7 @@ subroutine hfields_1dinfo(t, mode) integer , pointer :: ilarr(:) ! temporary integer , pointer :: iparr(:) ! temporary type(file_desc_t), pointer :: ncid ! netcdf file - type(bounds_type) :: bounds + type(bounds_type) :: bounds character(len=*),parameter :: subname = 'hfields_1dinfo' !----------------------------------------------------------------------- @@ -3330,11 +3330,11 @@ subroutine hist_htapes_wrapup( rstwr, nlend, bounds, & ! !ARGUMENTS: logical, intent(in) :: rstwr ! true => write restart file this step logical, intent(in) :: nlend ! true => end of run on this step - type(bounds_type) , intent(in) :: bounds - real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) - real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) - real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) + type(bounds_type) , intent(in) :: bounds + real(r8) , intent(in) :: watsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: sucsat_col( bounds%begc:,1: ) + real(r8) , intent(in) :: bsw_col( bounds%begc:,1: ) + real(r8) , intent(in) :: hksat_col( bounds%begc:,1: ) ! ! !LOCAL VARIABLES: integer :: t ! tape index @@ -3518,8 +3518,8 @@ subroutine hist_htapes_wrapup( rstwr, nlend, bounds, & endif end do - ! Reset number of time samples to zero if file is full - + ! Reset number of time samples to zero if file is full + do t = 1, ntapes if (.not. history_tape_in_use(t)) then cycle @@ -3529,7 +3529,7 @@ subroutine hist_htapes_wrapup( rstwr, nlend, bounds, & tape(t)%ntimes = 0 end if end do - + end subroutine hist_htapes_wrapup !----------------------------------------------------------------------- @@ -3551,7 +3551,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) use pio ! ! !ARGUMENTS: - type(bounds_type), intent(in) :: bounds + type(bounds_type), intent(in) :: bounds type(file_desc_t), intent(inout) :: ncid ! netcdf file character(len=*) , intent(in) :: flag !'read' or 'write' character(len=*) , intent(in), optional :: rdate ! restart file time stamp for name @@ -3681,7 +3681,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) ier = PIO_put_att(ncid, vardesc%varid, 'interpinic_flag', iflag_skip) ! max_nflds is the maximum number of fields on any tape - ! max_flds is the maximum number possible number of fields + ! max_flds is the maximum number possible number of fields max_nflds = max_nFields() @@ -3714,7 +3714,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) num2d = tape(t)%hlist(f)%field%num2d nacs => tape(t)%hlist(f)%nacs hbuf => tape(t)%hlist(f)%hbuf - + if (type1d_out == grlnd) then if (ldomain%isgrid2d) then dim1name = 'lon' ; dim2name = 'lat' @@ -3724,10 +3724,10 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) else dim1name = type1d_out ; dim2name = 'undefined' endif - + if (dim2name == 'undefined') then if (num2d == 1) then - call ncd_defvar(ncid=ncid_hist(t), varname=trim(name), xtype=ncd_double, & + call ncd_defvar(ncid=ncid_hist(t), varname=trim(name), xtype=ncd_double, & dim1name=dim1name, & long_name=trim(long_name), units=trim(units)) call ncd_defvar(ncid=ncid_hist(t), varname=trim(name_acc), xtype=ncd_int, & @@ -3769,9 +3769,9 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_defdim( ncid_hist(t), 'avgflag_len' , avgflag_strlen, dimid) call ncd_defdim( ncid_hist(t), 'scalar' , 1 , dimid) call ncd_defdim( ncid_hist(t), 'max_chars' , max_chars , dimid) - call ncd_defdim( ncid_hist(t), 'max_nflds' , max_nflds , dimid) - call ncd_defdim( ncid_hist(t), 'max_flds' , max_flds , dimid) - + call ncd_defdim( ncid_hist(t), 'max_nflds' , max_nflds , dimid) + call ncd_defdim( ncid_hist(t), 'max_flds' , max_flds , dimid) + call ncd_defvar(ncid=ncid_hist(t), varname='nhtfrq', xtype=ncd_int, & long_name="Frequency of history writes", & comment="Namelist item", & @@ -3811,7 +3811,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_defvar(ncid=ncid_hist(t), varname='begtime', xtype=ncd_double, & long_name="Beginning time", units="time units", & dim1name='scalar') - + call ncd_defvar(ncid=ncid_hist(t), varname='num2d', xtype=ncd_int, & long_name="Size of second dimension", units="unitless", & dim1name='max_nflds' ) @@ -3853,7 +3853,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_enddef(ncid_hist(t)) - end do ! end of ntapes loop + end do ! end of ntapes loop RETURN @@ -3877,7 +3877,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_io('locfnh', my_locfnh, 'write', ncid, nt=t) call ncd_io('locfnhr', my_locfnhr, 'write', ncid, nt=t) end do - + fincl(:,1) = hist_fincl1(:) fincl(:,2) = hist_fincl2(:) fincl(:,3) = hist_fincl3(:) @@ -3926,7 +3926,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) itemp(:) = 0 do f=1,tape(t)%nflds itemp(f) = tape(t)%hlist(f)%field%num2d - end do + end do call ncd_io(varname='num2d', data=itemp(:), ncid=ncid_hist(t), flag='write') itemp(:) = 0 @@ -3969,7 +3969,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_io('l2g_scale_type', l2g_scale_type, 'write', ncid_hist(t)) deallocate(tname,tlongname,tunits,tmpstr,tavgflag) deallocate(p2c_scale_type, c2l_scale_type, l2g_scale_type) - enddo + enddo deallocate(itemp) ! @@ -4023,7 +4023,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) end if ! Determine necessary indices - the following is needed if model decomposition is different on restart - + start(1)=1 if ( is_restart() )then @@ -4038,7 +4038,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) if ( t == 1 )then call ncd_inqdlen(ncid_hist(1),dimid,max_nflds,name='max_nflds') - + allocate(itemp(max_nflds)) end if @@ -4221,7 +4221,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) hist_fexcl10(:) = fexcl(:,10) end if - + if ( allocated(itemp) ) deallocate(itemp) end if @@ -4232,8 +4232,8 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) ! so that subsequent time samples are added until the file is full. ! A new history file is used on a branch run. !====================================================================== - - if (flag == 'write') then + + if (flag == 'write') then do t = 1,ntapes if (.not. history_tape_in_use(t)) then @@ -4260,7 +4260,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) write(iulog,*) trim(subname),' ERROR: allocation' call endrun(msg=errMsg(sourcefile, __LINE__)) end if - + hbuf1d(beg1d_out:end1d_out) = hbuf(beg1d_out:end1d_out,1) nacs1d(beg1d_out:end1d_out) = nacs(beg1d_out:end1d_out,1) @@ -4284,9 +4284,9 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) call ncd_pio_closefile(ncid_hist(t)) - end do ! end of ntapes loop + end do ! end of ntapes loop - else if (flag == 'read') then + else if (flag == 'read') then ! Read history restart information if history files are not full @@ -4307,7 +4307,7 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) end1d_out = tape(t)%hlist(f)%field%end1d_out nacs => tape(t)%hlist(f)%nacs hbuf => tape(t)%hlist(f)%hbuf - + if (num2d == 1) then allocate(hbuf1d(beg1d_out:end1d_out), & nacs1d(beg1d_out:end1d_out), stat=status) @@ -4315,15 +4315,15 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) write(iulog,*) trim(subname),' ERROR: allocation' call endrun(msg=errMsg(sourcefile, __LINE__)) end if - + call ncd_io(ncid=ncid_hist(t), flag='read', varname=trim(name), & dim1name=type1d_out, data=hbuf1d) call ncd_io(ncid=ncid_hist(t), flag='read', varname=trim(name_acc), & dim1name=type1d_out, data=nacs1d) - + hbuf(beg1d_out:end1d_out,1) = hbuf1d(beg1d_out:end1d_out) nacs(beg1d_out:end1d_out,1) = nacs1d(beg1d_out:end1d_out) - + deallocate(hbuf1d) deallocate(nacs1d) else @@ -4335,13 +4335,13 @@ subroutine hist_restart_ncd (bounds, ncid, flag, rdate) end do end if - + call ncd_pio_closefile(ncid_hist(t)) - + end do - + end if - + end subroutine hist_restart_ncd !----------------------------------------------------------------------- @@ -4363,7 +4363,7 @@ integer function max_nFields() end do return end function max_nFields - + !----------------------------------------------------------------------- character(len=max_namlen) function getname (inname) ! @@ -4560,7 +4560,7 @@ subroutine hist_addfld1d (fname, units, avgflag, long_name, type1d_out, & character(len=scale_type_strlen) :: scale_type_p2c ! scale type for subgrid averaging of pfts to column character(len=scale_type_strlen) :: scale_type_c2l ! scale type for subgrid averaging of columns to landunits character(len=scale_type_strlen) :: scale_type_l2g ! scale type for subgrid averaging of landunits to gridcells - type(bounds_type):: bounds ! boudns + type(bounds_type):: bounds ! boudns character(len=16):: l_default ! local version of 'default' character(len=*),parameter :: subname = 'hist_addfld1d' !------------------------------------------------------------------------ @@ -4786,13 +4786,13 @@ subroutine hist_addfld2d (fname, type2d, units, avgflag, long_name, type1d_out, character(len=scale_type_strlen) :: scale_type_p2c ! scale type for subgrid averaging of pfts to column character(len=scale_type_strlen) :: scale_type_c2l ! scale type for subgrid averaging of columns to landunits character(len=scale_type_strlen) :: scale_type_l2g ! scale type for subgrid averaging of landunits to gridcells - type(bounds_type):: bounds + type(bounds_type):: bounds character(len=16):: l_default ! local version of 'default' character(len=*),parameter :: subname = 'hist_addfld2d' !------------------------------------------------------------------------ call get_proc_bounds(bounds) - + ! Error-check no_snow_behavior optional argument: It should be present if and only if ! type2d is 'levsno', and its value should be one of the public no_snow_* parameters ! defined above. @@ -4871,7 +4871,7 @@ subroutine hist_addfld2d (fname, type2d, units, avgflag, long_name, type1d_out, case ('levsno') num2d = nlevsno case ('nlevcan') - num2d = nlevcan + num2d = nlevcan case ('nvegwcs') num2d = nvegwcs case default @@ -5172,12 +5172,12 @@ end subroutine hist_add_subscript subroutine strip_null(str) character(len=*), intent(inout) :: str - integer :: i + integer :: i do i=1,len(str) if(ichar(str(i:i))==0) str(i:i)=' ' end do end subroutine strip_null - + !------------------------------------------------------------------------ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, rstwr, nlend) ! @@ -5197,7 +5197,7 @@ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, logical, intent(out) :: if_stop !true => last time step of run logical, intent(out) :: if_disphist(ntapes) !true => save and dispose history file logical, intent(in) :: rstwr - logical, intent(in) :: nlend + logical, intent(in) :: nlend ! ! !LOCAL VARIABLES: integer :: t ! history tape index @@ -5207,26 +5207,26 @@ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, rest_now = .false. stop_now = .false. - + if (nlend) stop_now = .true. if (rstwr) rest_now = .true. - + if_stop = stop_now - + if (stop_now) then ! End of run - dispose all history files - + if_disphist(1:ntapes) = .true. - + else if (rest_now) then ! Restart - dispose all history files - + do t = 1,ntapes if_disphist(t) = .true. end do else ! Dispose - + if_disphist(1:ntapes) = .false. do t = 1,ntapes if (hist_ntimes(t) == hist_mfilt(t)) then @@ -5234,7 +5234,7 @@ subroutine hist_do_disp (ntapes, hist_ntimes, hist_mfilt, if_stop, if_disphist, endif end do endif - + end subroutine hist_do_disp !----------------------------------------------------------------------- @@ -5274,3 +5274,4 @@ end function avgflag_valid end module histFileMod + From 07add4ed3be92398782c912834e00b190964add8 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Wed, 11 Mar 2020 10:28:29 -0600 Subject: [PATCH 210/255] added required version of CMEPS for these changes --- Externals_cime.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Externals_cime.cfg b/Externals_cime.cfg index cbede7df52..63c73adb96 100644 --- a/Externals_cime.cfg +++ b/Externals_cime.cfg @@ -1,5 +1,5 @@ [cmeps] -hash = 181ff1ed9dfb279e619e8a2173f43baf7bf1dce3 +hash = e0bfc6bdf2e1069e12301380fc1f624f0b33225dhash protocol = git repo_url = https://github.com/ESCOMP/CMEPS.git local_path = src/drivers/nuopc/ From b6a1d505aa88304a8ef010d85d76e3a7609642af Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Wed, 11 Mar 2020 11:15:23 -0600 Subject: [PATCH 211/255] Remove commented-out line and unused local variable --- src/main/ncdio_pio.F90.in | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/main/ncdio_pio.F90.in b/src/main/ncdio_pio.F90.in index 3ccc9f19a4..ff7320bc70 100644 --- a/src/main/ncdio_pio.F90.in +++ b/src/main/ncdio_pio.F90.in @@ -218,7 +218,7 @@ contains ! !ARGUMENTS: class(file_desc_t), intent(inout) :: file ! PIO file handle to close !----------------------------------------------------------------------- - integer :: ierr + call pio_closefile(file) end subroutine ncd_pio_closefile @@ -2531,7 +2531,6 @@ contains deallocate(gsmOP) -! call pio_initdecomp(pio_subsystem, baseTYPE, dims(1:ndims), compDOF, iodesc_list(iodnum)%iodesc) call pio_initdecomp(pio_subsystem, xTYPE, dims(1:ndims), compDOF, iodesc_list(iodnum)%iodesc) deallocate(compDOF) From 2392303538298ae1e54421efe094d2d14ac4ce81 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sat, 14 Mar 2020 15:53:18 -0600 Subject: [PATCH 212/255] Point to latest version of cime master --- Externals.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Externals.cfg b/Externals.cfg index b15f54e496..f20cf0c66b 100644 --- a/Externals.cfg +++ b/Externals.cfg @@ -30,7 +30,7 @@ required = True local_path = cime protocol = git repo_url = https://github.com/ESMCI/cime -tag = branch_tags/cime5.8.15_a01 +hash = 4f1880756a66ff12d304937d3c166d451ea50cf9 externals = ../Externals_cime.cfg required = True From 380a62087e83bf15f566282d65354ee4cf78b832 Mon Sep 17 00:00:00 2001 From: Mariana Vertenstein Date: Sun, 15 Mar 2020 17:33:44 -0600 Subject: [PATCH 213/255] bug fix for ndep fields from atm --- src/cpl/nuopc/lnd_import_export.F90 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/cpl/nuopc/lnd_import_export.F90 b/src/cpl/nuopc/lnd_import_export.F90 index 564348854e..0838b7a00a 100644 --- a/src/cpl/nuopc/lnd_import_export.F90 +++ b/src/cpl/nuopc/lnd_import_export.F90 @@ -562,9 +562,9 @@ subroutine import_fields( gcomp, bounds, glc_present, rof_prognostic, & ! The mediator is sending ndep in units if kgN/m2/s - and ctsm uses units of gN/m2/sec ! so the following conversion needs to happen - call state_getimport(importState, 'Faxa_nhx', bounds, output=forc_nhx, ungridded_index=1, rc=rc ) + call state_getimport(importState, 'Faxa_ndep', bounds, output=forc_nhx, ungridded_index=1, rc=rc ) if (ChkErr(rc,__LINE__,u_FILE_u)) return - call state_getimport(importState, 'Faxa_noy', bounds, output=forc_noy, ungridded_index=2, rc=rc ) + call state_getimport(importState, 'Faxa_ndep', bounds, output=forc_noy, ungridded_index=2, rc=rc ) if (ChkErr(rc,__LINE__,u_FILE_u)) return do g = begg,endg atm2lnd_inst%forc_ndep_grc(g) = (forc_nhx(g) + forc_noy(g))*1000._r8 @@ -1027,7 +1027,7 @@ subroutine fldlist_realize(state, fldList, numflds, flds_scalar_name, flds_scala ESMF_LOGMSG_INFO) ! Create the scalar field call SetScalarField(field, flds_scalar_name, flds_scalar_num, rc=rc) - if (ESMF_LogFoundError(rcToCheck=rc, msg=ESMF_LOGERR_PASSTHRU, line=__LINE__, file=u_FILE_u)) return + if (ChkErr(rc,__LINE__,u_FILE_u)) return else ! Create the field if (fldlist(n)%ungridded_lbound > 0 .and. fldlist(n)%ungridded_ubound > 0) then @@ -1038,7 +1038,7 @@ subroutine fldlist_realize(state, fldList, numflds, flds_scalar_name, flds_scala if (ChkErr(rc,__LINE__,u_FILE_u)) return else field = ESMF_FieldCreate(mesh, ESMF_TYPEKIND_R8, name=stdname, meshloc=ESMF_MESHLOC_ELEMENT, rc=rc) - if (ESMF_LogFoundError(rcToCheck=rc, msg=ESMF_LOGERR_PASSTHRU, line=__LINE__, file=u_FILE_u)) return + if (ChkErr(rc,__LINE__,u_FILE_u)) return end if call ESMF_LogWrite(trim(subname)//trim(tag)//" Field = "//trim(stdname)//" is connected using mesh", & ESMF_LOGMSG_INFO) @@ -1046,13 +1046,13 @@ subroutine fldlist_realize(state, fldList, numflds, flds_scalar_name, flds_scala ! NOW call NUOPC_Realize call NUOPC_Realize(state, field=field, rc=rc) - if (ESMF_LogFoundError(rcToCheck=rc, msg=ESMF_LOGERR_PASSTHRU, line=__LINE__, file=u_FILE_u)) return + if (ChkErr(rc,__LINE__,u_FILE_u)) return else if (stdname /= trim(flds_scalar_name)) then call ESMF_LogWrite(subname // trim(tag) // " Field = "// trim(stdname) // " is not connected.", & ESMF_LOGMSG_INFO) call ESMF_StateRemove(state, (/stdname/), rc=rc) - if (ESMF_LogFoundError(rcToCheck=rc, msg=ESMF_LOGERR_PASSTHRU, line=__LINE__, file=u_FILE_u)) return + if (ChkErr(rc,__LINE__,u_FILE_u)) return end if end if end do From 5893d31edf080cfdabb108f3c8e159990cf3be42 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 09:11:54 -0600 Subject: [PATCH 214/255] Add nuopc test to expected fails list https://github.com/ESCOMP/CTSM/pull/939 should fix this. --- cime_config/testdefs/ExpectedTestFails.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/cime_config/testdefs/ExpectedTestFails.xml b/cime_config/testdefs/ExpectedTestFails.xml index d12defc385..8272e9d30a 100644 --- a/cime_config/testdefs/ExpectedTestFails.xml +++ b/cime_config/testdefs/ExpectedTestFails.xml @@ -44,6 +44,13 @@ + + + PEND + #943 + + + From 3d08f6bdbb3a7d6d81d5c02885df5f3b5cf508b5 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 09:18:00 -0600 Subject: [PATCH 215/255] Point to cime tag The only difference from the previously pointed to hash is the update to the cime ChangeLog. --- Externals.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Externals.cfg b/Externals.cfg index f20cf0c66b..493f13ad2f 100644 --- a/Externals.cfg +++ b/Externals.cfg @@ -30,7 +30,7 @@ required = True local_path = cime protocol = git repo_url = https://github.com/ESMCI/cime -hash = 4f1880756a66ff12d304937d3c166d451ea50cf9 +tag = cime5.8.17 externals = ../Externals_cime.cfg required = True From 6391110b1eb151d7efed81a58c101150507a3a2b Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 09:24:53 -0600 Subject: [PATCH 216/255] Update ChangeLog --- doc/ChangeLog | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/ChangeSum | 1 + 2 files changed, 107 insertions(+) diff --git a/doc/ChangeLog b/doc/ChangeLog index cf7d461530..de3441808b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,110 @@ =============================================================== +Tag name: ctsm1.0.dev085 +Originator(s): sacks (Bill Sacks) +Date: Mon Mar 16 09:19:57 MDT 2020 +One-line Summary: Update cime + +Purpose of changes +------------------ + +Update to latest version of cime master + +Bugs fixed or introduced +------------------------ + +Known bugs introduced in this tag (include github issue ID): +- https://github.com/ESCOMP/CTSM/issues/943 - NUOPC tests will fail in ctsm1.0.dev085 + + +Significant changes to scientifically-supported configurations +-------------------------------------------------------------- + +Does this tag change answers significantly for any of the following physics configurations? +(Details of any changes will be given in the "Answer changes" section below.) + + [Put an [X] in the box for any configuration with significant answer changes.] + +[ ] clm5_0 + +[ ] ctsm5_0-nwp + +[ ] clm4_5 + +Notes of particular relevance for users +--------------------------------------- + +Caveats for users (e.g., need to interpolate initial conditions): +- NUOPC cases will fail from a standalone checkout + +Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables): none + +Changes made to namelist defaults (e.g., changed parameter values): none + +Changes to the datasets (e.g., parameter, surface or initial files): none + +Substantial timing or memory changes: none + +Notes of particular relevance for developers: (including Code reviews and testing) +--------------------------------------------- +NOTE: Be sure to review the steps in README.CHECKLIST.master_tags as well as the coding style in the Developers Guide + +Caveats for developers (e.g., code that is duplicated that requires double maintenance): none + +Changes to tests or testing: none + +Code reviewed by: self + + +CTSM testing: + + [PASS means all tests PASS and OK means tests PASS other than expected fails.] + + build-namelist tests: + + cheyenne - not run + + tools-tests (test/tools): + + cheyenne - not run + + PTCLM testing (tools/shared/PTCLM/test): + + cheyenne - not run + + python testing (see instructions in python/README.md; document testing done): + + (any machine) - not run + + regular tests (aux_clm): + + cheyenne ---- ok + izumi ------- pass + +Two test failures: + + PEND SMS_D_Vnuopc.f10_f10_musgs.I2000Clm50SpRsGs.cheyenne_intel.clm-default SHAREDLIB_BUILD + I have added this to the expected fails list for now + FAIL SMS_P720x1_Ln6.hcru_hcru.I2000Clm50BgcCruGs.cheyenne_intel.clm-coldStart BASELINE ctsm1.0.dev084: ERROR BFAIL baseline directory '/glade/p/cgd/tss/ctsm_baselines/ctsm1.0.dev084/SMS_P720x1_Ln6.hcru_hcru.I2000Clm50BgcCruGs.cheyenne_intel.clm-coldStart' does not exist + This test was added in the previous tag, but apparently wasn't run from there + +If the tag used for baseline comparisons was NOT the previous tag, note that here: + + +Answer changes +-------------- + +Changes answers relative to baseline: NO + +Detailed list of changes +------------------------ + +List any externals directories updated (cime, rtm, mosart, cism, fates, etc.): +cime: branch_tags/cime5.8.15_a01 -> cime5.8.17 + +Pull Requests that document the changes (include PR ids): none + +=============================================================== +=============================================================== Tag name: ctsm1.0.dev084 Originator(s): negins (Negin Sobhani,UCAR/CSEG,303-497-1224) Date: Wed Feb 19 15:05:03 MST 2020 diff --git a/doc/ChangeSum b/doc/ChangeSum index c59c6a2359..0dcf0c484c 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,6 @@ Tag Who Date Summary ============================================================================================================================ + ctsm1.0.dev085 sacks 03/16/2020 Update cime ctsm1.0.dev084 negins 02/19/2020 Bounds assertion for C isotopes when threading is on ctsm1.0.dev083 negins 02/06/2020 Some BFB Fixes: Resolve issues #683, # 874, #878, # 885, # 745, #838 ctsm1.0.dev082 oleson 02/01/2020 Rename variables to avoid confusion; fix QSNOEVAP diagnostic From 7bcd30df8361990f520b97e57a6e6872ab5114b6 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 09:26:03 -0600 Subject: [PATCH 217/255] Add a note to ChangeLog --- doc/ChangeLog | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index de3441808b..61b4c6ef2d 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -80,13 +80,17 @@ CTSM testing: cheyenne ---- ok izumi ------- pass -Two test failures: + Two test failures: PEND SMS_D_Vnuopc.f10_f10_musgs.I2000Clm50SpRsGs.cheyenne_intel.clm-default SHAREDLIB_BUILD I have added this to the expected fails list for now FAIL SMS_P720x1_Ln6.hcru_hcru.I2000Clm50BgcCruGs.cheyenne_intel.clm-coldStart BASELINE ctsm1.0.dev084: ERROR BFAIL baseline directory '/glade/p/cgd/tss/ctsm_baselines/ctsm1.0.dev084/SMS_P720x1_Ln6.hcru_hcru.I2000Clm50BgcCruGs.cheyenne_intel.clm-coldStart' does not exist This test was added in the previous tag, but apparently wasn't run from there + Note: I did testing using cime hash + 4f1880756a66ff12d304937d3c166d451ea50cf9, then updated to the tag + (cime5.8.17). The two are identical except for the cime ChangeLog. + If the tag used for baseline comparisons was NOT the previous tag, note that here: From 757bb684857188e3b9779d92e5c58520f3b116fb Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 10:19:09 -0600 Subject: [PATCH 218/255] Update cmeps version @mvertens says this is needed along with the recent bug fix --- Externals_cime.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Externals_cime.cfg b/Externals_cime.cfg index 63c73adb96..4751386a44 100644 --- a/Externals_cime.cfg +++ b/Externals_cime.cfg @@ -1,5 +1,5 @@ [cmeps] -hash = e0bfc6bdf2e1069e12301380fc1f624f0b33225dhash +hash = 253f612acae07b2b1dc73c84f1bb30b8e1b86ddd protocol = git repo_url = https://github.com/ESCOMP/CMEPS.git local_path = src/drivers/nuopc/ From 302a2c3e5f394e87b88072e3f79cebe56d46591b Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 10:36:48 -0600 Subject: [PATCH 219/255] Remove nuopc test from ExpectedFails list We expect this to work now. Moreover, I am going to replace that test with a different test. --- cime_config/testdefs/ExpectedTestFails.xml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/cime_config/testdefs/ExpectedTestFails.xml b/cime_config/testdefs/ExpectedTestFails.xml index 8272e9d30a..d12defc385 100644 --- a/cime_config/testdefs/ExpectedTestFails.xml +++ b/cime_config/testdefs/ExpectedTestFails.xml @@ -44,13 +44,6 @@ - - - PEND - #943 - - - From 9ce8fcb3230102eaba769489e95386ee3499d123 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 10:56:08 -0600 Subject: [PATCH 220/255] Remove compsets added on this branch For these reasons (in addition to the duplication of the two blocks): 1. It looks like you don't actually reference them in any tests 2. The IHistClm50SpRsGs alias incorrectly produces a BGC compset 3. If you truly want a RsGs compset, there are others now available --- cime_config/config_compsets.xml | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index 7ca17cf1cf..50b82db54c 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -53,26 +53,6 @@ 2000_DATM%GSWP3v1_CLM50%SP_SICE_SOCN_MOSART_CISM2%NOEVOLVE_SWAV - - - IHistClm50BgcRsGs - HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV - - - IHistClm50SpRsGs - HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV - - - - - IHistClm50BgcRsGs - HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV - - - IHistClm50SpRsGs - HIST_DATM%GSWP3v1_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV - - I2000Clm50SpRsGs From a6bc8f8dfb86ec66faecf32238266bdd079da8d5 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 10:59:39 -0600 Subject: [PATCH 221/255] Change I1Pt compsets to have Rs in their name Since they were changed to use SROF, they should explicitly have this in their names Also fix a typo in testlist_clm_nuopc.xml --- cime_config/config_compsets.xml | 4 ++-- cime_config/testdefs/testlist_clm.xml | 22 ++++++++++----------- cime_config/testdefs/testlist_clm_nuopc.xml | 2 -- 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index 50b82db54c..bf0cb94221 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -37,12 +37,12 @@ - I1PtClm50SpGs + I1PtClm50SpRsGs 2000_DATM%1PT_CLM50%SP_SICE_SOCN_SROF_SGLC_SWAV - I1PtClm45SpGs + I1PtClm45SpRsGs 2000_DATM%1PT_CLM45%SP_SICE_SOCN_SROF_SGLC_SWAV diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index 84e0145caf..2325e11bcc 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -842,7 +842,7 @@ - + @@ -876,7 +876,7 @@ - + @@ -884,7 +884,7 @@ - + @@ -892,7 +892,7 @@ - + @@ -1125,7 +1125,7 @@ - + @@ -1133,7 +1133,7 @@ - + @@ -1141,7 +1141,7 @@ - + @@ -1234,7 +1234,7 @@ - + @@ -1243,7 +1243,7 @@ - + @@ -1305,7 +1305,7 @@ - + @@ -1886,7 +1886,7 @@ - + diff --git a/cime_config/testdefs/testlist_clm_nuopc.xml b/cime_config/testdefs/testlist_clm_nuopc.xml index 0578ecd5f4..09b1e377c2 100644 --- a/cime_config/testdefs/testlist_clm_nuopc.xml +++ b/cime_config/testdefs/testlist_clm_nuopc.xml @@ -1,5 +1,3 @@ -PET_P36x1_D_Vnuopc.f10_f10_musgs.I1850Clm50BgcCrop.cheyenne_intel.clm-default - From 24b13b4e0569f6cc7892219b0906c16c48bec73c Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 11:10:48 -0600 Subject: [PATCH 222/255] Remove I2000Clm50BgcCruRsGs compset that was added on this branch This was just being used in one test in testlist_clm_nuopc, but this test (which used the camdenNJ grid) is one we wanted to drop anyway: see https://github.com/ESCOMP/CTSM/issues/808 --- cime_config/config_compsets.xml | 5 ----- cime_config/testdefs/testlist_clm_nuopc.xml | 8 -------- 2 files changed, 13 deletions(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index bf0cb94221..070afa5422 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -160,11 +160,6 @@ 2000_DATM%QIA_CLM45%BGC-CROP_SICE_SOCN_SROF_SGLC_SWAV - - I2000Clm50BgcCruRsGs - 2000_DATM%CRUv7_CLM50%BGC_SICE_SOCN_SROF_SGLC_SWAV - - I2000Clm50BgcCruGs 2000_DATM%CRUv7_CLM50%BGC_SICE_SOCN_MOSART_SGLC_SWAV diff --git a/cime_config/testdefs/testlist_clm_nuopc.xml b/cime_config/testdefs/testlist_clm_nuopc.xml index 09b1e377c2..fe8f121f4a 100644 --- a/cime_config/testdefs/testlist_clm_nuopc.xml +++ b/cime_config/testdefs/testlist_clm_nuopc.xml @@ -8,14 +8,6 @@ - - - - - - - - From d24c6f6222f089b47882c65deaff4612932a00d5 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 11:13:53 -0600 Subject: [PATCH 223/255] Fix typo in comment --- cime_config/config_compsets.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index 070afa5422..646cb9f7e5 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -331,7 +331,7 @@ 2000_DATM%GSWP3v1_CLM45%FATES_SICE_SOCN_RTM_CISM2%NOEVOLVE_SWAV - + I2000Clm45FatesRsGs 2000_DATM%GSWP3v1_CLM45%FATES_SICE_SOCN_SROF_SGLC_SWAV From b2e4b1bdc8aefbfcbab6bedf717611c4bd3f80de Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 11:59:52 -0600 Subject: [PATCH 224/255] Change nuopc test to use mosart rather than srof This will work once we point to the new version of mosart that includes a nuopc cap. --- cime_config/testdefs/testlist_clm.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index 2325e11bcc..201a9dd5f8 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -1896,7 +1896,7 @@ - + From 05e4636cbd19b6aeb556054d5c9e84aca8640442 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 12:22:34 -0600 Subject: [PATCH 225/255] Add a compset for RTM testing I'm planning to use this compset in the RTM test suite for the nuopc test of RTM. I want a BGC-CROP test in order to exercise any irrigation-related fluxes. --- cime_config/config_compsets.xml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cime_config/config_compsets.xml b/cime_config/config_compsets.xml index 646cb9f7e5..19528a4e9f 100644 --- a/cime_config/config_compsets.xml +++ b/cime_config/config_compsets.xml @@ -76,6 +76,12 @@ 2000_DATM%GSWP3v1_CLM50%BGC-CROP_SICE_SOCN_RTM_CISM2%NOEVOLVE_SWAV + + + I2000Clm50BgcCropRtmGs + 2000_DATM%GSWP3v1_CLM50%BGC-CROP_SICE_SOCN_RTM_SGLC_SWAV + + I2000Clm50BgcCrop 2000_DATM%GSWP3v1_CLM50%BGC-CROP_SICE_SOCN_MOSART_CISM2%NOEVOLVE_SWAV From 3f496b26a4625d419f9b89615091a81afa776ccf Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Mon, 16 Mar 2020 14:17:14 -0600 Subject: [PATCH 226/255] Point to updated mosart and rtm For rtm, this includes the NUOPC cap. For mosart, this has fixes to the NUOPC cap. --- Externals.cfg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Externals.cfg b/Externals.cfg index 493f13ad2f..8f7908623b 100644 --- a/Externals.cfg +++ b/Externals.cfg @@ -16,14 +16,14 @@ required = True local_path = components/rtm protocol = git repo_url = https://github.com/ESCOMP/rtm -tag = rtm1_0_70 +tag = rtm1_0_71 required = True [mosart] local_path = components/mosart protocol = git repo_url = https://github.com/ESCOMP/mosart -tag = mosart1_0_35 +tag = mosart1_0_36 required = True [cime] From 61f2b05b69891bbba00aa57a2d046786e3c75067 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 19 Mar 2020 15:22:28 -0600 Subject: [PATCH 227/255] Update initial conditions file used in LII test Without this change, LII_D_Ld3.f19_g17_gl4.I2000Clm50BgcCrop.cheyenne_intel.clm-glcMEC_spunup_1way failed because it's pointing to an old initial conditions file that has a certain variable as a double when it is expected to be an int. I guess this worked with the old ncdio_pio code but breaks with the ncdio_pio changes on this branch. I have updated the initial conditions file using the finidat_inter_dest.nc file from this test, as described in the README file. --- .../testdefs/testmods_dirs/clm/glcMEC_spunup_1way/user_nl_clm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cime_config/testdefs/testmods_dirs/clm/glcMEC_spunup_1way/user_nl_clm b/cime_config/testdefs/testmods_dirs/clm/glcMEC_spunup_1way/user_nl_clm index c269a24911..c58bc66d21 100644 --- a/cime_config/testdefs/testmods_dirs/clm/glcMEC_spunup_1way/user_nl_clm +++ b/cime_config/testdefs/testmods_dirs/clm/glcMEC_spunup_1way/user_nl_clm @@ -2,4 +2,4 @@ ! ! Initial condition file at the desired configuration to run, so can verify that interpolating from it gives the same result ! Note that this was generated with GLC_TWO_WAY_COUPLING=FALSE -finidat = '$DIN_LOC_ROOT/lnd/clm2/initdata_map/clmi.I2000Clm50BgcCrop.2000-01-01.1.9x2.5_gx1v7_gl4_simyr2000_c180306.nc' +finidat = '$DIN_LOC_ROOT/lnd/clm2/initdata_map/clmi.I2000Clm50BgcCrop.2000-01-01.1.9x2.5_gx1v7_gl4_simyr2000_c200319.nc' From 4d7c7b7c3e2f694860a1858a0750c57c708a81be Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 19 Mar 2020 16:14:16 -0600 Subject: [PATCH 228/255] Update ChangeLog --- doc/ChangeLog | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/ChangeSum | 1 + 2 files changed, 152 insertions(+) diff --git a/doc/ChangeLog b/doc/ChangeLog index 61b4c6ef2d..c497d7b5e7 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,155 @@ =============================================================== +Tag name: ctsm1.0.dev086 +Originator(s): mvertens (Mariana Vertenstein) +Date: Thu Mar 19 16:03:26 MDT 2020 +One-line Summary: Updates to NUOPC cap and minor fixes to ncdio_pio + +Purpose of changes +------------------ + +This tag has updates to the NUOPC cap that are needed for the latest +version of CMEPS. + +Now each component NUOPC cap needs to compute possibly time varying +orbital parameters. Before, in cpl7, this was done in the driver and +passed to the components via seq_infodata. However, now the driver is +really just a simple ascii file - so those calculations needed to +migrate to the component caps. + +In addition, this tag contains changes to ncdio_pio.F90 that improve +performance in some situations. + +This also updates MOSART and RTM tags to include fixes for the NUOPC cap +for MOSART and implementation of an initial NUOPC cap for RTM. + +Also, I1Pt compsets now use SROF rather than using an active runoff +model in 'null' mode. This leads to differences in namelists, but not in +results. + +Mariana Vertenstein implemented most of the changes in this tag; Jim +Edwards implemented the ncdio_pio changes; Bill Sacks did final testing +and integration. + +Bugs fixed or introduced +------------------------ + +Issues fixed (include CTSM Issue #): +- Resolves ESCOMP/ctsm#943 (NUOPC tests will fail in ctsm1.0.dev085) + +Significant changes to scientifically-supported configurations +-------------------------------------------------------------- + +Does this tag change answers significantly for any of the following physics configurations? +(Details of any changes will be given in the "Answer changes" section below.) + + [Put an [X] in the box for any configuration with significant answer changes.] + +[ ] clm5_0 + +[ ] ctsm5_0-nwp + +[ ] clm4_5 + +Notes of particular relevance for users +--------------------------------------- + +Caveats for users (e.g., need to interpolate initial conditions): none + +Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables): none + +Changes made to namelist defaults (e.g., changed parameter values): none + +Changes to the datasets (e.g., parameter, surface or initial files): none + +Substantial timing or memory changes: none + +Notes of particular relevance for developers: (including Code reviews and testing) +--------------------------------------------- +NOTE: Be sure to review the steps in README.CHECKLIST.master_tags as well as the coding style in the Developers Guide + +Caveats for developers (e.g., code that is duplicated that requires double maintenance): none + +Changes to tests or testing: +- I1Pt tests and cases now use SROF rather than an active runoff model + with a null grid (only impacts namelists, not results) +- Changed nuopc test to use MOSART rather than SROF +- Changed finidat file used by LII test to solve a problem that was + uncovered with the ncdio_pio changes in this tag + +Code reviewed by: Bill Sacks + + +CTSM testing: + + [PASS means all tests PASS and OK means tests PASS other than expected fails.] + + build-namelist tests: + + cheyenne - not run + + tools-tests (test/tools): + + cheyenne - not run + + PTCLM testing (tools/shared/PTCLM/test): + + cheyenne - not run + + python testing (see instructions in python/README.md; document testing done): + + (any machine) - not run + + regular tests (aux_clm): + + cheyenne ---- pass + izumi ------- pass + +If the tag used for baseline comparisons was NOT the previous tag, note that here: + + +Answer changes +-------------- + +Changes answers relative to baseline: YES (just for NUOPC configurations) + + If a tag changes answers relative to baseline comparison the + following should be filled in (otherwise remove this section): + + Summarize any changes to answers, i.e., + - what code configurations: Just some NUOPC configurations + - what platforms/compilers: + - nature of change (roundoff; larger than roundoff/same climate; new climate): + Not investigated carefully, but likely to be larger than roundoff + / same climate (due to introduction of time-varying orbital parameters) + + Differences are expected in NUOPC configurations using time-varying + orbital parameters. Note that no differences showed up in the test + suite, however, because the only nuopc test in the test suite is + new in this tag (so did not have baselines). + + If bitwise differences were observed, how did you show they were no worse + than roundoff? N/A + + If this tag changes climate describe the run(s) done to evaluate the new + climate (put details of the simulations in the experiment database) + - casename: N/A + + URL for LMWG diagnostics output used to validate new climate: N/A + + +Detailed list of changes +------------------------ + +List any externals directories updated (cime, rtm, mosart, cism, fates, etc.): +- mosart: mosart1_0_35 -> mosart1_0_36 +- rtm: rtm1_0_70 -> rtm1_0_71 +- cmeps + +Pull Requests that document the changes (include PR ids): +https://github.com/ESCOMP/CTSM/issues/943 + +=============================================================== +=============================================================== Tag name: ctsm1.0.dev085 Originator(s): sacks (Bill Sacks) Date: Mon Mar 16 09:19:57 MDT 2020 diff --git a/doc/ChangeSum b/doc/ChangeSum index 0dcf0c484c..e8eef4d85e 100644 --- a/doc/ChangeSum +++ b/doc/ChangeSum @@ -1,5 +1,6 @@ Tag Who Date Summary ============================================================================================================================ + ctsm1.0.dev086 mvertens 03/19/2020 Updates to NUOPC cap and minor fixes to ncdio_pio ctsm1.0.dev085 sacks 03/16/2020 Update cime ctsm1.0.dev084 negins 02/19/2020 Bounds assertion for C isotopes when threading is on ctsm1.0.dev083 negins 02/06/2020 Some BFB Fixes: Resolve issues #683, # 874, #878, # 885, # 745, #838 From 41b4e065e72b07e7e1cf6b087b889742baa8c471 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sun, 22 Mar 2020 14:40:24 -0600 Subject: [PATCH 229/255] Add external for documentation images --- .gitignore | 1 + Externals_CLM.cfg | 7 +++++++ 2 files changed, 8 insertions(+) diff --git a/.gitignore b/.gitignore index 4a5672d970..c4e9ffb366 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ manage_externals.log /tools/PTCLM/ /cime/ /components/ +/doc/source/images/ # ignore svn directories **/.svn/** diff --git a/Externals_CLM.cfg b/Externals_CLM.cfg index 84b7d5ec33..1ca392b31f 100644 --- a/Externals_CLM.cfg +++ b/Externals_CLM.cfg @@ -12,6 +12,13 @@ repo_url = https://github.com/ESCOMP/ptclm tag = PTCLM2_180611 required = True +[doc-images] +local_path = doc/source/images +protocol = git +repo_url = https://github.com/ESCOMP/CTSM-doc-images.git +hash = 0f039e7a043fabfce91ddf4f41186a3014603aac +required = False + [externals_description] schema_version = 1.0.0 From c80bf40a75c36afc06f400b825c33add37ce6f7a Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sun, 22 Mar 2020 15:35:34 -0600 Subject: [PATCH 230/255] Move documentation images up a level Having this under doc rather than doc/source seems to make more sense. In addition, I think this will prevent the documentation build from looking in here for files to build (otherwise, I think I would need to add this directory to the exclude list in conf.py). --- .gitignore | 2 +- Externals_CLM.cfg | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index c4e9ffb366..2c7a551197 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,7 @@ manage_externals.log /tools/PTCLM/ /cime/ /components/ -/doc/source/images/ +/doc/images/ # ignore svn directories **/.svn/** diff --git a/Externals_CLM.cfg b/Externals_CLM.cfg index 1ca392b31f..f01e14ebb2 100644 --- a/Externals_CLM.cfg +++ b/Externals_CLM.cfg @@ -13,7 +13,7 @@ tag = PTCLM2_180611 required = True [doc-images] -local_path = doc/source/images +local_path = doc/images protocol = git repo_url = https://github.com/ESCOMP/CTSM-doc-images.git hash = 0f039e7a043fabfce91ddf4f41186a3014603aac From fc67ffa5998488430eed83629c2f0e2cdc34819f Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sun, 22 Mar 2020 16:58:57 -0600 Subject: [PATCH 231/255] Update paths etc. to allow documentation build from here I tested the build with: make BUILDDIR=../../../ctsm-docs/doc/build clean make BUILDDIR=../../../ctsm-docs/doc/build html A few warnings were generated in the build, but I'm pretty sure I got exactly those same warnings when building from the gh-pages branch. I compared against a previous documentation build I had done from the gh-pages branch - i.e., before moving the documentation source into this repository. The differences seemed minor / trivial: - Differences in a bunch of generated math svg files - at a glance, from spot-checking a few, it looks like some lines got moved around - Differences in `html/_sources`, as expected (changes reflecting the changes I made in paths) (I didn't look super closely, but this looked like all it was, from a quick glance) - Differences in `html/searchindex.js` (not surprising) - Some minor changes in some `users_guide` files, that (at a glance) look to all originate from the fact that it was pulling in README files from the current branch (based on master) rather than the release branch (which is what I used when building from the gh-pages branch). So it seems like I have faithfully reproduced the documentation build from before. --- doc/source/conf.py | 5 +---- .../tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 2 +- .../Decomposition/CLM50_Tech_Note_Decomposition.rst | 4 ++-- .../Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 2 +- .../CLM50_Tech_Note_External_Nitrogen_Cycle.rst | 2 +- .../tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst | 4 ++-- .../Hydrology/CLM50_Tech_Note_Hydrology.rst | 4 ++-- .../Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- .../tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 2 +- .../tech_note/Methane/CLM50_Tech_Note_Methane.rst | 2 +- .../CLM50_Tech_Note_Plant_Hydraulics.rst | 4 ++-- .../CLM50_Tech_Note_Radiative_Fluxes.rst | 2 +- .../CLM50_Tech_Note_Snow_Hydrology.rst | 2 +- .../CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 2 +- .../CLM50_Tech_Note_Transient_Landcover.rst | 6 +++--- .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 6 +++--- ...LM50_Tech_Note_Vegetation_Phenology_Turnover.rst | 2 +- doc/source/tech_note/conf.py | 4 +--- doc/source/users_guide/conf.py | 13 +------------ doc/source/users_guide/overview/introduction.rst | 2 +- doc/source/users_guide/overview/quickstart.rst | 2 +- .../users_guide/overview/scientific_validation.rst | 2 +- .../running-PTCLM/introduction-to-ptclm.rst | 2 +- ...p-the-Satellite-Phenology-Model-CLMSP-spinup.rst | 4 ++-- .../Spinning-up-the-biogeochemistry-BGC-spinup.rst | 8 ++++---- doc/source/users_guide/testing/testing.rst | 8 ++++---- .../using-clm-tools/building-the-clm-tools.rst | 2 +- .../using-clm-tools/creating-domain-files.rst | 4 ++-- ...reating-input-for-surface-dataset-generation.rst | 2 +- .../using-clm-tools/creating-surface-datasets.rst | 6 +++--- 30 files changed, 48 insertions(+), 64 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index a561207501..30259e17b3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -73,10 +73,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [ - "clm5.0", - "**/README_EXTERNALS.rst" -] +exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index 9bddee21ca..63024c7e0e 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -35,7 +35,7 @@ variables for vegetation carbon, and 22 for vegetation nitrogen. .. _Figure Vegetation fluxes and pools: -.. figure:: CLMCN_pool_structure_v2_lores.png +.. figure:: ../../../images/tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png :width: 753px :height: 513px diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index 0d2ad98687..baeb744dcb 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -20,7 +20,7 @@ calculations (see Section :numref:`Soil Layers` for soil layering). .. _Figure Schematic of decomposition model in CLM: -.. figure:: CLM4_vertsoil_soilstruct_drawing.png +.. figure:: ../../../images/tech_note/Decomposition/CLM4_vertsoil_soilstruct_drawing.png Schematic of decomposition model in CLM. @@ -65,7 +65,7 @@ structures is in :ref:`Koven et al. (2013) `. .. _Figure Pool structure: -.. figure:: soil_C_pools_CN_century.png +.. figure:: ../../../images/tech_note/Decomposition/soil_C_pools_CN_century.png Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index d90c8cab40..2fbbaeff9a 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -53,7 +53,7 @@ classes. .. _Figure CLM subgrid hierarchy: -.. Figure:: image1.png +.. Figure:: ../../../images/tech_note/Ecosystem/image1.png Configuration of the CLM subgrid hierarchy. Box in upper right shows hypothetical subgrid distribution for a single grid cell. Note that the Crop land unit is only used when the model is run with the crop model active. Abbreviations: TBD – Tall Building District; HD – High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – Crop, V – Vegetated, PFT – Plant Functional Type, Irr – Irrigated, UIrr – Unirrigated. Red arrows indicate allowed land unit transitions. Purple arrows indicate allowed patch-level transitions. diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst index ca7a4a9d2c..8d1016380d 100644 --- a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst @@ -118,7 +118,7 @@ Where :math:`{NF}_{nfix,sminn}` (gN m\ :sup:`-2` s\ :sup:`-1`) is the rate of fr .. _Figure Biological nitrogen fixation: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/External_Nitrogen_Cycle/image1.png Free-living nitrogen fixation as a function of annual evapotranspiration. Results here show annual N inputs from free-living N fixations, but the model actually calculates inputs on a per second basis. diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index d967cd5ff0..a0b7e04ac3 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -961,14 +961,14 @@ height :math:`z_{0h} ^{{'} }` and the canopy air at height .. _Figure Schematic diagram of sensible heat fluxes: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Fluxes/image1.png Figure Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. .. _Figure Schematic diagram of latent heat fluxes: -.. figure:: image2.png +.. figure:: ../../../images/tech_note/Fluxes/image2.png Figure Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index c4e0824ea7..6e0b593d29 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -38,7 +38,7 @@ al. 2008) ` and :math:`\Delta t` is the time step (s). .. _Figure Hydrologic processes: -.. Figure:: hydrologic.processes.png +.. Figure:: ../../../images/tech_note/Hydrology/hydrologic.processes.png Hydrologic processes represented in CLM. @@ -798,7 +798,7 @@ the effective root fraction :math:`r_{e,\, i}` .. _Figure Water flux schematic: -.. Figure:: image2.png +.. Figure:: ../../../images/tech_note/Hydrology/image2.png Schematic diagram of numerical scheme used to solve for soil water fluxes. diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index 7240dfa8d9..df3201827e 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -627,6 +627,6 @@ processes simulated include (:numref:`Figure Land processes`): .. _Figure Land processes: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Introduction/image1.png Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM5.0). diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index 439de8a7a1..dbd07703ee 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -47,7 +47,7 @@ and discharges the water to its downstream spatial unit or the ocean. .. _Figure MOSART conceptual diagram: -.. figure:: mosart_diagram.png +.. figure:: ../../../images/tech_note/MOSART/mosart_diagram.png :width: 800px :height: 400px diff --git a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index 7c89f857e3..8c92a24556 100644 --- a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -89,7 +89,7 @@ into the inundated concentration when the inundated fraction increases. .. _Figure Methane Schematic: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Methane/image1.png Schematic representation of biological and physical processes integrated in CLM that affect the net CH\ :sub:`4` diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index b2afa06646..e1ecb07118 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -159,7 +159,7 @@ on leaf water potential. .. _Figure Plant hydraulic circuit: -.. figure:: circuit.jpg +.. figure:: ../../../images/tech_note/Plant_Hydraulics/circuit.jpg Circuit diagram of plant hydraulics scheme @@ -714,6 +714,6 @@ The outermost level of iteration works towards convergence of leaf temperature, .. _Figure PHS Flow Diagram: -.. figure:: flow.png +.. figure:: ../../../images/tech_note/Plant_Hydraulics/flow.png Flow diagram of leaf flux calculations diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index 5e368456ba..a687d5bc2d 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -37,7 +37,7 @@ depth of direct beam per unit leaf and stem area (section :numref:`Canopy Radiat .. _Figure Radiation Schematic: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Radiative_Fluxes/image1.png Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index 8d22a19bc9..2d58d36795 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -18,7 +18,7 @@ snow pack. .. _Figure three layer snow pack: -.. Figure:: image1.png +.. Figure:: ../../../images/tech_note/Snow_Hydrology/image1.png Example of three layer snow pack (:math:`snl=-3`). diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index 56b6adff3f..efbb382f45 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -223,7 +223,7 @@ interface of two layers .. _Figure Soil Temperature Schematic: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Soil_Snow_Temperatures/image1.png Schematic diagram of numerical scheme used to solve for soil temperature. diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index de7ef86173..637dd28d05 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -347,18 +347,18 @@ data files in the mksurfdata_map tool. .. _Figure Schematic of land cover change: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Transient_Landcover/image1.png Schematic of land cover change impacts on CLM carbon pools and fluxes. .. _Figure Schematic of translation of annual LUH2 land units: -.. figure:: image2.png +.. figure:: ../../../images/tech_note/Transient_Landcover/image2.png Schematic of translation of annual LUH2 land units to CLM5 plant and crop functional types. .. _Figure Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool: -.. figure:: image3.png +.. figure:: ../../../images/tech_note/Transient_Landcover/image3.png Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index e9d9261b0d..c63e8a37b1 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -128,7 +128,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic representation of the urban landunit: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Urban/image1.png Schematic representation of the urban land unit. See the text for description of notation. Incident, reflected, and net solar and longwave radiation are calculated for each individual surface but are not shown for clarity. @@ -136,7 +136,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic of urban and atmospheric model coupling: -.. Figure:: image2.png +.. Figure:: ../../../images/tech_note/Urban/image2.png Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section :numref:`Atmospheric Coupling`). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. @@ -144,7 +144,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic of THESIS urban properties tool: -.. Figure:: image3.gif +.. Figure:: ../../../images/tech_note/Urban/image3.gif Schematic of THESIS urban properties tool. Executable scripts are in orange, input files are blue, and output files are green. Items within the black box outline are either read in as input, executed, or output by the driver script (urban_prop.csh). diff --git a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst index 7ede3405e0..ffa2a5c96d 100644 --- a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst +++ b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst @@ -33,7 +33,7 @@ storage over the course of a single growing season. .. _Figure annual phenology cycle: -.. figure:: image1.png +.. figure:: ../../../images/tech_note/Vegetation_Phenology_Turnover/image1.png Example of annual phenology cycle for seasonal deciduous. diff --git a/doc/source/tech_note/conf.py b/doc/source/tech_note/conf.py index 69d97bf9eb..5c5b1d86ad 100644 --- a/doc/source/tech_note/conf.py +++ b/doc/source/tech_note/conf.py @@ -73,9 +73,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [ - "clm5.0/*" -] +exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py index 687732893a..ab8a299b9f 100644 --- a/doc/source/users_guide/conf.py +++ b/doc/source/users_guide/conf.py @@ -76,18 +76,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [ - "clm5.0/manage_externals", - "clm5.0/components", - "clm5.0/cime/scripts", - "clm5.0/cime/doc", - "clm5.0/cime/config", - "clm5.0/cime/tools/statistical_ensemble_test", - "clm5.0/cime/src", - "clm5.0/cime/utils", - "**/README_EXTERNALS.rst", - "clm5.0/README.rst" -] +exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index c3d29ab83b..a7a9ef434c 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -153,7 +153,7 @@ README file describing |version| The README (which can be found in ``$CTSMROOT/doc``) is repeated here. -.. include:: ../../clm5.0/README +.. include:: ../../../../README :literal: .. _best-practices-for-usage: diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index 9160666051..65398200e9 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -31,5 +31,5 @@ Note other directories have README files that explain different components and t The Quickstart.GUIDE (which can be found in ``$CTSMROOT/doc``) is repeated here. -.. include:: ../../clm5.0/doc/Quickstart.GUIDE +.. include:: ../../../Quickstart.GUIDE :literal: diff --git a/doc/source/users_guide/overview/scientific_validation.rst b/doc/source/users_guide/overview/scientific_validation.rst index 9b38be4808..d05497a645 100644 --- a/doc/source/users_guide/overview/scientific_validation.rst +++ b/doc/source/users_guide/overview/scientific_validation.rst @@ -27,5 +27,5 @@ The IMPORTANT_NODES file goes into more details on this. The IMPORTANT_NOTES (which can be found in ``$CTSMROOT/doc``) is repeated here. -.. include:: ../../clm5.0/doc/IMPORTANT_NOTES +.. include:: ../../../IMPORTANT_NOTES :literal: diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst index 1eaf471739..04fad02db2 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -135,5 +135,5 @@ Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne PTCLMmkdata includes a README file that gives some extra details and a simple example. -.. include:: ../../clm5.0/tools/PTCLM/README +.. include:: ../../../../tools/PTCLM/README :literal: diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst index d6b6c74d91..a93610f9fa 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst @@ -19,7 +19,7 @@ a specified equilibrium state (denoted by the dotted lines) due to the different .. _Figure SP spinup plot for 1850: -.. figure:: image1.png +.. figure:: ../../../images/users_guide/running-special-cases/image1.png SP spinup plot for year 1850. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl. @@ -28,6 +28,6 @@ Again, it takes about 10 years to reach equilibrium. .. _Figure SP spinup plot for 2000 CO2: -.. figure:: image2.png +.. figure:: ../../../images/users_guide/running-special-cases/image2.png SP spinup plot for year 2000 CO2. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl. diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst index 9808ceb05b..3ad4bdb5a5 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst @@ -12,7 +12,7 @@ total ecosystem carbon disequilibrium takes the longest to satisfy due to slow s .. _Figure BGC AD spinup plot for 1850 GSWP3: -.. figure:: image3.png +.. figure:: ../../../images/users_guide/running-special-cases/image3.png BGC AD spinup plot for a year 1850 case with GSWP3 atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. @@ -24,7 +24,7 @@ criteria depending on their application. .. _Figure BGC pAD spinup plot for 1850 GSWP3: -.. figure:: image4.png +.. figure:: ../../../images/users_guide/running-special-cases/image4.png BGC pAD spinup plot for a year 1850 case with GSWP3 atmospheric forcing and initialization from the end of the BGC AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. @@ -35,7 +35,7 @@ such as TLAI (total leaf area index), GPP (gross primary production), and TWS (t .. _Figure BGC initialized spinup plot for 1850: -.. figure:: image5.png +.. figure:: ../../../images/users_guide/running-special-cases/image5.png BGC initialized spinup plot for year 1850. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. @@ -44,7 +44,7 @@ Again, it takes about 10 years to reach equilibrium for TLAI, GPP, and TWS. .. _Figure BGC initialized spinup plot for 2000 CO2: -.. figure:: image6.png +.. figure:: ../../../images/users_guide/running-special-cases/image6.png BGC initialized spinup plot for year 2000 CO2. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index 04f90fc3d3..a01630c293 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -29,13 +29,13 @@ see the `CTSM Wiki on Testing Date: Mon, 23 Mar 2020 16:47:30 -0600 Subject: [PATCH 232/255] Fixes for pdf - Change urban figure from gif to png (gif doesn't work with pdf output) - Remove some broken latex coding from the References section; it doesn't seem like this was accomplishing anything before (based on looking at an old version of the pdf, generated Feb 2019) --- Externals_CLM.cfg | 2 +- .../References/CLM50_Tech_Note_References.rst | 786 ------------------ .../tech_note/Urban/CLM50_Tech_Note_Urban.rst | 2 +- 3 files changed, 2 insertions(+), 788 deletions(-) diff --git a/Externals_CLM.cfg b/Externals_CLM.cfg index f01e14ebb2..05fe44c0ae 100644 --- a/Externals_CLM.cfg +++ b/Externals_CLM.cfg @@ -16,7 +16,7 @@ required = True local_path = doc/images protocol = git repo_url = https://github.com/ESCOMP/CTSM-doc-images.git -hash = 0f039e7a043fabfce91ddf4f41186a3014603aac +hash = 9e12e5531d8cd3f2e9c6a0154dba8289ffd32c7f required = False [externals_description] diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index c0fe7cc556..f5ffc26b95 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -3,14 +3,8 @@ References ============== -.. |br| raw:: latex - - \\ - .. _Aberetal1990: -|br| - Aber, J.D., Melillo, J.M. and McClaugherty, C.A., 1990. Predicting long-term patterns of mass loss, nitrogen dynamics, and soil organic matter formation from initial fime litter chemistry in temperate forest @@ -18,8 +12,6 @@ ecosystems. Canadian Journal of Botany, 68: 2201-2208. .. _Aberetal2003: -|br| - Aber, J.D., Goodale, C.L., Ollinger, S.V., Smith, M.-L., Magill, A.H., Martin, M.E., Hallett, R.A., and Stoddard, J.L. 2003. Is nitrogen deposition altering the nitrogen status of northeastern forests? @@ -27,32 +19,24 @@ BioScience 53:375-389. .. _Alietal2016: -|br| - Ali, A. A., C. Xu, A. Rogers, R. A. Fisher, S. D. Wullschleger, E. Massoud, J. A. Vrugt, J. D. Muss, N. McDowell, and J. Fisher, 2016: A global scale mechanistic model of photosynthetic capacity (LUNA V1. 0). Geosci. Mod. Dev., 9:587-606. .. _Allenetal2005: -|br| - Allen, C.B., Will, R.E., and Jacobson, M.A. 2005. Production efficiency and radiation use efficiency of four tree species receiving irrigation and fertilization. Forest Science 51:556-569. .. _Anderson1976: -|br| - Anderson, E.A. 1976. A point energy and mass balance model of a snow cover. NOAA Technical Report NWS 19, Office of Hydrology, National Weather Service, Silver Spring, MD. .. _Andréetal1986: -|br| - André, J.-C., Goutorbe, J.-P., and Perrier, A. 1986. HAPEX-MOBILHY: A hydrologic atmosphere experiment for the study of water budget and evaporation flux at the climatic scale. Bull. Amer. Meteor. Soc. @@ -60,53 +44,39 @@ evaporation flux at the climatic scale. Bull. Amer. Meteor. Soc. .. _AndrénPaustian1987: -|br| - Andrén, O. and Paustian, K., 1987. Barley straw decomposition in the field: a comparison of models. Ecology 68:1190-1200. .. _ArahStephen1998: -|br| - Arah, J.R.M. and Stephen, K.D., 1998. A model of the processes leading to methane emission from peatland. Atmos. Environ. 32:3257-3264. .. _ArahVinten1995: -|br| - Arah, J. and Vinten, A., 1995. Simplified models of anoxia and denitrification in aggregated and simple-structured soils. European Journal of Soil Science 46:507-517. .. _Arendtetal2012: -|br| - Arendt, A., et al. 2012. Randolph Glacier Inventory: A Dataset of Global Glacier Outlines Version: 1.0, Global Land Ice Measurements from Space, Boulder Colorado, USA. Digital Media. .. _AroraBoer2005: -|br| - Arora, V.K. and Boer, G.J. 2005. Fire as an interactive component of dynamic vegetation models. J. Geophys. Res. 110:G02008. DOI:10.1029/2005JG000042. .. _Arya2001: -|br| - Arya, S.P. 2001. Introduction to Meteorology. Academic Press, San Diego, CA. .. _Asneretal1998: -|br| - Asner, G.P., Wessman, C.A., Schimel, D.S., and Archer, S. 1998. Variability in leaf and litter optical properties: implications for BRDF model inversions using AVHRR, MODIS, and MISR. Remote Sens. Environ. @@ -114,76 +84,56 @@ model inversions using AVHRR, MODIS, and MISR. Remote Sens. Environ. .. _AxelssonAxelsson1986: -|br| - Axelsson, E., and Axelsson, B. 1986. Changes in carbon allocation patterns in spruce and pine trees following irrigation and fertilization. Tree Phys. 2:189-204. .. _Atkin2016: -|br| - Atkin OK, Bloomfield KJ, Reich PB, Tjoelker MG, Asner GP, Bonal D et al (2015) Global variability in leaf respiration in relation to climate, plant functional types and leaf traits. New Phytologist 206:614–636 .. _Atkin2017: -|br| - Leaf Respiration in Terrestrial Biosphere Models. In Plant Respiration: Metabolic Fluxes and Carbon Balance, Advances in Photosynthesis and Respiration 43, G. Tcherkez, J. Ghashghaie (eds.) Springer International Publishing AG 2017 .. _BadgerandDirmeyer2015: -|br| - Badger, A.M., and Dirmeyer, P.A., 2015. Climate response to Amazon forest replacement by heterogeneous crop cover. Hydrol. Earth. Syst. Sci. 19:4547- 4557. .. _Bairdetal2004: -|br| - Baird, A.J., Beckwith, C.W., Waldron, S. and Waddington, J.M., 2004. Ebullition of methane-containing gas bubbles from near-surface Sphagnum peat. Geophys. Res. Lett. 31. DOI:10.1029/2004GL021157. .. _Baldocchietal2001: -|br| - Baldocchi, D., et al. 2001. FLUXNET: A new tool to study the temporal and spatial variability of ecosystem-scale carbon dioxide, water vapor, and energy flux densities. Bull. Amer. Meteor. Soc. 82:2415-2433. .. _Barbottinetal2005: -|br| - Barbottin, A., Lecomte, C., Bouchard, C., and Jeuffroy, M.-H. 2005. Nitrogen remobilization during grain filling in wheat: Genotypic and environmental effects. Crop Sci. 45:1141-1150. .. _Batjes2006: -|br| - Batjes, N.H., 2006. ISRIC-WISE derived soil properties on a 5 by 5 arc-minutes global grid. Report 2006/02 (available through : http://www.isric.org) .. _Berger1978a: -|br| - Berger, A.L. 1978a. Long-term variations of daily insolation and quaternary climatic changes. J. Atmos. Sci. 35:2362-2367. .. _Berger1978b: -|br| - Berger, A.L. 1978b. A simple algorithm to compute long-term variations of daily or monthly insolation. Contribution de l’Institut d’Astronomie et de Géophysique, Université Catholique de Louvain, Louvain-la-Neuve, @@ -191,37 +141,27 @@ No. 18. .. _Bergeretal1993: -|br| - Berger, A., Loutre, M.-F., and Tricot, C. 1993. Insolation and Earth’s orbital periods. J. Geophys. Res. 98:10341-10362. .. _BerkowitzBalberg1992: -|br| - Berkowitz, B., and Balberg, I. 1992. Percolation approach to the problem of hydraulic conductivity in porous media. Transport in Porous Media 9:275–286. .. _BevenKirkby1979: -|br| - Beven, K.J., and Kirkby, M.J. 1979. A physically based variable contributing area model of basin hydrology. Hydrol. Sci. Bull. 24:43-69. .. _BohrenHuffman1983: -|br| - Bohren, C. F., and Huffman, D. R. 1983. Absorption and scattering of light by small particles. John Wiley & Sons, New York, NY. .. _Bonan1996: -|br| - Bonan, G.B. 1996. A land surface model (LSM version 1.0) for ecological, hydrological, and atmospheric studies: Technical description and user’s guide. NCAR Technical Note NCAR/TN-417+STR, National Center for @@ -229,23 +169,17 @@ Atmospheric Research, Boulder, CO, 150 pp. .. _Bonan1998: -|br| - Bonan, G.B. 1998. The land surface climatology of the NCAR Land Surface Model coupled to the NCAR Community Climate Model. J. Climate 11:1307-1326. .. _Bonan2002: -|br| - Bonan, G.B. 2002. Ecological Climatology: Concepts and Applications. Cambridge University Press. .. _Bonanetal2002a: -|br| - Bonan, G.B., Oleson, K.W., Vertenstein, M., Levis, S., Zeng, X., Dai, Y., Dickinson, R.E., and Yang, Z.-L. 2002a. The land surface climatology of the Community Land Model coupled to the NCAR Community Climate Model. @@ -253,24 +187,18 @@ J. Climate 15: 3123-3149. .. _Bonanetal2002b: -|br| - Bonan, G.B., Levis, S., Kergoat, L., and Oleson, K.W. 2002b. Landscapes as patches of plant functional types: An integrating concept for climate and ecosystem models. Global Biogeochem. Cycles 16: 5.1-5.23. .. _BonanLevis2006: -|br| - Bonan, G.B., and Levis, S. 2006. Evaluating aspects of the Community Land and Atmosphere Models (CLM3 and CAM3) using a dynamic global vegetation model. J. Climate 19:2290-2301. .. _Bonanetal2011: -|br| - Bonan, G.B., Lawrence P.J., Oleson K.W., Levis S., Jung M., Reichstein M., Lawrence, D.M., and Swenson, S.C. 2011. Improving canopy processes in the Community Land Model (CLM4) using global flux fields empirically @@ -279,8 +207,6 @@ DOI:10.1029/2010JG001593. .. _Bonanetal2012: -|br| - Bonan, G. B., Oleson, K.W., Fisher, R.A., Lasslop, G., and Reichstein, M. 2012. Reconciling leaf physiological traits and canopy flux data: Use of the TRY and FLUXNET databases in the Community Land Model version 4, @@ -288,8 +214,6 @@ J. Geophys. Res., 117, G02026. DOI:10.1029/2011JG001913. .. _Bonanetal2014: -|br| - Bonan, G.B., Williams, M., Fisher, R.A., and Oleson, K.W. 2014. Modeling stomatal conductance in the earth system: linking leaf water-use efficiency and water transport along the soil–plant–atmosphere continuum, @@ -297,68 +221,48 @@ Geosci. Model Dev., 7, 2193-2222, doi:10.5194/gmd-7-2193-2014. .. _botta2000: -|br| - Botta, A et al., 2000. A global prognostic scheme of leaf onset using satellite data. Global Change Biology 6.7, pp. 709-725. .. _Brun1989: -|br| - Brun, E. 1989. Investigation of wet-snow metamorphism in respect of liquid water content. Ann. Glaciol. 13:22-26. .. _Brunkeetal2016: -|br| - Brunke, M. A., P. Broxton, J. Pelletier, D. Gochis, P. Hazenberg, D. M. Lawrence, L. R. Leung, G.-Y. Niu, P. A. Troch, and X. Zeng, 2016: Implementing and Evaluating Variable Soil Thickness in the Community Land Model, Version 4.5 (CLM4.5). J. Clim. 29:3441-3461. .. _Brzosteketal2014: -|br| - Brzostek, E. R., J. B. Fisher, and R. P. Phillips, 2014. Modeling the carbon cost of plant nitrogen acquisition: Mycorrhizal trade-offs and multipath resistance uptake improve predictions of retranslocation. J. Geophys. Res. Biogeosci., 119, 1684–1697, doi:10.1002/2014JG002660. .. _BugmannSolomon2000: -|br| - Bugmann, H., and Solomon, A.M. 2000. Explaining forest composition and biomass across multiple biogeographical regions. Ecol. Appl. 10:95-114. .. _Busing2005: -|br| - Busing, R.T. 2005. Tree mortality, canopy turnover, and woody detritus in old cove forests of the southern Appalachians. Ecology 86:73-84. .. _Buzanetal2015: -|br| - Buzan, J.R., Oleson, K., and Huber, M. 2015: Implementation and comparison of a suite of heat stress metrics within the Community Land Model version 4.5, Geosci. Model Dev., 8, 151-170, doi:10.5194/gmd-8-151-2015. .. _byram1959: -|br| - Byram, G.M., 1959. Combustion of forest fuels. In Forest fire: control and use.(Ed. KP Davis) pp. 61-89. .. _CampbellNorman1998: -|br| - Campbell, G.S., and Norman, J.M. 1998. An Introduction to Environmental Biophysics (2:math:`{}^{nd}` edition). Springer-Verlag, New York. .. _Castilloetal2012: -|br| - Castillo, G., Kendra, C., Levis, S., and Thornton, P. 2012. Evaluation of the new CNDV option of the Community Land Model: effects of dynamic vegetation and interactive nitrogen on CLM4 means and variability. J. @@ -366,16 +270,12 @@ Climate 25:3702–3714. .. _Caoetal1996: -|br| - Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and methane emissions from natural wetlands: Application of a process-based model. J. Geophys. Res. 101(D9):14,399-14,414. .. _Chuangetal2006: -|br| - Chuang Y.L., Oren R., Bertozzi A.L, Phillips N., Katul G.G. 2006. The porous media model for the hydraulic system of a conifer tree: Linking sap flux data to transpiration rate, Ecological Modelling, 191, 447-468, @@ -383,16 +283,12 @@ doi:10.1016/j.ecolmodel.2005.03.027. .. _Churkinaetal2003: -|br| - Churkina, G. et al., 2003. Analyzing the ecosystem carbon dynamics of four European coniferous forests using a biogeochemistry model. Ecosystems, 6: 168-184. .. _CIESIN2005: -|br| - CIESIN: Gridded population of the world version 3 (GPWv3), 2005. Population density grids, Technical report, Socioeconomic Data and Applications Center (SEDAC), Columbia University, Palisades, New York, @@ -400,23 +296,17 @@ USA. .. _ClappHornberger1978: -|br| - Clapp, R.B., and Hornberger, G.M. 1978. Empirical equations for some soil hydraulic properties. Water Resour. Res. 14:601-604. .. _ClauserHuenges1995: -|br| - Clauser, C., and Huenges, E. 1995. Thermal conductivity of rocks and minerals. pp. 105-126. In: T. J. Ahrens (editor) Rock Physics and Phase Relations: A Handbook of Physical Constants. Washington, D.C. .. _Clevelandetal1999: -|br| - Cleveland, C.C., Townsend, A.R., Schimel, D.S., Fisher, H., Howarth, R.W., Hedin, L.O., Perakis, S.S., Latty, E.F., Von Fischer, J.C., Elseroad, A., and Wasson, M.F. 1999. Global patterns of terrestrial @@ -425,8 +315,6 @@ Biogeochem. Cycles 13:623-645. .. _Collatzetal1991: -|br| - Collatz, G.J., Ball, J.T., Grivet, C., and Berry, J.A. 1991. Physiological and environmental regulation of stomatal conductance, photosynthesis, and transpiration: A model that includes a laminar @@ -434,31 +322,23 @@ boundary layer. Agric. For. Meteor. 54:107-136. .. _Collatzetal1992: -|br| - Collatz, G.J., Ribas-Carbo, M., and Berry, J.A. 1992. Coupled photosynthesis-stomatal conductance model for leaves of C\ :math:`{}_{4}` plants. Aust. J. Plant Physiol. 19:519-538. .. _Colmer2003: -|br| - Colmer, T.D., 2003. Long-distance transport of gases in plants: a perspective on internal aeration and radial oxygen loss from roots. Plant Cell and Environment 26:17-36. .. _Conwayetal1996: -|br| - Conway, H., Gades, A., and Raymond, C.F. 1996. Albedo of dirty snow during conditions of melt. Water Resour. Res. 32:1713-1718. .. _Cosbyetal1984: -|br| - Cosby, B.J., Hornberger, G.M., Clapp, R.B., and Ginn, T.R. 1984. A statistical exploration of the relationships of soil moisture characteristics to the physical properties of soils. Water Resour. Res. @@ -466,38 +346,28 @@ characteristics to the physical properties of soils. Water Resour. Res. .. _Crawfordetal1982: -|br| - Crawford, T. W., Rendig, V. V., and Broadent, F. E. 1982. Sources, fluxes, and sinks of nitrogen during early reproductive growth of maize (Zea mays L.). Plant Physiol. 70:1645-1660. .. _Dahlinetal2015: -|br| - Dahlin, K., R. Fisher, and P. Lawrence, 2015: Environmental drivers of drought deciduous phenology in the Community Land Model. Biogeosciences, 12:5061-5074. .. _DaiZeng1997: -|br| - Dai, Y., and Zeng, Q. 1997. A land surface model (IAP94) for climate studies. Part I: formulation and validation in off-line experiments. Adv. Atmos. Sci. 14:433-460. .. _Daietal2001: -|br| - Dai, Y., et al. 2001. Common Land Model: Technical documentation and user’s guide [Available online at http://climate.eas.gatech.edu/dai/clmdoc.pdf]. .. _Daietal2003: -|br| - Dai, Y., Zeng, X., Dickinson, R.E., Baker, I., Bonan, G.B., Bosilovich, M.G., Denning, A.S., Dirmeyer, P.A., Houser, P.R., Niu, G., Oleson, K.W., Schlosser, C.A., and Yang, Z.-L. 2003. The Common Land Model. @@ -505,32 +375,24 @@ Bull. Amer. Meteor. Soc. 84:1013-1023. .. _Daietal2004: -|br| - Dai, Y., Dickinson, R.E., and Wang, Y.-P. 2004. A two-big-leaf model for canopy temperature, photosynthesis, and stomatal conductance. J. Climate 17:2281-2299. .. _DaiTrenberth2002: -|br| - Dai, A., and Trenberth, K.E. 2002. Estimates of freshwater discharge from continents: Latitudinal and seasonal variations. J. Hydrometeor. 3:660-687. .. _DeFriesetal2000: -|br| - DeFries, R.S., Hansen, M.C., Townshend, J.R.G., Janetos, A.C., and Loveland, T.R. 2000. A new global 1-km dataset of percentage tree cover derived from remote sensing. Global Change Biol. 6:247-254. .. _DegensSparling1996: -|br| - Degens, B. and Sparling, G., 1996. Changes in aggregation do not correspond with changes in labile organic C fractions in soil amended with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): @@ -538,8 +400,6 @@ with :math:`{}^{14}`\ C-glucose. Soil Biology and Biochemistry, 28(4/5): .. _deKauwe2015: -|br| - de Kauwe, D.A., Kala, J., Lin, Y.-S., Pitman, A.J., Medlyn, B.E., Duursma, R.A., Abramowitz, G., Wang, Y.-P., Miralles, D.G. 2015. A test of an optimal stomatal conductance scheme within the CABLE land surface model. Geosci. Model Dev. @@ -547,22 +407,16 @@ conductance scheme within the CABLE land surface model. Geosci. Model Dev. .. _deVries1963: -|br| - de Vries, D.A. 1963. Thermal Properties of Soils. In: W.R. van Wijk (editor) Physics of the Plant Environment. North-Holland, Amsterdam. .. _Dickinson1983: -|br| - Dickinson, R.E. 1983. Land surface processes and climate-surface albedos and energy balance. Adv. Geophys. 25:305-353. .. _Dickinsonetal1993: -|br| - Dickinson, R.E., Henderson-Sellers, A., and Kennedy, P.J. 1993. Biosphere-Atmosphere Transfer Scheme (BATS) version 1e as coupled to the NCAR Community Climate Model. NCAR Technical Note NCAR/TN-387+STR. @@ -570,8 +424,6 @@ National Center for Atmospheric Research, Boulder, CO. .. _Dickinsonetal2006: -|br| - Dickinson, R.E., Oleson, K.W., Bonan, G., Hoffman, F., Thornton, P., Vertenstein, M., Yang, Z.-L., and Zeng, X. 2006. The Community Land Model and its climate statistics as a component of the Community Climate @@ -579,30 +431,22 @@ System Model. J. Climate 19:2302-2324. .. _Dingman2002: -|br| - Dingman, S.L. 2002. Physical Hydrology. Second Edition. Prentice Hall, NJ. .. _Dirmeyeretal1999: -|br| - Dirmeyer, P.A., Dolman, A.J., and Sato, N. 1999. The pilot phase of the Global Soil Wetness Project. Bull. Amer. Meteor. Soc. 80:851-878. .. _Dobsonetal2000: -|br| - Dobson, J.E., Bright, E.A., Coleman, P.R., Durfee, R.C., and Worley, B.A. 2000. LandScan: A global population database for estimating populations at risk. Photogramm. Eng. Rem. Sens. 66:849-857. .. _DormanSellers1989: -|br| - Dorman, J.L., and Sellers, P.J. 1989. A global climatology of albedo, roughness length and stomatal resistance for atmospheric general circulation models as represented by the simple biosphere model (SiB). @@ -610,63 +454,47 @@ J. Appl. Meteor. 28:833-855. .. _Doughertyetal1994: -|br| - Dougherty, R.L., Bradford, J.A., Coyne, P.I., and Sims, P.L. 1994. Applying an empirical model of stomatal conductance to three C4 grasses. Agric. For. Meteor. 67:269-290. .. _Drewniaketal2013: -|br| - Drewniak, B., Song, J., Prell, J., Kotamarthi, V.R., and Jacob, R. 2013. Modeling agriculture in the Community Land Model. Geosci. Model Dev. 6:495-515. DOI:10.5194/gmd-6-495-2013. .. _Dunfieldetal1993: -|br| - Dunfield, P., Knowles, R., Dumont, R. and Moore, T.R., 1993. Methane Production and Consumption in Temperate and Sub-Arctic Peat Soils - Response to Temperature and Ph. Soil Biology & Biochemistry 25:321-326. .. _EntekhabiEagleson1989: -|br| - Entekhabi, D., and Eagleson, P.S. 1989. Land surface hydrology parameterization for atmospheric general circulation models including subgrid scale spatial variability. J. Climate 2:816-831. .. _FangStefan1996: -|br| - Fang, X. and Stefan, H.G., 1996. Long-term lake water temperature and ice cover simulations/measurements. Cold Regions Science and Technology 24:289-304. .. _Farouki1981: -|br| - Farouki, O.T. 1981. The thermal properties of soils in cold regions. Cold Regions Sci. and Tech. 5:67-75. .. _Farquharetal1980: -|br| - Farquhar, G.D., von Caemmerer, S., and Berry, J.A. 1980. A biochemical model of photosynthetic CO\ :sub:`2` assimilation in leaves of C\ :math:`{}_{3}` species. Planta 149:78-90. .. _FarquharvonCaemmerer1982: -|br| - Farquhar, G.D., and von Caemmerer, S. 1982. Modeling of photosynthetic response to environmental conditions. pp. 549-587. In: O.L. Lange, P.S. Nobel, C.B. Osmond, and H. Zeigler (editors) Encyclopedia of Plant @@ -675,86 +503,62 @@ and Carbon Assimilation. Springer-Verlag, New York. .. _FeddemaKauffman2016: -|br| - Feddema, J., Kauffman, B. 2016. Urban Properties Tool (Version 1.2). NCAR THESIS Tools Library. Retrieved from: https://svn-iam-thesis-release.cgd.ucar.edu/urban_properties/. doi:10.5065/D6R78CMT. .. _Ferrari1999: -|br| - Ferrari, J.B., 1999. Fine-scale patterns of leaf litterfall and nitrogen cycling in an old-growth forest. Canadian Journal of Forest Research, 29: 291-302. .. _FirestoneDavidson1989: -|br| - Firestone, M.K. and Davidson, E.A. 1989. Exchange of Trace Gases between Terrestrial Ecosystems and the Atmosphere. In: M.O. Andreae and D.S. Schimel (Editors). John Wiley and Sons, pp. 7-21. .. _Fisheretal2010: -|br| - Fisher, J. B., S. Sitch, Y. Malhi, R. A. Fisher, C. Huntingford, and S.-Y. Tan, 2010. Carbon cost of plant nitrogen acquisition: A mechanistic, globally applicable model of plant nitrogen uptake, retranslocation, and fixation. Global Biogeochem. Cycles, 24, GB1014, doi:10.1029/2009GB003621. .. _Fisheretal2015: -|br| - Fisher, R. A., S. Muszala, M. Verteinstein, P. Lawrence, C. Xu, N. G. McDowell, R. G. Knox, C. Koven, J. Holm, B. M. Rogers, A. Spessa, D. Lawrence, and G. Bonan, 2015: Taking off the training wheels: the properties of a dynamic vegetation model without climate envelopes, CLM4.5(ED). Geosci. Model Dev., 8: 3593-3619, doi:10.5194/gmd-8-3593-2015. .. _Fisheretal2018: -|br| - Fisher, R.A., C.D. Koven, W.R.L. Anderegg, et al., 2018: Vegetation demographics in Earth System Models: A review of progress and priorities. Glob Change Biol. 2018;24:35–54. https://doi.org/10.1111/gcb.13910 .. _FlannerZender2005: -|br| - Flanner, M.G., and Zender. C.S. 2005. Snowpack radiative heating: Influence on Tibetan Plateau climate. Geophys. Res. Lett. 32:L06501. DOI:10.1029/2004GL022076. .. _FlannerZender2006: -|br| - Flanner, M.G., and Zender, C.S. 2006. Linking snowpack microphysics and albedo evolution. J. Geophys. Res. 111:D12208. DOI:10.1029/2005JD006834. .. _Flanneretal2007: -|br| - Flanner, M.G., Zender, C.S., Randerson, J.T., and Rasch, P.J. 2007. Present day climate forcing and response from black carbon in snow. J. Geophys. Res. 112:D11202. DOI:10.1029/2006JD008003. .. _Flatauetal1992: -|br| - Flatau, P.J., Walko, R.L., and Cotton, W.R. 1992. Polynomial fits to saturation vapor pressure. J. Appl. Meteor. 31:1507-1513. .. _foley1996: -|br| - Foley, J.A. et al., 1996. An integrated biosphere model of land surface processes, terrestrial carbon balance, and vegetation dynamics. Global Biogeochemical Cycles 10.4, pp. 603-628. .. _Friedl,etal2002: -|br| - Friedl, M.A., McIver, D.K., Hodges, J.C.F., Zhang, X.Y., Muchoney, D., Strahler, A.H., Woodcock, C.E., Gopal, S., Schneider, A., Cooper, A., Baccini, A., Gao, F., and Schaaf, C. 2002. Global land cover mapping @@ -763,29 +567,21 @@ from MODIS: algorithms and early results. Remote Sens. Environ. .. _Frolkingetal2001: -|br| - Frolking, S., et al. 2001. Modeling Northern Peatland Decomposition and Peat Accumulation. Ecosystems. 4:479-498. .. _fyllas2014: -|br| - Fyllas, N.M. et al., 2014. Analysing Amazonian forest productivity using a new individual and trait- based model (TFS v. 1). Geoscientific Model Development 7.4, pp. 1251-1269. .. _Gallaisetal2006: -|br| - Gallais, A., Coque, M. Quillere, I., Prioul, J., and Hirel, B. 2006. Modeling postsilking nitrogen fluxes in maize (Zea mays) using 15N-labeling field experiments. New Phytologist 172:696-707. .. _Gallaisetal2007: -|br| - Gallais, A., Coque, M., Gouis, J. L., Prioul, J. L., Hirel, B., and Quillere, I. 2007. Estimating the proportion of nitrogen remobilization and of postsilking nitrogen uptake allocated to maize kernels by @@ -793,15 +589,11 @@ Nitrogen-15 labeling. Crop Sci. 47:685-693. .. _Gallowayetal2004: -|br| - Galloway, J.N., et al. 2004. Nitrogen cycles: past, present, and future. Biogeochem. 70:153-226. .. _Garciaetal1988: -|br| - Garcia, R.L., Kanemasu, E.T., Blad, B.L., Bauer, A., Hatfield, J.L., Major, D.A., Reginato, R.J., and Hubbard, K.G. 1988. Interception and use efficiency of light in winter wheat under different nitrogen @@ -809,15 +601,11 @@ regimes. Agric. For. Meteor. 44:175-186. .. _Gardner1960: -|br| - Gardner, W. R. 1960. Dynamic aspects of water availability to plants, Soil Sci., 89, 63–73. .. _Gashetal1996: -|br| - Gash, J.H.C., Nobre, C.A., Roberts, J.M., and Victoria, R.L. 1996. An overview of ABRACOS. pp. 1-14. In: J.H.C. Gash, C.A. Nobre, J.M. Roberts, and R.L. Victoria (editors) Amazonian Deforestation and @@ -825,22 +613,16 @@ Climate. John Wiley and Sons, Chichester, England. .. _Getiranaetal2012: -|br| - Getirana, A. C. V., A. Boone, D. Yamazaki, B. Decharme, F. Papa, and N. Mognard. 2012. The hydrological modeling and analysis platform (HyMAP): Evaluation in the Amazon basin, J. Hydrometeorol., 13, 1641-1665. .. _Ghimireetal2016: -|br| - Ghimire, B., W. J. Riley, C. D. Koven, M. Mu, and J. T. Randerson, 2016: Representing leaf and root physiological traits in CLM improves global carbon and nitrogen cycling predictions. J. Adv. Mod. Earth Sys. 8: 598-613. .. _Gholzetal1985: -|br| - Gholz, H.L., Perry, C.S., Cropper, W.P., Jr. and Hendry, L.C., 1985. Litterfall, decomposition, and nitrogen and phosphorous dynamics in a chronosequence of slash pine (*Pinus elliottii*) plantations. Forest @@ -848,8 +630,6 @@ Science, 31: 463-478. .. _Giglioetal2006: -|br| - Giglio, L., Csiszar, I., and Justice, C.O. 2006. Global distribution and seasonality of active fires as observed with the Terra and Aqua Moderate Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. @@ -857,32 +637,24 @@ Resolution Imaging Spectroradiometer (MODIS) sensors. J. Geophys. Res. .. _GlobalSoilDataTask2000: -|br| - Global Soil Data Task 2000. Global soil data products CD-ROM (IGBP-DIS). International Geosphere-Biosphere Programme-Data and Information Available Services [Available online at http://www.daac.ornl.gov]. .. _Gomesetal2003: -|br| - Gomes, E.P.C., Mantovani, W., and Kageyama, P.Y. 2003. Mortality and recruitment of trees in a secondary montane rain forest in southeastern Brazil. Brazilian Journal of Biology 63:47-60. .. _Goszetal1973: -|br| - Gosz, J.R., Likens, G.E., and Bormann, F.H. 1973. Nutrient release from decomposing leaf and branch litter in the Hubbard Brook Forest, New Hampshire. Ecological Monographs 43:173-191. .. _GotangcoCastilloetal2012: -|br| - Gotangco Castillo C., Levis S., and Thornton P. 2012. Evaluation of the new CNDV option of the Community Land Model: Effects of dynamic vegetation and interactive nitrogen on CLM4 means and variability. J. @@ -890,8 +662,6 @@ Climate 25:3702-3714. DOI:10.1175/JCLID-11-00372.1. .. _Grahametal1999: -|br| - Graham, S.T., Famiglietti, J.S., and Maidment, D.R. 1999. Five-minute, 1/2º, and 1º data sets of continental watersheds and river networks for use in regional and global hydrologic and climate system modeling @@ -899,30 +669,22 @@ studies. Water Resour. Res. 35:583-587. .. _Gravenetal2017: -|br| - Graven, H., C. E. Allison, D. M. Etheridge, S. Hammer, R. F. Keeling, I. Levin, H. A. J. Meijer, M. Rubino, P. P. Tans, C. M. Trudinger, B. H. Vaughn and J. W. C. White, 2017. Compiled records of carbon isotopes in atmospheric CO2 for historical simulations in CMIP6, Geoscientific Model Development, in review. doi: 10.5194/gmd-2017-166. .. _GrenfellWarren1999: -|br| - Grenfell, T.C., and Warren, S.G. 1999. Representation of a nonspherical ice particle by a collection of independent spheres for scattering and absorption of radiation. J. Geophys. Res. 104(D24):37697-37709. .. _delGrossoetal2000: -|br| - del Grosso, S.J., et al. 2000. General model for N2O and N2 gas emissions from soils due to dentrification. Global Biogeochem. Cycles 14:1045-1060. .. _Guentheretal1995: -|br| - Guenther, A., Hewitt, C.N., Erickson, D., Fall, R., Geron, C., Graedel, T., Harley, P., Klinger, L., Lerdau, M., McKay, W.A., Pierce, T., Scholes, B., Steinbrecher, R., Tallamraju, R., Taylor, J., and @@ -931,8 +693,6 @@ emissions. J. Geophys. Res. 100:8873-8892. .. _Guentheretal2006: -|br| - Guenther, A., Karl, T., Harley, P., Wiedinmyer, C., Palmer. P.I., and Geron, C. 2006. Estimates of global terrestrial isoprene emissions using MEGAN (Model of Emissions of Gases and Aerosols from Nature). Atmos. @@ -940,8 +700,6 @@ Chem. Phys. 6:3181–3210. .. _Guentheretal2012: -|br| - Guenther, A. B., Jiang, X., Heald, C. L., Sakulyanontvittaya, T., Duhl, T., Emmons, L. K., & Wang, X., 2012. The Model of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1): an extended and updated @@ -950,8 +708,6 @@ framework for modeling biogenic emissions, Geosci. Model Dev., 5, .. _Hacketal2006: -|br| - Hack, J.J., Caron, J.M., Yeager, S.G., Oleson, K.W., Holland, M.M., Truesdale, J.E., and Rasch, P.J. 2006. Simulation of the global hydrological cycle in the CCSM Community Atmosphere Model version 3 @@ -959,8 +715,6 @@ hydrological cycle in the CCSM Community Atmosphere Model version 3 .. _Hansenetal2003: -|br| - Hansen, M., DeFries, R.S., Townshend, J.R.G., Carroll, M., Dimiceli, C., and Sohlberg, R.A. 2003. Global percent tree cover at a spatial resolution of 500 meters: first results of the MODIS vegetation @@ -968,8 +722,6 @@ continuous fields algorithm. Earth Interactions 7:1-15. .. _Hastingsetal1999: -|br| - Hastings, D.A., Dunbar, P.K., Elphingstone, G.M., Bootz, M., Murakami, H., Maruyama, H., Masaharu, H., Holland, P., Payne, J., Bryant, N.A., Logan, T.L., Muller, J.-P., Schreier, G., and MacDonald, J.S., eds., @@ -980,8 +732,6 @@ Colorado 80305-3328, U.S.A. .. _Healdetal2008: -|br| - Heald, C.L., Henze, D.K., Horowitz, L.W., Feddema, J., Lamarque, J.-F., Guenther, A., Hess, P.G., Vitt, F., Seinfeld, J.H., Goldstein, A.H., and Fung, I. 2008. Predicted change in global secondary organic aerosol @@ -990,8 +740,6 @@ change. J. Geophys. Res. 113:D05211. DOI:10.1029/2007JD009092. .. _Healdetal2009: -|br| - Heald, C.L., Wilkinson, M.J., Monson, R.K., Alo, C.A., Wang, G.L., and Guenther, A. 2009. Response of isoprene emission to ambient CO\ :sub:`2` changes and implications for global budgets. Global @@ -999,54 +747,40 @@ Change Biol. 15:1127-1140. DOI:10.1111/j.1365-2486.2008.01802.x .. _Henderson-Sellers1985: -|br| - Henderson-Sellers, B. 1985. New formulation of eddy diffusion thermocline models. Appl. Math. Modelling 9:441-446. .. _Henderson-Sellers1986: -|br| - Henderson-Sellers, B. 1986. Calculating the surface energy balance for lake and reservoir modeling: A review. Rev. Geophys. 24:625-649. .. _Henderson-Sellersetal1993: -|br| - Henderson-Sellers, A., Yang, Z.-L., and Dickinson, R.E. 1993. The project for intercomparison of land-surface parameterization schemes. Bull. Amer. Meteor. Soc. 74: 1335-1349. .. _HostetlerBartlein1990: -|br| - Hostetler, S.W., and Bartlein, P.J. 1990. Simulation of lake evaporation with application to modeling lake level variations of Harney-Malheur Lake, Oregon. Water Resour. Res. 26:2603-2612. .. _Hostetleretal1993: -|br| - Hostetler, S.W., Bates, G.T., and Giorgi, F. 1993. Interactive coupling of a lake thermal model with a regional climate model. J. Geophys. Res. 98:5045-5057. .. _Hostetleretal1994: -|br| - Hostetler, S.W., Giorgi, F., Bates, G.T., and Bartlein, P.J. 1994. Lake-atmosphere feedbacks associated with paleolakes Bonneville and Lahontan. Science 263:665-668. .. _Houetal2012: -|br| - Hou, Z., Huang, M., Leung, L.R., Lin, G., and Ricciuto, D.M. 2012. Sensitivity of surface flux simulations to hydrologic parameters based on an uncertainty quantification framework applied to the Community Land @@ -1054,14 +788,10 @@ Model. J. Geophys. Res. 117:D15108. .. _Houltonetal2008: -|br| - Houlton, B.Z., Wang, Y.P., Vitousek, P.M. and Field, C.B., 2008. A unifying framework for dinitrogen fixation in the terrestrial biosphere. Nature, 454(7202), p.327. .. _HuangLiang2006: -|br| - Huang, M., and Liang, X. 2006. On the assessment of the impact of reducing parameters and identification of parameter uncertainties for a hydrologic model with applications to ungauged basins. J. Hydrol. @@ -1069,8 +799,6 @@ hydrologic model with applications to ungauged basins. J. Hydrol. .. _Hugeliusetal2012: -|br| - Hugelius, G., C. Tarnocai, G. Broll, J.G. Canadell, P. Kuhry, adn D.K. Swanson, 2012. The Northern Circumpolar Soil Carbon Database: spatially distributed datasets of soil coverage and soil carbon storage in the @@ -1079,24 +807,18 @@ northern permafrost regions. Earth Syst. Sci. Data Discuss., 5, 707-733 .. _Huntetal1988: -|br| - Hunt, H.W., Ingham, E.R., Coleman, D.C., Elliott, E.T., and Reid, C.P.P. 1988. Nitrogen limitation of production and decomposition in prairie, mountain meadow, and pine forest. Ecology 69:1009-1016. .. _HuntRunning1992: -|br| - Hunt, E.R., Jr. and Running, S.W., 1992. Simulated dry matter yields for aspen and spruce stands in the north american boreal forest. Canadian Journal of Remote Sensing, 18: 126-133. .. _Huntetal1996: -|br| - Hunt, E.R., Jr. et al., 1996. Global net carbon exchange and intra-annual atmospheric CO\ :sub:`2` concentrations predicted by an ecosystem process model and three-dimensional atmospheric transport @@ -1104,8 +826,6 @@ model. Global Biogeochemical Cycles, 10: 431-456. .. _Hurttetal2006: -|br| - Hurtt, G.C., Frolking, S., Fearon, M.G., Moore, B., Shevliakova, E., Malyshev, S., Pacala, S.W., and Houghton, R.A. 2006. The underpinnings of land-use history: three centuries of global gridded land-use @@ -1114,8 +834,6 @@ Global Change Biol. 12:1208-1229. .. _Hurttetal2011: -|br| - Hurtt, G.C., et al. 2011. Harmonization of land-use scenarios for the period 1500-2100: 600 years of global gridded annual land-use transitions, wood harvest, and resulting secondary lands. Climatic @@ -1123,31 +841,23 @@ Change 109:117-161. DOI:10.1007/s10584-011-0153-2. .. _Idso1981: -|br| - Idso, S.B. 1981. A set of equations for full spectrum and 8- to 14-\ :math:`\mu` \ m and 10.5- to 12.5-\ :math:`\mu` \ m thermal radiation from cloudless skies. Water Resour. Res. 17:295-304. .. _IiyamaHasegawa2005: -|br| - Iiyama, I. and Hasegawa, S., 2005. Gas diffusion coefficient of undisturbed peat soils. Soil Science and Plant Nutrition 51:431-435. .. _Jacksonetal1996: -|br| - Jacksonetal1996: E., and Schulze, E. D. 1996. A global analysis of root distributions for terrestrial biomes Oecologia 108:389–411. DOI:10.1007/BF00333714. .. _Jacksonetal2010: -|br| - Jackson, T.L., Feddema, J.J., Oleson, K.W., Bonan, G.B., and Bauer, J.T. 2010. Parameterization of urban characteristics for global climate modeling. Annals of the Association of American Geographers. @@ -1155,32 +865,24 @@ modeling. Annals of the Association of American Geographers. .. _JenkinsonColeman2008: -|br| - Jenkinson, D. and Coleman, K. 2008. The turnover of organic carbon in subsoils. Part 2. Modelling carbon turnover. European Journal of Soil Science 59:400-413. .. _Jordan1991: -|br| - Jordan, R. 1991. A One-dimensional Temperature Model for a Snow Cover: Technical Documentation for SNTHERM.89. U.S. Army Cold Regions Research and Engineering Laboratory, Special Report 91-16. .. _KattgeKnorr2007: -|br| - Kattge, J., and Knorr, W. 2007. Temperature acclimation in a biochemical model of photosynthesis: a reanalysis of data from 36 species. Plant Cell Environ. 30:1176-1190. DOI:10.1111/j.1365-3040.2007.01690.x. .. _Kattgeetal2009: -|br| - 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 Biol. @@ -1188,24 +890,18 @@ for global–scale terrestrial biosphere models. Global Change Biol. .. _Kavetskietal2002: -|br| - Kavetski, D., Binning, P. and Sloan, S.W., 2002. Noniterative time stepping schemes with adaptive truncation error control for the solution of Richards equation. Water Resources Research, 38(10). .. _Kelleretal2004: -|br| - Keller, M., Palace, M., Asner, G.P., Pereira, R., Jr. and Silva, J.N.M., 2004. Coarse woody debris in undisturbed and logged forests in the eastern Brazilian Amazon. Global Change Biology, 10: 784-795. .. _Kellneretal2006: -|br| - Kellner, E., Baird, A.J., Oosterwoud, M., Harrison, K. and Waddington, J.M., 2006. Effect of temperature and atmospheric pressure on methane (CH4) ebullition from near-surface peats. Geophys. Res. Lett. 33. @@ -1213,24 +909,18 @@ DOI:10.1029/2006GL027509. .. _Kimballetal1997: -|br| - Kimball, J.S., Thornton, P.E., White, M.A. and Running, S.W. 1997. Simulating forest productivity and surface-atmosphere exchange in the BOREAS study region. Tree Physiology 17:589-599. .. _Kohyamaetal2001: -|br| - Kohyama, T., Suzuki, E., Partomihardjo, T., and Yamada, T. 2001. Dynamic steady state of patch-mosaic tree size structure of a mixed diptocarp forest regulated by local crowding. Ecological Research 16:85-98. .. _Kourzeneva2009: -|br| - Kourzeneva, E., 2009. Global dataset for the parameterization of lakes in Numerical Weather Prediction and Climate modeling. ALADIN Newsletter, No 37, July-December, 2009, F. Bouttier and C. Fischer, Eds., @@ -1238,48 +928,36 @@ Meteo-France, Toulouse, France, 46-53. .. _Kourzeneva2010: -|br| - Kourzeneva, E., 2010: External data for lake parameterization in Numerical Weather Prediction and climate modeling. Boreal Environment Research, 15, 165-177. .. _Kourzenevaetal2012: -|br| - Kourzeneva, E., Asensio, H., Martin, E. and Faroux, S., 2012. Global gridded dataset of lake coverage and lake depth for use in numerical weather prediction and climate modelling. Tellus A 64. .. _Kovenetal2009: -|br| - Koven, C., et al. 2009. On the formation of high-latitude soil carbon stocks: The effects of cryoturbation and insulation by organic matter in a land surface model. Geophys. Res. Lett. 36: L21501. .. _Kovenetal2011: -|br| - Koven, C.D., et al. 2011. Permafrost carbon-climate feedbacks accelerate global warming. Proceedings of the National Academy of Sciences 108:14769-14774. .. _Kovenetal2013: -|br| - Koven, C.D. et al. 2013. The effect of vertically-resolved soil biogeochemistry and alternate soil C and N models on C dynamics of CLM4. Biogeosciences Discussions 10:7201-7256. .. _Kovenetal2015: -|br| - Koven, C.D. et al. 2015. Permafrost carbon-climate feedback is sensitive to deep soil carbon decomposability but not deep soil nitrogen dynamics. Proceedings of the National Academies of Science, @@ -1287,20 +965,14 @@ nitrogen dynamics. Proceedings of the National Academies of Science, .. _Kovenetal2017: -|br| - Koven, C.D., G. Hugelius, D.M. Lawrence, and W.R. Wieder, 2017: Higher climatological temperature sensitivity of soil carbon in cold than warm climates. Nature Clim. Change, 7, doi:10.1038/nclimate3421. .. _kucharik1998: -|br| - Kucharik, C.J., J.M. Norman, and S.T. Gower, 1998. Measurements of branch area and adjusting leaf area index indirect measurements. Agricultural and Forest Meteorology 91.1, pp. 69-88. .. _Kuchariketal2000: -|br| - Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., Lenters, J.D., Young-Molling, C., and Ramankutty, N. 2000. Testing the performance of a dynamic global ecosystem model: water balance, carbon @@ -1309,8 +981,6 @@ balance, and vegetation structure. Global Biogeochem. Cycles 14: .. _KucharikBrye2003: -|br| - Kucharik, C.J., and Brye, K.R. 2003. Integrated BIosphere Simulator (IBIS) yield and nitrate loss predictions for Wisconsin maize receiving varied amounts of nitrogen fertilizer. Journal of Environmental Quality @@ -1318,8 +988,6 @@ varied amounts of nitrogen fertilizer. Journal of Environmental Quality .. _Laddetal2992: -|br| - Ladd, J.N., Jocteur-Monrozier, L. and Amato, M., 1992. Carbon turnover and nitrogen transformations in an alfisol and vertisol amended with [U-:math:`{}^{14}`\ C] glucose and [:math:`{}^{15}`\ N] ammonium @@ -1327,8 +995,6 @@ sulfate. Soil Biology and Biochemistry, 24: 359-371. .. _Lamarqueetal2010: -|br| - Lamarque, J.-F., et al. 2010. Historical (1850-2000) gridded anthropogenic and biomass burning emissions of reactive gases and aerosols: methodology and application. Atmos. Chem. Phys. Discuss. @@ -1336,31 +1002,23 @@ aerosols: methodology and application. Atmos. Chem. Phys. Discuss. .. _Larcher1995: -|br| - Larcher, W. 1995. Physiological Plant Ecology, Springer-Verlag, Berlin Heidelberg. .. _LavigneRyan1997: -|br| - Lavigne, M.B., and Ryan, M.G. 1997. Growth and maintenance respiration rates of aspen, black spruce, and jack pine stems at northern and southern BOREAS sites. Tree Phys. 17:543-551. .. _Lawetal2003: -|br| - Law, B.E., Sun, O.J., Campbell, J., Van Tuyl, S. and Thornton, P.E. 2003. Changes in carbon storage and fluxes in a chronosequence of ponderosa pine. Global Change Biology, 9: 510-514. .. _Lawrenceetal2007: -|br| - Lawrence, D.M., Thornton, P.E., Oleson, K.W., and Bonan, G.B. 2007. The partitioning of evapotranspiration into transpiration, soil evaporation, and canopy evaporation in a GCM: Impacts on land-atmosphere interaction. @@ -1368,15 +1026,11 @@ J. Hydrometeor. 8:862-880. .. _LawrenceSlater2008: -|br| - Lawrence, D.M., and Slater, A.G. 2008. Incorporating organic soil into a global climate model. Clim. Dyn. 30. DOI:10.1007/s00382-007-0278-1. .. _Lawrenceetal2008: -|br| - Lawrence, D.M., Slater, A.G., Romanovsky, V.E., and Nicolsky, D.J. 2008. The sensitivity of a model projection of near-surface permafrost degradation to soil column depth and inclusion of soil organic matter. @@ -1384,8 +1038,6 @@ J. Geophys. Res. 113:F02011. DOI:10.1029/2007JF000883. .. _Lawrenceetal2011: -|br| - Lawrence, D.M., K.W. Oleson, M.G. Flanner, P.E. Thornton, S.C. Swenson, P.J. Lawrence, X. Zeng, Z.-L. Yang, S. Levis, K. Sakaguchi, G.B. Bonan, and A.G. Slater, 2011. Parameterization improvements and functional and @@ -1394,8 +1046,6 @@ Model. Earth Sys. 3. DOI:10.1029/2011MS000045. .. _Lawrenceetal2016: -|br| - Lawrence, D.M., Hurtt, G.C., Arneth, A., Brovkin, V., Calvin, K.V., Jones, A.D., Jones, C.D., Lawrence, P.J., de Noblet-Ducoudré, N., Pongratz, J., Seneviratne, S.I., and Shevliakova, E. 2016. The Land Use Model @@ -1405,24 +1055,18 @@ DOI:10.5194/gmd-9-2973-2016. .. _LawrenceChase2007: -|br| - Lawrence, P.J., and Chase, T.N. 2007. Representing a MODIS consistent land surface in the Community Land Model (CLM 3.0). J. Geophys. Res. 112:G01023. DOI:10.1029/2006JG000168. .. _LawrenceChase2010: -|br| - Lawrence, P.J., and Chase, T.N. 2010. Investigating the climate impacts of global land cover change in the Community Climate System Model. Int. J. Climatol. 30:2066-2087. DOI:10.1002/joc.2061. .. _Lawrenceetal2012: -|br| - Lawrence, P.J., et al. 2012. Simulating the biogeochemical and biogeophysical impacts of transient land cover change and wood harvest in the Community Climate System Model (CCSM4) from 1850 to 2100. J. @@ -1430,22 +1074,16 @@ Climate 25:3071-3095. DOI:10.1175/JCLI-D-11-00256.1. .. _LehnerDoll2004: -|br| - Lehner, B. and Döll, P., 2004. Development and validation of a global database of lakes, reservoirs and wetlands, J. Hydrol., 296, 1–22. .. _Lehneretal2008: -|br| - Lehner, B., Verdin, K. and Jarvis, A., 2008. New global hydrograhy derived from spaceborne elevation data. Eos Trans., AGU, 89, 93 – 94. .. _LePageetal2010: -|br| - Le Page, Y., van der Werf, G.R., Morton, D.C., and Pereira, J.M.C. 2010. Modeling fire-driven deforestation potential in Amazonia under current and projected climate conditions. J. Geophys. Res. 115:G03012. @@ -1453,23 +1091,17 @@ DOI:10.1029/2009JG001190. .. _Lerman1979: -|br| - Lerman, A., 1979. Geochemical processes: Water and sediment environments. John Wiley and Sons, New York, N.Y. .. _Lettsetal2000: -|br| - Letts, M.G., Roulet, N.T., Comer, N.T., Skarupa, M.R., and Verseghy, D.L. 2000. Parametrization of peatland hydraulic properties for the Canadian Land Surface Scheme. Atmos.-Ocean 38:141-160. .. _Levisetal2003: -|br| - Levis, S., Wiedinmyer, C., Bonan, G.B., and Guenther, A. 2003. Simulating biogenic volatile organic compound emissions in the Community Climate System Model. J. Geophys. Res. 108:4659. @@ -1477,8 +1109,6 @@ DOI:10.1029/2002JD003203. .. _Levisetal2004: -|br| - Levis, S., Bonan, G.B., Vertenstein, M., and Oleson, K.W. 2004. The community land model’s dynamic global vegetation model (CLM-DGVM): technical description and user’s guide. NCAR Technical Note @@ -1487,16 +1117,12 @@ Colorado. 50 pp. .. _Levisetal2009: -|br| - Levis, S., Thornton, P., Bonan, G., and Kucharik, C. 2009. Modeling land use and land management with the Community Land Model. iLeaps newsletter, No. 7. .. _Levisetal2012: -|br| - Levis, S., Bonan, G., Kluzek, E., Thornton, P., Jones, A., Sacks, W., and Kucharik, C 2012. Interactive crop management in the Community Earth System Model (CESM1): Seasonal influences on land-atmosphere fluxes. J. @@ -1504,32 +1130,24 @@ Climate 25: 4839-4859. DOI:10.1175/JCLI-D-11-00446.1. .. _Levisetal2016: -|br| - Levis, S., Badger, A., Drewniak, B., Nevison, C., Ren, X. 2016. CLMcrop yields and water requirements: avoided impacts by choosing RCP 4.5 over 8.5. Climatic Change. DOI:10.1007/s10584-016-1654-9. .. _Lietal2000: -|br| - Li, C., Aber, J., Stange, F., Butterbach-Bahl, K. and Papen, H. 2000. A process-oriented model of N2O and NO emissions from forest soils: 1. Model development. J. Geophys. Res. 105(D4):4369-4384. .. _Lietal2012a: -|br| - Li, F., Zeng, X.-D., and Levis, S. 2012a. A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model. Biogeosciences 9:2761-2780. .. _Lietal2012b: -|br| - Li, F., Zeng, X. D., and Levis, S. 2012b. Corrigendum to “A process-based fire parameterization of intermediate complexity in a Dynamic Global Vegetation Model†published in Biogeosciences, 9, @@ -1537,24 +1155,18 @@ Dynamic Global Vegetation Model†published in Biogeosciences, 9, .. _Lietal2013a: -|br| - Li, F., Levis, S., and Ward, D. S. 2013a. Quantifying the role of fire in the Earth system – Part 1: Improved global fire modeling in the Community Earth System Model (CESM1). Biogeosciences 10:2293-2314. .. _LiLawrence2017: -|br| - Li, F., and Lawrence, D. 2017. Role of fire in the global land water budget during the 20th century through changing ecosystems. J. Clim. 30: 1894-1908. .. _Lietal2013b: -|br| - Li, H.-Y., Huang, M., Tesfa, T., Ke, Y., Sun, Y., Liu, Y., and Leung, L. R. 2013b. A subbasin-based framework to represent land surface processes in an Earth System Model, Geosci. Model Dev. Discuss. 6:2699-2730. @@ -1562,8 +1174,6 @@ DOI:10.5194/gmdd-6-2699-2013. .. _Lietal2011: -|br| - Li, H., Huang, M., Wigmosta, M.S., Ke, Y., Coleman, A.M., Leung, L.R., Wang, A., and Ricciuto, D.M. 2011. Evaluating runoff simulations from the Community Land Model 4.0 using observations from flux towers and a @@ -1572,8 +1182,6 @@ DOI:10.1029/2011JD016276. .. _Lietal2015a: -|br| - Li, H., L. Leung, A. Getirana, M. Huang, H. Wu, Y. Xu, J. Guo and N. Voisin. 2015a. Evaluating global streamflow simulations by a physically-based routing model coupled with the Community Land Model, @@ -1581,8 +1189,6 @@ J. of Hydromet., 16(2):948-971, doi: 10.1175/JHM-D-14-0079.1 .. _Lietal2015b: -|br| - Li, H., L. Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang. 2015. Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. @@ -1590,68 +1196,50 @@ Earth Syst., 7, doi:10.1002/2015MS000471. .. _Liangetal1994: -|br| - Liang, X., Lettenmaier, D.P., Wood, E.F., and Burges, S.J. 1994. A simple hydrologically based model of land surface water and energy fluxes for GSMs. J. Geophys. Res. 99(D7):14,415–14,428. .. _lichstein2011: -|br| - Lichstein, J.W. and S.W. Pacala, 2011. Local diversity in heterogeneous landscapes: quantitative assessment with a height-structured forest metacommunity model`. Theoretical Ecology 4.2, pp. 269-281. .. _LipscombSacks2012: -|br| - Lipscomb, W., and Sacks, W. 2012. The CESM land ice model documentation and user’s guide. 46 pp. [Available online at http://www.cesm.ucar.edu/models/cesm1.1/cism/]. .. _lischke2006: -|br| - Lischke, H. et al., 2006. TreeMig: a forest-landscape model for simulating spatio-temporal patterns from stand to landscape scale. Ecological Modelling 199.4, pp. 409-420. 41 .. _LloydTaylor1994: -|br| - Lloyd, J. and Taylor, J.A., 1994. On the temperature dependence of soil respiration. Functional Ecology, 8: 315-323. .. _Lloydetal2010: -|br| - Lloyd, J., et al. 2010. Optimisation of photosynthetic carbon gain and within-canopy gradients of associated foliar traits for Amazon forest trees. Biogeosci. 7:1833-1859. DOI:10.5194/bg-7-1833-2010. .. _Lobelletal2006: -|br| - Lobell, D.B., Bala, G., and Duffy, P.B. 2006. Biogeophysical impacts of cropland management changes on climate. Geophys. Res. Lett. 33:L06708. DOI:10.1029/2005GL025492. .. _Lombardozzietal2015: -|br| - Lombardozzi, D.L., Bonan, G.B., Smith, N.G., Dukes, J.S. 2015. Temperature acclimation of photosynthesis and respiration: A key uncertainty in the carbon cycle-climate feedback. Geophys. Res. Lett. 42:8624-8631. .. _Lovelandetal2000: -|br| - Loveland, T.R., Reed, B.C., Brown, J.F., Ohlen, D.O., Zhu, Z., Yang, L., and Merchant, J.W. 2000. Development of a global land cover characteristics database and IGBP DISCover from 1 km AVHRR data. Int. J. @@ -1659,31 +1247,23 @@ Remote Sens. 21:1303-1330. .. _Lowe1977: -|br| - Lowe, P.R. 1977. An approximating polynomial for the computation of saturation vapor pressure. J. Appl. Meteor. 16:100-103. .. _Luoetal2006: -|br| - Luo, Y., Hui, D., and Zhang, D. 2006. Elevated CO2 stimulates net accumulations of carbon and nitrogen in land ecosystems: a meta-analysis. Ecology 87:53-63. .. _Magilletal1997: -|br| - Magill, A.H. et al., 1997. Biogeochemical response of forest ecosystems to simulated chronic nitrogen deposition. Ecological Applications, 7: 402-415. .. _Mahowaldetal2006: -|br| - Mahowald, N.M., Muhs, D.R., Levis, S., Rasch, P.J., Yoshioka, M., Zender, C.S., and Luo, C. 2006. Change in atmospheric mineral aerosols in response to climate: last glacial period, pre-industrial, modern and @@ -1692,23 +1272,17 @@ DOI:10.1029/2005JD006653. .. _Makela2002: -|br| - Makela, A. 2002. Derivation of stem taper from the pipe model theory in a carbon balance framework. Tree Phys. 22:891-905. .. _Maoetal2012: -|br| - Mao, J., Thornton, P.E., Shi, X., Zhao, M., and Post, W.M. 2012. Remote sensing evaluation of CLM4 GPP for the period 2000 to 2009. J. Climate 25:5327-5342. .. _Maoetal2013: -|br| - Mao, J., Shi, X., Thornton, P.E., Hoffman, F.M., Zhu, Z., and Ranga B. Myneni, R.B. 2013. Global latitudinal-asymmetric vegetation growth trends and their driving mechanisms: 1982-2009. Remote Sensing @@ -1716,30 +1290,22 @@ trends and their driving mechanisms: 1982-2009. Remote Sensing .. _Martinetal1980: -|br| - Martin, J.P., Haider, K. and Kassim, G., 1980. Biodegradation and stabilization after 2 years of specific crop, lignin, and polysaccharide carbons in soils. Soil Science Society of America Journal 44:1250-1255. .. _Maryetal1993: -|br| - Mary, B., Fresneau, C., Morel, J.L. and Mariotti, A., 1993. C and N cycling during decomposition of root mucilage, roots and glucose in soil. Soil Biology and Biochemistry 25:1005-1014. .. _Mcdowelletal2013: -|br| - McDowell, N.G. et al., 2013. Evaluating theories of drought-induced vegetation mortality using a multimodel experiment framework. New Phytologist 200.2, pp. 304-321. .. _McGuireetal1992: -|br| - McGuire, A.D., Melillo, J.M., Joyce, L.A., Kicklighter, D.W., Grace, A.L., Moore III, B., and Vorosmarty, C.J. 1992. Interactions between carbon and nitrogen dynamics in estimating net primary productivity for @@ -1748,8 +1314,6 @@ potential vegetation in North America. Global Biogeochem. Cycles .. _Medlynetal2011: -|br| - Medlyn, B.E., Duursma, R.A., Eamus, D., Ellsworth, D.S., Prentice, I.C., Barton, C.V.M., Crous, K.Y., De Angelis, P., Freeman, M., and Wingate, L., 2011. Reconciling the optimal and empirical approaches to @@ -1758,67 +1322,49 @@ doi:10.1111/j.1365-2486.2010.02375.x .. _MelzerOLeary1987: -|br| - Melzer, E., and O’Leary, M.H. 1987. Anapleurotic CO2 Fixation by Phosphoenolpyruvate Carboxylase in C3 Plants. Plant. Physiol. 84:58. .. _Milleretal1994: -|br| - Miller, J.R., Russell, G.L., and Caliri, G. 1994. Continental-scale river flow in climate models. J. Climate 7:914-928. .. _MillingtonQuirk1961: -|br| - Millington, R. and Quirk, J.P., 1961. Permeability of Porous Solids. Transactions of the Faraday Society 57:1200-1207. .. _Mironovetal2010: -|br| - Mironov, D. et al., 2010. Implementation of the lake parameterisation scheme FLake into the numerical weather prediction model COSMO. Boreal Environment Research 15:218-230. .. _MitchellJones2005: -|br| - Mitchell, T.D., and Jones, P.D. 2005. An improved method of constructing a database of monthly climate observations and associated high-resolution grids. Int. J. Climatol. 25:693-712. .. _Moldrupetal2003: -|br| - Moldrup, P. et al. 2003. Modeling diffusion and reaction in soils: X. A unifying model for solute and gas diffusivity in unsaturated soil. Soil Science 168:321-337. .. _mc_2001: -|br| - Moorcroft, P.R., G.C. Hurtt, and S.W. Pacala, 2001. A method for scaling vegetation dynamics: the ecosystem demography model ED. Ecological monographs 71.4, pp. 557-586. .. _Mynenietal2002: -|br| - Myneni, R.B., et al. 2002. Global products of vegetation leaf area and fraction absorbed PAR from year one of MODIS data. Remote Sens. Environ. 83:214-231. .. _Neffetal2005: -|br| - Neff, J.C., Harden, J.W. and Gleixner, G. 2005. Fire effects on soil organic matter content, composition, and nutrients in boreal interior Alaska. Canadian Journal of Forest Research-Revue Canadienne De @@ -1826,8 +1372,6 @@ Recherche Forestiere 35:2178-2187. .. _Neitschetal2005: -|br| - Neitsch, S.L., Arnold, J.G., Kiniry, J.R., and Williams J.R. 2005. Soil and Water Assessment Tool, Theoretical Documentation: Version 2005. Temple, TX. USDA Agricultural Research Service and Texas A&M Blackland @@ -1835,23 +1379,17 @@ Research Center. .. _NegronJuarezetal2015: -|br| - Negron-Juarez, R. Koven, C.D., Riley, W.J., Knox, R.G., Chambers, J.Q. 2015. Environmental Research Letters 10:064017. DOI:10.1088/1748-9326/10/6/064017. .. _NemaniRunning1996: -|br| - Nemani, R.R., and Running, S.W. 1996. Implementation of a hierarchical global vegetation classification in ecosystem function models. J. Veg. Sci. 7:337-346. .. _Niinemetstal1998: -|br| - Niinemets, U., Kull, O., and Tenhunen, J.D. 1998. An analysis of light effects on foliar morphology, physiology, and light interception in temperate deciduous woody species of contrasting shade tolerance. Tree @@ -1859,16 +1397,12 @@ Phys. 18:681-696. .. _Niuetal2005: -|br| - Niu, G.-Y., Yang, Z.-L., Dickinson, R.E., and Gulden, L.E. 2005. A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models. J. Geophys. Res. 110:D21106. DOI:10.1029/2005JD006111. .. _NiuYang2006: -|br| - Niu, G.-Y., and Yang, Z.-L. 2006. Effects of frozen soil on snowmelt runoff and soil water storage at a continental scale. J. Hydrometeor. 7:937-952. @@ -1884,29 +1418,21 @@ basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674. .. _norman1979: -|br| - Norman, J.M., 1979. Modeling the complete crop canopy. Modification of the Aerial Environment of Crops, pp. 249-280. .. _Oikawaetal2005: -|br| - Oikawa, S., Hikosaka, K. and Hirose, T., 2005. Dynamics of leaf area and nitrogen in the canopy of an annual herb, Xanthium canadense. Oecologia, 143: 517-526. .. _Oke1987: -|br| - Oke, T. 1987. Boundary Layer Climates (2:math:`{}^{nd}` edition). Routledge, London and New York. .. _OlesonBonan2000: -|br| - Oleson, K.W., and Bonan, G.B. 2000. The effects of remotely-sensed plant functional type and leaf area index on simulations of boreal forest surface fluxes by the NCAR land surface model. J. Hydrometeor. @@ -1914,8 +1440,6 @@ surface fluxes by the NCAR land surface model. J. Hydrometeor. .. _Olesonetal2004: -|br| - Oleson, K.W., Dai, Y., Bonan, G., Bosilovich, M., Dickinson, R., Dirmeyer, P., Hoffman, F., Houser, P., Levis, S., Niu, G.-Y., Thornton, P., Vertenstein, M., Yang, Z.-L., and Zeng. X. 2004. Technical @@ -1925,8 +1449,6 @@ Colorado. 173 pp. .. _Olesonetal2008a: -|br| - Oleson, K.W., Niu, G.-Y., Yang, Z.-L., Lawrence, D.M., Thornton, P.E., Lawrence, P.J., Stöckli, R., Dickinson, R.E., Bonan, G.B., Levis, S., Dai, A., and Qian, T. 2008a. Improvements to the Community Land Model @@ -1935,8 +1457,6 @@ DOI:10.1029/2007JG000563. .. _Olesonetal2008b: -|br| - Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Grimmond, C.S.B. 2008b. An urban parameterization for a global climate model. 1. Formulation and evaluation for two cities. J. Appl. Meteor. Clim. @@ -1944,8 +1464,6 @@ Formulation and evaluation for two cities. J. Appl. Meteor. Clim. .. _Olesonetal2008c: -|br| - Oleson, K.W., Bonan, G.B., Feddema, J., and Vertenstein, M. 2008c. An urban parameterization for a global climate model. 2. Sensitivity to input parameters and the simulated urban heat island in offline @@ -1953,16 +1471,12 @@ simulations. J. Appl. Meteor. Clim. 47:1061-1076. .. _Olesonetal2010a: -|br| - Oleson, K.W., et al. 2010a. Technical description of version 4.0 of the Community Land model (CLM). NCAR Technical Note NCAR/TN-478+STR, National Center for Atmospheric Research, Boulder, CO, 257 pp. .. _Olesonetal2010b: -|br| - Oleson, K.W., Bonan, G.B., Feddema, J., Vertenstein, M., and Kluzek, E. 2010b. Technical description of an urban parameterization for the Community Land Model (CLMU). NCAR Technical Note NCAR/TN-480+STR, @@ -1970,31 +1484,23 @@ National Center for Atmospheric Research, Boulder, CO, 169 pp. .. _Olesonetal2013: -|br| - Oleson, K.W., et al. 2013. Technical description of version 4.5 of the Community Land Model (CLM). NCAR Technical Note NCAR/TN-503+STR, National Center for Atmospheric Research, Boulder, CO, 420 pp. .. _OlesonFeddema2018: -|br| - Oleson, K.W., and Feddema, J. 2018. Parameterization and surface data improvements and new capabilities for the Community Land Model Urban (CLMU). JAMES, submitted. .. _Olson1963: -|br| - Olson, J.S., 1963. Energy storage and the balance of producers and decomposers in ecological systems. Ecology 44:322-331. .. _Olsonetal2001: -|br| - Olson, D.M., Dinerstein, E., Wikramanayake, E.D., Burgess, N.D., Powell, G.V.N., Underwood, E.C., D’Amico, J.A., Itoua, I., Strand, H. E., Morrison, J. C., Loucks, C. J., Allnutt, T. F., Ricketts, T. H., Kura, @@ -2004,23 +1510,17 @@ Bioscience, 51, 933–938. .. _OrchardCook1983: -|br| - Orchard, V.A. and Cook, F.J., 1983. Relationship between soil respiration and soil moisture. Soil Biology and Biochemistry, 15: 447-453. .. _Owen1964: -|br| - Owen, P.R. 1964. Saltation of uniform grains in air. J. Fluid Mech\ *.* 20:225-242. .. _Ozdoganetal2010: -|br| - Ozdogan, M., Rodell, M., Beaudoing, H.K., and Toll, D.L. 2010. Simulating the effects of irrigation over the United States in a land surface model based on satellite-derived agricultural data. Journal of @@ -2028,122 +1528,88 @@ Hydrometeorology 11:171-184. .. _Pageetal2002: -|br| - Page, S.E., Siegert, F., Rieley, J.O., Boehm, H-D.V., Jaya, A., and Limin, S. 2002. The amount of carbon released from peat and forest fires in Indonesia in 1997. Nature 420:61-65. .. _PanofskyDutton1984: -|br| - Panofsky, H.A., and Dutton, J.A. 1984. Atmospheric Turbulence: Models and Methods for Engineering Applications. John Wiley and Sons, New York. .. _Partonetal1988: -|br| - Parton, W., Stewart, J. and Cole, C., 1988. Dynamics of C, N, P And S in Grassland Soils - A Model. Biogeochemistry 5:109-131. .. _Partonetal1993: -|br| - Parton, W.J., et al. 1993. Observations and modeling of biomass and soil organic matter dynamics for the grassland biome worlwide. Global Biogeochemical Cycles 7:785-809. .. _Partonetal1996: -|br| - Parton, W. et al. 1996. Generalized model for N2 and N2O production from nitrification and denitrification. Global Biogeochemical Cycles 10:401-412. .. _Partonetal2001: -|br| - Parton, W.J. et al. 2001. Generalized model for NOx and N2O emissions from soils. J. Geophys. Res. 106(D15):17403-17419. .. _Paterson1994: -|br| - Paterson, W.S.B., 1994. The Physics of Glaciers. Elsevier Science Inc., New York, 480 pp. .. _Pelletieretal2016: -|br| - Pelletier, J. D., P. D. Broxton, P. Hazenberg, X. Zeng, P. A. Troch, G. Y. Niu, Z. Williams, M. A. Brunke, and D. Gochis, 2016: A gridded global data set of soil, intact regolith, and sedimentary deposit thicknesses for regional and global land surface modeling. J. Adv. Mod. Earth Sys. 8:41-65. .. _peterson1986: -|br| - Peterson, D.L. and K.C. Ryan, 1986. Modeling postfire conifer mortality for long-range planning. Environmental Management 10.6, pp. 797-808. .. _Petrescuetal2010: -|br| - Petrescu, A.M.R. et al. 2010. Modeling regional to global CH4 emissions of boreal and arctic wetlands. Global Biogeochemical Cycles, 24(GB4009). .. _pfeiffer2013: -|br| - Pfeiffer, M., A. Spessa, and J.O. Kaplan, 2013. A model for global biomass burning in preindustrial time: LPJ-LMfire (v1. 0). Geoscientific Model Development 6.3, pp. 643-685. .. _Philip1957: -|br| - Philip, J.R. 1957. Evaporation, and moisture and heat fields in the soil. J. Meteor. 14:354-366. .. _Piaoetal2012: -|br| - Piao, S.L., et al. 2012. The carbon budget of terrestrial ecosystems in East Asia over the last two decades. Biogeosciences 9:3571-3586. .. _Pivovarov1972: -|br| - Pivovarov, A.A., 1972. Thermal Conditions in Freezing Lakes and Reservoirs. John Wiley, New York. .. _Pollmeretal1979: -|br| - Pollmer, W.G., Eberhard, D., Klein, D., and Dhillon, B.S. 1979. Genetic control of nitrogen uptake and translocation in maize. Crop Sci. 19:82-86. .. _Pomeroyetal1998: -|br| - Pomeroy, J. W., D. M. Gray, K. R. Shook, B. Toth, R. L. H. Essery, A. Pietroniro, and N. Hedstrom. 1998. An evaluation of snow accumulation and ablation processes for land surface modelling. Hydrol. Process. 12:2339–2367. .. _Portmannetal2010: -|br| - Portmann, F.T., Siebert, S., and Döll, P. 2010. MIRCA2000 - Global monthly irrigated and rainfed crop areas around the year 2000: A new high-resolution data set for agricultural and hydrological modeling. @@ -2151,24 +1617,18 @@ Global Biogeochem. Cycles. 24, GB1011. DOI:10.1029/2008GB003435. .. _Pressetal1992: -|br| - Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P. 1992. Numerical Recipes in FORTRAN: The Art of Scientific Computing. Cambridge University Press, New York. .. _Prigentetal2007: -|br| - Prigent, C., Papa, F., Aires, F., Rossow, W.B. and Matthews, E. 2007. Global inundation dynamics inferred from multiple satellite observations, 1993-2000. J. Geophys. Res. 112(D12). .. _Pritchardetal2008: -|br| - Pritchard, M.S., Bush, A.B.G., and Marshall, S.J. 2008. Neglecting ice-atmosphere interactions underestimates ice sheet melt in millennial-scale deglaciation simulations. Geophys. Res. Lett. ** @@ -2176,28 +1636,20 @@ millennial-scale deglaciation simulations. Geophys. Res. Lett. ** .. _purves2008: -|br| - Purves, D.W. et al., 2008. Predicting and understanding forest dynamics using a simple tractable model. Proceedings of the National Academy of Sciences 105.44, pp. 17018-17022. .. _Qianetal2006: -|br| - Qian, T et al., 2006. Simulation of global land surface conditions from 1948 to 2004: Part I: Forcing data and evaluations. J. Hydrometeorology 7, pp. 953-975. .. _RamankuttyFoley1998: -|br| - Ramankutty, N., and Foley, J. A., 1998. Characterizing patterns of global land use: An analysis of global croplands data. Global Biogeochemical Cycles, 12, 667-685. .. _Ramankuttyetal2008: -|br| - Ramankutty, N., Evan, A., Monfreda, C., and Foley, J.A. 2008. Farming the Planet. Part 1: The Geographic Distribution of Global Agricultural Lands in the Year 2000. Global Biogeochem. Cycles. 22:GB1003. @@ -2205,8 +1657,6 @@ DOI:10.1029/2007GB002952. .. _Randlettetal1996: -|br| - Randlett, D.L., Zak, D.R., Pregitzer, K.S., and Curtis, P.S. 1996. Elevated atmospheric carbon dioxide and leaf litter chemistry: Influences on microbial respiration and net nitrogen mineralization. @@ -2214,8 +1664,6 @@ Soil Sci. Soc. Am. J. 60:1571-1577. .. _Rastetteretal1991: -|br| - Rastetter, E.B., Ryan, M.G., Shaver, G.R., Melillo, J.M., Nadelhoffer, K.J., Hobbie, J.E., and Aber, J.D. 1991. A general biogeochemical model describing the responses of the C and N cycles in terrestrial ecosystems @@ -2223,16 +1671,12 @@ to changes in CO2, climate and N deposition. Tree Phys. 9:101-126. .. _Rastneretal2012: -|br| - Rastner, P., Bolch, T., Mölg, N., Machguth, H., and Paul, F., 2012. The first complete glacier inventory for the whole of Greenland, The Cryosphere Discuss., 6, 2399-2436, 10.5194/tcd-6-2399-2012. .. _Rileyetal2011a: -|br| - Riley, W. J., Z. M. Subin, D. M. Lawrence, S. C. Swenson, M. S. Torn, L. Meng, N. Mahowald, and P. Hess, 2011a. Barriers to predicting global terrestrial methane fluxes: Analyses using a methane biogeochemistry @@ -2241,42 +1685,30 @@ DOI:10.5194/bg-8-1925-2011. .. _Rileyetal2011b: -|br| - Riley, W.J. et al. 2011b. CLM4Me, a Methane Biogeochemistry Model Integrated in CESM, Land and Biogeochemistry Model Working Group Meeting, Boulder, CO. .. _Roeschetal2001: -|br| - Roesch, A., M. Wild, H. Gilgen, and A. Ohmura. 2001. A new snow cover fraction parametrization for the ECHAM4 GCM, Clim. Dyn., 17:933–946. .. _Rogers2014: -|br| - Rogers, A., 2014: The use and misuse of Vcmax in Earth system models. Photosynt. Res., 119:1-15. .. _Rogersetal2017: -|br| - Rogers, A., B. E. Medlyn, J. S. Dukes, G. Bonan, S. Caemmerer, M. C. Dietze, J. Kattge, A. D. Leakey, L. M. Mercado, and U. Niinemets, 2017: A roadmap for improving the representation of photosynthesis in Earth system models. New Phytologist, 213:22-42. .. _Ryan1991: -|br| - Ryan, M. G. 1991. A simple method for estimating gross carbon budgets for vegetation in forest ecosystems. Tree Phys. 9:255-266. .. _RunningCoughlan1988: -|br| - Running, S.W. and Coughlan, J.C., 1988. A general model of forest ecosystem processes for regional applications. I. Hydrological balance, canopy gas exchange and primary production processes. Ecological @@ -2284,24 +1716,18 @@ Modelling, 42: 125-154. .. _Runningetal1989: -|br| - Running, S.W. et al., 1989. Mapping regional forest evapotranspiration and photosynthesis by coupling satellite data with ecosystem simlation. Ecology, 70: 1090-1101. .. _RunningGower1991: -|br| - Running, S.W. and Gower, S.T., 1991. FOREST BGC, A general model of forest ecosystem processes for regional applications. II. Dynamic carbon allocation and nitrogen budgets. Tree Physiology, 9: 147-160. .. _RunningHunt1993: -|br| - Running, S.W. and Hunt, E.R., Jr., 1993. Generalization of a forest ecosystem process model for other biomes, BIOME-BGC, and an applicationfor global-scale models. In: J.R. Ehleringer and C. Field @@ -2310,16 +1736,12 @@ Press, San Diego, CA, pp. 141-158. .. _Sacksetal2009: -|br| - Sacks, W. J., Cook, B. I., Buenning, N., Levis, S., and Helkowski, J. H. 2009. Effects of global irrigation on the near-surface climate. Climate Dyn., 33, 159–175. DOI:10.1007/s00382-008-0445-z. .. _Saggaretal1994: -|br| - Saggar, S., Tate, K.R., Feltham, C.W., Childs, C.W. and Parshotam, A., 1994. Carbon turnover in a range of allophanic soils amended with :math:`{}^{14}`\ C-labelled glucose. Soil Biology and Biochemistry, 26: @@ -2327,8 +1749,6 @@ Saggar, S., Tate, K.R., Feltham, C.W., Childs, C.W. and Parshotam, A., .. _Sakaguchietal2009: -|br| - Sakaguchi, K., and Zeng, X. 2009. Effects of soil wetness, plant litter, and under-canopy atmospheric stability on ground evaporation in the Community Land Model (CLM3.5). J. Geophys. Res. 114:D01107. @@ -2336,14 +1756,10 @@ DOI:10.1029/2008JD010834. .. _sato2007: -|br| - Sato, H., A. Itoh, and T. Kohyama, 2007. SEIB-DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach. Ecological Modelling 200.3, pp. 2793307. .. _Schaafetal2002: -|br| - Schaaf, C.B., Gao, F., Strahler, A.H., Lucht, W., Li, X., Tsang, T., Strugnell, N.C., Zhang, X., Jin, Y., and Muller, J.-P. 2002. First operational BRDF, albedo nadir reflectance products from MODIS. Remote @@ -2351,54 +1767,40 @@ Sens. Environ. 83:135-148. .. _Schlesinger1997: -|br| - Schlesinger, W.H., 1997. Biogeochemistry: an analysis of global change. Academic Press, London, 588 pp. .. _SchnellKing1996: -|br| - Schnell, S. and King, G.M., 1996. Responses of methanotrophic activity in soils and cultures to water stress. Applied and Environmental Microbiology 62:3203-3209. .. _Segers1998: -|br| - Segers, R., 1998. Methane production and methane consumption: a review of processes underlying wetland methane fluxes. Biogeochemistry 41:23-51. .. _Sellers1985: -|br| - Sellers, P.J. 1985. Canopy reflectance, photosynthesis and transpiration. Int. J. Remote Sens. 6:1335-1372. .. _Sellersetal1986: -|br| - Sellers, P.J., Mintz, Y., Sud, Y.C., and Dalcher, A. 1986. A simple biosphere model (SiB) for use within general circulation models. J. Atmos. Sci. 43:505-531. .. _Sellersetal1988: -|br| - Sellers, P.J., Hall, F.G., Asrar, G., Strebel, D.E., and Murphy, R.E. 1988. The First ISLSCP Field Experiment (FIFE). Bull. Amer. Meteor. Soc. 69:22-27. .. _Sellersetal1992: -|br| - Sellers, P.J., Berry, J.A., Collatz, G.J., Field, C.B., and Hall, F.G. 1992. Canopy reflectance, photosynthesis, and transpiration. III. A reanalysis using improved leaf models and a new canopy integration @@ -2406,16 +1808,12 @@ scheme. Remote Sens. Environ. 42:187-216. .. _Sellersetal1995: -|br| - Sellers, P.J., et al. 1995. The Boreal Ecosystem-Atmosphere Study (BOREAS): An overview and early results from the 1994 field year. Bull. Amer. Meteor. Soc. 76:1549-1577. .. _Sellersetal1996: -|br| - Sellers, P.J., Randall, D.A., Collatz, G.J., Berry, J.A., Field, C.B., Dazlich, D.A., Zhang, C., Collelo, G.D., and Bounoua, L. 1996. A revised land surface parameterization (SiB2) for atmospheric GCMs. Part I: Model @@ -2423,14 +1821,10 @@ formulation. J. Climate 9:676-705. .. _sellers1996: -|br| - Sellers, Piers J et al. (1996). A revised land surface parameterization (SiB2) for atmospheric GCMs. Part II: The generation of global fields of terrestrial biophysical parameters from satellite data. Journal of climate 9.4, pp. 706-737. .. _Shietal2013: -|br| - Shi, X., Mao, J., Thornton, P.E., and Huang, M. 2013. Spatiotemporal patterns of evapotranspiration in response to multiple environmental factors simulated by the Community Land Model. Environ. Res. Lett. @@ -2438,65 +1832,47 @@ factors simulated by the Community Land Model. Environ. Res. Lett. .. _Shietal2016: -|br| - Shi, M., J. B. Fisher, E. R. Brzostek, and R. P. Phillips, 2016: Carbon cost of plant nitrogen acquisition: global carbon cycle impact from an improved plant nitrogen cycle in the Community Land Model. Glob. Change Biol., 22:1299-1314. .. _Shiklomanov2000: -|br| - Shiklomanov, I.A. 2000. Appraisal and assessment of world water resources. Water International 25:11-32. .. _Siebertetal2005: -|br| - Siebert, S., Döll, P., Hoogeveen, J., Faures, J.M., Frenken, K., Feick, S., 2005. Development and validation of the global map of irrigation areas. Hydrol Earth Syst Sc 9:535–547 .. _Simardetal2011: -|br| - Simard, M., Pinto, N., Fisher, J.B., and Baccini, A. (2011), Mapping forest canopy height globally with spaceborne lidar. J. Geophys. Res., 116, G04021, doi:10.1029/2011JG001708. .. _Simpsonetal1983: -|br| - Simpson, R.J., Lambers, H., and Dalling, M.J. 1983. Nitrogen redistribution during grain growth in wheat (Triticum avestivum L.). Plant Physiol. 71:7-14. .. _sitch2003: -|br| - Sitch, S et al. (2003). Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model. Global Change Biology 9.2, pp. 161-185. .. _Sivak2013: -|br| - Sivak, M. 2013. Air conditioning versus heating: climate control is more energy demanding in Minneapolis than in Miami. Environ. Res. Lett., 8, doi:10.1088/1748-9326/8/1/014050. .. _smith2001: -|br| - Smith, B., I.C. Prentice, and M.T. Sykes, 2001. Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space. Global Ecology and Biogeography 10.6, pp. 621-637. .. _Smithetal2005: -|br| - Smith, A.M.S., Wooster, M.J., Drake, N.A., Dipotso, F.M. and Perry, G.L.W., 2005. Fire in African savanna: Testing the impact of incomplete combustion on pyrogenic emissions estimates. Ecological Applications, @@ -2504,38 +1880,28 @@ combustion on pyrogenic emissions estimates. Ecological Applications, .. _smith2007: -|br| - Smith, A.M. and M. Stitt, 2007. Coordination of carbon supply and plant growth. Plant, cell & environment 30.9, pp. 1126-1149. .. _Sollins1982: -|br| - Sollins, P., 1982. Input and decay of coarse woody debris in coniferous stands in western Oregon and Washington. Canadian Journal of Forest Research, 12: 18-28. .. _SonGower1991: -|br| - Son, Y. and Gower, S.T., 1991. Aboveground nitrogen and phosphorus use by five plantation-grown trees with different leaf longevities. Biogeochemistry, 14: 167-191. .. _Sorensen1981: -|br| - Sørensen, L.H., 1981. Carbon-nitrogen relationships during the humification of cellulose in soils containing different amounts of clay. Soil Biology and Biochemistry, 13: 313-321. .. _Sperryetal1998: -|br| - Sperry, J.S., Adler, F.R., Campbell, G.S. and Comstock, J.P. 1998. Limitation of plant water use by rhizosphere and xylem conductance: results from a model. Plant, Cell & Environment, 21: 347–359. @@ -2543,16 +1909,12 @@ doi:10.1046/j.1365-3040.1998.00287.x .. _SperryandLove2015: -|br| - Sperry, J.S. and Love, D.M. 2015. What plant hydraulics can tell us about responses to climate-change droughts. New Phytol, 207: 14–27. doi:10.1111/nph.13354 .. _Sprugeletal1995: -|br| - Sprugel, D.G., Ryan, M.G., Brooks, J.R., Vogt, K.A., and Martin, T.A. 1995. Respiration from the organ level to stand level. pp. 255-299. In: W. K. Smith and T. M. Hinkley (editors) Resource Physiology of Conifers. @@ -2560,23 +1922,17 @@ Academic Press, San Diego,CA. .. _StaufferAharony1994: -|br| - Stauffer, D., and Aharony, A. 1994. Introduction to Percolation Theory. Taylor and Francis, London. .. _Stilletal2003: -|br| - Still, C.J., Berry, J.A., Collatz, G.J., and DeFries, R.S. 2003. Global distribution of C3 and C4 vegetation: carbon cycle implications. Global Biogeochem. Cycles 17:1006. DOI:10.1029/2001GB001807. .. _Stocklietal2008: -|br| - Stöckli, R., Lawrence, D.M., Niu, G.-Y., Oleson, K.W., Thornton, P.E., Yang, Z.-L., Bonan, G.B., Denning, A.S., and Running, S.W. 2008. Use of FLUXNET in the Community Land Model development. J. Geophys. Res. @@ -2584,39 +1940,29 @@ FLUXNET in the Community Land Model development. J. Geophys. Res. .. _Stracketal2006: -|br| - Strack, M., Kellner, E. and Waddington, J.M., 2006. Effect of entrapped gas on peatland surface level fluctuations. Hydrological Processes 20:3611-3622. .. _Strahleretal1999: -|br| - Strahler, A.H., Muchoney, D., Borak, J., Friedl, M., Gopal, S., Lambin, E., and Moody. A. 1999. MODIS Land Cover Product: Algorithm Theoretical Basis Document (Version 5.0). Boston University, Boston. .. _Stull1988: -|br| - Stull, R.B. 1988. An Introduction to Boundary Layer Meteorology. Kluwer Academic Publishers, Dordrecht. .. _Subinetal2012a: -|br| - Subin, Z.M., Riley, W.J. and Mironov, D. 2012a. Improved lake model for climate simulations, J. Adv. Model. Earth Syst., 4, M02001. DOI:10.1029/2011MS000072. .. _Subinetal2012b: -|br| - Subin, Z.M., Murphy, L.N., Li, F., Bonfils, C. and Riley, W.J., 2012b. Boreal lakes moderate seasonal and diurnal temperature variation and perturb atmospheric circulation: analyses in the Community Earth System @@ -2624,32 +1970,24 @@ Model 1 (CESM1). Tellus A, North America, 64. .. _Sunetal2012: -|br| - Sun, Y., Gu, L., and Dickinson, R. E. 2012. A numerical issue in calculating the coupled carbon and water fluxes in a climate model, J. Geophys. Res., 117, D22103. DOI:10.1029/2012JD018059. .. _Swensonetal2012: -|br| - Swenson, S.C., Lawrence, D.M., and Lee, H. 2012. Improved Simulation of the Terrestrial Hydrological Cycle in Permafrost Regions by the Community Land Model. JAMES, 4, M08002. DOI:10.1029/2012MS000165. .. _SwensonLawrence2012: -|br| - Swenson, S.C. and Lawrence, D.M. 2012. A New Fractional Snow Covered Area Parameterization for the Community Land Model and its Effect on the Surface Energy Balance. JGR, 117, D21107. DOI:10.1029/2012JD018178. .. _SwensonLawrence2014: -|br| - Swenson, S.C., and D. M. Lawrence. 2014. Assessing a dry surface layer-based soil resistance parameterization for the Community Land Model using GRACE and FLUXNET-MTE data. JGR, 119, 10, 299–10,312, @@ -2657,23 +1995,17 @@ DOI:10.1002/2014JD022314. .. _SwensonLawrence2015: -|br| - Swenson, S.C., and D. M. Lawrence. 2015. A GRACE-based assessment of interannual groundwater dynamics in the Community Land Model. WRR, 51, doi:10.1002/2015WR017582. .. _TaWeiland1992: -|br| - Ta, C.T. and Weiland, R.T. 1992. Nitrogen partitioning in maize during ear development. Crop Sci. 32:443-451. .. _TangRiley2013: -|br| - Tang, J.Y. and Riley, W.J. 2013. A new top boundary condition for modeling surface diffusive exchange of a generic volatile tracer: Theoretical analysis and application to soil evaporation. Hydrol. Earth @@ -2681,30 +2013,22 @@ Syst. Sci. 17:873-893. .. _Tarnocaietal2011: -|br| - Tarnocai, C., Kettles, I. M., and Lacelle, B., 2011. Peatlands of Canada, Geological Survey of Canada, Open File 6561, CD-ROM. DOI:10.495/288786. .. _Tayloretal1989: -|br| - Taylor, B.R., Parkinson, D. and Parsons, W.F.J., 1989. Nitrogen and lignin content as predictors of litter decay rates: A microcosm test. Ecology, 70: 97-104. .. _Thomasetal2015: -|br| - Thomas R.Q., Brookshire E.N., Gerber S. 2015. Nitrogen limitation on land: how can it occur in Earth system models? Global Change Biology, 21, 1777-1793, doi:10.1111/gcb.12813. .. _Thonickeetal2001: -|br| - Thonicke, K., Venevsky, S., Sitch, S., and Cramer, W. 2001. The role of fire disturbance for global vegetation dynamics: coupling fire into a Dynamic Global Vegetation Model. Global Ecology and Biogeography @@ -2712,15 +2036,11 @@ Dynamic Global Vegetation Model. Global Ecology and Biogeography .. _thonickeetal2010: -|br| - Thonicke, K. et al., 2010. The influence of vegetation, fire spread and fire behaviour on biomass burning and trace gas emissions: results from a process-based model. Biogeosciences 7.6, pp. 1991-2011. .. _Thornton1998: -|br| - Thornton, P.E., 1998. Regional ecosystem simulation: combining surface- and satellite-based observations to study linkages between terrestrial energy and mass budgets. Ph.D. Thesis, The University of Montana, @@ -2728,8 +2048,6 @@ Missoula, 280 pp. .. _Thorntonetal2002: -|br| - Thornton, P.E., Law, B.E., Gholz, H.L., Clark, K.L., Falge, E., Ellsworth, D.S., Goldstein, A.H., Monson, R.K., Hollinger, D., Falk, M., Chen, J., and Sparks, J.P. 2002. Modeling and measuring the effects of @@ -2738,24 +2056,18 @@ needleleaf forests. Agric. For. Meteor. 113:185-222. .. _ThorntonRosenbloom2005: -|br| - Thornton, P.E., and Rosenbloom, N.A. 2005. Ecosystem model spin-up: estimating steady state conditions in a coupled terrestrial carbon and nitrogen cycle model. Ecological Modelling 189:25-48. .. _ThorntonZimmermann2007: -|br| - Thornton, P.E., and Zimmermann, N.E. 2007. An improved canopy integration scheme for a land surface model with prognostic canopy structure. J. Climate 20:3902-3923. .. _Thorntonetal2007: -|br| - Thornton, P.E., Lamarque, J.-F., Rosenbloom, N.A., and Mahowald, N.M. 2007. Influence of carbon-nitrogen cycle coupling on land model response to CO\ :sub:`2` fertilization and climate variability. Global @@ -2763,8 +2075,6 @@ Biogeochem. Cycles 21:GB4018. .. _Thorntonetal2009: -|br| - Thornton, P.E., Doney, S.C., Lindsay, K., Moore, J.K., Mahowald, N., Randerson, J.T., Fung, I., Lamarque, J.F., Feddema, J.J., and Lee, Y.H. 2009. Carbon-nitrogen interactions regulate climate-carbon cycle @@ -2773,8 +2083,6 @@ Biogeosci. 6:2099-2120. .. _Tianetal2010: -|br| - Tian, H. et al. 2010. Spatial and temporal patterns of CH4 and N2O fluxes in terrestrial ecosystems of North America during 1979-2008: application of a global biogeochemistry model. Biogeosciences @@ -2782,8 +2090,6 @@ application of a global biogeochemistry model. Biogeosciences .. _Toonetal1989: -|br| - Toon, O.B., McKay, C.P., Ackerman, T.P., and Santhanam, K. 1989. Rapid calculation of radiative heating rates and photodissociation rates in inhomogeneous multiple scattering atmospheres. J. Geophys. Res. @@ -2791,16 +2097,12 @@ inhomogeneous multiple scattering atmospheres. J. Geophys. Res. .. _Turetskyetal2002: -|br| - Turetsky, M.R., Wieder, R.K., Halsey, L.A., and Vitt, D.H. 2002. Current disturbance and the diminishing peatland carbon sink. Geophys. Res. Lett. 29:1526. DOI:10.1029/2001GL014000. .. _Turetskyetal2004: -|br| - Turetsky, M.R., Amiro, B.D., Bosch, E., and Bhatti, J.S. 2004. Historical burn area in western Canadian peatlands and its relationship to fire weather indices. Global Biogeochem. Cycles 18:GB4014. @@ -2808,37 +2110,27 @@ DOI:10.1029/2004GB002222. .. _Tyeetal2005: -|br| - Tye, A.M., et al. 2005. The fate of N-15 added to high Arctic tundra to mimic increased inputs of atmospheric nitrogen released from a melting snowpack. Global Change Biology 11:1640-1654. .. _Unlandetal1996: -|br| - Unland, H.E., Houser, P.R., Shuttleworth, W.J., and Yang, Z.-L. 1996. Surface flux measurement and modeling at a semi-arid Sonoran Desert site. Agric. For. Meteor. 82:119-153. .. _UNSTAT2005: -|br| - UNSTAT, 2005. National Accounts Main Aggregates Database, United Nations Statistics Division. .. _uriarte2009: -|br| - Uriarte, M. et al., 2009. Natural disturbance and human land use as determinants of tropical forest dynamics: results from a forest simulator. Ecological Monographs 79.3, pp. 423-443. .. _VallanoSparks2007: -|br| - Vallano, D.M. and Sparks, J.P. 2007. Quantifying foliar uptake of gaseous itrogen dioxide using enriched foliar :math:`\delta^{15}`\ N values. New Phytologist @@ -2846,8 +2138,6 @@ gaseous itrogen dioxide using enriched foliar .. _vanderWerfetal2010: -|br| - van der Werf, G.R., Randerson, J.T., Giglio, L., Collatz, G.J., Mu, M., Kasibhatla, S.P., Morton, D.C., DeFries, R.S., Jin, Y., van Leeuwen, T.T. 2010. Global fire emissions and the contribution of deforestation, @@ -2856,16 +2146,12 @@ Phys. 10:11707-11735. .. _van Veenetal1984: -|br| - van Veen, J.A., Ladd, J.N. and Frissel, M.J., 1984. Modelling C and N turnover through the microbial biomass in soil. Plant and Soil, 76: 257-274. .. _vanKampenhoutetal2017: -|br| - van Kampenhout, L., J.T.M. Lenaerts, W.H. Lipscomb, W.J. Sacks, D.M. Lawrence, A.G. Slater, and M.R. van den Broeke, 2017. Improving the Representation of Polar Snow and Firn in the @@ -2873,8 +2159,6 @@ Community Earth System Model. Journal of Advances in Modeling Earth Systems 9, n .. _VanTrichtetal2016: -|br| - Van Tricht, K., Lhermitte, S., Gorodetskaya, I.V. and van Lipzig, N.P.M., 2016. Improving satellite-retrieved surface radiative fluxes in polar regions using a smart sampling approach. The Cryosphere @@ -2882,8 +2166,6 @@ polar regions using a smart sampling approach. The Cryosphere .. _VanVuurenetal2006: -|br| - Van Vuuren, D.P., Lucas, P.S., and Hilderink, H.B.M., 2006. Downscaling drivers of global environmental change: enabling use of global SRES scenarios at the national and grid levels, Report 550025001, Netherlands @@ -2891,22 +2173,16 @@ Environmental Assessment Agency, 45 pp. .. _VanninenMakela2005: -|br| - Vanninen, P., and Makela, A. 2005. Carbon budget for Scots pine trees: effects of size, competition and site fertility on growth allocation and production. Tree Phys. 25:17-30. .. _venevsky2002: -|br| - Venevsky, S. et al., 2002. Simulating fire regimes in human-dominated ecosystems: Iberian Peninsula case study. Global Change Biology 8.10, pp. 984-998. .. _VerdinGreenlee1996: -|br| - Verdin, K. L., and S. K. Greenlee, 1996. Development of continental scale digital elevation models and extraction of hydrographic features, paper presented at the Third International Conference/Workshop on @@ -2915,16 +2191,12 @@ January, Natl. Cent. for Geogr. Inf. and Anal., Santa Barbara, Calif. .. _Vionnetetal2012: -|br| - Vionnet, V., E. Brun, S. Morin, A. Boone, S. Faroux, P. Le Moigne, E. Martin, and J.-M. Willemet. The Detailed Snowpack Scheme Crocus and Its Implementation in SURFEX v7.2. GMD 5, no. 3 (May 24, 2012): 773-91. https://doi.org/10.5194/gmd-5-773-2012. .. _Viovy2011: -|br| - Viovy, N. 2011. CRUNCEP dataset. [Description available at http://dods.extra.cea.fr/data/p529viov/cruncep/readme.htm. Data available at @@ -2932,23 +2204,17 @@ http://dods.extra.cea.fr/store/p529viov/cruncep/V4\_1901\_2011/]. .. _VitousekHowarth1991: -|br| - Vitousek, P.M., and Howarth, R.W. 1991. Nitrogen limitation on land and in the sea: How can it occur? Biogeochem. 13:87-115. .. _Walteretal2001: -|br| - Walter, B.P., Heimann, M. and Matthews, E., 2001. Modeling modern methane emissions from natural wetlands 1. Model description and results. J. Geophys. Res. 106(D24):34189-34206. .. _Waniaetal2009: -|br| - Wania, R., Ross, I. and Prentice, I.C. 2009. Integrating peatlands and permafrost into a dynamic global vegetation model: 2. Evaluation and sensitivity of vegetation and carbon cycle processes. Global Biogeochem. @@ -2956,8 +2222,6 @@ Cycles 23. .. _Waniaetal2010: -|br| - Wania, R., Ross, I. and Prentice, I.C. 2010. Implementation and evaluation of a new methane model within a dynamic global vegetation model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions @@ -2965,30 +2229,22 @@ model LPJ-WHyMe v1.3. Geoscientific Model Development Discussions .. _WangZeng2009: -|br| - Wang, A., and Zeng, X. 2009. Improving the treatment of vertical snow burial fraction over short vegetation in the NCAR CLM3. Adv. Atmos. Sci. 26:877-886. DOI:10.1007/s00376-009-8098-3. .. _weng2014: -|br| - Weng, E.S. et al., 2014. Scaling from individuals to ecosystems in an Earth System Model using a mathematically tractable model of height-structured competition for light. Biogeosciences Discussions 11.12, pp. 17757-17860. .. _Whiteetal1997: -|br| - White, M.A., Thornton, P.E., and Running, S.W. 1997. A continental phenology model for monitoring vegetation responses to interannual climatic variability. Global Biogeochem. Cycles 11:217-234. .. _Whiteetal2000: -|br| - White, M.A., Thornton, P.E., Running, S.W., and Nemani, R.R. 2000. Parameterization and sensitivity analysis of the Biome-BGC terrestrial ecosystem model: net primary production controls. Earth Interactions @@ -2996,8 +2252,6 @@ ecosystem model: net primary production controls. Earth Interactions .. _Wiederetal2015: -|br| - Wieder, W. R., Cleveland, C. C., Lawrence, D. M., and Bonan, G. B. 2015. Effects of model structural uncertainty on carbon cycle projections: biological nitrogen fixation as a case study. Environmental Research @@ -3005,8 +2259,6 @@ Letters, 10(4), 044016. .. _Williamsetal1996: -|br| - Williams, M., Rastetter, E.B., Fernandes, D.N., Goulden, M.L., Wofsy, S.C., Shaver, G.R., Melillo, J.M., Munger, J.W., Fan, S.M. and Nadelhoffer, K.J. 1996. Modelling the soil-plant-atmosphere @@ -3017,15 +2269,11 @@ doi:10.1111/j.1365-3040.1996.tb00456.x .. _WiscombeWarren1980: -|br| - Wiscombe, W.J., and Warren, S.G. 1980. A model for the spectral albedo of snow. I. Pure snow. J. Atmos. Sci. 37:2712-2733. .. _Woodetal1992: -|br| - Wood, E.F., Lettenmaier, D.P., and Zartarian, V.G. 1992. A land-surface hydrology parameterization with subgrid variability for general circulation models. J. Geophys. Res. 97(D3):2717–2728. @@ -3033,96 +2281,70 @@ DOI:10.1029/91JD01786. .. _WorldBank2004: -|br| - World Bank, 2004. World development indicators 2004, Oxford University Press, New York, 416 pp. .. _Wuetal2011: -|br| - Wu, H., J. S. Kimball, N. Mantua, and J. Stanford, 2011: Automated upscaling of river networks for macroscale hydrological modeling. Water Resour. Res., 47, W03517, doi:10.1029/2009WR008871. .. _Wuetal2012: -|br| - Wu, H., J. S. Kimball, H. Li, M. Huang, L. R. Leung, and R. F. Adler, 2012. A New Global River Network Database for Macroscale Hydrologic modeling, Water Resour. Res., 48, W09701, doi:10.1029/2012WR012313. .. _xiaodong2005: -|br| - Xiaodong, Y. and H.H. Shugart, 2005. FAREAST: a forest gap model to simulate dynamics and patterns of eastern Eurasian forests. Journal of Biogeography 32.9, pp. 1641-1658. .. _Xuetal2012: -|br| - Xu, C., R. Fisher, S. D. Wullschleger, C. J. Wilson, M. Cai, and N. G. McDowell, 2012: Toward a mechanistic modeling of nitrogen limitation on vegetation dynamics. PloS one, 7:e37914. .. _Yang1998: -|br| - Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and temperature model. Unpublished manuscript. .. _Zenderetal2003: -|br| - Zender, C.S., Bian, H., and Newman, D. 2003. Mineral dust entrainment and deposition (DEAD) model: Description and 1990s dust climatology. ** J. Geophys. Res\ *.* 108(D14):4416. DOI:10.1029/2002JD002775. .. _ZengDickinson1998: -|br| - Zeng, X., and Dickinson, R.E. 1998. Effect of surface sublayer on surface skin temperature and fluxes. J.Climate 11:537-550. .. _Zengetal1998: -|br| - Zeng, X., Zhao, M., and Dickinson, R.E. 1998. Intercomparison of bulk aerodynamic algorithms for the computation of sea surface fluxes using the TOGA COARE and TAO data. J. Climate 11:2628-2644. .. _Zeng2001: -|br| - Zeng, X. 2001. Global vegetation root distribution for land modeling. J. Hydrometeor. 2:525-530. .. _Zengetal2002: -|br| - Zeng, X., Shaikh, M., Dai, Y., Dickinson, R.E., and Myneni, R. 2002. Coupling of the Common Land Model to the NCAR Community Climate Model. J. Climate 15:1832-1854. .. _Zengetal2005: -|br| - Zeng, X., Dickinson, R.E., Barlage, M., Dai, Y., Wang, G., and Oleson, K. 2005. Treatment of under-canopy turbulence in land models. J. Climate 18:5086-5094. .. _ZengWang2007: -|br| - Zeng, X., and Wang, A. 2007. Consistent parameterization of roughness length and displacement height for sparse and dense canopies in land models. J. Hydrometeor. 8:730-737. @@ -3133,8 +2355,6 @@ water table. J. Hydrometeor. 10:308-319. .. _Zengetal2008: -|br| - Zeng, X., Zeng, X., and Barlage, M. 2008. Growing temperate shrubs over arid and semiarid regions in the Community Land Model - Dynamic Global Vegetation Model. Global Biogeochem. Cycles 22:GB3003. @@ -3142,8 +2362,6 @@ DOI:10.1029/2007GB003014. .. _Zhangetal2002: -|br| - Zhang, Y., Li, C.S., Trettin, C.C., Li, H. and Sun, G., 2002. An integrated model of soil, hydrology, and vegetation for carbon dynamics in wetland ecosystems. Global Biogeochemical Cycles 16. @@ -3151,8 +2369,6 @@ DOI:10.1029/2001GB001838. .. _Zhuangetal2004: -|br| - Zhuang, Q., et al. 2004. Methane fluxes between terrestrial ecosystems and the atmosphere at northern high latitudes during the past century: A retrospective analysis with a process-based biogeochemistry model. @@ -3160,8 +2376,6 @@ Global Biogeochemical Cycles 18. DOI:10.1029/2004GB002239. .. _Zilitinkevich1970: -|br| - Zilitinkevich, S.S. 1970. Dynamics of the Atmospheric Boundary Layer. Leningrad Gidrometeor. diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index c63e8a37b1..7b74bdf4ab 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -144,7 +144,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic of THESIS urban properties tool: -.. Figure:: ../../../images/tech_note/Urban/image3.gif +.. Figure:: ../../../images/tech_note/Urban/image3.png Schematic of THESIS urban properties tool. Executable scripts are in orange, input files are blue, and output files are green. Items within the black box outline are either read in as input, executed, or output by the driver script (urban_prop.csh). From 477bcb413a41b1f0ae839b0d0e11dc5268b799fb Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 26 Mar 2020 15:59:12 -0600 Subject: [PATCH 233/255] Point to a rewritten version of the images repo This contains a svg image in place of the original flow.png for PHS --- Externals_CLM.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Externals_CLM.cfg b/Externals_CLM.cfg index 05fe44c0ae..162fae65b1 100644 --- a/Externals_CLM.cfg +++ b/Externals_CLM.cfg @@ -16,7 +16,7 @@ required = True local_path = doc/images protocol = git repo_url = https://github.com/ESCOMP/CTSM-doc-images.git -hash = 9e12e5531d8cd3f2e9c6a0154dba8289ffd32c7f +hash = 476c694359e76c5054958e1397b8fa18aa0ff3e0 required = False [externals_description] From 2cbde17c625d78de20d068d2f95d596b9b6d01b8 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 26 Mar 2020 16:00:30 -0600 Subject: [PATCH 234/255] Update plant hydraulics to point to new svg version of the image --- .../Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index e1ecb07118..c2ea4ec1bd 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -714,6 +714,6 @@ The outermost level of iteration works towards convergence of leaf temperature, .. _Figure PHS Flow Diagram: -.. figure:: ../../../images/tech_note/Plant_Hydraulics/flow.png +.. figure:: ../../../images/tech_note/Plant_Hydraulics/phs_iteration_schematic.svg Flow diagram of leaf flux calculations From 1a879b42020f28f87fcdcc9698d72b6c498ed5f9 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 26 Mar 2020 17:12:45 -0600 Subject: [PATCH 235/255] Remove old UsersGuide, no longer used --- doc/UsersGuide/Makefile | 193 --- doc/UsersGuide/addco2_datm.buildnml.diff | 59 - doc/UsersGuide/adding_files.xml | 357 ---- doc/UsersGuide/addxhtmlhead.pl | 78 - doc/UsersGuide/appendix.xml | 305 ---- doc/UsersGuide/badpergro.jpg | Bin 40077 -> 0 bytes doc/UsersGuide/clm_stylesheet.dsl | 154 -- doc/UsersGuide/clm_ug.xml | 191 --- doc/UsersGuide/co2_streams.txt | 50 - doc/UsersGuide/custom.xml | 1615 ------------------- doc/UsersGuide/get_Icaselist.pl | 136 -- doc/UsersGuide/limitLineLen.pl | 104 -- doc/UsersGuide/modelnl/Makefile | 85 - doc/UsersGuide/modelnl/index.cpp | 45 - doc/UsersGuide/modelnl/showinfo.js | 193 --- doc/UsersGuide/modelnl/xmldef2html_compsets | 162 -- doc/UsersGuide/pergro.jpg | Bin 35642 -> 0 bytes doc/UsersGuide/preface.xml | 1419 ---------------- doc/UsersGuide/ptclm.xml | 992 ------------ doc/UsersGuide/single_point.xml | 930 ----------- doc/UsersGuide/special_cases.xml | 916 ----------- doc/UsersGuide/stylesheethtml2docbook.xsl | 579 ------- doc/UsersGuide/tools.xml | 1396 ---------------- doc/UsersGuide/trouble_shooting.xml | 545 ------- 24 files changed, 10504 deletions(-) delete mode 100644 doc/UsersGuide/Makefile delete mode 100644 doc/UsersGuide/addco2_datm.buildnml.diff delete mode 100644 doc/UsersGuide/adding_files.xml delete mode 100755 doc/UsersGuide/addxhtmlhead.pl delete mode 100644 doc/UsersGuide/appendix.xml delete mode 100644 doc/UsersGuide/badpergro.jpg delete mode 100644 doc/UsersGuide/clm_stylesheet.dsl delete mode 100644 doc/UsersGuide/clm_ug.xml delete mode 100644 doc/UsersGuide/co2_streams.txt delete mode 100644 doc/UsersGuide/custom.xml delete mode 100755 doc/UsersGuide/get_Icaselist.pl delete mode 100755 doc/UsersGuide/limitLineLen.pl delete mode 100644 doc/UsersGuide/modelnl/Makefile delete mode 100644 doc/UsersGuide/modelnl/index.cpp delete mode 100644 doc/UsersGuide/modelnl/showinfo.js delete mode 100755 doc/UsersGuide/modelnl/xmldef2html_compsets delete mode 100644 doc/UsersGuide/pergro.jpg delete mode 100644 doc/UsersGuide/preface.xml delete mode 100644 doc/UsersGuide/ptclm.xml delete mode 100644 doc/UsersGuide/single_point.xml delete mode 100644 doc/UsersGuide/special_cases.xml delete mode 100644 doc/UsersGuide/stylesheethtml2docbook.xsl delete mode 100644 doc/UsersGuide/tools.xml delete mode 100644 doc/UsersGuide/trouble_shooting.xml diff --git a/doc/UsersGuide/Makefile b/doc/UsersGuide/Makefile deleted file mode 100644 index 1c76bc75bd..0000000000 --- a/doc/UsersGuide/Makefile +++ /dev/null @@ -1,193 +0,0 @@ -# -# Makefile to convert DocBook CLM Users-Guide into html and/or pdf -# (rtf, txt, ps, tex, man, dvi, and texi are also valid docbook formats) -# -VPATH := ../../tools/cprnc . .. ../../bld ../../tools/ncl_scripts \ - ../../tools/mksurfdata ../../test/system ../../bld/namelist_files \ - ../../bld/config_files ../../tools ../../../../../scripts/ccsm_utils/Tools \ - ../../../../../scripts/ccsm_utils/Tools/lnd/clm/PTCLM/ ../../src/main - -PDFUG := clm_ug.pdf -HTMLUG := book1.html -DOCBKUG := clm_ug.xml -CFGLOG := config_help -CPRLOG := cprnc_readme -BNMLOG := buildnml_help -BSTLOG := build_streams_help -RESLOG := buildnml_resolutions -USCLOG := buildnml_usecases -QCKLOG := quickstart_guide -COPLOG := filecopies -MKSLOG := mksurfdata.pl -USRLOG := quickstart_usrdat -PTCLOG := ptclm_help -PTCLST := ptclm_list -TDRLOG := test_driver.sh -GETREG := getregional_datasets -CO2DIF := addco2_datm.buildnml -DATLOG := build_date -NMLDFTBL := namelist_definition_table -NMLDLTBL := namelist_defaults_clm_table -HSFLDTBL := history_fields_table -CFGDFTBL := config_definition_table -COMPLIST := compsets_list_ofIcases.xml -SOURCES := $(DOCBKUG) $(COMPLIST) $(CFGLOG).xml $(PTCLOG).xml $(BNMLOG).xml \ - $(RESLOG).xml $(USCLOG).xml $(QCKLOG).xml $(COPLOG).xml $(PTCLST).xml \ - $(USRLOG).xml $(GETREG).xml preface.xml custom.xml special_cases.xml \ - tools.xml adding_files.xml single_point.xml addco2_datm.buildnml.xml \ - appendix.xml trouble_shooting.xml ptclm.xml $(BSTLOG).xml \ - $(MKSLOG).xml $(TDRLOG).xml $(DATLOG).xml $(CPRLOG).xml \ - $(NMLDFTBL).xml $(NMLDLTBL).xml $(CFGDFTBL).xml $(HSFLDTBL).xml - -CONVAMP := sed 's/\&/\&/g' -CONVSIGNS := sed 's/>/\>/g' | sed 's/ tmpFile.txt - addxhtmlhead.pl tmpFile.txt > $@ - $(RM) tmpFile.txt - -$(NMLDLTBL).xhtml: namelist_defaults_clm.xml namelist_defaults.xsl - xsltproc ../../bld/namelist_files/namelist_defaults.xsl $< > tmpFile.txt - addxhtmlhead.pl tmpFile.txt > $@ - $(RM) tmpFile.txt - -$(CFGDFTBL).xhtml: config_definition.xml config_definition.xsl - xsltproc ../../bld/config_files/config_definition.xsl $< > tmpFile.txt - addxhtmlhead.pl tmpFile.txt > $@ - $(RM) tmpFile.txt - -history_fields.xml: findHistFields.pl - cd ../../src/main; ./findHistFields.pl >& tmpFile.txt - $(RM) tmpFile.txt - -$(HSFLDTBL).xhtml: history_fields.xml history_fields.xsl - xsltproc ../../bld/namelist_files/history_fields.xsl $< > tmpFile.txt - addxhtmlhead.pl tmpFile.txt > $@ - $(RM) tmpFile.txt - -.xhtml.xml: - xsltproc stylesheethtml2docbook.xsl $< > $@ - -.tlog.xml: - $(CONVAMP) $< | $(CONVSIGNS) > tempFile.txt - limitLineLen.pl tempFile.txt > $@ - $(RM) tempFile.txt - -.diff.xml: - $(CONVAMP) $< | $(CONVSIGNS) > $@ - -debug: - @echo "SOURCES: $(SOURCES)" - @echo "CONVAMP: $(CONVAMP)" - @echo "CONVSIGNS: $(CONVSIGNS)" - -$(COMPLIST): - ./get_Icaselist.pl > $@ - -$(HTMLUG): $(SOURCES) - docbook2html --dsl clm_stylesheet.dsl#html $< - -$(PDFUG): $(SOURCES) - docbook2pdf --dsl clm_stylesheet.dsl#print $< - -$(BNMLOG).tlog: build-namelist - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../bld/build-namelist -help >& $@ - -$(BSTLOG).tlog: build_streams - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../../../../scripts/ccsm_utils/Tools/build_streams --help >& $@ - -$(DATLOG).tlog: - @echo "Get current build date" - date +%b-%d-%Y >& $@ - -$(RESLOG).tlog: build-namelist - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../bld/build-namelist -res list >& $@ - -$(USCLOG).tlog: build-namelist - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../bld/build-namelist -use_case list >& $@ - -$(CFGLOG).tlog: configure - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../bld/configure -help >& $@ - -$(PTCLOG).tlog: PTCLM.py - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../../../../scripts/ccsm_utils/Tools/lnd/clm/PTCLM/PTCLM.py --help >& $@ - -$(PTCLST).tlog: PTCLM.py - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - cd ../../../../../scripts/ccsm_utils/Tools/lnd/clm/PTCLM; \ - PTCLM.py --list >& $(CURDIR)/$@ - -$(MKSLOG).tlog: mksurfdata.pl - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../tools/mksurfdata/mksurfdata.pl -help >& $@ - -$(TDRLOG).tlog: test_driver.sh - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $@ is good and redo your make" - ../../test/system/test_driver.sh -help >& $@ - -$(QCKLOG).tlog: Quickstart.GUIDE - cp $< $@ - -$(COPLOG).tlog: README.filecopies - cp $< $@ - -$(CPRLOG).tlog: README - cp $< $@ - -$(USRLOG).tlog: Quickstart.userdatasets - cp $< $@ - -$(GETREG).tlog: getregional_datasets.pl - @echo "The following line will fail in the make as it calls die -- but that is expected" - @echo "Check that the output $(GETREG) is good and redo your make" - ../../tools/ncl_scripts/getregional_datasets.pl -help >& $@ - -clean: - $(RM) -f $(HTMLUG) $(PDFUG) *.tlog $(DATLOG).xml *.xhtml *.tex - -realclean: clean - $(RM) -f f*.html c*.html x*.html a*.html i*.html $(COMPLIST) $(CFGLOG).xml \ - $(BNMLOG).xml $(BSTLOG).xml $(PTCLOG).xml $(PTCLST).xml \ - $(RESLOG).xml $(USCLOG).xml $(USRLOG).xml $(GETREG).xml $(QCKLOG).xml \ - $(CO2DIF).xml *.tlog $(MKSLOG).xml $(TDRLOG).xml $(DATLOG).xml \ - $(NMLDFTBL).xml $(NMLDLTBL).xml $(CFGDFTBL).xml $(CPRLOG).xml \ - $(COPLOG).xml diff --git a/doc/UsersGuide/addco2_datm.buildnml.diff b/doc/UsersGuide/addco2_datm.buildnml.diff deleted file mode 100644 index b8fbf34e36..0000000000 --- a/doc/UsersGuide/addco2_datm.buildnml.diff +++ /dev/null @@ -1,59 +0,0 @@ -*** datm.buildnml.csh.orig 2010-06-11 10:59:29.246523532 -0600 ---- datm.buildnml.csh 2010-06-11 11:06:30.710784206 -0600 -*************** -*** 34,48 **** - streams = 'clm_qian.T62.stream.Solar.txt 1895 1948 1972 ', - 'clm_qian.T62.stream.Precip.txt 1895 1948 1972 ', - 'clm_qian.T62.stream.TPQW.txt 1895 1948 1972 ', -! 'presaero.stream.txt 1849 1849 2006' - vectors = 'null' - mapmask = 'nomask', - 'nomask', - 'nomask', - 'nomask' - tintalgo = 'coszen', - 'nearest', - 'linear', - 'linear' - / - EOF1 ---- 34,56 ---- - streams = 'clm_qian.T62.stream.Solar.txt 1895 1948 1972 ', - 'clm_qian.T62.stream.Precip.txt 1895 1948 1972 ', - 'clm_qian.T62.stream.TPQW.txt 1895 1948 1972 ', -! 'presaero.stream.txt 1849 1849 2006', -! 'datm.global1val.stream.CO2.txt 1766 1766 2005 ' - vectors = 'null' - mapmask = 'nomask', - 'nomask', - 'nomask', -+ 'nomask', - 'nomask' -+ mapalgo = 'bilinear', -+ 'bilinear', -+ 'bilinear', -+ 'bilinear', -+ 'nn' - tintalgo = 'coszen', - 'nearest', - 'linear', -+ 'linear', - 'linear' - / - EOF1 -*************** -*** 1112,1121 **** ---- 1120,1132 ---- - - EOF1 - -+ cp $CASEBUILD/co2_streams.txt datm.global1val.stream.CO2.txt -+ - - $CASETOOLS/listfilesin_streams -input_data_list -t clm_qian.T62.stream.Solar.txt >> $CASEBUILD/datm.input_data_list - $CASETOOLS/listfilesin_streams -input_data_list -t clm_qian.T62.stream.Precip.txt >> $CASEBUILD/datm.input_data_list - $CASETOOLS/listfilesin_streams -input_data_list -t clm_qian.T62.stream.TPQW.txt >> $CASEBUILD/datm.input_data_list -+ $CASETOOLS/listfilesin_streams -input_data_list -t datm.global1val.stream.CO2.txt >> $CASEBUILD/datm.input_data_list - - cat >! presaero.stream.txt << EOF1 - diff --git a/doc/UsersGuide/adding_files.xml b/doc/UsersGuide/adding_files.xml deleted file mode 100644 index 18c034cbbb..0000000000 --- a/doc/UsersGuide/adding_files.xml +++ /dev/null @@ -1,357 +0,0 @@ - - -Adding New Resolutions or New Files to the build-namelist Database - -In the last chapter we gave the details on how to create new files for input into -CLM. These files could be either global resolutions, regional-grids or even a single -grid point. If you want to easily have these files available for continued use in your -development you will then want to include them in the build-namelist database so -that build-namelist can easily find them for you. You can deal with them, just by -editing your namelist by hand (or using a &usernlclm; namelist file), or by using -&CLMUSRDAT;. Another way to deal with them is to enter them into -the database for build-namelist, so that build-namelist can find them for you. -This keeps one central database for all your files, rather than having multiple locations -to keep track of files. If you have a LOT of files to keep track of it also might -be easier than keeping track by hand, especially if you have to periodically update -your files. If you just have a few quick experiments to try, for a short time period -you might be best off using the other methods mentioned above. - - -There are two parts to adding files to the build-namelist database. The first part -is adding new resolution names which is done in the -models/lnd/clm/bld/namelist_files/namelist_definition.xml file -(and in the -models/lnd/clm/bld/config_files/config_definition.xml file -when adding supported single-point datasets). -The second part is actually adding the new filenames which is done in the -models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml file -(models/lnd/clm/bld/namelist_files/namelist_defaults_clm_tools.xml -file for CLM tools). -If you aren't adding any new resolutions, and you are just changing the files for existing -resolutions, you don't need to edit the namelist_definition file. - - - -Managing Your Own Data-files - -If you are running on a supported machine (such as bluefire or jaguar) the standard -input datasets will already be available and you won't have to check them out of the -subversion inputdata server. However, you also will NOT be able to add your own datafiles -to these standard inputdata directories -- because most likely you won't have permissions -to do so. In order to add files to the XML database or to use &CLMUSRDAT; you need -to put data in the standard locations so that they can be found. The recommended -way to do this is to use the link_dirtree tool in the &cesm; scripts. -Some information on link_dirtree is available in the -&cesmrel; Scripts User's Guide. We also have -some examples of it's use here and in other sections of this User's Guide. - - -Using link_dirtree is quite simple, you give the directory where -data exists and then the directory that you want to create where datasets will point -to the original source files. In the example below we use "$HOME/inputdata", but -MYCSMDATA could be any directory you have access to where you want to -put your data. - -> cd scripts -# First make sure you have a inputdata location that you can write to -# You only need to do this step once, so you won't need to do this in the future -# (except to bring in any updated files in the original $CSMDATA location). -> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data -> ./link_dirtree $CSMDATA $MYCSMDATA - -Then when you create a case you will change DIN_LOC_ROOT_CSMDATA to -point to the location you linked to rather than the default location. - -> ./xmlchange -file env_run.xml -id DIN_LOC_ROOT_CSMDATA -val $MYCSMDATA - - - -In order to list the files that you have created you merely need to use the UNIX -command find to find the files that are NOT softlinks. So for -example executing the following command: - -> find $MYCSMDATA -type f -print - -for me gives the following list of &CLMUSRDAT; files that I have created. - -/blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_monthly_1849-2006_1x1pt_US-Ha1.nc -/blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_monthly_1849-2006_13x12pt_f19_alaskaUSA.nc -/blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_rcp8.5_monthly_1850-2100_13x12pt_f19_alaskaUSA.nc -/blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_rcp4.5_monthly_1850-2100_13x12pt_f19_alaskaUSA.nc -/blhome/erik/inputdata/atm/datm7/domain.clm/domain.lnd.1x1pt_US-Ha1_USGS.nc -/blhome/erik/inputdata/atm/datm7/domain.clm/domain.lnd.13x12pt_f19_alaskaUSA_gx1v6.nc -/blhome/erik/inputdata/lnd/clm2/griddata/fracdata_13x12pt_f19_alaskaUSA_gx1v6.nc -/blhome/erik/inputdata/lnd/clm2/griddata/fracdata_1x1pt_US-Ha1_USGS.nc -/blhome/erik/inputdata/lnd/clm2/griddata/topodata_13x12pt_f19_alaskaUSA.nc -/blhome/erik/inputdata/lnd/clm2/griddata/griddata_1x1pt_US-Ha1.nc -/blhome/erik/inputdata/lnd/clm2/griddata/griddata_13x12pt_f19_alaskaUSA.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_13x12pt_f19_alaskaUSA_simyr1850.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_1x1pt_US-Ha1_simyr2000.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_rcp4.5_13x12pt_f19_alaskaUSA_simyr1850-2100.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_1x1pt_US-Ha1_simyr1850.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_13x12pt_f19_alaskaUSA_simyr2000.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_1x1pt_US-Ha1_simyr1849-2006.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_13x12pt_f19_alaskaUSA_simyr1850-2100.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_rcp8.5_13x12pt_f19_alaskaUSA_simyr1850-2100.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_13x12pt_f19_alaskaUSA_simyr1849-2006.nc -/blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_1x1pt_US-Ha1_simyr1850-2100.nc - -You can also use find to list files that have a particular pattern -in the name as well (using the -name option with wildcards). Also you can always rerun the -link_dirtree command if any new files are added that you need to be -linked into your directory tree. Since, the files are soft-links -- it doesn't take up -much space other than the files that you add there. This way all of the files are kept -in one place, they are organized by usage according to &cesm; standards, and you can -easily find your own files, and &clm; can find them as well. - - - - -Adding Resolution Names - -If you are adding files for new resolutions which aren't covered in the -namelist_definition file -- you'll need to add them in. The list of valid resolutions -is in the id="res" entry in the -models/lnd/clm/bld/namelist_files/namelist_definition.xml file. -You need to choose a name for your new resolution and simply add it to the comma -delimited -list of valid_values for the id="res" entry. The convention for global Gaussian grids -is number_of_latitudes x number_of_longitudes. The convention for global finite -volume grids is latitude_grid_size x longitude_grid_size where latitude and longitude -is measured in degrees. For regional or single-point datasets the names have a grid size -number_of_latitudes x number_of_longitudes followed by an underscore and then a -descriptive name such as a City name followed by an abbreviation for the Country in caps. -The only hard requirement is that names be unique for different grid files. -Here's what the entry for resolutions looks like in the file: - -<entry id="res" type="char*30" category="default_settings" - group="default_settings" - valid_values= -"128x256,64x128,48x96,32x64,8x16,94x192,0.23x0.31,0.47x0.63, -0.9x1.25,1.9x2.5,2.65x3.33,4x5,10x15,5x5_amazon, -1x1_camdenNJ,1x1_vancouverCAN,1x1_mexicocityMEX,1x1_asphaltjungleNJ, -1x1_brazil,1x1_urbanc_alpha,0.5x0.5"> -Horizontal resolutions -</entry> - -As you can see you just add your new resolution names to the end of the valid_values -list. - - -When using &ptclm; and adding supported single-point resolutions, you'll also want to -add these resolutions to the -models/lnd/clm/bld/config_files/config_definition.xml under -the sitespf_pt name. The entry in that file looks like: - -<entry id="sitespf_pt" -valid_values="none,1x1_brazil,5x5_amazon, -1x1_camdenNJ,1x1_vancouverCAN,1x1_mexicocityMEX,1x1_asphaltjungleNJ, -1x1_urbanc_alpha,1x1_numaIA,1x1_smallvilleIA" -value="none" category="physics"> -Flag to turn on site specific special configuration flags for supported single -point resolutions. -Currently the only special settings are for MEXICOCITY and VANCOUVER, which make -changes to urban parameters. -</entry> - -&ptclm; assumes that any supported single-point resolutions are valid settings for -sitespf_pt. - - - - -Adding or Changing Default Filenames - -To add or change the default filenames you edit the -models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml -and either change an existing filename or add a new one. Most entries in the -default namelist files, include different attributes that describe the different -properties that describe the differences in the datasets. Attributes include -the: resolution, year to simulation, range of years to simulate for transient -datafiles, the land-mask, the representative concentration pathway (rcp) for future -scenarios, and the type of biogeochemistry (bgc) model used. For example the -fatmgrid for the 1.9x2.5 resolution is as follows: - -<fatmgrid hgrid="1.9x2.5" >lnd/clm2/griddata/griddata_1.9x2.5_060404.nc -</fatmgrid> - -Other fatmgrid files are distinguished from this one by -their resolution (hgrid) attribute. - - -To add or change the default filenames for &clm; tools edit the -models/lnd/clm/bld/namelist_files/namelist_defaults_clm_tools.xml -and either change an existing filename or add a new one. Editing this file is -similar to the namelist_defaults_clm.xml talked about above. - - -What are the required files? - -Different types of simulations and different types of configurations for &clm; require -different lists of files. The Carbon Nitrogen (cn) Biogeochemistry model for example -requires stream_fldfilename_ndep files, which are NOT required by -other bgc modes. Transient simulations also require transient datasets, and the names -of these datasets are sometimes different from the static versions (sometimes both are -required as in the dynamic PFT cases). - - -In the following table we list the different files used by CLM, they are listed -in order of importance, dependencies, and customizing. So the required files -are all near the top, and the files used only under different conditions are listed -later, and files with the fewest dependencies are near the top, as are the files -that are least likely to be customized. - - -Required Files for Different Configurations and Simulation Types - - - - - - - Filename - Config. type - Simulation type - Resol. Dependent? - Other Dependencies? - - - Notes - - - - - - fpftcon - ALL - ALL - No - No - - - Not usually customized, as describes plant function -type properties. &ptclm; copies the file for you so that you can customize it if you -like, see . - - - fsnowoptics - ALL - ALL - No - No - - - Not usually customized as describes global snow optical properties. - - - fsnowaging - ALL - ALL - No - No - - - Not usually customized as describes global snow aging properties. - - - fatmgrid - ALL - ALL - Yes - No - - - Creating, using mkgriddata -usually gives you the amount of customization -you need, as it just describes the grid and grid extents. - - - fatmlndfrc - ALL - ALL - Yes - land-mask - - - Describes the land-mask for points with active land, as well as the fraction -of each grid-cell covered by land. You might customize it to make sure the land-fraction -of your grid-cell matches the expected values for your site. But, usually you will just -use what mkgriddata gives you. - - - fsurdat - ALL - ALL - Yes - simulation-year - - - Describes percentages of different land-units, columns and -vegetation types within each grid-cell. To customize for a specific point -or region you may want to use custom input datasets to mksurfdata when -creating the file. mksurfdata also allows you to customize the PFT, -and soil types to it see . &ptclm; takes -advantage of this to create customized datasets as well, see the chapter on &ptclm; -at . - - - flanduse_timeseries - ALL - transient land-use land-cover change - Yes - Simulation year range, and representative concentration pathway (rcp) - - - See notes on fsurdat files. - - - frivinp_rtm - RTM only - ALL - No - No - - - We only provide a half-degree global river routing file. If you want -to model river flow for a smaller scale, or a basin regional scale, you would -need to create your own custom file to do that. Normally, we turn river-routing -OFF for regional or single point simulations. - - - finidat - ALL - RUN_TYPE="startup", CLM_FORCE_COLDSTART="off" - Yes - mask, maxpft, bgc, simulation-year, start-date - - - Used for starting the model from a spun-up state. -Create these files by running the model -for multiple years and saving the restart file from the end of a spin-up -simulation. - - - - stream_fldfilename_ndep - bgc=cn/cndv - Yes - No - simulation-year - - - -You may customize this file to get the Nitrogen deposition characteristics -of your site if available. This file will be interpolated while the model is -running from it's resolution to the resolution that &clm; is running at. - - - - - -
- - - - - - diff --git a/doc/UsersGuide/addxhtmlhead.pl b/doc/UsersGuide/addxhtmlhead.pl deleted file mode 100755 index d5f9615c58..0000000000 --- a/doc/UsersGuide/addxhtmlhead.pl +++ /dev/null @@ -1,78 +0,0 @@ -#!/usr/bin/env perl -# -use strict; -use Cwd; -use English; -use IO::File; -use Getopt::Long; -use IO::Handle; -#----------------------------------------------------------------------------------------------- - -# Get the directory name and filename of this script. If the command was -# issued using a relative or absolute path, that path is in $ProgDir. Otherwise assume -# the -# command was issued from the current working directory. - -(my $ProgName = $0) =~ s!(.*)/!!; # name of this script -my $ProgDir = $1; # name of directory containing this script -- may be a - # relative or absolute path, or null if the script - # is in - # the user's PATH -my $nm = "$ProgName::"; # name to use if script dies -my $scrdir; -if ($ProgDir) { - $scrdir = $ProgDir; -} else { - $scrdir = getcwd() -} - -sub usage { - my $msg = shift; - - print "ERROR:: $msg\n"; - die < -OPTIONS - NONE -EOF -} - -my %opts = ( ); - -GetOptions( -) or usage(); - -if ( $#ARGV != 0 ) { - &usage( "Wrong number of command line arguments" ); -} - -my $inputFile = $ARGV[0]; - -if ( ! -f $inputFile ) { - &usage( "Input file does NOT exist : $inputFile" ); -} - -my $fh = IO::File->new($inputFile, '<') or die "** $nm - can't open input file: -$inputFile\n"; - -# -# Add in XML XHTML headers -# -print <<"EOF"; - - - -EOF -while (my $line = <$fh>) { - if ( $line =~ /^$/ ) { - print "
\n"; - } elsif ( $line =~ /^'."\n"; - } else { - print $line; - } -} -$fh->close(); diff --git a/doc/UsersGuide/appendix.xml b/doc/UsersGuide/appendix.xml deleted file mode 100644 index 058e67d577..0000000000 --- a/doc/UsersGuide/appendix.xml +++ /dev/null @@ -1,305 +0,0 @@ - -Editing Template Files Before Configure - -The last kind of customization that you can do for a case, before configure is run -is to edit the templates. The &clm; template is in -models/lnd/clm/bld/clm.cpl7.template, the &datm; template is -in models/atm/datm/bld/datm.cpl7.template, and the driver templates -are in the models/drv/bld directory and are named: -ccsm.template and cpl.template. When a case is -created they are also copied to the Tools/Templates directory -underneath your case. If you want to make changes that will impact all your cases, you -should edit the template files under the models directory, but -if you want to make a change ONLY for a particular case you should edit the template -under that specific case. - - - -Editing the template files is NOT for the faint of heart! We recommend this ONLY for -experts! It's difficult to do because the template is a script that actually creates -another script. So part of the script is echoing the script to be created and part of -it is a script that is run when "configure -case" is run. As a result any variables -in the part of the script that is being echoed have to be escaped like this: - -\$VARIABLE - -But, in other parts of the script that is run, you can NOT escape variables. So you -need to understand if you are in a part of the script that is echoing the script to -be created, or in the part of the script that is actually run. - - - -If you can customize your case using: compsets, env_*.xml variables, -or a user namelist, as outlined in you should do so. -The main reason to actually edit the template files, is if you are in a situation where -the template aborts when you try it run it when "configure -case" is run. The other -reason to edit the template is if you are &clm; developer and need to make adjustments -to the template because of code or script updates. An example of modifying the &datm; -template is in where sed is used to modify the path -for &CPLHIST; data. - - -Outline of the &clm; template - -The outline of the &clm; template is as follows: - -# set up options for clm configure and then run clm configure -$CODEROOT/lnd/clm*/bld/configure <options> -# set up options for clm build-namelist and then run clm build-namelist -$CODEROOT/lnd/clm*/bld/build-namelist <options> -# echo the $CASEBUILD/clm.buildnml.csh script out -cat >! $CASEBUILD/clm.buildnml.csh << EOF1 -# NOTE: variables in this section must be escaped -EOF1 -# Remove temporary namelist files - -# echo the $CASEBUILD/clm.buildexe.csh script out -cat > $CASEBUILD/clm.buildexe.csh <<EOF2 -# NOTE: variables in this section must be escaped -EOF2 -# Remove temporary configure files - - - - - -Outline of the &datm; template - -The outline of the &datm; template is as follows: - -# Check $GRID to set the $DOMAINFILE and $DOMAINPATH - -# Check DATM_PRESAERO to set the prescribed aerosol option -# If &CLMUSRDAT; is set and $DOMAINFILE is NOT -- set it by &CLMUSRDAT; -# Ensure $DOMAINFILE is set or else abort - -#============================================================================== -# Create resolved prestage data script -#============================================================================== -cat >! $CASEBUILD/datm.buildnml.csh << EOF1 -# NOTE: variables in this section must be escaped -EOF1 -# Major if blocks look at DATM_MODE: -# the if blocks setup streams and run Tools/build_streams to create stream files -#----- CLM_QIAN mode ---------------------------------------------------------- -else if ($DATM_MODE == "&CLMQIAN;" ) then -. - # Customize &CLMQIAN; options here - - # A.) Setup datm_atm_in namelist -cat >! $CASEBUILD/datm.buildnml.csh << EOF -cat >! datm_atm_in << EOF1 -# NOTE: variables in this section must be escaped -EOF1 -EOF - - # B.) Setup options to build_streams -. -. -. -#----- CLM1PT mode ---------------------------------------------------------- -else if ($DATM_MODE == "CLM1PT" ) then -. - # Customize CLM1PT options here - - # A.) Setup datm_atm_in namelist -cat >! $CASEBUILD/datm.buildnml.csh << EOF -cat >! datm_atm_in << EOF1 -# NOTE: variables in this section must be escaped -EOF1 -EOF - - # B.) Setup options to build_streams -. -. -. -. -#----- CPLHIST 3-hourly time-averaging mode ----------------------------------------------------------- -else if ($DATM_MODE == "&CPLHIST;" ) then -. - # Customize &CPLHIST; options here - - # A.) Setup datm_atm_in namelist -cat >! $CASEBUILD/datm.buildnml.csh << EOF -cat >! datm_atm_in << EOF1 -# NOTE: variables in this section must be escaped -EOF1 -EOF - - # B.) Setup options to build_streams -. -. -. -. - -#----- INVALID mode -----------------------------------------------------------else - echo "ERROR: unrecognized DATM_MODE = \$DATM_MODE " - exit -1 -endif - -#============================================================================== -# Create prescribed aero streams if appropriate -#============================================================================== -. -. -. -#============================================================================== -# Create remaining resolved namelist -#============================================================================== - -cat >! $CASEBUILD/datm.buildnml.csh << EOF -cat >! datm_in << EOF1 -# NOTE: variables in this section must be escaped -. -. -. -EOF1 - -EOF - -#============================================================================== -# Create script to build executable -#============================================================================== - -cat > $CASEBUILD/datm.buildexe.csh <<EOF -#! /bin/csh -f -# NOTE: variables in this section must be escaped -EOF - -#============================================================================== -# end of script -#============================================================================== - - - - - -Adding a new DATM_MODE to the &datm; template - - The steps to adding a new DATM_MODE - -Add a new "if" block to the &datm; template - -As you can see from above -there are major "if" blocks for the different DATM_MODE's. So adding a new -DATM_MODE means adding a new "if" block. The two major parts of each DATM_MODE -block are: - -Setup datm_atm_in namelist -Setup options to build_streams - - - - -In the "if" block create the <filename>datm_atm_in</filename> namelist - -See for some notes about the -&datm; namelist and streams files. That and the - -&datm; User's Guide should give you guidance on how to -setup the namelist for your case. - - - -In the "if" block create options to and call <command>build_streams</command> - -The next part of the "if" block in the &datm; template file to work with is the -call to build_streams. You may need to add additional options -to it. You may also need to call it multiple times for multiple streams. You will -also likely need to add a new source option to it with the "-s" option. For more -information on build_streams do the following. - -Getting help with <command>build_streams</command> for &datm; - -> scripts/ccsm_utils/Tools/build_streams -help - - -The output of the above command is: - - -&build_streams_help; - - - - - -Add new streams templates to the &datm; -<filename>datm.template.streams.xml</filename> file - -As part of modifying the behavior of build_streams you will also -have to edit the models/atm/datm7/bld/datm.template.streams.xml -file as well (or the local version in your -$CASENAME/Tools/Templates directory for a particular case). -The template is an XML file much like the output streams file, but there are attributes -to distinguish which fields will be used based on things like: RESOLUTION or datasource. -And there are filename indicators (starting with a "%") that get translated into various -things such as: - -%c = Case (from above -case command line option) -%do = Use domain file -%y = Year (through range given from begyear to endyear) -%ym = Year-Month (all 12 months through year range) -%6ym = Like %ym but 6 digit year (ie. %YYYYYY-MM). (can replace the 6 with any digit 1-9) - - - - -Add a new valid_value to the <filename>config_definition.xml</filename> file in -scripts. - -Adding a new DATM_MODE also requires adding a new valid_value to -scripts/ccsm_utils/Case.template/config_definition.xml. This -enables the scripts to recognize the new value as a valid option to DATM_MODE -in the &envconf; file. - - - - - - - -Building the Users-Guide Documentation for &clm; - -All of the documentation for &clm; can be built using GNU Makefiles that are -available in the appropriate directories. The Makefiles require the following -utilities: docbook2html, docbook2pdf, -protex, and latex2html. - - -To build the Users Guide for &clm; (requires docbook). - -> cd models/lnd/clm/doc/UsersGuide -> gmake - -Note, that when the Users-Guide is built it will get output from other &clm; -utilities that by nature abort, and hence stop the make from continuing. However, -this is expected so you should simply run gmake again until -it either completes or comes upon a legitimate issue. Here is what a sample -warning looks like when gmake is run. - -The following line will fail in the make as it calls die -- but that is expected -Check that the output config_help.tlog is good and redo your make -../../bld/configure -help >&` config_help.tlog -make: *** [config_help.tlog] Error 255 - -To build the Code Reference Guide for &clm; (requires protex and -latex2html). The make here uses a Filepath -file that points to the list of directories that you want protex -to run over. You should examine this file and make sure it is appropriate for what -you need to do, before running the make. - -> cd models/lnd/clm/doc/CodeReference -> gmake - -To build the table of tests for the &clm; test suite. The make here runs a UNIX -shell script to create a html table of the list of tests run on the different machines -from the &clm; test suite. - -> cd models/lnd/clm/test/system -> gmake - - - - - diff --git a/doc/UsersGuide/badpergro.jpg b/doc/UsersGuide/badpergro.jpg deleted file mode 100644 index 4a378cf52d71870efb21201d0bd38a9d364ebc2f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 40077 zcmce;cUV*1*ESfc0)l`Pk=~?(pmaovQW9yQ6N-SKlmtSr3J542LhlNM-b)g?(u;u7 zNkVVZr8mKk=eypSd44nRT-Q7Q%sRPp_Q}cFYoE2V_E~$~_s-wxzY73rpqi!{fPjDi zpmDPS{^9_t03yPF-H@|3NiozArUcvg!C2- z?d^M3ex6HhlXzW@!7` z-6P~fQr=Cq4{o&mqxJt#d9x=XCLtgsy*Z~q10eiIC*h5ah;EVm^OYN&G@Qh=;v~v? zT-Nt)>gSgDQbS6w0=7vUrQ><58uIP8zT3~m{l8ei9U_98nmL4J5=~#jt<1QXjz@zQPBd=dE1;K0uHUeA9s|cvD!; z(;a(8%R78u?;cZFdp`8k&qe~|1jRM~pka;Q%+?P#iT(W9fI6wkC=Yw0-RVZM2P}2B z%-erS{udBoDmLAw%RH0@_wtSDa7NCMIbpa2!en@m$FR`Q6t9&fWo|pVOJTF)h@rYQ z=@!&a{|@d2$G?Ei$i6g(0*U$8@_0}=W?7prn2ol!O5p4r&jH~85*%YL4BRW2o6HMo)D9cLg&=goNi)FbtpGbeQM#bu0x7xdM)gO^U+ zUfKrVk){R8v0dTo8rE%2kvIqMHjC*ZD0Xq(?Q>Fb0fk&L`506$qIm6)@lcA^68krmC}$UO?JQfFSj{ZElF-cP%oo8avdYnU zsxV-Jz@%;OdUpWz@)xHipMoC@7J|)Po|Qv6uf`6xK@5F`_zJ2ENRH^Tuv*Kv6q)26 z-=Z8t=j3z<&t!Q2GJJ{Ldm?98Xmo1-gtQ+F`_nZ zf>R+$W@^3AIhW(R$1^(2s+7};1I&!;Bd-PW(IuJ^t0@*%e^|__L$;M(&b5JEsKa>I9=zE3@*}P(gLa^Kqa;1q=E=c3gIVvAz&Iu(CJaBU9{PX z78j@PZu$#gYWCL`t$gx8WudkK3BV}O7Z=AhsPBA!vMMBgRNqVmY&HJ6uaM(qTfk6O zz;A-=(3-$SnHy7*r&B#SmMP*Jo{%1ZICv!&Kbax6tTJ8q~tG{y;%Qi_JUTwMqYnr9Rl7|~!Hmpzq?dKJl^~}P6-7K9BP3O z8m!M_tO>VGa(sYc8IVZCi2)ja%w0(JtB0w;FT$>El{W38XY#vhjfNM!O!i=gqbidF zRS5>#(WGymicYPZbGQny9jdchZ;@TgOizAc*2kh!<=CDn8fZAB)7*Jv9$1+4V^;aq zZdFhKa7jw?{pdf2e;gibUe!cIy8p$rk|G6EJF^aYPun)VeJH9|$2Q4iR z*nuEUVy?<$DxSpMW0}EY!tN|A{ykUDRnv@rw&;$OWHu*7>?o6JRhWoE zmdC7c=K$^BH^Nk+iOT`o;jm$t84rP198fzISCa< z7@w;GpR0cL`US2s%xUhk-MJKJ(p(J`B-Q9zIenF4w}bOYbG?#J;8FWD7FYk1@=MQT zk^sxB2Y*4vkE750R|M6o=%-5Kvrc{ckQ|}A@`+Ay4z>8CB+yF}n(?W!_yO_{qAf-A zzmw^`u&?=fVoE<_ezE1Lc6$a#1%7e#r@~~0XFLg~Gw}I-VW;^Te%9E8%HPetewZY^ zLWNUIBBmhi6g8S{cW&3aAX`d!@G=T^}*Q$mkU%CSEm zv<|i;x7Zp4=ieI+e?Q{iw~T6r)GwXFbbU1`T*fNKf6FIdy7-R;HyB)H zYM4fhcO3|gp}iW`-x1(aeY-}7`((6%r-HD?E>)51l8?x#+xOJALMD8DA7-1Izv$U} zV23iiq)BBhN_(zmX6mrFp|^={31sfJwYF`A zw!E;E#vXk~0ToQDt|m}f(hnT8vV?AIq>qXE{>Lvc!OdXtxxgRd&?gL^v3Q{7Z6PJ# z*}Z;FB_TV)TW0^W0m(pZDy!9XA}duZ8K&}}dU+Cpwfjh>Uz+=HWgt@k_ljDipJUg1 zmz~H(B3!85a+pndt*uk&wr&14MQ z*x@XQwc8oS2bdi?3UWZi*)0Xo_UxcBy3(RaPo1l*(W-f4_KvZCm47fa2;Kxef#5~V z^8E`DIf$^tQEGEp3m&ZFd&-J)0Uhi@uj%o}+4_G0Z=RH$PW1k+C#eADyF2k2G^WVy z1bbzRd}2+Yzupv+rl*;S$KjwG?*d!fdzy3VO5bmW?r>7}jB}!fw!eTt@277J{sLx(1h0((cbiwV{LZ`Y6SI^y@SGRR|zY0@A5_n|`pC8Bc8Z2r?r|d|RU44~Oh4L|T!^+|sknZ_xeI4<=hl=j2C40=iH`#<&jq!V za+k^uVtr#&+iPIYCxCr5mrM>YI^x1*uLuHd7{Ng>fBD^XCFYpZ;`V>_M=`3vCL8R? zAWz$|S_WLYjlN_(#E3D{yGd;om@YE=S#70#VgA$TqGWaSA3xlw5HTiV>+w%tBKR2&0l^oW!dMz-65twJoDj^Z&Q5_xNo#{-2s}(bajXNAxy6KC(>iW0Y@c z&e>|g>wg2Y3hl(LwRz23pZs7%K5y`s@qbyLD>bhK({A z091*Tnzuz=PcZ!3pBm^VqTiHKs*i5BYZu@=3g_lbZL+N;+A=UXBW2dkBtbUk92hC~ z$JL*KXD_a)7T8hk4F(a}`oX=2?!bV%*SH%8`%h;pF&#bioEjX?v#mDdQ=e|N-Rq0b zbQznXa-*m*S5{AJGe{D{fTeY{yMk^@ax&%WZS|RVr`K$_qZzm^dVfp|Z`MDWTi}sd z`1p;&=n_dBR!l;DTa&xD>tn7QkBjck0*y6R-?z#VO3xiUTiWi&Y<~#!^h)0h9 z@K?X3uKTCW5h<4<)T!i52D+^seagg?DJt5%-S9_FyUqC8a>QOt|EN&iY3BpmpXsf5 z!(XFg{I7W-FV5&H<@b#SPWKn4=uM;$PJE4TJ$0jt1l@oNi_55hH%z;^AJj)nqAU%^ zht@0xgzvb3QbgPWxreVF!zoL4Ie{uV$TQ3Vffa{0+d}Zq|FH6oB(H~YiM9t4* zSW3!F;;S}Q!*=2tUa-9qM0|dkBx!f-W5+j~t2*Y;IN9U(e?O@vARUps$KUzJ3u-2w zvZ|}kINs{kFjA);-J9&Da^>-B7Zx9%r$R2JdlrEw?^QnL&DPsw)EC>ft=;aA`)EUb zNeeTYDb;(4yJ!rx1P|V)J4}UV<%ryO}DRepRUw~<1sa-CF(EWIN*T_trszC-~1BpJ<+QtcK?qs z+Cb&BEW;(vF1}hGWev6EZmcijz%g9t9_7*ZqC)a$%>{o`8_?-gSLsC~14~avejt(s zlaZ(l=q2ri;hPI}2XZ%ae+F;<9nFFJo?EtCu?vw~F(MjXayhsUE}y?BYZZs_L1Vju zoa;*j=Ocrsx4jg5ng!iLw1HCtr|P9xN9-HNAMo=s_{WQdrIl3w0)P71KPn2$$TjTT zM(B1(P!XZZB}jmr9~`f&y?oJs&bl@Krm3S1Yi+qxd1|8*i%(&^Mli$|Dt_dfJ~HDP`gcc9IcV!?7WX(AoAY~}Tqcf4=8qwdnSDgN=^Z%17V?V0p! zd_g?AWRrItZNB;oAnC8)h$?tHBiVCn^maQWmGc{~Xg-W}RnwzsP!!rHLl_~>j-6GbYqpHiKji%_ zi$#ndPlg{fUxinFX_XX7MiPjbpeje+H^EZLz~IC?$~dH1a#(qIwhz%4VmC zoLmb6|1g`iH$H4NOrWpGR$93udf{i;j~J9*gKcZ3$E#X@(n}+AnCyKT1k6-jsrouQ zTEz`rH^QkKYA-Ue?taTP6-6^QU?s=sWBfz7?tAU&7O}+e*M1nmj6gY@>9WUVKh&^2 zn_0hw%8zu31ACi$LB(X9SS-IE7yl9s#cB=@wPGkE7eQE1as4 z!#z)J!#JUMGx#%;!GpP3=UtV6&oc1^NOMhkT&)9J`}DqW1SVTWTu7iDpN}_d8tGb! z(-?gKa*8#B4pYnuD3PDAXm>6>OdPv72{5UAyy@e;hnlju!Zde8%CU;($Zr~j<}w_c zg51^y#r1|JDt}km>*UpxGWcj=Lvim^#i#JT#+oHB)iU0^j{oV9&}ht6@Hu#qjKmTA zv3Dyq?HbxZHIq=s6?g&xd15A`oVHZI3iT<=7r;q4UpQ$TkS)=X7@s{Po8T=ILXV7i zuCuq9n3zTP(d^qVH}mom6MrN;RT~hHkGX1%30&TY)77zIEaSzMfXlvbl()i~JG*Qo zUa4y;Oz+UsHIBgd@Ab?3@cAwORLiV)s+`APzaI;5&qba+9Z$(A*s(Ogu5N>4aP4Og zG~Jfz>0uJu2NYVDVhy;RjRe6?TD`j#@)CpYnM%{haQxeNgyEtS@DFi(j(H>BDLYwo z=)8HdXV&)M0c~d;#L8Y(_)8n*mxg>8FHgm*xGl_0Ks#-GUopaoK{gq(cdl+AD+(gz z4s*fI)^){x{|r{ArwdWSe^?%gBle#veWrshf(z{m_-|6^uQ88L+M(UzJRNza1)LMH z);-uW-PRKmoDE=_Z}=)DP8;cMsQB0+pc&aQGIi^t1vu_ok)`0X#pvdK=>Z*vsKEhH zN<>AY?1{WRqPZ*lpb<)%-vQ&M?1cXyBUvAB2qh7U7g_)i5Pu=gkvw`?J~#L(*R!eH z=G@&BxP%k=M2T$R4-NlNS?s2S7tj`pxN;-K>k55mM`p6oBts4s%Pwl(B|=>>c>hU* zm9$}6M0S=lC#UU5&A$0`6K5XO?b~NqT&x?t?kj}ELp{go5+EExA*Jf)J-qvePOpJu&vEQIoZhAlxu{@>rJ#*}-)zo_CVd?{df+2eP zLV>*UQb9&-LgX{N&#B|ROOGWjxG3KVBbkMZ(aefFB{E3o!ud7^py#s)IVjm~kwrcJ zP1BS7x3hDXODmr%>{~S@2S7aGQzdeGfgl;-E5BYBw0}Vm-hKyt!ZqX?6A4j@{N?^W z^pd7+#ownAFfo@dA``9?-#0!f#=vYF4cQaZX!_p#sT2+bX$2u=YWg*ex{3O=FaL16 zOmgO@sTwm>`2`|<6h-b$2zRtYD)hRCP|UoOsR(htc!TZ48#V0e5KZ{q?(or*m+BxOcR_-#gU{^t!zNPA2&>T;gM z^N)UE@~WETHHE{RIF4b@zxbQ9Jpzu1#htd14}zK!HZr*ext1Tmk6KEmRxgYyDQZSU z+N%XA)9-S}D*?9YRP;}cM@PypR0&7k5B)CmWOyzNw$&{%<1{Oh;c3}S3MI{N%l?FC zJ)IMa=b18#S3^}5@pS0jWPxI%hT{qkm7)e2b|r2F9*|mJ67^k;O{TFNY;5$ z+73A%AuA{ax*G+kyclRh3G+ZDiU7sqT?=)j;AYaRQQi5#LC2Vby#}|o?0&vK#`%8f z;8}TKM)9g(ME5s&3p8C08~f3rTiICKXY2Xe+tbXTkmgo}!xP1}BE^HFL;W~QpEAcVsEhOrB$-*D%kFNPV;d+QqQR7Kb=va znLm^ct*EuDg#V0ldKn%J7XUYk^aj9p&r}G!pM7fZbP~|}fptLo0wMZwXK0|7WT&1JO(b^jZO?~k&yH?3k3ev6(9Dh| zz-;G!9r&(YM?=MWw&&QsKsSH!84p5JKC!jIyqP!sQqUsisH?w5Q>O@K_95yO<*AN4 z48(?W=T&uaKiD)x8W|$8K7alTXfPX??rwh9=KR|%rxMksqi4zdM$}mL(7$;;v!!`< zW|m0^Df(GV;t7!!+}TN0VmtChCPi(puh-zUM5QtY%H4>ym=Kdfs0VGmHJP{L<#UxZ zEPS0AQ^|6kQexCdYXV(=HJ}gl6C95RX)~mt1`s;5x($4;UV6+AhO;TO>iT}NkSee$ z!47%L*#_8Ah1gC~vZD$@#1b}i=&89t``zVc?~b$PgFs#KrIK-QtAix*eF{#)P!^$skd z-XalhO%oq4>Sx61=M~6Un5k|y*6>kG_Aymm#z4qK|H^cBbt?}&cBsy+ANt6GQ*{5B zbsQNubfPh7`j9(mu2Ri2-_VVM*bS@yYf%L)_k(-Zyg&`^pL>ehUmz!H^yw3p+0x7H z6LS@b8A|DHlUUPK6?msVc-th@hs7ol1OyMXvq_rg} zM3dV1wP(^ep8TwHilzl*2@}vMC0BvAUsnyHc%y$;!r~>nf z>M9yDm)o7w{7q(dkZi$wwf8VE&|6dO0d{H@O=1^}yq0@5uxZhot~09Oyb#3FL(3>P zoJJ~dX+Tc*8t9;`#OMBdr}ks6t56`_NX9rUuR-)=SkkK|{Lyz6v7$y<8dz}z`q-UR zXpcK$9i2=9OI)CgAX54-C_vTogMqN$%3LV zOS)PKK}hkn$17Zqe?duv$XACnnOV`&Pcl4>96g_Ly{nuatUax@yCO|C$|x~>$6|)x zbGEB*#cEGJQOsRu(9-PKKA)4_e9?4FFOl{#1*H9%okU3UM3>_OYPmN=t*3xKdsl8I z%ws)!?c~aNvd7BtO1ydZsRKM+tp5WIG)W+#n?yhvjwI%xChf|OjPd>ba!dCj5#-%M zA>Cq~)>_AN9A$vx*2wj)Pr*WNzea$=4K{iB(lx;ez3=Tv1UGn@1hC`twBBgOhMiO# zMegm|ix;M9eqkF0<)=?4>rnS_DVb=N43+$Jwt`pp1BWMWfI@l6(!~H@@tqppAt)M& zK@tP7WV2SZ2x%f{AG=&x?ObB{`JASEtDWD^vU?(ESy2tcU?y?<=}{x^9o_;C>goB{ zv5??H#p7q)M^?b_SC2+jsc8KI~E7d)G5lI@a+7G>l0m3}zaYzICRnwV*<$c)z9tFP3I{tIyS zq4LsizboM6Ce0DUvi!YX$#a~eY+69cMUO&cM^+IQm0f85(RqK{T9a2)3OnZqM5x4n zR;*!5Rtk~jOSlEy8q)sq`=nDFC11(hjQ08qxGElsy;*}IrU8dIaEga@gWcS?R(M6iUMLxJ-dNlTa;6flz2I6KS$AxAeR z?~#cty3?~a$t0%Z+|{DgXICGp?BV9#lq}~Tbpz872RAiJ76X6gMgIf0sXOVq1v6KR$Ys`h@81rlVXbelA5K@(-$PGsRfo+Y6h$LrG5;w+CX%+Qvo2@T6U& zpJtCh`Hp{9W385&=*TaVP(mqgSEozEa-uR5%EDEylP%L`nobo8xZX_KXT#coYg($# z;Z8)v`PAH4xrjyL)6fMbXWz*)UBI#&Y@>MqaMVZ%*kfvKB=owch(onoM20pm@r0gNn zEk;yWLB&?nI65UhAZU6zrnj%?F90uu^ZjXG8&$s1sOFh49L9SrH`Lhpw0OG!p(1lm z4Dh;nRZ&z-PJA0Fawt+beAW@QF64%v8hAS5QlK|Fq;6FlE#CE>rs_?@j?Q&uSKE2U zlFVqc_aDS8!N@z@C~fNPzX0!dR==x=%<_vWaaxN^p3Ogz`}bRle1bM~IC2#OgP$#0 zee@{O;W5{mg9(toZjizO-E_s=fYj94qqSfiy5KfkcFWWYAI1Bt7%Y8+=@prKi|uU@ z(#uTf$R}+)YQMd0g8SNAFwtp|f8FsIz2m)M^(1xtcY9(Fjm}b|t@{yj&n_1^|08Uv z=`?2LTu>N@?nkSourQn-BvFqya0d7kZS$?J&-b?BW{w~9*Kbh`3dc-~PHHR(yFQ0? zr~+e7QTi9{Vr;!G9OKe_wVT=`F<)asRuc-8L#88Zyp_E`l})D%m|~s}HDj_{^S(%5QdoI|DjSM!c#mn2hw171-bp&e7*jc4ZmK8W!@7LF!G3(8_YkI+0oU%Zqp%5PYknHVKKmdGaQ^?eAH6 zdD!yy3u^`!XMFJTJ=TEt;?OTmt;gwNIX)^ghmie_&yK|fY{Ek~t{(?On1XFl)gKX~ zkawoe-UaN;C61>DYL_n6=j4%jo7pz4(jp2DV9n-nM=*YS`K=Jo(v+`n@14Gi(F+T8 zvSa3nEaoG%d8$plI(LLtvrw5T<6u)=6FNiQs zJG^-Ay339KBY(z5z&sIV#pJrAW3Bh*g*`~<%6?YK%%v3et$Sfsu=`qmN zbUS56j6J8{>mjo0=kOzB>6p4R+~+A`X?`iLef1)Fi-{`M+s=Ob^-p6q=90j*F-}M8 z5>Xh@Z1DCbiaV9{&%M3I;?{gQl$C_$udaK1oG2`7V!ZeR1?dNn+7v>6^VEf)A`4d- z!8|mWtHK9k$xaeM^Th@g&XfW!!oluof{=V32L$r05j-wC7WO9gk2US(`5o#3w4pq_ z9Cu#NXKr~5we1?ASD`WkJ3fyEkLDLAyg@orW-Y+2R!c)z-p~~4JhA0KYVpv($=u(LH;UYOO7rn0?sHEscUe;~z$( zwCfOIE(MuG5BOX-*pEK(5LNFtlmY9+7W*6>^ z{RP|w0fjolj|UvuKdpOZbP6?J=Q@gX=u2#0v`XD_d@Nj&@1pW!`I8d4>-J{?J(B0n zUh^){vfne4Svu^9qh!cqf&Qdbs@8s|9DF&AIB0-|TDw4crVP^4} zZHAf+IhXdUcf5|WEnxLu9vGI4Wf@j4((U6s4D52wxnvYS3q4AZm=~jOnc;(sA};mQ zW{9(UzqW7r-dd4ndjTo|j{h93P>T%DE9ydAm+{Z{Fv#qWguZbs)vGWZ4wX{x#-X!X zuC7;^e^%N$w|T50Q8Fo)%VIcJ5G|{l9pbggmO#jWj>9Pgq(j-WfI<=~#PnvglnER) zRDrP@>o3JGEhFEYrb2xzQsm7hbD8Z0}#dSdN*=hDt#Egs?A0tGDZfo8td%E^So|9oxSN&8DL!kUhJ*hOV~AfG zphoU22q@8#Uc!{*13zL*XNkW_5)p@`D35U37QZ-s*tnvX?AZ8B%vwriR$ug%Z37wr zCJg`6a;7~8b<|}7@@Z!)zk98=G4M_&v=JHavfUQ7Cm`6~*Na6&Xf#yvy;TF@M@=L? zbn|A%+1?Cl4*#3#b3=e298wraW_zrdKDRtdo&03fhjqNZ?3)IghN9Fhzmcc1Wh_Q* zoA92;cbs^l&htMVroIYe6ZVkZ62qYis*yb9R6Gdp8O?J7GdY8lFFk&?e=eP+iWt8& zh?s+=<#{_Wy6y2*cy;vCFuy^MPoOov*TmZqw^csPs4fw? zz}ptKNoIitV&G$@at6A$s52`~tIAkX5!BIMa}*y8i0jk9zxUlgNzk{b_%c?1FurN` zRz3HUrxDu1Q#(iVMm@ixs)|)H+YSvO_`&WPnWWavHlU(`LIQtAXzAqA~ad} zDgvksZvSdPu)SK1sDQqenxJy~aoN@xTBMLRz&o{v*qh34x{zY@C)>L!DE7 zL7lg(OtXb)agVgQtm56`qP)=~tX}Z~Qh;}}wEeEEzk$VUOLNhTuob$jv9Ne$vbjjR zx}qlcyUTP-W2%7BB#W?W(7^;NIWPsBv(#1%pMP&7IPf#-g!lDWfcHHIs_8_V=%KLU zDc!W;rWLRF#4i3nug~~gZgLXd^>u*vT5wYF^z`h%0KueG^Mr>R{z+Exhm~v~-1~90 zzkt%TKrBjgMmSTNS+rSsmT#@!u%(;(=SR7IrVESPG?*$ zLDNsrY*>@G*)R5N_9524_UwgVD@eIGa?}usBG=jr+uaM;POLNMsm!pzDf+fa+V;T* zTl^89JIx1Qe|n~=I6!C1*(IRRDC9yWxQgab+&9l%6=M95rrO1AzO&cBHHWOWX=1hV zZ6KK8WDWvK3*2%M;NC7C8dQRpy~y!{+gD0F{0_xr7p(`7S?h2&R?FYLO|GbUvcK+# zs0rOD%mvk(i=1_e^9Y)JcmT2nnz8uM#X5q~x;${=y&7E{bTgx3vJ5C{urX>f>pS4n zPX05pwQ8_OmN!f>^#MDjVK!tBM}NO(#BuOg6MKS|u0yx@nw1pKs0^C*M>N-9QI?3ClO`cs^TnT-MUL z2dw{Xx)+?xByu1NWY>kp>#~y*CNI#lBBaj~%x}wmVDQ`>yZ7r@@@=2U(D(XTx(gqm zPe_CM;%*q}fDzdHW3Qzc|mQ>rK`9n#|;^0S7JI3 z90k@7L7{W@b6{f#*a7B57JmgA4Ir1Ik=T(E?swbAG5-oh+hfd49E8jWn78wXApQYg zPq3|0tc;D;DNgmyLQ?52=}(0jDEg=xST&~0;fi-9-Of;WB2@42^_0lDwkbmF;YU{8 zpRb$MqsS$PkdIQooSY3?g(kCEjOtw(iV8uflikbMT2;^7k>jOXJt3hLcKjE1PBODV zsQ_#HtvjiPlTG1?T9iUnZF?Sx^@w-r{Fr{pkEt_g{@>YKQQDv~BmPsVLj}pqTIjxN z4RQugqHo+Uu<+m+BNus+1^|#)Eg!jWnowqXd?JFq{@PX37fW(=|F+xn#Y5HRxZB*W z%0%C;!0$L6!L9GPvhbY7hG2u`>5oCrT4HCKU3`p;}!=@{q4!H#PEh#73)n63SG$qLh1oRBBcyn)a@01>@ zAKJSQ=QjxM_Q(g;@n#9#jW%g{PLrc|ua?9esFK`tS0s2I&t6+Oh`sMN_>?v$d`vL% z7rejXBli~ts?~8sd;!75*96Rb-)Z^In1`?%Y3ruDO!pyCQ@2bC7qT@Riw!0d^&33d zfI!=Ri*C~b8wtU>Qp_-=pNEA#sE!19#xIzHQPN@Avk4WomA`=a(!74(4rAKI@f7>z z6ODw$ira?$M|8(j-wfXmuf7hjLpN z4#;1u%OCTt-F%p7F3GT3NbP(}R}@iMn1A?UhcVCgbD|^>!6{FWL^ze6;zkgsftCmZg zkv_1$MF?#-V{v9ehxFZ*zHO973riK?kE3N43OqIP0znICk?a_Nmdb2xpDm+QKE2m~ zw{QZYxm2Ug4B7uuX3EJ+;ukak94Z2TC{tA*#^*JHuT{i0NJNplf#fRMio4-ry(xo> zEX^*D4%na&m^4eK_A(rU*Jr@YR-VY5f`%|k31XRjk;)Vf$^0odSopB(a-Tm5Own+% zbiBAs6Ya_U#%jE%Ek>qW%|P7qjaNmE@Ilq=n?0sME-}#_8)<9bh=esA)WDw9rU7<| z3nGdsC}vHfcx#07-xWf>?Q!vkVrveKndt^|A*mel8v0<}6efyrLY--ImI1fM!UN3KQVj*_R2aO4D9TQ`pKX z-UCS#WbkRkUME;Zr|zzBnxG;=L{4Lx}d&l!_VolePf4 zoSec^IWyR<-mE7S)rx5MIv6$Xve=30bL#YKeom1oWg6>`v zya->8J)^Am z`YW#ljOvd#3kyqB!%p8p4(3Hp?S@1%au7*x#})%|yYne?klh0Tph0)=f5V}dn13m^ z-Q8RyB3vhpd=U54^-&p*=QHvyR=YWBQ=KP5jr$xs7?tsV2FB6Fq}zB$zT^r~WEZi=QW{UsN$yK1XWm z-z=IaK-`x1;Z*W^OCoT?`P4o)%3DE53Nj#HKdP)NXUadpgxuljiKFHJKsjDLeb5kE zv3^&Y4q1$NM^j5n@(tKawd!}C@HX6T!ZY7wSC_59ywW?9;o)rQqq=Js>}u1@M_wUo zaF!Q{W)|*7yJVCs7dr}0f?Fmx)?}>;*ZA4&jqm8;kF6< zMP}Ylv-JF(K?8C1pd)-#ZGnTbf7<_Su0%_?AMRXM@>CPEB$4rs*+-jgU>ryO_7?GW zP(m#tal7CgTjX0=KK&a~W)zk3I0J9t8QMoR1DB5(3PK?HBD13helY$y{03p zj#4GjZvr(OwdQdDgo%&CtoH|vn}y44S5>@}Dm5K})D7Hr0ESz%D&dzOs%hTk-GH;8 zCx?2H5AD7+`oh5a(KbWf;E);GNhYYsF6nS6y;v{WIeUcLcrtUz@!OM2<_>(?3R>8! zxSHi=9y@-3a}WUcD+a{toQiEBbDr~mH%b*C`wb=T|is=6gnvT&i4{mQ#XEm>}jwuR_3(09E#A3hGP4rT_gg# zg}%LO#nqJYc5*ehn0;`H-0l|wl1G|Bd4ZhV{qjT$zRv`Ydjm^eO7n(=NgWV<(mgMT z`Bu2G2Bj zg+@u3iobwMG_5*Mf`#yzrM=A*v!XO>Z>2ZsOQ~_(&=)=M$uEh!l6S)Z$v(5{v0v{k zwWr=8?NmIpYolxV9>qsj&urCk_!ijt)|K5gS-6A`&-!Ou0iKdqK+!1 z2)`hQG`%tfsqll1$pVRTyoX;&V>9 zWhibk*>8OBt-WhH#?jL{8GB^% z4mp#n6)lN&AcDkyi0OT58S(h7n7Vv%EERIER+ddCVVA_e@R%k)0V?}+?cv*@#b_y8 zuS=YlNfmznqX3LybTlJ6th_8ufP-hJW*!=2->D2KF-$7ehtc>OIB#S9Ax`b3`n-=||&F95xM?$S?f*C}R zeQibJ8NPD7K{oPrX%l~#ncFR_qn_d&(=1vXjQxa#3|e=>&%Kh54p%J26|Q=fn^7^R zw~3x4%{^$!Bo43GMimHX+O6ZsC>2%S=joD@Xp#dmVs$1N_vGHqo~Y|!v&9+ZBkJXC z+-7JRcRuI82QM)S@PpVztpm`w-r*M2&qf7Bf;!{tZPK-M4rR}Nw;TQukhlLH{*+ZW z##A@AVrV?(EXr|M?7PM4dvfg=%|xf7!>rv-M!Z^>oMYQ6;h^SUz@yE-fWC1=sl0zv z1$4-5I{uNs)a}VkF4LYp#MbO}|e#kKC_YWg_*=XCi(pCHu=}PWZ00 zf1=l?BJw~WcP&xHz7BmwE#fm7E~TeHPf|zQ-f~#aj@7YJ+Y>aTn_=J4)2 zqsQ|SYh^*`LoRco2<`-V;=cfs$n(MREbROBuy(4S&4;JLQ0QZr#Q}(6FmPu=IPAjv zo99<7tt@>>Jk}PV&ZjPLegMnhzHhMJ~$Bt)}ZYbR%R=%IlKm#k^)U>RaC=I_NX_v*6#u zsg|hYBd7+TD;1NGqqT*Yg6-Cju`ZV(YYTPpntw?8HPJRubrrzv35`XKBit*ReYY^WF;kJM>`Vy)0N6hixA$C8n zDS&Gl(POsW21W(|T@|2SH+NiO{_QHm7YD|HRZDaDgIsIxg{&#IjkF~xaaZZAys=xq z(qQIqBJM$)yCQ@8U7E`ctsks5#ipHhwn?53`#0^a`;UFuLPu) zDNd-pxBRsdvyn=hc)`0gJKsLYGSAZA7gs4KDH3gO5NOcN^5%(e-`Q5kZZC6PvFj7m zGMkn8=Osi)(ylLcu6qMe#Fr%eWV=Tgjk!0AZYdt4VF0okcn5Q!7Bm&;ZgUiD2Ryi9 zW=+ZyvLB&{rgx9b)s9Is#>TOeUG_}Sw*T@Do8GZ%q`m>UFM5XN7frtvtAImOzq} zEVTt6U{U6Ftw$tNe&TsBiporsjxv|8_u`cppJa{?NA|eM{{oKE(JpHPP?OTrNF{#O zZ-B^yyZ@EiHnN~HoK?iFu`#J~-t>#X-#rw)DZ*L#rKeA-ot5 z-qD490p!SMs+Gmaf5$g%Y8NcnpY6=FSO(leG}NKLJm$Xjl50T&6h`v&hqNG&2SvXe zd-4=e`axyCRjKDdL^U!MOc`j*AjF!CB1{%gTOIeNgso+eBe~JhVqJ4J5PEY`WK?m0U z{#WB}hs~Xjl|Tn^W(UW33tW&hp@Ct0%*|?@YeThPSIatkf$EM16*8&z2~ai0Pg0u| z%GG@V+I{4~i_59BaqZCJyNv30Drh{D*B^lCuB%>0&1y~;!}|UL7MxTKJ@cy8_Pz}! zXW6CrAATCF{Di8+9%?`QU$nhtRGZN8JnLC&&bj7dZV`_E zq3Z*EW#q7m4@9Xi;E>q#lo@Q_s>mY#0>1bWw8|ItOsSgiyq)uTJ-cEx0UNW640o-2 z>l){tPCmIVgk0IN5KBqzCziqkCg%$tlPJVoRJC!t1$*{X%z(HAzES=z;Zkr7DXD(c zQE#XC@LA2VUuo@+Gr984HIJ^k(jN|9g|tozIFCkc3f7x?!%E9n zM8X|2HXSlrVOmA>a**?8U_p3#AfSJanI81{Qp!O3i_;XR1x`reMe)+pzDCiBPMU|1Tz8fC{w{7JQB9?>6(A!t0UlF% z;<*x2n`|})*Kc?va(A%E$rQu09|wt<{$+)75Zs(Jp?ddwZvE(C37uV>Xw*jU)L(!J z=QI07#MR9a-}L0~jOI77iv`%IlT(RR>JK@NqBcxgZI6Uv=MP*C-G>O9n0t2$IDC5< z@}3TXNr;1X1DqWZ?07h`djPWWDyrXdX58%_`@eiPEW(+s4w~o9&F3D;ajFWi7nsjH zvv;QJwtB~56V(uIRyVI@@^NcHEkOLdGH)`v?n_Cz!B`=s`F^X_wZ2d!?|h`a^kgC= zYIQ-+?KO!YSVkdi4X(;=U$zS!=N+P*xif5l1e9Gholt^+ZgGk>Htnz5EQ{n=s+9u!Np z>E=K<2nj_xH042HyT|Qptj5oVmO({*;6@4=Jael_ze*r-MqUIqb#L`~? z~f;x>c70MXSo^18g6q~i*UPCE_; z65{XszVCJ0KhTE5?smRI!}Rc<@P&0w>f|N|HbpKZp?>6K`Bt1?>J-DiqvY+y+)*p@ zj|NoNlTepQ#!)}Vz-2Nj_}YjjCGVV%tmy(LNp@4)O*R=S%pw9AE}+R7A~inSxd9|Q zP&@Gt#%PAKi=oFnRd``zF1Phfb#b9g!p|ZfjytQXXYJT0sy8n$z)hKk*gYR>^__No z+`ssb;m_e@-8kj-$#65eG|u4y2uBx<=fN?JqSfp`-T#YqjTKJ_?~r(v+#g5*g(Hqq zW{AGlWevJnh)!82+0Q&{RL$oBoIrr(5UoZ7stL-*#aQCm+(IkX9d zE3~6tLm1z7@odQ7=dgXG4(C6AW%T8?`L_K=4hHTmdqOMbJRP>=-Iv;I+0<@NWWVhB zW>pK>IT%DJWH;48J9QjQQ_V3n6G<%uw{`C*Tt~)?dRc!bQpn!`~;=L zBT}qba5Zr#d8ZK$YeqIuvhLb1Gfy2h^MyjXpgZZ&7?YvBGvfeXt88PblZ{*7B!YWJ z3nCU3yYdig1;AZe%KuSh{C10Za05E>j$x_c2RcbYb9!sVJFDxiF3d<8_gC#bouJtH z!qJiK&wmj$(k@0Hx~d7vbbP~D^!CEjltW6V!WR$9|8RgMU(0;nHH8!$1m)%mGTBK9 z+$U}cQcLd0fE|QSgbKfY!=Nw8Jji#*qQ=O%2a$xz&?3^T6p1&9i5`H1M4TD-4}YfERpNFm31x}yr4p;3R#4SE2=`T(P|DJ=wa3s@ z=|RN)yj}k*#_kQOs2}i(??E~EK$0y1d%?2fQER06d72It(<4(zMGZQV6+8di)Zy3|xb z3dsdc3Il3fS}8Rp8}{{8e*rl)!{$yIh-T*?&?_&fS6$|)zYhi{r&s?skCR)88{Twh z*>Lp<6{dL4$M_HzQ8feJzV_PTFe)yavuqn+-e`I4g4sey$e|$mNl_Gw zQQ~!ekpsa#6TA5*lqL4P+l%nT1xDr@z zm3QG8Ae{b=T=E~b4aKk=oKc2OTa&8^L+j*dJf-(^8$MjKKYW{szf3FGr{fH@_8N{5 zT$k{wxhX;=uU4z)HO}LhydIAb8tGJFI>&OZEw&!RDdjmW@|Uz1GOzjfFd7Fx`{rUB zf11?}{n=B>M+OB^tutA&$_Ofn0udOWtw z0|LXkNpJ-aFd^ZYGDFdBCM9LBA41Fp15tY)gUI7^$tOxcF=b{#(&KQZ1Kfwt^k?#X zwRQZ6zdJmV;16`{*ek_HwbMIK4Kf0+PaA4Oa!?Vp6sV~2x_|PP9BBO|Dm& zE8q!^BfEjav~1PAupf{lMUa_{TJI)O{f6snlC5xqLxzYjeN5w2pc7ha9ZHqg2rFLJkg{Xqs6+>K>BUd!C2?H%2+9jh`W$ed*!vpP*s zH#^UyFt0_(iI|7mGdN%L3W@amw!t&BK@p2n@>PjcF%E`-9ykc6;9pR~pJM z(<*(Bzlp}^Fu+>qek^8Y30zjc+n*%*Gay(spS|vjv4^QLPcD`~eto!1^kNZ<5T>l~ ztiT)2DLsO!7EysVE4{seBl8oTv<-LUR@Jklc!<^Fk_?9|ZcU>0sVj;Y9c>Rz1_nJ4 zZtTw8tDp$=K>j|!v+t){_+`YfCW!nf-=s{kSwqhYA!3kO0i2Ym)7#spSM~}AQR*jJ9PK}9$o9SRTwxrcdBW4r)(y*M>ku)u%e^U5h>n@ z+3|y6$Y5RbUk6V6hwWJn7=1FM;Ixs*1p2GHa?=S56Do~F9qr!e42E!krPhalYE9ZJ zS+_o3WF}B@m&l#R8rN{IuEIu^=fXO)ls%Qt$0A%+`$-ij)I(_r)ZztC4p)A@q6sY* zym6<RQAsqZ=*Ih&<8fCxrhT$PjfxQOv zSy-m=vYA%(*9)ek)vrx24&2X~os9ELDkyBjCoUwr&g*NDNu)}8(0cL!HU5~+z{|it zRngu_JbwY)w^J=v*vge+dXHcOQxCM}oP5oZS+U>Cf(Jzpt0ggXf_KdnM^pVKddR)k zucq(Ou#!lYyxVyRTkEh1xl!eezwi*$L)5N*&JyWW;a3-OtiK4H^+`GrxIu6<#$xJN z1iMVoe_8E4Yn5WYb#k{z8a$(qw(8o%G)^|(t9U%U)Uu`WEu-uEGsmd`|IFb11$ePB zZ$}?7LVb5tcPVTs=FV?^_X@RHeg< z{jyV^4Be6Ez4ncs2h7$zU$UElM$)V;G~DbydGXJyVKsMJ*o}DSuOg@j1NOo2Z_=US z{A3)w8c}-Yl1nb~2gn z4p4QJo1JEYSJMYv#=ebChP74GY~Gxl4Efzohm|)^P-utku**hfK13aXN z4;6~+Y%;bwWu+2VCD#QNYL+ebEZh{>D2o~=pVU&=MP({w9DislMe+aJe$aOnzn|5+apI1iwK|gibcBaC47-NT9@3kD;Gp9#Q7nQ=mp(qC~a(fY|g|5;J9jQJYy@ z`uve7x`hJ|PPrtmYt^SeSG%0!*G9w{-uZ%vswY$RHSsK^dIa%xdwi41D^f1cGwncH zvPWjm3Hz-5BBZ4iZUI%=|L|PH9&(LcZ?lU4S224BDuMCC z&|(QS7gE+NhAE?r_8oJ@HmM`TQdXBXjflZk%Y6)cb%^e)aRq>IOdyR?+4;)C;}1$U zJ7E-fb`^Y@bPvX?3r+|&)?(3z?J=m**YXt^wl+I&!C$v6UfFY(=o!zs3Vh=3 zlB8OcmtIG>%b!Fa-Xe3wvYs%@$lI&3Gg0vEuC~Pe1(4_c1$0*au<@(i*_dB*K(UDQ z^vpWb%wqmH6~C6^1)!k7;XX#Lj{3*d0v>2Gv%YZ6L&!E|6iqsqzK5s!Xrh^pFvQevuC>$CYSG^JIT-cetdm&g*9K3X<#(kVCNrUIQe*x3n-Q2Nd=5k(odoFM` z#Rx9U|9U&3WQwA)Y+1eKH2V0u2901>r~Egq(7lhBz+LHu&Rd^shP2M-;{BCUUv8J! z7p<|lkpr}U0dI%n4wm;yjTB5kg-}Fk)s?yJoq>s^PdonJ$WE(jxWc#^q@=BX{`>-J zvR>tW!}%=}@vW9%NwNgBx;qeK$M;Loc&m}dr^JiVrH${J!g+)K&Ey!P6Ztn z(OZq)Wi#UEn1|F_|5R~IO$rgik?5St-R74%rfAGQqF$)xh4x3wE;CdS39= z->9;O9XKKQ-}@&2T`K(F?mSuhxyk5RYi*ppRHVNmALG=q7j1gZhj;SIm4lH3$7xy7 zGNxnMDiUzZ*kipjn)TekHJdzOyJdlAG3srCVn?~v@qSGM29*CH2)vVWSYvH$6#EOP zXuG$S`e%uQ)jQA`tcxB(T4c5P1PuZuX&bZDE4`fW*#dO$Q%gw%SF2`u%RB+C5N zlpa`b`=fRsts1##x=@ii>rgv!ezom_98WZso>$j%v#THgCL)&%)OPI|^e)s4;MPe# zenzqzTm)GInwr~dGR)ugp|2Je;~xyz9in1_e3M$SM8=J{TvS$#ww8_u8g(=hho2v& z4%i8HB7~D4&BKt8OG-=RcrtxW+maFoIP&dI75|Vb-)CC7e*1KCzxNz+ixJ#?-p&x2 zVRE0_4v;m_GkeEfLM^yGCRES$U+at5cT2x6Rjrb}?__Uv%sQP#*jFxXa}dJ8p{RqV zeTa~`CDeV%nF5_QpVUDtoDOc;WZBw2>3-ogWJ8h?yb8N5CI(zKl+doo8KdNllk8Gy zL@n)`x+0`y;eG4*iGYJ#GSt@f_QRqDFEVLs?XauZGs2Sis`HJ`_!c2zH|{FVtay@O z!F#N;=j!3l)@jSIBhc}p#e0w6=Qmuii@yipmbGOTPTiw?<-ClZ|z#ENU+h@rHqAM@RMO zyCiioY4J^v+Usbzk$^Wm|cA+!#3 z1v4&U{VN80x;~C62`)w%77cq|>vefz9*@yyDS_u#H!(g=Ex@tQ9FXbhDC(R!KCxS7 z75xw|Ng5*NLkg6YcV+4h{MCpe5fU9 z?%bBwx5T8j-98xs%aQ%x+YJ3DXz}kBzm%GYR=@2b((N^6x}njUXxNejg++{`;@s26 z33$1yhV-I|q(nEjyXpq^$ld))>Vq-f5=Z+dLLB^IvA^9A1?&V$H@I|v0Wlv(!g*W5 zrt-Xf+#2V<#NpdNwb1$qPhYSP{AtFQE6YxZh{zT@f&%gGr2fS0D*S^Az$`&5i0x*C z-q|kR$LGz43mB!sf?kV3Q6Uvcw|;pjg22!V7xFqcuaCHJK?#Rb)XrVKir4Sqj{E?_ z?cugA!|QPmUDgNF^e~Usfx?6Zb?{@D0t)r;0H7#(pgL2jWRdC@N0_ENheY(`yfmAk zgm|D~A1Xp`2g$QKX5&O@=}5m^z&pl$Msk-^6Wr=OY793Q;?d+(@_yvlj#AJ928@?! z{wpTuBNW4msJ#cB{1CE=V%V8RB>g0N%1{Zr;Hv%oCTse_8QR1hpggSUs49JraoRfI zAw1u}D~*`@)RGlWAsT8J)@5nWhUYtNrWDE`cABS=1-16%+Dn{!$mwzpYXxIe?VUAC z1p+MOcrUSuDMC#T8q(}fq&!FZv6v2gkMRBiLe*Sat;e|Ef8niAp0ZDzM#q~hew!RLDOjjF7Cp`AS}PQ`N+@yumf`J~CYwq- zoEaDk6#YVA5xixVlQQ|xCqJ|0=96lZInm4U1n>ST<^J`o0ZX0*BTSv8scwN=a66Mn0Ktt<=hr9zi9j|&#xs|{qg+q)1%tdG=cJzSmYo@7I&0W?b0kyZ`LWzV{(WbeiE*^s^fXInR$2}Z?wza>JR~k4pBn@2DpIvl;_e3sClhPERa3su za~tZGR+Zdl+P~LAIOM;%W{Hgv1{vY(RPB6X*5-5_7HZ+Np%oVePO zsvkc%P8v>SpalF`5HB4_7lfND?)twRe;?%S=oh2xbZNR?Q`*k%hja9QojBoASDPPz@SP}~RU!3;hkJ&>&4lty;&TR`; zqiB*2k6V$j4x$T%e%sL=1uvC;jp%zgD;He7Bc@ztT{m=;X3Zy{u`##ui&cP={w z`{M1Cppu&lS-(C~r5ASY&cidms4UkX$6#JbwEfES$Uso%hOHc{aoM`ybB_2=YS0up zgEbQ4#p9y?WJ7PV#ji>SJ;V4?Oo^Bo&gRYR0!<~UCmMjNa>j#6;ZOs0vOd*}PoCq8 z&${2(#V86zyS4CaQu(%o413vlogzM-B~m+mpvC?m2=FYUNzQ%GAx#d}2`Mf(R$cRp zn}0vju7$wbXc9b`9)KxeM4WcQDdXrKI2mbHfZm-@eGCDajA+4d=l=$vM+Y6+1b)LYle;UqNq^dVQ`AY|ol%D$0|;a&EMUBD|F9vfxw8 zJO9|YlK?X>$9nzlrtWC~75tv}(9pm4~lxt`r#L)Oi4k)!$ia=WdBF8)Yj z0Ng*7G3+|*nlUdp9Di}XPUO}=yd+%%;t#SjA7gasoO5*l6+`}&1OAH#_;0DhN1AZ1 zt5?(n6LT{VzqvF%M<4pAz492BbjKGl&(NR251ml)SfWqEHw;9I+hX1bJStgOY@Hr@96^USUi2TM>W&vl4=l`tl^ikf%f|6S?_E;M2h6v4rO7w8h;NJB3 z*;J1ga#gzw%h&(fm$T|1`h|yY_7a@7XQb?}NgPsSQE;SXS&ntbFs;^&0agE%YdzF_ zJqhFNrO^@3-tt5s<`M?skB(eFcV?UVCMvaDEusGW%nVW-!5 zNkL{925~q?W!q1;tpA0iKOmv9Had+vWAY-q+l7)2U5E7dGU#H0`cW2+tWncYj~ z{w}S$)ggf;nvus()8)}8Fr!W1XxWG^d`-~3Xqj2ppGcl>x!kEe$cBr{1gp7hp-mv0 z8kjwfqm{B#Q~hijThaL7MQ<{3E!jLzX8CIFQxsjc= z8Pf8~`{A52g!p@GcnbWSv6Ct zTG-~C0X+Bg(6QMSZhL`X*Lbn|AMh84Q2bwj@Su~m@m(Wd(X$H%KJ;He=Gr|OBRDY` z&K3YzNIE9dg$}RY#cxC=eF7$%8!TlKj%NkskGd5Z&@ROfCfxPk?9!InbestKNUt1i+Bi!5p?U!94QU1R-3lZi%huhf+Qbvj!9+gkshK0GqmrWM+b z!~01nkWTS>{N|AiD}F7?!>u{AjcbOMc%Fwv3ZH=Uz+Q`DE9K^@Le!x_vRN|DwO%!j zkF+=b){A!$6eBhsz-~aED4i(vkl3AW+WdFiL#eSRkA8jXI(WoY&N8_6)QC2a<84cR zofjV(dVp#Wjs3Ok@OapUT;E1iF^;-`e*%gtO&p($ptA#D&te_tzW?WWhn%U9?W|iP zjDD|i)ORr3GrbZG`%#FUI3F>e;WpWJOdJZBg|I0wJ1J^LTn5g*yrG`<&*Gl7D~FJF z^08f>Z9FXnIr4f%%C=oAy7dT$I2%kqO?^j3i>#!UpCXhPS9Y~DNP>T_o}a#E;6FuV zE&EByan*$cp$zFc>2YynnH6Ax<&8d5U!IFJ4Z!ofU8lvJ-Flc83fB_qBj4zvI(KHJ zqbD?v=Xw>7E(pIjia2K$XuuQAyx#>V^;GCwFsj9)e=bKZ`>S~*2EPUw= z(IuBOv!>U9YaYUB1RBqr;Qoz@QDumZ&GGBpZbH85>}Qj6eB@f$yMb-A_>=KG^V(jq zJ6WS*6Q4~qPEVc~Z3-&kH5R^|AJui)YJ#&$^FD`UVrlYNP zNveK@ondy|ja#}%xL~y$9HwUn zxB`;1ygtTM72Z7#-};+H#!r`D#A`b@4>dHATUy9;)qZh;st(ZNsw;}d3o&Kp&<|9X zeQ+L5UU#>ahdkur->%>{ghC2#In|k2EeY?}v?|jfj?JpgJIya;Xgc+TY1rz79GvR= zv_^H~1IX3g7Xp@Ua$seXPE6jxbx9IN_@gNC+_bF5GEdn{XQH&&^&? z>eHOtU+66Zp3;$=3RFV_tj)@1v5Cg;ET2F(+O6SD+890oB6nVIv6?g$?@~#1tuLx> zM@4xNc*e4y4*Fd6<0iw%#<8rbMA&ifs?9+6+d);=>NFCALWK(s;s#yiQ#%liQ5&=_V%`Wg)0;L)n2-n2xCbFM~0@dJA;fo%4LDL*6`6*><+~WR7&m zH#)X!*yactjDv<}X)4Ez2F!y2e*|ebj?2+wx2?~*y?rJ`3kcd6ZCX`3xq{YLzH~V> z9Ohesi0mt_To&T}-M*SD#R$IDr0<8F(@Gmcr&CD7iRFJOF?Kwp?jU_U{U7IpuE;)o zWmb@yif8x;6bmeK8_3D4AfE-M^TCEExl__j<0TCyQw?b;@c<>VF(~36GWw@TgV%4| zFxc6)_|EqqP?rxI>;Yl$m(tT=G*%Fh=2K=6%zBP<9UjX}m(c#HSahvnU}EUj*I+xo zo!|{{9yLD?8&G9Kvlh8`MN4~N$>v0OE-%kcrW;FsMjPO5P`x?+;LKHUjsR`~OAUa-Oq(dDQ1 zmD~+=Aw)m1`z7whQMK0iZ>ih6e9CwG zNH{WK)7quoc48MP!O_oQrpfMBPwep!AsJj#WyD5g_r-xa)0!MFg}~*!4uMOY6*d1g zBsVAl%^3SVKq2m-E-*Ql;VLEPmzO4qJ;e`}DbI#{hB?y<*qBLj{DUa)d;wD~jcju0 zEme+$PBeu?L_FdKo+!(uh*ln)-8!??f1N0yee}K9LkNH2XbnQ7 zQyhOH4#dn$Os$H+hE;e>@TGv>t!;_*e!G4v(fI|7Z?`pF^u9FyVu3_YZ^Uf0t|pDu;%p_Lj)=&<-VSHTyH&5eNt(MC#DW3aR=mJ&%R9fNlBHT#oTNEk~_%Ix%F)- zbEKY8`ld;{fzy_m2tv;KB-ZTfR943V<@;w!mu=#^`kkRfi-ggBZH&BTy)droF76P) z2`CjayW*dC003(Rzu;P++jLF@(~Uks;j^A!n&;*K|XR0gUCK99KkPdvj`4qjbWA8!RbEJG@LjP+x594%^ ziM{)a-Qmu`gX!V1L9#+fQSV>CNm-7%Yc$BEgW)0#8um89C_SY3Xk(;CCW{+a5u6w{ zMUPKIiXbh>7A-zJuzmmA{?)cj&MbCOZDEHP$ zx&8(}^a5R2-q$dT+pT{^p7)Iz-FaPOq*at@|5J7F&r+JBVkhx+cL=yXlK1#ElL=JinKFbx#rf7ckP0 zv0owrDVTLFn~Ia%zbGq(phRDCPLu0db`SccT*Ch_akIO|XG`eB2Wd7k%J@64W$s^f zz?T04rcju#x1<}pg{@4Z4&Q~T*w;zN%o8ebM9} z+2q?CSRdV0!E!|UMvtq*jSUnP6>lt2vd*40__J`V+OeGO+%33@lPKLN4cWE*TJ0dV zM&g3RM`JS-5TRUMkle6N-XQWM0Hx0co`+GDMd;GkrB024`oGEdlT}^PjvY@U=R8f! zvq6&96{0xyqyaZTJw{h%Q{b$a*=5{1z`q1=*h zNKp^KT6IV%6$iw+;G@+-pVT35bIv%5&&dyI3_bTM&QBKPmmT=;@*7b%BiRf4&-do! zW~ftb)0pPBda`eb6g(eIn#Asq1GUe5ukvKhyzB*+0y+fmTTe^Zd@`;@zL#x|C17hkQsHWTPhXCPNnRXEjy1#9m6hlG$FP8xZ-k?LAiLNrd?R^Tjx$)r1ap z#HlEl7S&;8%WLA9M_{nznyOQ%2V=H>M1xuJ^=zim+p-sgeji+1IvoH674dLiXcN#cCrk(D$GkG3fXp7fac7G?*=%f|;z(1qj` z(bsuBChJ#pa10U@T`i?HY=l$^wGubav-V~^aCeZEvwF(_#hi!3iPf8>;34d^o9?}Kj+Z>UY}gFy8In`uk46GCIS>w%+3Ko zNFLzc$eF7~pHhHcU%v}pI3c7!F8E>mh2xn_9MKe}TNIS}hR{t2A2r89wi=Br_0-XG z2+5osat_n4ac=8tO-xrCF=o~a<>u>B#E3nmNgjZc1O73h6hQj8@V{g`|G>@Q#vfjO z@AWHgT*9HHXhLg-a4f|^-m%*mK1puLM`kW(sArFKfbh23nSv5YKTxKE=R+TCXM-mE zaD8}s>IOlM#{`Lo`yHv=>viZ8Dx@q|IZ(@r8VFx>7B=Y2v@4JKO^5>w6E9)05;q;J zUZ7*AGendGtD1thZ@iN zQ*>}Q#DPrf)u4!?70o?AGgA4L;t;O=9v{*`xAAY`V2tr3e0u~MZZ^9>uukC9NF7Ph zT*}+%@-p?M)+Dk)d1+ANb16=z@%7IG2^+U zNf#Iy%}?3^W$)rq`9qOWuX>>csG&|w??R%#tWU6hG+lKW$hhn%2{8x5hvmXMg~vCdZ|{GV8I)$135g5YNc5RsHDfO11S;M2v%M{oWK!oGXFO1pQvl6PdT`ec^;ItM7UaRj6UfwGXa@Iuxz> ztAbNuKtON}wd=~uoj0>cZMR2*Rr^MMkc;+V+}!sBu}eu47s9Nom(97yS1?0yyD^x- z6qTS+99kfYd{^!gB3HS5`c|cM63HUxwdJSCp}ApgxAYN*$%%Co5v3N18 zF}zrO1Mcd4!CZu3SE*5i|__w*o51$k_n7&J=_E$edYYv_v@s&XuF>Iy;3 z9O@t_mYAo-u=w7hQ}>@8s0TRZ*!V8RTPg-Ofg)m-t;W8H#QlcF`@7^0p-tLm(>e+ zb?obsjwWzBw`Us~Nq2vwcEY{)Ldyik?hXfGi?5=iykOD61^di9F3PV4EZiu{-G5x& zteQ4c&o16;P+M|ZAVW&npxh~#_lhtMNVIF!pjXr5c8*TiHOyiAP;FnAD&$h{z~trJ zOO=l9cg(#RHAciitMSPNSpj!i1sDs;Bi&YQkwr{E^A`9ED97|mA3!P$CUL07kX&|m z@1U@?lf*00nUxe~Z~erZgtbFVVmvM!OXu^HwJ)mWAETU})arR-GU)wQ4^57(AiY#N zrRJf;{(qnxuv8;W7~#KAj{hig{?t!%bIYuc`wvU_B2hysIyR&M&MiSI9Y_`T z*d}2k&6qiBz9)&lw*ocfZ3My$7~`Y07LJ$J?vae?-7>$Ju}OZ6e-vcug@Z&}wXLR< zg;2fyfia{_dPXGlY+8PpyDp)YH1HRb7cIxZc=AJRuq#BVo=|O_5}C1faZ_i_5l3S< zB=eSuzU~;T9#C^+hhPgitYNyVPpSE=Iu)by!Zflr7(3er0*!GTilhU@c zg^p;eaSe4Q2fI?PRQ~uC#XP&?R!{$0pfA%Rrja$C(dj_wp{`mbL@VHJ3uwijG& znT`H&24*_>h*uILN~|uMRNCfR9;#F=^+jpT`qUZJ`Fqh^Ort0n7H9SH#2%tj7)yr=^{UOo`uTQ+vaykh7(+5eF#`)7Snnq7*SytiD8iO-_1|09zB zw+p!}A6fdb=%7=7;!snPw{ntaeYyg)YOaIZDZl1H9*st;?{SL943)j4mQH*1^$2;H zxD|q<82c6J$V%Ao)vL#{Oo>3sk4~swu2*~?)K}?9{Ng-u<2EoQpoYx`0CfV(W;_qV*g|j|y>R-heMH9y>=Hb5uWBeqolXTa{a_por zYPrGPg5468cT**w=XxnYIag5hkc#gQUf0`vYJJ`?$bowsW-d(AQ2kq{gJ|sy$LvD_ zvv?{4gVj*hDG(9!3~|Vjb$GJ0`t8!_mHY{(-|An0{Ul9RttYSJ6-H#b^b7wq6=AaX`n?(#fw=@GD<$;7#rgiG*8pHrWnv>u|d5$+i!+b@(}luu=z10HI+4T>VR* z{8XBo{6vUXwJI%yn0wx{;oP6O_H$Dlzy%nFScXFC)8CBRPKgRjeA|8jBmDZQLdx3Z zSp9eW_)h{HVESr%GA)9ubcNv)dyU-~buhW1PsN5rESh;ny>l^a0g*k9P*5&LoO?Oj zwg}xR_&BGxTDpFO$c)lmo@22Q#^JCtPOayL9jUnNtxfg3k|*(_ z2~XOoieI-;DilH}tbu7dm0psb4(WCEC5as_CLS;zWRsc$0o6?Cce;w~H1wjJxpiwX z%{dYsZrF1R#7RDqGXD!&R(2@f$P2*bJLmHwLP}s z7Pa5w9xXeVHqxkX=>C_y69I@x+qNpQz=mqE}X`q!sL6Q zOjm!T9{NNL%qPWmcW$|{^xDOH?f)=XfOQE7<=?5W7E2LarbB z?5M^<+q{d8UsX}q{Bn-QQRbx!UjP$l0~HDR>rw^5k*i`^=a1*Vxu=+u9Q}wh;r0|{ zr`dP<9tlzucr0^%Ai$huj zZZdSG@JB+o2i$B7Mp&)a5!3?`F%<&>qLnoG(V3p|Vv7f3|HmYj4C2OW*Y@3dW1aMkQuE>YA-Yn~ zr8vX3L=f*quWkOzJZI#PvuG8cBRX2n#&lh5X&1(>)6x4A=rJcrT1=Wqcm&)?*d9?! zG1JVwqbO0~He$EQNclku!44aWhnF%KSmqAG7Z%|X{$e-(5qAu2*SMXKhm9^fC>Xa3rj%#*b{K z0H)zpxkEdvf6PSl2jc+j0s4MHo?O(>dL>douS!&? z=JDmfw45PD%eYkI0wrl4$B}vIu>2m9ah-WRcFUrw9aZ|tg{V%Ede3>wPR&UpgIOtM zZKFiuejh=1Uk#ux`)B}jpmOH2u3E6<_N) z<+RvGuF1V55VzpaY=ha+3pk%^8gqo2$1A6{C)^g?t8o5Y1Olh^LQx;Alic%7B7eDN zQ(urW7)qm`-QP*qla<(N<@_Ah#fN3UP{-6ZUjW)8x`JZcF|;c75|=ZphT7S4FCt>-?H`NSY`A!qNp# zAIaq1z-ir@9TIKbKr;%cFR_)BG&l#UuNf<~pQ6~`jij5stF7d%d`wr3J}5NQi7A+uRHsyUAFIWeSQZr;FccWp*Q-+r^@%>OGP{^I!|m`3ArN32AV9A`?ymyT7TAS z;i_z~cqzt7es2+T8f*yNtoInc0g-%$CQY8Yzmu|r@X!4T5Sqo>6Vu+nbOZiVi~JAC zj>hGIl9=e+O{qa2ZP6(@5x&zpL)LKm7_OvABAcOWS7 zcurE=k9O8UZ&~@;&#s^D|0wOcquKuZeXJraRa>npYE&pcqh^bmAqcfqjnGtLRurYE zQMJ$*_$JiZo~gk&Qqrd?pt zav|WrnbkryANsCCJYCa<_8&>ITDghvd$%r~yF|HF>!Ey%!D1vN*@{>Jf49XFY*7H< z=h3Lx)mHTw8ryiq2xNFCFvm?X-OV$EpY0P68o$*O(ZJQ3)@9xIRdDkJsrt%THMX6U z8tUbY$Q|u|Q)>dE%f7*o-|Ov)Zl`dzlp_XIO%qKm&Zh%0kiu%ud%pdA5>K;?nu_?s z^Q5usfiao=Q}3~d$*P8jfH-ivF2nsw&BrxUz`f7zqYBf3Z>ixQme#*3!ud8^ym#97 zc7lDNQ6)7USpSFF8**O20ZAAAQE+Ng?p!l=a07IjGwRcOM0j}G({|J^fFbDoQI_0K zwT?*ns@s;_DER2e83mExWNn9QPDL3!=B=xKVM}LE6K{yX&a4zJh-kkZoNK#Z!kZB} zh`ld3e}&JsQ5snG8zHn8?Q0kEduUuIyRw7i%}ZC}m%j*Dz0_8aP(QD{A&z*S^=$ca zu}yT%Igt)hj8}lAh^-U$)j@;zIycZcQ(7r({I_|dCow3~I719aO zF?w3x^aq>pyOCMSyM}70w3ITLG!*LOS`=+Be4ck1OFC;cXC=tAqoezidL!2x{M~t$ zC?3Ka*d&RMAN}6r7d{PPOucqr^Dv|$62oNu`+slTj*Nk?JXRYOgjEf-Je)oOyD%Gw z@XC5j6E72aVPeXvln8li=oVh)@d??{^`O)z2i3Eg)qmiVKQWicS-U>i;v@vcoPx_H ze}-LF)#P+Qe^=E^$&*69I`{8oUX?Gm$hMNzV#fnxcMv)5V@^(<+wU*q6y8716llyZ z%~mx@Ol{CD!(NQ}KxAFJQBl@X)@h&wXJzi%sYkc1Mi+mC*zyXQND-%vNkNygue9a2se8WDPke(9#u?N>fJumMa1jE=Ir!vIsP?@=NEn4qWYu-V26F;r%elm*QJE)%jjcwyqru2m0 zS+L~L>hR`lUmf2zZ9uqD=X204xO)4>V^BP&FmT55xK2sO(oC!`(5=MNrg(k z0A~3b>&TC#Te2@G;+{P=KVhJ-_i)QprEN^0>(zO80kB-NZd4fUJ z!Ucf4hB2K1IUjYX+x~ib*8ROeY<-O&;ad42+B|e8&$mCp1664x&{WJ;+|Qa6+#$=2 zmwY%>s7k(Bj@E->Qu?KOAG>J$y^r=!3wrF)pT@LUEp&$=n)DGyNJwk_CPu>7;wzm4 zS&$Y4^`?IHB`nXVun(6xbgx(3F%gA;Hilcd@u;mae3x0|JMcDd3o)VJO`*v2;?jco z$E>Ll^TfH@njO#Cs?nPX%&nSLGD01Zl%~pHQR)10Z8i9FGsR1%iZ6r!KO|GtC2I#Y zrVOIn^xu09Dj~I2{6t3)drXjXPYg*joOZXyCEw9j;%?8GcUp`jTo{i_*-| zgbQu+aHlHc39?I-Uq40ZW1uN!$pUWhvI1xiZN`iT+@e*}@_9%0HnSjH-zKA$>uQ=R zRm1DNdRyl#sURaWxE6i-;E0KLu*Rru-^JAjok5pLAieL*svajt6xlB`t-h9-+~q90 zfp~jbHJYv`7lD2A#BoB%G0IBFdim^#>OEd(B=g{XwAT6UpGvYcO9hNp3-4ojk?&G#S+*C zL~@C>&AMe0_e?|alFl{>P7dNRXe-+zuQpq_H;sXCk4t)t9I4-;2GN4nQ&jb4xkhJo;r^F<# zJ1Y-f4ar^)Z3qcRK3}x!Vz~F^`8jwY$?Sgl4{Nn4xt)W%b$CrCJa&!8spc-lhHRYFxIaCZtXZW#{HvSn*-@i`n+x{-8~0N99&ub7?9#wJ7XoL zcoZ>U+FUo9Zz+cJ1!6z&`0Mdj%aT1ryH)&@63S~ED(o*Ex}bN0>a-&oDTqnQVd9{# z#*=GA;4D1LDHN|W6D2L<wL-`dybXoDd9*jGtDEcJ#5q|q77UZJ_AAweTR?F6?HzA8hh2; zm$3c-j{LwqsjAAWiAn=WdhQbELQr=u5F1%E6*c~H)srFyosyj;aV_%J-P=@lLaOx)jQDP}EuH*f*b~(A z%Gm!j=|+{r72IB3bXmM@Ftb{a`G_KL*(LShYK~ZXECeLM@`EMRg148EDNgDM@U~A` z82$-_bTS@&n<(R5@A)3d=2~Q2N6F7UL1luV@}S_#1}a4PBex8Y*}p+rR8pq&xk)b{ zZb}DU@?G~{?P8ckc|djL)$5t7IOi>~ERVq!qlZq%ZR2}S@9-2UXgD~Itlyv&+?~~%bf~#fS$e^)KF*6MXe>V`D%jh&je?bz<1A@AJ-~ z@KcV)rQPi;%wRfxIb;kT+jVOlDQk6Cc~RDSRJ>5i4_5w-oS3w)fOZ6_N2Xl}+QyOh zysFWM0r__nIj-it4~DU7NpTQ(t=NGCfBU&Rqf&!lO+~W&G<&+Hx0b&RXG$N;r_NeQc`szqW&(UTA$He!sQ=j z8bWxNNEn9Rhq5B5J?9r!?Drkni#=LHs=j-B^okC*UE{M$J7;J%Mv)UghhxlJ#cPsVrg$m`3{ zn`SEBwwBQv#aPXV&Tqpm+#(^5?+37>-wYZNvAg zjiG~;m)DoDOEKz_nhLMxgPe!OL+o5UO!iM4`#-yl1{MF|jdKZ=!UrDxZkO+c|pV&Uh`T$rV6KB0~%w1hnl>Sy=Gvf7oInz z3--RVs}&+XeAmJzUnj}>c%RP-bN~s7<)P4H-3>l`@4zn

@F*Eyla3FNGkD>-QC0 z8*VerCdm!!H`IO3DV`b|^nds)`+Aq*z9uTX+m*%dsnR{Vc9VLcG0rhcpqFdjGU|{A z3ov=C5xx$?ev=jh5R3*e_~T%47cUK9J!dKW%*KhG^n*($<2)}YT}{^0&=LJZ%>kv1 zo%T;BUo+k*!2AOE1QskF z@4z+DwLB*s#mdOgT<%5Kh*x3O`%Bw&?8N}vYugIXT3|%W`5+|3%$@3{%jy^+lwQoO zDwt}+)MT0jPrca_^uS^F!t&+4w_V=jpa5*|Ug``uR}yZKdTsM6_26vUOHzDXPY0!T zvQc#?#};mW+|3|lm3YEB2~@1P8?~vtZqK?^<>riuGTeYHI4GAFcs!d4FPjt$ey-Y2 zbtq^HVN?O@y&H@p<^{vIcee1lL}xqBLSx;jvp*KYn##_`1vF0w2-OK~;0wiqww|4I zN7yLr^Dc+zxtQ`CUB~R$^*y0?F^zL=%r&b`!c`dj0?4JYPRW{H(4a!T-+E*Tr29sv zT^h+FY4l{Q#!~90fvH?mF2n$y5LrX=u-_ zM9b`W%^X9t`gHec&G`M2z?x%#?s3>XEBT>ph&$iv3em-9ji-E~*E# z;2Exq@8}$;8(PWyv zQ0#2Wpm4j@St}<5e;=sGD54KSW?24qI2<;e#H)3uGfkj0Tkr1iW@SmbD>oT>=7Z@> z-FVH^&P{+LVS-M+0^6zscJCqwdt4(C& zM0S6iPg75Vu;?=q3O&Ph)Nc&1D~%d*OuNFILo(Qv7p~fCcnRIQdxW>+88Nd%Op-$b z-Ak0Irz@yVrZy?0IOQe%2ky9!O(UK1JGpmCDtrxl6$y4557g;Jv*KSgAwz{eg1fE7 zzM!U>aj`O5m~@(u5GllJjBAUyQF2~;gb|KpVv3)K%S&7&M_^dyk877T4wVM2X7o=f z$Il?eSpHs^m9Bb>{{RYQ@-;{l3+QJQIe8rt0F3zQ1x&P@kE+`hlj{Y82$LK@0e>wN zTV))YoGWoK*?Z;Ij|hd_QF54CM({}mKE>L7j}|Zf@n`SGM@~(%fjCPZo|j#gnG{ms zX2jq2&mS9_SW5JZW@uY;Qxxr344oT;8wGT3;}KfrM`gp2=G9Za^xMeyW(!lErkiDL zWXAM@a6cl=F6Cf1a)v&dCNLDjl~T0rDxuY8kgF8s{McVF&yj<~_qF3E)gKDYBzUrG znWk}|jgl_*`ENmJZQxA2ofB+#Csrjm13L=>--dz?2$v?}#Y{pOV`aWEH3|9!7Vr{xKR8Mv$AqNs4eA1`Osc}WEd0PGqffa76^41GX z$UBsUcJ5I70~9oz;l3*UzMNC`0kx$KE?t_q?C=zKlkU+9IXyW-aIdwmFz!gtb_v=j zDf*1nSOS3Jk - -]> - - - - - - - - - -;;Default extension for filenames -(define %html-ext% ".html") -;;What font would you like for the body? -(define %body-font-family% - "Arial") - -(element emphasis -(if (equal? (normalize "bold") (attribute-string (normalize "role"))) - ($bold-seq$) - ($italic-seq$))) - -(element tgroup - (let* ((wrapper (parent (current-node))) - (frameattr (attribute-string (normalize "frame") wrapper)) - (pgwide (attribute-string (normalize "pgwide") wrapper)) - (footnotes (select-elements (descendants (current-node)) - (normalize "footnote"))) - (border (if (equal? frameattr (normalize "none")) - '(("BORDER" "0")) - '(("BORDER" "1")))) - (bgcolor '(("BGCOLOR" "#E0E0E0"))) - (width (if (equal? pgwide "1") - (list (list "WIDTH" ($table-width$))) - '())) - (head (select-elements (children (current-node)) (normalize "thead"))) - (body (select-elements (children (current-node)) (normalize "tbody"))) - (feet (select-elements (children (current-node)) (normalize "tfoot")))) - (make element gi: "TABLE" - attributes: (append - border - width - bgcolor - '(("CELLSPACING" "0")) - '(("CELLPADDING" "4")) - (if %cals-table-class% - (list (list "CLASS" %cals-table-class%)) - '())) - (process-node-list head) - (process-node-list body) - (process-node-list feet) - (make-table-endnotes)))) - - -;;Should verbatim items be 'shaded' with a table? -(define %shade-verbatim% - #t) - -;;Define shade-verbatim attributes -(define ($shade-verbatim-attr$) - (list - (list "BORDER" "0") - (list "BGCOLOR" "#E0E0E0") - (list "WIDTH" ($table-width$)))) - -;;Index -(define (generate-index) - ("1")) - -;;======================== -;;Title Pages for Books -;;======================= - -(define (book-titlepage-recto-elements) - (list (normalize "title") - (normalize "subtitle") - (normalize "authorgroup") - (normalize "author") - (normalize "date") - (normalize "releaseinfo") - (normalize "orgname") - (normalize "graphic") - (normalize "copyright") - (normalize "legalnotice"))) - - - - - - - - - -;;Index -(define ($insert.xref.page.number$) - ("yes")) - -;;Index -(define ($generate-index$) - ("1")) - -;;Tex Backend off -(define tex-backend - #f) - -;;What elements should have a LOT? -(define ($generate-book-lot-list$) - (list (normalize "example") - (normalize "table") - (normalize "figure") - (normalize "equation"))) - -;;======================== -;;Title Pages for Books -;;======================= - -(define (book-titlepage-recto-elements) - (list (normalize "title") - (normalize "subtitle") - (normalize "authorgroup") - (normalize "author") - (normalize "date") - (normalize "orgname") - (normalize "graphic") - (normalize "copyright") - (normalize "legalnotice") - (normalize "releaseinfo"))) - -(define %show-ulinks% - ;; Display URLs after ULinks? - #t) - -(define %indent-screen-lines% - ;; Indent lines in a 'Screen'? - " ") - - - - - - - - diff --git a/doc/UsersGuide/clm_ug.xml b/doc/UsersGuide/clm_ug.xml deleted file mode 100644 index 68aa69b1d6..0000000000 --- a/doc/UsersGuide/clm_ug.xml +++ /dev/null @@ -1,191 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - build-namelist"> - configure"> - NCAR"> - CCSM"> - CCSM4.0"> - CESM"> - CESM1.0"> - CESM1.0.1"> - CESM1.0.2"> - CESM1.0.3"> - - PTCLM"> - PTCLM1"> - PTCLM1.110504"> - CLM"> - CLMCN"> - CLMSP"> - CLMU"> - CLM3.0"> - CLM3.5"> - CLM4"> - CLM4.0.00"> - - - - - - - - DATM"> - models/lnd/clm/doc/KnownBugs"> - NetCDF"> - FORTRAN"> - FORTRAN-90"> - MPI"> - PIO"> - OpenMP"> - NCL"> - Perl"> - XML"> - xmlchange"> - 2"> - - - - env_run.xml"> - env_build.xml"> - env_conf.xml"> - user_nl_clm"> - - - PTS_MODE"> - CSMDATA"> - CLM_FORCE_COLDSTART"> - CLM_CONFIG_OPTS"> - CLM_BLDNML_OPTS"> - CLM_NML_USE_CASE"> - CLM_NAMELIST_OPTS"> - CLM_PT1_NAME"> - CLM_QIAN"> - CPLHIST3HrWx"> - CLM_USRDAT_NAME"> - CLM_CO2_TYPE"> - DIN_LOC_ROOT"> - - - CLM_QIAN"> - - - - %ISOamsa; - ]]> - - - - %ISOgrk1; - ]]> - -]> - - - - -&cesm; Research Tools: &clmrel; User's Guide Documentation - - - CESM - CLM - community earth system model - climate - climate model - earth system model - land surface model - hydrology - biogeochemistry - urban model - documentation - - - - - - Erik - Kluzek - - NCAR - - - - - - - -The user's guide to &clmrel; which is the active land surface model component of &cesmrel;. -The purpose of this guide is to instruct both the novice and experienced user, as well as -&clm; developers in the use of &clm4; for land-surface climate modeling. - - - -$URL$ - -&build_date; - - - - - -Dedicated to the Land Model Working Group, winners of the 2008 &ccsm; Distinguished Achievement Award. -May you continue to collaborate together well, and continue to drive -the science of land surface modeling forward with your diligent and persistent efforts. - - - - -&preface; -&custom; -&tools; -&adding_files; -&special_cases; -&single_point; -&ptclmdoc; -&trouble; -&testing; -&appendix; - - diff --git a/doc/UsersGuide/co2_streams.txt b/doc/UsersGuide/co2_streams.txt deleted file mode 100644 index 4d38c6d06e..0000000000 --- a/doc/UsersGuide/co2_streams.txt +++ /dev/null @@ -1,50 +0,0 @@ - - - This is a streams file to pass historical CO2 from datm8 to the other - surface models. It reads in a historical dataset derived from data used - by CAM. The getco2_historical.ncl script in components/clm/tools/ncl_scripts - was used to convert the CAM file to a streams compatible format (adding domain - information and making CO2 have latitude/longitude even if only for a single - point. - - - - Input stream description file for historical CO2 reconstruction data - - 04 March 2010: Converted to form that can be used by datm8 by Erik Kluzek - 18 December 2009: Prepared by B. Eaton using data provided by - Jean-Francois Lamarque. All variables except f11 are directly from - PRE2005_MIDYR_CONC.DAT. Data from 1765 to 2007 with 2006/2007 just - a repeat of 2005. - - - CLMNCEP - - - - time time - lonc lon - latc lat - area area - mask mask - - - /fis/cgd/cseg/csm/inputdata/atm/datm7/CO2 - - - fco2_datm_1765-2007_c100614.nc - - - - - CO2 co2diag - - - /fis/cgd/cseg/csm/inputdata/atm/datm7/CO2 - - - fco2_datm_1765-2007_c100614.nc - - - - diff --git a/doc/UsersGuide/custom.xml b/doc/UsersGuide/custom.xml deleted file mode 100644 index d6a60a28f7..0000000000 --- a/doc/UsersGuide/custom.xml +++ /dev/null @@ -1,1615 +0,0 @@ - - - - - - - component set - compset - "I" compsets - "B" compsets - "E" compsets - "F" compsets - &CLMCONFIG; - &CLMNAMELIST; - &CLMFORCECOLD; - &CLMUSECASE; - &CLM1PT; - &CLMUSRDAT; - &CLMCO2; - - -How to customize the configuration for a case with &clm; - - -The -&cesm; User's Guide gives you the details on how to setup, &configure;, build, and run -a case. That is the document to give you the details on using the &cesm; scripts. The purpose -of this document is to give you the details when using &cesm; with &clm; on how to customize -and use advanced features in &clm;. You should be familiar with the &cesm; User's Guide and -how to setup cases with &cesmrel; before referring to this document. - - -In this chapter we deal with three different ways of customizing a case: Choosing a compset, -Customizing Configuration options, and customizing the &clm; Namelist. There are many different -compsets that use &clm; and many are setup to enable special features of &clm; from the start. So -the first thing you want to be familiar with are the different options in the compsets. The -next section shows the different options for customizing the configuration options for -&clm;. -Here we introduce the &clm; &configure; and &buildnml; scripts and how using the options in -&envconf; you can customize the configuration and the initial -namelist. The final section tells you about the &clm; namelist and how you can customize the -namelist once you have run "&configure; -case" and have an initial namelist in -BuildConf/clm.buildnml.csh. You can also -use &envconf; options to change your namelist as well, before "&configure; -case" is -run. - - - -Choosing a compset using &clm; - - -When setting up a new case one of the first choices to make is which "component -set" (or compset) to use. The -compset refers to which component models are used as well as specific settings for them. We label the different -types of compsets with a different letter of the alphabet from "A" (for all data model) to "X" (for all dead model). -The compsets of interest when working with &clm; are the "I" compsets (which contain -&clm; with a data atmosphere model -and a stub ocean, and stub sea-ice models), "E" and "F" compsets (which contain &clm; -with the active atmosphere model (CAM), -prescribed sea-ice model, and a data ocean model), and "B" compsets which have all active components. Below we -go into details on the "I" compsets which emphasize &clm; as the only active model, and just mention the two other categories. - - -When working with &clm; you usually want to start with a relevant "I" compset before moving to the more -complex cases that involve other active model components. The "I" compsets can exercise -&clm; in a way that -is similar to the coupled modes, but with much lower computational cost and faster turnaround times. - - -Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets) -&compsets_list; - - - - Compsets coupled to active atmosphere with data ocean - - CAM compsets are compsets that start with "E" or "F" in the name. They are - described more fully in the scripts documentation or the CAM documentation. "E" compsets have -a slab ocean model while "F" compsets have a data ocean model. - - - - -Fully coupled compsets with fully active ocean, sea-ice, and atmosphere - - Fully coupled compsets are compsets that start with "B" in the name. They are - described more fully in the scripts documentation. - - - - -Conclusion to choosing a compset - -We've introduced the basic type of compsets that use &clm; and given some further details -for the "standalone &clm;" (or "I" compsets). The - -config_compsets.xml lists all of the compsets and gives a full description -of each of them. In the next section we look into customizing the &configure; time options -for compsets using &clm;. - - - - - - - -Customizing the &clm; configuration - -The "Creating a Case" section of the -&cesm1; Scripts -User's-Guide -gives instructions on creating a case. What is of interest here is how to customize your -use of &clm; -for the case that you created. In this section we discuss how to customize your case before the first -step -- the "&configure; -case" step is done. In the next section we will discuss how to customize your -&clm; namelist after "&configure; -case" has already been done. - - -For &clm; when "&configure; -case" is called there are two steps that take place: - - -The &clm; "&configure;" script is called to setup the build-time -configuration for &clm; (more information on &configure; is given in -). -The &clm; "&buildnml;" script is called to generate the initial -run-time namelist for &clm; (more information on &buildnml; is given below in -. - - -When customizing your case at the &configure; step you are able to modify the process by effecting either one -or both of these steps. The &clm; "&configure;" and "&buildnml;" scripts are both available in the "models/lnd/clm/bld" -directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what -types of options you can give either of them. - - -There are five different types of customization for the configuration that we will -discuss: &cesm1; &clm; configuration items, Configure time User Namelist, -other noteworthy &cesm; configuration items, the &clm; &configure; script options, and -the &clm; &buildnml; script options. - - -Information on all of the script, configuration, build and run items is found under -scripts/ccsm_utils/Case.template -in the -config_definition.xml - file. - - - -&clm; Script configuration items - -Below we list each of the &cesm; configuration items that are specific to &clm;. All -of these are available in your: &envconf; file. - - - - &CLMCONFIG; - &CLMBLDNML; - &CLMNAMELIST; - &CLMFORCECOLD; - &CLMUSECASE; - &CLM1PT; - &CLMUSRDAT; - &CLMCO2; - -For the precedence of the different options to &buildnml; see the section on -precedence below. - - -The first item &CLMCONFIG; has to do with customizing the &clm; configuration options for your case, the rest -all have to do with generating the initial namelist. - - - -&CLMCONFIG; - - -The option &CLMCONFIG; is all about passing command line arguments to the &clm; &configure; script. It is important -to note that some compsets, may already put a value into the &CLMCONFIG; variable. You can still add more -options to your &CLMCONFIG; but make sure you add to what is already there rather than replacing it. Hence, -we recommend using the "-append" option to the xmlchange script. In - -below we will go into more details on options that can be customized in the &clm; "&configure;" script. It's -also important to note that the &clm; template may already invoke certain &clm; &configure; options and as such those -command line options are NOT going to be available to change at this step (nor would you want to change them). -The options to &configure; are given with the "-help" option which is given in -. - - - - - -&CLMUSECASE; - - -&CLMUSECASE; is used to set a particular set of conditions that set multiple namelist items, all centering around -a particular usage of the model. -To list the valid options do the following: - - -> cd models/lnd/clm/doc -> ../bld/&buildnml; -use_case list - - -The output of the above command is: - - -&usecases_list; - - - -See the section for the precedence of this -option relative to the others. - - - - - - -&CLMBLDNML; - - -The option &CLMBLDNML; is for passing options to the &clm; "&buildnml;" script. As with the "&configure;" -script the &clm; template may already invoke certain options and as such those options will NOT be available to be -set here. The best way to see what options can be sent to the "&buildnml;" script is to do - - -> cd models/lnd/clm/bld -> ./&buildnml; -help - - -Here is the output from the above. - - -./&buildnml_help; - - -The &clm; template already sets the resolution and mask as well as the &configure; file, -the start-type, the co2_ppmv, rtm_tstep, and rtm_res, and defines an input -namelist and namelist input file, and it normally sets either "-ignore_ic_year" or -"-ignore_ic_date". Also many -of the options are designed solely for &clm; stand-alone testing and hence should NOT -be used (any of the options starting -with a "datm_" or "drv_" prefix. Hence there are then only five different options that could be set: - - - --lnd_res --sim_year --rcp --clm_demand --verbose - - - -"-lnd_res" is used to run &clm; in fine-mesh mode at a higher resolution than the atmospheric model. This can -be useful to get higher resolution from the land model, but saving computer time -by running the more expensive atmospheric model at a lower resolution. -To get a list of valid resolutions to run at do the following: - - -> cd models/lnd/clm/doc -> ../bld/&buildnml; -lnd_res list - - - -The fine-mesh mode is considered experimental, and you may run into problems when you use -it. Another option is to use the CESM level "tri-grid" capability to run the land model -on a different grid than the atmospheric model. Read the CESM User's-Guide to learn how -to do this. - - - - - -See the section for the precedence of this -option relative to the others. - - - - -"-clm_demand" asks the &buildnml; step to require that the list of variables -entered be set. Typically, this is used to require that optional filenames be used and ensure -they are set before continuing. For example, you may want to require that -flanduse_timeseries be set to get dynamically changing vegetation types. To do this -you would do the following. - -> ./xmlchange -file env_conf.xml -id &CLMBLDNML; -val "-clm_demand flanduse_timeseries" - -To see a list of valid variables that you could set do this: - -> cd models/lnd/clm/doc -> ../bld/&buildnml; -clm_demand list - - - - -Using a 20th-Century transient compset or the 20thC_transient use-case -using &CLMUSECASE; would set this as well, but would also use -dynamic nitrogen and aerosol deposition files, so using -clm_demand would be a way -to get just dynamic vegetation types and NOT the other files as well. - - - -"-sim_year" is used to set the simulation year you want the data-sets to simulate conditions for in the input -datasets. The simulation "year" can also be a range of years in order to do simulations -with changes in the dataset values as the simulation progresses. To list the valid -options do the following: - - -> cd models/lnd/clm/doc -> ../bld/&buildnml; -sim_year list - - -"-rcp" is used to set the representative concentration pathway for the future scenarios -you want the data-sets to simulate conditions for, in the input -datasets. To list the valid options do the following: - - -> cd models/lnd/clm/doc -> ../bld/&buildnml; -rcp list - - - - - -&CLMNAMELIST; - - -The option &CLMNAMELIST; is for passing namelist items into the "clm_inparm" namelist. -Any items that are set in &CLMNAMELIST; will be set in your namelist after "&configure; --case" is done. - - - -For character namelist items you need to use "&apos;" as quotes for strings so that the -scripts don't get confused with other quotes they use. - - - -Example, you want to set hist_dov2xy to .false. -so that you get vector output to your history files. To do so edit -&envconf; and add a setting for hist_dov2xy. -So do the following: - -> ./xmlchange -file env_conf.xml -id &CLMNAMELIST; -val hist_dov2xy=.false. - - - -Example, you want to set hist_fincl1 to add the variable 'HK' -to your history files. To do so edit -&envconf; and add a setting for hist_fincl1. -So do the following: - -> ./xmlchange -file env_conf.xml -id &CLMNAMELIST; -val "hist_fincl1=&apos;HK&apos;" - -For a list of the history fields available see -&clm; History Fields. - - - -See the section for the precedence of this -option relative to the others. - - - - - - -&CLMCO2; - - -&CLMCO2; sets the type of input &CO2; for either "constant", "diagnostic" or prognostic". -If "constant" the value from CCSM_CO2_PPMV will be used. If "diagnostic" -or "prognostic" the values MUST be sent from the atmosphere model. For more information on how -to send &CO2; from the data atmosphere model see . - - - - - -&CLMFORCECOLD; - - -&CLMFORCECOLD; when set to on, requires that -your simulation do a cold start from arbitrary initial conditions. If this is NOT set, it -will use an initial condition file if it can find an appropriate one, and otherwise do a cold -start. &CLMFORCECOLD; is a good way to ensure that you are doing a cold -start if that is what you want to do. - - - - - -&CLM1PT; - - -&CLM1PT; is used ONLY for a pt1_pt1 -resolution simulation to set the name of the single-point files to use. -To see a list of the valid resolutions do this: - -> cd models/lnd/clm/doc -> ../bld/&buildnml; -res list - - - -The output of the above command is: - - -&res_list; - - -the valid resolutions that can be used with &CLM1PT; are the ones that -have city or nation names such as: 5x5_amazon, 1x1_vancouverCAN 1x1_mexicocityMEX, or -1x1_brazil. The "1x1_" prefix means the file is for a single-point, while "5x5_" prefix means -it's for a region of five points in latitude by five points in longitude. Both regional -and single point datasets can be used for &CLM1PT;. If you create your own datasets -you can also use &CLM1PT; along with &CLMUSRDAT; (documented below), setting &CLM1PT; to -the value in &CLMUSRDAT; so that your datasets are used rather than the standard ones.o - - - - - -&CLMUSRDAT; - - -&CLMUSRDAT; provides a way to enter your own datasets into the initial -namelist setup at "&configure; -case". The files you create must be named with -specific naming conventions outlined in: . -To see what the expected names of the files are, use the -queryDefaultNamelist.pl to see -what the names will need to be. For example if your &CLMUSRDAT; will -be "1x1_boulderCO", with a "navy" land-mask, constant simulation year range, for 1850, -the following will list what your filenames should be: - -> cd models/lnd/clm/bld -> queryDefaultNamelist.pl -usrname "1x1_boulderCO" -options \ -mask=navy,sim_year=1850,sim_year_range="constant" -csmdata $CSMDATA - -An example of using &CLMUSRDAT; for a simulation is given in -. - - - -See the section for the precedence of this -option relative to the others. - - - - - - - - - -Configure time User Namelist - -&CLMNAMELIST; as described above allows you to set any -extra namelist items you would like to appear in your namelist after first &configure;d. -However, it only allows you a single line to enter namelist items, and strings must -be quoted with &apos; which is a bit awkward. If you have a long list of namelist -items you want to set (such as a long list of history fields) a convenient way to do it -is to create a &usernlclm; that contains just the list of namelist -variables you want to add to your initial namelist. The &usernlclm; -will only be used when &configure; is run, so if you change it after &configure; -- it won't -change anything. The file needs to be in valid FORTRAN namelist format, and the &configure; -step will abort if there are syntax errors. It merely needs to be named correctly -&usernlclm; and placed in your case directory (where your other -env_*.xml files are). The namelist name actually doesn't have to be -valid, but all the variable names must be. Here's an example &usernlclm; -namelist that sets a bunch of history file related items, to create output history files -monthly, daily, every six and 1 hours. - -Example &usernlclm; namelist file - -&clmexp - hist_fincl2 = 'TG','TBOT','FIRE','FIRA','FLDS','FSDS', - 'FSR','FSA','FGEV','FSH','FGR','TSOI', - 'ERRSOI','BUILDHEAT','SABV','SABG', - 'FSDSVD','FSDSND','FSDSVI','FSDSNI', - 'FSRVD','FSRND','FSRVI','FSRNI', - 'TSA','FCTR','FCEV','QBOT','RH2M','H2OSOI', - 'H2OSNO','SOILLIQ','SOILICE', - 'TSA_U', 'TSA_R', - 'TREFMNAV_U', 'TREFMNAV_R', - 'TREFMXAV_U', 'TREFMXAV_R', - 'TG_U', 'TG_R', - 'RH2M_U', 'RH2M_R', - 'QRUNOFF_U', 'QRUNOFF_R', - 'SoilAlpha_U', - 'Qanth', 'SWup', 'LWup', 'URBAN_AC', 'URBAN_HEAT' - hist_fincl3 = 'TG:I', 'FSA:I', 'SWup:I', 'URBAN_AC:I', 'URBAN_HEAT:I', - 'TG_U:I', 'TG_R:I', - hist_fincl4 = 'TG', 'FSA', 'SWup', 'URBAN_AC', 'URBAN_HEAT' - hist_mfilt = 1, 30, 28, 24 - hist_nhtfrq = 0, -24, -6, -1 -/ - - - - -See the section for the precedence of this -option relative to the others. - - - - -In the above example we use an invalid namelist name &clmexp -- but it works anyway -because the &clm; &buildnml; knows the namelist that specific variable names belong to, and -it puts them there. - - -Obviously, all of this would be difficult to put in the &CLMNAMELIST; -variable, especially having to put &apos; around all the character strings. For -more information on the namelist variables being set here and what they mean, see -the section on &clm; namelists below, as well as the namelist definition that gives -details on each variable. - - - - -Precedence of Options - -Note: The precedence for setting the values of namelist variables with the -different env_conf options is (highest to lowest): - -Namelist values set by specific command-line options, like, -d, -sim_year -(i.e. &CLMBLDNML; env_conf variable) -Values set on the command-line using the -namelist option, -(i.e. &CLMNAMELIST; env_conf variable) -Values read from the file specified by -infile, -(i.e. &usernlclm; file) -Datasets from the -clm_usr_name option, -(i.e. &CLMUSRDAT; env_conf variable) -Values set from a use-case scenario, e.g., -use_case -(i.e. &CLMUSECASE;env_conf variable) -Values from the namelist defaults file. - -Thus a setting in &CLMBLDNML; will override a setting for the same thing given in -a use case with &CLMUSECASE;. Likewise, a setting in &CLMNAMELIST; will override a -setting in &usernlclm;. - - - - -Setting Your Initial Conditions File - -Especially with &clmcn; starting from initial conditions is very important. Even -with &clmsp; it takes many simulation years to get the model fully spunup. There -are a couple different ways to provide an initial condition file. - - - - - - - - -Your initial condition file MUST agree with the surface dataset you are using -to run the simulation. If the two files do NOT agree you will get a -run-time about a mis-match in PFT weights, or in the number of PFT's or -columns. To get around this you'll need to use -to interpolate your initial condition dataset. - - - - - -Doing a hybrid simulation to provide initial conditions - -The first option is to setup a hybrid simulation and give a -RUN_REFCASE and RUN_REFDATE to specify the -reference case simulation name to use. -When you setup most cases, at the standard resolutions of "f09" or "f19" it -will already do this for you. For example, if you run an "I2000CN" compset -at "f09_g16" resolution the following settings will already be done for you. - -./xmlchange -file env_conf.xml -id RUN_TYPE -val hybrid -./xmlchange -file env_conf.xml -id RUN_REFCASE -val I2000CN_f09_g16_c100503 -./xmlchange -file env_conf.xml -id RUN_REFDATE -val 0001-01-01 -./xmlchange -file env_conf.xml -id GET_REFCASE -val TRUE - -Setting the GET_REFCASE option to TRUE means it -will copy the files from the: -$DIN_LOC_ROOT/ccsm4_init/I2000CN_f09_g16_c100503/0001-01-01 -directory. Note, that the RUN_REFCASE and -RUN_REFDATE variables are expanded to get the directory name -above. If you do NOT set GET_REFCASE to TRUE then -you will need to have placed the file in your run directory yourself. In either -case, the file is expected to be named: -$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc with the variables -expanded of course. - - - - -Doing a branch simulation to provide initial conditions - -The setup for running a branch simulation is essentially the same as for a hybrid. -With the exception of setting RUN_TYPE to branch -rather than hybrid. A branch simulation runs the case essentially -as restarting from it's place before to exactly reproduce it. While a hybrid simulation -allows you to change namelist items, and use a different code base that may have -fewer fields on it than a full restart file. The GET_REFCASE works -similarily for a branch case as for a hybrid. - - - - -Providing a finidat file in your &usernlclm; file - -Setting up a branch or hybrid simulation requires the initial condition file -to follow a standard naming convention, and a standard input directory if you -use the GET_REFCASE option. If you want to name your file willy -nilly and place it anywhere, you can set it in your &usernlclm; file as in this -example. - -&clm_inparm - finidat = '/glade/home/$USER/myinitdata/clmi_I1850CN_f09_g16_0182-01-01.c120329.nc' -/ - -Note, if you provide an initial condition file -- you can NOT set &CLMFORCECOLD; to -TRUE. - - - - -Adding a finidat file to the XML database - -Like other datasets, if you want to use a given initial condition file to -be used for all (or most of) your cases you'll want to put it in the XML -database so it will be used by default. The initial condition files, are -resolution dependent, and dependent on the number of PFT's and other variables -such as GLC_NEC or if irrigation is on or off. -See for more information on this. - - - - - -Other noteworthy configuration items - -For running "I" cases there are several other noteworthy configuration items that -you may want to work with. Most of these involve settings for the &datm;, but one -CCSM_CO2_PPMV applies to all models. If you are running an B, E, -or F case that doesn't use the &datm; obviously the DATM_* settings will not be used. -All of the settings below are in your &envconf; file - - CCSM_CO2_PPMV - CCSM_VOC - DATM_MODE - DATM_PRESAERO - DATM_CLMNCEP_YR_ALIGN - DATM_CLMNCEP_YR_START - DATM_CLMNCEP_YR_END - DATM_CPL_CASE - DATM_CPL_YR_ALIGN - DATM_CPL_YR_START - DATM_CPL_YR_END - - - - - -CCSM_CO2_PPMV - -CCSM_CO2_PPMV sets the mixing ratio of &CO2; in -parts per million by volume for ALL &cesm; components to use. Note that most compsets -already set this value to something reasonable. Also note that some compsets may -tell the atmosphere model to override this value with either historic or ramped -values. If the CCSM_BGC variable is set to something other than "none" -the atmosphere model will determine &CO2;, and &clm; will listen -and use what the atmosphere sends it. On the &clm; side the namelist item -co2_type tells &clm; to use the value sent from the atmosphere rather than -a value set on it's own namelist. - - - - -CCSM_VOC - -CCSM_VOC enables passing of the Volatile Organic Compounds (VOC) from -&clm; to the atmospheric model. This of course is only important if the atmosphere -model is a fully active model that can use these fields in it's chemistry calculations. - - - - -DATM_MODE - -DATM_MODE sets the mode that the &datm; model should run in this determines -how data is handled as well as what the source of the data will be. Many of the modes -are setup specifically to be used for ocean and/or sea-ice modeling. The modes -that are designed for use by &clm; are: - -&CLMQIAN; -CLM1PT -&CPLHIST; - - - -&CLMQIAN; is for the standard mode of using global atmospheric data -that was developed by Qian et. al. for &clm; using NCEP data from 1948 to 2004. -See for more information on -the &datm; settings for &CLMQIAN; mode. -CLM1PT is for the special cases where we have single-point tower -data for particular sites. Right now we only have data for three urban locations: -MexicoCity Mexico, Vancouver Canada, and the urban-c alpha site. -See for more information on -the &datm; settings for CLM1PT mode. -&CPLHIST; is for running with atmospheric forcing from a previous &cesm; simulation. -See for more information on -the &datm; settings for &CPLHIST; mode. - - -There is a problem with running simulations for the CLM1PT mode -that are greater than one data cycle, where the atm forcing will be held constant. -This will result in useless -results as all atmosphere forcing fields will be held constant at the last value. -See bug 1377 in the &KnownBugs; file on how to fix this problem. - - - - - - - -DATM_PRESAERO - -DATM_PRESAERO sets the prescribed aerosol mode for the data atmosphere -model. The list of valid options include: - -clim_1850 = constant year 1850 conditions -clim_2000 = constant year 2000 conditions -trans_1850-2000 = transient 1850 to year 2000 conditions -rcp2.6 = transient conditions for the rcp=2.6 -W/m2 future -scenario -rcp4.5 = transient conditions for the rcp=4.5 -W/m2 future -scenario -rcp6.0 = transient conditions for the rcp=6.0 -W/m2 future -scenario -rcp8.5 = transient conditions for the rcp=8.5 -W/m2 future -scenario -pt1_pt1 = read in single-point or regional datasets - - - - - -DATM_CLMNCEP_YR_START - -DATM_CLMNCEP_YR_START sets the beginning year to cycle the atmospheric -data over for the &CLMQIAN; mode. - - - - -DATM_CLMNCEP_YR_END - -DATM_CLMNCEP_YR_END sets the ending year to cycle the atmospheric -data over for the &CLMQIAN; mode. - - - - -DATM_CLMNCEP_YR_ALIGN - -DATM_CLMNCEP_YR_START and DATM_CLMNCEP_YR_END determine -the range of years to cycle the atmospheric data over, and DATM_CLMNCEP_YR_ALIGN -determines which year in that range of years the simulation will start with. - - - - -DATM_CPL_CASE - -DATM_CPL_CASE sets the casename to use for the &CPLHIST; mode. - - - - -DATM_CPL_YR_START - -DATM_CPL_YR_START sets the beginning year to cycle the atmospheric -data over for the &CPLHIST; mode. - - - - -DATM_CPL_YR_END - -DATM_CPL_YR_END sets the ending year to cycle the atmospheric -data over for the &CPLHIST; mode. - - - - -DATM_CPL_YR_ALIGN - -DATM_CPL_YR_START and DATM_CPL_YR_END determine -the range of years to cycle the atmospheric data over, and DATM_CPL_YR_ALIGN -determines which year in that range of years the simulation will start with. - - - - - - - - -Downloading DATM Forcing Data - -In Chapter One of the -&cesm; User's Guide -there is a section on "Downloading input data". The normal process of setting up -cases will use the "scripts/ccsm_utils/Tools/check_input_data" script to retrieve -data from the &cesm; subversion inputdata repository. However, the DATM forcing data -is unique -- because it is large compared to the rest of the input data (56 Gbytes). Most of the -data is stored in the directory set by the &envrun; variable -DIN_LOC_ROOT_CSMDATA. The &CLMQIAN; forcing data is in a (possibly) -separate directory using the &envrun; variable DIN_LOC_ROOT_CLMQIAN. -In most cases this directory will be in the directory: -atm/datm7/atm_forcing.datm7.Qian.T62.c080727 under -DIN_LOC_ROOT_CSMDATA. On bluefire there is a separate path for -the &CLMQIAN; forcing data. We have the full set of data available on a few of -the machines we use: bluefire, jaguarpf, and edinburgh. As of October, 18th, 2011 -we've uploaded the entire set of forcing data into the input data repository so -now it can be treated like other input datasets and the check_input_data script -can retreive it for you. Previously only two years of data was available. -You can also download the data from the -Earth System Grid for other machines. See the -Model Forcing Data -link under the -&clm; Documentation Page - - - - -Customizing via the template files - -The final thing that the user may wish to do before &configure; is run is to edit -the template files which determine the configuration and initial namelist. The -variables in &envconf; typically mean you will NOT have -to edit the template. But, there are rare instances where it is useful to do so. - gives the details on how to do this. -The template files are copied to your case directory and are available under -Tools/Templates. -The list of template files you might wish to edit are: - - clm.cpl7.template - datm.cpl7.template - cpl.template - - - - - - -More information on the &clm; &configure; script - -The &configure; script defines the details of a clm configuration and summarizes it into a -config_cache.xml file. The config_cache.xml -will be placed in your case directory under Buildconf/clmconf. -The config_definition.xml -in models/lnd/clm/bld/config_files -gives a definition of each &clm; configuration item, it is viewable in a web-browser. -Many of these items are things that you would NOT change, but looking through the -list gives you the valid options, and a good description of each. Below we repeat -the config_definition.xml files contents: - - - - - -Help on &clm; &configure; - -Coupling this with looking at the options to &configure; with -"-help" as below will enable you to understand how to set the different options. - -> cd models/lnd/clm/bld -> &configure; -help - - - -The output to the above command is as follows: - - -&config_help; - - -We've given details on how to use the options in &envconf; to -interact with the &clm; "&configure;" and "&buildnml;" scripts, as well as giving a good -understanding of how these scripts work and the options to them. In the next section we -give further details on the &clm; namelist. You could customize the namelist for these -options after "&configure; -case" is run. - - - - - - - - - - Customizing the &clm; namelist - -Once a case is &configure;d, we can then customize the case further, by editing the -run-time namelist for &clm;. First let's list the definition of each namelist -item and their valid values, and then we'll list the default values for them. -Next for some of the most used or tricky namelist items we'll give examples of their -use, and give you example namelists that highlight these features. - - - - -Definition of Namelist items and their default values - -Here we point to you where you can find the definition of each namelist item and -separately the default values for them. The default values may change depending on -the resolution, land-mask, simulation-year and other attributes. Both of these -files are viewable in your web browser. Below we provide the link for them, and -then expand each in turn. - - - -Definition of each Namelist Item - - -Default values of each -&clm; Namelist Item - - - -One set of the namelist items allows you to add fields to the output history files: -hist_fincl1, hist_fincl2, -hist_fincl3, hist_fincl4, -hist_fincl5, and hist_fincl6. The link -&clm; History Fields -documents all of the history fields available and gives the long-name and units -for each. - - - - - -&hisfldtbl; - - - - - - - -Examples of using different namelist features - -Below we will give examples of user namelists that activate different commonly used -namelist features. We will discuss the namelist features in different examples and then -show a user namelist that includes an example of the use of these features. First we -will show the default namelist that doesn't activate any user options. - - - -The default namelist - -Here we give the default namelist as it would be created for a I1850CN compset at 0.9x1.25 -resolution with a gx1v6 land-mask. To edit the namelist you would edit the -BuildConf/clm.buildnml.csh under your case (or before &configure; -include a user namelist with just the items you want to change). For simplicity we will -just show the namelist and NOT the entire file. In the sections below, for simplicity - we will just show the user namelist (&usernlclm;) that will add (or modify existing) -namelist items to the namelist. Again, just adding the &usernlclm; file to your case -directory, before "&configure; -case" is invoked will cause the given namelist items to -appear in your &clm; namelist. - -Default &clm; Namelist - -&clm_inparm - co2_ppmv = 284.7 - co2_type = 'constant' - create_crop_landunit = .false. - dtime = 1800 - fatmgrid = '$DIN_LOC_ROOT/lnd/clm2/griddata/griddata_0.9x1.25_070212.nc' - fatmlndfrc = -'$DIN_LOC_ROOT/lnd/clm2/griddata/fracdata_0.9x1.25_gx1v6_c090317.nc' - finidat = 'I1850CN_f09_g16_c100503.clm2.r.0001-01-01-00000.nc' - fpftcon = '$DIN_LOC_ROOT/lnd/clm2/pftdata/pft-physiology.c110425.nc' - frivinp_rtm = '$DIN_LOC_ROOT/lnd/clm2/rtmdata/rdirc_0.5x0.5_simyr2000_slpmxvl_c120717.nc' - fsnowaging = -'$DIN_LOC_ROOT/lnd/clm2/snicardata/snicar_drdt_bst_fit_60_c070416.nc' - fsnowoptics = -'$DIN_LOC_ROOT/lnd/clm2/snicardata/snicar_optics_5bnd_c090915.nc' - fsurdat = -'$DIN_LOC_ROOT/lnd/clm2/surfdata/surfdata_0.9x1.25_simyr1850_c091006.nc' - ice_runoff = .true. - outnc_large_files = .true. - rtm_nsteps = 6 - urban_hac = 'ON_WASTEHEAT' - urban_traffic = .false. -/ -&ndepdyn_nml - stream_fldfilename_ndep = -'$DIN_LOC_ROOT/lnd/clm2/ndepdata/fndep_clm_hist_simyr1849-2006_1.9x2.5_c100428.nc' - stream_year_first_ndep = 1850 - stream_year_last_ndep = 1850 -/ - - -Note that the namelist introduces some of the history namelist options that will be -talked about in further detail below (hist_mfilt and -hist_nhtfrq). - - - - -Adding/removing fields on your primary history file - -The primary history files are output monthly, and contain an extensive list of -fieldnames, but the list of fieldnames can be added to using hist_fincl1 -or removed from by adding fieldnames to hist_fexcl1. -A sample user namelist &usernlclm; adding few new fields -(cosine of solar zenith angle, and solar declination) and excluding a few -standard fields is (ground temperature, vegetation temperature, soil temperature and soil water).: - -Example &usernlclm; namelist adding and removing fields on primary history file - -&clm_inparm - hist_fincl1 = 'COSZEN', 'DECL' - hist_fexcl1 = 'TG', 'TV', 'TSOI', 'H2OSOI' -/ - - - - - - -Adding auxiliary history files and changing output -frequency - -The hist_fincl2 through hist_fincl6 set of -namelist variables add given history fieldnames to auxiliary history file "streams", and -hist_fexcl2 through hist_fexcl6 set of -namelist variables remove given history fieldnames from history file auxiliary "streams". -A history "stream" is a set of history files that are produced at a given frequency. -By default there is only one stream of monthly data files. To add more streams you -add history fieldnames to hist_fincl2 through -hist_fincl6. The output frequency and the way averaging is done -can be different for each history file stream. By default the primary history files -are monthly and any others are daily. You can have up to six active history streams, but you need -to activate them in order. So if you activate stream "6" by setting -hist_fincl6, but if any of hist_fincl2 through -hist_fincl5 are unset, only the history streams up to the first blank one -will be activated. - - -The frequency of the history file streams is given by the namelist variable -hist_nhtfrq which is an array of rank six for each history stream. -The values of the array hist_nhtfrq must be integers, where the -following values have the given meaning: - -Positive value means the output frequency is the number of -model steps between output. - -Negative value means the output frequency is the absolute -value in hours given (i.e -1 would mean an hour and -24 would mean a full day). Daily -(-24) is the default value for all auxiliary files. - -Zero means the output frequency is monthly. This is the -default for the primary history files. - - - - -The number of samples on each history file stream is given by the namelist variable -hist_mfilt which is an array of rank six for each history stream. -The values of the array hist_mfilt must be positive integers. By -default the primary history file stream has one time sample on it (i.e. output is -to separate monthly files), and all other streams have thirty time samples on them. - - -A sample user namelist &usernlclm; turning on four extra file -streams for output: daily, six-hourly, hourly, and every time-step, -leaving the primary history files as monthly, and changing the number -of samples on the streams to: yearly (12), thirty, weekly (28), daily (24), and daily -(48) is: - -Example &usernlclm; namelist adding auxiliary history files and changing output frequency - -&clm_inparm - hist_fincl2 = 'TG', 'TV' - hist_fincl3 = 'TG', 'TV' - hist_fincl4 = 'TG', 'TV' - hist_fincl5 = 'TG', 'TV' - hist_nhtfrq = 0, -24, -6, -1, 1 - hist_mfilt = 12, 30, 28, 24, 48 -/ - - - - - - -Removing all history fields - -Sometimes for various reasons you want to remove all the history fields either -because you want to do testing without any output, or you only want a very small -custom list of output fields rather than the default extensive list of fields. -By default only the primary history files are active, so technically using -hist_fexcl1 explained in the first example, you could list -ALL of the history fields that are output in -hist_fexcl1 and then you wouldn't get any output. However, as -the list is very extensive this would be a cumbersome thing to do. So to facilitate -this hist_empty_htapes allows you to turn off all default output. -You can still use hist_fincl1 to turn your own list of fields -on, but you then start from a clean slate. -A sample user namelist &usernlclm; turning off all history -fields and then activating just a few selected fields (ground and vegetation temperatures -and absorbed solar radiation) is: - -Example &usernlclm; namelist removing all history fields - -&clm_inparm - hist_empty_htapes = .true. - hist_fincl1 = 'TG', 'TV', 'FSA' -/ - - -Note, you could also build adding the "-noio" option to &CLMCONFIG;. But, this would -build the model without history output and you wouldn't be able to add that in later. - - - - -Various ways to change history output averaging flags - -There are two ways to change the averaging of output history fields. The first is using -hist_avgflag_pertape which gives a default value for each history -stream, the second is when you add fields using hist_fincl*, you add -an averaging flag to the end of the field name after a colon (for example 'TSOI:X', would -output the maximum of TSOI). -The types of averaging that can be done are: - -A Average, over the output interval. -I Instantaneous, output the value at the output interval. -X Maximum, over the output interval. -M Minimum, over the output interval. - - -The default averaging depends on the specific fields, but for most fields is an average. -A sample user namelist &usernlclm; making the monthly output -fields all averages (except TSOI for the first two streams and FIRE for the 5th stream), -and adding auxiliary file streams for instantaneous (6-hourly), -maximum (daily), minimum (daily), and average (daily). For some of the fields we -diverge from the per-tape value given and customize to some different type of -optimization. - -Example &usernlclm; namelist with various ways to average history fields - -&clm_inparm - hist_empty_htapes = .true. - hist_fincl1 = 'TSOI:X', 'TG', 'TV', 'FIRE', 'FSR', 'FSH', - 'EFLX_LH_TOT', 'WT' - hist_fincl2 = 'TSOI:X', 'TG', 'TV', 'FIRE', 'FSR', 'FSH', - 'EFLX_LH_TOT', 'WT' - hist_fincl3 = 'TSOI', 'TG:I', 'TV', 'FIRE', 'FSR', 'FSH', - 'EFLX_LH_TOT', 'WT' - hist_fincl4 = 'TSOI', 'TG', 'TV:I', 'FIRE', 'FSR', 'FSH', - 'EFLX_LH_TOT', 'WT' - hist_fincl5 = 'TSOI', 'TG', 'TV', 'FIRE:I', 'FSR', 'FSH', - 'EFLX_LH_TOT', 'WT' - hist_avgflag_pertape = 'A', 'I', 'X', 'M', 'A' - hist_nhtfrq = 0, -6, -24, -24, -24 -/ - - - - - -In the example we put the same list of fields on each of the tapes: soil-temperature, -ground temperature, vegetation temperature, emitted longwave radiation, reflected -solar radiation, sensible heat, total latent-heat, and total water storage. We also -modify the soil-temperature for the primary and secondary auxiliary tapes by outputting -them for a maximum instead of the prescribed per-tape of average and instantaneous -respectively. For the tertiary auxiliary tape we output ground temperature instantaneous -instead of as a maximum, and for the fourth auxiliary tape we output vegetation -temperature instantaneous instead of as a minimum. Finally, for the fifth auxiliary -tapes we output FIRE instantaneously instead of as an average. - - - - -We also use hist_empty_htapes as in the previous example, -so we can list ONLY the fields that we want on the primary history tapes. - - - - - -Outputting history files as a vector in order to analyze -the plant function types within gridcells - -By default the output to history files are the grid-cell average of all land-units, and -vegetation types within that grid-cell, and output is on the -full 2D latitude/longitude grid with ocean masked out. Sometimes it's important to -understand how different land-units or vegetation types are acting within a grid-cell. -The way to do this is to output history files as a 1D-vector of all land-units and vegetation -types. In order to display this, you'll need to do extensive post-processing to make sense -of the output. Often you may only be interested in a few points, so once you figure out the -1D indices for the grid-cells of interest, you can easily view that data. 1D vector output -can also be useful for single point datasets, since it's then obvious that all data is for the -same grid cell. - - -To do this you use hist_dov2xy which is an array of rank six for -each history stream. Set it to -.false. if you want one of the history streams to be a 1D vector. -You can also use hist_type1d_pertape if you want to average over all the: -Plant-Function-Types, columns, land-units, or grid-cells. -A sample user namelist &usernlclm; leaving the primary monthly -files as 2D, and then doing grid-cell (GRID), column (COLS), -and no averaging over auxiliary tapes output daily for a single field -(ground temperature) is: - -Example &usernlclm; namelist outputting some files in 1D Vector format - -&clm_inparm - hist_fincl2 = 'TG' - hist_fincl3 = 'TG' - hist_fincl4 = 'TG' - hist_fincl5 = 'TG' - hist_fincl6 = 'TG' - hist_dov2xy = .true., .false., .false., .false. - hist_type2d_pertape = ' ', 'GRID', 'COLS', ' ' - hist_nhtfrq = 0, -24, -24, -24 -/ - - - - -LAND and COLS are also options to the pertape averaging, but currently there is a bug -with them and they fail to work. - - - - - -Technically the default for hist_nhtfrq is for primary files -output monthly and the other auxiliary tapes for daily, so we don't actually have -to include hist_nhtfrq, we could use the default for it. Here -we specify it for clarity. - - - - -Visualizing global 1D vector files will take effort. You'll probably want -to do some post-processing and possibly just extract out single points of interest -to see what is going on. Since, the output is a 1D vector, of only land-points -traditional plots won't be helpful. The number of points per grid-cell will also -vary for anything, but grid-cell averaging. You'll need to use the output fields -pfts1d_ixy, and pfts1d_jxy, to get the mapping -of the fields to the global 2D array. pfts1d_itype_veg gives you -the PFT number for each PFT. Most likely you'll want to do this analysis in a -data processing tool (such as NCL, Matlab, Mathmatica, IDL, etcetera that is able -to read and process &netcdf; data files). - - - - - -Outputting multi-layer snow history fields - -A number of history fields provide information about individual snow layers: -SNO_ABS, SNO_T, SNO_GS, -SNO_Z, SNO_LIQH2O, -SNO_ICE, SNO_TK, and -SNO_BW; there is also an auxiliary field to aid -interpretation: SNO_EXISTENCE (described below). These fields -are inactive by default, but can be enabled like other history fields. If the -maximum number of snow layers is 5 (for example), then the layers of these -fields are arranged on the history file so that layer 1 is at the top of the -snow pack, and layer 5 only exists if the snow is deep enough to support all -layers. - - -Because snow layers can come into and out of existence, these fields can be -challenging to interpret. It is easiest to analyze these fields if you do output -every time step, and do not average to the grid cell (i.e., dov2xy = -.false.). Otherwise, a few principles should be kept in mind when -working with these fields: - -Temporal averages are taken only over times when a given snow layer exists -Grid cell averages are taken only over columns in which a given snow layer exists -SNO_EXISTENCE gives the fraction of the averaging -period in which a given snow layer existed. For grid cell averages, this gives -the weighted spatial fraction of the columns in which a snow layer existed for -this averaging period. This is most useful for subsetting grid cells for -analysis. For example, grid cells that have SNO_EXISTENCE = 1 -for all snow layers can be analyzed most easily. - - - -Here is a simple example illustrating this averaging; this considers a given -snow layer, L: - - -Assume a grid cell with 2 columns, with averaging done over 4 time steps. Column -#1 has subgrid weight 0.2, and no snow in layer L in any time -step. Column #2 has subgrid weight 0.8, and has snow in layer -L in time steps 3 and 4; the snow field of interest has -values 1.0 and 2.0 in these two time steps, for this layer. - - -SNO_EXISTENCE is then 0.8*(2/4) = 0.4. The snow field's value -would be 1.5 (note that times and columns with no snow in this layer are simply -ignored). - - -Finally, note that the SNOABS field is not computed for urban -columns, so it will have a missing value if snow only exists over urban columns -for a given snow layer. - - - - -Conclusion to namelist examples - -We've given various examples of namelists that feature the use of different namelist options -to customize a case for particular uses. Most the examples revolve around how to customize the -output history fields. This should give you a good basis for setting up your own &clm; namelist. - - - - - - - - - -Customizing the &datm; Namelist and Streams files - -When running "I" compsets with &clm; you use the &datm; model to give atmospheric -forcing data to &clm;. There are four ways to customize &datm;: - - -&datm; Main Namelist (datm_in) - - -&datm; Stream Namelist (datm_atm_in) - - -&datm; stream files - - -&datm; template file -(Tools/Templates.datm.cpl7.template) - - -The -Data Model Documentation gives the details of all the options for the data -models and for &datm; specifically. It goes into detail on all namelist items both for -&datm; -and for &datm; streams. It shows examples of stream files and talks about their use. In - we talk about editing the CLM and &datm; -template files. So here we won't talk about the &datm; template file, and we won't list -ALL of the &datm; namelist options, nor go into great details about stream files. But, -we will talk about a few of the different options that are relevant for running with -&clm;. All of the options for changing the namelists or stream files is done by editing -the Buildconf/datm.buildnml.csh file. - - -Because, they aren't useful for work with &clm; we will NOT discuss any of the options -for the main &datm; namelist. Use the &datm; Users Guide at the link above to find -details of that. For the streams namelist we will discuss three items: - - -mapalgo - - -taxmode - - -tintalgo - - -And for the streams file itself we will discuss: - - offset - -Again everything else (and including the above items) are discussed in the Data Model -User's Guide. Of the above the last three: offset, taxmode and tintalgo are all closely -related and have to do with the time interpolation of the &datm; data. - - - - -mapalgo - -mapalgo sets the spatial interpolation method to go from the -&datm; input data to the output &datm; model grid. The default is -bilinear. For CLM1PT we set it to nn to just -select the nearest neighbor. This saves time and we also had problems running the -interpolation for single-point mode. - - - - -taxmode - -taxmode is the time axis mode. For &clm; we usually have it -set to cycle which means that once the end of the data is reached -it will start over at the beginning. The extend modes is used -have it use the last time-step of the forcing data once it reaches the end of forcing -data (or use the first time-step before it reaches where the forcing data starts). -See the warning below about the extend mode. - - -THE extend OPTION NEEDS TO BE USED WITH CAUTION! -It is only invoked by default for the CLM1PT mode and is only intended for the -supported urban datasets to extend the data for a single time-step. If you have the -model run extensively through periods in this mode you will effectively -be repeating that last time-step over that entire period. This means the -output of your simulation will be worthless. See bug 1377 in the &KnownBugs; file for -more information on this issue. - - - - - - -offset (in the stream file) - -offset is the time offset in seconds to give to each stream -of data. Normally it is NOT used because the time-stamps for data is set correctly -for each stream of data. Note, the offset may NEED to be -adjusted depending on the taxmode described above, or it may -need to be adjusted to account for data that is time-stamped at the END of an -interval rather than the middle or beginning of interval. The -offset can is set in the stream file rather than on the -stream namelist. For data with a taxmode method of -coszen the time-stamp needs to be for the beginning of the interval, -while for other data it should be the midpoint. The offset can be -used to adjust the time-stamps to get the data to line up correctly. - - - - -tintalgo - -tintalgo is the time interpolation algorithm. For &clm; we usually -use one of three modes: coszen, nearest, or -linear. We use coszen for solar data, -nearest for precipitation data, and linear -for everything else. If your data is half-hourly or hourly, nearest -will work fine for everything. The coszen scaling is useful for -longer periods (three hours or more) to try to get the solar to match the cosine of -the solar zenith angle over that longer period of time. If you use -linear for longer intervals, the solar will cut out at night-time -anyway, and the straight line will be a poor approximation of the cosine of the -solar zenith angle of actual solar data. nearest likewise would -be bad for longer periods where it would be much higher than the actual values. - - -For coszen the time-stamps of the data should correspond to the -beginning of the interval the data is measured for. Either make sure the time-stamps -on the datafiles is set this way, or use the offset described above -to set it. - - - - -For nearest and linear the time-stamps of the -data should correspond to the middle of the interval the data is measured for. Either -make sure the time-stamps on the datafiles is set this way, or use the -offset described above to set it. - - - - - - -In the sections below we go over each of the relevant DATM_MODE -options and what the above &datm; settings are for each. This gives you examples -of actual usage for the settings. We also describe in what ways you might want -to customize them for your own case. - - - -&CLMQIAN; mode and it's &datm; settings - -In &CLMQIAN; mode the Qian dataset is used which has 6-hourly -solar and precipitation data, and 3-hourly for everything else. -The dataset is divided into those three data streams: solar, precipitation, -and everything else (temperature, pressure, humidity and wind). The time-stamps -of the data were also adjusted so that they are the beginning of the interval -for solar, and the middle for the other two. Because, of this the -offset is set to zero, and the tintalgo -is: coszen, nearest, and -linear for the solar, precipitation and other data -respectively. taxmode is set to cycle -and mapalgo is set to bilinear so that -the data is spatially interpolated from the input T62 grid to the grid the atmosphere -model is being run at. - - -Normally you wouldn't customize the &CLMQIAN; settings, but you might replicate -it's use for your own global data that had similar temporal characteristics. - - - - -CLM1PT mode and it's &datm; settings - -In CLM1PT mode the model is assumed to have half-hourly or hourly data -for a single-point. For the supported datasets that is exactly what it has. -But, if you add your own data you may need to make adjustments accordingly. -Using the &CLMUSRDAT; option you can easily extend this mode for your own -datasets that may be regional or even global and could be at different temporal -frequencies. If you do so you'll need to make adjustments to your &datm; settings. -The dataset has all data in a single stream file. The time-stamps -of the data were also adjusted so that they are at the middle of the interval. -Because, of this the offset is set to zero, and the -tintalgo is set to nearest. -taxmode is set to extend -and mapalgo is set to nn so that -simply the nearest point is used. - - -If you are using your own data for this mode and it's not at least hourly -you'll want to adjust the &datm; settings for it. If the data is three or -six hourly, you'll need to divide it up into separate streams like in -&CLMQIAN; mode which will require fairly extensive changes to the &datm; -namelist and streams files. For an example of doing this see -. - - - - -&CPLHIST; mode and it's &datm; settings - -In &CPLHIST; mode the model is assumed to have 3-hourly for a global grid from -a previous &cesm; simulation. Like &CLMQIAN; mode the data is divided into -three streams: one for precipitation, one for solar, and one for everything else. -The time-stamps for Coupler history files for &cesm; is at the end of the interval, -so the offset needs to be set in order to adjust the time-stamps to what it needs -to be for the tintalgo settings. For precipitation -taxmode is set to nearest so the -offset is set to -5400 seconds so that -the ending time-step is adjusted by an hour and half to the middle of the interval. -For solar taxmode is set to coszen so the -offset is set to -10800 seconds so that -the ending time-step is adjust by three hours to the beginning of the interval. -For everything else taxmode is set to -linear so the offset is set to --5400 seconds so that the ending time-step is adjusted by an -hour and half to the middle of the interval. - - -Normally you wouldn't modify the &datm; settings for this mode. However, if you -had data at a different frequency than 3-hours you would need to modify the -offset and possibly the taxmode. The other -two things that you might modify would be the path to the data (which you can -change in the &datm; template see ) or -the domain file for the resolution (which is currently hardwired to f09). For -data at a different input resolution you would need to change the domain file -in the streams file to use a domain file to the resolution that the data comes in -on. - - - - - - - -Conclusion to customizing chapter - -We've given extensive details on customizing cases with &clm;, by choosing compsets, by changing -&configure; options and interacting with the &clm; "&configure;" and "&buildnml;" scripts, -we've given details on all of the &clm; namelist items, and finally given some -instruction in customizing the &datm; namelist and streams files. In the next chapter we talk -about further ways to customize cases with &clm; by creating your own datasets using the tools -provided in &clm;. - - - - diff --git a/doc/UsersGuide/get_Icaselist.pl b/doc/UsersGuide/get_Icaselist.pl deleted file mode 100755 index 6aefc26159..0000000000 --- a/doc/UsersGuide/get_Icaselist.pl +++ /dev/null @@ -1,136 +0,0 @@ -#!/usr/bin/env perl -#----------------------------------------------------------------------------------------------- -# -# get_Icaselist.pl -# -# This utility gets a list of the I cases from the CCSM compset database. -# -#----------------------------------------------------------------------------------------------- - -use strict; -use Cwd; -use English; -use Getopt::Long; -use IO::File; -use IO::Handle; -#----------------------------------------------------------------------------------------------- - -sub usage { - die <autoflush(); - -#----------------------------------------------------------------------------------------------- -my $cwd = getcwd(); # current working directory -my $cfgdir; # absolute pathname of directory that contains this script -$cfgdir = $cwd; - -#----------------------------------------------------------------------------------------------- -# Parse command-line options. -my %opts = ( - ); -GetOptions( - "h|help" => \$opts{'help'}, -) or usage(); - -# Give usage message. -usage() if $opts{'help'}; - -# Check for unparsed argumentss -if (@ARGV) { - print "ERROR: unrecognized arguments: @ARGV\n"; - usage(); -} - -# Check for manditory case input if not just listing valid values - -my %cfg = (); # build configuration - -#----------------------------------------------------------------------------------------------- - -# Check for the configuration definition file. -my $config_def_file = "config_definition.xml"; -my $case_def_dir = "$cfgdir/../../../../../scripts/ccsm_utils/Case.template"; -(-f "$case_def_dir/$config_def_file") or die <<"EOF"; -** Cannot find configuration definition file \"$config_def_file\" in directory - \"$case_def_dir\" ** -EOF - -# Compset definition file. -my $compset_file = 'config_compsets.xml'; -(-f "$case_def_dir/$compset_file") or die <<"EOF"; -** Cannot find compset parameters file \"$compset_file\" in directory - \"$case_def_dir\" ** -EOF - -my $xml_dir = "$cfgdir/../../../../../scripts/ccsm_utils/Tools/perl5lib"; -# The XML::Lite module is required to parse the XML configuration files. -(-f "$xml_dir/XML/Lite.pm") or die <<"EOF"; -** Cannot find perl module \"XML/Lite.pm\" in directory - \"$xml_dir\" ** -EOF - - -#----------------------------------------------------------------------------------------------- -my @dirs = ( $cfgdir, $xml_dir, $case_def_dir ); -unshift @INC, @dirs; -require XML::Lite; -require ConfigCase; - -#----------------------------------------------------------------------------------------------- -my $cfg_ref = ConfigCase->new("$case_def_dir/$config_def_file"); -print_compsets( "$case_def_dir/$compset_file" ); - -#----------------------------------------------------------------------------------------------- -# FINNISHED #################################################################################### -#----------------------------------------------------------------------------------------------- - -#------------------------------------------------------------------------------- - -sub print_compsets -{ - # Print all currently supported valid compsets - - my ($compset_file) = @_; - my $xml = XML::Lite->new( $compset_file ); - my $root = $xml->root_element(); - - # Check for valid root node - my $name = $root->get_name(); - $name eq "config_compset" or die - "file $compset_file is not a compset parameters file\n"; - - # Read the compset parameters from $compset_file. - my @e = $xml->elements_by_name( "compset" ); - my %a = (); - my %data; - while ( my $e = shift @e ) { - %a = $e->get_attributes(); - my $sname = $a{'SHORTNAME'}; - if ($a{GRID_MATCH} && exists($data{$sname}) && defined($data{$sname}{'DESC'} && defined($a{'DESC'}) ) ) { - if ( $data{$sname}{'DESC'} =~ /^INVALID:/ ) { - $data{$sname}{'DESC'} = $a{'DESC'}; - } - } elsif ( $a{'SHORTNAME'} =~ /^I/ ) { - $data{$sname}{'NAME'} = $a{'NAME'}; - $data{$sname}{'DESC'} = $a{'DESC'}; - } - } - print "\n"; - foreach my $sname ( sort(keys(%data)) ) { - print "$data{$sname}{'NAME'}" . - "($sname)\n"; - print "$data{$sname}{'DESC'}\n"; - } - print "\n"; -} - diff --git a/doc/UsersGuide/limitLineLen.pl b/doc/UsersGuide/limitLineLen.pl deleted file mode 100755 index 25f1216d06..0000000000 --- a/doc/UsersGuide/limitLineLen.pl +++ /dev/null @@ -1,104 +0,0 @@ -#!/usr/bin/env perl -# -# Limit the line length for output designed to go into the document. -# -use strict; -use Cwd; -use English; -use IO::File; -use Getopt::Long; -use IO::Handle; -#----------------------------------------------------------------------------------------------- - -# Get the directory name and filename of this script. If the command was -# issued using a relative or absolute path, that path is in $ProgDir. Otherwise assume the -# command was issued from the current working directory. - -(my $ProgName = $0) =~ s!(.*)/!!; # name of this script -my $ProgDir = $1; # name of directory containing this script -- may be a - # relative or absolute path, or null if the script - # is in - # the user's PATH -my $nm = "$ProgName::"; # name to use if script dies -my $scrdir; -if ($ProgDir) { - $scrdir = $ProgDir; -} else { - $scrdir = getcwd() -} -my $limitLen = 99; - -sub usage { - my $msg = shift; - - print "ERROR:: $msg\n"; - die < -OPTIONS - -l = Limit line length to this value (default $limitLen) -EOF -} - -sub LengthofwhiteSpaceNearLength { - my $line = shift; - my $leng = shift; - - my $l = $leng; - while( substr( $line, $l, 1 ) !~ /\s|:|,|\// ) { - # First search for white-space before desired length -- and then after - if ( $l <= $leng ) { - $l--; - } else { - $l++; - } - # Once reach beginning of line, go to the desired length+1 and increment - if ( $l < 0 ) { $l = $leng+1; } - # Once reach the very end of the line die as couldn't break it - if ( $l >= length($line) ) { - die "ERROR : went through entire line and did NOT find a place to break it\n"; - } - } - return( $l ); -} - -my %opts = ( limitLen => $limitLen ); - -GetOptions( - "l=s" => \$opts{'limitLen'}, -) or usage(); - -if ( $#ARGV != 0 ) { - &usage( "Wrong number of command line arguments" ); -} - -$limitLen = $opts{'limitLen'}; - -my $inputFile = $ARGV[0]; - -if ( ! -f $inputFile ) { - &usage( "Input file does NOT exist : $inputFile" ); -} - -my $fh = IO::File->new($inputFile, '<') or die "** $nm - can't open input file: $inputFile\n"; - -while (my $line = <$fh>) { - - while( length($line) > $limitLen ) { - print STDERR "Line length over $limitLen\n"; - my $lenlim = &LengthofwhiteSpaceNearLength( $line, $limitLen ); - if ( ($lenlim == length($line)) || $lenlim < 0 ) { - print "Can NOT truncate long line: $line\n"; - die "ERROR : Having trouble breaking a long line\n"; - } - my $substring = substr( $line, 0, $lenlim+1 ); - print "$substring \\ \n"; - my $newline = " " . substr( $line, $lenlim+1, length($line) ); - $line = $newline; - } - print $line; - -} -$fh->close; - - diff --git a/doc/UsersGuide/modelnl/Makefile b/doc/UsersGuide/modelnl/Makefile deleted file mode 100644 index 595a1b3a3e..0000000000 --- a/doc/UsersGuide/modelnl/Makefile +++ /dev/null @@ -1,85 +0,0 @@ -# -# Makefile to create HTML documentation of namelists -# -SCRNLDIR := ../../../../../../scripts/doc/modelnl -VPATH := . $(SCRNLDIR) ../../../../../drv/bld/namelist_files ../../../../../glc/cism/bld/namelist_files \ - ../../../../../atm/datm/bld/namelist_files ../../../../../../scripts/ccsm_utils/Case.template \ - ../../../../../../scripts/ccsm_utils/Machines ../../../../../rof/rtm/bld/namelist_files \ - ../../../bld/namelist_files ../.. -SOURCES := namelist_definition_drv.xml namelist_definition_cism.xml namelist_definition.xml \ - namelist_definition_rtm.xm namelist_definition_datm.xml config_definition.xml \ - config_grid.xml config_machines.xml config_compsets.xml ChangeSum -TAGFILE := clmtag.txt - -CWD := $(shell pwd ) -ALLOUT := $(CWD)/clm_nl_drv.html $(CWD)/clm_nl_cism.html $(CWD)/clm_nl_clm.html $(CWD)/clm_nl_rtm.html \ - $(CWD)/clm_nl_datm.html $(CWD)/clm_env_case.html $(CWD)/clm_env_build.html $(CWD)/clm_env_pesetup.html \ - $(CWD)/clm_env_run.html $(CWD)/clm_grid.html $(CWD)/clm_machines.html $(CWD)/clm_compsets.html \ - $(TAGFILE) $(CWD)/index.html - -all: $(ALLOUT) - -debug: - @echo "SOURCES = $(SOURCES)" - @echo "VPATH = $(VPATH)" - @echo "ALLOUT = $(ALLOUT)" - @echo "SCRNLDIR = $(SCRNLDIR)" - @echo "CWD = $(CWD)" - @echo "TAGFILE = $(TAGFILE)" - -.SUFFIXES: -.SUFFIXES: .xml .html .txt - -RM := /bin/rm - -CTAGNAME = $(shell cat $(TAGFILE) ) - - -$(TAGFILE): ChangeSum - head -3 $< | tail -1 | awk '{print $$1}' > $@ - -$(CWD)/index.html: $(TAGFILE) index.cpp - sed 's/CLMTAGNAME/$(CTAGNAME)/' index.cpp > $@ - -$(CWD)/clm_nl_drv.html: namelist_definition_drv.xml - cd $(SCRNLDIR) ; ./nldef2html_drv > $@ - -$(CWD)/clm_nl_cism.html: namelist_definition_cism.xml - cd $(SCRNLDIR) ; ./nldef2html_cism > $@ - -$(CWD)/clm_nl_clm.html: namelist_definition.xml - cd $(SCRNLDIR) ; ./nldef2html_clm > $@ - -$(CWD)/clm_nl_rtm.html: namelist_definition_rtm.xml - cd $(SCRNLDIR) ; ./nldef2html_rtm > $@ - -$(CWD)/clm_nl_datm.html: namelist_definition_datm.xml - cd $(SCRNLDIR) ; ./nldef2html_datm > $@ - -$(CWD)/clm_env_case.html: config_definition.xml - cd $(SCRNLDIR) ; ./xmldef2html_env_case > $@ - -$(CWD)/clm_env_build.html: config_definition.xml - cd $(SCRNLDIR) ; ./xmldef2html_env_build > $@ - -$(CWD)/clm_env_pesetup.html: config_definition.xml - cd $(SCRNLDIR) ; ./xmldef2html_env_pesetup > $@ - -$(CWD)/clm_env_run.html: config_definition.xml - cd $(SCRNLDIR) ; ./xmldef2html_env_run > $@ - -$(CWD)/clm_grid.html: config_grid.xml - cd $(SCRNLDIR) ; ./xmldef2html_grid > $@ - -$(CWD)/clm_machines.html: config_machines.xml - cd $(SCRNLDIR) ; ./xmldef2html_machines > $@ - -$(CWD)/clm_compsets.html: config_compsets.xml - cd $(SCRNLDIR) ; ./xmldef2html_compsets > $@ - -clean: - $(RM) -f $(ALLOUT) - -realclean: clean - $(RM) -f $(TAGFILE) - diff --git a/doc/UsersGuide/modelnl/index.cpp b/doc/UsersGuide/modelnl/index.cpp deleted file mode 100644 index c55aa64159..0000000000 --- a/doc/UsersGuide/modelnl/index.cpp +++ /dev/null @@ -1,45 +0,0 @@ - - - - - -CLM Namelist Definitions (CLMTAGNAME) - - - - - - -

- - -

CLM Tag: CLMTAGNAME

- -

Component Namelist Definitions

- - -

create_newcase files (supported machines, grids, compsets)

- - -

$CASEROOT xml files

- - - - - - diff --git a/doc/UsersGuide/modelnl/showinfo.js b/doc/UsersGuide/modelnl/showinfo.js deleted file mode 100644 index fd8a608472..0000000000 --- a/doc/UsersGuide/modelnl/showinfo.js +++ /dev/null @@ -1,193 +0,0 @@ - function applyFilter(filter_text) { - - // applying a filter hides all standard names not matching filter_text - // if filter_text contains no spaces, it is treated as a regexp - // otherwise, all substrings must occur somewhere - - var is_match = false; - var search_type = 'regexp'; - var search_help_text = false; - var num_matches = 0; - var is_boolean_and = true; - - search_help_text = (document.getElementById('search_help_text').checked); - is_boolean_and = (document.getElementById('logical_operator_and').checked); - - if (filter_text.indexOf(' ') == -1) { - search_type = 'regexp'; - var re = new RegExp(filter_text, 'i') - } - else { - search_type = 'string'; - var string_parts = filter_text.split(' '); - } - - allTRs = document.getElementsByTagName('tr'); - - for (var i = 0; i < allTRs.length; i++) { - curTR = allTRs[i]; - - if (curTR.id != '') { - - if (search_type == 'regexp') { - - is_match = curTR.id.substring(0, curTR.id.length - 3).match(re); - - if (search_help_text) { - - var helpText = document.getElementById(curTR.id.substring(0,curTR.id.length - 3) + '_help').innerHTML; - is_match = is_match || helpText.match(re); - } - } - else { - - if (is_boolean_and) { - var is_name_match = true; - for (var j = 0; j < string_parts.length && is_name_match; j++) { - - if (!curTR.id.match(new RegExp(string_parts[j], 'i'))) { - is_name_match = false; - } - } - } - else { - - var is_name_match = false; - for (var j = 0; j < string_parts.length && !is_name_match; j++) { - - if (curTR.id.substring(0, curTR.id.length - 3).match(new RegExp(string_parts[j], 'i'))) { - is_name_match = true; - } - } - } - - is_match = is_name_match; - - if (search_help_text) { - var helpText = document.getElementById(curTR.id.substring(0,curTR.id.length - 3) + '_help').innerHTML; - - if (is_boolean_and) { - var is_help_match = true; - - for (var j = 0; j < string_parts.length && is_help_match; j++) { - - if (!helpText.match(new RegExp(string_parts[j], 'i'))) { - is_help_match = false; - } - } - } - else { - - var is_help_match = false; - - for (var j = 0; j < string_parts.length && !is_help_match; j++) { - - if (helpText.match(new RegExp(string_parts[j], 'i'))) { - is_help_match = true; - } - } - } - - is_match = is_match || is_help_match; - - } - } - - if (!is_match) { - curTR.style.display = 'none'; - } - else { - num_matches++; - curTR.style.display = ''; - if (search_help_text) { - showHelp(curTR.id.substring(0,curTR.id.length - 3)); - } - else { - hideHelp(curTR.id.substring(0,curTR.id.length - 3)); - } - } - } - } - - var filter_matches = document.getElementById('filter_matches'); - var filter_matches_num = document.getElementById('filter_matches_num'); - var filter_matches_query = document.getElementById('filter_matches_query'); - - if (filter_text != '') { - filter_matches.style.visibility = 'visible'; - filter_matches_num.innerHTML = num_matches; - filter_matches_query.innerHTML = filter_text; - } - else { - filter_matches.style.visibility = 'hidden'; - } - - } // end function applyFilter() - - function clearFilter() { - - allTRs = document.getElementsByTagName('tr'); - - for (var i = 0; i < allTRs.length; i++) { - curTR = allTRs[i]; - if (curTR.id != '') { - curTR.style.display = ''; - hideHelp(curTR.id.substring(0,curTR.id.length - 3)); - - } - } - - var filter_matches = document.getElementById('filter_matches'); - filter_matches.style.visibility = 'hidden'; - - document.getElementById('filter_text').value = ''; - } - - function toggleHelp(standard_name) { - - // check for the existence of the help "tr" object for this standard_name - - var helpDiv = document.getElementById(standard_name + '_help'); - - if (helpDiv) { - - if (helpDiv.style.display != 'none') { - - helpDiv.style.display = 'none'; - - curArrow = document.getElementById(standard_name + '_arrow'); - curArrow.src = "./images/arrow_right.gif"; - } - else { - helpDiv.style.display = ''; - - curArrow = document.getElementById(standard_name + '_arrow'); - curArrow.src = "./images/arrow_down.gif"; - } - } - } - - - function showHelp(standard_name) { - - var helpDiv = document.getElementById(standard_name + '_help'); - - if (helpDiv) { - - helpDiv.style.display = ''; - curArrow = document.getElementById(standard_name + '_arrow'); - curArrow.src = "./images/arrow_down.gif"; - } - } - - function hideHelp(standard_name) { - - var helpDiv = document.getElementById(standard_name + '_help'); - - if (helpDiv) { - helpDiv.style.display = 'none'; - curArrow = document.getElementById(standard_name + '_arrow'); - curArrow.src = "./images/arrow_right.gif"; - } - } - diff --git a/doc/UsersGuide/modelnl/xmldef2html_compsets b/doc/UsersGuide/modelnl/xmldef2html_compsets deleted file mode 100755 index 2659beed17..0000000000 --- a/doc/UsersGuide/modelnl/xmldef2html_compsets +++ /dev/null @@ -1,162 +0,0 @@ -#!/usr/bin/env perl - -use strict; - -if ( $#ARGV != 0 ) { - die "Wrong number of input arguments -- should just enter one filename\n"; -} -my $infilename = $ARGV[0]; -if ( ! -f $infilename ) { - die "Input file: $infilename does NOT exist\n"; -} - -my @dirs = ('../../../../../../scripts/ccsm_utils/Tools/per5lib', '../../../../../../scripts//ccsm_utils/Tools/perl5lib/Build'); -unshift @INC, @dirs; -require XML::Lite; -use lib "../../../../../../scripts/ccsm_utils/Tools/perl5lib"; - -my $image_dir = "./images"; - -print <<"END_of_Start"; - - - - - - - CESM Component Models Namelist Definitions - - - - - - -

Search or Browse supported component sets

-

-This page contains the complete list of config_grid.xml variables available. They are grouped -by categories designed to aid browsing. Clicking on the name of a variable will display descriptive -information. If search terms are entered in the text box below, the list will be condensed to contain -only matched variables. -

- -
- - - - - - -
- - - -
- - - (separate search terms with spaces) -
- -
-
- - - -END_of_Start - -my $xml = XML::Lite->new( $infilename ); -my $root = $xml->root_element(); - -# Check for valid root node -my $name = $root->get_name(); -$name eq "config_compset" or die - "file $infilename is not a compset definition file\n"; - -# Print table -print_start_table("config_compsets.xml variables"); -my @e = $xml->elements_by_name( "compset" ); -my %a = (); -while ( my $e = shift @e ) { - %a = $e->get_attributes(); - - if ($a{'NAME'} =~ /I_/ ) { - my $var = $a{'NAME'}; - my $doc = "Description: $a{DESC} \n"; - my $grp = "$a{SHORTNAME}"; - print_row($var, $doc, $grp); - } -} -print_end_table(); - -# Finish -print <<"END_of_html"; - - -END_of_html - -#-------------------------------------------------------------------------------------------- - -sub print_start_table { - my $hdr = shift; - -print <<"START_table"; -

$hdr

- - - -START_table -} - -#-------------------------------------------------------------------------------------------- - -sub print_row { - - my $name = shift; - my $doc = shift; - my $grp = shift; - -print <<"END_of_row"; - - - - -END_of_row -} - -#-------------------------------------------------------------------------------------------- - -sub print_end_table { - -print <<"END_table"; -
Compset NameShort Name
- - - $name - - - $grp
-END_table -} - -#-------------------------------------------------------------------------------------------- - diff --git a/doc/UsersGuide/pergro.jpg b/doc/UsersGuide/pergro.jpg deleted file mode 100644 index a0cb81e046e802b41c5bfde3073bfb5e1903ccf3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 35642 zcmc$_cUY6bx-S}<3P_PEARq!lsDkufg#@L9CJ9C9Eg-!kB1Jlc03sm8gd)8qp)0*h z@4ZSFq}R*Z_nv#!T6^Df_WA2ho+tUfB;U+C&%ABk-*0XvZWaKP;1{4506aWAfcotV za5D{11`y!?qy6KZ;IGzLlLUnKZXcv1B__T7_W!Wm`~W<-hc}M5On~yhO%CoC+us-ZNo(FC+@EF4x=0hnj_S{nm9MwR>XXP=Sr0SRufDwx0PyP- ztkWFa0VU5qk9H8mPMOdADcmv$r-ui$Rh=_`pfi62e24#WOq+2E1CVAK$aZvwF`aJ) zT@N*df&hr@?1i(^9RNB|yGkM+GnRz9BGLR=x&cv`)CMp+zxO4$02@$?^_I^`x9s_> z!DN&wmIqjCv=Rn2_{+LU#*`o=NcTik5J(C@WqW^?hs=3(Puul$!Hub&-^#xKP}C%? zouxsl?}}~@uF2`J-BHGg^mzItQV9eU^kn?r!Lr(CgS+!QLzEfUx8mt-Xek`t(&eab zMIM6gBVX_uFbF$pAR%~*evd~Oe{bSE@|rfA2TW5H${V04r*)A}G0J@a0z$eFewEV&|BO@ydSbHa8z_Sn#!~?Fo(@PEJg%D%2P$s>ZJ+Kk{{gv^)^YOGi7>`Q%=jNNqm4c zZ(g6Nt%iEU)2+>*QKMx)P%iE1I$7$r5xPJ1ffiTU2?G`WBQPC=jxs0s>#QF@JWJp( zU-V=IwSFbDJeOToZx{Ll*W|2np+D(ht^7n~ExUHeAV|$~7TRG>qW7SD;iKUfJn$vj z4yqKNl@%Dm963}rr@`R-c>R=Xp;>T6rt?7{?^3|8=+n>euASlhhN?v^|uk^Xw}u;I*fGKC}Hp>}zzy0x-nqoJUneMjg@iTk$%BEr{^DCYvvwHrnaW~_=CP4`fr{Np=zn9Xc{Z;bgC1xmI3ZY z68!2;Ntch87*E>g+UYgE0dOvW!rz%Y>ft(5PW{{%fh2_7D4Fiy>VqQhgD;uqzK4H5 znn=74bxZ#cZfWHSdzE`Buv7FDlCED>^||r7p|wqkb(2w1NsmeEjpA#40}7)3wz`L% z<@d_=GQ(FZdZ)W*x}2Oek~iR(*i`|=03d(G6qsrOgs1Rv5;jqm&da*oYfa7?St%6t zsvK4RAk~nVnx+Q?;H;`)b1+j0!q=S!-FloX$qvfJA};%BdW9 zFN}JY#tV7RFa5)MLZe*3f{oNJfb>604{e1EUZY9PaQ|T=HkmvadIQ2i2b3 zvv2;)QU3UA2Dv=4>vH)mEQHaN+4kdM0<&E@9G}n}wpAcQ_;(8Jpmj9)1$LV`poTZb zf*p?>+;L|64jhTTbz;-hrSux8y5eq)SJ&ShQiR6MAk4PJPGQ3a~eORuClx2jT+z7O5yM$Pfg;35 zQw?j92eHf-o)oHblacbR-g*13x8M9n8pdpA+lV$^^(2o+n(8e&(;HbEHZ#coal~U# ziZCue()SxqW965!m;ct|wjxIpYiQP7G5l_H`y&6k5kJ2`F{(ho&k322mXqejSDehx z8|olPrReO0~Xbtr`l^5DbHZ}?4 ze$5Hfx#wZwz%yykKl)8UZ=8Ged+hWMdM&7xDUcdRHUqD)2tH38YB9{>nDorc z0&;FshA+t$G`I+}!wB^&?E$#~tTkec3>cNO%T5r4wYv)Rwf544$-)?WI;THjCmtODCI z=g`y_zbX1oZU6}a@>e>0H-HZ%ZVTHK$b(YN*X~Rd;@~#6-s%^`CYUzbE|*DCqSmUd zt06j6D2o48VQIjJGTxlMF?C7KulkW|1rbrAO?Jan4udRPO`G-I155IANd(1l*+r&! z9TV7x7B9^oTG|a33xW8Ac-DDbEN#j2jZ+>$b(Wj)HijWJ{bpT#8e>0sLMk zi(K)O4YQV};xT!LTMBAW=5c9b9fOYORrBtmsZUDH@@+Tze6XKz&ipu8Cc-XVU))S~ zHSi_r%IPa%Tp2TjCMh}CIQ~3s-cU9q6#f`BF3B48r{Adj8&iMw%u|^5h3kE9tX(_= z%LFwDu4EYNJ})NLCgC9BpcE4~OK*xSdwD@_LD*Z=Z?Yq#%=z)Dd#Hw0dsvze)y1Wf z8NvHp^1EW7oeB{Ca|)U^oYtr&Tg1DgT+XoJPO+%b9$-f?`o5ylQjW02Od<_=F%C`H zj2uufdt*2e0ZB-tkyPn3cJ+YbHRaXjIB8vE^IxG^Bx7*DsXUe20&y0L_Wf% zcb4kw1QXKd_pz2HT*}t-@4y1WUm{$iyOFuD)CX8XA3H^tfPl5}tem?azZ1L%BT%6n z!S^QEf2+Q?`#(t|48wl;S6K=@%Cx|BWH1y!-tv#p(I7ix&nE&Z)Q;k}G})B5Q4fww zJ>0bJx!nNnFTO6mc-VbLHRxE|{L9VxQ{+Vmf8&{Gm)*qpEDz`g;F2W;O#)tS21wrk z{0vz4^{@3m_6L~$sZOM-nRN+N>(~{4-Fp&63wBW)-S!?*;A+1P3#x&jSj_10BR?kLyMr$h^>wc3CIGbkl%JhQFSsQH1JvFJ*$Mt&B*llB^t)2T})$MpL8dz4m1!~0Pe zu07rN{dvPpC)ICn0JLVSx`DtWwx7wpTd7ZHB!zoh=pE-oItBRK@Yp`Y8l?(wb;L7U zjW{1?>)qA*SE1|2wG18+(M<}xWYH^=<;;Bq<4>XSE8;-rDFpO~;+dgU%i|1Y7~I;6 z#hKQ*UbD@h72lpEG>^siY{EHP0gCKk4qJr3f!5!G!@aAW*YDd5&$Man^~AZ3{F=um z>7H);$HnzJd5q$)M6?p6;gL`eu)714&Cbzr+kYP1ALt>MaRX>5q&WS41K`0gHl=e; zj-apco~D1eRjU}q;{G|}wLm5FQGJ*(Bruy-&#PH$rmAW3-zM*Hw}AY<#Ymt>ylhvp zCCqwJ0wr;v5qUflkb1IOJ0W!dNxh$Vk*>9qB^CIutE~6WORh%*O(JXl$EvS0TQ4TM z%E>$9_|Mdh-3wYnvZ)>^gNHuIKetnAY#O`z$}4#`a_)6~TqM6#c$rU9&BK)D+py>$ zCUw-pu;L%M_)d90{?n#zB#F{IoSYW~xGXNPKfeJOUel)k+mQ8wX8aHKT!gT@LWAxZ zbSl3GY08*=rAe(QB#>8N?SlJ6tmPi8nA{t{Kj~NQ_zeK^=-~|@|C0W(O(I_prn%V_ z=gJXIyMwtH-sZKd@K`7inqxl^E1gtuzv9vTCus}*>H0q;kN$_`=}~{Z`qerXv3Ist zV7|fWTCJ*NBB)wV@-ApP6C-F0qJOK2W^dHX|-E0X$Ll?U;yOZx&*0(sxOt>h23w>N5#U4oBhWDnFtoh8gst2P` zV{Fl$;DgK;J5GNMMyqR(H^LOID?YxIxm9<#+RneNc%Z?px~Ir&g{@7W3HM&mrO&St?v!2B`R)QFt7Bgn)D<$PQ$^6%>YZ*$1T{JOPKE`dg<^?{sRUoMTerUH^?K@hiI zx5t4H@jZ0@eW%W6_TOz34SxU6M*HTE^KCDFt;H$E-xBsOJjOI+S5?93>UMr|BE<>I zX1WT-g)QEVP@&(SGW~HK9~mZfvf0MRsFKv<&mX=m(>hAtD$Zu#MSnOcXj<3Zn7^1R zy8%R&9u(XF#Q)wpuQgn8_`^0yszJBfzF+S$!y{Wliu+SVtL+EICxJRQfOogf>wi~x zP^$3@!R?ARIvI4^8Bv3X`T;X#&BfIf}_siIs=IA?m~Np~l8&i)!i*Puku# zFFURp`Pmv-9fJ|V(x2{5$D?K9E=meCDRLqV`V0;<0?t?Ar;cuHuaa$WN&b-RT=h-4 zg5NoJGg-Wj3$SQUtB$3Jgk5Ttu2BDt$2pyB0>euf( zu`|W5FU7AJ#&Vv8Exqzi;*+XaLMR#zR$&j%nr)Vc)OP>=LYRC5zTi!jt#6b*Kq5|a zwiE}~3xkoUp%wQOeut{NX*r_h&+h zm56l}X+*KH!R1;aT(Hy^5ESCx)e^2$+}KIs2izvTvTn_Or~mqBY%qEX-lrDDOorKl zi^{4Gx=IfuFHPW;{g$h-C#!?Ta^)EP5*!W?^e~wW#dH9$|N(~j@A*P`r{0NS3 z^lqz-Z|Zy_I*nU*k8Ndi+xN5EyV{0?f3@R&yL8NbT80<2NezHu8;uzV#Yxd$MT>O2 z7G5&r$T?@SkM7j`Zq&$nH0IK_w1`$I8aAB~qP_V=&1zeul+A9`P^ua32{hyj>>pEn z`+-CRX41bO-*zf3JE7r%NmCX?Wx6@|V0u(pN9Pgb$9BFQy1rJ)jAVOou{yEMK}dJ6>~&s_6Q z@`Ln3+f#SS=|nu0nwj_rJKk4>AxZQ!e++r?d5t!|5eiJ`er?<%!pot4Fq!#)$H$QJ zU>H?N37_Q@U{m#b98~R1U~}Ysh{P^W%vK$c^`Vx>=-|IAJnRbHH)68zFAB*D+OJ0O zWn*RO22iB^9j!R?>H@_ENXaB zxf<3^8JzkXWi8C1&Zvdg)@pd1G@Qd*`VMe!x%UqC4)s8InXjxT| zI;V-O?w;4{glNhxY8j$S-j$7Y5@E z`s$<1TA(eeWAAT#uEF`aOAR@uK6!QfP9Qm8;kMBYKu+#KtvR+n@1E}oQrwnU`Q;Cc zR8qh97F^^J@#DNV`S~0Ge@}LO(RCKR)$Ld(U?67p1#bjQpMaABcGba(I5+XC2Sq7e zm31@e0zE3P-Yps=jKj3<|4BJls5IVV7&8+)VpzRof*^l5IaEMl_IfJ~6Ne`NZe0_w z`o(WN*fIUaIDM4=)t&X^b5p*PpDBzEmdqet z;B_j@8aPf?Rwu&nj7@C07rg@51bdC^s<(Ii@fvQ+B( z7hXot-l6{jLby}c`6x7O-aFDpjGy zfpG3uOh{1Xnj}iBjl0%9~fG$L! z-H>eqUoL_D%jqGZ-{X0svR$ks$uYHHMK7$07yr@u)k*2RuBk@7LcMR^LXUvFOWf0C zayqpD99wwsNR;p*XGpOEksX#(lKy*yx{l@Vujr>I3d%z7b;bP0M}(G&JmCp5E@}K- zgKomXUo+gJgrAdI%O#CZtJNOpm!bJ>r8bf9o(wyZ#d^vEe^X=C%IPL$tSsCSLzOIx zHPI;H%i`(@wN>0}xNO>++fy*F(2#9EgP$^)8oGC6o=`PKW3aT&w$8RA$)?U~dk4-P z!930z=FbOkIhK;*#ME;Z;(cFSjYBXgmOx3_UV1tvur^JOm=YCoI|CrX`=Dpy$$p`K z?+>>?Rh!eA>Ek`g&Po`=2@Tp0UiYW}Xnc@+)1RU=^4wR*$m_!soD9|YtET6-Xjb%S^XtO#rucXK#s60IU3X7g^6#Ztvrma1*+{kUpf%!9lskwJ z5u6;@WHtn3k<0rn^JOyXQKe<9#0i}9=y}Ioggxmm!bv0A4)&uTQ6`zsoJ=aITB)fP zt>I2bQBPs9Qh6!GVg}l+mcJ1SP|fi9(S(T|hOxKtE0T?`3nbQf-@Wwy!>AR2ta{`_ zBsHYFXa~Vo?i5-QeuNrQxLAdgFHFDs-koGrnO=^Is97;IbE%<^a5YGo12dl`FDc$5 z)&Wo|%v%Y3ml>YOSwpPk0JWdVp}IvPyw0SA0Fu4i#CvHw3}gOTzb5&VzD!^j@Jy z1O6J3(UBxe;84@Wzmj0Ouh9K!{`yA4_7zJT+E*i(RgW0I?;9ZJ&PHh%ss^=JDU|F4 zY%boN6=?5~)ihbDg6p86vv0+IpaGP$lZxP}h;4NM=VP*9tqQN)9s%9NwSMbns{Qm} z6|Ukk$HF8>WT%oe_+|KKAGsw{zjdIx=4Fy6S6fNa^W4L9St-|a3nuqbRUW&p-QBA_ zpF(|&(4YMcPIXW1*7{Prx_RWjZhD#A#;S1x2L|Vd``5lZ5i`H2u%?=#BF1pL&*QjH zLrOG33yNoY3OeI&6tuzNy~qS))3U^|KBI^XqKAB~RWjQ6p_8s+Yc*$RIHSkoE1FOg zWnim;W|G^EO*6K`$agr?m*(;nT)Zn4eJP7XtmL~z^ydcT}NkRj}`Jd}DVmh}w%u3cO} zY3EKf(CA@gf^S~*;T(53xoES>-ORo}$!RIf`~?%623n4It#_$Vv>X{hRRz)nZ(<@# zM&!p_dyI*JKi%x7bdtDV=iOVZKe1Jbg!vXoS_@gqd(-Ocyw zX45a&qh7l#Mi}j1_-k;(+nXqyq*PqPiFrZJChCS(jt*+p6^B_O+jqkyG9za**<-xt zncA6a{mdBRBfX=qaxO4*w)V*+O~CPT5fv-+z9H1Ez1lC4^Y>Wm0^B# zI{3)BTI+-=@QFu_8+7AD3lsiDT2AI<|AOpQ120y#g!}X8kgl-xH}Sqiwqqkc%+@!q znqvrzM@I=XNz9`I*s|GDFf90QfYl|BTA3TqV`@PwyO6#-(`Q>^E-t3bAEThq7?)!c z-)wJ@zW2c2pMNd6_(v zLb=pX?e{pjc?ADt;Hv%+TX4hAz?9;L-wg5gF@-V_@(-Tfn?{_cdwYQ+$iD7=7|CRP zwVNxew!QP{Z!U6bIbCko%UE)JD z`6wYuqUYHx)*`_S@hL_Ev5!Deb`t<)kE$MjEcx~wqpDLh)(YL(|3-t>66=O}%=$pX z5umG09{GJy@x@rtMvDp#YoE}*Gi+4)i!Z}_^u~59#3V*@zd|Sq2DJ9}4N5d}-gJG@ z-IQEd?pG?4J0FjEMt zKEBV=r{IzNjW2HgT#L~m`Blu9c^LOyDn;NNHisPhy;LuJRM~BI=@T5f`kc}JuRo{I zybt0pT*}qYMju#)N+|9B#z#5^*L8o5 zpluc|uC|^7{YJjnS*{Zu;m6Y{#3h+;cZ%0FJ2GW2uYVdr|JQ(S?D|BW*z~pVNwgc; zxvq1Mj`=WEpEW3U2&t~_35L*6iin{-<(vBaWgiCuuR{_~r+-PiT$c7W@^`c-w#lAp zxbEsPaAxHc?@h~!pEru?v8Yz$Ud4VU{o&{nbTZJ?;w-@SpdWkwsyI*W?eSUQdS@}| z&`X`WVJY{FmY^#BJ0Dy7=KzrVO2pDuN~vT2!0XtM-EAp{J*Y)@ZRO+w&m2o zbi53U&k6DflWn-B)`?J0MPQnMqma%NVu zO$g&uAK`B;woSl8kqICOGMZhXK=8gko|pQ|+UE}DrSV7O&+D*`6;sfYH4PV%*Kj6c zRvtV^1P6eMm?H>J^x+Y4SH+j|i5&y!pirr$@%CCIn!Fh0nAh<}w+w~LKxWo3Y7^Rj z%{r@OSuv$)6-tNFB5nZki4_`7Vn?}a=-`g?=9XRlDj@H$vnmAt=SKMiEkK<9n+IQj zMgGc=`Kx9U^6?~2=O)tFd8UdU<>4d7QmcIAd$)uU=o=OrM*^x_XF=fHIq1B z!yRxG((Xsw#0s^xwdd9mx0`Etg59xoeB^Dm@f!+SqxY0z>j}Ub)MwYrywhDJ&s<() z@HaRs-($Y2km8m+*)1+qVQIK`71rP*Gl^lsHAhEaw^lc$mZ#In{dskgDJvUe;;BMV z6(VvCdRk-H5}uZnk8h5*?k9gy89{6I@Mj!*fH}@CepB9-fG5BAXBTBo!5!TrncPoH zo*T^KhIHT@4O_1ED_;Vc=_rg+SZE77bnNmi0_HkvfFPiNfJ3-p&v)yw;a6ot40d?j za5kX&Ip9uE=`7IXiGDM8UF3g3$jQeR-T>O<2M|q!K5HfNNvF=u5VjIq~p2nUx|D^4!z?n{3r?@8EIiY3>G&UNf*;}FzHhCw0 zAIDMO>z;gd5+BUCi{^H>8_hX0o^?G$Behm+ocazNxp8jkaiobVbVZ=c*P2#A;cWhP z?pZHf+NX^mQ1V0F=p>r_@3k+2+AL$O_+ftLlsgb7mZd-qWXeOEyo|4X+4l3p%B7d~ z@C_5)(Kc#Y4<~6iP3JTQ?$~O6)IY-VE+rbEm$9c3q(1iJ+;CkgZBw3EuctcmakJI* z{pu$iFP_y!Z{%BnWo3UkEyU+gXQ2sE&i!FWrtj5-OA@_bzHA5~jXDdn+%Ef67@g^3 z#NS!^vKS0gE|-6T%*o8=h#8>!uk`qTR8AWOdLw&wR6P#a#t~?-V0S(0lGgWi7S|rp zc@KFLOHUTx>vnL`!V~2zSJfrVi;o3ca%WH`R@Fqf1QEpFeoD&lM;v#)FeCD4G!IcI ze0}W>Z|78>#_$ z@L%<;WNO(3bx=?3I9QD(V*~`nvKSBUnpq{G_}?U8Nx3J_5=|uEw!)9?NNPJhrjr&| z+yhs+k3AGJkXZqY&b~vG`2G|HfAwSqA65U_JO3>DbXFCEh+K4vOEKK7i;*3z*&ld2 zIk4}f_qXrGE8KLlsoKdxT@g>(TZAijiHE{_|Pd?-H`&-Zf`PeIJ?edKx`X zER?`zuMGA&_&Pbj4BMLK(4icEsRSIbvVs|k zsR-qCiv8gq0RcA#1$!yz?PG<*;n_z18paOc9`IYdQSO)4=GT5UlKF9qVk>*a;Jzc~ z`0un+f8*Z@!Goc?!tAG3?e|A3lE@dEToB`u*x(7?ybJIEG-tM5lYg zExgD0w?xdEk)!$Dxx(lM`IW$oVv44(FS{1nd{097`&BX%`i`AQ>&w}yG*r9D<8w3N z_RxSVWC#(5SbXr89r}6e=K`SkO-4IZ60SOf6G&j0cnr{EqHV?1rE&dQV_HW~i+6}1 zHQP(+(=6GAkC@v%hgbOgqWM8!k(3}P1ask`4bi@H@xw4GS+NCIyt#3jYTRkM?J+Y{ z)$7RyZDi9HcqHqo#%HG+Y^@++tG(MnVW>y5x(7BM3uq zq4-H;89)xlG3%g~)ro_OUi-zEsM+QL0ls8=tNOLt;d5Xy}YtwH27jgbS{No=Jr~TqFBPcQtac}a^HAugJXWsO9(ka?Y!o!$zfg*fpy!-$1Zl@WcNRasD&OIe)w`EbV=mb`Rz(abV3Vj8liLmNDV+qvUDKv=J2FpfpE+ zmXU*{>pY5IJwQ*MN1R3_@eXk+XVE+{Oz2~TV|{tzG>OinDRpIb<$_bttoPib*AItY zM?}t-uU(x`{4~vbY8>zHKeuElCzV-tBIEFz*RIGw+@)cbKj*f1^2h{X1Vxya=(^rh zKj*D`FPJ&`Z#x)*WibxF5b*^KMHm%SR{+J0LUL2SX#eylFl)DFsKxOpyj`Nm>1k_u zJw0E9ZFC(x>RJ6fO3eiqBR=*duSJ6dw#Px3-6r;XZ+K>I4DvMsCwKXp%IZa=Wql8? z3r2C!Ly;q7PYos~7rte@(Q-;Jc0kW)Q6GWu{az2wOomM~N~Ce-5*SPrAf}98dS_t_ za?`-U_%k}t^CVtX69qa=j^)L+bT^Bi^nn@v365`HnDpCse@){br`Zl4t?)hZ=%Aq_ zN8D5YLj*rU|Ji-++H!g@8#^a#X-WM={#l(XxcT~ViEbfbJYX9?SPw9u{WyTv{h!FW zaqBWEw@R98Y_@cXXYgXR;8P`s&GR&$weC0!x?(hA9u8I~L;>G&S(Kk=%AFoatLoQuwKi_sd8}$(oxAm-6dD(_ct)QkYrYMXgjJe)py&e_pt>Ki| zlb8_d(ChrPioLQ^_0@g5ilfSr-`qi-jZd8Yu`kW{aAcNaS{p8SA(+`xbMjs@kSpHk zxg;N{TW}38IH$(>cTLIO&-(H&Fhh?{_%E4Gx;q1Z(E|7-U*|oxo!grN8>{>HTs^wi ze;Copzwdl#p!j5g#Kc;#DrmSuqk$?I?fgm%m2|t!%ODvE=UXmbxy!8vZR4c>$j?H}nE&v_ zK3_j2pLX?z@Rcann(8|87eLHw^8&Jzx|@EFrE;oJYT+Jj`fjjiZ;RRDj*@9(nPPFh zbdYXi_u!>NnF196NyLFWU{a3A{fafGLy-&E&@cY5kzX<2MbHCw63D|l`>N!n@3_v- zI1T2f5r0;9_@S%aUh5$l@Kg4AFr=0}_J7SfSG_Ww<(N3tp37E?d7|3%ti?)XBxS5e zfS-ZCT9Ma<42R-~$AiF(2rN0(epcz(j5dE!yN`BmdS_L&Ch-=AIZob2aUCR2R||)5 zYUqC4M51{(p#bWopo@k2q`tH7*~ZZ2`$S^mR_F*f_VwrKKFQ7DIF#^CMyU%3#KBRF zr>0yHn9~HsGBpri+6gGsSUvx8GQ+Y9x}yS0+h4$3yb>(kmKE{;{bkDbU(zp%kTK>& z5*2HX@6shzRctFU$s>w*3V{RuRJCgV zf;?1n&?nH~2sW^61eZ--Ny4fIMkC^mVGGD7oXKj3dWR1cQmF88A>RMN;rTe#{&@a1 z=i>Bg%7gy>3ye^*#b;@Zbl9`LSlzz@h6b#TwQTWoc^9iZ9u%A^e1f$j6y|`f62WE* zmoW<%VP;4EmX*D&hG zuuARjnX0mVAG&sfrLk6lbLOb~1sD(jA11Z`Jx80wps?F1Ut%kgPmd?^u|~TQT4^Dl zdaGtq49=@ITS`I^i)>1lh*)Qpv_@bXzVh?-EfBYxt$G?liVSoTg@H zYxOE{>Kb!7@NgqA%iEXYv1r>trFY+omZoYk-vtF7;ZcRDiYWNrF*WBa{Hn4%f)Lw~ zjF^GKFu}kSNqd_DJ4wHX^^2yggeETyn-q zJe79IdX|t8=h^F3>^{w;09JRGvnd=?#^Tq1?SzUWFxA|=1)hv>E-GDXe4lb}ccrr1 z>S}7xoy3`6s(ChGra`7ZilwT6MepBV1#@Vb$30BX^-I`qD;zaa)ZC& zBkv*w>wjB)yiGxm^22pXSQ##obq23~UUO~rVzC+(-L=GWy7O8&*jYN8q(KKfstS}< zK3MSC+wabgTEfXH`UXUetwcR)G{G8J@rSOfgK)k!Xp&<%Bej(i72T&Bz#-?GQ%Jlg zq%?oq|E$y+XyL}xk!@u5In`NB@dU+LYAdsZ)T<8hG&Ctt*(x8q&aD_7v2~X?{4BJD z-fb7EH3a!MG>L6hz{g#~zk8%lb>Z5zoHnX^a#5#?2L*x$i_*@22bo(k?!FPBEtR@T zI!E*Py!bCb<$pb~hB7T!O?ywH{PjsE(!%;wW3JWR%VVxaw(L;JQ|wzYUK7VHeq%G* zHe+!qoVFjfQV#EZ*JUm3EIgEPd;qhrC91Cy3HB)I=fB4^g-oabLWJn zIqlV2WWvMS>f1lqjfMXn`?vxmgqs!Fx|v4|ppR$I(1?`*wNKUe8RrLR3P4ybvXImqAs)sZt*l}Ah8k4TZ{%v}z7 z7dEwvnH~|D;eQTIVbE|X+X8PRa>r17&c~sgAo+U6qcL>r=~uQ8mz}gnKdf>zrCKz6 zCpK9$@^vXB@)8H_{-7w_K=MZl2Z7a?fror+vwrpF^bRj>1MVlyXj~sdA(R2{Jx_Ne z6&jyX@5P6|#is>FaiIcU@~^lLZvdV2+#rYx%Hl-;3iw8B#=UAL1ii8~L!xd5A@Kwp zi0f}^Q>JT0)byXFF8T;cy513#dkRP`45enq$aE|}&j5e6c5gl(-=TQ{X;K*Ls9zf2 zr3uM0DfkaM_V5`*KZk|Kv|$ai4Ha({laurJWO2Y|uoo_TvpK%<_bz4~qE5(IRM?jO zCeFRp`ud>H$>irpiVGG6AeCJb4JqV}J1UY4!dje>*v6Lr2(QlBc{@ z0z_L>7_G>JJfl=sdlxk--x{j3>O z>$xRsqOqGN4qb(-zB8e0uY(sb16IG?(^TlaUxZb=h8OTnb9ZyioUT9kGEDWk{>Ou! z?UaGv_lpI@C`r_HJX-Nq&eZ>Seb2s7D+w`!^C5LzxCZP>X>gJJ_qYb$}+i08i+3@LIccNKW$%6I|W{}hhA>{y_6 zHB}V>PB;U{<}?&B0sY;89k8AK__XijPI(G;{2&i)vVO{wyupdT<;@&_2QwPwnm))d%Two&#tmhA7e(T(ok)ZDAiZx{{s7Q9 zz?Q5oiWBHTLts-|MGMSz&NrukoAW_W31R>u4>Qv%20mXZ&P zUj<)^e-kV_zl`JL8P6=K{`ZYrpUWqk=~YFIEz2$|_}vHRo!ba$iaGJxHZmI^GG${K`+J>t73VS>tEl^$x4S5f7dKxEN(nGBKm-#bLiYK9-I z`a5&By7)CJ20yn-k0>wt)drr#ZJ4}lU*YE*qd`oi=}PH3#8%}W`gLs4t@nd#Ea;-5 z=QStOQ>n7l0@gnptB5U)Oo5RhDV|gy4uTZ|1?PI+7|YLb^so7he9gsu?LwO*KiTud zF^p%xa-~(SU=B0KL+>}U4ECUTbgSbpx9)`|&J}f6^&&4ZGa(J0mZF?v2wF6^=jH^L zN=)LnVuSJjd4d>Eq|R+j-nRB-wd{uj<8U^)6%SeJyETn1p(H>ac&jj^irEp!5iFt> z+2#wuReLW<(py_-#Lmo&i^hjpb-*Yv^ohnJRLdH8uZo;ic>o{FUbMk43*JN_mU5^0 zqxILW*|1V82`@kSFNyBb!%u|EpP zLO$-XVdzLi0^792b7YP+3!iV8kHgd23@&4Y&5a)jZwUKyO=!d5TP~iV_=>VHZLZ@2 z{Z0+89nb_JdmhCrtaX3uk)*(QN7YBQ;~X}y7w&Jb~k|V zxR^+?MxyeMbkig+HDt|w?+Qq*IXoIKJ}`)utMXR`=`HnFQN`aLiFOQ$_{bw?Q#mL|Aw_W9eA27-~V z+z8!wo>Dzgw?fwdK%ZQ{hrbayeRxUhR;7x}zplT3qShs7Ycf6pd(*)if>+y=wg z6tcycjkIq8gF=G{@sq@85P0X5_bxstKycrr-XqGSJ?)-$Jndio*#&%N86(qC&DI`l zOz=kV)#VQ=JPyY#53E6EYw8_+#r(da=c2m z74~Gd8ss`3H}h1u7o?86Sdj)MXTaCBFbwbb?G)7Xa9L7ANd=bRRTsC{tzTM4oi@LQ zEv>|#!2PF>e`;b63$PL(Y{x1&d4m5}Om17}yvJB7;xt-%8dW{}ieONA779t?=Rg$! z6b<7AMoLH;jNpScQ!86I^pYB1LqEo6Kmb$??E2IuMUB#rzN#2h>lrSoJ=!mJXtNSD{f1*4c1<;Jbmh+|c*h|i@_9EDF`cgiMg&5{ z?ma30nz-xPGfvs$UD4&F+UV)v316A^G8Ka`V=F)KRY5J9Rxc{qm|E6YiZN#p+ z5*3SH3M5o&NPQdK=7Glv+?1_89^@{G|87?K<e-ekLiZp{;p(cB~x)O_483)Dw4;PXyWbW2?|7G6N6aI=`P0)A_aR)EwnepoA(yV8 z`wN8q)ACb{U+7R%N}kE_&N6I1vRuz^G_-%xYKcyezJR|2`}5Wj3D3QQlT}22nLrnq z;W(&lNyr~?;U!s+@7JAPj5&L};c3s+XPVug?vdwm&b>Y=)9dcq6#r0i!tKdK|73D5 zRZfZhMeM+9f!b<9H2W%nWjs&X{|sRNa4hO)x`L}|VQ~18=|l5TCtMT2)Y*uCNeb0g zttgP32LJpUsxg!SHU3SLH3b>!#vY)y{(8@k=JM0h*Bg$&o1SNqp=l?D9ifjTyl6fC zBs`&1E=Q{WDV9j6tjZ*`uG|${b65v9rMNV4!=6o$FaO#3^<7gg>ibIlNUEkSrOhe&=3f&L4tIn4Z#`-t_?IA zT!I953r=v?#v#F-;L=ENhu}_bzjyC*&VKhjweR=+Tvbn1cdh4{bIm#C7-OL&h(`TE zn@IFY%K}iEr!vP>g83}3c$$Ul1@70OdC~fTbgV3HfiWu}SXUWl)YJ0b&(LT6I3a}B z^5JLxgI4z3eUE#wD0ZXe9?Nd?$$p(^FedJQlOcdu)AqbNtsutVd}w-L#tP{#?A+iio|X)t$J`8N-75<*s#Fj7iK+$YZ> zBWATfu#+{IE0Ft^Jke~Ttk^LQM2b4@aTJ2z!B??n8Y+p~r^V!pgXF_ztM}|y$e+=K zebEKCEjJ+^49|omo*sIi^PN?oGnRxh>HOk7kO@xR9O91b)`Q9@JA!2T8MYs-r~mx7 zK~0c*PJ3Z*=hZH|n{`ZrUcAN{NDh{~&wyU=h`!-6GaOxFY1D4_!${*OJ?w68nvzWz zB2{TW_>5eMu9pW1(e=921xehS;}Bv?qd7&#I#)G_LI{|`*oj?jLA;~K{ZgIE5i`p_ zU}Nf}Rc5Jqm>cJzb@vwAY^F`X93;`i<91sfCW^=b@!f1}Y`H&Z(ImThtTvF)yxHRT zwAA?KDiEYqg|J{v{ygG-IDlCyJ2-pC&mWL{PzQW$71!&ZnAbt`t@Zg5WDz$c@ z=XzJ3Jl3{CmC~5t3Sz0cQR~HsxBMMiZd9Qjd@UKX33w+@0>CdI?rW02oE) zeQbEVKbUmw7=0SBq796D+3~w1w5rcm)SMriKkShy_(|2qI#ls$k$5KFlAHwKb^@dYJ)g? z4OyyvW3fJaa4O;QJ#W(y2Sq<@ok+|qo#Aorz8eL#wbohkR6-<`a~iBcah_u6RQkL0 zb3byf9z_SdAb&BH$X54%95-&t;m008Az{RtRFMI zFm55;`bdjYHipFR*TpYZ_QHHVz2sW0#N-{XoV3_=Apv@CUv_J0-W$=+6B|>Htp8Tv zmVZ3k;^S}|p$zLg#&Tf@3!h$VBAErUH+)enrJ2oNi4}*F=xyCa?uEng!JIVlUuIHN z()?`PloIcYIMD+Hh@<6L<{W!7WAm4Ss+ixj(ea_>gH>|#1uw?R$1yCSgL4#gV8@R% z1(|v3d*`og8h>xQKAgIz8Vr&RpY9yNDq?&lj@Kv77Gw6vEx;E~yQyA+ zAZ4NdnX~sduNHO3sZ`c&eI~8oEViQ|52KnniU_-FI|y=)1u6EY<&bd*A2^ zU&cuX`vW@^J==JDX!Ju$Goo{_W z#40H~6Y0)N90bT(G$a_P9V{d4ts} zWtA0JPoqO6i< z;iYtexiq|6yx|gPGPNEXNNwD%j~^6Z{oYQDxw_;9Y9Bh-WFqnLhrv5CjfHu z-u%V+k~p6RL+xGKeTV11O{7?0Cr0n<)=odaQo6yf|s{SM^jia$f2q$c7x#Rw4$mp@_9z!Hfl*I>SMuXshNsa*%l1^Q5mg>=_qbtLSD^#&2c1}+Hl zI_VcJX1&#GmS<>dk2Srx9Bgrn8c-mglm5`J*4A&vw+>)k`l4b(-L$;?A-MIVM~d{A zdo=P`Ny=HBKfWUu_&A7EV#cJR*iZiE^P2H6453Ry(3|e?K8eDQaEp=yFv%@^ae8mO z?xpPO#IHRNdUg*MF{mBN9{nw|=(%P25HGKNMrMLAa$LL0)4ltq=$)@@Vv^R$F>IS) zv9{-=Jx=A!J(p^aqu}y`isU3dZkEK0Po^!ydbQS zjX=3`s99ATGexUxQuZ7SV`};j+7a!J)cwuOe(AZD!&T>V2dC!Y>Uki)rD}S_@lRrH zc)Ptt87(!6lXYP2(^h%G!7~I*VyRfTHam9o?NATwf=9=m$kBrw8^z&UduuWn7*FpH7Gv`=Ga*sSWPlzKwdKw&rBU~3;J+;yfX1a-*8k<^;3}x z#HK#I6*qbskhze9XM8l*&Y1e`VnHfw1{hC=YvnmtWLl3Ni+zpX5)o65oIMenx;FP-2 z%$RM$+|WZIcX+~WJJ~NmDK5IS%{}UcA*{&T3dVEde5qpQUc|hv9H!m-v?hg#Q9dsY zwTmR_U)1#Yu$8F+?F}b<9V4~<~ zzIP*!t8;$aY~fY%Z?%)O+vpcgkqGaXl)-5g0zrh-vy&fmvWBJkOor6TZ_DNEG0Wa% zD=@NLx*uSkWA0y9DJx$*kX3;ij9Q|elGRIv7HlfZpyXvi6w0OoXMy~4@*uV9yuxjQ zGVjKxp#rDLZaWRS^~Qm*+HeIUcI1bQog1h-(_kF1AXkt|cHV8&O4w3DM_I8nih(fa zxShb<^`*m-Xvj#tCpes|)E`#fYf=@@v~3Jz@7ryT+vue*trJ;OW{p1l%n~d8=4f#W|w@^0)ekP|V)A8pykc5aL%qtbl zh~00h*PJhgTA5e%lgr|k{-A+a+&EDdtZHB)#wjw{Vfac4$jH9oJf*HFS+e$L>hPfv??QLlje8Nw^gczjf3zlbbGRAMMThHU%-ra|8tY4h6BSE@M)4c1OuMpI z#HGLeoAph8N|1u}>mq}(x(7w#sK9}^oBC9v;QJCslq@(Im2Gx2rZvQ`@AC{E2!H%R zyTvmtQf*s_aEbqehN6x&n`Jh2b|&p6-6Ur;YN7PLI?8|0oPPa5yNlpWh!QPhzO)?s zgI50s?ONMP?U1cU{vls%zrB}psLPt&Ao3!y{lM9I*r(HS`EF<5REavQ0ZEQ=vmIKO z;Pbr{6D1d$){nmpH&{(ueo*vD@R7JQxg9V_eVDX#lTizVHyzY_zaJ(KEorIM&Jq+a zrhp!K{>Wtn{5&|gW?kOB=H)yOOlj}d68RVQEWQ?C{&1Vo~w9B)S)A?DO z3&>BCfJA4X`c?2!Jj6OLoq)^nLX26ssd^4B(^j{CNkLus;6$o=Qs3s~K$USD^KcLSR)sj_lw=sQ$zcuE;+%PzTza?m9`oZLA= z3dTC0v`RVK#Of6&|;7da!UMAf8fJ^;Ib-p3e~y8*svKQWHhzn**2Ne03~Cn=m{jCxE( zbxadGo(DX1<$l7rpSmpWUr*E)i95VD!BhH>%2WLw0;@au9S8t*{ro>fg#LOg_+}*V z)yDVOveQ=_Rcx$Xo!uIqlKP8uD#m_876K=lsmjt4id9rbwp>*BBqJ5mL zsVl%bKrNlMp*b@GZ52`p0VzilV+oyLWpRl}eHRf~Y{OS67q2fqLU(O{Wjs5X`gT}g z-ak5<>YOAp7oFrx+%8WKHR_o!pZ2f_cJI$y&J8S*(ak3_HD%t;D9y(D`3KEq@82@5 z;%U3Gh1Ff>aE5GNaAQUY7acZ?Zx`CF92vxLM? z2GkO8y_u=J$btKU%@a=o@ut$+EZ!yYAMBKtArc*MvoxzITTainV1U@XuCr}CeinWa z8!g@^G%w|^v;P=z{-ZN`rXg?aLx*^vp`mM_Epa zF+!Onbo*bB(4Zu~+ziA?`T$fN*);I(u`CpY+h?LzQMPtpP%yUH>SxFgmMIUVFZxjR zX*SqXZ~#CouxBDt#t+3r(a}$Wd`Sj%!MjF~s=1{&c#pyRUi$Q8WZ8Ax%X+;lkJ9F; zMO8>Wm8C6Ok%meGMR zM~23*iz;ZYZIS6cml+eNiOv#?>Q~~HrOt|!emw1srdt~?J1+Gg7%0Uti zFq>`Z8*o^al6YK@?4^kMPO@3v!QZoKN*C$1gwD=%%u(av%fM~hOd*b8J-{o`K^7NE zx5J{Y7AkP{fu$zm=I881bpG@T7L}apcz8?f&RCrf{`k4>GHda5{`H**sZY(Dfq3rx zWs>8&TX%SK50ZT=>FWE^LGmDZcm9XfQ)~Vb=QeiVyA*p#Tz@GTe;oh^BrlJ#Iks1$ zRbpP~{j$+`Iy`&i9b!Jqz?@?aZ3$EsDa`d09Cgr-S1LddnQLc)vW*eZSl;Cr?7OIQ zFyJ)S#3jZ8xdn5Tx|Xfc!X}H@t8XRh7!&7Jb$X@B?p-(Jx=u7POs`*3X~8+P&aqR3 zZM=V<%m@zJIEfTSW>+pYffW)wDp=^gBUj!_^t#_#?Z=0EWhw_C)(1+$EbBFW`cF{F z0NLl{(N6}l&X~+SY8{_1D?T_bzoRJE-kt7$@p!1_nVD!JgN@bUR3hF4eM@aOV*eV_ z+VLa!n4pjm8#0b70hWJEulHrTQFe-|r#FEfBLa|GGo!1O&DZjXt=Yt)MPy!GPg3`t z72C6H33;{QBI`?{3L8w85BgKRB2qmX$;mxjo$OfH@YFE5Koi(+Q@+>$p*prcFTfwP z9`?_tG^qn6tXtH`Ls!}A+xHoK^zLnZK}U{jQc+i>iK;8lQn2^quQ05rB7Ly|v@Dw0^kKUwtGaIKPcbSKmbqR;F@Ml%Gv}3K zJ-?o-+cdSz9eJ$G;MP->Z2X!i+|{m@nw6O5?dAX)WEhBR&N*}gK#`jNxm3+d8}=O0 z>bp9{`*D(gJj2~Q)DXv<>fuNlq+Jh+C5jh3@z)r5B(7&$?EG@8O zk0bF^4Ie3u6nM%l4F%~bAE0Nz!hZ#~iL;V<_P z(()Z&jyCA|Rhf^Jh{Ori#n!0jW~vpl`(h0}OyA&Y8PPZN66oRDa~O1J`f{jn#mCM! zzJvN!KH*(ke4b;YVU5L!mBS3VZ@%I9)Ycn?JWg{=e4DCHVG}rFig<-!YpEwB7TODh z6YJurOA8R?NU9Ug6vAG&k<*;%{z}?+x&LULQX^o|-f%nqdTssX6!2AbI&U*}1CV4%CQ46+fzqE`SZ1ksk zpI5?0G=aZ(^d($2a>z{Aapk`E)w|F+HLvl6OMB1OphB{zIVDOI1f0D_8=APHIR}P; zp-_XGmf6hT*a3qt7@F$I09I-b6N<1(cYb`K*sSVGv^n5so)#qY63n|2R{c>YBfe`6 zI19`xJd`=51wzNYs&dM%(EL4L4S)Y}ow)ZzbYyPVVlbF1SDadkthE)^GX5Q+kwAbW zkNI5IAI~wIV7stuWdVL&?%1Y_V2=QsYHXGzUj5bxkq0|qz*8-FmYX_q`Klq+?eJ=) zR2Bn6xGnzHEBLf<@1Y41r!jSXjjgTYu~v8ig{7zphU(8CR4>bj4N_YHC=EnTz8k;V z-07RnFzgpt<{cS}?+l61sem)EP7X1XJ4hD|HGDq!1aT&*=3ghWzTVAwy>%=tz>@O% zRW6E7CMoR@y~l{^*jy!4Xj$xxKSucdn#q~?gBB?E;SXBs?bC|W_DifogYS}2+e!?z0){urntJVh31;P1P^pfwud$X>sllp z%8`;UvM-LcbpnqGUe4O_T?zU(GIKPwRvT#0G@|+ zhq`AdXzxGvP`*_v%PV^P&PCZ}5%E=&gRdpsgfK_C#W_a#MdmQpBVTh*EqYp?{)xbQmK-GzevFXGVYtH zyNX0*^&Z=tqX&W#<^<=LV^2%%0GvZbnq8%5nXcIr)K6R3jetJ6JK9-k0zo{vhCp@MnAc`yPwRASx}CWE;4cJwu5FwsnEAn&e5aLWt{FNHmR25^v8(=8cUTv8snq z=TqpL3FZwN^)pqB(J1kz#;_Zauc*>F$w9LM+$h(0QZ9qr>P{!8kdsxL^-0!LX!Xle zgEwWf2Wx#TJaPB(f6(k0?n&hhBXwg|3X6TH#vV}4h|C(&A*7fZAAf{Tei};!vsaI! ztIQMe#OKj}M;UIDT;#DS8{xv5jpFkN{zkz54+}|AP+g{I5}ZxfkhPbBNka;L_0kU3 z)F3bZdFWEKt5$M!`_`{w&v`jwYAO36`^3pGrJc}ZuyUzF{&Tc${KvU$R^8ra?fe48 z+DtZj#OOX+W}SKHWm)m!1$O|VA5`9|+(U1BUOcUA<0#N~6}X3PlC=OubTnXtjD6l% zlm-OuZGTwv(Yt3G^9kJTJfV+{U0g%JL@Gz7^kNn zM)>Kh9dg+ngUeQH;>V;wB4`5GBRT#Jk6CX4N7*;K>b&UGtzfh!^k9zD;7F0Epg4YU zKlEUp4Ta%t{ellCF5fdImTG;^v>x7CG!r@V_#Azx@erLOG*z~_5Lpx(nnX(swlrbM z#*LxnudNN8wQn>S=MQL((Vg$*E{$*m`@e7l)b-(sHr#&+9sYqO@%wTlL~PIx3j4B% zqxS>(2Q61KGcE!*{gU$g%3xz*jU70#k>!dzAI1%hVXRelB7NpI9*UzU@0478|I(E9 z_CS2xxbGrW1Dv+m;uWcTjPz*hE-S%Fd*`-Fjb+(iA>!5kntS0gr`IcJ5m_}chdCWR zjM(Ti7zf)_2^3OVk~&|ko)^_H-kR_r%c`JBydfM|2fCyuna;15PGVzMiN-VNv$5qy zPJ-U=nISup_N||E9&w+NyHV`~E|E!VrkgDTZokwQqrYUVOdMbRnA@-#-*CKyd$9l^ znbGeO&ohX6t6QW|Vv9vPdvMV#+HvmExIAb4dt*4=?n`AZV;!H4p(d@yiZcV*VV;HE z2J5Akcy13ec|kK` z>Zr3!LSbHV``xmt~Ay$Xfe@AKYpvbW7{NBIDIisr3dDQwN0GFgJC3?@sUfb z{632Mm1X)lj)I9~(}gY?n&Dk-&}=~<=dhb)!@|c=6*UvYy31nFcd3w>;OGwjqun!lW|9C0)(L%{L@`E1_!3yghT4jZLf6cG(Mol(q?@ds*aXr5aC{&o}NJvK@

vM359>@vt8j)}t0wqdGq z4zNe3lB_eRGWf0IK7fDW1=54(u~@B5MX1q+XH>`u_!@TctW=cy1rDa_ixsM?fODV4 zOEPFd6FS7bAsy2{qrl{dCyVjMso#^ z_UGzPcQAbSj19Q!HBlg21>;Ifl9`d2yy-bfT4l%!Y^!-6Cc5tM`AIn#fqb1nPJ9F- zoi(J7T3xAs<{sOaV=WEn3LQb59BMCVGBhQ;$rDg@jiW3w6NXjGbB!iOC!UuV$&J4+ z5vX4{bb0$~B5dvQ@_wD|*HNr`7Yy$}FSfI{@)keS@vp%UJK)Wy#MOm9E;^CYJ)R>{ zia_{Up@}Ods_6q^!x$MD&XjthRL?4CKASMDk-rz)yDhj6Qv`s{rvEPhnD~>X*bL~( z2NvHaQqFVY_rXHNQ%oCu`=AZ)mr;PAB}+HFNdP_rfR)By>E`pVnb;-|j||~*;RJ&( ze-Ttr@LMTc@27U1eT|Tr!SIYK;8=R%H4Mku5HYTv6HiORvQ5QE8+V5G_3lB@ICJjS z4%I!_-IdTp8#V;?bUM^804oi<6Yw?-Vv#^T1Qdb=8Lv)f$R&~xds445Syw+~e3SW* z>kO1l?mhL{mIvxL-g7UOIUEt5rVPJ*4p7Rwb6-V<()Gc714#K+G*{omM@L*p{gAQ* z4ZyY9i!0u@l=Ta2tj@*FZJ4rLrOF65_Nlu=0T1OE%C8`We@5VwBk@jUeI`2-h zoS)f^@#m6F^YrvM)(;mW0mu@c$38*i;k!m1A#`g8^)sU#Jared_$}YEYcU@fQT>p4 zp6BiALCstCjGG%ff3LOtcOA=L^CyYd<%?li1)xL^0hF!s47SP>8GlK$STHqx(v40d z*e4Z!JRnZLO4kgm!GO_d=GsQec6HywbXBB) zkYt!xEEiENWrb;J;w=1%w|ur$!JY#gp*+OCP+%BiRxj)b>(6{KRUg>e?qVEsS@8vi zcyL(L8=L84s@?LUw-*^|=jtQ6s}=5d*;>&B9&c1m*h;}0h83lqv#aQUEl9$jyHa`B zzoB?V(kWhXH=LsU-QKfE?Jc^6T%!{|h+bO{B(64Fzca*ENQzFOqzLcHWUlCJY}WkG z#|2pJbJgvtFFgw=8|uU++}1?QR?wl$u)fIsy<#Ms`2xTyPt!2dISu%l@yuCc@N*^8 zvwD244W2c;vS4uluvHh7DLE%EKlZo_hyjJD^AUUwu55OtJe6)C8uM&g`Z(LrN%5K5 zYg#LgL&~B-&tHAbmw{zZs^cB1nnS}Gx~Vk1rhM1+sgiEQZD9ge3T{@KBfKlfTlr*B zMY2yaDv&z#C-a85iLY9J{1=Vw-xwDE z1uDv=@j_}2dx-!emNPKqQ-G`=o6tB&}c;ntg?S<3N}q(Im3m!2C1xooQNx5)T}euNsaD2 zM%LUh(X^*8ETBXf!{WHVmkR`eeT_FX@MXKr<^Ds#nVm(Q{dcwh%isJDWv{$oV6e$a zCZ4RB@ff883bX|on9!D0+c-X$1m?-l-tW*~ez2{xxeT|@Pz*z7vb1opf;lMkfz6DM z^$b_%Q(3{`KwJu`FnNkG9N_}T$(_0AIxXA8Ya{8F@l!{;BIPPTp{1Sq5h7UqWZ_T2AO=VC+v@=m=)He*fO zd?a+EO{((XbS?Ld7zOefAf+#QfS;zmv*?oCqDaDbTw|4FA~W?Vo==rsd$+6IrsZ{| z{md=t?VYB}gINuIw6JE@gK|J(8Bwdm;D?+Qrs?L}n1yB(H-m^WWgc}yjQ!>F{$K&F zsZl5Nabh%V>@uZ;ZRN=!>%~OIipeEqXNCRHHRmRSjV1G%D=1@^Kxc%6Er{F&6m{v)aRI!%DnGaz7U#o%^#{#p*(daHdFbc!L&h`hp*zRHM0|yo)8Tf; zJM_tB8+GMiCodbGhW?MerUbgA^^u(XpDne za`9qUlEe6Ti(J|Xu|6ftyCGCB4WX3jcySyRaDWZA+Bq8j9MnErzr5O9f68+=D`0&e z=JkM5<-dKWa1Vs*-3Bz08jvg>T_8KEMue+6LRc}GztO3xIW^zvMW2qcwHvTr-}t-d zTGD=HF7~q*QGKrSf$FUf@ONeqH+q=F@_>iA(uxqH@bvi>bPD!~nE<}^YJuaWr`W)q z<&2DW1cyRud{Jb>1PHG9tu~kx5??ff9~3lc4LbKcn2UVDIg4Ko+a$AEp$WXooCr^x zhu#x3%ru@_uU}FeoE@g4{63CrH?R?YNsZQeolOW>A)Ni}p&}UjAJ%EnAFI4%mq>7q zW45j)Sy&QdIOf>UT-fVVK*9FGgsyIQ3CxCUbUI=nrCRGV^#4_KbMpGY%3-}(*i|4j z1L?iH8XT(+67lS&*nb+crE|hUpa;;&*X-9iq>4BCdPZ!n%B%2T3#t>Ew=@FQ+6dLtJ3?3o9n`aXlf95 z_jnfGF|*S8DS}G-}IK-}T$R<55olumbM&0-rno$}CfNkZ+{KwQCQX z%~{;M4WYqfa{CgQ>FnWGFA_y9bbVikN_G1)S2@NrED_y_n|7(JQh2S0*#-E@j{5-> z@`sORad!F3w!Qurc^9h0{y)!GB;@Dz9gOw^M$MLbV+3Xb##a7;c{uU-VA$iVJODsm zb9cWGrC{{38b-P8;SU>!(zU|AEEK^uuRz}_*Otbq>`g943L$6ZzUk=Y1<<9a@xQDn z=3Y%iFfr&-%P`G)b$e6ZC1z?d8;F~w!Nq*cVOKXee-SZ<`U;Rz*Y87t`L50wuXs*@ zk7!Ii0ugtab2GgMrDcDkvi-GS8?_I)3c!BzEQRoaF`?#2)<71D5;oBpOsOpWxP8tx zWMF8f@f+*F2da7l z_+^HgW9Arq1}DwgYF8L&1(}p*Wr($UUC!5OKPp3}EUs1h{14i=t~{yDoEv8+L3iF_ zx!SklU%|OgT4%)QxTzv*iMMm}M2Vh9XOynu15>+Qn(K0uOxb9Sb{vyj7Lsi$wY|ZI zBEP9;Ddg3B(Y*aIcIBDeEYEzb5lo#Sq63X4BfLGFnen7)fXQwJvrK8f*X-sD+1Yfn z@QnF+L$J_(v%|w#M>fPsE_R&Uickwy^Ogox#F0q5(CU-Yh>@$_1Fo#9z&iwyfE# z&!E@g`DHiI+KnzuwYB5dP8<{!q=LVwjH4{yWRITsCVDgOX5PN+Ht4#fSqEGt75nTP zkode<@QE(2W5EjS6+Y*M4Y1FCn`I_rRon@&t6p`m4whyTuU}xhm-P_ab6dDGY^#19^(v@(MzjZNHCw8wUyLS~QP$YjN;jXPSNJlaqAG#%11o$7D+ z;#lEZj9m?5uUqLLli4K+p3DBATn#cSUa+csY5gV1nsM>OV!JLTYt4Zk4un4V3RQavMm$J&`)ttc&l(N)P+ z#@bz=`t*cSd=dp{fMiiL=%(Z%YS#1X{ZFF5KV%&(NIyCBAkzl#{PdD6-!yd4s^gr&8oa;64EbhVC7BO8kN|v_0fd9960Q?QMOqQXzaMC4A1GGON=EykaKf z?i`i-NVos>7bz}hSpv;-xiK}9C~--)w}0E5R7IWvQ3MohftgYCih|j^_jd2{oiz8| z(c}`jp(|~}$Fz^9&swScgB+~=v^m9sAf7)kB$UuS?;rj9S7lo}(Fbgq*Oj0>SDBp^ zrWRi|XhK)}*B>i$@L_OI@#~uw6L3UdBT;CZv#m$ylk;}YOQ{(64u+^+QC+AuAY}Yr zNg`x@?RfL`>_bkkqh7ANZ1gIyk-qh=7U^jAC>Iv`P_#Ln`D!=D)``vBLx+bT{ZaXU zjFTY2^qa5!2CcHe{_xMBs)ZSA&&D`io_ZprEeW%V@?Zf(WP6{6B;{YX_k$uH&zLr> zHmjk0cb9k0KrwUP6X*UXVOkXMTs*>fMj_G+uY07*D(G%TWl7QgFqg-_`b7hpO+dQM zOb#;I{aYh4XCbBIQx$N~kRY42|4{gmJPz9K)0tsS(g2}AzEz@HcH$yd3QU^9*X>0h z2xi_b8F^(JZ z8+$+ZYPt^jIkaa5?)pH7$`m1SPf9QwvT{7WWd!wcH-&acrmT154HO!^G! z@?@)40}k2SxP{@S46H=5l1B(q*V?Q?-yC#h6^)cZ0qF;cZo^q%^;(ZRpM2y}eEqF6 z5PI}{OUN%v*_5B$QW;qt)JMVdgnGjMoT0gt#{f>vYc^kid_fr!qYOWLJL{@up-!9! z#-2kfqD@Daoi1|v|G5tM)8VCulDJihce~zeC@gXN5R}4aykq)hh>j5q?nj={JeVaUb9*bA>n=v)?9F=5LDG|44j~$OC@vhEQ4SpPSdIZL3tQ=XQD*5E zILDn`xN&`h4XF3X(=QZxRN5z}#v!3M7TE`9g-Ax{1&vGW6W9SXcQecN2l~YceC}O;uL7Yn@pkcU&&=G7A8xoO& zB+)~{B--5w)0|l$&mkGR*bqo7JAOvzsfcVeeAdkcHx9~;%kVo-rU7dDTH4jUFi(O_ zf;PSgg;}WNMmtH6q!fxjdLLo2MWCVqCN|TmW@bU?y1$7|oN!FAj9g!SB<-qtk*2*H ztG>fr#W1z{&x#e#oM(MRY%Tt~;F7s{73=PC)T74npA&JEul5sFl+Cd)iHPun5O35xtX|iDkjaY72y7>>MmW9@$@w;?+fj%yLWiJ}|B^ zJ&FtioaNz2U2`h?`^mb7x-yV3Dq^$7;W+D@TlTHTJefDnfkrH|Ios5%Us$*Ci??lX7u$b^G>t#F=O>8-f zK3C}Wy!`%ZUA3eHExNL=q8U5+<6yQLslH>61>ElZUq8JWwuw|Xdzh3w#rFCg98yx**{X1yEsU_Bezeh>&Cjc!4DTd- znZDMoH?2iupFWgrrQQh z&bS$|G7H-(#FH!b=)?zzx(muwxC*e{#TX8OVw{1Nx|x$?DXx!-uL`kvmD=$SHCXgXs9So z7(@KzKLZiPWJN!{(7;Gr*LLxWhK~xaO{cEa%k4^=*~FClFCnxHYkQM5vVP%8NypRH z=HBk1EWPB=s}dYY@je@E@eWlZKg4zs&D}|Q=Dz8_)=A4NuzWiO0l4X_ITW~{}x65FWN~AgHd~S*|=khMC|lA@@B2WgC{7B zG)Va)G3xSK3pzO+jrcM)c^pt|0)zjfGP@`NX6&`nAQ^K~#gqGZ`P!Z;LGM1>$OZEU z8p(bj6DAA+z+3obci7xE z&Xp#={bB_Cb$!Ud|9kDjV^$LWDPdKkx6bBY9JUS|t7qN}I*l>S#}79!8LgrRr09*$ zr(1pm7z$x*V&7;CT5mCo)|sC$9QUY^9`%MwGHXM=oR|)=eObtVpqO>GurI>L^qZyr z9-%_xdFlJR^pe?{@53NtFZZM8$UNQSlF2aR(-q=UtP@<;N0Ye?d3-sdJqf3LxkRp4 z={udl8^^$kKzgI)pfys)s@Ef_P6ftb#E@yno|;yC;L{iuA@voHdS@V*mG!V}oW99K z7Irci@$&i0g9e^j8#`%&hTEBO-=7VGf%fIBnK1@71|hnf*G{zxZTg3&njD_ze6c|) z^&ieGbEzW`(eZS`Kj#>ZYX4agO*>M*tNL|{D&#hbtQ}cf_>BX!V5}e$U;(APqlx7! zODSV>lTXuq7@g_IN}?GHSqAG16)x6O)eMD%wu#oEtMby8VsmaeGUK@k+~dI}u?e)q zF*WUPJxRI&t2=kx53jpgWOgTpb?HEEGf7;^Y|W7^HF^S>^r-je%=DTR@&bIN3Oqx zdDn=pwrKQbPIRt0e%d`+t==_D9%1O;*VPSKf&+`4C}5fJ_>0M zdVeR@{q|J@2gc78C&_23GnUZDK!j*r-aBH32o?+|Kh5z4u!pRZERqg;`!~7s4z79# zhkVRysS!YLrrVZ!0TtXDbvtB{bga)uG@Ji21;u#(xr>jCGMg=NzRd);RpCoA0nhqD zx4L>!H{WR8jGjt;8pLz|#ktVbr&BSU?zjAhk>$6ES~1@60!}VQ!RR@T&<6a*NYS;kxP?mN)%te`ki=d;Zm>p4+%`(7Yrh;2idd zmJvYGIR1Zu2mVj~@x6(ynma~5eF!4& zAu3czgV;U!`x_JAGJObrSQ6&jw{__acf*$t#_Q-vtbM3dmX4so#G@gJ-o$6{Nqp6t zqGT!75$=8JftfD`Hc>??5 zUbBHYQP-MGK0mqmyf!-D(z0y09?6^D%dbn5THU4C??~Yd^te-1-IPth(V@n5M&KGY zoKOI8VK7F(el(?2h)~%dH11!nr}{MY_Gb?gja4|Wau|2QJED%{t=RgUgZcmfIeE)U zkW&tki;H}PIm7RbiCDu`cExq;_@~EgY1ZR3QRv*^jr-^n&Xy1?IjTg^i!2ZCT@0n> zw@JrQh5DRTI)e1Cn`YkzRj6{h3?loI6Ix%9MRz5VLP)3#iR*$#3K5B3?p@INNrqz`$%;x@Yl^*&7!MQ7``4%onpw zk>Fs5=c62?TfghX)&;^lBN2;g2Y{r3f$<7bUdQfbMI=Oruv&Wxc*p297@zJY1MbM6bUS( zBC8VM-V2CS1I-62YfzYNQO|g_@^3d zi|{p@p{Z{W81PBX#^0+uSZzga^wfo)>6~I>Z>F@z^LoT&x-Yhzv?La31P!h4V~d}u z&%J;kP}VL^o)(|VraO1W_r4e>J>w+UdN#6X*f^BVJ56o02-x0DqU&9jcGV4+l4G30 z%+1sD{x&jfLw@wsSUaCE(hzZ*-b<-Z!G||U(FnaSFhQDh$xDHhyXd+~NhcB037_Y1 zwPu&L@f@d^>CALLblK0Z#W89#Nx0RmCiV}6ri@6tK>Mv%)sf|V!KCpQv}J~(1E6LG z;&e?4zoFzFsDFKE*G5V1OWShUA*x~K`Q?b$7^N*WEFMY;Z%&nO^$4l3BqS&O{n2rq zZribE9hStKe+i!7T*l;I0{O{bVsp1P5^iKGmIWI<`7W(8FlVWlSL;ihF>sg%1Q}6k z#?8?nnv)!rjFXr~*22Cl{2(IITmBdby5iHhN?^p<%XfkZW zXcg$#<$$}-^ZB7|DAP!^t9Lsoj8pbHK7bBnDbH*rT*}zG+=gi6<}waj0AFD~PhepUgq_WO=~-*JeB5H - - -$Id$ - -Acknowledgments - -I want to acknowledge all of the people that helped review or edit the model -documentation: David Lawrence, Samuel Levis, Keith Oleson, and Sean Swenson. -Thank you for your help in catching errors, and making the document more -understandable and readable. Our readers thank you as well, as now it is much -easier for them to digest. Any mistakes, or errors are all mine. If you run -across one of those errors, please let us know, by following -. -I also want to thank Sheri -Mickelson, for her work in doing perturbation analysis on bluefire and intrepid, -which was used in our initial versions of this User's Guide. We also want to -thank the original authors of &ptclm;: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, -Wilfred M. Post, and R. Quinn Thomas for providing a nice addition to the &cesm; -effort. We also want to thank the folks at University of Michigan Biological Stations -(US-UMB) who allowed us to use their Fluxnet station data and import it into our -inputdata repository, especially Gil Bohrer the PI on record for this site -(see for permission information on using this -data). - - - - -Introduction - - -The Community Land Model (&clmrel;) is the latest in a series of -global land models developed by the &cesm; Land Model Working Group -(LMWG) and maintained at the National Center for -Atmospheric Research (&ncar;). This guide is intended to instruct both -the novice and experienced user on running &clm;. This guide pertains to the -latest version &clmrel; available for download from the public release -subversion repository as a part of &cesmrel;. Documentation may be different if you are using an -older version, you should either update to the latest version, or use the -documentation inside your own source tree. There is information in the -ChangeLog file and in the -regarding the changes from previous versions of &cesm;. - - - -The novice user should read - in detail before beginning work, while the -expert user should read and - chapters, and then use the more detailed -chapters as reference. Before novice users go onto more technical problems covered -in , , , or they -should know the material covered in and be able -to replicate some of the examples given there. - - -All users should read the - -and sections to understand the document conventions -and the various ways of getting help on using &clm4;. Users should also read -the section to see if their planned use of the -model is something that has been scientifically validated and well tested. Users -that are NOT using &ncar; machines or our list of well tested machines should also -read the section to make sure they have -all the required UNIX utilities on the system they want to do their work. - - - - - -Introduction to the &clm4; User's Guide -What is in here anyway? - - -Here in the introduction we first give a simple guide to understand the document -conventions in . The next section -describes the differences between &clmrel; and &clm40; (for each &cesm; release version -up to &cesmrel;) as well as between -&clm40; and &clm35;, both from a scientific -as well as a software engineering point of view. It also talks about differences in the -configuration, namelist, and history fields. The next section -is for users that are already experts in using &clm; and gives a quickstart guide to the -bare details on how to use &clm4;. The next tells -you about what has been extensively tested and scientifically validated (and maybe more -importantly) what has NOT. lists the UNIX utilities -required to use &clm4; and is important if you are running on non-&ncar; machines, generic -local machines, or machines NOT as well tested by us at &ncar;. Next we -have to detail some of the best practices for using -&clm4; for science. The last introductory section is which lists -different resources for getting help with &cesm1; and &clm4;. - - - - goes into detail on how to setup and run simulations with -&clm4; and especially how to customize cases. Details of &configure; -modes and &buildnml; options as well as namelist options are given in this chapter. - - - - gives instructions on the &clm4; tools for creating input datasets -for use by &clm;, for the expert user. There's an overview of what each tool does, and some general notes on how to build -the FORTRAN tools. Then each tool is described in detail along with different ways in -which the tool might be used. -A final section -on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. - - - -As a followup to the tools chapter, tells how to add files to the -XML database for &buildnml; to use. This is important if you want to use the XML database to automatically select -user-created input files that you have created when you setup new cases with &clm;. - - - -In , again for the expert user, we give details on how to do some particularly -difficult special cases. For example, we give the protocol for spinning up both the &clmcn; model and &clm; with dynamic -vegetation active (CNDV). We give instructions to do a spinup case -from a previous case with Coupler history output for atmospheric forcing. We also give -instructions on running the prognostic crop model and its irrigation option. We also review -how to validate a port to a new machine using the Perturbation error -growth technique. Lastly we tell the user how to use the DATM model to send historical &CO2; data to &clm;. - - - - outlines how to do single-point or -regional simulations using &clm4;. -This is useful to either compare &clm; simulations with point observational stations, -such as tower sites (which might include your own atmospheric forcing), or -to do quick simulations with &clm; for example to test a new parameterization. There are -several different ways given on how to perform -single-point simulations which range from simple &PTSMODE; to more complex where you create all your own datasets, tying into - and also to add the -files into the &buildnml; XML database. After this chapter - chapter outlines how to use the &ptclm; python script to -help you run single-point simulations. - - - -Finally, gives some guidance on trouble-shooting -problems when using &clm4;. It doesn't cover all possible problems with &clm;, but gives -you some guidelines for things that can be done for some common problems. - - - -In the appendices we talk about some issues that are useful for advanced users and -developers of &clm;. -In we give some basic background to the &clm; -developer on how to edit the models/lnd/clm/bld/clm.cpl7.template. -This is a very difficult exercise and we don't recommend it for any, but the most -advanced users of &clm; who are also experts in UNIX and UNIX scripting. - - -In we go over how to run the script -runinit_ibm.csh" that will interpolate standard resolution -initial condition dataset to several other resolutions at once. It also runs &clm; -to create template files as well as doing the interpolation using -interpinic. In general this is only something that a developer -would want to do. Most users will only want to interpolate for a few specific -resolutions. - - -In we go over the automated testing scripts for -validating that the &clm; is working correctly. The test scripts run many different -configurations and options with &clm; making sure that they work, as well as doing -automated testing to verify restarts are working correctly, and testing at many -different resolutions. In general this is an activity important only for a developer -of &clm;, but could also be used by users who are doing extensive code modifications -and want to ensure that the model continues to work correctly. - - -Finally in we give instructions on how to build -the documentation associated with &clm; (i.e. how to build this document). This -document is included in every &clm; distribution and can be built so that you can -view a local copy rather than having to go to the &cesm; website. This also could -be useful for developers who need to update the documentation due to changes they -have made. - - - - - - - - - -Important Notes and Best Practices for Usage of &clm4; - - - -When running with CN, it is critical to begin with initial conditions -hat are provided with the release or to spin the model up following the CN spinup -procedure before conducting scientific runs (see . -Simulations without a proper spinup will effectively be starting from an unvegetated -world. See for information on how to -provide initial conditions for your simulation. - - -Initial condition files are provided for fully coupled BCN and offline -ICN cases for 1850 and 2000 at 1deg, 2deg, and T31 resolutions. There's also an -initial condition file for ICN with the prognostic crop model for 2000 at 2deg -resolution, and one with &clmsp; for 2000 at 2deg resolution. We also have initial -conditions for offline CNDV for 1850. And there are interpolated datasets for 4x5 and -10x15 resolution for 1850. The 1850 initial condition -files are in 'reasonable' equilibrium. The 2000 initial condition files represent -the model state for the year 2000, and have been taken from transient simulations. -Therefore, by design the year 2000 initial condition files do not represent an -equilibrium state. Note also that spinning the 2000 initial conditions out to -equilibrium will not reflect the best estimate of the real carbon/nitrogen state -for the year 2000. - - -Users can generate initial condition files at different resolutions by -using the &clm; tool interpinic to interpolate from one of the -provided resolutions to the resolution of interest. Interpolated initial condition -files may no longer be in 'reasonable' equilibrium. - - -Aerosol deposition is a required field to &clm4; sent from the -atmosphere model. Simulations without aerosol deposition will exhibit unreasonably -high snow albedos. The model sends aerosol deposition from the atmospheric model (either -CAM or &datm;). When running with prescribed aerosol the atmosphere -model will interpolate the aerosols from 2-degree resolution to the resolution the -atmosphere model is running at. - - - - - - - - - - - - - $EDITOR - - - -How to Use This Document -Conventions used in the document for code and commands - - -This section provides the details in using &clm; with the &cesm; modeling -system. Links to descriptions and definitions have been provided in the code below. -We use the same conventions used in the &cesm; documentation as outlined below. - - - -Throughout the document this style is used to indicate shell -commands and options, fragments of code, namelist variables, etc. -Where examples from an interactive shell session are presented, lines -starting with > indicate the shell prompt. A backslash "\" at the end -of a line means the line continues onto the next one (as it does in -standard UNIX shell). Note that $EDITOR" is used to refer to the -text editor of your choice. $EDITOR is a standard UNIX environment -variable and should be set on most UNIX systems. Comment lines are -signaled with a "#" sign, which is the standard UNIX comment sign as well. -$CSMDATA is used to denote the path to the inputdata directory for -your &cesm; data. - -> This is a shell prompt with commands \ -that continues to the following line. -> $EDITOR filename # means you are using a text editor to edit "filename" -# This is a comment line - - - - - - - - - - - &clmcn; - &clmsp; - - -What is new with &clmrel; since previous public releases? - -In this section we list the updates that have occurred to &clm4; since previous -public releases. In the first sections we describe changes in &clmrel; since the &ccsm4; release, -and in the last one we describe changes from &clm35; to &clm40; release. Note, that -the changes in the last section do NOT include the more recent changes given in the -first section, but only list the changes from &clm35; to the &clm40; release that -was part of the &ccsm4; public release. We will describe both the -changes in the science in the model as the software engineering changes. Software -engineering changes includes the configure and namelist changes, as well as the new -history fields. - - -What is new with &clmrel; since the December 8th, 2010 &cesm102; release? - - - -What is new with &clmrel; Science since &clmcesm102;? - -A prognostic crop model option was added in (based on Agro-IBIS) from work by -Samuel Levis. The crop model adds in four new vegetation types for: soybean, -winter and spring temperate cereals, and corn on their own separate columns. Winter -cereal was added as a PFT type, but doesn't exist in the input datasets, only -spring cereal is used. Winter cereal also has NOT been scientifically validated -or tested. The model manages these by modeling both planting and harvesting. See for an example of running with it. - - -An irrigation model was added from work by Samuel Levis and Bill Sacks. This -model takes water from runoff and adds it to the crop pfts for areas equipped -for irrigation. See for an example of running with it. -Please note that the irrigation model only works with the crop model active. - - - - -What is new with &clmrel; Software since &clmcesm102;? - -Since &clmcesm102; all Input/Output uses &pio; (Parallel Input/Output package). -Restart history files are now &netcdf;. Input and output files can be read/written -in parallel using PIO. We removed a list of old CPP defines and removed the -old misc/preproc.h files. Also a new tool for working with single-point sites was -added into the &cesm; scripts the Python tool &ptclm;. We have a complete chapter on it's use. - - -New configuration options: - --crop --noio - - - -Configuration options removed: - --dust --progsslt - - - -New build-namelist options: - --co2_ppmv --rtm_res --rtm_tstep - - - -New precedence for build-namelist options is... - -Values set on the command-line using the -namelist option -(&CLMNAMELIST;). -Values read from the file specified by -infile (&usernlclm; file). -Datasets from the -clm_usr_name option (&CLMUSRDAT;). -Values set from a use-case scenario, e.g., -use_case (&CLMUSECASE;). -Values from the namelist defaults file. - - - -Namelist options renamed: - -carbon_only => suplnitro (can be set to NONE or ALL) - - - -namelist options removed: - -carbon_only => suplnitro -scaled_harvest -hist_crtinic -hist_pioflag -ncd_lowmem2d -ncd_pio_def -ncd_pio_UseRearranger -ncd_pio_UseBoxRearr -ncd_pio_SerialCDF -ncd_pio_IODOF_rootonly -ncd_pio_DebugLevel -ncd_pio_num_iotasks - - - -New history fields: - -A5TMIN 5-day running mean of min 2-m temperature -(K) -A10TMIN 10-day running mean of min 2-m temperature -(K) -GDD0 Growing degree days base 0C from planting -(ddays) -GDD8 Growing degree days base 8C from planting -(ddays) -GDD10 Growing degree days base 10C from planting -(ddays) -GDD020 Twenty year average of growing degree days base 0C from planting -(ddays) -GDD820 Twenty year average of growing degree days base 8C from planting -(ddays) -GDD1020 Twenty year average of growing degree days base 10C from planting -(ddays) -GDDPLANT Accumulated growing degree days past planting date for crop -(ddays) -GDDHARV Growing degree days (gdd) needed to harvest -(ddays) -GDDTSOI Growing degree-days from planting (top two soil layers) -(ddays) -QIRRIG water added through irrigation -(mm/s) - - - -SNOWLIQ and SNOWICE changed from average to instantaneous output. - - - - -What was new with &clm4014; (in &cesm102;) since the September 17th, 2010 &cesm101; release? - -Since, &clm4010; in the &cesm101; release there were several developments made -to &clmrel;. Several new namelist items were added -a few new history fields. There were also some updates for -running the model with single-point mode. - - -Configuration options that were renamed: - -prog_seasalt => progsslt - - - -Namelist items removed: - -prog_seasalt => progsslt - - - -What was new with &clm4014; Science since &clm4010;? - -A long simulation at the course resolution of T31 (typically used for Paleo-climate -studies) was done and an spun-up initial condition file was provided for this -resolution (also by default the namelist variable ice_runoff was -turned off for T31). Also a new surface dataset and transient land-cover dataset was -provided for half-degree resolution. - - - -What was new with &clm4014; Software since &clm4010;? - -New configuration options - -sitespf_pt - - - -sitespf_pt is used for single-point/regional mode and is set to the site-name -that will be used (see the config_definition.xml for the -list of valid options). - - -Configuration options that were renamed: - -prog_seasalt => progsslt - - - -Namelist items removed: - -faerdep -fndepdat -fndepdyn -use_ndepstream - - - -Nitrogen deposition datasets are now only entered through the -ndepdyn_nml namelist (removing fndepdat, fndepdyn, and -use_ndepstream). Aerosol deposition is now a required input from -the atmosphere model, hence faerdep is removed. - - -New history fields: - -U10 10-m wind (m/s) -U10_DUST 10-m wind for dust model (m/s) -VA atmospheric wind speed plus convective velocity (m/s) -VOLR RTM storage: LIQ (m3) -VOLR_ICE RTM storage: ICE (m3) - - - - - - -What was new with &clm4010; (in &cesm101;) since the April 1st, 2010 &ccsm4; release? - -From, &clm40; in the &ccsm4; release to &clm4010; there were several developments made -to &clm;. A glacier multiple elevation class option was added that allows the -use of &clm4; with a glacier land ice model the Community Ice Sheet Model (CISM). -A bug-fix for the snow hydrology was added. Several new namelist items were added -a few new history fields. Also the capability of reading aerosol and nitrogen -deposition from stream files at one resolution and regridded on the fly rather than -with datasets at the model resolution was added in. This was important for higher -resolutions so that large datasets do not have to be created before running the model, -nor are datasets for every resolution required. - - -What was new with &clm4010; Science since &ccsm4;? - -In general, snow layers should not be thinner than - -dzmin = wice/rhoice + wliq/rholiq - -If dz < dzmin, then the value of "void" computed in subroutine -SnowCompaction is negative, which is unphysical. This doesn't cause -problems with the compaction itself, but results in unrealistic values -of vol_ice, vol_liq, and eff_porosity in subroutine SnowWater. We can -have vol_ice = 1 and vol_liq = 0 even when liquid is present, which cuts -off the runoff (qout) from the lowest snow layer. Liquid water then -accumulates in the snow column without draining, which leads to further -problems and eventually a code crash. - - -The solution to this problem was to adjust layer thickness dz for any water+ice content -changes in excess of previous layer thickness, e.g., - -dz(c,j) = max(dz(c,j),h2osoi_liq(c,j)/denh2o + h2osoi_ice(c,j)/denice) - -at appropriate steps in the snow hydrology subroutines. - - - -Snow hydrology bug fix. -Add multiple elevation class option for glaciers so can interact with -the land ice sheet model. - - - - -What was new with &clm4010; Software since &ccsm4;? - -New configuration options - -glc_nec - - - -glc_nec can be 1,3,5, or 10 and MUST match the number on the input surface dataset -the elevation classes themselves are read from the surface dataset - - -New namelist items: - -carbon_only -create_glacier_mec_landunit -glc_dyntopo -ice_runoff -ndepmapalgo -scaled_harvest - - - -carbon_only = If true, and CLMCN carbon-nitrogen model is on, Nitrogen is unlimited - rather than prognosed and vegetation will be over-productive (replaces the supplemental Nitrogen #ifdef) - - - create_glacier_mec_landunit (= T when these landunits are created; F by default) - - - glc_dyntopo (= T if &clm; topography changes dynamically; currently F) - (NOT fully implemented yet) - - -ice_runoff = If true, river runoff will be split up into liquid and ice streams, - otherwise ice runoff will be zero and all runoff directed to liquid stream - - - ndepmapalgo = Mapping method from Nitrogen deposition input file to the model - resolution (can be bilinear,nn,nnoni,nnonj,spval,copy, bilinear by default) - - -scaled_harvest = If true, harvesting will be scaled according to coefficients - determined by Johann Feddema, 2009 - - -New history fields: - -aais_area Antarctic ice area (km^2) -aais_mask Antarctic mask (unitless) -gris_area Greenland ice area (km^2) -gris_mask Greenland mask (unitless) -QICE ice growth/melt (mm/s) -QICEYR ice growth/melt (mm/s) -QTOPSOIL water input to surface (mm/s) -VOLR RTM storage: LIQ (m3) -VOLR_ICE RTM storage: ICE (m3) - - - - - - - -What was new with &clm40; since &clm35;? - - -From &clm35; to &clm40; there were advances in both the science and the software infrastructure. -There were also new configure and namelist options as well as new history fields. In this -section we will describe each of these changes in turn. - - - -What was new with &clm40; Science? - -The following aspects are changes to the science in &clm40; since &clm35;. - - -Biogeophysics and Hydrology - -Changes to &clm40; beyond &clm35; (Oleson et al., 2008a; Stockli et al., 2008) include -updates throughout the model. The hydrology scheme has been modified with a revised -numerical solution of the Richards equation (Zeng and Decker, 2009; Decker and Zeng, -2009); a revised soil evaporation parameterization that removes the soil resistance term -introduced in &clm35; and replaces it with a so-called &Bgr; formulation, as well as accounts for the role of litter and within- -canopy stability (Sakaguchi and Zeng, 2009). -&clm4; also includes a representation of the thermal and hydraulic properties of organic -soil that operates in conjunction with the mineral soil properties (Lawrence and Slater, -2008). The ground column has been extended to ~50-m depth by adding five additional -hydrologically inactive ground layers (making a total of 15 ground layers, 10 soil -layers and 5 bedrock layers; Lawrence et al., 2008). An urban landunit and associated -urban canyon model (&clmu;) has been added which permits the study of urban climate -and urban heat island effects (Oleson et al., 2008b). - - - - -Snow Model - -The snow model is significantly modified via incorporation of SNICAR (SNow and Ice Aerosol Radiation) which represents the effect of aerosol deposition (e.g. black and organic carbon and dust) on albedo, introduces a grain-size dependent snow aging parameterization, and permits vertically resolved snowpack heating (Flanner and Zender, 2005; Flanner and Zender, 2006; Flanner et al., 2007). The new snow model also includes a new density-dependent snow cover fraction parameterization (Niu and Yang, 2007), a revised snow burial fraction over short vegetation (Wang and Zeng, 2009) and corrections to snow compaction (Lawrence and Slater, 2009). - - - - -Surface Datasets - -The PFT distribution is as in Lawrence and -Chase (2007) except that a new cropping dataset is used (Ramankutty et al., 2008) and -a grass PFT restriction has been put in place to reduce a high grass PFT bias in -forested regions by replacing the herbaceous fraction with low trees rather than grass. -Grass and crop PFT optical properties have been adjusted according to values presented -in Asner et al. (1998), resulting in significantly reduced albedo biases. Soil colors -have been re-derived according to the new PFT distribution. - - - - -Biogeochemistry - -The model is extended with a carbon-nitrogen biogeochemical model (Thornton et al., 2007; -Thornton et al., 2009; Randerson et al., 2009) which is referred to as &clmcn;. CN is -based on the terrestrial biogeochemistry Biome-BGC model with prognostic carbon and -nitrogen cycle (Thornton et al., 2002; Thornton and Rosenbloom, 2005). &clmcn; is -prognostic with respect to carbon and nitrogen state variables in the vegetation, litter, -and soil organic matter. Vegetation phenology and canopy heights are also prognostic. A -detailed description of the biogeochemical component can be found in Thornton et al. -(2007). Note that &clm40; can be run with either prescribed satellite phenology -(&clmsp;) or with prognostic phenology provided by the carbon- nitrogen cycle model -(&clmcn;). Additionally, a transient land cover and land use change, including wood harvest, -capability has been introduced that enables the evaluation of the impact of historic and -future land cover and land use change on energy, water, and momentum fluxes as well as -carbon and nitrogen fluxes. The dynamic global vegetation model in &clm3; has been -revised such that the carbon dynamics (e.g. productivity, decomposition, phenology, -allocation, etc.) are controlled by CN and only the dynamic vegetation biogeography -(competition) aspect of the &clm3; DGVM is retained. -The biogenic volatile organic compounds model (BVOC) that was available in &clm3; has -been replaced with the MEGAN BVOC model (Heald et al. 2008). - - - - -Miscellaneous Changes - -Several other minor changes have been incorporated including a change to the atmospheric reference height so that it is the height above zo+d for all surface types. The convergence of -canopy roughness length zo and displacement height d to bare soil values as the -above-ground biomass, or the sum of leaf and stem area indices, goes to zero is ensured -(Zeng and Wang, 2007). Several corrections have been made to the way the offline forcing -data is interpreted. The main change is a vastly improved and smooth diurnal cycle of -incoming solar radiation that conserves the total incoming solar radiation from the -forcing dataset. Additionally, in offline mode rather than partitioning incoming solar -radiation into a constant 70%/30% direct vs diffuse split, it is partitioned according to -empirical equations that are a function of total solar radiation. Finally, to improve -global energy conservation in fully coupled simulations, runoff is split into separate -liquid and ice water streams that are passed separately to the ocean. Input to the ice -water comes from excess snowfall in snow-capped regions. - - - - -Summary of Science Changes - -Taken together, these augmentations to &clm35; in &clm40; result in improved soil moisture dynamics -that lead to higher soil moisture variability and drier soils. Excessively wet and -unvarying soil moisture was recognized as a deficiency in &clm35; (Oleson et al. 2008a, -Decker and Zeng, 2009). The revised model also simulates, on average, higher snow cover, -cooler soil temperatures in organic-rich soils, greater global river discharge, lower -albedos over forests and grasslands, and higher transition-season albedos in snow covered -regions, all of which are improvements compared to &clm35;. - - - - - -What is new with &clm40; Software Infrastructure? - -The following aspects are changes to the software infrastructure in &clm40; since &clm35;. - - - - Update to cpl7 and scripts. - Remove offline and cpl6 modes. - Remove support for CASA model. - Update to datm8 atmospheric data model. - Add gx3v7 land mask for T31 and fv-4x5 horizontal resolutions. - Add gx1v6 land mask for f05, f09, and f19 horizontal resolutions. - Add tx1v1 land mask and 1.9x2.5_tx1v1 horizontal resolution. - Add in 2.5x3.33 horizontal resolution. - Add in T62 horizontal resolution so can run at same resolution as input &datm; -data. - Allow first history tape to be 1D. - Add ability to use own version of input datasets with &CLMUSRDAT; -variable. - Add a script to extract out regional datasets. - New &buildnml; system with XML file describing all namelist -items. - Add glacier_mec use-case and stub glacier model. - Make default of maxpatch_pft=numpft+1 instead of 4. - Only output static 3D fields on first h0 history file to save space. - Add new fields for VOC (Volatile Organic Compounds) on surface datasets, - needed for the new MEGAN VOC model. - Add multiple elevation class option for glaciers in mksurfdata tool (NOT used -in &clm; yet). - Add ascale field to land model in support of model running on it's own -grid. - - - - - -What are The New Configuration Options in &clm40;? - -Describe any changes made to build system: - - - -Change directory structure to match &ccsm;. -Add BGP target. -Add choice between ESMF and MCT frameworks. -Start removing #ifdef and directives that supported Cray-X1 Phoenix as now -decommissioned. -Make default of maxpatch_pft=numpft+1 instead of 4 for all -configurations. -By default turn on CLAMP when either CN or CASA is enabled -New SNICAR_FRC, CARBON_AERO, and C13 CPP ifdef tokens. - - - - -New options added to &configure;: -More information on options to &clm; &configure; are given in . - - - - -OptionDescription --comp_intf <name>Component interface to use (ESMF or MCT) (default -MCT) --nofireTurn off wildfires for bgc setting of CN (default includes -fire for CN) --pio <name>Switch enables building with Parallel I/O library. [on -| off] (default is on) --snicar_frc <name>Turn on SNICAR radiative forcing calculation. [on | -off] (default is off) - -More information on options to &clm; &configure; are given in . - - - - -What are The New Namelist Options in &clm40;? - -&buildnml; now checks the validity of your namelist you generate by looking at data in -the namelist_definition.xml file. In order to add new namelist items you need to -change the code and also edit this file (e.g. a namelist option required for your -research project that is not currently an option in &clm40;). To view information -on the namelist view the -file: models/lnd/clm/bld/namelist_files/namelist_definition.xml -in a browser and you'll see the names, type, description and valid_values for all -namelist variables. - - -Changes to &buildnml;: - -Allow simulation year entered to include ranges of years (i.e. 1850-2000) -Remove cam_hist_case option. -Make sure options ONLY used for stand-alone testing have a "drv_" or "datm_" - prefix in them and list these options all together and last when asking for - help from &buildnml;. - - - - New option to &buildnml;: - - -clm_usr_name "name" Dataset resolution/descriptor for personal datasets. - Default: not used - Example: 1x1pt_boulderCO_c090722 to describe location, - number of pts, and date files created - - - - New list options to &buildnml; - - cd models/lnd/clm/bld - ./&buildnml; -res list # List valid resolutions - ./&buildnml; -mask list # List valid land-masks - ./&buildnml; -sim_year list # List valid simulation years and simulation year ranges - ./&buildnml; -clm_demand list # List namelist variables including those you could - # demand to be set. - ./&buildnml; -use_case list # List valid use-cases - - - - -New use-cases for &buildnml;: - - 1850_control = Conditions to simulate 1850 land-use - 2000_control = Conditions to simulate 2000 land-use -20thC_transient = Simulate transient land-use, aerosol and Nitrogen deposition - from 1850 to 2005 - - - - - New namelist items: - - urban_hac = OFF, ON or ON_WASTEHEAT (default OFF) Flag for urban Heating - and Air-Conditioning - OFF = Building internal temperature is un-regulated. - ON = Building internal temperature is bounded to reasonable range. - ON_WASTEHEAT = Building internal temperature is bounded and resultant waste - heat is given off. - urban_traffic = .true. or .false. Flag to include additional multiplicative - factor of urban traffic to sensible heat flux. - (default .false.) - fsnowoptics = filename file for snow/aerosol optical properties (required) - fsnowaging = filename file for snow aging parameters (required) - -More information on the &buildnml; options are given in -. -and in -&CLMBLDNML;. - - -More information on the &buildnml; options are given in in . - - - - -What are The New History Fields? - -New history variables: (note watt vs. W in units, 26 vs. 76) - - - - -NameLong-nameUnitsActive/Inactive -BCDEPtotal BC deposition (dry+wet) from -atmospherekg/m^2/s -BIOGENCObiogenic CO -fluxuGC/M2/H -C13_PRODUCT_CLOSSC13 total carbon loss from wood product -poolsgC13/m^2/s -DSTDEPtotal dust deposition (dry+wet) from -atmospherekg/m^2/s -EFLX_DYNBALdynamic land cover change conversion energy -fluxW/m^2 -FGR12heat flux between soil layers 1 and -2watt/m^2 -FSATfractional area with water table at -surfaceunitless -FSH_NODYNLNDUSEsensible heat flux not including correction for land use change - watt/m^2 -GC_HEAT1initial gridcell total heat -contentJ/m^2 -GC_HEAT2post land cover change total heat -contentJ/m^2inactive -GC_ICE1initial gridcell total ice -contentmm/s -GC_ICE2post land cover change total ice -contentmm/sinactive -GC_LIQ1initial gridcell total liq -contentmm -GC_LIQ2initial gridcell total liq content -mminactive -H2OSNO_TOPmass of snow in top snow -layerkg - HEAT_FROM_ACsensible heat flux put into canyon due to heat -removed from air conditioningwatt/m^2 -HKhydraulic -conductivitymm/sinactive -ISOPRENEisoprene fluxuGC/M2/H -LAND_USE_FLUXtotal C emitted from land cover conversion and -wood product poolsgC/m^2/s -LAND_UPTAKENEE minus LAND_USE_FLUX, negative for -updategC/m^2/s -LWupupwelling longwave -radiationwatt/m^2inactive -MONOTERPmonoterpene -fluxuGC/M2/H -NBPnet biome production, includes fire, landuse, and harvest -flux, positive for sinkgC/m^2/s -OCDEPtotal OC deposition (dry+wet) from -atmospherekg/m^2/s -OVOCother VOC fluxuGC/M2/H -ORVOCother reactive VOC -fluxuGC/M2/H -PBOTatmospheric pressurePa -PCO2atmospheric partial pressure of -&CO2;Pa -PRODUCT_CLOSStotal carbon loss from wood product -poolsgC/m^2/s -PRODUCT_NLOSStotal N loss from wood product -poolsgN/m^2/s -Qairatmospheric specific -humiditykg/kginactive -Qanthanthropogenic heat -fluxwatt/m^2inactive -Qtaumomentum fluxkg/m/s^2 -QFLX_LIQ_DYNBALliq dynamic land cover change conversion -runoff fluxmm/s -QFLX_ICE_DYNBALice dynamic land cover change conversion -runoff fluxmm/s -QRUNOFF_NODYNLNDUSEtotal liquid runoff not including correction for land use change (does not include QSNWCPICE) -mm/s -QSNWCPICEexcess snowfall due to snow -cappingmm/s -QSNWCPICE_NODYNLNDUSEexcess snowfall due to snow capping not including correction for land use change -mm/s -QSNWCPLIQexcess rainfall due to snow -cappingmm/sinactive -SMPsoil matric -potentialmminactive -SNOAERFRC2Lsurface forcing of all aerosols in snow, averaged only when snow is present (land) -watt/m^2 -SNOAERFRCLsurface forcing of all aerosols in snow -(land)watt/m^2 -SNOBCFRCLsurface forcing of BC in snow -(land)watt/m^2 -SNOBCMCLmass of BC in snow -columnkg/m2 -SNOBCMSLmass of BC in top snow -layerkg/m2 -SNOdTdzLtop snow layer temperature gradient -(land)K/m -SNODSTFRC2Lsurface forcing of dust in snow, averaged only when snow is present (land) -watt/m^2 -SNODSTFRCLsurface forcing of dust in snow -(land)watt/m^2 -SNODSTMCLmass of dust in snow -columnkg/m2 -SNODSTMSLmass of dust in top snow -layerkg/m2 -SNOFSRNDdirect nir reflected solar radiation from -snowwatt/m^2inactive -SNOFSRNIdiffuse nir reflected solar radiation from -snowwatt/m^2inactive -SNOFSRVDdirect vis reflected solar radiation from -snowwatt/m^2inactive -SNOFSRVIdiffuse vis reflected solar radiation from -snowwatt/m^2inactive -SNOFSDSNDdirect nir incident solar radiation on -snowwatt/m^2inactive -SNOFSDSNIdiffuse nir incident solar radiation on -snowwatt/m^2inactive -SNOFSDSVDdirect vis incident solar radiation on -snowwatt/m^2inactive -SNOFSDSVIdiffuse vis incident solar radiation on -snowwatt/m^2inactive -SNOLIQFLtop snow layer liquid water fraction -(land)fractioninactive -SNOOCMCLmass of OC in snow -columnkg/m2 -SNOOCMSLmass of OC in top snow -layerKg/m2 -SNOOCFRC2Lsurface forcing of OC in snow, averaged only when snow is present (land) -watt/m^2 -SNOOCFRCLsurface forcing of OC in snow -(land)watt/m^2 -SNORDSLtop snow layer effective grain -radiusm^-6inactive -SNOTTOPLsnow temperature (top -layer)K/minactive -SWupupwelling shortwave -radiationwatt/m^2inactive -TSOI_10CMsoil temperature in top 10cm of -soilK -URBAN_ACurban air conditioning -fluxwatt/m^2 -URBAN_HEATurban heating -fluxwatt/m^2 -VOCFLXTtotal VOC flux into -atmosphereuGC/M2/H -Windatmospheric wind velocity -magnitudem/sinactive -WOOD_HARVESTCwood harvest (to product -pools)gC/m^2/s -WOOD_HARVESTwood harvest (to product -pools)gN/m^2/s - - - - - History field name changes: - - -OldNew -ANNSUM_PLANT_NDEMAND= -ANNSUM_POTENTIAL_GPP -ANNSUM_RETRANSN= ANNMAX_RETRANSN -C13_DWT_PROD10C_LOSS= C13_PROD10C_LOSS -C13_DWT_PROD100C_LOSS= C13_PROD100C_LOSS -C13_DWT_PROD10N_LOSS= C13_PROD10N_LOSS -C13_DWT_PROD100C_LOSS= C13_PROD100C_LOSS -DWT_PROD100N_LOSS= PROD10N_LOSS -DWT_PROD100N_LOSS= PROD100N_LOSS -DWT_PROD100C_LOSS= PROD10C_LOSS -DWT_PROD100C_LOSS= PROD100C_LOSS -HCSOISNO= HC -TEMPSUM_PLANT_NDEMAND= -TEMPSUM_POTENTIAL_GPP -TEMPSUM_RETRANSN= TEMPMAX_RETRANSN - - - -History field names deleted include: SNOWAGE, TSNOW, FMICR, FCO2, DMI, QFLX_SNOWCAP - - - -Add new urban oriented _U, and _R (Urban and Rural) for the following history variables: -EFLX_LH_TOT, FGR, FIRA, FSH, FSM, Q2M, QRUNOFF, RH2M, SoilAlpha, TG, TREFMNAV, -TREFMXAV, and TSA (missing _R for SoilAlpha as the regular SoilAlpha is only defined -for rural areas anyway) - - - -We are missing the Rural soil-alpha variable: SoilAlpha_R on purpose. -SoilAlpha_U is only defined over pervious road, and missing everywhere else. -SoilAlpha is defined only for rural areas. - - - - - - - - - - - -Quickstart to using &clm4; - -Before working with &clm4; read the QuickStart Guide in the -&cesmrel; -Scripts User's Guide. Once you are familiar with how to setup cases for -any type of simulation with &cesm; you will want to direct your attention to the specifics -of using &clm;. - - -For some of the details of setting up cases for &clm4; read the README and text files available -from the "models/lnd/clm/doc" directory (see the "&clm; Web pages" section for a link to the list -of these files). Here are the important ones that you should be familiar with. - -README file describing the directory structure. -Quickstart.userdatasets file describing how to -use your own datasets in the model (also see ). -&KnownBugs; file describing known -problems in &clm4; (that we expect to eventually fix). -KnownLimitations file -describing known limitations in &clm4; and workarounds that we do NOT expect to -fix. - - -The IMPORTANT_NOTES file is given in the next chapter on what -is functional/validated in &clm4;? - -The ChangeLog/ChangeSum files are largely explained in the previous chapter on "What is new with -&clm4;?" - -Note other directories have README files that explain different components and tools used -when running &clm; and are useful in -understanding how those parts of the model work and should be consulted when using tools in those directories. -For more details on configuring and customizing a case with &clm; see . - -The Quickstart.GUIDE (which can be found in -models/lnd/clm/doc) is repeated here. - -&quickstart_guide; - - - - -What is scientifically validated and functional in &clm4;? - -In this section we go over what has been extensively tested and scientifically validated -with &clm4;, and maybe more importantly what has NOT been tested and may NOT be -scientifically validated. You can use all features of &clm;, but need to realize that -some things haven't been tested extensively or validated scientifically. When you use -these features you may run into trouble doing so, and will need to do your own work to -make sure the science is reasonable. - - - -Standard Configuration and Namelist Options that are Validated - -The standard version of the model is &clmcn; at 1-degree horizontal resolution (0.9x1.25). This version has been scientifically -validated with long simulations for: fully coupled simulations ("B" cases), coupled to -atmosphere model CAM ("F" cases), and stand-alone &clm; -cases ("I" cases). We've also done both long simulations for 1850 conditions, and transient 20th century simulations from 1850 to 2005 (with -transient land-use, Nitrogen and Aerosol deposition). There have also been transient -future scenario simulations done for fully coupled cases for different "representative -concentration pathway" (RCP) scenarios (RCP2.6, RCP4.5, RCP6.0, and RCP8.5). -To a lesser extent there have also -been simulations done at T31 and 2-degree horizontal -resolution (1.9x2.5), and with &clmsp; for these resolutions. As such we have provided -appropriate 1-degree, 2-degree, and T31 initial condition -datasets for these configurations. The irrigation and prognostic crop models were both -validated at 2-degree resolution. The irrigation model for &clmsp; for present day -conditions for an "I" compset, and the prognostic crop model for present day conditions -for a case coupled to the active land model, but using a data ocean model (an "F" -compset). Other resolutions, configurations, and namelist options are less well tested or scientifically validated. -The further you get away from the standard configurations and resolutions, the more likely you are to run into trouble, and/or need to -scientifically validate your work. - - -In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You -are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even -with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case -you will need to go through more extensive work to validate these options from a scientific standpoint. - - - - -Configure Modes NOT scientifically validated, documented, supported or, in some -cases, even advised to be used: - - - - - C13(-c13) -The C13 mode for bgc=cn is NOT scientifically validated or documented and is NOT -recommended for use. - - - - - - CASA(-bgc casa) -The bgc=casa mode is NOT scientifically validated or documented and is NOT -recommended for use. - - - - - - SNICAR_FRC(-snicar_frc) - This mode is tested and functional, but is NOT constantly scientifically validated, and should be - considered experimental. - - - - - - - -Namelist options that should NOT be exercised: - -Build-Namelist options that should NOT be exercised: - - --irrig with -bgc cn -We have only run the irrigation model with &clmsp; (i.e. without the CN model). We -recommend that if you want to run the irrigation model with CN, that you do a spinup. -But, more than that you may need to make adjustments to -irrig_factor in -models/lnd/clm/src/biogeophys/CanopyFluxesMod.F90. See the -notes on this in the description of the irrigation model in the - -Technical Descriptions of the Interactive Crop Management and Interactive -Irrigation Models. - - --irrig with -crop on -Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to -generic crop currently, which negates it's practical usage. We also have a known -problem when both are on (see bug 1326 in the &KnownBugs; file). -If you try to run in this mode, the &clm; &buildnml; will return with an error. - - --lnd_res: Fine-mesh mode, functional, but experimental - --rcp: Representative Concentration Pathway (RCP) -for future scenarios, functional for limited resolutions, but experimental - --datm_*: All options that start with "datm_" they are -only used for &clm; stand-alone testing. - --drv_*: All options that start with "drv_" they are -only used for &clm; stand-alone testing. - - - - - - -Namelist items that should NOT be exercised: - - -casa namelist options: lnpp, lalloc, q10, spunup, and fcpool - - CASA has NOT been scientifically validated in &clm4;. - - - - suplnitro='ALL' - The suplnitro namelist option to the CN Biogeochemistry model supplies -unlimited nitrogen and therefore vegetation is over-productive in this mode. - - - -urban_traffic: Not currently functional - - - - - - - - - -What are the UNIX utilities required to use &clm;? - -Running the &clm; requires a suite of UNIX utilities and programs and you should -make sure you have all of these available before trying to go forward with using -it. If you are missing one of these you should contact the systems administrator -for the machine you wish to run on and make sure they are installed. - -&FORTRAN90; compiler -"C" compiler -GNU make -UNIX csh and tcsh shells -UNIX sh shell -UNIX bash shell -UNIX awk -UNIX sed -&netcdf; library -MPI Library -"C" pre-processor -&perl; -Autoconf -m4 macro processor -Parallel &netcdf; (optional) -&ncl; (for some of the offline tools for creating/modifying &clm; input -datasets see for more information on &ncl;) -Python (optional, needed for &ptclm;) -xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide) -protex and latex2html (optional, needed to build the Code-Reference Guide) - - - - - - - - - &cesm; Online Bulletin Board - &cesmrel; Scripts User's Guide - - -Other resources to get help from - - -In addition to this users-guide there are several other resources that are available -to help you use &clm4;. The first one is the &cesm; User's-Guide, which documents the entire -process of creating cases with &cesm;. The next is the &cesm; bulletin board which is -a web-site for exchanging information between users of &cesm;. There are also &clm; -web-pages specific for &clm;, and finally there is an email address to report bugs that -you find in &cesm1;. - - - -The &cesm; User's-Guide - -&clmrel; is always run from within the standard &cesmrel; build and run scripts. Therefore, the -user of &clm4; -should familiarize themselves with the &cesmrel; scripts and understand how to work with them. -User's-Guide documentation on the &cesmrel; scripts are available from the following web-page. The purpose -of this &clmrel; User's Guide is to give the &clm4; user more complete details on how to work -with &clm; and the set of tools that support &clm;, as well as to give examples that are unique to the use -of &clm;. However, the &cesmrel; Scripts User's-Guide remains the primary source to get detailed -information on how to build and run the &cesm; system. - -&cesm1; Scripts -User's-Guide - - - - - -The &cesm; Bulletin Board - -There is a rich and diverse set of people that use the &cesm;, and often it is useful to be in contact with -others to get help in solving problems or trying something new. To facilitate this we have an online -Bulletin Board for questions on the &cesm;. There are also different sections in the Bulletin Board for -the different component models or for different topics. - -&cesm; Online Bulletin Board - - - - - -The &clm; web pages - -The main &clm; web page contains information on the &clm;, it's history, developers, as well as -downloads for previous model versions. There are also documentation text files in the -models/lnd/clm/doc directory that give some quick information on using &clm;. - -&clm; web page -&clm; Documentation Text Files - -Also note that several of the XML database files can be viewed in a web browser to get -a nice table of namelist options, namelist defaults, or compsets. Simply view them -as a local file and bring up one of the following files: - -models/lnd/clm/bld/namelist_files/namelist_definition.xml --- definition of &clm; namelist items. -models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml --- default values for &clm; namelist items. -scripts/ccsm_utils/Case.template/config_definition.xml --- definition of all env_*.xml items. -scripts/ccsm_utils/Case.template/config_compsets.xml --- definition of all the compsets. -models/lnd/clm/bld/namelist_files/history_fields.xml --- definition of &clm; history fields. - - - - - -Reporting bugs in &clm4; - -If you have any problems, additional questions, bug reports, or any other feedback, please send an email to -cesmhelp@cgd.ucar.edu. If you find bad, wrong, or misleading information - in this users guide send an email to erik@ucar.edu. The current list of -known issues for &clmrel; is in the &KnownBugs; file, and the list of issues for -&cesmrel; is at... - -&cesmwebmodelrel;/tags/cesm1_0_3/#PROBLEMS -. - - - - - - - - diff --git a/doc/UsersGuide/ptclm.xml b/doc/UsersGuide/ptclm.xml deleted file mode 100644 index 6c0ef2aec8..0000000000 --- a/doc/UsersGuide/ptclm.xml +++ /dev/null @@ -1,992 +0,0 @@ - - -How to run &ptclm; - -&ptclm; (pronounced point clime) is a Python script to help you set up PoinT CLM -simulations. It runs the &clm; tools for you to get datasets set up, and copies them -to a location you can use them according to the &CLMUSRDAT; naming convention. Then -it runs create_newcase for you and modifies the env settings and -namelist appropriately. &ptclm; has a simple ASCII text file for storing basic -information for your sites. We also have complete lists for AmeriFlux and Fluxnet-Canada -sites, although we only have the meteorology data for one site. For other sites you -will need to obtain the meteorology data and translate it to a format that the &cesm; -datm model can use. But, even without meteorology data &ptclm; is useful to setup -datasets to run with standard &CLMQIAN; data. - - - -The original authors of &ptclm; are: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, -Wilfred M. Post all at Environmental Sciences Division, Oak Ridge National Laboratory -(ORNL) and R. Quinn Thomas at Cornell University. It was then modified -fairly extensively by Erik Kluzek at &ncar;. We want to thank all of these individuals -for this contribution to the &cesm; effort. We also want to thank the folks at -University of Michigan Biological Stations (US-UMB) who allowed us to use their Fluxnet -station data and import it into our inputdata repository, especially Gil Bohrer the -PI on record for this site. - - - -Introduction to PTCLM - -To get help on &ptclm; use the "--help" option as follows. - -> cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM -> ./PTCLM.py --help - - - -The output to the above command is as follows: - - - -&ptclm_help; - - - - -Here we give a simple example of using &ptclm; for a straightforward case of running -at the US-UMB Fluxnet site on bluefire where we already have the meteorology data on -the machine. Note, see for permission information -to use this data. - -Example of running &ptclm; for US-UMB on bluefire - -setenv CSMDATA /fis/cgd/cseg/csm/inputdata -setenv MYCSMDATA $HOME/inputdata -setenv SITE US-UMB -setenv MYMACH bluefire -setenv MYCASE testPTCLM - -# First link the standard input files to a location you have write access -cd scripts -./link_dirtree $CSMDATA $MYCSMDATA - -# Next build all of the clm tools you will need -cd ../models/lnd/clm/tools/mksurfdata -gmake -gmake clean -cd ../mkdatadomain -gmake -gmake clean -cd ../mkgriddata -gmake -gmake clean -# next run PTCLM (NOTE -- MAKE SURE python IS IN YOUR PATH) -cd ../../../../../scripts/ccsm_utils/Tools/lnd/clm/PTCLM -./PTCLM.py -m $MYMACH --case=$MYCASE --site=$SITE --csmdata=$MYCSMDATA \ - --aerdepgrid --ndepgrid -# NOTE: we use --aerdepgrid --ndepgrid so that you use the global -# aerosol and Nitrogen deposition files rather than site-specific ones. -cd ../../../../../$MYCASE -# Finally configure, build, and run the case as normal - - - - - - -Guide to the options of &ptclm; - -There are three types of options to &ptclm;: required, configure/run-time, and -dataset generation options. The three required options are the three settings that -MUST be specified for &ptclm; to work at all. The other settings have default -values that will default to something useful. The configure/run-time options control -how the simulation will be setup and run. The dataset generation options control -the generation of datasets needed when &ptclm; is run. Most options use a double -dash "--" "longname" such as "--list", but the most common options also have a short-name -with a single dash (such as -m instead of --machine). - - -The required options to &ptclm; are: inputdata directory (-d), machine (-m) and -site-name (-s). Inputdata directory is the directory where you have the &cesm; -inputdata files, you need to have write access to this directory, so if you are -running on a machine that you do NOT have write access to the standard inputdata -location (such as &ncar; bluefire or ORNL jaguar) you need -to link the standard files to a location you do have control over. We recommend -using the scripts/link_dirtree tool to do that. "machine" is -the scripts name for the machine/compiler you will be using for your case. And -finally site-name is the name of the site that you want to run for. Site-name -can either be a valid &CLM1PT; supported dataset name or a Fluxnet site name -from the list of sites you are running on (see the --sitegroupname for more information -about the site lists). - - -After &ptclm; is run a case directory where you can then configure, build and run -your &cesm; case as normal. It also creates a README.PTCLM -in that directory that documents the commandline options to &ptclm; that were used -to create it. - - -After "help" the "list" option is one of the most useful options for getting -help on using &ptclm;. This option gives you information about some of the other -options to &ptclm;. To get a list of the machine, sites, and compsets that can be -used for &ptclm; use the "--list" option as follows. - -> cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM -> ./PTCLM.py --list - - - -The output to the above command is as follows: - - - -&ptclm_list; - - - - -Overview on using &ptclm; - -Steps in running &ptclm; - -Setup Inputdata directory with write access (use -<command>link_dirtree</command> script) - -You need to setup an inputdata directory where you have write access to it. -Normally, for &ncar; machines the data is on an inputdata where the user -does NOT have write access to it. A way that you can get around this is -to use the link_dirtree script to create softlinks from -the normal location to a location you have write access to. So for example -on bluefire: - -> setenv CSMDATA /fs/cgd/csm/inputdata -> setenv MYCSMDATA $HOME/inputdata -> mkdir $MYCSMDATA -> cd scripts -> ./link_dirtree $CSMDATA $MYCSMDATA - -See for more information on this. - - - -Build the &clm; tools - -Next you need to make sure all the &clm; &FORTRAN; tools are built. - -> cd models/lnd/clm/tools/mkgriddata -> gmake -> gmake clean -> cd ../mkdatadomain -> gmake -> gmake clean -> cd ../mksurfdata -> gmake -> gmake clean - - - - -Run &ptclm; - -Next you actually run &ptclm; which does the different things listed below: - - - -&ptclm; names your case based on your input - -&ptclm; names you case based on the input you give to it. - -[Prefix_]SiteCode_Compset[_QIAN][_spinuptype] -Where: - Prefix is from the caseidprefix option (or blank if not used). - SiteCode is the site name you entered with the -s option. - Compset is the compset name you entered with the -c option. - _QIAN is part of the name only if the useQIAN is used. - _spinuptype is part of the name if one of: ad_spinup, exit_spinup, or - final_spinup is used, and the exact spinup name chosen is used. - -For example, the casename for the following will be: - -> cd scripts -> ./PTCLM.py -m bluefire -s US-UMB -d $MYCSMDATA -c I_2000_CN --ad_spinup --useQIAN - -"US-UMB_I_2000_CN_QIAN_ad_spinup". - - - -&ptclm; creates datasets for you - -It will populate $MYCSMDATA with new datasets it creates using the -&clm; tools. - - - -If a transient compset and &ptclm; finds a <filename>_dynpftdata.txt</filename> -file - -If you are running a transient compset (such as the "I_1850-2000_CN" compset) -AND you there is a file in the PTCLM_sitedata directory under -the &ptclm; directory called $SITE_dynpftdata.txt it will use -this file for the land-use changes. Otherwise it will leave land-use constant, unless -you use the pftgrid option so it uses the global dataset for landuse changes. -See for more information on this. There -is a sample transient dataset called US-Ha1_dynpftdata.txt. -Transient compsets, are compsets that create transient land-use change and -forcing conditions such as: -'I_1850-2000', 'I_1850-2000_CN', 'I_RCP8.5_CN', 'I_RCP6.0_CN', 'I_RCP4.5_CN', -or 'I_RCP2.6_CN'. - - - -&ptclm; creates a <filename>pft-physiology</filename> for you - -&ptclm; will create a local copy of the pft-physiology -specific for your site that you could then customize with changes specific -for that site. - - - -&ptclm; creates a <filename>README.PTCLM</filename> for you - -&ptclm; will create a simple text file with the command line for it in a file -called README.PTCLM in the case directory it creates for you. - - - - - - -Customize, configure, build and run case as normal - -You then customize your case as you would normally. See the chapter for more information on doing this. - - - - - - - -Details on the options of &ptclm; - -Next we discuss the configure and run-time options, dividing them up into -configure, spinup, and run-time options. - - -Configure options include: - --c MYCOMPSET, --compset=MYCOMPSET ---caseidprefix=MYCASEID ---cesm_root=BASE_CESM ---namelist=NAMELIST ---rmold ---scratchroot=SCRATCHROOT ---sitegroupname=SITEGROUP ---QIAN_tower_yrs ---useQIAN - - - - - ---compset - -The "-c" option is the most commonly used option after the required options, as it -specifies the &cesm; scripts component set to use with &ptclm;. The default compset -is the "ICN" compset with CN on for present day conditions. - - - - - ---caseidprefix - -This option gives a prefix to include in the casename when the case is created, in -case you want to customize your casenames a bit. By default, casenames are figured -out based on the other options. The argument to this option can either be a name to -prefix casenames with and/or a pathname to include. Hence, if you want cases to -appear in a specific directory you can give the pathname to that directory with this -option. - - - - - ---cesm_root - -This option is for running &ptclm; with a different root directory to &cesm; than the -version &ptclm; exists in. Normally you do NOT need to use this option. - - - - - ---namelist - -This option adds any items given into the &clm; &usernlclm; namelist. This allows you to -add customizations to the namelist before the clm.buildnml.csh file -is created for the case. - - - - - ---rmold - -This option will remove an old case directory of the same name if one exists. Otherwise, -if an old case directory already exists and you try to run &ptclm; it will return with -an error. - - - - - ---scratchroot - -This option is ONLY valid when using one of the generic machines (the -m option). -This passed onto create_newcase and gives the location where cases -will be built and run. - - - - - ---sitegroupname - -In the &ptclm; directory there is a subdirectory "PTCLM_sitedata" that contains -files with the site, PFT and soil data information for groups of sites. These site groups -are all separate ASCII files with the same prefix followed by a "_*data.txt" name. -See for more information on these files. -By default we have provided three different valid group names: - -EXAMPLE -AmeriFlux -Fluxnet-Canada - -The EXAMPLE is the group used by default and ONLY includes the US-UMB site as that -is the only site we have data provided for. The other two site groups include the -site information for all of both the AmeriFlux and Fluxnet-Canada sites. You can use -the "sitegroupname" option to use one of the other lists, or you can create your own -lists using the EXAMPLE file as an example. Your list of sites could be real world -locations or could be theoretical "virtual" sites given to exercise &clm; on -differing biomes for example. Note, see with -permission information to use the US-UMB data. - - - - - ---useQIAN - -This option says to use the standard &clm; global Qian T62 atmospheric forcing rather -than any tower site forcing data available. Otherwise, &ptclm; will try to find tower -forcing data for the specific site entered. - - - - - ---QIAN_tower_yrs - -This option is used with the "useQIAN" option to set the years to cycle over for -the Qian data. In this case Qian atmospheric forcing will be used, but the -simulation will run over the same years that tower site is available for this site. - - - - - - -Spinup options include: - ---coldstart ---ad_spinup ---exit_spinup ---final_spinup ---finidat=FINIDAT - - - - -The spinup options enable the different CN spinup modes, but also set the run -length. The coldstart option says to startup with OUT an initial condition file, while -the finidat option explicitly gives the initial condition file to use. Obviously, -the different spinup options can NOT be used together, nor can the coldstart and -finidat options be either. - - ---coldstart - -This option ensures that a cold-start will be done with arbitrary initial conditions. - - - - - ---ad_spinup - -This option enables the accelerated decomposition mode when a CN compset is used. It -also sets the run-length as given in the example for running exit spinup in -. - - - - - ---exit_spinup - -This option enables the exit spinup mode when a CN compset is used. It also sets the -run-length to a year just as given in the example for running exit spinup in -. - - - - - ---final_spinup - -This option sets the run length as given in the example for a final spinup in -. This option can be used for any compset. - - -There is a bug in the final_spinup mode for setting the run length. Because of the -bug, final_spinup mode only runs for a very short time, you'll need to edit -the run length by hand to be 50 years. See bug 1367 in the &KnownBugs; file. - - - - - - - ---finidat - -This option sets the initial condition file to startup the simulation from. - - - - - - - - - -Run-time options include: - ---debug ---run_n=MYRUN_N ---run_units=MYRUN_UNITS ---stdurbpt - - - - - - - ---debug - -This option tells &ptclm; to echo what it would do if it were run, but NOT actually -run anything. So it will show you the dataset creation commands it would use. -It does however, run create_newcase, but then it only displays -the xmlchange commands and changes that it would do. Also note -that if you give the "--rmold" option it won't delete the case directory beforehand. -Primarily this is intended for debugging the operation of &ptclm;. - - - - - ---run_n - -This option along with run_units is used to set the length for the simulation. "run_n" -is the number of units to use. -The default run length depends on the site, compset, -and configuration and for example if a "spinup" option is selected. - - - - - ---run_units - -This option is the units of time to use for the length of the simulation. It is used -along with "run_n" to set the length of the simulation. -The default run length depends on the site, compset, -and configuration and for example if a "spinup" option is selected. - - - - - ---stdurbpt - -This option turns on the "stdurbpt_pd" use-case for &CLMUSECASE;. This option -can NOT be used for compsets that set the use-case to something besides present-day. - - - - - - - - -Lastly we discuss the dataset generation options. The dataset generation options are: - ---aerdepgrid ---ndepgrid ---pftgrid ---soilgrid ---nopointdata ---owritesrfaer - - - - -The options that with a "grid" suffix all mean to create datasets using the global -gridded information rather than using the site specific point data. By default the -site specific point data is used. The "nopointdata" and "owritesrfaer" options have to -do with file creation. - - -Because supported single-point datasets already have the data created for them, you -MUST use the "nopointdata" and "ndepgrid" options when you are using a supported -single-point site. You must use "ndepgrid" even for a compset without CN. You also -can NOT use the options: "soilgrid", "pftgrid", "aerdepgrid", or "owritesrfaer". - - - - - ---aerdepgrid - -This option says to use the aerosol deposition files from the global dataset rather -than creating an interpolated version. - - -This option must NOT be used when you you are using a site that -is a supported single point dataset. - - - - - ---ndepgrid - -This option says to use the Nitrogen deposition files from the global dataset rather -than creating an interpolated version. This is only needed for compsets with CN. - - - -This option is required when you you are using a site that -is a supported single point dataset. This is true even when you are NOT using a -compset with CN. - - - - - - ---pftgrid - -This option says to use the PFT values provided on the global dataset rather than -using the specific site based values from the -PTCLM_sitedata/*_pftdata.txt file when creating the surface dataset. - - -This option must NOT be used when you you are using a site that -is a supported single point dataset. - - - - - ---soilgrid - -This option says to use the soil values provided on the global dataset rather than -using the specific site based values from the -PTCLM_sitedata/*_soildata.txt file when creating the surface dataset. - - -This option must NOT be used when you you are using a site that -is a supported single point dataset. - - - - - ---nopointdata - -This option says to NOT create any input datasets -- assume this step has already been -done. If datasets weren't already created, your case will fail when you try to run it. -In general the first time you run &ptclm; for a new site you want it to generate new -datasets, but the next time and future times you want to use this option so that it -doesn't waste a lot of time rebuilding datasets over again. - - - -This option is required when you you are using a site that -is a supported single point dataset. - - - - - - ---owritesrfaer - -This option says to overwrite any surface and/or aerosol deposition datasets that -were already created. Otherwise, the creation of these files will be skipped if a file -is already found (but it WILL create files if they don't exist). - - -This option must NOT be used when you you are using a site that -is a supported single point dataset. - - - - - - - - -Note on the aerosol and Nitrogen deposition files. When the "aerdepgrid" and "ndepgrid" -options are NOT used -- aerosol and Nitrogen deposition files will be created by -interpolating from the global datasets. However, after these interpolated files -are created you could customize them for your site with data that you provide. You -could then write protect the files and use the "nopointdata" option so that &ptclm; -doesn't try to overwrite them in the future. - - - - - - -Examples using &ptclm; - -Now let's give a few more complex examples using some of the options we have -discussed above. - - -In this first example, we'll demonstrate using a supported single point dataset, -which then requires using the "nopointdata" and "ndepgrid" options. We'll also -demonstrate the compset option, "stdurbpt" and "caseidprefix" options. - -Example of running &ptclm; for the Mexicocity supported single point -dataset - -> cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM -> ./PTCLM.py -m bluefire -s 1x1_mexicocityMEX -d $CSMDATA --nopointdata --ndepgrid \ ---stdurbpt -c I --caseidprefix `pwd`/myPTCLMcases/site -> cd myPTCLMcases/site_1x1_mexicocityMEX_I -> ./configure -case -# Now build and run normally -> ./site_1x1_mexicocityMEX_I.bluefire.build -# Here we show running interactively -> ./site_1x1_mexicocityMEX_I.bluefire.run - - - - - -Now, let's demonstrate using a different group list, doing a spinup, running with Qian -global forcing data, but using tower years to set the years to run over. This uses -the options: sitegroupname, ad_spinup, useQIAN, and QIANtower_years. - -Example of running &ptclm; for a spinup simulation with Qian data for tower years. - - -> cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM -> ./PTCLM.py -m bluefire -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux \ ---ad_spinup --useQIAN --QIAN_tower_yrs -> cd ../../../../../US-Ha1_ICN_QIAN_ad_spinup -> ./configure -case -# Now build and run normally -> ./US-Ha1_ICN_QIAN_ad_spinup.bluefire.build -# Here we show running interactively -> ./US-Ha1_ICN_QIAN_ad_spinup.bluefire.run - - - - - -Finally, let's demonstrate using a generic machine (which then requires the scratchroot -option), using the global grid for PFT and soil types, and setting the run length -to two months. - -Example of running &ptclm; on a generic machine with global PFT and soil types -dataset - -> cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM -# Note, see the with permission information -# to use the US-UMB data. -> ./PTCLM.py -m generic_darwin_intel -s US-UMB -d $CSMDATA --pftgrid --soilgrid \ ---scratchroot $HOME --run_n 2 --run_units nmonths -> cd ../../../../../US-UMB_ICN -> ./configure -case -# Now build -> ./US-UMB_ICN.generic_darwin_intel.build -# To get the files from the svn server... -# First list the files from the streams text file -> ../ccsm_utils/Tools/listfilesin_streams \ --t $HOME/US-UMB_ICN/run/clm1PT.1x1pt_US-UMB.stream.txt -l \ -> Buildconf/datm.input_data_list -# And now run the script to export data to your machine -> ../ccsm_utils/Tools/check_input_data -export -# Here we show running interactively -> ./US-UMB_ICN.generic_darwin_intel.run - - - - -Because of Bug 1364, when running this case as above we get a floating point -error after reaching time-step 124 for the example exactly as above. Other -machines or compilers probably won't have this problem. See the &KnownBugs; file -for more information on this problem. - - - - -As documented in Bug 1368, spinning up the US-UMB site for a I2000CN compset gives -zero Gross Primary Production (GPP). If the user wishes to use this site for &clmcn;, -they'll need to address this issue. -See the &KnownBugs; file for more information on this problem. - - - - - - -Adding data for use by &ptclm; - -&ptclm; Group Site Lists - -The "sitegroupname" option to &ptclm; looks for groups of sites in the -files in the PTCLM_sitedata directory under the &ptclm; directory. -You can add new names available for this option including your own lists of sites, by -adding more files in this directory. There are three files for each "sitegroupname": -$SITEGROUP_sitedata.txt, -$SITEGROUP_soildata.txt -and $SITEGROUP_pftdata.txt (where $SITEGROUP is the name that would -be entered as "sitegroupname" to &ptclm;). Each file needs to have the same list of sites, -but gives different information: site data, PFT data, and soil data respectively. -Although the site codes need to be the same between the three files, the files do NOT -have to be in the same order. Each file has a one-line header that lists the contents -of each column which are separated by commas. The first column for each of the files -is the "site_code" which must be consistent between the three files. The site code -can be any unique character string, but in general we use the AmeriFlux site code. - - -Site data file: $SITEGROUP_sitedata.txt): The header for -this file is: - -site_code,name,state,lon,lat,elev,startyear,endyear,alignyear - -The columns: name, state, and elevation are informational only. Name is a longer -descriptive name of the site, and state is the state for U.S. sites or country -for non U.S. sites. The columns: lon and lat are the longitude and latitude of -the location in decimal degrees. The last three columns are the start and ending -year for the data and the align year for an 1850 case for the data. The align year -is currently unused. - - -Soil data file: $SITEGROUP_soildata.txt): The header for this -file is: - -site_code,soil_depth,n_layers,layer_depth,layer_sand%,layer_clay% - -The first three fields after "site_code" are currently unused. The only two that -are used are the percent sand and clay columns to set the soil texture. - - -PFT data file: $SITEGROUP_pftdata.txt): The header for this -file is: - -site_code,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5 - -This file gives the vegetation coverage for the different vegetation types for the site. -The file only supports up to five PFT's at the same time. The columns with "pft_f" are -the fractions for each PFT, and the columns with "pft_c" is the integer index of the -given PFT. Look at the pft-physiology file to see what the PFT index for each PFT type -is. - - - - -Dynamic Land-Use Change Files for use by &ptclm; - -There is a mechanism for giving site-specific land-use change in &ptclm;. Adding -site specific files to the PTCLM_sitedata directory under -&ptclm; allows you to specify the change in vegetation and change in harvesting -(for the CN model) for that site. Files are named: -$SITE_dynpftdata.txt. There is a sample file for the US-Ha1 -site called: US-Ha1_dynpftdata.txt. The file has a one-line -header with the information that the file has, and then one-line for each year -with a transition. The header line is as follows: - -trans_year,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5,har_vh1,har_vh2,har_sh1,har_sh2,har_sh3,graze,hold_harv,hold_graze - -This file only requires a line for each year where a transition or harvest happens. As -in the "pftdata" file above "pft_f" refers to the fraction and "pft_c" refers to the -PFT index, and only up to five vegetation types are allowed to co-exist. The last -eight columns have to do with harvesting and grazing. The last two columns are whether -to hold harvesting and/or grazing constant until the next transition year and will -just be either 1 or 0. This file will be converted by the -PTCLM_sitedata/cnvrt_trnsyrs2_landuse_timeseries_txtfile.pl script in the &ptclm; -directory to a format that mksurfdata can read that has an entry -for each year for the range of years valid for the compset in question. - - - - -Converting AmeriFlux Data for use by &ptclm; - -AmeriFlux data comes in comma separated format and is available from: - -http://public.ornl.gov/ameriflux/dataproducts.shtml. Before you -download the data you need to agree to the usage terms. - - -Here is a copy of the usage terms from the web-site on June/13/2011. - - -"The AmeriFlux data provided on this site are freely available and were furnished by -individual AmeriFlux scientists who encourage their use. Please kindly inform the -appropriate AmeriFlux scientist(s) of how you are using the data and of any publication -plans. Please acknowledge the data source as a citation or in the acknowledgments if the -data are not yet published. If the AmeriFlux Principal Investigators (PIs) feel that they -should be acknowledged or offered participation as authors, they will let you know and we -assume that an agreement on such matters will be reached before publishing and/or use of -the data for publication. If your work directly competes with the PI's analysis they may -ask that they have the opportunity to submit a manuscript before you submit one that uses -unpublished data. In addition, when publishing, please acknowledge the agency that -supported the research. Lastly, we kindly request that those publishing papers using -AmeriFlux data provide preprints to the PIs providing the data and to the data archive at -the Carbon Dioxide Information Analysis Center (CDIAC)." - - -The above agreement applies to the "US-UMB" dataset imported into our repository as -well, and Gil Bohrer is the PI on record for that dataset. - - -The &cesm; can NOT handle missing data, so we recommend using the "Level 4" Gap filled -datasets. -The fields will also need to be renamed. The "WS" column becomes "WIND", "PREC" becomes -"PRECmms", "RH" stays as "RH", "TA" becomes "TBOT", "Rg" becomes "FSDS", "Rgl" becomes -"FLDS", "PRESS" becomes "PSRF". "ZBOT" can just be set to the constant of "30" (m). -The units of Temperature need to be converted from "Celsius" to "Kelvin" (use the -value in SHR_CONST_TKFRZ in the file -models/csm_share/shr/shr_const.F90 of 273.15. -The units of Pressure also need to be converted from "kPa" to "Pa". LATIXY, and -LONGXY should also be set to the latitude and longitude of the site. - - - -&ptclm; transient example over a shorter time period - - -Example of running &ptclm; for transient land-use 1991-2006 for US-Ha1 on bluefire - -This is an example of using &ptclm; for Harvard Forest (AmeriFlux site code US-Ha1). In -order to do this we would've needed to have converted the AmeriFlux data into &netcdf; -format as show in the section above. Also note -that this site has a site-specific dynamic land-use change file for it -PTCLM_sitedata/US-Ha1_dynpftdata.txt in the &ptclm; directory -and this file will be used for land-use change and harvesting rather than the -global dataset. - - -> cd scripts/ccsm_utils/Tools/lnd/clm/PTCLM -# We are going to use forcing data over 1991 to 2006, but we need to start with -# a transient compset to do so, so we use the 20th Century transient: 1850-2000 -# Note: When creating the flanduse_timeseries dataset for this site it will use the -# PTCLM_sitedata/US-Ha1_dynpftdata.txt -# file for land-use change and harvesting -> ./PTCLM.py -m bluefire -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux \ --c I_1850-2000_CN -> mkdir $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 -> cd $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 -# Copy data in &netcdf; format to this directory, filenames should be YYYY-MM.nc -# The fieldnames on the file should be: -# FLDS,FSDS,LATIXY, LONGXY, PRECTmms,PSRF,RH,TBOT,WIND,ZBOT -# With units -# W/m2,W/m2,degrees_N,degrees_E,mm/s, Pa, %, K, m/s, m -# The time coordinate units should be: days since YYYY-MM-DD 00:00:00 -> cd ../../../../../US-Ha1_I_1850-2000_CN -# We need to turn cold-start on, so it doesn't expect an initial condition file -# preferably, you would generate your own initial condition file and then use -# the --finidat option to &ptclm; to enter it -> ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on -# Now we need to set the start date to 1991, and have it cycle forcing data -# over 1991 to 2006 -> ./xmlchange -file env_conf.xml -id RUN_STARTDATE -val 1991-01-01 -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_ALIGN -val 1991 -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_END -val 2006 -> ./xmlchange -file env_conf.xml -id CLM_NAMELIST_OPTS -val \ -# Similarly for Nitrogen deposition data we cycle over: 1991 to 2006 -"model_year_align_ndep=1991,stream_year_first_ndep=1991,stream_year_last_ndep=2006" -# Now configure the case, and we'll edit the datm namelist for prescribed aerosols -> ./configure -case -# We also need to change the datm to run with aerosols over the 1991-2006 period -cat << EOF > patch.diff -*** datm.buildnml.csh.orig 2011-06-14 09:28:20.000000000 -0600 ---- datm.buildnml.csh 2011-06-14 09:28:57.000000000 -0600 -*************** -*** 32,38 **** - dataMode = 'CLMNCEP' - domainFile = '$DOMAINFILE' - streams = 'clm1PT.1x1pt_US-Ha1.stream.txt 1991 1991 2006 ', -! 'presaero.stream.txt 1849 1849 2006' - vectors = 'null','null' - mapmask = 'nomask','nomask' - mapalgo = 'nn','nn' ---- 32,38 ---- - dataMode = 'CLMNCEP' - domainFile = '$DOMAINFILE' - streams = 'clm1PT.1x1pt_US-Ha1.stream.txt 1991 1991 2006 ', -! 'presaero.stream.txt 1991 1991 2006' - vectors = 'null','null' - mapmask = 'nomask','nomask' - mapalgo = 'nn','nn' -EOF -# Apply the above patch to the datm build namelist file -> patch Buildconf/datm.buildnml.csh patch.diff - - - - - - -Because of bug 1361, this won't work out of the box. You'll need to add the change -to PTCLM.py given in the KnownBugs file on this issue. - - - - - - - - -A bit about the structure of &ptclm;, what it does, and how it works - -A large part of &ptclm; just sets up the different options and does error checking -on the options given. &ptclm; then uses the options provided to use -create_newcase to create a new case. It then queries both the -case directory and/or the XML database (using -queryDefaultNamelist.pl in models/lnd/clm/bld -and does other settings for the case. It then runs the different &clm; tools in turn to -create the necessary datasets and points to them in the case with the &CLMUSRDAT; option. -It runs mkgriddata, mksurfdata.pl, and -mkdatadomain as well as the aerdepregrid.ncl and -ndepregrid.ncl &ncl; scripts. mkgriddata and -mkdatadomain have template namelist files in the -scripts/ccsm_utils/Tools/lnd/clm/PTCLM/usr_files directory. -When running mksurfdata.pl if it finds a -$SITE_dynpftdata.txt in the -scripts/ccsm_utils/Tools/lnd/clm/PTCLM/PTCLM_sitedata directory -it will use that file for transient landuse changes (there's a sample file for -"US-Ha1" called US-Ha1_dynpftdata.txt). -It modifies the different env*.xml using -xmlchange and creates an initial &usernlclm; filename. After -&ptclm; is run you can then make changes to the case by hand, and configure, build -and run as normal. - - -There is a simple test script to test &ptclm;. See -for more information on using it. - - - - - diff --git a/doc/UsersGuide/single_point.xml b/doc/UsersGuide/single_point.xml deleted file mode 100644 index b07f76ecb6..0000000000 --- a/doc/UsersGuide/single_point.xml +++ /dev/null @@ -1,930 +0,0 @@ - - - -How to run Single-Point/Regional cases - -The &clm; also allows you to set up and run cases with a single-point or a local region as well -as global resolutions. This is often useful for running quick cases for testing, evaluating -specific vegetation types, or land-units, or running with observed data for a specific site. -There are four different ways to do this: &PTSMODE;, -&CLM1PT;, &CLMUSRDAT;, and with &ptclm;. - -&PTSMODE; -- to run for a single point -using global datasets. -&CLM1PT; -- to run for a supported single-point -or regional dataset. -&CLMUSRDAT; -- to run using your own datasets (single-point -or regional). -&ptclm; -- to easily setup simulations to run for -tower sites.. - - - - -&PTSMODE; and &ptclm; only work for a single point, while the other two options can -also work for regional datasets as well. - - - -Which Single Point Option Should I choose? - -In general is the quick and dirty method -that gets you started without having to create datasets -- but has limitations. It's -good for an initial attempt at seeing results for a point of interest, but since you -can NOT restart with it, it's usage is limited. It is the quickest method as you can -create a case for it directly from create_newcase. Although you -can't restart, running a single point is very fast, and you can run for long -simulation times even without restarts. If you need restarts a good solution is to use -getregional_datasets.pl and &CLMUSRDAT; -which can get you running almost as quickly as well as -&PTSMODE;. Like -&PTSMODE; - only runs for points that exist within -a global dataset. - - -Running &CLM1PT; is a great solution, if one of the supported -single-point/regional datasets, is your region of interest (see -). All the datasets are -created for you, and you can easily select one and run, pretty much, out of the box -with it. The problem is that there is a very limited set of supported datasets. You -can also use this method for your own datasets, but you have to create the datasets, -and add them to the XML database and to the &datm;. This is worthwhile if you want to -repeat many multiple cases for a given point or region. - - -Next, &CLMUSRDAT; is the best way to setup cases quickly -where you have to create your own datasets (see -). With this method you don't have to -change &datm; or add files to the XML database -- but you have to follow a strict -naming convention for files. However, once the files are named and in the proper -location, you can easily setup new cases that use these datasets. This is good -for treating all the required datasets as a "group" and for a particular -model version. For advanced &clm; developers who need to track dataset changes with -different model versions you would be best off adding these datasets as supported -datasets with the &CLM1PT; method. - - -Lastly &ptclm; is a great way to easily create datasets, -setup simulations and run simulations for tower sites. It takes advantage of both -&CLM1PT; and &CLMUSRDAT; internally. A big advantage to it, is that it's one-stop -shopping, it runs tools to create datasets, and runs create_newcase -and sets the appropriate env variables for you. So you only have to learn how to run -one tool, rather than work with many different ones. &ptclm; is described in the next -chapter . - - -Finally, if you also have meteorology data that you want to force your &clm; simulations -with you'll need to setup cases as described in . -You'll need to create &clm; datasets either according to &CLM1PT; -or &CLMUSRDAT;, but you'll also need to modify &datm; to use -your forcing data. And you'll need to change your forcing data to be in a format that -&datm; can use. In the &ptclm; chapter the -section tells you how to use AmeriFlux data for atmospheric forcing. - - - - -Running &PTSMODE; configurations - -&PTSMODE; enables you to run the model using global datasets, but just picking a -single point from those datasets and operating on it. It can be a very quick way to do fast -simulations and get a quick turnaround. - - -To setup a &PTSMODE; simulation you use the "-pts_lat" and "-pts_lon" -arguments to create_newcase to give the latitude and longitude of the point you want to -simulate for (the code will pick the point on the global grid nearest to the point you -give. Here's an example to setup a simulation for the nearest point at 2-degree resolution -to Boulder Colorado. - -> cd scripts -> ./create_newcase -case testPTS_MODE -res f19_g16 -compset I -mach bluefire \ --pts_lat 40.0 -pts_lon -105 -> cd testPTS_MODE -# We make sure the model will start up cold rather than using initial conditions -> ./xmlchange -file env_conf.xml -id &CLMFORCECOLD; -val on -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup - -Then configure, build and run as normal. We make sure initial conditions are NOT used -since &PTSMODE; currently CAN NOT run with initial conditions. - - - -By default it sets up to run with -USE_MPISERIAL (in the env_build.xml file) turned on, -which allows you to run the model interactively. On some machines this mode is NOT -supported and you may need to change it to FALSE before you are able to build. - - - - -&PTSMODE; currently does NOT restart nor -is it able to startup from global initial condition files. See bugs "1017 and 1025" -in the KnownLimitations file. - - - - -You can change the point you are simulating for at run-time by changing the values of -PTS_LAT and PTS_LON in the env_run.xml file. - - - - -Note, that when running with &PTSMODE; the number of processors -is automatically set to one. When running a single grid point you can only use a single -processor. You might also want to set the "env_conf" variable: USE_MPISERIAL to -TRUE so that you can also run interactively without having to use -&mpi; to start up your job. - - - - -Warning about Running with a Single-Processor on a Batch Machine - -This problem always comes up when running for a single point, because you can only use -a single-processor, but may come up in other instances when you are running with -one processor. This applies to all the different ways of running in single-point mode. - - - -A warning for submitting single-point simulations to the batch que when only using -one processor. On many machines this will mean using up at least an entire node, and -being charged for all the CPU's on that node even if you aren't using them. For example, -on the &ncar; machine bluefire, there are 32 processors for each node -and the batch scripts are setup to have exclusive use of that node (and hence be charged -for all 32 processors). There are similar issues on other machines, below we show you -what to do when running on bluefire. - - -To change this on bluefire -- change the following: - -#BSUB -q regular -#BSUB -N -#BSUB -x - -to... - -#BSUB -q share -#BSUB -N - -so remove the "#BSUB -x" which gives you the entire node exclusively, and change to the -share que. One other machines you may have to do something similar, but the particulars -depend on the given machine, hence you will need to consult with the system -administrators for the given machine you are running on. - - - - -Another similar problem on many machines is that some batch ques have a minimum number -of nodes or processors that can be used. On these machine you may have to change the -queue (in some way similar to the above for bluefire) and possibly the time-limits of -the job, to get it to run in the batch que. - - - -Another way to get around this problem is to run the job interactively using -USE_MPISERIAL so that you don't submit the job to the batch que. -For single point mode you also may want to consider using a smaller workstation or -cluster, rather than a super-computer, because you can't take advantage of the -multi-processing power of the super-computer anyway. - - - - -Running Supported Single-point/Regional Datasets - -In addition to &PTSMODE; the &clm; supports running using single-point or -regional datasets that are customized to a particular region. In the section below we -tell the user how to create their own dataset, but we also support a small number of -single-point and regional datasets that are ready to setup and run in the CESM modeling -system. - - -To get the list of supported dataset resolutions see the method given in the -section on use of &CLM1PT;, which results in the following: - -&res_list; - -The resolution names that have an underscore in them ("_") are all single-point or -regional resolutions. -To run with the supported single-point and regional datasets, you setup a simulation for the -"pt1_pt1" resolution and give the short-name for the file to use in the -env_conf.xml file. - - -To run for the Brazil test site -do the following: - -Example of running &clm; over a single-point test site in Brazil -with the default Qian atmosphere data forcing. - - -> cd scripts -> ./create_newcase -case testSPDATASET -res pt1_pt1 -compset I \ --mach bluefire -> cd testSPDATASET -# Configure to run for the test site -> set SITE=1x1_brazil -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-sitespf_pt $SITE" -> ./xmlchange -file env_conf.xml -id &CLM1PT; -val $SITE - - - - -Then configure, build and run normally. - - -Then to run for the urban Mexico City Mexico test site that also has atmosphere -forcing data, but to run it with the Qian forcing data, but over the period for -which it's own forcing data is provided do the following: - -Example of running &clm; over the single-point of Mexicocity Mexico -with the default Qian atmosphere data forcing. - - -> cd scripts -> ./create_newcase -case testSPDATASET -res pt1_pt1 -compset I \ --mach bluefire -> cd testSPDATASET -# Set a variable to the site you want to use (as it's used several times below) -> set SITE=1x1_mexicocityMEX -# Configure to run for the urban test site -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-sitespf_pt $SITE" -> ./xmlchange -file env_conf.xml -id &CLM1PT; -val $SITE -# Set &datm; prescribed aerosols to single-point dataset -# Will then use the dataset with just the point for this $SITE -> ./xmlchange -file env_conf.xml -id DATM_PRESAERO -val pt1_pt1 -# -# Set some of the settings that are particular to this site, by values contained -# in the XML database. For some sites, or for new sites this information won't be -# stored. And the queryDefaultNamelist.pl command will abort. -# -# Set &datm; start and end range (optional just to run over the same years that -# atmospheric forcing data is available for this site) -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_START -val \ -`../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist default_settings -silent -var datm_cycle_beg_year -justvalue` -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_END -val \ -`../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist default_settings -silent -var datm_cycle_end_year -justvalue` - - - - -Then configure, build and run normally. - - - -Just like &PTSMODE; above, By default it sets up to run with -USE_MPISERIAL (in the env_build.xml file) turned on, -which allows you to run the model interactively. On some machines this mode is NOT -supported and you may need to change it to FALSE before you are able to build. - - - - -See for a warning about running single-point jobs -on batch machines. - - - - -Note, that when running a pt1_pt1 resolution the number of processors -is automatically set to one. When running a single grid point you can only use a single -processor. You might also want to set the "env_conf" variable: USE_MPISERIAL to -TRUE so that you can also run interactively without having to use -mpi to start up your job. - - - -Running Supported Single-point Datasets that have their own Atmospheric Forcing - -Of the supported single-point datasets we have three that also have atmospheric forcing data -that go with them: Mexico City (Mexico), Vancouver, (Canada, British Columbia), and -urbanc_alpha (test data for an Urban inter-comparison project). Mexico city and Vancouver -also have "#ifdef" in the source code for them to work with modified urban data -parameters that are particular to these locations. They can be turned on by using -the &CLMCONFIG; &envconf; variable to set the "-sitespf_pt" option in the &clm; -&configure;. To turn on the atmospheric forcing for these datasets, you set the -&envconf; DATM_MODE variable to "CLM1PT", and then the atmospheric -forcing datasets will be used for the point picked. - - -When running with datasets that have their own atmospheric forcing you need to be careful -to run over the period that data is available. If you have at least one year of forcing -it will cycle over the available data over and over again no matter how long of a simulation -you run. However, if you have less than a years worth of data (or if the start date doesn't -start at the beginning of the year, or the end date doesn't end at the end of the year) then -you won't be able to run over anything but the data extent. In this case you will need to -carefully set the RUN_STARTDATE, START_TOD and -STOP_N/STOP_OPTION variables for your case to run over the entire time extent -of your data. For the supported data points, these values are in the XML database -and you can use the queryDefaultNamelist.pl script to query the values -and set them for your case (they are set for the three urban test cases: Mexicocity, Vancouver, and -urbanc_alpha). - - -In the example below we will show how to do this for the Vancouver, Canada point. - - -Example of running &clm; over the single-point of Vancouver Canada with -supplied atmospheric forcing data for Vancouver. - - -> cd scripts -# Create a case at the single-point resolutions -> ./create_newcase -case testSPDATASETnAtmForcing -res pt1_pt1 -compset I \ --mach bluefire -> cd testSPDATASETnAtmForcing -# Set a variable to the site you want to use (as it's used several times below) -> set SITE=1x1_vancouverCAN -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-sitespf_pt $SITE" -# Now set the CLM single-point variable to the site name -> ./xmlchange -file env_conf.xml -id &CLM1PT; -val $SITE -# Set the aerosols to use the single-point dataset for 2000 conditions -# You could also use the default global dataset, but running would be a bit slower -> ./xmlchange -file env_conf.xml -id DATM_MODE -val CLM1PT -# Set the coupling frequency to once an hour -> ./xmlchange -file env_conf.xml -id ATM_NCPL -val 24 -# Set the standard namelist options for an urban test site -> ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val stdurbpt -# Set many of the settings that are particular to this site, by values contained -# in the XML database. For some sites, or for new sites this information won't be -# stored. And the queryDefaultNamelist.pl command will abort. -# -# Set the start date -> setenv RUN_STARTDATE \ -`../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist default_settings -silent -var run_startdate -justvalue` -> setenv STARTDATE `echo $RUN_STARTDATE | sed s/-//g` -> @ START_YEAR = $STARTDATE / 10000 -> ./xmlchange -file env_conf.xml -id RUN_STARTDATE -val $RUN_STARTDATE -# Set the run length and start time of day -> ./xmlchange -file env_run.xml -id STOP_OPTION \ --val `../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist seq_timemgr_inparm -silent -var stop_option -justvalue` -> setenv STOP_N \ -`../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist seq_timemgr_inparm -silent -var stop_n -justvalue` -> ./xmlchange -file env_run.xml -id STOP_N -val $STOP_N -> ./xmlchange -file env_run.xml -id START_TOD \ --val `../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist seq_timemgr_inparm -silent -var start_tod -justvalue` -# Set &datm; start and end range... -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_START -val -`../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist default_settings -silent -var datm_cycle_beg_year -justvalue` -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_END -val -`../../models/lnd/clm/bld/queryDefaultNamelist.pl -res $SITE \ --namelist default_settings -silent -var datm_cycle_end_year -justvalue` -# Set the User namelist to set the output frequencies of the history files -# Setting the stdurbpt use-case option create three history file streams -# The frequencies and number of time-samples needs to be set -> cat << EOF > &usernlclm; -&clm_inparm - hist_mfilt = $STOP_N,$STOP_N,$STOP_N - hist_nhtfrq = -1,-1,-1 -/ -EOF -# Set align year to start year as defined above -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_ALIGN -val $START_YEAR -# Set &datm; prescribed aerosols to single-point dataset -# Will then use the dataset with just the point for this site -> ./xmlchange -file env_conf.xml -id DATM_PRESAERO -val pt1_pt1 -> ./configure -case - - - - -If you don't set the start-year and run-length carefully as shown above the -model will abort with a "dtlimit error" in the atmosphere model (see bug 1110 in -the KnownLimitations file for documentation on this). Since, the forcing data for -this site (and the MexicoCity site) is less than a year, the model won't be able to -run for a full year. The 1x1_urbanc_alpha site has data for more -than a full year, but neither year is complete hence, it has the same problem (see the -problem for this site above). - - - - -Just like &PTSMODE; above, By default it sets up to run with -USE_MPISERIAL (in the env_build.xml file) turned on, -which allows you to run the model interactively. On some machines this mode is NOT -supported and you may need to change it to FALSE before you are able to build. - - - - -See for a warning about running single-point jobs -on batch machines. - - - - -Note, that when running a pt1_pt1 resolution the number of processors -is automatically set to one. When running a single grid point you can only use a single -processor. You might also want to set the "env_conf" variable: USE_MPISERIAL to -TRUE so that you can also run interactively without having to use -mpi to start up your job. - - - - - - -Creating your own single-point/regional surface datasets - -The file: -Quickstart.userdatasets in the -models/lnd/clm/doc directory gives guidelines on how to create and run -with your own single-point or regional datasets. Below we reprint the above guide. - -&quickstart_userdata; - - - - -Using getregional_datasets.pl to get a complete suite of single-point/regional -surface datasets from global ones - -Use the regional extraction script to get regional datasets from the global ones -The getregional_datasets.pl script to extract out regional datasets of interest. -Note, the script works on all files other than the "finidat" file as it's a 1D vector file. -The script will extract out a block of gridpoints from all the input global datasets, -and create the full suite of input datasets to run over that block. The input datasets -will be named according to the input "id" you give them and the id can then be used -as input to &CLMUSRDAT; to create a case that uses it. See -the section on &clm; Script Configuration Items for -more information on setting &CLMUSRDAT; (in ). The list of files extracted by -their name used in the namelists are: -fatmgrid, fatmlndfrc, -fsurdat, flanduse_timeseries, -stream_fldfilename_ndep, and the &datm; files -domainfile, and faerdep. -For more information on these files see the Table on required files. - - -The alternatives to using this script are to use &PTSMODE;, -discussed earlier, to use &ptclm; discussed in the next chapter, or creating the files -individually using the different file creation tools (given in the -Tools Chapter). Creating -all the files individually takes quite a bit of effort and time. &PTSMODE; -has some limitations as discussed earlier, but also as it uses global files, is -a bit slower when running simulations than using files that just have the set -of points you want to run over. Another advantage is that once you've created the -files using this script you can customize them if you have data on this specific -location that you can replace with what's already in these files. - - -The script requires the use of both "Perl" and "NCL". See the NCL Script section in the Tools Chapter -on getting and using NCL and NCL scripts. The main script to use is a &perl; script -which will then in turn call the NCL script that actually creates the output files. -The ncl script gets it's settings from environment variables set by the perl script. -To get help with the script use "-help" as follows: - -> cd models/lnd/clm/tools/ncl_scripts -> ./getregional_datasets.pl -help - -The output of the above is: - -&getreg_datasets; - - - -The required options are: -id, --ne, and -se, for the output identifier -name to use in the filenames, latitude and longitude of the Northeast corner, and -latitude and longitude of the SouthEast corner (in degrees). Options that specify -which files will be used are: -mask, -res, --rcp, -sim_year, and -sim_yr_rng -for the land-mask to use, global resolution name, representative concentration pathway -for future scenarios, simulation year, and simulation year range. The location of the -input and output files will be determined by the option -mycsmdata -(can also be set by using the environment variable $CSMDATA). If -you are running on a machine like at &ncar; where you do NOT have write permission -to the CESM inputdata files, you should use the scripts/link_dirtree -script to create soft-links of the original files to a location that you can write -to. This way you can use both your new files you created as well as the original -files and use them from the same location. - - -The remaining options to the script are -debug, -and -verbose. -debug is used to show what -would happen if the script was run, without creating the actual files. --verbose adds extra log output while creating the files so you -can more easily see what the script is doing. - - -For example, Run the extraction for data from 52-73 North latitude, 190-220 longitude -that creates 13x12 gridcell region from the f19 (1.9x2.5) global resolution over Alaska. - -Example of running <command>getregional_datasets.pl</command> to get -datasets for a specific region over Alaska - -> cd scripts -# First make sure you have a inputdata location that you can write to -# You only need to do this step once, so you won't need to do this in the future -> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data -> ./link_dirtree $CSMDATA $MYCSMDATA -> cd ../models/lnd/clm/tools/ncl_scripts -> ./getregional_datasets.pl -sw 52,190 -ne 73,220 -id 13x12pt_f19_alaskaUSA -mycsmdata $MYCSMDATA - - -Repeat this process if you need files for multiple sim_year, resolutions, land-masks, -and sim_year_range values. - - - -See for a warning about running single-point jobs -on batch machines. - - - - -See for notes about managing your data -when using link_dirtree. - - - -Now to run a simulation with the datasets created above, you create a single-point -case, and set &CLMUSRDAT; to the identifier used above. Note that in the example below -we set the number of processors to use to one (-pecount 1). For a single point, you -should only use a single processor, but for a regional grid, such as the example below -you could use up to the number of grid points (12x13=156 processors. - - -Example of using &CLMUSRDAT; to run a simulation using user datasets for a -specific region over Alaska - -> cd scripts -# Create the case and set it to only use one processor -> ./create_newcase -case my_userdataset_test -res pt1_pt1 -compset I1850 \ --mach bluefire -> cd my_userdataset_test/ -> ./xmlchange -file env_run.xml -id DIN_LOC_ROOT_CSMDATA -val $MYCSMDATA -> ./xmlchange -file env_conf.xml -id &CLMUSRDAT; -val 13x12pt_f19_alaskaUSA -> ./xmlchange -file env_conf.xml -id &CLMBLDNML; -val '-mask gx1v6' -> ./xmlchange -file env_conf.xml -id &CLM1PT; -val 13x12pt_f19_alaskaUSA -> ./configure -case - - - - - - - -Running with your own atmosphere forcing - -Here we want to run with our own customized datasets for &clm; as well as -running with our own supplied atmosphere forcing datasets. Thus we effectively -combine the information from with -. First we need to follow -the procedures in to come up with &clm; -datasets that are customized for our point or region in question. This includes -running link_dirtree to create a directory location where you -can add your own files to it. Next, set -DATM_MODE to "CLM1PT" and &CLM1PT; and &CLMUSRDAT; to the -id of the data you created. To see a list of what the filenames need to be -see the section on setting &CLMUSRDAT;. - - -Next we need to setup the atmosphere forcing data in &netcdf; format that can be -read by &datm;. There is a list of eight variables that are expected to be on the input -files with the names and units on the following table (in the table TDEW and SHUM -are optional fields that can be used in place of RH). In the table we also list -which of the fields are required and if not required what the code will do to -replace them. If the names of the fields are different or the list is changed -from the standard list of eight fields: FLDS, FSDS, PRECTmms, -PSRF, RH, TBOT, WIND, and ZBOT, the resulting streams file will need to be modified -to take this into account (see an example streams file for this in below). - -Atmosphere Forcing Fields - - - - Short-name - Description - Units - Required? - If NOT required how replaced - - - - - FLDSincident longwave -(FLDS)W/m2No -calculates based on Temperature, Pressure and Humidity - - - FSDSincident solar -(FSDS)W/m2Yes- - - - FSDSdifincident solar (FSDS) -diffuseW/m2Nobased on FSDS - - - FSDSdirincident solar (FSDS) -directW/m2Nobased on FSDS - - - PRECTmmsprecipitation -(PRECTmms)mm/sYes- - - - PSRFpressure at the lowest atm level -(PSRF)PaNoassumes standard-pressure - - - RHrelative humidity at the lowest atm level -(RH)%Nocan be replaced with SHUM or TDEW - - - SHUMspecific humidity at the lowest atm level -kg/kgOptional in place of RHcan be replaced with RH or TDEW - - - TBOTtemperature at the lowest atm level -(TBOT)K (or can be C)Yes- - - - TDEWdew point temperature -K (or can be C)Optional in place of RHcan be replaced with RH or SHUM - - - WINDwind at the lowest atm level -(WIND)m/sYes- - - - ZBOTobservational heightmNo -assumes 30 meters - - - -
-All of the variables should be dimensioned: time, lat, lon, with time being the unlimited -dimension. The coordinate variable "time" is also required with CF-compliant units in -days, hours, minutes, or seconds. It can also have a calendar attribute that can -be "noleap" or "gregorian". Normally the files will be placed in the: -$MYCSMDATA/atm/datm7/CLM1PT_data/$MYUSRDAT directory with separate files per -month called YYYY-MM.nc where YYYY-MM corresponds to the four -digit year and two digit month with a dash in-between. You also need a domain file that -gives the coordinate information for the data that should be placed in: -$MYCSMDATA/atm/datm7/domain.lnd.$MYUSRDAT_USGS.nc. - -Example of setting up a case with your own atmosphere forcing - -> cd scripts -# First make sure you have a inputdata location that you can write to -# You only need to do this step once, so you won't need to do this in the future -> setenv MYCSMDATA $HOME/inputdata # Set env var for the directory for input data -> ./link_dirtree $CSMDATA $MYCSMDATA -# Next create and move all your datasets into $MYCSMDATA with id $MYUSRDAT -# See above for naming conventions - -# Now create a single-point case -> ./create_newcase -case my_atmforc_test -res pt1_pt1 -compset I1850 \ --mach bluefire -> cd my_atmforc_test -# Set the data root to your inputdata directory, and set &CLM1PT; and &CLMUSRDAT; -# to the user id you created for your datasets above -> ./xmlchange -file env_run.xml -id DIN_LOC_ROOT_CSMDATA -val $MYCSMDATA -> ./xmlchange -file env_conf.xml -id &CLM1PT; -val $MYUSRDAT -> ./xmlchange -file env_conf.xml -id &CLMUSRDAT; -val $MYUSRDAT -# Set the land-mask to USGS, so both clm and &datm; can find files -> ./xmlchange -file env_conf.xml -id &CLMBLDNML; -val '-mask USGS' -# Then set DATM_MODE to single-point mode so &datm; will use your forcing datasets -# Put your forcing datasets into $MYCSMDATA/atm/datm7/CLM1PT_data/$MYUSRDAT -> ./xmlchange -file env_conf.xml -id DATM_MODE -val CLM1PT -> ./configure -case -# If the list of fields, or filenames, filepaths, or fieldnames are different -# you'll need to edit the &datm; namelist streams file to make it consistent -> $EDITOR Buildconf/datm.buildnml.csh - - - - - -See for a warning about running single-point jobs -on batch machines. - - - - -See for notes about managing your data -when using link_dirtree. - - - - -Now, we'll show an example of what the &datm; streams file might look like for a case -with your own forcing data with 3-hourly forcing. In this example, we'll leave off the -fields: ZBOT, and FLDS so they'll be calculated as given in the - table above. We'll also include: -FSDSdif and FSDSdir which aren't required, and we'll use TDEW in place of RH. In this -example the datafiles are in &netcdf; format and contain the fields: TA, Tdew, WS, -PREC, Rg, Rgdir, Rgdif, and PRESS which are translated into the &datm; internal names -in this streams file. There is also a domain file that has the position information -for this location. The normal assumption for CLM1PT mode in the &datm; is that data is -hourly or half-hourly and as such is often enough that using the data on the nearest -time-stamp is reasonable and as such the data is in a single streams file (see - for more information on -the default settings for &datm; and how to change them. If the data is less often three to six hours -- see -below, where you will need to modify the time-interpolation method as well as the -time stamp offsets. In the example below we also have to divide the single -stream file into three files to manage the time-stamps and time interpolation -algorithm for the different types of data differently. - -Example of &datm; streams files with your own forcing for 3-hourly data - -Precipitation streams file -(clm1PT.1x1pt_lapazMEX.precip.stream.txt file) . - - -<streamstemplate> -<stream> - <dataSource> - CLMNCEP - </dataSource> - <domainInfo> - <variableNames> - time time - xc lon - yc lat - area area - mask mask - </variableNames> - <filePath> - $DIN_LOC_ROOT/atm/datm7/domain.clm - </filePath> - <fileNames> - domain.lnd.1x1pt_lapazMEX_navy.nc - </fileNames> - </domainInfo> - <fieldInfo> - <variableNames> - PRECTmms PREC - </variableNames> - <offset> - -5400 - </offset> - <filePath> - $DIN_LOC_ROOT/atm/datm7/CLM1PT_data/1x1pt_lapazMEX - </filePath> - <fileNames> - 2004-01.nc - 2004-02.nc - 2004-03.nc -. -. -. - 2009-12.nc - </fileNames> - </fieldInfo> -</stream> -</streamstemplate> - - -Solar streams file (clm1PT.1x1pt_lapazMEX.solar.stream.txt file). - - -<streamstemplate> -<stream> - <dataSource> - CLMNCEP - </dataSource> - <domainInfo> - <variableNames> - time time - xc lon - yc lat - area area - mask mask - </variableNames> - <filePath> - $DIN_LOC_ROOT/atm/datm7/domain.clm - </filePath> - <fileNames> - domain.lnd.1x1pt_lapazMEX_navy.nc - </fileNames> - </domainInfo> - <fieldInfo> - <variableNames> - FSDS Rg - FSDSdir Rgdir - FSDSdif Rgdif - </variableNames> - <offset> - -10800 - </offset> - <filePath> - $DIN_LOC_ROOT/atm/datm7/CLM1PT_data/1x1pt_lapazMEX - </filePath> - <fileNames> - 2004-01.nc - 2004-02.nc - 2004-03.nc -. -. -. - 2009-12.nc - </fileNames> - </fieldInfo> -</stream> -</streamstemplate> - - -Other fields streams file. -(clm1PT.1x1pt_lapazMEX.other.stream.txt file) . - - -<streamstemplate> -<stream> - <dataSource> - CLMNCEP - </dataSource> - <domainInfo> - <variableNames> - time time - xc lon - yc lat - area area - mask mask - </variableNames> - <filePath> - $DIN_LOC_ROOT/atm/datm7/domain.clm - </filePath> - <fileNames> - domain.lnd.1x1pt_lapazMEX_navy.nc - </fileNames> - </domainInfo> - <fieldInfo> - <variableNames> - TBOT TA - TDEW Tdew - WIND WS - PSRF PRESS - </variableNames> - <offset> - -5400 - </offset> - <filePath> - $DIN_LOC_ROOT/atm/datm7/CLM1PT_data/1x1pt_lapazMEX - </filePath> - <fileNames> - 2004-01.nc - 2004-02.nc - 2004-03.nc -. -. -. - 2009-12.nc - </fileNames> - </fieldInfo> -</stream> -</streamstemplate> - - -Example streams namelist for the above streams files: - - - &shr_strdata_nml - dataMode = 'CLMNCEP' - domainFile = '$DOMAINFILE' - streams = 'clm1PT.1x1pt_lapazMEX.solar.stream.txt 1 2004 2009 ', - 'clm1PT.1x1pt_lapazMEX.precip.stream.txt 1 2004 2009 ', - 'clm1PT.1x1pt_lapazMEX.other.stream.txt 1 2004 2009 ', - 'presaero.stream.txt 1 2000 2000' - vectors = 'null','null','null','null' - mapmask = 'nomask','nomask','nomask','nomask' - mapalgo = 'nn','nn','nn','nn' - tintalgo = 'coszen','nearest','linear','linear' - taxmode = 'cycle','cycle','cycle','cycle' - / - - - - - -The example above shows the resolved namelist and streams file after &configure; -has been run. In order to save this configuration for future use, you would need -to edit the &datm; template adding new DATM_MODE see - for more information on how to do this. - - - - -We've outlined and given a few examples of using your own atmosphere -forcing. In the next chapter we go into the details of using &ptclm;. - - - - - - diff --git a/doc/UsersGuide/special_cases.xml b/doc/UsersGuide/special_cases.xml deleted file mode 100644 index ac5c7fef3b..0000000000 --- a/doc/UsersGuide/special_cases.xml +++ /dev/null @@ -1,916 +0,0 @@ - - -How to run some special cases - -In this chapter we describe how to run some special cases that take more than one step -to do. The straightforward cases have compsets and/or build-namelist use-cases setup for -them or require simple editing of a single-case. All of the cases here require you -to do at least two simulations with different configurations, or require more complex -editing of the case (changing the streams files). - - -The nine cases we will describe are: - - - -Running with the prognostic crop model on - - - - -Running with the irrigation model on - - - - -Spinning up the Satellite Phenology Model (&clmsp; spinup) - - - - -Spinning up the biogeochemistry Carbon-Nitrogen Model (CN spinup) - - - - -Spinning up the Carbon-Nitrogen Dynamic Global Vegetation Model (CNDV spinup) - - - - -Running with MOAR data as atmospheric forcing to spinup the model - - - - -Running with your own previous simulation as atmospheric forcing to spinup the model - - - - -Doing perturbation error growth tests - - - - -Running stand-alone &clm; with transient historical &CO2; -concentration - - - - - - -The cases in this chapter are more sophisticated and require more technical knowledge -and skill than cases in previous chapters. The user should be very familiar with doing -simple cases before moving onto the cases described here. - - - -Running with the prognostic crop model on - - -In &clmcesm103; a prognostic crop model was added to &clm4;. The prognostic crop -model is setup to work with CN for present day conditions and we have surface -and initial condition datasets at f19 resolution. In order to use the initial condition -file, we need to set the RUN_TYPE to startup rather -than hybrid since the compset for f19 sets up to use an initial -condition file without crop active. To activate the crop model we simply add "-crop on" -to &CLMCONFIG;. - -Example Crop Simulation - -> cd scripts -> ./create_newcase -case CROP -res f19_g16 -compset ICN -mach bluefire -> cd CROP -# Append "-crop on" to &CLMCONFIG; in env_conf.xml (you could also use an editor) -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-crop on" -append -# Change to startup type so uses spunup initial conditions file for crop if it exists -# By default the model will do a hybrid startup with an initial condition file -# incompatible with the crop surface dataset. -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup -> ./configure -case -# Now build and run normally -> ./CROP.bluefire.build -> ./CROP.bluefire.submit - - - - - - -Running with the irrigation model on - - -In &clmcesm103; an irrigation model for generic crop was added to &clm4;. Currently, -irrigation and crop can NOT be used together see bug number 1326 in the -&KnownBugs; file. -The irrigation model is tuned to work only with &clmsp; see the caution below for -for more information on this. To turn on -irrigation we simply add "-irrig on" to &CLMBLDNML;. Just as in the crop example we -also change RUN_TYPE to startup so that we don't use -an initial condition file that is incompatible with irrigation. - -Example Irrigation Simulation - -> cd scripts -# Note here we do a &clmsp; simulation as that is what has been validated -> ./create_newcase -case IRRIG -res f19_g16 -compset I -mach bluefire -> cd IRRIG -# Append "-irrig on" to &CLMBLDNML; in env_conf.xml (you could also use an editor) -> ./xmlchange -file env_conf.xml -id &CLMBLDNML; -val "-irrig" -append -# Change to startup type so uses spunup initial conditions file for irrigation if it exists -# By default the model will do a hybrid startup with an initial condition file -# incompatible with the irrigation surface dataset. -> xmlchange -file env_conf.xml -id RUN_TYPE -val startup -> ./configure -case -# Now build and run normally -> ./IRRIG.bluefire.build -> ./IRRIG.bluefire.submit - - - - -We have only run the irrigation model with &clmsp; (i.e. without the CN model). We -recommend that if you want to run the irrigation model with CN, that you do a spinup -as outlined in the examples below. But, more than that you may need to make -the adjustments we discuss in . - - - - - - -Spinning up the Satellite Phenology Model (&clmsp; spinup) - - -To spin-up the &clmsp; model you merely need to run &clmsp; for 50 simulation -years starting from arbitrary initial conditions. You then use the final -restart file for initial conditions in other simulations. -Because, this is a straight forward operation we will NOT give -the details on how to do that here, but leave it as an exercise for the reader. -See the as an example of doing this -as the last step for &clmcn;. - - - - -Spinning up the biogeochemistry Carbon-Nitrogen Model (CN spinup) - -To get the &clmcn; model to a steady state, you first run it from arbitrary initial conditions -using the "accelerated decomposition spinup" (-ad_spinup in configure) mode for 600 simulation years. After -this you branch from this mode in the "exit spinup" (-exit_spinup in configure), run -for a simulation year, and then save a restart from that and use it as initial conditions -for further spinup of CN (at least 50 simulation years). - - -Spinup of &clmcn; - -AD_SPINUP - -For the first step of running 600 years in "-ad_spinup" mode, you will setup -a case, and then edit the values in env_conf.xml and -env_run.xml so that the right configuration is turned on and -the simulation is setup to run for the required length of simulation time. -So do the following: - -Example AD_SPINUP Simulation - -> cd scripts -> ./create_newcase -case CN_spinup -res f19_g16 -compset ICN -mach bluefire -> cd CN_spinup -# Append "-ad_spinup on" to &CLMCONFIG; in env_conf.xml -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-ad_spinup on" -append -# The following sets &CLMFORCECOLD; to "on" in env_conf.xml (you could also use an editor) -> ./xmlchange -file env_conf.xml -id &CLMFORCECOLD; -val on -# Make the output history files only annual, by adding the following to the &usernlclm; namelist -> echo '&clm_inparm hist_nhtfrq = -8760 /' > &usernlclm; -# Now configure -> ./configure -case -> ./xmlchange -file env_run.xml -id STOP_DATE -val 6010101 -# Now build -> ./CN_spinup.bluefire.build -# The following sets RESUBMIT to 30 times in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id RESUBMIT -val 30 -# The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears -# The following sets STOP_N to 20 years in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_N -val 20 -# The following sets STOP_DATE to Jan/1 of year 601 in env_run.xml (you could also use an editor) -# Now run normally -> ./CN_spinup.bluefire.submit - - -Afterwards save the last restart file from this simulation to use in the next step. - - - - -EXIT_SPINIP - - -Example EXIT_SPINUP Simulation - -> cd scripts -> ./create_newcase -case CN_exitspinup -res f19_g16 -compset ICN -mach bluefire -> cd CN_exitspinup -# Append "-exit_spinup on" to &CLMCONFIG; in env_conf.xml -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-exit_spinup on" -append -# Change run type to branch and branch from the last year of the last simulation -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val branch -> ./xmlchange -file env_conf.xml -id RUN_REFCASE -val CN_spinup -> ./xmlchange -file env_conf.xml -id RUN_REFDATE -val 0601-01-01 -> ./xmlchange -file env_conf.xml -id GET_REFCASE -val FALSE -> ./configure -case -# Go ahead and build, so that the run directory is created -> ./CN_exitspinup.bluefire.build -# Now, Copy the last restart files from the earlier case into your run directory -> cp /ptmp/$LOGIN/archive/CN_spinup/rest/CN_spinup.*.r*.0601-01-01-00000* /ptmp/$LOGIN/CN_exitspinup -# And copy the rpointer files for datm and drv from the earlier case -> cp /ptmp/$LOGIN/archive/CN_spinup/rest/rpointer.atm /ptmp/$LOGIN/CN_exitspinup -> cp /ptmp/$LOGIN/archive/CN_spinup/rest/rpointer.drv /ptmp/$LOGIN/CN_exitspinup -# The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears -> ./xmlchange -file env_run.xml -id STOP_N -val 1 -# Now run normally -> ./CN_exitspinup.bluefire.submit - - - - - - -Final spinup - -Next save the last restart file from this step and use it as the "finidat" file to -use for one more spinup for at least 50 years in normal mode. -So do the following: - -Example Final CN Spinup Simulation - -> cd scripts -> ./create_newcase -case CN_finalspinup -res f19_g16 -compset ICN -mach bluefire -> cd CN_finalspinup -# The following sets &CLMFORCECOLD; to "on" in env_conf.xml (you could also use an editor) -> ./xmlchange -file env_conf.xml -id &CLMFORCECOLD; -val on -# Now, Copy the last &clm; restart file from the earlier case into your run directory -> cp /ptmp/$LOGIN/archive/CN_exitspinup/rest/CN_exitspinup.clm*.r*.0602-01-01-00000.nc \ -/ptmp/$LOGIN/CN_finalspinup -# And copy the rpointer files for datm and drv from the earlier case -> cp /ptmp/$LOGIN/archive/CN_exitspinup/rest/rpointer.atm /ptmp/$LOGIN/CN_finalspinup -> cp /ptmp/$LOGIN/archive/CN_exitspinup/rest/rpointer.drv /ptmp/$LOGIN/CN_finalspinup -# Set the finidat file to the last restart file saved in previous step -> echo '&clm_inparm finidat = "CN_exitspinup.clm2.r.0602-01-01-00000.nc" /' > &usernlclm; -# Now configure -> ./configure -case -> $EDITOR Buildconf/clm.buildnml.csh -> Now build -> .CN_finalspinup.bluefire.build -# The following sets RESUBMIT to 5 times in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id RESUBMIT -val 5 -# The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears -# The following sets STOP_N to 10 years in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_N -val 10 -> Now run as normal -> .CN_finalspinup.bluefire.submit - - - - -To assess if the model is spunup plot trends of CN variables of interest. If you see -a trend, you may need to run the simulation longer. -Finally save the restart file from the end of this simulation to use as an "finidat" file for future -simulations. - - - - - - -Spinning up the Carbon-Nitrogen Dynamic Global Vegetation Model (CNDV spinup) - -To spinup the &clm; CNDV model -- you first follow the procedures above to spinup the CN model. -Then you take the CN initial state file you created for the spinup with just CN, and -run CNDV for 200 more years. -We've provided such spunup files for two resolutions (f09 and f19) and two time-periods -(1850 and 2000), so in this example we will use the files provided to start from. -We've also provided a spinup file at f19 resolution for CNDV, hence the following is -NOT required when running at f19. -If you were to start from your own &clmcn; spunup files -- the procedure would require -some modification. -There are no compsets using CNDV, so in -env_conf.xml change CLM_CONFIG_OPTS to --bgc cndv. - -Example CNDV Spinup Simulation - -> cd scripts -> ./create_newcase -case CNDV_spinup -res f09_g16 -compset ICN -mach bluefire -> cd CNDV_spinup -# Set run type to startup and do a cold start -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup -# The following sets CLM_CONFIG_OPTS to "-bgc cndv" in env_conf.xml (you could also use an editor) -> ./xmlchange -file env_conf.xml -id CLM_CONFIG_OPTS -val "-bgc cndv" -# Make the default primary history file annual and add an annual 1D vector auxiliary file -# By putting the following in a &usernlclm; file. -> cat << EOF > &usernlclm; -&clm_inparm - hist_nhtfrq = -8760, -8760 - hist_mfilt = 1, 1 - hist_fincl2 = 'TLAI', 'TSAI', 'HTOP', 'HBOT', 'NPP' - hist_dov2xy = .true., .false. -/ -> ./configure -case -# NOTE: If you were using your own CN spinup files you would edit the namelist to use it -# $EDITOR Buildconf/clm.buildnml.csh -# -# Now build and run as normal -> ./CNDV_spinup.bluefire.build -# The following sets RESUBMIT to 10 times in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id RESUBMIT -val 10 -# The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears -# The following sets STOP_N to 20 years in env_run.xml (you could also use an editor) -> ./xmlchange -file env_run.xml -id STOP_N -val 20 -# Make sure you turn archiving on, so you save your files to long term archival -> ./xmlchange -file env_run.xml -id DOUT_L_MS -val TRUE -> ./CNDV_spinup.bluefire.submit - - - - - -There is a build bug with &clmcesm103; see bug 1370 in the &KnownBugs; on -how to address this. - - - - - -In a data analysis tool you should examine the auxiliary file and examine the -pfts1d_wtgcell to see where and what types of vegetation have -been established. See the caution in for more -information on visualizing and analyzing 1D vector fields. - - - -CNDV also writes out two vector fields to "hv" auxiliary files, on an annual basis by -default. - - - - -We've provided a spinup file for CNDV at f19 resolution, you could also use -interpinic to interpolate this file to other resolutions. - - - - - -Running with MOAR data as atmospheric forcing to spinup the model - -Because it takes so long to spinup the CN model (as we just saw previously), if you -are doing fully coupled simulations with active atmosphere and ocean, you will want -to do the spinup portion of this "offline". So instead of doing expensive fully -coupled simulations for the spinup duration, you run &clm; in a very cheap "I" -compset using atmospheric forcing from a shorter fully coupled simulation -(or a simulation run previously by someone else). - - -In this example we will use the I1850SPINUPCN compset to setup -&clm; to run with atmospheric forcing from a previous fully coupled simulation with -data that is already stored on disk on bluefire. There are several simulations that -have high frequency data for which we can do this. You can also do this on a machine -other than bluefire, but would need to download the data from the Earth System Grid and -change the datapath similar to . -This compset is designed for constant -1850 conditions, but unfortunately (because of bug 1354 see the &KnownBugs; file) by -default it points to a transient simulation instead of an 1850 simulation. Here we -point to an 1850 simulation and setup the forcing years to run over. - -Example Simulation with MOAR Data on bluefire - -> cd scripts -> ./create_newcase -case MOARforce1850 -res f19_g16 -compset I1850SPINUPCN -mach bluefire -> cd MOARforce1850 -# The following sets the casename to point to for atm forcing (you could also use an editor) -> ./xmlchange -file env_conf.xml -id DATM_CPL_CASE -val b40.1850.track1.1deg.006a -# The following sets the align year and years to run over for atm forcing -# (you could also use an editor) -> ./xmlchange -file env_conf.xml -id DATM_CPL_YR_ALIGN -val 1 -> ./xmlchange -file env_conf.xml -id DATM_CPL_YR_START -val 960 -> ./xmlchange -file env_conf.xml -id DATM_CPL_YR_END -val 1030 -> ./configure -case -# Now build and run as normal -> ./MOARforce1850.bluefire.build -> ./MOARforce1850.bluefire.submit - - - - -Because of bug 1339 (see the &KnownBugs; file on this) -you can't run with 83 or more years of forcing. If you do need to run with more years of -forcing, you'll need to address the issue as outlined in the &KnownBugs; file. - - - - - - -Running with your own previous simulation as atmospheric forcing to spinup the model - -Another way that you might want to spinup the model is to run your own simulation -for a relatively short period (either a B, E, or F compset) and then use it as forcing -for your "I" case later. By only running 20 to 50 years for the fully coupled case, -you'll save a substantial amount of computer time rather than running the entire spinup -period with a fully coupled model. - - -The first thing we need to do is to run a fully coupled case and save the atmospheric -coupling fields on a three hourly basis. In this example, we will run on bluefire -and archive the data to a local disk that we can then use in the next simulation. - -Example Fully Coupled Simulation to Create Data to Force Next Example Simulation - -> cd scripts -> ./create_newcase -case myBCN1850 -res f09_g16 -compset B1850CN -mach bluefire -> cd myBCN1850 -> ./configure -case -# Set histaux_a2x3hr to .true. in cpl.buildnml.csh so output from the atmosphere model -# will be saved 3 hourly -$EDITOR BuildConf/cpl.buildnml.csh -# Now build -> ./myBCN1850.bluefire.build -# The following sets the archival disk space (you could also use an editor) -> ./xmlchange -file env_run.xml -id DOUT_S_ROOT -val '/glade/home/$USER/$CASE' -# Make sure files are archived to disk, but NOT to long term storage -# (you could also use an editor) -> ./xmlchange -file env_run.xml -id DOUT_S -val TRUE -> ./xmlchange -file env_run.xml -id DOUT_L_MS -val FALSE -# Set the run length to run a total of 20 years (you could also use an editor) -> ./xmlchange -file env_run.xml -id RESUBMIT -val 9 -> ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears -> ./xmlchange -file env_run.xml -id STOP_N -val 2 -# Now run as normal -> ./myBCN1850.bluefire.submit - - - - -Now we run an I compset forced with the data from the previous simulation using -the &CPLHIST; option to DATM_MODE. See - for more information on the -&datm; settings for &CPLHIST; mode. - -Example Simulation Forced with Data from the Previous Simulation - -> cd scripts -> ./create_newcase -case frcwmyBCN1850 -res f09_g16 -compset I1850SPINUPCN -mach bluefire -> cd frcWmyBCN1850 -# The following sets the casename to point to for atm forcing (you could also use an editor) -> ./xmlchange -file env_conf.xml -id DATM_CPL_CASE -val "myBCN1850" -# The following sets the align year and years to run over for atm forcing -# (you could also use an editor) -> ./xmlchange -file env_conf.xml -id DATM_CPL_YR_ALIGN -val "1" -> ./xmlchange -file env_conf.xml -id DATM_CPL_YR_START -val "1" -> ./xmlchange -file env_conf.xml -id DATM_CPL_YR_END -val "20" -# Set the datapath in the template to the archival path from the case above -> sed -E 's#set datapath = ".+"#set datapath = "/glade/home/$USER/%c/cpl/hist"#' \ - Tools/Templates/datm.cpl7.template > new.datm.cpl7.template -> mv -f new.datm.cpl7.template Tools/Templates/datm.cpl7.template -> chmod +x Tools/Templates/datm.cpl7.template -> ./configure -case -# Now build and run as normal -> ./frcwmyBCN1850.bluefire.build -> ./frcwmyBCN1850.bluefire.submit - - - - -In order to accomplish this we needed to edit the &datm; template file. See - for more information on doing this. -If your input case was at a resolution besides f09 you would have to edit -the &datm; template file even further to use a domain file at the input resolution. - - - - - - -Doing perturbation error growth tests - -Doing perturbation error growth tests is a way to validate a port of -the model to a new machine or to verify that changes are only roundoff. -The steps are the same in either case, but in the discussion below I will -assume you are doing a port validation to a new machine (but in parentheses -I will put a reminder that it could also be for code-mods). -The basic idea is to run a case on the trusted machine (trusted code) and -another with initial conditions perturbed by roundoff and compare the results of -the two. The difference between these two simulations (the error) will grow over time -and describe a curve that we compare with the error growth on the new machine (code -changes). The error growth on the new machine is the difference between the non-perturbed -state on the trusted machine and the non-perturbed state on the new machine (code -changes). If the new machine (code changes) are well-behaved -the plot of this error growth compared to the error growth curve on the trusted machine -should be similar. If the -changes are NOT well-behaved the changes from the new machine (code changes) will be -larger than the perturbation changes. In summary the simulations and steps that need to be performed are: - - -Run a simulation with the trusted code on the trusted machine. -(optionally you can use a dataset from inputdata repository). - - - -Run a simulation with the trusted code on the trusted machine with initial conditions -perturbed by roundoff (using a namelist item to do so). -(this is optional is you are using inputdata repository datasets) - - - -Run a simulation with the new code on the non-trusted machine (code changes). - - -Do a plot of the RMS difference of history variables between simulation 1 and simulation 2. - - -Do a plot of the RMS difference of history variables between simulation 1 and simulation 3. - - -Compare the two plots in steps 4 and 5. - - -If the plots compare well the new machine (code changes) is running as well as the trusted machine. - - -If the plots do NOTcompare well the new machine is -NOTrunning as well as the trusted machine. Typically the -recommendation here is to lower the optimization level on the new machine and try -again (or in the case of code changes, modify or simplify the code changes to get -something that should be closer). - -The history variables we have used to do this is either 'TSOI', and/or 'TSA'. 'TSOI' are -the 3D snow and soil temperatures for vegetated land-units. If there is a change in -soil physics it should show up in this field (and it should show up even for something -that is at a pretty deep soil depth). However, as 'TSOI' is only for vegetated -land-units, changes in lake or urban land-units -- will NOT show up. 'TSA' by contrast is -the 2m surface temperature across all land-units, so changes in urban or lake land-units -will show up. However, changes in deep soil physics will only show up as it propagates -to the surface. So one field may show something that the other doesn't. In the examples, -we use 'TSOI', but 'TSA' can be used as well. And in most cases you should check both. - - - -Now we will give a detailed description of the procedure with examples and the -exact steps to perform. - - -Using Perturbation Error Growth Analysis to Verify a Port to a New Machine - -Running non-perturbed on trusted machine - -The first step is to run a non-perturbed case on the trusted machine. You need to run -all of the steps with the same compset and same resolution. For these examples we will -use 2-degree resolution with the ICN compset for 2000 conditions. You need to run for -three days with a cold-start. - - - -As we describe below, This is optional if you will be using datasets from the -inputdata repository to take place of this step. - - - - -Example non-perturbed error growth simulation - -> cd scripts -> ./create_newcase -case trustedMachinePergro0 -compset ICN -res f19_g16 \ --mach bluefire -> cd trustedMachinePergro0 -# Set the non-perturbed PERGRO use-case -> ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val pergro0_pd -# Set coldstart on so arbitrary initial conditions will be used -> ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup -# Set PERGRO on in the configure -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-pergro on" -append -# Now configure and build -> ./configure -case -> ./trustedMachinePergro0.bluefire.build -# Set it to run for three days and turn archiving off -> ./xmlchange -file env_run.xml -id STOP_N -val 3 -> ./xmlchange -file env_run.xml -id DOUT_S -val FALSE -# Run the case and then you will save the history file output for later use -> ./trustedMachinePergro0.bluefire.submit - - - - - -If you aren't able to do this step, as you don't have access to a trusted machine, you -can use datasets that are available from the svn inputdata repository to take place of -running it yourself. The disadvantage is that this is only done for certain model -versions and for exactly the configuration/namelist given here. You won't be able to -test it for your own custom code or configurations. - - - - -Running perturbed on the trusted machine - -The next step is to run a perturbed case on the trusted machine. - -Example perturbed error growth simulation - -> cd scripts -> ./create_newcase -case trustedMachinePergroRnd -compset ICN -res f19_g16 \ --mach bluefire -> cd trustedMachinePergroRnd -# Set the perturbed PERGRO use-case -> ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val pergro_pd -# Set coldstart on so arbitrary initial conditions will be used -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup -> ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on -# Set PERGRO on in the configure -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-pergro on" -append -# Now configure and build -> ./configure -case -> ./trustedMachinePergroRnd.bluefire.build -# Set it to run for three days and turn archiving off -> ./xmlchange -file env_run.xml -id STOP_N -val 3 -> ./xmlchange -file env_run.xml -id DOUT_S -val FALSE -# Run the case and then you will save the history file output for later use -> ./trustedMachinePergroRnd.bluefire.submit - - - - - -If you aren't able to do this step, as you don't have access to a trusted machine, you -can use datasets that are available from the svn inputdata repository to take place of -running it yourself. The disadvantage is that this is only done for certain model -versions and for exactly the configuration/namelist given here. You won't be able to -test it for your own custom code or configurations. - - - - -Running non-perturbed on the new machine - -The next step is to run a non-perturbed case on the new machine. Here -we will demonstrate using the machine intrepid. For the previous two steps -you have the option of using datasets provided in the subversion inputdata -repository to take their place -- however this step is required. - -> cd scripts -> ./create_newcase -case newMachinePergro0 -compset ICN -res f19_g16 \ --mach intrepid -> cd newMachinePergro0 -# Set the non-perturbed PERGRO use-case -> ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val pergro0_pd -> ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on -> ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup -# Set PERGRO on in the configure -> ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-pergro on" -append -# Now configure and build -> ./configure -case -> ./newMachinePergro0.intrepid.build -# Set it to run for three days and turn archiving off -> ./xmlchange -file env_run.xml -id STOP_N -val 3 -> ./xmlchange -file env_run.xml -id DOUT_S -val FALSE -# Run the case and then you will save the history file output for later use -> ./newMachinePergro0.intrepid.submit - - - - - -Plotting the differences - -You can use the cprnc program to compute root mean square differences -between the relevant history files. See for more information -on it and how to build it. On many platforms you will need to set some environment -variables in order to complete the build (see for -more information on building the tools). - -# Build the cprnc program -> cd models/lnd/clm/tools/cprnc -> gmake -# Now go to your case directory and run cprnc on the trusted-machine with and without -# perturbation -> cd ../../../../../scripts/trustedMachinePergro0 -> ../../models/lnd/clm/tools/cprnc/cprnc trustedMachinePergro0.clm2.h0.001-01-01.00000.nc \ -../trustedMachinePergroRnd/trustedMachinePergroRnd.clm2.h0.001-01-01.00000.nc > trustedPergro.log -# Copy the history file from the new machine to here -# -# And now run cprnc on the trusted-machine and the new machine both without perturbation -> ../../models/lnd/clm/tools/cprnc/cprnc trustedMachinePergro0.clm2.h0.001-01-01.00000.nc \ -../newMachinePergro0/newMachinePergro0.clm2.h0.001-01-01.00000.nc > newPergro.log -# Now extract out the RMS differences of TSOI for both -# You may want to extract out the RMS differences for TSA as well -# Changes in urban or lake land-units won't be detected with TSOI -> grep "RMS TSOI" trustedPergro.log | awk '{print $3}' > RMStrusted.dat -> grep "RMS TSOI" newPergro.log | awk '{print $3}' > RMSnewmachine.dat -# And plot the two curves up to your screen -> env TYPE=x11 RMSDAT=RMSnewmachine.dat RMSDAT2=RMStrusted.dat ncl \ -../../models/lnd/clm/tools/ncl_scripts/pergroPlot.ncl - -Here is a sample plot for several trusted machines: bluefire, intrepid, jaguar, -and edinburgh (with both the lahey and intel compilers). -The green line is the error growth for bluefire, the red is the error growth -for intrepid, the dashed navy is for jaguar, the dashed maroon is for the intel -compiler on edinburgh, and the thick dashed goldenrod line is for edinburgh with the -lahey compiler. Note, the data for this plot is in -models/lnd/clm/tools/ncl_scripts the files are named: -according to the legend. Note, that the lines tend to cluster together and follow -quite closely to the bluefire line which is our main trusted machine. -

-Sample Good Perturbation Error Growth Curves (within roundoff) - - - -
- - - -When you do NOT have access to a trusted machine you can use the trusted file from -bluefire that is available on the inputdata repository. - -# Build the cprnc program -> cd models/lnd/clm/tools/cprnc -> gmake -# Get the unperturbed file from the subversion repository -> cd ../../../../../scripts/newMachinePergro0 -> set dir = "lnd/clm2/pergrodata" -> set file = bluefirePergro0.ICN.0001-01-01_1.9x2.5_gx1v6_simyr2000_clm4-cesm1_0_3.c110617.nc -> echo "trustedfile = DIN_LOC_ROOT/$dir/$file" > clm.input_data_list -> ../ccsm_utils/Tools/check_input_data -datalistdir . -export -inputdata $DIN_LOC_ROOT -# And now run cprnc on the bluefire file and the new machine both without perturbation -> ../../models/lnd/clm/tools/cprnc/cprnc $file \ -../newMachinePergro0/newMachinePergro0.clm2.h0.001-01-01.00000.nc > newPergro.log -# Now extract out the RMS difference -# You may want to extract out the RMS differences for TSA as well -# Changes in urban or lake land-units won't be detected with TSOI -> grep "RMS TSOI" newPergro.log | awk '{print $3}' > RMSnewmachine.dat -# And plot the new curve versus the trusted curve up to your screen -> env TYPE=x11 RMSDAT=RMSnewmachine.dat \ -RMSDAT2=../../models/lnd/clm/tools/ncl_scripts/RMSbluefire.dat \ -../../models/lnd/clm/tools/ncl_scripts/pergroPlot.ncl - - - -In the figure below we now show example of curves for changes that are larger than -roundoff. Once again the green curve is the trusted error growth from bluefire. The -other curves are for changes that may be fairly small, but are larger than roundoff. The -goldenrod curve is for using the 1850, and the navy is for using the 1999 Nitrogen -deposition files rather than for year 2000. The red is for using the 1850 aerosol -dataset rather than 2000, and the maroon is for adding the snow combination bug in. The -differences in changes that are greater than roundoff is that the curves climb very -steeply to the 10-6 value and then level off, while the -curve for bluefire climbs much more slowly and gradually. The curves also don't mimic -each other in any way, like the trusted machine plots do. -
-Sample Bad Perturbation Error Growth Curves (changes greater than roundoff) - - - -
- - - - - - - -Running stand-alone &clm; with transient historical &CO2; -concentration - -In this case you want to run a simulation with stand-alone &clm; responding -to changes in &CO2; for a historical period. -For this example, we will start with the "I_1850-2000_CN" compset that -has transient: land-use, Nitrogen and Aerosol deposition already. You could -also use another compset if you didn't want these other features to be transient. -In order to get &CO2; to be transient we need to edit the -&datm; template so that we add an extra streams file to describe how -&CO2; varies over the historical period. You also need -a &netcdf; datafile that datm can read that gives the variation. You could -supply your own file, but we have a standard file that is used by CAM for this -and our example will make use of this file. - - - -Most everything here has to do with changing datm rather than &clm; -to allow this to happen. As such the user that wishes to do this should -first become more familiar with datm and read the -&cesm; Data -Model User's Guide especially as it pertains to the datm. Note, also -that in this example we show how to edit the datm "buildnml" file for your -case, but you could do something similar by editing the datm template. - - - - -This section documents the process for doing something that is non-standard. -There may be errors with the documentation and process, and you may have to do -some work before all of this works for you. If that is the case, we recommend -that you do further research into understanding the process and the files, as -well as understanding the datm and how it works. You may have to read documentation -found in the code for datm as well as "csm_share". - - - -The datm has "streams" files that have rough XML-like syntax and specify the -location and file to get data from, as well as information on the variable names -and the data locations of the grid points. The datm expects specific variable names -and the datm "maps" the expected variable names from the file to the names expected -by datm. The file we are working with here is a file with a single-point, that covers -the entire globe (so the vertices go from -90 to 90 degrees in latitude and 0 to 360 -degrees in longitude). Since it's a single point it's a little easier to work with -than datasets that may be at a given horizontal resolution. The datm also expects -that variables will be in certain units, and only expects a limited number of -variables so arbitrary fields can NOT be exchanged this way. However, the process -would be similar for datasets that do contain more than one point. - - -The three things that are needed: a domain file, a data file, and a streams text file. -The domain file is a CF-compliant &netcdf; file that has information -on the grid points (latitudes and longitudes for cell-centers and vertices, mask -, fraction, and areas). The datafile is a CF-compliant &netcdf; file with the data that -will be mapped. The streams text file is the XML-like file that tells datm how to find -the files and how to map the variables datm knows about to the variable names on the -&netcdf; files. Note, that in our case the domain file and the data file are the same -file. In other cases, the domain file may be separate from the data file. - - -First we are going to create a case, and we will edit -the Buildconf/datm.buildnml.csh so that we add a -&CO2; data stream in. There is a streams text file -available in models/lnd/clm/doc/UsersGuide/co2_streams.txt, -that includes file with a &CO2; time-series from 1765 to 2007. - -Example Transient Simulation with Historical &CO2; - -> cd scripts -> ./create_newcase -case DATM_CO2_TSERIES -res f19_g16 -compset I_1850-2000_CN \ --mach bluefire -> cd DATM_CO2_TSERIES -# Set CCSM_BGC to CO2A so that CO2 will be passed from atmosphere to land -> ./xmlchange -file env_conf.xml -id CCSM_BGC -val CO2A -# Set CLM_CO2_TYPE to diagnostic so that the land will use the value sent from the atmosphere -> ./xmlchange -file env_conf.xml -id CLM_CO2_TYPE -val diagnostic -> ./configure -case -> cd Buildconf -# Copy the sample streams file over -> cp ../../../models/lnd/clm/doc/UsersGuide/co2_streams.txt . - - -The first thing we will do is to edit the datm buildnml script to add -a CO2 file stream in. To do this we will apply a patch with the differences -needed. The patch file addco2_datm.buildnml.diff is -in models/lnd/clm/doc/UsersGuide and looks like this... - -&co2streams_diff; - -So to apply the patch you do this... - -> cd scripts/DATM_CO2_TSERIES/Buildconf -> patch < ../../../models/lnd/clm/doc/UsersGuide/addco2_datm.buildnml.diff - -Once, you've done that you can build and run your case normally. - - - -The patch assumes you are using a I_1850-2000_CN compset out of the box, with -DATM_PRESAERO equal to trans_1850-2000. So it assumes standard -Qian atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes -anything here the patch will fail, and you will need to put the changes in by hand. - - - - - -If the patch fails, you will have to add the changes to the -datm.buildnml.csh found in the above -patch file by hand. Basically, it adds an extra streams file for &CO2; to the end of the streams variable, -and other arrays associated with streams (adding mapalgo as a new array with bilinear for everything, but -the &CO2; file which should be "nn" for nearest neighbor). - - - - - -The streams file above is hard-coded for the path of the file on &ncar; computers. To use it on an outside -machine you'll need to edit the filepath in the streams file to point to the location where you have the file. - - - - -After going through these steps, you will have a case where you have datm reading -in an extra streams text file that points to a data file with &CO2; -data on it that will send that data to the &clm;. - - - - diff --git a/doc/UsersGuide/stylesheethtml2docbook.xsl b/doc/UsersGuide/stylesheethtml2docbook.xsl deleted file mode 100644 index 13c30ff71d..0000000000 --- a/doc/UsersGuide/stylesheethtml2docbook.xsl +++ /dev/null @@ -1,579 +0,0 @@ - - - - - -wb -file:///epicuser/AISolutions/graphics/AIWorkbench/ - - - - - - - - - - <xsl:value-of select=".//html:h1[1] - |.//html:h2[1] - |.//html:h3[1]"/> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - inlinemediaobject - - mediaobject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Matched -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - No template for - - - - - - No template for - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - _ - - - - - - - - - - - - - - _ - - - - - - - - - - - - - - - - - - - - - - - - - <xsl:value-of select=".//html:caption"/> - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Attempting to count columns on a non-table element - - - Row parameter is not a valid row - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/UsersGuide/tools.xml b/doc/UsersGuide/tools.xml deleted file mode 100644 index f5fd8beac4..0000000000 --- a/doc/UsersGuide/tools.xml +++ /dev/null @@ -1,1396 +0,0 @@ - - -Using the &clm; tools to create your own input datasets - -There are several tools provided with &clm; that allow you to create your own input -datasets at resolutions you choose, or to interpolate initial conditions to a different -resolution, or used to compare &clm; history files between different cases. The tools are -all available in the models/lnd/clm/tools directory. Most of the tools -are &FORTRAN; stand-alone programs in their own directory, but there is also a suite of -&ncl; -scripts in the ncl_scripts directory. Some of the &ncl; scripts are -very specialized and not meant for general use, and we won't document them here. They -still contain documentation in the script itself and the README file in the tools -directory. But, the list of generally important scripts and programs are: - - - cprnc to compare &netcdf; files with a time axis. - - - interpinic to interpolate initial condition files. - - - mkgriddata to create grid datasets. - - - mkdatadomain to create domain files from grid datasets -used by &datm; or docn. - - - mksurfdata to create surface datasets from grid datasets. - - - ncl_scripts/getregional_datasets.pl script to extract a -region or a single-point from global input datasets. See the single-point chapter -for more information on this. - - - ncl_scripts/npdepregrid.ncl interpolate the Nitrogen -deposition datasets to a new resolution. - - - ncl_scripts/aerdepregrid.ncl interpolate the Aerosol -deposition datasets to a new resolution. - - - - - -In the sections to come we will go into detailed description of how to use each of -these tools in turn. First, however we will discuss the common environment variables -and options that are used by all of the &FORTRAN; tools. Second, we go over the outline -of the entire file creation process for all input files needed by &clm; for a new -resolution, then we turn to each tool. In the last section we will -discuss how to customize files for particular observational sites. - - - -Common environment variables and options used in building the &FORTRAN; -tools - -The &FORTRAN; tools all have similar makefiles, and similar options for building. -All of the Makefiles use GNU Make extensions and thus require that you use GNU make -to use them. They also auto detect the type of platform you are on, using "uname -s" -and set the compiler, compiler flags and such accordingly. There are also environment -variables that can be set to set things that must be customized. All the tools use -&netcdf; and hence require the path to the &netcdf; libraries and include files. -On some platforms (such as Linux) multiple compilers can be used, and hence there -are env variables that can be set to change the &FORTRAN; and/or "C" compilers used. -The tools other than cprnc also allow finer control, by also -allowing the user to add compiler flags they choose, for both &FORTRAN; and "C", as -well as picking the compiler, linker and and add linker options. Finally the tools -other than cprnc allow you to turn -optimization on (which is off by default but on for the mksurfdata and -interpinic -programs) with the OPT flag so that the -tool will run faster. To get even faster performance, the interpinic, -mksurfdata, and -mkgriddata programs allow you to also use the SMP to -turn on multiple shared memory processors. -When SMP=TRUE you set the number of threads used by the program with -the OMP_NUM_THREADS environment variable. - - -Options used by all: cprnc, interpinic, -mkdatadomain, mkgriddata, and -mksurfdata - -LIB_NETCDF -- sets the location of the &netcdf; library. -INC_NETCDF -- sets the location of the &netcdf; include files. -USER_FC -- sets the name of the &FORTRAN; compiler. - -Options used by: interpinic, mkdatadomain, -mkgriddata, and mksurfdata - -MOD_NETCDF -- sets the location of the &netcdf; &FORTRAN; module. -USER_LINKER -- sets the name of the linker to use. -USER_CPPDEFS -- adds any CPP defines to use. -USER_CFLAGS -- add any "C" compiler flags to use. -USER_FFLAGS -- add any &FORTRAN; compiler flags to use. -USER_LDFLAGS -- add any linker flags to use. -USER_CC -- sets the name of the "C" compiler to use. -OPT -- set to TRUE to compile the code optimized (TRUE or FALSE) - -Options used by: interpinic, mkgriddata, and mksurfdata: - -SMP -- set to TRUE to turn on shared memory parallelism (i.e. -&omp;) (TRUE or FALSE) -Filepath -- list of directories to build source code from. -Srcfiles -- list of source code filenames to build executable from. - -Options used only by cprnc: - -EXEDIR -- sets the location where the executable will be built. -VPATH -- colon delimited path list to find the source files. - -More details on each environment variable. - - -LIB_NETCDF - -This variable sets the path to the &netcdf; library file -(libnetcdf.a). If not -set it defaults to /usr/local/lib. In order to use the tools -you need to build the &netcdf; library and be able to link to it. In order to build -the model with a particular compiler you may have to compile the &netcdf; library with -the same compiler (or at least a compatible one). - - - - - -INC_NETCDF - -This variable sets the path to the &netcdf; include directory (in order to find -the include file netcdf.inc). -if not set it defaults to /usr/local/include. - - - - - -MOD_NETCDF - -This variable sets the path to the &netcdf; module directory (in order to find -the &netcdf; &FORTRAN90; module file when &netcdf; is used with a &FORTRAN90; -use statement. When not set it defaults to the -LIB_NETCDF value. - - - - - -USER_FC - -This variable sets the command name to the &FORTRAN90; compiler to use when -compiling the tool. The default compiler to use depends on the platform. And -for example, on the AIX platform this variable is NOT used - - - - - -USER_LINKER - -This variable sets the command name to the linker to use when linking the object -files from the compiler together to build the executable. By default this is set to -the value of the &FORTRAN90; compiler used to compile the source code. - - - - - -USER_CPPDEFS - -This variable adds additional optional values to define for the C preprocessor. -Normally, there is no reason to do this as there are very few CPP tokens in the CLM -tools. However, if you modify the tools there may be a reason to define new CPP -tokens. - - - - - -USER_CC - -This variable sets the command name to the "C" compiler to use when -compiling the tool. The default compiler to use depends on the platform. And -for example, on the AIX platform this variable is NOT used - - - - - -USER_CFLAGS - -This variable adds additional compiler options for the "C" compiler to use -when compiling the tool. By default the compiler options are picked according -to the platform and compiler that will be used. - - - - - -USER_FFLAGS - -This variable adds additional compiler options for the &FORTRAN90; compiler to use -when compiling the tool. By default the compiler options are picked according -to the platform and compiler that will be used. - - - - - -USER_LDFLAGS - -This variable adds additional options to the linker that will be used when linking -the object files into the executable. By default the linker options are picked according -to the platform and compiler that is used. - - - - - -SMP - -This variable flags if shared memory parallelism (using i&omp;) should be used when -compiling the tool. It can be set to either TRUE or -FALSE, by default it is set to FALSE, so -shared memory parallelism is NOT used. When set to TRUE you can -set the number of threads by using the OMP_NUM_THREADS environment -variable. Normally, the most you would set this to would be to the number of on-node -CPU processors. Turning this on should make the tool run much faster. - - - -Note, that depending on the compiler answers may be different when SMP -is activated. - - - - - - -OPT - -This variable flags if compiler optimization should be used when -compiling the tool. It can be set to either TRUE or -FALSE, by default it is set to FALSE for -mkdatadomain and TRUE for -mksurfdata and interpinic. -Turning this on should make the tool run much faster. - - - -Note, you should expect that answers will be different when OPT -is activated. - - - - - - -Filepath - -All of the tools are stand-alone and don't need any outside code to operate. The -Filepath is the list of directories needed to compile -and hence is always simply "." the current directory. Several tools use -copies of code outside their directory that is in the &cesm; -distribution (either csm_share code or &clm; source code). - - - - - -Srcfiles - -The Srcfiles lists the filenames of the source code to use -when building the tool. - - - - - -EXEDIR - -The cprnc tool uses this variable to set the location of where the executable -will be built. The default is the current directory. - - - - - -VPATH - -The cprnc tool uses this variable to set the colon delimited pathnames of where -the source code exists. The default is the current directory. - - - - - - - - - -There are several files that are copies of the original files from either -models/lnd/clm/src/main, -models/csm_share/shr, or copies from other tool -directories. By having copies the tools can all be made stand-alone, but -any changes to the originals will have to be put into the tool directories -as well. - - - -The README.filecopies (which can be found in -models/lnd/clm/tools) is repeated here. - -&filecopies; - - - - - -General information on running the &FORTRAN; tools - -The tools run either one of two ways, with a namelist to provide options, or -with command line arguments (and NOT both). interpinic and -cprnc run with command line arguments, and the other tools -run with namelists. - - -Running &FORTRAN; tools with namelists - -mkgridata, mksurfdata and -mkdatadomain run with namelists that are read from -standard input. Hence, you create a namelist and then run them by -redirecting the namelist file into standard input as follows: - -./program < namelist - -For programs with namelists there is at least one sample namelist with the -name "program".namelist (i.e. mksurfdata.namelist -for the mksurfdata program). There may also be other sample -namelists that end in a different name besides "namelist". Namelists that you create -should be similar to the example namelist. The namelist values are also documented -along with the other namelists in the: - -models/lnd/clm/bld/namelist_files/namelist_definition.xml -file and default values in the: - -models/lnd/clm/bld/namelist_files/namelist_defaults_clm_tools.xml -file. - - - -Running &FORTRAN; tools with command line options - -interpinic and cprnc run with command line -arguments. The detailed sections below will give you more information on the command -line arguments specific to each tool. Also running the tool without any arguments -will give you a general synopsis on how to run the tool. For example to get help -on running interpinic do the following. - -cd models/lnd/clm/tools/interpinic -gmake -./interpinic - - - - -Running &FORTRAN; tools built with SMP=TRUE - -When you enable SMP=TRUE on your build of one of the tools that -make use of it, you are using &omp; for shared memory parallelism (SMP). In -SMP loops are run in parallel with different threads run on different processors -all of which access the same memory (called on-node). Thus you can only usefully -run up to the number of processors that are available on a single-node of the machine -you are running on. For example, on the &ncar; machine bluefire there are 32 processors -per node, but the SMT hardware on the machine allows you to submit twice as many -threads or 64 threads. So to run the mksurfdata on bluefire -optimized, with 64 threads you would do the following: - -cd models/lnd/clm/tools/mksurfdata -gmake OPT=TRUE SMP=TRUE -setenv OMP_NUM_THREADS 64 -./mksurfdata < mksurfdata.namelist - - - - - - -The File Creation Process - - -When just creating a replacement file for an existing one, the relevant tool should -be used directly to create the file. When you are creating a set of files for a new -resolution there are some dependencies between the tools that you need to keep in mind -when creating them. The main dependency is that the mkgriddata MUST -be done first as the grid dataset is then input into the other tools. Also look at -. - - - -Creating a complete set of files for input to &clm; - -Create grid and fraction datasets - -First use mkgriddata to create grid and fraction datasets. -See for more information on this. - - - - -Create domain dataset (if NOT already done) - -Next use mkdatadomain to create a domain file for use by -&datm; from the grid and fraction datasets just created. This is required, unless -a domain file already created was input into mkgriddata on -the previous step. -See for more information on this. - - - - -Create surface datasets - -Next use mksurfdata to create a surface dataset, using the grid -dataset as input. -See for more information on this. - - - - -Interpolate aerosol deposition datasets (optional) - -By default the atmosphere model will interpolate -these datasets on the fly, so you don't normally need to do this step. -A reason you might want to do this is to make the read and interpolation faster, -by reducing the amount of data read in and removing the need for the interpolation. -So, if you do, you can use aerdepregrid.ncl to regrid aerosol -deposition datasets to your new resolution using the grid dataset as input. -See for more information on this. - - - - -Interpolate Nitrogen deposition datasets (optional, but only needed if running &clmcn;) - -By default Nitrogen deposition is read in from stream -files at 2-degree resolution and interpolated to the resolution you are running at, -so you don't need to do this step. As with aerosol deposition datasets a reason -you might want to do this is to make the read and interpolation faster, -by reducing the amount of data read in and removing the need for the interpolation. -So, if you do you can use ndepregrid.ncl -to regrid Nitrogen deposition datasets to your new resolution using the grid dataset -as input. -See for more information on this. - - - - -Create some sort of initial condition dataset - - -You then need to do one of the following three options to have an initial dataset -to start from. - - - - - -Use spinup-procedures to create initial condition datasets - -The first option is to do the spinup procedures from arbitrary initial conditions -to get good initial datasets. This is the most robust method to use. -See , , or - for more information on this. - - - - -Use <command>interpinic</command> to interpolate existing initial -condition datasets - -The next option is to interpolate from spunup datasets at a different resolution, using -interpinic. -See for more information on this. - - - - -Start up from arbitrary initial conditions - -The last alternative is to run from arbitrary initial conditions without using any -spun-up datasets. This is inappropriate when using &clmcn; (bgc=cn or cndv) as it -takes a long time to spinup Carbon pools. - - -This is NOT recommended as many fields in &clm; take a long time to equilibrate. - - - - - - - - - - -Enter the new datasets into the &buildnml; XML database - -The last optional thing to do is to enter the new datasets into the &buildnml; -XML database. See for more information on -doing this. This is optional because the user may enter these files into their -namelists manually. The advantage of entering them into the database is so that -they automatically come up when you create new cases. - - - - - - - - -Using the <command>cprnc</command> tool to compare two history files - -cprnc is a tool shared by both CAM and &clm; to compare two -&netcdf; history files. -It differences every field that has a time-axis that is also shared on both files, -and reports a summary of the difference. The summary includes the three largest -differences, as well as the root mean square (RMS) difference. It also gives some -summary information on the field as well. You have to enter at least one file, and up to -two files. With one file it gives you summary information on the file, and with two it -gives you information on the differences between the two. At the end it will give you a -summary of the fields compared and how many fields were different and how many were -identical. - - -Options: - --m = do NOT align time-stamps before comparing --v = verbose output --ipr --jpr --kpr - -See the cprnc -README file for more details which is -repeated here: - -&cprnc_readme; - - - -To compare files with OUT a time axis you can use the cprnc.ncl -&ncl; script in models/lnd/clm/tools/ncl_scripts. It won't give -you the details on the differences but will report if the files are identical or -different. - - - - - - -Using <command>interpinic</command> to interpolate initial conditions to different -resolutions - -"interpinic" is used to interpolate initial conditions from one resolution to another. -In order to do the interpolation you must first run &clm; to create a restart file to -use as the "template" to interpolate into. Running from arbitrary initial conditions -(i.e. finidat = ' ') for a single time-step is sufficient to do this. Make sure the -model produces a restart file. You also need to make sure that you setup the same -configuration that you want to run the model with, when you create the template file. - - -Command line options to interpinic: - --i = Input filename to interpolate from --o = Output interpolated file, and starting template file - - - -There is a sample template file in the models/lnd/clm/tools/interpinic -directory and can be used to run interpolate to. -However, this file was created with an older version of &clm; and hence -we actually recommend that you would do a short run with &clm; to create a template file -to use. - - - - -Example of running &clm; to create a template file for -<command>interpinic</command> to interpolate to - -> cd scripts -> ./create_newcase -case cr_f10_TmpltI1850CN -res f10_f10 -compset I1850CN \ --mach bluefire -> cd cr_f10_TmpltI1850CN -# Set starting date to end of year -> ./xmlchange -file env_conf.xml -id RUN_STARTDATE -val 1948-12-31 -# Set year align to starting year -> ./xmlchange -file env_conf.xml -id DATM_CLMNCEP_YR_ALIGN -val 1948 -# Set to run a cold start -> ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on -# Set to run only a single day, so a restart file will be created on Jan/1/1949 -> ./xmlchange -file env_run.xml -id STOP_N -val 1 -# Then configure, build and run as normal -> ./configure -case -> ./cr_f10_TmpltI1850CN.bluefire.build -> ./cr_f10_TmpltI1850CN.bluefire.submit -# And copy the resulting restart file to your interpinic directory -> cd ../models/lnd/clm/tools/interpinic -> cp /ptmp/$LOGIN/cr_f10_TmpltI1850CN/run/cr_f10_TmpltI1850CN.clm2.r.1949-01-01-00000.nc . - - - - -In the next example we build interpinic optimized with shared -memory on for 64 threads so that it runs as fast as possible, to interpolate one of -the standard 1-degree datasets to the above 10x15 template file that we created. - - -Example of building and running <command>interpinic</command> to -interpolate a 1-degree <filename>finidat</filename> dataset to 10x15 - -> cd models/lnd/clm/tools/interpinic -> gmake OPT=TRUE SMP=TRUE -> env OMP_NUM_THREADS=64 ./interpinic -o cr_f10_TmpltI1850CN.clm2.r.1949-01-01-00000.nc / --i /fs/cgd/csm/inputdata/ccsm4_init/b40.1850.track1.1deg.006/0863-01-01/b40.1850.track1.1deg.006.clm2.r.0863-01-01-00000.nc - - - - -Running interpinic at high resolution can take a long time, so we -recommend that you always build it optimized and with shared memory processing on, to -cut down the run time as much as possible. - - - - -interpinic does NOT work for CNDV (bgc=cndv). - - - - - - -In we give a simpler way to run -interpinic for several standard resolutions at once, with a script -to loop over several resolutions. This is useful for &clm; developers who need to -create many finidat files at once. - - - - - -Using <command>mkgriddata</command> to create grid datasets - -mkgriddata is used to create grid, fraction, and topography -datasets to run &clm; at a new resolution. It is typically the first step in creating -datasets needed to run &clm; at a new resolution (followed by -mksurfdata, and -then the interpolation programs, aerdepregrid.ncl, and -ndepregrid.ncl when running with CN). - - - -mkgriddata namelist - -mkgriddata is controlled by a namelist. There are ten different -namelist items, and you need to use enough of them so that files will be output. -The different types of input datasets contain different input data types, that -correspond to the three different types of output files: grid, fraction, and topography. -Output files for each of these will only be output if there is input data that -correspond to these. If you only have input data for grid locations -- you will only -get an output grid file. If you have both grid and fraction data you will get grid and -fraction data files. If you also have topography data you will also get topo files. - - -Namelist options to mkgriddata include: - -mksrf_fnavyoro -- Navy orography file to use for land fraction -and surface heights. -mksrf_frawtopo -- Raw topography file with just surface -heights. -mksrf_fcamfile -- CAM initial conditions file with -land-fractions and topography -mksrf_fclmgrid -- &clm; grid file -mksrf_fccsmdom -- &cesm; domain file -mksrf_fcamtopo -- CAM topography file -mksrf_lsmlon -- number of longitude for regional grid -mksrf_lsmlatnumber of latitudes for regional grid -mksrf_edgen -- Northern edge for regional grid -mksrf_edgee -- Southern edge for regional grid -mksrf_edges -- Eastern edge for regional grid -mksrf_edgew -- Western edge for regional grid - - - -You need to enter one of the following four options: - - mksrf_fnavyoro - high resolution topo dataset (topo data) - mksrf_lsmlon - number of longitudes - mksrf_lsmlat - number of latitudes - mksrf_edgen - northern edge of grid (degrees) - mksrf_edgee - eastern edge of grid (degrees) - mksrf_edges - southern edge of grid (degrees) - mksrf_edgew - western edge of grid (degrees) - -or - - mksrf_fcamfile - CAM topo file (grid and possibly fraction data) - -or - - mksrf_fccsmdom - &cesm; domain file (both grid, and fraction data) - -or - - mksrf_fclmgrid - &clm; grid or surface dataset file (grid data) - -Note, you can provide more than one of the needed datasets, and the output -data will be determined by the datasets according to an order of precedence. -The order of precedence for data is as follows: - -mksrf_fcamfile -mksrf_fclmgrid -mksrf_fnavyoro -mksrf_fccsmdom - -Grid data then will be established by the file with the highest precedence. -&cesm; domain files sometimes have latitudes and longitudes that are "off" from -the standard by a small amount. By establishing an order of precedence you can ensure -that grid locations exactly match a given standard file, even if the values in the domain -file are off from that. - - - -There are three different major modes for using "mkgriddata" to create grid files -for &clm;: - -mksrf_fnavyoro -- Navy orography file to use for land fraction -and surface heights. -mksrf_frawtopo -- Raw topography file with just surface -heights. -mksrf_fcamfile -- CAM initial conditions file with -land-fractions and topography -mksrf_fclmgrid -- &clm; grid file -mksrf_fccsmdom -- &cesm; domain file -mksrf_fcamtopo -- CAM topography file -mksrf_lsmlon -- number of longitude for regional grid -mksrf_lsmlat -- number of latitudes for regional grid -mksrf_edgen -- Northern edge for regional grid -mksrf_edgee -- Southern edge for regional grid -mksrf_edges -- Eastern edge for regional grid -mksrf_edgew -- Western edge for regional grid - - - -You need to enter one of the following four options: - - mksrf_fnavyoro - high resolution topo dataset (topo data) - mksrf_lsmlon - number of longitudes - mksrf_lsmlat - number of latitudes - mksrf_edgen - northern edge of grid (degrees) - mksrf_edgee - eastern edge of grid (degrees) - mksrf_edges - southern edge of grid (degrees) - mksrf_edgew - western edge of grid (degrees) - -or - - mksrf_fcamfile - CAM topo file (grid and possibly fraction data) - -or - - mksrf_fccsmdom - &cesm; domain file (both grid, and fraction data) - -or - - mksrf_fclmgrid - &clm; grid or surface dataset file (grid data) - -Note, you can provide more than one of the needed datasets, and the output -data will be determined by the datasets according to an order of precedence. -The order of precedence for data is as follows: - -mksrf_fcamfile -mksrf_fclmgrid -mksrf_fnavyoro -mksrf_fccsmdom - -Grid data then will be established by the file with the highest precedence. -&cesm; domain files sometimes have latitudes and longitudes that are "off" from -the standard by a small amount. By establishing an order of precedence you can ensure -that grid locations exactly match a given standard file, even if the values in the domain -file are off from that. - - - -There are three different major modes for using mkgriddata to -create grid files for &clm;: - -Convert &cesm; domain files to &clm; grid files -Create single point or regional area grid files -Convert CAM files to &clm; grid files - - - - - -Convert &cesm; domain files to &clm; grid files - -&cesm; domain files such as used for &datm;, include all the information -needed to create &clm; grid and fraction files. - -Example <command>mkgriddata</command> namelist to convert &cesm; 4x5 domain files to &clm; grid files - -&clmexp - mksrf_fccsmdom= -'/fs/cgd/csm/inputdata/lnd/dlnd7/domain.lnd.4x5_gx3v5.060404.nc' - mksrf_fclmgrid= -'/fs/cgd/csm/inputdata/lnd/clm2/griddata/griddata_4x5_060404.nc' -/ - - - - -Notice that in the above example, a &clm; grid file is included as well, even though -it's not required. The reason for this is to ensure that the latitude and longitudes -on the output files exactly match a standard grid file. - - - - - - -Create single point or regional area grid files - -The process to create single-point or regional area &clm; grid files is the same. -You enter the number of latitudes and longitudes you want on your output file and -the extent of the grid: North, East, South and West. You also tell -mkgriddata that -you are entering a "regional" grid and you also enter the standard Navy orography -dataset (or your own orography file if desired). For a single point you simply -enter "1" for the number of latitudes and longitudes, but you still enter the -grid extent (of the single grid cell). Here is a sample regional namelist to create -a 5x5 regional grid over the Amazon: - -Example <command>mkgriddata</command> namelist to create regional grid over Amazon - -&clmexp - mksrf_fnavyoro= -"/fs/cgd/csm/inputdata/lnd/clm2/rawdata/mksrf_navyoro_20min.c010129.nc" - mksrf_lsmlon = 5 - mksrf_lsmlat = 5 - mksrf_edgee = 303.75 - mksrf_edgew = 286.25 - mksrf_edges = -15. - mksrf_edgen = -4. -/ - - - - - -Currently you can NOT have regional grids that straddle both -sides of the Greenwich (longitude = zero) line. - - - - -You should enter longitudes with values from 0 to 360 East. - - - - - -Convert <acronym>CAM</acronym> files to &clm; grid files (deprecated) - -Older CAM initial files included all the information needed to create &clm; -grid files. Newer CAM files no longer include land fraction data. Hence you -can use CAM files to give you the grid coordinates, but you need other data -to give you the land-mask and topography. Since, CAM files no longer -contain the needed information, this option is now deprecated. In most cases you should -use one of the other two options. - - - - - - - -Using <command>mkdatadomain</command> to create domain datasets for &datm; or docn from &clm; grid datasets - -"mkdatadomain" is used to convert &clm; grid and fraction datasets into domain datasets -that can be used by either the "datm" or "docn" models. Most often &clm; users will want -to convert the grid datasets they just created using mkgriddata into -domain datasets to be used by &datm; for an "I" case. mkdatadomain is -controlled by a namelist, and has a very straight forward operation with only four -namelist items all of which are required. You specify which output mode you want "datm" -or "docn", and then set the input &clm; grid and frac datasets, and the output domain file. - - -Example <command>mkdatadomain</command> namelist to create a domain file from -&clm; frac and grid data files - -&domain_nl - dtype = "datm" - f_fracdata = -'/fs/cgd/csm/inputdata/lnd/clm2/griddata/fracdata_4x5_USGS_070110.nc' - f_griddata = -'/fs/cgd/csm/inputdata/lnd/clm2/griddata/griddata_4x5_060404.nc' - f_domain = -'domain.lnd.fv4x5_USGS.090117.nc' -/ - - - - - -Using mksurfdata to create surface datasets from grid datasets - -mksurfdata is used to create surface-datasets from grid datasets and raw datafiles -at half-degree resolution to produce files that describe the surface characteristics -needed by &clm; (fraction of grid cell covered by different land-unit types, and fraction -for different vegetation types, as well as things like soil color, and soil texture, -etc.). To run mksurfdata you can either use the -mksurfdata.pl script which will create namelists for you using the &buildnml; -XML database, or you can run it by hand using a namelist that you provide (possibly -modeled after an example provided in the -models/lnd/clm/tools/mksurfdata directory). The namelist for -mksurfdata is sufficiently complex that we recommend using the -mksurfdata.pl tool to build them. In the next section -we describe how to use the mksurfdata.pl script and the following -section gives more details on running mksurfdata by hand and the -various namelist input variables to it. - - -Running <command>mksurfdata.pl</command> - -The script mksurfdata.pl can be used to run the -mksurfdata program for several configurations, resolutions, -simulation-years and simulation year ranges. It will create the needed namelists for -you and move the files -over to your inputdata directory location (and create a list of the files created, and -for developers this file is also a script to import the files into the svn inputdata -repository). It will also use the &buildnml; XML database -to determine the correct input files to use, and for transient cases it will create -the appropriate mksrf_fdynuse file with the list of files for each -year needed for this case. And in the case of urban single-point -datasets (where surface datasets are actually input into mksurfdata) -it will do the additional processing required so that the output dataset -can be used once again by mksurfdata. Because, it figures out -namelist and input files for you, it is recommended that you use this script for creation -of standard surface datasets. If you need to create surface datasets for customized -cases, you might need to run mksurfdata on it's own. But you -could use mksurfdata.pl with the "-debug" option to give you -a namelist to start from. -For help on mksurfdata.pl you can use the "-help" option as below: - -> cd models/lnd/clm/tools/mksurfdata -> mksurdata.pl -help - -The output of the above command is: - -&mksurfdatapl; - - - -To run the script with optimized mksurfdata for a 4x5 degree grid -for 1850 conditions, on bluefire you would do the following: - -Example of running <command>mksurfdata.pl</command> to create a 4x5 resolution -<filename>fsurdat</filename> for a 1850 simulation year - -> cd models/lnd/clm/tools/mksurfdata -> gmake -> mksurfdata.pl -y 1850 -r 4x5 - - - - - - -Running <command>mksurfdata</command> by Hand - -In the above section we show how to run mksurfdata through -the mksurfdata.pl using input datasets that are in the &buildnml; -XML database. When you are running with input datasets that are NOT available in -the XML database you either need to add them as outlined in -, or you need to run mksurfdata -by hand, as we will outline here. - - - -Preparing your <command>mksurfdata</command> namelist - -When running mksurfdata by hand you will need to prepare your -own input namelist. There are sample namelists that are setup for running on the -&ncar; machine bluefire. You will need to change the filepaths to -run on a different machine. The list of sample namelists include - -mksurfdata.namelist -- standard sample namelist. -mksurfdata.regional -- sample namelist to -build for a regional grid dataset (5x5_amazon) -mksurfdata.singlept -- sample namelist to -build for a single point grid dataset (1x1_brazil) - -Note, that one of the inputs mksrf_fdynuse is a filename that -includes the filepaths to other files. The filepaths in this file will have to -be changed as well. You also need to make sure that the line lengths remain the same -as the read is a formatted read, so the placement of the year in the file, must remain -the same, even with the new filenames. One advantage of the mksurfdata.pl -script is that it will create the mksrf_fdynuse file for you. - - -We list the namelist items below. Most of the namelist items are filepaths to give to -the input half degree resolution datasets that you will use to scale from to the -resolution of your grid dataset. -You must first specify the input grid dataset for the resolution to output for: - -mksrf_fgrid Grid dataset - -Then you must specify settings for input high resolution datafiles - -mksrf_ffrac land fraction and land mask dataset -mksrf_fglacier Glacier dataset -mksrf_fglacierregion Glacier region ID dataset -mksrf_flai Leaf Area Index dataset -mksrf_flanwat Land water dataset -mksrf_forganic Organic soil carbon dataset -mksrf_fmax Max fractional saturated area dataset -mksrf_fsoicol Soil color dataset -mksrf_fsoitex Soil texture dataset -mksrf_ftopo Topography dataset (this is used to limit -the extent of urban regions and is used for glacier multiple elevation classes) - -mksrf_furban Urban dataset -mksrf_fvegtyp PFT vegetation type dataset -mksrf_fvocef Volatile Organic Compound Emission Factor -dataset -mksrf_fgdp GDP dataset -mksrf_fpeat Peatland dataset -mksrf_fabm Agricultural fire peak month dataset -mksrf_ftopostats Topography statistics dataset -mksrf_fvic VIC parameters dataset -mksrf_fch4 Inversion-derived CH4 parameters dataset - -You specify the ASCII text file with the land-use files. - -mksrf_fdynuse "dynamic land use" for transient -land-use/land-cover changes. This is an ASCII text file that lists the filepaths -to files for each year and then the year it represents (note: you MUST change the -filepaths inside the file when running on a machine NOT at &ncar;). -We always use this file, even for creating datasets of a fixed year. Also note -that when using the "pft_" settings this file will be an XML-like file with settings -for PFT's rather than filepaths (see below). - - - -And optionally you can specify settings for: - -all_urban If entire area is urban (typically used for -single-point urban datasets, that you want to be exclusively urban) -no_inlandwet If TRUE, set wetland to 0% over land -(renormalizing other landcover types as needed); wetland will only be used for ocean -points. (Only applies to CLM4.5 version of mksurfdata_map, for which the default is -TRUE.) -mksrf_firrig Irrigation dataset, if you want -activate the irrigation model over generic cropland -(experimental mode, normally NOT used) -mksrf_gridnm Name of output grid resolution (if not -set the files will be named according to the number of longitudes by latitudes) -mksrf_gridtype Type of grid (default is 'global') -nglcec number of glacier multiple elevation classes. -Can be 0, 1, 3, 5, or 10. When using the resulting dataset with &clm; you can then run -with glc_nec of either 0 or this value. - (experimental normally use the default of 0, when running with the land-ice -model in practice only 10 has been used) -numpft number of Plant Function Types (PFT) -in the input vegetation mksrf_fvegtyp dataset. You change -this to 20, if you want to create a dataset with prognostic crop activated. The -vegetation dataset also needs to have prognostic crop types on it as well. - (experimental normally not changed from the default of 16) -outnc_large_files If output should be in &netcdf; large file -format -outnc_double If output should be in double -precision (normally we turn this on) -pft_frc array of fractions to override PFT -data with for all gridpoints (experimental mode, normally NOT used). -pft_idx array of PFT indices to override PFT -data with for all gridpoints (experimental mode, normally NOT used). -soil_clay percent clay soil to override -all gridpoints with (experimental mode, normally NOT used). -soil_color Soil color to override -all gridpoints with (experimental mode, normally NOT used). -soil_fmax Soil maximum fraction to override -all gridpoints with (experimental mode, normally NOT used). -soil_sand percent sandy soil to -override all gridpoints with (experimental mode, normally NOT used). - - - -After creating your namelist, -when running on a non &ncar; machine you will need to get the files -from the inputdata repository. -In order to retrieve the files needed for mksurfdata you can do the following on your -namelist to get the files from the inputdata repository, using the -check_input_data script which also allows you to export data to -your local disk. - -Getting the raw datasets for <command>mksurfdata</command> to your local -machine using the <command>check_input_data</command> script - -> cd models/lnd/clm/tools/mksurfdata -# First remove any quotes and copy into a filename that can be read by the -# check_input_data script -> sed "s/'//g" namelist > clm.input_data_list -# Run the script with -export and give the location of your inputdata with $CSMDATA -> ../../../../../scripts/ccsm_utils/Tools/check_input_data -datalistdir . \ --inputdata $CSMDATA -check -export -# You must then do the same with the flanduse_timeseries file referred to in the namelist -# in this case we add a file = to the beginning of each line -> awk '{print "file = "$1}' landuse_timeseries_hist_simyr2000-2000.txt > clm.input_data_list -# Run the script with -export and give the location of your inputdata with $CSMDATA -> ../../../../../scripts/ccsm_utils/Tools/check_input_data -datalistdir . \ --inputdata $CSMDATA -check -export - - - - -Experimental options to <command>mksurfdata</command> - -The options: pft_frc, pft_idx, soil_clay, soil_color, soil_fmax, and soil_sand are also -new and considered experimental. They provide a way to override the PFT and soil -values for all grid points to the given values that you set. This is useful for -running with single-point tower sites where the soil type and vegetation is known. -Note that when you use pft_frc, all other landunits will be zeroed out, and the -sum of your pft_frc array MUST equal 100.0. Also note that when using the "pft_" -options the mksrf_fdynuse file instead of having filepath's -will be an XML-like file with PFT settings. Unlike the file of file-paths, you will -have to create this file by hand, mksurfdata.pl will NOT be able -to create it for you (other than the first year which will be set to the values -entered on the command line). Note, that when &ptclm; is run, it CAN create these -files for you from a simpler format (see ). -Instead of a filepath you have a list of XML elements that give information on the PFT's -and harvesting for example: - -<pft_f>100</pft_f><pft_i>1</pft_i><harv>0,0,0,0,0</harv><graz>0</graz> - -So the <pft_f> tags give the PFT fractions and the <pft_i> tags give the -index for that fraction. Harvest is an array of five elements, and grazing is a single -value. Like the usual file each list of XML elements goes with a year, and there is -limit on the number of characters that can be used. - - - - - -Standard Practices when using <command>mksurfdata</command> - -In this section we give the recommendations for how to use mksurfdata -to give similar results to the files that we created when using it. - - -If you look at the standard surface datasets that we have created and provided for use, -there are three practices that we have consistently done in each (you also see these in -the sample namelists and in the mksurfdata.pl script). The first is -that we always output data in double precision (hence outnc_double -is set to .true.). The next is that we always use the procedure -for creating transient datasets (using mksrf_fdynuse) even when -creating datasets for a fixed simulation year. This is to ensure that the fixed year -datasets will be consistent with the transient datasets. When this is done a -"landuse_timeseries" dataset will be created -- but will NOT be used in &clm;. If you look -at the sample namelist mksurfdata.namelist you note that it -sets mksrf_fdynuse to the file -landuse_timeseries_hist_simyr2000.txt, where the single file entered is -the same PFT file used in the rest of the namelist (as mksrf_fvegtyp). -The last practice that we always do is to always set mksrf_ftopo, -even if glacier elevation classes are NOT active. This is -important in limiting urban areas based on topographic height, and hence is important -to use all the time. The glacier multiple elevation classes will be used as well if -you are running a compset with the active glacier model. - - -There are two other important practices for creating urban single point datasets. The -first is that you often will want to set all_urban to -.true. so that the dataset will have 100% of the gridcell output -as urban rather than some mix of: urban, vegetation types, and other landunits. The -next practice is that most of our specialized urban datasets have custom values for -the urban parameters, hence we do NOT want to use the global urban dataset to get -urban parameters -- we use a previous version of the surface dataset for the urban -parameters. However, in order to do this, we need to append onto the previous surface -dataset the grid and land mask/land fraction information from the grid and fraction -datasets. This is done in mksurfdata.pl using the NCO -program ncks. An example of doing this for the Mexico City, Mexico -urban surface dataset is as follows: - -> ncks -A $CSMDATA/lnd/clm2/griddata/griddata_1x1pt_mexicocityMEX_c090715.nc \ -$CSMDATA/lnd/clm2/surfdata/surfdata_1x1_mexicocityMEX_simyr2000_c100407.nc -> ncks -A $CSMDATA/lnd/clm2/griddata/fracdata_1x1pt_mexicocityMEX_navy_c090715.nc \ -$CSMDATA/lnd/clm2/surfdata/surfdata_1x1_mexicocityMEX_simyr2000_c100407.nc - -Note, if you look at the current single point urban surface datasets you will note -that the above has already been done. - - -The final issue is how to build mksurfdata. When NOT optimized -mksurfdata is very slow, and can take many hours to days to -even run for medium resolutions such as one or two degree. So usually you will want -to run it optimized. Possibly you also want to use shared memory parallelism using -&omp; with the SMP option. The problem with running optimized is that -answers will be different when running optimized versus non-optimized for most -compilers. So if you want answers to be the same as a previous surface dataset, you -will need to run it on the same platform and optimization level. Likewise, running -with or without &omp; may also change answers (for most compilers it will NOT, however -it does for the IBM compiler). However, answers should be the same regardless of the -number of threads used when &omp; is enabled. Note, that the output surface datasets -will have attributes that describe whether the file was written out optimized or not, -with threading or not and the number of threads used, to enable the user to more -easily try to match datasets created previously. For more information on the different -compiler options for the &clm4; tools see . - - - - - - - -Using &ncl; scripts <command>ndepregrid.ncl</command> and -<command>aerdepregrid.ncl</command> to interpolate aerosol deposition datasets - -Unlike the other tools, these are &ncar; Command Language (&ncl;) scripts -and you will need to get a copy of &ncl; in order to use them. You also won't have to -build an executable in order to use them, hence no Makefile is provided. &ncl; is provided -for free download as either binaries or source code from: -http://www.ncl.ucar.edu/. The &ncl; -web-site also contains documentation on &ncl; and it's use. - - -By default at this point neither of these scripts HAS to be used, -as the model is now constructed to read aerosol and Nitrogen deposition from 2-degree -datasets and interpolate to the model resolution on the fly. The main reason you might -want to do this now, is for better performance for single-point simulations. - - -Both the ndepregrid.ncl and aerdepregrid.ncl -scripts have similar interfaces and you customize the output resolution and -characteristics based on the settings of environment variables that you set (if you -don't set any of the variables, the script has defaults that it will use). -The list of environment variables that can be set are: - -RES -- output resolution name -RCP -- representative concentration pathway for future scenarios -(example 2.6, 4.5, 6, or 8.5) -SIM_YR -- simulation year (example 1850 or 2000) -SIM_YR_RNG -- simulation year range (example 1850-2000 or -1850-2100) -GRDFIL -- full pathname of grid file to use -(in place of getting the default grid file based on the RES value) -CSMDATA -- &cesm; inputdata directory -CLM_ROOT -- root directory for &clm; (models/lnd/clm directory) - - - - -You MUST provide either RES or both -GRDFIL AND RES. If you -just give RES the default namelist database in -models/lnd/clm/bld will be used to find the default grid -file based on the resolution name RES. If you provide -GRDFIL the input pathname of the gridfile provided will be used, -and the output filename will include RES as part of it's name -to designate it as an output file at that resolution. - - - -Both scripts assume that you will be interpolating from a native resolution of 1.9x2.5 -and using the default files found in the namelist database to interpolate from. If you -want to interpolate from another resolution or use other files, you would need to edit -the scripts to do so. Both scripts also use a bilinear interpolation to do the -regridding. The environment variables: RCP, SIM_YR, -and SIM_YR_RNG will be used to query the namelist database to -determine which native dataset to interpolate from. If you don't provide valid -values for these variables, it won't be able to find a dataset to interpolate from. -You can use the build-namelist script to query what the valid values for these can -be. Likewise, when you use RES to determine the grid file to interpolate -to, it needs to be a valid value from the namelist database. - - -The scripts can be used to interpolate from (and create output) constant or -transient datasets. -Constant datasets specify the SIM_YR and set SIM_YR_RNG -to constant (which is also the default). Transient datasets need -to specify both SIM_YR and SIM_YR_RNG, where -SIM_YR is set to the first year in the interval (typically 1850). - - -The default for CSMDATA works for &ncar; computers, but will need to -be set to the top level directory location of your &cesm; input data on other computers. -If you set this as a default for your shell when you login (for example with your -$HOME/.cshrc if you use csh) you won't have to set it each time -you run the script. CLM_ROOT will default to the proper location -when you run it in the models/lnd/clm/tools/ncl_script -directory. It is only useful if you want to run the script out of a different -directory. - - -Using <command>ndepregrid.ncl</command> to interpolate Nitrogen deposition datasets - -ndepregrid.ncl interpolates the Nitrogen deposition datasets from one resolution -to another. - - - -Interpolating Nitrogen deposition files is no longer needed, because the model can -read Nitrogen deposition files at one resolution and interpolate to the resolution the -model is running at on the fly. Interpolating to another -resolution is only useful for very course resolutions, if you want to save some computing -resources in reading larger datasets. For example, this may be useful in obtaining -single-point datasets. - - - -For example, to interpolate to an output resolution of 0.9x1.25, for a constant -simulation-year of 1850, you would do the following: - -> env RES=0.9x1.25 SIM_YR=1850 ncl ndepregrid.ncl - - - - - -Using <command>aerdepregrid.ncl</command> to interpolate Aerosol deposition datasets - -aerdepregrid.ncl interpolates the Aerosol deposition datasets from one resolution. -It can be used to interpolate either constant datasets (for example: -aerosoldep_monthly_2000_0.9x1.25_c090828.nc) or transient datasets (for example: -aerosoldep_monthly_1849-2006_0.9x1.25_c090830.nc). - - - -Interpolating aerosol deposition files is no longer needed, because the &datm; model can -read aerosol deposition files at one resolution and interpolate to the resolution the -model is running at on the fly. Interpolating to another -resolution is only useful for very course resolutions, if you want to save some computing -resources in reading larger datasets. For example, this may be useful in obtaining -single-point datasets. - - - -For example, to interpolate to an output resolution of 4x5, for a transient -simulation-year range of 1850 to 2100 and the rcp of 8.5, you would do the following: - -> env RES=4x5 SIM_YR=1850 SIM_YR_RNG=1850-2100 RCP=8.5 ncl ndepregrid.ncl - - - - - - -How to Customize Datasets for particular Observational Sites - -There are two ways to customize datasets for a particular observational site. The first -is to customize the input to the tools that create the dataset, and the second is to -over-write the default data after you've created a given dataset. Depending on the tool -it might be easier to do it one way or the other. In we list the files that are most likely to be -customized and the way they might be customized. Of those files, the ones you are most -likely to customize are: fatmlndfrc, fsurdat, faerdep (for &datm;), and -stream_fldfilename_ndep. Note mksurfdata as documented previously -has options to overwrite the vegetation and soil types. For more information on this also see - and &ptclm; uses these methods to -customize datasets see . - - -Another aspect of customizing your input datasets is customizing the input atmospheric -forcing datasets. See the for more -information on this. Also the chapter on &ptclm; in -has information on using the AmeriFlux tower site data as atmospheric forcing. - - - - -Conclusion of tools description - -We've given a description of how to use the different tools with &clm; to create -customized datasets. In the next chapter we will talk about how to make these -files available for build-namelist so that you can easily create simulations -that include them. In the chapter on single-point and regional datasets we also -give an alternative way to enter new datasets without having to edit files. - - - - - diff --git a/doc/UsersGuide/trouble_shooting.xml b/doc/UsersGuide/trouble_shooting.xml deleted file mode 100644 index 418cfabaae..0000000000 --- a/doc/UsersGuide/trouble_shooting.xml +++ /dev/null @@ -1,545 +0,0 @@ - - -Trouble Shooting Problems - -In this chapter we give some guidance on what to do when you encounter some of the -most common problems. We can't cover all the problems that a user could potentially -have, but we will try to help you recognize some of the most common situations. -And we'll give you some suggestions on how to approach the problem to come up with -a solution. - - -In general you will run into one of three type of problems: - -configure-time -build-time -run-time - -You may also run into problems with create_newcase itself, or -with the archiving scripts -- for those problems you should consult the -&cesmrel; Scripts User's Guide. - - - -Trouble with Configuration - -The first type of problem happens when you invoke the configure -case -command. This indicates there is something wrong with your template files, or input -datasets, or the details of what you are trying to configure the model to do. -There's also a trouble-shooting chapter in the &cesmrel; -Scripts User's Guide. Many of the problems with configuration can be resolved -with the guidelines given there. Here we will restrict ourselves to problems from the -&clm; or &datm; templates or input files. - -Example of configure problem with missing datasets - -> ./create_newcase -case T31rcp6 -res T31_g37 -compset IRCP60CN \ --mach bluefire -> ./configure -case - -The following is what is displayed to the screen. - -Generating resolved namelist, prestage, and build scripts -configure done. -adding use_case 1850-2100_rcp6_transient defaults for var clm_demand with val flanduse_timeseries -adding use_case 1850-2100_rcp6_transient defaults for var clm_start_type with val startup -adding use_case 1850-2100_rcp6_transient defaults for var model_year_align_ndep with val -1850 -adding use_case 1850-2100_rcp6_transient defaults for var rcp with val 6 -adding use_case 1850-2100_rcp6_transient defaults for var sim_year with val 1850 -adding use_case 1850-2100_rcp6_transient defaults for var sim_year_range with val -1850-2100 -adding use_case 1850-2100_rcp6_transient defaults for var stream_year_first_ndep with val -1850 -adding use_case 1850-2100_rcp6_transient defaults for var stream_year_last_ndep with val -2100 -adding use_case 1850-2100_rcp6_transient defaults for var use_case_desc with val Simulate -transient land-use, aerosol and Nitrogen deposition changes with historical data from -1850 to 2005 and then with the RCP6 scenario from AIM - -build-namelist - No default value found for flanduse_timeseries. - Are defaults provided for this resolution and land mask? -ERROR: generate_resolved.csh error for lnd template -configure error: configure generated error in attempting to created resolved scripts - - -The important thing to note here is the line: - -ERROR: generate_resolved.csh error for lnd template - -which tells us that the problem is in the land template. It may also indicate problems -in one of the other templates (atm, ccsm, cpl, glc, ice, or ocn), in which case you -should consult the appropriate model user's guide, and examine the given template file -in Tools/Templates. For more information on working with template -files see . - - -In the example above, it's obvious that the problem is coming from the &clm; &buildnml;, -in other situations it might not be so obvious where the problem is occurring. In such -cases it might be useful to add a "set echo" command to the top of the template file so -that each command in the template will be echoed to the screen and you can see what -is happening and where the error is occurring. - -set echo - - - -In the example, the error is that the &clm; XML database does NOT have a -flanduse_timeseries for the given resolution, rcp scenario and ocean mask. -That means you will need to create the file and then supply the file into your case. See - for more information on creating files, and see - for more information on adding files to the -XML database. Alternatively, you can provide the file to your case by creating -a user namelist as shown in . - - - -The two most common problems from your &clm; template will be errors from the &clm; -&configure; or &buildnml;. For more information on these scripts see: - and -the section on &CLMBLDNML;. - - - - - -Trouble with Building - -Here's an example of running the build for a case and having it fail in the land model -build. As you can see it lists which model component is being built and the build log -for that component. - - CCSM BUILDEXE SCRIPT STARTING - - Build Libraries: mct pio csm_share -Sat Jun 19 21:21:19 MDT 2010 /ptmp/erik/test_build/mct/mct.bldlog.100619-212107 -Sat Jun 19 21:22:18 MDT 2010 /ptmp/erik/test_build/pio/pio.bldlog.100619-212107 -Sat Jun 19 21:23:18 MDT 2010 -/ptmp/erik/test_build/csm_share/csm_share.bldlog.100619-212107 -Sat Jun 19 21:24:00 MDT 2010 /ptmp/erik/test_build/run/cpl.bldlog.100619-212107 -Sat Jun 19 21:24:00 MDT 2010 /ptmp/erik/test_build/run/atm.bldlog.100619-212107 -Sat Jun 19 21:24:06 MDT 2010 /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 -ERROR: clm.buildexe.csh failed, see /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 -ERROR: cat /ptmp/erik/test_build/run/lnd.bldlog.100619-212107 - -You can then examine the build log that failed and see what went wrong. Most compilers -will give the full filepath and line number for the file that filed to compile. - - - - -Trouble with Running - -Tracking down problems while the model is running is much more difficult to do -than configure or build problems. In this section we will give some suggestions -on how to find run time problems. Below we show the log file results of a job -that aborted while running. - - CCSM PRESTAGE SCRIPT HAS FINISHED SUCCESSFULLY -Sun Jun 20 18:24:06 MDT 2010 -- CSM EXECUTION BEGINS HERE -Sun Jun 20 18:24:35 MDT 2010 -- CSM EXECUTION HAS FINISHED -Model did not complete - see /ptmp/erik/test_run/run/cpl.log.100620-182358 - -In the next section we will talk about using the different log files to track -down problems, and find out where the problem is coming from. In the section -after that we give some general advice on debugging problems and some suggestions -on ideas that may be helpful to track the problem down. Some of the examples -below are from the &KnownBugs; file. - - -Tracking Problems by Querying Log Files - -The first thing to do when tracking down problems is to query the different log -files to see if you can discover where the problem occurs, and any error messages about -it. It's important to figure out if the problem comes in at initialization or in the -run phase of the model, and in which model component the problem happens. There -are different log files for the different major components, and they all end -with the date and time in YYMMDD-HHMMSS format (2-digit: year, month, day, hour -minute and second). When the model runs to completion the log files will be copied -to the logs directory in the script directory, but when the -model fails they will remain in the run directory. Here's an example list of -log files from an "I" case where the model dies in the land model initialization. -For "I" cases the sea-ice and ocean components are just stubs and don't create -log files (and unless running with the active land-ice model "glc" log files won't -be created either). - -atm.log.100620-182358 -ccsm.log.100620-182358 -cpl.log.100620-182358 -lnd.log.100620-182358 - - - - -The coupler log file - -The first log file to check is the coupler log file so that you can see where -the model dies and which model component it fails in. When the model dies at -initialization the last model component listed is the component that failed. - - -Example of a case that fails in the &clm; land model initialization. - -(seq_timemgr_clockPrint) Prev Time = 00001201 00000 -(seq_timemgr_clockPrint) Next Time = 99991201 00000 -(seq_timemgr_clockPrint) Intervl yms = 9999 0 0 - -(seq_mct_drv) : Initialize each component: atm, lnd, ocn, and ice -(seq_mct_drv) : Initialize atm component -(seq_mct_drv) : Initialize lnd component - - - - - -The ccsm log file - -The ccsm log files are to some extent the "garbage collection" of log output. The -&clm; sends it's output from it's master processor, but sends other output and possibly -errors to the ccsm log file. Because, of this, often error messages are somewhere in the -ccsm log file. However, since there is so much other output it may be difficult to find. -For example, here is some output from an older version of &cesm; (&cesm102;) where the -RTM river routing file (before it was converted to &netcdf;) was not provided and -the error on the open statement for the file was embedded near the end of the ccsm log -file. - -NODE# NAME -( 0) be1105en.ucar.edu -"/gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/lnd/clm/src/riverroute/RtmMod.F90", line -239: 1525-155 The file name provided in the OPEN statement for unit 1 has zero length or -contains all blanks. The program will recover by ignoring the OPEN statement. -"/gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/lnd/clm/src/riverroute/RtmMod.F90", line -241: 1525-001 The READ statement on the file fort.1 cannot be completed because the end -of the file was reached. The program will stop. - -Running: ./ccsm.exe -Please wait... - -Memory usage for ./ccsm.exe (task # 0) is: 51696 KB. Exit status: 1. Signal: 0 - -Although the example is from an earlier version of the model it still serves to -illustrate finding problems from the ccsm log file. - - -When working with the ccsm log file, for a run-time problem, you will need to be able -to separate it's output into three categories: pre-crash, crash, and post-crash. The -pre-crash section is everything that is normal output for good operation of the model. -The crash section is the section where the model dies and reports on the actual problem. -the post-crash section is the cleanup and finalization after the model dies. The most -important part of this of course is the crash section. The tricky part is distinguishing -it from the other sections. Also because the ccsm log file most likely has duplicated -output from multiple processors it is even more difficult to distinguish the different -sections and to some extent the sections may be intertwined, as different processors -reach the different sections at different times. Because, of this reducing the number of -processors for your simulation may help you sort out the output in the file (see -). Also much of the output from the ccsm log file are -system level information having to do with &mpi; multiprocessing. Usually you can ignore -this information, but it makes it more difficult to trudge through. - - -Sometimes the ccsm log file is the ONLY file available, because the model terminates -early in initialization. In this case understanding the output in the ccsm log file -becomes even more important. This also indicates the model did NOT advance far enough -to reach the initialization of the individual model components. This may mean that the -initialization of the multiprocessing for &mpi; and/or &omp; failed, or that the -reading of the driver namelist file "drv_in" failed. - - -Here we show those three sections for a ccsm log file where a two task job failed on -reading the namelist file. For a typical job with many tasks similar sections of this -will be repeated not just twice but for each task and hence make it harder to read. - - -Pre-crash section of the ccsm log file - -ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. -ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. -ATTENTION: 0031-378 MP_EUIDEVICE setting ignored when LoadLeveler is not being used. -ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. - 0:INFO: 0031-724 Executing program: </usr/local/lsf/7.0/aix5-64/bin/lsnrt_run> - 1:INFO: 0031-724 Executing program: </usr/local/lsf/7.0/aix5-64/bin/lsnrt_run> - 0:/contrib/bin/ccsm_launch: process 401894 bound to logical CPU 0 on host be0310en.ucar.edu ... - 1:/contrib/bin/ccsm_launch: process 439264 bound to logical CPU 1 on host be0310en.ucar.edu ... - 0:INFO: 0031-619 64bit(us, Packet striping on) ppe_rmas MPCI_MSG: MPI/MPCI library was compiled on Wed Aug 5 13:36:06 2009 - 0: - 1:LAPI version #14.26 2008/11/23 11:02:30 1.296 src/rsct/lapi/lapi.c, lapi, rsct_rpt53, rpt53s004a 09/04/29 64bit(us) library compiled on Wed Apr 29 15:30:42 2009 - 1:. - 1:LAPI is using lightweight lock. - 0:LAPI version #14.26 2008/11/23 11:02:30 1.296 src/rsct/lapi/lapi.c, lapi, rsct_rpt53, rpt53s004a 09/04/29 64bit(us) library compiled on Wed Apr 29 15:30:42 2009 - 0:. - 0:LAPI is using lightweight lock. - 0:Use health ping for failover/recovery - 1:Use health ping for failover/recovery - 0:Initial communication over instance 2. - 1:Initial communication over instance 0. - 1:IB RDMA initialization completed successfully - 1:The MPI shared memory protocol is used for the job - 0:IB RDMA initialization completed successfully - 0:LAPI job ID for this job is: 1684890719 - 0:The MPI shared memory protocol is used for the job - 0:(seq_comm_setcomm) initialize ID ( 7 GLOBAL ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 2 ATM ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 1 LND ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 4 ICE ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 5 GLC ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 3 OCN ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_setcomm) initialize ID ( 6 CPL ) pelist = 0 1 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 8 CPLATM ) join IDs = 6 2 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 9 CPLLND ) join IDs = 6 1 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 10 CPLICE ) join IDs = 6 4 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 11 CPLOCN ) join IDs = 6 3 ( npes = 2) ( nthreads = 1) - 0:(seq_comm_joincomm) initialize ID ( 12 CPLGLC ) join IDs = 6 5 ( npes = 2) ( nthreads = 1) - 0: - 0: (seq_comm_printcomms) ID layout : global pes vs local pe for each ID - 0: gpe LND ATM OCN ICE GLC CPL GLOBAL CPLATM CPLLND CPLICE CPLOCN CPLGLC nthrds - 0: --- ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ - 0: 0 : 0 0 0 0 0 0 0 0 0 0 0 0 1 - 1: 1 : 1 1 1 1 1 1 1 1 1 1 1 1 1 - 1: - 0: (t_initf) Read in prof_inparm namelist from: drv_in - 1: (seq_io_init) cpl_io_stride, iotasks or root out of bounds - resetting to defaults 4 0 1 - 0: piolib_mod.f90 1353 1 2 1 2 - 1: piolib_mod.f90 1353 1 2 1 2 - 0: pio_support::pio_die:: myrank= 0 : ERROR: piolib_mod.f90: 1354 : not enough procs for the stride - 1: pio_support::pio_die:: myrank= 1 : ERROR: piolib_mod.f90: 1354 : not enough procs for the stride - - - -Crash section of the ccsm log file - - 0: - 0: Traceback: - 1: - 1: Traceback: - 0: Offset 0x00000c4c in procedure __pio_support_NMOD_piodie, near line 88 in file pio_support.F90.in - 1: Offset 0x00000c4c in procedure __pio_support_NMOD_piodie, near line 88 in file pio_support.F90.in - 0: Offset 0x00000fd0 in procedure __piolib_mod_NMOD_init, near line 1354 in file piolib_mod.F90 - 1: Offset 0x00000fd0 in procedure __piolib_mod_NMOD_init, near line 1354 in file piolib_mod.F90 - 1: Offset 0x00000398 in procedure __seq_io_mod_NMOD_seq_io_init, near line 247 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/shr/seq_io_mod.F90 - 0: Offset 0x00000398 in procedure __seq_io_mod_NMOD_seq_io_init, near line 247 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/shr/seq_io_mod.F90 - 0: Offset 0x0001aa88 in procedure ccsm_driver, near line 465 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/driver/ccsm_driver.F90 - 0: --- End of call chain --- - 1: Offset 0x0001aa88 in procedure ccsm_driver, near line 465 in file /gpfs/proj2/fis/cgd/home/erik/clm_trunk/models/drv/driver/ccsm_driver.F90 - 1: --- End of call chain --- - - - -Post-crash section of the ccsm log file - - 1:Communication statistics of task 1 is associated with task key: 1684890719_1 - 0:Communication statistics of task 0 is associated with task key: 1684890719_0 - 0: - 0:Running: ./ccsm.exe - 0:Please wait... - 0: - 0:Memory usage for ./ccsm.exe (task # 0) is: 198892 KB. Exit status: 134. Signal: 0 - 1: - 1:Running: ./ccsm.exe - 1:Please wait... - 1: - 1:Memory usage for ./ccsm.exe (task # 0) is: 198572 KB. Exit status: 134. Signal: 0 -INFO: 0031-656 I/O file STDOUT closed by task 0 -INFO: 0031-656 I/O file STDERR closed by task 0 -ERROR: 0031-250 task 0: IOT/Abort trap -INFO: 0031-656 I/O file STDOUT closed by task 1 -INFO: 0031-656 I/O file STDERR closed by task 1 -ERROR: 0031-250 task 1: IOT/Abort trap -INFO: 0031-639 Exit status from pm_respond = 0 -ATTENTION: 0031-386 MP_INSTANCES setting ignored when LoadLeveler is not being used. -Job /usr/local/lsf/7.0/aix5-64/bin/poejob /contrib/bin/ccsm_launch /contrib/bin/job_memusage.exe ./ccsm.exe - -TID HOST_NAME COMMAND_LINE STATUS TERMINATION_TIME -===== ========== ================ ======================= =================== -00000 be0310en /contrib/bin/ccs Exit (134) 08/31/2010 12:32:57 -00001 be0310en /contrib/bin/ccs Exit (134) 08/31/2010 12:32:57 - - - - - -The &clm; log file - -Of course when you are working with and making changes to &clm;, most of your focus -will be on the &clm; log file and the errors it shows. As already pointed out -if you don't see errors in the lnd.log.* file you should look -in the ccsm.log.* to see if any errors showed up there. - - -Here's an example of the lnd.log.* file when running -&PTSMODE; with initial conditions (this is bug 1025 in the &KnownBugs; file). - - Successfully initialized variables for accumulation - - reading restart file I2000CN_f09_g16_c100503.clm2.r.0001-01-01-00000.nc - Reading restart dataset - ERROR - setlatlon.F:Cant get variable dim for lat or lsmlat - ENDRUN: called without a message string - - - - - -The &datm; log file - -When working with "I cases" the second most common problems after &clm; problems are -problems with the data atmosphere model. So examining the atm.log.* -is important. - - -Here's an example of a problem that occurs when the wrong prescribed aerosol file -is given to a pt1_pt1 simulation. - -(datm_comp_init) atm mode = CLMNCEP -(shr_strdata_init) calling shr_dmodel_mapSet for fill -(shr_strdata_init) calling shr_dmodel_mapSet for remap - ('shr_map_getWts') ERROR: yd outside bounds 19.5000000000000000 -(shr_sys_abort) ERROR: ('shr_map_getWts') ERROR yd outside 90 degree bounds -(shr_sys_abort) WARNING: calling shr_mpi_abort() and stopping - - - - - -The batch log files - -The names of the batch log files will depend on the batch system of the machine -that is being used. They will normally be in the script directory. Usually, they -don't contain important information, but they are a last resort place to look for -error messages. On the &ncar; IBM system "bluefire" the batch files are called -with names that start with "poe" and then either "stderr" or "stdout", with the -job number at the end. - - - - - - -General Advice on Debugging Run time Problems - -Here are some suggestions on how to track down a problem while running. In general -if the problem still occurs for a simpler case, it will be easier to track down. - -Run in DEBUG mode -Run with a smaller set of processors -Run in serial mode with a single processor -Run at a lower resolution -Run a simpler case -Run with a debugger - - - - -Run in DEBUG mode - -The first thing to try is to run in DEBUG mode so that float point trapping will be -triggered as well as array bounds checking and other things the compiler can turn -on to help you find problems. To do this edit the &envbuild; file and set DEBUG - to TRUE as follows: - -> ./xmlchange -file env_build.xml -id DEBUG -val TRUE - - - - - -Run with a smaller set of processors - -Another way to simplify the system is to run with a smaller set of processors. You -will need to clean the configure and edit the env_mach_pes.xml. -For example, to run with four processors: - -> ./configure -cleanall -> ./xmlchange -file env_mach_pes.xml -id NTASKS_ATM -val 4 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_LND -val 4 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_ICE -val 4 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_OCN -val 4 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_CPL -val 4 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_GLC -val 4 -> ./configure -case - -Another recommended simplification is to run without threading, so set the -NTHRDS for each component to "1" if it isn't already. Sometimes, -multiprocessing problems require a certain number of processors before they occur -so you may not be able to debug the problem without enough processors. But, it's always -good to reduce it to as low a number as possible to make it simpler. For threading -problems you may have to have threading enabled to find the problem, but you can run -with 1, 2, or 3 threads to see what happens. - - - - -Run in serial mode with a single processor - -Simplifying to one processor removes all multi-processing problems and makes -the case as simple as possible. If you can enable USE_MPI_SERIAL -you will also be able to run interactively rather than having to submit to a job -queue, which sometimes makes it easier to run and debug. If you can use -USE_MPI_SERIAL you can also use threading, but still run interactively -in order to use more processors to make it faster if needed. - -> ./configure -cleanall -# Set tasks and threads for each component to 1 -# You could also set threads to something > 1 for speed, but still -# run interactively if threading isn't an issue. -> ./xmlchange -file env_mach_pes.xml -id NTASKS_ATM -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTHRDS_ATM -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_LND -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTHRDS_LND -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_ICE -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTHRDS_ICE -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_OCN -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTHRDS_OCN -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_CPL -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTHRDS_CPL -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTASKS_GLC -val 1 -> ./xmlchange -file env_mach_pes.xml -id NTHRDS_GLC -val 1 -# If mpi-serial capability is available on the machine you are using -# set USE_MPI_SERIAL to true so that you can run interactively -> ./xmlchange -file env_conf.xml -id USE_MPI_SERIAL -val TRUE -> ./configure -case -# Then build your case -# And finally run, by running the *.run script interactively -# (If you were able to set USE_MPI_SERIAL to true) - - - - - -Run at a lower resolution - -If you can create a new case running at a lower resolution and replicate the problem -it may be easier to solve. This of course requires creating a whole new case, and trying -out different lower resolutions. - - - - -Run a simpler case - -Along the same lines, you might try running a simpler case, trying another compset -with a simpler setup and see if you can replicate the problem and then debug from that -simpler case. Again, of course you will need to create new cases to do this. - - - - -Run with a debugger - -Another suggestion is to run the model with a debugger such as: dbx, -gdb, or totalview. Often to run with a debugger -you will need to reduce the number of processors as outlined above. Some debuggers such -as dbx will only work with one processor, while more advanced -debuggers such as totalview can work with both &mpi; tasks and OMP -threads. Even simple debuggers though can be used to query core files, to see where -the code was at when it died (for example using the where in -dbx for a core file can be very helpful. For help in running -with a debugger you will need to contact your system administrators for the machine -you are running on. - - - - - - - - From dd76d2a66cae1151980ac1430956fde2be5337e4 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 26 Mar 2020 17:13:37 -0600 Subject: [PATCH 236/255] Use git LFS to track image files --- .gitattributes | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..4ef52ab007 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +*.svg filter=lfs diff=lfs merge=lfs -text +*.png filter=lfs diff=lfs merge=lfs -text +*.jpg filter=lfs diff=lfs merge=lfs -text +*.jpeg filter=lfs diff=lfs merge=lfs -text +*.gif filter=lfs diff=lfs merge=lfs -text From 13a3883b3c629c6b72de951568e31db46e51b423 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 26 Mar 2020 16:25:45 -0600 Subject: [PATCH 237/255] By default, don't fetch files stored in LFS Based on https://github.com/git-lfs/git-lfs/issues/2717 The purpose of this is two-fold: (1) It keeps clones and fetches lighter-weight (2) It keeps our LFS bandwidth down, so we're less likely to need to upgrade our account (though that may be free for our educational account). --- .lfsconfig | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .lfsconfig diff --git a/.lfsconfig b/.lfsconfig new file mode 100644 index 0000000000..3d2778fad3 --- /dev/null +++ b/.lfsconfig @@ -0,0 +1,2 @@ +[lfs] + fetchexclude = * From eb196da132251be798dde444130603dbdd722d5f Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 26 Mar 2020 17:25:59 -0600 Subject: [PATCH 238/255] Store images directly in repository, managed by git LFS Get rid of the images external. Instead, put the images directly in the users guide / tech note source. These images will be managed by git LFS. --- .gitignore | 1 - Externals_CLM.cfg | 7 ------- .../tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst | 2 +- .../tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png | 3 +++ .../Decomposition/CLM4_vertsoil_soilstruct_drawing.png | 3 +++ .../Decomposition/CLM50_Tech_Note_Decomposition.rst | 4 ++-- .../tech_note/Decomposition/soil_C_pools_CN_century.png | 3 +++ .../tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst | 2 +- doc/source/tech_note/Ecosystem/image1.png | 3 +++ .../CLM50_Tech_Note_External_Nitrogen_Cycle.rst | 2 +- doc/source/tech_note/External_Nitrogen_Cycle/image1.png | 3 +++ doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst | 4 ++-- doc/source/tech_note/Fluxes/image1.png | 3 +++ doc/source/tech_note/Fluxes/image2.png | 3 +++ .../tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst | 4 ++-- doc/source/tech_note/Hydrology/hydrologic.processes.png | 3 +++ doc/source/tech_note/Hydrology/image1.png | 3 +++ doc/source/tech_note/Hydrology/image2.png | 3 +++ .../Introduction/CLM50_Tech_Note_Introduction.rst | 2 +- doc/source/tech_note/Introduction/image1.png | 3 +++ doc/source/tech_note/Isotopes/image1.png | 3 +++ doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst | 2 +- doc/source/tech_note/MOSART/mosart_diagram.png | 3 +++ doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst | 2 +- doc/source/tech_note/Methane/image1.png | 3 +++ .../Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst | 4 ++-- doc/source/tech_note/Plant_Hydraulics/circuit.jpg | 3 +++ .../Plant_Hydraulics/phs_iteration_schematic.svg | 3 +++ doc/source/tech_note/Plant_Respiration/image1.png | 3 +++ doc/source/tech_note/Plant_Respiration/image2.png | 3 +++ .../Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst | 2 +- doc/source/tech_note/Radiative_Fluxes/image1.png | 3 +++ .../Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst | 2 +- doc/source/tech_note/Snow_Hydrology/image1.png | 3 +++ .../CLM50_Tech_Note_Soil_Snow_Temperatures.rst | 2 +- doc/source/tech_note/Soil_Snow_Temperatures/image1.png | 3 +++ .../CLM50_Tech_Note_Transient_Landcover.rst | 6 +++--- doc/source/tech_note/Transient_Landcover/image1.png | 3 +++ doc/source/tech_note/Transient_Landcover/image2.png | 3 +++ doc/source/tech_note/Transient_Landcover/image3.png | 3 +++ doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst | 6 +++--- doc/source/tech_note/Urban/image1.png | 3 +++ doc/source/tech_note/Urban/image2.png | 3 +++ doc/source/tech_note/Urban/image3.png | 3 +++ .../CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst | 2 +- .../tech_note/Vegetation_Phenology_Turnover/image1.png | 3 +++ ...ning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst | 4 ++-- .../Spinning-up-the-biogeochemistry-BGC-spinup.rst | 8 ++++---- doc/source/users_guide/running-special-cases/image1.png | 3 +++ doc/source/users_guide/running-special-cases/image2.png | 3 +++ doc/source/users_guide/running-special-cases/image3.png | 3 +++ doc/source/users_guide/running-special-cases/image4.png | 3 +++ doc/source/users_guide/running-special-cases/image5.png | 3 +++ doc/source/users_guide/running-special-cases/image6.png | 3 +++ doc/source/users_guide/using-clm-tools/GlobalDomain.jpeg | 3 +++ .../using-clm-tools/LegendCLMToolDataFlow.jpeg | 3 +++ .../users_guide/using-clm-tools/creating-domain-files.rst | 4 ++-- .../creating-input-for-surface-dataset-generation.rst | 2 +- .../using-clm-tools/creating-surface-datasets.rst | 4 ++-- .../users_guide/using-clm-tools/mkmapdata_details.jpeg | 3 +++ .../users_guide/using-clm-tools/mkmapdata_mksurfdata.jpeg | 3 +++ doc/source/users_guide/using-clm-tools/mknoocnmap.jpeg | 3 +++ .../users_guide/using-clm-tools/mksurfdata_details.jpeg | 3 +++ 63 files changed, 155 insertions(+), 43 deletions(-) create mode 100644 doc/source/tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png create mode 100644 doc/source/tech_note/Decomposition/CLM4_vertsoil_soilstruct_drawing.png create mode 100644 doc/source/tech_note/Decomposition/soil_C_pools_CN_century.png create mode 100755 doc/source/tech_note/Ecosystem/image1.png create mode 100755 doc/source/tech_note/External_Nitrogen_Cycle/image1.png create mode 100755 doc/source/tech_note/Fluxes/image1.png create mode 100755 doc/source/tech_note/Fluxes/image2.png create mode 100644 doc/source/tech_note/Hydrology/hydrologic.processes.png create mode 100755 doc/source/tech_note/Hydrology/image1.png create mode 100755 doc/source/tech_note/Hydrology/image2.png create mode 100755 doc/source/tech_note/Introduction/image1.png create mode 100755 doc/source/tech_note/Isotopes/image1.png create mode 100644 doc/source/tech_note/MOSART/mosart_diagram.png create mode 100755 doc/source/tech_note/Methane/image1.png create mode 100644 doc/source/tech_note/Plant_Hydraulics/circuit.jpg create mode 100644 doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.svg create mode 100755 doc/source/tech_note/Plant_Respiration/image1.png create mode 100755 doc/source/tech_note/Plant_Respiration/image2.png create mode 100755 doc/source/tech_note/Radiative_Fluxes/image1.png create mode 100755 doc/source/tech_note/Snow_Hydrology/image1.png create mode 100755 doc/source/tech_note/Soil_Snow_Temperatures/image1.png create mode 100755 doc/source/tech_note/Transient_Landcover/image1.png create mode 100755 doc/source/tech_note/Transient_Landcover/image2.png create mode 100755 doc/source/tech_note/Transient_Landcover/image3.png create mode 100755 doc/source/tech_note/Urban/image1.png create mode 100755 doc/source/tech_note/Urban/image2.png create mode 100644 doc/source/tech_note/Urban/image3.png create mode 100755 doc/source/tech_note/Vegetation_Phenology_Turnover/image1.png create mode 100644 doc/source/users_guide/running-special-cases/image1.png create mode 100644 doc/source/users_guide/running-special-cases/image2.png create mode 100644 doc/source/users_guide/running-special-cases/image3.png create mode 100644 doc/source/users_guide/running-special-cases/image4.png create mode 100644 doc/source/users_guide/running-special-cases/image5.png create mode 100644 doc/source/users_guide/running-special-cases/image6.png create mode 100644 doc/source/users_guide/using-clm-tools/GlobalDomain.jpeg create mode 100644 doc/source/users_guide/using-clm-tools/LegendCLMToolDataFlow.jpeg create mode 100644 doc/source/users_guide/using-clm-tools/mkmapdata_details.jpeg create mode 100644 doc/source/users_guide/using-clm-tools/mkmapdata_mksurfdata.jpeg create mode 100644 doc/source/users_guide/using-clm-tools/mknoocnmap.jpeg create mode 100644 doc/source/users_guide/using-clm-tools/mksurfdata_details.jpeg diff --git a/.gitignore b/.gitignore index 2c7a551197..4a5672d970 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,6 @@ manage_externals.log /tools/PTCLM/ /cime/ /components/ -/doc/images/ # ignore svn directories **/.svn/** diff --git a/Externals_CLM.cfg b/Externals_CLM.cfg index 162fae65b1..84b7d5ec33 100644 --- a/Externals_CLM.cfg +++ b/Externals_CLM.cfg @@ -12,13 +12,6 @@ repo_url = https://github.com/ESCOMP/ptclm tag = PTCLM2_180611 required = True -[doc-images] -local_path = doc/images -protocol = git -repo_url = https://github.com/ESCOMP/CTSM-doc-images.git -hash = 476c694359e76c5054958e1397b8fa18aa0ff3e0 -required = False - [externals_description] schema_version = 1.0.0 diff --git a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst index 63024c7e0e..9bddee21ca 100644 --- a/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst +++ b/doc/source/tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.rst @@ -35,7 +35,7 @@ variables for vegetation carbon, and 22 for vegetation nitrogen. .. _Figure Vegetation fluxes and pools: -.. figure:: ../../../images/tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png +.. figure:: CLMCN_pool_structure_v2_lores.png :width: 753px :height: 513px diff --git a/doc/source/tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png b/doc/source/tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png new file mode 100644 index 0000000000..71a6c288a7 --- /dev/null +++ b/doc/source/tech_note/CN_Pools/CLMCN_pool_structure_v2_lores.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f275a1988475be5dae7979e94e5425342797f4db34fdafee1024915164f4257f +size 38450 diff --git a/doc/source/tech_note/Decomposition/CLM4_vertsoil_soilstruct_drawing.png b/doc/source/tech_note/Decomposition/CLM4_vertsoil_soilstruct_drawing.png new file mode 100644 index 0000000000..5bbd835f60 --- /dev/null +++ b/doc/source/tech_note/Decomposition/CLM4_vertsoil_soilstruct_drawing.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:60e79931915921514486ee7c42f7944b05ec7f3c86885bb9aedc55c0c70732a6 +size 141651 diff --git a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst index baeb744dcb..0d2ad98687 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -20,7 +20,7 @@ calculations (see Section :numref:`Soil Layers` for soil layering). .. _Figure Schematic of decomposition model in CLM: -.. figure:: ../../../images/tech_note/Decomposition/CLM4_vertsoil_soilstruct_drawing.png +.. figure:: CLM4_vertsoil_soilstruct_drawing.png Schematic of decomposition model in CLM. @@ -65,7 +65,7 @@ structures is in :ref:`Koven et al. (2013) `. .. _Figure Pool structure: -.. figure:: ../../../images/tech_note/Decomposition/soil_C_pools_CN_century.png +.. figure:: soil_C_pools_CN_century.png Pool structure, transitions, respired fractions (numbers at end of arrows), and turnover times (numbers in boxes) for the 2 diff --git a/doc/source/tech_note/Decomposition/soil_C_pools_CN_century.png b/doc/source/tech_note/Decomposition/soil_C_pools_CN_century.png new file mode 100644 index 0000000000..abc02ec15a --- /dev/null +++ b/doc/source/tech_note/Decomposition/soil_C_pools_CN_century.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:47635548f549ccf6cd70a57dbcdcdb22d12d306a3aa32b6a708c07baa174ffb8 +size 53905 diff --git a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst index 2fbbaeff9a..d90c8cab40 100644 --- a/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst +++ b/doc/source/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.rst @@ -53,7 +53,7 @@ classes. .. _Figure CLM subgrid hierarchy: -.. Figure:: ../../../images/tech_note/Ecosystem/image1.png +.. Figure:: image1.png Configuration of the CLM subgrid hierarchy. Box in upper right shows hypothetical subgrid distribution for a single grid cell. Note that the Crop land unit is only used when the model is run with the crop model active. Abbreviations: TBD – Tall Building District; HD – High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – Crop, V – Vegetated, PFT – Plant Functional Type, Irr – Irrigated, UIrr – Unirrigated. Red arrows indicate allowed land unit transitions. Purple arrows indicate allowed patch-level transitions. diff --git a/doc/source/tech_note/Ecosystem/image1.png b/doc/source/tech_note/Ecosystem/image1.png new file mode 100755 index 0000000000..4745f3f419 --- /dev/null +++ b/doc/source/tech_note/Ecosystem/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4e40ab5a4c6076f1f9990e727ed9823ed2b387fff8b4bc99e4f2cf647a52569d +size 254797 diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst index 8d1016380d..ca7a4a9d2c 100644 --- a/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst +++ b/doc/source/tech_note/External_Nitrogen_Cycle/CLM50_Tech_Note_External_Nitrogen_Cycle.rst @@ -118,7 +118,7 @@ Where :math:`{NF}_{nfix,sminn}` (gN m\ :sup:`-2` s\ :sup:`-1`) is the rate of fr .. _Figure Biological nitrogen fixation: -.. figure:: ../../../images/tech_note/External_Nitrogen_Cycle/image1.png +.. figure:: image1.png Free-living nitrogen fixation as a function of annual evapotranspiration. Results here show annual N inputs from free-living N fixations, but the model actually calculates inputs on a per second basis. diff --git a/doc/source/tech_note/External_Nitrogen_Cycle/image1.png b/doc/source/tech_note/External_Nitrogen_Cycle/image1.png new file mode 100755 index 0000000000..b28b5d1894 --- /dev/null +++ b/doc/source/tech_note/External_Nitrogen_Cycle/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f3acfbbb90ad0c44ff7179a257c44f59d4b0b5a0da348825b02aa5034bee1640 +size 29009 diff --git a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst index a0b7e04ac3..d967cd5ff0 100644 --- a/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst +++ b/doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst @@ -961,14 +961,14 @@ height :math:`z_{0h} ^{{'} }` and the canopy air at height .. _Figure Schematic diagram of sensible heat fluxes: -.. figure:: ../../../images/tech_note/Fluxes/image1.png +.. figure:: image1.png Figure Schematic diagram of sensible heat fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. .. _Figure Schematic diagram of latent heat fluxes: -.. figure:: ../../../images/tech_note/Fluxes/image2.png +.. figure:: image2.png Figure Schematic diagram of water vapor fluxes for (a) non-vegetated surfaces and (b) vegetated surfaces. diff --git a/doc/source/tech_note/Fluxes/image1.png b/doc/source/tech_note/Fluxes/image1.png new file mode 100755 index 0000000000..b74d0a0c92 --- /dev/null +++ b/doc/source/tech_note/Fluxes/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6e1c868e187fac803a6b051b0148936909d3994bc2e89de2d58bf2c96bcfaef7 +size 9847 diff --git a/doc/source/tech_note/Fluxes/image2.png b/doc/source/tech_note/Fluxes/image2.png new file mode 100755 index 0000000000..b1698d8a95 --- /dev/null +++ b/doc/source/tech_note/Fluxes/image2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c195ab48a35ca413acd9fc3509643369b1359be005770b31d511d5cee89cbeb1 +size 15100 diff --git a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst index 6e0b593d29..c4e0824ea7 100644 --- a/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst +++ b/doc/source/tech_note/Hydrology/CLM50_Tech_Note_Hydrology.rst @@ -38,7 +38,7 @@ al. 2008) ` and :math:`\Delta t` is the time step (s). .. _Figure Hydrologic processes: -.. Figure:: ../../../images/tech_note/Hydrology/hydrologic.processes.png +.. Figure:: hydrologic.processes.png Hydrologic processes represented in CLM. @@ -798,7 +798,7 @@ the effective root fraction :math:`r_{e,\, i}` .. _Figure Water flux schematic: -.. Figure:: ../../../images/tech_note/Hydrology/image2.png +.. Figure:: image2.png Schematic diagram of numerical scheme used to solve for soil water fluxes. diff --git a/doc/source/tech_note/Hydrology/hydrologic.processes.png b/doc/source/tech_note/Hydrology/hydrologic.processes.png new file mode 100644 index 0000000000..4617f7394a --- /dev/null +++ b/doc/source/tech_note/Hydrology/hydrologic.processes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:328caf5897f168486357c782c99936183a55931fcdd1727015ca1778c816b6bc +size 93244 diff --git a/doc/source/tech_note/Hydrology/image1.png b/doc/source/tech_note/Hydrology/image1.png new file mode 100755 index 0000000000..f18bfd3617 --- /dev/null +++ b/doc/source/tech_note/Hydrology/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21f039196cb89474168e1b93c55b506a7cf802205b09bbc43b40b7c8655605d4 +size 41171 diff --git a/doc/source/tech_note/Hydrology/image2.png b/doc/source/tech_note/Hydrology/image2.png new file mode 100755 index 0000000000..8f10f2f87e --- /dev/null +++ b/doc/source/tech_note/Hydrology/image2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c5833196770f045373914ae7b4cbcd8bfad4f1259fc03c48969930103107e7e2 +size 9152 diff --git a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst index df3201827e..7240dfa8d9 100644 --- a/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst +++ b/doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst @@ -627,6 +627,6 @@ processes simulated include (:numref:`Figure Land processes`): .. _Figure Land processes: -.. figure:: ../../../images/tech_note/Introduction/image1.png +.. figure:: image1.png Land biogeophysical, biogeochemical, and landscape processes simulated by CLM (adapted from :ref:`Lawrence et al. (2011)` for CLM5.0). diff --git a/doc/source/tech_note/Introduction/image1.png b/doc/source/tech_note/Introduction/image1.png new file mode 100755 index 0000000000..9b2971a1b2 --- /dev/null +++ b/doc/source/tech_note/Introduction/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e2ee10ffecdda7bd8994490508186da98ea538f5868ec90ef9d633ba0cc3811a +size 171166 diff --git a/doc/source/tech_note/Isotopes/image1.png b/doc/source/tech_note/Isotopes/image1.png new file mode 100755 index 0000000000..53a4e3bade --- /dev/null +++ b/doc/source/tech_note/Isotopes/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e1f7d7602d156eb1ea23f50089e16c2809c02e61facf21dc3289ac76af30588b +size 8538 diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst index dbd07703ee..439de8a7a1 100644 --- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst +++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst @@ -47,7 +47,7 @@ and discharges the water to its downstream spatial unit or the ocean. .. _Figure MOSART conceptual diagram: -.. figure:: ../../../images/tech_note/MOSART/mosart_diagram.png +.. figure:: mosart_diagram.png :width: 800px :height: 400px diff --git a/doc/source/tech_note/MOSART/mosart_diagram.png b/doc/source/tech_note/MOSART/mosart_diagram.png new file mode 100644 index 0000000000..ac33eee692 --- /dev/null +++ b/doc/source/tech_note/MOSART/mosart_diagram.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:438d5d1165d0bce83ee713444ac3d79f81205cb7040ee230e2713b166062d78d +size 212280 diff --git a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst index 8c92a24556..7c89f857e3 100644 --- a/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst +++ b/doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst @@ -89,7 +89,7 @@ into the inundated concentration when the inundated fraction increases. .. _Figure Methane Schematic: -.. figure:: ../../../images/tech_note/Methane/image1.png +.. figure:: image1.png Schematic representation of biological and physical processes integrated in CLM that affect the net CH\ :sub:`4` diff --git a/doc/source/tech_note/Methane/image1.png b/doc/source/tech_note/Methane/image1.png new file mode 100755 index 0000000000..73fdbba723 --- /dev/null +++ b/doc/source/tech_note/Methane/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a25dc959f42d9b3b8eaa8e30867f36bf6d002282d4aa199f48818e9f7a7cc051 +size 151331 diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index c2ea4ec1bd..6c56e7b904 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -159,7 +159,7 @@ on leaf water potential. .. _Figure Plant hydraulic circuit: -.. figure:: ../../../images/tech_note/Plant_Hydraulics/circuit.jpg +.. figure:: circuit.jpg Circuit diagram of plant hydraulics scheme @@ -714,6 +714,6 @@ The outermost level of iteration works towards convergence of leaf temperature, .. _Figure PHS Flow Diagram: -.. figure:: ../../../images/tech_note/Plant_Hydraulics/phs_iteration_schematic.svg +.. figure:: phs_iteration_schematic.svg Flow diagram of leaf flux calculations diff --git a/doc/source/tech_note/Plant_Hydraulics/circuit.jpg b/doc/source/tech_note/Plant_Hydraulics/circuit.jpg new file mode 100644 index 0000000000..aa53b48d4b --- /dev/null +++ b/doc/source/tech_note/Plant_Hydraulics/circuit.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82acf5e36c7676057f37d760d7cfa1bf6923ec513a86f8d2190c8b8028229b39 +size 52862 diff --git a/doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.svg b/doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.svg new file mode 100644 index 0000000000..f88c0a1492 --- /dev/null +++ b/doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c95178fd7b6fcfd8858babab319669684b8d490fbbff6f4f31a35132f7049b59 +size 276151 diff --git a/doc/source/tech_note/Plant_Respiration/image1.png b/doc/source/tech_note/Plant_Respiration/image1.png new file mode 100755 index 0000000000..cf2e4ed9cc --- /dev/null +++ b/doc/source/tech_note/Plant_Respiration/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4cb87e15bbaa818c2c8fc34cd75f247a85057a19d0ca143ce3f3270102773785 +size 7125 diff --git a/doc/source/tech_note/Plant_Respiration/image2.png b/doc/source/tech_note/Plant_Respiration/image2.png new file mode 100755 index 0000000000..cee74c0178 --- /dev/null +++ b/doc/source/tech_note/Plant_Respiration/image2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:54aec7a404e377c6f87b68377c6117060f0ee4b531235fa69fa9f4cb804db396 +size 47589 diff --git a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst index a687d5bc2d..5e368456ba 100644 --- a/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst +++ b/doc/source/tech_note/Radiative_Fluxes/CLM50_Tech_Note_Radiative_Fluxes.rst @@ -37,7 +37,7 @@ depth of direct beam per unit leaf and stem area (section :numref:`Canopy Radiat .. _Figure Radiation Schematic: -.. figure:: ../../../images/tech_note/Radiative_Fluxes/image1.png +.. figure:: image1.png Schematic diagram of (a) direct beam radiation, (b) diffuse solar radiation, and (c) longwave radiation absorbed, transmitted, and diff --git a/doc/source/tech_note/Radiative_Fluxes/image1.png b/doc/source/tech_note/Radiative_Fluxes/image1.png new file mode 100755 index 0000000000..a1c66d96b9 --- /dev/null +++ b/doc/source/tech_note/Radiative_Fluxes/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c567ff0794cf34fbd41b31656d0ee02461d3cf3c140e836973280faa2d8ba6dd +size 11143 diff --git a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst index 2d58d36795..8d22a19bc9 100644 --- a/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst +++ b/doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst @@ -18,7 +18,7 @@ snow pack. .. _Figure three layer snow pack: -.. Figure:: ../../../images/tech_note/Snow_Hydrology/image1.png +.. Figure:: image1.png Example of three layer snow pack (:math:`snl=-3`). diff --git a/doc/source/tech_note/Snow_Hydrology/image1.png b/doc/source/tech_note/Snow_Hydrology/image1.png new file mode 100755 index 0000000000..655911ecca --- /dev/null +++ b/doc/source/tech_note/Snow_Hydrology/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b9283f5c65c099c866251e63916fcf1495add87bff685abe8cc191115ee6298a +size 8599 diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst index efbb382f45..56b6adff3f 100644 --- a/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst +++ b/doc/source/tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.rst @@ -223,7 +223,7 @@ interface of two layers .. _Figure Soil Temperature Schematic: -.. figure:: ../../../images/tech_note/Soil_Snow_Temperatures/image1.png +.. figure:: image1.png Schematic diagram of numerical scheme used to solve for soil temperature. diff --git a/doc/source/tech_note/Soil_Snow_Temperatures/image1.png b/doc/source/tech_note/Soil_Snow_Temperatures/image1.png new file mode 100755 index 0000000000..adfbc2bf08 --- /dev/null +++ b/doc/source/tech_note/Soil_Snow_Temperatures/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:50f5744a0542e005e22057e9f9b70ba0f676eba143d8e8b25dc12284d898a9f5 +size 8725 diff --git a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst index 637dd28d05..de7ef86173 100644 --- a/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst +++ b/doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst @@ -347,18 +347,18 @@ data files in the mksurfdata_map tool. .. _Figure Schematic of land cover change: -.. figure:: ../../../images/tech_note/Transient_Landcover/image1.png +.. figure:: image1.png Schematic of land cover change impacts on CLM carbon pools and fluxes. .. _Figure Schematic of translation of annual LUH2 land units: -.. figure:: ../../../images/tech_note/Transient_Landcover/image2.png +.. figure:: image2.png Schematic of translation of annual LUH2 land units to CLM5 plant and crop functional types. .. _Figure Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool: -.. figure:: ../../../images/tech_note/Transient_Landcover/image3.png +.. figure:: image3.png Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool diff --git a/doc/source/tech_note/Transient_Landcover/image1.png b/doc/source/tech_note/Transient_Landcover/image1.png new file mode 100755 index 0000000000..bdb419ffbf --- /dev/null +++ b/doc/source/tech_note/Transient_Landcover/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:69d48a8706cd8bbcc8b3157070f06e55d6955ea15826eddea261cb2c6a86dd09 +size 44693 diff --git a/doc/source/tech_note/Transient_Landcover/image2.png b/doc/source/tech_note/Transient_Landcover/image2.png new file mode 100755 index 0000000000..cb88aa7b4c --- /dev/null +++ b/doc/source/tech_note/Transient_Landcover/image2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7695d3b33bd6c1a8ea0fd1e4cac2bb1ee9f33776e6e2f9f08359dea402d461f3 +size 35882 diff --git a/doc/source/tech_note/Transient_Landcover/image3.png b/doc/source/tech_note/Transient_Landcover/image3.png new file mode 100755 index 0000000000..f06f71b6c5 --- /dev/null +++ b/doc/source/tech_note/Transient_Landcover/image3.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:749cd9858eb4d55af4eb72ca900c180e8bb69aa6483ce0cfd05b40a338b24c7a +size 64824 diff --git a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst index 7b74bdf4ab..e5f4ac33e5 100644 --- a/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst +++ b/doc/source/tech_note/Urban/CLM50_Tech_Note_Urban.rst @@ -128,7 +128,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic representation of the urban landunit: -.. figure:: ../../../images/tech_note/Urban/image1.png +.. figure:: image1.png Schematic representation of the urban land unit. See the text for description of notation. Incident, reflected, and net solar and longwave radiation are calculated for each individual surface but are not shown for clarity. @@ -136,7 +136,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic of urban and atmospheric model coupling: -.. Figure:: ../../../images/tech_note/Urban/image2.png +.. Figure:: image2.png Schematic of urban and atmospheric model coupling. The urban model is forced by the atmospheric model wind (:math:`u_{atm}` ), temperature (:math:`T_{atm}` ), specific humidity (:math:`q_{atm}` ), precipitation (:math:`P_{atm}` ), solar (:math:`S_{atm} \, \downarrow` ) and longwave (:math:`L_{atm} \, \downarrow` ) radiation at reference height :math:`z'_{atm}` (section :numref:`Atmospheric Coupling`). Fluxes from the urban landunit to the atmosphere are turbulent sensible (:math:`H`) and latent heat (:math:`\lambda E`), momentum (:math:`\tau` ), albedo (:math:`I\uparrow` ), emitted longwave (:math:`L\uparrow` ), and absorbed shortwave (:math:`\vec{S}`) radiation. Air temperature (:math:`T_{ac}` ), specific humidity (:math:`q_{ac}` ), and wind speed (:math:`u_{c}` ) within the urban canopy layer are diagnosed by the urban model. :math:`H` is the average building height. @@ -144,7 +144,7 @@ interior building temperature at yearly time resolution. .. _Figure schematic of THESIS urban properties tool: -.. Figure:: ../../../images/tech_note/Urban/image3.png +.. Figure:: image3.png Schematic of THESIS urban properties tool. Executable scripts are in orange, input files are blue, and output files are green. Items within the black box outline are either read in as input, executed, or output by the driver script (urban_prop.csh). diff --git a/doc/source/tech_note/Urban/image1.png b/doc/source/tech_note/Urban/image1.png new file mode 100755 index 0000000000..64feb80128 --- /dev/null +++ b/doc/source/tech_note/Urban/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3ff37606b73060c4cfb71b1b4f2a86f8cf2f043f3bbe0996bffece953e598aed +size 18462 diff --git a/doc/source/tech_note/Urban/image2.png b/doc/source/tech_note/Urban/image2.png new file mode 100755 index 0000000000..c8e4ecafc2 --- /dev/null +++ b/doc/source/tech_note/Urban/image2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:75441a9fd1b237b7c9d20ed24f5a0605e964174d1061e1304ab03edaf86b9060 +size 17235 diff --git a/doc/source/tech_note/Urban/image3.png b/doc/source/tech_note/Urban/image3.png new file mode 100644 index 0000000000..2f73f14961 --- /dev/null +++ b/doc/source/tech_note/Urban/image3.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:99da4f166c41855656434081e91da268266108d43a96e0f0e53d888df7fa71c1 +size 243653 diff --git a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst index ffa2a5c96d..7ede3405e0 100644 --- a/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst +++ b/doc/source/tech_note/Vegetation_Phenology_Turnover/CLM50_Tech_Note_Vegetation_Phenology_Turnover.rst @@ -33,7 +33,7 @@ storage over the course of a single growing season. .. _Figure annual phenology cycle: -.. figure:: ../../../images/tech_note/Vegetation_Phenology_Turnover/image1.png +.. figure:: image1.png Example of annual phenology cycle for seasonal deciduous. diff --git a/doc/source/tech_note/Vegetation_Phenology_Turnover/image1.png b/doc/source/tech_note/Vegetation_Phenology_Turnover/image1.png new file mode 100755 index 0000000000..c10923a819 --- /dev/null +++ b/doc/source/tech_note/Vegetation_Phenology_Turnover/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b2b957eea477e79313ec8d3731e28a4c04a7f4204a8fbc89a53bcc37b494565 +size 9363 diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst index a93610f9fa..d6b6c74d91 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst @@ -19,7 +19,7 @@ a specified equilibrium state (denoted by the dotted lines) due to the different .. _Figure SP spinup plot for 1850: -.. figure:: ../../../images/users_guide/running-special-cases/image1.png +.. figure:: image1.png SP spinup plot for year 1850. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl. @@ -28,6 +28,6 @@ Again, it takes about 10 years to reach equilibrium. .. _Figure SP spinup plot for 2000 CO2: -.. figure:: ../../../images/users_guide/running-special-cases/image2.png +.. figure:: image2.png SP spinup plot for year 2000 CO2. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl. diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst index 3ad4bdb5a5..9808ceb05b 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst @@ -12,7 +12,7 @@ total ecosystem carbon disequilibrium takes the longest to satisfy due to slow s .. _Figure BGC AD spinup plot for 1850 GSWP3: -.. figure:: ../../../images/users_guide/running-special-cases/image3.png +.. figure:: image3.png BGC AD spinup plot for a year 1850 case with GSWP3 atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. @@ -24,7 +24,7 @@ criteria depending on their application. .. _Figure BGC pAD spinup plot for 1850 GSWP3: -.. figure:: ../../../images/users_guide/running-special-cases/image4.png +.. figure:: image4.png BGC pAD spinup plot for a year 1850 case with GSWP3 atmospheric forcing and initialization from the end of the BGC AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. @@ -35,7 +35,7 @@ such as TLAI (total leaf area index), GPP (gross primary production), and TWS (t .. _Figure BGC initialized spinup plot for 1850: -.. figure:: ../../../images/users_guide/running-special-cases/image5.png +.. figure:: image5.png BGC initialized spinup plot for year 1850. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. @@ -44,7 +44,7 @@ Again, it takes about 10 years to reach equilibrium for TLAI, GPP, and TWS. .. _Figure BGC initialized spinup plot for 2000 CO2: -.. figure:: ../../../images/users_guide/running-special-cases/image6.png +.. figure:: image6.png BGC initialized spinup plot for year 2000 CO2. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability.ncl. diff --git a/doc/source/users_guide/running-special-cases/image1.png b/doc/source/users_guide/running-special-cases/image1.png new file mode 100644 index 0000000000..fba40ddfa1 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/image1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7d17c1ff7945bfa5d86958f8cc90b96fbd58bbeb81003aaf2cdcc2e6104788da +size 318875 diff --git a/doc/source/users_guide/running-special-cases/image2.png b/doc/source/users_guide/running-special-cases/image2.png new file mode 100644 index 0000000000..79cc812929 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/image2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bf3d0b888e7c442838f1fa4290987b29c4a54f82a49aac7d5070db5e3e5abfe1 +size 320601 diff --git a/doc/source/users_guide/running-special-cases/image3.png b/doc/source/users_guide/running-special-cases/image3.png new file mode 100644 index 0000000000..0c11688829 --- /dev/null +++ b/doc/source/users_guide/running-special-cases/image3.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:347a4e32e072c6b5d9f87ae7fd36ee3621c8436910691b18f63d9365f853d8de +size 280086 diff --git a/doc/source/users_guide/running-special-cases/image4.png b/doc/source/users_guide/running-special-cases/image4.png new file mode 100644 index 0000000000..09456b93af --- /dev/null +++ b/doc/source/users_guide/running-special-cases/image4.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4587fe62aa8c34906e56d13c99749b69d2600f4c770c50781d81faf2480b8842 +size 287344 diff --git a/doc/source/users_guide/running-special-cases/image5.png b/doc/source/users_guide/running-special-cases/image5.png new file mode 100644 index 0000000000..f0d073565f --- /dev/null +++ b/doc/source/users_guide/running-special-cases/image5.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:991c6fa7d321f0a0e50f38c82f951eb978ba3ae62efe184bc941fcacaf4352c5 +size 316593 diff --git a/doc/source/users_guide/running-special-cases/image6.png b/doc/source/users_guide/running-special-cases/image6.png new file mode 100644 index 0000000000..949acde48d --- /dev/null +++ b/doc/source/users_guide/running-special-cases/image6.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:65a5121d47597ae3d508a8bda8989708c928e3f0b9e183009dfc4bcd661ad4b6 +size 311278 diff --git a/doc/source/users_guide/using-clm-tools/GlobalDomain.jpeg b/doc/source/users_guide/using-clm-tools/GlobalDomain.jpeg new file mode 100644 index 0000000000..7e2df5ad90 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/GlobalDomain.jpeg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9000cdb3c7761a9838e9af059f36dfcc204c7a02bdab6d5206da0de1bf3051ac +size 38541 diff --git a/doc/source/users_guide/using-clm-tools/LegendCLMToolDataFlow.jpeg b/doc/source/users_guide/using-clm-tools/LegendCLMToolDataFlow.jpeg new file mode 100644 index 0000000000..e0f1559cbd --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/LegendCLMToolDataFlow.jpeg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d71ecdf638e4582f66f1c2b101b6548bd9d47fe2cb3de0f58386048f6ce6cfbc +size 15711 diff --git a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst index 2feef0b554..972967da0c 100644 --- a/doc/source/users_guide/using-clm-tools/creating-domain-files.rst +++ b/doc/source/users_guide/using-clm-tools/creating-domain-files.rst @@ -16,7 +16,7 @@ Global Domain file creation .. _Figure Global-Domain: -.. figure:: ../../../images/users_guide/using-clm-tools/GlobalDomain.jpeg +.. figure:: GlobalDomain.jpeg Global Domain file creation @@ -29,7 +29,7 @@ Domain file creation using mknoocnmap.pl .. _Figure mknoocnmap.pl: -.. figure:: ../../../images/users_guide/using-clm-tools/mknoocnmap.jpeg +.. figure:: mknoocnmap.jpeg Domain file creation using mknoocnmap.pl diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst index 229d077514..6048baa98c 100644 --- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst +++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst @@ -107,7 +107,7 @@ mkmapdata.sh has a help option with the following .. _Figure mkmapdata.sh: -.. figure:: ../../../images/users_guide/using-clm-tools/mkmapdata_details.jpeg +.. figure:: mkmapdata_details.jpeg Details of running mkmapdata.sh diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst index ebd200b8f5..c974b9c886 100644 --- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst @@ -10,7 +10,7 @@ When just creating a replacement file for an existing one, the relevant tool sho .. _Figure Data_Flow: -.. figure:: ../../../images/users_guide/using-clm-tools/mkmapdata_mksurfdata.jpeg +.. figure:: mkmapdata_mksurfdata.jpeg Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files @@ -20,7 +20,7 @@ Starting from a SCRIP grid file that describes the grid you will run the model o .. _Figure Data_Flow_Legend: -.. figure:: ../../../images/users_guide/using-clm-tools/LegendCLMToolDataFlow.jpeg +.. figure:: LegendCLMToolDataFlow.jpeg Legend for Data Flow Figures diff --git a/doc/source/users_guide/using-clm-tools/mkmapdata_details.jpeg b/doc/source/users_guide/using-clm-tools/mkmapdata_details.jpeg new file mode 100644 index 0000000000..b8d33578b8 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/mkmapdata_details.jpeg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:56399b80b49aa4705b27a0e98758b120f78c4eb62d993f85944db2c1d2122d0f +size 51018 diff --git a/doc/source/users_guide/using-clm-tools/mkmapdata_mksurfdata.jpeg b/doc/source/users_guide/using-clm-tools/mkmapdata_mksurfdata.jpeg new file mode 100644 index 0000000000..7e59cee7f3 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/mkmapdata_mksurfdata.jpeg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d85feb3d5c6aba70963f51b10406cd45ff334c60f2daf965ccb9b1abbc158985 +size 41951 diff --git a/doc/source/users_guide/using-clm-tools/mknoocnmap.jpeg b/doc/source/users_guide/using-clm-tools/mknoocnmap.jpeg new file mode 100644 index 0000000000..308fde0e1c --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/mknoocnmap.jpeg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2c4d6c677d6e68761f9c6677be4bc94d93cd75c26989c834cd3e022db432359d +size 33914 diff --git a/doc/source/users_guide/using-clm-tools/mksurfdata_details.jpeg b/doc/source/users_guide/using-clm-tools/mksurfdata_details.jpeg new file mode 100644 index 0000000000..9d6e829891 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/mksurfdata_details.jpeg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:32104479195bd2612b09df1322b97c5b2db220d8d0115e32e6020e17ade597e0 +size 41837 From 50e7e62f2bf58245baee54c4b53b83feca9566c5 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Fri, 27 Mar 2020 11:20:32 -0600 Subject: [PATCH 239/255] Before building html or pdf, automatically obtain all of the images This is needed because we have configured this repository (via an .lfsconfig file at the top level) to NOT automatically fetch any of the large files when cloning / fetching. --- doc/Makefile | 11 ++++++++++- doc/Makefile.tech_note | 11 ++++++++++- doc/Makefile.users_guide | 11 ++++++++++- 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 6e8d96d485..65aa7572bf 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,7 +12,16 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +# Before building html or pdf, obtain all of the images. This is needed +# because we have configured this repository (via an .lfsconfig file at +# the top level) to NOT automatically fetch any of the large files when +# cloning / fetching. +html: fetch-images +latexpdf: fetch-images +fetch-images: + git lfs pull --exclude="" + +.PHONY: help fetch-images Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/doc/Makefile.tech_note b/doc/Makefile.tech_note index 3ba843c70e..e19b31e182 100644 --- a/doc/Makefile.tech_note +++ b/doc/Makefile.tech_note @@ -12,7 +12,16 @@ BUILDDIR = build/tech_note help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +# Before building html or pdf, obtain all of the images. This is needed +# because we have configured this repository (via an .lfsconfig file at +# the top level) to NOT automatically fetch any of the large files when +# cloning / fetching. +html: fetch-images +latexpdf: fetch-images +fetch-images: + git lfs pull --exclude="" + +.PHONY: help fetch-images Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/doc/Makefile.users_guide b/doc/Makefile.users_guide index babfffa52c..2fa8bb453f 100644 --- a/doc/Makefile.users_guide +++ b/doc/Makefile.users_guide @@ -12,7 +12,16 @@ BUILDDIR = build/users_guide help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +# Before building html or pdf, obtain all of the images. This is needed +# because we have configured this repository (via an .lfsconfig file at +# the top level) to NOT automatically fetch any of the large files when +# cloning / fetching. +html: fetch-images +latexpdf: fetch-images +fetch-images: + git lfs pull --exclude="" + +.PHONY: help fetch-images Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). From 89602f80ec9e4bf1e9f304b23d3e2b1fa40ba855 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Fri, 27 Mar 2020 11:53:58 -0600 Subject: [PATCH 240/255] Use git lfs to track pdf files I'm going to add a pdf image file, so this is needed for that purpose. --- .gitattributes | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitattributes b/.gitattributes index 4ef52ab007..e9f0bd7694 100644 --- a/.gitattributes +++ b/.gitattributes @@ -3,3 +3,4 @@ *.jpg filter=lfs diff=lfs merge=lfs -text *.jpeg filter=lfs diff=lfs merge=lfs -text *.gif filter=lfs diff=lfs merge=lfs -text +*.pdf filter=lfs diff=lfs merge=lfs -text From ade8e8963ba540447e73f3d14987b4fcb133c3b9 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Fri, 27 Mar 2020 12:02:45 -0600 Subject: [PATCH 241/255] Add a pdf version of phs_iteration_schematic This is needed for the pdf build: latexpdf cannot read svg files. I converted this using Inkscape (simply using "save as" and saving it as a pdf). --- .../CLM50_Tech_Note_Plant_Hydraulics.rst | 2 +- .../README.phs_iteration_schematic | 9 +++++++++ .../Plant_Hydraulics/phs_iteration_schematic.pdf | Bin 0 -> 131 bytes 3 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 doc/source/tech_note/Plant_Hydraulics/README.phs_iteration_schematic create mode 100644 doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.pdf diff --git a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst index 6c56e7b904..88d09d18a5 100644 --- a/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst +++ b/doc/source/tech_note/Plant_Hydraulics/CLM50_Tech_Note_Plant_Hydraulics.rst @@ -714,6 +714,6 @@ The outermost level of iteration works towards convergence of leaf temperature, .. _Figure PHS Flow Diagram: -.. figure:: phs_iteration_schematic.svg +.. figure:: phs_iteration_schematic.* Flow diagram of leaf flux calculations diff --git a/doc/source/tech_note/Plant_Hydraulics/README.phs_iteration_schematic b/doc/source/tech_note/Plant_Hydraulics/README.phs_iteration_schematic new file mode 100644 index 0000000000..c04c25d117 --- /dev/null +++ b/doc/source/tech_note/Plant_Hydraulics/README.phs_iteration_schematic @@ -0,0 +1,9 @@ +Daniel Kennedy provided the original file, +phs_iteration_schematic.svg. This can be used to generate the html +documentation. Bill Sacks then converted it to pdf using Inkscape +(simply using "save as" and saving it as a pdf); the pdf is needed when +generating a pdf (since latexpdf cannot use svg files). + +Note that the figure is referenced in the rst as +phs_iteration_schematic.*; each builder then uses the appropriate file +(svg or pdf as needed). diff --git a/doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.pdf b/doc/source/tech_note/Plant_Hydraulics/phs_iteration_schematic.pdf new file mode 100644 index 0000000000000000000000000000000000000000..8505f8df531f6ceadc5df6ebf70c1f4c09f14793 GIT binary patch literal 131 zcmWN_OAf*y5CG6Ur{DsX?*R5T!#D_uO5?O$czU~f$vgQgV}5ks_f1w~o@2kgnk<+7 zs0+=vk&VfmPR;Sq($Pa&3t$0nLuRUgKG>S>luL6^m?$#?x|A`LgehhhTcY41QlSXV NT2eB8tX;6zsy_j+Ctd&m literal 0 HcmV?d00001 From fb4e647ea8b95bec413669fdb99bb917c839b8ff Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sat, 28 Mar 2020 14:39:38 -0600 Subject: [PATCH 242/255] Remove near-duplicated Makefiles and conf.py files Previously, we had been (sort of) supporting builds of just the User's Guide or just the Tech Note via near-duplicated copies of the Makefile and conf.py file. However, these didn't really seem to work right for an html build (the files ended up in the wrong directory structure), and this was going to be harder to support and maintain moving forward, because of the duplication. Erik Kluzek and Keith Oleson have confirmed that they don't actually need support for an html build of just part of the documentation. I have made changes to the main Makefile to support just building a pdf of the tech note (not including the User's Guide), which IS needed. --- doc/Makefile | 13 +++ doc/Makefile.tech_note | 29 ------ doc/Makefile.users_guide | 29 ------ doc/source/tech_note/conf.py | 171 -------------------------------- doc/source/users_guide/conf.py | 174 --------------------------------- 5 files changed, 13 insertions(+), 403 deletions(-) delete mode 100644 doc/Makefile.tech_note delete mode 100644 doc/Makefile.users_guide delete mode 100644 doc/source/tech_note/conf.py delete mode 100644 doc/source/users_guide/conf.py diff --git a/doc/Makefile b/doc/Makefile index 65aa7572bf..47304542de 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -23,6 +23,19 @@ fetch-images: .PHONY: help fetch-images Makefile +# For the pdf, we only build the tech note, but use the conf.py file in +# the top-level source directory (the -c option says where to find +# conf.py). Note that we also override the setting of +# numfig_secnum_depth in order to have figure numbering as desired in +# the pdf, given that the pdf just contains the tech note, so doesn't +# have the top-level numbering present in the web documentation (where +# top-level section 1 is the User's Guide and section 2 is the Tech +# Note). +# +# The use of $(0) is as in the catch-all target. +latexpdf: + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)/tech_note" "$(BUILDDIR)" -c "$(SOURCEDIR)" -D numfig_secnum_depth=1 $(SPHINXOPTS) $(O) + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/doc/Makefile.tech_note b/doc/Makefile.tech_note deleted file mode 100644 index e19b31e182..0000000000 --- a/doc/Makefile.tech_note +++ /dev/null @@ -1,29 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = clmdoc -SOURCEDIR = source/tech_note -BUILDDIR = build/tech_note - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -# Before building html or pdf, obtain all of the images. This is needed -# because we have configured this repository (via an .lfsconfig file at -# the top level) to NOT automatically fetch any of the large files when -# cloning / fetching. -html: fetch-images -latexpdf: fetch-images -fetch-images: - git lfs pull --exclude="" - -.PHONY: help fetch-images Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile.tech_note - $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/Makefile.users_guide b/doc/Makefile.users_guide deleted file mode 100644 index 2fa8bb453f..0000000000 --- a/doc/Makefile.users_guide +++ /dev/null @@ -1,29 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = clmdoc -SOURCEDIR = source/users_guide -BUILDDIR = build/users_guide - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -# Before building html or pdf, obtain all of the images. This is needed -# because we have configured this repository (via an .lfsconfig file at -# the top level) to NOT automatically fetch any of the large files when -# cloning / fetching. -html: fetch-images -latexpdf: fetch-images -fetch-images: - git lfs pull --exclude="" - -.PHONY: help fetch-images Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile.users_guide - $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/tech_note/conf.py b/doc/source/tech_note/conf.py deleted file mode 100644 index 5c5b1d86ad..0000000000 --- a/doc/source/tech_note/conf.py +++ /dev/null @@ -1,171 +0,0 @@ -# -*- coding: utf-8 -*- -# -# clmdoc documentation build configuration file, created by -# sphinx-quickstart on Thu Feb 23 17:14:30 2017. -# -# 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. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- 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.ext.intersphinx', - 'sphinx.ext.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.imgmath', - 'sphinx.ext.githubpages'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'clmdoc' -copyright = u'2017, Erik Kluzek, Bill Sacks, Ben Andre' -author = u'Erik Kluzek, Bill Sacks, Ben Andre' - -# 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 = u'' -# The full version, including alpha/beta/rc tags. -release = u'' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - -imgmath_image_format = 'svg' - -# -- 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 = 'bizstyle' - -# 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 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'] - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'clmdocdoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - 'preamble': '\\usepackage{hyperref}', - - 'fncychap': '\\usepackage[Conny]{fncychap}', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'clmdoc', u'clmdoc Documentation', - [author], 1) -] - - -# -- 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 = [ - (master_doc, 'clmdoc', u'clmdoc Documentation', - author, 'clmdoc', 'One line description of project.', - 'Miscellaneous'), -] - - - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - -numfig = True -numfig_format = {'figure': 'Figure %s', - 'table': 'Table %s', - 'code-block': 'Code %s', - 'section': '%s', - } diff --git a/doc/source/users_guide/conf.py b/doc/source/users_guide/conf.py deleted file mode 100644 index ab8a299b9f..0000000000 --- a/doc/source/users_guide/conf.py +++ /dev/null @@ -1,174 +0,0 @@ -# -*- coding: utf-8 -*- -# -# clmdoc documentation build configuration file, created by -# sphinx-quickstart on Thu Feb 23 17:14:30 2017. -# -# 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. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- 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.ext.intersphinx', - 'sphinx.ext.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.imgmath', - 'sphinx.ext.githubpages'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'clmdoc' -copyright = u'2018, Erik Kluzek, Bill Sacks, Ben Andre, Alice Bertini' -author = u'Erik Kluzek, Bill Sacks, Ben Andre, Alice Bertini' - -# 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 = u'clm5.0' -# The full version, including alpha/beta/rc tags. -release = u'release-clm5.0.01' - -# The format to print out today in -today_fmt = u'%Y-%m-%D %H:%M' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - -imgmath_image_format = 'svg' - -# -- 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 = 'bizstyle' - -# 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 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'] - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'clmdocdoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - 'preamble': '\\usepackage{hyperref}', - - 'fncychap': '\\usepackage[Conny]{fncychap}', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'clmdoc', u'clmdoc Documentation', - [author], 1) -] - - -# -- 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 = [ - (master_doc, 'clmdoc', u'clmdoc Documentation', - author, 'clmdoc', 'One line description of project.', - 'Miscellaneous'), -] - - - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - -numfig = True -numfig_format = {'figure': 'Figure %s', - 'table': 'Table %s', - 'code-block': 'Code %s', - 'section': '%s', - } From 885a37e38fb83e9dd10b96bdbb7835d0fb88e222 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sat, 28 Mar 2020 14:44:36 -0600 Subject: [PATCH 243/255] Change copyright, version, and other metadata --- doc/source/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 30259e17b3..32b583fbba 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -50,18 +50,18 @@ master_doc = 'index' # General information about the project. -project = u'clmdoc' -copyright = u'2018, Erik Kluzek, Bill Sacks, Ben Andre' -author = u'Erik Kluzek, Bill Sacks, Ben Andre' +project = u'ctsm' +copyright = u'2020, UCAR' +author = u'' # 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 = u'clm5.0' +version = u'master' # The full version, including alpha/beta/rc tags. -release = u'release-clm5.0.01' +release = u'master' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From d1ea77c6cb1b70fbaa6504bceef9e97fa0ec7581 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Sat, 28 Mar 2020 15:55:23 -0600 Subject: [PATCH 244/255] Change html build to make versioned documentation with a dropdown menu This changes the documentation theme to use the readthedocs theme, with some JavaScript that provides capabilities for a dropdown menu allowing you to select between different versions. This mimics the changes in https://github.com/ESMCI/cime/pull/3439, which in turn was based on ESCOMP/CISM-wrapper#23. --- doc/source/_static/pop_ver.js | 37 +++++++++++++++++++++++++++++++ doc/source/_templates/footer.html | 5 +++++ doc/source/_templates/layout.html | 3 +++ doc/source/conf.py | 18 +++++++++++---- 4 files changed, 59 insertions(+), 4 deletions(-) create mode 100644 doc/source/_static/pop_ver.js create mode 100644 doc/source/_templates/footer.html create mode 100644 doc/source/_templates/layout.html diff --git a/doc/source/_static/pop_ver.js b/doc/source/_static/pop_ver.js new file mode 100644 index 0000000000..b8c58658a8 --- /dev/null +++ b/doc/source/_static/pop_ver.js @@ -0,0 +1,37 @@ +$(document).ready(function() { + /* For a URL that looks like + https://blah.github.io/versions/VERSIONFOO/html/bar/index.html, set cur_version_dir to + 'VERSIONFOO' (i.e., the portion of the path following 'versions'). + */ + var proj_end = document.baseURI.indexOf("versions") + 9; + var end = document.baseURI.indexOf("/", proj_end); + var cur_version_dir = document.baseURI.substring(proj_end, end); + var mylist = $("#version-list"); + mylist.empty(); + $.getJSON(version_json_loc, function(data) { + if (data.hasOwnProperty(cur_version_dir)) { + /* First add the current version so that it appears first in the drop-down + menu and starts as the selected element of the menu. If you click on the + current version, you should stay at the current page. + + The conditional around this block should generally be true, but we check it + just in case the current version is missing from the versions.json file for + some reason. + */ + cur_version_name = data[cur_version_dir]; + mylist.append($("