Loading...
Searching...
No Matches
HydroCouple Namespace Reference

HydroCouple namespace contains the core interface specifications for the HydroCouple component-based modeling framework interface specification. More...

Namespaces

namespace  Distributed
 HydroCouple's interfaces for distributed and cloud execution.
 
namespace  Helpers
 Convenience helpers for the HydroCouple interface standard; non-normative except for the two lifecycle transition tables.
 
namespace  Spatial
 HydroCouple's interfaces that have a spatial component.
 
namespace  SpatioTemporal
 HydroCouple's interfaces that have both spatial and temporal components.
 
namespace  Temporal
 HydroCouple's interfaces that have a time varying component.
 

Classes

struct  BufferDescriptor
 BufferDescriptor describes a typed, possibly strided, possibly device-resident multi-dimensional array. More...
 
struct  DifferentialEntry
 DifferentialEntry pairs one data item, in one role, with a buffer holding its tangent (forward mode) or cotangent (reverse mode). More...
 
struct  ErrorEntry
 ErrorEntry is one diagnostic record in a component's error queue. More...
 
class  IAdaptedOutput
 An IAdaptedOutput adds one or more data operations on top of an IOutput. More...
 
class  IAdaptedOutputFactory
 IAdaptedOutputFactory is used to create instances of IAdaptedOutput. More...
 
class  IAdaptedOutputFactoryComponent
 IAdaptedOutputFactoryComponent is an IAdaptedOutputFactory generated from an IAdaptedOutputFactoryComponentInfo. More...
 
class  IAdaptedOutputFactoryComponentInfo
 IAdaptedOutputFactoryComponentInfo interface class provides information about an IAdaptedOutputFactoryComponent. More...
 
class  IArgument
 IArgument interface class used to set the arguments for components. More...
 
class  ICheckpointableAdaptedOutput
 ICheckpointableAdaptedOutput is an adapted output that can save and restore the state it carries between refreshes. More...
 
class  ICheckpointableModelComponent
 ICheckpointableModelComponent is an IModelComponent that can save and restore its complete simulation state. More...
 
class  ICloneableModelComponent
 The ICloneableModelComponent class is an IModelComponent that supports deep cloning of itself and its configuration. More...
 
class  IComponentDataItem
 IComponentDataItem is a fundamental unit of data for a component. More...
 
class  IComponentDataItemValueChanged
 IComponentDataItemValueChanged interface class used to notify when the values of a IComponentDataItem change. More...
 
class  IComponentInfo
 IComponentInfo interface class is a factory that provides detailed metadata about a component and creates new instances of a component. More...
 
class  IComponentStatusChangeEventArgs
 The IComponentStatusChangeEventArgs contains the information that will be passed when the IModelComponent fires a signal. More...
 
class  IDescription
 IDescription interface class provides descriptive information on a HydroCouple object. More...
 
class  IDifferentiableAdaptedOutput
 IDifferentiableAdaptedOutput is an adapted output that can report the derivative of its most recent refresh(). More...
 
class  IDifferentiableModelComponent
 IDifferentiableModelComponent is a model component that can report the derivative of its most recent step. More...
 
class  IDimension
 IDimension provides the properties of one axis of a data item's index space. More...
 
class  IExchangeItem
 IExchangeItem the base data item the can be exchanged between components at runtime. More...
 
class  IIdBasedComponentDataItem
 IIdBasedComponentDataItem is an IComponentDataItem whose data is indexed by string identifiers. More...
 
class  IIdentity
 IIdentity interface class defines a method to get the Id of an HydroCouple entity. More...
 
class  IInput
 An IInput item that can accept values for an IModelComponent. More...
 
class  ILicensedComponent
 ILicensedComponent is an optional side interface for components that require license validation. More...
 
class  IModelComponent
 IModelComponent interface is the core interface in the HydroCouple standard defining a model component. More...
 
class  IModelComponentInfo
 IModelComponentInfo interface inherits from the IComponentInfo interface which provides detailed metadata about an IModelComponent. More...
 
class  IMultiInput
 The IMultiInput class is an IInput class that has multiple outputs supplying data to it. More...
 
class  IOutput
 An output exchange item that can deliver values from an IModelComponent. More...
 
class  IPropertyChanged
 IPropertyChanged interface is used to emit signal/event when a property of an object changes. More...
 
class  IQuality
 IQuality describes qualitative data, where a value is specified as one category within a number of predefined (possible) categories. More...
 
class  IQuantity
 IQuantity specifies values as an amount of some unit, usually as a floating point number. More...
 
class  ISignal
 Forward declarations. More...
 
class  ISlot
 ISlot interface class must be implemented by classes that want to listen to signals. More...
 
class  IUIProvider
 IUIProvider is an optional side interface for entities that can present a graphical editor and/or viewer. More...
 
class  IUnit
 IUnit interface, describing the physical unit of a IQuantity. More...
 
class  IUnitDimensions
 Defines the order of dimension in each FundamentalDimension for a unit. More...
 
class  IValueDefinition
 IValueDefinition describes the type and properties of values held by an IComponentDataItem. More...
 
class  IWorkflowComponent
 IWorkflowComponent manages the execution workflow for a set of coupled IModelComponent instances. More...
 
class  IWorkflowComponentInfo
 IWorkflowComponentInfo provides metadata about an IWorkflowComponent and creates new instances of it. More...
 
class  IWorkflowComponentStatusChangeEventArgs
 The IWorkflowComponentStatusChangeEventArgs contains the information that will be passed when the IWorkflowComponent fires a signal. More...
 

Typedefs

using DifferentialSet = std::span<const DifferentialEntry>
 DifferentialSet is a non-owning view of DifferentialEntry records.
 

Enumerations

enum class  ByteOrder : uint8_t {
  BigEndian = 0 ,
  LittleEndian = 1
}
 The ByteOrder enum class indicates the byte order of serialized data. More...
 
enum class  DataKind : uint8_t {
  Unknown = 0 ,
  Int8 ,
  UInt8 ,
  Int16 ,
  UInt16 ,
  Int32 ,
  UInt32 ,
  Int64 ,
  UInt64 ,
  Float32 ,
  Float64 ,
  Boolean ,
  String ,
  Opaque
}
 DataKind identifies the element type of a typed data buffer. More...
 
enum class  MemorySpace : uint8_t {
  Host = 0 ,
  HostPinned ,
  Device ,
  Unified
}
 MemorySpace identifies where a buffer's bytes physically live. More...
 
enum class  DeviceBackend : uint8_t {
  None = 0 ,
  CUDA ,
  HIP ,
  SYCL ,
  LevelZero ,
  OpenCL ,
  Other
}
 DeviceBackend identifies the runtime that owns a device-resident buffer. More...
 
enum class  Capability : uint32_t {
  DeviceBuffers = 0 ,
  PartitionedData ,
  DistributedExecution ,
  Checkpointing ,
  Cloneable ,
  UserInterface ,
  Licensing ,
  Differentiable ,
  LayeredData ,
  VendorBase = 2147483648
}
 Capability identifies an optional behavior a component may support. More...
 
enum class  DifferentialRole : uint8_t {
  Input = 0 ,
  Argument ,
  Output ,
  StateBefore ,
  StateAfter
}
 DifferentialRole says which side of a component's step a derivative buffer belongs to. More...
 
enum class  ValueKind : uint8_t {
  Unknown = 0 ,
  Intensive ,
  Extensive ,
  Flux ,
  Density
}
 How a value behaves when it is regridded or aggregated. More...
 

Variables

constexpr int HYDROCOUPLE_ABI_VERSION = 5
 ABI version for the HydroCouple interface.
 

Detailed Description

HydroCouple namespace contains the core interface specifications for the HydroCouple component-based modeling framework interface specification.

These interfaces cross shared-library boundaries by design — a component in one image hands its data items to an SDK or host living in another — and dynamic_cast across images only works when a class's type_info is one entity.

These interfaces cross shared-library boundaries by design — a component in one image hands its data items to an SDK or host living in another — and dynamic_cast across images only works when a class's type_info is one entity. Projects routinely build with -fvisibility=hidden, which would give every image its own private copy of these typeinfos and make such casts fail silently; forcing default visibility here keeps the RTTI shared regardless of the including project's flags.

Projects routinely build with -fvisibility=hidden, which would give every image its own private copy of these typeinfos and make such casts fail silently; forcing default visibility here keeps the RTTI shared regardless of the including project's flags.

Typedef Documentation

◆ DifferentialSet

DifferentialSet is a non-owning view of DifferentialEntry records.

Enumeration Type Documentation

◆ ByteOrder

enum class HydroCouple::ByteOrder : uint8_t
strong

The ByteOrder enum class indicates the byte order of serialized data.

Enumerator
BigEndian 

BigEndian serialized data byte order (most significant byte first).

LittleEndian 

LittleEndian serialized data byte order (least significant byte first).

◆ Capability

enum class HydroCouple::Capability : uint32_t
strong

Capability identifies an optional behavior a component may support.

Orchestrators query IModelComponent::capabilities() to learn which optional component interfaces and data-item mixins a component offers, and dynamic_cast only to interfaces the set advertises. The set is the discovery mechanism; the cast is the access mechanism. A component must advertise every capability whose interface it (or any of its data items) implements.

Adapted outputs are the one exception. An IAdaptedOutput is made by a factory, not owned by the component whose output it adapts, and has no capability set of its own; its optional interfaces (IDifferentiableAdaptedOutput, ICheckpointableAdaptedOutput) are discovered by casting the adapter itself.

Values at or above VendorBase are reserved for vendor- or project-specific capabilities: a vendor picks values in that range, casts them to Capability, and documents them; the standard never assigns values there.

Enumerator
DeviceBuffers 

Data items can produce/accept Device/Unified BufferDescriptors.

PartitionedData 

Component exposes IPartitionedComponentDataItem items (see hydrocoupledistributed.h).

DistributedExecution 

Component implements IDistributedModelComponent.

Checkpointing 

Component implements ICheckpointableModelComponent.

Cloneable 

Component implements ICloneableModelComponent.

UserInterface 

Component implements IUIProvider.

Licensing 

Component implements ILicensedComponent.

Differentiable 

Component implements IDifferentiableModelComponent.

LayeredData 

Component exposes data items implementing Spatial::ILayering.

VendorBase 

First value of the vendor-reserved range (0x80000000).

◆ DataKind

enum class HydroCouple::DataKind : uint8_t
strong

DataKind identifies the element type of a typed data buffer.

This is the type vocabulary of the data-exchange plane. The numeric and Boolean kinds have a fixed element size (see Helpers::dataKindSize()) and are the kinds a transport or a device can carry.

String is a host-only metadata kind: a String buffer points to an array of std::string objects, whose layout is not stable across toolchains, cannot live in device memory, and cannot be serialized by an ITransport. Items may use it for labels and arguments; a transport or a device-space request presented a String buffer must refuse it with a message rather than attempt to move it.

Opaque carries implementation-defined bytes whose meaning both endpoints agree on out of band. Its size is not out of band: an Opaque descriptor must carry BufferDescriptor::itemSizeBytes > 0, so that transports, halo exchangers and helpers can compute byte extents without knowing the meaning.

Enumerator
Unknown 

No/unknown element type.

Int8 

int8_t

UInt8 

uint8_t

Int16 

int16_t

UInt16 

uint16_t

Int32 

int32_t

UInt32 

uint32_t

Int64 

int64_t

UInt64 

uint64_t

Float32 

float

Float64 

double

Boolean 

bool (stored one element per byte)

String 

std::string (host memory only)

Opaque 

Implementation-defined bytes; meaning agreed out of band, size in BufferDescriptor::itemSizeBytes.

◆ DeviceBackend

enum class HydroCouple::DeviceBackend : uint8_t
strong

DeviceBackend identifies the runtime that owns a device-resident buffer.

Vendor-neutral in the sense that matters — no vendor types appear in the standard — but a device ordinal alone is ambiguous on a node that carries more than one runtime (a CUDA device 0 and a Level Zero device 0 are different memory). The backend and BufferDescriptor::deviceId together name one address space.

Enumerator
None 

Host memory; no device runtime involved.

CUDA 

NVIDIA CUDA runtime.

HIP 

AMD HIP/ROCm runtime.

SYCL 

SYCL (any implementation).

LevelZero 

Intel oneAPI Level Zero.

OpenCL 

OpenCL.

Other 

An implementation-defined runtime both endpoints agree on.

◆ DifferentialRole

enum class HydroCouple::DifferentialRole : uint8_t
strong

DifferentialRole says which side of a component's step a derivative buffer belongs to.

A step maps (StateBefore, Input, Argument) to (StateAfter, Output). The same state item appears on both sides, which is why the role is carried explicitly rather than inferred from the item's type.

Enumerator
Input 

An IInput of the component, as consumed by the step.

Argument 

An IArgument of the component (a parameter of the step).

Output 

An IOutput of the component, as produced by the step.

StateBefore 

A state item's value at the start of the step.

StateAfter 

The same state item's value at the end of the step.

◆ MemorySpace

enum class HydroCouple::MemorySpace : uint8_t
strong

MemorySpace identifies where a buffer's bytes physically live.

Vendor-neutral by design: no CUDA/HIP/SYCL types appear in this standard. The pairing of MemorySpace and device id is resolved to a concrete runtime by the implementing SDK's execution backend.

Enumerator
Host 

Ordinary pageable host memory.

HostPinned 

Page-locked host memory (fast staging to/from devices).

Device 

Accelerator-resident memory addressed by (backend, deviceId).

Unified 

Unified/managed memory accessible from host and device.

◆ ValueKind

enum class HydroCouple::ValueKind : uint8_t
strong

How a value behaves when it is regridded or aggregated.

Two components rarely share a mesh, so almost every exchange is resampled — and the right way to resample depends on what the number is. A temperature handed from a coarse cell to four fine ones is copied; a mass is divided; a flux is scaled by area. Every IValueDefinition therefore declares its kind, so that an adapter never has to be told out of band — being told out of band is how two sides end up disagreeing about what a number means.

Enumerator
Unknown 

Not declared.

Adapters must not guess; they should refuse or ask.

Intensive 

Independent of extent — temperature, concentration, elevation.

Averages.

Extensive 

Proportional to extent — mass, volume, heat content.

Sums.

Flux 

Per unit area and time.

Integrates over the area it crosses.

Density 

Per unit volume.

Integrates over the volume it fills.

Variable Documentation

◆ HYDROCOUPLE_ABI_VERSION

int HydroCouple::HYDROCOUPLE_ABI_VERSION = 5
constexpr

ABI version for the HydroCouple interface.

3: ICheckpointableModelComponent gained releaseState() (its vtable grew). 4: contract-consistency round (2026-09-29): BufferDescriptor gained itemSizeBytes/backend/queue; IDimension::role(); IValueDefinition gained valueKind() and lost type(); IModelComponent::states(); IArgument::role(); temporal/spatial vtables changed (see CHANGELOG); IAdaptedOutput::states(), IDifferentiableAdaptedOutput:: differentiableStates() and ICheckpointableAdaptedOutput (stateful adapters, 2026-10-02 – the same, still unreleased, ABI 4). 5: release-readiness round (2026-11-13): IOutput::addConsumer() carries the provider role, so it is the one wiring entry point for multi-inputs too; IExchangeRequest::waitFor(); WorkflowStatus::Invalid; the two status enums are uint8_t with pinned values; ByteOrder moved into this namespace; IValueDefinition::standardName()/conceptURI() and IUnit::symbol()/ucumCode() bind exchanged quantities to published vocabularies (the ontology items held since 2026-09-29).