next up previous contents
Next: 4 History File Fields Up: UsersGuide Previous: 2 Creating and Running   Contents

Subsections

3 Namelist or Resource File Parameters

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.

3.1 Specification of run length, run type and initial run date

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

3.2 Specification of model input datasets

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

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.

3.3 Specification of history and restart files

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):

3.4 Specification of input physics variables

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

3.5 Specification of RTM River routing

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

3.6 Cam mode namelist specification

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.

3.7 Csm mode namelist specifications

When running in csm mode, the user must make sure that the settings of the following namelist variables:

have identical values to the corresponding CAM2.0 namelist variables (see CAM2.0 user's guide).

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.


next up previous contents
Next: 4 History File Fields Up: UsersGuide Previous: 2 Creating and Running   Contents
Mariana Vertenstein 2002-05-16