Chapter 2. Creating and Setting Up A Case

Table of Contents
How to create a new case
How to set up a case and customize the PE layout
Multi-instance component functionality
Modifying an xml file
Cloning a case (Experts only)

The first step in creating a CESM experiment is to use create_newcase.

How to create a new case

CESM supports out of the box component sets, model grids and hardware platforms. Component sets (usually referred to as compsets) define both the specific model components that will be used in a given CESM configuration, and any component-specific namelist or configuration settings that are specific to this configuration. In the CESM1.2 release series (starting with CESM1.2.0) component sets and resolutions have been significantly changed to permit addressing the growing model complexity. Both compsets and models grids are now associated with three names: a new longname, a new short name (that is backwards compatible with the older CESM1.1 release series long name) and a new alias name (that is backwards compatible with the older CESM1.1 release series short name).

New Component Set Naming Convention

The new component set (compset) longname has the form


TIME = model time period (e.g. 2000, 20TR, RCP8...)   
LND  = [CLM40, CLM45, DLND, SLND, XLND]	   
GLC  = [CISM1, SGLC, XGLC]			   
WAV  = [SWAV, XWAV]				   
BGC  = optional BGC scenario                    

The OPTIONAL %phys attributes specify sub-modes of the given system
For example DOCN%DOM is the  DOCN data ocean (rather than slab-ocean) mode.
ALL the possible %phys choices for each component are listed 
by the calling create_newcase with the -list compsets argument.
ALL data models now have a %phys option that corresponds to the data
model mode 

As an example, the new longname, 20TR_CAM4_CLM40%CN_CICE_POP2_RTM_SGLC_SWAV, refers to running the prognostic components CAM, CLM, RTM, CICE, POP2 with stubs SGLC and SWAV components. The particular configuration will be a transient 1850 to 2000 run using cam5 physics, clm4.0 physics with clm4.0 cn, prognostic cice (default) and pop2 (default). The shortname and alias for this compset are now B_1850-2000_CAM5_CN and B20TRC5CN, which correspond to the CESM1.1 series longname and shortname, respectively. Any one of the three compset names (longname, shortname or alias) can be used as input to create_newcase. It is now also much easier to create your own custom compset (see How do I create my own compset?). All the out-of-the-box CESM1.2 release series compsets are listed in component sets. Upon clicking on any of the long names a pop up box will appear that provides more details of the component configuration.

New Overall Model Grid Naming Convention

The new model grid longname has the form


a%  = atmosphere grid 
l%  = land grid 
oi% = ocean/sea-ice grid (must be the same) 
r%  = river grid 
m%  = land mask grid 
g%  = internal land-ice (CISM) grid
w%  = wave component grid (not relevant in CESM1.2 series) 

From the point of view of model coupling - the glc (CISM) grid is assumed to
be identical to the land grid. However, the internal CISM grid can be different, 
and is specified by the g% value.

As an example, the new longname, a%ne30np4_l%ne30np4_oi%gx1v6_r%r05_m%gx1v6_g%null_w%null, refers to running an ne30np4 spectral element 1-degree atmosphere and land grids a gx1v6 Greenland pole 1-degree ocean and sea-ice grids a 1/2 degree river routing grid, null wave and internal cism grids and an ocean/land mask that is determined by the gx1v6 ocean mask. The shortname and alias for this grid are now ne30np4_gx1v6 and ne30_g16, which correspond to the CESM1.1 series longname nad shortname respectively. Any one of the three grid names (longname, shortname or alias) can be used as input to create_newcase. It is now simpler for you to introduce new user defined grids (see Adding a new user-defined grid). All the out-of-the-box CESM1.2 release series model grids are listed in grids . Upon clicking on any of the long names a pop up box will appear that provides more details of the model grid.

Component grids (such as the atmosphere grid or ocean grid above) are denoted by the following naming convention:

  • "[dlat]x[dlon]" are regular lon/lat finite volume grids where dlat and dlon are the approximate grid spacing. The shorthand convention is "fnn" where nn is generally a pair of numbers indicating the resolution. An example is 1.9x2.5 or f19 for the approximately "2-degree" finite volume grid. Note that CAM uses an [nlat]x[nlon] naming convection internally for this grid.

  • "Tnn" are spectral lon/lat grids where nn is the spectral truncation value for the resolution. The shorthand name is identical. An example is T85.

  • "ne[X]np[Y]" are cubed sphere resolutions where X and Y are integers. The short name is generally ne[X]. An example is ne30np4 or ne30.

  • "pt1" is a single grid point.

  • "gx[D]v[n]" is a displaced pole grid where D is the approximate resolution in degrees and n is the grid version. The short name is generally g[D][n]. An example is gx1v6 or g16 for a grid of approximately 1-degree resolution.

  • "tx[D]v[n]" is a tripole grid where D is the approximate resolution in degrees and n is the grid version.

Using create_newcase

You should first use the -h option in calling create_newcase to document its input options. In addition, the create_newcase -list [compsets,grids,machine] option can also be used to see which component sets, model grids, and machines are supported. The links above, however, provide a much more complete determination. create_newcase can be called with the following arguments:

create_newcase \     
     -case case-name \        
     -compset component-set \      
     -res resolution \         
     -mach machine-name \
     [-compiler compiler-name> \
     [-mpilib mpi-library-name] \
     [-mach_dir alternative pathname for Machines directory] \
     [-confopts [_AOA],[AOE],[_D],[_E],[_N],[_P],[_R]] \
     [-pecount [S,M,L,X1,X2]] \
     [-pes_file full-pathname] \
     [-user_compset new user compset long name] \
     [-user_grid_file full-pathname of user xml grid file] \
     [-help [or -h]] |
     [-list [compsets,grids,machines]  \         
     [-silent [or -s]] \
     [-verbose [or -v]] \
     [-xmlmode [normal, expert]] \

Required arguments to create_newcase are -case, -mach, -compset and -res. If you want to use your own pes setup file, specify the full pathname of that file for the optional -pes_file argument. The required pes_file format is provided at $CCSMROOT/scripts/sample_pes_file.xml.

Following is a simple example of using create_newcase: In what follows, $CCSMROOT is the full pathname of the root directory of the CESM distribution.

> cd $CCSMROOT/scripts 
> create_newcase -case ~/cesm/example1 \ 
  -compset B_1850_CAM5_CN \ 
  -res ne30np4_gx1v6 \
  -mach yellowstone

This example creates a $CASEROOT directory ~/cesm1/example1 where $CASE is "example1" with a model resolution of 0.9x1.25_gx1v6 (a 1-degree atmosphere/land grid with a nominal 1-degree ocean/ice grid using the gx1v6 ocean mask). The component set B_1850_CN uses fully active components configured to produce a present-day simulation. The complete example appears in the basic example. $CASE can include letters, numbers, ".", and "_". Note that create_newcase creates the $CASEROOT directory. If the directory already exists, it prints a warning and aborts.

As a more general description, create_newcase creates the directory $CASEROOT, which is specified by the -case option. In $CASEROOT, create_newcase installs files to build and run the model and perform long term archiving of the case on the target platform. create_newcase also creates the directory $CASEROOT/Buildconf/, that in turn contains scripts to generate component namelist and build component libraries. The table below outlines the files and directories created by create_newcase

Table 2-1. Result of invoking create_newcase

Directory or FilenameDescription
README.caseFile detailing your create_newcase usage. This is a good place for you to keep track of runtime problems and changes.
CaseStatusFile containing a list of operations done in the current case.
Buildconf/Directory containing scripts to generate component namelists and component and utility libraries (e.g., PIO, MCT). You should never have to edit the contents of this directory (unlike in CESM1.0.5)
SourceMods/Directory where you can place modified source code.
LockedFiles/Directory that holds copies of files that should not be changed. The xml files are "locked" after its variables have been used by other parts of the system and cannot be changed. The scripts do this by "locking" a file and not permitting you to modify that file unless a 'clean' operation is performend. See the Section called BASICS: Why is there file locking and how does it work? in Chapter 6. You should never edit the contents of this directory.
Tools/Directory containing support utility scripts. You should never need to edit the contents of this directory.
env_mach_specificFile used to set a number of machine-specific environment variables for building and/or running. Although you can edit this at any time, build environment variables should not be edited after a build is invoked.
env_case.xml Sets case specific variables (e.g. model components, model and case root directories) and cannot be modified after a case has been created. To make changes, your should re-run create_newcase with different options.
env_build.xml Sets model build settings, including component resolutions and component configuration options (e.g. CAM_CONFIG_OTPS) where applicable (see env_build.xml variables).
env_mach_pes.xml Sets component machine-specific processor layout (see the Section called Changing the PE layout). The settings in this are critical to a well-load-balanced simulation (see loadbalancing a run).
env_run.xmlSets run-time settings such as length of run, frequency of restarts, output of coupler diagnostics, and short-term and long-term archiving. See run initialization variables, run stop variables, run restart control variables, for a more complete discussion of general run control settings.
cesm_setup Script used to set up the case (create the $ script and user_nl_xxx files)
$CASE.$ Script to build component and utility libraries and model executable.
$CASE.$MACH.clean_build Script to remove all object files and libraries and unlocks Macros and env_build.xml. This step is required before a clean build of the system.
$CASE.$MACH.l_archiveScript to performs long-term archiving of output data (see long-term archiving). This script will only be created if long-term archiving is available on the target machine.
xmlchangeUtility for modifying values in the xml files.
preview_namelistsUtility to enable users to see their component namelists in $CASEROOT/CaseDocs before running the model. NOTE: the namelists generated in $CASEROOT/CaseDocs should not be edited by the user - they are only their to document model behavior.
check_input_dataUtility that checks for various input datasets and moves them into place.
create_production_testUtility used to create a test of your case.

For more complete information about the files in the case directory, see the Section called BASICS: What are the directories and files in my case directory? in Chapter 6

The xml variables in the env_*.xml files are translated into csh environment variables with the same name by the script $CASEROOT/Tools/ccsm_getenv. Conversion of xml variables to environment variables is used by numerous script utilities as part of building, and running a given case. It is important to note that you do not explicitly see this conversion.

Note: Users can only modify the xml variables. Users cannot modify the csh environment variables directly.

Complete lists of CESM environment variables in the xml files that appear in $CASEROOT are provided in case variables , pe layout variables , build-time variables , and run-time variables.