3 API

3.1 Generic Component: NUOPC_Driver

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:

• Initialize:
  • label_SetModelServices
    • Optional. By default driver has no child components.
    • Use NUOPC_DriverAddComp() repeatedly to add child components to the driver.
    • Use NUOPC_CompAttributeSet() or NUOPC_CompAttributeIngest() to set attributes on child components.
    • Create and set driver clock with startTime, stopTime, and timeStep, if not done by the driver's parent.
  • label_SetRunSequence
    • Optional. By default drive child components in the sequence they were added.
    • Define and set a RunSequence either by calling NUOPC_DriverIngestRunSequence(), or by using the NUOPC_DriverNewRunSequence() and NUOPC_DriverAddRunElement() API.
  • label_ModifyInitializePhaseMap
    • Optional. By default InitializePhaseMap attributes are not modified.
    • Modify the InitializePhaseMap attribute on the child components as desired. This is very rarely needed.
  • label_ModifyCplLists
    • Optional. By default CplList attributes are not modified.
    • Modify the CplList attribute on the child components as desired. This can be useful to set custom Connection Options for specific Field pairs.
  • label_PreChildrenAdvertise
    • Optional.
    • Allow driver to execute specific code before calling the Advertise phase of its children.
  • label_PostChildrenAdvertise
    • Optional.
    • Allow driver to execute specific code after calling the Advertise phase of its children.
  • label_PreChildrenRealize
    • Optional.
    • Allow driver to execute specific code before calling the Realize phase of its children.
  • label_PostChildrenRealize
    • Optional.
    • Allow driver to execute specific code after calling the Realize phase of its children.
  • label_PreChildrenDataInitialize
    • Optional.
    • Allow driver to execute specific code before calling the DataInitialize phase of its children.
  • label_PostChildrenDataInitialize
    • Optional.
    • Allow driver to execute specific code after calling the DataInitialize phase of its children.
• Run:
  • label_SetRunClock
    • Optional. By default driver clock is left unchanged if the parent component has no valid clock. If there is a valid parent clock, the current time is checked between it and the driver clock. An error is returned if the current time does not agree. Otherwise (current time does agree between both clocks), the driver clock stop time is adjusted to a single time step of the parent clock in the future. This ensures that the driver returns at the appropriate parent time step, even if that might change dynamically during the run.
    • Modify the driver clock before executing RunSequence. This is very rarely needed.
  • label_ExecuteRunSequence
    • Optional. By default use NUOPC generic RunSequence execution.
    • Implement a custom RunSequence execution. This is very rarely needed.
• Finalize:
  • label_Finalize
    • Optional. By default do nothing.
    • Destroy any objects created during Initalize.

3.2 Generic Component: NUOPC_ModelBase

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:

• Initialize:
  • label_Advertise
    • Required in order to advertise fields.
    • Use NUOPC_Advertise() to advertise specific fields in the Import- and ExportState of the component.
    • Alternatively set the FieldTransferPolicy attribute on the Import- and ExportState of the component to request field mirroring.
  • label_ModifyAdvertised
    • Optional. By default do not modify the advertised fields.
    • Mostly used when field mirroring was requested during Advertise.
    • Remove undesired advertised fields in the Import- and ExportState of the component.
    • Adjust attributes e.g. for TransferOffer on advertised fields.
  • label_RealizeProvided
    • Required in order to realize fields.
    • Use NUOPC_Realize() to realize fields previously advertised, and for which this component is responsible for providing the Field allocation and/or the GeomObject.
  • label_AcceptTransfer
    • Optional. By default accept the Distribution of the transferred GeomObjects.
    • Change the distribution of any of the transferred GeomObjects.
  • label_RealizeAccepted
    • Optional. Needed for any fields for which component is accepting the GeomObject.
    • Use NUOPC_Realize() to realize fields previously advertised, and for which this component is accepting the GeomObject.
  • label_SetClock
    • Optional. By default create clock according to time information provided by driver.
    • Adjust and set the component clock.
  • label_DataInitialize
    • Optional. Needed to initialize data, and to participate in resolution of data dependencies between components during initialize.
    • Initialize data in fields.
    • Set NUOPC attributes used for data dependency resolution.
• Run:
  • label_Advance
    • Called every timeStep on the component internal clock.
    • Implement the forward integration of the model.
    • Ensure data in the export fields is updated before returning.
  • label_AdvanceClock
    • Optional. By default the component internal clock is advanced by one internal timeStep at the end of the Advance step.
  • label_CheckImport
    • Optional. By default check the timestamp of all import fields against the current time of the internal clock.
  • label_SetRunClock
    • Optional. By default do not adjust the internal clock when entering Run.
  • label_TimestampExport
    • Optinal. By default timestamp all export fields according to the current time of the component internal clock before returning.
• Finalize:
  • label_Finalize
    • Optional. By default do nothing.
    • Destroy any objects created during Initalize.

3.3 Generic Component: NUOPC_Model

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:

• Initialize:
  • label_Advertise
    • Required in order to advertise fields.
    • Use NUOPC_Advertise() to advertise specific fields in the Import- and ExportState of the component.
    • Alternatively set the FieldTransferPolicy attribute on the Import- and ExportState of the component to request field mirroring.
  • label_ModifyAdvertised
    • Optional. By default do not modify the advertised fields.
    • Mostly used when field mirroring was requested during Advertise.
    • Remove undesired advertised fields in the Import- and ExportState of the component.
    • Adjust attributes e.g. for TransferOffer on advertised fields.
  • label_RealizeProvided
    • Required in order to realize fields.
    • Use NUOPC_Realize() to realize fields previously advertised, and for which this component is responsible for providing the Field allocation and/or the GeomObject.
  • label_AcceptTransfer
    • Optional. By default accept the Distribution of the transferred GeomObjects.
    • Change the distribution of any of the transferred GeomObjects.
  • label_RealizeAccepted
    • Optional. Needed for any fields for which component is accepting the GeomObject.
    • Use NUOPC_Realize() to realize fields previously advertised, and for which this component is accepting the GeomObject.
  • label_SetClock
    • Optional. By default create clock according to time information provided by driver.
    • Adjust and set the component clock.
  • label_DataInitialize
    • Optional. Needed to initialize data, and to participate in resolution of data dependencies between components during initialize.
    • Initialize data in fields.
    • Set NUOPC attributes used for data dependency resolution.
• Run:
  • label_Advance
    • Called every timeStep on the component internal clock.
    • Implement the forward integration of the model.
    • Ensure data in the export fields is updated before returning.
  • label_AdvanceClock
    • Optional. By default the component internal clock is advanced by one internal timeStep at the end of the Advance step.
  • label_CheckImport
    • Optional. By default check the timestamp of all import fields against the current time of the internal clock.
  • label_SetRunClock
    • Optional. By default do not adjust the internal clock when entering Run.
  • label_TimestampExport
    • Optinal. By default timestamp all export fields according to the current time of the component internal clock before returning.
• Finalize:
  • label_Finalize
    • Optional. By default do nothing.
    • Destroy any objects created during Initalize.

3.4 Generic Component: NUOPC_Mediator

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:

• Initialize:
  • label_Advertise
    • Required in order to advertise fields.
    • Use NUOPC_Advertise() to advertise specific fields in the Import- and ExportState of the component.
    • Alternatively set the FieldTransferPolicy attribute on the Import- and ExportState of the component to request field mirroring.
  • label_ModifyAdvertised
    • Optional. By default do not modify the advertised fields.
    • Mostly used when field mirroring was requested during Advertise.
    • Remove undesired advertised fields in the Import- and ExportState of the component.
    • Adjust attributes e.g. for TransferOffer on advertised fields.
  • label_RealizeProvided
    • Required in order to realize fields.
    • Use NUOPC_Realize() to realize fields previously advertised, and for which this component is responsible for providing the Field allocation and/or the GeomObject.
  • label_AcceptTransfer
    • Optional. By default accept the Distribution of the transferred GeomObjects.
    • Change the distribution of any of the transferred GeomObjects.
  • label_RealizeAccepted
    • Optional. Needed for any fields for which component is accepting the GeomObject.
    • Use NUOPC_Realize() to realize fields previously advertised, and for which this component is accepting the GeomObject.
  • label_SetClock
    • Optional. By default create clock according to time information provided by driver.
    • Adjust and set the component clock.
  • label_DataInitialize
    • Optional. Needed to initialize data, and to participate in resolution of data dependencies between components during initialize.
    • Initialize data in fields.
    • Set NUOPC attributes used for data dependency resolution.
• Run:
  • label_Advance
    • Called every timeStep on the component internal clock.
    • Implement the forward integration of the model.
    • Ensure data in the export fields is updated before returning.
  • label_AdvanceClock
    • Optional. By default the component internal clock is advanced by one internal timeStep at the end of the Advance step.
  • label_CheckImport
    • Optional. By default check the timestamp of all import fields against the current time of the internal clock.
  • label_SetRunClock
    • Optional. By default do not adjust the internal clock when entering Run.
  • label_TimestampExport
    • Optinal. By default timestamp all export fields according to the current time of the component internal clock before returning.
• Finalize:
  • label_Finalize
    • Optional. By default do nothing.
    • Destroy any objects created during Initalize.

3.5 Generic Component: NUOPC_Connector

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:

• Initialize:
  • label_ComputeRouteHandle
    • Optional. By default compute routehandles according to CplList attribute.
• Run:
  • label_ExecuteRouteHandle
    • Optional. By default execute routehandles stored in the Connector.
• Finalize:
  • label_ReleaseRouteHandle
    • Optional. By default release routehandles stored in the Connector.
  • label_Finalize
    • Optional. By default do nothing.
    • Destroy any objects created during Initalize.

3.6 General Generic Component Methods

3.7 Field Dictionary Methods

3.8 Free Format Methods

3.9 Utility Routines

3.10 Auxiliary Routines

Auxiliary routines are provided with the NUOPC Layer as a convenience to the user. Typically more work is needed on these methods before considering them NUOPC core functionality.