Go to the bottom of this page. See the search engine and sub-section links.
Go to next page Go to previous page Go to top of this section Go to top page Go to table of contents

Previous Section Headers


User's Guide to NCAR CAM2.0


2. Using CAM2.0

2.2 Model Input Variables

A model run is controlled using the CAM namelist CAMEXP and the CLM2.0 namelist, CLMEXP. The focus of this section is to describe the variables that constitute the CAM namelist input.  For specific namelist examples, see  "Section 2.4 Namelist Examples".

The CAMEXP namelist control variables are broken into the following categories:

Numerous namelist variables are not documented below although they appear in the CAM2.0 release code. We do not ensure that the model will run or that the resulting simulation will be scientifically valid if the user decides to use any of the these undocumented variables. The CCSM Software Engineering Group (CSEG) will not provide support for use of any undocumented variables or features.

Table 2.6 displays supported variables contained in the CAMEXP namelist. Variables are grouped according to the above categories. Namelist variable names displayed in BOLD font must be defined in order for the model to run.  Namelist options added since CAM2.0 are marked with a    Most of the variables in CAMEXP are single-valued, but some are array-valued. Included in the table are the following pieces of information:

CAM is capable of executing using default values for most of the namelist variables (most default values are only appropriate at the T42/26-level resolution). However, some of the namelist variables must be explicitly set by the user in order for the model to execute. The only CAMEXP variables that must be specified are:

Before discussing the namelist variables, a brief summary is given of the types of model runs. An initial run starts the model from an initial conditions dataset. As the model executes, history datasets, restart datasets and initial condition datasets are periodically written. (see "Model Output Datasets") and "Model generated initial condition dataset files" for more details).

In addition to initial simulations, there are two types of continuation runs: restart and branch. A restart run is an exact continuation of a previous simulation from its point of termination. Namelist variables other than NESTEP, NELAPSE, and NSREST should never be modified for restart runs. A branch run, on the other hand, is a new case that uses restart data from a previous simulation to begin the integration. Since a branch run must be a new case, 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 control run. Only history file namelist options should be modified for branch runs. If the user desires to modify other options, such as physics control variables, a new initial run should be done using initial datasets generated by the control run. The user should also note that any namelist variable that can be used as a part or all of a UNIX pathname (e.g. CASEID,NREVSN,..) should only contain characters that are acceptable in UNIX path names.

The description of the land model namelist is given below in Table 2.5. The land model namelist should follow the atmospheric model namelist.

Table 2.4: CAMEXP namelist Input Variables

RUN TYPE

CASEID
Type:   Char*32
Default:   None,  Setting is Required
Example(s):   Ex.1
Description:   Case identifier (saved in history file header record) and normally used as part of the MSS path name (see the ARCHIVE_DIR namelist option). By default also used in output filenames (see the HFILENAME_SPEC namelist option).

CTITLE
Type:   Char*80
Default:   blanks
Example(s):   Ex.1
Description:   Case title

NSREST
Type:  I
Default:   0 
Example(s):    Ex.1,  Ex.3,   Ex.5
Description:   Run type:  0=initial , 1=restart , 3=branch 

TIME MANAGEMENT

STOP_YMD
Type:   Integer
Default:   None,  Setting is Required if NELAPSE and NESTEP not set.
Description:   Stopping date for run encoded in yearmmdd format. Either NELAPSE, NESTEP or STOP_YMD (and possibly STOP_TOD) must be set if not running through flux coupler. (STOP_YMD,STOP_TOD) takes precedence if set. STOP_YMD is not required or used when running in coupled mode.

STOP_TOD
Type:   Integer
Default:   0
Description:   Stopping time of day for run in seconds since 0Z. Not used when running through flux coupler.

NESTEP
Type:   Integer
Default:   None,  Setting is Required if NELAPSE and STOP_YMD not set.
Description:   Ending timestep.
If positive the ending absolute timestep (from the start of the initial run). If negative the ending absolute (from the start of the initial run) number of days to process. .  Either NELAPSE, NESTEP or (STOP_YMD,STOP_TOD) must be set if not running through flux coupler. (STOP_YMD,STOP_TOD) take precedence if set. NESTEP is not required or used when running in coupled mode.

NELAPSE
Type:   Integer
Default:   None,  Setting is Required if NESTEP or STOP_YMD not set. 
Description:   Elapsed time to run.
In iterations (positive) or days (negative) to run. May be entered instead of NESTEP or STOP_YMD and STOP_TOD.  Note, NESTEP is not required or used when running in coupled mode.

DTIME
Type:   Real
Default:   1200. for EUL; 3600. for SLD and fv
Example(s):   Ex.1
Description:   Length of model timestep in seconds.
CAUTION: Changing this variable directly impacts the physical parameterizations in the model and may impact the climate.
Changing resolution usually requires a change in DTIME.

START_YMD
Type:   Integer
Default: Use date from initial condition dataset.
Description:   Starting date for run as yyyymmdd. If not input, value is set to NCDATE from initial dataset header.

START_TOD
Type:   Integer
Default: Use time of day from initial condition dataset.
Description:   Starting time-of-day (seconds). If not input, value is set to NCSEC from initial dataset header.

REF_YMD
Type:   Integer
Default: Use starting date
Description:  Reference date for run as yyyymmdd. The reference date is the reference for the time variable output on the history files.

REF_TOD
Type:   Integer
Default: Use starting time of day.
Description:  Reference time-of-day (seconds).

CALENDAR
Type:   Char*32
Default:   "NO_LEAP"
Valid values:   "NO_LEAP" or "GREGORIAN"
Description:   Calendar type 'NO_LEAP' for consistent 365-days per year or 'GREGORIAN' to include leap-years. Note that if "GREGORIAN" is selected although leap-years will be used in the calender manager the calculation of the earth's orbit still assumes 365 day years.

INPUT DATASETS

BNDTVO
Type:   Char*256
Default:   None,  Setting is Required
Example(s):   Ex.1
Description:   Full pathname of time-variant ozone mixing ratios boundary dataset (NetCDF format). 

BNDTVS
Type:   Char*256
Default:  None,  Setting is Required (unless running with CCSM)
Example(s):   Ex.1,  Ex.2,  Ex.7
Description:   Full pathname of time-variant sea-surface temperature and sea-ice concentration boundary dataset (NetCDF format). 

ABSEMS_DATA
Type:   Char*256
Default:  None, Setting is Required
Description:   Filename of absorption/emission dataset. This file is a required input dataset. It consists of terms used for determining the absorptivity and emissivity of water vapor in the longwave parameterization of radiation.

NCDATA
Type:   Char*256
Default:   None,  Setting is Required
Example(s):   Ex.1,  Ex.2,
Description:   Full pathname of initial dataset (NetCDF format). 

OZNCYC
Type:   Logical
Default:   .TRUE. 
Description:   Flag for yearly cycling of ozone data. If set to .FALSE., a multi-year dataset is assumed.

SSTCYC
Type:   Logical
Default:   .TRUE. 
Example(s):   Ex.7
Description:   Flag for yearly cycling of SST data. If set to .FALSE., a multi-year dataset is assumed. Not used if running with CCSM.

MASS STORE CONTROLS

ARCHIVE_DIR
Type:   Char*256
Default:   /$USER/csm/caseid/ (where caseid if the caseid from the namelist and $USER is the username converted to uppercase.
Description:   Head mass store archival directory name. CAM history files will be stored under $ARCHIVE_DIR/atm/hist, restart files under $ARCHIVE_DIR/atm/rest, and initial files under $ARCHIVE_DIR/atm/init. Land-model output files will be stored under similar directory names with "lnd" to specify the land-model subdirectory.

MSS_IRT
Type:   Integer
Default:   365 
Example(s):  Ex.1,  Ex.2,  Ex.6,  Ex.9
Description:   Retention period in days for history and restart files stored on NCAR Mass Store. If MSS_IRT=0, no history or restart files will be archived.

MSS_WPASS
Type:   Char*8
Default:   blanks
Example(s):  Ex.1,  Ex.5
Description:   NCAR Mass Store write password for all output datasets. Must remain the same throughout a case run, or a continuation run will not update original history files.

HISTORY FILE OPTIONS

EMPTY_HTAPES
Type:   Logical
Default:   .FALSE.
Description:   If set don't put any of the variables on the history tapes by default. Only output the variables that the user explicitly lists in the fincl# namelist items.

HFILENAME_SPEC(ptapes)
Type:   Char*256
Default:   "%c.cam2.h%t.%y-%m","%c.cam2.h%t.%y-%m-%d-%s","%c.cam2.h%t.%y-%m-%d-%s",... 
Description:   Array of history filename specifiers. Filename, specifiers give generic formats for the filenames with the specific dates, file-series number, and caseid, filled in when the files are created. The following strings are expanded when the filename is created: For example, for a simulation with caseid="test" and current date of 0000/12/31 0:00UT, the monthly average files with a filename specifier of "%c.cam2.h%t.%y-%m.nc" expand into "test.cam2.h0.0000-12.nc", daily files with a filename specifier of "%c.cam2.h%t.%y-%m-%d-%s.nc" expand to ""test.cam2.h0.0000-12-31-00000.nc". Spaces are not allowed in filename specifiers. Although the character "/" is allowed in the specifier, it will be interpreted as a directory name and the corresponding directories will have to be created in the model execution directory (directory given to configure with -cam_exedir option) before model execution.

MFILT(ptapes)
Type:   Integer
Default:  30,30,30,...
Example(s):    Ex.1,  Ex.5,  Ex.9
Description:   Array of number of time samples to write to the primary and auxiliary history files (a time sample is the history output from a given timestep).

NDENS(ptapes)
Type:   Integer
Default:  2,2,2,...
Example(s):    Ex.1,  Ex.5,  Ex.9
Description:   Array specifying output format for primary and auxiliary history files. Valid values are 1 or 2. "1" implies output to be written out in 64-bit NetCDF format, and "2" writes data out in 32-bit NetCDF format.

INITHIST
Type:  Char*8
Default: 'NONE'
Valid values: 'NONE', 'MONTHLY', 'YEARLY'
Description:   Frequency that initial files will be output, monthly, yearly, or never.

AVGFLAG_PERTAPE(ptapes)
Type:  Char*1
Default:   Use default averaging flags for each variable
Valid values: 'A', 'I', 'X', 'M'
Description:   To set the averaging flag for all variables on a particular history files series. Valid values include: Average (A), Instantaneous (I), Maximum (X), or Minimum (M). If averaging flags for specific variables are selected using the FINCL options the flags

NHTFRQ(ptapes)
Type:   Integer
Default:   0,-24,-24,-24...
Example(s):    Ex.1,  Ex.5,  Ex.9
Description:   Array of time sample, write frequencies, for primary and auxiliary history files. If NHTFRQ(1)=0, the file will be a monthly average. Only the first file may be a monthly average. If NHTFRQ(i)>0, frequency is input as number of timesteps. If NHTFRQ(i)<0, frequency is input as number of hours.

FINCL1,FINCL2,FINCL3,FINCL4,FINCL5,FINCL6 (pflds)
Type:   Char*8
Default:   blanks
Example(s):    Ex.5,  Ex.6
Description:   List of fields to include on the history files. The added fields must be in Master Field List see Table 2.7 for the list of fields that can be added as well as which fields are on the default primary history files (FINCL1). Table 2.8 gives the list of fields on the default secondary history files (FINCL2). Using a ":" following a field gives the averaging flag for the output field. Valid flags are: I for instantaneous, A for average, M for minimum, and X for maximum. See Section 2.5.1.1 for more information on the averaging flag.

FEXCL1,FEXCL2,FEXCL3,FEXCL4,FEXCL5, FEXCL6 (pflds)
Type:   Char*8
Default:   blanks
Example(s):  Ex.6
Description:   List of fields to exclude on the default history files (must be in Master Field List). The default history files include a monthly series and a daily series. For a list of what fields are included on the primary files and secondary files by default see Table 2.7 and Table 2.8.

PRECC_THRESH
Type:   Real
Default:   0.1
Example(s):
Description:   Precipitation threshhold for use with the PRECCINT and PRECCFRQ fields for history files.

RESTART FILE OPTIONS

NREFRQ
Type:  Integer
Default:   1
Description:   Frequency of restart dataset writes. This variable can only be 1 or 0. If 1, restart files are written and archived for every archive of the primary history file. If this variable is 0, then no restarts are written.

NREVSN
Type:   Char*256
Default:   None,  Setting is Required for branch run.
Description:   Full pathname of master restart file from which to branch. 

REST_PFILE
Type:   Char*256
Default:  '$HOME/cam2.CASEID.rpointer'
Description:   Full pathname of restart pointer file.

DYNAMIC CONTROLS

DIF2
Type:  Real
Default:  2.5E5 for EUL; 0. for SLD*
Description:  del2 horizontal diffusion coefficient. Not used for fv dynamics.

DIF4
Type:  Real
Default:  1.E16 for EUL; 0. for SLD*
Description:  del4 horizontal diffusion coefficient. Not used for fv dynamics.

EPS
Type:   Real
Default:   0.06
Description:  Time filter coefficient.

DIVDAMPN
Type:   Real
Default:   0.0
Description:   Number of days (from timestep 0) to run divergence damper. Use only if model is blowing up because of spin-up problems. Suggested value: 10. (Value must be greater than 0.) Not used for fv dynamics.

IORD
Type:  Integer
Default:   4
Requirements: Only for fv dynamics
Description:   East-west transport (used with Finite-Volume (fv)) dynamical core only.

JORD
Type:   Integer
Default:  4
Requirements: Only for fv dynamics
Description:   North-south transport (used with Finite-Volume (fv)) dynamical core only.

KMXHDC
Type:   Integer
Default:   1 
Description:   Number of levels over which to apply Courant limiter, starting at top of model.

KORD
Type:   Integer
Default:   4
Requirements: Only for fv dynamics
Description:   Vertical mapping (used with Finite-Volume (fv)) dynamical core only.

NSPLIT
Type:  Integer
Default:   UNDEFINED 
Requirements:   fv dynamics only
Description:   Lagrangian time splits when using Finite-Volume dynamics. If zero or not specified, a best-estimate will be automatically calculated.

USE_ETA
Type:   Logical
Default:  .FALSE.
Requirements:  Only for fv dynamics
Description:   If defined to TRUE, use the vertical coordinate (eta) values defined in the finite volume dynamical core code rather than the values defined on the input dataset (used with Finite-Volume (fv)) dynamical core only.

PHYSICS CONTROLS

ADIABATIC
Type:   Logical
Default:  .FALSE. 
Description:   If true, do not run model physics, only run the dynamical core. In this mode, water vapor is advected as a passive tracer.

CO2VMR
Type:   Real
Default:   3.550e-4
Example(s):  Ex.4
Description: CO2 volume mixing ratio 

CH4VMR
Type:  Real
Default:  1.714e-6
Example(s):   Ex.4
Description:CH4 volume mixing ratio.  

F11VMR
Type:  Real
Default:   0.280e-9
Example(s):  Ex.4
Description:  CFC11 volume mixing ratio.

F12VMR
Type:   Real
Default:   0.503e-9
Example(s):  Ex.4
Description:  CFC12 volume mixing ratio.

IRADAE
Type:   Integer
Default:  -12 
Description:   Frequency of absorptivity/emissivity calculations in iterations (if positive) or model hours (if negative). To avoid having the abs/ems values saved on the restart output, this variable should divide evenly into MFILT(1)*NHTFRQ(1).

IRADLW
Type:   Integer
Default:   -1
Example(s):  
Description:   Frequency of long-wave radiation calculation in timesteps (if positive) or model hours (if negative).

IRADSW
Type:   Integer
Default:   -1 
Description:   Frequency of short-wave radiation calculation in timesteps (if positive) or model hours (if negative).

ITSST
Type:  Integer
Default:   1 
Description:  Frequency of SST update in timesteps.

N2OVMR
Type:   Real
Default:   0.311e-6
Example(s):  Ex.4
Description:  N2O volume mixing ratio.

NLVDRY
Type:   Integer
Default:   3 
Description:   Number of layers from the top of the model over which to do dry convective adjustment. Must be less than plev (the number of vertical levels).

PERTLIM
Type:  Real
Default:  0.0
Description:   Perturb the initial conditions for temperature randomly by up to the given amount. Only applied for initial simulations.

PROGNOSTIC_ICESNOW
Type:   Logical
Default:   .TRUE. 
Description:   Accumulate snow over sea-ice (with a 0.5m maximum). If .FALSE. then use a climatology for snow depth.

RESET_CSIM_ICE_PROPS
Type:  Logical
Default:   .FALSE. n
Description:   Reset the CSIM ice-model properties. Snow-cover is set to zero, and ice-temperatures are all set to freezing. This is important when starting from an initial dataset that isn't in equilibrium. This is used, for example, when starting from initial conditions that are interpolated from a different resolution.

SCON
Type:  Real
Default:   1.367E6
Example(s):   Ex.4
Description:  Solar constant (W/m2).

TAUVIS
Type:   Real
Default:   0.14
Description:   Visible optical depth.

NON-WATER CONSTITUENTS

NUSR_ADV
Type:   Integer
Default:   0
Description:  number of user defined advected tracers

NUSR_NAD
Type:   Integer
Default:   0
Description:  number of user defined non-advected tracers

READTRACE
Type:   Logical
Default:  .TRUE. 
Description:   If true and PCNST+PNATS .GT. 1, obtain all initial tracer data from initial conditions dataset.

TRACE_TEST1,TRACE_TEST2,TRACE_TEST3 
Type:   Logical
Default:   .FALSE.
Description:   If TRACE_TEST1 is true, turn on test tracer code with 1 tracer (PCNST=2). If TRACE_TEST2 is true, turn on test tracer code with 2 tracers(PCNST=3).  If TRACE_TEST3 is true, turn on test tracer code with 3 tracers(PCNST=4).  NOTE: these variables are to be used for testing/debugging purposes only. Leave settings to FALSE during production runs.

MEMORY CONTROL

LINEBUF
Type:  Logical
Default:   .FALSE.
Example(s):   Ex.9
Description:   If true, force buffer flush of stdout with each new-line generated (useful for debugging). 

PRINT_STEP_COST
Type:   Logical
Default:  .TRUE.
Description:  If true, print CPU timing per model timestep.

ORBITAL PARAMETERS

ECCEN
Type:  Real
Default:   None,  Setting is Required (if IYEAR_AD not set)
Example(s):  Ex.4
Description:   Earth's eccentricity of orbit. (unitless: typically 0. to 0.1). 

IYEAR_AD
Type:   Integer
Default:  None,  Setting is Required (unless ECCEN, OBLIQ and MVELP are set)
Example(s):   Ex.1,   Ex.4
Description:   Year (AD) used to compute earth's orbital parameters. If not set, then use the values from the eccen, mvelp, and obliq namelist parameters.  If only IYEAR_AD is set, orbital parameters will be computed automatically (based on Berger, 1977). If one of  OBLIQ, ECCEN, OR MVELP is set, all three must be set.  If all four of the above are set by the user, IYEAR_AD takes precedence. 

MVELP
Type:  Real
Default:   None,  Setting is Required (if IYEAR_AD not set)
Example(s):   Ex.4
Description:   Earth's moving vernal equinox at perihelion (degrees: 0. to 360.0). 

OBLIQ
Type:   Real
Default:   None,  Setting is Required (if IYEAR_AD not set)
Example(s):   Ex.4
Description:   Earth's orbital  angle of obliquity 
(degrees: -90. to +90., typically 22. to 26.).

The set of CLMEXP namelist variables that must be specified depends on whether or not a CLM2.0 surface dataset is available at the desired model resolution. If such a dataset exists, then the minimum set CLMEXP of namelist variables that must be specified are


If a CLM surface dataset is to be created at run time, then the following CLM namelist variables must be specified: The above datasets define the time invariant surface information, but do not provide initial condition information for the land model. Initial conditions are specified with the namelist variable "FINIDAT". When initial conditions are given, the surface dataset, and plant function types still need to be specified. NOTE: When the user provides FSURDAT or FINIDAT datasets to the model the surface land mask and orography MUST agree with the land mask and orography of the atmospheric model initial conditions dataset (ncdata). Furthermore, the land informaton must agree between the FINIDAT and FSURDAT datasets as well. For more informaton on CLM namelist options see the CLM2 Documentation at

http://www.cesm.ucar.edu/models/ccsm2.0/clm/.

Note, that several namelist items are only used when running CLM offline, or coupled. Below we only document the variables needed when running CLM as part of CAM.

Table 2.5: CLMEXP namelist Input Variables

FINIDAT
Type:   Char*256
Default:   None
Description: Initial dataset of the land surface model state (initial temperatures, soil water content etcetera). If this dataset is not provided the model will use reasonable values to start from. Note, that some features of the land-surface model take several simulation years to "spin-up" before they reach equilibrium.

FPTFTCON
Type:   Char*256
Default:   None,  Setting is Required
Description: Dataset of plant-function types.

FSURDAT
Type:   Char*256
Default:   None
Description: Time invariant surface dataset for this resolution. Has basic description of land surface vegetation types, fractions, soil colors, soil texture etcetera. If this dataset is not provided on an initial run the high resolution datasets MKSRF_FVEGTYP, MKSRF_FSOITEX, MKSRF_FSOICOL, MKSRF_FLANWAT, MKSRF_FURBAN, MKSRF_FGLACIER, and MKSRF_FLAI will be used to create the surface dataset. On a continuation run (branch or restart) this dataset MUST be provided.

MKSRF_FVEGTYP
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Vegetation Type dataset needed to determine the time-invariant surface dataset (FSURDAT).

MKSRF_FSOITEX
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Soil Texture dataset needed to determine the time-invariant surface dataset (FSURDAT).

MKSRF_FSOICOL
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Soil Color dataset needed to determine the time-invariant surface dataset (FSURDAT).

MKSRF_FLANWAT
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Land water (lake and river) dataset needed to determine the time-invariant surface dataset (FSURDAT).

MKSRF_FURBANP
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Urban Area dataset needed to determine the time-invariant surface dataset (FSURDAT).

MKSRF_FGLACIER
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Glacier dataset needed to determine the time-invariant surface dataset (FSURDAT).

MKSRF_FLAI
Type:   Char*256 (Required if FSURDAT not defined)
Default:   None
Description: High resolution Leaf Area Index (LAI) dataset needed to determine the time-invariant surface dataset (FSURDAT).

 Go to the top of this page. See links to previous section headers.
Go to next page Go to previous page Go to top of this section Go to top page Go to table of contents

 Search for keywords in the CAM2.0 Users GuideSearch page

Questions on these pages can be sent to... erik@ucar.edu .

$Name: $ $Revision: 1.1 $ $Date: 2004/06/08 02:57:21 $ $Author: jmccaa $