function ESMF_DistGridCreateDBT(minIndexPTile, maxIndexPTile, deBlockList, &
deToTileMap, keywordEnforcer, deLabelList, indexflag, connectionList, &
delayout, vm, indexTK, rc)
!
! !RETURN VALUE:
type(ESMF_DistGrid) :: ESMF_DistGridCreateDBT
!
! !ARGUMENTS:
integer, intent(in) :: minIndexPTile(:,:)
integer, intent(in) :: maxIndexPTile(:,:)
integer, intent(in) :: deBlockList(:,:,:)
integer, intent(in) :: deToTileMap(:)
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
integer, 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
!
! !DESCRIPTION:
! Create an {\tt ESMF\_DistGrid} on multiple logically
! rectangular tiles with decomposition specified by {\tt deBlockList}.
!
! The arguments are:
! \begin{description}
! \item[minIndexPTile]
! The first index provides the index space tuple of the lower
! corner of a tile. The second index indicates the tile number.
! \item[maxIndexPTile]
! The first index provides the index space tuple of the upper
! corner of a tile. The second index indicates the tile number.
! \item[deBlockList]
! List of DE-local blocks. The third index of {\tt deBlockList}
! steps through the deBlock elements (i.e. deCount), which are defined
! by the first two indices.
! The first index must be of size {\tt dimCount} and the
! second index must be of size 2. Each element of {\tt deBlockList}
! defined by the first two indices hold the following information.
! \begin{verbatim}
! +---------------------------------------> 2nd index
! | 1 2
! | 1 minIndex(1) maxIndex(1)
! | 2 minIndex(2) maxIndex(2)
! | . minIndex(.) maxIndex(.)
! | .
! v
! 1st index
! \end{verbatim}
! It is required that there be no overlap between the DE blocks.
! \item[deToTileMap]
! List assigning each DE to a specific tile. The size of
! {\tt deToTileMap} must be equal to {\tt deCount}.
! The order of DEs is the same as in {\tt deBlockList}.
! \item[{[deLabelList]}]
! List assigning DE labels to the default sequence of DEs. The default
! sequence is given by the order of DEs in the {\tt deBlockList}
! argument.
! \item[{[indexflag]}]
! Indicates whether the indices provided by the {\tt minIndexPTile} and
! {\tt maxIndexPTile} 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 minIndexPTile} and {\tt maxIndexPTile}, 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]}]
! Optional {\tt ESMF\_DELayout} object to be used. By default a new
! DELayout object will be created with the correct number of DEs. If
! a DELayout object is specified its number of DEs must match the
! number indicated by {\tt regDecomp}.
! \item[{[vm]}]
! Optional {\tt ESMF\_VM} object of the current context. Providing the
! VM of the current context will lower the method's overhead.
! \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) :: deBlockListAux ! helper variable
type(ESMF_InterArray) :: deToTileMapAux ! 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
! Initialize the pointer to NULL
distgrid%this = ESMF_NULL_POINTER
ESMF_DistGridCreateDBT = 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(farray2D=minIndexPTile, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
maxIndexAux = ESMF_InterArrayCreate(farray2D=maxIndexPTile, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
deBlockListAux = ESMF_InterArrayCreate(farray3D=deBlockList, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
deToTileMapAux = ESMF_InterArrayCreate(deToTileMap, 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
! call into the C++ interface, which will sort out optional arguments
call c_ESMC_DistGridCreateDBT(distgrid, minIndexAux, maxIndexAux, &
deBlockListAux, deToTileMapAux, 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(deBlockListAux, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
call ESMF_InterArrayDestroy(deToTileMapAux, 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_DistGridCreateDBT = distgrid
! Set init code
ESMF_INIT_SET_CREATED(ESMF_DistGridCreateDBT)
! return successfully
if (present(rc)) rc = ESMF_SUCCESS
end function ESMF_DistGridCreateDBT