API Reference#

The hydrocouple package mirrors the C++20 v2.0.0 interface standard 1:1: same names (snake_cased), same inheritance, same pure-abstract discipline. For the corresponding C++ declarations see the C++ interface docs at the site root.

hydrocouple.core #

The core standard: enums, the ErrorEntry diagnostic record, the signal/slot contracts, identity and metadata chains, the model-component lifecycle, and the typed hyperslab data plane on IComponentDataItem.

HydroCouple core abstract base classes.

Python ABC mirrors of the C++ HydroCouple v2.0.0 interfaces defined in hydrocouple.h. These define the component-based modeling framework contracts that all HydroCouple-compliant components must implement.

The hierarchy follows the C++ namespace HydroCouple and preserves the same inheritance relationships and the two governing principles of the standard: the ABCs carry no behavior (mirroring the header-only, no-implementation rule — conveniences live in hydrocouple.helpers), and nothing is defined here that the C++ headers do not declare.

Data plane: field data moves exclusively through IComponentDataItem.get_values_into() / IComponentDataItem.set_values_from() as NumPy arrays. An ndarray is the Python-side BufferDescriptor: its data pointer, dtype, shape, and strides carry exactly the information the C++ descriptor encodes, so the Cython bridge marshals zero-copy in both directions.

@see: U{HydroCouple C++ API <https://hydrocouple.org/HydroCouple/html/>}

class ByteOrder(*values)[source]#

Bases: IntEnum

Byte-order enumeration mirroring C++ ByteOrder.

BigEndian – Most-significant byte first (network order).
LittleEndian – Least-significant byte first (x86 native).

BigEndian = 0#

LittleEndian = 1#

class DataKind(*values)[source]#

Bases: IntEnum

Element type of a typed data buffer.

Mirrors C++ HydroCouple::DataKind. This is the type vocabulary of the data-exchange plane; hydrocouple.helpers maps each kind to its NumPy dtype.

Unknown = 0#

Int8 = 1#

UInt8 = 2#

Int16 = 3#

UInt16 = 4#

Int32 = 5#

UInt32 = 6#

Int64 = 7#

UInt64 = 8#

Float32 = 9#

Float64 = 10#

Boolean = 11#

String = 12#

Opaque = 13#

class MemorySpace(*values)[source]#

Bases: IntEnum

Where a buffer’s bytes physically live.

Mirrors C++ HydroCouple::MemorySpace. Vendor-neutral by design.

Host = 0#

HostPinned = 1#

Device = 2#

Unified = 3#

class Capability(*values)[source]#

Bases: IntEnum

Optional behavior a component may support.

Mirrors C++ HydroCouple::Capability. Orchestrators branch on IModelComponent.capabilities() instead of type-probing chains.

DeviceBuffers = 0#

PartitionedData = 1#

DistributedExecution = 2#

Checkpointing = 3#

Cloneable = 4#

UserInterface = 5#

Licensing = 6#

class ComponentStatus(*values)[source]#

Bases: IntEnum

Lifecycle status of a model component.

Mirrors C++ HydroCouple::IModelComponent::ComponentStatus. Legal transitions are encoded by hydrocouple.helpers.is_valid_component_status_transition().

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#

class LengthType(*values)[source]#

Bases: IntEnum

Dimension length type mirroring C++ IDimension::LengthType.

Static = 0#

Dynamic = 1#

class FundamentalUnitDimension(*values)[source]#

Bases: IntEnum

Fundamental unit dimensions mirroring C++ IUnitDimensions::FundamentalUnitDimension.

Length = 0#

Mass = 1#

Time = 2#

ElectricCurrent = 3#

Temperature = 4#

AmountOfSubstance = 5#

LuminousIntensity = 6#

Currency = 7#

Unitless = 8#

class DistanceUnitType(*values)[source]#

Bases: IntEnum

Distance unit type mirroring C++ IUnit::DistanceUnitType.

Standard = 0#

Geographic = 1#

Unknown = 2#

class DistanceUnits(*values)[source]#

Bases: IntEnum

Distance units mirroring C++ IUnit::DistanceUnits.

Meters = 0#

Kilometers = 1#

Feet = 2#

NauticalMiles = 3#

Yards = 4#

Miles = 5#

Degrees = 6#

Centimeters = 7#

Millimeters = 8#

Inches = 9#

Unknown = 10#

class AreaUnits(*values)[source]#

Bases: IntEnum

Area units mirroring C++ IUnit::AreaUnits.

SquareMeters = 0#

SquareKilometers = 1#

SquareFeet = 2#

SquareYards = 3#

SquareMiles = 4#

Hectares = 5#

Acres = 6#

SquareNauticalMiles = 7#

SquareDegrees = 8#

SquareCentimeters = 9#

SquareMillimeters = 10#

SquareInches = 11#

Unknown = 12#

class ArgumentInputType(*values)[source]#

Bases: IntEnum

Input representation of an argument value.

Mirrors C++ IArgument::ArgumentInputType.

String = 0#

File = 1#

JSON = 2#

YAML = 3#

XML = 4#

URL = 5#

MEMORY_OBJECT = 6#

class WorkflowStatus(*values)[source]#

Bases: IntEnum

Workflow lifecycle status mirroring C++ IWorkflowComponent::WorkflowStatus.

Created = 0#

Initializing = 1#

Initialized = 2#

Validating = 3#

Validated = 4#

Preparing = 5#

Prepared = 6#

Updating = 7#

Updated = 8#

Paused = 9#

Done = 10#

Finishing = 11#

Finished = 12#

Failed = 13#

class ErrorEntry(severity=Severity.Information, code=0, source='', message='')[source]#

Bases: object

One diagnostic record in a component’s error queue.

Mirrors C++ HydroCouple::ErrorEntry. The error queue is the normative failure channel for distributed and embedded execution, where exceptions cannot cross process, C-ABI, or language boundaries.

Parameters:

severity (Severity)
code (int)
source (str)
message (str)

class Severity(*values)[source]#

Bases: IntEnum

Severity of an ErrorEntry.

Information = 0#

Warning = 1#

Error = 2#

Fatal = 3#

severity: Severity = 0#

code: int = 0#

source: str = ''#

message: str = ''#

class ISignal[source]#

Bases: ABC

Signal emitter mirroring C++ ISignal<Args...>.

Slots are Python callables; the argument signature is documented by each concrete signal owner.

abstractmethod connect(slot)[source]#

Connect a slot to this signal.

Parameters:: slot (Callable)
Return type:: None

abstractmethod disconnect(slot)[source]#

Disconnect a slot from this signal.

Parameters:: slot (Callable)
Return type:: None

abstractmethod block_signals(block)[source]#

Block or unblock emission of this signal.

Parameters:: block (bool)
Return type:: None

class IPropertyChanged[source]#

Bases: ISignal

Emits a signal when a property of an object changes.

Mirrors C++ IPropertyChanged (ISignal<std::string>); slots are called as slot(property_name: str).

class IDescription[source]#

Bases: IPropertyChanged

Descriptive information on a HydroCouple object.

Mirrors C++ IDescription.

abstract property caption: str#: Caption (title or heading) for the entity.

abstract property description: str#: Additional descriptive information for the entity.

class IIdentity[source]#

Bases: IDescription

Adds a unique identifier to a describable entity.

Mirrors C++ IIdentity. The id must be unique within its context and must not be empty.

abstract property id: str#: Unique identifier for the entity within its context.

class IComponentInfo[source]#

Bases: IIdentity

Factory metadata about a component.

Mirrors C++ IComponentInfo. Must be implemented as an IModelComponentInfo, IAdaptedOutputFactoryComponentInfo, or IWorkflowComponentInfo. Licensing lives on the optional ILicensedComponent side interface.

abstract property library_file_path: str#: Path to the library from which this component was created.

abstract property icon_file_path: str#: Path to the component icon, relative to the component library.

abstract property developer: str#: Name of the developer/vendor of this component.

abstract property documentation: list[str]#: Citations of publications related to this component.

abstract property license: str#: License information for this component.

abstract property copyright: str#: Copyright information for this component.

abstract property url: str#: Developer URL.

abstract property email: str#: Developer email.

abstract property version: str#: Component version string.

abstract property tags: set[str]#: Categorical tags classifying this component.

class ILicensedComponent[source]#

Bases: ABC

Optional side interface for components requiring license validation.

Mirrors C++ ILicensedComponent. Components implementing it advertise Capability.Licensing.

abstractmethod validate_license(license_info=None)[source]#

Validate (and optionally register) the component license.

Parameters:: license_info (str | None) – License information to register, or None to check the current license.
Returns:: (ok, validation_message).
Return type:: tuple[bool, str]

class IUIProvider[source]#

Bases: ABC

Optional side interface for entities with a graphical editor/viewer.

Mirrors C++ IUIProvider. UI concerns were removed from IModelComponent and IComponentDataItem so the core standard stays headless; the owning component advertises Capability.UserInterface.

abstract property has_editor: bool#: Whether this entity has a UI editor.

abstractmethod show_editor(opaque_ui_pointer=None)[source]#

Show the editor for this entity.

Parameters:: opaque_ui_pointer (object)
Return type:: None

abstract property has_viewer: bool#: Whether this entity has a UI viewer.

abstractmethod show_viewer(opaque_ui_pointer=None)[source]#

Show the viewer for this entity.

Parameters:: opaque_ui_pointer (object)
Return type:: None

class IModelComponentInfo[source]#

Bases: IComponentInfo

Metadata about an IModelComponent; creates instances of it.

Mirrors C++ IModelComponentInfo.

abstractmethod create_component_instance()[source]#

Create a new IModelComponent instance.

Return type:: IModelComponent

abstract property adapted_output_factories: list[IAdaptedOutputFactory]#: Factories for creating adapted outputs for this component.

class IModelComponent[source]#

Bases: IIdentity

The core interface defining a model component.

Mirrors C++ IModelComponent. Also an ISignal<shared_ptr<IComponentStatusChangeEventArgs>>: status-changed slots are called as slot(event_args: IComponentStatusChangeEventArgs).

Lifecycle: initialize() -> validate() -> prepare() -> update()... -> finish(); legal status transitions are encoded by hydrocouple.helpers.is_valid_component_status_transition().

abstract property component_info: IModelComponentInfo | None#: Metadata about this component instance.

abstract property status: ComponentStatus#: Current lifecycle status of this component.

abstract property arguments: list[IArgument]#

Arguments needed to let the component do its work.

Available as soon as the instance is created; the entire persistent configuration of a component must be expressible through them.

abstract property inputs: list[IInput]#: Consumer items through which this component can receive values.

abstract property outputs: list[IOutput]#: Producer items through which this component provides results.

abstract property results: list[IComponentDataItem]#: The model’s output result data items.

abstractmethod initialize()[source]#

Initialize the component from its arguments.

Return type:: None

abstractmethod validate()[source]#

Validate the populated instance after connections are made.

Returns:: Messages; with status Invalid at least one message indicates a fatal error.
Return type:: list[str]

abstractmethod prepare()[source]#

Prepare the component for calls to update().

Return type:: None

abstractmethod update(required_outputs=None)[source]#

Let the component update itself, reaching its next state.

Parameters:: required_outputs (Sequence[IOutput] | None)
Return type:: None

abstractmethod finish()[source]#

The last method invoked; writes final results, frees resources.

Return type:: None

abstract property workflow: IWorkflowComponent | None#: The workflow this component is part of, or None.

abstractmethod capabilities()[source]#

The optional capabilities this component supports.

Components with no optional capabilities return an empty set.

Return type:: set[Capability]

abstractmethod errors(clear_after_read=False)[source]#

Drain this component’s diagnostic queue.

Implementations must queue an entry for every Warning-or-worse condition and a Fatal entry whenever status becomes Failed.

Parameters:: clear_after_read (bool)
Return type:: list[ErrorEntry]

abstract property reference_directory: str#: Directory from which this component’s relative paths resolve.

class IComponentStatusChangeEventArgs[source]#

Bases: ABC

Payload of a component status-changed signal.

Mirrors C++ IComponentStatusChangeEventArgs.

abstract property component: IModelComponent#: The component that fired the event.

abstract property previous_status: ComponentStatus#: Status before the change.

abstract property status: ComponentStatus#: Status after the change.

abstract property message: str#: Details about the status change.

abstract property has_progress_monitor: bool#: Whether percent_progress is meaningful.

abstract property percent_progress: float#: Progress in percent (0-100).

class ICloneableModelComponent[source]#

Bases: IModelComponent

A model component supporting deep cloning.

Mirrors C++ ICloneableModelComponent; the owning component advertises Capability.Cloneable.

abstract property parent: ICloneableModelComponent | None#: The component this instance was cloned from.

abstractmethod clone(clone_optional_arguments=None)[source]#

Deep clone this component, including its arguments.

Argument values are string-encoded (numeric values in decimal form).

Parameters:: clone_optional_arguments (dict[str, str] | None)
Return type:: ICloneableModelComponent

abstract property clones: list[ICloneableModelComponent]#: Components cloned from this instance.

class ICheckpointableModelComponent[source]#

Bases: IModelComponent

A model component that can save and restore its complete state.

Mirrors C++ ICheckpointableModelComponent; the owning component advertises Capability.Checkpointing. During save/restore the status is ComponentStatus.Checkpointing.

abstractmethod save_state()[source]#

Save the component’s complete state.

Returns:: (ok, token, message) where token is an opaque identifier with which the state can be restored later.
Return type:: tuple[bool, str, str]

abstractmethod restore_state(token)[source]#

Restore state previously saved by save_state().

Returns:: (ok, message).
Parameters:: token (str)
Return type:: tuple[bool, str]

class IValueDefinition[source]#

Bases: IDescription

Describes the type and properties of values of a data item.

Mirrors C++ IValueDefinition. Implement IQuality or IQuantity, not this directly.

abstract property type: type#: The Python type of the values (mirror of C++ type_info).

abstract property missing_value: float#

Value representing missing data.

Meaningful for numeric DataKinds only; for String/Opaque kinds the value must be ignored.

abstract property default_value: float#: Default value for this definition (numeric DataKinds only).

class IDimension[source]#

Bases: IIdentity

Properties of one dimension of a variable.

Mirrors C++ IDimension.

abstract property length_type: LengthType#: Whether the dimension extent is static or dynamic.

class IQuality[source]#

Bases: IValueDefinition

Qualitative (categorical) value definition.

Mirrors C++ IQuality. Data values are indexes into categories.

abstract property categories: list[str]#

The category labels allowed for this quality.

Ordered qualities list them in their defined sequence.

abstract property is_ordered: bool#: Whether the categories form an ordered set.

class IUnitDimensions[source]#

Bases: IDescription

Powers of the fundamental dimensions of a unit.

Mirrors C++ IUnitDimensions.

abstractmethod power(dimension)[source]#

The power of the given fundamental dimension (e.g. Length -> 3 and Time -> -1 for flow in m3/s).

Parameters:: dimension (FundamentalUnitDimension)
Return type:: float

class IUnit[source]#

Bases: IDescription

The physical unit of an IQuantity.

Mirrors C++ IUnit.

abstract property dimensions: IUnitDimensions#: Fundamental dimensions of the unit.

abstract property conversion_factor_to_si: float#

SI-value = A * value + B.

Type:: ‘A’ in

abstract property offset_to_si: float#

SI-value = A * value + B.

Type:: ‘B’ in

class IQuantity[source]#

Bases: IValueDefinition

Quantitative value definition with a unit.

Mirrors C++ IQuantity.

abstract property unit: IUnit#: Unit of this quantity.

abstract property min_value: float#: Minimum allowed value.

abstract property max_value: float#: Maximum allowed value.

class IComponentDataItemValueChanged[source]#

Bases: ABC

Payload of a data-item value-changed signal.

Mirrors C++ IComponentDataItemValueChanged.

abstract property component_data_item: IComponentDataItem#: The data item that fired the event.

abstract property start: list[int]#: First changed index in each dimension.

abstract property count: list[int]#: Changed extent in each dimension.

class IComponentDataItem[source]#

Bases: IIdentity

A fundamental unit of typed, multi-dimensional data for a component.

Mirrors C++ IComponentDataItem. Also an ISignal<shared_ptr<IComponentDataItemValueChanged>>; value-changed slots are called as slot(event_args).

Data access is typed and bulk-oriented: all field data moves through get_values_into() / set_values_from() as hyperslab selections copied into/from NumPy arrays whose dtype must correspond to data_kind (see hydrocouple.helpers.DATA_KIND_TO_DTYPE). Dimension semantics (which axis is time, entity, layer, …) are described by dimensions and by the canonical orderings documented on each specialization.

abstract property model_component: IModelComponent | None#: The owner component of this item, or None.

abstract property dimensions: list[IDimension]#: Descriptive metadata for each dimension.

abstract property shape: tuple[int, ...]#: The extent of each dimension, parallel to dimensions.

abstract property data_kind: DataKind#: The element type of this item’s values.

abstract property value_definition: IValueDefinition#: The value definition (an IQuality or IQuantity).

abstractmethod get_values_into(destination, start, count)[source]#

Copy a hyperslab of this item’s values into destination.

The selection is the box [start[k], start[k] + count[k]) in each dimension k of shape. destination.dtype must correspond to data_kind (no implicit conversion) and destination.size must equal the product of count. destination may be non-contiguous (strided views are honored).

Returns:

(ok, message).

Parameters:

destination (np.ndarray)
start (Sequence[int])
count (Sequence[int])

Return type:

tuple[bool, str]

abstractmethod set_values_from(source, start, count)[source]#

Copy values from source into a hyperslab of this item.

Selection and compatibility rules are identical to get_values_into().

Returns:

(ok, message).

Parameters:

source (np.ndarray)
start (Sequence[int])
count (Sequence[int])

Return type:

tuple[bool, str]

class IIdBasedComponentDataItem[source]#

Bases: IComponentDataItem

An IComponentDataItem indexed by string identifiers.

Mirrors C++ IIdBasedComponentDataItem. Canonical dimension ordering: the identifier dimension is dimension 0 of shape; data access uses the inherited hyperslab API with the identifier index as start[0].

abstract property identifiers: list[str]#: The identifiers of this item’s identifier dimension.

abstract property identifier_dimension: IDimension#: The identifier dimension (dimension 0 of shape).

class IArgument[source]#

Bases: IComponentDataItem

Configuration argument of a component or adapted output.

Mirrors C++ IArgument. Arguments are the normative serialization unit: a component’s entire persistent configuration must be expressible through its arguments, so any driver can round-trip a component without knowing its internals.

abstract property is_optional: bool#: Whether this argument is optional.

abstract property is_read_only: bool#: Whether the argument’s values may not be edited.

abstractmethod save_data()[source]#

Write data to files associated with this argument, if any.

Return type:: None

abstract property file_filters: list[str]#: File filters readable by this argument, e.g. "Configuration Files (*.yaml *.yml *.json)".

abstract property valid_component_data_item_types: list[type]#: Data item types this argument can be initialized from.

abstractmethod is_valid_arg_type(arg_type)[source]#

Whether the given input representation is supported.

Parameters:: arg_type (ArgumentInputType)
Return type:: bool

abstract property current_argument_input_type: ArgumentInputType#: How this argument was initialized.

abstractmethod initialize(value, arg_type=None)[source]#

Read the argument value from a string representation or an equivalent IComponentDataItem.

Returns:

(ok, message).

Parameters:

value (str | IComponentDataItem)
arg_type (ArgumentInputType | None)

Return type:

tuple[bool, str]

abstractmethod serialize(arg_type)[source]#

Serialize the current value to the requested representation.

The write-side counterpart of initialize(). For large field payloads implementations must not inline bulk data into text formats: the serialized form should carry an external binary payload reference (URI, DataKind, and shape inline; bulk bytes in a sidecar), with inline text arrays only for small payloads.

Returns:: (ok, value, message).
Parameters:: arg_type (ArgumentInputType)
Return type:: tuple[bool, str, str]

class IExchangeItemChangeEventArgs[source]#

Bases: ABC

Payload of an exchange-item-changed signal.

Mirrors C++ IExchangeItemChangeEventArgs.

abstract property exchange_item: IExchangeItem#: The exchange item that fired the signal.

abstract property message: str#: Message associated with the event.

class IExchangeItem[source]#

Bases: IComponentDataItem

Base data item exchangeable between components at runtime.

Mirrors C++ IExchangeItem; implement IInput or IOutput.

class IOutput[source]#

Bases: IExchangeItem

An output exchange item that delivers values from a component.

Mirrors C++ IOutput.

abstract property consumers: list[IInput]#: Inputs that will consume this output’s values.

abstractmethod add_consumer(consumer)[source]#

Add a consumer to this output.

Parameters:: consumer (IInput)
Return type:: None

abstractmethod remove_consumer(consumer)[source]#

Remove a consumer from this output.

Parameters:: consumer (IInput)
Return type:: bool

abstract property adapted_outputs: list[IAdaptedOutput]#: Adapted outputs that adapt this output.

abstractmethod add_adapted_output(adapted_output)[source]#

Add an adapted output to this output.

Parameters:: adapted_output (IAdaptedOutput)
Return type:: None

abstractmethod remove_adapted_output(adapted_output)[source]#

Remove an adapted output from this output.

Parameters:: adapted_output (IAdaptedOutput)
Return type:: bool

abstractmethod update_values(query_specifier)[source]#

Provide values matching the query specifier’s requirements.

Parameters:: query_specifier (IInput)
Return type:: None

class IAdaptedOutput[source]#

Bases: IOutput

Adds data operations (interpolation, aggregation, unit conversion, …) on top of an adaptee IOutput.

Mirrors C++ IAdaptedOutput.

abstract property adapted_output_factory: IAdaptedOutputFactory#: The factory that generated this adapted output.

abstract property arguments: list[IArgument]#: Arguments configuring this adapted output.

abstractmethod initialize()[source]#

Initialize based on the current argument values.

Return type:: None

abstract property adaptee: IOutput#: The output being adapted.

abstractmethod refresh()[source]#

Refresh after the adaptee has been updated; must cascade to child adapted outputs.

Return type:: None

class IAdaptedOutputFactory[source]#

Bases: IIdentity

Creates IAdaptedOutput instances.

Mirrors C++ IAdaptedOutputFactory.

abstractmethod get_available_adapted_output_ids(provider, consumer=None)[source]#

Identifiers of adapted outputs that can adapt the provider.

Parameters:

provider (IOutput)
consumer (IInput | None)

Return type:

list[IIdentity]

abstractmethod create_adapted_output(adapted_provider_id, provider, consumer=None)[source]#

Create an adapted output that fits the provider to the consumer.

Parameters:

adapted_provider_id (IIdentity)
provider (IOutput)
consumer (IInput | None)

Return type:

IAdaptedOutput

class IAdaptedOutputFactoryComponentInfo[source]#

Bases: IComponentInfo

Metadata about an IAdaptedOutputFactoryComponent.

Mirrors C++ IAdaptedOutputFactoryComponentInfo.

abstractmethod create_component_instance()[source]#

Create a new factory component instance.

Return type:: IAdaptedOutputFactoryComponent

class IAdaptedOutputFactoryComponent[source]#

Bases: IAdaptedOutputFactory

An adapted-output factory generated from a component info.

Mirrors C++ IAdaptedOutputFactoryComponent.

abstract property component_info: IAdaptedOutputFactoryComponentInfo#: Metadata about this factory component.

class IInput[source]#

Bases: IExchangeItem

An input exchange item that accepts values for a component.

Mirrors C++ IInput.

abstract property provider: IOutput | None#: The output this input gets its values from.

abstractmethod set_provider(provider)[source]#

Set the provider of this input.

Parameters:: provider (IOutput | None)
Return type:: bool

abstractmethod can_consume(provider)[source]#

Whether this input can consume the given provider.

Returns:: (ok, message).
Parameters:: provider (IOutput)
Return type:: tuple[bool, str]

class IMultiInput[source]#

Bases: IInput

An input supplied by multiple providers.

Mirrors C++ IMultiInput.

abstract property provider_labels: list[IIdentity]#: Role labels for the providers required by this consumer.

abstractmethod is_required_provider(provider_label)[source]#

Whether the labeled provider role is required.

Parameters:: provider_label (IIdentity)
Return type:: bool

abstract property providers: list[IOutput]#: The providers supplying data to this input.

abstractmethod add_provider(provider, provider_role_identifier=None)[source]#

Add a provider.

Parameters:

provider (IOutput)
provider_role_identifier (IIdentity | None)

Return type:

bool

abstractmethod remove_provider(provider)[source]#

Remove a provider.

Parameters:: provider (IOutput)
Return type:: bool

class IWorkflowComponentInfo[source]#

Bases: IComponentInfo

Metadata about an IWorkflowComponent.

Mirrors C++ IWorkflowComponentInfo.

abstractmethod create_component_instance()[source]#

Create a new workflow component instance.

Return type:: IWorkflowComponent

class IWorkflowComponent[source]#

Bases: IIdentity

Orchestrates the execution of a set of coupled model components.

Mirrors C++ IWorkflowComponent. Also an ISignal<shared_ptr<IWorkflowComponentStatusChangeEventArgs>>.

abstract property component_info: IWorkflowComponentInfo | None#: Metadata about this workflow component.

abstract property model_component_labels: list[IIdentity]#: Role labels of the model components required by this workflow.

abstractmethod is_required_model_component(label)[source]#

Whether the labeled component role is required.

Parameters:: label (IIdentity)
Return type:: bool

abstractmethod initialize()[source]#

Initialize the workflow.

Return type:: None

abstractmethod update()[source]#

Update the workflow for the current step.

Return type:: None

abstractmethod finish()[source]#

Finalize the workflow and release resources.

Return type:: None

abstract property status: WorkflowStatus#: Current workflow status.

abstract property model_components: list[IModelComponent]#: The model components managed by this workflow.

abstractmethod add_model_component(component, model_role_identifier=None)[source]#

Add a model component to the workflow.

Parameters:

component (IModelComponent)
model_role_identifier (IIdentity | None)

Return type:

bool

abstractmethod remove_model_component(component)[source]#

Remove a model component from the workflow.

Parameters:: component (IModelComponent)
Return type:: bool

class IWorkflowComponentStatusChangeEventArgs[source]#

Bases: ABC

Payload of a workflow status-changed signal.

Mirrors C++ IWorkflowComponentStatusChangeEventArgs.

abstract property workflow_component: IWorkflowComponent#: The workflow component that fired the event.

abstract property previous_status: WorkflowStatus#: Status before the change.

abstract property status: WorkflowStatus#: Status after the change.

abstract property message: str#: Details about the status change.

abstract property has_progress_monitor: bool#: Whether percent_progress is meaningful.

abstract property percent_progress: float#: Progress in percent (0-100).

hydrocouple.temporal #

Date/time representation, time spans, time-marching model components, and time-series data items (time is canonical dimension 0).

HydroCouple temporal abstract base classes.

Python ABC mirrors of the C++ HydroCouple v2.0.0 interfaces defined in hydrocoupletemporal.h: date/time representation, time spans, time-marching model components, and time-series component data items.

class IDateTime[source]#

Bases: IPropertyChanged

A date/time based on a Julian day.

Mirrors C++ Temporal::IDateTime. The normative convention is the astronomical Julian day number in the proleptic Gregorian (“standard”) calendar, UTC; persistence layers writing CF metadata should emit units = "days since ..." with calendar = "standard".

abstract property julian_day: float#: Date and time as a Julian day value.

abstract property modified_julian_day: float#: Modified Julian day value.

abstract property serial_date: float#: Serial date number.

class ITimeSpan[source]#

Bases: IDateTime

A time duration anchored at a start date/time.

Mirrors C++ Temporal::ITimeSpan.

abstract property duration: float#: Duration of the timespan in days.

class ITimeModelComponent[source]#

Bases: IModelComponent

A model component that advances through time during simulation.

Mirrors C++ Temporal::ITimeModelComponent.

abstract property current_date_time: IDateTime#: Current date and time of the model simulation.

abstract property simulation_period: ITimeSpan#: The time horizon of the model.

class ITimeSeriesComponentDataItem[source]#

Bases: IComponentDataItem

An IComponentDataItem with a temporal dimension.

Mirrors C++ Temporal::ITimeSeriesComponentDataItem. Canonical dimension ordering: time is dimension 0 of shape; any additional dimensions follow. Data access uses the inherited get_values_into() / set_values_from() hyperslab API with the time index as start[0], so “current time step, all entities” is a contiguous slab.

abstractmethod time(time_index)[source]#

The IDateTime at the given time index (spot queries).

Parameters:: time_index (int)
Return type:: IDateTime

abstract property time_count: int#: The number of times.

abstract property times: np.ndarray#

Bulk access to all time coordinates as Julian day values.

A float64 array of time_count elements ordered with the time dimension; the accessor IO writers and interpolating adapters must use.

abstract property time_span: ITimeSpan#: The time span covered by this data item.

abstract property time_dimension: IDimension#: The time dimension (dimension 0 of shape).

class ITimeIdBasedComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem

A time-series data item whose entity dimension is identifier-based.

Mirrors C++ Temporal::ITimeIdBasedComponentDataItem. Canonical dimension ordering: time is dimension 0, the identifier dimension is dimension 1 of shape; any additional dimensions follow.

abstract property identifiers: list[str]#: The identifiers of the identifier dimension.

abstract property identifier_dimension: IDimension#: The identifier dimension (dimension 1 of shape).

hydrocouple.spatial #

OGC Simple Features geometry, spatial reference systems, the UGRID-congruent IMeshView bulk structure-of-arrays view, rasters, regular grids, and the spatial data items.

HydroCouple geospatial abstract base classes.

Python ABC mirrors of the C++ HydroCouple v2.0.0 interfaces defined in hydrocouplespatial.h: OGC Simple Features geometry types, spatial reference systems, mesh/network structures with bulk structure-of-arrays views, rasters, regular grids, and the spatial component data items.

Bulk accessors (IMeshView, grid coordinate arrays) return NumPy arrays and are the accessors partitioners, interpolating adapters, IO writers, and device staging must use; per-entity object accessors are a convenience for spot queries and editing.

class MeshDataObjectType(*values)[source]#

Bases: IntEnum

Part of a mesh’s geometry that data corresponds to.

Mirrors C++ Spatial::MeshDataObjectType.

Cell = 0#

Vertex = 1#

Edge = 2#

Face = 3#

class NetworkDataObjectType(*values)[source]#

Bases: IntEnum

Part of a network that data corresponds to.

Mirrors C++ Spatial::NetworkDataObjectType.

Node = 0#

Edge = 1#

class SpatialDataType(*values)[source]#

Bases: IntEnum

Structure of per-entity values.

Mirrors C++ Spatial::SpatialDataType.

Scalar = 0#

MultiScalar = 1#

Vector = 2#

Tensor = 3#

class RegularGridType(*values)[source]#

Bases: IntEnum

Type of a regular grid.

Mirrors C++ Spatial::RegularGridType.

Cartesian = 0#

Rectilinear = 1#

Curvilinear = 2#

class GeometryType(*values)[source]#

Bases: IntEnum

OGC geometry type codes mirroring C++ IGeometry::GeometryType.

Geometry = 0#

Point = 1#

LineString = 2#

Polygon = 3#

MultiPoint = 4#

MultiLineString = 5#

MultiPolygon = 6#

GeometryCollection = 7#

CircularString = 8#

CompoundCurve = 9#

CurvePolygon = 10#

MultiCurve = 11#

MultiSurface = 12#

Curve = 13#

Surface = 14#

PolyhedralSurface = 15#

TIN = 16#

Triangle = 17#

GeometryZ = 1000#

PointZ = 1001#

LineStringZ = 1002#

PolygonZ = 1003#

MultiPointZ = 1004#

MultiLineStringZ = 1005#

MultiPolygonZ = 1006#

GeometryCollectionZ = 1007#

CircularStringZ = 1008#

CompoundCurveZ = 1009#

CurvePolygonZ = 1010#

MultiCurveZ = 1011#

MultiSurfaceZ = 1012#

CurveZ = 1013#

SurfaceZ = 1014#

PolyhedralSurfaceZ = 1015#

TINZ = 1016#

TriangleZ = 1017#

GeometryM = 2000#

PointM = 2001#

LineStringM = 2002#

PolygonM = 2003#

MultiPointM = 2004#

MultiLineStringM = 2005#

MultiPolygonM = 2006#

GeometryCollectionM = 2007#

CircularStringM = 2008#

CompoundCurveM = 2009#

CurvePolygonM = 2010#

MultiCurveM = 2011#

MultiSurfaceM = 2012#

CurveM = 2013#

SurfaceM = 2014#

PolyhedralSurfaceM = 2015#

TINM = 2016#

TriangleM = 2017#

GeometryZM = 3000#

PointZM = 3001#

LineStringZM = 3002#

PolygonZM = 3003#

MultiPointZM = 3004#

MultiLineStringZM = 3005#

MultiPolygonZM = 3006#

GeometryCollectionZM = 3007#

CircularStringZM = 3008#

CompoundCurveZM = 3009#

CurvePolygonZM = 3010#

MultiCurveZM = 3011#

MultiSurfaceZM = 3012#

CurveZM = 3013#

SurfaceZM = 3014#

PolyhedralSurfaceZM = 3015#

TINZM = 3016#

TriangleZM = 3017#

class RasterDataType(*values)[source]#

Bases: IntEnum

Raster band element type mirroring C++ IRaster::RasterDataType.

Unknown = 0#

Byte = 1#

UInt16 = 2#

Int16 = 3#

UInt32 = 4#

Int32 = 5#

Float32 = 6#

Float64 = 7#

CInt16 = 8#

CInt32 = 9#

CFloat32 = 10#

CFloat64 = 11#

ARGB32 = 12#

ARGB32_Premultiplied = 13#

class ISpatialReferenceSystem[source]#

Bases: ABC

Spatial reference system of a geometric object.

Mirrors C++ Spatial::ISpatialReferenceSystem.

abstract property auth_srid: int#: The authority-specific spatial reference id (e.g. EPSG code).

abstract property auth_name: str#: The authority name (e.g. "EPSG").

abstract property sr_text: str#: Well-known text representation of the SRS.

abstract property distance_units: DistanceUnits#: The measurement distance units of the SRS.

class IEnvelope[source]#

Bases: ABC

Axis-aligned bounding box.

Mirrors C++ Spatial::IEnvelope.

abstract property min_x: float#: Minimum x.

abstract property max_x: float#: Maximum x.

abstract property min_y: float#: Minimum y.

abstract property max_y: float#: Maximum y.

abstract property min_z: float#: Minimum z.

abstract property max_z: float#: Maximum z.

class IGeometry[source]#

Bases: ABC

Base OGC geometry.

Mirrors C++ Spatial::IGeometry.

abstract property id: str#: Id of the geometry.

abstract property index: int#: Index of the geometry within a collection.

abstract property dimension: int#

0 points, 1 lines, 2 surfaces.

Type:: Topological dimension

abstract property coordinate_dimension: int#: Dimension of the coordinates (2 or 3; 0 for an empty point).

abstract property geometry_type: GeometryType#: The instantiable OGC subtype of this geometry.

abstract property spatial_reference_system: ISpatialReferenceSystem#: The SRS of this geometry.

abstract property envelope: IEnvelope#: The bounding envelope of this geometry.

abstractmethod get_wkt()[source]#

Well-known text representation.

Return type:: str

abstractmethod get_wkb()[source]#

Well-known binary representation.

Return type:: bytes

abstract property is_empty: bool#: Whether this geometry is the empty geometry.

abstract property is_simple: bool#: Whether this geometry has no anomalous points.

abstract property is_3d: bool#: Whether this geometry has z coordinates.

abstract property is_measured: bool#: Whether this geometry has m values.

abstract property boundary: IGeometry#: The closure of the combinatorial boundary.

abstractmethod equals(geom)[source]#

Spatial equality.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod disjoint(geom)[source]#

Spatially disjoint.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod intersects(geom)[source]#

Spatially intersects.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod touches(geom)[source]#

Spatially touches.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod crosses(geom)[source]#

Spatially crosses.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod within(geom)[source]#

Spatially within.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod contains(geom)[source]#

Spatially contains.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod overlaps(geom)[source]#

Spatially overlaps.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod relate(geom)[source]#

DE-9IM relation test.

Parameters:: geom (IGeometry)
Return type:: bool

abstractmethod locate_along(value)[source]#

The m-locate-along geometry.

Parameters:: value (float)
Return type:: IGeometry

abstractmethod locate_between(m_start, m_end)[source]#

The m-locate-between geometry.

Parameters:

m_start (float)
m_end (float)

Return type:

IGeometry

abstractmethod distance(geom)[source]#

Shortest distance to another geometry.

Parameters:: geom (IGeometry)
Return type:: float

abstractmethod buffer(buffer_distance)[source]#

All points within the given distance of this geometry.

Parameters:: buffer_distance (float)
Return type:: IGeometry

abstractmethod convex_hull()[source]#

The convex hull.

Return type:: IGeometry

abstractmethod intersection(geom)[source]#

Point-set intersection.

Parameters:: geom (IGeometry)
Return type:: IGeometry

abstractmethod union(geom)[source]#

Point-set union (C++ unionG).

Parameters:: geom (IGeometry)
Return type:: IGeometry

abstractmethod difference(geom)[source]#

Point-set difference.

Parameters:: geom (IGeometry)
Return type:: IGeometry

abstractmethod symmetric_difference(geom)[source]#

Point-set symmetric difference.

Parameters:: geom (IGeometry)
Return type:: IGeometry

class IGeometryCollection[source]#

Bases: IGeometry

A collection of geometries. Mirrors C++ IGeometryCollection.

abstract property geometry_count: int#: Number of geometries in the collection.

abstractmethod geometry(index)[source]#

The geometry at the given index.

Parameters:: index (int)
Return type:: IGeometry

class IPoint[source]#

Bases: IGeometry

A 0-dimensional point. Mirrors C++ IPoint.

abstract property x: float#: x coordinate.

abstract property y: float#: y coordinate.

abstract property z: float#: z coordinate (when IGeometry.is_3d).

abstract property m: float#: m value (when IGeometry.is_measured).

class IMultiPoint[source]#

Bases: IGeometryCollection

A collection of points. Mirrors C++ IMultiPoint.

abstractmethod point(index)[source]#

The point at the given index.

Parameters:: index (int)
Return type:: IPoint

class IVertex[source]#

Bases: IPoint

A point participating in topology. Mirrors C++ IVertex.

abstract property vertex_index: int#: Unique vertex index (C++ index(); renamed to avoid clashing with IGeometry.index).

abstract property edge: IEdge#: An arbitrary outgoing edge of this vertex.

class ICurve[source]#

Bases: IGeometry

A 1-dimensional geometry. Mirrors C++ ICurve.

abstract property length: float#: Curve length.

abstract property start_point: IPoint#: First point of the curve.

abstract property end_point: IPoint#: Last point of the curve.

abstract property is_closed: bool#: Whether start and end points coincide.

abstract property is_ring: bool#: Whether the curve is closed and simple.

class IMultiCurve[source]#

Bases: IGeometryCollection

A collection of curves. Mirrors C++ IMultiCurve.

abstract property is_closed: bool#: Whether every member curve is closed.

abstract property length: float#: Total length of the member curves.

class ILineString[source]#

Bases: ICurve

A curve with linear interpolation between points.

Mirrors C++ ILineString.

abstract property point_count: int#: Number of points in the line string.

abstractmethod point(index)[source]#

The point at the given index.

Parameters:: index (int)
Return type:: IPoint

class IMultiLineString[source]#

Bases: IMultiCurve

A collection of line strings. Mirrors C++ IMultiLineString.

abstractmethod line_string(index)[source]#

The line string at the given index.

Parameters:: index (int)
Return type:: ILineString

class ILine[source]#

Bases: ILineString

A line string with exactly two points. Mirrors C++ ILine.

class ILinearRing[source]#

Bases: ILineString

A closed, simple line string. Mirrors C++ ILinearRing.

class IEdge[source]#

Bases: ABC

A quad-edge topology edge.

Mirrors C++ IEdge. Per-entity topology navigation is a convenience for spot queries and editing; bulk consumers must use IMeshView.

abstract property index: int#: Unique edge index.

abstract property orig: IVertex | None#: Origin vertex, or None if unknown.

abstract property dest: IVertex | None#: Destination vertex, or None if unknown.

abstract property left: IPolygon | None#: Left face, or None if unknown.

abstract property right: IPolygon | None#: Right face, or None if unknown.

abstract property face: IPolygon | None#: Target face if dual, else None.

abstract property rot: IEdge#: Dual edge, right-to-left.

abstract property inv_rot: IEdge#: Dual edge, left-to-right.

abstract property sym: IEdge#: The edge from dest to orig.

abstract property orig_next: IEdge#: Next ccw edge around the origin.

abstract property orig_prev: IEdge#: Next cw edge around the origin.

abstract property dest_next: IEdge#: Next ccw edge around the destination.

abstract property dest_prev: IEdge#: Next cw edge around the destination.

abstract property left_next: IEdge#: Ccw edge around the left face after this edge.

abstract property left_prev: IEdge#: Ccw edge around the left face before this edge.

abstract property right_next: IEdge#: Ccw edge around the right face after this edge.

abstract property right_prev: IEdge#: Ccw edge around the right face before this edge.

class ISurface[source]#

Bases: IGeometry

A 2-dimensional geometry. Mirrors C++ ISurface.

abstract property area: float#: Surface area.

abstract property centroid: IPoint#: Mathematical centroid (not necessarily on the surface).

abstract property point_on_surface: IPoint#: A point guaranteed to be on the surface.

abstract property boundary_multi_curve: IMultiCurve#: The boundary curves of the surface.

class IMultiSurface[source]#

Bases: IGeometryCollection

A collection of surfaces. Mirrors C++ IMultiSurface.

abstract property area: float#: Total area of the member surfaces.

abstract property centroid: IPoint#: Mathematical centroid.

abstract property point_on_surface: IPoint#: A point guaranteed to be on one of the member surfaces.

class IPolygon[source]#

Bases: ISurface

A planar surface with an exterior ring and interior rings.

Mirrors C++ IPolygon.

abstract property exterior_ring: ILineString#: The exterior boundary ring.

abstract property interior_ring_count: int#: Number of interior rings (holes).

abstractmethod interior_ring(index)[source]#

The interior ring at the given index.

Parameters:: index (int)
Return type:: ILineString

abstract property edge: IEdge | None#: An arbitrary boundary edge, when the polygon participates in topology.

abstract property polyhedral_surface: IPolyhedralSurface | None#: The polyhedral surface this polygon is a patch of, if any.

class IMultiPolygon[source]#

Bases: IMultiSurface

A collection of polygons. Mirrors C++ IMultiPolygon.

abstractmethod polygon(index)[source]#

The polygon at the given index.

Parameters:: index (int)
Return type:: IPolygon

class ITriangle[source]#

Bases: IPolygon

A triangular polygon. Mirrors C++ ITriangle.

abstract property vertex1: IVertex#: First vertex.

abstract property vertex2: IVertex#: Second vertex.

abstract property vertex3: IVertex#: Third vertex.

abstractmethod vertex(index)[source]#

The vertex at the given index (0-2).

Parameters:: index (int)
Return type:: IVertex

class IMeshView[source]#

Bases: ABC

Bulk, structure-of-arrays view of an unstructured mesh or network.

Mirrors C++ Spatial::IMeshView: flat coordinate arrays plus CSR (compressed sparse row) connectivity, deliberately congruent with the UGRID conventions so persistence, message packing, and device staging can consume the view without transformation. Arrays remain valid until the underlying mesh topology or geometry changes.

abstract property node_count: int#: Number of nodes (vertices).

abstract property edge_count: int#: Number of edges.

abstract property face_count: int#: Number of faces (patches/cells); 0 for a pure network.

abstract property node_x: np.ndarray#: x coordinates of all nodes (float64, node_count).

abstract property node_y: np.ndarray#: y coordinates of all nodes (float64, node_count).

abstract property node_z: np.ndarray#: z coordinates of all nodes; empty for a 2D mesh.

abstract property face_node_offsets: np.ndarray#: CSR row offsets into face_nodes (int64, face_count + 1 elements; empty for a pure network).

abstract property face_nodes: np.ndarray#: Concatenated node indexes of all faces, ccw per face (int64).

abstract property edge_nodes: np.ndarray#: Node index pairs of all edges (int64, 2 * edge_count): edge e connects edge_nodes[2*e] and edge_nodes[2*e+1].

class INetwork[source]#

Bases: IIdentity

A graph of connected vertices and edges.

Mirrors C++ Spatial::INetwork.

abstract property edge_count: int#: Number of edges in the network.

abstractmethod edge(index)[source]#

The edge at the given index (spot queries).

Parameters:: index (int)
Return type:: IEdge

abstract property vertex_count: int#: Number of vertices in the network.

abstractmethod vertex(index)[source]#

The vertex at the given index (spot queries).

Parameters:: index (int)
Return type:: IVertex

abstract property mesh_view: IMeshView#: Bulk structure-of-arrays view of this network.

class IPolyhedralSurface[source]#

Bases: ISurface

A contiguous collection of polygon patches stitched along shared boundary edges.

Mirrors C++ Spatial::IPolyhedralSurface.

abstract property patch_count: int#: Number of polygon patches.

abstractmethod patch(index)[source]#

The patch at the given index (spot queries).

Parameters:: index (int)
Return type:: IPolygon

abstract property vertex_count: int#: Number of vertices.

abstractmethod vertex(index)[source]#

The vertex at the given index (spot queries).

Parameters:: index (int)
Return type:: IVertex

abstractmethod bounding_polygons(polygon)[source]#

The polygons bounding the given polygon.

Parameters:: polygon (IPolygon)
Return type:: IMultiPolygon

abstract property is_closed: bool#: Whether the surface is closed and therefore bounds a solid.

abstract property mesh_view: IMeshView#: Bulk structure-of-arrays view of this surface.

class ITIN[source]#

Bases: IPolyhedralSurface

A triangulated irregular network of ITriangle patches.

Mirrors C++ Spatial::ITIN.

abstractmethod triangle(index)[source]#

The triangle at the given index.

Parameters:: index (int)
Return type:: ITriangle

class IRaster[source]#

Bases: IIdentity

A raster spatial feature.

Mirrors C++ Spatial::IRaster.

abstract property x_size: int#: Number of columns.

abstract property y_size: int#: Number of rows.

abstract property raster_band_count: int#: Number of bands.

abstractmethod add_raster_band(data_type)[source]#

Add a band of the given element type.

Parameters:: data_type (RasterDataType)
Return type:: None

abstract property spatial_reference_system: ISpatialReferenceSystem#: The SRS of this raster.

abstractmethod geo_transformation()[source]#

The six-element affine geotransform (float64).

Return type:: np.ndarray

abstractmethod get_raster_band(band_index)[source]#

The band at the given index.

Parameters:: band_index (int)
Return type:: IRasterBand

class IRasterBand[source]#

Bases: IIdentity

One band of an IRaster.

Mirrors C++ Spatial::IRasterBand. Block read/write is the storage-level accessor; the canonical exchange path is the raster component data item’s hyperslab API.

abstract property x_size: int#: Number of columns.

abstract property y_size: int#: Number of rows.

abstract property raster: IRaster#: The owning raster.

abstract property data_type: RasterDataType#: Element type of this band.

abstractmethod read(x_offset, y_offset, x_size, y_size)[source]#

Read a block as a [y_size, x_size] array.

Parameters:

x_offset (int)
y_offset (int)
x_size (int)
y_size (int)

Return type:

np.ndarray

abstractmethod write(x_offset, y_offset, image)[source]#

Write a [y_size, x_size] block.

Parameters:

x_offset (int)
y_offset (int)
image (np.ndarray)

Return type:

None

abstract property no_data: float#: The no-data sentinel value.

class IRegularGrid2D[source]#

Bases: IIdentity

A two-dimensional structured grid of nodes and cells.

Mirrors C++ Spatial::IRegularGrid2D.

abstract property spatial_reference_system: ISpatialReferenceSystem#: The SRS of this grid.

abstract property grid_type: RegularGridType#: The type of regular grid.

abstract property num_x_nodes: int#: Number of nodes in the x direction.

abstract property num_y_nodes: int#: Number of nodes in the y direction.

abstractmethod x_node_location(x_node_index, y_node_index)[source]#

x coordinate of a node (spot queries; bulk consumers use node_xs).

Parameters:

x_node_index (int)
y_node_index (int)

Return type:

float

abstractmethod y_node_location(x_node_index, y_node_index)[source]#

y coordinate of a node (spot queries; bulk consumers use node_ys).

Parameters:

x_node_index (int)
y_node_index (int)

Return type:

float

abstract property node_xs: np.ndarray#: Bulk x coordinates of all nodes, row-major [y][x] (float64).

abstract property node_ys: np.ndarray#: Bulk y coordinates of all nodes, row-major [y][x] (float64).

abstractmethod is_active(x_cell_index, y_cell_index)[source]#

Whether a cell is active (spot queries; bulk consumers use active_cells).

Parameters:

x_cell_index (int)
y_cell_index (int)

Return type:

bool

abstract property active_cells: np.ndarray#: Bulk activity mask of all cells, row-major [y][x]; nonzero means active (uint8).

class IRegularGrid3D[source]#

Bases: IIdentity

A three-dimensional structured grid of nodes and cells.

Mirrors C++ Spatial::IRegularGrid3D.

abstract property spatial_reference_system: ISpatialReferenceSystem#: The SRS of this grid.

abstract property grid_type: RegularGridType#: The type of regular grid.

abstract property num_x_nodes: int#: Number of nodes in the x direction.

abstract property num_y_nodes: int#: Number of nodes in the y direction.

abstract property num_z_nodes: int#: Number of nodes in the z direction.

abstractmethod x_node_location(x_node_index, y_node_index)[source]#

x coordinate of a node (spot queries).

Parameters:

x_node_index (int)
y_node_index (int)

Return type:

float

abstractmethod y_node_location(x_node_index, y_node_index)[source]#

y coordinate of a node (spot queries).

Parameters:

x_node_index (int)
y_node_index (int)

Return type:

float

abstractmethod z_node_location(x_node_index, y_node_index, z_node_index)[source]#

z coordinate of a node (spot queries).

Parameters:

x_node_index (int)
y_node_index (int)
z_node_index (int)

Return type:

float

abstract property node_xs: np.ndarray#: Bulk x coordinates of a horizontal layer, row-major [y][x].

abstract property node_ys: np.ndarray#: Bulk y coordinates of a horizontal layer, row-major [y][x].

abstract property node_zs: np.ndarray#: Bulk z coordinates of all nodes, row-major [z][y][x].

abstractmethod is_active(x_cell_index, y_cell_index, z_cell_index)[source]#

Whether a cell is active (spot queries).

Parameters:

x_cell_index (int)
y_cell_index (int)
z_cell_index (int)

Return type:

bool

abstract property active_cells: np.ndarray#: Bulk activity mask of all cells, row-major [z][y][x] (uint8).

class IGeometryComponentDataItem[source]#

Bases: IComponentDataItem

Data associated with a collection of geometries.

Mirrors C++ Spatial::IGeometryComponentDataItem. Canonical dimension ordering: the geometry dimension is dimension 0 of shape; any additional dimensions follow.

abstract property geometry_type: GeometryType#: The type of the associated geometries.

abstract property geometry_count: int#: Number of associated geometries.

abstractmethod geometry(geometry_index)[source]#

The geometry at the given index.

Parameters:: geometry_index (int)
Return type:: IGeometry

abstract property geometry_dimension: IDimension#: The geometry dimension (dimension 0 of shape).

abstract property envelope: IEnvelope#: Envelope bounding all associated geometries.

class INetworkComponentDataItem[source]#

Bases: IComponentDataItem

Data associated with the edges and/or vertices of a network.

Mirrors C++ Spatial::INetworkComponentDataItem. Canonical dimension ordering: the entity dimension selected by network_data_type (edge or vertex) is dimension 0 of shape.

abstract property network: INetwork#: The associated network.

abstract property network_data_object_type: NetworkDataObjectType#: The kind of network object the values describe.

abstract property network_data_type: SpatialDataType#: The mesh entity the values are attached to.

abstract property edge_dimension: IDimension#: The network edge dimension.

abstract property vertex_dimension: IDimension#: The network vertex dimension.

class IPolyhedralSurfaceComponentDataItem[source]#

Bases: IComponentDataItem

Data associated with the patches, edges, or vertices of a polyhedral surface.

Mirrors C++ Spatial::IPolyhedralSurfaceComponentDataItem. Canonical dimension ordering: the entity dimension selected by mesh_data_type is dimension 0 of shape.

abstract property mesh_data_object_type: MeshDataObjectType#: The kind of mesh object the values describe.

abstract property mesh_data_type: SpatialDataType#: The mesh entity the values are attached to.

abstract property polyhedral_surface: IPolyhedralSurface#: The associated polyhedral surface.

abstract property patch_dimension: IDimension#: The surface patch dimension.

abstract property edge_dimension: IDimension#: The surface edge dimension.

abstract property vertex_dimension: IDimension#: The surface vertex dimension.

class ITINComponentDataItem[source]#

Bases: IPolyhedralSurfaceComponentDataItem

A polyhedral-surface data item whose surface is a TIN.

Mirrors C++ Spatial::ITINComponentDataItem.

abstract property tin: ITIN#: The associated TIN (C++ TIN()).

class IRasterComponentDataItem[source]#

Bases: IComponentDataItem

Data associated with a raster.

Mirrors C++ Spatial::IRasterComponentDataItem. Canonical dimension ordering: band is dimension 0, y (row) is dimension 1, x (column) is dimension 2 of shape.

abstract property raster: IRaster#: The associated raster.

abstract property x_dimension: IDimension#: The column dimension (dimension 2 of shape).

abstract property y_dimension: IDimension#: The row dimension (dimension 1 of shape).

abstract property band_dimension: IDimension#: The band dimension (dimension 0 of shape).

class IRegularGrid2DComponentDataItem[source]#

Bases: IComponentDataItem

Data associated with the cells of a 2D regular grid.

Mirrors C++ Spatial::IRegularGrid2DComponentDataItem. Canonical dimension ordering: y-cell is dimension 0, x-cell is dimension 1 of shape; optional cell edge and cell vertex dimensions follow.

abstract property grid: IRegularGrid2D#: The associated grid.

abstract property mesh_data_object_type: MeshDataObjectType#: The kind of mesh object the values describe.

abstract property x_cell_dimension: IDimension#: The x-cell dimension (dimension 1 of shape).

abstract property y_cell_dimension: IDimension#: The y-cell dimension (dimension 0 of shape).

abstract property cell_edge_dimension: IDimension#: The per-cell edge dimension, when values attach to cell edges.

abstract property cell_vertex_dimension: IDimension#: The per-cell vertex dimension, when values attach to cell vertices.

class IRegularGrid3DComponentDataItem[source]#

Bases: IComponentDataItem

Data associated with the cells of a 3D regular grid.

Mirrors C++ Spatial::IRegularGrid3DComponentDataItem. Canonical dimension ordering: z-cell is dimension 0, y-cell is dimension 1, x-cell is dimension 2 of shape; optional cell face and cell vertex dimensions follow.

abstract property grid: IRegularGrid3D#: The associated grid.

abstract property mesh_data_object_type: MeshDataObjectType#: The kind of mesh object the values describe.

abstract property x_cell_dimension: IDimension#: The x-cell dimension (dimension 2 of shape).

abstract property y_cell_dimension: IDimension#: The y-cell dimension (dimension 1 of shape).

abstract property z_cell_dimension: IDimension#: The z-cell dimension (dimension 0 of shape).

abstract property cell_face_dimension: IDimension#: The per-cell face dimension, when values attach to cell faces.

abstract property cell_vertex_dimension: IDimension#: The per-cell vertex dimension, when values attach to cell vertices.

hydrocouple.spatiotemporal #

Data items whose values vary in both time and space; typed combinations of the temporal and spatial data items with time outermost.

HydroCouple spatiotemporal abstract base classes.

Python ABC mirrors of the C++ HydroCouple v2.0.0 interfaces defined in hydrocouplespatiotemporal.h: component data items whose values vary in both time and space, formed by combining the temporal and spatial data item interfaces. Data access is the inherited hyperslab API; each class documents its canonical dimension ordering (time is always outermost).

class ITimeGeometryComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem, IGeometryComponentDataItem

Geometry data varying in time.

Mirrors C++ SpatioTemporal::ITimeGeometryComponentDataItem. Canonical dimension ordering: time is dimension 0, geometry is dimension 1; “current time step, all geometries” is a contiguous slab.

class ITimeNetworkComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem, INetworkComponentDataItem

Network data varying in time.

Mirrors C++ SpatioTemporal::ITimeNetworkComponentDataItem. Canonical dimension ordering: time is dimension 0, the entity dimension selected by network_data_type is dimension 1.

class ITimeSeriesPolyhedralSurfaceComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem, IPolyhedralSurfaceComponentDataItem

Polyhedral-surface data varying in time.

Mirrors C++ SpatioTemporal::ITimeSeriesPolyhedralSurfaceComponentDataItem. Canonical dimension ordering: time is dimension 0, the entity dimension selected by mesh_data_type is dimension 1.

class ITimeSeriesTINComponentDataItem[source]#

Bases: ITimeSeriesPolyhedralSurfaceComponentDataItem

A time-varying polyhedral-surface data item whose surface is a TIN.

Mirrors C++ SpatioTemporal::ITimeSeriesTINComponentDataItem.

abstract property tin: ITIN#: The associated TIN (C++ TIN()).

class ITimeSeriesRasterComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem, IRasterComponentDataItem

Raster data varying in time.

Mirrors C++ SpatioTemporal::ITimeSeriesRasterComponentDataItem. Canonical dimension ordering: time 0, band 1, y (row) 2, x (column) 3.

class ITimeRegularGrid2DComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem, IRegularGrid2DComponentDataItem

2D regular-grid data varying in time.

Mirrors C++ SpatioTemporal::ITimeRegularGrid2DComponentDataItem. Canonical dimension ordering: time 0, y-cell 1, x-cell 2; optional cell edge and cell vertex dimensions follow.

class ITimeRegularGrid3DComponentDataItem[source]#

Bases: ITimeSeriesComponentDataItem, IRegularGrid3DComponentDataItem

3D regular-grid data varying in time.

Mirrors C++ SpatioTemporal::ITimeRegularGrid3DComponentDataItem. Canonical dimension ordering: time 0, z-cell 1, y-cell 2, x-cell 3; optional cell face and cell vertex dimensions follow.

hydrocouple.distributed #

Transport-neutral distributed execution: message transports, distributed components, proxies for remote components, and partitioned data items with local virtual (ghost/halo) entity representation.

HydroCouple distributed-execution abstract base classes.

Python ABC mirrors of the C++ HydroCouple v2.0.0 interfaces defined in hydrocoupledistributed.h: transport-neutral message channels, distributed model components, proxies for remote components, and partitioned data items with local virtual (ghost/halo) entity representation. Transport payloads are NumPy arrays — the Python-side BufferDescriptor.

Transport implementations (MPI, in-process, sockets) are SDK territory; this module only defines the contracts.

class IExchangeRequest[source]#

Bases: ABC

Handle to an asynchronous communication operation.

Mirrors C++ Distributed::IExchangeRequest. Returned by the asynchronous ITransport operations and by IPartitionedComponentDataItem.synchronize_async().

abstractmethod test()[source]#

Non-blocking completion test.

Return type:: bool

abstractmethod wait()[source]#

Block until the operation completes.

Return type:: None

abstractmethod failed()[source]#

Whether the operation failed; returns (failed, message).

Return type:: tuple[bool, str]

class Endpoint(address='', rank=-1)[source]#

Bases: object

One participant reachable through a transport.

Mirrors C++ Distributed::ITransport::Endpoint.

Parameters:

address (str)
rank (int)

address: str = ''#

rank: int = -1#

class ITransport[source]#

Bases: IIdentity

A transport-neutral, tagged message channel between processes.

Mirrors C++ Distributed::ITransport. Payloads are NumPy arrays; message ordering is guaranteed only between a fixed (sender, receiver, tag) triple.

abstract property local_endpoint: Endpoint#: The endpoint of the calling process.

abstract property participant_count: int#: The number of participants reachable through this transport.

abstractmethod send(to, tag, payload)[source]#

Send a typed payload, blocking until the buffer is reusable.

Returns:

(ok, message).

Parameters:

to (Endpoint)
tag (int)
payload (np.ndarray)

Return type:

tuple[bool, str]

abstractmethod receive(source, tag, into)[source]#

Receive a typed payload into a pre-allocated array, blocking.

Returns:

(ok, message).

Parameters:

source (Endpoint)
tag (int)
into (np.ndarray)

Return type:

tuple[bool, str]

abstractmethod send_async(to, tag, payload)[source]#

Nonblocking send; the payload must stay valid until completion.

Parameters:

to (Endpoint)
tag (int)
payload (np.ndarray)

Return type:

IExchangeRequest

abstractmethod receive_async(source, tag, into)[source]#

Nonblocking receive; into must stay valid until completion.

Parameters:

source (Endpoint)
tag (int)
into (np.ndarray)

Return type:

IExchangeRequest

class IDistributedModelComponent[source]#

Bases: IModelComponent

An IModelComponent participating in distributed execution through a transport.

Mirrors C++ Distributed::IDistributedModelComponent; advertises DistributedExecution.

abstract property transport: ITransport#: The transport this component communicates through.

abstract property partition_count: int#: Number of partitions the domain is decomposed into (1 if none).

abstract property partition_rank: int#: The zero-based partition this instance computes.

class IProxyModelComponent[source]#

Bases: IDistributedModelComponent

A local stand-in for a remote model component.

Mirrors C++ Distributed::IProxyModelComponent. Every IModelComponent method forwards to the remote peer; an orchestrator cannot — and need not — distinguish a proxy from a local component. If the peer dies or a request times out, the proxy transitions to Failed, queues a Fatal ErrorEntry, and fires its status signal.

abstract property remote_endpoint: Endpoint#: The endpoint of the remote component.

abstract property remote_id: str#: The unique identifier of the remote component.

abstractmethod connect_remote()[source]#

Establish the connection to the remote component.

Returns:: (ok, message).
Return type:: tuple[bool, str]

Note

named connect_remote to avoid clashing with the inherited signal method connect(slot); mirrors C++ connect().

abstractmethod disconnect_remote()[source]#

Close the connection to the remote component.

Return type:: None

abstract property is_connected: bool#: Whether the proxy currently holds a live connection.

abstractmethod ping(timeout_seconds)[source]#

Liveness probe of the remote component.

Parameters:: timeout_seconds (float)
Return type:: bool

abstract property request_timeout: float#: Timeout applied to forwarded requests (non-positive = wait indefinitely).

class IPartitionedComponentDataItem[source]#

Bases: IComponentDataItem

A data item whose entity dimension is decomposed across partitions, with local virtual (ghost/halo) representation of remote entities.

Mirrors C++ Distributed::IPartitionedComponentDataItem. The entity dimension indexes locally resident entities: first the locally owned entities, then the virtual entities mirrored from other partitions. Virtual entities carry no degrees of freedom — they are read-only mirrors overwritten by synchronization, never solved locally. Components exposing partitioned items advertise PartitionedData.

abstract property global_count: int#: Global entity count across all partitions.

abstract property owned_global_indexes: np.ndarray#: Global identities of locally owned entities (int64 array).

abstract property virtual_global_indexes: np.ndarray#: Global identities of local virtual (ghost/halo) entities (int64 array); they follow the owned entities in the local entity dimension.

abstract property virtual_owners: np.ndarray#: Owner partition rank of each virtual entity (int32 array, parallel to virtual_global_indexes).

abstract property synchronization_epoch: int#: Monotonically increasing counter, incremented each time a halo synchronization completes.

abstractmethod synchronize_async()[source]#

Begin an asynchronous halo synchronization of the virtual entities. Computation on owned entities may overlap the returned request; virtual-entity values are defined only after completion.

Return type:: IExchangeRequest

hydrocouple.helpers #

Non-normative conveniences mirroring the C++ hydrocouplehelpers.h.

Non-normative convenience helpers for the HydroCouple Python bindings.

Mirrors hydrocouplehelpers.h — the single sanctioned exception to the standard’s no-implementation rule. Nothing here is required to implement or consume the standard; it may be ignored entirely.

The DATA_KIND_TO_DTYPE / DTYPE_TO_DATA_KIND maps are the Python spelling of the C++ DataKindOf<T> trait: they tie the standard’s DataKind vocabulary to NumPy dtypes, which are the Python-side BufferDescriptor.

DATA_KIND_TO_DTYPE: dict[DataKind, dtype] = {DataKind.Int8: dtype('int8'), DataKind.UInt8: dtype('uint8'), DataKind.Int16: dtype('int16'), DataKind.UInt16: dtype('uint16'), DataKind.Int32: dtype('int32'), DataKind.UInt32: dtype('uint32'), DataKind.Int64: dtype('int64'), DataKind.UInt64: dtype('uint64'), DataKind.Float32: dtype('float32'), DataKind.Float64: dtype('float64'), DataKind.Boolean: dtype('bool')}#

Native-endian NumPy dtype for each numeric DataKind.

String, Opaque, and Unknown have no dtype mapping.

DTYPE_TO_DATA_KIND: dict[dtype, DataKind] = {dtype('bool'): DataKind.Boolean, dtype('int8'): DataKind.Int8, dtype('uint8'): DataKind.UInt8, dtype('int16'): DataKind.Int16, dtype('uint16'): DataKind.UInt16, dtype('int32'): DataKind.Int32, dtype('uint32'): DataKind.UInt32, dtype('int64'): DataKind.Int64, dtype('uint64'): DataKind.UInt64, dtype('float32'): DataKind.Float32, dtype('float64'): DataKind.Float64}#: Inverse of DATA_KIND_TO_DTYPE.

JULIAN_DAY_UNIX_EPOCH = 2440587.5#

00 UTC).

Type:: The Julian day of the Unix epoch (1970-01-01 00
Type:: 00

data_kind_size(kind)[source]#

Size in bytes of one element of the given kind.

Mirrors Helpers::dataKindSize; 0 for String, Opaque, and Unknown.

Parameters:: kind (DataKind)
Return type:: int

data_kind_of(dtype)[source]#

The DataKind corresponding to a NumPy dtype.

Mirrors Helpers::DataKindOf; unmapped dtypes are DataKind.Opaque. Byte-swapped (non-native-endian) dtypes are deliberately unmapped: the wire and memory formats of the standard are native-endian.

Parameters:: dtype (dtype | type)
Return type:: DataKind

dtype_of(kind)[source]#

The NumPy dtype for a numeric DataKind.

Raises:: ValueError – for String, Opaque, and Unknown.
Parameters:: kind (DataKind)
Return type:: dtype

is_valid_component_status_transition(from_status, to_status)[source]#

Whether a component status transition is legal.

Mirrors Helpers::isValidComponentStatusTransition — the normative statement of the component lifecycle state machine. Implementations must not perform transitions for which this returns False.

Parameters:

from_status (ComponentStatus)
to_status (ComponentStatus)

Return type:

bool

get_value(item, index)[source]#

Read the single element at index; returns (ok, value, message).

Mirrors Helpers::getValue.

Parameters:

item (IComponentDataItem)
index (Sequence[int])

set_value(item, value, index)[source]#

Write the single element at index; returns (ok, message).

Mirrors Helpers::setValue.

Parameters:

item (IComponentDataItem)
index (Sequence[int])

Return type:

tuple[bool, str]

get_values(item, start, count, out=None)[source]#

Read a hyperslab into a C-ordered array of shape count.

Mirrors Helpers::getValues; allocates out when not supplied. :returns: (ok, values, message).

Parameters:

item (IComponentDataItem)
start (Sequence[int])
count (Sequence[int])
out (Optional[np.ndarray])

Return type:

tuple[bool, np.ndarray, str]

set_values(item, values, start, count)[source]#

Write a hyperslab from values; returns (ok, message).

Mirrors Helpers::setValues.

Parameters:

item (IComponentDataItem)
values (np.ndarray)
start (Sequence[int])
count (Sequence[int])

Return type:

tuple[bool, str]

get_values_or_raise(item, start, count, out=None)[source]#

Raising wrapper over get_values().

Raises:

RuntimeError – with the item’s failure message on error.

Parameters:

item (IComponentDataItem)
start (Sequence[int])
count (Sequence[int])
out (Optional[np.ndarray])

Return type:

np.ndarray

set_values_or_raise(item, values, start, count)[source]#

Raising wrapper over set_values().

Raises:

RuntimeError – with the item’s failure message on error.

Parameters:

item (IComponentDataItem)
values (np.ndarray)
start (Sequence[int])
count (Sequence[int])

Return type:

None

julian_day_to_datetime(julian_day)[source]#

Convert a Julian day value to a timezone-aware UTC datetime.

Parameters:: julian_day (float)
Return type:: datetime

datetime_to_julian_day(value)[source]#

Convert a datetime (naive values are taken as UTC) to a Julian day.

Parameters:: value (datetime)
Return type:: float

days_to_timedelta(days)[source]#

Convert a duration in days (e.g. ITimeSpan.duration) to a timedelta.

Parameters:: days (float)
Return type:: timedelta

hydrocouple.loader #

Load compiled C++ HydroCouple components from shared libraries.

Example

>>> from hydrocouple.loader import load
>>> component, info, handle = load("./libMyComponent.so")
>>> component.initialize()
>>> component.status
<ComponentStatus.Initialized: 2>

load(library_path, symbol_name='CreateComponentInfo')[source]#

Load a compiled C++ HydroCouple component from a shared library.

Parameters:

library_path (str | os.PathLike) – Path to the shared library (.so, .dylib, or .dll).
symbol_name (str) – Name of the exported extern "C" factory function that returns an IModelComponentInfo*. Defaults to "CreateComponentInfo".

Returns:

component (IModelComponent) – The newly created model component instance.
info (IModelComponentInfo) – Metadata about the component (developer, version, etc.).
handle (object) – An opaque handle to the loaded shared library. You must keep this alive for as long as the component is in use.

Raises:

OSError – If the library cannot be loaded or the symbol is not found.
RuntimeError – If the factory or createComponentInstance() returns null.

Return type:

tuple[‘IModelComponent’, ‘IModelComponentInfo’, object]

API Reference#

hydrocouple.core#

hydrocouple.temporal#

hydrocouple.spatial#

hydrocouple.spatiotemporal#

hydrocouple.distributed#

hydrocouple.helpers#

hydrocouple.loader#

hydrocouple.core #

hydrocouple.temporal #

hydrocouple.spatial #

hydrocouple.spatiotemporal #

hydrocouple.distributed #

hydrocouple.helpers #

hydrocouple.loader #