8 Major cpl6 Modules

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.

8.1 The domain module

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:

lat

latitude value in degrees

lon

longitude value in degrees

area

the component's (e.g. ocean) value for the area of a grid cell

aream

the mapping program's (e.g. SCRIP) value for the area of a grid cell

mask

list of active/inactive cells. 0 for inactive cells

pid

Processor id (identical for all points)

8.2 The bundle module

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.

8.3 The infobuf module

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.

8.4 The contract module

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.

8.5 The interface module

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_interface_init

Initialize the communication infrastructure, e.g. MPI communicator groups.

cpl_interface_contractInit

Initialize a contract with the Coupler. This is where the coupler is told the grid of the component model and what fields will be exchanged.

cpl_interface_contractSend

Send data (bundles and infobuffers) to the Coupler

cpl_interface_contractRecv

Receive data (bundles and infobuffers) from the Coupler

Along with reducing the needed routines to a handful, the interface module also simplifies the argument list. Aside from the contract, which is a Fortran90 derived datatype, the remaining arguments in cpl_interface_ methods are simple native Fortran (90 or 77) types such as real and integer scalars and arrays. Access to these simple arrays is coordinated through the use of integer indicies defined in the fields module discussed below. By making no assumptions on the relation between Coupler datatypes and model datatypes, moving data between the model's internal data structures and the arguments to cpl_interface_* is done with a copy. Testing shows that the cost of all copying is insignificant compared to the total time to simulate a day in CCSM3. More detail on the use of INTERFACE is given in Section 10.2.

8.6 The fields module

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:

cpl_fields_ibuf_<name>:

index of an integer scalar quantity in the integer portion of the infobuffer

cpl_fields_rbuf_<name>:

index of a real scalar quantity in the real portion of the infobuffer

Examples include cpl_fields_ibuf_rcode, an inter-model error code and
cpl_fields_rbuf_eccen, the eccentricity of the Earth's orbit. The values given to these indicies in cpl_fields_mod.F90 are arbitrary. CCSM developers should ignore them and use the long names like cpl_fields_rbuf_eccen to retrieve/set values in the interface arrays.

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:

cpl_fields_a2c_lwdn

Longwave Downward radiation passed from the Atmosphere to the Coupler

cpl_fields_c2i_ot

Ocean Sea Surface Temperature passed from the Coupler to the Ocean

Along with integer indicies for each field exchanged, the fields module also contains a colon-delimited character string defining the fields exchanged between each model and the coupler. One example is the string defining all the fields sent from the atmosphere to the coupler, cpl_fields_a2c_fields. This and similar character strings are used by the Coupler to allocate memory in a BUNDLE at runtime. The number of colon-separated items in the string is counted and that number, along with the local grid size, is used to allocate local storage. The individual string names, also called ``attributes'' of the BUNDLE (and the underlying MCT ATTRIBUTEVECTOR), are used internally by the Coupler to access data in the bundle. The exact name of each field is up to the user however repeating names between strings is part of the how the Coupler controls the flow of information between components (Section 9.2.4).

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.

8.7 The map module

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.