An accumulator is a data class used for computing running sums
and/or time averages of AttrVect class data.
The period of time over which data are accumulated/averaged is the
accumulation cycle, which is defined by the total number
of accumulation steps (the component Accumulator%num_steps). When
the accumulation routine accumulate_ is invoked, the number
of accumulation cycle steps (the component
Accumulator%steps_done)is incremented, and compared with
the number of steps in the accumulation cycle to determine if the
accumulation cycle has been completed. The accumulation buffers
of the Accumulator are stored in an AttrVect (namely
the component Accumulator%data), which allows the user to
define the number of variables and their names at run-time.
Finally, one can define for each field
being accumulated the specific accumulation action. Currently,
there are two options: Time Averaging and Time Summation. The
user chooses the specific action by setting an integer action
flag for each attribute being accumulated. The supported options
are defined by the public data member constants MCT_SUM and
MCT_AVG.
This module also supports a simple usage of accumulator where all
the actions are SUM (inits_ and initavs_) and the user
must call average_ to calculate the average from the current
value of Accumulator%steps_done. Accumulator%num_steps
is ignored in this case.
INTERFACE:
module m_AccumulatorUSES:
use m_List, only : List use m_AttrVect, only : AttrVect use m_realkinds,only : SP,DP,FP implicit none private ! exceptPUBLIC TYPES:
public :: Accumulator ! The class data structure Type Accumulator #ifdef SEQUENCE sequence #endif integer :: num_steps ! total number of accumulation steps integer :: steps_done ! number of accumulation steps performed integer, pointer, dimension(:) :: iAction ! index of integer actions integer, pointer, dimension(:) :: rAction ! index of real actions type(AttrVect) :: data ! accumulated sum field storage End Type AccumulatorPUBLIC MEMBER FUNCTIONS:
public :: init ! creation method public :: initp ! partial creation method (MCT USE ONLY) public :: clean ! destruction method public :: initialized ! check if initialized public :: lsize ! local length of the data arrays public :: NumSteps ! number of steps in a cycle public :: StepsDone ! number of steps completed in the ! current cycle public :: nIAttr ! number of integer fields public :: nRAttr ! number of real fields public :: indexIA ! index the integer fields public :: indexRA ! index the real fields public :: getIList ! Return tag from INTEGER ! attribute list public :: getRList ! Return tag from REAL attribute ! list public :: exportIAttr ! Return INTEGER attribute as a vector public :: exportRAttr ! Return REAL attribute as a vector public :: importIAttr ! Insert INTEGER vector as attribute public :: importRAttr ! Insert REAL vector as attribute public :: zero ! Clear an accumulator public :: SharedAttrIndexList ! Returns the number of shared ! attributes, and lists of the ! respective locations of these ! shared attributes public :: accumulate ! Add AttrVect data into an Accumulator public :: average ! Calculate an average in an Accumulator Definition of interfaces for the methods for the Accumulator: interface init ; module procedure & init_, & inits_, & initv_, & initavs_ end interface interface initp ; module procedure initp_ ; end interface interface clean ; module procedure clean_ ; end interface interface initialized; module procedure initialized_ ; end interface interface lsize ; module procedure lsize_ ; end interface interface NumSteps ; module procedure NumSteps_ ; end interface interface StepsDone ; module procedure StepsDone_ ; end interface interface nIAttr ; module procedure nIAttr_ ; end interface interface nRAttr ; module procedure nRAttr_ ; end interface interface indexIA; module procedure indexIA_; end interface interface indexRA; module procedure indexRA_; end interface interface getIList; module procedure getIList_; end interface interface getRList; module procedure getRList_; end interface interface exportIAttr ; module procedure exportIAttr_ ; end interface interface exportRAttr ; module procedure & exportRAttrSP_, & exportRAttrDP_ end interface interface importIAttr ; module procedure importIAttr_ ; end interface interface importRAttr ; module procedure & importRAttrSP_, & importRAttrDP_ end interface interface zero ; module procedure zero_ ; end interface interface SharedAttrIndexList ; module procedure & aCaCSharedAttrIndexList_, & aVaCSharedAttrIndexList_ end interface interface accumulate ; module procedure accumulate_ ; end interface interface average ; module procedure average_ ; end interfacePUBLIC DATA MEMBERS:
public :: MCT_SUM public :: MCT_AVG integer, parameter :: MCT_SUM = 1 integer, parameter :: MCT_AVG = 2REVISION HISTORY:
7Sep00 - Jay Larson <[email protected]> - initial prototype 7Feb01 - Jay Larson <[email protected]> - Public interfaces to getIList() and getRList(). 9Aug01 - E.T. Ong <[email protected]> - added initialized and initp_ routines. Added 'action' in Accumulator type. 6May02 - Jay Larson <[email protected]> - added import/export routines. 26Aug02 - E.T. Ong <[email protected]> - thourough code revision; no added routines 10Jan08 - R. Jacob <[email protected]> - add simple accumulator use support and check documentation.
This routine allocates space for the output Accumulator argument aC, and at a minimum sets the number of time steps in an accumulation cycle (defined by the input INTEGER argument num_steps), and the length of the Accumulator register buffer (defined by the input INTEGER argument lsize). If one wishes to accumulate integer fields, the list of these fields is defined by the input CHARACTER argument iList, which is specified as a colon-delimited set of substrings (further information regarding this is available in the routine init_() of the module m_AttrVect). If no value of iList is supplied, no integer attribute accumulation buffers will be allocated. The accumulation action on each of the integer attributes can be defined by supplying the input INTEGER array argument iAction(:) (whose length must correspond to the number of items in iList). The values of the elements of iAction(:) must be one of the values among the public data members defined in the declaration section of this module. If the integer attributes are to be accumulated (i.e. one supplies iList), but iAction(:) is not specified, the default action for all integer accumulation operations will be summation. The input arguments rList and rAction(:) define the names of the real variables to be accumulated and the accumulation action for each. The arguments rList and rAction(:) are related to each other the same way as iList and iAction(:). Finally, the user can manually set the number of completed steps in an accumulation cycle (e.g. for restart purposes) by supplying a value for the optional input INTEGER argument steps_done.
INTERFACE:
subroutine init_(aC, iList, iAction, rList, rAction, lsize, & num_steps,steps_done)USES:
use m_AttrVect, only : AttrVect_init => init use m_AttrVect, only : AttrVect_zero => zero use m_List, only: List use m_List, only: List_nullify => nullify use m_List, only: List_init => init use m_List, only: List_nitem => nitem use m_List, only: List_clean => clean use m_stdio use m_die implicit noneINPUT PARAMETERS:
character(len=*), optional, intent(in) :: iList integer, dimension(:), optional, intent(in) :: iAction character(len=*), optional, intent(in) :: rList integer, dimension(:), optional, intent(in) :: rAction integer, intent(in) :: lsize integer, intent(in) :: num_steps integer, optional, intent(in) :: steps_doneOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: aCREVISION HISTORY:
11Sep00 - Jay Larson <[email protected]> - initial prototype 27JUL01 - E.T. Ong <[email protected]> - added iAction, rAction, niAction, and nrAction to accumulator type. Also defined MCT_SUM and MCT_AVG for accumulator module.
This routine allocates space for the output simple Accumulator argument aC, and sets the length of the Accumulator register buffer (defined by the input INTEGER argument lsize). If one wishes to accumulate integer fields, the list of these fields is defined by the input CHARACTER argument iList, which is specified as a colon-delimited set of substrings (further information regarding this is available in the routine init_() of the module m_AttrVect). If no value of iList is supplied, no integer attribute accumulation buffers will be allocated. The input argument rList define the names of the real variables to be accumulated. Finally, the user can manually set the number of completed steps in an accumulation cycle (e.g. for restart purposes) by supplying a value for the optional input INTEGER argument steps_done. Its default value is zero.
In a simple accumulator, the action is always SUM.
INTERFACE:
subroutine inits_(aC, iList, rList, lsize,steps_done)USES:
use m_List, only : List_init => init use m_List, only : List_clean => clean use m_List, only : List_nitem => nitem use m_AttrVect, only : AttrVect_init => init use m_AttrVect, only : AttrVect_zero => zero use m_die implicit noneINPUT PARAMETERS:
character(len=*), optional, intent(in) :: iList character(len=*), optional, intent(in) :: rList integer, intent(in) :: lsize integer, optional, intent(in) :: steps_doneOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: aCREVISION HISTORY:
10Jan08 - R. Jacob <[email protected]> - initial version based on init_
This routine is an internal service routine for use by the other initialization routines in this module. It sets up some--but not all--of the components of the output Accumulator argument aC. This routine can set up the following components of aC:
INTERFACE:
subroutine initp_(aC, iAction, rAction, num_steps, steps_done)USES:
use m_die implicit noneINPUT PARAMETERS:
integer, dimension(:), optional, intent(in) :: iAction integer, dimension(:), optional, intent(in) :: rAction integer, intent(in) :: num_steps integer, optional, intent(in) :: steps_doneOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: aCREVISION HISTORY:
11Sep00 - Jay Larson <[email protected]> - initial prototype 27JUL01 - E.T. Ong <[email protected]> - added iAction, rAction, niAction, and nrAction to accumulator type. Also defined MCT_SUM and MCT_AVG for accumulator module.
This routine takes the integer and real attribute information (including accumulation action settings for each attribute) from a previously initialized Accumulator (the input argument bC), and uses it to create another Accumulator (the output argument aC). In the absence of the INTEGER input arguments lsize, num_steps, and steps_done, aC will inherit from bC its length, the number of steps in its accumulation cycle, and the number of steps completed in its present accumulation cycle, respectively.
INTERFACE:
subroutine initv_(aC, bC, lsize, num_steps, steps_done)USES:
use m_List, only : List use m_List, only : ListExportToChar => exportToChar use m_List, only : List_copy => copy use m_List, only : List_allocated => allocated use m_List, only : List_clean => clean use m_die implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: bC integer, optional, intent(in) :: lsize integer, optional, intent(in) :: num_steps integer, optional, intent(in) :: steps_doneOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: aCREVISION HISTORY:
11Sep00 - Jay Larson <[email protected]> - initial prototype 17May01 - R. Jacob <[email protected]> - change string_get to list_get 27JUL01 - E.T. Ong <[email protected]> - added iaction,raction compatibility 2Aug02 - J. Larson <[email protected]> made argument num_steps optional
This routine takes the integer and real attribute information (including from a previously initialized AttributeVector (the input argument aV), and uses it to create a simple (sum only) Accumulator (the output argument aC). In the absence of the INTEGER input argument lsize, aC will inherit from Av its length. In the absence of the optional INTEGER argument, steps_done will be set to zero.
INTERFACE:
subroutine initavs_(aC, aV, acsize, steps_done)USES:
use m_AttrVect, only: AttrVect_lsize => lsize use m_AttrVect, only: AttrVect_nIAttr => nIAttr use m_AttrVect, only: AttrVect_nRAttr => nRAttr use m_AttrVect, only: AttrVect_exIL2c => exportIListToChar use m_AttrVect, only: AttrVect_exRL2c => exportRListToChar use m_die implicit noneINPUT PARAMETERS:
type(AttrVect), intent(in) :: aV integer, optional, intent(in) :: acsize integer, optional, intent(in) :: steps_doneOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: aCREVISION HISTORY:
10Jan08 - R. Jacob <[email protected]> - initial version based on initv_
This routine deallocates all allocated memory structures associated with the input/output Accumulator argument aC. The success (failure) of this operation is signified by the zero (non-zero) value of the optional INTEGER output argument stat. If clean_() is invoked with stat present, it is the user's obligation to check this return code and act accordingly. If stat is not supplied and any of the deallocation operations fail, this routine will terminate execution with an error statement.
INTERFACE:
subroutine clean_(aC, stat)USES:
use m_mall use m_stdio use m_die use m_AttrVect, only : AttrVect_clean => clean implicit noneINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aCOUTPUT PARAMETERS:
integer, optional, intent(out) :: statREVISION HISTORY:
11Sep00 - Jay Larson <[email protected]> - initial prototype 27JUL01 - E.T. Ong <[email protected]> - deallocate pointers iAction and rAction. 1Mar02 - E.T. Ong <[email protected]> removed the die to prevent crashes and added stat argument.
This logical function returns a value of .TRUE. if the input Accumulator argument aC is initialized correctly. The term "correctly initialized" means there is internal consistency between the number of integer and real attributes in aC, and their respective data structures for accumulation registers, and accumulation action flags. The optional LOGICAL input argument die_flag if present, can result in messages written to stderr:
INTERFACE:
logical function initialized_(aC, die_flag, source_name)USES:
use m_stdio use m_die use m_List, only : List use m_List, only : List_allocated => allocated use m_AttrVect, only : AttrVect use m_AttrVect, only : Attr_nIAttr => nIAttr use m_AttrVect, only : Attr_nRAttr => nRAttr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aC logical, optional, intent(in) :: die_flag character(len=*), optional, intent(in) :: source_nameREVISION HISTORY:
7AUG01 - E.T. Ong <[email protected]> - initital prototype
This INTEGER query function returns the number of data points for which the input Accumulator argument aC is performing accumulation. This value corresponds to the length of the AttrVect component aC%data that stores the accumulation registers.
INTERFACE:
integer function lsize_(aC)USES:
use m_AttrVect, only : AttrVect_lsize => lsize implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aCREVISION HISTORY:
12Sep00 - Jay Larson <[email protected]> - initial prototype
This INTEGER query function returns the number of time steps in an accumulation cycle for the input Accumulator argument aC.
INTERFACE:
integer function NumSteps_(aC)USES:
use m_die, only : die use m_stdio, only : stderr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aCREVISION HISTORY:
7Aug02 - Jay Larson <[email protected]> - initial prototype
This INTEGER query function returns the of time steps that have been completed in the current accumulation cycle for the input Accumulator argument aC.
INTERFACE:
integer function StepsDone_(aC)USES:
use m_die, only : die use m_stdio, only : stderr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aCREVISION HISTORY:
7Aug02 - Jay Larson <[email protected]> - initial prototype
This INTEGER query function returns the number of integer attributes that are stored in the input Accumulator argument aC. This value is equal to the number of integer attributes in the AttrVect component aC%data that stores the accumulation registers.
INTERFACE:
integer function nIAttr_(aC)USES:
use m_AttrVect, only : AttrVect_nIAttr => nIAttr implicit noneINPUT PARAMETERS:
type(Accumulator),intent(in) :: aCREVISION HISTORY:
12Sep00 - Jay Larson <[email protected]> - initial prototype
This INTEGER query function returns the number of real attributes that are stored in the input Accumulator argument aC. This value is equal to the number of real attributes in the AttrVect component aC%data that stores the accumulation registers.
INTERFACE:
integer function nRAttr_(aC)USES:
use m_AttrVect, only : AttrVect_nRAttr => nRAttr implicit noneINPUT PARAMETERS:
type(Accumulator),intent(in) :: aCREVISION HISTORY:
12Sep00 - Jay Larson <[email protected]> - initial prototype
This routine returns as a String (see the mpeu module m_String for information) the name of the ith item in the integer registers of the Accumulator argument aC.
INTERFACE:
subroutine getIList_(item, ith, aC)USES:
use m_AttrVect, only : AttrVect_getIList => getIList use m_String, only : String implicit noneINPUT PARAMETERS:
integer, intent(in) :: ith type(Accumulator), intent(in) :: aCOUTPUT PARAMETERS:
type(String), intent(out) :: itemREVISION HISTORY:
12Sep00 - Jay Larson <[email protected]> - initial prototype
This routine returns as a String (see the mpeu module m_String for information) the name of the ith item in the real registers of the Accumulator argument aC.
INTERFACE:
subroutine getRList_(item, ith, aC)USES:
use m_AttrVect, only : AttrVect_getRList => getRList use m_String, only : String implicit noneINPUT PARAMETERS:
integer, intent(in) :: ith type(Accumulator),intent(in) :: aCOUTPUT PARAMETERS:
type(String), intent(out) :: itemREVISION HISTORY:
12Sep00 - Jay Larson <[email protected]> - initial prototype
This INTEGER query function returns the index in the integer accumulation register buffer of the Accumulator argument aC the attribute named by the CHARACTER argument item. That is, all the accumulator running tallies for the attribute named item reside in
aC%data%iAttr(indexIA_(aC,item),:).The user may request traceback information (e.g., the name of the routine from which this one is called) by providing values for either of the optional CHARACTER arguments perrWith or dieWith In the event indexIA_() can not find item in aC, the routine behaves as follows:
INTERFACE:
integer function indexIA_(aC, item, perrWith, dieWith)USES:
use m_AttrVect, only : AttrVect_indexIA => indexIA use m_die, only : die use m_stdio,only : stderr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aC character(len=*), intent(in) :: item character(len=*), optional, intent(in) :: perrWith character(len=*), optional, intent(in) :: dieWithREVISION HISTORY:
14Sep00 - Jay Larson <[email protected]> - initial prototype
This INTEGER query function returns the index in the real accumulation register buffer of the Accumulator argument aC the attribute named by the CHARACTER argument item. That is, all the accumulator running tallies for the attribute named item reside in
aC%data%rAttr(indexRA_(aC,item),:).The user may request traceback information (e.g., the name of the routine from which this one is called) by providing values for either of the optional CHARACTER arguments perrWith or dieWith In the event indexRA_() can not find item in aC, the routine behaves as follows:
INTERFACE:
integer function indexRA_(aC, item, perrWith, dieWith)USES:
use m_AttrVect, only : AttrVect_indexRA => indexRA use m_die, only : die use m_stdio,only : stderr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aC character(len=*), intent(in) :: item character(len=*), optional, intent(in) :: perrWith character(len=*), optional, intent(in) :: dieWithREVISION HISTORY:
14Sep00 - Jay Larson <[email protected]> - initial prototype
This routine extracts from the input Accumulator argument aC the integer attribute corresponding to the tag defined in the input CHARACTER argument AttrTag, and returns it in the INTEGER output array outVect, and its length in the output INTEGER argument lsize.
N.B.: This routine will fail if the AttrTag is not in the Accumulator List component aC%data%iList.
N.B.: The flexibility of this routine regarding the pointer association status of the output argument outVect means the user must invoke this routine with care. If the user wishes this routine to fill a pre-allocated array, then obviously this array must be allocated prior to calling this routine. If the user wishes that the routine create the output argument array outVect, then the user must ensure this pointer is not allocated (i.e. the user must nullify this pointer) at the time this routine is invoked.
N.B.: If the user has relied on this routine to allocate memory associated with the pointer outVect, then the user is responsible for deallocating this array once it is no longer needed. Failure to do so will result in a memory leak.
INTERFACE:
subroutine exportIAttr_(aC, AttrTag, outVect, lsize)USES:
use m_die use m_stdio use m_AttrVect, only : AttrVect_exportIAttr => exportIAttr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aC character(len=*), intent(in) :: AttrTagOUTPUT PARAMETERS:
integer, dimension(:), pointer :: outVect integer, optional, intent(out) :: lsizeREVISION HISTORY:
6May02 - J.W. Larson <[email protected]> - initial prototype.
This routine extracts from the input Accumulator argument aC the real attribute corresponding to the tag defined in the input CHARACTER argument AttrTag, and returns it in the REAL output array outVect, and its length in the output INTEGER argument lsize.
N.B.: This routine will fail if the AttrTag is not in the Accumulator List component aC%data%iList.
N.B.: The flexibility of this routine regarding the pointer association status of the output argument outVect means the user must invoke this routine with care. If the user wishes this routine to fill a pre-allocated array, then obviously this array must be allocated prior to calling this routine. If the user wishes that the routine create the output argument array outVect, then the user must ensure this pointer is not allocated (i.e. the user must nullify this pointer) at the time this routine is invoked.
N.B.: If the user has relied on this routine to allocate memory associated with the pointer outVect, then the user is responsible for deallocating this array once it is no longer needed. Failure to do so will result in a memory leak.
INTERFACE:
subroutine exportRAttrSP_(aC, AttrTag, outVect, lsize)USES:
use m_die use m_stdio use m_AttrVect, only : AttrVect_exportRAttr => exportRAttr implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aC character(len=*), intent(in) :: AttrTagOUTPUT PARAMETERS:
real(SP), dimension(:), pointer :: outVect integer, optional, intent(out) :: lsizeREVISION HISTORY:
6May02 - J.W. Larson <[email protected]> - initial prototype.
This routine imports data provided in the input INTEGER vector inVect into the Accumulator argument aC, storing it as the integer attribute corresponding to the tag defined in the input CHARACTER argument AttrTag. The input INTEGER argument lsize is used to ensure there is sufficient space in the Accumulator to store the data.
N.B.: This routine will fail if the AttrTag is not in the Accumulator List component aC%data%rList.
INTERFACE:
subroutine importIAttr_(aC, AttrTag, inVect, lsize)USES:
use m_die use m_stdio , only : stderr use m_AttrVect, only : AttrVect_importIAttr => importIAttr implicit noneINPUT PARAMETERS:
character(len=*), intent(in) :: AttrTag integer, dimension(:), pointer :: inVect integer, intent(in) :: lsizeINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aCREVISION HISTORY:
6May02 - J.W. Larson <[email protected]> - initial prototype.
This routine imports data provided in the input REAL vector inVect into the Accumulator argument aC, storing it as the real attribute corresponding to the tag defined in the input CHARACTER argument AttrTag. The input INTEGER argument lsize is used to ensure there is sufficient space in the Accumulator to store the data.
N.B.: This routine will fail if the AttrTag is not in the Accumulator List component aC%data%rList.
INTERFACE:
subroutine importRAttrSP_(aC, AttrTag, inVect, lsize)USES:
use m_die use m_stdio , only : stderr use m_AttrVect, only : AttrVect_importRAttr => importRAttr implicit noneINPUT PARAMETERS:
character(len=*), intent(in) :: AttrTag real(SP), dimension(:), pointer :: inVect integer, intent(in) :: lsizeINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aCREVISION HISTORY:
6May02 - J.W. Larson <[email protected]> - initial prototype.
This subroutine clears the the Accumulator argument aC. This is accomplished by setting the number of completed steps in the accumulation cycle to zero, and zeroing out all of the accumlation registers.
INTERFACE:
subroutine zero_(aC)USES:
use m_AttrVect, only : AttrVect_zero => zero implicit noneINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aCREVISION HISTORY:
7Aug02 - Jay Larson <[email protected]> - initial prototype
aCaCSharedAttrIndexList_() takes a pair of user-supplied Accumulator variables aC1 and aC2, and for choice of either REAL or INTEGER attributes (as specified literally in the input CHARACTER argument attrib) returns the number of shared attributes NumShared, and arrays of indices Indices1 and Indices2 to their storage locations in aC1 and aC2, respectively.
N.B.: This routine returns two allocated arrays--Indices1(:) and Indices2(:)--which must be deallocated once the user no longer needs them. Failure to do this will create a memory leak.
INTERFACE:
subroutine aCaCSharedAttrIndexList_(aC1, aC2, attrib, NumShared, & Indices1, Indices2)USES:
use m_stdio use m_die, only : MP_perr_die, die, warn use m_List, only : GetSharedListIndices implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: aC1 type(Accumulator), intent(in) :: aC2 character*7, intent(in) :: attribOUTPUT PARAMETERS:
integer, intent(out) :: NumShared integer,dimension(:), pointer :: Indices1 integer,dimension(:), pointer :: Indices2REVISION HISTORY:
7Feb01 - J.W. Larson <[email protected]> - initial version
aVaCSharedAttrIndexList_() a user-supplied AttrVect variable aV and an Accumulator variable aC, and for choice of either REAL or INTEGER attributes (as ! specified literally in the input CHARACTER argument attrib) returns the number of shared attributes NumShared, and arrays of indices Indices1 and Indices2 to their storage locations in aV and aC, respectively.
N.B.: This routine returns two allocated arrays--Indices1(:) and Indices2(:)--which must be deallocated once the user no longer needs them. Failure to do this will create a memory leak.
INTERFACE:
subroutine aVaCSharedAttrIndexList_(aV, aC, attrib, NumShared, & Indices1, Indices2)USES:
use m_stdio use m_die, only : MP_perr_die, die, warn use m_AttrVect, only : AttrVect use m_List, only : GetSharedListIndices implicit noneINPUT PARAMETERS:
type(AttrVect), intent(in) :: aV type(Accumulator), intent(in) :: aC character(len=*), intent(in) :: attribOUTPUT PARAMETERS:
integer, intent(out) :: NumShared integer,dimension(:), pointer :: Indices1 integer,dimension(:), pointer :: Indices2REVISION HISTORY:
7Feb01 - J.W. Larson <[email protected]> - initial version
This routine performs time accumlation of data present in an MCT field data AttrVect variable aV and combines it with the running tallies stored in the MCT Accumulator variable aC. This routine automatically identifies which fields are held in common by aV and aC and uses the accumulation action information stored in aC to decide how each field in aV is to be combined into its corresponding running tally in aC. The accumulation operations currently supported are:
This routine also automatically increments the counter in aC signifying the number of steps completed in the accumulation cycle.
NOTE: The user must reset (zero) the Accumulator after the average has been formed or the next call to accumulate will add to the average.
INTERFACE:
subroutine accumulate_(aV, aC)USES:
use m_stdio, only : stdout,stderr use m_die, only : die use m_AttrVect, only : AttrVect use m_AttrVect, only : AttrVect_lsize => lsize use m_AttrVect, only : AttrVect_nIAttr => nIAttr use m_AttrVect, only : AttrVect_nRAttr => nRAttr use m_AttrVect, only : AttrVect_indexRA => indexRA use m_AttrVect, only : AttrVect_indexIA => indexIA implicit noneINPUT PARAMETERS:
type(AttrVect), intent(in) :: aV ! Input AttrVectINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aC ! Output AccumulatorREVISION HISTORY:
18Sep00 - J.W. Larson <[email protected]> -- initial version. 7Feb01 - J.W. Larson <[email protected]> -- General version. 10Jun01 - E.T. Ong -- fixed divide-by-zero problem in integer attribute accumulation. 27Jul01 - E.T. Ong <[email protected]> -- removed action argument. Make compatible with new Accumulator type.
This routine will compute the average of the current values in an Accumulator using the current value of steps_done in the Accumulator
INTERFACE:
subroutine average_(aC)USES:
use m_stdio, only : stdout,stderr use m_die, only : die use m_AttrVect, only : AttrVect use m_AttrVect, only : AttrVect_lsize => lsize use m_AttrVect, only : AttrVect_nIAttr => nIAttr use m_AttrVect, only : AttrVect_nRAttr => nRAttr use m_AttrVect, only : AttrVect_indexRA => indexRA use m_AttrVect, only : AttrVect_indexIA => indexIA implicit noneINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aC ! Output AccumulatorREVISION HISTORY:
11Jan08 - R.Jacob <[email protected]> -- initial version based on accumulate_
This module contains communications methods for the Accumulator datatype (see m_Accumulator for details). MCT's communications are implemented in terms of the Message Passing Interface (MPI) standard, and we have as best as possible, made the interfaces to these routines appear as similar as possible to the corresponding MPI routines. For the Accumulator, we currently support only the following collective operations: broadcast, gather, and scatter. The gather and scatter operations rely on domain decomposition descriptors that are defined elsewhere in MCT: the GlobalMap, which is a one-dimensional decomposition (see the MCT module m_GlobalMap for more details); and the GlobalSegMap, which is a segmented decomposition capable of supporting multidimensional domain decompositions (see the MCT module m_GlobalSegMap for more details).
INTERFACE:
module m_AccumulatorCommsUSES:
No external modules are used in the declaration section of this module. implicit none private ! exceptPUBLIC MEMBER FUNCTIONS:
List of communications Methods for the Accumulator class public :: gather ! gather all local vectors to the root public :: scatter ! scatter from the root to all PEs public :: bcast ! bcast from root to all PEs Definition of interfaces for the communication methods for the Accumulator: interface gather ; module procedure & GM_gather_, & GSM_gather_ end interface interface scatter ; module procedure & GM_scatter_, & GSM_scatter_ end interface interface bcast ; module procedure bcast_ ; end interfaceREVISION HISTORY:
31Oct00 - Jay Larson <[email protected]> - initial prototype-- These routines were separated from the module m_Accumulator 15Jan01 - Jay Larson <[email protected]> - Specification of APIs for the routines GSM_gather_() and GSM_scatter_(). 10May01 - Jay Larson <[email protected]> - Changes in the comms routine to match the MPI model for collective communications, and general clean-up of prologues. 9Aug01 - E.T. Ong <[email protected]> - Added private routine bcastp_. Used new Accumulator routines initp_ and initialized_ to simplify the routines. 26Aug02 - E.T. Ong <[email protected]> - thourough code revision; no added routines
GM_gather() takes a distributed (across the communicator associated with the handle comm) input Accumulator argument iC and gathers its data to the Accumulator oC on the root. The decomposition of iC is described by the input GlobalMap argument Gmap. The success (failure) of this operation is signified by the zero (nonzero) value of the optional output argument stat.
INTERFACE:
subroutine GM_gather_(iC, oC, GMap, root, comm, stat)USES:
use m_stdio use m_die use m_mpif90 use m_GlobalMap, only : GlobalMap use m_AttrVect, only : AttrVect_clean => clean use m_Accumulator, only : Accumulator use m_Accumulator, only : Accumulator_initialized => initialized use m_Accumulator, only : Accumulator_initv => init use m_AttrVectComms, only : AttrVect_gather => gather implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: iC type(GlobalMap) , intent(in) :: GMap integer, intent(in) :: root integer, intent(in) :: commOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: oC integer, optional,intent(out) :: statREVISION HISTORY:
13Sep00 - Jay Larson <[email protected]> - initial prototype 31Oct00 - Jay Larson <[email protected]> - relocated to the module m_AccumulatorComms 15Jan01 - Jay Larson <[email protected]> - renamed GM_gather_ 10May01 - Jay Larson <[email protected]> - revamped comms model to match MPI comms model, and cleaned up prologue 9Aug01 - E.T. Ong <[email protected]> - 2nd prototype. Used the intiialized_ and accumulator init routines.
This routine takes the distrubuted (on the communcator associated with the handle comm) input Accumulator argument iC gathers it to the the Accumulator argument oC (valid only on the root). The decompositon of iC is contained in the input GlobalSegMap argument GSMap. The success (failure) of this operation is signified by the zero (nonzero) returned value of the INTEGER flag stat.
INTERFACE:
subroutine GSM_gather_(iC, oC, GSMap, root, comm, stat)USES:
use m_stdio use m_die use m_mpif90 use m_GlobalSegMap, only : GlobalSegMap use m_AttrVect, only : AttrVect_clean => clean use m_Accumulator, only : Accumulator use m_Accumulator, only : Accumulator_initv => init use m_Accumulator, only : Accumulator_initialized => initialized use m_AttrVectComms, only : AttrVect_gather => gather implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: iC type(GlobalSegMap), intent(in) :: GSMap integer, intent(in) :: root integer, intent(in) :: commOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: oC integer, optional, intent(out) :: statREVISION HISTORY:
15Jan01 - Jay Larson <[email protected]> - API specification. 10May01 - Jay Larson <[email protected]> - Initial code and cleaned up prologue. 09Aug01 - E.T. Ong <[email protected]> - 2nd prototype. Used the intiialized_ and accumulator init routines.
This routine takes the input Accumulator argument iC (valid only on the root), and scatters it to the distributed Accumulator argument oC on the processes associated with the communicator handle comm. The decompositon used to scatter the data is contained in the input GlobalMap argument GMap. The success (failure) of this operation is signified by the zero (nonzero) returned value of the INTEGER flag stat.
INTERFACE:
subroutine GM_scatter_(iC, oC, GMap, root, comm, stat)USES:
use m_stdio use m_die use m_mpif90 use m_GlobalMap, only : GlobalMap use m_Accumulator, only : Accumulator use m_Accumulator, only : Accumulator_initv => init use m_Accumulator, only : Accumulator_initialized => initialized use m_AttrVect, only : AttrVect_clean => clean use m_AttrVectComms, only : AttrVect_scatter => scatter implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: iC type(GlobalMap), intent(in) :: GMap integer, intent(in) :: root integer, intent(in) :: commOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: oC integer, optional, intent(out) :: statREVISION HISTORY:
14Sep00 - Jay Larson <[email protected]> - initial prototype 31Oct00 - Jay Larson <[email protected]> - moved from the module m_Accumulator to m_AccumulatorComms 15Jan01 - Jay Larson <[email protected]> - renamed GM_scatter_. 10May01 - Jay Larson <[email protected]> - revamped code to fit MPI-like comms model, and cleaned up prologue. 09Aug01 - E.T. Ong <[email protected]> - 2nd prototype. Used the initialized_, Accumulator init_, and bcastp_ routines.
This routine takes the input Accumulator argument iC (valid only on the root), and scatters it to the distributed Accumulator argument oC on the processes associated with the communicator handle comm. The decompositon used to scatter the data is contained in the input GlobalSegMap argument GSMap. The success (failure) of this operation is signified by the zero (nonzero) returned value of the INTEGER flag stat.
INTERFACE:
subroutine GSM_scatter_(iC, oC, GSMap, root, comm, stat)USES:
use m_stdio use m_die use m_mpif90 use m_GlobalSegMap, only : GlobalSegMap use m_Accumulator, only : Accumulator use m_Accumulator, only : Accumulator_initv => init use m_Accumulator, only : Accumulator_initialized => initialized use m_AttrVect, only : AttrVect_clean => clean use m_AttrVectComms, only : AttrVect_scatter => scatter implicit noneINPUT PARAMETERS:
type(Accumulator), intent(in) :: iC type(GlobalSegMap), intent(in) :: GSMap integer, intent(in) :: root integer, intent(in) :: commOUTPUT PARAMETERS:
type(Accumulator), intent(out) :: oC integer, optional, intent(out) :: statREVISION HISTORY:
15Jan01 - Jay Larson <[email protected]> - API specification. 10May01 - Jay Larson <[email protected]> - Initial code/prologue 09Aug01 - E.T. Ong <[email protected]> 2nd prototype. Used the initialized and accumulator init routines.
This routine takes the input Accumulator argument aC (on input valid only on the root), and broadcasts it to all the processes associated with the communicator handle comm. The success (failure) of this operation is signified by the zero (nonzero) returned value of the INTEGER flag stat.
INTERFACE:
subroutine bcast_(aC, root, comm, stat)USES:
use m_die use m_mpif90 use m_AttrVectComms, only : AttrVect_bcast => bcast use m_Accumulator, only : Accumulator use m_Accumulator, only : Accumulator_initialized => initialized implicit noneINPUT PARAMETERS:
integer,intent(in) :: root integer,intent(in) :: commINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aC ! (IN) on root, (OUT) elsewhereOUTPUT PARAMETERS:
integer, optional, intent(out) :: statREVISION HISTORY:
14Sep00 - Jay Larson <[email protected]> - initial prototype 31Oct00 - Jay Larson <[email protected]> - moved from the module m_Accumulator to m_AccumulatorComms 09May01 - Jay Larson <[email protected]> - cleaned up prologue 09Aug01 - E.T. Ong <[email protected]> - 2nd prototype. Made use of bcastp_ routine. Also more argument checks.
This routine broadcasts all components of the accumulator aC except for aCto be used by accumulator scatter and gather routines.
INTERFACE:
subroutine bcastp_(aC, root, comm, stat)USES:
use m_die use m_mpif90 use m_AttrVectComms, only : AttrVect_bcast => bcast use m_Accumulator, only : Accumulator use m_Accumulator, only : Accumulator_initp => initp use m_Accumulator, only : Accumulator_nIAttr => nIAttr use m_Accumulator, only : Accumulator_nRAttr => nRAttr implicit noneINPUT PARAMETERS:
integer,intent(in) :: root integer,intent(in) :: commINPUT/OUTPUT PARAMETERS:
type(Accumulator), intent(inout) :: aC ! (IN) on root, (OUT) elsewhereOUTPUT PARAMETERS:
integer, optional, intent(out) :: statREVISION HISTORY:
09Aug01 - E.T. Ong <[email protected]> - initial prototype