The first step in creating a CESM experiment is to use create_newcase.
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).
The new component set (compset) longname has the form
TIME_ATM[%phys]_LND[%phys]_ICE[%phys]_OCN[%phys]_ROF[%phys]_GLC[%phys]_WAV[%phys][_BGC%phys] TIME = model time period (e.g. 2000, 20TR, RCP8...) ATM = [CAM4, CAM5, DATM, SATM, XATM] LND = [CLM40, CLM45, DLND, SLND, XLND] ICE = [CICE, DICE, SICE, SICE] OCN = [POP2, DOCN, SOCN, XOCN,AQUAP] ROF = [RTM, DROF, SROF, XROF] 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.
The new model grid longname has the form
a%name_l%name_oi%name_r%name_m%mask_g%name_w%name 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.
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]] \
[-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: In what
follows, $CCSMROOT is the full pathname of the root directory of the
CESM distribution.
> 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.
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 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.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_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 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.