ESMF_DistGridCreateDG Function

  function ESMF_DistGridCreateDG(distgrid, keywordEnforcer, &
    firstExtra, lastExtra, indexflag, connectionList, balanceflag, &
    delayout, vm, rc)
!         
! !RETURN VALUE:
    type(ESMF_DistGrid) :: ESMF_DistGridCreateDG
!
! !ARGUMENTS:
    type(ESMF_DistGrid),           intent(in)            :: distgrid
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
    integer, target,               intent(in),  optional :: firstExtra(:)
    integer, target,               intent(in),  optional :: lastExtra(:)
    type(ESMF_Index_Flag),         intent(in),  optional :: indexflag
    type(ESMF_DistGridConnection), intent(in),  optional :: connectionList(:)
    logical,                       intent(in),  optional :: balanceflag
    type(ESMF_DELayout),           intent(in),  optional :: delayout
    type(ESMF_VM),                 intent(in),  optional :: vm
    integer,                       intent(out), optional :: rc
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{5.2.0r}
! \begin{description}
! \item[6.3.0r] Added argument {\tt vm} to support object creation on a
!               different VM than that of the current context.
! \item[8.0.0] Added argument {\tt delayout} to support changing the layout of
!              DEs across PETs.\newline
!              Added argument {\tt balanceflag} to support rebalancing of the
!              incoming DistGrids decomposition.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
!     Create a new DistGrid from an existing DistGrid, keeping the decomposition
!     unchanged, unless {\tt balanceflag=.true.} (see below).
!     The {\tt firstExtraPTile} and {\tt lastExtraPTile} arguments allow extra
!     elements to be added at the first/last edge DE in each dimension. The 
!     method also allows the {\tt indexflag} to be set. Further, if the 
!     {\tt connectionList} argument provided in it will be used to set 
!     connections in the newly created DistGrid, otherwise the connections of
!     the incoming DistGrid will be used.
!
!     The {\tt balanceflag} argument allows a change in the decomposition, and
!     thus of the number of DEs. An attempt is made to decompose the index
!     space into as many DEs as there are PETs in the VM for which the DistGrid
!     is created. See the argument description for details.
!
!     Setting the {\tt balanceflag} argument to {\tt .true.} is currently
!     incompatible with providing any of the other optional arguments.
!
!     The arguments are:
!     \begin{description}
!     \item[distgrid]
!          Incoming DistGrid object.
!     \item[{[firstExtra]}]
!          Extra elements added to the first DE along each 
!          dimension. This increases the size of the index space compared to 
!          that of the incoming {\tt distgrid}. The decomposition of the
!          enlarged index space is constructed to align with the original index
!          space provided by {\tt distgrid}.
!          The default is a zero vector.
!     \item[{[lastExtra]}]
!          Extra elements added to the last DE along each 
!          dimension. This increases the size of the index space compared to 
!          that of the incoming {\tt distgrid}. The decomposition of the
!          enlarged index space is constructed to align with the original index
!          space provided by {\tt distgrid}.
!          The default is a zero vector.
!     \item[{[indexflag]}]
!          If present, override the indexflag setting of the incoming
!          {\tt distgrid}. See section \ref{const:indexflag} for a 
!          complete list of options. By default use the indexflag setting of 
!          {\tt distgrid}. 
!     \item[{[connectionList]}]
!          If present, override the connections of the incoming {\tt distgrid}.
!          See section \ref{api:DistGridConnectionSet} for the associated Set()
!          method. By default use the connections defined in {\tt distgrid}.
!     \item[{[balanceflag]}]
!          If set to {\tt .true}, rebalance the incoming {\tt distgrid}
!          decompositon to exactly one DE per PET. The DEs along each dimension
!          are chosen to provide the most balanced decomposition across all
!          dimensions.
!          The default is {\tt .false.}, leaving the decomposition, and
!          therefore the number of DEs unchanged. For this case, PETs might end
!          up with no DE, one DE, or multiple DEs.
!     \item[{[delayout]}]
!          If present, override the DELayout of the incoming {\tt distgrid}.
!          By default use the DELayout defined in {\tt distgrid}.
!     \item[{[vm]}]
!          If present, the DistGrid object and the DELayout object
!          are created on the specified {\tt ESMF\_VM} object. The 
!          default is to use the VM of the current context. 
!     \item[{[rc]}]
!          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!     \end{description}
!
!EOP
!------------------------------------------------------------------------------
    integer               :: localrc        ! local return code
    type(ESMF_DistGrid)   :: dg             ! opaque pointer to new C++ DistGrid
    type(ESMF_InterArray) :: firstExtraAux  ! helper variable
    type(ESMF_InterArray) :: lastExtraAux   ! helper variable
    type(ESMF_InterArray) :: connectionListAux  ! helper variable
    type(ESMF_Logical)    :: opt_balanceflag    ! 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    
    dg%this = ESMF_NULL_POINTER
    ESMF_DistGridCreateDG = dg 

    ! Check init status of arguments
    ESMF_INIT_CHECK_DEEP(ESMF_DistGridGetInit, distgrid, rc)
    if (present(vm)) then
      ESMF_INIT_CHECK_DEEP(ESMF_VMGetInit, vm, rc)
    endif
    
    ! Deal with (optional) array arguments
    firstExtraAux = ESMF_InterArrayCreate(firstExtra, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    lastExtraAux = ESMF_InterArrayCreate(lastExtra, 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

    ! Set default flags
    opt_balanceflag = ESMF_FALSE
    if (present(balanceflag)) opt_balanceflag = balanceflag

    ! Mark this DistGrid as invalid
    dg%this = ESMF_NULL_POINTER

    ! call into the C++ interface, which will sort out optional arguments
    call c_ESMC_DistGridCreateDG(dg, distgrid, firstExtraAux, &
      lastExtraAux, indexflag, connectionListAux, opt_balanceflag, &
      delayout, vm, localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
      
    ! garbage collection
    call ESMF_InterArrayDestroy(firstExtraAux, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    call ESMF_InterArrayDestroy(lastExtraAux, 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_DistGridCreateDG = dg 
 
    ! Set init code
    ESMF_INIT_SET_CREATED(ESMF_DistGridCreateDG)
 
    ! return successfully
    if (present(rc)) rc = ESMF_SUCCESS
 
  end function ESMF_DistGridCreateDG