function ESMF_DistGridCreateRDT(minIndexPTile, maxIndexPTile, &
keywordEnforcer, regDecompPTile, decompflagPTile, regDecompFirstExtraPTile,&
regDecompLastExtraPTile, deLabelList, indexflag, connectionList, &
delayout, vm, indexTK, rc)
!
! !RETURN VALUE:
type(ESMF_DistGrid) :: ESMF_DistGridCreateRDT
!
! !ARGUMENTS:
integer, intent(in) :: minIndexPTile(:,:)
integer, intent(in) :: maxIndexPTile(:,:)
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
integer, intent(in), optional :: regDecompPTile(:,:)
type(ESMF_Decomp_Flag), target, intent(in), optional :: decompflagPTile(:,:)
integer, target, intent(in), optional :: regDecompFirstExtraPTile(:,:)
integer, target, intent(in), optional :: regDecompLastExtraPTile(:,:)
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
!
! !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 multiple logically rectangular tiles.
! Each tile has a regular decomposition, where the tile is decomposed
! into a fixed number of DEs along each dimension. A regular decomposition
! of a multi-tile DistGrid is expressed by a list of DE count vectors, one
! vector for each tile. If a DELayout is specified, it must contain at least
! as many DEs as there are tiles.
!
! 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[{[regDecompPTile]}]
! List of DE counts for each dimension. The second index steps through
! the tiles. The total {\tt deCount} is determined as ths sum over
! the products of {\tt regDecomp} elements for each tile.
! By default each tile is decomposed only along the first dimension.
! The default number of DEs per tile is at least 1, but may be greater
! for the leading tiles if the {\tt deCount} is greater than the
! {\tt tileCount}. If no DELayout is specified, the {\tt deCount} is
! by default set equal to the number of PETs ({\tt petCount}), or the
! number of tiles ({\tt tileCount}), which ever is greater. This means
! that as long as {\tt petCount} > {\tt tileCount}, the resulting
! default distribution will be 1 DE per PET. Notice that some tiles
! may be decomposed into more DEs than other tiles.
! \item[{[decompflagPTile]}]
! List of decomposition flags indicating how each dimension of each
! tile is to be divided between the DEs. The default setting
! is {\tt ESMF\_DECOMP\_BALANCED} in all dimensions for all tiles.
! See section \ref{const:decompflag} for a list of valid decomposition
! flag options. The second index indicates the tile number.
! \item[{[regDecompFirstExtraPTile]}]
! 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 regDecompFirstExtraPTile} 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[{[regDecompLastExtraPTile]}]
! 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 regDecompLastExtraPTile} 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 regDecompPTile}
! elements in the sequence as they appear following the tile index.
! \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 as many DEs as there are PETs,
! or tiles, which ever is greater. If a DELayout object is specified,
! the number of DEs must match {\tt regDecompPTile}, if present. In the
! case that {\tt regDecompPTile} was not specified, the {\tt deCount}
! must be at least that of the default DELayout. The
! {\tt regDecompPTile} will be constructed accordingly.
! \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) :: regDecompAux ! helper variable
type(ESMF_Decomp_Flag), target :: dummyDf(0,0) ! satisfy C interface
type(ESMF_Decomp_Flag), pointer:: opt_decompflag(:,:) ! optional arg helper
integer :: len1_decompflag ! helper variable
integer :: len2_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_DistGridCreateRDT = 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
regDecompAux = ESMF_InterArrayCreate(farray2D=regDecompPTile, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
if (present(decompflagPTile)) then
len1_decompflag = size(decompflagPTile, 1)
len2_decompflag = size(decompflagPTile, 2)
opt_decompflag => decompflagPTile
else
len1_decompflag = 0
len2_decompflag = 0
opt_decompflag => dummyDf
endif
regDecompFirstExtraAux = &
ESMF_InterArrayCreate(farray2D=regDecompFirstExtraPTile, rc=localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
regDecompLastExtraAux = &
ESMF_InterArrayCreate(farray2D=regDecompLastExtraPTile, 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_DistGridCreateRDT(distgrid, minIndexAux, maxIndexAux, &
regDecompAux, opt_decompflag, len1_decompflag, len2_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_DistGridCreateRDT = distgrid
! Set init code
ESMF_INIT_SET_CREATED(ESMF_DistGridCreateRDT)
! return successfully
if (present(rc)) rc = ESMF_SUCCESS
end function ESMF_DistGridCreateRDT