ESMF_GridCompCreate Function

  recursive function ESMF_GridCompCreate(keywordEnforcer, grid, gridList, &
    mesh, meshList, locstream, locstreamList, xgrid, xgridList, &
    hconfig, config, configFile, clock, petList, devList, contextflag, name, rc)
!
! !RETURN VALUE:
    type(ESMF_GridComp) :: ESMF_GridCompCreate
!
! !ARGUMENTS:
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
    type(ESMF_Grid),         intent(in),    optional :: grid
    type(ESMF_Grid),         intent(in),    optional :: gridList(:)
    type(ESMF_Mesh),         intent(in),    optional :: mesh
    type(ESMF_Mesh),         intent(in),    optional :: meshList(:)
    type(ESMF_LocStream),    intent(in),    optional :: locstream
    type(ESMF_LocStream),    intent(in),    optional :: locstreamList(:)
    type(ESMF_XGrid),        intent(in),    optional :: xgrid
    type(ESMF_XGrid),        intent(in),    optional :: xgridList(:)
    type(ESMF_HConfig),      intent(in),    optional :: hconfig
    type(ESMF_Config),       intent(in),    optional :: config
    character(len=*),        intent(in),    optional :: configFile
    type(ESMF_Clock),        intent(in),    optional :: clock
    integer,                 intent(in),    optional :: petList(:)
    integer,                 intent(in),    optional :: devList(:)
    type(ESMF_Context_Flag), intent(in),    optional :: contextflag
    character(len=*),        intent(in),    optional :: name
    integer,                 intent(out),   optional :: rc
!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{5.2.0r}
! \begin{description}
! \begin{sloppypar}
! \item[7.1.0r] Added arguments {\tt gridList}, {\tt mesh}, {\tt meshList},
!   {\tt locstream}, {\tt locstreamList}, {\tt xgrid}, and {\tt xgridList}.
!   These arguments add support for holding references to multiple geom objects,
!   either of the same type, or different type, in the same
!   {\tt ESMF\_GridComp} object.
! \item[8.6.0] Added argument {\tt devList} to support management of accelerator
!   devices.
! \item[8.7.0] Added argument {\tt hconfig} to simplify direct usage of
!   {\tt ESMF\_HConfig} objects with Components.
! \end{sloppypar}
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
! This interface creates an {\tt ESMF\_GridComp} object. By default, a
! separate VM context will be created for each component.  This implies
! creating a new MPI communicator and allocating additional memory to
! manage the VM resources. When running on a large number of processors,
! creating a separate VM for each component could be both time and memory
! inefficient.  If the application is sequential, i.e., each component is
! running on all the PETs of the global VM, it will be more efficient to use
! the global VM instead of creating a new one.  This can be done by setting
! {\tt contextflag} to ESMF\_CONTEXT\_PARENT\_VM.
!
! The return value is the new {\tt ESMF\_GridComp}.
!
! The arguments are:
! \begin{description}
! \item[{[grid]}]
!   Associate an {\tt ESMF\_Grid} object with the newly created component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt grid} object.
!   The {\tt grid} argument is mutually exclusive with the {\tt gridList}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt grid} nor {\tt gridList} are provided,
!   no {\tt ESMF\_Grid} objects are associated with the component.
! \item[{[gridList]}]
!   Associate a list of {\tt ESMF\_Grid} objects with the newly created
!   component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt gridList} object.
!   The {\tt gridList} argument is mutually exclusive with the {\tt grid}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt grid} nor {\tt gridList} are provided,
!   no {\tt ESMF\_Grid} objects are associated with the component.
! \item[{[mesh]}]
!   Associate an {\tt ESMF\_Mesh} object with the newly created component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt mesh} object.
!   The {\tt mesh} argument is mutually exclusive with the {\tt meshList}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt mesh} nor {\tt meshList} are provided,
!   no {\tt ESMF\_Mesh} objects are associated with the component.
! \item[{[meshList]}]
!   Associate a list of {\tt ESMF\_Mesh} objects with the newly created
!   component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt meshList} object.
!   The {\tt meshList} argument is mutually exclusive with the {\tt mesh}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt mesh} nor {\tt meshList} are provided,
!   no {\tt ESMF\_Mesh} objects are associated with the component.
! \item[{[locstream]}]
!   Associate an {\tt ESMF\_LocStream} object with the newly created component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt locstream} object.
!   The {\tt locstream} argument is mutually exclusive with the
!   {\tt locstreamList}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt locstream} nor {\tt locstreamList} are
!   provided, no {\tt ESMF\_LocStream} objects are associated with the
!   component.
! \item[{[locstreamList]}]
!   Associate a list of {\tt ESMF\_LocStream} objects with the newly created
!   component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt locstreamList} object.
!   The {\tt locstreamList} argument is mutually exclusive with the
!   {\tt locstream}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt locstream} nor {\tt locstreamList} are
!   provided, no {\tt ESMF\_LocStream} objects are associated with the
!   component.
! \item[{[xgrid]}]
!   Associate an {\tt ESMF\_XGrid} object with the newly created component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt xgrid} object.
!   The {\tt xgrid} argument is mutually exclusive with the {\tt xgridList}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt xgrid} nor {\tt xgridList} are provided,
!   no {\tt ESMF\_XGrid} objects are associated with the component.
! \item[{[xgridList]}]
!   Associate a list of {\tt ESMF\_XGrid} objects with the newly created
!   component.
!   This is simply a convenience feature for the user. The ESMF library code
!   does not access the {\tt xgridList} object.
!   The {\tt xgridList} argument is mutually exclusive with the {\tt xgrid}
!   argument. If both arguments are provided, the routine will fail, and an
!   error is returned in {\tt rc}.
!   By default, i.e. if neither {\tt xgrid} nor {\tt xgridList} are provided,
!   no {\tt ESMF\_XGrid} objects are associated with the component.
! \item[{[hconfig]}]
!   An already-created {\tt ESMF\_HConfig} object to be attached to the newly
!   created component.
!   Only one of {\tt hconfig}, {\tt config}, or {\tt configFile} must be
!   specified.
! \item[{[config]}]
!   An already-created {\tt ESMF\_Config} object to be attached to the newly
!   created component.
!   Only one of {\tt hconfig}, {\tt config}, or {\tt configFile} must be
!   specified.
! \item[{[configFile]}]
!   The filename of a config file.
!   If specified, a new {\tt ESMF\_Config} object is created and attached to the
!   newly created component. The {\tt configFile} file is opened and associated
!   with the new config object.
!   Only one of {\tt hconfig}, {\tt config}, or {\tt configFile} must be
!   specified.
! \item[{[clock]}]
!   \begin{sloppypar}
!   The {\tt ESMF\_Clock} object associated with the component. Often this will
!   be a component specific clock that can be queried and updated by the
!   component freely. In that case it should be a clock object separate from
!   that of other components, particularily that of the parent component.
!   However, ESMF itself does not access or update {\tt clock} and therefore
!   does not impose any direct restrictions. It is the user's responsibility to
!   ensure correct usage of the {\tt clock} object by the parent and child
!   components.
!   \end{sloppypar}
! \item[{[petList]}]
!   List of parent {\tt PET}s given to the created child component by the
!   parent component. If {\tt petList} is not specified, or is empty, all of the
!   parent {\tt PET}s are given to the child component. The order of
!   PETs in {\tt petList} determines how the child local PETs map back to
!   the parent PETs.
! \item[{[devList]}]
!   List of accelerator devices global ids {\tt DEV}s to be associated with the
!   created child component. If {\tt devList} is not specified, or is empty,
!   no devices are associated with the component.
! \item[{[contextflag]}]
!   Specify the component's VM context. The default context is
!   {\tt ESMF\_CONTEXT\_OWN\_VM}. See section \ref{const:contextflag} for a
!   complete list of valid flags.
! \item[{[name]}]
!   Name of the newly-created {\tt ESMF\_GridComp}.  This name can be altered
!   from within the {\tt ESMF\_GridComp} code once the initialization routine
!   is called.
! \item[{[rc]}]
!   Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
! \end{description}
!
!EOP
!------------------------------------------------------------------------------
    type(ESMF_CompClass), pointer :: compclass       ! generic comp
    type(ESMF_GridComp)           :: gcomp
    integer :: localrc                               ! local error status

    ESMF_INIT_CHECK_DEEP(ESMF_GridGetInit,grid,rc)
    ESMF_INIT_CHECK_DEEP(ESMF_HConfigGetInit,hconfig,rc)
    ESMF_INIT_CHECK_DEEP(ESMF_ConfigGetInit,config,rc)
    ESMF_INIT_CHECK_DEEP(ESMF_ClockGetInit,clock,rc)

    ! Initialize the pointer to null.
    nullify(ESMF_GridCompCreate%compp)
    nullify(compclass)

    ! initialize return code; assume routine not implemented
    if (present(rc)) rc = ESMF_RC_NOT_IMPL
    localrc = ESMF_RC_NOT_IMPL

    ! Allocate a new comp class
    allocate(compclass, stat=localrc)
    if (ESMF_LogFoundAllocError(localrc, msg="compclass", &
      ESMF_CONTEXT, rcToReturn=rc)) return

    ! call Comp method
    call ESMF_CompConstruct(compclass, ESMF_COMPTYPE_GRID, name, &
      configFile=configFile, config=config, hconfig=hconfig, clock=clock, &
      petList=petList, devList=devList, contextflag=contextflag, rc=localrc)
    if (ESMF_LogFoundError(localrc, &
      ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) then
      deallocate(compclass)
      return
    endif

    gcomp%compp => compclass
    ! Add reference to this object into ESMF garbage collection table
    call c_ESMC_VMAddFObject(gcomp, ESMF_ID_COMPONENT%objectID)

    ! Set return values
    ESMF_GridCompCreate%compp => compclass

    ESMF_INIT_SET_CREATED(ESMF_GridCompCreate)

    ! deal with geom object arguments
    call ESMF_GridCompSet(ESMF_GridCompCreate, grid=grid, gridList=gridList, &
      mesh=mesh, meshList=meshList, locstream=locstream, &
      locstreamList=locstreamList, xgrid=xgrid, xgridList=xgridList, rc=localrc)
    if (ESMF_LogFoundError(localrc, &
      ESMF_ERR_PASSTHRU, &
      ESMF_CONTEXT, rcToReturn=rc)) return

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

  end function ESMF_GridCompCreate