The bundle data type is a fundamental coupler data type. A bundle consists of one or more fields, all of which share the same domain. The field data is stored together in an MCT AttributeVector (mct_aVect) which provides a flexible and indexible storage type. Following MCT, the individual fields (T, u, SST, etc.) are referred to as ``attributes''. Each attribute contains the data for a field in a one-dimensional vector. The size of the vector is equal to the local size of the domain on a processor.
This module defines the bundle datatype and provides several methods for manipulating bundles.
REVISION HISTORY:
2002-Sep-10 - T. Craig - add cpl_bundle_split, cpl_bundle_gather
2001-Mar-20 - T. Craig, B. Kauffman, R. Jacob - first prototype
INTERFACE:
module cpl_bundle_modUSES:
use cpl_mct_mod
use cpl_comm_mod
use cpl_domain_mod
use cpl_kind_mod
use cpl_control_mod, only: dbug=>cpl_control_infoDBug
use cpl_control_mod, only: bfbflag=>cpl_control_bfbflag
use shr_sys_mod
use shr_mpi_mod
implicit none
private ! except
PUBLIC TYPES:
public :: cpl_bundle
type cpl_bundle
character(80) :: name ! id string for bundle
type(cpl_mct_aVect) :: data ! attribute vector containing data
type(cpl_domain),pointer :: dom ! domain associated with data
integer(IN) :: cnt ! counter for accumulating bundles
end type cpl_bundle
PUBLIC MEMBER FUNCTIONS:
public :: cpl_bundle_init
public :: cpl_bundle_initv
public :: cpl_bundle_clean
public :: cpl_bundle_info
public :: cpl_bundle_fill
public :: cpl_bundle_dump
public :: cpl_bundle_copy
public :: cpl_bundle_fcopy
public :: cpl_bundle_split
public :: cpl_bundle_gather
public :: cpl_bundle_hasAttr
public :: cpl_bundle_zero
public :: cpl_bundle_accum
public :: cpl_bundle_avg
public :: cpl_bundle_add
public :: cpl_bundle_mult
public :: cpl_bundle_divide
public :: cpl_bundle_gsum
PUBLIC DATA MEMBERS:
! no public data
Initialize the bundle data type bun. bun will be given the name name and associated with the domain dom. Memory will be allocated to hold the attributes listed in the input rList in an MCT AttributeVector.
REVISION HISTORY:
2001-Mar-20 - T. Craig, B. Kauffman, R. Jacob - first prototypeINTERFACE:
subroutine cpl_bundle_init(bun,name,rList,dom)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(out) :: bun ! bundle to initialize
character(*) ,intent(in) :: name ! name used in netCDF files
character(*) ,intent(in) :: rList ! aVect real data list string
type(cpl_domain),intent(in),target :: dom ! domain assigned to bundle
This routine will initialize bun to have the same attributes as the input bun2 but will be given the new name name and will be associated with the domain dom. Note that this routine only allocates memory and does not copy the contents of bun2 to bun.
REVISION HISTORY:
2002-jan-15 - T. Craig - first prototypeINTERFACE:
subroutine cpl_bundle_initv(bun,name,bun2,dom)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(out) :: bun ! bundle to initialize
character(*) ,intent(in) :: name ! name used in netCDF files
type(cpl_bundle),intent(in) :: bun2 ! bundle to "copy" from
type(cpl_domain),intent(in),target :: dom ! domain assigned to bundle
Deallocate all allocated memory associated with the input/output argument bun.
REVISION HISTORY:
2002-Jan-20 - T. Craig - first prototypeINTERFACE:
subroutine cpl_bundle_clean(bun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle) ,intent(inout) :: bun ! bundle to initialize
Print out the following information about the bundle bun:
REVISION HISTORY:
2002-May-09 - B. Kauffman - make's use of cpl_mct_aVect_info routine
2001-Jun-14 - T. Craig
INTERFACE:
subroutine cpl_bundle_info(bun)USES:
use cpl_fields_mod
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle) ,intent(in) :: bun ! bundle to initialize
Fill each field in the input bundle bun with a slightly different sine wave. Used for debugging.
REVISION HISTORY:
2001-Jun-14 - T. CraigINTERFACE:
subroutine cpl_bundle_fill(bun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(inout) :: bun ! bundle to fill
Write out the contents of bun on each processor to a seperate file. Filename will be fort.(iun + coupler processor id).
REVISION HISTORY:
2002-Jan-14 - T. CraigINTERFACE:
subroutine cpl_bundle_dump(iun,bun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(in) :: bun ! bundle to write
integer(IN),intent(in) :: iun ! base unit number
This routine copies from input argument inbun into the output argument outbun the data of all the attributes shared between the two. If only a subset of shared attributes should be copied, use the optional arguments bunrList and buniList to specify which attributes should be copied. If any attributes in outbun have different names for the same quantity, provide a corresponding optional translation list, bunTrList and bunTiList, in addition to bunrList and buniList. The translation list is identical to the input List with translated names in place of the names in inbun.
Optional argument fcopy directs this routine to use cpl_bundle_copy instead of cpl_mct_aVect_copy. This is obsolete since cpl_mct_aVect_copy now uses the same algorithm.
REVISION HISTORY:
2002-Jul-02 - R. Jacob -- initial versionINTERFACE:
subroutine cpl_bundle_copy(inbun,bunrList,bunTrList,buniList,bunTiList,outbun,fcopy)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(in) :: inbun ! bundle to read
character(*) ,intent(in),optional :: buniList
character(*) ,intent(in),optional :: bunrList
character(*) ,intent(in),optional :: bunTiList
character(*) ,intent(in),optional :: bunTrList
type(cpl_bundle),intent(out) :: outbun ! bundle to write to
logical ,intent(in),optional :: fcopy ! use fcopy
This routine copies from input argument inbun into the output argument outbun the data of all the attributes shared real between the two.
NOTE: This routine will be deleted in future versions since it is no longer necessary.
REVISION HISTORY:
2003-Aug-26 - T. Craig -- initial versionINTERFACE:
subroutine cpl_bundle_fcopy(inbun,outbun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(in) :: inbun ! bundle to read
type(cpl_bundle),intent(out) :: outbun ! bundle to write to
Copy data from input bundle bun_X into multiple output bundles. Can have up to 12 output bundles: bun1, bun2, bun3 etc. On return, each output bundle with an attribute name that matches an attribute in bun_X will have a copy of the data for that attribute.
The optional argument fcopy will use the fast version of cpl_bundle_copy.
This routine is used to ``split'' data in a bundle received in the Coupler from a model into bundles for each data pathway through the Coupler.
NOTE: All arguments must already be initialized.
REVISION HISTORY:
2002-Apr-12 - B. Kauffman - first version
2002-Jul-02 - R. Jacob - use bundle copy
2002-Jul-15 - T. Craig - generalized
INTERFACE:
subroutine cpl_bundle_split(bun_X,bun1,bun2,bun3,bun4,bun5,bun6,bun7,bun8,bun9,bun10,bun11,bun12,fcopy)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle), intent(in ) :: bun_X ! input bundle
type(cpl_bundle),optional,intent(out) :: bun1 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun2 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun3 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun4 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun5 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun6 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun7 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun8 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun9 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun10 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun11 ! split bundle
type(cpl_bundle),optional,intent(out) :: bun12 ! split bundle
logical ,optional,intent(in) :: fcopy ! use fcopy
Copy into the output argument bun_X all the data from the input bundles bun1, bun2, bun3 etc. which have the same attribute names.
The optional argument fcopy will use the fast version of cpl_bundle_copy.
If there is a common attribute name between 2 or more of the input bundles which also exists in the output bundle, the values in the output bundle will that of the last listed input bundle.
This routine is used to ``gather'' data from multiple sources into one bundle for sending from the Coupler to a model.
NOTE: All arguments must already be initialized.
REVISION HISTORY:
2002-Jun-22 - B. Kauffman - first version
2002-Jul-15 - T. Craig - generalized
2003-Sep-01 - T. Craig - add fcopy optional argument
INTERFACE:
subroutine cpl_bundle_gather(bun_X, bun1,bun2,bun3,bun4,bun5,bun6,bun7,bun8,bun9,bun10,bun11,bun12,fcopy)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle), intent(out) :: bun_X ! output bundle
type(cpl_bundle),optional,intent(in ) :: bun1 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun2 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun3 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun4 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun5 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun6 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun7 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun8 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun9 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun10 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun11 ! gather bundle
type(cpl_bundle),optional,intent(in ) :: bun12 ! gather bundle
logical ,optional,intent(in) :: fcopy ! use fcopy
Return true if input bundle bun has any real or integer attributes.
REVISION HISTORY:
2002-Sep-11 - R. Jacob - first versionINTERFACE:
logical function cpl_bundle_hasAttr(bun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(in ) :: bun
Set all fields (real and integer) in input bundle bun to 0. If the optional fld argument is present, only set that field to 0.
The bundle must already be initialized.
REVISION HISTORY:
2002-Sep-15 - T. Craig -- initial version
2002-Sep-17 - T. Craig -- add optional fld argument
INTERFACE:
subroutine cpl_bundle_zero(bun,fld)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle) ,intent(inout) :: bun ! bundle to zero
character(*),optional,intent(in) :: fld ! field in bundle to zero
Accumulate fields in input bundle inbun in output bundle outbun. This mimics cpl_bundle_copy but instead of overwriting the data in outbun with the data in inbun, the data in inbun is added to the corresponding fields in outbun.
It is recommended that a cpl_bundle_accum only be called once for each set of fields to be accumulated at each accumulation step because of the primitive nature of the bundle counter (buntime cpl_bundle_accum is called for the output bundle.
REVISION HISTORY:
2002-Sep-15 - T. Craig -- initial versionINTERFACE:
subroutine cpl_bundle_accum(inbun,bunrList,bunTrList,buniList,bunTiList,outbun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(in) :: inbun ! bundle to read
character(*) ,intent(in),optional :: buniList
character(*) ,intent(in),optional :: bunrList
character(*) ,intent(in),optional :: bunTiList
character(*) ,intent(in),optional :: bunTrList
type(cpl_bundle),intent(out) :: outbun ! bundle to write to
Average the data in input bundle bun. Divide all fields in the bundle bun by the value of the bundle counter, bun%cnt.
REVISION HISTORY:
2002-Sep-15 - T. Craig -- initial versionINTERFACE:
subroutine cpl_bundle_avg(bun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(inout) :: bun ! bundle to read
Form the product of individual fields from the input bundles bun1, bun2, bun3 etc. and add it to the field fld in the input/output argument bun.
fld1 is taken from bun1, fld2 is taken from bun2, etc.
If only fld1 and bun1 are present, then fld1 will be added to bun
If the optional argument scalar is present, it will also by part of the product.
If the optional argument zero is present, the input/output argument bun will be zeroed before adding the product.
This routine is used to merge data in the Coupler.
REVISION HISTORY:
2002-Sep-15 - T. Craig -- initial versionINTERFACE:
subroutine cpl_bundle_add(bun,fld,bun1,fld1,bun2,fld2,bun3,fld3,bun4,fld4,bun5,fld5,bun6,fld6,scalar,zero)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle) ,intent(inout) :: bun ! bundle output
character(*) ,intent(in) :: fld ! bun field name
type(cpl_bundle) ,intent(in) :: bun1 ! bundle input
character(*) ,intent(in) :: fld1 ! bun1 field name
type(cpl_bundle),optional,intent(in) :: bun2 ! bundle input
character(*) ,optional,intent(in) :: fld2 ! bun2 field name
type(cpl_bundle),optional,intent(in) :: bun3 ! bundle input
character(*) ,optional,intent(in) :: fld3 ! bun3 field name
type(cpl_bundle),optional,intent(in) :: bun4 ! bundle input
character(*) ,optional,intent(in) :: fld4 ! bun4 field name
type(cpl_bundle),optional,intent(in) :: bun5 ! bundle input
character(*) ,optional,intent(in) :: fld5 ! bun5 field name
type(cpl_bundle),optional,intent(in) :: bun6 ! bundle input
character(*) ,optional,intent(in) :: fld6 ! bun6 field name
real(R8) ,optional,intent(in) :: scalar ! scalar multiplier
logical ,optional,intent(in) :: zero ! zero lhs initially
Replace each field in bun by the product of that field and the field fld1 from input argument bun1.
If optional argument bunlist is present, only those attributes in bun will be replaced.
If optional argument initbun is present, then the data in bun is replaced by the product of the data in initbun and fld1 from bun1. NOTE: this assume initbun has the exact same attributes in the same order as bun.
REVISION HISTORY:
2002-Oct-15 - T. Craig -- initial version
2003-Jan-02 - T. Craig -- added bundle sub-list option (bunlist)
INTERFACE:
subroutine cpl_bundle_mult(bun,bun1,fld1,bunlist,initbun)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle) ,intent(inout) :: bun ! bundle output
type(cpl_bundle) ,intent(in) :: bun1 ! bundle input
character(*) ,intent(in) :: fld1 ! bun1 field name
character(*),optional,intent(in) :: bunlist! sublist of field in bun
type(cpl_bundle),optional,intent(in):: initbun! optional initialization bun
Divide each attribute in bun by the data in fld1 from the input bundle bun1
REVISION HISTORY:
2002-Oct-15 - T. Craig -- initial versionINTERFACE:
subroutine cpl_bundle_divide(bun,bun1,fld1)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle),intent(inout) :: bun ! bundle output
type(cpl_bundle),intent(in) :: bun1 ! bundle input
character(*) ,intent(in) :: fld1 ! bun1 field name
Calculate the global sum of all the attributes in input bundle bun and output the results to stdout.
The data in bun can be weighted by the optional arguments. If present, the data in bun will be multiplied by the data from fld1 of AV1 and data from fld2 of AV2 and the scalar scalar.
If optional argument istr is present, it will be included in the output string between the global sum and the name of the attribute.
REVISION HISTORY:
2003-Jan-2 - T. Craig -- initial versionINTERFACE:
subroutine cpl_bundle_gsum(bun,AV1,fld1,AV2,fld2,scalar,istr)USES:
INPUT/OUTPUT PARAMETERS:
type(cpl_bundle) ,intent(in) :: bun ! bundle input
type(cpl_mct_aVect),optional,intent(in) :: AV1 ! weight bundle input
character(*) ,optional,intent(in) :: fld1 ! AV1 field name
type(cpl_mct_aVect),optional,intent(in) :: AV2 ! weight bundle input
character(*) ,optional,intent(in) :: fld2 ! AV2 field name
real(R8) ,optional,intent(in) :: scalar ! scalar for weights
character(*) ,optional,intent(in) :: istr ! string for print