Customizing the CLM namelist

Definition of CLM history variables

Included in the table are the following pieces of information:

• Variable name.

• Long name description.

• units

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 (user_nl_clm) that will add (or modify existing) namelist items to the namelist. Again, just adding the user_nl_clm 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
/

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 user_nl_clm 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'
/

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:

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 user_nl_clm 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
/

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 user_nl_clm 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'
/

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:

&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.

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 user_nl_clm 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
/

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.