subroutine ESMF_ArrayRedist(srcArray, dstArray, routehandle, keywordEnforcer, &
routesyncflag, finishedflag, cancelledflag, zeroregion, checkflag, rc)
!
! !ARGUMENTS:
type(ESMF_Array), intent(in), optional :: srcArray
type(ESMF_Array), intent(inout), optional :: dstArray
type(ESMF_RouteHandle), intent(inout) :: routehandle
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
type(ESMF_RouteSync_Flag), intent(in), optional :: routesyncflag
logical, intent(out), optional :: finishedflag
logical, intent(out), optional :: cancelledflag
type(ESMF_Region_Flag), intent(in), optional :: zeroregion
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{5.2.0r}
! \begin{description}
! \item[7.1.0r] Added argument {\tt zeroregion} to allow user to control
! how the destination array is zero'ed out. This is especially
! useful in cases where the source and destination arrays do not
! cover the identical index space.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
! \begin{sloppypar}
! Execute a precomputed Array redistribution from {\tt srcArray}
! to {\tt dstArray}.
! Both {\tt srcArray} and {\tt dstArray} must match the respective Arrays
! used during {\tt ESMF\_ArrayRedisttore()} in {\em type}, {\em kind}, and
! memory layout of the {\em distributed} dimensions. However, the size,
! number, and index order of {\em undistributed} dimensions may be different.
! See section \ref{RH:Reusability} for a more detailed discussion of
! RouteHandle reusability.
! \end{sloppypar}
!
! The {\tt srcArray} and {\tt dstArray} arguments are optional in support of
! the situation where {\tt srcArray} and/or {\tt dstArray} are not defined on
! all PETs. The {\tt srcArray} and {\tt dstArray} must be specified on those
! PETs that hold source or destination DEs, respectively, but may be omitted
! on all other PETs. PETs that hold neither source nor destination DEs may
! omit both arguments.
!
! It is erroneous to specify the identical Array object for {\tt srcArray} and
! {\tt dstArray} arguments.
!
! See {\tt ESMF\_ArrayRedistStore()} on how to precompute
! {\tt routehandle}.
!
! This call is {\em collective} across the current VM.
!
! \begin{description}
! \item [{[srcArray]}]
! {\tt ESMF\_Array} with source data.
! \item [{[dstArray]}]
! {\tt ESMF\_Array} with destination data.
! \item [routehandle]
! Handle to the precomputed Route.
! \item [{[routesyncflag]}]
! Indicate communication option. Default is {\tt ESMF\_ROUTESYNC\_BLOCKING},
! resulting in a blocking operation.
! See section \ref{const:routesync} for a complete list of valid settings.
! \item [{[finishedflag]}]
! \begin{sloppypar}
! Used in combination with {\tt routesyncflag = ESMF\_ROUTESYNC\_NBTESTFINISH}.
! Returned {\tt finishedflag} equal to {\tt .true.} indicates that all
! operations have finished. A value of {\tt .false.} indicates that there
! are still unfinished operations that require additional calls with
! {\tt routesyncflag = ESMF\_ROUTESYNC\_NBTESTFINISH}, or a final call with
! {\tt routesyncflag = ESMF\_ROUTESYNC\_NBWAITFINISH}. For all other {\tt routesyncflag}
! settings the returned value in {\tt finishedflag} is always {\tt .true.}.
! \end{sloppypar}
! \item [{[cancelledflag]}]
! A value of {\tt .true.} indicates that were cancelled communication
! operations. In this case the data in the {\tt dstArray} must be considered
! invalid. It may have been partially modified by the call. A value of
! {\tt .false.} indicates that none of the communication operations was
! cancelled. The data in {\tt dstArray} is valid if {\tt finishedflag}
! returns equal {\tt .true.}.
! \item [{[zeroregion]}]
! \begin{sloppypar}
! If set to {\tt ESMF\_REGION\_TOTAL} the total regions of
! all DEs in {\tt dstArray} will be initialized to zero before updating the
! elements with the results of the sparse matrix multiplication. If set to
! {\tt ESMF\_REGION\_EMPTY} the elements in {\tt dstArray} will not be
! modified prior to the sparse matrix multiplication and results will be
! added to the incoming element values. Setting {\tt zeroregion} to
! {\tt ESMF\_REGION\_SELECT} will only zero out those elements in the
! destination Array that will be updated by the sparse matrix
! multiplication. See section \ref{const:region} for a complete list of
! valid settings. The default is {\tt ESMF\_REGION\_SELECT}.
! \end{sloppypar}
! \item [{[checkflag]}]
! If set to {\tt .TRUE.} the input Array pair will be checked for
! consistency with the precomputed operation provided by {\tt routehandle}.
! If set to {\tt .FALSE.} {\em (default)} only a very basic input check
! will be performed, leaving many inconsistencies undetected. Set
! {\tt checkflag} to {\tt .FALSE.} to achieve highest performance.
! \item [{[rc]}]
! Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
! \end{description}
!
!EOP
!------------------------------------------------------------------------------
integer :: localrc ! local return code
type(ESMF_Array) :: opt_srcArray ! helper variable
type(ESMF_Array) :: opt_dstArray ! helper variable
type(ESMF_RouteSync_Flag) :: opt_routesyncflag ! helper variable
type(ESMF_Logical) :: opt_finishedflag ! helper variable
type(ESMF_Logical) :: opt_cancelledflag ! helper variable
type(ESMF_Region_Flag) :: opt_zeroregion ! helper variable
type(ESMF_Logical) :: opt_checkflag ! helper variable
type(ESMF_Pointer) :: this
! initialize return code; assume routine not implemented
localrc = ESMF_RC_NOT_IMPL
if (present(rc)) rc = ESMF_RC_NOT_IMPL
! Check init status of arguments, deal with optional Array args
ESMF_INIT_CHECK_DEEP(ESMF_RouteHandleGetInit, routehandle, rc)
if (present(srcArray)) then
call ESMF_ArrayGetThis(srcArray, this, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
if (this /= ESMF_NULL_POINTER) then
ESMF_INIT_CHECK_DEEP(ESMF_ArrayGetInit, srcArray, rc)
endif
opt_srcArray = srcArray
else
call ESMF_ArraySetThisNull(opt_srcArray, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
endif
if (present(dstArray)) then
call ESMF_ArrayGetThis(dstArray, this, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
if (this /= ESMF_NULL_POINTER) then
ESMF_INIT_CHECK_DEEP(ESMF_ArrayGetInit, dstArray, rc)
endif
opt_dstArray = dstArray
else
call ESMF_ArraySetThisNull(opt_dstArray, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
endif
! Set default flags
opt_routesyncflag = ESMF_ROUTESYNC_BLOCKING
if (present(routesyncflag)) opt_routesyncflag = routesyncflag
opt_zeroregion = ESMF_REGION_SELECT
if (present(zeroregion)) opt_zeroregion = zeroregion
opt_checkflag = ESMF_FALSE
if (present(checkflag)) opt_checkflag = checkflag
! Call into the C++ interface, which will sort out optional arguments
call c_ESMC_ArrayRedist(opt_srcArray, opt_dstArray, routehandle, &
opt_routesyncflag, opt_finishedflag, opt_cancelledflag, opt_zeroregion, &
opt_checkflag, localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! translate back finishedflag
if (present(finishedflag)) then
finishedflag = opt_finishedflag
endif
! translate back cancelledflag
if (present(cancelledflag)) then
cancelledflag = opt_cancelledflag
endif
! return successfully
if (present(rc)) rc = ESMF_SUCCESS
end subroutine ESMF_ArrayRedist