env_run.xml variables

case run directory (by default will be set to $EXEROOT/../run) .
The directory where the executable will be run.
By default this is set to EXEROOT/../run.
RUNDIR allows you to keep the run directory separate from the build directory.

CCSM tag

case description

Run initialization type .
Determines the model run initialization type.
This setting is only important for the initial run of a production run when the
CONTINUE_RUN variable is set to FALSE.  After the initial run, the CONTINUE_RUN
variable is set to TRUE, and the model restarts exactly using input
files in a case, date, and bit-for-bit continuous fashion.
Default: startup.
-- In a startup run (the default), all components are initialized
using baseline states.  These baseline states are set independently by
each component and can include the use of restart files, initial
files, external observed data files, or internal initialization (i.e.,
a cold start). In a startup run, the coupler sends the start date to
the components at initialization. In addition, the coupler does not
need an input data file.  In a startup initialization, the ocean model
does not start until the second ocean coupling (normally the second
day).
-- In a branch run, all components are initialized using a consistent
set of restart files from a previous run (determined by the
RUN_REFCASE and RUN_REFDATE variables in env_run.xml).  The case name
is generally changed for a branch run, although it does not have to
be. In a branch run, setting RUN_STARTDATE is ignored because the
model components obtain the start date from their restart datasets.
Therefore, the start date cannot be changed for a branch run. This is
the same mechanism that is used for performing a restart run (where
CONTINUE_RUN is set to TRUE in the env_run.xml) Branch runs are
typically used when sensitivity or parameter studies are required, or
when settings for history file output streams need to be modified
while still maintaining bit-for-bit reproducibility. Under this
scenario, the new case is able to produce an exact bit-for-bit restart
in the same manner as a continuation run IF no source code or
component namelist inputs are modified. All models use restart files
to perform this type of run.  RUN_REFCASE and RUN_REFDATE are required
for branch runs.
To set up a branch run, locate the restart tar file or restart
directory for RUN_REFCASE and RUN_REFDATE from a previous run, then
place those files in the RUNDIR directory.
--- A hybrid run indicates that the model is initialized more like a
startup, but uses initialization datasets FROM A PREVIOUS case.  This
is somewhat analogous to a branch run with relaxed restart
constraints.  A hybrid run allows users to bring together combinations
of initial/restart files from a previous case (specified by
RUN_REFCASE) at a given model output date (specified by
RUN_REFDATE). Unlike a branch run, the starting date of a hybrid run
(specified by RUN_STARTDATE) can be modified relative to the reference
case. In a hybrid run, the model does not continue in a bit-for-bit
fashion with respect to the reference case. The resulting climate,
however, should be continuous provided that no model source code or
namelists are changed in the hybrid run.  In a hybrid initialization,
the ocean model does not start until the second ocean coupling
(normally the second day), and the coupler does a cold start without
a restart file.
Valid Values: startup,hybrid,branch 

Run start date (yyyy-mm-dd). Only used for startup or hybrid runs

start time-of-day

Reference case for hybrid or branch runs

Reference date for hybrid or branch runs (yyyy-mm-dd)

Reference time of day (seconds) for hybrid or branch runs (sssss)

allow same branch casename as reference casename
Valid Values: TRUE,FALSE 

flag for automatically prestaging the refcase restart dataset
Valid Values: TRUE,FALSE 

sets the run length with STOP_N and STOP_DATE (must be nyear(s) for _GLC compsets for restarts to work properly) .
Ending simulation time (character)
(must be nyear(s) for _GLC compsets for restarts to work properly)
Valid Values: none,never,nsteps,nstep,nseconds,nsecond,nminutes,nminute,nhours,nhour,ndays,nday,nmonths,nmonth,nyears,nyear,date,ifdays0,end 

sets the run length with STOP_OPTION and STOP_DATE .
Provides a numerical count for $STOP_OPTION. (integer)

date in yyyymmdd format, sets the run length with STOP_OPTION and STOP_N .
Alternative yyyymmdd date option, negative value implies off. (integer)

sets frequency of model restart writes (same options as STOP_OPTION) (must be nyear(s) for _GLC compsets) .
Restart write interval.
valid varlues: none,never,nsteps,nstep,nseconds,nsecond,nminutes,nminute,nhours,nhour,ndays,nday,nmonths,nmonth,nyears,nyear,date,ifdays0,end
(must be nyear(s) for _GLC compsets)

sets model restart writes with REST_OPTION and REST_DATE .
Number of intervals to write a restart. (integer)

date in yyyymmdd format, sets model restart write date with REST_OPTION and REST_N .
Alternative yyyymmdd date option, negative value implies off. (integer)

A setting of TRUE implies a continuation run .
When you first begin a branch, hybrid or startup run, CONTINUE_RUN
must be set to FALSE. When you successfully run and get a restart
file, you will need to change CONTINUE_RUN to TRUE for the remainder
of your run. This variable determines if the run is a restart run.
Set to FALSE when initializing a startup, branch or hybrid case.
Set to TRUE when continuing a run. (logical)
Valid Values: TRUE,FALSE 

If RESUBMIT is greater than 0, then case will automatically resubmit .
Enables the model to automatically resubmit a new run.  To get
multiple runs, set RESUBMIT greater than 0, then RESUBMIT will be
decremented and the case will be resubmitted.  The case will stop automatically
resubmitting when the RESUBMIT value reaches 0.
Long runs can easily outstrip supercomputer queue time limits. For
this reason, a case is usually run as a series of jobs, each
restarting where the previous finished.

logical that turns on diagnostic budgets
Valid Values: TRUE,FALSE 

Turns on component varying thread control in the driver
Valid Values: TRUE,FALSE 

Turns on component barriers for component timing
Valid Values: TRUE,FALSE 

turns on bit-for-bit reproducibility with varying pe counts in coupler
Valid Values: TRUE,FALSE 

level of debug output, 0=minimum, 1=normal, 2=more, 3=too much
Valid Values: 0,1,2,3 

timer output depth

cpl decomp option
Valid Values: 0,1,2,3,4,5,6 

logical to diagnose model timing at the end of the run
Valid Values: TRUE,FALSE 

logical to save timing files in rundir
Valid Values: TRUE,FALSE 

TRUE implies perform asynchronous i/o
Valid Values: TRUE,FALSE 

mpi task stride between io tasks

pio root processor

pio number of io tasks

pio io type
Valid Values: netcdf,pnetcdf,netcdf4p,netcdf4c,default 

pio debug level
Valid Values: 0,1,2,3,4,5,6 

pio blocksize

pio buffer size limit

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

pio stride

pio root processor

pio number of io tasks

pio io type
Valid Values: nothing,netcdf,pnetcdf,netcdf4p,netcdf4c 

mpi run command

sets coupler snapshot history file frequency (like REST_OPTION)

sets coupler snapshot history file frequency (like REST_N)

yyyymmdd format, sets coupler snapshot history date (like REST_DATE)

base period associated with NCPL coupling frequency
Valid Values: hour,day,year,decade 

number of atm coupling intervals per NCPL_BASE_PERIOD (integer)

number of land coupling intervals per NCPL_BASE_PERIOD (integer)

number of ice coupling intervals per NCPL_BASE_PERIOD (integer)

number of ocn coupling intervals per NCPL_BASE_PERIOD (integer)

number of glc coupling intervals per NCPL_BASE_PERIOD (integer)

number of rof coupling intervals per NCPL_BASE_PERIOD (integer)

if TRUE, treats ocean model like lnd/ice in coupling
Valid Values: TRUE,FALSE 

Latitude to find nearest points for points mode

Longitude to find nearest points for points mode

atm domain file

path of atm domain file

lnd domain file

path of lnd domain file

rof domain file

path of rof domain file

ice domain file

path of ice domain file

ocn domain file

path of ocn domain file

local inputdata directory for CCSM prestaged data .
The root directory of CESM input data for the selected machine.
This is usually a shared disk area.
Default values for the target machine are in the
$CCSMROOT/scripts/ccsm_utils/Machines/config_machines.xml

general ccsm inputdata directory for CLM datm forcing .
CLM-specific root directory for CLM type input forcing data.
This directory will only be used for I (CLM/DATM) compsets and only
for datm forcing data that is NOT checked into the svn repository
(datasets other than the Qian or single-point forcing).
This is usually a shared disk area.
Default values for the target machine are in the
$CCSMROOT/scripts/ccsm_utils/Machines/config_machines.xml

directory where log files should be copied .
Extra copies of the component log files will be saved here.

logical to turn on short term archiving .
If TRUE, short term archiving will be turned on. (default is TRUE)
Valid Values: TRUE,FALSE 

local short term archiving root directory .
Root directory for short term archiving. This directory must be
visible to compute nodes.

logical to archive all interim restart files, not just those at eor .
If TRUE, perform short term archiving on all interim restart files,
not just those at the end of the run. By default, this value is FALSE.
This is for expert users ONLY and requires expert knowledge. We will
not document this further in this guide.
Valid Values: TRUE,FALSE 

logical to turn on long term archiving (if DOUT_S is also TRUE) .
If TRUE, perform long-term archiving on the output data. Default is FALSE
Valid Values: TRUE,FALSE 

local long term archiving root directory .
Root directory on long term archiving store system for long-term data archives.

hpss account number

logical to tar up long term archiver history files .
If true, DOUT_L_HTAR the long-term archiver will store history data in annual tar files.
Default is FALSE
Valid Values: TRUE,FALSE 

standard ccsm baselines directory for testing

standard location of the cprnc tool

Only used for C,G compsets: if ocn, ocn provides EP balance factor for precip .
Provides EP balance factor for precip for POP2. A factor computed by
POP2 is applied to precipitation so that precipitation balances
evaporation and ocn global salinity does not drift. This is intended
for use when coupling POP2 to a DATM. Only used for C and G compsets.
Default is off.
Valid Values: off,ocn 

Only used for C,G compsets: if true, compute albedos to work with daily avg SW down .
If false, albedos are computed with the assumption that downward
solar radiation from the atm component has a diurnal cycle and
zenith-angle dependence. This is normally the case when using an active
atm component
If true, albedos are computed with the assumption that downward
solar radiation from the atm component is a daily average quantity and
does not have a zenith-angle dependence. This is often the case when
using a data atm component.
This is only used for C and G compsets.
Default is false.
Valid Values: true,false 

BGC flag .
If the value is not none, the coupler is compiled so that optional
BGC related fields are exchanged between component models.  Currently
only none and CO2A are supported.  CO2A will activate sending
diagnostic and prognostic co2 from the atm component to the lnd component.
Valid Values: none,CO2A,CO2B,CO2C,CO2_DMSA 

Glacier model number of elevation classes, 0 implies no glacier land unit in clm .
Used by both CLM and CISM (even if CISM is not running, and only SGLC is used)
Valid Values: 0,1,3,5,10 

CO2 ppmv .
This set the namelist values of CO2 ppmv for CAM and CLM. This variables is
introduced to coordinate this value among multiple components. 

CAM namelist use_case .
Provides the use_case option for the CAM build-namelist utility
(which is called from $CASEROOT/Buildconf/cam.buildnml.csh).
The CAM build-namelist leverages groups of namelist options
(use cases) that are often paired with the CAM configure options.
These use cases are xml files located in
$CCSMROOT/models/atm/cam/bld/namelist_files/use_cases.
In general, this variable should not be modified for supported
component sets (compsets).
Recommendation: If you want to modify this value for your experiment,
use your own user-defined component sets.

CAM specific namelist settings for -namelist option .
Provides options to the -namelist argument for the CAM build-namelist utility (see above).
This should be reserved for component set specification. Users
should modify CAM namelists only via the $CASEROOT/user_nl_cam file

CLM build-namelist options

CLM namelist use_case . Determines the use-case that will be sent to the CLM build-namelist utility.
This is normally set by the component set. This is an advanced flag and should only be
used by expert users.

CLM specific namelist settings . CLM-specific namelist settings for -namelist option in the CLM
build-namelist. CLM_NAMELIST_OPTS is normally set as a compset variable
and in general should not be modified for supported compsets.
It is recommended that if you want to modify this value for your experiment,
you should use your own user-defined component sets via using create_newcase
with a compset_file argument.
This is an advanced flag and should only be used by expert users.

clm co2 type .
Determines how CLM will determine where CO2 is set.
If value is constant, it will be set to CCSM_CO2_PPMV,
if value is either diagnostic or prognostic, the atmosphere model
MUST send it to CLM. CLM_CO2_TYPE is normally set by the specific
compset, since it HAS to be coordinated with settings for the
atmospheric model. Do not modify this variable. If you want to modify for
your experiment, use your own user-defined component set
This is an advanced flag and should only be used by expert users.
Valid Values: constant,diagnostic,prognostic 

Force CLM model to do a cold-start .
Flag to the CLM build-namelist command to force CLM to do a
cold start (finidat will be set to blanks).
A value of on forces the model to spin up from a cold-start
(arbitrary initial conditions). Setting this value in the xml file will take
precedence over any settings for finidat in the $CASEROOT/user_clm_clm file.
Valid Values: on,off 

My Data ID .
Dataset name for user-created datasets. This is used as the argument
in Buildconf/clm.buildnml.csh to build-namelist -clm_usr_name. An example of
such a dataset would be 1x1pt_boulderCO_c090722. The default value is UNSET.
This is an advanced flag and should only be used by expert users.

CICE specific namelist settings for -namelist option

surface heat and freshwater forcing, partial is consistent with coupling to a data atm model .
Determine surface freshwater and heat forcing settings.
The full option yields settings that are appropriate for coupling to an
active atmospheric model (e.g., a B-type compset). The partial option yields
settings that are appropriate for coupling to a data atmospheric model
(e.g., a C or G-type compset). The create_newcase command selects the
appropriate setting for this variable based on the specified compset.
Users should NOT EDIT this setting.
Valid Values: full,partial 

under ice forcing, inactive is consistent with coupling to a data ice model .
Determine under-ice forcing settings.
The active option yields settings that are appropriate for coupling to an active ice model
(e.g., a B or G-type compset). The inactive option yields settings that are appropriate for
coupling to a data ice model (e.g., a C-type compset). The create_newcase command
selects the appropriate setting for this variable based on the specified compset.
Users should NOT EDIT this setting.
Valid Values: active,inactive 

provenance of surface Chl for radiative penetration computations .
Determines provenance of surface Chl for radiative penetration
computations. This option is used in the POP2 ecosystem model.
The default is diagnostic.
Valid Values: diagnostic,prognostic 

provenance of atmospheric CO2 for gas flux computation .
Determines provenance of atmospheric CO2 for gas flux computation.
This option is used in the POP2 ecosystem model.
The default is constant.
Valid Values: constant,prognostic,diagnostic 

TRUE implies using fix to pH scale of carbon thermodynamic constants
Valid Values: TRUE,FALSE 

specification of transient forcing datasets .
Determine settings for transient forcing datasets (e.g., atmospheric pCFC
concentrations). The create_newcase command selects the appropriate setting for this
variable based on the specified compset. This option is used in the POP2 ecosystem model.
Users should NOT EDIT this setting.
Valid Values: unset,1850-2000 

tavg output control for tracer-budget terms
Valid Values: TRUE,FALSE 

tavg output control for high-frequency output
Valid Values: TRUE,FALSE 

Glacier model grid - used only for glacier land mask in clm .
Currently the GLC grid and GLC_NX and GLC_NY is assumed to be
identical to the land grid. GLC_GRID determines the specific local internal
grid that CISM will use for internal calculations.
The default is gland5UM (5km grid).
Valid Values: gland20,gland10,gland5,gland5UM 

Valid Values: true,false 

DATM mode .
Mode for data atmosphere component.
The default is CORE2_NYF (CORE2 normal year forcing) is the
DATM mode used in C and G compsets. CLM_QIAN and CLM1PT are
modes using observational data for forcing CLM in I compsets.
Valid Values: CORE2_NYF,CORE2_IAF,TN460,CLM_QIAN,CLM1PT,CPLHIST3HrWx,COPYALL_NPS_v1,COPYALL_NPS_CORE2_v1,WRF 

DATM prescribed aerosol forcing
Valid Values: none,clim_1850,clim_2000,trans_1850-2000,rcp2.6,rcp4.5,rcp6.0,rcp8.5,pt1_pt1 

year align (only used for CLM_QIAN mode)

starting year to loop data over (only used for CLM_QIAN mode) .
For I compset only. Starting year to loop data over for
CLM_QIAN mode. Default value is 2004.

ending year to loop data over (only used for CLM_QIAN mode) .
For I compset only. Ending year to loop data over for CLM_QIAN
mode. Default value is 2004.

case name for coupler history data mode (only used for CPLHIST3HrWx mode)

year align (only used for CPLHIST3HrWx mode) .
For I compset only. Year align (simulation year corresponding to
starting year) for CLM_QIAN mode. Default value is 1.

starting year to loop data over (only used for CPLHIST3HrWx mode)

ending year to loop data over (only used for CPLHIST3HrWx mode)

DICE mode .
DICE is a combination of a data model and a prognostic model.
The data functionality reads in ice coverage. The prognostic functionality
calculates the ice/atmosphere and ice/ocean fluxes. DICE receives the same
atmospheric input from the coupler as the active CICE model (i.e., atmospheric
states, shortwave fluxes, and ocean ice melt flux). DICE acts very similarly
to CICE running in prescribed mode.) Currently, this component is only
used to drive POP2 in C compsets.
If DICE_MODE is set to ssmi or ssmi_iaf, it is a prognostic mode.
It requires data be sent to the ice model.
Ice fraction (extent) data is read from an input stream,
atmosphere state variables are received from the coupler, and then
an atmosphere-ice surface flux is computed and sent to the
coupler. Normally the ice fraction data is found in the same data files
that provide SST data to the data ocean model. They are normally found
in the same file because the SST and ice fraction data are derived from the
same observational data sets and are consistent with each other.
Valid Values: prescribed,ssmi,ssmi_iaf,null 

DOCN mode .
The data ocean component (DOCN) always returns SSTs to the
driver. The atmosphere/ocean fluxes are computed in the
coupler. Therefore, the data ocean model does not compute fluxes like
the data ice model. DOCN has two distinct modes of operation. It can
arun as a pure data model, reading in ocean SSTs (normally
climatological) from input datasets, performing time/spatial
interpolations, and passing these to the coupler. Alternatively,
DOCN can compute updated SSTs by running as a slab ocean model where
bottom ocean heat flux convergence and boundary layer depths are read
in and used with the atmosphere/ocean and ice/ocean fluxes obtained
from the driver.
--- A setting of prescribed assumes the only field in the input stream is SST.
It also assumes the SST is in Celsius and must be converted to Kelvin.
All other fields are set to zero except for ocean salinity, which
is set to a constant reference salinity value.
Normally the ice fraction data is found in the same data files that
provide SST data to the data ocean model. They are normally found in
the same file because the SST and ice fraction data are derived from
the same observational data sets and are consistent with each other.
to the data ocean model. They are normally found in the same file
because the SST and ice fraction data are derived from the same
observational data sets and are consistent with each other.
--- A setting of som (slab ocean model) mode is a prognostic mode.  This mode
computes a prognostic sea surface temperature and a freeze/melt
potential (surface Q-flux) used by the sea ice model.  This
calculation requires an external SOM forcing data file that includes
ocean mixed layer depths and bottom-of-the-slab Q-fluxes.
Scientifically appropriate bottom-of-the-slab Q-fluxes are normally
ocean resolution dependent and are derived from the ocean model output
of a fully coupled CCSM run.  Note that while this mode runs out of
the box, the default SOM forcing file is not scientifically
appropriate and is provided for testing and development purposes only.
Users must create scientifically appropriate data for their particular
application.  A tool is available to derive valid SOM forcing.
Default is prescribed.
Valid Values: prescribed,som,null 

Sets SOM forcing data filename for pres runs, only used in D and E compset . Sets SOM forcing data filename for pres runs, only used in D and E compset

valid values: CPLHIST,NULL .
DLND mode. Valid values are CPLHIST and NULL. In CPLHIST mode, land
forcing data (produced by CLM) from a previous model run is output in
coupler history files and read in by the data land model. In NULL
mode, land forcing is set to zero and not utilized. The default is
NULL.
Valid Values: CPLHIST,NULL 

valid values: CPLHIST,NULL
Valid Values: CPLHIST,NULL 

directory for coupler history data mode (only used for CPLHIST mode)

case name for coupler history data mode (only used for CPLHIST mode)

year align (only used for CPLHIST mode)

starting year to loop data over (only used for CPLHIST mode)

ending year to loop data over (only used for CPLHIST mode)

valid values: CPLHIST,DIATREN_ANN_RX1,DIATREN_IAF_RX1,NULL .
DROF mode. Values are CPLHIST, *_RX1, and NULL. In *_RX1 mode,
observational climatological or interannual
1-degree runoff data is used. In CPLHIST mode, runoff
data from a previous model run is read in. In NULL mode, the runoff
data is set to zero. In CPLHIST mode, land forcing data from a previous
model run is output by the coupler and read in by the data land
model. In NULL mode, land forcing is set to zero and not used. The
default is DIATREN_ANN_RX1.
Valid Values: CPLHIST,DIATREN_ANN_RX1,DIATREN_IAF_RX1,NULL 

directory for coupler history data mode (only used for CPLHIST mode)

case name for coupler history data mode (only used for CPLHIST mode)

year align (only used for CPLHIST mode)

starting year to loop data over (only used for CPLHIST mode)

ending year to loop data over (only used for CPLHIST mode)

Sets sst/ice_cov stream name for pres runs, only used in F,A compset

Sets sst/ice_cov data filename for prescribed runs, only used in F,A compset .
Sets sst/ice_cov filename for AMIP runs, only used in F and A compsets
Default is UNSET.

Sets sst/ice_cov grid filename for pres runs, only used in F,A compset

Sets model year align of sst/ice_cov for pres runs, only used in F,A compset .
Sets model year align of sst/ice_cov for pres runs, only used in F,A compset
Type is integer,
Default is -999

Sets year start of sst/ice_cov for pres runs, only used in F,A compset .
Sets start year of sst/ice_cov for AMIP runs, only used in F and A compsets.
Type is integer,
Default is -999.

Sets year end of sst/ice_cov for pres runs, only used in F,A compset .
Sets end year of sst/ice_cov for AMIP runs, only used in F and A compset.
Type is integer,
Default is -999.