function ESMF_DistGridCreateRD(minIndex, maxIndex, keywordEnforcer, regDecomp, &
decompflag, regDecompFirstExtra, regDecompLastExtra, deLabelList, &
indexflag, connectionList, delayout, vm, indexTK, rc)
!
! !RETURN VALUE:
type(ESMF_DistGrid) :: ESMF_DistGridCreateRD
!
! !ARGUMENTS:
integer, intent(in) :: minIndex(:)
integer, intent(in) :: maxIndex(:)
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
integer, target, intent(in), optional :: regDecomp(:)
type(ESMF_Decomp_Flag), target, intent(in), optional :: decompflag(:)
integer, target, intent(in), optional :: regDecompFirstExtra(:)
integer, target, intent(in), optional :: regDecompLastExtra(:)
integer, target, intent(in), optional :: deLabelList(:)
type(ESMF_Index_Flag), intent(in), optional :: indexflag
type(ESMF_DistGridConnection), intent(in), optional :: connectionList(:)
type(ESMF_DELayout), intent(in), optional :: delayout
type(ESMF_VM), intent(in), optional :: vm
type(ESMF_TypeKind_Flag), intent(in), optional :: indexTK
integer, intent(out), optional :: rc
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{5.2.0r}
! \begin{description}
! \item[8.1.0] Added argument {\tt indexTK} to support explicit selection
! between 32-bit and 64-bit sequence indices.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
! Create an {\tt ESMF\_DistGrid} from a single logically rectangular tile.
! The tile has a regular decomposition, where the tile is decomposed
! into a fixed number of DEs along each dimension. A regular decomposition
! of a single tile is expressed by a single {\tt regDecomp} list of DE
! counts in each dimension.
!
! The arguments are:
! \begin{description}
! \item[minIndex]
! Index space tuple of the lower corner of the single tile.
! \item[maxIndex]
! Index space tuple of the upper corner of the single tile.
! \item[{[regDecomp]}]
! List of DE counts for each dimension. The total {\tt deCount} is
! determined as the product of {\tt regDecomp} elements.
! By default {\tt regDecomp} = (/{\tt deCount},1,...,1/),
! where {\tt deCount}
! is the number of DEs in the {\tt delayout}. If the default
! {\tt delayout} is used, the {\tt deCount} is equal to {\tt petCount}.
! This leads to a simple 1 DE per PET distribution, where the
! decompsition is only along the first dimension.
! \item[{[decompflag]}]
! List of decomposition flags indicating how each dimension of the
! tile is to be divided between the DEs. The default setting
! is {\tt ESMF\_DECOMP\_BALANCED} in all dimensions. See section
! \ref{const:decompflag} for a list of valid decomposition options.
! \item[{[regDecompFirstExtra]}]
! Specify how many extra elements on the first DEs along each
! dimension to consider when applying the regular decomposition
! algorithm. This does {\em not} add extra elements to the
! index space defined by {\tt minIndex} and {\tt maxIndex}. Instead
! {\tt regDecompFirstExtra} is used to correctly interpret the
! specified index space: The {\tt regDecomp} is first applied to the
! index space {\em without} the extra elements. The extra elements are
! then added back in to arrive at the final decomposition. This is
! useful when aligning the decomposition of index spaces that only
! differ in extra elements along the edges, e.g. when dealing with
! different stagger locations.
! The default is a zero vector, assuming no extra elements.
! \item[{[regDecompLastExtra]}]
! Specify how many extra elements on the last DEs along each
! dimension to consider when applying the regular decomposition
! algorithm. This does {\em not} add extra elements to the
! index space defined by {\tt minIndex} and {\tt maxIndex}. Instead
! {\tt regDecompLastExtra} is used to correctly interpret the
! specified index space: The {\tt regDecomp} is first applied to the
! index space {\em without} the extra elements. The extra elements are
! then added back in to arrive at the final decomposition. This is
! useful when aligning the decomposition of index spaces that only
! differ in extra elements along the edges, e.g. when dealing with
! different stagger locations.
! The default is a zero vector, assuming no extra elements.
! \item[{[deLabelList]}]
! List assigning DE labels to the default sequence of DEs. The default
! sequence is given by the column major order of the {\tt regDecomp}
! argument.
! \item[{[indexflag]}]
! Indicates whether the indices provided by the {\tt minIndex} and
! {\tt maxIndex} arguments are forming a global
! index space or not. This does {\em not} affect the indices held
! by the DistGrid object, which are always identical to what was
! specified by {\tt minIndex} and {\tt maxIndex}, regardless of the
! {\tt indexflag} setting. However, it does affect whether an
! {\tt ESMF\_Array} object created on the DistGrid can choose global
! indexing or not. The default is {\tt ESMF\_INDEX\_DELOCAL}.
! See section \ref{const:indexflag} for a complete list of options.
! \item[{[connectionList]}]
! List of {\tt ESMF\_DistGridConnection} objects, defining connections
! between DistGrid tiles in index space.
! See section \ref{api:DistGridConnectionSet} for the associated Set()
! method.
! \item[{[delayout]}]
! {\tt ESMF\_DELayout} object to be used. If a DELayout object is
! specified its {\tt deCount} must match the number indicated by
! {\tt regDecomp}. By default a new DELayout object will be created
! with the correct number of DEs.
! \item[{[vm]}]
! If present, the DistGrid object (and the DELayout object if not
! provided) are created on the specified {\tt ESMF\_VM} object. The
! default is to use the VM of the current context.
! \item[{[indexTK]}]
! Typekind used for global sequence indexing. See section
! \ref{const:typekind} for a list of typekind options. Only integer
! types are supported. The default is to have ESMF automatically choose
! between {\tt ESMF\_TYPEKIND\_I4} and {\tt ESMF\_TYPEKIND\_I8},
! depending on whether the global number of elements held by the
! DistGrid is below or above the 32-bit limit, respectively.
! Because of the use of signed integers for sequence indices,
! element counts of $ > 2^{31}-1 = 2,147,483,647$ will switch to 64-bit
! indexing.
! \item[{[rc]}]
! Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
! \end{description}
!
!EOP
!------------------------------------------------------------------------------
integer :: localrc ! local return code
type(ESMF_DistGrid) :: distgrid ! opaque pointer to new C++ DistGrid
type(ESMF_InterArray) :: minIndexAux ! helper variable
type(ESMF_InterArray) :: maxIndexAux ! helper variable
type(ESMF_InterArray) :: regDecompAux ! helper variable
type(ESMF_Decomp_Flag), target :: dummyDf(0) ! satisfy C interface
type(ESMF_Decomp_Flag), pointer :: opt_decompflag(:) ! optional arg helper
integer :: len_decompflag ! helper variable
type(ESMF_InterArray) :: regDecompFirstExtraAux ! helper variable
type(ESMF_InterArray) :: regDecompLastExtraAux ! helper variable
type(ESMF_InterArray) :: deLabelListAux ! helper variable
type(ESMF_InterArray) :: connectionListAux ! helper variable
! initialize return code; assume routine not implemented
localrc = ESMF_RC_NOT_IMPL
if (present(rc)) rc = ESMF_RC_NOT_IMPL
! invalidate return value
distgrid%this = ESMF_NULL_POINTER
ESMF_DistGridCreateRD = distgrid
! Check init status of arguments
ESMF_INIT_CHECK_DEEP(ESMF_DELayoutGetInit, delayout, rc)
ESMF_INIT_CHECK_DEEP(ESMF_VMGetInit, vm, rc)
! Deal with (optional) array arguments
minIndexAux = ESMF_InterArrayCreate(minIndex, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
maxIndexAux = ESMF_InterArrayCreate(maxIndex, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
regDecompAux = ESMF_InterArrayCreate(regDecomp, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
if (present(decompflag)) then
len_decompflag = size(decompflag)
opt_decompflag => decompflag
else
len_decompflag = 0
opt_decompflag => dummyDf
endif
regDecompFirstExtraAux = ESMF_InterArrayCreate(regDecompFirstExtra, &
rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
regDecompLastExtraAux = ESMF_InterArrayCreate(regDecompLastExtra, &
rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
deLabelListAux = ESMF_InterArrayCreate(deLabelList, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
connectionListAux = ESMF_InterArrayCreateDGConn(connectionList, &
rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! Mark this DistGrid as invalid
distgrid%this = ESMF_NULL_POINTER
! call into the C++ interface, which will sort out optional arguments
call c_ESMC_DistGridCreateRD(distgrid, minIndexAux, maxIndexAux, &
regDecompAux, opt_decompflag, len_decompflag, regDecompFirstExtraAux, &
regDecompLastExtraAux, deLabelListAux, indexflag, &
connectionListAux, delayout, vm, indexTK, localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! garbage collection
call ESMF_InterArrayDestroy(minIndexAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(maxIndexAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(regDecompAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(regDecompFirstExtraAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(regDecompLastExtraAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(deLabelListAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(connectionListAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! Set return value
ESMF_DistGridCreateRD = distgrid
! Set init code
ESMF_INIT_SET_CREATED(ESMF_DistGridCreateRD)
! return successfully
if (present(rc)) rc = ESMF_SUCCESS
end function ESMF_DistGridCreateRD