Chapter 2. Creating a Case

Table of Contents
How to create a new case
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

In what follows, $CCSMROOT is the full pathname of the root directory of your CESM source code. First use the -h option to document the create_newcase options. Then use the -l option to determine which component sets, resolutions, and machines are supported.


> cd $CCSMROOT/scripts
> create_newcase -h 
> create_newcase -l

As explained in cesm compsets, a component set (compset) defines the specific model components that will be used in a given CESM configuration, along with any component-specific namelist or configuration settings that are specific to this configuration. See the component set table for a complete list of supported compset options. If you want to create a custom compset, create an appropriate xml compset file and use the create_newcase option -compset_file on the create_newcase command line. For more information, see the frequently asked quesitons (FAQ) section How do I create my own compset?

See the grids table for a complete list of supported grids options.

See the machines table for a complete list of machines.

Note: CESM component sets and resolutions have both short and long names. Either the short or long name can be entered as input to create_newcase. As an example, the component set B_1850_RAMPCO2_CN has the short name B1850RMCN. Similarly, the resolution, 0.9x2.5_gx1v6 has the short name f09_g16. Both the long and short names appear in the output from create_newcase -l, where the short name always appears in parentheses.

For a generic machine, create_newcase can be invoked with the following arguments:


> create_newcase -case [case name] \
           -mach [machine name] \
           -compset [compset name] \
           -res [resolution] \
           -scratchroot [executable root directory] \
           -din_loc_root_csmdata [input data root directory] \
           -max_tasks_per_node [max mpi tasks per node] \
           [-pes_file [user-defined pes-setup file]] \
           [-compset_file [user-defined compset file]] \
           [-pecount [S, M, L, X1, or X2]] \
           [-silent] [-verbose] \
           [-xmlmode normal/expert]

For a non-generic machine, create_newcase can be invoked with the following arguments:


> create_newcase -case [case name] \
           -mach [machine name] \
           -compset [compset name] \
           -res [resolution] \
           [-pes_file [user-defined pes-setup file]] \
           [-compset_file [user-defined compset file]] \
           [-pecount [S, M, L, X1, or X2]] \
           [-silent] [-verbose] \
           [-xmlmode normal/expert]

Note: -case, -mach, -compset and -res are required arguments to create_newcase. In addition, -scratchroot, -din_loc_root_csmdata and -max_tasks_per_node are additional required arguments when a generic machine is targeted.

If you want to use your own pes setup file, specify the full pathname of that file for the optional -pes_file argument. The sample pes_file format is provided at $CCSMROOT/sample_pes_file.xml.

Here is a simple example of using create_newcase for a non-generic machine.


> cd $CCSMROOT/scripts
> create_newcase -case ~/cesm/b40.B2000 \
                 -compset B_2000 \
                 -res 0.9x1.25_gx1v6 -mach yellowstone

This example creates a $CASEROOT directory ~/cesm/b40.B2000 where $CASE is b40.B2000 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_2000 uses fully active components configured to produce a present-day simulation.

Note: 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.

create_newcase creates the directory $CASEROOT, which is specified by the -case option. In $CASEROOT, create_newcase installs the files and directories that are responsible for configuring, building, and running the case. For example, the above command creates the following files and directories in ~/cesm/b40.B2000/. (Note that user-modifiable files/directories appear in italics.)

Directory or FilenameDescription
LockedFiles/A directory that holds copies of files that should not be changed.
Macros.yellowstone Contains machine-specific makefile directives. In the current release, the Macros have been organized into groups of machine-dependent files each containing site-specific and machine-specific options.
README/A directory of README files for the components.
README.caseA file detailing the create_newcase usage in creating your case. This is a good place to keep track of runtime problems and changes.
SourceModsA directory where users can place modified source code.
Tools/A directory containing support utility scripts. Users should never need to access the contents of this directory.
check_input_dataA script that checks for various input datasets and moves them into place.
configure A script used to configure your case.
create_production_testA script used to create a test of your case.
env_build.xml Controls model build settings (see customizing a build).
env_case.xml Sets model components and resolution. This file cannot be modified after a case has been created. To make changes, re-run create_newcase with different options.
env_conf.xml Controls general settings including run initialization type (see the Section called Setting the case initialization type in Chapter 3), coupler mapping files, component configuration, and namelist generation. Sets environment variables that are used by the component template scripts to generate component namelist and build scripts (see customizing components).
env_mach_pes.xmlControls component machine-specific processor layout (see the Section called Setting the case PE layout in Chapter 3). The settings in this are critical to a well-load-balanced simulation (see loadbalancing a run).
env_mach_specificA file used to set a number of machine-specific environment variables for building and/or running. This file can be edited at any time. However, build environment variables should not be edited after a build is invoked.
env_run.xmlControls run-time settings such as length of run, frequency of restarts, output of coupler diagnostics, and short-term and long-term archiving. See running a case.
xmlchangeA script used to modify values in the xml files.

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

Note: Since default values are provided for the above xml file variables, you could now go to configuring a case and configure your case. However, you should first understand what variables you might want to change and how these xml variables are used by the scripts. Please continue reading below if you are a new user.

The xml variables in the env_*.xml files are translated into csh environment variables with the same name by the script Tools/ccsm_getenv. Conversion of xml variables to environment variables is used by numerous script utilities as part of configuring, 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 env_case.xml variables, env_conf.xml variables , env_mach_pes.xml variables , env_build.xml variables , and env_run.xml variables.