CESM1.0.z User's Guide
Prev	Chapter 3. Configuring a Case	Next

Setting component-specific variables

To understand how the component-specific variables in env_conf.xml (e.g., CAM_CONFIG_OPTS) are used to set compile and namelist settings for that component, you first need to understand how configure uses the variables in env_conf.xml to create the files in Buildconf/.

In each $CASEROOT directory, the subdirectory $CASEROOT/Tools/Templates contains files of the form $component[.cpl7].template, where $component corresponds to each of the model components that is part of the selected component set. The .cpl7 appears in some templates and not in others. configure translates the $env_*.xml xml variables to csh environment variables, and each of the component template scripts uses those environment variables to create Buildconf/$component.buildexe.csh (which creates the component library) and Buildconf/$component.buildnml.csh (which creates the component namelist).

  configure   
     ⇓
  Tools/Templates/$component.cpl7.template 
     ⇓
  Buildconf/$component.buildexe.csh
  Buildconf/$component.buildnml.csh

When the model run is submitted, $CASE.$MACH.run will call Buildconf/$component.buildnml.csh to produce the run-time component namelists:

  $CASE.$MACH.run
     ⇓
  Buildconf/$component.buildnml.csh
     ⇓
  $RUNDIR/$model_in

As an example, for CAM

  $CASE.$MACH.run
     ⇓
  Buildconf/cam.buildnml.csh
     ⇓
  $RUNDIR/atm_in

Important:: Component namelists should normally be set using env_conf.xml variables (see below). If a namelist needs to be modified after configure is called, then this should be done in Buildconf/$component.buildnml.csh. Note that if configure -cleanall or configure -cleannamelist is called, then any local changes to Buildconf/$component.buildnml.csh will be lost.

The discussions in the sections below assume the following:

References to $component.cpl7.template refer to Tools/Templates/$component.cpl7.template
References to $component.buildexe.csh and $component.buildnml.csh refer to Buildconf/$component.buildexe.csh and Buildconf.$component.buildnml.csh.

CAM variables

The following are CAM-specific env_conf.xml variables

CAM's configure utility is invoked by cam.cpl7.template as:

  configure   
     ⇓
  Tools/Templates/cam.cpl7.template 
     ⇓
  $CCSMROOT/models/atm/cam/bld/configure \
     -ccsm_seq -ice none -ocn none -spmd \
     -dyn $CAM_DYCORE -res $ATM_GRID \
     $CAM_CONFIG_OPTS \
    ...
     ⇓
   camconf/ 
   # Do Not Modify contents of camconf/
     ⇓
   Buildconf/cam.buildexe.csh

Note that $CAM_DYCORE and $ATM_GRID are env_conf.xml and env_case.xml variables, respectively.

CAM's build-namelist utility is invoked by cam.cpl7.template as:

  configure   
     ⇓
  Tools/Templates/cam.cpl7.template 
     ⇓
  $CCSMROOT/models/atm/cam/bld/build-namelist \
     -use_case $CAM_NML_USE_CASE \
     -namelist "$CAM_NAMELIST_OPTS /"
     ...
     ⇓
   camconf/ 
   # Do Not Modify contents of camconf/
     ⇓
   Buildconf/cam.buildnml.csh

The following env_conf.xml variables are used by CAM to invoke its configure and build-namelist utilities.

CAM_CONFIG_OPTS

Provides option(s) for CAM's configure utility (see above). CAM_CONFIG_OPTS are normally set as compset variables (e.g., "-phys cam4 -chem waccm_mozart") and in general should not be modified for supported compsets. Recommendation: If you want to modify this value for your experiment, use your own (user-defined component sets).

CAM_NML_USE_CASE

Provides the use_case option for CAM's build-namelist utility (see above). CAM's build-namelist leverages groups of namelist options (use cases) that are often paired with CAM's 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 compsets. Recommendation: If you want to modify this value for your experiment, use your own (user-defined component sets.

CAM_NAMELIST_OPTS

Provides options to the -namelist argument in CAM's build-namelist utility (see above).

This serves to specify namelist settings directly on the command line by supplying a string containing Fortran namelist syntax. The resulting namelist will appear in cam.buildnml.csh.

Note: To insert a single quotation mark (apostrophe) when setting CAM_NAMELIST_OPTS, use the string "'". Also note that the "$" symbol should not be used in CAM_NAMELIST_OPTS.

This example shows how to use xmlchange to set CAM_NAMELIST_OPTS:

xmlchange -id CAM_NAMELIST_OPTS\
          -val ncdata=&apos;cam_0.9x1.25.1860.nc&apos;

If you want to modify numerous cam namelist values, you can use an alternate scheme: Place a file user_nl_cam containing modified cam namelist settings in $CASEROOT. For example, user_nl_cam could contain the following:

 
&camexp
 solar_const = 1363.27
 ch4vmr = 1860.0e-9
 nhtfrq = -24
/

and the above settings would appear in cam.buildnml.csh.

CLM variables

The following are CLM-specific env_conf.xml variables

CLM's configure utility is invoked by clm.cpl7.template as:

  configure -case  
     ⇓
  Tools/Templates/clm.cpl7.template 
     ⇓
  $CCSMROOT/models/lnd/clm/bld/configure \
     -mode ext_ccsm_seq \
      -comp_intf cpl_$COMP \
      -usr_src $CASEROOT/SourceMods/src.clm \
      $CLM_CONFIG_OPTS 
      ...
      ⇓
    clmconf/ 
    # Do Not Modify contents of clmconf/
      ⇓
    Buildconf/clm.buildexe.csh

CLM's build-namelist utility is also invoked by clm.cpl7.template as:

  configure -case  
     ⇓
  Tools/Templates/clm.cpl7.template 
     ⇓
  $CCSMROOT/lnd/clm/bld/build-namelist 
    -clm_usr_name $CLM_USRDAT_NAME \
    -res $LND_GRID -mask $OCN_GRID \
    -clm_start_type $START_TYPE 
    -use_case $CLM_NML_USE_CASE 
    -namelist "&clm_inparm $CLM_NAMELIST_OPTS /" 
     ...
     ⇓
   clmconf/ 
   # Do Not Modify contents of clmconf/
     ⇓
   Buildconf/clm.buildnml.csh

Note: Confusion can arise here. CLM supports the values of default, cold, arb_ic, and startup for the -clm_start_type argument. A value of cold implies always starting with arbitrary initial conditions. A value of arb_ic implies starting with arbitrary initial conditions if initial conditions do not exist. A value of startup implies that initial conditions must be used, and the configure -case will abort if one isn't provided (either from the CLM XML namelist database, or entered with CLM_NAMELIST_OPTS or user_nl_clm). If "default" is entered, the CLM build-namelist will determine the setting based on the resolution.
$START_TYPE (above) is a derived variable in clm.cpl7.template. For a hybrid run, $START_TYPE is set to "startup", otherwise it is set to "default" unless $$CLM_FORCE_COLDSTART is set to "on", in which case is it set to "cold". It is unfortunate that the name "startup" is the same as the name used for initializing a CESM run, because in this case it means something very different.

CLM_CONFIG_OPTS

Provides option(s) for CLM's configure utility (see above). CLM_CONFIG_OPTS are normally set as compset variables (e.g., -bgc cn).

Do not modify this variable. If you want to modify this for your experiment, use your own (user-defined component sets).