subroutine ESMF_FieldRegrid(srcField, dstField, routehandle, keywordEnforcer, &
zeroregion, termorderflag, checkflag, dynamicMask, 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
type(ESMF_DynamicMask), target, intent(in), optional :: dynamicMask
integer, intent(out), optional :: rc
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{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.
! \item[7.1.0r] Added argument {\tt dynamicMask}.
! The new argument supports the dynamic masking feature.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
! Execute the precomputed regrid operation stored in {\tt routehandle} to
! interpolate from {\tt srcField} to {\tt dstField}. See {\tt ESMF\_FieldRegridStore()} on how to
! precompute the {\tt routehandle}.
!
! \begin{sloppypar}
! Both {\tt srcField} and {\tt dstField} must match the respective Fields
! used during {\tt ESMF\_FieldRegridStore()} 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.
!
! This call is {\em collective} across the current VM.
!
! \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 Array 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 setting depends on whether the {\tt dynamicMask} argument
! is present or not. With {\tt dynamicMask} argument present, the default
! of {\tt termorderflag} is {\tt ESMF\_TERMORDER\_SRCSEQ}. This ensures
! that {\tt all} source terms are present on the destination side, and
! the interpolation can be calculated as a single sum. When
! {\tt dynamicMask} is absent, the default of {\tt termorderflag} is
! {\tt ESMF\_TERMORDER\_FREE}, allowing maximum flexibility and partial
! sums for optimum performance.
! \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 [{[dynamicMask]}]
! Object holding dynamic masking information.
! See section \ref{RH:DynMask} for a discussion of dynamic masking.
! \item [{[rc]}]
! Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
! \end{description}
!EOP
integer :: localrc
type(ESMF_Array) :: srcArray
type(ESMF_Array) :: dstArray
! Initialize return code; assume failure until success is certain
localrc = ESMF_SUCCESS
if (present(rc)) rc = ESMF_RC_NOT_IMPL
! Now we go through the painful process of extracting the data members
! that we need, if present.
if (present(srcField)) then
call ESMF_FieldGet(srcField, array=srcArray, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
endif
if (present(dstField)) then
call ESMF_FieldGet(dstField, array=dstArray, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
endif
if (present(srcField) .and. present(dstField)) then
call ESMF_ArraySMM(srcArray=srcArray, dstArray=dstArray, &
routehandle=routehandle, zeroregion=zeroregion, &
termorderflag=termorderflag, checkflag=checkflag, &
dynamicMask=dynamicMask, rc=localrc)
else if (present(srcField) .and. .not. present(dstField)) then
call ESMF_ArraySMM(srcArray=srcArray, &
routehandle=routehandle, zeroregion=zeroregion, &
termorderflag=termorderflag, checkflag=checkflag, &
dynamicMask=dynamicMask, rc=localrc)
else if (.not. present(srcField) .and. present(dstField)) then
call ESMF_ArraySMM(dstArray=dstArray, &
routehandle=routehandle, zeroregion=zeroregion, &
termorderflag=termorderflag, checkflag=checkflag, &
dynamicMask=dynamicMask, rc=localrc)
else if (.not. present(srcField) .and. .not. present(dstField)) then
call ESMF_ArraySMM(routehandle=routehandle, zeroregion=zeroregion, &
termorderflag=termorderflag, checkflag=checkflag, &
dynamicMask=dynamicMask, rc=localrc)
else
call ESMF_LogSetError(rcToCheck=ESMF_RC_ARG_WRONG, &
msg="Supplied combination of optional Fields not supported", &
ESMF_CONTEXT, rcToReturn=rc)
return
endif
if (ESMF_LogFoundError(localrc, &
ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! Once the compilation order is sorted out,
! Should be able to call into Field SMM directly.
!call ESMF_FieldSMM(srcField=srcField, dstField=dstField, &
! routehandle=routehandle, zeroregion=zeroregion, &
! checkflag=checkflag, rc=localrc)
!if (ESMF_LogFoundError(localrc, &
! ESMF_ERR_PASSTHRU, &
! ESMF_CONTEXT, rcToReturn=rc)) return
if(present(rc)) rc = ESMF_SUCCESS
end subroutine ESMF_FieldRegrid