ESMF_DELayoutGet Subroutine

  recursive subroutine ESMF_DELayoutGet(delayout, keywordEnforcer, vm, deCount,&
    petMap, vasMap, oneToOneFlag, pinflag, localDeCount, localDeToDeMap, &
    localDeList, &      ! DEPRECATED ARGUMENT
    vasLocalDeCount, vasLocalDeToDeMap, &
    vasLocalDeList, &   ! DEPRECATED ARGUMENT
    rc)
!
! !ARGUMENTS:
    type(ESMF_DELayout),      intent(in)            :: delayout
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
    type(ESMF_VM),            intent(out), optional :: vm
    integer,                  intent(out), optional :: deCount
    integer, target,          intent(out), optional :: petMap(:)
    integer, target,          intent(out), optional :: vasMap(:)
    logical,                  intent(out), optional :: oneToOneFlag
    type(ESMF_Pin_Flag),      intent(out), optional :: pinflag
    integer,                  intent(out), optional :: localDeCount
    integer, target,          intent(out), optional :: localDeToDeMap(:)
    integer, target, intent(out), optional :: localDeList(:)  !DEPRECATED ARG
    integer,                  intent(out), optional :: vasLocalDeCount
    integer, target,          intent(out), optional :: vasLocalDeToDeMap(:)
    integer, target, intent(out), optional :: vasLocalDeList(:) !DEPRECATED ARG
    integer,                  intent(out), optional :: rc  
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{5.2.0r}
! \begin{description}
! \item[5.2.0rp1] Added arguments {\tt localDeToDeMap} and {\tt vasLocalDeToDeMap}.
!                 Started to deprecate arguments {\tt localDeList} and 
!                 {\tt vasLocalDeList}. 
!                 The new argument names correctly use the {\tt Map} suffix and
!                 better describe the returned information.
!                 This was pointed out by user request.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
!   Access to DELayout information.
!
!   The arguments are:
!   \begin{description}
!   \item[delayout] 
!     Queried {\tt ESMF\_DELayout} object.
!   \item[{[vm]}]
!     The {\tt ESMF\_VM} object on which {\tt delayout} is defined.
!   \item[{[deCount]}]
!     The total number of DEs in the DELayout.
!   \item[{[petMap]}]
!     List of PETs against which the DEs are mapped. The {\tt petMap} 
!     argument must at least be of size {\tt deCount}.
!   \item[{[vasMap]}]
!     List of VASs against which the DEs are mapped. The {\tt vasMap}
!     argument must at least be of size {\tt deCount}.
!   \item[{[oneToOneFlag]}]
!     A value of {\tt .TRUE.} indicates that {\tt delayout} maps each DE to a
!     single PET, and each PET maps to a single DE. All other layouts return
!     a value of {\tt .FALSE.}.
!   \item[{[pinflag]}]
!     The type of DE pinning. See section \ref{const:pin_flag} for a list
!     of valid pinning options.
!   \item[{[localDeCount]}]
!     The number of DEs in the DELayout associated with the local PET.
!   \item[{[localDeToDeMap]}]
!     Mapping between localDe indices and the (global) DEs associated with
!     the local PET. The localDe index variables are discussed in sections
!     \ref{DELayout_general_mapping} and \ref{Array_native_language_localde}.
!     The provided actual argument must be of size {\tt localDeCount}.
!   \item[{[localDeList]}]
!     \apiDeprecatedArgWithReplacement{localDeToDeMap}
!   \item[{[vasLocalDeCount]}]
!     The number of DEs in the DELayout associated with the local VAS.
!   \item[{[vasLocalDeToDeMap]}]
!     Mapping between localDe indices and the (global) DEs associated with
!     the local VAS. The localDe index variables are discussed in sections
!     \ref{DELayout_general_mapping} and \ref{Array_native_language_localde}.
!     The provided actual argument must be of size {\tt localDeCount}.
!   \item[{[vasLocalDeList]}]
!     \apiDeprecatedArgWithReplacement{vasLocalDeToDeMap}
!   \item[{[rc]}] 
!     Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!   \end{description}
!
!EOP
!
!
!    integer, target,          intent(out),  optional  :: compCapacity(:)
!    integer, target,          intent(out),  optional  :: commCapacity(:,:)
!     \item[{[compCapacity]}]
!        \begin{sloppypar}
!        Upon return this holds a relative measure of the computational
!        capacity for each DE. The {\tt compCapacity} argument must at least be
!        of size {\tt deCount}.
!        \end{sloppypar}
!     \item[{[commCapacity]}]
!        Upon return this holds a relative measure of the communication
!        capacity for each pair of DEs. The {\tt commCapacity} argument is a
!        2D array where each dimension must at least be of size {\tt deCount}.
!
!------------------------------------------------------------------------------
    integer               :: localrc                ! local return code
    type(ESMF_InterArray) :: petMapArg              ! helper variable
    type(ESMF_InterArray) :: vasMapArg              ! helper variable
    type(ESMF_InterArray) :: localDeToDeMapArg      ! helper variable
    type(ESMF_InterArray) :: vasLocalDeToDeMapArg   ! helper variable
    type(ESMF_Logical)    :: oneToOneFlagArg        ! helper variable
    
    ! initialize return code; assume routine not implemented
    localrc = ESMF_RC_NOT_IMPL
    if (present(rc)) rc = ESMF_RC_NOT_IMPL

    ! Check init status of arguments
    ESMF_INIT_CHECK_DEEP(ESMF_DELayoutGetInit, delayout, rc)
    
    ! Not implemented features
!    if (present(compCapacity)) then
!      call ESMF_LogSetError(rcToCheck=ESMF_RC_NOT_IMPL, &
!        msg="- compCapacity query not implemented", &
!        ESMF_CONTEXT, rcToReturn=rc)
!      return
!    endif
!    if (present(commCapacity)) then
!      call ESMF_LogSetError(rcToCheck=ESMF_RC_NOT_IMPL, &
!        msg="- commCapacity query not implemented", &
!        ESMF_CONTEXT, rcToReturn=rc)
!      return
!    endif
    
    ! Deal with (optional) array arguments
    petMapArg = ESMF_InterArrayCreate(petMap, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    vasMapArg = ESMF_InterArrayCreate(vasMap, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    localDeToDeMapArg = ESMF_InterArrayCreate(localDeToDeMap, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    vasLocalDeToDeMapArg = ESMF_InterArrayCreate(vasLocalDeToDeMap, &
      rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
      
    ! extra code to deal with deprecated arguments -> will be removed eventually
    if (present(localDeList)) then
      call ESMF_LogWrite("The use of argument 'localDeList' in call "// &
        "ESMF_DELayoutGet() is DEPRECATED! Use argumemt 'localDeToDeMap' "// &
        "instead.", ESMF_LOGMSG_WARNING, rc=localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return
      if (.not.present(localDeToDeMap)) then
        call ESMF_InterArrayDestroy(localDeToDeMapArg, rc=localrc)
        if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
          ESMF_CONTEXT, rcToReturn=rc)) return
        localDeToDeMapArg = ESMF_InterArrayCreate(localDeList, rc=localrc)
        if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
          ESMF_CONTEXT, rcToReturn=rc)) return
      endif
    endif
    if (present(vasLocalDeList)) then
      call ESMF_LogWrite("The use of argument 'vasLocalDeList' in call "// &
        "ESMF_DELayoutGet() is DEPRECATED! Use argument 'vasLocalDeToDeMap' "// &
        "instead.", ESMF_LOGMSG_WARNING, rc=localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return
      if (.not.present(vasLocalDeToDeMap)) then
        call ESMF_InterArrayDestroy(vasLocalDeToDeMapArg, rc=localrc)
        if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
          ESMF_CONTEXT, rcToReturn=rc)) return
        vasLocalDeToDeMapArg = ESMF_InterArrayCreate(vasLocalDeList, &
          rc=localrc)
        if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
          ESMF_CONTEXT, rcToReturn=rc)) return
      endif
    endif
    
    ! Call into the C++ interface, which will sort out optional arguments
    call c_ESMC_DELayoutGet(delayout, vm, deCount, petMapArg, vasMapArg, &
      oneToOneFlagArg, pinflag, localDeCount, localDeToDeMapArg, &
      vasLocalDeCount, vasLocalDeToDeMapArg, localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    if (present (oneToOneFlag)) &
      oneToOneFlag = oneToOneFlagArg
      
    ! Set init code for deep C++ objects
    if (present(vm)) then
      call ESMF_VMSetInitCreated(vm, rc=localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return
    endif
    
    ! garbage collection
    call ESMF_InterArrayDestroy(petMapArg, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    call ESMF_InterArrayDestroy(vasMapArg, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    call ESMF_InterArrayDestroy(localDeToDeMapArg, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
    call ESMF_InterArrayDestroy(vasLocalDeToDeMapArg, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return
      
    ! finish dealing with deprecated arguments -> will be removed eventually
    if (present(localDeList) .and. present(localDeToDeMap)) then
      localDeList = localDeToDeMap
    endif
    if (present(vasLocalDeList) .and. present(vasLocalDeToDeMap)) then
      vasLocalDeList = vasLocalDeToDeMap
    endif

    ! return successfully
    if (present(rc)) rc = ESMF_SUCCESS

  end subroutine ESMF_DELayoutGet