subroutine ESMF_FieldSMMStoreNF(srcField, dstField, &
routehandle, keywordEnforcer, ignoreUnmatchedIndices, &
srcTermProcessing, pipelineDepth, rc)
!
! !ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
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 arguments {\tt srcTermProcessing}, {\tt pipelineDepth}
! The two arguments {\tt srcTermProcessing} and {\tt pipelineDepth}
! provide access to the tuning parameters affecting the sparse matrix
! execution.
! \item[7.0.0] Added argument {\tt transposeRoutehandle} to allow a handle to
! the transposed matrix operation to be returned.\newline
! Added argument {\tt ignoreUnmatchedIndices} to support sparse
! matrices that contain elements with indices that do not have a
! match within the source or destination Array.
! \item[7.1.0r] Removed argument {\tt transposeRoutehandle} and provide it
! via interface overloading instead. This allows argument
! {\tt srcField} to stay strictly intent(in) for this entry point.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
!
! \begin{sloppypar}
! Store a Field sparse matrix multiplication operation from {\tt srcField}
! to {\tt dstField}. PETs that specify non-zero matrix coefficients must use
! the <type><kind> overloaded interface and provide the {\tt factorList} and
! {\tt factorIndexList} arguments. Providing {\tt factorList} and
! {\tt factorIndexList} arguments with {\tt size(factorList) = (/0/)} and
! {\tt size(factorIndexList) = (/2,0/)} or {\tt (/4,0/)} indicates that a
! PET does not provide matrix elements. Alternatively, PETs that do not
! provide matrix elements may also call into the overloaded interface
! {\em without} {\tt factorList} and {\tt factorIndexList} arguments.
! \end{sloppypar}
!
! Both {\tt srcField} and {\tt dstField} are interpreted as sequentialized
! vectors. The
! sequence is defined by the order of DistGrid dimensions and the order of
! tiles within the DistGrid or by user-supplied arbitrary sequence indices. See
! section \ref{Array:SparseMatMul} for details on the definition of {\em sequence indices}.
! SMM corresponds to an identity mapping of the source Field vector to
! the destination Field vector.
!
! Source and destination Fields may be of different <type><kind>. Further source
! and destination Fields may differ in shape, however, the number of elements
! must match.
!
! It is erroneous to specify the identical Field object for srcField and dstField
! arguments.
!
! The routine returns an {\tt ESMF\_RouteHandle} that can be used to call
! {\tt ESMF\_FieldSMM()} on any pair of Fields that matches
! {\tt srcField} and {\tt dstField} 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.
!
! This method is overloaded for:\newline
! {\tt ESMF\_TYPEKIND\_I4}, {\tt ESMF\_TYPEKIND\_I8},\newline
! {\tt ESMF\_TYPEKIND\_R4}, {\tt ESMF\_TYPEKIND\_R8}.
! \newline
!
! This call is collective across the current VM.
!
! For examples and associated documentation regarding this method see Section
! \ref{sec:field:usage:smm_1dptr}.
!
! The arguments are:
!
! \begin{description}
!
! \item [srcField]
! {\tt ESMF\_Field} with source data.
!
! \item [dstField]
! {\tt ESMF\_Field} with destination data. The data in this Field may be
! destroyed by this call.
!
! \item [routehandle]
! Handle to the precomputed Route.
!
! \item [{[ignoreUnmatchedIndices]}]
! A logical flag that affects the behavior for when sequence indices
! in the sparse matrix are encountered that do not have a match on the
! {\tt srcField} or {\tt dstField} side. The default setting is
! {\tt .false.}, indicating that it is an error when such a situation is
! encountered. Setting {\tt ignoreUnmatchedIndices} to {\tt .true.} ignores
! entries with unmatched indices.
!
! \item [{[srcTermProcessing]}]
! The {\tt srcTermProcessing} parameter controls how many source terms,
! located on the same PET and summing into the same destination element,
! are summed into partial sums on the source PET before being transferred
! to the destination PET. A value of 0 indicates that the entire arithmetic
! is done on the destination PET; source elements are neither multiplied
! by their factors nor added into partial sums before being sent off by the
! source PET. A value of 1 indicates that source elements are multiplied
! by their factors on the source side before being sent to the destination
! PET. Larger values of {\tt srcTermProcessing} indicate the maximum number
! of terms in the partial sums on the source side.
!
! Note that partial sums may lead to bit-for-bit differences in the results.
! See section \ref{RH:bfb} for an in-depth discussion of {\em all}
! bit-for-bit reproducibility aspects related to route-based communication
! methods.
!
! \begin{sloppypar}
! The {\tt ESMF\_FieldSMMStore()} method implements an auto-tuning scheme
! for the {\tt srcTermProcessing} parameter. The intent on the
! {\tt srcTermProcessing} argument is "{\tt inout}" in order to
! support both overriding and accessing the auto-tuning parameter.
! If an argument $>= 0$ is specified, it is used for the
! {\tt srcTermProcessing} parameter, and the auto-tuning phase is skipped.
! In this case the {\tt srcTermProcessing} argument is not modified on
! return. If the provided argument is $< 0$, the {\tt srcTermProcessing}
! parameter is determined internally using the auto-tuning scheme. In this
! case the {\tt srcTermProcessing} argument is re-set to the internally
! determined value on return. Auto-tuning is also used if the optional
! {\tt srcTermProcessing} argument is omitted.
! \end{sloppypar}
!
! \item [{[pipelineDepth]}]
! The {\tt pipelineDepth} parameter controls how many messages a PET
! may have outstanding during a sparse matrix exchange. Larger values
! of {\tt pipelineDepth} typically lead to better performance. However,
! on some systems too large a value may lead to performance degradation,
! or runtime errors.
!
! Note that the pipeline depth has no effect on the bit-for-bit
! reproducibility of the results. However, it may affect the performance
! reproducibility of the exchange.
!
! The {\tt ESMF\_FieldSMMStore()} method implements an auto-tuning scheme
! for the {\tt pipelineDepth} parameter. The intent on the
! {\tt pipelineDepth} argument is "{\tt inout}" in order to
! support both overriding and accessing the auto-tuning parameter.
! If an argument $>= 0$ is specified, it is used for the
! {\tt pipelineDepth} parameter, and the auto-tuning phase is skipped.
! In this case the {\tt pipelineDepth} argument is not modified on
! return. If the provided argument is $< 0$, the {\tt pipelineDepth}
! parameter is determined internally using the auto-tuning scheme. In this
! case the {\tt pipelineDepth} argument is re-set to the internally
! determined value on return. Auto-tuning is also used if the optional
! {\tt pipelineDepth} argument is omitted.
!
! \item [{[rc]}]
! Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!
! \end{description}
!
!EOP
!----------------------------------------------------------------------------
! local variables as temporary input/output arguments
! internal local variables
integer :: localrc
type(ESMF_Array) :: srcArray, dstArray
! Initialize return code; assume routine not implemented
localrc = ESMF_RC_NOT_IMPL
if(present(rc)) rc = ESMF_RC_NOT_IMPL
! check variable: focus on field and farray
! rely on ArraySMM to check the sanity of other variables
ESMF_INIT_CHECK_DEEP(ESMF_FieldGetInit, srcField, rc)
ESMF_INIT_CHECK_DEEP(ESMF_FieldGetInit, dstField, rc)
! Retrieve source and destination arrays.
call ESMF_FieldGet(srcField, array=srcArray, rc=localrc)
if (ESMF_LogFoundError(localrc, &
ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_FieldGet(dstField, array=dstArray, rc=localrc)
if (ESMF_LogFoundError(localrc, &
ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! perform sparse matrix multiplication through array
! For performance consideration:
! Rely on ArraySMM to perform sanity checking of the other parameters
call ESMF_ArraySMMStore(srcArray=srcArray, dstArray=dstArray, &
routehandle=routehandle, &
ignoreUnmatchedIndices=ignoreUnmatchedIndices, &
srcTermProcessing=srcTermProcessing, pipelineDepth=pipelineDepth, &
rc=localrc)
if (ESMF_LogFoundError(localrc, &
ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
if (present(rc)) rc = ESMF_SUCCESS
end subroutine ESMF_FieldSMMStoreNF