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 file).

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. See setting up a branch run for an example.

A hybrid run indicates that CESM 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.

In CESM1.2, driver namelist are in two groups - those that are set directly from xml variables in env_case.xml, env_mach_pes.xml and env_run.xml, and those that are set by the driver build-namelist utility ($CCSMROOT/models/drv/bld/build-namelist) for the target compset and resolution. Except for the following driver namelist variables (see below), driver namelist variables that are in env_run.xml can be changed either by changing the xml variable OR by adding the correct key-word value pair at the end of user_nl_cpl, where any changes in user_nl_cpl will take precedence over values set in the xml file. For example, to change eps_frac to 1.0e-15, add the following line to the end of the user_nl_cpl, "eps_frac = 1.0e-15". To see the result of this modification to user_nl_cpl call preview_namelists and verify that this new value appears in CaseDocs/drv_in.

The following namelist variables MAY NOT be changed in user_nl_cpl -
but must be changed in the appropriate $CASEROOT xml file.  
XXX  refers to ATM,LND,ICE,OCN,ROF,GLC,WAV
======================================
drv namelist   => xml variable 
variable       
======================================
case_name      => CASE                
username       => CCSMUSER         
hostname       => MACH                
model_version  => CCSM_REPOTAG  
start_type     => RUN_TYPE          
start_ymd      => RUN_STARTDATE  
start_tod      => START_TOD
XXX_cpl_dt     => XXX_NCPL          
XXX_ntasks     => NTASKS_XXX
XXX_nthreads   => NTHRDS_XXX
XXX_rootpe     => ROOTPE_XXX
XXX_pestride   => PSTRID_XXX
XXX_layout     => NINST_XXX_LAYOUT

CAM's configure and build-namelist utilities are called by Buildconf/cam.buildnml.csh. CAM_CONFIG_OPTS, CAM_NAMELIST_OPTS and CAM_NML_USECASE are used to set compset variables (e.g., "-phys cam5" for CAM_CONFIG_OPTS) and in general should not be modified for supported compsets. For a complete documentation of namelist settings, see CAM namelist variables. To modify CAM namelist settings, you should add the appropriate keyword/value pair at the end of the $CASEROOT/user_nl_cam file (see the documentation for each file at the top of that file). For example, to change the solar constant to 1363.27, modify the user_nl_cam file to contain the following line at the end "solar_const=1363.27". To see the result of adding this, call preview_namelists and verify that this new value appears in CaseDocs/atm_in.

CLM's configure and build-namelist utilities are called by Buildconf/clm.buildnml.csh. CLM_CONFIG_OPTS and CLM_NML_USE_CASE are used to set compset specific variables and in general should not be modified for supported compsets. For a complete documentation of namelist settings, see CLM namelist variables. To modify CLM namelist settings, you should add the appropriate keyword/value pair at the end of the $CASEROOT/user_nl_clm file (see the documentation for each file at the top of that file). To see the result of your change, call preview_namelists and verify that the changes appear correctly in CaseDocs/lnd_in.

RTM's build-namelist utility is called by Buildconf/rtm.buildnml.csh. For a complete documentation of namelist settings, see RTM namelist variables. To modify RTM namelist settings, you should add the appropriate keyword/value pair at the end of the $CASEROOT/user_nl_rtm file (see the documentation for each file at the top of that file). To see the result of your change, call preview_namelists and verify that the changes appear correctly in CaseDocs/rof_in.

CICE's configure and build-namelist utilities are now called by Buildconf/cice.buildnml.csh. Note that CICE_CONFIG_OPTS, and CICE_NAMELIST_OPTS are used to set compset specific variables and in general should not be modified for supported compsets. For a complete documentation of namelist settings, see CICE namelist variables. To modify CICE namelist settings, you should add the appropriate keyword/value pair at the end of the $CASEROOT/user_nl_cice file (see the documentation for each file at the top of that file). To see the result of your change, call preview_namelists and verify that the changes appear correctly in CaseDocs/ice_in.

In addition, cesm_setup creates CICE's compile time block decomposition variables in env_build.xml as follows:

  ./cesm_setup
     ⇓
  Buildconf/cice.buildnml.csh and $NTASKS_ICE and $NTHRDS_ICE
     ⇓
  env_build.xml variables CICE_BLCKX, CICE_BLCKY, CICE_MXBLCKS, CICE_DECOMPTYPE 
  CPP variables in cice.buildexe.csh

See POP2 namelist variables for a complete description of the POP2 run-time namelist variables. Note that OCN_COUPLING, OCN_ICE_FORCING, OCN_TRANSIENT are normally utilized ONLY to set compset specific variables and should not be edited. For a complete documentation of namelist settings, see CICE namelist variables. To modify POP2 namelist settings, you should add the appropriate keyword/value pair at the end of the $CASEROOT/user_nl_pop2 file (see the documentation for each file at the top of that file). To see the result of your change, call preview_namelists and verify that the changes appear correctly in CaseDocs/ocn_in.

In addition, cesm_setup also generates POP2's compile time compile time block decomposition variables in env_build.xml as follows:

  ./cesm_setup  
     ⇓
  Buildconf/pop2.buildnml.csh and $NTASKS_OCN and $NTHRDS_OCN
     ⇓
  env_build.xml variables POP2_BLCKX, POP2_BLCKY, POP2_MXBLCKS, POP2_DECOMPTYPE 
  CPP variables in pop2.buildexe.csh

See CISM namelist variables for a complete description of the CISM run-time namelist variables. This includes variables that appear both in cism_in and in cism.config. To modify any of these settings, you should add the appropriate keyword/value pair at the end of the user_nl_cism file (see the documentation for each file at the top of that file). To see the result of your change, call preview_namelists and verify that the changes appear correctly in CaseDocs/cism_in and CaseDocs/cism.config.

There are also some run-time settings set via env_run.xml, as documented in CISM run time variables - in particular, the model resolution, set via CISM_GRID. The value of CISM_GRID determines the default value of a number of other namelist parameters.

DATM is discussed in detail in Data Model's User's Guide. DATM is normally used to provide observational forcing data (or forcing data produced by a previous run using active components) to drive CLM (I compset), POP2 (C compset), and POP2/CICE (G compset). As a result, DATM variable settings are specific to the compset that will be targeted.

DATM can be user configured in three different ways.

You can set DATM run-time variables my modifying control settings for CLM and CPLHIST forcing.

You can edit user_nl_datm to change namelist settings namelists settings by adding all user specific namelist changes in the form of "namelist_var = new_namelist_value". Note that any namelist variable from shr_strdata_nml and datm_nml can be modified below using the this syntax. Use preview_namelists to view (not modify) the output namelist in CaseDocs.

You can modify the contents of a DATM stream txt file. To do this:

• use preview_namelists to obtain the contents of the stream txt files in CaseDocs

• place a copy of this file in $CASEROOT with the string "user_" prepended

• Make sure you change the permissions of the file to be writeable (chmod 644)

• Modify the user_datm.streams.txt.* file.

DOCN is discussed in detail in Data Model's User's Guide.

DOCN running in prescribed mode assumes that the only field in the input stream is SST and also that 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 (used for prescribed CICE) is found in the same data files that provide SST data to the data ocean model since SST and ice fraction data are derived from the same observational data sets and are consistent with each other. For DOCN prescribed mode, default yearly climatological datasets are provided for various model resolutions. For multi-year runs requiring AMIP datasets of sst/ice_cov fields, you need to set the variables for DOCN_SSTDATA_FILENAME, DOCN_SSTDATA_YEAR_START, and DOCN_SSTDATA_YEAR_END. CICE in prescribed mode also uses these values.

DOCN running as a slab ocean model is used (in conjunction with CICE running in prognostic mode) in all E compsets. 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 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.

DOCN can be user-customized in three ways.

You can set DOCN run-time variables.

You can edit user_nl_docn to change namelist settings by adding all user specific namelist changes in the form of "namelist_var = new_namelist_value". Note that any namelist variable from shr_strdata_nml and datm_nml can be modified below using the this syntax. Use preview_namelists to view (not modify) the output namelist in CaseDocs.

You can modify the contents of a DOCN stream txt file. To do this:

• use preview_namelists to obtain the contents of the stream txt files in CaseDocs/

• place a copy of this file in $CASEROOT with the string "user_" prepended

• Make sure you change the permissions of the file to be writeable (chmod 644)

• Modify the user_docn.streams.txt.* file.

DICE is discussed in detail in Data Model's User's Guide.

DICE can be user-customized in three ways.

You can set DICE run-time variables.

You can edit user_nl_dice to change namelist settings by adding all user specific namelist changes in the form of "namelist_var = new_namelist_value". Note that any namelist variable from shr_strdata_nml and datm_nml can be modified below using the this syntax. Use preview_namelists to view (not modify) the output namelist in CaseDocs/.

You can modify the contents of a DICE stream txt file. To do this:

• use preview_namelists to obtain the contents of the stream txt files in CaseDocs/

• place a copy of this file in $CASEROOT with the string "user_" prepended

• Make sure you change the permissions of the file to be writeable (chmod 644)

• Modify the user_dice.streams.txt.* file.

DLND is discussed in detail in Data Model's User's Guide. The data land model is different from the other data models because it can run as a purely data-land model (reading in coupler history data for atm/land fluxes and land albedos produced by a previous run), or to read in model output from CLM to send to CISM.

DLND can be user-customized in three ways:

You can set DLND run-time variables.

You can edit user_nl_dlnd OR user_nl_dsno depending on the component set, to change namelist settings namelists settings by adding all user specific namelist changes in the form of "namelist_var = new_namelist_value". Note that any namelist variable from shr_strdata_nml and dlnd_nml or dsno_nml can be modified below using the this syntax. Use preview_namelists to view (not modify) the output namelist in CaseDocs/.

You can modify the contents of a DLND stream txt file. To do this:

• use preview_namelists to obtain the contents of the stream txt files in CaseDocs/

• place a copy of this file in $CASEROOT with the string "user_" prepended

• Make sure you change the permissions of the file to be writeable (chmod 644)

• Modify the user_dlnd.streams.txt.* file.

DROF is discussed in Data Model's User's Guide. The data river runoff model reads in runoff data and sends it back to the coupler. In general, the data river runoff model is only used to provide runoff forcing data to POP2 when running C or G compsets

DROF can be user-customized in three ways:

You can set DROF run-time variables.

You can edit user_nl_drof to change namelist settings namelists settings by adding all user specific namelist changes in the form of "namelist_var = new_namelist_value". Note that any namelist variable from shr_strdata_nml and drof_nml can be modified using the this syntax. Use preview_namelists to view (not modify) the output namelist in CaseDocs/.

You can modify the contents of a DROF stream txt file. To do this:

• use preview_namelists to obtain the contents of the stream txt files in CaseDocs/

• place a copy of this file in $CASEROOT with the string "user_" prepended

• Make sure you change the permissions of the file to be writeable (chmod 644)

• Modify the user_drof.streams.txt.* file.