hydrocouple.h

Go to the documentation of this file.

 
#ifndef HYDROCOUPLE_H
#define HYDROCOUPLE_H
 
#include <string>
#include <array>
#include <vector>
#include <span>
#include <cstdint>
#include <functional>
#include <list>
#include <set>
#include <memory>
#include <typeinfo>
#include <unordered_map>
 

enum class ByteOrder : uint8_t
{

  BigEndian = 0,

  LittleEndian = 1
};

namespace HydroCouple
{
  constexpr int HYDROCOUPLE_ABI_VERSION = 2;

  template <typename... Args>
  class ISignal;
  class IComponentDataItem;
  class IModelComponent;
  class IAdaptedOutputFactory;
  class IArgument;
  class IInput;
  class IOutput;
  class IExchangeItem;
  class IAdaptedOutput;
  class IAdaptedOutputFactoryComponent;
  class IUnit;
  class IComponentDataItemValueChanged;
  class IComponentStatusChangeEventArgs;
  class IWorkflowComponent;
  class IWorkflowComponentStatusChangeEventArgs;

  enum class DataKind : uint8_t
  {
    Unknown = 0, 
    Int8,        
    UInt8,       
    Int16,       
    UInt16,      
    Int32,       
    UInt32,      
    Int64,       
    UInt64,      
    Float32,     
    Float64,     
    Boolean,     
    String,      
    Opaque       
  };

  enum class MemorySpace : uint8_t
  {
    Host = 0,   
    HostPinned, 
    Device,     
    Unified     
  };

  struct BufferDescriptor
  {
    void          *data = nullptr;         
    DataKind       kind = DataKind::Unknown; 
    int32_t        rank = 0;               
    const int64_t *shape = nullptr;        
    const int64_t *stridesBytes = nullptr; 
    MemorySpace    space = MemorySpace::Host; 
    int32_t        deviceId = 0;           
  };

  enum class Capability : uint32_t
  {
    DeviceBuffers = 0,    
    PartitionedData,      
    DistributedExecution, 
    Checkpointing,        
    Cloneable,            
    UserInterface,        
    Licensing             
  };

  struct ErrorEntry
  {
    enum class Severity : uint8_t
    {
      Information = 0, 
      Warning,         
      Error,           
      Fatal            
    };
 
    Severity    severity = Severity::Information; 
    int32_t     code = 0;                         
    std::string source;                           
    std::string message;                          
  };

  template <typename... Args>
  class ISlot
  {
  public:
    virtual ~ISlot() = default;

    virtual void operator()(const ISignal<Args...> &sender, Args... args) = 0;
  };

  template <typename... Args>
  class ISignal
  {
  public:
    virtual ~ISignal() = default;

    virtual void connect(const std::shared_ptr<ISlot<Args...>> &slot) = 0;

    virtual void disconnect(const std::shared_ptr<ISlot<Args...>> &slot) = 0;

    virtual void blockSignals(bool block) = 0;
 
  protected:
    virtual void emit(Args... args) = 0;
  };

  class IPropertyChanged : public virtual ISignal<std::string>
  {
 
  public:
    virtual ~IPropertyChanged() = default;
  };

  class IDescription : public virtual IPropertyChanged
  {
 
  public:
    virtual ~IDescription() = default;

    [[nodiscard]] virtual const std::string &caption() const = 0;

    virtual void setCaption(const std::string &caption) = 0;

    [[nodiscard]] virtual const std::string &description() const = 0;

    virtual void setDescription(const std::string &description) = 0;
  };

  class IIdentity : public virtual IDescription
  {
  public:
    virtual ~IIdentity() = default;

    [[nodiscard]] virtual const std::string &id() const = 0;
  };

  class IComponentInfo : public virtual IIdentity
  {
 
  public:
    virtual ~IComponentInfo() = default;

    [[nodiscard]] virtual std::string libraryFilePath() const = 0;

    virtual void setLibraryFilePath(const std::string &filePath) = 0;

    [[nodiscard]] virtual std::string iconFilePath() const = 0;

    [[nodiscard]] virtual std::string developer() const = 0;

    [[nodiscard]] virtual std::vector<std::string> documentation() const = 0;

    [[nodiscard]] virtual std::string license() const = 0;

    [[nodiscard]] virtual std::string copyright() const = 0;

    [[nodiscard]] virtual std::string url() const = 0;

    [[nodiscard]] virtual std::string email() const = 0;

    [[nodiscard]] virtual std::string version() const = 0;

    [[nodiscard]] virtual std::set<std::string> tags() const = 0;
  };

  class ILicensedComponent
  {
  public:
    virtual ~ILicensedComponent() = default;

    [[nodiscard]] virtual bool validateLicense(const std::string &licenseInfo, std::string &validationMessage) = 0;

    [[nodiscard]] virtual bool validateLicense(std::string &validationMessage) = 0;
  };

  class IUIProvider
  {
  public:
    virtual ~IUIProvider() = default;

    [[nodiscard]] virtual bool hasEditor() const = 0;

    virtual void showEditor(void *opaqueUIPointer = nullptr) = 0;

    [[nodiscard]] virtual bool hasViewer() const = 0;

    virtual void showViewer(void *opaqueUIPointer = nullptr) = 0;
  };

  class IModelComponentInfo : public virtual IComponentInfo
  {
 
  public:
    virtual ~IModelComponentInfo() = default;

    [[nodiscard]] virtual std::unique_ptr<IModelComponent> createComponentInstance() = 0;

    [[nodiscard]] virtual std::vector<IAdaptedOutputFactory *> adaptedOutputFactories() const = 0;
  };

  class IModelComponent : public virtual IIdentity, public virtual ISignal<const std::shared_ptr<IComponentStatusChangeEventArgs> &>
  {
 
  public:
    enum class ComponentStatus
    {
      Created,

      Initializing,

      Initialized,

      Validating,

      Valid,

      WaitingForData,

      Invalid,

      Preparing,

      Updating,

      Updated,

      Checkpointing,

      Done,

      Finishing,

      Finished,

      Failed,
    };
 
    // The legal lifecycle transitions form a normative state machine. The
    // non-normative constexpr helper isValidComponentStatusTransition() in
    // hydrocouplehelpers.h encodes the transition table; implementations must not
    // perform transitions that table rejects.

    virtual ~IModelComponent() = default;

    [[nodiscard]] virtual IModelComponentInfo *componentInfo() const = 0;

    [[nodiscard]] virtual ComponentStatus status() const = 0;

    [[nodiscard]] virtual std::vector<IArgument *> arguments() const = 0;

    [[nodiscard]] virtual std::vector<IInput *> inputs() const = 0;

    [[nodiscard]] virtual std::vector<IOutput *> outputs() const = 0;

    [[nodiscard]] virtual std::vector<IComponentDataItem *> results() const = 0;

    virtual void initialize() = 0;

    [[nodiscard]] virtual std::vector<std::string> validate() = 0;

    virtual void prepare() = 0;

    virtual void update(const std::vector<IOutput *> &requiredOutputs = {}) = 0;

    virtual void finish() = 0;

    [[nodiscard]] virtual const IWorkflowComponent *workflow() const = 0;

    virtual void setWorkflow(const IWorkflowComponent *workflow) = 0;

    [[nodiscard]] virtual std::set<Capability> capabilities() const = 0;

    [[nodiscard]] virtual std::vector<ErrorEntry> errors(bool clearAfterRead = false) = 0;

    [[nodiscard]] virtual std::string referenceDirectory() const = 0;

    virtual void setReferenceDirectory(const std::string &referenceDirectory) = 0;
  };

  class IComponentStatusChangeEventArgs
  {
  public:
    virtual ~IComponentStatusChangeEventArgs() = default;

    [[nodiscard]] virtual IModelComponent *component() const = 0;

    [[nodiscard]] virtual IModelComponent::ComponentStatus previousStatus() const = 0;

    [[nodiscard]] virtual IModelComponent::ComponentStatus status() const = 0;

    [[nodiscard]] virtual std::string message() const = 0;

    [[nodiscard]] virtual bool hasProgressMonitor() const = 0;

    [[nodiscard]] virtual float percentProgress() const = 0;
  };

  class ICloneableModelComponent : public virtual IModelComponent
  {
  public:
    virtual ~ICloneableModelComponent() = default;

    [[nodiscard]] virtual ICloneableModelComponent *parent() const = 0;

    [[nodiscard]] virtual ICloneableModelComponent *clone(const std::unordered_map<std::string, std::string> &clone_optional_arguments = std::unordered_map<std::string, std::string>()) = 0;

    [[nodiscard]] virtual std::vector<ICloneableModelComponent *> clones() const = 0;
  };

  class ICheckpointableModelComponent : public virtual IModelComponent
  {
  public:
    virtual ~ICheckpointableModelComponent() = default;

    [[nodiscard]] virtual bool saveState(std::string &token, std::string &message) = 0;

    [[nodiscard]] virtual bool restoreState(const std::string &token, std::string &message) = 0;
  };

  class IValueDefinition : public virtual IDescription
  {
  public:
    virtual ~IValueDefinition() = default;

    [[nodiscard]] virtual const std::type_info &type() const = 0;

    [[nodiscard]] virtual double missingValue() const = 0;

    [[nodiscard]] virtual double defaultValue() const = 0;
  };

  class IDimension : public virtual IIdentity
  {
  public:
    enum class LengthType
    {
      Static = 0,

      Dynamic = 1
    };

    virtual ~IDimension() = default;

    [[nodiscard]] virtual LengthType lengthType() const = 0;
  };

  class IQuality : public virtual IValueDefinition
  {
  public:
    virtual ~IQuality() = default;

    [[nodiscard]] virtual std::vector<std::string> categories() const = 0;

    [[nodiscard]] virtual bool isOrdered() const = 0;
  };

  class IUnitDimensions : public virtual IDescription
  {
  public:
    enum class FundamentalUnitDimension
    {
      Length,

      Mass,

      Time,

      ElectricCurrent,

      Temperature,

      AmountOfSubstance,

      LuminousIntensity,

      Currency,

      Unitless,
    };

    virtual ~IUnitDimensions() = default;

    [[nodiscard]] virtual double power(HydroCouple::IUnitDimensions::FundamentalUnitDimension dimension) = 0;
  };

  class IUnit : public virtual IDescription
  {
  public:
    enum class DistanceUnitType
    {
      Standard,
      Geographic,
      Unknown
    };

    enum class DistanceUnits
    {

      Meters,

      Kilometers,

      Feet,

      NauticalMiles,

      Yards,

      Miles,

      Degrees,

      Centimeters,

      Millimeters,

      Inches,

      Unknown
    };

    enum class AreaUnits
    {

      SquareMeters,

      SquareKilometers,

      SquareFeet,

      SquareYards,

      SquareMiles,

      Hectares,

      Acres,

      SquareNauticalMiles,

      SquareDegrees,

      SquareCentimeters,

      SquareMillimeters,

      SquareInches,

      Unknown
    };

    virtual ~IUnit() = default;

    [[nodiscard]] virtual IUnitDimensions *dimensions() const = 0;

    [[nodiscard]] virtual double conversionFactorToSI() const = 0;

    [[nodiscard]] virtual double offsetToSI() const = 0;
  };

  class IQuantity : public virtual IValueDefinition
  {
  public:
    virtual ~IQuantity() = default;

    [[nodiscard]] virtual IUnit *unit() const = 0;

    [[nodiscard]] virtual double minValue() const = 0;

    [[nodiscard]] virtual double maxValue() const = 0;
  };

  class IComponentDataItem : public virtual IIdentity, public virtual ISignal<const std::shared_ptr<IComponentDataItemValueChanged> &>
  {
  public:
    virtual ~IComponentDataItem() = default;

    [[nodiscard]] virtual IModelComponent *modelComponent() const = 0;

    [[nodiscard]] virtual std::vector<IDimension *> dimensions() const = 0;

    [[nodiscard]] virtual std::vector<int64_t> shape() const = 0;

    [[nodiscard]] virtual DataKind dataKind() const = 0;

    [[nodiscard]] virtual IValueDefinition *valueDefinition() const = 0;

    [[nodiscard]] virtual bool getValuesInto(
        const BufferDescriptor &destination,
        std::span<const int64_t> start,
        std::span<const int64_t> count,
        std::string *message = nullptr) const = 0;

    [[nodiscard]] virtual bool setValuesFrom(
        const BufferDescriptor &source,
        std::span<const int64_t> start,
        std::span<const int64_t> count,
        std::string *message = nullptr) = 0;
 
    // Typed convenience wrappers over getValuesInto()/setValuesFrom() (scalar reads,
    // flat-span hyperslab reads/writes) are provided as non-normative free function
    // templates in hydrocouplehelpers.h; the interface itself carries no executable code.
  };

  class IComponentDataItemValueChanged
  {
  public:
    virtual ~IComponentDataItemValueChanged() = default;

    [[nodiscard]] virtual IComponentDataItem *componentDataItem() const = 0;

    [[nodiscard]] virtual std::vector<int64_t> start() const = 0;

    [[nodiscard]] virtual std::vector<int64_t> count() const = 0;
  };

  class IArgument : public virtual IComponentDataItem
  {
 
  public:
    enum class ArgumentInputType
    {
      String,

      File,

      JSON,

      YAML,

      XML,

      URL,

      MEMORY_OBJECT
    };

    virtual ~IArgument() = default;

    [[nodiscard]] virtual bool isOptional() const = 0;

    [[nodiscard]] virtual bool isReadOnly() const = 0;

    [[nodiscard]] virtual std::string toString() const = 0;

    virtual void saveData() = 0;

    [[nodiscard]] virtual std::vector<std::string> fileFilters() const = 0;

    [[nodiscard]] virtual std::vector<const std::type_info *> validComponentDataItemTypes() const = 0;

    [[nodiscard]] virtual bool isValidArgType(ArgumentInputType argType) const = 0;

    [[nodiscard]] virtual ArgumentInputType currentArgumentInputType() const = 0;

    [[nodiscard]] virtual bool initialize(const std::string &value, ArgumentInputType argType, std::string &message) = 0;

    [[nodiscard]] virtual bool initialize(const IComponentDataItem &componentDataItem, std::string &message) = 0;

    [[nodiscard]] virtual bool serialize(ArgumentInputType argType, std::string &value, std::string &message) const = 0;
  };

  class IExchangeItemChangeEventArgs
  {
  public:
    virtual ~IExchangeItemChangeEventArgs() = default;

    [[nodiscard]] virtual IExchangeItem *exchangeItem() const = 0;

    [[nodiscard]] virtual std::string message() const = 0;
  };

  class IExchangeItem : public virtual IComponentDataItem
  {
 
  public:
    virtual ~IExchangeItem() = default;
  };

  class IOutput : public virtual IExchangeItem
  {
  public:
    virtual ~IOutput() = default;

    [[nodiscard]] virtual std::vector<IInput *> consumers() const = 0;

    virtual void addConsumer(IInput *consumer) = 0;

    [[nodiscard]] virtual bool removeConsumer(IInput *consumer) = 0;

    [[nodiscard]] virtual std::vector<IAdaptedOutput *> adaptedOutputs() const = 0;

    virtual void addAdaptedOutput(IAdaptedOutput *adaptedOutput) = 0;

    [[nodiscard]] virtual bool removeAdaptedOutput(IAdaptedOutput *adaptedOutput) = 0;

    virtual void updateValues(const IInput *querySpecifier) = 0;
  };

  class IAdaptedOutput : public virtual IOutput
  {
  public:
    virtual ~IAdaptedOutput() = default;

    [[nodiscard]] virtual IAdaptedOutputFactory *adaptedOutputFactory() const = 0;

    [[nodiscard]] virtual std::vector<IArgument *> arguments() const = 0;

    virtual void initialize() = 0;

    [[nodiscard]] virtual IOutput *adaptee() const = 0;

    virtual void refresh() = 0;
  };

  class IAdaptedOutputFactory : public virtual IIdentity
  {
  public:
    virtual ~IAdaptedOutputFactory() = default;

    [[nodiscard]] virtual std::vector<IIdentity *> getAvailableAdaptedOutputIds(const IOutput *provider, const IInput *consumer = nullptr) = 0;

    [[nodiscard]] virtual std::unique_ptr<IAdaptedOutput> createAdaptedOutput(IIdentity *adaptedProviderId, IOutput *provider, IInput *consumer = nullptr) = 0;
  };

  class IAdaptedOutputFactoryComponentInfo : public virtual IComponentInfo
  {
  public:
    virtual ~IAdaptedOutputFactoryComponentInfo() = default;

    [[nodiscard]] virtual IAdaptedOutputFactoryComponent *createComponentInstance() = 0;
  };

  class IAdaptedOutputFactoryComponent : public virtual IAdaptedOutputFactory
  {
  public:
    virtual ~IAdaptedOutputFactoryComponent() = default;

    [[nodiscard]] virtual IAdaptedOutputFactoryComponentInfo *componentInfo() const = 0;
  };

  class IInput : public virtual IExchangeItem
  {
  public:
    virtual ~IInput() = default;

    [[nodiscard]] virtual IOutput *provider() const = 0;

    [[nodiscard]] virtual bool setProvider(IOutput *provider) = 0;

    [[nodiscard]] virtual bool canConsume(IOutput *provider, std::string &message) const = 0;
  };

  class IMultiInput : public virtual IInput
  {
  public:
    virtual ~IMultiInput() = default;

    [[nodiscard]] virtual std::vector<IIdentity *> providerLabels() const = 0;

    [[nodiscard]] virtual bool isRequiredProvider(const IIdentity *providerLabel) const = 0;

    [[nodiscard]] virtual std::vector<IOutput *> providers() const = 0;

    [[nodiscard]] virtual bool canConsume(IOutput *provider, std::string &message, const IIdentity *providerRoleIdentifier = nullptr) const = 0;

    [[nodiscard]] virtual bool addProvider(IOutput *provider, const IIdentity *providerRoleIdentifier = nullptr) = 0;

    [[nodiscard]] virtual bool removeProvider(IOutput *provider) = 0;
  };

  class IIdBasedComponentDataItem : public virtual IComponentDataItem
  {
 
  public:
    virtual ~IIdBasedComponentDataItem() = default;

    [[nodiscard]] virtual std::vector<std::string> identifiers() const = 0;

    [[nodiscard]] virtual IDimension *identifierDimension() const = 0;
  };

  class IWorkflowComponentInfo : public virtual IComponentInfo
  {
 
  public:
    virtual ~IWorkflowComponentInfo() = default;

    [[nodiscard]] virtual IWorkflowComponent *createComponentInstance() = 0;
  };

  class IWorkflowComponent : public virtual IIdentity, public virtual ISignal<const std::shared_ptr<IWorkflowComponentStatusChangeEventArgs> &>
  {
 
  public:
    enum class WorkflowStatus
    {
      Created,
      Initializing,
      Initialized,
      Validating,
      Validated,
      Preparing,
      Prepared,
      Updating,
      Updated,
      Paused,
      Done,
      Finishing,
      Finished,
      Failed
    };

    virtual ~IWorkflowComponent() = default;

    [[nodiscard]] virtual IWorkflowComponentInfo *componentInfo() const = 0;

    [[nodiscard]] virtual std::vector<IIdentity *> modelComponentLabels() const = 0;

    [[nodiscard]] virtual bool isRequiredModelComponent(const IIdentity *modelComponentLabel) const = 0;

    virtual void initialize() = 0;

    [[nodiscard]] virtual std::vector<std::string> validate() = 0;

    virtual void prepare() = 0;

    virtual void update() = 0;

    virtual void finish() = 0;

    virtual void requestStop() = 0;

    virtual void requestPause() = 0;

    virtual void resume() = 0;

    [[nodiscard]] virtual std::vector<ErrorEntry> errors(bool clearAfterRead = false) = 0;

    [[nodiscard]] virtual WorkflowStatus status() const = 0;

    [[nodiscard]] virtual std::vector<IModelComponent *> modelComponents() const = 0;

    [[nodiscard]] virtual bool addModelComponent(IModelComponent *component, const IIdentity *modelRoleIdentifier = nullptr, std::string *message = nullptr) = 0;

    [[nodiscard]] virtual bool removeModelComponent(IModelComponent *component) = 0;
  };

  class IWorkflowComponentStatusChangeEventArgs
  {
  public:
    virtual ~IWorkflowComponentStatusChangeEventArgs() = default;

    [[nodiscard]] virtual IWorkflowComponent *workflowComponent() const = 0;

    [[nodiscard]] virtual IWorkflowComponent::WorkflowStatus previousStatus() const = 0;

    [[nodiscard]] virtual IWorkflowComponent::WorkflowStatus status() const = 0;

    [[nodiscard]] virtual std::string message() const = 0;

    [[nodiscard]] virtual bool hasProgressMonitor() const = 0;

    [[nodiscard]] virtual float percentProgress() const = 0;
  };
 
}
 
#endif // HYDROCOUPLE_H