Chapter 2. CPL7 User Guide

Table of Contents
General Overview
Design Discussion

General Overview

Note: This document discusses the coupler in the CESM1 model. The coupler in this implementation is nearly identical to the version in the CCSM4 release. In fact, many of the variables, filenames, comments, and namelists still use the CCSM name convention. Any reference in this document to the CESM1 version will generally hold for the CCSM4 release as well. Comparisons are generally made to the CCSM3 coupler which was a very different coupler.

The CESM1 Version of the Community Earth System Model has some significant changes compared to previous pre-CCSM4 versions. In particular, CESM1 is NOT run via multiple executables in a concurrent only processor layout. There is now a top level driver and components are called via standard init, run, and finalize methods. Components can be run sequentially, concurrently, or in some mixed sequential/concurrent layout on processors. A coupler component that runs on a subset of the total processors still exists in the system as part of the driver. The driver runs on all processors and the coupler functions (mapping, merging, flux calculations, and diagnostics) runs on a user defined subset of the total processors. The processor layout is specified at runtime via namelist inputs.

While the processor layout is relatively flexible and components can be run sequentially or concurrently, the sequencing of the science in the driver is fixed and independent of the processor layout. So changing the processor layout only changes the performance of the simulation system.

Like all components in CESM, the driver scripting system is setup such that a component template file (models/drv/bld/cpl.template) is run by the cesm configure script, and it generates partially resolved cpl.buildnml.csh and cpl.buildexe.csh scripts. The CESM configure script also generates case .build, .run, and .clean_build scripts. See the CESM user guide for more detailed information about this process. But briefly, the process is as follows,

 - run create_newcase to generate a case directory.
 - edit env_conf.xml and env_mach_pes.xml and then run configure -case.  this 
   runs the coupler cpl.template file among other things.  the configure script
   generates the .build, .run, and .clean_build scripts and
   the partially resolved buildnml and buildexe scripts in the
   Buildconf directory.
 - edit env_build.xml and run the .build script.
 - edit env_run.xml and submit the .run script.