component set compset "I" compsets "B" compsets "E" compsets "F" compsets &CLMCONFIG; &CLMNAMELIST; &CLMFORCECOLD; &CLMUSECASE; &CLM1PT; &CLMUSRDAT; &CLMCO2; 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. 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_list; 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 are compsets that start with "B" in the name. They are described more fully in the scripts documentation. 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;. The "Creating a Case" section of the &cesm1; Scripts User's-Guide gives instructions on creating a case. What is of interest here is how to customize your use of &clm; for the case that you created. In this section we discuss how to customize your case before the first step -- the "&configure; -case" step is done. In the next section we will discuss how to customize your &clm; namelist after "&configure; -case" has already been done. For &clm; when "&configure; -case" is called there are two steps that take place: The &clm; "&configure;" script is called to setup the build-time configuration for &clm; (more information on &configure; is given in ). The &clm; "&buildnml;" script is called to generate the initial run-time namelist for &clm; (more information on &buildnml; is given below in . When customizing your case at the &configure; step you are able to modify the process by effecting either one or both of these steps. The &clm; "&configure;" and "&buildnml;" scripts are both available in the "models/lnd/clm/bld" directory in the distribution. Both of these scripts have a "-help" option that is useful to examine to see what types of options you can give either of them. There are five different types of customization for the configuration that we will discuss: &cesm1; &clm; configuration items, Configure time User Namelist, other noteworthy &cesm; configuration items, the &clm; &configure; script options, and the &clm; &buildnml; script options. Information on all of the script, configuration, build and run items is found under scripts/ccsm_utils/Case.template in the config_definition.xml file. 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, glc_grid, 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: -irrig -lnd_res -sim_year -rcp -clm_demand -verbose When "-irrig" is used &buildnml; will try to find surface datasets that have the irrigation model enabled. "-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 fpftdyn 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 fpftdyn" 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 "'" 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='HK'" 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. &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 ' 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. &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 ' 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. Note: The precedence for setting the values of namelist variables with the different env_conf options is (highest to lowest): Namelist values set by specific command-line options, like, -d, -sim_year (i.e. &CLMBLDNML; env_conf variable) Values set on the command-line using the -namelist option, (i.e. &CLMNAMELIST; env_conf variable) Values read from the file specified by -infile, (i.e. &usernlclm; file) Datasets from the -clm_usr_name option, (i.e. &CLMUSRDAT; env_conf variable) Values set from a use-case scenario, e.g., -use_case (i.e. &CLMUSECASE;env_conf variable) Values from the namelist defaults file. Thus a setting in &CLMBLDNML; will override a setting for the same thing given in a use case with &CLMUSECASE;. Likewise, a setting in &CLMNAMELIST; will override a setting in &usernlclm;. 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. 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. 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. 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. 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. 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. 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 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 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: 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. 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. Here we point to you where you can find the definition of each namelist item and separately the default values for them. The default values may change depending on the resolution, land-mask, simulation-year and other attributes. Both of these files are viewable in your web browser. Below we provide the link for them, and then expand each in turn. Definition of each Namelist Item Default values of each &clm; Namelist Item One set of the namelist items allows you to add fields to the output history files: hist_fincl1, hist_fincl2, hist_fincl3, hist_fincl4, hist_fincl5, and hist_fincl6. The link &clm; History Fields documents all of the history fields available and gives the long-name and units for each. &hisfldtbl; 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. 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. &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_c101124.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). 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).: &clm_inparm hist_fincl1 = 'COSZEN', 'DECL' hist_fexcl1 = 'TG', 'TV', 'TSOI', 'H2OSOI' / 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: &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 / 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: &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. 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. &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. 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: &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). 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. When running "I" compsets with &clm; you use the &datm; model to give atmospheric forcing data to &clm;. There are four ways to customize &datm;: &datm; Main Namelist (datm_in) &datm; Stream Namelist (datm_atm_in) &datm; stream files &datm; template file (Tools/Templates.datm.cpl7.template) The Data Model Documentation gives the details of all the options for the data models and for &datm; specifically. It goes into detail on all namelist items both for &datm; and for &datm; streams. It shows examples of stream files and talks about their use. In we talk about editing the CLM and &datm; template files. So here we won't talk about the &datm; template file, and we won't list ALL of the &datm; namelist options, nor go into great details about stream files. But, we will talk about a few of the different options that are relevant for running with &clm;. All of the options for changing the namelists or stream files is done by editing the Buildconf/datm.buildnml.csh file. Because, they aren't useful for work with &clm; we will NOT discuss any of the options for the main &datm; namelist. Use the &datm; Users Guide at the link above to find details of that. For the streams namelist we will discuss three items: mapalgo taxmode tintalgo And for the streams file itself we will discuss: offset Again everything else (and including the above items) are discussed in the Data Model User's Guide. Of the above the last three: offset, taxmode and tintalgo are all closely related and have to do with the time interpolation of the &datm; data. mapalgo mapalgo sets the spatial interpolation method to go from the &datm; input data to the output &datm; model grid. The default is bilinear. For CLM1PT we set it to nn to just select the nearest neighbor. This saves time and we also had problems running the interpolation for single-point mode. taxmode taxmode is the time axis mode. For &clm; we usually have it set to cycle which means that once the end of the data is reached it will start over at the beginning. The extend modes is used have it use the last time-step of the forcing data once it reaches the end of forcing data (or use the first time-step before it reaches where the forcing data starts). See the warning below about the extend mode. THE extend OPTION NEEDS TO BE USED WITH CAUTION! It is only invoked by default for the CLM1PT mode and is only intended for the supported urban datasets to extend the data for a single time-step. If you have the model run extensively through periods in this mode you will effectively be repeating that last time-step over that entire period. This means the output of your simulation will be worthless. See bug 1377 in the &KnownBugs; file for more information on this issue. offset (in the stream file) offset is the time offset in seconds to give to each stream of data. Normally it is NOT used because the time-stamps for data is set correctly for each stream of data. Note, the offset may NEED to be adjusted depending on the taxmode described above, or it may need to be adjusted to account for data that is time-stamped at the END of an interval rather than the middle or beginning of interval. The offset can is set in the stream file rather than on the stream namelist. For data with a taxmode method of coszen the time-stamp needs to be for the beginning of the interval, while for other data it should be the midpoint. The offset can be used to adjust the time-stamps to get the data to line up correctly. tintalgo tintalgo is the time interpolation algorithm. For &clm; we usually use one of three modes: coszen, nearest, or linear. We use coszen for solar data, nearest for precipitation data, and linear for everything else. If your data is half-hourly or hourly, nearest will work fine for everything. The coszen scaling is useful for longer periods (three hours or more) to try to get the solar to match the cosine of the solar zenith angle over that longer period of time. If you use linear for longer intervals, the solar will cut out at night-time anyway, and the straight line will be a poor approximation of the cosine of the solar zenith angle of actual solar data. nearest likewise would be bad for longer periods where it would be much higher than the actual values. For coszen the time-stamps of the data should correspond to the beginning of the interval the data is measured for. Either make sure the time-stamps on the datafiles is set this way, or use the offset described above to set it. For nearest and linear the time-stamps of the data should correspond to the middle of the interval the data is measured for. Either make sure the time-stamps on the datafiles is set this way, or use the offset described above to set it. In the sections below we go over each of the relevant DATM_MODE options and what the above &datm; settings are for each. This gives you examples of actual usage for the settings. We also describe in what ways you might want to customize them for your own case. 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. 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 . 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. 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;.