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 onot 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.1, driver namelist are in two groups - those that are set directly from xml variables in env_run.xml and env_build.xml - and those that can be modified via changing the user_nl_cpl file. A full discussion namelist variables that can be changed by setting env_run.xml and env_build.xml variables is provided at the top of the user_nl_cpl file. For those namelist variabes that are not set by directly changing env_run.xml xml variables, or env_build.xml, you should add the appropriate keyword/value pair at the end of the $CASEROOT/user_nl_cpl file. For example, to change eps_frac to 1.0e-05, add the following line to the end of the user_nl_cpl, "eps_frac = 1.0e-02". To see the result of adding this, call preview_namelists and verify that this new value appears in CaseDocs/drv_in.

CAM's configure and build-namelist utilities are now called by Buildconf/cam.buildnml.csh. Note that CAM_CONFIG_OPTS, and CAM_NAMELIST_OPTS and CAM_NML_USE_CASE are normally utilized ONLY to set compset variables (e.g., "-phys cam3_5_1 -chem waccm_mozart" 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 now called by Buildconf/clm.buildnml.csh. Note that CLM_CONFIG_OPTS, and CLM_NML_USE_CASE and other CLM run-time settings are normally utilized ONLY 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 normally utilized ONLY 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 GLC_GRID. The value of GLC_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 (in conjunction with CICE running in prescribed mode) is used in all F component sets. It assumes that the only field in the input stream is SST and 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 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. 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. For 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 configured in three different 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 configured in three different 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 configured in three different way:

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 configured in three different way:

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.