This section describes some of the cpl6 modules and how they are used in the Coupler and CCSM3. Detailed information on each module and its contents can be found in the CPL6 API Reference Manual.
One of the fundamental datatypes in cpl6 is the domain which is defined in cpl_domain_mod.F90. The domain contains information about the physical grid that a quantity, such as Temperature, is defined on. This includes a descriptive name for the grid, the total number of points and number of points in each horizontal dimension. (Since all the fields exchanged by the Coupler in CCSM3 are two dimensional, the domain currently only supports two-dimensional grids.) Finally, the domain contains information about the how the global grid is decomposed over processors. This information is stored using an MCT datatype called the GlobalSegmentMap. All of this information is identical on each processor the Coupler runs on.
The domain also includes numerical data about the grid such as the latitude and longitude values and grid-cell area but only for points local to the processor. The contents of this component of a domain will thus vary from processor to processor. The values are stored in another MCT datatype, the AttributeVector. The complete list of values saved for each grid point is:
The bundle is another fundamental datatype in cpl6 and is defined in cpl_bundle_mod.F90. A bundle contains the actual values of fields passed in and out of the coupler such as temperature, wind speed, etc. These values are stored as a one-dimensional vector using an MCT AttributeVector. The bundle also contains a pointer to the domain associated with the data in the bundle. Thus all the data in a bundle must be on the same domain however more than one bundle can point to a given domain.
Within the coupler, there are many bundles. Most are named according to what component they're involved with but their content can also be regrouped using methods such as cpl_bundle_split according to how the Coupler treats them. For example bun_Si2c_i contains all the state data passed from the ice model to the Coupler while bun_Fi2c_i contains the flux data.
While the bundle is for gridded data, the infobuffer, defined in cpl_infobuf_mod.F90 is used to hold scalar data, integers and reals, exchanged between models and the Coupler. ``info'' is used because much of the integer data acts as logical control flags so the Coupler can tell a component model to perform actions such as write a history file or do diagnostics or halt execution. The size of the real and integer parts of the infobuffer and the location of each real and integer number in the arrays is the same in all models and is set by parameters in cpl_fields_mod.F90 (See Sec. 8.6). It is not necessary for each model to define every possible value in the infobuffer. For example, the eccentricity of Earth's orbit is set in the atmosphere model and passed to the Coupler through the infobuffer while the other models never receive or set this value.
The contract is a key concept and an important datatype in cpl6 and is defined in cpl_contract_mod.F90. A contract contains all of the information needed for a single model-coupler exchange. Thus there is one contract for the data sent by the atmosphere model to the Coupler and a second contract for the data received by the atmosphere from the Coupler. The main interaction between a model and the Coupler is conceptualized as first setting and then sending or receiving contracts.
To contain all the information needed for a data exchange, the contract contains an infobuffer, a bundle and a domain (which the bundle points to). The contract also contains an MCT datatype called the Router which contains all the information needed to do a parallel data transfer between a distributed memory parallel model running on one set of processors and the distributed memory parallel Coupler running on a different set of processors.
cpl_interface_mod.F90 contains the routines component models and the Coupler call to interact with each other. The interface is closely related to the contract and a contract is an argument in nearly all the interface routines.
The purpose of the interface module is to provide a simple, compact interface for component models to talk to the Coupler while making no constraints on how the component models represent data internally. Four methods from cpl_interface_mod.F90 do nearly all the work in allowing a component model to interact with the Coupler:
cpl_fields_mod.F90 contains the master list of all scalar and gridded data transferred between the coupler and component models. The coupler and each component model shares this data through Fortran90 USE association of this module. Localizing this information in one module and requiring all component model subroutines which read or set transferred data to use it helps coordinate the access of the simple arrays used in the cpl_interface_mod routines.
The integer indicies for the data in the infobuffer is set in cpl_fields_mod.F90. Elements of the infobuffer are named according to their type and a descriptive name:
The indicies for data sent in the bundle portion of the contract are also set in cpl_fields_mod.F90. These indicies are named according to the direction of travel (Coupler to Atmosphere, c2a, or Atmosphere to Coupler, a2c) and a descriptive name. For example:
Each *_fields string is actually assembled by joining two sub-strings, *_fluxes and *_states. The distinction is used to route the correct data to the correct interpolation routine. See Section 9.2.4 for more information.
Finally, the fields module also contains the total number of fields exchanged between each model and the coupler, e.g. cpl_fields_a2c_total. This parameter is used in setting the size of the simple arrays used in the interface routines at compile-time.
NOTE: There is a strong relation between the colon separated character string *_fields and the integer parameters like cpl_fields_a2c_lwdn. Since ``Faxa_lwdn'' (longwave down from the atmosphere) is the 10th item in the cpl_fields_a2c_fields character string, cpl_fields_a2c_lwdn must be set equal to 10. (See cpl_fields_mod.F90). This relationship must be maintained by the programmer when modifying cpl_fields_mod.F90.
The map module represents a major subsystem of cpl6. Cpl6 uses ``Mapping'' to refer to the interpolation of gridded data from one grid to another, e.g. mapping atmosphere data onto the ocean grid. This is sometimes called ``regridding''.
cpl_map_mod.F90 contains datatypes for holding all of the information needed to perform a mapping of data between two grids and methods for initializing that data, cpl_map_init, and performing the mapping between two bundles, cpl_map_bun.
The details of the mapping calculation are described in Section 16.1. The cpl_map datatype includes not just storage for the mapping weights, but also information needed to perform any communication necessary to complete the mapping. Because the source and destination grids are each decomposed over processors in their own way, all the data needed to complete the mapping may not be present on a processor. Thus cpl_map_bun performs necessary communication using additional information in cpl_map and methods from MCT such as Rearranger.