The first step in creating a CESM experiment is to use create_newcase.
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 $ |
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 $ |
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. $
CASEcan include letters, numbers, ".", and "_". Note that create_newcase creates the $CASEROOTdirectory. 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 Filename | Description |
|---|---|
| LockedFiles/ | A directory that holds copies of files that should not be changed. |
| Macros.bluefire | 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.case | A file detailing the create_newcase usage in creating your case. This is a good place to keep track of runtime problems and changes. |
| SourceMods | A 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_data | A script that checks for various input datasets and moves them into place. |
| configure | A script used to configure your case. |
| create_production_test | A 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.xml | Controls 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_specific | A 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.xml | Controls 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. |
| xmlchange | A 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.