Subsections

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:


RUN:


FINALIZE:

7.2 NUOPC_ModelBase IPD implementation


INITIALIZE:


RUN:


FINALIZE:

7.3 NUOPC_Model IPD implementation


INITIALIZE:


RUN:


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:


RUN:


FINALIZE:

7.5 NUOPC_Connector IPD implementation


INITIALIZE:


RUN:


FINALIZE:

esmf_support@ucar.edu