MODULE:
module NUOPC_Driver
DESCRIPTION:
Component that drives and coordinates initialization of its child components: Model, Mediator, and Connector components. For every Driver time step the same run sequence, i.e. sequence of Model, Mediator, and Connector Run methods is called. The run sequence is fully customizable. The default run sequence implements explicit time stepping.
SUPER:
ESMF_GridComp
USE DEPENDENCIES:
use ESMF
SETSERVICES:
subroutine SetServices(driver, rc) type(ESMF_GridComp) :: driver integer, intent(out) :: rc
SEMANTIC SPECIALIZATION LABELS:
INTERFACE:
! Private name; call using NUOPC_DriverAddComp() recursive subroutine NUOPC_DriverAddGridComp(driver, compLabel, & compSetServicesRoutine, compSetVMRoutine, petList, info, config, comp, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver character(len=*), intent(in) :: compLabel #if defined (__NVCOMPILER) || defined (__PGI) || defined (ESMF_COMPILER_AOCC) interface recursive subroutine compSetServicesRoutine(gridcomp, rc) use ESMF implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface interface recursive subroutine compSetVMRoutine(gridcomp, rc) use ESMF implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface optional :: compSetVMRoutine #else abstract interface recursive subroutine SetServicesRoutine(gridcomp, rc) use ESMF implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine recursive subroutine SetVMRoutine(gridcomp, rc) use ESMF implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface procedure(SetServicesRoutine) :: compSetServicesRoutine procedure(SetVMRoutine), optional :: compSetVMRoutine #endif integer, intent(in), optional :: petList(:) type(ESMF_Info), intent(in), optional :: info type(ESMF_Config), intent(in), optional :: config type(ESMF_GridComp), intent(out), optional :: comp integer, intent(out), optional :: rcDESCRIPTION:
Create and add a GridComp (i.e. Model, Mediator, or Driver) as a child component to a Driver. The component is created on the provided petList, or by default across all of the Driver PETs.
The specified compSetServicesRoutine() is called back immediately after the new child component has been created internally. Very little around the component is set up at that time (e.g. NUOPC component attributes will not be available). The routine should therefore be very light weight, with the sole purpose of setting the entry points of the component - typically by deriving from a generic component followed by the appropriate specilizations.
If provided, the compSetVMRoutine() is called back before the compSetServicesRoutine(). This allows the child component to set aspects of its own VM, such as threading or the PE distribution among PETs.
The info argument can be used to pass custom attributes to the child component. These attributes are available on the component when compSetVMRoutine() and compSetServicesRoutine() are called. The attributes provided in info are copied onto the child component. This allows the same info object to be used for multiple child components without conflict.
The compLabel must uniquely identify the child component within the context of the Driver component.
If the comp argument is specified, it will reference the newly created component on return.
INTERFACE:
! Private name; call using NUOPC_DriverAddComp() recursive subroutine NUOPC_DriverAddGridCompSO(driver, compLabel, & sharedObj, petList, info, config, comp, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver character(len=*), intent(in) :: compLabel character(len=*), intent(in), optional :: sharedObj integer, intent(in), optional :: petList(:) type(ESMF_Info), intent(in), optional :: info type(ESMF_Config), intent(in), optional :: config type(ESMF_GridComp), intent(out), optional :: comp integer, intent(out), optional :: rcDESCRIPTION:
Create and add a GridComp (i.e. Model, Mediator, or Driver) as a child component to a Driver. The component is created on the provided petList, or by default across all of the Driver PETs.
The SetServices() routine in the sharedObj is called back immediately after the new child component has been created internally. Very little around the component is set up at that time (e.g. NUOPC component attributes will not be available). The routine should therefore be very light weight, with the sole purpose of setting the entry points of the component - typically by deriving from a generic component followed by the appropriate specilizations.
The info argument can be used to pass custom attributes to the child component. These attributes are available on the component when compSetVMRoutine() and compSetServicesRoutine() are called. The attributes provided in info are copied onto the child component. This allows the same info object to be used for multiple child components without conflict.
The compLabel must uniquely identify the child component within the context of the Driver component.
If the comp argument is specified, it will reference the newly created component on return.
INTERFACE:
! Private name; call using NUOPC_DriverAddComp() recursive subroutine NUOPC_DriverAddCplComp(driver, srcCompLabel, & dstCompLabel, compSetServicesRoutine, compSetVMRoutine, petList, info, & config, comp, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver character(len=*), intent(in) :: srcCompLabel character(len=*), intent(in) :: dstCompLabel #if defined (__NVCOMPILER) || defined (__PGI) || defined (ESMF_COMPILER_AOCC) interface recursive subroutine compSetServicesRoutine(cplcomp, rc) use ESMF implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface interface recursive subroutine compSetVMRoutine(cplcomp, rc) use ESMF implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface optional :: compSetVMRoutine #else abstract interface recursive subroutine SetServicesRoutine(cplcomp, rc) use ESMF implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine recursive subroutine SetVMRoutine(cplcomp, rc) use ESMF implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface procedure(SetServicesRoutine) :: compSetServicesRoutine procedure(SetVMRoutine), optional :: compSetVMRoutine #endif integer, target, intent(in), optional :: petList(:) type(ESMF_Info), intent(in), optional :: info type(ESMF_Config), intent(in), optional :: config type(ESMF_CplComp), intent(out), optional :: comp integer, intent(out), optional :: rcDESCRIPTION:
Create and add a CplComp (i.e. Connector) as a child component to a Driver. The component is created on the provided petList, or by default across the union of PETs of the components indicated by srcCompLabel and dstCompLabel.
The specified SetServices() routine is called back immediately after the new child component has been created internally. Very little around the component is set up at that time (e.g. NUOPC component attributes will not be available). The routine should therefore be very light weight, with the sole purpose of setting the entry points of the component - typically by deriving from a generic component followed by the appropriate specilizations.
The info argument can be used to pass custom attributes to the child component. These attributes are available on the component when compSetVMRoutine() and compSetServicesRoutine() are called. The attributes provided in info are copied onto the child component. This allows the same info object to be used for multiple child components without conflict.
The compLabel must uniquely identify the child component within the context of the Driver component.
If the comp argument is specified, it will reference the newly created component on return.
INTERFACE:
! Private name; call using NUOPC_DriverAddRunElement() recursive subroutine NUOPC_DriverAddRunElementMPL(driver, slot, compLabel, & phaseLabel, relaxedflag, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver integer, intent(in) :: slot character(len=*), intent(in) :: compLabel -- The following arguments require argument keyword syntax (e.g. rc=rc). -- character(len=*), intent(in), optional :: phaseLabel logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Add an element associated with a Model, Mediator, or Driver component to the run sequence of the Driver. The component must have been added to the Driver, and associated with compLabel prior to this call.
If phaseLabel was not specified, the first entry in the RunPhaseMap attribute of the referenced component will be used to determine the run phase of the added element.
By default an error is returned if no component is associated with the specified compLabel. This error can be suppressed by setting relaxedflag=.true., and no entry will be added to the run sequence.
The slot number identifies the run sequence time slot in case multiple sequences are available. Slots start counting from 1.
INTERFACE:
! Private name; call using NUOPC_DriverAddRunElement() recursive subroutine NUOPC_DriverAddRunElementCPL(driver, slot, srcCompLabel,& dstCompLabel, phaseLabel, relaxedflag, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver integer, intent(in) :: slot character(len=*), intent(in) :: srcCompLabel character(len=*), intent(in) :: dstCompLabel -- The following arguments require argument keyword syntax (e.g. rc=rc). -- character(len=*), intent(in), optional :: phaseLabel logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Add an element associated with a Connector component to the run sequence of the Driver. The component must have been added to the Driver, and associated with srcCompLabel and dstCompLabel prior to this call.
If phaseLabel was not specified, the first entry in the RunPhaseMap attribute of the referenced component will be used to determine the run phase of the added element.
By default an error is returned if no component is associated with the specified compLabel. This error can be suppressed by setting relaxedflag=.true., and no entry will be added to the run sequence.
The slot number identifies the run sequence time slot in case multiple sequences are available. Slots start counting from 1.
INTERFACE:
! Private name; call using NUOPC_DriverAddRunElement() recursive subroutine NUOPC_DriverAddRunElementL(driver, slot, linkSlot, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver integer, intent(in) :: slot integer, intent(in) :: linkSlot integer, intent(out), optional :: rcDESCRIPTION:
Add an element to the run sequence of the Driver that links to the time slot indicated by linkSlot.
INTERFACE:
recursive subroutine NUOPC_DriverEgestRunSequence(driver, freeFormat, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver type(NUOPC_FreeFormat), intent(out) :: freeFormat integer, intent(out), optional :: rcDESCRIPTION:
Egest the run sequence stored in the driver as a FreeFormat object. It is the caller's responsibility to destroy the created freeFormat object.
INTERFACE:
! Private name; call using NUOPC_DriverGet() recursive subroutine NUOPC_DriverGet(driver, slotCount, parentClock, & importState, exportState, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver integer, intent(out), optional :: slotCount type(ESMF_Clock), intent(out), optional :: parentClock type(ESMF_State), intent(out), optional :: importState type(ESMF_State), intent(out), optional :: exportState integer, intent(out), optional :: rcDESCRIPTION:
Access Driver information.
INTERFACE:
! Private name; call using NUOPC_DriverGetComp() recursive subroutine NUOPC_DriverGetGridComp(driver, compLabel, comp, petList, & importState, exportState, relaxedflag, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver character(len=*), intent(in) :: compLabel type(ESMF_GridComp), intent(out), optional :: comp integer, pointer, optional :: petList(:) type(ESMF_State), intent(out), optional :: importState type(ESMF_State), intent(out), optional :: exportState logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Query the Driver for a GridComp (i.e. Model, Mediator, or Driver) child component that was added under compLabel.
If provided, the petList argument will be associated with the petList that was used to create the referenced component. This is an internal allocation owned by the library. This pointer must not be deallocated by the user!
By default an error is returned if no component is associated with the specified compLabel. This error can be suppressed by setting relaxedflag=.true., and unassociated arguments will be returned.
INTERFACE:
! Private name; call using NUOPC_DriverGetComp() recursive subroutine NUOPC_DriverGetCplComp(driver, srcCompLabel, & dstCompLabel, comp, petList, relaxedflag, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver character(len=*), intent(in) :: srcCompLabel character(len=*), intent(in) :: dstCompLabel type(ESMF_CplComp), intent(out), optional :: comp integer, pointer , optional :: petList(:) logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Query the Driver for a CplComp (i.e. Connector) child component that was added under compLabel.
If provided, the petList argument will be associated with the petList that was used to create the referenced component. This is an internal allocation owned by the library. This pointer must not be deallocated by the user!
By default an error is returned if no component is associated with the specified compLabel. This error can be suppressed by setting relaxedflag=.true., and unassociated arguments will be returned.
INTERFACE:
! Private name; call using NUOPC_DriverGetComp() recursive subroutine NUOPC_DriverGetAllGridComp(driver, compList, petLists, & rc)ARGUMENTS:
type(ESMF_GridComp) :: driver type(ESMF_GridComp), pointer, optional :: compList(:) type(ESMF_PtrInt1D), pointer, optional :: petLists(:) integer, intent(out), optional :: rcDESCRIPTION:
Get all the GridComp (i.e. Model, Mediator, or Driver) child components from a Driver.
The incoming compList and petLists arguments must enter unassociated. This means that the user code must explicitly call nullify() or use the => null() syntax on the variables passed in as the actual arguments.
On return it becomes the responsibility of the caller to deallocate associated compList and petLists arguments:
if (associated(compList)) deallocate(compList) if (associated(petLists)) deallocate(petLists)
Notice that the petLists(i)%ptr members, if associated, are pointing to an internal allocation owned by the library. These pointers must not be deallocated by the user!
INTERFACE:
! Private name; call using NUOPC_DriverGetComp() recursive subroutine NUOPC_DriverGetAllCplComp(driver, compList, petLists, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver type(ESMF_CplComp), pointer :: compList(:) type(ESMF_PtrInt1D), pointer, optional :: petLists(:) integer, intent(out), optional :: rcDESCRIPTION:
Get all the CplComp (i.e. Connector) child components from a Driver.
The incoming compList and petLists arguments must enter unassociated. This means that the user code must explicitly call nullify() or use the => null() syntax on the variables passed in as the actual arguments.
On return it becomes the responsibility of the caller to deallocate associated compList and petLists arguments:
if (associated(compList)) deallocate(compList) if (associated(petLists)) deallocate(petLists)
Notice that the petLists(i)%ptr members, if associated, are pointing to an internal allocation owned by the library. These pointers must not be deallocated by the user!
INTERFACE:
! Private name; call using NUOPC_DriverIngestRunSequence() recursive subroutine NUOPC_DriverIngestRunSequenceFF(driver, freeFormat, & autoAddConnectors, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver type(NUOPC_FreeFormat), intent(in), target :: freeFormat logical, intent(in), optional :: autoAddConnectors integer, intent(out), optional :: rcDESCRIPTION:
Ingest the run sequence from a FreeFormat object and replace the run sequence currently held by the driver. Every line in freeFormat corresponds to either a component run sequence element, or is part of a time loop or alarm block defintion. Anything following a '#' character on a line is considered a comment, and ignored for the purpose of ingesting run sequence elements.
Component run sequence elements define the run method of a single component. The lines are interpreted sequentially, however, components will execute concurrently as long as this is not prevented by data-dependencies or overlapping petLists.
Each line specifies the precise run method phase for a single component instance. For model, mediator, and driver components the format is this:
compLabel [phaseLabel]Here compLabel is the label by which the component instance is known to the driver. It is optionally followed a phaseLabel identifying a specific run phase. An example of calling the run phase of the ATM instance that contains the "fast" processes, and is labeled fast:
ATM fastBy default, i.e. without phaseLabel, the first registered run method of the component is used.
The format for connector components is different. It looks like this:
srcCompLabel -> dstCompLabel [connectionOptions]A connector instance is uniquely known by the two components it connects, i.e. by srcCompLabel and dstCompLabel. The syntax requires that the token -> be specified between source and destination. Optionally connectionOptions can be supplied using the format discussed under section 2.4.5. The connection options are set as attribute ConnectionOptions on the respective connector component.
An example of executing the connector instance that transfers fields from the ATM component to the OCN component, using redistribution for remapping:
ATM -> OCN :remapMethod=redist
By default autoAddConnectors is .false., which means that all components referenced in the freeFormat run sequence, including connectors, must already be available as child components of the driver component. An error will be returned if this is not the case. However, when autoAddConnectors is set to .true., connector components encountered in the run sequence that are no already present in the driver will be added automatically. The default NUOPC_Connector implementation is used for all automatically added connector instances.
Lines that contain a time loop definition have the general format:
@{timeStep|*}[:runDuration] ... ... @Both timeStep and runDuration are numbers in units of seconds. Time loops can be nested and concatenated.
A wildcard "*" character can be specified in place of an actual timeStep number. In this case the timeStep of the associated run clock object is set to be equal to the timeStep of the time loop one level up in the loop nesting hierarchy. If a wildcard time step is used for a single outer time loop in the run sequence, then the associated run clock is identical to the driver clock and must be set explicitly by the driver code, or its parent component.
The runDuration specification is optional. If omitted, the duration of the associated run clock is set to the timeStep of the time loop one level up in the loop nesting hierarchy. This ensures that for a single nested time loop, the loop returns to the parent loop level at the appropriate time.
A simple example of a single time loop with one hour timestep:
@3600 ... ... @Each time loop has its own associated clock object. NUOPC manages these clock objects, i.e. their creation and destruction, as well as startTime, endTime, timeStep adjustments during the execution. The outer most time loop of the run sequence is a special case. It uses the driver clock itself. If a single outer most loop is defined in the run sequence provided by freeFormat, this loop becomes the driver loop level directly. Therefore, setting the timeStep or runDuration for the outer most time loop results modifiying the driver clock itself. However, for cases with concatenated loops on the upper level of the run sequence in freeFormat, a single outer loop is added automatically during ingestion, and the driver clock is used for this loop instead.
A more complex run sequence example, that shows component run sequence elements outside of time loops, a nested time loop, time step wildcards, explicit duration specifications, and concatenated time loops:
@100:800 ATM -> OCN OCN -> ATM ATM OCN @* OCN -> EXTOCN EXTOCN @ @ ATM -> EXTATM EXTATM @100:1000 ATM -> OCN OCN -> ATM ATM OCN @Here the timeStep of the first time loop is explicitly chosen at . The runDuration is explicitly set to . The first time loop steps the current time forward for , for each iteration executing ATM-OCN coupling, followed by the nested loop that calls the OCN -> EXTOCN and EXTOCN components. The nested loop uses a wildcard timeStep and therefore is identical to the parent loop level timeStep of . The nested runDuration is not specified and therefore also defaults to the parent time step of . In other words, the nested loop is executed exactly once for every parent loop iteration.
After the first time loop is exited, and followed by explicit calls to ATM -> EXTAMT and EXTATM components. Finally the second time loop is entered for another runDuration. The timeStep is again explicitly set to . The second time loop only implements ATM-OCN coupling, and no coupling to EXTOCN is implemented. Finally, after the sequence returns to the driver level loop.
Lines that contain an alarm block definition have the general format:
@@{alarmTime|*} ... ... @@The alarmTime is a number in units of seconds, and indicates at which interval the alarm will ring. The first ring time of an alarm is the current time of the parent clock.
Specification of the wildcard character * sets the alarmTime equal to the timeStep of the parentClock.
When an alarm rings, the entire alarm block is executed once.
Nesting of time loops and alarm blocks is supported.
INTERFACE:
! Private name; call using NUOPC_DriverIngestRunSequence() recursive subroutine NUOPC_DriverIngestRunSequenceHC(driver, hconfig, & autoAddConnectors, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver type(ESMF_HConfig), intent(in) :: hconfig logical, intent(in), optional :: autoAddConnectors integer, intent(out), optional :: rcDESCRIPTION:
Ingest the run sequence from a HConfig object and replace the run sequence currently held by the driver. The provided hconfig must be a scalar, or else an error is returned. The scalar is interpreted as a string, broken into lines at the newline character. Each line is subsequently interpreted according to the rules described under the FreeFormat version of the NUOPC_DriverIngestRunSequence() interface.
To preserve newline characters in run sequences expressed in YAML block notation, it is important to use literals indicated by the '|' character in YAML. For example:
# A simple run sequence example as a YAML block literal --- | @900:1800 # comments are ignored MED MED -> ATM # any line can have a comment MED -> OCN ATM OCN ATM -> MED OCN -> MED @
Notice the leading whitespace character(s) on each line of the block literal string. YAML requires at least one (1) leading whitespace character for strings in block notation.
INTERFACE:
recursive subroutine NUOPC_DriverNewRunSequence(driver, slotCount, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver integer, intent(in) :: slotCount integer, intent(out), optional :: rcDESCRIPTION:
Replace the current run sequence of the Driver with a new one that has slotCount slots. Each slot uses its own clock for time keeping.
INTERFACE:
recursive subroutine NUOPC_DriverPrint(driver, orderflag, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver logical, intent(in), optional :: orderflag integer, intent(out), optional :: rcDESCRIPTION:
Print internal Driver information. If orderflag is provided and set to .true., the output is ordered from lowest to highest PET. Setting this flag makes the method collective.
INTERFACE:
! Private name; call using NUOPC_DriverSetRunSequence() recursive subroutine NUOPC_DriverSetRunSequence(driver, slot, clock, alarm, rc)ARGUMENTS:
type(ESMF_GridComp) :: driver integer, intent(in) :: slot type(ESMF_Clock), intent(in) :: clock type(ESMF_Alarm), intent(in), optional :: alarm integer, intent(out), optional :: rcDESCRIPTION:
Set the clock in the run sequence under slot of the Driver.
MODULE:
module NUOPC_ModelBase
DESCRIPTION:
Partial specialization of a component with a default explicit time dependency. Each time the Run method is called the component steps one timeStep forward on the passed in parent
clock. The component flags incompatibility during Run if the current time of the incoming
clock does not match the current time of the internal clock.
SUPER:
ESMF_GridComp
USE DEPENDENCIES:
use ESMF
SETSERVICES:
subroutine SetServices(modelBase, rc) type(ESMF_GridComp) :: modelBase integer, intent(out) :: rc
SEMANTIC SPECIALIZATION LABELS:
MODULE:
module NUOPC_Model
DESCRIPTION:
Model component with a default explicit time dependency. Each time the Run method is called the model integrates one timeStep forward on the passed in parent clock. The internal clock is advanced at the end of each Run call. The component flags incompatibility during Run if the current time of the incoming clock does not match the current time of the internal clock.
SUPER:
NUOPC_ModelBase
USE DEPENDENCIES:
use ESMF
SETSERVICES:
subroutine SetServices(model, rc) type(ESMF_GridComp) :: model integer, intent(out) :: rc
SEMANTIC SPECIALIZATION LABELS:
INTERFACE:
subroutine NUOPC_ModelGet(model, driverClock, modelClock, & importState, exportState, rc)ARGUMENTS:
type(ESMF_GridComp) :: model type(ESMF_Clock), intent(out), optional :: driverClock type(ESMF_Clock), intent(out), optional :: modelClock type(ESMF_State), intent(out), optional :: importState type(ESMF_State), intent(out), optional :: exportState integer, intent(out), optional :: rcDESCRIPTION:
Access Model information.
MODULE:
module NUOPC_Mediator
DESCRIPTION:
Mediator component with a default explicit time dependency. Each time the Run method is called, the time stamp on the imported Fields must match the current time (on both the incoming and internal clock). Before returning, the Mediator time stamps the exported Fields with the same current time, before advancing the internal clock one timeStep forward.
SUPER:
NUOPC_ModelBase
USE DEPENDENCIES:
use ESMF
SETSERVICES:
subroutine SetServices(mediator, rc) type(ESMF_GridComp) :: mediator integer, intent(out) :: rc
SEMANTIC SPECIALIZATION LABELS:
INTERFACE:
subroutine NUOPC_MediatorGet(mediator, driverClock, mediatorClock, & importState, exportState, rc)ARGUMENTS:
type(ESMF_GridComp) :: mediator type(ESMF_Clock), intent(out), optional :: driverClock type(ESMF_Clock), intent(out), optional :: mediatorClock type(ESMF_State), intent(out), optional :: importState type(ESMF_State), intent(out), optional :: exportState integer, intent(out), optional :: rcDESCRIPTION:
Access Mediator information.
MODULE:
module NUOPC_Connector
DESCRIPTION:
Component that makes a unidirectional connection between model, mediator, and or driver components. During initialization field pairing is performed between the import and export side according to section 2.4.2, and paired fields are connected. By default the bilinear regrid method is used during Run to transfer data from the connected import Fields to the connected export Fields.
SUPER:
ESMF_CplComp
USE DEPENDENCIES:
use ESMF
SETSERVICES:
subroutine SetServices(connector, rc) type(ESMF_CplComp) :: connector integer, intent(out) :: rc
SEMANTIC SPECIALIZATION LABELS:
INTERFACE:
subroutine NUOPC_ConnectorGet(connector, srcFields, dstFields, rh, state, & CplSet, cplSetList, srcVM, dstVM, driverClock, rc)ARGUMENTS:
type(ESMF_CplComp) :: connector type(ESMF_FieldBundle), intent(out), optional :: srcFields type(ESMF_FieldBundle), intent(out), optional :: dstFields type(ESMF_RouteHandle), intent(out), optional :: rh type(ESMF_State), intent(out), optional :: state character(*), intent(in), optional :: CplSet character(ESMF_MAXSTR), pointer, optional :: cplSetList(:) type(ESMF_VM), intent(out), optional :: srcVM type(ESMF_VM), intent(out), optional :: dstVM type(ESMF_Clock), intent(out), optional :: driverClock integer, intent(out), optional :: rcDESCRIPTION:
Get parameters from the connector internal state.
The Connector keeps information about the connection that it implements in its internal state. When customizing a Connector, it is often necessary to access and sometimes modify these data objects.
The arguments are:
INTERFACE:
subroutine NUOPC_ConnectorSet(connector, srcFields, dstFields, rh, state, & CplSet, srcVM, dstVM, rc)ARGUMENTS:
type(ESMF_CplComp) :: connector type(ESMF_FieldBundle), intent(in), optional :: srcFields type(ESMF_FieldBundle), intent(in), optional :: dstFields type(ESMF_RouteHandle), intent(in), optional :: rh type(ESMF_State), intent(in), optional :: state character(*), intent(in), optional :: CplSet type(ESMF_VM), intent(in), optional :: srcVM type(ESMF_VM), intent(in), optional :: dstVM integer, intent(out), optional :: rcDESCRIPTION:
Set parameters in the connector internal state.
The Connector keeps information about the connection that it implements in its internal state. When customizing a Connector, it is often necessary to access and sometimes modify these data objects.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAreServicesSet() function NUOPC_GridCompAreServicesSet(comp, rc)RETURN VALUE:
logical :: NUOPC_GridCompAreServicesSetARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if SetServices has been called for comp. Otherwise return .false..
INTERFACE:
! Private name; call using NUOPC_CompAreServicesSet() function NUOPC_CplCompAreServicesSet(comp, rc)RETURN VALUE:
logical :: NUOPC_CplCompAreServicesSetARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if SetServices has been called for comp. Otherwise return .false..
INTERFACE:
! Private name; call using NUOPC_CompAttributeAdd() subroutine NUOPC_GridCompAttributeAdd(comp, attrList, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(len=*), intent(in) :: attrList(:) integer, intent(out), optional :: rcDESCRIPTION:
Add Attributes to the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeAdd() subroutine NUOPC_CplCompAttributeAdd(comp, attrList, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(len=*), intent(in) :: attrList(:) integer, intent(out), optional :: rcDESCRIPTION:
Add Attributes to the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeEgest() subroutine NUOPC_GridCompAttributeEge(comp, freeFormat, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp type(NUOPC_FreeFormat), intent(out) :: freeFormat integer, intent(out), optional :: rcDESCRIPTION:
Egest the Attributes of the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance") as a FreeFormat object. It is the caller's responsibility to destroy the created freeFormat object.
INTERFACE:
! Private name; call using NUOPC_CompAttributeEgest() subroutine NUOPC_CplCompAttributeEge(comp, freeFormat, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp type(NUOPC_FreeFormat), intent(out) :: freeFormat integer, intent(out), optional :: rcDESCRIPTION:
Egest the Attributes of the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance") as a FreeFormat object. It is the caller's responsibility to destroy the created freeFormat object.
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_GridCompAttributeGet(comp, name, value, isPresent, isSet, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp character(*), intent(in) :: name character(*), intent(out) :: value logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance.
This call assumes to find a scalar value. An error is returned otherwise.
This call concverts to a string value, regardless of the actual attribute storage.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_CplCompAttributeGet(comp, name, value, isPresent, isSet, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp character(*), intent(in) :: name character(*), intent(out) :: value logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance.
This call assumes to find a scalar value. An error is returned otherwise.
This call concverts to a string value, regardless of the actual attribute storage.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_GridCompAttributeGetI(comp, name, value, isPresent, isSet, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp character(*), intent(in) :: name integer, intent(out) :: value logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_CplCompAttributeGetI(comp, name, value, isPresent, isSet, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp character(*), intent(in) :: name integer, intent(out) :: value logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_GridCompAttributeGetSL(comp, name, valueList, isPresent, & isSet, itemCount, typekind, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp character(*), intent(in) :: name character(*), intent(out), optional :: valueList(:) logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: itemCount type(ESMF_TypeKind_Flag), intent(out), optional :: typekind integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance. Returns with error if the attribute is not present or not set.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_CplCompAttributeGetSL(comp, name, valueList, isPresent, & isSet, itemCount, typekind, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp character(*), intent(in) :: name character(*), intent(out), optional :: valueList(:) logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: itemCount type(ESMF_TypeKind_Flag), intent(out), optional :: typekind integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance. Returns with error if the attribute is not present or not set.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_GridCompAttributeGetIL(comp, name, valueList, isPresent, & isSet, itemCount, typekind, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp character(*), intent(in) :: name integer, intent(out) :: valueList(:) logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: itemCount type(ESMF_TypeKind_Flag), intent(out), optional :: typekind integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance. Returns with error if the attribute is not present or not set.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeGet() subroutine NUOPC_CplCompAttributeGetIL(comp, name, valueList, isPresent, & isSet, itemCount, typekind, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp character(*), intent(in) :: name integer, intent(out) :: valueList(:) logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: itemCount type(ESMF_TypeKind_Flag), intent(out), optional :: typekind integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of comp using the convention NUOPC and purpose Instance. Returns with error if the attribute is not present or not set.
Unless isPresent and isSet are provided, return with error if the attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_CompAttributeIngest() subroutine NUOPC_GridCompAttributeIng(comp, freeFormat, addFlag, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp type(NUOPC_FreeFormat), intent(in) :: freeFormat logical, intent(in), optional :: addFlag integer, intent(out), optional :: rcDESCRIPTION:
Ingest the Attributes from a FreeFormat object onto the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
Important: Attributes ingested by this method are stored as type character strings, and must be accessed accordingly. Conversion from string into a different data type, e.g. integer or real, is the user's responsibility.
If addFlag is .false. (default), an error will be returned if an attribute is to be ingested that was not previously added to the comp object. If addFlag is .true., all missing attributes will be added by this method automatically as needed.
Each line in freeFormat is of this format:
attributeName = attributeValue
For example:
Verbosity = 0 Profiling = 0 Diagnostic = 0could directly be ingested as Attributes for any instance of the four standard NUOPC component kinds. This is because Verbosity, Profiling, and Diagnostic are pre-defined Attributes of the NUOPC component kinds according to sections 2.3.1, 2.3.2, 2.3.3, and 2.3.4.
When Attributes are specified in freeFormat that are not pre-defined for a specific component kind, they can still be ingested by a component instance using the addFlag=.true. option. For instance:
ModelOutputChoice = 2specifies a user-level Attribute, which is not part of the pre-defined Attributes of any of the standard NUOPC component kinds.
INTERFACE:
! Private name; call using NUOPC_CompAttributeIngest() subroutine NUOPC_CplCompAttributeIng(comp, freeFormat, addFlag, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp type(NUOPC_FreeFormat), intent(in) :: freeFormat logical, intent(in), optional :: addFlag integer, intent(out), optional :: rcDESCRIPTION:
Ingest the Attributes from a FreeFormat object onto the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
Important: Attributes ingested by this method are stored as type character strings, and must be accessed accordingly. Conversion from string into a different data type, e.g. integer or real, is the user's responsibility.
If addFlag is .false. (default), an error will be returned if an attribute is to be ingested that was not previously added to the comp object. If addFlag is .true., all missing attributes will be added by this method automatically as needed.
Each line in freeFormat is of this format:
attributeName = attributeValue
For example:
Verbosity = 0 Profiling = 0 Diagnostic = 0could directly be ingested as Attributes for any instance of the four standard NUOPC component kinds. This is because Verbosity, Profiling, and Diagnostic are pre-defined Attributes of the NUOPC component kinds according to sections 2.3.1, 2.3.2, 2.3.3, and 2.3.4.
When Attributes are specified in freeFormat that are not pre-defined for a specific component kind, they can still be ingested by a component instance using the addFlag=.true. option. For instance:
ModelOutputChoice = 2specifies a user-level Attribute, which is not part of the pre-defined Attributes of any of the standard NUOPC component kinds.
INTERFACE:
! Private name; call using NUOPC_CompAttributeIngest() subroutine NUOPC_GridCompAttributeIngHC(comp, hconfig, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp type(ESMF_HConfig), intent(in) :: hconfig integer, intent(out), optional :: rcDESCRIPTION:
Ingest component attributes from a HConfig object onto the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
The provided hconfig is expected to be a map. An error is returned if this condition is not met. Each key-value pair held by hconfig is added as an attribute to comp. A copy of the source contents is made.
Transfers of scalar, sequence, and map values from hconfig are supported. Maps are treated recursively. Sequences are restricted to scalar elements of the same typekind.
The keys of any map provided by the hconfig object must be of scalar type. Keys are interpreted as strings when transferred as an attribute.
Existing attributes with the same key are overridden by this operation. When attributes are overridden, the typekind of the associated value element is allowed to change.
# A simple YAML definition of standard NUOPC attributes, followed by # component specific attributes. Verbosity: 4609 # decimal representation of explicit bit pattern Profiling: low # pre-defined NUOPC setting Diagnostic: 0 # explicit 0 turns OFF feature CustomSeq1: [1, 2, 3, 4] # sequence of integers CustomSeq2: [1., 2., 3., 4.] # sequence of floats CustomSeq3: [true, false] # sequence of bools CustomType: {k1: [a, aa, aaa], k2: b, k3: c} # complex structure
INTERFACE:
! Private name; call using NUOPC_CompAttributeIngest() subroutine NUOPC_CplCompAttributeIngHC(comp, hconfig, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp type(ESMF_HConfig), intent(in) :: hconfig integer, intent(out), optional :: rcDESCRIPTION:
Ingest component attributes from a HConfig object onto the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
The provided hconfig is expected to be a map. An error is returned if this condition is not met. Each key-value pair held by hconfig is added as an attribute to comp. A copy of the source contents is made.
Transfers of scalar, sequence, and map values from hconfig are supported. Maps are treated recursively. Sequences are restricted to scalar elements of the same typekind.
The keys of any map provided by the hconfig object must be of scalar type. Keys are interpreted as strings when transferred as an attribute.
Existing attributes with the same key are overridden by this operation. When attributes are overridden, the typekind of the associated value element is allowed to change.
# A simple YAML definition of standard NUOPC attributes, followed by # component specific attributes. Verbosity: 4609 # decimal representation of explicit bit pattern Profiling: low # pre-defined NUOPC setting Diagnostic: 0 # explicit 0 turns OFF feature CustomSeq1: [1, 2, 3, 4] # sequence of integers CustomSeq2: [1., 2., 3., 4.] # sequence of floats CustomSeq3: [true, false] # sequence of bools CustomType: {k1: [a, aa, aaa], k2: b, k3: c} # complex structure
INTERFACE:
! Private name; call using NUOPC_CompAttributeReset() subroutine NUOPC_GridCompAttributeReset(comp, attrList, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(len=*), intent(in) :: attrList(:) integer, intent(out), optional :: rcDESCRIPTION:
Reset Attributes on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeReset() subroutine NUOPC_CplCompAttributeReset(comp, attrList, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(len=*), intent(in) :: attrList(:) integer, intent(out), optional :: rcDESCRIPTION:
Reset Attributes on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeSet() subroutine NUOPC_GridCompAttributeSetS(comp, name, value, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(*), intent(in) :: name character(*), intent(in) :: value integer, intent(out), optional :: rcDESCRIPTION:
Set the Attribute name inside of comp on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeSet() subroutine NUOPC_CplCompAttributeSetS(comp, name, value, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(*), intent(in) :: name character(*), intent(in) :: value integer, intent(out), optional :: rcDESCRIPTION:
Set the Attribute name inside of comp on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeSet() subroutine NUOPC_GridCompAttributeSetI(comp, name, value, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(*), intent(in) :: name integer, intent(in) :: value integer, intent(out), optional :: rcDESCRIPTION:
Set the Attribute name inside of comp on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeSet() subroutine NUOPC_CplCompAttributeSetI(comp, name, value, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(*), intent(in) :: name integer, intent(in) :: value integer, intent(out), optional :: rcDESCRIPTION:
Set the Attribute name inside of comp on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeSet() subroutine NUOPC_GridCompAttributeSetSL(comp, name, valueList, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(*), intent(in) :: name character(*), intent(in) :: valueList(:) integer, intent(out), optional :: rcDESCRIPTION:
Set the Attribute name inside of comp on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompAttributeSet() subroutine NUOPC_CplCompAttributeSetSL(comp, name, valueList, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(*), intent(in) :: name character(*), intent(in) :: valueList(:) integer, intent(out), optional :: rcDESCRIPTION:
Set the Attribute name inside of comp on the highest level of the standard NUOPC AttPack hierarchy (convention="NUOPC", purpose="Instance").
INTERFACE:
! Private name; call using NUOPC_CompCheckSetClock() subroutine NUOPC_GridCompCheckSetClock(comp, externalClock, checkTimeStep, & forceTimeStep, rc)ARGUMENTS:
type(ESMF_GridComp), intent(inout) :: comp type(ESMF_Clock), intent(in) :: externalClock logical, intent(in), optional :: checkTimeStep logical, intent(in), optional :: forceTimeStep integer, intent(out), optional :: rcDESCRIPTION:
Compare externalClock to the internal clock of comp to make sure they match in their current time. Also ensure that the time step of the external clock is a multiple of the time step of the internal clock. If both conditions are satisfied then set the stop time of the internal clock so it is reached in one time step of the external clock. Otherwise leave the internal clock unchanged and return with error. The direction of the involved clocks is taking into account. Setting the forceTimeStep argument to .true. forces the timeStep of the externalClock to be used to reset the timeStep of the internal clock.
INTERFACE:
! Private name; call using NUOPC_CompDerive() recursive subroutine NUOPC_GridCompDerive(comp, genericSetServicesRoutine, rc)ARGUMENTS:
type(ESMF_GridComp), intent(in) :: comp interface subroutine genericSetServicesRoutine(gridcomp, rc) use ESMF implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Derive a GridComp (i.e. Model, Mediator, or Driver) from a generic component by calling into the specified SetServices() routine of the generic component. This is typically the first call in the SetServices() routine of the specializing component, and is followed by NUOPC_CompSpecialize() calls.
INTERFACE:
! Private name; call using NUOPC_CompDerive() recursive subroutine NUOPC_CplCompDerive(comp, genericSetServicesRoutine, rc)ARGUMENTS:
type(ESMF_CplComp), intent(in) :: comp interface subroutine genericSetServicesRoutine(cplcomp, rc) use ESMF implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Derive a CplComp (i.e. Connector) from a generic component by calling into the specified SetServices() routine of the generic component. This is typically the first call in the SetServices() routine of the specializing component, and is followed by NUOPC_CompSpecialize() calls.
INTERFACE:
! Private name; call using NUOPC_CompFilterPhaseMap() subroutine NUOPC_GridCompFilterPhaseMap(comp, methodflag, acceptStringList, & rc)ARGUMENTS:
type(ESMF_GridComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag character(len=*), intent(in) :: acceptStringList(:) integer, intent(out), optional :: rcDESCRIPTION:
Filter all PhaseMap entries in a GridComp (i.e. Model, Mediator, or Driver) that do not match any entry in the acceptStringList.
INTERFACE:
! Private name; call using NUOPC_CompFilterPhaseMap() subroutine NUOPC_CplCompFilterPhaseMap(comp, methodflag, acceptStringList, & rc)ARGUMENTS:
type(ESMF_CplComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag character(len=*), intent(in) :: acceptStringList(:) integer, intent(out), optional :: rcDESCRIPTION:
Filter all PhaseMap entries in a CplComp (i.e. Connector) that do not match any entry in the acceptStringList.
INTERFACE:
! Private name; call using NUOPC_CompGet() subroutine NUOPC_GridCompGet(comp, name, verbosity, profiling, diagnostic, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(len=*), intent(out), optional :: name integer, intent(out), optional :: verbosity integer, intent(out), optional :: profiling integer, intent(out), optional :: diagnostic integer, intent(out), optional :: rcDESCRIPTION:
Access information from a GridComp.
INTERFACE:
! Private name; call using NUOPC_CompGet() subroutine NUOPC_CplCompGet(comp, name, verbosity, profiling, diagnostic, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(len=*), intent(out), optional :: name integer, intent(out), optional :: verbosity integer, intent(out), optional :: profiling integer, intent(out), optional :: diagnostic integer, intent(out), optional :: rcDESCRIPTION:
Access information from a CplComp.
INTERFACE:
! Private name; call using NUOPC_CompSearchPhaseMap() subroutine NUOPC_GridCompSearchPhaseMap(comp, methodflag, internalflag, & phaseLabel, phaseIndex, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag logical, intent(in), optional :: internalflag character(len=*), intent(in), optional :: phaseLabel integer, intent(out) :: phaseIndex integer, intent(out), optional :: rcDESCRIPTION:
Search all PhaseMap entries in a GridComp (i.e. Model, Mediator, or Driver) to see if phaseLabel is found. Return the associated ESMF phaseIndex, or -1 if not found. If phaseLabel is not specified, set phaseIndex to the first entry in the PhaseMap, or -1 if there are no entries. The internalflag argument allows to search the internal phase maps of driver components. The default is internalflag=.false..
INTERFACE:
! Private name; call using NUOPC_CompSearchPhaseMap() subroutine NUOPC_CplCompSearchPhaseMap(comp, methodflag, phaseLabel, & phaseIndex, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag character(len=*), intent(in), optional :: phaseLabel integer, intent(out) :: phaseIndex integer, intent(out), optional :: rcDESCRIPTION:
Search all PhaseMap entries in a CplComp (i.e. Connector) to see if phaseLabel is found. Return the associated ESMF phaseIndex, or -1 if not found. If phaseLabel is not specified, set phaseIndex to the first entry in the PhaseMap, or -1 if there are no entries.
INTERFACE:
! Private name; call using NUOPC_CompSearchRevPhaseMap() subroutine NUOPC_GridCompSearchRevPhaseMap(comp, methodflag, internalflag, & phaseIndex, phaseLabel, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag logical, intent(in), optional :: internalflag integer, intent(in), optional :: phaseIndex character(len=*), intent(out) :: phaseLabel integer, intent(out), optional :: rcDESCRIPTION:
Search all PhaseMap entries in a GridComp (i.e. Model, Mediator, or Driver) to see if the ESMF phaseIndex is found. Return the associated phaseLabel, or an empty string if not found. If phaseIndex is not specified, set phaseLabel to the first entry in the PhaseMap, or an empty string if there are no entries. The internalflag argument allows to search the internal phase maps of driver components. The default is internalflag=.false..
INTERFACE:
! Private name; call using NUOPC_CompSearchRevPhaseMap() subroutine NUOPC_CplCompSearchRevPhaseMap(comp, methodflag, phaseIndex, & phaseLabel, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag integer, intent(in), optional :: phaseIndex character(len=*), intent(out) :: phaseLabel integer, intent(out), optional :: rcDESCRIPTION:
Search all PhaseMap entries in a CplComp (i.e. Connector) to see if the ESMF phaseIndex is found. Return the associated phaseLabel, or an empty string if not found. If phaseIndex is not specified, set phaseLabel to the first entry in the PhaseMap, or an empty string if there are no entries.
INTERFACE:
! Private name; call using NUOPC_CompSetClock() subroutine NUOPC_GridCompSetClock(comp, externalClock, stabilityTimeStep, rc)ARGUMENTS:
type(ESMF_GridComp), intent(inout) :: comp type(ESMF_Clock), intent(in) :: externalClock type(ESMF_TimeInterval), intent(in), optional :: stabilityTimeStep integer, intent(out), optional :: rcDESCRIPTION:
Set the component internal clock as a copy of externalClock, but with a timeStep that is less than or equal to the stabilityTimeStep. At the same time ensure that the timeStep of the external clock is a multiple of the timeStep of the internal clock. If the stabilityTimeStep argument is not provided then the internal clock will simply be set as a copy of the external clock.
INTERFACE:
! Private name; call using NUOPC_CompSetEntryPoint() subroutine NUOPC_GridCompSetEntryPoint(comp, methodflag, phaseLabelList, & userRoutine, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag character(len=*), intent(in) :: phaseLabelList(:) interface subroutine userRoutine(gridcomp, importState, exportState, clock, rc) use ESMF_CompMod use ESMF_StateMod use ESMF_ClockMod implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional type(ESMF_State) :: importState ! must not be optional type(ESMF_State) :: exportState ! must not be optional type(ESMF_Clock) :: clock ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Set an entry point for a GridComp (i.e. Model, Mediator, or Driver). Publish the new entry point in the correct PhaseMap component attribute.
Starting with version 8.1.0, the use of this method is deprecated. Components should instead specialize exclusively using the NUOPC_CompSpecialize() method.
INTERFACE:
! Private name; call using NUOPC_CompSetEntryPoint() subroutine NUOPC_CplCompSetEntryPoint(comp, methodflag, phaseLabelList, & userRoutine, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag character(len=*), intent(in) :: phaseLabelList(:) interface subroutine userRoutine(cplcomp, importState, exportState, clock, rc) use ESMF_CompMod use ESMF_StateMod use ESMF_ClockMod implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional type(ESMF_State) :: importState ! must not be optional type(ESMF_State) :: exportState ! must not be optional type(ESMF_Clock) :: clock ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Set an entry point for a CplComp (i.e. Connector). Publish the new entry point in the correct PhaseMap component attribute.
Starting with version 8.1.0, the use of this method is deprecated. Components should instead specialize exclusively using the NUOPC_CompSpecialize() method.
INTERFACE:
! Private name; call using NUOPC_CompSetInternalEntryPoint() subroutine NUOPC_GridCompSetIntEntryPoint(comp, methodflag, phaseLabelList, & userRoutine, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp type(ESMF_Method_Flag), intent(in) :: methodflag character(len=*), intent(in) :: phaseLabelList(:) interface subroutine userRoutine(gridcomp, importState, exportState, clock, rc) use ESMF_CompMod use ESMF_StateMod use ESMF_ClockMod implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional type(ESMF_State) :: importState ! must not be optional type(ESMF_State) :: exportState ! must not be optional type(ESMF_Clock) :: clock ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Set an internal entry point for a GridComp (i.e. Driver). Only Drivers currently utilize internal entry points. Internal entry points allow user specialization on the driver level during initialization and run sequencing.
INTERFACE:
! Private name; call using NUOPC_CompSetServices() recursive subroutine NUOPC_GridCompSetServices(comp, sharedObj, userRc, rc)ARGUMENTS:
type(ESMF_GridComp), intent(inout) :: comp character(len=*), intent(in), optional :: sharedObj integer, intent(out), optional :: userRc integer, intent(out), optional :: rcDESCRIPTION:
Try to find a routine called "SetServices" in the sharedObj file and execute the routine. An attempt is made to find a routine that is close in name to "SetServices", allowing for compiler name mangling, i.e. upper and lower case, as well as trailing underscores.
INTERFACE:
! Private name; call using NUOPC_CompSetVM() recursive subroutine NUOPC_GridCompSetVM(comp, sharedObj, userRc, rc)ARGUMENTS:
type(ESMF_GridComp), intent(inout) :: comp character(len=*), intent(in), optional :: sharedObj integer, intent(out), optional :: userRc integer, intent(out), optional :: rcDESCRIPTION:
Try to find a routine called "SetVM" in the sharedObj file and execute the routine. An attempt is made to find a routine that is close in name to "SetVM", allowing for compiler name mangling, i.e. upper and lower case, as well as trailing underscores.
INTERFACE:
! Private name; call using NUOPC_CompSpecialize() subroutine NUOPC_GridCompSpecialize(comp, specLabel, specPhaseLabel, & specRoutine, rc)ARGUMENTS:
type(ESMF_GridComp) :: comp character(len=*), intent(in) :: specLabel character(len=*), intent(in), optional :: specPhaseLabel interface subroutine specRoutine(gridcomp, rc) use ESMF implicit none type(ESMF_GridComp) :: gridcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Specialize a derived GridComp (i.e. Model, Mediator, or Driver). If specPhaseLabel is specified, the specialization only applies to the associated phase. Otherwise the specialization applies to all phases.
INTERFACE:
! Private name; call using NUOPC_CompSpecialize() subroutine NUOPC_CplCompSpecialize(comp, specLabel, specPhaseLabel, & specRoutine, rc)ARGUMENTS:
type(ESMF_CplComp) :: comp character(len=*), intent(in) :: specLabel character(len=*), intent(in), optional :: specPhaseLabel interface subroutine specRoutine(cplcomp, rc) use ESMF implicit none type(ESMF_CplComp) :: cplcomp ! must not be optional integer, intent(out) :: rc ! must not be optional end subroutine end interface integer, intent(out), optional :: rcDESCRIPTION:
Specialize a derived CplComp (i.e. Connector). If specPhaseLabel is specified, the specialization only applies to the associated phase. Otherwise the specialization applies to all phases.
INTERFACE:
subroutine NUOPC_FieldDictionaryAddEntry(standardName, canonicalUnits, rc)ARGUMENTS:
character(*), intent(in) :: standardName character(*), intent(in) :: canonicalUnits integer, intent(out), optional :: rcDESCRIPTION:
Add an entry to the NUOPC Field dictionary. If necessary the dictionary is first set up.
INTERFACE:
subroutine NUOPC_FieldDictionaryEgest(freeFormat, iofmt, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(out) :: freeFormat type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt integer, intent(out), optional :: rcDESCRIPTION:
Egest the contents of the NUOPC Field dictionary into a FreeFormat object. If I/O format option iofmt is provided and equal to ESMF_IOFMT_YAML, the FreeFormat object will contain the NUOPC Field dictionary expressed in YAML format. Other values for iofmt are ignored and this method behaves as if the optional iofmt argument were missing. In such a case, freeFormat will contain NUOPC Field dictionary entries in the traditional format. It is the caller's responsibility to destroy the created freeFormat object.
INTERFACE:
subroutine NUOPC_FieldDictionaryGetEntry(standardName, canonicalUnits, rc)ARGUMENTS:
character(*), intent(in) :: standardName character(*), intent(out), optional :: canonicalUnits integer, intent(out), optional :: rcDESCRIPTION:
Return the canonical units that the NUOPC Field dictionary associates with the standardName.
INTERFACE:
function NUOPC_FieldDictionaryHasEntry(standardName, rc)RETURN VALUE:
logical :: NUOPC_FieldDictionaryHasEntryARGUMENTS:
character(*), intent(in) :: standardName integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the NUOPC Field dictionary has an entry with the specified standardName, .false. otherwise.
INTERFACE:
function NUOPC_FieldDictionaryMatchSyno(standardName1, standardName2, rc)RETURN VALUE:
logical :: NUOPC_FieldDictionaryMatchSynoARGUMENTS:
character(*), intent(in) :: standardName1 character(*), intent(in) :: standardName2 integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the NUOPC Field dictionary considers standardName1 and standardName2 synonyms, .false. otherwise. Also, if standardName1 and/or standardName2 do not correspond to an existing dictionary entry, .false. will be returned.
INTERFACE:
subroutine NUOPC_FieldDictionarySetSyno(standardNames, rc)ARGUMENTS:
character(*), intent(in) :: standardNames(:) integer, intent(out), optional :: rcDESCRIPTION:
Set all of the elements of the standardNames argument to be considered synonyms by the field dictionary. Every element in standardNames must correspond to the standard name of already existing entries in the field dictionary, or else an error will be returned.
INTERFACE:
! Private name; call using NUOPC_FieldDictionarySetup() subroutine NUOPC_FieldDictionarySetupDefault(rc)ARGUMENTS:
integer, intent(out), optional :: rcDESCRIPTION:
Setup the default NUOPC Field dictionary.
INTERFACE:
! Private name; call using NUOPC_FieldDictionarySetup() subroutine NUOPC_FieldDictionarySetupFile(fileName, rc)ARGUMENTS:
character(len=*), intent(in) :: fileName integer, intent(out), optional :: rcDESCRIPTION:
Setup the NUOPC Field dictionary by reading its content from YAML file. If the NUOPC Field dictionary already exists, remove it and create a new one. This feature requires ESMF built with YAML support. Please see the ESMF User's Guide for details.
INTERFACE:
subroutine NUOPC_FreeFormatAdd(freeFormat, stringList, line, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(inout) :: freeFormat character(len=*), intent(in) :: stringList(:) integer, optional, intent(in) :: line integer, optional, intent(out) :: rcDESCRIPTION:
Add lines to a FreeFormat object. The capacity of freeFormat may increase during this operation. The new lines provided in stringList are added starting at position line. If line is greater than the current lineCount of freeFormat, blank lines are inserted to fill the gap. By default, i.e. without specifying the line argument, the elements in stringList are added to the end of the freeFormat object.
INTERFACE:
! Private name; call using NUOPC_FreeFormatCreate() function NUOPC_FreeFormatCreateDefault(freeFormat, stringList, capacity, rc)RETURN VALUE:
type(NUOPC_FreeFormat) :: NUOPC_FreeFormatCreateDefaultARGUMENTS:
type(NUOPC_FreeFormat), optional, intent(in) :: freeFormat character(len=*), optional, intent(in) :: stringList(:) integer, optional, intent(in) :: capacity integer, optional, intent(out) :: rcDESCRIPTION:
Create a new FreeFormat object, which by default is empty. If freeFormat is provided, then the newly created object starts as a copy of freeFormat. If stringList is provided, then it is added to the end of the newly created object. If capacity is provided, it is used for the initial creation of the newly created FreeFormat object. However, if the freeFormat or stringList arguments are present, the final capacity may be larger than specified by capacity.
INTERFACE:
! Private name; call using NUOPC_FreeFormatCreate() function NUOPC_FreeFormatCreateRead(config, label, relaxedflag, rc)RETURN VALUE:
type(NUOPC_FreeFormat) :: NUOPC_FreeFormatCreateReadARGUMENTS:
type(ESMF_Config) :: config character(len=*), intent(in) :: label logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Create a new FreeFormat object from ESMF_Config object. The config object must exist, and label must reference either a single line or a table attribute within config. The content of the attribute is read and returned in the newly created FreeFormat object.
By default an error is returned if label is not found in config. This error can be suppressed by setting relaxedflag=.true., in which case an empty FreeFormat object is returned.
INTERFACE:
subroutine NUOPC_FreeFormatDestroy(freeFormat, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(inout) :: freeFormat integer, optional, intent(out) :: rcDESCRIPTION:
Destroy a FreeFormat object. All internal memory is deallocated.
INTERFACE:
subroutine NUOPC_FreeFormatGet(freeFormat, lineCount, capacity, stringList, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(in) :: freeFormat integer, optional, intent(out) :: lineCount integer, optional, intent(out) :: capacity character(len=NUOPC_FreeFormatLen), optional, pointer :: stringList(:) integer, optional, intent(out) :: rcDESCRIPTION:
Get information from a FreeFormat object.
INTERFACE:
subroutine NUOPC_FreeFormatGetLine(freeFormat, line, commentChar, lineString, & tokenCount, tokenList, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(in) :: freeFormat integer, intent(in) :: line character, optional, intent(in) :: commentChar character(len=NUOPC_FreeFormatLen), optional, intent(out) :: lineString integer, optional, intent(out) :: tokenCount character(len=NUOPC_FreeFormatLen), optional, intent(out) :: tokenList(:) integer, optional, intent(out) :: rcDESCRIPTION:
Get information about a specific line in a FreeFormat object. If commentChar is specified, anything on the line, starting with commentChar is considered a comment, and subsequently ignored.
INTERFACE:
subroutine NUOPC_FreeFormatLog(freeFormat, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(in) :: freeFormat integer, optional, intent(out) :: rcDESCRIPTION:
Write a FreeFormat object to the default Log.
INTERFACE:
subroutine NUOPC_FreeFormatPrint(freeFormat, rc)ARGUMENTS:
type(NUOPC_FreeFormat), intent(in) :: freeFormat integer, optional, intent(out) :: rcDESCRIPTION:
Print a FreeFormat object.
INTERFACE:
subroutine NUOPC_AddNamespace(state, Namespace, nestedStateName, & nestedState, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state character(len=*), intent(in) :: Namespace character(len=*), intent(in), optional :: nestedStateName type(ESMF_State), intent(out), optional :: nestedState integer, intent(out), optional :: rcDESCRIPTION:
Add a Namespace to state. Namespaces are implemented via nested states. This creates a nested state inside of state. The nested state is returned as nestedState. If provided, nestedStateName will be used to name the newly created nested state. The default name of the nested state is equal to Namespace.
The arguments are:
INTERFACE:
subroutine NUOPC_AddNestedState(state, Namespace, CplSet, nestedStateName, & vm, nestedState, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state character(len=*), intent(in), optional :: Namespace character(len=*), intent(in), optional :: CplSet character(len=*), intent(in), optional :: nestedStateName type(ESMF_VM), intent(in), optional :: vm type(ESMF_State), intent(out), optional :: nestedState integer, intent(out), optional :: rcDESCRIPTION:
Create a nested state inside of state. The arguments Namespace and tt CplSet are used to set NUOPC attributes on the newly created state. The nested state is returned as nestedState. If provided, nestedStateName will be used to name the newly created nested state. The default name of the nested state is equal to Namespace_CplSet, Namespace, or CplSet if the arguments are provided.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Advertise() subroutine NUOPC_AdvertiseField(state, StandardName, Units, & LongName, ShortName, name, TransferOfferGeomObject, SharePolicyField, & SharePolicyGeomObject, vm, field, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state character(*), intent(in) :: StandardName character(*), intent(in), optional :: Units character(*), intent(in), optional :: LongName character(*), intent(in), optional :: ShortName character(*), intent(in), optional :: name character(*), intent(in), optional :: TransferOfferGeomObject character(*), intent(in), optional :: SharePolicyField character(*), intent(in), optional :: SharePolicyGeomObject type(ESMF_VM), intent(in), optional :: vm type(ESMF_Field), intent(out), optional :: field integer, intent(out), optional :: rcDESCRIPTION:
Advertise a field in a state. This creates an empty field and adds it to state. The "StandardName", "Units", "LongName", "ShortName", and "TransferOfferGeomObject" attributes of the field are set according to the provided input..
The call checks the provided information against the NUOPC Field Dictionary to ensure correctness. Defaults are set according to the NUOPC Field Dictionary.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Advertise() subroutine NUOPC_AdvertiseFields(state, StandardNames, & TransferOfferGeomObject, SharePolicyField, SharePolicyGeomObject, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state character(*), intent(in) :: StandardNames(:) character(*), intent(in), optional :: TransferOfferGeomObject character(*), intent(in), optional :: SharePolicyField character(*), intent(in), optional :: SharePolicyGeomObject integer, intent(out), optional :: rcDESCRIPTION:
Advertise a list of fields in a state. This creates a list of empty fields and adds it to the state. The "StandardName", "TransferOfferGeomObject", "SharePolicyField", and "SharePolicyGeomObject" attributes of all the fields are set according to the provided input. The "Units", "LongName", and "ShortName" attributes for each field are set according to the defaults documented under method 3.9.3
The call checks the provided information against the NUOPC Field Dictionary to ensure correctness.
The arguments are:
INTERFACE:
subroutine NUOPC_AdjustClock(clock, maxTimestep, rc)ARGUMENTS:
type(ESMF_Clock) :: clock type(ESMF_TimeInterval), intent(in), optional :: maxTimestep integer, intent(out), optional :: rcDESCRIPTION:
Adjust the clock to have a potentially smaller timestep. The timestep on the incoming clock object is compared to the maxTimestep, and reset to the smaller of the two.
The arguments are:
INTERFACE:
subroutine NUOPC_CheckSetClock(setClock, checkClock, setStartTimeToCurrent, & currTime, forceCurrTime, checkTimeStep, forceTimeStep, rc)ARGUMENTS:
type(ESMF_Clock), intent(inout) :: setClock type(ESMF_Clock), intent(in) :: checkClock logical, intent(in), optional :: setStartTimeToCurrent type(ESMF_Time), intent(in), optional :: currTime logical, intent(in), optional :: forceCurrTime logical, intent(in), optional :: checkTimeStep logical, intent(in), optional :: forceTimeStep integer, intent(out), optional :: rcDESCRIPTION:
By default compare setClock to checkClock to ensure they match in their current time. Further ensure that the timeStep of checkClock is a multiple of the timeStep of setClock. If both conditions are satisfied then the stopTime of the setClock is set one checkClock timeStep, or setClock runDuration, ahead of the current time, which ever is shorter. The direction of checkClock is considered when setting the stopTime.
By default the startTime of the setClock is not modified. However, if setStartTimeToCurrent == .true. the startTime of setClock is set to the currentTime of checkClock.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_GetAttribute() subroutine NUOPC_GetAttributeFieldVal(field, name, value, isPresent, isSet, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field character(*), intent(in) :: name character(*), intent(out) :: value logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of field using the convention NUOPC and purpose Instance.
Unless isPresent and isSet are provided, return with error if the Attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_GetAttribute() subroutine NUOPC_GetAttributeFieldTK(field, name, isPresent, isSet, & itemCount, typekind, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field character(*), intent(in) :: name logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: itemCount type(ESMF_TypeKind_Flag), intent(out), optional :: typekind integer, intent(out), optional :: rcDESCRIPTION:
Query the typekind of the attribute name inside of field using the convention NUOPC and purpose Instance.
Unless isPresent and isSet are provided, return with error if the Attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_GetAttribute() subroutine NUOPC_GetAttributeState(state, name, value, isPresent, isSet, & itemCount, typekind, rc)ARGUMENTS:
type(ESMF_State), intent(in) :: state character(*), intent(in) :: name character(*), intent(out), optional :: value logical, intent(out), optional :: isPresent logical, intent(out), optional :: isSet integer, intent(out), optional :: itemCount type(ESMF_TypeKind_Flag), intent(out), optional :: typekind integer, intent(out), optional :: rcDESCRIPTION:
Access the attribute name inside of state using the convention NUOPC and purpose Instance. Returns with error if the attribute is not present or not set.
Unless isPresent and isSet are provided, return with error if the Attribute is not present or not set, respectively.
The arguments are:
INTERFACE:
subroutine NUOPC_GetStateMemberLists(state, StandardNameList, & ConnectedList, NamespaceList, CplSetList, itemNameList, fieldList, & stateList, nestedFlag, rc)ARGUMENTS:
type(ESMF_State), intent(in) :: state character(ESMF_MAXSTR), pointer, optional :: StandardNameList(:) character(ESMF_MAXSTR), pointer, optional :: ConnectedList(:) character(ESMF_MAXSTR), pointer, optional :: NamespaceList(:) character(ESMF_MAXSTR), pointer, optional :: CplSetList(:) character(ESMF_MAXSTR), pointer, optional :: itemNameList(:) type(ESMF_Field), pointer, optional :: fieldList(:) type(ESMF_State), pointer, optional :: stateList(:) logical, intent(in), optional :: nestedFlag integer, intent(out), optional :: rcDESCRIPTION:
Construct lists containing the StandardNames, field names, and connected status of the fields in state. Return this information in the list arguments. Recursively parse through nested States.
All pointer arguments present must enter this method unassociated. This means that the user code must explicitly call nullify() or use the => null() syntax on the variables passed in as any of the pointer arguments. On return, the pointer arguments may either be unassociated or associated. Consequently the user code must first check the status of any of the returned pointer arguments via the associated() intrinsic before accessing the argument. The responsibility for deallocation of associated pointer arguments transfers to the caller.
The arguments are:
INTERFACE:
subroutine NUOPC_GetStateMemberCount(state, fieldCount, nestedFlag, rc)ARGUMENTS:
type(ESMF_State), intent(in) :: state integer, intent(out), optional :: fieldCount logical, intent(in), optional :: nestedFlag integer, intent(out), optional :: rcDESCRIPTION:
Determine the number of fields in state. By default recursively parse through nested States.
The arguments are:
INTERFACE:
subroutine NUOPC_GetTimestamp(field, isValid, time, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field logical, intent(out), optional :: isValid type(ESMF_Time), intent(out), optional :: time integer, intent(out), optional :: rcDESCRIPTION:
Access the timestamp on field in form of an ESMF_Time object.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IngestPetList() subroutine NUOPC_IngestPetListFF(petList, freeFormat, rc)ARGUMENTS:
integer, allocatable, intent(out) :: petList(:) type(NUOPC_FreeFormat), intent(in), target :: freeFormat integer, intent(out), optional :: rcDESCRIPTION:
Construct a petList from a FreeFormat object.
The arguments are:
For an example, the free format petList definition
"2-5 12 0 15-23"would translate into a petList output of
(/2, 3, 4, 5, 12, 0, 15, 16, 17, 18, 19, 20, 21, 22, 23/)
INTERFACE:
! Private name; call using NUOPC_IngestPetList() subroutine NUOPC_IngestPetListHC(petList, hconfig, rc)ARGUMENTS:
integer, allocatable, intent(out) :: petList(:) type(ESMF_HConfig), intent(in) :: hconfig integer, intent(out), optional :: rcDESCRIPTION:
Construct a petList from a HConfig object.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IsAtTime() function NUOPC_IsAtTimeField(field, time, rc)RETURN VALUE:
logical :: NUOPC_IsAtTimeFieldARGUMENTS:
type(ESMF_Field), intent(in) :: field type(ESMF_Time), intent(in) :: time integer, intent(out), optional :: rcDESCRIPTION:
Returns .true. if field has a timestamp that matches time. Otherwise returns .false.. On PETs with only a proxy instance of the field, .true. is returned regardless of the actual timestamp.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IsAtTime() function NUOPC_IsAtTimeState(state, time, fieldName, count, fieldList, rc)RETURN VALUE:
logical :: NUOPC_IsAtTimeStateARGUMENTS:
type(ESMF_State), intent(in) :: state type(ESMF_Time), intent(in) :: time character(*), intent(in), optional :: fieldName integer, intent(out), optional :: count type(ESMF_Field), allocatable, intent(out), optional :: fieldList(:) integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the field(s) in state have a timestamp that matches time. Otherwise return .false..
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IsConnected() function NUOPC_IsConnectedField(field, rc)RETURN VALUE:
logical :: NUOPC_IsConnectedFieldARGUMENTS:
type(ESMF_Field), intent(in) :: field integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the field is connected. Otherwise return .false..
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IsConnected() function NUOPC_IsConnectedState(state, fieldName, count, rc)RETURN VALUE:
logical :: NUOPC_IsConnectedStateARGUMENTS:
type(ESMF_State), intent(in) :: state character(*), intent(in), optional :: fieldName integer, intent(out), optional :: count integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the field(s) in state are connected. Otherwise return .false..
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IsUpdated() function NUOPC_IsUpdatedField(field, rc)RETURN VALUE:
logical :: NUOPC_IsUpdatedFieldARGUMENTS:
type(ESMF_Field), intent(in) :: field integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the field has its "Updated" attribute set to "true". Otherwise return .false..
The arguments are:
INTERFACE:
! Private name; call using NUOPC_IsUpdated() function NUOPC_IsUpdatedState(state, fieldName, count, rc)RETURN VALUE:
logical :: NUOPC_IsUpdatedStateARGUMENTS:
type(ESMF_State), intent(in) :: state character(*), intent(in), optional :: fieldName integer, intent(out), optional :: count integer, intent(out), optional :: rcDESCRIPTION:
Return .true. if the field(s) in state have the "Updated" attribute set to "true". Otherwise return .false..
The arguments are:
INTERFACE:
subroutine NUOPC_NoOp(gcomp, rc)ARGUMENTS:
type(ESMF_GridComp) :: gcomp integer, intent(out) :: rcDESCRIPTION:
No-Op method with an interface that matches the requirements for a attachable method for ESMF_GridComp objects.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Realize() subroutine NUOPC_RealizeCompleteG(state, grid, fieldName, typekind, & staggerloc, selection, dataFillScheme, field, rc)ARGUMENTS:
type(ESMF_State) :: state type(ESMF_Grid), intent(in) :: grid character(*), intent(in), optional :: fieldName type(ESMF_TypeKind_Flag), intent(in), optional :: typekind type(ESMF_StaggerLoc), intent(in), optional :: staggerloc character(len=*), intent(in), optional :: selection character(len=*), intent(in), optional :: dataFillScheme type(ESMF_Field), intent(out), optional :: field integer, intent(out), optional :: rcDESCRIPTION:
Realize or remove fields inside of state according to selection. All of the fields that are realized are created internally on the same grid object, allocating memory for as many field dimensions as there are grid dimensions.
The type and kind of the created fields is according to argument typekind.
Realized fields are filled with data according to the dataFillScheme argument.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Realize() subroutine NUOPC_RealizeCompleteLS(state, locstream, fieldName, typekind, selection,& dataFillScheme, field, rc)ARGUMENTS:
type(ESMF_State) :: state type(ESMF_LocStream), intent(in) :: locstream character(*), intent(in), optional :: fieldName type(ESMF_TypeKind_Flag), intent(in), optional :: typekind character(len=*), intent(in), optional :: selection character(len=*), intent(in), optional :: dataFillScheme type(ESMF_Field), intent(out), optional :: field integer, intent(out), optional :: rcDESCRIPTION:
Realize or remove fields inside of state according to selection. All of the fields that are realized are created internally on the same locstream object, allocating memory accordingly.
The type and kind of the created fields is according to argument typekind.
Realized fields are filled with data according to the dataFillScheme argument.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Realize() subroutine NUOPC_RealizeCompleteM(state, mesh, fieldName, typekind, & meshloc, selection, dataFillScheme, field, rc)ARGUMENTS:
type(ESMF_State) :: state type(ESMF_Mesh), intent(in) :: mesh character(*), intent(in), optional :: fieldName type(ESMF_TypeKind_Flag), intent(in), optional :: typekind type(ESMF_MeshLoc), intent(in), optional :: meshloc character(len=*), intent(in), optional :: selection character(len=*), intent(in), optional :: dataFillScheme type(ESMF_Field), intent(out), optional :: field integer, intent(out), optional :: rcDESCRIPTION:
Realize or remove fields inside of state according to selection. All of the fields that are realized are created internally on the same mesh object, allocating memory accordingly.
The type and kind of the created fields is according to argument typekind.
Realized fields are filled with data according to the dataFillScheme argument.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Realize() subroutine NUOPC_RealizeField(state, field, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state type(ESMF_Field), intent(in) :: field integer, intent(out), optional :: rcDESCRIPTION:
Realize a previously advertised field in state by replacing the advertised field with field of the same name.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Realize() subroutine NUOPC_RealizeTransfer(state, fieldName, typekind, gridToFieldMap, & ungriddedLBound, ungriddedUBound, totalLWidth, totalUWidth, & realizeOnlyConnected, removeNotConnected, realizeOnlyNotShared, & realizeOnlyNotComplete, field, rc)ARGUMENTS:
type(ESMF_State) :: state character(*), intent(in) :: fieldName type(ESMF_TypeKind_Flag), intent(in), optional :: typekind integer, target, intent(in), optional :: gridToFieldMap(:) integer, target, intent(in), optional :: ungriddedLBound(:) integer, target, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) logical, intent(in), optional :: realizeOnlyConnected logical, intent(in), optional :: removeNotConnected logical, intent(in), optional :: realizeOnlyNotShared logical, intent(in), optional :: realizeOnlyNotComplete type(ESMF_Field), intent(out), optional :: field integer, intent(out), optional :: rcDESCRIPTION:
Realize a field where GeomObject has been set by the NUOPC GeomObject transfer protocol.
The data of the realized field is left uninitialized by this method.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetAttribute() subroutine NUOPC_SetAttributeField(field, name, value, rc)ARGUMENTS:
type(ESMF_Field) :: field character(*), intent(in) :: name character(*), intent(in) :: value integer, intent(out), optional :: rcDESCRIPTION:
Set the attribute name inside of field using the convention NUOPC and purpose Instance.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetAttribute() subroutine NUOPC_SetAttributeState(state, name, value, rc)ARGUMENTS:
type(ESMF_State) :: state character(*), intent(in) :: name character(*), intent(in) :: value integer, intent(out), optional :: rcDESCRIPTION:
Set the attribute name inside of state using the convention NUOPC and purpose Instance.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetTimestamp() subroutine NUOPC_SetTimestampField(field, time, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Time), intent(in) :: time integer, intent(out), optional :: rcDESCRIPTION:
Set the TimeStamp according to time on field.
This call should rarely be needed in user written code.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetTimestamp() subroutine NUOPC_SetTimestampFieldList(fieldList, time, selective, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: fieldList(:) type(ESMF_Time), intent(in) :: time logical, intent(in), optional :: selective integer, intent(out), optional :: rcDESCRIPTION:
Set the TimeStamp according to time on field.
This call should rarely be needed in user written code.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetTimestamp() subroutine NUOPC_SetTimestampFieldListClk(fieldList, clock, selective, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: fieldList(:) type(ESMF_Clock), intent(in) :: clock logical, intent(in), optional :: selective integer, intent(out), optional :: rcDESCRIPTION:
Set the TimeStamp according to time on field.
This call should rarely be needed in user written code.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetTimestamp() subroutine NUOPC_SetTimestampState(state, time, selective, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state type(ESMF_Time), intent(in) :: time logical, intent(in), optional :: selective integer, intent(out), optional :: rcDESCRIPTION:
Set the TimeStamp according to clock on all the fields in state. Depending on selective, all or only some fields may be updated.
This call should rarely be needed in user written code. It is used by the generic Connector.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_SetTimestamp() subroutine NUOPC_SetTimestampStateClk(state, clock, selective, rc)ARGUMENTS:
type(ESMF_State), intent(inout) :: state type(ESMF_Clock), intent(in) :: clock logical, intent(in), optional :: selective integer, intent(out), optional :: rcDESCRIPTION:
Set the TimeStamp according to clock on all the fields in state. Depending on selective, all or only some fields may be updated.
This call should rarely be needed in user written code. It is used by the generic Connector.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Write() subroutine NUOPC_SCRIPWrite(factorList, factorIndexList, fileName, & relaxedflag, rc)ARGUMENTS:
real(ESMF_KIND_R8), intent(in), target :: factorList(:) integer, intent(in), target :: factorIndexList(:,:) character(*), intent(in) :: fileName logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Write the destributed interpolaton matrix provided by factorList and factorIndexList to a SCRIP formatted NetCDF file. Each PET calls with its local list of factors and indices. The call then writes the distributed factors into a single file. If the file already exists, the contents is replaced by this call.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Write() subroutine NUOPC_FactorsWrite(factorList, fileName, rc)ARGUMENTS:
real(ESMF_KIND_R8), pointer :: factorList(:) character(*), intent(in) :: fileName integer, intent(out), optional :: rcDESCRIPTION:
THIS METHOD IS DEPRECATED. Use 3.10.1 instead.
Write the destributed factorList to file. Each PET calls with its local list of factors. The call then writes the distributed factors into a single file. The order of the factors in the file is first by PET, and within each PET the PET-local order is preserved. Changing the number of PETs for the same regrid operation will likely change the order of factors across PETs, and therefore files written will differ.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Write() subroutine NUOPC_FieldWrite(field, fileName, overwrite, status, timeslice, & iofmt, relaxedflag, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field character(*), intent(in) :: fileName logical, intent(in), optional :: overwrite type(ESMF_FileStatus_Flag), intent(in), optional :: status integer, intent(in), optional :: timeslice type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Write the data in field to file under the field's "StandardName" attribute if supported by the iofmt.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Write() subroutine NUOPC_StateWrite(state, fieldNameList, fileNamePrefix, overwrite, & status, timeslice, iofmt, relaxedflag, rc)ARGUMENTS:
type(ESMF_State), intent(in) :: state character(len=*), intent(in), optional :: fieldNameList(:) character(len=*), intent(in), optional :: fileNamePrefix logical, intent(in), optional :: overwrite type(ESMF_FileStatus_Flag), intent(in), optional :: status integer, intent(in), optional :: timeslice type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Write the data of the fields within a state to NetCDF files. Each field is written to an individual file using the "StandardName" attribute as NetCDF attribute.
The arguments are:
INTERFACE:
! Private name; call using NUOPC_Write() subroutine NUOPC_FieldBundleWrite(fieldbundle, fieldNameList, fileNamePrefix, overwrite, & status, timeslice, iofmt, relaxedflag, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle character(len=*), intent(in), optional :: fieldNameList(:) character(len=*), intent(in), optional :: fileNamePrefix logical, intent(in), optional :: overwrite type(ESMF_FileStatus_Flag), intent(in), optional :: status integer, intent(in), optional :: timeslice type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt logical, intent(in), optional :: relaxedflag integer, intent(out), optional :: rcDESCRIPTION:
Write the data of the fields within a fieldbundle to NetCDF files. Each field is written to an individual file using the "StandardName" attribute as NetCDF attribute.
The arguments are:
esmf_support@ucar.edu