The following quick start guide is for versions of CESM that have already been ported to the local target machine. If CESM has not yet been ported to the target machine, please see Chapter 5. If you are new to CESM1, please consider reading the introduction first

These definitions are required to understand this section:

  • $COMPSET refers to the component set.
  • $RES refers to the model resolution.
  • $MACH refers to the target machine.
  • $CCSMROOT refers to the CESM root directory.
  • $CASE refers to the case name.
  • $CASEROOT refers to the full pathname of the root directory where the case ($CASE) will be created.
  • $EXEROOT refers to the executable directory. ($EXEROOT is normally NOT the same as $CASEROOT).
  • $RUNDIR refers to the directory where CESM actually runs. This is normally set to $EXEROOT/run.

This is the procedure for quickly setting up and running a CESM case.

  1. Download CESM (see Download CESM).

  2. Select a machine, a component set, and a resolution from the list displayed after invoking this command:

    > cd $CCSMROOT/scripts
> create_newcase -list

    See the supported component sets, supported model resolutions and supported machines. for a complete list of CESM1.1 supported component sets, grids and computational platforms.

  3. Create a case.

    The create_newcase command creates a case directory containing the scripts and xml files to configure a case (see below) for the requested resolution, component set, and machine. create_newcase has several required arguments and if a generic machine is used, several additional options must be set (invoke create_newcase -h for help).

    If running on a supported machine, ($MACH), then invoke create_newcase as follows:

    > create_newcase -case $CASEROOT \
         -mach $MACH \
         -compset $COMPSET \
         -res $RES

    If running on a new target machine, see porting in Chapter 5.

  4. Setting up the case run script

    Issuing the cesm_setup command creates a $CASEROOT/$CASE.run script along with user_nl_xxx files, where xxx denotes the set of components for the given case configuraiton. Before invoking cesm_setup, modify the env_mach_pes.xml file in $CASEROOT as needed for the experiment.

    1. cd to the $CASEROOT directory.

      > cd $CASEROOT

    2. Modify settings in env_mach_pes.xml (optional). (Note: To edit any of the env xml files, use the xmlchange command. invoke xmlchange -h for help.)

    3. Invoke the cesm_setup command.

      > ./cesm_setup

  5. Build the executable.

    1. Modify build settings in env_build.xml (optional).

    2. Run the build script.

      > $CASE.build

  6. Run the case.

    1. Modify runtime settings in env_run.xml (optional). In particular, set the $DOUT_S variable to FALSE.

    2. Submit the job to the batch queue. This example uses a submission command for a Cray computer:

      > qsub $CASE.run

  7. When the job is complete, review the following directories and files

    1. $RUNDIR. This directory is set in the env_build.xml file. This is the location where CESM was run. There should be log files there for every component (ie. of the form cpl.log.yymmdd-hhmmss). Each component writes its own log file. Also see whether any restart or history files were written. To check that a run completed successfully, check the last several lines of the cpl.log file for the string " SUCCESSFUL TERMINATION OF CPL7-CCSM ".

    2. $CASEROOT/logs. The log files should have been copied into this directory if the run completed successfully.

    3. $CASEROOT. There could be a standard out and/or standard error file.

    4. $CASEROOT/CaseDocs. The case namelist files are copied into this directory from the $RUNDIR.

    5. $CASEROOT/timing. There should be a couple of timing files there that summarize the model performance.

    6. $DOUT_S_ROOT/$CASE. This is the archive directory. If $DOUT_S is FALSE, then no archive directory should exist. If $DOUT_S is TRUE, then log, history, and restart files should have been copied into a directory tree here.