subroutine ESMF_FieldSMM(srcField, dstField, routehandle, keywordEnforcer, &
zeroregion, termorderflag, checkflag, rc)
!
! !ARGUMENTS:
type(ESMF_Field), intent(in), optional :: srcField
type(ESMF_Field), intent(inout), optional :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
type(ESMF_Region_Flag), intent(in), optional :: zeroregion
type(ESMF_TermOrder_Flag), intent(in), optional :: termorderflag
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
!
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \begin{description}
! \item[6.1.0] Added argument {\tt termorderflag}.
! The new argument gives the user control over the order in which
! the src terms are summed up.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
! \begin{sloppypar}
! Execute a precomputed Field sparse matrix multiplication from {\tt srcField} to
! {\tt dstField}.
! Both {\tt srcField} and {\tt dstField} must match the respective Fields
! used during {\tt ESMF\_FieldSMMStore()} in {\em type}, {\em kind}, and
! memory layout of the {\em gridded} dimensions. However, the size, number,
! and index order of {\em ungridded} dimensions may be different. See section
! \ref{RH:Reusability} for a more detailed discussion of RouteHandle
! reusability.
! \end{sloppypar}
!
! The {\tt srcField} and {\tt dstField} arguments are optional in support of
! the situation where {\tt srcField} and/or {\tt dstField} are not defined on
! all PETs. The {\tt srcField} and {\tt dstField} 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 Field object for {\tt srcField} and
! {\tt dstField} arguments.
!
! See {\tt ESMF\_FieldSMMStore()} on how to precompute
! {\tt routehandle}.
!
! This call is {\em collective} across the current VM.
!
! For examples and associated documentation regarding this method see Section
! \ref{sec:field:usage:smm_1dptr}.
!
! \begin{description}
! \item [{[srcField]}]
! {\tt ESMF\_Field} with source data.
! \item [{[dstField]}]
! {\tt ESMF\_Field} with destination data.
! \item [routehandle]
! Handle to the precomputed Route.
! \item [{[zeroregion]}]
! \begin{sloppypar}
! If set to {\tt ESMF\_REGION\_TOTAL} {\em (default)} the total regions of
! all DEs in {\tt dstField} 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 dstField} 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 Field that will be updated by the sparse matrix
! multiplication. See section \ref{const:region} for a complete list of
! valid settings.
! \end{sloppypar}
! \item [{[termorderflag]}]
! Specifies the order of the source side terms in all of the destination
! sums. The {\tt termorderflag} only affects the order of terms during
! the execution of the RouteHandle. See the \ref{RH:bfb} section for an
! in-depth discussion of {\em all} bit-for-bit reproducibility
! aspects related to route-based communication methods.
! See \ref{const:termorderflag} for a full list of options.
! The default is {\tt ESMF\_TERMORDER\_FREE}, allowing maximum flexibility
! in the order of terms for optimum performance.
! \item [{[checkflag]}]
! If set to {\tt .TRUE.} the input Field 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
! local variables to buffer optional arguments
type(ESMF_Array) :: l_srcArray ! helper variable
type(ESMF_Array) :: l_dstArray ! helper variable
! 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 Field args
ESMF_INIT_CHECK_DEEP(ESMF_RouteHandleGetInit, routehandle, rc)
ESMF_INIT_CHECK_DEEP(ESMF_FieldGetInit, srcField, rc)
ESMF_INIT_CHECK_DEEP(ESMF_FieldGetInit, dstField, rc)
if (present(srcField)) then
call ESMF_FieldGet(srcField, array=l_srcArray, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
else
call ESMF_ArraySetThisNull(l_srcArray, localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
endif
if (present(dstField)) then
call ESMF_FieldGet(dstField, array=l_dstArray, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
else
call ESMF_ArraySetThisNull(l_dstArray, localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
endif
! perform Field sparse matrix multiplication through internal array
call ESMF_ArraySMM(srcArray=l_srcArray, dstArray=l_dstArray, &
routehandle=routehandle, zeroregion=zeroregion, &
termorderflag=termorderflag, checkflag=checkflag, &
rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! return successfully
if (present(rc)) rc = ESMF_SUCCESS
end subroutine ESMF_FieldSMM