HydroCouple  1.0.0
Description of the HydroCouple Component-Based Model Coupling Interface Definitions
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  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...
 

Signals

virtual void componentStatusChanged (const QSharedPointer< IComponentStatusChangeEventArgs > &statusChangedEvent)=0
 The componentStatusChanged() function must be implemented as a signal and emitted when Status of the component changes. More...
 
- Signals inherited from HydroCouple::IPropertyChanged
virtual void propertyChanged (const QString &propertyName)=0
 IPropertyChanged::propertyChanged() is called to emit signal/event when property of child class changes. More...
 

Public Member Functions

virtual ~IModelComponent ()
 ~IModelComponent More...
 
virtual int index () const =0
 index More...
 
virtual void setIndex (int index)=0
 setIndex More...
 
virtual IModelComponentInfocomponentInfo () const =0
 Contains the metadata about this IModelComponent instance. More...
 
virtual QList< 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 QList< IInput * > inputs () const =0
 The list of consumer items for which a component can recieve values. More...
 
virtual QList< 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 QList< QString > 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 QList< IOutput * > &requiredOutputs=QList< 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 IWorkflowComponentworkflow () const =0
 workflow 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 QSet< int > mpiAllocatedProcesses () const =0
 mpiAllocatedProcesses are the list of MPI processes/ranks allocated to this component. More...
 
virtual void mpiAllocateProcesses (const QSet< int > &mpiProcessesToAllocate)=0
 mpiAllocateResources More...
 
virtual void mpiClearAllocatedProcesses ()=0
 mpiClearAllocatedProcesses More...
 
virtual int gpuPlatform (int mpiProcess) const =0
 gpuPlatform More...
 
virtual int gpuDevice (int mpiProcess) const =0
 gpuDevice More...
 
virtual int gpuMaxNumBlocksOrWorkGrps (int mpiProcess) const =0
 maxNumGPUBlocksOrWorkGrps specified the maximum number of CUDA blocks or OpenCL workgroups allocated for the specified MPI Process. More...
 
virtual void gpuAllocatedResources (int mpiProcess, int gpuPlatform, int gpuDevice, int maxNumGPUBlocksOrWorkGrps)=0
 gpuAllocatedResources More...
 
virtual void gpuClearAllocatedResources ()=0
 gpuClearAllocatedResources More...
 
virtual QString referenceDirectory () const =0
 referenceDirectory More...
 
virtual void setReferenceDirectory (const QString &referenceDirectory)=0
 setReferenceDirectory More...
 
- Public Member Functions inherited from HydroCouple::IIdentity
virtual ~IIdentity ()
 
virtual QString id () const =0
 Gets a unique identifier for the entity. More...
 
- Public Member Functions inherited from HydroCouple::IDescription
virtual ~IDescription ()
 
virtual QString caption () const =0
 Gets caption for the entity. More...
 
virtual void setCaption (const QString &caption)=0
 Sets caption for the entity. More...
 
virtual QString description () const =0
 Gets additional descriptive information for the entity. More...
 
virtual void setDescription (const QString &description)=0
 Gets additional descriptive information for the entity. More...
 
- Public Member Functions inherited from HydroCouple::IPropertyChanged
virtual ~IPropertyChanged ()
 

Detailed Description

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

Member Enumeration Documentation

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 succesfully initialized itself by calliing 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 succesfully 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-intialized 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

virtual HydroCouple::IModelComponent::~IModelComponent ( )
inlinevirtual

~IModelComponent

Member Function Documentation

virtual QList<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.
virtual IModelComponentInfo* HydroCouple::IModelComponent::componentInfo ( ) const
pure virtual

Contains the metadata about this IModelComponent instance.

Returns
An IModelComponentInfo that provides metadata about a component.
virtual void HydroCouple::IModelComponent::componentStatusChanged ( const QSharedPointer< IComponentStatusChangeEventArgs > &  statusChangedEvent)
pure virtualsignal

The componentStatusChanged() function must be implemented as a signal and emitted when Status of the component changes.

See HydroCouple::ComponentStatus for the possible states.

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.

virtual void HydroCouple::IModelComponent::gpuAllocatedResources ( int  mpiProcess,
int  gpuPlatform,
int  gpuDevice,
int  maxNumGPUBlocksOrWorkGrps 
)
pure virtual

gpuAllocatedResources

Parameters
mpiProcess
gpuPlatform
gpuDevice
maxNumGPUBlocksOrWorkGrps
virtual void HydroCouple::IModelComponent::gpuClearAllocatedResources ( )
pure virtual

gpuClearAllocatedResources

virtual int HydroCouple::IModelComponent::gpuDevice ( int  mpiProcess) const
pure virtual

gpuDevice

Parameters
mpiProcess
Returns
Returns the integer identifier of the GPU Device
virtual int HydroCouple::IModelComponent::gpuMaxNumBlocksOrWorkGrps ( int  mpiProcess) const
pure virtual

maxNumGPUBlocksOrWorkGrps specified the maximum number of CUDA blocks or OpenCL workgroups allocated for the specified MPI Process.

Parameters
mpiProcess
Returns
virtual int HydroCouple::IModelComponent::gpuPlatform ( int  mpiProcess) const
pure virtual

gpuPlatform

Parameters
mpiProcess
Returns
virtual int HydroCouple::IModelComponent::index ( ) const
pure virtual

index

Returns
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.
virtual QList<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.
virtual QSet<int> HydroCouple::IModelComponent::mpiAllocatedProcesses ( ) const
pure virtual

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

Returns
virtual void HydroCouple::IModelComponent::mpiAllocateProcesses ( const QSet< int > &  mpiProcessesToAllocate)
pure virtual

mpiAllocateResources

Parameters
mpiProcessesToAllocate
virtual void HydroCouple::IModelComponent::mpiClearAllocatedProcesses ( )
pure virtual

mpiClearAllocatedProcesses

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

mpiNumProcesses

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

mpiProcess is the MPI process/rank of this component.

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

mpiSetProcess

Parameters
processRank
virtual QList<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.
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.

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

virtual QString 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
virtual void HydroCouple::IModelComponent::setIndex ( int  index)
pure virtual

setIndex

Parameters
index
virtual void HydroCouple::IModelComponent::setReferenceDirectory ( const QString &  referenceDirectory)
pure virtual

setReferenceDirectory

sets the reference directory for this component instance.

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

setWorkflow

Parameters
workflow
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
virtual void HydroCouple::IModelComponent::update ( const QList< IOutput * > &  requiredOutputs = QList< 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 whould 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 succesfully, 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
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.
virtual QList<QString> 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.
virtual const IWorkflowComponent* HydroCouple::IModelComponent::workflow ( ) const
pure virtual

workflow

Returns

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