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
New 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

In what follows, $CCSMROOT is the full pathname of the root directory of the CESM distribution. You should first use the -h option in calling create_newcase to document its input 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

CESM supports out of the box model resolutions, hardware platforms and component sets. 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. 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 (see How do I create my own compset?).

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. As of CESM1.1, it is now simpler for you to introduce both new user defined grids and new machines.

create_newcase can be invoked 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] \
     [-compset_file full-pathname] \
     [-grid_file full-pathname] \
     [-help [or -h]] |
     [-list] \         
     [-silent [or -s]] \
     [-verbose [or -v]] \
     [-xmlmode [normal, expert]] \
     [-nowarning]      

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:


> cd $CCSMROOT/scripts
> create_newcase -case ~/cesm1/example1 \
                 -compset B_1850_CN \
                 -res 0.9x1.25_gx1v6 \
                 -mach bluefire 

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.

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.n)
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 $CASE.run script and user_nl_xxx files)
$CASE.$MACH.build 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 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.