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 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 $ |
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 $ |
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 Filename | Description |
|---|---|
| README.case | File detailing your create_newcase usage. This is a good place for you to keep track of runtime problems and changes. |
| CaseStatus | File 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 7. 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_specific | File 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.xml | Sets 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_archive | Script 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. |
| xmlchange | Utility for modifying values in the xml files. |
| preview_namelists | Utility 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_data | Utility that checks for various input datasets and moves them into place. |
| create_production_test | Utility 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 7
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.