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 7bfd1bebdb..c0970d2bd5 100644 --- a/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst +++ b/doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst @@ -336,7 +336,7 @@ where If :math:`{NF}_{total\_demand,j}`\ :math:`\Delta`\ *t* :math:`<` :math:`{N 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, immobilization is reduced proportional to the discrepancy, by :math:`f_{immob\_ demand,j}`, where +If :math:`{NF}_{total\_demand,j} \Delta t \mathrm{\ge} {NS}_{sminn,j}`, then there is not enough mineral nitrogen to meet the combined demands for plant growth and heterotrophic immobilization, immobilization is reduced proportional to the discrepancy, by :math:`f_{immob\_ demand,j}`, where .. math:: :label: 21.30) 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 a86b945384..8c0899cc17 100644 --- a/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst +++ b/doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst @@ -253,7 +253,7 @@ The effect is to cause the temperature optimum of :math:`V_{c\max }` and :math:` 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 :math:`V_{c\max }`. Acclimation is restricted over the temperature range :math:`T_{10} -T_{f} \ge 11`°C and :math:`T_{10} -T_{f} \le 35`°C. +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°C and :math:`T_{10} -T_{f} \le` 35°C. .. _Canopy scaling: 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 405a0bd014..f28d5583f1 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 @@ -530,7 +530,7 @@ For each constituent (ice, two black carbon species, two organic carbon species, \tau _{k} =\psi _{k} w_{k} -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 :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 :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 :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` (:ref:`Wiscombe and Warren 1980 `) in all spectral bands, producing effective values (denoted with *) that are applied in the two-stream solution +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 :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 :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 :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` (:ref:`Wiscombe and Warren 1980 `) in all spectral bands, producing effective values (denoted with :math:`*`) that are applied in the two-stream solution .. math:: :label: 3.66 diff --git a/doc/source/users_guide/adding-new-resolutions/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 index ccd196baf6..78edaaf629 100644 --- a/doc/source/users_guide/adding-new-resolutions/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 @@ -1,7 +1,7 @@ -.. _adding-resolutions: - .. include:: ../substitutions.rst +.. _adding-resolutions: + ======================== Adding New Resolutions ======================== diff --git a/doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst b/doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst index 4511116344..216de19f54 100644 --- a/doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst +++ b/doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst @@ -1,7 +1,7 @@ -.. _adding-resolution-names: - .. include:: ../substitutions.rst +.. _adding-resolution-names: + ========================= Adding Resolution Names ========================= diff --git a/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst b/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst index 16ed81f679..a2e7fcfc4e 100644 --- a/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst +++ b/doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst @@ -1,7 +1,7 @@ -.. _changing-default-filenames: - .. include:: ../substitutions.rst +.. _changing-default-filenames: + ============================ Changing Default Filenames ============================ @@ -26,6 +26,8 @@ Different types of simulations and different types of configurations for CLM req 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. +.. _reqd-files-table: + 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 index 88bbda3f5b..f524461395 100644 --- a/doc/source/users_guide/adding-new-resolutions/index.rst +++ b/doc/source/users_guide/adding-new-resolutions/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _adding-new-resolutions-section: - .. include:: ../substitutions.rst +.. _adding-new-resolutions-section: + ##################################### Adding New Resolutions ##################################### diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 3a1c2b4d8f..74765d1ad0 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -1,7 +1,7 @@ -.. _getting-help: - .. include:: ../substitutions.rst +.. _getting-help: + ============== Getting Help ============== @@ -35,22 +35,22 @@ 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 $CTSMROOT/doc directory that give some quick information on using CLM. +The main `CLM web page `_ contains information on the CLM, its history, developers, as well as downloads for previous model versions. Some other links are available at the `CESM2 land component webpage `. 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 help with namelist options, namelist defaults, or compsets. For the most recent release: -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_ctsm.xml `_ -- definition of latest CTSM namelist items. +- `$CTSMROOT/bld/namelist_files/namelist_defaults_ctsm.xml `_ -- default values for latest CTSM namelist items. +- `$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. + +Some archives are available for previous versions: + +- `Archive of namelist_definition_clm4_0.xml `_ -- definition of CLM4.0 namelist items. +- `Archive of namelist_definition_clm4_5.xml `_ -- definition of CLM4.5/CLM5.0 namelist items. +- `Archive of namelist_defaults_clm4_0.xml `_ -- default values for CLM4.0 namelist items. +- `Archive of namelist_defaults_clm4_5.xml `_ -- default values for CLM4.5/CLM5.0 namelist items. -- `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_0.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_clm4_5.xml `_ -- default values for CLM4.5/CLM5.0 namelist items. -- `$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. ---------------------------- Reporting bugs in |version| @@ -58,6 +58,8 @@ Reporting bugs in |version| 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. +.. _acronyms-and-terms: + --------------------------------------- Some Acronym's and Terms We'll be Using --------------------------------------- diff --git a/doc/source/users_guide/overview/index.rst b/doc/source/users_guide/overview/index.rst index b03eae4034..b0dcfcdd96 100644 --- a/doc/source/users_guide/overview/index.rst +++ b/doc/source/users_guide/overview/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _overview_section: - .. include:: ../substitutions.rst +.. _overview_section: + ##################################### Overview ##################################### diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index f7add659a7..bc7c1fd82c 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -1,7 +1,7 @@ -.. _introduction: - .. include:: ../substitutions.rst +.. _introduction: + **User's Guide to version |version| of the Community Land Model (CLM)** **Authors: Benjamin Andre, Erik Kluzek, William Sacks** @@ -17,23 +17,30 @@ P. O. Box 3000, Boulder, Colorado 80307-3000 Introduction ============== -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 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? `_ regarding the changes from previous versions of CESM. +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 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 :ref:`what-is-new-with-clm` regarding the changes from previous versions of CESM. .. note:: This release of |version| in |cesmrelease| includes BOTH CLM4.0 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). 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 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 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. +The novice user should read the :ref:`overview_section` chapter in detail before beginning work, while the expert user should read :ref:`what-is-new-with-clm` and :ref:`quickstart`, and then use the more detailed sections as reference. Before novice users go onto more technical problems covered in :ref:`customizing_section`, :ref:`using-clm-tools-section`, :ref:`adding-new-resolutions-section`, :ref:`running-special-cases-section` or :ref:`running-single-points`, they should know the material covered in :ref:`overview_section` 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 |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 sure they have all the required UNIX utilities on the system they want to do their work. +All users should read :ref:`how-to-use-this-document` and :ref:`getting-help` to understand the document conventions and the various ways of getting help on using |version|. Users should also read the :ref:`scientific-validiation` 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 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. +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 :ref:`testing_section`. 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-clm5_0: +.. _what-is-new-with-clm: ============================ What is New with |version| ============================ -`What's new with |version| science `_ gives a synopsis of the changes to CLM since the CLM4.5 release. More details are given in the `CLM ChangeLog file `_. +`What's new with |version| science `_ gives a synopsis of the changes to CLM since the CLM4.5 release. More details are given in the CLM ChangeLog files: + +- `CLM 3.0 ChangeLog file `_ +- `CLM 4.0 ChangeLog file `_ +- `CLM 4.5 ChangeLog file `_ +- `CLM 5.0 ChangeLog file `_ +- `CTSM 1.0 ChangeLog file `_ +- `Latest ChangeLog file `_ Previous release pages give similar list of changes for previous versions of the model. @@ -43,27 +50,29 @@ Previous release pages give similar list of changes for previous versions of the 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 |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.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 |version| and |cesmrelease|. +In this introduction we first give a simple guide to understand the document conventions in :ref:`how-to-use-this-document`. The next section, :ref:`what-is-new-with-clm`, 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.2.2 documentation. The :ref:`quickstart` section is for users that are already experts in using CLM and gives a quickstart guide to the bare details on how to use |version|. It also 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. The :ref:`scientific-validiation` section tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. Next we have :ref:`best-practices-for-usage` to detail some of the best practices for using |version| for science. The last introductory section is :ref:`getting-help`, 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. +:ref:`customizing_section` 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.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. +:ref:`using-clm-tools-section` 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 (CLM4.0, CLM4.5 and |version| physics). +As a followup to the tools chapter, :ref:`adding-new-resolutions-section` 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 (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). 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. +In :ref:`running-special-cases-section`, 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). 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. 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. +:ref:`running-single-points` 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 :ref:`using-clm-tools-section` and also :ref:`adding-new-resolutions-section` 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... +Need :ref:`running-PTCLM` blurb... -`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. +:ref:`troubleshooting-index` 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. +:ref:`testing_section` 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. 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). 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. +Finally on Github 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. + +.. _readme: ================================ README file describing |version| @@ -80,9 +89,9 @@ The README (which can be found in ``$CTSMROOT/doc``) is repeated here. Best Practices ================ -- |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 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 `_ ). +- |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 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 :ref:`acronyms-and-terms`). -- 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. +- 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 :ref:`spinning-up-clm-bgc` or :ref:`spinning-up-sp`). Simulations without a proper spinup will effectively be starting from an unvegetated world. See :ref:`setting-initial-conditions` 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. diff --git a/doc/source/users_guide/overview/quickstart.rst b/doc/source/users_guide/overview/quickstart.rst index f8b810cc0d..5414963c4d 100644 --- a/doc/source/users_guide/overview/quickstart.rst +++ b/doc/source/users_guide/overview/quickstart.rst @@ -1,31 +1,29 @@ -.. _quickstart: - .. include:: ../substitutions.rst +.. _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 "|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 `Software/OS Prerequisites `_ section of the CESM User's Guide. + - 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) +- NCL (for some of the offline tools for creating/modifying CLM input datasets; see :ref:`using-ncl` for more information) - 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. - -`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|?" `_. +Before working with |version| read the `CESM QuickStart 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. -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?" `_. +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: -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. +- :ref:`readme` 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 :ref:`scientific-validiation`. +- The ChangeLog/ChangeSum talk about advances in different versions of CLM. The content of these files is largely explained in the previous chapter on :ref:`what-is-new-with-clm`. +- 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 `_. +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 :ref:`customizing_section`. 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 3110cbd81f..348bd97250 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: - .. include:: ../substitutions.rst +.. _scientific-validiation: + ======================== 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 9492b9ce59..d085c2f689 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,7 +1,7 @@ -.. _adding-ptclm-site-data: - .. include:: ../substitutions.rst +.. _adding-ptclm-site-data: + ============================ Adding PTCLMmkdata Site Data ============================ @@ -40,6 +40,8 @@ There is a mechanism for giving site-specific land-use change in PTCLMmkdata. Ad 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-for-ptclmmkdata: + ------------------------------------------------ Converting AmeriFlux Data for use by PTCLMmkdata ------------------------------------------------ @@ -58,7 +60,7 @@ The CESM can NOT handle missing data, so we recommend using the "Level 4" Gap fi Example: PTCLMmkdata transient example over a shorter time period ----------------------------------------------------------------- -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. +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 shown in :ref:`converting-ameriflux-for-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. :: diff --git a/doc/source/users_guide/running-PTCLM/index.rst b/doc/source/users_guide/running-PTCLM/index.rst index 26e18d3a73..0b44c01b49 100644 --- a/doc/source/users_guide/running-PTCLM/index.rst +++ b/doc/source/users_guide/running-PTCLM/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _running-PTCLM: - .. include:: ../substitutions.rst +.. _running-PTCLM: + ##################################### 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 a94d62d1b5..9ae4186d2c 100644 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst @@ -105,7 +105,7 @@ 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 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. +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 :ref:`converting-ameriflux-for-ptclmmkdata` for permission information to use this data. Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne ------------------------------------------------------------------ diff --git a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst index 8b341c89ae..6801c5f3d8 100644 --- a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst +++ b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst @@ -1,7 +1,7 @@ -.. _ptclm-examples: - .. include:: ../substitutions.rst +.. _ptclm-examples: + ============================== Examples of using PTCLMmkdata ============================== diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst index c69e2cdd91..e7be79bee6 100644 --- a/doc/source/users_guide/running-PTCLM/using-ptclm.rst +++ b/doc/source/users_guide/running-PTCLM/using-ptclm.rst @@ -1,7 +1,7 @@ -.. _using-ptclm.rst: - .. include:: ../substitutions.rst +.. _using-ptclm.rst: + ************************** Using PTCLMmkdata ************************** @@ -78,7 +78,7 @@ Configure options include: 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 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: + 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 :ref:`adding-ptclm-site-data` for more information on these files. By default we have provided three different valid group names: EXAMPLE ------- @@ -86,7 +86,7 @@ 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 PTCLMmkdata `_ with permission information to use the US-UMB data. +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 :ref:`converting-ameriflux-for-ptclmmkdata` with permission information to use the US-UMB data. ``--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. diff --git a/doc/source/users_guide/running-single-points/index.rst b/doc/source/users_guide/running-single-points/index.rst index e1d955ac0a..ba342d0ba9 100644 --- a/doc/source/users_guide/running-single-points/index.rst +++ b/doc/source/users_guide/running-single-points/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _running-single-points: - .. include:: ../substitutions.rst +.. _running-single-points: + ##################################### 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 9362e93fe8..d3b14e6184 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,7 +1,7 @@ -.. _pts_mode: - .. include:: ../substitutions.rst +.. _pts_mode: + **************************************************** 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 778deb3220..8588da8b99 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,12 +1,12 @@ -.. _running-single-point-datasets: - .. include:: ../substitutions.rst +.. _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. +In addition to ``PTS_MODE`` (Sect. :numref:`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: :: @@ -29,10 +29,20 @@ Which results in the following: 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: +.. note:: When running a single point, the number of processors is automatically set to one, which is the only value allowed. + +.. warning:: + Just like ``PTS_MODE`` (Sect. :numref:`pts_mode`), by default these setups sometimes 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. + +.. _single-point-global-climate: + +Single-point runs with global climate forcings +============================================== -Example: Running CLM over a single-point test site in Brazil ------------------------------------------------------------- +Example: Use global forcings at a site without its own special forcings +----------------------------------------------------------------------- + +This example uses the single-point site in Brazil. :: > cd scripts @@ -42,10 +52,11 @@ Example: Running CLM over a single-point test site in Brazil 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: Use global forcings at a site WITH its own special forcings +-------------------------------------------------------------------- + +The urban Mexico City test site has its own atmosphere forcing data (see Sect. :numref:`single-point-with-own-forcing`). To ignore that and run it with the default global forcing data, but over the period for which its 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 @@ -54,25 +65,20 @@ Example: Running CLM over the single-point of Mexicocity Mexico with the default > ./create_newcase -case testSPDATASET -res $SITE -compset I1PtClm50SpGs > cd testSPDATASET -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. +(Note the use of ``I1Pt`` instead of ``I2000`` as in the example above.) Then setup, build and run normally. -.. 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. +.. _single-point-with-own-forcing: -.. 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 -================================================================================ +Supported single-point runs for sites with 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 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. 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. -------------------------------------------------------------------------------------------------------------------------- +Example: Use site-specific atmospheric forcings +----------------------------------------------- +In this example, we show how to use the atmospheric forcings specific to the Vancouver, Canada point. :: > cd scripts @@ -104,9 +110,7 @@ Example: Running CLM over the single-point of Vancouver Canada with supplied atm .. 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. - -.. 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-singlepoint-dataset: Creating your own single-point dataset =================================================== @@ -134,7 +138,7 @@ Example: Using CLM_USRDAT_NAME to run a simulation using user datasets for a spe #> 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. +The first step is to create the domain and surface datasets using the process outlined in :ref:`using-clm-tools-section`. Below we show an example of the process. Example: Creating a surface dataset for a single point --------------------------------------------------------------------- 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 a927bed53e..34a199ebe8 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,7 +1,7 @@ -.. _single-point-configurations: - .. include:: ../substitutions.rst +.. _single-point-configurations: + ***************************************** Single and Regional Grid Configurations ***************************************** @@ -27,13 +27,13 @@ There are three different ways to do this for normal-supported site 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. +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 :ref:`running-single-point-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. +In general :ref:`pts_mode` 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. +Next, ``CLM_USRDAT_NAME`` is the best way to setup cases quickly where you have to create your own datasets (see :ref:`running-single-point-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 *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. PTCLMmkdata is described in the next chapter `Chapter 6 `_. +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. PTCLMmkdata is described in the next chapter, :ref:`running-PTCLM`. -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 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. +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 :ref:`creating-your-own-singlepoint-dataset`. 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. :ref:`converting-ameriflux-for-ptclmmkdata` tells you how to use AmeriFlux data for atmospheric forcing. diff --git a/doc/source/users_guide/running-special-cases/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 index 9e9bacaf1e..f93bcca2f0 100644 --- a/doc/source/users_guide/running-special-cases/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 @@ -1,14 +1,14 @@ -.. _running-with-historical-co2-forcing: - .. include:: ../substitutions.rst +.. _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. +.. 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". diff --git a/doc/source/users_guide/running-special-cases/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 index 7f210ba151..dbe01c497c 100644 --- a/doc/source/users_guide/running-special-cases/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 @@ -1,14 +1,14 @@ -.. _running-with-moar-data: - .. include:: ../substitutions.rst +.. _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 ``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 `_. +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 :numref:`eg-sim-data-from-prev-sim`. Example: Simulation with MOAR Data on cheyenne ------------------------------------------------------------- diff --git a/doc/source/users_guide/running-special-cases/Running-with-anomaly-forcing.rst b/doc/source/users_guide/running-special-cases/Running-with-anomaly-forcing.rst index 06429688d4..0c6009f3fe 100644 --- a/doc/source/users_guide/running-special-cases/Running-with-anomaly-forcing.rst +++ b/doc/source/users_guide/running-special-cases/Running-with-anomaly-forcing.rst @@ -1,7 +1,7 @@ -.. _running-with-anomaly-forcing: - .. include:: ../substitutions.rst +.. _running-with-anomaly-forcing: + ============================== Running with anomaly forcing ============================== diff --git a/doc/source/users_guide/running-special-cases/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 index af98005840..ff05836f6e 100644 --- a/doc/source/users_guide/running-special-cases/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 @@ -1,7 +1,7 @@ -.. _running-with-previous-simulation-forcing: - .. include:: ../substitutions.rst +.. _running-with-previous-simulation-forcing: + ============================================================= Running with atmospheric forcing from a previous simulation ============================================================= @@ -36,7 +36,9 @@ Example: Fully Coupled Simulation to Create Data to Force Next Example Simulatio # Now run as normal > ./case.submit -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. +Now we run an I compset forced with the data from the previous simulation using the ``CPLHISTForcing`` option to DATM_MODE. See :ref:`cplhistforcing` for more information. + +.. _eg-sim-data-from-prev-sim: Example: Simulation Forced with Data from the Previous Simulation ------------------------------------------------------------------------------ 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 3292a2bbf6..eb482efdd6 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 @@ -1,12 +1,12 @@ -.. _spinning-up-sp: - .. include:: ../substitutions.rst +.. _spinning-up-sp: + =========================================== Spinning up the Satellite Phenology Model =========================================== -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. +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 :numref:`eg-final-clmbgc-spinup` 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. 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 20cbdae1e5..cc266506a8 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 @@ -1,10 +1,10 @@ -.. _spinning-up-clm50-bgc: - .. include:: ../substitutions.rst -========================== +.. _spinning-up-clm-bgc: + +============================= Spinup of |version|-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**, 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. @@ -69,6 +69,8 @@ Afterwards save the last restart file from this simulation to use in the next st **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 400+ years in normal mode. So do the following: +.. _eg-final-clmbgc-spinup: + Example: Final CLMBGC Spinup Simulation for |version|-BGC ------------------------------------------------------------------ :: diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst index 0a9950a966..7ead8f1551 100644 --- a/doc/source/users_guide/running-special-cases/index.rst +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _running-special-cases-section: - .. include:: ../substitutions.rst +.. _running-special-cases-section: + ##################################### 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 caa7b86552..7e19af8678 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,7 +1,7 @@ -.. running-prognostic-crop-model: - .. include:: ../substitutions.rst +.. _running-prognostic-crop-model: + =================================== 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 f4b04c5b59..12fa76af5b 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,7 +1,7 @@ -.. running-with-irrigation: - .. include:: ../substitutions.rst +.. _running-with-irrigation: + =================================== 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 4f6a46a7d5..eece6aab51 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,7 +1,7 @@ -.. _what is a special case: - .. include:: ../substitutions.rst +.. _what is a special case: + ========================= 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 a081f9e869..a3fb4770f7 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,27 +1,23 @@ -.. _choosing-a-compset: - .. 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. 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. -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`). +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. 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). - -Here is the entire list of compsets available. - -`CESM compsets `_ +The entire list of compsets available out-of-the-box can be browsed at the `CESM Component Set Definitions `_ page. Note that using the compset longnames, even more combinations are possible than those listed. That webpage also includes information on whether each compset has been tested and/or scientifically validated. -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: +To get a list of the compsets use the ``query_config`` command as follows: :: $CTSMROOT/cime/scripts/query_config --compsets clm @@ -36,4 +32,4 @@ 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 `$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. +We've introduced the basic type of compsets that use CLM and given some further details for the "standalone CLM" (or "I" compsets). `$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 5321e471c2..f8b5fee002 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,7 +1,7 @@ -.. _configuring-clm: - .. include:: ../substitutions.rst +.. _configuring-clm: + ******************************** Customizing CLM's Configuration ******************************** @@ -10,9 +10,9 @@ The section of the |cesmrelease| Quickstart `CESM Create a Case `_). 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 (see :ref:`more-info-clm-config-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 `_. +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 :ref:`def-nl-items-and-defaults`). 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. @@ -43,10 +43,10 @@ For the precedence of the different options to **build-namelist** see the sectio 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 **$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. + 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 :ref:`more-info-clm-config-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 **$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 :ref:`more-info-clm-config-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: + ``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. (See :ref:`precedence-of-opts` for the precedence of this option relative to the others.) To list the valid options do the following: :: > cd $CTSMROOT @@ -100,8 +100,6 @@ 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 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 $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 :: @@ -237,17 +235,17 @@ CLM_BLDNML_OPTS -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 + 1. 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, + 2. 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, + 3. values read from the file(s) specified by -infile, (i.e. user_nl_clm files) - 3. datasets from the -clm_usr_name option, + 4. 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 + 5. 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. + 6. values from the namelist defaults file. 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: @@ -276,7 +274,7 @@ The **$CTSMROOT/cime_config/buildnml** script already sets the resolution and ma #. -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 :ref:`spinning-up-clm-bgc` 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. @@ -318,7 +316,7 @@ When "-irrig on" is used **build-namelist** will try to find surface datasets th > ../bld/build-namelist -sim_year list ``CLM_NAMELIST_OPTS`` - passes namelist items into one of the CLM namelists. + passes namelist items into one of the CLM namelists. (See :ref:`precedence-of-opts` for the precedence of this option relative to the others.) .. 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. @@ -332,26 +330,22 @@ When "-irrig on" is used **build-namelist** will try to find surface datasets th > ./xmlchange CLM_NAMELIST_OPTS="hist_fincl1='HK'" - For a list of the history fields available see `CLM History Fields `_. - - .. note::See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + For lists of the history fields available see :ref:`customizing_section`. ``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: + Provides a way to enter your own datasets into the namelist. The files you create must be named with specific naming conventions outlined in :ref:`creating-your-own-singlepoint-dataset`. 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 $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 `_. - - .. note: See `the Section called Precedence of Options `_ section for the precedence of this option relative to the others. + An example of using ``CLM_USRDAT_NAME`` for a simulation is given in Example :numref:`creating-your-own-singlepoint-dataset`. ``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 `_. + 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. See :ref:`running-with-historical-co2-forcing` for more information on how to send CO2 from the data atmosphere model. =============== User Namelist @@ -405,12 +399,12 @@ 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 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-opts: + --------------------- Precedence of Options --------------------- @@ -431,19 +425,23 @@ Note: The precedence for setting the values of namelist variables with the diffe 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-initial-conditions: + ------------------------------------ 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 `_ +- :ref:`doing-a-hybrid-sim-for-init-conds` +- :ref:`doing-a-branch-sim-for-init-conds` +- :ref:`providing-finidat-in-usernlclm` +- :ref:`adding-finidat-to-xml` **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-sim-for-init-conds: + ------------------------------------------------------- Doing a hybrid simulation to provide initial conditions ------------------------------------------------------- @@ -454,12 +452,16 @@ The first option is to setup a hybrid simulation and give a ``RUN_REFCASE`` and 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-sim-for-init-conds: + ------------------------------------------------------- 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-finidat-in-usernlclm: + ------------------------------------------------- Providing a finidat file in your user_nl_clm file ------------------------------------------------- @@ -471,6 +473,8 @@ Setting up a branch or hybrid simulation requires the initial condition file to Note, if you provide an initial condition file -- you can NOT set ``CLM_FORCE_COLDSTART`` to ``TRUE``. +.. _adding-finidat-to-xml: + ------------------------------------------- Adding a finidat file to the XML database ------------------------------------------- @@ -511,16 +515,22 @@ For running "I" cases there are several other noteworthy configuration items tha CPLHISTForcing ``CLMCRUNCEP`` - 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. + 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 :ref:`clmcruncep-and-its-datm` for more information. ``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. + Version 7 of the CRUNCEP data from 1901 to 2016. See :ref:`clmcruncep-and-its-datm` for more information. ``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. ``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. + 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 :ref:`clmqian-and-its-datm` for more information. + +``CLM1PT`` + This 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 :ref:`clm1pt-and-its-datm` for more information. + +``CPLHISTForcing`` + This is for running with atmospheric forcing from a previous CESM simulation. See :ref:`cplhistforcing` for more information. ``DATM_PRESAERO`` sets the prescribed aerosol mode for the data atmosphere model. The list of valid options include: @@ -583,11 +593,13 @@ The final thing that the user may wish to do before **case.setup** is run is to **datm.buildexe.csh** **datm.buildnml.csh** +.. _more-info-clm-config-script: + -------------------------------------------- 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 ``$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: +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_ctsm.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. Help on CLM configure --------------------- 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 afd850d458..ff76a841c9 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,7 +1,7 @@ -.. _customizing-a-case: - .. include:: ../substitutions.rst +.. _customizing-a-case: + ============================ Customizing CLM's namelist ============================ @@ -10,41 +10,22 @@ Once a case has run **case.setup**, we can then customize the case further, by e 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. +.. _def-nl-items-and-defaults: + ----------------------------------------------------- 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| `_ - -2. `Default values of each CLM4.0 Namelist Item `_ +1. `Definition of Namelists `_ -3. `Default values of each |version| Namelist Item `_ +2. `Default values of each 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. - -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 from a BgcCrop case -------------------------------------------------- -For Table from a BgcCrop case, please see :doc:`history_fields_nofates`. - -Table 1-4. CLM History Fields from a Fates case ------------------------------------------------ -For Table from a Fates case, please see :doc:`history_fields_fates`. +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 :doc:`history_fields_nofates` and :doc:`history_fields_fates` files list all of the history fields available and gives the long-name and units for each. --------------------------------------------- Examples of using different namelist features 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 df55e46b22..92aa8b4aaa 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,7 +1,7 @@ -.. customizing-the-datm-namelist: - .. include:: ../substitutions.rst +.. _customizing-the-datm-namelist: + =============================== Customizing the DATM namelist =============================== @@ -58,12 +58,16 @@ In ``CLMCRUNCEPv7`` mode the CRUNCEP dataset is used and all of it's data is on For more information on CRUNCEP forcing see `http://dods.extra.cea.fr/data/p529viov/cruncep/ `_. +.. _clmcruncep-and-its-datm: + -------------------------------------- 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. +.. _clmqian-and-its-datm: + ------------------------------------ CLM_QIAN mode and it's DATM settings ------------------------------------ @@ -72,18 +76,22 @@ In ``CLM_QIAN`` mode the Qian dataset is used which has 6-hourly solar and preci 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-and-its-datm: + ---------------------------------- 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 `_. +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 :ref:`eg-sim-data-from-prev-sim`. + +.. _cplhistforcing: ------------------------------------------ CPLHISTForcing mode and it's DATM settings ------------------------------------------ -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. 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 `_. +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. 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 :ref:`running-with-moar-data`. 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 index b11587ee21..40988c303e 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 @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _customizing_section: - .. include:: ../substitutions.rst +.. _customizing_section: + ##################################### Setting Up and Running a Case ##################################### diff --git a/doc/source/users_guide/testing/index.rst b/doc/source/users_guide/testing/index.rst index 7d1370dec6..b7baedc04f 100644 --- a/doc/source/users_guide/testing/index.rst +++ b/doc/source/users_guide/testing/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _testing_section: - .. include:: ../substitutions.rst +.. _testing_section: + ##################################### Testing ##################################### diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index c821ba19e7..b270455946 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -1,12 +1,12 @@ -.. _testing: - .. include:: ../substitutions.rst +.. _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. +Technically, you could use the customization we gave in :ref:`customizing_section` 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 ==================== diff --git a/doc/source/users_guide/trouble-shooting/index.rst b/doc/source/users_guide/trouble-shooting/index.rst index 64b0cecee3..de6b0c053a 100644 --- a/doc/source/users_guide/trouble-shooting/index.rst +++ b/doc/source/users_guide/trouble-shooting/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _troubleshooting: - .. include:: ../substitutions.rst +.. _troubleshooting-index: + ##################################### Troubleshooting ##################################### diff --git a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst index 6fc53c3a89..e139796f71 100644 --- a/doc/source/users_guide/trouble-shooting/trouble-shooting.rst +++ b/doc/source/users_guide/trouble-shooting/trouble-shooting.rst @@ -1,7 +1,7 @@ -.. _trouble-shooting: - .. include:: ../substitutions.rst +.. _trouble-shooting: + *************** Troubleshooting *************** diff --git a/doc/source/users_guide/using-clm-tools/cprnc.rst b/doc/source/users_guide/using-clm-tools/cprnc.rst index 67ea63e638..05a2ca8279 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.rst +++ b/doc/source/users_guide/using-clm-tools/cprnc.rst @@ -1,7 +1,7 @@ -.. comparing-history-files: - .. include:: ../substitutions.rst +.. _comparing-history-files: + ========================= Comparing History Files ========================= @@ -20,5 +20,5 @@ Options: -kpr -See the **cprnc** `README `_ file for more details. +See the ``cprnc`` `README `_ file for more details. 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 202881bf20..d4ebd6c4e7 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,12 +1,12 @@ -.. _creating-domain-files: - .. include:: ../substitutions.rst +.. _creating-domain-files: + ***************************** 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. :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**. +*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 :ref:`using-mkocnmap`) 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. @@ -21,7 +21,7 @@ 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. +Note that the SCRIP grid file used to start this process is also used in ``mkmapdata.sh`` (see :ref:`using-mkocnmap`). Next we create domain files for a single-point or regional domain. 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 9c6e8a1f20..276394e2b9 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,18 +1,20 @@ -.. _creating-maps-for-mksurfdata: - .. include:: ../substitutions.rst +.. _creating-maps-for-mksurfdata: + ********************************************* Creating input for surface dataset generation ********************************************* -1. Generating SCRIP grid files +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. +.. _using-mkocnmap: + Using mknocnmap.pl to create grid and maps for single-point regional grids -------------------------------------------------------------------------- @@ -38,18 +40,18 @@ If you want to create a regular latitude/longitude single-point or regional grid See :numref:`Figure mknoocnmap.pl` for a visual representation of this process. -2. Creating mapping files for mksurfdata_map +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 ``$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 :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 +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 :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 :numref:`adding-new-resolutions-section`), or leave the files in place and use the ``-res usrspec -usr_gname -usr_gdate`` options to ``mksurfdata_map``. ``mkmapdata.sh`` has a help option with the following :: ../../tools/mkmapdata/mkmapdata.sh ********************** - usage on cheyenne: + usage on cheyenne:Figure mkmapdata.sh ./mkmapdata.sh valid arguments: @@ -102,4 +104,4 @@ The bash shell script ``$CTSMROOT/tools/mkmapgrids/mkmapdata.sh`` uses **ESMF_Re 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`. +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 Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool`. 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 c974b9c886..cfaa8527cd 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,12 +1,12 @@ -.. _creating-surface-datasets: - .. include:: ../substitutions.rst +.. _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. :numref:`Figure Data_Flow` 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 :numref:`reqd-files-table` 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: @@ -14,9 +14,9 @@ When just creating a replacement file for an existing one, the relevant tool sho 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. +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 :numref:`Figure Workflow of CLM5 Land Use Data Tool and Mksurfdata_map Tool` 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`). +: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` and :numref:`Figure mknoocnmap.pl`). .. _Figure Data_Flow_Legend: 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 deleted file mode 100644 index 4ddd738b5d..0000000000 --- a/doc/source/users_guide/using-clm-tools/datasts-for-observational-sites.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. include:: ../substitutions.rst - -================================== - 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 index 58435f92aa..e9a1dd5238 100644 --- a/doc/source/users_guide/using-clm-tools/index.rst +++ b/doc/source/users_guide/using-clm-tools/index.rst @@ -3,10 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _using-clm-tools-section: - .. include:: ../substitutions.rst +.. _using-clm-tools-section: + ##################################### Using CLM tools ##################################### @@ -18,7 +18,6 @@ Using CLM tools 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 observational-sites-datasets.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 index 8fafca1df0..385ec159aa 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,11 +1,11 @@ -.. _observational-sites-datasets: - .. include:: ../substitutions.rst +.. _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 `_. +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 overwrite 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 :numref:`reqd-files-table` 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 :ref:`creating-your-own-singlepoint-dataset`. ``PTCLM`` uses these methods to customize datasets; see Chapter :numref:`running-PTCLM`. -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. +Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets; see :ref:`creating-your-own-singlepoint-dataset` for more information on this. :ref:`converting-ameriflux-for-ptclmmkdata` 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 index dd650a79e9..6921e4dafd 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,7 +1,7 @@ -.. _what-are-the-clm-tools: - .. include:: ../substitutions.rst +.. _what-are-the-clm-tools: + ======================== What are the CLM tools ======================== @@ -58,6 +58,8 @@ 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 36 processors per node, so you can use up to 36 processors. +.. _using-ncl: + --------- Using NCL ---------