# How to customize the configuration for a case with &clm;

The &cesm; User's Guide gives you the details on how to setup, &configure;, build, and run a case. That is the document to give you the details on using the &cesm; scripts. The purpose of this document is to give you the details when using &cesm; with &clm; on how to customize and use advanced features in &clm;. You should be familiar with the &cesm; User's Guide and how to setup cases with &cesmrel; before referring to this document.

In this chapter we deal with three different ways of customizing a case: Choosing a compset, Customizing Configuration options, and customizing the &clm; Namelist. There are many different compsets that use &clm; and many are setup to enable special features of &clm; from the start. So the first thing you want to be familiar with are the different options in the compsets. The next section shows the different options for customizing the configuration options for &clm;. Here we introduce the &clm; &configure; and &buildnml; scripts and how using the options in &envconf; you can customize the configuration and the initial namelist. The final section tells you about the &clm; namelist and how you can customize the namelist once you have run "&configure; -case" and have an initial namelist in `BuildConf/clm.buildnml.csh`. You can also use &envconf; options to change your namelist as well, before "&configure; -case" is run.

## Choosing a compset using &clm;

When setting up a new case one of the first choices to make is which "component set" (or compset) to use. The compset refers to which component models are used as well as specific settings for them. We label the different types of compsets with a different letter of the alphabet from "A" (for all data model) to "X" (for all dead model). The compsets of interest when working with &clm; are the "I" compsets (which contain &clm; with a data atmosphere model and a stub ocean, and stub sea-ice models), "E" and "F" compsets (which contain &clm; with the active atmosphere model (CAM), prescribed sea-ice model, and a data ocean model), and "B" compsets which have all active components. Below we go into details on the "I" compsets which emphasize &clm; as the only active model, and just mention the two other categories.

When working with &clm; you usually want to start with a relevant "I" compset before moving to the more complex cases that involve other active model components. The "I" compsets can exercise &clm; in a way that is similar to the coupled modes, but with much lower computational cost and faster turnaround times.

### Compsets coupled to data atmosphere and stub ocean/sea-ice ("I" compsets)

&compsets_list;

### Compsets coupled to active atmosphere with data ocean

CAM compsets are compsets that start with "E" or "F" in the name. They are described more fully in the scripts documentation or the CAM documentation. "E" compsets have a slab ocean model while "F" compsets have a data ocean model.

### Fully coupled compsets with fully active ocean, sea-ice, and atmosphere

Fully coupled compsets are compsets that start with "B" in the name. They are described more fully in the scripts documentation.

### Conclusion to choosing a compset

We've introduced the basic type of compsets that use &clm; and given some further details for the "standalone &clm;" (or "I" compsets). The config_compsets.xml lists all of the compsets and gives a full description of each of them. In the next section we look into customizing the &configure; time options for compsets using &clm;.

## Customizing the &clm; configuration

The "Creating a Case" section of the &cesm1; Scripts User's-Guide gives instructions on creating a case. What is of interest here is how to customize your use of &clm; for the case that you created. In this section we discuss how to customize your case before the first step -- the "&configure; -case" step is done. In the next section we will discuss how to customize your &clm; namelist after "&configure; -case" has already been done.

For &clm; when "&configure; -case" is called there are two steps that take place:

1. The &clm; "&configure;" script is called to setup the build-time configuration for &clm; (more information on &configure; is given in ).

2. The &clm; "&buildnml;" script is called to generate the initial run-time namelist for &clm; (more information on &buildnml; is given below in .

When customizing your case at the &configure; step you are able to modify the process by effecting either one or both of these steps. The &clm; "&configure;" and "&buildnml;" scripts are both available in the "models/lnd/clm/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them.

There are five different types of customization for the configuration that we will discuss: &cesm1; &clm; configuration items, Configure time User Namelist, other noteworthy &cesm; configuration items, the &clm; &configure; script options, and the &clm; &buildnml; script options.

Information on all of the script, configuration, build and run items is found under `scripts/ccsm_utils/Case.template` in the `config_definition.xml` file.

### &clm; Script configuration items

Below we list each of the &cesm; configuration items that are specific to &clm;. All of these are available in your: &envconf; file.

- &CLMCONFIG;
- &CLMBLDNML;
- &CLMNAMELIST;
- &CLMFORCECOLD;
- &CLMUSECASE;
- &CLM1PT;
- &CLMUSRDAT;
- &CLMCO2;

For the precedence of the different options to &buildnml; see the section on precedence below.

The first item &CLMCONFIG; has to do with customizing the &clm; configuration options for your case, the rest all have to do with generating the initial namelist.

&CLMCONFIG;

  The option &CLMCONFIG; is all about passing command line arguments to the &clm; &configure; script. It is important to note that some compsets, may already put a value into the &CLMCONFIG; variable. You can still add more options to your &CLMCONFIG; but make sure you add to what is already there rather than replacing it. Hence, we recommend using the "-append" option to the xmlchange script. In below we will go into more details on options that can be customized in the &clm; "&configure;" script. It's also important to note that the &clm; template may already invoke certain &clm; &configure; options and as such those command line options are NOT going to be available to change at this step (nor would you want to change them). The options to &configure; are given with the "-help" option which is given in .

&CLMUSECASE;

  &CLMUSECASE; is used to set a particular set of conditions that set multiple namelist items, all centering around a particular usage of the model. To list the valid options do the following:

      > cd models/lnd/clm/doc
      > ../bld/&buildnml; -use_case list

  The output of the above command is:

      &usecases_list;

  See the section for the precedence of this option relative to the others.

&CLMBLDNML;

  The option &CLMBLDNML; is for passing options to the &clm; "&buildnml;" script. As with the "&configure;" script the &clm; template may already invoke certain options and as such those options will NOT be available to be set here. The best way to see what options can be sent to the "&buildnml;" script is to do

      > cd models/lnd/clm/bld
      > ./&buildnml; -help

  Here is the output from the above.

      ./&buildnml_help;

  The &clm; template already sets the resolution and mask as well as the &configure; file, the start-type, the co2_ppmv, rtm_tstep, and rtm_res, and defines an input namelist and namelist input file, and it normally sets either "-ignore_ic_year" or "-ignore_ic_date". Also many of the options are designed solely for &clm; stand-alone testing and hence should NOT be used (any of the options starting with a "datm_" or "drv_" prefix. Hence there are then only five different options that could be set:

  1. -lnd_res

  2. -sim_year

  3. -rcp

  4. -clm_demand

  5. -verbose

  "-lnd_res" is used to run &clm; in fine-mesh mode at a higher resolution than the atmospheric model. This can be useful to get higher resolution from the land model, but saving computer time by running the more expensive atmospheric model at a lower resolution. To get a list of valid resolutions to run at do the following:

      > cd models/lnd/clm/doc
      > ../bld/&buildnml; -lnd_res list

  The fine-mesh mode is considered experimental, and you may run into problems when you use it. Another option is to use the CESM level "tri-grid" capability to run the land model on a different grid than the atmospheric model. Read the CESM User's-Guide to learn how to do this.

  See the section for the precedence of this option relative to the others.

  "-clm_demand" asks the &buildnml; step to require that the list of variables entered be set. Typically, this is used to require that optional filenames be used and ensure they are set before continuing. For example, you may want to require that `flanduse_timeseries` be set to get dynamically changing vegetation types. To do this you would do the following.

      > ./xmlchange -file env_conf.xml -id &CLMBLDNML; -val "-clm_demand flanduse_timeseries"

  To see a list of valid variables that you could set do this:

      > cd models/lnd/clm/doc
      > ../bld/&buildnml; -clm_demand list

  Using a 20th-Century transient compset or the `20thC_transient` use-case using &CLMUSECASE; would set this as well, but would also use dynamic nitrogen and aerosol deposition files, so using `-clm_demand` would be a way to get just dynamic vegetation types and NOT the other files as well.

  "-sim_year" is used to set the simulation year you want the data-sets to simulate conditions for in the input datasets. The simulation "year" can also be a range of years in order to do simulations with changes in the dataset values as the simulation progresses. To list the valid options do the following:

      > cd models/lnd/clm/doc
      > ../bld/&buildnml; -sim_year list

  "-rcp" is used to set the representative concentration pathway for the future scenarios you want the data-sets to simulate conditions for, in the input datasets. To list the valid options do the following:

      > cd models/lnd/clm/doc
      > ../bld/&buildnml; -rcp list

&CLMNAMELIST;

  The option &CLMNAMELIST; is for passing namelist items into the "clm_inparm" namelist. Any items that are set in &CLMNAMELIST; will be set in your namelist after "&configure; -case" is done.

  For character namelist items you need to use "&apos;" as quotes for strings so that the scripts don't get confused with other quotes they use.

  Example, you want to set `hist_dov2xy` to `.false.` so that you get vector output to your history files. To do so edit &envconf; and add a setting for `hist_dov2xy`. So do the following:

      > ./xmlchange -file env_conf.xml -id &CLMNAMELIST; -val hist_dov2xy=.false.

  Example, you want to set `hist_fincl1` to add the variable `'HK'` to your history files. To do so edit &envconf; and add a setting for `hist_fincl1`. So do the following:

      > ./xmlchange -file env_conf.xml -id &CLMNAMELIST; -val "hist_fincl1=&apos;HK&apos;"

  For a list of the history fields available see &clm; History Fields.

  See the section for the precedence of this option relative to the others.

&CLMCO2;

  &CLMCO2; sets the type of input &CO2; for either "constant", "diagnostic" or prognostic". If "constant" the value from `CCSM_CO2_PPMV` will be used. If "diagnostic" or "prognostic" the values MUST be sent from the atmosphere model. For more information on how to send &CO2; from the data atmosphere model see .

&CLMFORCECOLD;

  &CLMFORCECOLD; when set to `on`, requires that your simulation do a cold start from arbitrary initial conditions. If this is NOT set, it will use an initial condition file if it can find an appropriate one, and otherwise do a cold start. &CLMFORCECOLD; is a good way to ensure that you are doing a cold start if that is what you want to do.

&CLM1PT;

  &CLM1PT; is used ONLY for a `pt1_pt1` resolution simulation to set the name of the single-point files to use. To see a list of the valid resolutions do this:

      > cd models/lnd/clm/doc
      > ../bld/&buildnml; -res list

  The output of the above command is:

      &res_list;

  the valid resolutions that can be used with &CLM1PT; are the ones that have city or nation names such as: 5x5_amazon, 1x1_vancouverCAN 1x1_mexicocityMEX, or 1x1_brazil. The "1x1_" prefix means the file is for a single-point, while "5x5_" prefix means it's for a region of five points in latitude by five points in longitude. Both regional and single point datasets can be used for &CLM1PT;. If you create your own datasets you can also use &CLM1PT; along with &CLMUSRDAT; (documented below), setting &CLM1PT; to the value in &CLMUSRDAT; so that your datasets are used rather than the standard ones.o

&CLMUSRDAT;

  &CLMUSRDAT; provides a way to enter your own datasets into the initial namelist setup at "&configure; -case". The files you create must be named with specific naming conventions outlined in: . To see what the expected names of the files are, use the `queryDefaultNamelist.pl` to see what the names will need to be. For example if your &CLMUSRDAT; will be "1x1_boulderCO", with a "navy" land-mask, constant simulation year range, for 1850, the following will list what your filenames should be:

      > cd models/lnd/clm/bld
      > queryDefaultNamelist.pl -usrname "1x1_boulderCO" -options \
      mask=navy,sim_year=1850,sim_year_range="constant"  -csmdata $CSMDATA

  An example of using &CLMUSRDAT; for a simulation is given in .

  See the section for the precedence of this option relative to the others.

### Configure time User Namelist

&CLMNAMELIST; as described above allows you to set any extra namelist items you would like to appear in your namelist after first &configure;d. However, it only allows you a single line to enter namelist items, and strings must be quoted with &apos; which is a bit awkward. If you have a long list of namelist items you want to set (such as a long list of history fields) a convenient way to do it is to create a &usernlclm; that contains just the list of namelist variables you want to add to your initial namelist. The &usernlclm; will only be used when &configure; is run, so if you change it after &configure; -- it won't change anything. The file needs to be in valid FORTRAN namelist format, and the &configure; step will abort if there are syntax errors. It merely needs to be named correctly &usernlclm; and placed in your case directory (where your other `env_*.xml` files are). The namelist name actually doesn't have to be valid, but all the variable names must be. Here's an example &usernlclm; namelist that sets a bunch of history file related items, to create output history files monthly, daily, every six and 1 hours.

#### Example &usernlclm; namelist file

    &clmexp
     hist_fincl2    = 'TG','TBOT','FIRE','FIRA','FLDS','FSDS',
                      'FSR','FSA','FGEV','FSH','FGR','TSOI',
                      'ERRSOI','BUILDHEAT','SABV','SABG',
                      'FSDSVD','FSDSND','FSDSVI','FSDSNI',
                      'FSRVD','FSRND','FSRVI','FSRNI',
                      'TSA','FCTR','FCEV','QBOT','RH2M','H2OSOI',
                      'H2OSNO','SOILLIQ','SOILICE',
                      'TSA_U', 'TSA_R',
                      'TREFMNAV_U', 'TREFMNAV_R',
                      'TREFMXAV_U', 'TREFMXAV_R',
                      'TG_U', 'TG_R',
                      'RH2M_U', 'RH2M_R',
                      'QRUNOFF_U', 'QRUNOFF_R',
                      'SoilAlpha_U',
                      'Qanth', 'SWup', 'LWup', 'URBAN_AC', 'URBAN_HEAT'
      hist_fincl3 = 'TG:I', 'FSA:I', 'SWup:I', 'URBAN_AC:I', 'URBAN_HEAT:I',
                    'TG_U:I', 'TG_R:I',
      hist_fincl4 = 'TG', 'FSA', 'SWup', 'URBAN_AC', 'URBAN_HEAT'
      hist_mfilt  = 1, 30,  28, 24
      hist_nhtfrq = 0, -24, -6, -1
    /

See the section for the precedence of this option relative to the others.

In the above example we use an invalid namelist name &clmexp -- but it works anyway because the &clm; &buildnml; knows the namelist that specific variable names belong to, and it puts them there.

Obviously, all of this would be difficult to put in the &CLMNAMELIST; variable, especially having to put &apos; around all the character strings. For more information on the namelist variables being set here and what they mean, see the section on &clm; namelists below, as well as the namelist definition that gives details on each variable.

### Precedence of Options

Note: The precedence for setting the values of namelist variables with the different env_conf options is (highest to lowest):

1. Namelist values set by specific command-line options, like, -d, -sim_year (i.e. &CLMBLDNML; env_conf variable)

2. Values set on the command-line using the -namelist option, (i.e. &CLMNAMELIST; env_conf variable)

3. Values read from the file specified by -infile, (i.e. &usernlclm; file)

4. Datasets from the -clm_usr_name option, (i.e. &CLMUSRDAT; env_conf variable)

5. Values set from a use-case scenario, e.g., -use_case (i.e. &CLMUSECASE;env_conf variable)

6. Values from the namelist defaults file.

Thus a setting in &CLMBLDNML; will override a setting for the same thing given in a use case with &CLMUSECASE;. Likewise, a setting in &CLMNAMELIST; will override a setting in &usernlclm;.

### Setting Your Initial Conditions File

Especially with &clmcn; starting from initial conditions is very important. Even with &clmsp; it takes many simulation years to get the model fully spunup. There are a couple different ways to provide an initial condition file.

Your initial condition file MUST agree with the surface dataset you are using to run the simulation. If the two files do NOT agree you will get a run-time about a mis-match in PFT weights, or in the number of PFT's or columns. To get around this you'll need to use to interpolate your initial condition dataset.

#### Doing a hybrid simulation to provide initial conditions

The first option is to setup a hybrid simulation and give a `RUN_REFCASE` and `RUN_REFDATE` to specify the reference case simulation name to use. When you setup most cases, at the standard resolutions of "f09" or "f19" it will already do this for you. For example, if you run an "I2000CN" compset at "f09_g16" resolution the following settings will already be done for you.

    ./xmlchange -file env_conf.xml -id RUN_TYPE    -val hybrid
    ./xmlchange -file env_conf.xml -id RUN_REFCASE -val I2000CN_f09_g16_c100503
    ./xmlchange -file env_conf.xml -id RUN_REFDATE -val 0001-01-01
    ./xmlchange -file env_conf.xml -id GET_REFCASE -val TRUE

Setting the `GET_REFCASE` option to `TRUE` means it will copy the files from the: `$DIN_LOC_ROOT/ccsm4_init/I2000CN_f09_g16_c100503/0001-01-01` directory. Note, that the `RUN_REFCASE` and `RUN_REFDATE` variables are expanded to get the directory name above. If you do NOT set `GET_REFCASE` to `TRUE` then you will need to have placed the file in your run directory yourself. In either case, the file is expected to be named: `$RUN_REFCASE.clm2.r.$RUN_REFDATE-00000.nc` with the variables expanded of course.

#### Doing a branch simulation to provide initial conditions

The setup for running a branch simulation is essentially the same as for a hybrid. With the exception of setting `RUN_TYPE` to `branch` rather than `hybrid`. A branch simulation runs the case essentially as restarting from it's place before to exactly reproduce it. While a hybrid simulation allows you to change namelist items, and use a different code base that may have fewer fields on it than a full restart file. The `GET_REFCASE` works similarily for a branch case as for a hybrid.

#### Providing a finidat file in your &usernlclm; file

Setting up a branch or hybrid simulation requires the initial condition file to follow a standard naming convention, and a standard input directory if you use the `GET_REFCASE` option. If you want to name your file willy nilly and place it anywhere, you can set it in your &usernlclm; file as in this example.

    &clm_inparm
     finidat    = '/glade/home/$USER/myinitdata/clmi_I1850CN_f09_g16_0182-01-01.c120329.nc'
    /

Note, if you provide an initial condition file -- you can NOT set &CLMFORCECOLD; to `TRUE`.

#### Adding a finidat file to the XML database

Like other datasets, if you want to use a given initial condition file to be used for all (or most of) your cases you'll want to put it in the XML database so it will be used by default. The initial condition files, are resolution dependent, and dependent on the number of PFT's and other variables such as `GLC_NEC` or if irrigation is on or off. See for more information on this.

### Other noteworthy configuration items

For running "I" cases there are several other noteworthy configuration items that you may want to work with. Most of these involve settings for the &datm;, but one `CCSM_CO2_PPMV` applies to all models. If you are running an B, E, or F case that doesn't use the &datm; obviously the DATM_* settings will not be used. All of the settings below are in your &envconf; file

- `CCSM_CO2_PPMV`
- `CCSM_VOC`
- `DATM_MODE`
- `DATM_PRESAERO`
- `DATM_CLMNCEP_YR_ALIGN`
- `DATM_CLMNCEP_YR_START`
- `DATM_CLMNCEP_YR_END`
- `DATM_CPL_CASE`
- `DATM_CPL_YR_ALIGN`
- `DATM_CPL_YR_START`
- `DATM_CPL_YR_END`

CCSM_CO2_PPMV

  `CCSM_CO2_PPMV` sets the mixing ratio of &CO2; in parts per million by volume for ALL &cesm; components to use. Note that most compsets already set this value to something reasonable. Also note that some compsets may tell the atmosphere model to override this value with either historic or ramped values. If the `CCSM_BGC` variable is set to something other than "none" the atmosphere model will determine &CO2;, and &clm; will listen and use what the atmosphere sends it. On the &clm; side the namelist item `co2_type` tells &clm; to use the value sent from the atmosphere rather than a value set on it's own namelist.

CCSM_VOC

  `CCSM_VOC` enables passing of the Volatile Organic Compounds (VOC) from &clm; to the atmospheric model. This of course is only important if the atmosphere model is a fully active model that can use these fields in it's chemistry calculations.

DATM_MODE

  `DATM_MODE` sets the mode that the &datm; model should run in this determines how data is handled as well as what the source of the data will be. Many of the modes are setup specifically to be used for ocean and/or sea-ice modeling. The modes that are designed for use by &clm; are:

  - &CLMQIAN;
  - CLM1PT
  - &CPLHIST;

  &CLMQIAN; is for the standard mode of using global atmospheric data that was developed by Qian et. al. for &clm; using NCEP data from 1948 to 2004. See for more information on the &datm; settings for &CLMQIAN; mode. CLM1PT is for the special cases where we have single-point tower data for particular sites. Right now we only have data for three urban locations: MexicoCity Mexico, Vancouver Canada, and the urban-c alpha site. See for more information on the &datm; settings for CLM1PT mode. &CPLHIST; is for running with atmospheric forcing from a previous &cesm; simulation. See for more information on the &datm; settings for &CPLHIST; mode.

  There is a problem with running simulations for the CLM1PT mode that are greater than one data cycle, where the atm forcing will be held constant. This will result in useless results as all atmosphere forcing fields will be held constant at the last value. See bug 1377 in the &KnownBugs; file on how to fix this problem.

DATM_PRESAERO

  `DATM_PRESAERO` sets the prescribed aerosol mode for the data atmosphere model. The list of valid options include:

  - `clim_1850` = constant year 1850 conditions
  - `clim_2000` = constant year 2000 conditions
  - `trans_1850-2000` = transient 1850 to year 2000 conditions
  - `rcp2.6` = transient conditions for the rcp=2.6 W/m2 future scenario
  - `rcp4.5` = transient conditions for the rcp=4.5 W/m2 future scenario
  - `rcp6.0` = transient conditions for the rcp=6.0 W/m2 future scenario
  - `rcp8.5` = transient conditions for the rcp=8.5 W/m2 future scenario
  - `pt1_pt1` = read in single-point or regional datasets
DATM_CLMNCEP_YR_START

  `DATM_CLMNCEP_YR_START` sets the beginning year to cycle the atmospheric data over for the &CLMQIAN; mode.

DATM_CLMNCEP_YR_END

  `DATM_CLMNCEP_YR_END` sets the ending year to cycle the atmospheric data over for the &CLMQIAN; mode.

DATM_CLMNCEP_YR_ALIGN

  `DATM_CLMNCEP_YR_START` and `DATM_CLMNCEP_YR_END` determine the range of years to cycle the atmospheric data over, and `DATM_CLMNCEP_YR_ALIGN` determines which year in that range of years the simulation will start with.

DATM_CPL_CASE

  `DATM_CPL_CASE` sets the casename to use for the &CPLHIST; mode.

DATM_CPL_YR_START

  `DATM_CPL_YR_START` sets the beginning year to cycle the atmospheric data over for the &CPLHIST; mode.

DATM_CPL_YR_END

  `DATM_CPL_YR_END` sets the ending year to cycle the atmospheric data over for the &CPLHIST; mode.

DATM_CPL_YR_ALIGN

  `DATM_CPL_YR_START` and `DATM_CPL_YR_END` determine the range of years to cycle the atmospheric data over, and `DATM_CPL_YR_ALIGN` determines which year in that range of years the simulation will start with.

### Downloading DATM Forcing Data

In Chapter One of the &cesm; User's Guide there is a section on "Downloading input data". The normal process of setting up cases will use the "scripts/ccsm_utils/Tools/check_input_data" script to retrieve data from the &cesm; subversion inputdata repository. However, the DATM forcing data is unique -- because it is large compared to the rest of the input data (56 Gbytes). Most of the data is stored in the directory set by the &envrun; variable `DIN_LOC_ROOT_CSMDATA`. The &CLMQIAN; forcing data is in a (possibly) separate directory using the &envrun; variable `DIN_LOC_ROOT_CLMQIAN`. In most cases this directory will be in the directory: `atm/datm7/atm_forcing.datm7.Qian.T62.c080727` under `DIN_LOC_ROOT_CSMDATA`. On bluefire there is a separate path for the &CLMQIAN; forcing data. We have the full set of data available on a few of the machines we use: bluefire, jaguarpf, and edinburgh. As of October, 18th, 2011 we've uploaded the entire set of forcing data into the input data repository so now it can be treated like other input datasets and the check_input_data script can retreive it for you. Previously only two years of data was available. You can also download the data from the Earth System Grid for other machines. See the Model Forcing Data link under the &clm; Documentation Page

### Customizing via the template files

The final thing that the user may wish to do before &configure; is run is to edit the template files which determine the configuration and initial namelist. The variables in &envconf; typically mean you will NOT have to edit the template. But, there are rare instances where it is useful to do so. gives the details on how to do this. The template files are copied to your case directory and are available under `Tools/Templates`. The list of template files you might wish to edit are:

- `clm.cpl7.template`
- `datm.cpl7.template`
- `cpl.template`

### More information on the &clm; &configure; script

The &configure; script defines the details of a clm configuration and summarizes it into a `config_cache.xml` file. The `config_cache.xml` will be placed in your case directory under `Buildconf/clmconf`. The config_definition.xml in `models/lnd/clm/bld/config_files` gives a definition of each &clm; configuration item, it is viewable in a web-browser. Many of these items are things that you would NOT change, but looking through the list gives you the valid options, and a good description of each. Below we repeat the `config_definition.xml` files contents:

#### Help on &clm; &configure;

Coupling this with looking at the options to &configure; with "-help" as below will enable you to understand how to set the different options.

    > cd models/lnd/clm/bld
    > &configure; -help

The output to the above command is as follows:

    &config_help;

We've given details on how to use the options in &envconf; to interact with the &clm; "&configure;" and "&buildnml;" scripts, as well as giving a good understanding of how these scripts work and the options to them. In the next section we give further details on the &clm; namelist. You could customize the namelist for these options after "&configure; -case" is run.

## Customizing the &clm; namelist

Once a case is &configure;d, we can then customize the case further, by editing the run-time namelist for &clm;. First let's list the definition of each namelist item and their valid values, and then we'll list the default values for them. Next for some of the most used or tricky namelist items we'll give examples of their use, and give you example namelists that highlight these features.

### Definition of Namelist items and their default values

Here we point to you where you can find the definition of each namelist item and separately the default values for them. The default values may change depending on the resolution, land-mask, simulation-year and other attributes. Both of these files are viewable in your web browser. Below we provide the link for them, and then expand each in turn.

1. Definition of each Namelist Item

2. Default values of each &clm; Namelist Item

One set of the namelist items allows you to add fields to the output history files: `hist_fincl1`, `hist_fincl2`, `hist_fincl3`, `hist_fincl4`, `hist_fincl5`, and `hist_fincl6`. The link &clm; History Fields documents all of the history fields available and gives the long-name and units for each.

&hisfldtbl;

### Examples of using different namelist features

Below we will give examples of user namelists that activate different commonly used namelist features. We will discuss the namelist features in different examples and then show a user namelist that includes an example of the use of these features. First we will show the default namelist that doesn't activate any user options.

#### The default namelist

Here we give the default namelist as it would be created for a I1850CN compset at 0.9x1.25 resolution with a gx1v6 land-mask. To edit the namelist you would edit the `BuildConf/clm.buildnml.csh` under your case (or before &configure; include a user namelist with just the items you want to change). For simplicity we will just show the namelist and NOT the entire file. In the sections below, for simplicity we will just show the user namelist (&usernlclm;) that will add (or modify existing) namelist items to the namelist. Again, just adding the &usernlclm; file to your case directory, before "&configure; -case" is invoked will cause the given namelist items to appear in your &clm; namelist.

##### Default &clm; Namelist

    &clm_inparm
     co2_ppmv   = 284.7
     co2_type   = 'constant'
     create_crop_landunit	= .false.
     dtime	  = 1800
     fatmgrid   = '$DIN_LOC_ROOT/lnd/clm2/griddata/griddata_0.9x1.25_070212.nc'
     fatmlndfrc   =
    '$DIN_LOC_ROOT/lnd/clm2/griddata/fracdata_0.9x1.25_gx1v6_c090317.nc'
     finidat    = 'I1850CN_f09_g16_c100503.clm2.r.0001-01-01-00000.nc'
     fpftcon    = '$DIN_LOC_ROOT/lnd/clm2/pftdata/pft-physiology.c110425.nc'
     frivinp_rtm	= '$DIN_LOC_ROOT/lnd/clm2/rtmdata/rdirc_0.5x0.5_simyr2000_slpmxvl_c120717.nc'
     fsnowaging   =
    '$DIN_LOC_ROOT/lnd/clm2/snicardata/snicar_drdt_bst_fit_60_c070416.nc'
     fsnowoptics	=
    '$DIN_LOC_ROOT/lnd/clm2/snicardata/snicar_optics_5bnd_c090915.nc'
     fsurdat    =
    '$DIN_LOC_ROOT/lnd/clm2/surfdata/surfdata_0.9x1.25_simyr1850_c091006.nc'
     ice_runoff   = .true.
     outnc_large_files    = .true.
     rtm_nsteps   = 6
     urban_hac    = 'ON_WASTEHEAT'
     urban_traffic	  = .false.
    /
    &ndepdyn_nml
     stream_fldfilename_ndep    =
    '$DIN_LOC_ROOT/lnd/clm2/ndepdata/fndep_clm_hist_simyr1849-2006_1.9x2.5_c100428.nc'
     stream_year_first_ndep	  = 1850
     stream_year_last_ndep	  = 1850
    /

Note that the namelist introduces some of the history namelist options that will be talked about in further detail below (`hist_mfilt` and `hist_nhtfrq`).

#### Adding/removing fields on your primary history file

The primary history files are output monthly, and contain an extensive list of fieldnames, but the list of fieldnames can be added to using `hist_fincl1` or removed from by adding fieldnames to `hist_fexcl1`. A sample user namelist &usernlclm; adding few new fields (cosine of solar zenith angle, and solar declination) and excluding a few standard fields is (ground temperature, vegetation temperature, soil temperature and soil water).:

##### Example &usernlclm; namelist adding and removing fields on primary history file

    &clm_inparm
     hist_fincl1 = 'COSZEN', 'DECL'
     hist_fexcl1 = 'TG', 'TV', 'TSOI', 'H2OSOI'
    /

#### Adding auxiliary history files and changing output frequency

The `hist_fincl2` through `hist_fincl6` set of namelist variables add given history fieldnames to auxiliary history file "streams", and `hist_fexcl2` through `hist_fexcl6` set of namelist variables remove given history fieldnames from history file auxiliary "streams". A history "stream" is a set of history files that are produced at a given frequency. By default there is only one stream of monthly data files. To add more streams you add history fieldnames to `hist_fincl2` through `hist_fincl6`. The output frequency and the way averaging is done can be different for each history file stream. By default the primary history files are monthly and any others are daily. You can have up to six active history streams, but you need to activate them in order. So if you activate stream "6" by setting `hist_fincl6`, but if any of `hist_fincl2` through `hist_fincl5` are unset, only the history streams up to the first blank one will be activated.

The frequency of the history file streams is given by the namelist variable `hist_nhtfrq` which is an array of rank six for each history stream. The values of the array `hist_nhtfrq` must be integers, where the following values have the given meaning:

- Positive value means the output frequency is the number of model steps between output.
- Negative value means the output frequency is the absolute value in hours given (i.e -1 would mean an hour and -24 would mean a full day). Daily (-24) is the default value for all auxiliary files.
- Zero means the output frequency is monthly. This is the default for the primary history files.

The number of samples on each history file stream is given by the namelist variable `hist_mfilt` which is an array of rank six for each history stream. The values of the array `hist_mfilt` must be positive integers. By default the primary history file stream has one time sample on it (i.e. output is to separate monthly files), and all other streams have thirty time samples on them.

A sample user namelist &usernlclm; turning on four extra file streams for output: daily, six-hourly, hourly, and every time-step, leaving the primary history files as monthly, and changing the number of samples on the streams to: yearly (12), thirty, weekly (28), daily (24), and daily (48) is:

##### Example &usernlclm; namelist adding auxiliary history files and changing output frequency

    &clm_inparm
     hist_fincl2 = 'TG', 'TV'
     hist_fincl3 = 'TG', 'TV'
     hist_fincl4 = 'TG', 'TV'
     hist_fincl5 = 'TG', 'TV'
     hist_nhtfrq = 0, -24, -6, -1, 1
     hist_mfilt  = 12, 30, 28, 24, 48
    /

#### Removing all history fields

Sometimes for various reasons you want to remove all the history fields either because you want to do testing without any output, or you only want a very small custom list of output fields rather than the default extensive list of fields. By default only the primary history files are active, so technically using `hist_fexcl1` explained in the first example, you could list ALL of the history fields that are output in `hist_fexcl1` and then you wouldn't get any output. However, as the list is very extensive this would be a cumbersome thing to do. So to facilitate this `hist_empty_htapes` allows you to turn off all default output. You can still use `hist_fincl1` to turn your own list of fields on, but you then start from a clean slate. A sample user namelist &usernlclm; turning off all history fields and then activating just a few selected fields (ground and vegetation temperatures and absorbed solar radiation) is:

##### Example &usernlclm; namelist removing all history fields

    &clm_inparm
     hist_empty_htapes = .true.
     hist_fincl1 = 'TG', 'TV', 'FSA'
    /

Note, you could also build adding the "-noio" option to &CLMCONFIG;. But, this would build the model without history output and you wouldn't be able to add that in later.

#### Various ways to change history output averaging flags

There are two ways to change the averaging of output history fields. The first is using `hist_avgflag_pertape` which gives a default value for each history stream, the second is when you add fields using `hist_fincl*`, you add an averaging flag to the end of the field name after a colon (for example 'TSOI:X', would output the maximum of TSOI). The types of averaging that can be done are:

- A Average, over the output interval.
- I Instantaneous, output the value at the output interval.
- X Maximum, over the output interval.
- M Minimum, over the output interval.

The default averaging depends on the specific fields, but for most fields is an average. A sample user namelist &usernlclm; making the monthly output fields all averages (except TSOI for the first two streams and FIRE for the 5th stream), and adding auxiliary file streams for instantaneous (6-hourly), maximum (daily), minimum (daily), and average (daily). For some of the fields we diverge from the per-tape value given and customize to some different type of optimization.

##### Example &usernlclm; namelist with various ways to average history fields

    &clm_inparm
     hist_empty_htapes = .true.
     hist_fincl1 = 'TSOI:X', 'TG',   'TV',   'FIRE',   'FSR', 'FSH',
                   'EFLX_LH_TOT', 'WT'
     hist_fincl2 = 'TSOI:X', 'TG',   'TV',   'FIRE',   'FSR', 'FSH',
                   'EFLX_LH_TOT', 'WT'
     hist_fincl3 = 'TSOI',   'TG:I', 'TV',   'FIRE',   'FSR', 'FSH',
                   'EFLX_LH_TOT', 'WT'
     hist_fincl4 = 'TSOI',   'TG',   'TV:I', 'FIRE',   'FSR', 'FSH',
                   'EFLX_LH_TOT', 'WT'
     hist_fincl5 = 'TSOI',   'TG',   'TV',   'FIRE:I', 'FSR', 'FSH',
                   'EFLX_LH_TOT', 'WT'
     hist_avgflag_pertape = 'A', 'I', 'X',   'M', 'A'
     hist_nhtfrq = 0, -6, -24, -24, -24
    /

In the example we put the same list of fields on each of the tapes: soil-temperature, ground temperature, vegetation temperature, emitted longwave radiation, reflected solar radiation, sensible heat, total latent-heat, and total water storage. We also modify the soil-temperature for the primary and secondary auxiliary tapes by outputting them for a maximum instead of the prescribed per-tape of average and instantaneous respectively. For the tertiary auxiliary tape we output ground temperature instantaneous instead of as a maximum, and for the fourth auxiliary tape we output vegetation temperature instantaneous instead of as a minimum. Finally, for the fifth auxiliary tapes we output `FIRE` instantaneously instead of as an average.

We also use `hist_empty_htapes` as in the previous example, so we can list ONLY the fields that we want on the primary history tapes.

#### Outputting history files as a vector in order to analyze the plant function types within gridcells

By default the output to history files are the grid-cell average of all land-units, and vegetation types within that grid-cell, and output is on the full 2D latitude/longitude grid with ocean masked out. Sometimes it's important to understand how different land-units or vegetation types are acting within a grid-cell. The way to do this is to output history files as a 1D-vector of all land-units and vegetation types. In order to display this, you'll need to do extensive post-processing to make sense of the output. Often you may only be interested in a few points, so once you figure out the 1D indices for the grid-cells of interest, you can easily view that data. 1D vector output can also be useful for single point datasets, since it's then obvious that all data is for the same grid cell.

To do this you use `hist_dov2xy` which is an array of rank six for each history stream. Set it to `.false.` if you want one of the history streams to be a 1D vector. You can also use `hist_type1d_pertape` if you want to average over all the: Plant-Function-Types, columns, land-units, or grid-cells. A sample user namelist &usernlclm; leaving the primary monthly files as 2D, and then doing grid-cell (GRID), column (COLS), and no averaging over auxiliary tapes output daily for a single field (ground temperature) is:

##### Example &usernlclm; namelist outputting some files in 1D Vector format

    &clm_inparm
     hist_fincl2 = 'TG'
     hist_fincl3 = 'TG'
     hist_fincl4 = 'TG'
     hist_fincl5 = 'TG'
     hist_fincl6 = 'TG'
     hist_dov2xy = .true., .false., .false., .false.
     hist_type2d_pertape = ' ', 'GRID', 'COLS', ' '
     hist_nhtfrq = 0, -24, -24, -24
    /

LAND and COLS are also options to the pertape averaging, but currently there is a bug with them and they fail to work.

Technically the default for `hist_nhtfrq` is for primary files output monthly and the other auxiliary tapes for daily, so we don't actually have to include `hist_nhtfrq`, we could use the default for it. Here we specify it for clarity.

Visualizing global 1D vector files will take effort. You'll probably want to do some post-processing and possibly just extract out single points of interest to see what is going on. Since, the output is a 1D vector, of only land-points traditional plots won't be helpful. The number of points per grid-cell will also vary for anything, but grid-cell averaging. You'll need to use the output fields `pfts1d_ixy`, and `pfts1d_jxy`, to get the mapping of the fields to the global 2D array. `pfts1d_itype_veg` gives you the PFT number for each PFT. Most likely you'll want to do this analysis in a data processing tool (such as NCL, Matlab, Mathmatica, IDL, etcetera that is able to read and process &netcdf; data files).

#### Outputting multi-layer snow history fields

A number of history fields provide information about individual snow layers: `SNO_ABS`, `SNO_T`, `SNO_GS`, `SNO_Z`, `SNO_LIQH2O`, `SNO_ICE`, `SNO_TK`, and `SNO_BW`; there is also an auxiliary field to aid interpretation: `SNO_EXISTENCE` (described below). These fields are inactive by default, but can be enabled like other history fields. If the maximum number of snow layers is 5 (for example), then the layers of these fields are arranged on the history file so that layer 1 is at the top of the snow pack, and layer 5 only exists if the snow is deep enough to support all layers.

Because snow layers can come into and out of existence, these fields can be challenging to interpret. It is easiest to analyze these fields if you do output every time step, and do not average to the grid cell (i.e., `dov2xy = .false.`). Otherwise, a few principles should be kept in mind when working with these fields:

- Temporal averages are taken only over times when a given snow layer exists
- Grid cell averages are taken only over columns in which a given snow layer exists
- `SNO_EXISTENCE` gives the fraction of the averaging period in which a given snow layer existed. For grid cell averages, this gives the weighted spatial fraction of the columns in which a snow layer existed for this averaging period. This is most useful for subsetting grid cells for analysis. For example, grid cells that have `SNO_EXISTENCE = 1` for all snow layers can be analyzed most easily.

Here is a simple example illustrating this averaging; this considers a given snow layer, `L`:

Assume a grid cell with 2 columns, with averaging done over 4 time steps. Column #1 has subgrid weight 0.2, and no snow in layer `L` in any time step. Column #2 has subgrid weight 0.8, and has snow in layer `L` in time steps 3 and 4; the snow field of interest has values 1.0 and 2.0 in these two time steps, for this layer.

`SNO_EXISTENCE` is then 0.8*(2/4) = 0.4. The snow field's value would be 1.5 (note that times and columns with no snow in this layer are simply ignored).

Finally, note that the `SNOABS` field is not computed for urban columns, so it will have a missing value if snow only exists over urban columns for a given snow layer.

#### Conclusion to namelist examples

We've given various examples of namelists that feature the use of different namelist options to customize a case for particular uses. Most the examples revolve around how to customize the output history fields. This should give you a good basis for setting up your own &clm; namelist.

## Customizing the &datm; Namelist and Streams files

When running "I" compsets with &clm; you use the &datm; model to give atmospheric forcing data to &clm;. There are four ways to customize &datm;:

1. &datm; Main Namelist (`datm_in`)

2. &datm; Stream Namelist (`datm_atm_in`)

3. &datm; stream files

4. &datm; template file (`Tools/Templates.datm.cpl7.template`)

The Data Model Documentation gives the details of all the options for the data models and for &datm; specifically. It goes into detail on all namelist items both for &datm; and for &datm; streams. It shows examples of stream files and talks about their use. In we talk about editing the CLM and &datm; template files. So here we won't talk about the &datm; template file, and we won't list ALL of the &datm; namelist options, nor go into great details about stream files. But, we will talk about a few of the different options that are relevant for running with &clm;. All of the options for changing the namelists or stream files is done by editing the `Buildconf/datm.buildnml.csh` file.

Because, they aren't useful for work with &clm; we will NOT discuss any of the options for the main &datm; namelist. Use the &datm; Users Guide at the link above to find details of that. For the streams namelist we will discuss three items:

1. mapalgo

2. taxmode

3. tintalgo

And for the streams file itself we will discuss:

- offset

Again everything else (and including the above items) are discussed in the Data Model User's Guide. Of the above the last three: offset, taxmode and tintalgo are all closely related and have to do with the time interpolation of the &datm; data.

mapalgo

  `mapalgo` sets the spatial interpolation method to go from the &datm; input data to the output &datm; model grid. The default is `bilinear`. For CLM1PT we set it to `nn` to just select the nearest neighbor. This saves time and we also had problems running the interpolation for single-point mode.

taxmode

  `taxmode` is the time axis mode. For &clm; we usually have it set to `cycle` which means that once the end of the data is reached it will start over at the beginning. The `extend` modes is used have it use the last time-step of the forcing data once it reaches the end of forcing data (or use the first time-step before it reaches where the forcing data starts). See the warning below about the `extend` mode.

  THE `extend` OPTION NEEDS TO BE USED WITH CAUTION! It is only invoked by default for the CLM1PT mode and is only intended for the supported urban datasets to extend the data for a single time-step. If you have the model run extensively through periods in this mode you will effectively be repeating that last time-step over that entire period. This means the output of your simulation will be worthless. See bug 1377 in the &KnownBugs; file for more information on this issue.

offset (in the stream file)

  `offset` is the time offset in seconds to give to each stream of data. Normally it is NOT used because the time-stamps for data is set correctly for each stream of data. Note, the `offset` may NEED to be adjusted depending on the `taxmode` described above, or it may need to be adjusted to account for data that is time-stamped at the END of an interval rather than the middle or beginning of interval. The `offset` can is set in the stream file rather than on the stream namelist. For data with a `taxmode` method of `coszen` the time-stamp needs to be for the beginning of the interval, while for other data it should be the midpoint. The `offset` can be used to adjust the time-stamps to get the data to line up correctly.

tintalgo

  `tintalgo` is the time interpolation algorithm. For &clm; we usually use one of three modes: `coszen`, `nearest`, or `linear`. We use `coszen` for solar data, `nearest` for precipitation data, and `linear` for everything else. If your data is half-hourly or hourly, `nearest` will work fine for everything. The `coszen` scaling is useful for longer periods (three hours or more) to try to get the solar to match the cosine of the solar zenith angle over that longer period of time. If you use `linear` for longer intervals, the solar will cut out at night-time anyway, and the straight line will be a poor approximation of the cosine of the solar zenith angle of actual solar data. `nearest` likewise would be bad for longer periods where it would be much higher than the actual values.

  For `coszen` the time-stamps of the data should correspond to the beginning of the interval the data is measured for. Either make sure the time-stamps on the datafiles is set this way, or use the `offset` described above to set it.

  For `nearest` and `linear` the time-stamps of the data should correspond to the middle of the interval the data is measured for. Either make sure the time-stamps on the datafiles is set this way, or use the `offset` described above to set it.

In the sections below we go over each of the relevant `DATM_MODE` options and what the above &datm; settings are for each. This gives you examples of actual usage for the settings. We also describe in what ways you might want to customize them for your own case.

### &CLMQIAN; mode and it's &datm; settings

In &CLMQIAN; mode the Qian dataset is used which has 6-hourly solar and precipitation data, and 3-hourly for everything else. The dataset is divided into those three data streams: solar, precipitation, and everything else (temperature, pressure, humidity and wind). The time-stamps of the data were also adjusted so that they are the beginning of the interval for solar, and the middle for the other two. Because, of this the `offset` is set to zero, and the `tintalgo` is: `coszen`, `nearest`, and `linear` for the solar, precipitation and other data respectively. `taxmode` is set to `cycle` and `mapalgo` is set to `bilinear` so that the data is spatially interpolated from the input T62 grid to the grid the atmosphere model is being run at.

Normally you wouldn't customize the &CLMQIAN; settings, but you might replicate it's use for your own global data that had similar temporal characteristics.

### CLM1PT mode and it's &datm; settings

In CLM1PT mode the model is assumed to have half-hourly or hourly data for a single-point. For the supported datasets that is exactly what it has. But, if you add your own data you may need to make adjustments accordingly. Using the &CLMUSRDAT; option you can easily extend this mode for your own datasets that may be regional or even global and could be at different temporal frequencies. If you do so you'll need to make adjustments to your &datm; settings. The dataset has all data in a single stream file. The time-stamps of the data were also adjusted so that they are at the middle of the interval. Because, of this the `offset` is set to zero, and the `tintalgo` is set to `nearest`. `taxmode` is set to `extend` and `mapalgo` is set to `nn` so that simply the nearest point is used.

If you are using your own data for this mode and it's not at least hourly you'll want to adjust the &datm; settings for it. If the data is three or six hourly, you'll need to divide it up into separate streams like in &CLMQIAN; mode which will require fairly extensive changes to the &datm; namelist and streams files. For an example of doing this see .

### &CPLHIST; mode and it's &datm; settings

In &CPLHIST; mode the model is assumed to have 3-hourly for a global grid from a previous &cesm; simulation. Like &CLMQIAN; mode the data is divided into three streams: one for precipitation, one for solar, and one for everything else. The time-stamps for Coupler history files for &cesm; is at the end of the interval, so the offset needs to be set in order to adjust the time-stamps to what it needs to be for the `tintalgo` settings. For precipitation `taxmode` is set to `nearest` so the `offset` is set to `-5400` seconds so that the ending time-step is adjusted by an hour and half to the middle of the interval. For solar `taxmode` is set to `coszen` so the `offset` is set to `-10800` seconds so that the ending time-step is adjust by three hours to the beginning of the interval. For everything else `taxmode` is set to `linear` so the `offset` is set to `-5400` seconds so that the ending time-step is adjusted by an hour and half to the middle of the interval.

Normally you wouldn't modify the &datm; settings for this mode. However, if you had data at a different frequency than 3-hours you would need to modify the `offset` and possibly the `taxmode`. The other two things that you might modify would be the path to the data (which you can change in the &datm; template see ) or the domain file for the resolution (which is currently hardwired to f09). For data at a different input resolution you would need to change the domain file in the streams file to use a domain file to the resolution that the data comes in on.

## Conclusion to customizing chapter

We've given extensive details on customizing cases with &clm;, by choosing compsets, by changing &configure; options and interacting with the &clm; "&configure;" and "&buildnml;" scripts, we've given details on all of the &clm; namelist items, and finally given some instruction in customizing the &datm; namelist and streams files. In the next chapter we talk about further ways to customize cases with &clm; by creating your own datasets using the tools provided in &clm;.