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:

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 cam3_5_1 -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='cam_0.9x1.25.1860.nc'

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

 
&psolar_inparm
 solar_const = 1363.27
/
&cam_inparm
 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 CCSM 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).

This is an advanced flag and should only be used by expert users.

CLM_NAMELIST_OPTS

CLM-specific namelist settings for -namelist option in CLM's build-namelist (see above). We recommend that if you want to change the clm namelist settings such as the initial dataset (finidat) or the history output defaults (hist_nhtfrq) you either include a user_nl_clm or you manually edit the resulting Buildconf/clm.buildnml.csh.

This is an advanced flag and should only be used by expert users.

CLM_FORCE_COLDSTART

Flag to CLM's build-namelist to force CLM to do a cold start. Valid values are on, off. The "on" value forces the model to spin up from a cold-start (arbitrary initial conditions).

This is an advanced flag and should only be used by expert users.

CLM_USRDAT_NAME

Dataset name for user-created datasets. This is used as the argument to build-namelist -clm_usr_name (see above). 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.

CLM_PT1_NAME

Grid name when the CLM/ATM grid is a single point. This is used in I compsets only.

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 constant, it will be set to CCSM_CO2_PPMV, if set otherwise, 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 sets).

This is an advanced flag and should only be used by expert users.

CLM_NML_USE_CASE

Determines the use-case that will be sent to the CLM build-namelist. CLM_CO2_TYPE is normally set by the specific compset.

This is an advanced flag and should only be used by expert users.

CICE variables

The following are CICE-specific env_conf.xml variables

CICE's configure utility is invoked by cice.cpl7.template as:


  configure -case  
     ⇓
  Tools/Templates/cice.cpl7.template 
     ⇓
  $CCSMROOT/models/ice/cice/bld/configure \
     -hgrid $ICE_GRID  \
     -mode $CICE_MODE  \
     $CICE_CONFIG_OPTS \
     ...
     ⇓
   ciceconf/ 
   # Do Not Modify contents of ciceconf/
     ⇓
  Buildconf/cice.buildexe.csh

CICE's build-namelist utility is invoked by cice.cpl7.template as:


  configure -case  
     ⇓
  Tools/Templates/cice.cpl7.template 
     ⇓
  $CCSMROOT/ice/cice/bld/build-namelist 
     -presaero_type $CICE_PRESAERO_TYPE 
     -namelist "&cice_inparm $CICE_NAMELIST_OPTS /" 
     ... 
     ⇓
   ciceconf/ 
   # Do Not Modify contents of ciceconf/
     ⇓
  Buildconf/cice.buildnml.csh

CICE_MODE

Option to CICE's configure utility for the -mode argument (see above). Valid values are prognostic, prescribed, thermo_only. The default is prognostic.

CICE_CONFIG_OPTS

Provides option(s) for CICE's configure utility (see above). Default value is "-ntr_aero 3 -ntr_pond 1 -ntr_iage 1 -ntr_FY 1".

CICE_PRESAERO_TYPE

Option to CICE's build-namelist utility for the -prescaero flag (see above). This determines the CICE prescribed aerosol type and is only used if not obtained from atmosphere.

CICE_NAMELIST_OPTS

CICE-specific namelist settings for -namelist option (see above).

In addition, $CASEROOT/configure also generates the CICE's block decomposition in env_build.xml as follows (also see env_build.xml variables ):


  configure -case  
     ⇓
  $NTASKS_ICE and $NTHRDS_ICE
     ⇓
  Tools/Templates/generate_cice_decomp.xml
     ⇓  
  Tools/Templates/cice_decomp.xml
     ⇓
  sets env_build.xml CICE_BLCKX
  sets env_build.xml CICE_BLCKY
  sets env_build.xml CICE_MXBLCKS
  sets env_build.xml CICE_DECOMPTYPE
     ⇓
  CPP variables in cice.buildexe.csh

POP2 variables

The following are POP2-specific env_conf.xml variables

POP2's namelist construction utility is invoked by pop2.cpl7.template in the following sequence:


  configure -case  
     ⇓
  Tools/Templates/pop2.cpl7.template 
     ⇓
  $CCSMROOT/models/ocn/pop2/input_templates/pop2_in_build.csh 
  $CCSMROOT/models/ocn/pop2/input_templates/ocn.*.setup.csh
     ⇓
  Buildconf/pop2.buildnml.csh

POP2's script to generate the ocn binary library is created directly from pop2.cpl7.template:


  configure -case  
     ⇓
  Tools/Templates/pop2.cpl7.template 
     ⇓
  Buildconf/pop2.buildexe.csh

In addition, configure also generates POP2's block decomposition in env_build.xml as follows (also see env_build.xml variables ):


  configure -case  
     ⇓
  $NTASKS_OCN and $NTHRDS_OCN
     ⇓
  Tools/Templates/generate_pop_decomp.xml
     ⇓
  Tools/Templates/pop_decomp.xml
     ⇓
  sets env_build.xml POP_BLCKX
  sets env_build.xml POP_BLCKY
  sets env_build.xml POP_MXBLCKS
  sets env_build.xml POP_DECOMPTYPE
     ⇓
  CPP variables in pop2.buildexe.csh

The following variables are used by the POP2 scripts to generate the settings used in your $CASE.

OCN_CHL_TYPE

Determine provenance of surface Chl for radiative penetration computations. Valid values are diagnostic, prognostic. The default is diagnostic. This option is used in the POP2 ecosystem model, which will be available in the CESM1.0 release.

OCN_CO2_TYPE

Determine provenance of atmospheric CO2 for gas flux computation. Valid values are constant, prognostic. The default is constant. This option is used in the POP2 ecosystem model, which will be available in the CESM1.0 release.

OCN_COUPLING

Determine surface freshwater and heat forcing settings. Valid values are full, partial. 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 change this setting.

OCN_ICE_FORCING

Determine under-ice forcing settings. Valid values are active, inactive. 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 change this setting.

OCN_TRANSIENT

Determine settings for transient forcing datasets (e.g., atmospheric pCFC concentrations). Valid values are unset, 1850-2000. The create_newcase command selects the appropriate setting for this variable based on the specified compset. Users should not change this setting. This option is used in the POP2 ecosystem model, which will be available in the CESM1.0 release.

DATM variables

The following are DATM-specific env_conf.xml variables

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 uses the datm.cpl7.template as follows:


  configure   
     ⇓
  Tools/Templates/datm.cpl7.template 
     ⇓
  Buildconf/datm.builexe.csh

and


  configure   
     ⇓
  Tools/Templates/datm.cpl7.template 
     ⇓
  $CCSMROOT/scripts/ccsm_utils/build_streams 
     ⇓
  Buildconf/datm.buildml.csh

The following are CCSM environment variables that are used by datm.cpl7.template:

DATM_MODE

Mode for data atmosphere component (datm). Valid values are CORE2_NYF, CLM_QIAN, CLM1PT. The default is CORE2_NYF.

CORE2_NYF (CORE2 normal year forcing) is the DATM mode used in C and G compsets.

CLM_QIAN and CLM1PT are DATM modes using observational data for forcing CLM in I compsets.

DATM_CLMNCEP_YR_ALIGN

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

DATM_CLMNCEP_YR_START

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

DATM_CLMNCEP_YR_END

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

DLND variables

The following are DLND-specific env_conf.xml variables

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-runoff model (reading in runoff data), or as a purely data-land model (reading in coupler history data for atm/land fluxes and land albedos produced by a previous run), or both. In general, the data land model is only used to provide runoff forcing data to POP2 when running C or G compsets.

DLND uses the datm.cpl7.template as follows:


  configure   
     ⇓
  Tools/Templates/dlnd.cpl7.template 
     ⇓
  Buildconf/dlnd.builexe.csh

and


  configure   
     ⇓
  Tools/Templates/dlnd.cpl7.template 
     ⇓
  $CCSMROOT/scripts/ccsm_utils/build_streams 
     ⇓
  Buildconf/dlnd.buildml.csh

The following are variables that are used by dlnd.cpl7.template.

DLND_MODE

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.

DLND_RUNOFF_MODE

DLND_RUNOFF mode. Valid values are CPLHIST, RX1, and NULL. In RX1 mode, observational 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 RX1.

DICE variables

The following are DICE-specific env_conf.xml variables

DICE is discussed in detail in Data Model's User's Guide. 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.

DICE uses the dice.cpl7.template as follows:


  configure   
     ⇓
  Tools/Templates/dice.cpl7.template 
     ⇓
  Buildconf/dice.builexe.csh

and


  configure   
     ⇓
  Tools/Templates/dice.cpl7.template 
     ⇓
  $CCSMROOT/scripts/ccsm_utils/build_streams 
     ⇓
  Buildconf/dice.buildml.csh

The following are variables that are used by dice.cpl7.template.

DICE_MODE

DICE mode. Valid value is ssmi.

DOCN variables

The following are DOCN-specific env_conf.xml variables

The following are variables that are used by docn.cpl7.template.

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

The data ocean component (DOCN) always returns SSTs to the driver. In CCSM, 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 run 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.

DOCN running in prescribed mode (in conjunction with CICE running in prescribed mode) is used in all F component sets.

DOCN running as a slab ocean model is used (in conjunction with CICE running in prognostic mode) in all E compsets.

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 uses the docn.cpl7.template as follows:


  configure   
     ⇓
  Tools/Templates/docn.cpl7.template 
     ⇓
  Buildconf/docn.builexe.csh

and


  configure   
     ⇓
  Tools/Templates/docn.cpl7.template 
     ⇓
  $CCSMROOT/scripts/ccsm_utils/build_streams 
     ⇓
  Buildconf/docn.buildml.csh

DOCN_MODE

DOCN mode. Valid values are prescribed, som. Default is prescribed.

DOCN_SSTDATA_FILENAME

Sets sst/ice_cov filename for AMIP runs, only used in F compset. Default is UNSET.

DOCN_SSTDATA_YEAR_START

Sets start year of sst/ice_cov for AMIP runs, only used in F compset. Default is -999.

DOCN_SSTDATA_YEAR_END

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

Driver/coupler variables

The following are CPL-specific env_conf.xml variables

CPL_EPBAL

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.

Valid values are off, ocn. Default is off.

CPL_ALBAV

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. Valid values are true, false. Default is false.

CCSM_BGC

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 are: none, CO2A.

MAP_A2OF_FILE

atm-to-ocn mapping file for fluxes (currently first-order conservative).

MAP_A2OS_FILE

atm-to-ocn mapping file for states (currently bilinear).

MAP_O2AF_FILE

ocn-to-atm mapping file for fluxes (currently first-order conservative).

MAP_O2AS_FILE

ocn-to-atm mapping file for states (currently bilinear).

MAP_A2LF_FILE

atm-to-land mapping file for fluxes (currently first-order conservative).

MAP_A2LS_FILE

atm-to-land mapping file for states (currently bilinear).

MAP_R2O_FILE_R05

0.5-degree runoff-to-ocn mapping file.

MAP_R2O_FILE_RX1

1-degree runoff-to-ocn mapping file.

MAP_R2O_FILE_R19

19-basin runoff-to-ocn mapping file.

Other variables

The following variables impact more than one component.

CCSM_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.