This module represents a major subsystem of cpl6.
This module contains the highest level routines for communication between models and the Coupler.
These routines present component models with an API using mostly native Fortran 90 datatypes such as real an integer scalars and arrays. Only one derived datatype, the contract appears in the arguments. This satisifes a Coupler requirement to present a simple interface to coupled model programmers. Most of the routines in this module are wrappers to other cpl6 subroutines.
These routines are all that is necessary for a component model to connect to, and exchange data with, version 6 of the CCSM Coupler.
REVISION HISTORY:
2003-Jan-15 - T. Craig - change ibuf to infobuf datatype module
2002-Dec-05 - T. Craig - changed call from cpl_coupling to cpl_contract
2002-Sep-10 - T. Craig - abstracted functionality into cpl_coupling_mod.F90
2001-Aug-16 - B. Kauffman - reorganized code according to arch document.
2001-Mar-20 - T. Craig - first prototype
INTERFACE:
module cpl_interface_modUSES:
use cpl_mct_mod ! mct interface
use cpl_comm_mod ! mpi/mph communicator info
use cpl_fields_mod ! coupler/model data field indicies
use cpl_bundle_mod ! defines bundle
use cpl_domain_mod ! defines domain
use cpl_infobuf_mod ! defines infobuf
use cpl_contract_mod ! defines contract
use cpl_kind_mod ! defines cpl kinds
use cpl_control_mod, only: dbug=>cpl_control_infoDBug
use shr_sys_mod ! share system routines
use shr_timer_mod ! share timer routines
use shr_mpi_mod ! mpi layer
implicit none
private ! except
PUBLIC TYPES:
! nonePUBLIC MEMBER FUNCTIONS:
public :: cpl_interface_init
public :: cpl_interface_finalize
public :: cpl_interface_ibufSend
public :: cpl_interface_ibufRecv
public :: cpl_interface_infobufSend
public :: cpl_interface_infobufRecv
public :: cpl_interface_contractSend
public :: cpl_interface_contractRecv
public :: cpl_interface_contractInit
public :: cpl_interface_dbugSet ! set this module's internal dbug level
interface cpl_interface_ibufSend; module procedure cpl_interface_infobufSend; end interface
interface cpl_interface_ibufRecv; module procedure cpl_interface_infobufRecv; end interface
PUBLIC DATA MEMBERS:
! none
Wrapper routine for cpl_comm_init. Calls MPI_Init and reports model name to the coupled system. Returns an MPI_Communicator comm for use in the calling model.
name must be one of the component names in cpl_fields_mod.
REVISION HISTORY:
2001-Mar-20 - T. Craig, B. Kauffman, R. Jacob -- first prototypeINTERFACE:
subroutine cpl_interface_init(name,comm)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
character(*),intent(in) :: name ! name of component name
integer(IN) ,intent(out) :: comm ! communicator group for component
Calls MPI_Finalize() and disengages the model cname from the CCSM. cname must be one of the component names in cpl_fields_mod.
REVISION HISTORY:
2001-mmm-dd -INTERFACE:
subroutine cpl_interface_finalize(cname)USES:
INPUT/OUTPUT PARAMETERS:
character(*),intent(in) :: cname ! component name
integer(IN) :: rcode ! return code
Initialize the contract between model my_name and model other_name. This is a wrapper to cpl_contract_init. Only two sets of optional arguments are allowed. A Model uses the ``send'' form and should provide buf, which contains grid information such as latitude and longitude values (see cpl_contract_initSend). The Coupler uses the ``recv'' form and does not provide buf. bunname and fields are used to initialize the bundle in the output contract.
REVISION HISTORY:
2002-Jul-30 - T.Craig -- prototypeINTERFACE:
subroutine cpl_interface_contractInit(contract,my_name,other_name,fields,ibufi,buf,ibufr,bunname,decomp)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_contract) ,intent(out) :: contract ! contract
character(*) ,intent(in) :: my_name ! my component name
character(*) ,intent(in) :: other_name ! other component name
character(*) ,intent(in) :: fields ! fields char string for bun
integer(IN) ,optional,intent(inout) :: ibufi(:) ! info buffer ints
real(R8) ,optional,intent(in) :: buf(:,:) ! data buffer
real(R8) ,optional,intent(inout) :: ibufr(:) ! info buffer reals
character(*),optional,intent(in) :: bunname
integer(IN) ,optional,intent(in) :: decomp ! decomposition type
Load an infobuffer using the input arrays ibufi and ibufr and send it to the root processor of the model with name cname.
REVISION HISTORY:
2001-Aug-16 -INTERFACE:
subroutine cpl_interface_infobufSend(cname,ibufi,ibufr)USES:
INPUT/OUTPUT PARAMETERS:
character(*) ,intent(in) :: cname ! component name
integer(IN),optional,intent(inout) :: ibufi(:) ! info buffer ints
real(R8) ,optional,intent(inout) :: ibufr(:) ! info buffer reals
Receive an infobuffer from the model with name cname and return its integer contents in the ibufi array and the real contents in the ibufr array.
REVISION HISTORY:
2001-mmm-dd -INTERFACE:
subroutine cpl_interface_infobufRecv(cname,ibufi,ibufr)USES:
INPUT/OUTPUT PARAMETERS:
character(*) ,intent(in) :: cname ! component name
integer(IN),optional,intent(out) :: ibufi(cpl_infobuf_ibufSize) ! info-buffer
real(R8) ,optional,intent(out) :: ibufr(cpl_infobuf_rbufSize) ! info-buffer
Send data in the infobuffer and bundle of the input contract to the component cname (which could be a model or the Coupler). If optional arguments ibufi and/or ibufr are present, that information will be placed in the contract's infobuffer and sent instead. If optional argument buf is present, then that data will be placed in in the contract's bundle and sent to cname.
In CCSM3, the Coupler calls this with only cname and contract while Models use the simple ibufi and buf arguments.
REVISION HISTORY:
2001-mmm-dd -INTERFACE:
subroutine cpl_interface_contractSend(cname,contract,ibufi,buf,ibufr)USES:
INPUT/OUTPUT PARAMETERS:
character(*) ,intent(in) :: cname ! component name
type(cpl_contract) ,intent(inout) :: contract ! data buffer and domain
integer(IN),optional,intent(inout) :: ibufi(:) ! info buffer ints
real(R8) ,optional,intent(inout) :: ibufr(:) ! info buffer reals
real(R8) ,optional,intent(inout) :: buf(:,:) ! data buffer
Recive data into the infobuffer and bundle of the input/output contract from the component cname (which could be a model or the Coupler). If optional arguments ibufi and/or ibufr are present, that information is copied out of the contract's infobuffer and placed into those arrays. If optional argument buf is present, then data in the contract's bundle after the receive will be returned in buf.
In CCSM3, the Coupler calls this with only cname and contract while Models use the simple ibufi and buf arguments.
REVISION HISTORY:
2001-mmm-dd -INTERFACE:
subroutine cpl_interface_contractRecv(cname,contract,ibufi,buf,ibufr)USES:
INPUT/OUTPUT PARAMETERS:
character(*) ,intent(in) :: cname ! component name
type(cpl_contract) ,intent(inout) :: contract ! data buffer and domain
integer(IN),optional,intent(out) :: ibufi(:) ! info buffer ints
real(R8) ,optional,intent(out) :: ibufr(:) ! info buffer reals
real(R8) ,optional,intent(out) :: buf(:,:) ! data buffer
Set this module's internal debug level: 0,1,2,3 (lowest to highest). If debug level is 2 or greater, each call to cpl_interface_contractSend or cpl_interface_contractRecv will output the global sum of all data sent/received to stdout using cpl_bundle_gsum.
REVISION HISTORY:
2003-Jan-21 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_interface_dbugSet(level)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN),intent(in) :: level ! requested debug level