7 Source Code Overview

Source code for the coupler is available as part of the CCSM3 distribution at
http://www.cesm.ucar.edu/models/ . This distribution includes the source code for all CCSM component models. Documentation for other CCSM component models, as well as input data for running the models, is also available at this site.

The coupler code consists of two parts. The coupler main specific to this version of CCSM is located in .../models/cpl/cpl6/ (All path names are relative to the top level directory created when untarring the CCSM3 source code distribution.) The general-purpose cpl6 datatypes and methods are located in CCSM's location for code shared by all the component models,
.../models/csm_share/cpl.

7.1 cpl6 programming conventions

The Coupler source code is written entirely using standard Fortran 90. Interfacing with the Coupler requires at least a portion of an interfacing model's code, the part that communicates with the Coupler, to be compiled with a Fortran90 compiler. The Coupler uses a naming convention for source files and the functions they contain. In general, the source code for cpl_<module name>_<method name> can be found in cpl_<module name>_mod.F90. Files containing _mod.F90 are Fortran90 modules.

The source files are self documenting with headers and comments written for post-processing with the Protex system. Protex generates L^ATEXversions of the header information and allows a close linkage between source and documentation.

The Coupler source code was developed using the CVS revision control system, but only one ``tagged'' version of the Coupler is available within any CCSM source code distribution. This information can be used to identify the coupler version contained in a particular distribution and is printed as part of the output when the coupler starts.

The Coupler can only be built within CCSM's build system which uses GNUMake. There is no ``standalone'' coupler. Within the CCSM build system, the coupler is treated as a component like the atmosphere, ocean, etc. and is built automatically with the rest of CCSM3's components. See the CCSM3 User's Guide for more information on the build system.

7.2 The cpl6 version of the CCSM coupler

The source code for the CCSM coupler is located in .../models/cpl/cpl6. The directory path follows the CCSM convention: .../models/cpl contains all of the couplers that could be used in the CCSM system just like ../models/atm contains the atmosphere model's available in the system. .../models/cpl/cpl6 contains the implementation of the CCSM coupler using cpl6 datatypes and methods.

A summary of the modules and subroutines in .../models/cpl/cpl6 is given below. Additional details can be found below or in Part III for code which handles scientific calculations in the coupler.

main.F90

Contains all the code to implement the ``hub'' in the CCSM3 hub-and-spoke, concurrent execution system (See Section 12) including all communication calls with component models and appropriate mapping and flux calculation calls.
(remaining routines are in alphabetical order)

areafact_mod.F90

Module to hold and calculate grid area ratios. See Section 16.4

bitCheck_mod.F90

Module with routines to calculate and output statistics for a field at high precision for bit-for-bit checking.

data_mod.F90

Module to hold and initialize most variables used in main.F90

diag_mod.F90

Module with routines for calculating global diagnostics.

flux_mod.F90

Module with routines for calculating inter-model fluxes and surface albedos. See Section 16.2

frac_mod.F90

Module to hold, initialize and update inter-model fractional weights. See Section 16.5

history_mod.F90

Module with routines to write instantaneous and time average coupler history files.

merge_mod.F90

Module with routines for merging fluxes between models.

restart_mod.F90

Module with routines to read/write Coupler restart files.

tStamp_mod.F90

Module with routine to output current model date and time

timeCheck.F90

Module with routine to verify/enforce time coordination between models.

Code for many of the Coupler's tasks (diagnostics, flux calculation) are naturally separated into files as above. However we should note that some modules, such as merge_mod.F90 and data_mod.F90 were created to prevent main.F90 from becoming too long.

7.3 Cpl6 General Datatypes and Methods.

Besides a new version of the CCSM coupler main(), cpl6 also includes a set of Fortran90 modules consisting of derived datatypes and methods which act on them. The contents of these modules are used to construct the new coupler and provide a uniform, flexible and extendable interface between the Coupler and the component models of CCSM.

The cpl6 modules make extensive use of another set of Fortran90 modules called the Model Coupling Toolkit (MCT). MCT provides generic datatypes and methods for the construction of parallel couplers in a distributed memory parallel application. cpl6 combines and extends many of the datatypes in MCT and provides additional datatypes to meet the specific requirements of the CCSM Coupler. The reader of this section may also need to refer to The Model Coupler Toolkit API Reference Manual and the User's Guide to the Model Coupling Toolkit for additional information on the concepts underlying cpl6.
See http://www.mcs.anl.gov/mct.

A summary of what each module in cpl6 handles is below in alphabetical order:

cpl_bundle_mod.F90

The gridded data values exchanged between model's and the domain associated with that data.

cpl_comm_mod.F90

MPI communication groups and model ID's. This module uses methods from the MPH3 library to divide MPI_COMM_WORLD into sections for each component.

cpl_const_mod.F90

Physical and other constants used in the Coupler.

cpl_contract_mod.F90

Information needed to exchange data between models including a bundle and a domain.

cpl_control_mod.F90

Integration control and Fortran namelist processing for the Coupler.

cpl_domain_mod.F90

Data about the grid (latitude, longitude values, etc.) and its parallel decomposition.

cpl_fields_mod.F90

Master list of all fields exchanged between models and the Coupler.

cpl_infobuf_mod.F90

Scalar data exchanged between models.

cpl_interface_mod.F90

Wrapper routines with simple arguments used to interface between component models and the Coupler.

cpl_iobin_mod.F90

Binary I/O methods for the Coupler

cpl_iocdf_mod.F90

NetCDF I/O methods for the Coupler

cpl_kind_mod.F90

Fortran90 KIND typing for the Coupler

cpl_map_mod.F90

Interpolation between different grids

cpl_mct_mod.F90

Master list of MCT functions and datatypes used in cpl6

7.4 Summary of CPL6 structure

The software which makes up cpl6 is summarized in Figure 1.

Figure 1: The software structure of cpl6.

The cpl6 main is the top level program and is built on top of the software layers beneath it. MPEU, the Message Passing Environment Utilities, is part of MCT. OpenMP and BLAS calls are planned for future releases.