CLM2.0 namelist inputs are presented in several tables below. In these tables, "mode" has values of "offline", "csm", "cam" or "all", corresponding to offline mode, csm mode, cam mode, or all the modes. If a namelist variable setting is listed as REQUIRED, then the value must be set in the namelist in order for CLM2.0 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 5.
The following table specifies namelist variables associated with the definition of run case names, types (restart, initial or branch), model time step, and initial run date. An initial run starts the model from either arbitrary initial conditions that are set internally in the code or using 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 restart data 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.
| Namelist: Define the type and length of run | |
| CASEID | |
| description | case name (short identifier for run) (see ex. 3) |
| type | char*32 |
| mode | offline, csm (obtained from atm in cam mode) |
| default | REQUIRED (must be changed for branch run) |
| CTITLE | |
| description | case title for use within history files (long identifier) |
| type | char*80 |
| mode | offline, csm (obtained from atm in cam mode) |
| default | blank |
| NSREST | |
| description | run type (0 for initial run, 1 for restart, 3 for branch) (see ex. 1) |
| type | integer |
| mode | offline, csm (obtained from atm in cam mode) |
| default | REQUIRED |
| DTIME | |
| description | model time step (seconds) (see ex. 1) |
| type | real |
| mode | offline, must agree with CAM in csm mode, obtained from atm in cam mode |
| default | REQUIRED (suggested range: 1200-3600 s) |
| NELAPSE | |
| description | elapsed run time in model time steps (positive) or days (negative) (see ex. 2) |
| type | integer |
| mode | offline (obtained from atm/coupler in cam/csm mode, respectively) |
| default | REQUIRED (if NESTEP not set) |
| NESTEP | |
| description | ending run time in model time steps (positive) or days (negative) (see ex.ample 1) |
| type | integer |
| mode | offline (obtained from atm/coupler in cam/csm mode, respectively) |
| default | REQUIRED (if NELAPSE not set) |
| START_YMD | |
| description | start date of run (yyyymmdd format) (see ex. 1) |
| type | integer |
| mode | offline, csm (obtained from atm in cam mode) |
| default | REQUIRED |
| START_TOD | |
| description | start time of day of run (seconds) (see ex. 1) |
| type | integer |
| mode | offline, csm (obtained from atm in cam mode) |
| default | 0 |
| Namelist: Input datasets | |
| FINIDAT | |
| description | full pathname of initial conditions dataset (see ex. 4) |
| type | char*256 |
| mode | all |
| default | blank |
| notes | datasets provided are in $MODEL_DATADIR/inidata |
| FSURDAT | |
| description | full pathname of surface dataset (see ex. 1) |
| type | char*256 |
| mode | all |
| default | blank |
| notes | raw datasets to generate surface dataset provided are in $MODEL_DATADIR/rawdata |
| surface datasets provided with the distribution are in $MODEL_DATADIR/srfdata | |
| 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 $MODEL_DATADIR/pftdata/pft-physiology |
| FRIVINP_RTM | |
| description | full pathname of RTM input dataset (see ex. 4) |
| type | char*256 |
| mode | offline, csm |
| default | REQUIRED if cpp token RTM is defined in preproc.h |
| notes | dataset provided is $MODEL_DATADIR/rtmdata/rdirc.05 |
| 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) |
| MKSRF_FVEGTYP | |
| description | full pathname of raw vegetation type dataset (see ex. 5) |
| type | char*256 |
| mode | all |
| default | REQUIRED (if FSURDAT is blank) |
| notes | dataset provided is $MODEL_DATADIR/rawdata/mksrf_pft.nc |
| 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 $MODEL_DATADIR/rawdata/mksrf_soitex.10level.nc |
| 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 | $MODEL_DATADIR/rawdata/mksrf_soicol_clm2.nc |
| 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 $MODEL_DATADIR/rawdata/mksrf_lanwat.nc |
| 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 $MODEL_DATADIR/rawdata/mksrf_urban.nc |
| 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 $MODEL_DATADIR/rawdata/mksrf_glacier.nc |
| 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 $MODEL_DATADIR/rawdata/mksrf_lai.nc |
| 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 $MODEL_DATADIR/rawdata/mksrf_navyoro_20min.nc |
| MKSRF_OFFLINE_FGRID | |
| description | dataset specifying land grid and mask at desired resolution |
| type | char*256 |
| mode | offline |
| default | blank, REQUIRED (if MKSRF_OFFLINE_FNAVYORO not set and fsurdat is blank) |
| MKSRF_OFFLINE_EDGEN | |
| description | northern edge of land grid (degrees north) (see ex. 5) |
| type | real |
| mode | offline |
| default | 90. |
| MKSRF_OFFLINE_EDGEE | |
| description | eastern edge of land grid (degrees east) (see ex. 5) |
| type | real |
| mode | offline |
| default | 180. |
| MKSRF_OFFLINE_EDGES | |
| description | southern edge of land grid (degrees north) (see ex. 5) |
| type | real |
| mode | offline |
| default | -90. |
| MKSRF_OFFLINE_EDGEW | |
| description | western edge of grid land (degrees east) (see ex. 5) |
| type | real |
| mode | offline |
| default | -180. |
| OFFLINE_ATMDIR | |
| description | directory containing atmospheric forcing datasets (see ex. 1) |
| type | char*256 |
| mode | offline |
| default | REQUIRED |
| notes | data provided is in directory $MODEL_DATADIR/NCEPDATA |
The file, 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. Several surface datasets are provided with the distribution:
If the value of FSURDAT is set to the empty string, a new surface dataset will be generated at run time for the specified model resolution and land/ocean mask. The creation of the new surface dataset requires that the full pathname of the following raw datasets be specified:
These raw datasets are only used when a surface dataset is created at run time. The required raw datasets are provided with the distribution and are contained in the directory $MODEL_DATADIR/rawdata.
In addition to raw datasets, a land/ocean mask is required in order for a new surface dataset to be created. If CLM2.0 is run in csm or cam mode, this mask is obtained from either the CCSM flux coupler or from the CAM atmosphere model at run time. 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 a dataset via the setting of the namelist variable MKSRF_OFFLINE_FGRID.
Subroutines involved in creating a surface data set from the raw data
reside in the directory
$MODEL_SRCDIR/mksrfdata. In most cases the
creation of a surface dataset involves a straightforward interpolation
from the raw data 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 CLM2.0 code reads it back in so that the same
results will be obtained regardless of whether a run starts from an
existing surface dataset or creates one at the same resolution at
start up.
The file, FINIDAT, contains values for the time-dependent variables needed to initialize CLM2.0 from a spun-up state. If FINIDAT is set to the empty string, these variables are initialized to non spun-up values in CLM2.0. HIST_CRTINIC described in the next section can be used to create these files during a model run. CLM2.0 initial datasets provided with the distribution can be found in the following directories:
FPFTCON specifies the data file containing plant functional type physiological constants. The dataset provided with the distribution is $MODEL_DATADIR/pftdata/pft-physiology.
If the cpp token RTM is defined, then the RTM river routing scheme will be invoked in running CLM2.0. In this case, FRIVINP_RTM must be set to a river routing dataset. The dataset provided with the distribution is $MODEL_DATADIR/rtmdata/rdirc.05
NREVSN is ignored unless a branch run is specified (i.e., NSREST is set to 3).
In offline mode, time dependent atmospheric forcing data must be read in. The directory containing these files is given by OFFLINE_ATMDIR. The forcing data provided with the distribution can be found in $MODEL_DATADIR/NCEPDATA. This variable is ignored in cam or csm mode.
The following table specifies namelist variables associated with history, restart, and initialization files.
| Namelist: History and restart files | |
| HIST_CRTINIC | |
| description | frequency to generate initial dataset that can be used for future initial runs [set to 'MONTHLY','YEARLY','NONE'] |
| type | char*8 |
| mode | offline, csm (obtained from atm in cam mode) |
| default | 'YEARLY' |
| HIST_NHTFRQ(1) | |
| description | primary history file interval (+ for model time steps, - for hours, 0 for monthly ave) (see ex. 4) |
| type | integer |
| mode | offline, csm (obtained from atm in cam mode) |
| default | -24 |
| HIST_MFILT(1) | |
| description | number of time samples per primary history file (see ex. 4) |
| type | integer |
| mode | offline, csm (obtained from atm in cam mode) |
| default | 1 |
| HIST_NHTFRQ(2:maxhist) | |
| description | auxillary history file interval (see ex. 4) |
| type | integer |
| mode | all |
| default | required (if auxillary files are requested) |
| HIST_MFILT(2:maxhist) | |
| description | number of time samples per auxiliary history file (see ex. 4) |
| type | integer |
| mode | all |
| default | required (if auxillary files are requested) |
| HIST_NDENS | |
| description | output file precision, 1 (double precision) or 2 (single precision) |
| type | integer |
| mode | all |
| default | 1 |
| HIST_DOV2XY(1:maxhist) | |
| description | true if want grid-average history field as opposed to vector history field (see ex. 4) |
| type | logical |
| mode | all |
| default | true |
| HIST_CHNTYP(2,maxalflds) | |
| description | paired field name and field type (i.e., instant, maximum, minimum, average, constant) to override default settings (see ex. 4) |
| type | char*8 |
| mode | all |
| default | blank |
| HIST_FLDAUX1(maxalflds) | |
| description | names of fields for first auxillary history file (see ex. 4) |
| type | char*8 |
| mode | all |
| default | blank |
| HIST_FLDAUX2(maxalflds) | |
| description | names of fields for second auxillary history file |
| type | char*8 |
| mode | all |
| default | blank |
| HIST_FLDADD(maxalflds) | |
| description | names of fields to change to active in primary history file (see ex. 4) |
| type | char*8 |
| mode | all |
| default | blank |
| MSS_IRT | |
| description | mass store retention period (days) (see ex. 4) |
| type | integer |
| mode | offline, csm (obtained from atm in cam mode) |
| default | 0 (i.e., history files will be written to local disk, not the mass store) |
| MSS_WPASS | |
| description | mass store write password for output data sets |
| type | char*8 |
| mode | all |
| default | blank |
| RPNTPATH | |
| description | full unix pathname of the local restart pointer file |
| type | char*256 |
| mode | all |
| default | lnd.CASEID.rpointer in home directory |
CLM2.0 writes its own history, restart and initial files. History files
are in netCDF file format and contain model data values written at
specified times during a run. Generally these values are
time-averaged. CLM2.0 produces a primary history file and allows the user to
define up to two auxiliary history files. Primary history files contain the
string 'h0', whereas auxiliary history files contain the string 'h1'
or 'h2'.
Initial dataset files are
instantaneous netCDF files containing only initial data
fields. CLM2.0 produces initial datasets either yearly, monthly, or
not at all depending on the setting of the namelist variable HIST_CRTINIC (the default setting is ``YEARLY''). These
datasets can be utilized as ``spun-up'' initial conditions.
Restart files are in binary format and can be used only to
restart or branch runs from previous model simulations. Whenever a
restart file is written, a corresponding restart pointer file on local
disk (lnd.CASEID.rpointer) is overwritten.
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. Note that for non-monthly history files, yyyy-mm-dd-sssss corresponds to the first timestamp of data on the file. CASEID is the case identifier set via the namelist input.
| File Name | Synopsis |
| CASEID.clm2.r.yyyy-mm-dd-sssss | restart file |
| CASEID.clm2.i.yyyy-mm-dd-sssss | initial file |
| CASEID.clm2.h[012].yyyy-mm | monthly average history file (primary or aux) |
| CASEID.clm2.h[012].yyyy-mm-dd-sssss | non-monthly history file (primary or aux) |
Model parameters relating to history files appear in routine src/main/clm_varpar.F90. The maximum number of history files is set by the parameter maxhist. Currently, there can be at most two auxiliary history files (the dimension maxhist is set to 3). The maximum number of fields is set by the parameter, maxalflds, whose dimension is defined as the sum of the maximum allowable single-level fields (75) and multi-level fields (10).
History fields are either defined as 'active' or 'inactive'. These default settings are set in routine src/main/histFileMod.F90. Default inactive fields can be made active by setting the HIST_FLDADD variable to the appropriate field name via the namelist input. All active fields will appear on the primary history file. A field set to inactive cannot appear on auxillary files.
The namelist variables HIST_FLDAUX1 and HIST_FLDAUX2 are used to specify desired output fields on auxiliary history files. Time averaging aspects of auxiliary files are controlled via settings of the namelist variables HIST_NHTFRQ(2:maxhist) and HIST_MFILT(2:maxhist).
Field time averaging types can be overridden by setting the HIST_CHNTYP variable to the appropriate field name. Valid field types are "average" (average field over history interval), "maximum" (maximum field value), "minimum" (minimum field value), "instant" (instantaneous field value) and "constant" (time invariant field value). An example of this specification would be, HIST_CHNTYP = 'TSA','maximum'. This specifies that the 2-m air temperature is to be recorded on the primary history file as a maximum value over the specified history interval (e.g., if the history interval is monthly, the recorded value would be the maximum value of the 2-m air temperature occurring within that month).
The default averaging for each field and a list of active fields can be found in the routine src/main/histFileMod.F90. The table in section 4 contains a list of all fields currently in histFileMod.F90.
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):
| Namelist: Input physics | |
| CONCHK | |
| description | does error checks on energy and water conservation (see example 4) |
| type | logical |
| mode | all |
| default | true |
| IRAD | |
| description | frequency of solar radiation calculations (+ for model time steps, - for hours) (see ex. 4) |
| type | integer |
| mode | offline, must be consistent with CAM in csm mode |
| obtained from atm in cam mode | |
| default | -1 |
| CSM_DOFLXAVE | |
| description | if true, flux averaging is performed over the duration set in IRAD |
| type | logical |
| mode | csm (must agree with CAM setting) |
| default | true |
| 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 |
| Namelist: RTM River Routing | |
| RTM_NSTEPS | |
| description | average rtm output over rtm_nsteps time steps |
| type | integer |
| mode | all |
| default | number of timesteps in 3 hours |
When running CLM2.0 in cam mode, certain CLM2.0 namelist variables cannot be set independently. In particular, any user specification for the CLM2.0 namelist variables, CASEID, CTITLE, IRAD, NSREST, HIST_CRTINIC, HIST_NHTFRQ(1), HIST_MFILT(1), MSS_IRT will be overwritten by values obtained from the CAM model. All other namelist settings that are active in cam mode may be set independently by the user.
The following table specifies the CLM namelist variables that are overwritten with CAM values, and lists the associated CAM namelist variable and its default value.
| CASEID | |
| CAM namelist | CASEID |
| CAM default | REQUIRED |
| CTITLE | |
| CAM namelist | CTITLE |
| CAM default | blank |
| NSREST | |
| CAM namelist | NSREST |
| CAM default | 0 |
| IRAD | |
| CAM namelist | IRADSW |
| CAM default | -1 |
| HIST_CRTINIC | |
| CAM namelist | INITHIST |
| CAM default | 'MONTHLY' |
| HIST_NHTFRQ(1) | |
| CAM namelist | NHTFRQ(1) |
| CAM default | 0 |
| HIST_MFILT(1) | |
| CAM namelist | MFILT(1) |
| CAM default | 1 |
| MSS_IRT | |
| CAM namelist | MSS_IRT |
| CAM default | 365 |
The minimum set of CLM2.0 namelist variables that must be given values in the input namelist depends on if a pre-existing surface dataset and/or initial dataset will be used and if RTM is enabled. At a minimum, only the namelist variables FPFTCON must be given a value if no surface dataset exists and if the cpp variable RTM is not defined. If RTM is defined, then FRIVINP_RTM must also be specified. Finally, the namelist variables FSURDAT and/or FINIDAT must be set appropriately if a pre-existing surface dataset and/or initial datasets are to be utilized.
When running in csm mode, the user must make sure that the settings of the following namelist variables:
Two input datsets are required in csm mode: an RTM input dataset, rdirc.05, associated with the namelist variable FRIVINP_RTM and a dataset containing ecophysiological constants, pft-physiology, associated with the namelist variable FPFTCON.
Two other input datasets may also be provided, but are not required. A surface dataset will be generated at run time if the namelist variable FSURDAT is not specified. In csm mode, the CAM and CLM2.0 grids must be identical. However, the land mask for this grid is provided by the flux coupler at run time. This land mask is dependent on the specific ocean domain being used. Consequently, a different surface dataset is required for each atm/ocn grid combination. Surface dataset names are automatically generated by lnd.setup.csh given the corresponding atm/ocn resolutions. Currently, two standard combinations are supported: [T42 atm] with [gx1v3 ocn] and [T31 atm] with [gx3 ocn].
Additionally, a spun-up initial dataset may be provided containing values for the time-dependent variables needed to initialize CLM2.0 from a spun-up state by setting the namelist FINIDAT. This file MUST have the same atm/ocn resolution as the model run. These variables are initialized to non spun-up values in CLM2.0 if FINIDAT is not set.
Finally, the only CLM2.0 namelist variable that is specific to csm mode is CSM_DOFLXAVE. If this variable is set to true, flux averaging is perfromed over the duration that the namelist variable IRAD is set to.