7 Appendix B: Initialize Phase Definition Versions

IMPORTANT: Use of explicit Initialize Phase Definition versions and phase labels is deprecated - this section is provided only for reference for NUOPC caps that still use the IPD syntax. See the section on Semantic Specialization Labels for the preferred method of specializing NUOPC caps.

The interaction between NUOPC compliant components during the initialization process is regulated by the Initialize Phase Definition or IPD. The IPDs are versioned, with a higher version number indicating backward compatibility with all previous versions.

There are two perspectives of looking at the IPD. From the driver perspective the IPD regulates the sequence in which it must call the different phases of the Initialize() routines of its child components. To this end the generic NUOPC_Driver component implements support for IPDs up to a version specified in the API documentation.

The other angle of looking at the IPD is from the driver's child components. From this perspective the IPD assigns specific meaning to each initialize phase. The child components of a driver can be divided into two groups with respect to the meaning the IPD assigns to each initialize phase. In one group are the model, mediator, and driver components, and in the other group are the connector components. Child components publish their available initialize phases through the InitializePhaseMap attribute.

The driver also calls into its own internal initialize methods. This allows the driver to participate in the initialization of its children in a structured fashion. The internal initialization phases of a driver are published via the InternalInitializePhaseMap attribute.

The following tables document the meaning of each initialization phase of the available IPD versions for the child components and for the driver component itself. The phases are listed in the sequence in which the driver calls them.

IPDv00 label	Component	Meaning
IPDv00p1	driver-internal	unspecified by NUOPC
IPDv00p1	models, mediators, drivers	Advertise their import and export Fields.
IPDv00p1	connectors	Construct their CplList Attribute.
IPDv00p2	driver-internal	unspecified by NUOPC
IPDv00p2	models, mediators, drivers	Realize their import and export Fields.
IPDv00p2a	connectors	Set the Connected Attribute on each import and export Field according to the CplList Attribute. Reconcile the import and export States.
IPDv00p2b	connectors	Precompute the RouteHandle.
IPDv00p3	driver-internal	unspecified by NUOPC
IPDv00p3	models, mediators, drivers	Check for compatibility of their Fields' Connected status.
IPDv00p4	driver-internal	unspecified by NUOPC
IPDv00p4	models, mediators, drivers	Handle Field data initialization. Timestamp their export Fields.

IPDv01 label	Component	Meaning
IPDv01p1	driver-internal	unspecified by NUOPC
IPDv01p1	models, mediators, drivers	Advertise their import and export Fields.
IPDv01p1	connectors	Construct their CplList Attribute.
IPDv01p2	driver-internal	Modify the CplList Attributes on the Connectors.
IPDv01p2	models, mediators, drivers	unspecified/unused by NUOPC
IPDv01p2	connectors	Set the Connected Attribute on each import and export Field according to the CplList Attribute.
IPDv01p3	driver-internal	unspecified by NUOPC
IPDv01p3	models, mediators, drivers	Realize their "connected" import and export Fields.
IPDv01p3a	connectors	Reconcile the import and export States.
IPDv01p3b	connectors	Precompute the RouteHandle according to the CplList Attribute.
IPDv01p4	driver-internal	unspecified by NUOPC
IPDv01p4	models, mediators, drivers	Check for compatibility of their Fields' Connected status.
IPDv01p5	driver-internal	unspecified by NUOPC
IPDv01p5	models, mediators, drivers	Handle Field data initialization. Timestamp their export Fields.

IPDv02 label	Component	Meaning
IPDv02p1	driver-internal	unspecified by NUOPC
IPDv02p1	models, mediators, drivers	Advertise their import and export Fields.
IPDv02p1	connectors	Construct their CplList Attribute.
IPDv02p2	driver-internal	Modify the CplList Attributes on the Connectors.
IPDv02p2	models, mediators, drivers	unspecified/unused by NUOPC
IPDv02p2	connectors	Set the Connected Attribute on each import and export Field according to the CplList Attribute.
IPDv02p3	driver-internal	unspecified by NUOPC
IPDv02p3	models, mediators, drivers	Realize their "connected" import and export Fields.
IPDv02p3a	connectors	Reconcile the import and export States.
IPDv02p3b	connectors	Precompute the RouteHandle according to the CplList Attribute.
IPDv02p4	driver-internal	unspecified by NUOPC
IPDv02p4	models, mediators, drivers	Check for compatibility of their Fields' Connected status.
IPDv02p5	driver-internal	unspecified by NUOPC
IPDv02p5	models, mediators, drivers	Handle Field data initialization. Timestamp their export Fields.
A loop is entered over all those model, mediator, driver Components that use IPDv02 and have unsatisfied data dependencies, repeating the following two steps:
Run()	connectors	Loop over all Connectors that connect to the Component that is currently indexed by the outer loop.
IPDv02p5	models, mediators, drivers	Handle Field data initialization. Timestamp their export Fields and set the Updated and InitializeDataComplete Attributes accordingly.
Repeat these two steps until all data dependencies have been statisfied, or a dead-lock situation is detected.

IPDv03 label	Component	Meaning
IPDv03p1	driver-internal	unspecified by NUOPC
IPDv03p1	models, mediators, drivers	Advertise their import and export Fields and set the TransferOfferGeomObject Attribute.
IPDv03p1	connectors	Construct their CplList Attribute.
IPDv03p2	driver-internal	Modify the CplList Attributes on the Connectors.
IPDv03p2	models, mediators, drivers	unspecified/unused by NUOPC
IPDv03p2	connectors	Set the Connected Attribute on each import and export Field according to the CplList Attribute. Set the TransferActionGeomObject Attribute.
IPDv03p3	driver-internal	unspecified by NUOPC
IPDv03p3	models, mediators, drivers	Realize their "connected" import and export Fields that have TransferActionGeomObject equal to "provide".
IPDv03p3	connectors	Transfer the Grid/Mesh/LocStream objects (only DistGrid) for Field pairs that have a provider and an acceptor side.
IPDv03p4	driver-internal	unspecified by NUOPC
IPDv03p4	models, mediators, drivers	Optionally modify the decomposition and distribution information of the accepted Grid/Mesh/LocStream by replacing the DistGrid.
IPDv03p4	connectors	Transfer the full Grid/Mesh/LocStream objects (with coordinates) for Field pairs that have a provider and an acceptor side.
IPDv03p5	driver-internal	unspecified by NUOPC
IPDv03p5	models, mediators, drivers	Realize all Fields that have TransferActionGeomObject equal to "accept" on the transferred Grid/Mesh/LocStream objects.
IPDv03p5a	connectors	Reconcile the import and export States.
IPDv03p5b	connectors	Precompute the RouteHandle according to the CplList Attribute.
IPDv03p6	driver-internal	unspecified by NUOPC
IPDv03p6	models, mediators, drivers	Check compatibility of their Fields' Connected status.
IPDv03p7	driver-internal	unspecified by NUOPC
IPDv03p7	models, mediators, drivers	Handle Field data initialization. Timestamp the export Fields.
A loop is entered over all those model, mediator, driver Components that use IPDv02 and have unsatisfied data dependencies, repeating the following two steps:
Run()	connectors	Loop over all Connectors that connect to the Component that is currently indexed by the outer loop.
IPDv03p7	models, mediators, drivers	Handle Field data initialization. Time stamp the export Fields and set the Updated and InitializeDataComplete Attributes accordingly.
Repeat these two steps until all data dependencies have been statisfied, or a dead-lock situation is detected.

IPDv04 label	Component	Meaning
IPDv04p1	driver-internal	unspecified by NUOPC
IPDv04p1	models, mediators, drivers	Advertise their import and export Fields and set the TransferOfferGeomObject Attribute.
IPDv04p1a	connectors	Consider all connection possibilities for their CplList Attribute.
IPDv04p1b	connectors	Unambiguous construction of their CplList Attribute.
IPDv04p2	driver-internal	Modify the CplList Attributes on the Connectors.
IPDv04p2	models, mediators, drivers	unspecified/unused by NUOPC
IPDv04p2	connectors	Set the Connected Attribute on each import and export Field according to the CplList Attribute. Set the TransferActionGeomObject Attribute.
IPDv04p3	driver-internal	unspecified by NUOPC
IPDv04p3	models, mediators, drivers	Realize their "connected" import and export Fields that have TransferActionGeomObject equal to "provide".
IPDv04p3	connectors	Transfer the Grid/Mesh/LocStream objects (only DistGrid) for Field pairs that have a provider and an acceptor side.
IPDv04p4	driver-internal	unspecified by NUOPC
IPDv04p4	models, mediators, drivers	Optionally modify the decomposition and distribution information of the accepted Grid/Mesh/LocStream by replacing the DistGrid.
IPDv04p4	connectors	Transfer the full Grid/Mesh/LocStream objects (with coordinates) for Field pairs that have a provider and an acceptor side.
IPDv04p5	driver-internal	unspecified by NUOPC
IPDv04p5	models, mediators, drivers	Realize all Fields that have TransferActionGeomObject equal to "accept" on the transferred Grid/Mesh/LocStream objects.
IPDv04p5a	connectors	Reconcile the import and export States.
IPDv04p5b	connectors	Precompute the RouteHandle according to the CplList Attribute.
IPDv04p6	driver-internal	unspecified by NUOPC
IPDv04p6	models, mediators, drivers	Check compatibility of their Fields' Connected status.
IPDv04p7	driver-internal	unspecified by NUOPC
IPDv04p7	models, mediators, drivers	Handle Field data initialization. Timestamp the export Fields.
A loop is entered over all those model, mediator, driver Components that use IPDv02 and have unsatisfied data dependencies, repeating the following two steps:
Run()	connectors	Loop over all Connectors that connect to the Component that is currently indexed by the outer loop.
IPDv04p7	models, mediators, drivers	Handle Field data initialization. Time stamp the export Fields and set the Updated and InitializeDataComplete Attributes accordingly.
Repeat these two steps until all data dependencies have been statisfied, or a dead-lock situation is detected.

IPDv05 label	Component	Meaning
IPDv05p1	driver-internal	Advertise import and export Fields and set the TransferOfferGeomObject Attribute. Optionally set FieldTransferPolicy Attribute on States.
IPDv05p1	models, mediators, drivers	Advertise their import and export Fields and set the TransferOfferGeomObject Attribute. Optionally set FieldTransferPolicy Attribute on States.
IPDv05p1	connectors	Consider FieldTransferPolicy Attribute on import and export States. Advertise Fields to be transferred.
IPDv05p2	driver-internal	Optionally modify import and export States before connectors construct CplList Attribute.
IPDv05p2	models, mediators, drivers	Optionally modify import and export States before connectors construct CplList Attribute.
IPDv05p2a	connectors	Consider all connection possibilities for their CplList Attribute.
IPDv05p2b	connectors	Unambiguous construction of their CplList Attribute.
IPDv05p3	driver-internal	Modify the CplList Attributes on the Connectors.
IPDv05p3	models, mediators, drivers	unspecified/unused by NUOPC
IPDv05p3	connectors	Set the Connected Attribute on each import and export Field according to the CplList Attribute. Set the TransferActionGeomObject Attribute.
IPDv05p4	driver-internal	Realize "connected" import and export Fields that have TransferActionGeomObject equal to "provide".
IPDv05p4	models, mediators, drivers	Realize their "connected" import and export Fields that have TransferActionGeomObject equal to "provide".
IPDv05p4	connectors	Transfer the Grid/Mesh/LocStream objects (only DistGrid) for Field pairs that have a provider and an acceptor side.
IPDv05p5	driver-internal	Optionally modify the decomposition and distribution information of the accepted Grid/Mesh/LocStream by replacing the DistGrid.
IPDv05p5	models, mediators, drivers	Optionally modify the decomposition and distribution information of the accepted Grid/Mesh/LocStream by replacing the DistGrid.
IPDv05p5	connectors	Transfer the full Grid/Mesh/LocStream objects (with coordinates) for Field pairs that have a provider and an acceptor side.
IPDv05p6	driver-internal	Realize all Fields that have TransferActionGeomObject equal to "accept" on the transferred Grid/Mesh/LocStream objects.
IPDv05p6	models, mediators, drivers	Realize all Fields that have TransferActionGeomObject equal to "accept" on the transferred Grid/Mesh/LocStream objects.
IPDv05p6a	connectors	Reconcile the import and export States.
IPDv05p6b	connectors	Precompute the RouteHandle according to the CplList Attribute.
IPDv05p7	driver-internal	unspecified by NUOPC
IPDv05p7	models, mediators, drivers	Check compatibility of their Fields' Connected status.
IPDv05p8	driver-internal	unspecified by NUOPC
IPDv05p8	models, mediators, drivers	Handle Field data initialization. Timestamp the export Fields.
A loop is entered over all those model, mediator, driver Components that use IPDv02 and have unsatisfied data dependencies, repeating the following two steps:
Run()	connectors	Loop over all Connectors that connect to the Component that is currently indexed by the outer loop.
IPDv05p8	models, mediators, drivers	Handle Field data initialization. Time stamp the export Fields and set the Updated and InitializeDataComplete Attributes accordingly.
Repeat these two steps until all data dependencies have been statisfied, or a dead-lock situation is detected.

7.1 NUOPC_Driver IPD implementation

INITIALIZE:

• phase 0: (REQUIRED, NUOPC PROVIDED)
  • Ensure that the InitializePhaseMap and InternalInitializePhaseMap attributes are set consistent with the available NUOPC Initialize Phase Definition (IPD) versions (see section 7 for a precise definition). The default implementation uses IPDv02 for InitializePhaseMap, and sets
    • IPDv02p1 (NUOPC PROVIDED)
    • IPDv02p3 (NUOPC PROVIDED)
    • IPDv02p5 (NUOPC PROVIDED).
    The default implementation uses IPDv05 for InternalInitializePhaseMap, and sets
    • IPDv05p1 (NUOPC PROVIDED)
    • IPDv05p2 (NUOPC PROVIDED)
    • IPDv05p3 (NUOPC PROVIDED)
    • IPDv05p4 (NUOPC PROVIDED)
    • IPDv05p6 (NUOPC PROVIDED)
    • IPDv05p8 (NUOPC PROVIDED).
• phase 1: (REQUIRED, NUOPC PROVIDED)
  • A default Initialize entry point for the higher level (e.g. application level) to initialize the Driver with a single call.
  • Internally calls into the InitializePhaseMap: IPDv02p1, IPDv02p3, IPDv02p5 phases in sequence.

• InitializePhaseMap: IPDv02p1 (NUOPC PROVIDED)
  • Allocate and initialize internal data structures.
  • If the internal clock is not yet set, set the default internal clock to be a copy of the incoming clock, but only if the incoming clock is valid.
  • Required specialization to set component services: label_SetModelServices.
    • Call NUOPC_DriverAddComp() for all Model, Mediator, and Connector components to be added.
    • Optionally replace the default clock.
  • Create States for all of the child GridComps.
  • Create Connectors to/from Driver component itself.
  • Set default run sequence.
  • Execute Initialize phase=0 for all Model, Mediator, and Connector components. This is the method where each component is required to initialize its InitializePhaseMap Attribute.
  • Optional specialization to analyze and modify the InitializePhaseMap Attribute of the child components before the Driver uses it: label_ModifyInitializePhaseMap.
  • Optional specialization to set run sequence: label_SetRunSequence.
  • Drive the initialize sequence for the child components, compatible with up to IPDv05, as documented in section 7, through IPDv05p3.

• InitializePhaseMap: IPDv02p3 (NUOPC PROVIDED)
  • Continue to drive the initialize sequence for the child components, compatible with up to IPDv05, as documented in section 7, through IPDv05p7.

• InitializePhaseMap: IPDv02p5 (NUOPC PROVIDED)
  • Continue to drive the initialize sequence for the child components, compatible with up to IPDv05, as documented in section 7, through IPDv05p8.

• InternalInitializePhaseMap: IPDv05p1 (NUOPC PROVIDED)
  • Request that fields in export and import State of child components are mirrored onto the driver's own import and export States.
  • This includes transferring the associated Grid, Mesh, or LocStream objects.

• InternalInitializePhaseMap: IPDv05p2 (NUOPC PROVIDED)
  • Reset the request of field mirroring.

• InternalInitializePhaseMap: IPDv05p3 (NUOPC PROVIDED)
  • Add the REMAPMETHOD=redist option to all entries in CplList attribute on all Connectors to/from the driver itself.
  • Optional specialization to modify the CplList attribute on all of the Connectors: label_ModifyCplLists.

• InternalInitializePhaseMap: IPDv05p4 (NUOPC PROVIDED)
  • Check that all connected fields in the driver's own import and export State have a producer connection.

• InternalInitializePhaseMap: IPDv05p6 (NUOPC PROVIDED)
  • Complete the allocation of all the fields in the driver's own import and export State.

• InternalInitializePhaseMap: IPDv05p8 (NUOPC PROVIDED)
  • Set the InitializeDataComplete consistent with the data-dependency protocol.

RUN:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • If the incoming clock is valid, set the internal stop time to one time step interval on the incoming clock.
  • Drive the time stepping loop, from current time to stop time, incrementing by time step.
    • For each time step iteration the Model and Connector components Run() methods are being called according to the run sequence.

FINALIZE:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • Execute the Finalize() methods of all Connector components in order.
  • Execute the Finalize() methods of all Model components in order.
  • Optional specialization to finalize custom parts of the component: label_Finalize.
  • Destroy all Model components and their import and export states.
  • Destroy all Connector components.
  • Internal clean-up.

7.2 NUOPC_ModelBase IPD implementation

INITIALIZE:

• phase 0: (REQUIRED, NUOPC PROVIDED)
  • Initialize the InitializePhaseMap Attribute according to the NUOPC Initialize Phase Definition (IPD) version 00 (see section 7 for a precise definition). The default implementation sets the following mapping:
    • IPDv00p1 = 1: (REQUIRED, IMPLEMENTOR PROVIDED)
    • IPDv00p2 = 2: (REQUIRED, IMPLEMENTOR PROVIDED)
    • IPDv00p3 = 3: (REQUIRED, IMPLEMENTOR PROVIDED)
    • IPDv00p4 = 4: (REQUIRED, IMPLEMENTOR PROVIDED)

RUN:

• phase 1: (NUOPC PROVIDED)
  • SPECIALIZATION REQUIRED/PROVIDED: label_SetRunClock to check and set the internal Clock against the incoming Clock.
    • IF (Phase specific specialization present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: By default check that internal Clock and incoming Clock agree on current time and that the time step of the incoming Clock is a multiple of the internal Clock time step. Under these conditions set the internal stop time to one time step interval of the incoming Clock. Otherwise exit with error, flagging an incompatibility.
  • SPECIALIZATION REQUIRED/PROVIDED: label_CheckImport to check Fields in the import State.
    • IF (Phase specific specialization is present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: By default check that all import Fields are at the current time of the internal Clock.
  • Time stepping loop: starting at current time, running to stop time of the internal Clock.
    • Timestamp the Fields in the export State according to the current time of the internal Clock.
    • SPECIALIZATION REQUIRED: label_Advance to execute model or mediation code.
    • SPECIALIZATION OPTIONAL: label_AdvanceClock to advance the current time of the internal Clock. By default (without specialization) advance the current time of the internal Clock according to the time step of the internal Clock.
  • SPECIALIZATION OPTIONAL: label_TimestampExport to timestamp Fields in the export State.

FINALIZE:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • Optional specialization to finalize custom parts of the component: label_Finalize.

7.3 NUOPC_Model IPD implementation

INITIALIZE:

• phase 0: Set Initialize Phase Definition Version (REQUIRED, NUOPC PROVIDED)
  • Initialize the InitializePhaseMap Attribute according to the NUOPC Initialize Phase Definition (IPD) version 00 (see section 7 for a precise definition). The default implementation sets the following mapping:
    • IPDv00p1 = 1: (REQUIRED, IMPLEMENTOR PROVIDED)
      • Advertise Fields in import and export States.
    • IPDv00p2 = 2: (REQUIRED, IMPLEMENTOR PROVIDED)
      • Realize the advertised Fields in import and export States.
    • IPDv00p3 = 3: (REQUIRED, NUOPC PROVIDED)
      • Check compatibility of the Fields' Connected status.
    • IPDv00p4 = 4: (REQUIRED, NUOPC PROVIDED)
      • Handle Field data initialization. Time stamp the export Fields.
• IPDv00p1, IPDv01p1, IPDv02p1, IPDv03p1, IPDv04p1, IPDv05p1: Advertise fields in import and export States (REQUIRED, IMPLEMENTOR PROVIDED)
  • Advertise fields in import/export states using one of the two NUOPC_Advertise methods (3.9.3, 3.9.4). The methods require Standard Names for each field, and the Standard Names must appear in the NUOPC Field Dictionary or a runtime error is generated. NUOPC_Advertise accepts a TransferOfferGeomObject argument which may be one of:
    • “will provide” (default) - The field will provide its own geometric object (i.e., Grid, Mesh, or LocStream)
    • “can provide”- The field can provide its own geometric object, but only if the connected field in the other component will not provide it
    • “cannot provide” - The field cannot provide its own geometric object. It must accept a geometric object from a connected field.
    See section 2.4.6 for more details about transferring geometric objects between NUOPC components. Memory is not allocated for advertised fields, but attributes are set on the field which can be used in later phases, especially for determining if another component can provide and/or consume the advertised field.
• IPDv00p2, IPDv01p3, IPDv02p3, IPDv03p3, IPDv04p3, IPDv05p4: Realize field providing a geometric object (REQUIRED*, IMPLEMENTOR PROVIDED)
  • Realize connected import and export fields that have their TransferActionGeomObject attribute set to “provide”, i.e., that will provide their own geometric object (i.e., Grid, Mesh, or LocStream). “provide” is the default value of TransferActionGeomObject. Realize means an ESMF_Field object is created on a geometric object and memory for the field is allocated or referenced.

    The NUOPC_Realize methods (3.9.21, 3.9.22, 3.9.23, 3.9.24, 3.9.25) are used to realize fields. Only previously advertised fields can be realized and the field's name is used to search the state for the previously advertised field.

    *Note: This phase is not required if all fields are accepting a geometric object.

• IPDv03p4, IPDv04p4, IPDv05p5: Modify decomposition of accepted geometric object (OPTIONAL, IMPLEMENTOR PROVIDED)
  • Optionally modify the decomposition information of any accepted geometric object by replacing the DistGrid. In the case of the Grid geometric object, this can be accomplished by retrieving the Grid (and its DistGrid) from the Field, creating a new DistGrid with modified decomposition, creating a new Grid on the new (modified) DistGrid, and then using ESMF_FieldEmptySet to replace the existing Grid with the new one.

    This phase is useful when accepting a Grid from another component, but when the PET counts differ between components. In this case, a new decomposition needs to be set based on the current processor count.

• IPDv03p5, IPDv04p5, IPDv05p6: Realize fields accepting a geometric object (REQUIRED*, IMPLEMENTOR PROVIDED)
  • Realize connected import and export fields that have their TransferActionGeomObject attribute set to “accept”, i.e., that will accept a geometric object from a connected field in another component. If the generic NUOPC_Connector is used, at this point the full geometric object has already been set in the field and only a call to ESMF_FieldEmptyComplete is required to allocate memory for the field.

    The NUOPC_Realize methods (3.9.21, 3.9.22, 3.9.23, 3.9.24, 3.9.25) are used to realize fields. Only previously advertised fields can be realized and the field's name is used to search the state for the previously advertised field.

    *Note: This phase is not required if all fields are providing a geometric object.

• IPDv00p3, IPDv01p4, IPDv02p4, IPDv03p6, IPDv04p6, IPDv05p7: Verify import fields connected and set clock (NUOPC PROVIDED)
  • If the model internal clock is found to be not set, then set the model internal clock as a copy of the incoming clock.
  • Optional specialization to set the internal clock and/or alarms: label_SetClock.
  • Check compatibility, ensuring all advertised import Fields are connected.
• IPDv00p4, IPDv01p5: Initialize export fields (NUOPC PROVIDED)
  • Optional specialization to initialize export Fields: label_DataInitialize
  • Time stamp Fields in export State for compatibility checking.
• IPDv02p5, IPDv03p7, IPDv04p7, IPDv05p8: Initialize export fields (NUOPC PROVIDED)
  • Optional specialization to initialize export Fields: label_DataInitialize
  • Timestamp Fields in export State for compatibility checking.
  • Set Component metadata used to resolve initialize data dependencies.

RUN:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • SPECIALIZATION REQUIRED/PROVIDED: label_SetRunClock to check and set the internal Clock against the incoming Clock.
    • IF (Phase specific specialization present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: By default check that internal Clock and incoming Clock agree on current time and that the time step of the incoming Clock is a multiple of the internal Clock time step. Under these conditions set the internal stop time to one time step interval of the incoming Clock. Otherwise exit with error, flagging an incompatibility.
  • SPECIALIZATION REQUIRED/PROVIDED: label_CheckImport to check Fields in the import State.
    • IF (Phase specific specialization is present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: By default check that all import Fields are at the current time of the internal Clock.
  • Time stepping loop: starting at current time, running to stop time of the internal Clock.
    • Timestamp the Fields in the export State according to the current time of the internal Clock.
    • SPECIALIZATION REQUIRED: label_Advance to execute model code.
    • SPECIALIZATION OPTIONAL: label_AdvanceClock to advance the current time of the internal Clock. By default (without specialization) advance the current time of the internal Clock according to the time step of the internal Clock.
  • SPECIALIZATION OPTIONAL/PROVIDED: label_TimestampExport to timestamp Fields in the export State.
    • IF (Phase specific specialization present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: Timestamp all Fields in the export State according to the current time of the internal Clock, which now is identical to the stop time of the internal Clock.

FINALIZE:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • Optional specialization to finalize custom parts of the component: label_Finalize.

7.3.1 Initialize Phase Specialization - label_SetClock

OPTIONAL, IMPLEMENTOR PROVIDED
Called from: IPDv00p3, IPDv01p4, IPDv02p4, IPDv03p6, IPDv04p6, IPDv05p7

The specialization method can change aspects of the internal clock, which defaults to a copy of the incoming parent clock. For example, the timeStep size may be changed and/or Alarms may be set on the clock.

The method NUOPC_CompSetClock(comp, externalClock, stabilityTimeStep) (3.6.36) can be used to set the internal clock as a copy of externalClock, but with a timeStep that is less than or equal to the stabilityTimeStep. At the same time it ensures 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.

7.3.2 Initialize Phase Specialization - label_DataInitialize

OPTIONAL, IMPLEMENTOR PROVIDED
Called from: IPDv00p4, IPDv01p5, IPDv02p5, IPDv03p7, IPDv04p7, IPDv05p8

The specialization method should initialize field data in the export state. Fields in the export state will be timestamped automatically by the calling phase for all fields that have the “Updated” attribute set to “true”.

7.3.3 Run Phase Specialization - label_SetRunClock

REQUIRED, NUOPC PROVIDED
Called from: default run phase

A specialization method to check and set the internal clock against the incoming clock. This method is called by the default run phase.

If not overridden, the default method will check that the internal clock and incoming clock agree on the current time and that the time step of the incoming clock is a multiple of the internal clock time step. Under these conditions set the internal stop time to one time step interval of the incoming clock. Otherwise exit with error, flagging an incompatibility.

7.3.4 Run Phase Specialization - label_CheckImport

REQUIRED, NUOPC PROVIDED
Called from: default run phase

A specialization method to verify import fields before advancing in time. If not overridden, the default method verifies that all import fields are at the current time of the internal clock.

7.3.5 Run Phase Specialization - label_Advance

REQUIRED, IMPLEMENTOR PROVIDED
Called from: default run phase

A specialization method that advances the model forward in time by one timestep of the internal clock. This method will be called iteratively by the default run phase until reaching the stop time on the internal clock.

7.3.6 Run Phase Specialization - label_TimestampExport

REQUIRED, NUOPC PROVIDED
Called from: default run phase

A specialization method to set the timestamp on export fields after the model has advanced. If not overridden, the default method sets the timestamp on all export fields to the stop time on the internal clock (which is also now the current model time).

7.3.7 Finalize Phase Specialization - label_Finalize

OPTIONAL, IMPLEMENTOR PROVIDED
Called from: default finalize phase

An optional specialization method for custom finalization code and deallocations of user data structures.

7.4 NUOPC_Mediator IPD implementation

INITIALIZE:

• phase 0: (REQUIRED, NUOPC PROVIDED)
  • Initialize the InitializePhaseMap Attribute according to the NUOPC Initialize Phase Definition (IPD) version 00 (see section 7 for a precise definition). The default implementation sets the following mapping:
    • IPDv00p1 = 1: (REQUIRED, IMPLEMENTOR PROVIDED)
      • Advertise Fields in import and export States.
    • IPDv00p2 = 2: (REQUIRED, IMPLEMENTOR PROVIDED)
      • Realize the advertised Fields in import and export States.
    • IPDv00p3 = 3: (REQUIRED, NUOPC PROVIDED)
      • Check compatibility of the Fields' Connected status.
    • IPDv00p4 = 4: (REQUIRED, NUOPC PROVIDED)
      • Handle Field data initialization. Time stamp the export Fields.
• IPDv00p3, IPDv01p4, IPDv02p4: (NUOPC PROVIDED)
  • Set the Mediator internal clock as a copy of the incoming clock.
  • Check compatibility, ensuring all advertised import Fields are connected.
• IPDv00p4, IPDv01p5: (NUOPC PROVIDED)
  • Optional specialization to initialize export Fields: label_DataInitialize
  • Time stamp Fields in import and export States for compatibility checking.
• IPDv02p5: (NUOPC PROVIDED)
  • Optional specialization to initialize export Fields: label_DataInitialize
  • Time stamp Fields in export State for compatibility checking.
  • Set Component metadata used to resolve initialize data dependencies.

RUN:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • SPECIALIZATION REQUIRED/PROVIDED: label_SetRunClock to check and set the internal Clock against the incoming Clock.
    • IF (Phase specific specialization present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: By default check that internal Clock and incoming Clock agree on current time and that the time step of the incoming Clock is a multiple of the internal Clock time step. Under these conditions set the internal stop time to one time step interval of the incoming Clock. Otherwise exit with error, flagging an incompatibility.
  • SPECIALIZATION REQUIRED/PROVIDED: label_CheckImport to check Fields in the import State.
    • IF (Phase specific specialization is present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: By default check that all import Fields are at the current time of the internal Clock.
  • Time stepping loop: starting at current time, running to stop time of the internal Clock.
    • Timestamp the Fields in the export State according to the current time of the internal Clock.
    • SPECIALIZATION REQUIRED: label_Advance to execute mediation code.
    • SPECIALIZATION OPTIONAL: label_AdvanceClock to advance the current time of the internal Clock. By default (without specialization) advance the current time of the internal Clock according to the time step of the internal Clock.
  • SPECIALIZATION OPTIONAL/PROVIDED: label_TimestampExport to timestamp Fields in the export State.
    • IF (Phase specific specialization present): Execute the phase specific specialization.
    • ELSE: Execute the phase independent specialization. PROVIDED: Timestamp all Fields in the export State according to the current time of the internal Clock when entering the RUN method.

FINALIZE:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • Optional specialization to finalize custom parts of the component: label_Finalize.

7.5 NUOPC_Connector IPD implementation

INITIALIZE:

• phase 0: (REQUIRED, NUOPC PROVIDED)
  • Initialize the InitializePhaseMap Attribute according to the NUOPC Initialize Phase Definition (IPD) version 04 (see section 7 for a precise definition). The default implementation sets the following mapping:
    • IPDv04p1a = phase : (REQUIRED, NUOPC PROVIDED)
    • IPDv04p1b = phase : (REQUIRED, NUOPC PROVIDED)
    • IPDv04p2 = phase : (REQUIRED, NUOPC PROVIDED)
    • IPDv04p3 = phase : (REQUIRED, NUOPC PROVIDED)
    • IPDv04p4 = phase : (REQUIRED, NUOPC PROVIDED)
    • IPDv04p5a = phase : (REQUIRED, NUOPC PROVIDED)
    • IPDv04p5b = phase : (REQUIRED, NUOPC PROVIDED)
• IPDv01p1, IPDv02p1: (NUOPC PROVIDED)
  • Construct a list of matching Field pairs between import and export State based on the StandardName Field metadata.
  • Store this list of StandardName entries in the CplList attribute of the Connector Component metadata.
• IPDv01p2, IPDv02p2: (NUOPC PROVIDED)
  • Allocate and initialize the internal state.
  • Use the CplList attribute to construct srcFields and dstFields FieldBundles in the internal state that hold matched Field pairs.
  • Set the Connected attribute to true in the Field metadata for each Field that is added to the srcFields and dstFields FieldBundles.
• IPDv01p3, IPDv02p3: (NUOPC PROVIDED)
  • Use the CplList attribute to construct srcFields and dstFields FieldBundles in the internal state that hold matched Field pairs.
  • Set the Connected attribute to true in the Field metadata for each Field that is added to the srcFields and dstFields FieldBundles.
  • Optional specialization to precompute a Connector operation: label_ComputeRouteHandle. Simple custom implementations store the precomputed communication RouteHandle in the rh member of the internal state. More complex implementations use the state member in the internal state to store auxiliary Fields, FieldBundles, and RouteHandles.
  • By default (if label_ComputeRouteHandle was not provided) precompute the Connector RouteHandle as a bilinear Regrid operation between srcFields and dstFields, with unmappedaction set to ESMF_UNMAPPEDACTION_IGNORE. The resulting RouteHandle is stored in the rh member of the internal state.

RUN:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • Optional specialization to execute a Connector operation: label_ExecuteRouteHandle. Simple custom implementations access the srcFields, dstFields, and rh members of the internal state to implement the required data transfers. More complex implementations access the state member in the internal state, which holds the auxiliary Fields, FieldBundles, and RouteHandles that potentially were added during the optional label_ComputeRouteHandle method during initialize.
  • By default (if label_ExecuteRouteHandle was not provided) execute the precomputed Connector RouteHandle between srcFields and dstFields.
  • Update the time stamp on the Fields in dstFields to match the time stamp on the Fields in srcFields.

FINALIZE:

• phase 1: (REQUIRED, NUOPC PROVIDED)
  • Optional specialization to release the custom Connector operation: label_ReleaseRouteHandle; or by default, if label_ReleaseRouteHandle was not provided, release the default Connector RouteHandle.
  • Optional specialization to finalize custom parts of the component: label_Finalize.
  • Internal clean-up.