User’s Guide to version |version| of the Community Land Model (CLM)
Authors: Benjamin Andre, Erik Kluzek, William Sacks
The National Center for Atmospheric Research (NCAR) is operated by the nonprofit University Corporation for Atmospheric Research (UCAR) under the sponsorship of the National Science Foundation. Any opinions, findings, conclusions, or recommendations expressed in this publication are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.
National Center for Atmospheric Research P. O. Box 3000, Boulder, Colorado 80307-3000
1.1.1. Introduction¶
The Community Land Model (CTSM master in CESM2.2 beta) 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 CTSM1 in CESM2.2 beta available for download from the public release subversion repository as a part of CESM2.2 beta. 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 What is New with CTSM1 regarding the changes from previous versions of CESM.
Note
This release of CTSM1 in CESM2.2 beta includes BOTH CLM4.0 physics and CLM4.5 physics used in previous releases as well as the updated CTSM1 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 CTSM1 in CESM2.2 beta 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 CTSM1 in CESM2.2 beta rather than to a specific version of CLM4.5. Likewise, when referring to CTSM1 we are referring to the CTSM1 physics in CTSM1 in CESM2.2 beta.
The novice user should read the Overview chapter in detail before beginning work, while the expert user should read What is New with CTSM1 and Quickstart, and then use the more detailed sections as reference. Before novice users go onto more technical problems covered in Setting Up and Running a Case, Using CLM tools, Adding New Resolutions, Running Special Cases or Running Single Point Regional Cases, they should know the material covered in Overview and be able to replicate some of the examples given there.
All users should read How To Use This Document and Getting Help to understand the document conventions and the various ways of getting help on using CTSM1. Users should also read the Scientific Validation 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 CTSM1? 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 Testing. 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.
1.1.2. What is New with CTSM1¶
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:
Previous release pages give similar list of changes for previous versions of the model.
1.1.3. 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 CTSM1, gives references to describe the differences between CTSM1 in CESM2.2 beta and previous CESM releases both from a scientific as well as a software engineering point of view. For information on previous releases of CTSM1 before CTSM1 in CESM2.2 beta see the CESM1.2.2 documentation. The 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 CTSM1. It also lists the UNIX utilities required to use CTSM1 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 Scientific Validation section tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. Next we have Best Practices to detail some of the best practices for using CTSM1 for science. The last introductory section is Getting Help, which lists different resources for getting help with CTSM1 and CESM2.2 beta.
Setting Up and Running a Case goes into detail on how to setup and run simulations with CTSM1 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.
Using CLM tools gives instructions on the CLM tools for either CLM4.5 or CTSM1 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, Adding New Resolutions 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 CTSM1 physics).
In Running Special Cases, 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 CTSM1-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.
Running Single Point Regional Cases outlines how to do single-point or regional simulations using CTSM1. This is useful to either compare CTSM1 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 Using CLM tools and also Adding New Resolutions 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 Running PTCLM blurb…
Troubleshooting gives some guidance on trouble-shooting problems when using CTSM1. It doesn’t cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems.
Testing 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 CTSM1 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 CTSM1, 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 CTSM1.
Finally on Github we give instructions on how to build the documentation associated with CTSM1 (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.
1.1.4. README file describing CTSM1¶
The README (which can be found in $CTSMROOT/doc) is repeated here.
$CTSMROOT/README 06/08/2018
Community Terrestrial Systems Model (CTSM) science version 5.1 series -- source code, tools,
offline-build and test scripts. This gives you everything you need
to run CTSM with CESM with the CMEPS driver and CDEPS data models to provide CRU NCEP or GSWP3 forcing data in
place of a modeled atmosphere.
CMEPS is the Community Mediator for Earth Prediction Systems. And CDEPS is the
Community Data Models for Earth Prediction System. They are both NUOPC based models
used to drive the CESM (Community Earth System Model) of which CTSM is a component of.
NUOPC is the National Unified Operational Prediction Capability a standard way of building
coupled model systems. The NUOPC layer is based on the Earth System Modeling Framework (ESMF).
For lists of current bugs (issues) and current development see the CTSM GitHub page:
https://github.com/ESCOMP/CTSM
INFORMATION ON THE CMEPS DRIVER:
https://escomp.github.io/CMEPS
https://earthsystemmodeling.org/nuopc/
IMPORTANT NOTE ON CESM CHECKOUT VERSUS A CTSM CHECKOUT:
If this is the top level directory from making a clone of CTSM the
directory structure is a little bit different than if CTSM is from
a clone of the entire CESM. If this is part of CESM this directory
will be under components/clm alongside other CESM component models.
For a CTSM checkout this will be the top level directory.
Other documentation will refer to $CTSMROOT and it means the directory
that this file is at. CIMEROOT is the directory where "cime" is for
this checkout. For a CESM checkout $CIMEROOT will be the "cime" directory
beneath the top level directory. For a CTSM checkout $CIMEROOT will
be $CTSMROOT/cime.
General directory structure ($CTSMROOT):
doc --------------- Documentation of CTSM.
bld --------------- Template, configure and build-namelist scripts for clm.
src --------------- CTSM Source code.
lilac ------------- Lightweight Infrastructure for Land-Atmosphere Coupling (for coupling to a host atmosphere model)
test -------------- CTSM Testing scripts for CTSM offline tools.
tools ------------- CTSM Offline tools to prepare input datasets and process output.
cime_config ------- Configuration files of cime for compsets and CTSM settings
manage_externals -- Script to manage the external source directories
py_env_create ----- Script to setup the python environment for CTSM python tools using conda
python ------------ Some python modules mostly for use by run_sys_tests (but could be used elsewhere l
Directory structure only for a CTSM checkout:
components -------- Other active sub-components needed for CTSM to run (river routing and land-ice models)
libraries --------- CESM libraries: MCT (Model Coupling Toolkit) and PIO
share ------------- CESM shared code
cime/scripts --------------- cesm/cime driver scripts
components/cmeps -------------------- CESM top level driver (for NUOPC driver [which is the default]) source code.
components/cdeps -------------------- CESM top level data model shared code (for NUOPC driver).
cime/src/externals ------------------ CESM external utility codes (genf90)
components/cism --------------------- CESM Community land Ice Sheet Model.
components/mosart ------------------- Model for Scale Adaptive River Transport
components/rtm ---------------------- CESM River Transport Model.
components/cpl7 --------------------- CESM top level driver for MCT driver (being deprecated)
Top level documentation ($CTSMROOT):
README ------------------- This file
README.rst --------------- File that displays under the project in github
README_EXTERNALS.rst ----- Information on how to work with subversion externals for clm
CODE_OF_CONDUCT.md ------- Code of Conduct for how to work with each other on the CTSM project
Copyright ---------------- CESM Copyright file
doc/UpdateChangeLog.pl --- Script to add documentation on a tag to the
ChangeLog/ChangeSum files
doc/ChangeLog ------------ Documents different CTSM versions
doc/ChangeSum ------------ Summary documentation of different CTSM versions
doc/design --------------- Software Engineering and code design document files
Checklists for standard Software Engineering tasks
./doc/README.CHECKLIST.master_tags
./bld/namelist_files/README.CHECKLIST.interpolating_initial_conditions.md
Documentation of Namelist Items: (view the following in a web browser)
bld/namelist_files/namelist_definition_ctsm.xml --- Definition of all namelist items
bld/namelist_files/namelist_defaults_ctsm.xml ----- Default values
=============================================================================================
Important files in main directories (under $CTSMROOT):
=============================================================================================
Externals.cfg --------------- File for management of the main high level externals
Externals_CLM.cfg ----------- File for management of the CTSM specific externals (i.e. FATES)
run_sys_tests --------------- Python script to send the standard CTSM testing off (submits
the create_test test suite for several different compilers on the
machines we do standard CTSM testing on).
parse_cime.cs.status -------- Script to parse test status files cs.status.* created by create_test
(can be used along with run_sys_tests)
doc/Quickstart.GUIDE -------- Quick guide to using NUOPC scripts.
doc/IMPORTANT_NOTES --------- Some important notes about this version of
clm, configuration modes and namelist items
that are not validated or functional.
doc/ChangeLog --------------- Detailed list of changes for each model version.
doc/ChangeSum --------------- Summary one-line list of changes for each
model version.
doc/README ------------------ Documentation similar to this file
doc/UsersGuide -------------- CTSM Users Guide
doc/IMPORTANT_NOTES --------- Some important notes on caveats for some configurations/namelist items
bld/README ------------------ Description of how to use the configure and
build-namelist scripts.
bld/configure --------------- Script to prepare CTSM to be built.
bld/build-namelist ---------- Script to build CTSM namelists.
cime_config/buildnml ------------- Build the CTSM namelist for CIME
cime_config/buildlib ------------- Build the CTSM library
cime_config/config_compsets.xml -- Define CTSM compsets
cime_config/config_component.xml - Define CTSM XML settings
cime_config/config_tests.xml ----- Define CTSM specific tests
cime_config/config_pes.xml ------- Define Processor layouts for various CTSM grids and compsets
cime_config/testdefs ------------- Directory for specification of CTSM testing
cime_config/testdefs/ExpectedTestFails.xml -- List of tests that are expected to fail
cime_config/usermods_dirs -------- Directories of sets of user-modification subdirs
(These are directories that add specific user modifications to
simulations created using "cime/scripts/create_newcase --user-mods-dir".
Current sub directories are for various CMIP6 configurations)
test/tools/test_driver.sh -- Script for general software testing of
CTSM's offline tools.
tools/mksurfdata_map ---------- Directory to build program to create surface dataset
at any resolution.
tools/mkdatadomain ------------ Directory to build program to create datm7 or docn7
domain files from clm files.
tools/mkprocdata_map ---------- Process history data from unstructed grids to a gridded
format.
tools/mkmapgrids -------------- NCL script to create a SCRIP grid file for a regular lat/lon grid
tools/ncl_scripts ------------ Directory of NCL and perl scripts to do various
tasks. Most notably to plot perturbation error growth
testing and to extract regional information from
global datasets for single-point/regional simulations.
tools/site_and_regional ------- Scripts to create input datasets for single site and regional
cases, primarily by modifying existing global datasets
tools/contrib ----------------- Miscellansous useful scripts for pre and post processing
as well as case management of CTSM. These scripts are
contributed by users and may not be as well tested or
supported as other tools.
=============================================================================================
Source code directory structure:
=============================================================================================
src/biogeochem ---- Biogeochemisty
src/main ---------- Main control and high level code
src/cpl ----------- Land model high level caps for NUOPC driver (and MCT and LILAC)
src/biogeophys ---- Biogeophysics (Hydrology)
src/dyn_subgrid --- Dynamic land unit change
src/init_interp --- Online interpolation
scr/fates --------- FATES model and sub-directories
Functionally Assembled Terrestrial Ecosystem Simulator (FATES)
Experimental Ecosystem Demography model
src/utils --------- Utility codes
src/unit_test_shr - Unit test shared modules for unit testing
src/unit_test_stubs Unit test stubs that replicate CTSM code simpler
=============================================================================================
QUICKSTART: using the NUOPC driver scripts
=============================================================================================
cd $CIMEROOT/scripts
./create_newcase # get help on how to run create_newcase
./create_newcase --case testI --res f19_g17_gl4 --compset I2000Clm50BgcCrop
# create new "I" case for default machine at 1.9x2.5_gx1v7
# with 4km greenland ice sheetres resolution
# "I2000Clm50BgcCrop" case is clm5_0 active, datm8, and inactive ice/ocn
# With no-evolve ice-sheet, and MOSART for river-routing
cd testI
./case.setup # create the $CASE.run file
./case.build # build model and create namelists
./case.submit # submit script
# (NOTE: ./xmlchange RESUBMIT=10 to set RESUBMIT to number
# # of times to automatically resubmit -- 10 in this example)
1.1.5. Best Practices¶
CTSM1 includes BOTH the old CLM4.0, CLM4.5 physics AND the new CTSM1 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 CTSM1 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 CTSM1 biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see Some Acronym’s and Terms We’ll be Using).
When running with CLMCN (either CLM4.0 or CTSM1 physics) or CTSM1-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 Spinup of CTSM1-BGC-Crop or Spinning up the Satellite Phenology Model). Simulations without a proper spinup will effectively be starting from an unvegetated world. See Setting Your Initial Conditions File for information on how to provide initial conditions for your simulation.
Initial condition files are provided for CLM4.0-CN as before, for fully coupled BCN and offline ICN cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There’s also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with CLMSP for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. The 1850 initial condition files are in ‘reasonable’ equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000.
Initial condition files are also provided for CTSM1 for several configurations and resolutions. For CLM4.5-SP and CLM4.5-BGC with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. For CTSM1-SP and CTSM1-BGC-Crop with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. Normally, these files are interpolated to any other resolution that you run at.
Users can interpolate initial condition files at different resolutions at startup of a CLM4.5 or CTSM1 simulation. And the file created can be stored for later use. Interpolated initial condition files may no longer be in ‘reasonable’ equilibrium.
In CTSM1 for both CTSM1-CN, CTSM1-BGC, and CTSM1-BGC-Crop the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2014 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day – the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate.
Aerosol deposition is a required field to both CLM4.0, CLM4.5 and CTSM1 physics, sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at.
1.1.6. A CTSM versus a CESM checkout¶
The directory structure for CTSM1 is different depending on if it’s checked out from CTSM master or CESM2.2 beta. If CTSM1 is checked out from https://github.com/ESCOMP/ctsm the CLM source code is directly under the top level directory. If CESM2.2 beta is checkout out from https://github.com/ESCOMP/cesm then the CLM source directories are under “components/clm” from the top level directory. We will refer to this directory for the CLM source directories in the User’s Guide as “$CTSMROOT”.
1.1.7. How To Use This Document¶
Links to descriptions and definitions have been provided in the code below. We use the same conventions used in the CESM documentation as outlined below.
Throughout the document this style is used to indicate shell commands and options, fragments of code, namelist variables, etc. Where examples from an interactive shell session are presented, lines starting with > indicate the shell prompt. A backslash "\" at the end of a line means the line continues onto the next one (as it does in standard UNIX shell). Note that $EDITOR" is used to refer to the text editor of your choice. $EDITOR is a standard UNIX environment variable and should be set on most UNIX systems. Comment lines are signaled with a "#" sign, which is the standard UNIX comment sign as well. $CSMDATA is used to denote the path to the inputdata directory for your CESM data.
> This is a shell prompt with commands \
that continues to the following line.
> $EDITOR filename # means you are using a text editor to edit "filename"
# This is a comment line
$CTSMROOT means the path to the root of the CTSM model