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	ComponentStatus { Created , Initializing , Initialized , Validating , Valid , WaitingForData , Invalid , Preparing , Updating , Updated , Done , Finishing , Finished , Failed }
	HydroCouple::ComponentStatus is an enumerator that describes the status of a component over the course of its lifetime. More...

Public Member Functions
virtual	~IModelComponent ()=0
	IModelComponent::~IModelComponent destructor. More...

virtual IModelComponentInfo *	componentInfo () const =0
	Contains the metadata about this IModelComponent instance. More...

virtual vector< IArgument * >	arguments () const =0
	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. More...

virtual ComponentStatus	status () const =0
	Defines current status of the IModelComponent. See HydroCouple::Componentstatus for the possible values. More...

virtual vector< IInput * >	inputs () const =0
	The list of consumer items for which a component can recieve values. More...

virtual vector< IOutput * >	outputs () const =0
	The list of IOutputs for which a component can produce results. More...

virtual void	initialize ()=0
	Initializes the current IModelComponent. More...

virtual vector< string >	validate ()=0
	Validates the populated instance of the IModelComponent. More...

virtual void	prepare ()=0
	Prepares the IModelComponent for calls to the Update method. More...

virtual void	update (const vector< IOutput * > &requiredOutputs=vector< IOutput * >())=0
	This method is called to let the component update itself, thus reaching its next state. More...

virtual void	finish ()=0
	The finish() must be invoked as the last of any methods in the IModelComponent interface. More...

virtual const IWorkflowComponent *	workflow () const =0
	workflow is the workflow that this component is part of. More...

virtual void	setWorkflow (const IWorkflowComponent *workflow)=0
	setWorkflow More...

virtual int	mpiNumOfProcesses () const =0
	mpiNumProcesses More...

virtual int	mpiProcessRank () const =0
	mpiProcess is the MPI process/rank of this component. More...

virtual void	mpiSetProcessRank (int processRank)=0
	mpiSetProcess More...

virtual set< int >	mpiAllocatedProcesses () const =0
	mpiAllocatedProcesses are the set of MPI processes/ranks allocated to this component. More...

virtual void	mpiAllocateProcesses (const set< int > &mpiProcessesToAllocate)=0
	mpiAllocateResources allocates the specified MPI processes/ranks to this component. More...

virtual void	mpiClearAllocatedProcesses ()=0
	mpiClearAllocatedProcesses More...

virtual string	referenceDirectory () const =0
	referenceDirectory More...

virtual void	setReferenceDirectory (const string &referenceDirectory)=0
	setReferenceDirectory More...

virtual void	registerComponentStatusChangedListener (const function< void(const shared_ptr< IComponentStatusChangeEventArgs > &)> &statusChangedEventListener)=0
	The registerComponentStatusChangedListener() method registers a listener to be called when the status of the component changes. More...

virtual void	deRegisterComponentStatusChangedListener (const function< void(const shared_ptr< IComponentStatusChangeEventArgs > &)> &statusChangedEventListener)=0
	The deRegisterComponentStatusChangedListener() method deregisters a listener that is called when the status of the component changes. More...

Public Member Functions inherited from HydroCouple::IIdentity
virtual	~IIdentity ()=0
	IIdentity::~IIdentity is a virtual destructor. More...

virtual string	id () const =0
	Gets a unique identifier for the entity. More...

Public Member Functions inherited from HydroCouple::IDescription
virtual	~IDescription ()=0
	IDescription::~IDescription is a virtual destructor. More...

virtual string	caption () const =0
	Gets caption for the entity. More...

virtual void	setCaption (const string &caption)=0
	Sets caption for the entity. More...

virtual string	description () const =0
	Gets additional descriptive information for the entity. More...

virtual void	setDescription (const string &description)=0
	Gets additional descriptive information for the entity. More...

Public Member Functions inherited from HydroCouple::IPropertyChanged
virtual	~IPropertyChanged ()=0
	IPropertyChanged::~IPropertyChanged is a virtual destructor. More...

virtual void	registerPropertyChangedListener (const function< void(const any &, const string &)> &propertyChangedListener)=0
	IPropertyChanged::registerPropertyChangedListener() registers a listener to be called when a property of an object changes. More...

virtual void	deRegisterPropertyChangedListener (const function< void(const any &, const string &propertyName)> &propertyChangedListener)=0
	IPropertyChanged::deRegisterPropertyChangedListener() deregisters a listener that is called when a property of an object changes. More...

Detailed Description

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

Member Enumeration Documentation

◆ ComponentStatus

enum HydroCouple::IModelComponent::ComponentStatus

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

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 HydroCouple::IValueSet::getValue() 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.
Done	The last update process that the IModelComponent performed was the final one. A next call to the HydroCouple::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 disposed, e.g. through the garbage collection mechanism.
Failed	The IModelComponent was requested to perform the actions to be perform 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 back to Created if the IModelComponent supports being re-initialized. If it cannot be re-initialized, it can be released from memory.

Constructor & Destructor Documentation

◆ ~IModelComponent()

virtual HydroCouple::IModelComponent::~IModelComponent ( )

pure virtual

IModelComponent::~IModelComponent destructor.

Member Function Documentation

◆ arguments()

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

pure 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.

◆ componentInfo()

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

pure virtual

Contains the metadata about this IModelComponent instance.

Returns: An IModelComponentInfo that provides metadata about a component.

◆ deRegisterComponentStatusChangedListener()

virtual void HydroCouple::IModelComponent::deRegisterComponentStatusChangedListener ( const function< void(const shared_ptr< IComponentStatusChangeEventArgs > &)> & statusChangedEventListener )

pure virtual

The deRegisterComponentStatusChangedListener() method deregisters a listener that is called when the status of the component changes.

See HydroCouple::ComponentStatus for the possible states.

◆ finish()

virtual void HydroCouple::IModelComponent::finish ( )

pure virtual

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

This method must be accessible after the prepare() method has been invoked. If this method is invoked before the prepare() method has been invoked an exception must be thrown by the IModelComponent.

Immediately after the method is invoked, it changes the IModelComponent's status() to HydroCouple::Finishing. Once the finishing is completed, the component changes its status() to HydroCouple::Finished if it can not 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 the Arguments property.

Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Initializing. When the method is executed and an error occurs, the status of the component will change to HydroCouple::Failed, and an exception will be thrown. If the component initializes succesfully, the status is changed to HydroCouple::Initialized.

When the initialize() method has been finished and the status is HydroCouple::Initialized, the properties Id, Caption, Description, Inputs, Outputs, have been set, and the method validate() can be called.

The initialize() method can be invoked as long as a component is either HydroCouple::Created HydroCouple::Failed, or HydroCouple::Initialized

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 vector<IInput *> HydroCouple::IModelComponent::inputs ( ) const

pure virtual

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

This property must be accessible after the initialize() method has been invoked and until the validate() method has been invoked. If this property is accessed before the initialize() method has been invoked or after the validate() method has been invoked and the IModelComponent cannot handle this an exception must be thrown.

Returns: This method basically returns references to IInputs items. There is no guarantee that the list of objects is not altered by other components after it has been returned. It is the responsibility of the IModelComponent to make sure that such possible alterations do not subsequently corrupt the IModelComponent.

◆ mpiAllocatedProcesses()

virtual set<int> HydroCouple::IModelComponent::mpiAllocatedProcesses ( ) const

pure virtual

mpiAllocatedProcesses are the set of MPI processes/ranks allocated to this component.

Returns

◆ mpiAllocateProcesses()

virtual void HydroCouple::IModelComponent::mpiAllocateProcesses ( const set< int > & mpiProcessesToAllocate )

pure virtual

mpiAllocateResources allocates the specified MPI processes/ranks to this component.

Parameters

mpiProcessesToAllocate are the list of MPI processes/ranks to allocate to this component.

This method must be accessible after the initialize() method has been invoked. If this method is invoked before the initialize() method has been invoked an exception must be thrown.

This method must preferably be called on a processor with rank 0.

◆ mpiClearAllocatedProcesses()

virtual void HydroCouple::IModelComponent::mpiClearAllocatedProcesses ( )

pure virtual

mpiClearAllocatedProcesses

◆ mpiNumOfProcesses()

virtual int HydroCouple::IModelComponent::mpiNumOfProcesses ( ) const

pure virtual

mpiNumProcesses

Returns: Returns the number of MPI processes allocated to this component.

◆ mpiProcessRank()

virtual int HydroCouple::IModelComponent::mpiProcessRank ( ) const

pure virtual

mpiProcess is the MPI process/rank of this component.

Returns: Returns the integer identifier of the MPI process/rank of this component.

◆ mpiSetProcessRank()

virtual void HydroCouple::IModelComponent::mpiSetProcessRank ( int processRank )

pure virtual

mpiSetProcess

Parameters

processRank

◆ outputs()

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

pure virtual

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

This property must be accessible after the initialize() method has been invoked and until the validate() method has been invoked. If this property is accessed before the initialize() method has been invoked or after the validate() method has been invoked and the IModelComponent cannot handle this an exception must be thrown.

The list only contains the core IOutputs of the IModelComponent, not the IAdaptedProducerItem derived from each IOutput (etc.). To get a complete list of producers traverse the chain of IAdaptedProducerItem that start with the IOutput returned in the list.

Returns: This method basically returns references to IOutputs. There is no guarantee that the list of objects is not altered by other components after it has been returned. It is the responsibility of the IModelComponents to make sure that such possible alterations do not subsequently corrupt the IModelComponents.

◆ prepare()

virtual void HydroCouple::IModelComponent::prepare ( )

pure virtual

Prepares the IModelComponent for calls to the Update method.

Before prepare() is called, the IModelComponent are not required to honor any type of action that retrieves values from the IModelComponent. After prepare() is called, the IModelComponent must be ready for providing values.

This method must be accessible after the initialize() method has been invoked and until the finish() method has been invoked. If this property is accessed before the initialize() method has been invoked or after the finish() method has been invoked and the IModelComponent cannot handle this an exception must be thrown.

Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Preparing.

When the method has finished, the status of the IModelComponent has changed to either HydroCouple::Updated or HydroCouple::Failed.

It is only required that the prepare() method can be invoked once. If the prepare() method is invoked more that once and the IModelComponent cannot handle this an exception must be thrown.

◆ referenceDirectory()

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

pure virtual

referenceDirectory

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

◆ registerComponentStatusChangedListener()

virtual void HydroCouple::IModelComponent::registerComponentStatusChangedListener ( const function< void(const shared_ptr< IComponentStatusChangeEventArgs > &)> & statusChangedEventListener )

pure virtual

The registerComponentStatusChangedListener() method registers a listener to be called when the status of the component changes.

See HydroCouple::ComponentStatus for the possible states.

◆ setReferenceDirectory()

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

pure virtual

setReferenceDirectory

sets the reference directory for this component instance.

Parameters

referenceDirectory

◆ setWorkflow()

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

pure virtual

setWorkflow

Parameters

workflow is the workflow that this component is part of.

◆ status()

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

pure virtual

Defines current status of the IModelComponent. See HydroCouple::Componentstatus for the possible values.

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

Returns: the current status of this component

◆ update()

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

pure virtual

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

Immediately after this method is invoked, it changes the component's status() to HydroCouple::Updating.

The type of actions a component takes during the Update method 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 output items can provide up-to-date values.

If the Update method is performed successfully, the component sets its state to HydroCouple::Updated, unless after this update() action the component is at the end of its computation, in which case it will be set its State to HydroCouple::Done. If during the update() method a problem arises, the component sets its state to HydroCouple::Failed, and throws an exception.

Parameters

requiredOutputs is 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 vector<string> HydroCouple::IModelComponent::validate ( )

pure virtual

Validates the populated instance of the IModelComponent.

This method must be accessible after the initialize() method has been invoked and until the finish() method has been invoked. If this property is accessed before the initialize() method has been invoked or after the Finish method has been invoked and the IModelComponent cannot handle this an exception must be thrown.

The method will and must be invoked after the various provider/consumer relations between this component's exchange items and the exchange items of other components present in the composition.

Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Validating.

When the validate() method has finished, the status of the IModelComponent has changed to either Valid or HydroCouple::Invalid.

Returns: Returns an array of strings of length 0 if there are no messages at all. If there are messages while the components status is HydroCouple::Valid, the messages are purely informative. If there are messages while the components status is HydroCouple::Componentstatus. HydroCouple::Invalid when at least one of the messages indicates a fatal error.

◆ workflow()

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

pure virtual

workflow is the workflow that this component is part of.

Returns

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

/home/runner/work/HydroCouple/HydroCouple/HydroCouple/include/hydrocouple.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ ComponentStatus

Constructor & Destructor Documentation

◆ ~IModelComponent()

Member Function Documentation

◆ arguments()

◆ componentInfo()

◆ deRegisterComponentStatusChangedListener()

◆ finish()

◆ initialize()

◆ inputs()

◆ mpiAllocatedProcesses()

◆ mpiAllocateProcesses()

◆ mpiClearAllocatedProcesses()

◆ mpiNumOfProcesses()

◆ mpiProcessRank()

◆ mpiSetProcessRank()

◆ outputs()

◆ prepare()

◆ referenceDirectory()

◆ registerComponentStatusChangedListener()

◆ setReferenceDirectory()

◆ setWorkflow()

◆ status()

◆ update()

◆ validate()

◆ workflow()