recursive function ESMF_GridCompCreate(keywordEnforcer, grid, gridList, &
mesh, meshList, locstream, locstreamList, xgrid, xgridList, &
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_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.
! \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[{[config]}]
! An already-created {\tt ESMF\_Config} object to be attached to the newly
! created component.
! If both {\tt config} and {\tt configFile} arguments are specified,
! {\tt config} takes priority.
! \item[{[configFile]}]
! The filename of an {\tt ESMF\_Config} format 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.
! If both {\tt config} and {\tt configFile} arguments are specified,
! {\tt config} takes priority.
! \item[{[clock]}]
! \begin{sloppypar}
! Component-specific {\tt ESMF\_Clock}. This clock is available to be
! queried and updated by the new {\tt ESMF\_GridComp} as it chooses.
! This should
! not be the parent component clock, which should be maintained and passed
! down to the initialize/run/finalize routines separately.
! \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_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, 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