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++ HydroCouple::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#
Differentiable = 7#
LayeredData = 8#
VendorBase = 2147483648#
class DeviceBackend(*values)[source]#

Bases: IntEnum

Runtime owning a device-resident buffer; mirrors C++ HydroCouple::DeviceBackend. Named NoBackend where C++ says None because None is not a legal Python identifier.

NoBackend = 0#
CUDA = 1#
HIP = 2#
SYCL = 3#
LevelZero = 4#
OpenCL = 5#
Other = 6#
class ValueKind(*values)[source]#

Bases: IntEnum

How a value behaves under regridding and aggregation; mirrors C++ HydroCouple::ValueKind.

Unknown = 0#
Intensive = 1#
Extensive = 2#
Flux = 3#
Density = 4#
class DifferentialRole(*values)[source]#

Bases: IntEnum

Which side of a component’s step a derivative buffer belongs to.

Mirrors C++ HydroCouple::DifferentialRole. A step maps (StateBefore, Input, Argument) to (StateAfter, Output).

Input = 0#
Argument = 1#
Output = 2#
StateBefore = 3#
StateAfter = 4#
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 DimensionRole(*values)[source]#

Bases: IntEnum

What an axis of a data item’s index space means; mirrors C++ IDimension::Role.

Unknown = 0#
Time = 1#
Entity = 2#
Layer = 3#
Band = 4#
Row = 5#
Column = 6#
Depth = 7#
Component = 8#
Realization = 9#
Other = 10#
class ArgumentRole(*values)[source]#

Bases: IntEnum

What an argument is to the model that owns it; mirrors C++ IArgument::Role.

Configuration = 0#
Parameter = 1#
InitialCondition = 2#
Forcing = 3#
Geometry = 4#
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#
PlaneAngle = 9#
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 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#
Invalid = 14#

The composition has problems; fix it and validate again (appended in ABI 5, so earlier values keep their meaning).

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

abstract property states: list[IComponentDataItem]#

The data items that make up the state carried from one update to the next (prognostic variables). Empty for a component whose update does not depend on its past.

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]

abstractmethod release_state(token)[source]#

Release a state saved by save_state() that will not be restored, so whatever it set aside (a file, a buffer) can be reclaimed. A component whose token is the state itself returns (True, ""). After this the token is dead.

Returns:

(ok, message).

Parameters:

token (str)

Return type:

tuple[bool, str]

class IDifferentiableModelComponent[source]#

Bases: IModelComponent

A model component that can report the derivative of its most recent step.

Mirrors C++ IDifferentiableModelComponent; the owning component advertises Capability.Differentiable. The step maps the state before it, the inputs and the arguments to the state after it and the outputs; state is listed by differentiable_states() so that a state cotangent can be carried to the previous step. The linearization point is the most recent update(); vjp() and jvp() do not change the component’s state.

Entries are (item, role, buffer) triples: item one of the listed data items, role a DifferentialRole, buffer an array spanning the item’s whole shape (an ndarray, or any DLPack tensor). Results are overwritten, never accumulated; an absent seed is zero.

A Python component written in PyTorch or JAX need not hand-write these: see hydrocouple.torch and hydrocouple.jax, which also drive C++ components that implement them.

abstractmethod differentiable_inputs()[source]#

Inputs a derivative reaches; the rest are constants.

Return type:

list[IInput]

abstractmethod differentiable_arguments()[source]#

Arguments (parameters) a derivative reaches.

Return type:

list[IArgument]

abstractmethod differentiable_outputs()[source]#

Outputs whose derivative the component can report.

Return type:

list[IOutput]

abstractmethod differentiable_states()[source]#

Items that carry state from one step to the next.

Return type:

list[IComponentDataItem]

abstractmethod vjp(seeds, results)[source]#

Vector-Jacobian product of the most recent step.

Parameters:
  • seeds (Sequence[tuple]) – cotangents of Output / StateAfter entries.

  • results (Sequence[tuple]) – buffers to overwrite with cotangents of Input / Argument / StateBefore entries.

Returns:

(ok, message).

Return type:

tuple[bool, str]

abstractmethod jvp(seeds, results)[source]#

Jacobian-vector product of the most recent step.

Parameters:
  • seeds (Sequence[tuple]) – tangents of Input / Argument / StateBefore entries.

  • results (Sequence[tuple]) – buffers to overwrite with tangents of Output / StateAfter entries.

Returns:

(ok, message).

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 value_kind: ValueKind#

How values of this definition behave under regridding and aggregation. ValueKind.Unknown is legal and means an adapter that needs the distinction must refuse rather than assume.

abstract property standard_name: str#

The CF standard name of the measured quantity, or "" when not declared. Never a name outside the CF Standard Name Table.

abstract property concept_uri: str#

An absolute URI naming the quantity in a published vocabulary (CSDMS Standard Names, QUDT, SWEET, HY_Features, …), or "".

Two definitions name the same quantity when their concept URIs are equal or, when either is undeclared, their standard names are; a difference between two declared names is a warning, not an error.

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.

abstract property role: DimensionRole#

What this axis means (time, entity, layer, …).

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

abstract property symbol: str#

The unit as a UDUNITS-2 string ("m3 s-1"), or "".

abstract property ucum_code: str#

The unit as a case-sensitive UCUM code ("m3/s"), or "".

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

When C++ drives a Python item, destination is an ndarray view over the caller’s memory if that memory is host accessible (MemorySpace.Host, HostPinned, Unified). For MemorySpace.Device it is a hydrocouple.dlpack.BufferView: an object with shape, data_kind and the DLPack protocol, so that torch.from_dlpack(destination) (or CuPy’s, or JAX’s) yields a tensor aliasing the caller’s device memory. Either view is valid only for the duration of the call.

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 role: ArgumentRole#

What this argument is to the model (configuration, parameter, initial condition, forcing, geometry).

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:
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 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, provider_role=None)[source]#

Connect a consumer to this output.

The single wiring entry point for every kind of input. For an IMultiInput the output checks consumer.can_consume(self, provider_role) and calls consumer.add_provider(self, provider_role); for any other input provider_role must be None and the output checks can_consume and calls set_provider(self). Raises on refusal.

Parameters:
Return type:

None

abstractmethod remove_consumer(consumer)[source]#

Disconnect a consumer (remove_provider on a multi-input, set_provider(None) on any other).

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

abstract property states: list[IComponentDataItem]#

Items carrying state from one refresh to the next.

Empty for an adapter whose values depend only on its adaptee’s current values and its arguments (the common case). An adapter whose values also depend on its previous refreshes (relaxation, a recorded history) lists that state – possibly itself – so an orchestrator knows it must be restored with the components; see ICheckpointableAdaptedOutput.

class IDifferentiableAdaptedOutput[source]#

Bases: IAdaptedOutput

An adapted output that can report the derivative of its most recent refresh.

Mirrors C++ IDifferentiableAdaptedOutput. In (item, role, buffer) entries the adapter itself is DifferentialRole.Output, its adaptee is DifferentialRole.Input, its differentiable_arguments() are DifferentialRole.Argument and its differentiable_states() are DifferentialRole.StateBefore / DifferentialRole.StateAfter. Buffer rules are those of IDifferentiableModelComponent. A stateful one should also be an ICheckpointableAdaptedOutput, so an orchestrator can replay the refreshes before the latest.

abstractmethod differentiable_arguments()[source]#

Arguments of this adapter a derivative reaches.

Return type:

list[IArgument]

abstractmethod differentiable_states()[source]#

State items the derivative follows; a subset of states (empty for a stateless adapter).

Return type:

list[IComponentDataItem]

abstractmethod vjp(seeds, results)[source]#

Vector-Jacobian product of the most recent refresh.

Parameters:
Return type:

tuple[bool, str]

abstractmethod jvp(seeds, results)[source]#

Jacobian-vector product of the most recent refresh.

Parameters:
Return type:

tuple[bool, str]

class ICheckpointableAdaptedOutput[source]#

Bases: IAdaptedOutput

An adapted output that can save and restore the state it carries between refreshes.

Mirrors C++ ICheckpointableAdaptedOutput, with the semantics of ICheckpointableModelComponent: a restored adapter behaves as if it had refreshed its way to the saved state (its child adapters are restored in their own right), and a released token is dead. Adapters have no status, so all three are legal any time after IAdaptedOutput.initialize().

abstractmethod save_state()[source]#

Save the adapter’s complete state.

Returns:

(ok, token, message).

Return type:

tuple[bool, str, str]

abstractmethod restore_state(token)[source]#

Restore a state saved by save_state().

Returns:

(ok, message).

Parameters:

token (str)

Return type:

tuple[bool, str]

abstractmethod release_state(token)[source]#

Release a saved state that will not be restored; the token is dead afterwards.

Returns:

(ok, message).

Parameters:

token (str)

Return type:

tuple[bool, str]

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:
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:
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 (None for a multi-input, whose providers are read through providers).

abstractmethod set_provider(provider)[source]#

Record the provider of this input.

A callback of IOutput.add_consumer() and IOutput.remove_consumer(); orchestrators wire through the output and never call this directly.

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]#

Record a provider in a role.

A callback of IOutput.add_consumer(), which passes the role; orchestrators wire through the output and never call this directly.

Parameters:
Return type:

bool

abstractmethod remove_provider(provider)[source]#

Remove a provider (a callback of IOutput.remove_consumer()).

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 validate()[source]#

Validate the composition: required roles filled, every component valid, every link’s two ends compatible.

An empty list means valid; otherwise one message per problem, and the workflow is Failed.

Return type:

list[str]

abstractmethod prepare()[source]#

Prepare every managed component and build the execution plan.

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

abstractmethod request_stop()[source]#

Cooperative stop: takes effect after the step in flight.

Return type:

None

abstractmethod request_pause()[source]#

Cooperative pause: takes effect after the step in flight.

Return type:

None

abstractmethod resume()[source]#

Resume a Paused workflow; a no-op otherwise.

Return type:

None

abstractmethod errors(clear_after_read=False)[source]#

The workflow’s diagnostic queue (the normative failure channel).

Parameters:

clear_after_read (bool)

Return type:

list[ErrorEntry]

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

TIME_EQUALITY_TOLERANCE_DAYS = 1e-08#

Two instants are the same instant when their Julian days differ by no more than this (1e-8 days, about 0.86 ms). Mirrors C++ Temporal::TIME_EQUALITY_TOLERANCE_DAYS; every “exact” time comparison (TimeInterpolation.NoInterpolation, matching a consumer’s times against a provider’s) uses it.

INTERVAL_LENGTH_CONTIGUOUS = -1.0#

The interval_length of an item whose intervals are contiguous but not of one length: interval i runs from time i-1 to time i, interval 0 from the start of time_span. Mirrors C++ Temporal::INTERVAL_LENGTH_CONTIGUOUS; any negative value means this.

class TimeKind(*values)[source]#

Bases: IntEnum

What a value’s time coordinate refers to; mirrors C++ Temporal::TimeKind.

Unknown = 0#
Instantaneous = 1#
IntervalMean = 2#
IntervalMinimum = 3#
IntervalMaximum = 4#
Accumulated = 5#
class TimeInterpolation(*values)[source]#

Bases: IntEnum

How a provider produces a value between held instants; mirrors C++ Temporal::TimeInterpolation.

Unknown = 0#
NoInterpolation = 1#
Previous = 2#
Nearest = 3#
Linear = 4#
class TimeExtrapolation(*values)[source]#

Bases: IntEnum

How a provider produces a value outside its held range; mirrors C++ Temporal::TimeExtrapolation.

Unknown = 0#
Refuse = 1#
HoldLast = 2#
Linear = 3#
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.

abstract property end_julian_day: float#

julian_day + duration.

Type:

End of the interval

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.

abstract property next_date_time_julian_day: float#

The Julian day the next update() will advance current_date_time to; never earlier than the current time.

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

abstract property time_kind: TimeKind#

What each value’s time coordinate refers to.

abstract property interval_length: float#

Averaging/accumulation interval in days.

Positive: every interval has this length and ends at its time coordinate. INTERVAL_LENGTH_CONTIGUOUS (any negative value): contiguous intervals of varying length. Zero: not declared (and what instantaneous items return).

abstract property time_interpolation: TimeInterpolation#

What this item does (output) or accepts (input) between held instants.

abstract property time_extrapolation: TimeExtrapolation#

What this item does (output) or accepts (input) outside its held range.

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 MeshLocation(*values)[source]#

Bases: IntEnum

Which mesh or network entity a data item’s values are attached to.

Mirrors C++ Spatial::MeshLocation; named after UGRID’s location.

Node = 0#
Edge = 1#
Face = 2#
Volume = 3#
class VectorBasis(*values)[source]#

Bases: IntEnum

The frame a vector or tensor value is expressed in.

Mirrors C++ Spatial::VectorBasis.

Unknown = 0#
Cartesian = 1#
EastNorthUp = 2#
NormalTangential = 3#
AlongEntity = 4#
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 VerticalCoordinateKind(*values)[source]#

Bases: IntEnum

The family a vertical coordinate belongs to.

Mirrors C++ Spatial::VerticalCoordinateKind. Named so two models can tell whether they agree about what a layer is before exchanging values on one: a sigma model and a z-level model both index values by layer, and those indices mean different things.

Unknown = 0#
Sigma = 1#
ZLevel = 2#
ZStar = 3#
Hybrid = 4#
Isopycnal = 5#
DepthBelowSurface = 6#
class CrossSectionKind(*values)[source]#

Bases: IntEnum

How a cross-section’s shape is held by whoever produced it.

Mirrors C++ Spatial::CrossSectionKind.

Unknown = 0#
StationElevation = 1#
WidthElevation = 2#
Analytic = 3#
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 horizontal axes.

abstract property vertical_auth_name: str#

Authority of the vertical reference system, or "" if undeclared.

abstract property vertical_auth_srid: int#

Authority id of the vertical reference system, or 0 if undeclared.

abstract property vertical_sr_text: str#

WKT of the vertical reference system, or "" if undeclared.

abstract property vertical_distance_units: DistanceUnits#

The measurement distance units of the vertical axis.

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, intersection_pattern_matrix)[source]#

DE-9IM relation test against a 9-character pattern.

Parameters:
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:
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].

abstract property face_edge_offsets: np.ndarray#

CSR row offsets into face_edges (int64, face_count + 1).

abstract property face_edges: np.ndarray#

Concatenated edge indexes of all faces (int64).

abstract property edge_faces: np.ndarray#

Left/right face of every edge (int64, 2 * edge_count); -1 marks the outside.

abstract property face_x: np.ndarray#

x of every face’s representative point, or empty if not held.

abstract property face_y: np.ndarray#

y of every face’s representative point, or empty if not held.

abstract property face_areas: np.ndarray#

Plan area of every face, or empty if not held.

abstract property edge_lengths: np.ndarray#

Length of every edge, or empty if not held.

abstract property edge_normal_x: np.ndarray#

x of every edge’s unit normal (left face to right face), or empty if not held.

abstract property edge_normal_y: np.ndarray#

y of every edge’s unit normal, or empty if not held.

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, destination)[source]#

Read a window into destination (a [y_size, x_size] array of the band’s dtype); the same data plane as get_values_into.

Parameters:
  • x_offset (int)

  • y_offset (int)

  • x_size (int)

  • y_size (int)

  • destination (np.ndarray)

Return type:

tuple[bool, str]

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

Write a [y_size, x_size] window from source.

Parameters:
  • x_offset (int)

  • y_offset (int)

  • x_size (int)

  • y_size (int)

  • source (np.ndarray)

Return type:

tuple[bool, str]

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 location: MeshLocation#

Which network entity (Node or Edge) the values are attached to.

abstract property network_data_type: SpatialDataType#

Scalar, MultiScalar, Vector or Tensor.

abstract property vector_basis: VectorBasis#

The frame of vector/tensor values.

abstract property entity_dimension: IDimension#

The entity dimension (dimension 0 of shape).

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 location is dimension 0 of shape.

abstract property location: MeshLocation#

Which mesh entity (Node, Edge, Face, Volume) the values are attached to.

abstract property mesh_data_type: SpatialDataType#

Scalar, MultiScalar, Vector or Tensor.

abstract property vector_basis: VectorBasis#

The frame of vector/tensor values.

abstract property polyhedral_surface: IPolyhedralSurface#

The associated polyhedral surface.

abstract property entity_dimension: IDimension#

The entity dimension (dimension 0 of shape).

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 location: MeshLocation#

Which grid entity the values are attached to.

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 location: MeshLocation#

Which grid entity the values are attached to.

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.

class IVerticalCoordinate[source]#

Bases: ABC

Where the layers of a layered or volumetric data item actually are.

Mirrors C++ Spatial::IVerticalCoordinate. Values indexed by {cell, layer} cannot be interpreted without this: under a terrain-following coordinate the elevation of layer k moves every step with the free surface.

Conventions, as in the standard: elevations are positive up, in the vertical datum and units the parent geometry’s ISpatialReferenceSystem declares. Interface 0 is the top of the column, so a column of layer_count layers has layer_count + 1 interfaces.

abstract property kind: VerticalCoordinateKind#

The coordinate family.

abstract property layer_count: int#

Number of layers in a column.

abstract property column_count: int#

Number of columns (plan entities); the parent item’s entity count.

abstract property is_time_varying: bool#

Whether interface elevations change from step to step.

True for every coordinate that follows the free surface; a consumer caching elevations must then re-read them each exchange.

abstract property geometry_epoch: int#

Counter incremented every time the elevations change.

A consumer records it with the profile it cached and compares, rather than re-reading every column to learn nothing moved. Constant when is_time_varying is false.

abstractmethod interface_elevation(cell_index, interface_index)[source]#

Elevation of one interface in one cell (spot queries).

interface_index runs from 0 at the top to layer_count at the bed. Bulk consumers use interface_elevations.

Parameters:
  • cell_index (int)

  • interface_index (int)

Return type:

float

abstract property interface_elevations: np.ndarray#

All interface elevations of all columns.

A float64 array of shape (column_count, layer_count + 1), top interface first within a column – the C++ row-major [column][interface] span, shaped. Valid until geometry_epoch changes; the accessor a remap uses.

class ILayering[source]#

Bases: ABC

Values resolved into vertical layers, whatever the plan geometry.

Mirrors C++ Spatial::ILayering. Mixed into the layered mesh and layered network items, so a consumer that needs only “values by layer, with elevations I can trust” can test for this and stay indifferent to whether the producer is a mesh or a network.

abstract property layer_dimension: IDimension#

The layer dimension (role DimensionRole.Layer).

Immediately after the entity dimension in shape – dimension 1 on a plain layered item, 2 on a time-varying one – and before any Component dimension. Layer 0 is at the top.

abstract property vertical_coordinate: IVerticalCoordinate#

Where those layers are. Never None.

class ILayeredMeshComponentDataItem[source]#

Bases: IPolyhedralSurfaceComponentDataItem, ILayering

A polyhedral surface whose values are resolved into vertical layers.

Mirrors C++ Spatial::ILayeredMeshComponentDataItem. Values are indexed {face, layer} (then a Component dimension if any); location is MeshLocation.Volume for cell values and Face for values on each face’s layer interfaces.

class ICrossSection[source]#

Bases: ABC

The shape of a channel at one place, as a function of stage.

Mirrors C++ Spatial::ICrossSection. The contract is the derived quantities, which station-elevation (HEC-RAS, SWMM), width-elevation (CE-QUAL-W2) and analytic producers can all answer exactly; station_count is 0 for producers that hold no survey points.

Conventions, as in the standard: stage is a water-surface elevation, positive up, in the parent geometry’s vertical datum; every length is in its vertical distance units and areas in their square. Below invert_elevation every quantity is zero. At the invert the areas are zero but top_width() and wetted_perimeter() take their limiting values from above (the bottom width of a flat-bottomed section), so nothing divides by zero at a wet front. Flow area and storage area differ wherever part of the section stores water without conveying it.

abstract property kind: CrossSectionKind#

How the producer holds this shape.

abstract property invert_elevation: float#

Lowest elevation in the section.

abstractmethod top_width(stage)[source]#

Width of the water surface at stage.

Parameters:

stage (float)

Return type:

float

abstractmethod storage_area(stage)[source]#

Total wetted area at stage – everything holding water.

Parameters:

stage (float)

Return type:

float

abstractmethod flow_area(stage)[source]#

The conveying part of that area; never above storage_area().

Parameters:

stage (float)

Return type:

float

abstractmethod wetted_perimeter(stage)[source]#

Wetted perimeter of the conveying area at stage.

Paired with flow_area(), so their ratio is the hydraulic radius a friction law expects.

Parameters:

stage (float)

Return type:

float

abstractmethod evaluate(stages, top_widths=None, storage_areas=None, flow_areas=None, wetted_perimeters=None)[source]#

Evaluate the section at many stages in one call.

Mirrors the C++ out-parameter form so a caller can tabulate into arrays it already holds: each output is None (not wanted) or a writable float64 array of len(stages) that is filled in place.

Parameters:
  • stages (np.ndarray)

  • top_widths (Optional['np.ndarray'])

  • storage_areas (Optional['np.ndarray'])

  • flow_areas (Optional['np.ndarray'])

  • wetted_perimeters (Optional['np.ndarray'])

Return type:

None

abstract property station_count: int#

Number of survey points, or 0 when the producer holds none.

abstractmethod stations()[source]#

The survey points, left bank to right bank.

Returns (stations, elevations), two float64 arrays of station_count elements (empty when there are none). A consumer that needs a shape regardless uses the area and width accessors, which every producer answers.

Return type:

tuple[np.ndarray, np.ndarray]

class ILayeredNetworkComponentDataItem[source]#

Bases: INetworkComponentDataItem, ILayering

A network carrying a vertical profile, and optionally a channel shape, at each node or edge.

Mirrors C++ Spatial::ILayeredNetworkComponentDataItem – the shape shared by CE-QUAL-W2, HEC-RAS and SWMM. Values are indexed {entity, layer} (then a Component dimension if any), the entity being whichever of node or edge location reports.

abstractmethod cross_section(entity_index)[source]#

The channel shape at one entity, or None where there is none.

None says plainly that a stratified network carries no surveyed section there; a zero-width section would not.

Parameters:

entity_index (int)

Return type:

ICrossSection | None


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.

class ITimeLayeredMeshComponentDataItem[source]#

Bases: ITimeSeriesPolyhedralSurfaceComponentDataItem, ILayeredMeshComponentDataItem

A layered mesh item whose values also vary in time.

Mirrors C++ SpatioTemporal::ITimeLayeredMeshComponentDataItem. Canonical dimension ordering: time 0, entity (face or volume) 1, layer 2; a Component dimension follows when mesh_data_type is not Scalar. The vertical coordinate’s geometry_epoch tells a consumer whether the elevations it cached still describe the current time step.

class ITimeLayeredNetworkComponentDataItem[source]#

Bases: ITimeNetworkComponentDataItem, ILayeredNetworkComponentDataItem

A layered network item whose values also vary in time.

Mirrors C++ SpatioTemporal::ITimeLayeredNetworkComponentDataItem. Canonical dimension ordering: time 0, entity (node or edge) 1, layer 2; a Component dimension follows when network_data_type is not Scalar.


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 wait_for(timeout_seconds)[source]#

Block until the operation completes or the timeout elapses.

Returns:

True if the operation has completed (successfully or not), False if it is still pending. A non-positive timeout tests once without blocking, as test() does.

Parameters:

timeout_seconds (float)

Return type:

bool

abstractmethod cancel()[source]#

Ask to abandon the operation; True if it is now complete, False if this transport cannot cancel and the caller must still wait().

Return type:

bool

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

A payload whose size the receiver cannot know (text, a growing list) is sent as its extent first – a one-element int64 array – and then the payload itself as a 1-D array on the same tag; text travels as UTF-8 bytes in a uint8 array. A transport that can detect a lost peer completes every pending operation with it as failed; callers bound their waits with the asynchronous operations and IExchangeRequest.wait_for().

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:
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:
Return type:

tuple[bool, str]

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

Nonblocking send; the payload must stay valid until completion.

Parameters:
Return type:

IExchangeRequest

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

Nonblocking receive; into must stay valid until completion.

Parameters:
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.

The command protocol between a proxy and its peer belongs to the SDK that provides both ends; proxies from different SDKs need not interoperate.

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]

Mirrors C++ connectToPeer() (renamed there for the same reason this is not called connect: the inherited signal method).

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 axis partitioned_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 partitioned_dimension: int#

Index into shape of the decomposed (entity) axis.

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.

Failed is reachable from every status except Finished: a failure can be detected while a component rests (a proxy whose peer dies while it is Updated).

Parameters:
Return type:

bool

is_valid_workflow_status_transition(from_status, to_status)[source]#

Whether a workflow status transition is legal.

Mirrors Helpers::isValidWorkflowStatusTransition.

Parameters:
Return type:

bool

get_value(item, index)[source]#

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

Mirrors Helpers::getValue.

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

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

Mirrors Helpers::setValue.

Parameters:
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:
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:
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:
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:
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.

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]