4 Namelist Parameters

CLM3.0 namelist inputs are presented in sections 4.1 - 4.7 below. In what follows, "mode" has values of "offline", "ccsm", "cam" or "all", corresponding to offline mode, ccsm mode, cam mode, or all the modes. If a namelist variable setting is listed as required, the value must be set in the namelist in order for the model to execute successfully. If a setting is specified as required and the mode is only given as offline, then that variable must only be specified when running in offline mode. For namelist variable settings not listed as required, the code will provide default settings at initialization. In the following variable descriptions, we refer to examples presented in section 9. See Example 1 for a description of the minimum required namelist for a successful run.

4.1 Run definitions

The following list specifies namelist variables associated with the definition of run case names, run types (restart, initial or branch), model time step, and initial run date.

An initial run starts the model from either initial conditions that are set internally in the code (referred to as arbitrary initial conditions) or from an initial conditions dataset (see namelist variable FINIDAT) that enables the model to start from a spun-up state.

A restart run is an exact continuation of a previous simulation from its point of termination. Output from a restart run should be bit-for-bit the same as if the previous simulation had not stopped. Run control variables set in the namelist must be the same as in the run that is being restarted.

A branch run is a new case that uses a restart dataset from a previous simulation to begin the integration. For a branch run, the length of the history interval and the output history fields do not have to be the same as in the control simulation. For example, the branching option can be used to output selected fields more frequently than was the case in the original run or to add new auxiliary history files to the model run.

name

CASEID

description

Case name (short identifier for run) (see ex. 1,2,3).

type

char*256

mode

offline, ccsm (obtained from atm in cam mode)

default

required (must be changed for branch run
unless BRNCH_RETAIN_CASENAME is set to .true.)

name

CTITLE

description

Case title for use within history files (long identifier).

type

char*256

mode

offline, ccsm (obtained from atm in cam mode)

default

blank

name

NSREST

description

Run type (0 for initial run, 1 for restart, 3 for branch) (see ex. 1,2,3).

type

integer

mode

offline, ccsm (obtained from atm in cam mode)

default

required

name

DTIME

description

Model time step (seconds) (see ex. 1).

type

integer

mode

offline, must agree with CAM model in ccsm mode, obtained from CAM model directly in cam mode

default

required (suggested range: 1200-3600 s)

name

STOP_YMD

description

Stop date (YYYYMMDD)

type

integer

mode

offline (obtained from CAM in cam mode and CCSM coupler in ccsm mode)

default

required (if NESTEP or NELAPSE not set)

name

STOP_TOD

description

Stop time of day (seconds). Ignored if STOP_YMD not defined

type

integer

mode

offline (obtained from CAM in cam mode and CCSM coupler in ccsm mode)

default

0

name

NESTEP

description

Ending run time in model time steps (positive) or days (negative) (see ex. 1). Value is ignored if STOP_YMD is specified.

type

integer

mode

offline (ending time obtained from CAM in cam mode and CCSM coupler in ccsm mode)

default

required (if neither NELAPSE nor STOP_YMD are set)

name

NELAPSE

description

Elapsed run time in model time steps (positive) or days (negative) (see ex. 2). Value is ignored if either STOP_YMD or NELAPSE are specified.

type

integer

mode

offline (ending time is obtained from CAM in cam mode and CCSM coupler in ccsm mode)

default

required (if neither NESTEP nor STOP_YMD are set)

name

START_YMD

description

Start date of run (yyyymmdd format) (see ex. 1).

type

integer

mode

offline, ccsm (obtained from CAM model in cam mode)

default

required

name

START_TOD

description

Start time of day of run (seconds).

type

integer

mode

offline, ccsm (obtained from CAM in cam mode)

default

0

name

REF_YMD

description

Reference date for time coordinate (yyyymmdd format).

type

integer

mode

offline, ccsm (obtain from CAM in cam mode)

default

no default value but if not set, then the model reference date will automatically be set to START_YMD

name

REF_TOD

description

Reference time of day for time coordinate (secs).

type

integer

mode

offline, ccsm (obtain from CAM in cam mode)

default

0

name

CALENDAR

description

Calendar to use in date calculations ("no-leap" or "gregorian").

type

char*32

mode

offline, ccsm (obtained from CAM in cam mode)

default

no-leap

name

CLUMP_PPROC

description

Number of ``clumps'' per process (see section 5).

type

integer

mode

offline, ccsm (obtained from CAM in cam mode)

default

1 if OpenMP is disabled
number of OpenMP threads (specified in the environment) if OpenMP is enabled.

name

BRNCH_RETAIN_CASENAME

description

Flag to retain case name on a branch run. If true, then allow case name to remain the same for branch run. In cam mode, this flag must be set for both the cam and clm namelists.

type

logical

mode

offline, cam, ccsm

default

.false.

4.2 Specification of model input datasets

The following list specifies namelist variables associated with model input datasets.

name

FSURDAT

description

Full pathname of surface dataset (see ex. 1,5,6).

type

char*256

mode

all

default

blank (details at the end of this section)

notes

surface datasets provided with the distribution are in $CSMDATA/srfdata, raw datasets to generate surface datasets are in $CSMDATA/rawdata

name

FINIDAT

description

Full pathname of initial conditions dataset (see ex. 1,2,3).

type

char*256

mode

all

default

blank (details at the end of this section)

notes

no initial datasets are provided, the user will need to generate these

name

FPFTCON

description

Full pathname of plant functional type (PFT) physiological constants dataset (see ex. 1).

type

char*256

mode

all

default

required

notes

dataset provided is $CSMDATA/pftdata/pft-physiology

name

FRIVINP_RTM

description

full pathname of RTM input dataset (see ex. 4).

type

char*256

mode

offline, ccsm

default

required if cpp token RTM is defined in preproc.h

notes

dataset provided is $CSMDATA/rtmdata/rdirc.05

name

NREVSN

description

Full pathname of restart file name (only for branch runs) (see ex. 3).

type

char*256

mode

all

default

required (only if branch run, NSREST=3)

name

MKSRF_ALL_PFTS

description

Flag to turn on new surface dataset format. If true, new surface dataset format (see section 6) is used.

type

logical

mode

all

default

.false.

name

MKSRF_FVEGTYP

description

Full pathname of raw plant functional type dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_pft.nc

name

MKSRF_FSOITEX

description

full pathname of raw soil texture dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_soitex.10level.nc

name

MKSRF_FSOICOL

description

Full pathname of raw soil color dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_soicol_clm2.nc

name

MKSRF_FLANWAT

description

Full pathname of raw inland water dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_lanwat.nc

name

MKSRF_FURBAN

description

full pathname of urban dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_urban.nc

name

MKSRF_FGLACIER

description

Full pathname of glacier dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_glacier.nc

name

MKSRF_FLAI

description

full pathname of leaf and stem area index, canopy top and bottom height dataset (see ex. 5).

type

char*256

mode

all

default

required (if FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_lai.nc

name

MKSRF_OFFLINE_FNAVYORO

description

20 min navy orography dataset used to generate land mask (see ex. 5).

type

char*256

mode

offline

default

required (if MKSRF_OFFLINE_FGRID not set and FSURDAT is blank)

notes

dataset provided is $CSMDATA/rawdata/mksrf_navyoro_20min.nc

name

MKSRF_OFFLINE_FGRID

description

Dataset specifying land grid and mask at desired resolution (see ex. 6).

type

char*256

mode

offline

default

blank, required (if MKSRF_OFFLINE_FNAVYORO not set and FSURDAT is blank)

notes

datasets provided in $CSMDATA/srfdata

name

MKSRF_OFFLINE_EDGEN

description

Northern edge of land grid (degrees north) (see ex. 5).

type

real

mode

offline

default

90.

name

MKSRF_OFFLINE_EDGEE

description

Eastern edge of land grid (degrees east) (see ex. 5).

type

real

mode

offline

default

180.

name

MKSRF_OFFLINE_EDGES

description

Southern edge of land grid (degrees north) (see ex. 5).

type

real

mode

offline

default

-90.

name

MKSRF_OFFLINE_EDGEW

description

Western edge of grid land (degrees east) (see ex. 5).

type

real

mode

offline

default

-180.

name

OFFLINE_ATMDIR

description

Directory containing atmospheric forcing datasets (see ex. 1).

type

char*256

mode

offline

default

required

notes

datasets provided are in directory $CSMDATA/NCEPDATA

Additional details: FSURDAT specifies a surface dataset containing time-invariant land properties such as plant functional types and soil textures and time-variant properties such as leaf area index. If FSURDAT is set to the empty string, a new surface dataset is generated at run time for the specified model resolution. The creation of a new surface dataset requires the specification of the full pathname of the following raw datasets: MKSRF_FVEGTYP, MKSRF_FSOITEX, MKSRF_FSOICOL, MKSRF_FLANWAT, MKSRF_FURBAN, MKSRF_FGLACIER, MKSRF_FLAI. These datasets are only used for the generation of a model surface dataset.

In addition to raw datasets, a land/ocean mask is also required for the creation of a new surface dataset. If the model is run in ccsm or cam mode, this mask is obtained from either the ccsm flux coupler or from the cam atmosphere model at startup. In offline mode, however, the land/ocean mask can either be calculated from a high resolution orography dataset by setting the namelist variable MKSRF_OFFLINE_FNAVYORO or can be read in from an input dataset already at the target resolution via the setting of the namelist variable MKSRF_OFFLINE_FGRID.

Finally, if a surface dataset is to be created at run time, the user must specify if a new-format or old-format dataset will be generated. By default, old-format datasets are created. By setting the namelist variable MKSRF_ALL_PFTS to .true., a new-format surface dataset will be created (see section 6).

Subroutines involved in creating a surface dataset at run time reside in the source code directory mksrfdata/. In most cases the creation of a surface dataset involves a straightforward interpolation from the raw dataset resolution to the desired model resolution. For soil texture, however, averaging would create new soil types. Consequently, the model determines the dominant soil texture profile per gridcell from the raw resolution to the desired resolution.

Once the surface dataset is created, the user should use FSURDAT to point to that dataset, in order to avoid creating the same dataset multiple times.

The input file specified by the namelist variable FINIDAT contains values for the time-dependent variables needed to initialize the model from a spun-up state. If FINIDAT is set to the empty string, the model is internally initialized to non spun-up values. The setting of the namelist variable, HIST_CRTINIC (described in section 4.3) can be used to generate initial CLM files during a model run. We also provide a new tool, interpinic, which provides users with the ability to use an already existing initial dataset at one model resolution to generate a new initial dataset at another model resolution. Section 7 provides more details of this tool.

When the cpp token RTM is defined, the RTM river routing scheme will be invoked in running the model. In this case, FRIVINP_RTM must be set to a river routing dataset.

In offline mode, time dependent atmospheric forcing data must be read in periodically. The directory containing these files is given by OFFLINE_ATMDIR. This variable is ignored in cam and ccsm mode.

4.3 Specification of history and restart files

The following describes namelist variables associated with history, restart, and initialization files. In what follows, max_tapes denotes the maximum allowable number of different types of history files (tapes) that the model can produce (currently set to 6) and max_flds denotes the maximum number of history fields that may appear on any given history tape (currently set to 1000).

name

HIST_CRTINIC

description

Frequency with which initial datasets will be generated.
Valid values are 'YEARLY','MONTHLY','DAILY','6-HOURLY' or'NONE'.

type

char*8

mode

offline, ccsm (obtained from CAM in cam mode)

default

'YEARLY'

name

HIST_NHTFRQ

description

History tape interval(s)
(+ for model time steps, - for hours, 0 for monthly ave) (see ex. 1,3).

type

integer array (up to max_tapes values separated by commas)

mode

offline, ccsm (obtained from CAM in cam mode)

default

0

name

HIST_MFILT

description

Number of time samples per history tape(s) (see ex. 3,4).

type

integer array (up to max_tapes values separated by commas)

mode

offline, ccsm (obtained from CAM in cam mode)

default

1 when HIST_NHTFRQ=0, else 30

name

HIST_NDENS

description

Output tape precision(s). Valid values are 1 (double precision) or 2 (single precision).

type

integer array (up to max_tapes values separated by commas)

mode

all

default

2

name

HIST_DOV2XY

description

Per tape spatial averaging flag. If set to true, produces grid-average history fields on output tape. If set to false, one-dimensional fields are produced (see ex. 4).

type

logical array (up to max_tapes values separated by commas)

mode

all

default

.true.

name

HIST_AVGFLAG_PERTAPE

description

Per tape time averaging flag. Valid values are 'A' (average over history period), 'I' (instantaneous), 'X' (maximum over history period) or 'M' (minimum over history period).

type

char*1 array (up to max_tapes values separated by commas)

mode

all

default

blank (in this case a hardwired flag per variable is used, found in histFldsMod.F90)

name

HIST_TYPE1D_PERTAPE

description

Per tape one dimensional output type. Only used if one dimensional output is selected for the given tape (via the setting of HIST_DOV2XY). Valid values are 'GRID', 'LAND', 'COLS', 'PFTS'. For example, if one dimensional output is selected for tape 3 and HIST_TYPE1D_PERTAPE is set to 'COLS', then all the fields will have 1d column output. If the specified one dimensional output type is not defined for a given field, output values will be set to 1.e36 for that field.

type

char*4 array (up to max_tapes values separated by commas)

mode

all

default

blank (in this case a hardwired type per variable is used)

name

HIST_EMPTY_HTAPES

description

If set to true, all the history tapes are empty by default. Only variables explicitly listed by the user will be output.

type

logical

mode

all

default

.false.

name

HIST_FINCL1, ..., HIST_FINCL6

description

List of fields to include on the respective history tape. See tables 9-18 for the list of default fields on the primary history tape. Namelist specification can take one of two forms. The user may simply specify the name of the field to be included on the history tape (in which case the default time averaging for that field will be used). For example, HIST_FINCL2='TV', will add the field TV to the second history tape with whatever default time averaging was specified for TV. Alternatively, the user may specify the field name, followed by a ":" followed by the time averaging flag desired (valid flags are 'I' for instantaneous, 'A' for average, 'M' for minimum, and 'X' for maximum). For example, HIST_FINCL2='TV:I'' will add the field TV with instantaneous output to the second history tape (see ex. 3,4).

type

char*34 array (up to max_flds values separated by commas)

mode

all

default

blank

name

HIST_FEXCL1, ..., HIST_FEXCL6

description

List of fields to exclude from the respective history tape. The field name must appear in the Master Field List of the default history tape (the primary tape). See tables 9-18 for more details.

type

char*32 array (up to max_flds values separated by commas)

mode

all

default

blank

name

MSS_IRT

description

Mass Store retention period (days) for output datasets (see ex. 4). User must have Mass Store access. For example NCAR supercomputers recognize Mass Store commands.

type

integer

mode

offline, ccsm (obtained from CAM in cam mode)

default

0 (i.e., history files will be written to local disk, not the NCAR Mass Store)

name

MSS_WPASS

description

Mass Store write password for output datasets.

type

char*8

mode

all

default

blank

name

RPNTPATH

description

Full unix pathname of the local restart pointer file.

type

char*256

mode

all

default

File lnd.CASEID.rpointer placed in user's home directory

name

ARCHIVE_DIR

description

Mass Store directory to archive output files

type

char*256

mode

all

default

/USERNAME/CSM/CASEID

Additional details: The model writes its own history, restart and initial files. History files are in netCDF file format and contain model data values written at user specified frequencies during a model run. Each field has a default time averaging flag determining how that field will be accumulated in time over a given history interval. The choices are to record averaged, instantaneous, maximum, or minimum values. The user may overwrite this default setting via the namelist variable HIST_FINCLt where t can equal 1 to 6. If the user wishes to see a field written at more than one output frequency (e.g. daily and hourly), additional history files must be declared containing that field. By default, CLM3.0 produces a monthly averaged primary history file and allows the user to define up to five auxiliary history files. All files contain grid averaged data unless the namelist variable HIST_DOV2XY is set to false for a given file. Primary history files contain the string 'h0', whereas auxiliary history files contain the string 'h1', 'h2', 'h3','h4' and 'h5'.

The model will also create netCDF datasets containing one dimensional instantaneous values of initial data fields at the frequency defined by namelist variable HIST_CRTINIC. These datasets can be utilized as ``spun-up'' initial conditions.

Restart files are in binary format and can be used only for restart or branch runs from previous model simulations. Whenever a restart file is written, a corresponding local disk restart pointer file is overwritten. The restart pointer file contains the name of the latest model restart file. By default, the restart pointer file is placed in the user's home directory under the name, lnd.CASEID.rpointer. The user may modify the full pathname of the restart pointer file via the setting of the namelist variable RPNTPATH.

The following table specifies the naming convention used for output files. In this table the string yyyy refers to the model year, mm refers to the model month, dd is the model day and sssss corresponds to seconds into the model day. Initial and restart files always contain one time slice of instantaneous data. However, non-monthly history files may contain multiple time slices of time-averaged data, so yyyy-mm-dd-sssss corresponds to the first timeslice of data on the file. CASEID is the case identifier set via the namelist input.

CASEID.clm2.r.yyyy-mm-dd-sssss

restart files

CASEID.clm2.i.yyyy-mm-dd-sssss.nc

initial files

CASEID.clm2.h[012345].yyyy-mm.nc

monthly average history files

CASEID.clm2.h[012345].yyyy-mm-dd-sssss.nc

non-monthly history files

History, restart and initialization files can be archived on the NCAR Mass Storage System (MSS) if the namelist variable MSS_IRT is set to a value greater than zero. History, restart and initial files are archived as follows (where USERNAME is the upper-case equivalent of the user's login name, i.e., the user's root directory on the MSS):

history files

/USERNAME/csm/CASEID/lnd/hist

restart files

/USERNAME/csm/CASEID/lnd/rest

initial files

/USERNAME/csm/CASEID/lnd/init

4.4 Specification of input physics variables

name

IRAD

description

Frequency of solar radiation calculations (+ for model time steps, - for hours).

type

integer

mode

offline, must be consistent with CAM3.0 in ccsm mode, obtained from CAM in cam mode

default

-1

name

CSM_DOFLXAVE

description

If set to true, flux averaging is performed over the duration set in IRAD.

type

logical

mode

ccsm (must agree with CAM3.0 setting in atm.setup.csh)

default

.true. (.false. not supported)

name

WRTDIA

description

If true, global average 2-m temperature written to standard out (ascii log file of the run) (see ex. 4).

type

logical

mode

all

default

.false.

name

PERTLIM

description

Perturbation limit (not supported at this time)

type

real

mode

all

default

0

4.5 Specification of RTM River routing

name

RTM_NSTEPS

description

Frequency in number of time steps at which RTM is called.

type

integer

mode

all

default

number of timesteps in 3 hours

4.6 Specification of cam mode namelist

When running in cam mode, certain CLM3.0 namelist variables cannot be set independently. In particular, any user specification for the namelist variables, CASEID, CTITLE, IRAD, NSREST, HIST_CRTINIC, MSS_IRT, HIST_NHTFRQ, and HIST_MFILT (the last two only for primary history files) will be overwritten by values obtained from CAM3.0 at startup. All other namelist settings may be set independently by the user.

The following table specifies the namelist variables that are overwritten with values obtained from cam and lists the associated CAM3.0 namelist variable and its default value.

Table 8: Namelist Variables overwritten with CAM settings

CLM Namelist	CAM namelist	CAM default
CASEID	CASEID	required
CTITLE	CTITLE	blank
NSREST	NSREST	0
IRAD	IRADSW	-1
HIST_CRTINIC	INITHIST	'MONTHLY'
HIST_NHTFRQ(1)	NHTFRQ(1)	0
HIST_MFILT(1)	MFILT(1)	1
MSS_IRT	MSS_IRT	365

4.7 Specification of ccsm mode namelist

When running in ccsm mode, the user must ensure that settings of the namelist variables, IRAD, DTIME and CSM_DOFLXAVE, have identical values to the corresponding CAM namelist variables IRADSW, DTIME and FLXAVE in the script cam.buildnml_prestage.csh (see CCSM3.0 User's Guide).

In ccsm mode the RTM input dataset must be specified in the namelist using variable FRIVINP_RTM, because RTM is defined by default.

In ccsm mode, CAM and CLM run on the same grid which depends on the specific ocean domain utilized. Consequently, a different surface dataset is required for each atm/ocn grid combination. Currently all supported ccsm-clm surface datasets will be released with the ccsm distribution. Not supported ones may be generated by the user by setting FSURDAT = ' '.

Additionally, a CLM3.0 spun-up initial dataset may be provided containing values for the time-dependent variables needed to initialize the model from a spun-up state by setting the namelist variable FINIDAT. This file MUST have the same atm/ocn resolution and landmask as the model run for which it will be used. The variables appearing in the FINIDAT file will be internally initialized to non spun-up values at run time if FINIDAT is not set.

Finally, the namelist variable CSM_DOFLXAVE is specific to ccsm mode only. If this variable is set to true (the default setting), flux averaging is performed over the time interval specified by the namelist variable, IRAD (IRAD must be greater than 1). The false setting is not supported.