4 Contract

4.1 Module cpl_contract_mod - coupler/component contract type (Source File: cpl_contract_mod.F90)

The contract datatype encapsulates all the information needed to communicate data between the Coupler and a model. This includes both the information being exchanged, contained in a bundle and an infobuffer and the relevant domain for the bundle. The contract also contains the information needed to send the data between the model's and the coupler's processors in an MCT Router datatype.

The routines in this module initialize and process contracts. It's functionality relies heavily on the MCT, MPH, and MPI libraries. These routines should not be called directly, use the cpl_interface_mod routines instead.

REVISION HISTORY:

       2002-Jul-16 - T. Craig - abstracted basic functionality from
                     cpl_msg and cpl_interface to this layer.
       2002 Aug 01 - T. Craig - prototype for contract datatype
       2002 Dec 05 - T. Craig - combined cpl-coupling module and cpl_contract

INTERFACE:

 
 module cpl_contract_mod

USES:

 
    use shr_timer_mod       ! timers
    use cpl_kind_mod        ! kinds
    use cpl_mct_mod         ! mct interface
    use cpl_comm_mod        ! mpi/mph communicator info
    use cpl_fields_mod      ! fields module
    use cpl_bundle_mod      ! defines bundle
    use cpl_domain_mod      ! defines domain
    use cpl_infobuf_mod     ! defines infobuf 
    use cpl_control_mod, only: dbug=>cpl_control_infoDBug
 
    implicit none
 
    private ! except

PUBLIC TYPES:

 
    public :: cpl_contract
 
    type cpl_contract
       type(cpl_infobuf)     :: infobuf       ! infobuf that goes with contract
       type(cpl_bundle)      :: bundle        ! bundle
       type(cpl_domain)      :: domain        ! domain info (grid with decomp)
       type(cpl_mct_Router)  :: rtr           ! MxN communication info
    end type cpl_contract

PUBLIC MEMBER FUNCTIONS:

 
    public :: cpl_contract_execute
    public :: cpl_contract_send
    public :: cpl_contract_recv
    public :: cpl_contract_init
    public :: cpl_contract_initSend
    public :: cpl_contract_initRecv

PUBLIC DATA MEMBERS:

 
   ! none

4.1.1 cpl_contract_execute - send/recv data/msg to component.

Code for cpl_contract_send and cpl_contract_recv combined into one routine.

REMARKS:

REVISION HISTORY:

      2002-09-10 - T.Craig - merged cpl_contract_send, cpl_contract_recv

INTERFACE:

 
 subroutine cpl_contract_execute(srtype,contract,mypid,comm,otherpid)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    character(*)      ,  intent(in)   :: srtype   ! 'send' or 'recv'
    type(cpl_contract),  intent(inout):: contract ! contract
    integer(IN),         intent(in)   :: mypid    ! my mpi process ID
    integer(IN),         intent(in)   :: comm     ! local communicator group
    integer(IN),         intent(in)   :: otherpid ! mpi process ID to send to

4.1.2 cpl_contract_send - send data/msg to component.

Send the data contained in the infobuffer and bundle of the input contract. infobuffer is sent from the root of MPI_Communicator comm and sent to otherpid in cpl_comm_wrld.

REMARKS:

     cpl_comm_wrld is defined in cpl_comm_mod

REVISION HISTORY:

      2002-08-01 - T.Craig - abstracted from cpl_interface and cpl_msg

INTERFACE:

 
 subroutine cpl_contract_send(contract,mypid,comm,otherpid)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    type(cpl_contract),  intent(inout):: contract ! contract
    integer(IN),         intent(in)   :: mypid    ! my mpi process ID
    integer(IN),         intent(in)   :: comm     ! local communicator group
    integer(IN),         intent(in)   :: otherpid ! mpi process ID to send to

4.1.3 cpl_contract_recv - receive data/msg from component.

Receive data into the infobuffer and bundle of the input/output argument contract. infobuffer is recived from otherpid in cpl_comm_wrld on the root of MPI_Communicator comm and then broadcast over comm

REMARKS:

     cpl_comm_wrld is defined by cpl_comm_mod

REVISION HISTORY:

      2002-08-01 - T.Craig - abstracted from cpl_interface and cpl_msg

INTERFACE:

 
 subroutine cpl_contract_recv(contract,mypid,comm,otherpid)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    type(cpl_contract),  intent(inout):: contract  ! contract
    integer(IN),         intent(in)   :: mypid     ! my mpi process ID
    integer(IN),         intent(in)   :: comm      ! local communicator group
    integer(IN),         intent(in)   :: otherpid  ! mpi process ID to recv from

4.1.4 cpl_contract_init - Initialize a contract

Initialize the input contract and the domain in the contract. The contract will be between model my_name and model ohter_name. Both models must make matching calls to this routine.

This routine is currently somewhat uneven because it both initializes a contract and sends grid data (lat, lon, area) values from a model to the Coupler and initializes the domain in the contract. This is how the Coupler ``learns'' what grid each model is running on. (The Coupler does not know this information at runtime.) The Coupler always calls this routine with srtype set to ``recv'' while the models call it with srtype set to ``send'' and supply the optional argument buf which contains the grid data. The sequence of events is:

1. Model sends infobuffer to Coupler which contains total sizes of grid.
2. both Model and Coupler initialize total grid size portion of contract's domain.
3. Coupler describes decomposition of Model's grid on the Coupler processors according to input argument decomp. Default decomposition is simple one-dimensional over all Coupler processors.
4. Both Model and Coupler initialize MCT GlobalSegMap part of domain
5. Model and Coupler initilize an MCT Router between them.
6. Model sends its grid data (lat, lon, area values) to Coupler.

REMARKS:

       This routine is called by cpl_interface_contractInit.

REVISION HISTORY:

      2002-Jul-30 - T.Craig -- prototype

INTERFACE:

 
 subroutine cpl_contract_init(srtype,contract,my_name,other_name,buf,decomp)

INPUT/OUTPUT PARAMETERS:

 
    character(*)        ,intent(in) :: srtype        ! 'send' or 'recv'
    character(*)        ,intent(in) :: my_name       ! component name (me)
    character(*)        ,intent(in) :: other_name    ! component name (other)
    type(cpl_contract)  ,intent(out):: contract      ! contract
    real(R8),optional   ,intent(in) ::  buf(:,:)     ! data buffer
    integer(IN),optional,intent(in) :: decomp        ! recv side decomp type
                                                     ! 1 = 1d in lat
                                                     ! 2 = 1d in lon

4.1.5 cpl_contract_initSend - Initialize contract, send side

Initialize the output contract between model my_name and model other_name. Send other_name the grid information in buf.

The first dimension of the array buf is the local size of the grid. The second dimenstion is cpl_fields_grid_total. The contents of the second dimension are the cpl_fields_grid_fields.

This calls cpl_contract_init with srtype equal to ``send''.

REVISION HISTORY:

      2002-Sep-10 - T.Craig -- prototype

INTERFACE:

 
 subroutine cpl_contract_initSend(contract,my_name,other_name,buf)

INPUT/OUTPUT PARAMETERS:

 
    character(*)      ,intent(in)  :: my_name       ! component name (me)
    character(*)      ,intent(in)  :: other_name    ! component name (other)
    type(cpl_contract),intent(out) :: contract      ! contract
    real(R8)          ,intent(in)  ::  buf(:,:)     ! data buffer

4.1.6 cpl_contract_initRecv - Initialize contract, receive side

Initialize the output contract between model my_name and model other_name. Recv grid information from other_name and store it in the domain of the contract.

This calls cpl_contract_init with srtype equal to ``recv''.

REVISION HISTORY:

      2002-Sep-10 - T.Craig -- prototype

INTERFACE:

 
 subroutine cpl_contract_initRecv(contract,my_name,other_name)

INPUT/OUTPUT PARAMETERS:

 
    character(*)      ,intent(in) :: my_name       ! component name (me)
    character(*)      ,intent(in) :: other_name    ! component name (other)
    type(cpl_contract),intent(out):: contract      ! contract