Loading...
Searching...
No Matches
HydroCouple::IModelComponent Class Referenceabstract

IModelComponent interface is the core interface in the HydroCouple standard defining a model component. More...

#include <hydrocouple.h>

Inheritance diagram for HydroCouple::IModelComponent:
Collaboration diagram for HydroCouple::IModelComponent:

Public Types

enum class  ComponentStatus : uint8_t {
  Created = 0 ,
  Initializing = 1 ,
  Initialized = 2 ,
  Validating = 3 ,
  Valid = 4 ,
  WaitingForData = 5 ,
  Invalid = 6 ,
  Preparing = 7 ,
  Updating = 8 ,
  Updated = 9 ,
  Checkpointing = 10 ,
  Done = 11 ,
  Finishing = 12 ,
  Finished = 13 ,
  Failed = 14
}
 HydroCouple::ComponentStatus is an enumerator that describes the status of a component over the course of its lifetime. More...
 

Public Member Functions

virtual ~IModelComponent ()=default
 IModelComponent::~IModelComponent destructor.
 
virtual IModelComponentInfo * componentInfo () const =0
 Contains the metadata about this IModelComponent instance.
 
virtual ComponentStatus status () const =0
 Defines current status of the IModelComponent.
 
virtual std::vector< IArgument * > arguments () const =0
 Arguments needed to let the component do its work.
 
virtual std::vector< IInput * > inputs () const =0
 The list of consumer items for which a component can receive values.
 
virtual std::vector< IOutput * > outputs () const =0
 The list of IOutputs for which a component can produce results.
 
virtual std::vector< IComponentDataItem * > results () const =0
 List of the model's output results.
 
virtual std::vector< IComponentDataItem * > states () const =0
 The data items that make up the state carried from one update() to the next.
 
virtual void initialize ()=0
 Initializes the current IModelComponent.
 
virtual std::vector< std::string > validate ()=0
 Validates the populated instance of the IModelComponent.
 
virtual void prepare ()=0
 Prepares the IModelComponent for calls to the update() method.
 
virtual void update (const std::vector< IOutput * > &requiredOutputs={})=0
 This method is called to let the component update itself, thus reaching its next state.
 
virtual void finish ()=0
 finish() must be invoked as the last of any methods in the IModelComponent interface.
 
virtual const IWorkflowComponent * workflow () const =0
 Gets the workflow that this component is part of.
 
virtual void setWorkflow (const IWorkflowComponent *workflow)=0
 Sets the workflow that this component is part of.
 
virtual std::set< Capability > capabilities () const =0
 The set of optional capabilities this component supports.
 
virtual std::vector< ErrorEntry > errors (bool clearAfterRead=false)=0
 Drains this component's diagnostic queue.
 
virtual std::string referenceDirectory () const =0
 Gets the reference directory for this component instance.
 
virtual void setReferenceDirectory (const std::string &referenceDirectory)=0
 setReferenceDirectory Sets the reference directory for this component instance.
 
- Public Member Functions inherited from HydroCouple::IIdentity
virtual ~IIdentity ()=default
 IIdentity::~IIdentity is a virtual destructor.
 
virtual const std::string & id () const =0
 Gets a unique identifier for the entity.
 
- Public Member Functions inherited from HydroCouple::IDescription
virtual ~IDescription ()=default
 IDescription::~IDescription is a virtual destructor.
 
virtual const std::string & caption () const =0
 Gets caption for the entity.
 
virtual void setCaption (const std::string &caption)=0
 Sets caption for the entity.
 
virtual const std::string & description () const =0
 Gets additional descriptive information for the entity.
 
virtual void setDescription (const std::string &description)=0
 Gets additional descriptive information for the entity.
 
- Public Member Functions inherited from HydroCouple::IPropertyChanged
virtual ~IPropertyChanged ()=default
 IPropertyChanged::~IPropertyChanged is a virtual destructor.
 
- Public Member Functions inherited from HydroCouple::ISignal< std::string >
virtual ~ISignal ()=default
 ISignal::~ISignal is a virtual destructor.
 
virtual void connect (const std::shared_ptr< ISlot< Args... > > &slot)=0
 connect is used to connect a slot to the signal.
 
virtual void disconnect (const std::shared_ptr< ISlot< Args... > > &slot)=0
 disconnect is used to disconnect a slot from the signal.
 
virtual void blockSignals (bool block)=0
 blockSignals is used to block signals from being emitted.
 
- Public Member Functions inherited from HydroCouple::ISignal< const std::shared_ptr< IComponentStatusChangeEventArgs > & >
virtual ~ISignal ()=default
 ISignal::~ISignal is a virtual destructor.
 
virtual void connect (const std::shared_ptr< ISlot< Args... > > &slot)=0
 connect is used to connect a slot to the signal.
 
virtual void disconnect (const std::shared_ptr< ISlot< Args... > > &slot)=0
 disconnect is used to disconnect a slot from the signal.
 
virtual void blockSignals (bool block)=0
 blockSignals is used to block signals from being emitted.
 

Additional Inherited Members

- Protected Member Functions inherited from HydroCouple::ISignal< std::string >
virtual void emit (Args... args)=0
 emit is used to emit the signal.
 
- Protected Member Functions inherited from HydroCouple::ISignal< const std::shared_ptr< IComponentStatusChangeEventArgs > & >
virtual void emit (Args... args)=0
 emit is used to emit the signal.
 

Detailed Description

IModelComponent interface is the core interface in the HydroCouple standard defining a model component.

Member Enumeration Documentation

◆ ComponentStatus

enum class HydroCouple::IModelComponent::ComponentStatus : uint8_t
strong

HydroCouple::ComponentStatus is an enumerator that describes the status of a component over the course of its lifetime.

The values are pinned: proxies carry them across processes and the language bindings mirror them, so a value never changes meaning and new statuses are appended.

Enumerator
Created 

The IModelComponent instance has just been created.

This status must and will be followed by HydroCouple::Initializing.

Initializing 

The IModelComponent is initializing itself.

This status will end in a status change to HydroCouple::Initialized or HydroCouple::Failed.

Initialized 

The IModelComponent has successfully initialized itself by calling IModelComponent::initialize().

The connections between its inputs/outputs and those of other components can be established.

Validating 

After links between an IModelComponent's inputs/outputs and those of other components have been established, the IModelComponent is HydroCouple::Validating whether its required input will be available when it updates itself, and whether indeed it will be able to provide the required output during this update.

This Validating status will when the IModelComponent::status() changes to HydroCouple::Valid or HydroCouple::Invalid.

Valid 

The IModelComponent is in a HydroCouple::Valid state.

When updating itself its required input will be available, and it will be able to provide the required output.

WaitingForData 

The IModelComponent wants to update itself, but is not yet able to perform the actual computation, because it is still waiting for input data from other components.

Invalid 

The IModelComponent is in an HydroCouple::Invalid state.

When updating itself not all required input will be available, and/or it will not be able to provide the required output. After the user has modified the connections between the IModelComponent's inputs/outputs and those of other components, the HydroCouple::Validating state can be entered again

Preparing 

The IModelComponent is preparing itself for the first update() and the first IComponentDataItem::getValuesInto() call.

This HydroCouple::Preparing state will end in a status change to HydroCouple::Updated or HydroCouple::Failed.

Updating 

The IModelComponent is updating itself.

It has received all required input data from other components, and is now performing the actual computation. This HydroCouple::Updating state will end in a status change to HydroCouple::Updated, HydroCouple::Done or HydroCouple::Failed.

Updated 

The IModelComponent has successfully updated itself.

Checkpointing 

The IModelComponent is saving or restoring a checkpoint of its state (see ICheckpointableModelComponent).

A save returns to the status it was entered from (HydroCouple::Updated or HydroCouple::Done); a successful restore always lands in HydroCouple::Updated; a failure lands in HydroCouple::Failed.

Done 

The last update process that the IModelComponent performed was the final one.

A next call to the IModelComponent::update() method will leave the IModelComponent's internal state unchanged.

Finishing 

The IModelComponent was requested to perform the actions to be performed before it will either be disposed or re-initialized again.Typical actions would be writing the final result files, close all open files, free memory, etc.

When all required actions have been performed, the status switches to HydroCouple::Created when re-initialization is possible. The status switches to HydroCouple::Finished when the IModelComponent is to be disposed

Finished 

The IModelComponent has successfully performed its finalization actions.

Re-initialization of the IModelComponent instance is not possible and should not be attempted. Instead the instance should be destroyed by its owner, after its connections are dismantled (see the lifetime convention).

What a component releases in this state is its computational resources — solver state, threads, scratch memory. Its data items may remain readable: a component backed by previously recorded results is Finished from the moment it is initialized, and exists precisely so its results() and outputs() can be read afterwards for analysis and visualization. Consumers must therefore not assume that Finished implies unreadable values; a component that genuinely cannot serve values after finalization should say so through its data items.

Failed 

The IModelComponent has encountered an unrecoverable error.

Reachable from every status except Finished: a failure can be detected while the component rests (a proxy whose peer dies while it is Updated). Diagnostics describing the failure must be available from IModelComponent::errors(). From this state the component may be re-initialized by calling initialize() if it supports re-initialization, or finished and disposed via finish().

Constructor & Destructor Documentation

◆ ~IModelComponent()

virtual HydroCouple::IModelComponent::~IModelComponent ( )
virtualdefault

IModelComponent::~IModelComponent destructor.

Here is the call graph for this function:

Member Function Documentation

◆ arguments()

virtual std::vector< IArgument * > HydroCouple::IModelComponent::arguments ( ) const
nodiscardpure virtual

Arguments needed to let the component do its work.

An unmodifiable list of (modifiable) arguments must be returned that is to be used to get information about the arguments and to set argument values.

Validation of changes can be done either when they occur (e.g., using notifications) or when the initialize method is called. Initialize will always be called before any call to the update method of the IModelComponent.

This property must be available as soon is the IModelComponent instance is created Arguments describes the arguments that can be set before the initialize() method is called.

Returns
A list of IArguments for instantiating this component.

◆ capabilities()

virtual std::set< Capability > HydroCouple::IModelComponent::capabilities ( ) const
nodiscardpure virtual

The set of optional capabilities this component supports.

This is the discovery mechanism for every optional interface in the standard (see Capability): an orchestrator consults the set and then dynamic_casts only to what is advertised. A component must list every capability it or its data items implement. Components with no optional capabilities return an empty set. Available in every status, including Created.

Returns
The set of supported Capability values.

◆ componentInfo()

virtual IModelComponentInfo * HydroCouple::IModelComponent::componentInfo ( ) const
nodiscardpure virtual

Contains the metadata about this IModelComponent instance.

Returns
An IModelComponentInfo that provides metadata about a component.

◆ errors()

virtual std::vector< ErrorEntry > HydroCouple::IModelComponent::errors ( bool clearAfterRead = false)
nodiscardpure virtual

Drains this component's diagnostic queue.

The error queue is the normative failure channel (see the error-channel convention): implementations must queue an ErrorEntry for every Warning-or-worse condition, must queue a Severity::Fatal entry whenever status() transitions to HydroCouple::Failed, must queue every message validate() returns, and must queue a Severity::Error entry whenever a bool-returning method returns false. Exceptions may additionally be thrown locally but do not replace the queue, because they cannot cross process, C-ABI, or language boundaries. Available in every status, including Created.

Parameters
[in]clearAfterReadindicates whether the queue is cleared after being read.
Returns
The queued diagnostics in insertion order.

◆ finish()

virtual void HydroCouple::IModelComponent::finish ( )
pure virtual

finish() must be invoked as the last of any methods in the IModelComponent interface.

Legal from HydroCouple::Initialized, HydroCouple::Valid, HydroCouple::Invalid, HydroCouple::Updated, HydroCouple::Done and HydroCouple::Failed, so that a composition can be torn down cleanly from any resting state — including one that never validated or was abandoned before prepare(). A component that has nothing to release in the earlier states simply transitions.

Immediately after the method is invoked, it changes the IModelComponent's status() to HydroCouple::Finishing. Once finishing is complete, the status becomes HydroCouple::Finished if the component cannot be restarted, or HydroCouple::Created if it can.

◆ initialize()

virtual void HydroCouple::IModelComponent::initialize ( )
pure virtual

Initializes the current IModelComponent.

The initialize() method must be invoked before any other method or property in the IModelComponent interface is invoked or accessed, except for arguments(), status(), capabilities(), errors() and componentInfo().

Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Initializing. On success the status becomes HydroCouple::Initialized and id(), caption(), description(), inputs(), outputs() and states() are populated. On failure the status becomes HydroCouple::Failed and a Severity::Fatal entry is queued (see the error-channel convention); an exception may additionally be thrown.

Legal from HydroCouple::Created, HydroCouple::Failed and HydroCouple::Initialized (re-initialization).

Remarks
The method will typically populate the component based on the values specified in its arguments, which can be retrieved with arguments. Settings can be used to read input files, allocate memory, and organize input and output exchange items.

◆ inputs()

virtual std::vector< IInput * > HydroCouple::IModelComponent::inputs ( ) const
nodiscardpure virtual

The list of consumer items for which a component can receive values.

Available from the moment initialize() succeeds: orchestrators wire connections between Initialized and Validating, and providers read their consumers' inputs during every update(). Accessing the list before initialize() is an error (see the error-channel convention). The set of inputs is fixed after initialize(); their values change.

Returns
Non-owning observers of this component's IInput items (see the ownership convention). The vector is a snapshot; the items stay valid until the component is destroyed or re-initialized (see the lifetime convention).

◆ outputs()

virtual std::vector< IOutput * > HydroCouple::IModelComponent::outputs ( ) const
nodiscardpure virtual

The list of IOutputs for which a component can produce results.

Available from the moment initialize() succeeds, under the same rules as inputs().

The list only contains the core IOutput items of the IModelComponent, not the IAdaptedOutput items derived from each IOutput. To get a complete list of outputs, traverse the chain of IAdaptedOutput items that start with the IOutput items returned in the list.

Returns
Non-owning observers of this component's IOutput items; a snapshot, valid until the component is destroyed or re-initialized.

◆ prepare()

virtual void HydroCouple::IModelComponent::prepare ( )
pure virtual

Prepares the IModelComponent for calls to the update() method.

Before prepare() is called, the IModelComponent is not required to honor any request that retrieves values from it. After prepare() has succeeded it must be ready to provide values, and any device-resident buffers it exports must keep a stable address until finish().

Legal from HydroCouple::Valid only. Immediately after the method is invoked the status becomes HydroCouple::Preparing; on success it becomes HydroCouple::Updated (meaning "ready to update, nothing computed yet" — there is no separate Prepared status), on failure HydroCouple::Failed with a queued Severity::Fatal entry.

prepare() is invoked at most once per initialize()/finish() cycle.

◆ referenceDirectory()

virtual std::string HydroCouple::IModelComponent::referenceDirectory ( ) const
nodiscardpure virtual

Gets the reference directory for this component instance.

All relative file paths specified that are associated with this component instance are referenced from this directory. Typically, this will be the directory for the project file for the current composition. Values are typically set from the Composition GUI and can be referenced internally for saving files and writing arguments for the component.

Returns
The reference directory path as a string.
Here is the caller graph for this function:

◆ results()

virtual std::vector< IComponentDataItem * > HydroCouple::IModelComponent::results ( ) const
nodiscardpure virtual

List of the model's output results.

Returns
A list of IComponentDataItem that are the results of the model.
Here is the caller graph for this function:

◆ setReferenceDirectory()

virtual void HydroCouple::IModelComponent::setReferenceDirectory ( const std::string & referenceDirectory)
pure virtual

setReferenceDirectory Sets the reference directory for this component instance.

Parameters
[in]referenceDirectorypath to the reference directory.
Here is the call graph for this function:

◆ setWorkflow()

virtual void HydroCouple::IModelComponent::setWorkflow ( const IWorkflowComponent * workflow)
pure virtual

Sets the workflow that this component is part of.

Parameters
[in]workflowis the workflow that this component is part of.
Here is the call graph for this function:

◆ states()

virtual std::vector< IComponentDataItem * > HydroCouple::IModelComponent::states ( ) const
nodiscardpure virtual

The data items that make up the state carried from one update() to the next.

The prognostic variables — what a checkpoint must capture, what a data-assimilation driver perturbs, what an ensemble generator copies, and what IDifferentiableModelComponent::differentiableStates() is a subset of. Diagnostic quantities that update() recomputes from scratch are not state and belong in results() or outputs(). A component whose update() does not depend on its past returns an empty vector. Items may appear here and in outputs() at once.

Available under the same rules as inputs(): from initialize(); non-owning observers valid until the component is destroyed or re-initialized.

Returns
The state items, in a stable order.

◆ status()

virtual ComponentStatus HydroCouple::IModelComponent::status ( ) const
nodiscardpure virtual

Defines current status of the IModelComponent.

See IModelComponent::ComponentStatus for the possible values.

The first status that a component sets is ComponentStatus::Created, as soon after it has been created. In this status, arguments() is the only property that may be accessed.

Thread-safety: safe to call from any thread at any time; implementations keep the status atomic. A proxy for a remote component updates it from the peer's notifications on whatever thread services the transport.

Returns
The current ComponentStatus of this component.

◆ update()

virtual void HydroCouple::IModelComponent::update ( const std::vector< IOutput * > & requiredOutputs = {})
pure virtual

This method is called to let the component update itself, thus reaching its next state.

Legal from HydroCouple::Updated and HydroCouple::WaitingForData (the retry after a provider has caught up). Immediately after this method is invoked, it changes the component's status() to HydroCouple::Updating.

The type of actions a component takes during update() depends on the type of component. A numerical model that progresses in time will typically compute a time step. A database would typically look at the consumers of its output items, and perform one or more queries to be able to provide the values that the consumers require. A GIS system would typically re-evaluate the values in a grid coverage, so that its output items can provide up-to-date values.

On success the component sets its status to HydroCouple::Updated, or to HydroCouple::Done when this update was the final one. A component that cannot proceed because a provider has not yet produced the values it needs may set HydroCouple::WaitingForData and return; the orchestrator is then responsible for updating the provider and calling update() again. An orchestrator that finds every component of a cycle WaitingForData must declare the composition deadlocked and fail it — no component retries on its own. On failure the status becomes HydroCouple::Failed with a queued Severity::Fatal entry; an exception may additionally be thrown.

Parameters
[in]requiredOutputsis an optional parameter lets the caller specify the specific producer items that should be updated. If the length is 0, the component will at least update its producer items that have consumers, or all its output items, depending on the component's implementation.

◆ validate()

virtual std::vector< std::string > HydroCouple::IModelComponent::validate ( )
nodiscardpure virtual

Validates the populated instance of the IModelComponent.

Legal from HydroCouple::Initialized, HydroCouple::Valid and HydroCouple::Invalid — i.e. after initialize() and after the provider/consumer relations between this component's exchange items and those of other components in the composition have been established; it may be repeated after connections change.

Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Validating; when it has finished the status is either HydroCouple::Valid or HydroCouple::Invalid.

Returns
An empty vector if there are no messages. Messages returned while the status is Valid are informative; while the status is Invalid at least one names a fatal problem. Every returned message is also queued on errors() — Severity::Error when Invalid, Severity::Warning when Valid — so that a proxy forwarding a remote validate() loses nothing.

◆ workflow()

virtual const IWorkflowComponent * HydroCouple::IModelComponent::workflow ( ) const
nodiscardpure virtual

Gets the workflow that this component is part of.

Returns
The IWorkflowComponent that this component belongs to, or nullptr if not part of a workflow.
Here is the caller graph for this function:

The documentation for this class was generated from the following file: