$Id$

# Acknowledgments

I want to acknowledge all of the people that helped review or edit the model documentation: David Lawrence, Samuel Levis, Keith Oleson, and Sean Swenson. Thank you for your help in catching errors, and making the document more understandable and readable. Our readers thank you as well, as now it is much easier for them to digest. Any mistakes, or errors are all mine. If you run across one of those errors, please let us know, by following . I also want to thank Sheri Mickelson, for her work in doing perturbation analysis on bluefire and intrepid, which was used in our initial versions of this User's Guide. We also want to thank the original authors of &ptclm;: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, Wilfred M. Post, and R. Quinn Thomas for providing a nice addition to the &cesm; effort. We also want to thank the folks at University of Michigan Biological Stations (US-UMB) who allowed us to use their Fluxnet station data and import it into our inputdata repository, especially Gil Bohrer the PI on record for this site (see for permission information on using this data).

# Introduction

The Community Land Model (&clmrel;) is the latest in a series of global land models developed by the &cesm; Land Model Working Group (LMWG) and maintained at the National Center for Atmospheric Research (&ncar;). This guide is intended to instruct both the novice and experienced user on running &clm;. This guide pertains to the latest version &clmrel; available for download from the public release subversion repository as a part of &cesmrel;. Documentation may be different if you are using an older version, you should either update to the latest version, or use the documentation inside your own source tree. There is information in the `ChangeLog` file and in the regarding the changes from previous versions of &cesm;.

The novice user should read in detail before beginning work, while the expert user should read and chapters, and then use the more detailed chapters as reference. Before novice users go onto more technical problems covered in , , , or they should know the material covered in and be able to replicate some of the examples given there.

All users should read the and sections to understand the document conventions and the various ways of getting help on using &clm4;. Users should also read the section to see if their planned use of the model is something that has been scientifically validated and well tested. Users that are NOT using &ncar; machines or our list of well tested machines should also read the section to make sure they have all the required UNIX utilities on the system they want to do their work.

# Introduction to the &clm4; User's Guide

What is in here anyway?

Here in the introduction we first give a simple guide to understand the document conventions in . The next section describes the differences between &clmrel; and &clm40; (for each &cesm; release version up to &cesmrel;) as well as between &clm40; and &clm35;, both from a scientific as well as a software engineering point of view. It also talks about differences in the configuration, namelist, and history fields. The next section is for users that are already experts in using &clm; and gives a quickstart guide to the bare details on how to use &clm4;. The next tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. lists the UNIX utilities required to use &clm4; and is important if you are running on non-&ncar; machines, generic local machines, or machines NOT as well tested by us at &ncar;. Next we have to detail some of the best practices for using &clm4; for science. The last introductory section is which lists different resources for getting help with &cesm1; and &clm4;.

goes into detail on how to setup and run simulations with &clm4; and especially how to customize cases. Details of &configure; modes and &buildnml; options as well as namelist options are given in this chapter.

gives instructions on the &clm4; tools for creating input datasets for use by &clm;, for the expert user. There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. Then each tool is described in detail along with different ways in which the tool might be used. A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter.

As a followup to the tools chapter, tells how to add files to the XML database for &buildnml; to use. This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with &clm;.

In , again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up both the &clmcn; model and &clm; with dynamic vegetation active (CNDV). We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. We also give instructions on running the prognostic crop model and its irrigation option. We also review how to validate a port to a new machine using the Perturbation error growth technique. Lastly we tell the user how to use the DATM model to send historical &CO2; data to &clm;.

outlines how to do single-point or regional simulations using &clm4;. This is useful to either compare &clm; simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with &clm; for example to test a new parameterization. There are several different ways given on how to perform single-point simulations which range from simple &PTSMODE; to more complex where you create all your own datasets, tying into and also to add the files into the &buildnml; XML database. After this chapter chapter outlines how to use the &ptclm; python script to help you run single-point simulations.

Finally, gives some guidance on trouble-shooting problems when using &clm4;. It doesn't cover all possible problems with &clm;, but gives you some guidelines for things that can be done for some common problems.

In the appendices we talk about some issues that are useful for advanced users and developers of &clm;. In we give some basic background to the &clm; developer on how to edit the `models/lnd/clm/bld/clm.cpl7.template`. This is a very difficult exercise and we don't recommend it for any, but the most advanced users of &clm; who are also experts in UNIX and UNIX scripting.

In we go over how to run the script `runinit_ibm.csh"` that will interpolate standard resolution initial condition dataset to several other resolutions at once. It also runs &clm; to create template files as well as doing the interpolation using `interpinic`. In general this is only something that a developer would want to do. Most users will only want to interpolate for a few specific resolutions.

In we go over the automated testing scripts for validating that the &clm; is working correctly. The test scripts run many different configurations and options with &clm; making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. In general this is an activity important only for a developer of &clm;, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly.

Finally in we give instructions on how to build the documentation associated with &clm; (i.e. how to build this document). This document is included in every &clm; distribution and can be built so that you can view a local copy rather than having to go to the &cesm; website. This also could be useful for developers who need to update the documentation due to changes they have made.

# Important Notes and Best Practices for Usage of &clm4;

- When running with CN, it is critical to begin with initial conditions hat are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see . Simulations without a proper spinup will effectively be starting from an unvegetated world. See for information on how to provide initial conditions for your simulation.

- Initial condition files are provided for fully coupled BCN and offline ICN cases for 1850 and 2000 at 1deg, 2deg, and T31 resolutions. There's also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with &clmsp; for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. And there are interpolated datasets for 4x5 and 10x15 resolution for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000.

- Users can generate initial condition files at different resolutions by using the &clm; tool `interpinic` to interpolate from one of the provided resolutions to the resolution of interest. Interpolated initial condition files may no longer be in 'reasonable' equilibrium.

- Aerosol deposition is a required field to &clm4; sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or &datm;). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at.

# How to Use This Document

Conventions used in the document for code and commands

This section provides the details in using &clm; with the &cesm; modeling system. Links to descriptions and definitions have been provided in the code below. We use the same conventions used in the &cesm; documentation as outlined below.

    Throughout the document this style is used to indicate shell
    commands and options, fragments of code, namelist variables, etc.
    Where examples from an interactive shell session are presented, lines
    starting with > indicate the shell prompt.  A backslash "\" at the end
    of a line means the line continues onto the next one (as it does in
    standard UNIX shell).  Note that $EDITOR" is used to refer to the
    text editor of your choice. $EDITOR is a standard UNIX environment
    variable and should be set on most UNIX systems. Comment lines are
    signaled with a "#" sign, which is the standard UNIX comment sign as well.
    $CSMDATA is used to denote the path to the inputdata directory for
    your &cesm; data.

    > This is a shell prompt with commands \
    that continues to the following line.
    > $EDITOR filename # means you are using a text editor to edit "filename"
    # This is a comment line

# What is new with &clmrel; since previous public releases?

In this section we list the updates that have occurred to &clm4; since previous public releases. In the first sections we describe changes in &clmrel; since the &ccsm4; release, and in the last one we describe changes from &clm35; to &clm40; release. Note, that the changes in the last section do NOT include the more recent changes given in the first section, but only list the changes from &clm35; to the &clm40; release that was part of the &ccsm4; public release. We will describe both the changes in the science in the model as the software engineering changes. Software engineering changes includes the configure and namelist changes, as well as the new history fields.

## What is new with &clmrel; since the December 8th, 2010 &cesm102; release?

### What is new with &clmrel; Science since &clmcesm102;?

A prognostic crop model option was added in (based on Agro-IBIS) from work by Samuel Levis. The crop model adds in four new vegetation types for: soybean, winter and spring temperate cereals, and corn on their own separate columns. Winter cereal was added as a PFT type, but doesn't exist in the input datasets, only spring cereal is used. Winter cereal also has NOT been scientifically validated or tested. The model manages these by modeling both planting and harvesting. See for an example of running with it.

An irrigation model was added from work by Samuel Levis and Bill Sacks. This model takes water from runoff and adds it to the crop pfts for areas equipped for irrigation. See for an example of running with it. Please note that the irrigation model only works with the crop model active.

### What is new with &clmrel; Software since &clmcesm102;?

Since &clmcesm102; all Input/Output uses &pio; (Parallel Input/Output package). Restart history files are now &netcdf;. Input and output files can be read/written in parallel using PIO. We removed a list of old CPP defines and removed the old misc/preproc.h files. Also a new tool for working with single-point sites was added into the &cesm; scripts the Python tool &ptclm;. We have a complete chapter on it's use.

New configuration options:

- -crop
- -noio

Configuration options removed:

- -dust
- -progsslt

New build-namelist options:

- -co2_ppmv
- -rtm_res
- -rtm_tstep

New precedence for build-namelist options is...

- Values set on the command-line using the -namelist option (&CLMNAMELIST;).
- Values read from the file specified by -infile (&usernlclm; file).
- Datasets from the -clm_usr_name option (&CLMUSRDAT;).
- Values set from a use-case scenario, e.g., -use_case (&CLMUSECASE;).
- Values from the namelist defaults file.

Namelist options renamed:

- carbon_only => suplnitro (can be set to NONE or ALL)

namelist options removed:

- carbon_only => suplnitro
- scaled_harvest
- hist_crtinic
- hist_pioflag
- ncd_lowmem2d
- ncd_pio_def
- ncd_pio_UseRearranger
- ncd_pio_UseBoxRearr
- ncd_pio_SerialCDF
- ncd_pio_IODOF_rootonly
- ncd_pio_DebugLevel
- ncd_pio_num_iotasks

New history fields:

- A5TMIN 5-day running mean of min 2-m temperature (K)
- A10TMIN 10-day running mean of min 2-m temperature (K)
- GDD0 Growing degree days base 0C from planting (ddays)
- GDD8 Growing degree days base 8C from planting (ddays)
- GDD10 Growing degree days base 10C from planting (ddays)
- GDD020 Twenty year average of growing degree days base 0C from planting (ddays)
- GDD820 Twenty year average of growing degree days base 8C from planting (ddays)
- GDD1020 Twenty year average of growing degree days base 10C from planting (ddays)
- GDDPLANT Accumulated growing degree days past planting date for crop (ddays)
- GDDHARV Growing degree days (gdd) needed to harvest (ddays)
- GDDTSOI Growing degree-days from planting (top two soil layers) (ddays)
- QIRRIG water added through irrigation (mm/s)

SNOWLIQ and SNOWICE changed from average to instantaneous output.

## What was new with &clm4014; (in &cesm102;) since the September 17th, 2010 &cesm101; release?

Since, &clm4010; in the &cesm101; release there were several developments made to &clmrel;. Several new namelist items were added a few new history fields. There were also some updates for running the model with single-point mode.

Configuration options that were renamed:

- prog_seasalt => progsslt

Namelist items removed:

- prog_seasalt => progsslt

### What was new with &clm4014; Science since &clm4010;?

A long simulation at the course resolution of T31 (typically used for Paleo-climate studies) was done and an spun-up initial condition file was provided for this resolution (also by default the namelist variable `ice_runoff` was turned off for T31). Also a new surface dataset and transient land-cover dataset was provided for half-degree resolution.

### What was new with &clm4014; Software since &clm4010;?

New configuration options

- sitespf_pt

sitespf_pt is used for single-point/regional mode and is set to the site-name that will be used (see the `config_definition.xml` for the list of valid options).

Configuration options that were renamed:

- prog_seasalt => progsslt

Namelist items removed:

- faerdep
- fndepdat
- fndepdyn
- use_ndepstream

Nitrogen deposition datasets are now only entered through the `ndepdyn_nml` namelist (removing `fndepdat, fndepdyn, and use_ndepstream`). Aerosol deposition is now a required input from the atmosphere model, hence `faerdep` is removed.

New history fields:

- U10 10-m wind (m/s)
- U10_DUST 10-m wind for dust model (m/s)
- VA atmospheric wind speed plus convective velocity (m/s)
- VOLR RTM storage: LIQ (m3)
- VOLR_ICE RTM storage: ICE (m3)

## What was new with &clm4010; (in &cesm101;) since the April 1st, 2010 &ccsm4; release?

From, &clm40; in the &ccsm4; release to &clm4010; there were several developments made to &clm;. A glacier multiple elevation class option was added that allows the use of &clm4; with a glacier land ice model the Community Ice Sheet Model (CISM). A bug-fix for the snow hydrology was added. Several new namelist items were added a few new history fields. Also the capability of reading aerosol and nitrogen deposition from stream files at one resolution and regridded on the fly rather than with datasets at the model resolution was added in. This was important for higher resolutions so that large datasets do not have to be created before running the model, nor are datasets for every resolution required.

### What was new with &clm4010; Science since &ccsm4;?

In general, snow layers should not be thinner than

    dzmin = wice/rhoice + wliq/rholiq

If dz < dzmin, then the value of "void" computed in subroutine SnowCompaction is negative, which is unphysical. This doesn't cause problems with the compaction itself, but results in unrealistic values of vol_ice, vol_liq, and eff_porosity in subroutine SnowWater. We can have vol_ice = 1 and vol_liq = 0 even when liquid is present, which cuts off the runoff (qout) from the lowest snow layer. Liquid water then accumulates in the snow column without draining, which leads to further problems and eventually a code crash.

The solution to this problem was to adjust layer thickness dz for any water+ice content changes in excess of previous layer thickness, e.g.,

    dz(c,j) = max(dz(c,j),h2osoi_liq(c,j)/denh2o + h2osoi_ice(c,j)/denice)

at appropriate steps in the snow hydrology subroutines.

- Snow hydrology bug fix.
- Add multiple elevation class option for glaciers so can interact with the land ice sheet model.

### What was new with &clm4010; Software since &ccsm4;?

New configuration options

- glc_nec

glc_nec can be 1,3,5, or 10 and MUST match the number on the input surface dataset the elevation classes themselves are read from the surface dataset

New namelist items:

- carbon_only
- create_glacier_mec_landunit
- glc_dyntopo
- ice_runoff
- ndepmapalgo
- scaled_harvest

carbon_only = If true, and CLMCN carbon-nitrogen model is on, Nitrogen is unlimited rather than prognosed and vegetation will be over-productive (replaces the supplemental Nitrogen #ifdef)

create_glacier_mec_landunit (= T when these landunits are created; F by default)

glc_dyntopo (= T if &clm; topography changes dynamically; currently F) (NOT fully implemented yet)

ice_runoff = If true, river runoff will be split up into liquid and ice streams, otherwise ice runoff will be zero and all runoff directed to liquid stream

ndepmapalgo = Mapping method from Nitrogen deposition input file to the model resolution (can be bilinear,nn,nnoni,nnonj,spval,copy, bilinear by default)

scaled_harvest = If true, harvesting will be scaled according to coefficients determined by Johann Feddema, 2009

New history fields:

- aais_area Antarctic ice area (km^2)
- aais_mask Antarctic mask (unitless)
- gris_area Greenland ice area (km^2)
- gris_mask Greenland mask (unitless)
- QICE ice growth/melt (mm/s)
- QICEYR ice growth/melt (mm/s)
- QTOPSOIL water input to surface (mm/s)
- VOLR RTM storage: LIQ (m3)
- VOLR_ICE RTM storage: ICE (m3)

## What was new with &clm40; since &clm35;?

From &clm35; to &clm40; there were advances in both the science and the software infrastructure. There were also new configure and namelist options as well as new history fields. In this section we will describe each of these changes in turn.

### What was new with &clm40; Science?

The following aspects are changes to the science in &clm40; since &clm35;.

#### Biogeophysics and Hydrology

Changes to &clm40; beyond &clm35; (Oleson et al., 2008a; Stockli et al., 2008) include updates throughout the model. The hydrology scheme has been modified with a revised numerical solution of the Richards equation (Zeng and Decker, 2009; Decker and Zeng, 2009); a revised soil evaporation parameterization that removes the soil resistance term introduced in &clm35; and replaces it with a so-called &Bgr; formulation, as well as accounts for the role of litter and within- canopy stability (Sakaguchi and Zeng, 2009). &clm4; also includes a representation of the thermal and hydraulic properties of organic soil that operates in conjunction with the mineral soil properties (Lawrence and Slater, 2008). The ground column has been extended to ~50-m depth by adding five additional hydrologically inactive ground layers (making a total of 15 ground layers, 10 soil layers and 5 bedrock layers; Lawrence et al., 2008). An urban landunit and associated urban canyon model (&clmu;) has been added which permits the study of urban climate and urban heat island effects (Oleson et al., 2008b).

#### Snow Model

The snow model is significantly modified via incorporation of SNICAR (SNow and Ice Aerosol Radiation) which represents the effect of aerosol deposition (e.g. black and organic carbon and dust) on albedo, introduces a grain-size dependent snow aging parameterization, and permits vertically resolved snowpack heating (Flanner and Zender, 2005; Flanner and Zender, 2006; Flanner et al., 2007). The new snow model also includes a new density-dependent snow cover fraction parameterization (Niu and Yang, 2007), a revised snow burial fraction over short vegetation (Wang and Zeng, 2009) and corrections to snow compaction (Lawrence and Slater, 2009).

#### Surface Datasets

The PFT distribution is as in Lawrence and Chase (2007) except that a new cropping dataset is used (Ramankutty et al., 2008) and a grass PFT restriction has been put in place to reduce a high grass PFT bias in forested regions by replacing the herbaceous fraction with low trees rather than grass. Grass and crop PFT optical properties have been adjusted according to values presented in Asner et al. (1998), resulting in significantly reduced albedo biases. Soil colors have been re-derived according to the new PFT distribution.

#### Biogeochemistry

The model is extended with a carbon-nitrogen biogeochemical model (Thornton et al., 2007; Thornton et al., 2009; Randerson et al., 2009) which is referred to as &clmcn;. CN is based on the terrestrial biogeochemistry Biome-BGC model with prognostic carbon and nitrogen cycle (Thornton et al., 2002; Thornton and Rosenbloom, 2005). &clmcn; is prognostic with respect to carbon and nitrogen state variables in the vegetation, litter, and soil organic matter. Vegetation phenology and canopy heights are also prognostic. A detailed description of the biogeochemical component can be found in Thornton et al. (2007). Note that &clm40; can be run with either prescribed satellite phenology (&clmsp;) or with prognostic phenology provided by the carbon- nitrogen cycle model (&clmcn;). Additionally, a transient land cover and land use change, including wood harvest, capability has been introduced that enables the evaluation of the impact of historic and future land cover and land use change on energy, water, and momentum fluxes as well as carbon and nitrogen fluxes. The dynamic global vegetation model in &clm3; has been revised such that the carbon dynamics (e.g. productivity, decomposition, phenology, allocation, etc.) are controlled by CN and only the dynamic vegetation biogeography (competition) aspect of the &clm3; DGVM is retained. The biogenic volatile organic compounds model (BVOC) that was available in &clm3; has been replaced with the MEGAN BVOC model (Heald et al. 2008).

#### Miscellaneous Changes

Several other minor changes have been incorporated including a change to the atmospheric reference height so that it is the height above zo+d for all surface types. The convergence of canopy roughness length zo and displacement height d to bare soil values as the above-ground biomass, or the sum of leaf and stem area indices, goes to zero is ensured (Zeng and Wang, 2007). Several corrections have been made to the way the offline forcing data is interpreted. The main change is a vastly improved and smooth diurnal cycle of incoming solar radiation that conserves the total incoming solar radiation from the forcing dataset. Additionally, in offline mode rather than partitioning incoming solar radiation into a constant 70%/30% direct vs diffuse split, it is partitioned according to empirical equations that are a function of total solar radiation. Finally, to improve global energy conservation in fully coupled simulations, runoff is split into separate liquid and ice water streams that are passed separately to the ocean. Input to the ice water comes from excess snowfall in snow-capped regions.

#### Summary of Science Changes

Taken together, these augmentations to &clm35; in &clm40; result in improved soil moisture dynamics that lead to higher soil moisture variability and drier soils. Excessively wet and unvarying soil moisture was recognized as a deficiency in &clm35; (Oleson et al. 2008a, Decker and Zeng, 2009). The revised model also simulates, on average, higher snow cover, cooler soil temperatures in organic-rich soils, greater global river discharge, lower albedos over forests and grasslands, and higher transition-season albedos in snow covered regions, all of which are improvements compared to &clm35;.

### What is new with &clm40; Software Infrastructure?

The following aspects are changes to the software infrastructure in &clm40; since &clm35;.

- Update to cpl7 and scripts.
- Remove offline and cpl6 modes.
- Remove support for CASA model.
- Update to datm8 atmospheric data model.
- Add gx3v7 land mask for T31 and fv-4x5 horizontal resolutions.
- Add gx1v6 land mask for f05, f09, and f19 horizontal resolutions.
- Add tx1v1 land mask and 1.9x2.5_tx1v1 horizontal resolution.
- Add in 2.5x3.33 horizontal resolution.
- Add in T62 horizontal resolution so can run at same resolution as input &datm; data.
- Allow first history tape to be 1D.
- Add ability to use own version of input datasets with &CLMUSRDAT; variable.
- Add a script to extract out regional datasets.
- New &buildnml; system with XML file describing all namelist items.
- Add glacier_mec use-case and stub glacier model.
- Make default of maxpatch_pft=numpft+1 instead of 4.
- Only output static 3D fields on first h0 history file to save space.
- Add new fields for VOC (Volatile Organic Compounds) on surface datasets, needed for the new MEGAN VOC model.
- Add multiple elevation class option for glaciers in mksurfdata tool (NOT used in &clm; yet).
- Add ascale field to land model in support of model running on it's own grid.

### What are The New Configuration Options in &clm40;?

Describe any changes made to build system:

- Change directory structure to match &ccsm;.
- Add BGP target.
- Add choice between ESMF and MCT frameworks.
- Start removing #ifdef and directives that supported Cray-X1 Phoenix as now decommissioned.
- Make default of maxpatch_pft=numpft+1 instead of 4 for all configurations.
- By default turn on CLAMP when either CN or CASA is enabled
- New SNICAR_FRC, CARBON_AERO, and C13 CPP ifdef tokens.

New options added to &configure;: More information on options to &clm; &configure; are given in .

Option Description -comp_intf <name>Component interface to use (ESMF or MCT) (default MCT) -nofire Turn off wildfires for bgc setting of CN (default includes fire for CN) -pio <name>Switch enables building with Parallel I/O library. [on | off] (default is on) -snicar_frc <name>Turn on SNICAR radiative forcing calculation. [on | off] (default is off) More information on options to &clm; &configure; are given in .

### What are The New Namelist Options in &clm40;?

&buildnml; now checks the validity of your namelist you generate by looking at data in the namelist_definition.xml file. In order to add new namelist items you need to change the code and also edit this file (e.g. a namelist option required for your research project that is not currently an option in &clm40;). To view information on the namelist view the file: `models/lnd/clm/bld/namelist_files/namelist_definition.xml` in a browser and you'll see the names, type, description and valid_values for all namelist variables.

Changes to &buildnml;:

- Allow simulation year entered to include ranges of years (i.e. 1850-2000)
- Remove cam_hist_case option.
- Make sure options ONLY used for stand-alone testing have a "drv_" or "datm_" prefix in them and list these options all together and last when asking for help from &buildnml;.

New option to &buildnml;:

      -clm_usr_name "name" Dataset resolution/descriptor for personal datasets.
                           Default: not used
                           Example: 1x1pt_boulderCO_c090722 to describe location,
                                    number of pts, and date files created

New list options to &buildnml;

         cd models/lnd/clm/bld
         ./&buildnml; -res list          # List valid resolutions
         ./&buildnml; -mask list         # List valid land-masks
         ./&buildnml; -sim_year list     # List valid simulation years and simulation year ranges
         ./&buildnml; -clm_demand list   # List namelist variables including those you could
                                       # demand to be set.
         ./&buildnml; -use_case list     # List valid use-cases

New use-cases for &buildnml;:

       1850_control = Conditions to simulate 1850 land-use
       2000_control = Conditions to simulate 2000 land-use
    20thC_transient = Simulate transient land-use, aerosol and Nitrogen deposition
                      from 1850 to 2005

New namelist items:

       urban_hac = OFF, ON or ON_WASTEHEAT   (default OFF)     Flag for urban Heating
                                                               and Air-Conditioning
                   OFF          = Building internal temperature is un-regulated.
                   ON           = Building internal temperature is bounded to reasonable range.
                   ON_WASTEHEAT = Building internal temperature is bounded and resultant waste
                                  heat is given off.
       urban_traffic = .true. or .false.     Flag to include additional multiplicative
                                             factor of urban traffic to sensible heat flux.
                                             (default .false.)
       fsnowoptics  = filename    file for snow/aerosol optical properties (required)
       fsnowaging   = filename    file for snow aging parameters (required)

More information on the &buildnml; options are given in . and in &CLMBLDNML;.

More information on the &buildnml; options are given in in .

### What are The New History Fields?

New history variables: (note watt vs. W in units, 26 vs. 76)

Name Long-name Units Active/Inactive BCDEP total BC deposition (dry+wet) from atmosphere kg/m^2/s BIOGENCO biogenic CO flux uGC/M2/H C13_PRODUCT_CLOSS C13 total carbon loss from wood product pools gC13/m^2/s DSTDEP total dust deposition (dry+wet) from atmosphere kg/m^2/s EFLX_DYNBAL dynamic land cover change conversion energy flux W/m^2 FGR12 heat flux between soil layers 1 and 2 watt/m^2 FSAT fractional area with water table at surface unitless FSH_NODYNLNDUSE sensible heat flux not including correction for land use change watt/m^2 GC_HEAT1 initial gridcell total heat content J/m^2 GC_HEAT2 post land cover change total heat content J/m^2 inactive GC_ICE1 initial gridcell total ice content mm/s GC_ICE2 post land cover change total ice content mm/s inactive GC_LIQ1 initial gridcell total liq content mm GC_LIQ2 initial gridcell total liq content mm inactive H2OSNO_TOP mass of snow in top snow layer kg HEAT_FROM_AC sensible heat flux put into canyon due to heat removed from air conditioning watt/m^2 HK hydraulic conductivity mm/s inactive ISOPRENE isoprene flux uGC/M2/H LAND_USE_FLUX total C emitted from land cover conversion and wood product pools gC/m^2/s LAND_UPTAKE NEE minus LAND_USE_FLUX, negative for update gC/m^2/s LWup upwelling longwave radiation watt/m^2 inactive MONOTERP monoterpene flux uGC/M2/H NBP net biome production, includes fire, landuse, and harvest flux, positive for sink gC/m^2/s OCDEP total OC deposition (dry+wet) from atmosphere kg/m^2/s OVOC other VOC flux uGC/M2/H ORVOC other reactive VOC flux uGC/M2/H PBOT atmospheric pressure Pa PCO2 atmospheric partial pressure of &CO2;Pa PRODUCT_CLOSS total carbon loss from wood product pools gC/m^2/s PRODUCT_NLOSS total N loss from wood product pools gN/m^2/s Qair atmospheric specific humidity kg/kg inactive Qanth anthropogenic heat flux watt/m^2 inactive Qtau momentum flux kg/m/s^2 QFLX_LIQ_DYNBAL liq dynamic land cover change conversion runoff flux mm/s QFLX_ICE_DYNBAL ice dynamic land cover change conversion runoff flux mm/s QRUNOFF_NODYNLNDUSE total liquid runoff not including correction for land use change (does not include QSNWCPICE) mm/s QSNWCPICE excess snowfall due to snow capping mm/s QSNWCPICE_NODYNLNDUSE excess snowfall due to snow capping not including correction for land use change mm/s QSNWCPLIQ excess rainfall due to snow capping mm/s inactive SMP soil matric potential mm inactive SNOAERFRC2L surface forcing of all aerosols in snow, averaged only when snow is present (land) watt/m^2 SNOAERFRCL surface forcing of all aerosols in snow (land)watt/m^2 SNOBCFRCL surface forcing of BC in snow (land)watt/m^2 SNOBCMCL mass of BC in snow column kg/m2 SNOBCMSL mass of BC in top snow layer kg/m2 SNOdTdzL top snow layer temperature gradient (land)K/m SNODSTFRC2L surface forcing of dust in snow, averaged only when snow is present (land) watt/m^2 SNODSTFRCL surface forcing of dust in snow (land)watt/m^2 SNODSTMCL mass of dust in snow column kg/m2 SNODSTMSL mass of dust in top snow layer kg/m2 SNOFSRND direct nir reflected solar radiation from snow watt/m^2 inactive SNOFSRNI diffuse nir reflected solar radiation from snow watt/m^2 inactive SNOFSRVD direct vis reflected solar radiation from snow watt/m^2 inactive SNOFSRVI diffuse vis reflected solar radiation from snow watt/m^2 inactive SNOFSDSND direct nir incident solar radiation on snow watt/m^2 inactive SNOFSDSNI diffuse nir incident solar radiation on snow watt/m^2 inactive SNOFSDSVD direct vis incident solar radiation on snow watt/m^2 inactive SNOFSDSVI diffuse vis incident solar radiation on snow watt/m^2 inactive SNOLIQFL top snow layer liquid water fraction (land)fraction inactive SNOOCMCL mass of OC in snow column kg/m2 SNOOCMSL mass of OC in top snow layer Kg/m2 SNOOCFRC2L surface forcing of OC in snow, averaged only when snow is present (land) watt/m^2 SNOOCFRCL surface forcing of OC in snow (land)watt/m^2 SNORDSL top snow layer effective grain radius m^-6 inactive SNOTTOPL snow temperature (top layer)K/m inactive SWup upwelling shortwave radiation watt/m^2 inactive TSOI_10CM soil temperature in top 10cm of soil K URBAN_AC urban air conditioning flux watt/m^2 URBAN_HEAT urban heating flux watt/m^2 VOCFLXT total VOC flux into atmosphere uGC/M2/H Wind atmospheric wind velocity magnitude m/s inactive WOOD_HARVESTC wood harvest (to product pools)gC/m^2/s WOOD_HARVEST wood harvest (to product pools)gN/m^2/s

History field name changes: Old New ANNSUM_PLANT_NDEMAND= ANNSUM_POTENTIAL_GPP ANNSUM_RETRANSN= ANNMAX_RETRANSN C13_DWT_PROD10C_LOSS= C13_PROD10C_LOSS C13_DWT_PROD100C_LOSS= C13_PROD100C_LOSS C13_DWT_PROD10N_LOSS= C13_PROD10N_LOSS C13_DWT_PROD100C_LOSS= C13_PROD100C_LOSS DWT_PROD100N_LOSS= PROD10N_LOSS DWT_PROD100N_LOSS= PROD100N_LOSS DWT_PROD100C_LOSS= PROD10C_LOSS DWT_PROD100C_LOSS= PROD100C_LOSS HCSOISNO= HC TEMPSUM_PLANT_NDEMAND= TEMPSUM_POTENTIAL_GPP TEMPSUM_RETRANSN= TEMPMAX_RETRANSN

History field names deleted include: SNOWAGE, TSNOW, FMICR, FCO2, DMI, QFLX_SNOWCAP

Add new urban oriented _U, and _R (Urban and Rural) for the following history variables: EFLX_LH_TOT, FGR, FIRA, FSH, FSM, Q2M, QRUNOFF, RH2M, SoilAlpha, TG, TREFMNAV, TREFMXAV, and TSA (missing _R for SoilAlpha as the regular SoilAlpha is only defined for rural areas anyway)

We are missing the Rural soil-alpha variable: SoilAlpha_R on purpose. SoilAlpha_U is only defined over pervious road, and missing everywhere else. SoilAlpha is defined only for rural areas.

# Quickstart to using &clm4;

Before working with &clm4; read the QuickStart Guide in the &cesmrel; Scripts User's Guide. Once you are familiar with how to setup cases for any type of simulation with &cesm; you will want to direct your attention to the specifics of using &clm;.

For some of the details of setting up cases for &clm4; read the README and text files available from the "models/lnd/clm/doc" directory (see the "&clm; Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with.

1. README file describing the directory structure.

2. Quickstart.userdatasets file describing how to use your own datasets in the model (also see ).

3. &KnownBugs; file describing known problems in &clm4; (that we expect to eventually fix).

4. KnownLimitations file describing known limitations in &clm4; and workarounds that we do NOT expect to fix.

The IMPORTANT_NOTES file is given in the next chapter on what is functional/validated in &clm4;?

The ChangeLog/ChangeSum files are largely explained in the previous chapter on "What is new with &clm4;?"

Note other directories have README files that explain different components and tools used when running &clm; and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with &clm; see .

The Quickstart.GUIDE (which can be found in `models/lnd/clm/doc)` is repeated here.

    &quickstart_guide;

# What is scientifically validated and functional in &clm4;?

In this section we go over what has been extensively tested and scientifically validated with &clm4;, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of &clm;, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable.

## Standard Configuration and Namelist Options that are Validated

The standard version of the model is &clmcn; at 1-degree horizontal resolution (0.9x1.25). This version has been scientifically validated with long simulations for: fully coupled simulations ("B" cases), coupled to atmosphere model CAM ("F" cases), and stand-alone &clm; cases ("I" cases). We've also done both long simulations for 1850 conditions, and transient 20th century simulations from 1850 to 2005 (with transient land-use, Nitrogen and Aerosol deposition). There have also been transient future scenario simulations done for fully coupled cases for different "representative concentration pathway" (RCP) scenarios (RCP2.6, RCP4.5, RCP6.0, and RCP8.5). To a lesser extent there have also been simulations done at T31 and 2-degree horizontal resolution (1.9x2.5), and with &clmsp; for these resolutions. As such we have provided appropriate 1-degree, 2-degree, and T31 initial condition datasets for these configurations. The irrigation and prognostic crop models were both validated at 2-degree resolution. The irrigation model for &clmsp; for present day conditions for an "I" compset, and the prognostic crop model for present day conditions for a case coupled to the active land model, but using a data ocean model (an "F" compset). Other resolutions, configurations, and namelist options are less well tested or scientifically validated. The further you get away from the standard configurations and resolutions, the more likely you are to run into trouble, and/or need to scientifically validate your work.

In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint.

## Configure Modes NOT scientifically validated, documented, supported or, in some cases, even advised to be used:

1. `C13`

       (-c13)

   The C13 mode for bgc=cn is NOT scientifically validated or documented and is NOT recommended for use.

2. `CASA`

       (-bgc casa)

   The bgc=casa mode is NOT scientifically validated or documented and is NOT recommended for use.

3. `SNICAR_FRC`

       (-snicar_frc)

   This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental.

## Namelist options that should NOT be exercised:

### Build-Namelist options that should NOT be exercised:

1. -irrig with -bgc cn We have only run the irrigation model with &clmsp; (i.e. without the CN model). We recommend that if you want to run the irrigation model with CN, that you do a spinup. But, more than that you may need to make adjustments to `irrig_factor` in `models/lnd/clm/src/biogeophys/CanopyFluxesMod.F90`. See the notes on this in the description of the irrigation model in the Technical Descriptions of the Interactive Crop Management and Interactive Irrigation Models.

2. -irrig with -crop on Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to generic crop currently, which negates it's practical usage. We also have a known problem when both are on (see bug 1326 in the &KnownBugs; file). If you try to run in this mode, the &clm; &buildnml; will return with an error.

3. -lnd_res: Fine-mesh mode, functional, but experimental

4. -rcp: Representative Concentration Pathway (RCP) for future scenarios, functional for limited resolutions, but experimental

5. -datm_*: All options that start with "datm_" they are only used for &clm; stand-alone testing.

6. -drv_*: All options that start with "drv_" they are only used for &clm; stand-alone testing.

### Namelist items that should NOT be exercised:

1. casa namelist options: lnpp, lalloc, q10, spunup, and fcpool

   CASA has NOT been scientifically validated in &clm4;.

2. suplnitro='ALL' The suplnitro namelist option to the CN Biogeochemistry model supplies unlimited nitrogen and therefore vegetation is over-productive in this mode.

3. urban_traffic: Not currently functional

# What are the UNIX utilities required to use &clm;?

Running the &clm; requires a suite of UNIX utilities and programs and you should make sure you have all of these available before trying to go forward with using it. If you are missing one of these you should contact the systems administrator for the machine you wish to run on and make sure they are installed.

- &FORTRAN90; compiler
- "C" compiler
- GNU make
- UNIX csh and tcsh shells
- UNIX sh shell
- UNIX bash shell
- UNIX awk
- UNIX sed
- &netcdf; library
- MPI Library
- "C" pre-processor
- &perl;
- Autoconf
- m4 macro processor
- Parallel &netcdf; (optional)
- &ncl; (for some of the offline tools for creating/modifying &clm; input datasets see for more information on &ncl;)
- Python (optional, needed for &ptclm;)
- xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide)
- protex and latex2html (optional, needed to build the Code-Reference Guide)

# Other resources to get help from

In addition to this users-guide there are several other resources that are available to help you use &clm4;. The first one is the &cesm; User's-Guide, which documents the entire process of creating cases with &cesm;. The next is the &cesm; bulletin board which is a web-site for exchanging information between users of &cesm;. There are also &clm; web-pages specific for &clm;, and finally there is an email address to report bugs that you find in &cesm1;.

## The &cesm; User's-Guide

&clmrel; is always run from within the standard &cesmrel; build and run scripts. Therefore, the user of &clm4; should familiarize themselves with the &cesmrel; scripts and understand how to work with them. User's-Guide documentation on the &cesmrel; scripts are available from the following web-page. The purpose of this &clmrel; User's Guide is to give the &clm4; user more complete details on how to work with &clm; and the set of tools that support &clm;, as well as to give examples that are unique to the use of &clm;. However, the &cesmrel; Scripts User's-Guide remains the primary source to get detailed information on how to build and run the &cesm; system.

- &cesm1; Scripts User's-Guide

## The &cesm; Bulletin Board

There is a rich and diverse set of people that use the &cesm;, and often it is useful to be in contact with others to get help in solving problems or trying something new. To facilitate this we have an online Bulletin Board for questions on the &cesm;. There are also different sections in the Bulletin Board for the different component models or for different topics.

- &cesm; Online Bulletin Board

## The &clm; web pages

The main &clm; web page contains information on the &clm;, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the models/lnd/clm/doc directory that give some quick information on using &clm;.

- &clm; web page
- &clm; Documentation Text Files

Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files:

- models/lnd/clm/bld/namelist_files/namelist_definition.xml -- definition of &clm; namelist items.
- models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml -- default values for &clm; namelist items.
- scripts/ccsm_utils/Case.template/config_definition.xml -- definition of all `env_*.xml` items.
- scripts/ccsm_utils/Case.template/config_compsets.xml -- definition of all the compsets.
- models/lnd/clm/bld/namelist_files/history_fields.xml -- definition of &clm; history fields.

## Reporting bugs in &clm4;

If you have any problems, additional questions, bug reports, or any other feedback, please send an email to cesmhelp@cgd.ucar.edu. If you find bad, wrong, or misleading information in this users guide send an email to erik@ucar.edu. The current list of known issues for &clmrel; is in the &KnownBugs; file, and the list of issues for &cesmrel; is at... &cesmwebmodelrel;/tags/cesm1_0_3/#PROBLEMS .