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:
IntEnumByte-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:
IntEnumElement type of a typed data buffer.
Mirrors C++
HydroCouple::DataKind. This is the type vocabulary of the data-exchange plane;hydrocouple.helpersmaps 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:
IntEnumWhere 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:
IntEnumOptional behavior a component may support.
Mirrors C++
HydroCouple::Capability. Orchestrators branch onIModelComponent.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:
IntEnumRuntime owning a device-resident buffer; mirrors C++
HydroCouple::DeviceBackend. NamedNoBackendwhere C++ saysNonebecauseNoneis not a legal Python identifier.- NoBackend = 0#
- CUDA = 1#
- HIP = 2#
- SYCL = 3#
- LevelZero = 4#
- OpenCL = 5#
- Other = 6#
- class ValueKind(*values)[source]#
Bases:
IntEnumHow 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:
IntEnumWhich 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:
IntEnumLifecycle status of a model component.
Mirrors C++
HydroCouple::IModelComponent::ComponentStatus. Legal transitions are encoded byhydrocouple.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:
IntEnumDimension length type mirroring C++
IDimension::LengthType.- Static = 0#
- Dynamic = 1#
- class DimensionRole(*values)[source]#
Bases:
IntEnumWhat 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:
IntEnumWhat 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:
IntEnumFundamental 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:
IntEnumDistance 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:
IntEnumInput 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:
IntEnumWorkflow 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:
objectOne 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.
- class ISignal[source]#
Bases:
ABCSignal 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
- class IPropertyChanged[source]#
Bases:
ISignalEmits a signal when a property of an object changes.
Mirrors C++
IPropertyChanged(ISignal<std::string>); slots are called asslot(property_name: str).
- class IDescription[source]#
Bases:
IPropertyChangedDescriptive information on a HydroCouple object.
Mirrors C++
IDescription.
- class IIdentity[source]#
Bases:
IDescriptionAdds a unique identifier to a describable entity.
Mirrors C++
IIdentity. The id must be unique within its context and must not be empty.
- class IComponentInfo[source]#
Bases:
IIdentityFactory metadata about a component.
Mirrors C++
IComponentInfo. Must be implemented as anIModelComponentInfo,IAdaptedOutputFactoryComponentInfo, orIWorkflowComponentInfo. Licensing lives on the optionalILicensedComponentside interface.- abstract property library_file_path: str#
Path to the library from which this component was created.
- class ILicensedComponent[source]#
Bases:
ABCOptional side interface for components requiring license validation.
Mirrors C++
ILicensedComponent. Components implementing it advertiseCapability.Licensing.
- class IUIProvider[source]#
Bases:
ABCOptional side interface for entities with a graphical editor/viewer.
Mirrors C++
IUIProvider. UI concerns were removed fromIModelComponentandIComponentDataItemso the core standard stays headless; the owning component advertisesCapability.UserInterface.
- class IModelComponentInfo[source]#
Bases:
IComponentInfoMetadata about an
IModelComponent; creates instances of it.Mirrors C++
IModelComponentInfo.- abstractmethod create_component_instance()[source]#
Create a new
IModelComponentinstance.- Return type:
- abstract property adapted_output_factories: list[IAdaptedOutputFactory]#
Factories for creating adapted outputs for this component.
- class IModelComponent[source]#
Bases:
IIdentityThe core interface defining a model component.
Mirrors C++
IModelComponent. Also anISignal<shared_ptr<IComponentStatusChangeEventArgs>>: status-changed slots are called asslot(event_args: IComponentStatusChangeEventArgs).Lifecycle:
initialize() -> validate() -> prepare() -> update()... -> finish(); legal status transitions are encoded byhydrocouple.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 update(required_outputs=None)[source]#
Let the component update itself, reaching its next state.
- 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:
- class IComponentStatusChangeEventArgs[source]#
Bases:
ABCPayload 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 has_progress_monitor: bool#
Whether
percent_progressis meaningful.
- class ICloneableModelComponent[source]#
Bases:
IModelComponentA model component supporting deep cloning.
Mirrors C++
ICloneableModelComponent; the owning component advertisesCapability.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:
- Return type:
- abstract property clones: list[ICloneableModelComponent]#
Components cloned from this instance.
- class ICheckpointableModelComponent[source]#
Bases:
IModelComponentA model component that can save and restore its complete state.
Mirrors C++
ICheckpointableModelComponent; the owning component advertisesCapability.Checkpointing. During save/restore the status isComponentStatus.Checkpointing.- abstractmethod restore_state(token)[source]#
Restore state previously saved by
save_state().
- 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.
- class IDifferentiableModelComponent[source]#
Bases:
IModelComponentA model component that can report the derivative of its most recent step.
Mirrors C++
IDifferentiableModelComponent; the owning component advertisesCapability.Differentiable. The step maps the state before it, the inputs and the arguments to the state after it and the outputs; state is listed bydifferentiable_states()so that a state cotangent can be carried to the previous step. The linearization point is the most recentupdate();vjp()andjvp()do not change the component’s state.Entries are
(item, role, buffer)triples:itemone of the listed data items,roleaDifferentialRole,bufferan 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.torchandhydrocouple.jax, which also drive C++ components that implement them.- abstractmethod differentiable_inputs()[source]#
Inputs a derivative reaches; the rest are constants.
- abstractmethod differentiable_states()[source]#
Items that carry state from one step to the next.
- Return type:
- class IValueDefinition[source]#
Bases:
IDescriptionDescribes the type and properties of values of a data item.
Mirrors C++
IValueDefinition. ImplementIQualityorIQuantity, not this directly.- abstract property value_kind: ValueKind#
How values of this definition behave under regridding and aggregation.
ValueKind.Unknownis 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.
- class IDimension[source]#
Bases:
IIdentityProperties 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:
IValueDefinitionQualitative (categorical) value definition.
Mirrors C++
IQuality. Data values are indexes intocategories.
- class IUnitDimensions[source]#
Bases:
IDescriptionPowers 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:
- class IUnit[source]#
Bases:
IDescriptionThe physical unit of an
IQuantity.Mirrors C++
IUnit.- abstract property dimensions: IUnitDimensions#
Fundamental dimensions of the unit.
- class IQuantity[source]#
Bases:
IValueDefinitionQuantitative value definition with a unit.
Mirrors C++
IQuantity.
- class IComponentDataItemValueChanged[source]#
Bases:
ABCPayload of a data-item value-changed signal.
Mirrors C++
IComponentDataItemValueChanged.- abstract property component_data_item: IComponentDataItem#
The data item that fired the event.
- class IComponentDataItem[source]#
Bases:
IIdentityA fundamental unit of typed, multi-dimensional data for a component.
Mirrors C++
IComponentDataItem. Also anISignal<shared_ptr<IComponentDataItemValueChanged>>; value-changed slots are called asslot(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 todata_kind(seehydrocouple.helpers.DATA_KIND_TO_DTYPE). Dimension semantics (which axis is time, entity, layer, …) are described bydimensionsand 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 value_definition: IValueDefinition#
- 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 dimensionkofshape.destination.dtypemust correspond todata_kind(no implicit conversion) anddestination.sizemust equal the product ofcount.destinationmay be non-contiguous (strided views are honored).When C++ drives a Python item,
destinationis an ndarray view over the caller’s memory if that memory is host accessible (MemorySpace.Host,HostPinned,Unified). ForMemorySpace.Deviceit is ahydrocouple.dlpack.BufferView: an object withshape,data_kindand the DLPack protocol, so thattorch.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.
- abstractmethod set_values_from(source, start, count)[source]#
Copy values from
sourceinto a hyperslab of this item.Selection and compatibility rules are identical to
get_values_into().
- class IIdBasedComponentDataItem[source]#
Bases:
IComponentDataItemAn
IComponentDataItemindexed by string identifiers.Mirrors C++
IIdBasedComponentDataItem. Canonical dimension ordering: the identifier dimension is dimension 0 ofshape; data access uses the inherited hyperslab API with the identifier index asstart[0].- abstract property identifier_dimension: IDimension#
The identifier dimension (dimension 0 of
shape).
- class IArgument[source]#
Bases:
IComponentDataItemConfiguration 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).
- 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:
- abstract property current_argument_input_type: ArgumentInputType#
How this argument was initialized.
- abstractmethod initialize(value, arg_type=None)[source]#
Read the argument value from a string representation or an equivalent
IComponentDataItem.- Returns:
(ok, message).- Parameters:
value (str | IComponentDataItem)
arg_type (ArgumentInputType | None)
- Return type:
- 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:
- class IExchangeItem[source]#
Bases:
IComponentDataItemBase data item exchangeable between components at runtime.
- class IOutput[source]#
Bases:
IExchangeItemAn output exchange item that delivers values from a component.
Mirrors C++
IOutput.- 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
IMultiInputthe output checksconsumer.can_consume(self, provider_role)and callsconsumer.add_provider(self, provider_role); for any other inputprovider_rolemust beNoneand the output checkscan_consumeand callsset_provider(self). Raises on refusal.
- abstractmethod remove_consumer(consumer)[source]#
Disconnect a consumer (
remove_provideron a multi-input,set_provider(None)on any other).
- 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:
- class IAdaptedOutput[source]#
Bases:
IOutputAdds 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.
- abstractmethod initialize()[source]#
Initialize based on the current argument values.
- Return type:
None
- 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:
IAdaptedOutputAn adapted output that can report the derivative of its most recent refresh.
Mirrors C++
IDifferentiableAdaptedOutput. In(item, role, buffer)entries the adapter itself isDifferentialRole.Output, itsadapteeisDifferentialRole.Input, itsdifferentiable_arguments()areDifferentialRole.Argumentand itsdifferentiable_states()areDifferentialRole.StateBefore/DifferentialRole.StateAfter. Buffer rules are those ofIDifferentiableModelComponent. A stateful one should also be anICheckpointableAdaptedOutput, so an orchestrator can replay the refreshes before the latest.- abstractmethod differentiable_states()[source]#
State items the derivative follows; a subset of
states(empty for a stateless adapter).- Return type:
- class ICheckpointableAdaptedOutput[source]#
Bases:
IAdaptedOutputAn adapted output that can save and restore the state it carries between refreshes.
Mirrors C++
ICheckpointableAdaptedOutput, with the semantics ofICheckpointableModelComponent: 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 afterIAdaptedOutput.initialize().- abstractmethod restore_state(token)[source]#
Restore a state saved by
save_state().
- class IAdaptedOutputFactory[source]#
Bases:
IIdentityCreates
IAdaptedOutputinstances.Mirrors C++
IAdaptedOutputFactory.
- class IAdaptedOutputFactoryComponentInfo[source]#
Bases:
IComponentInfoMetadata about an
IAdaptedOutputFactoryComponent.Mirrors C++
IAdaptedOutputFactoryComponentInfo.
- class IAdaptedOutputFactoryComponent[source]#
Bases:
IAdaptedOutputFactoryAn 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:
IExchangeItemAn 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 (
Nonefor a multi-input, whose providers are read throughproviders).
- abstractmethod set_provider(provider)[source]#
Record the provider of this input.
A callback of
IOutput.add_consumer()andIOutput.remove_consumer(); orchestrators wire through the output and never call this directly.
- class IMultiInput[source]#
Bases:
IInputAn 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.
- 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.
- abstractmethod remove_provider(provider)[source]#
Remove a provider (a callback of
IOutput.remove_consumer()).
- class IWorkflowComponentInfo[source]#
Bases:
IComponentInfoMetadata about an
IWorkflowComponent.Mirrors C++
IWorkflowComponentInfo.
- class IWorkflowComponent[source]#
Bases:
IIdentityOrchestrates the execution of a set of coupled model components.
Mirrors C++
IWorkflowComponent. Also anISignal<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.
- 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.
- abstractmethod prepare()[source]#
Prepare every managed component and build the execution plan.
- 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 errors(clear_after_read=False)[source]#
The workflow’s diagnostic queue (the normative failure channel).
- Parameters:
clear_after_read (bool)
- Return type:
- abstract property status: WorkflowStatus#
Current workflow status.
- abstract property model_components: list[IModelComponent]#
The model components managed by this workflow.
- abstractmethod add_model_component(component, model_role_identifier=None)[source]#
Add a model component to the workflow.
- Parameters:
component (IModelComponent)
model_role_identifier (IIdentity | None)
- Return type:
- abstractmethod remove_model_component(component)[source]#
Remove a model component from the workflow.
- Parameters:
component (IModelComponent)
- Return type:
- class IWorkflowComponentStatusChangeEventArgs[source]#
Bases:
ABCPayload 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 has_progress_monitor: bool#
Whether
percent_progressis meaningful.
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_lengthof 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 oftime_span. Mirrors C++Temporal::INTERVAL_LENGTH_CONTIGUOUS; any negative value means this.
- class TimeKind(*values)[source]#
Bases:
IntEnumWhat 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:
IntEnumHow 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:
IntEnumHow 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:
IPropertyChangedA 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 emitunits = "days since ..."withcalendar = "standard".
- class ITimeSpan[source]#
Bases:
IDateTimeA time duration anchored at a start date/time.
Mirrors C++
Temporal::ITimeSpan.
- class ITimeModelComponent[source]#
Bases:
IModelComponentA model component that advances through time during simulation.
Mirrors C++
Temporal::ITimeModelComponent.- abstract property next_date_time_julian_day: float#
The Julian day the next
update()will advancecurrent_date_timeto; never earlier than the current time.
- class ITimeSeriesComponentDataItem[source]#
Bases:
IComponentDataItemAn
IComponentDataItemwith a temporal dimension.Mirrors C++
Temporal::ITimeSeriesComponentDataItem. Canonical dimension ordering: time is dimension 0 ofshape; any additional dimensions follow. Data access uses the inheritedget_values_into()/set_values_from()hyperslab API with the time index asstart[0], so “current time step, all entities” is a contiguous slab.- abstract property times: np.ndarray#
Bulk access to all time coordinates as Julian day values.
A float64 array of
time_countelements ordered with the time dimension; the accessor IO writers and interpolating adapters must use.
- abstract property time_dimension: IDimension#
The time dimension (dimension 0 of
shape).
- 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:
ITimeSeriesComponentDataItemA 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 ofshape; any additional dimensions follow.- 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:
IntEnumWhich mesh or network entity a data item’s values are attached to.
Mirrors C++
Spatial::MeshLocation; named after UGRID’slocation.- Node = 0#
- Edge = 1#
- Face = 2#
- Volume = 3#
- class VectorBasis(*values)[source]#
Bases:
IntEnumThe 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:
IntEnumStructure of per-entity values.
Mirrors C++
Spatial::SpatialDataType.- Scalar = 0#
- MultiScalar = 1#
- Vector = 2#
- Tensor = 3#
- class RegularGridType(*values)[source]#
Bases:
IntEnumType of a regular grid.
Mirrors C++
Spatial::RegularGridType.- Cartesian = 0#
- Rectilinear = 1#
- Curvilinear = 2#
- class GeometryType(*values)[source]#
Bases:
IntEnumOGC 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:
IntEnumRaster 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:
IntEnumThe 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:
IntEnumHow 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:
ABCSpatial reference system of a geometric object.
Mirrors C++
Spatial::ISpatialReferenceSystem.- 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_distance_units: DistanceUnits#
The measurement distance units of the vertical axis.
- class IGeometry[source]#
Bases:
ABCBase OGC geometry.
Mirrors C++
Spatial::IGeometry.- 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.
- abstractmethod relate(geom, intersection_pattern_matrix)[source]#
DE-9IM relation test against a 9-character pattern.
- abstractmethod buffer(buffer_distance)[source]#
All points within the given distance of this geometry.
- class IGeometryCollection[source]#
Bases:
IGeometryA collection of geometries. Mirrors C++
IGeometryCollection.
- class IPoint[source]#
Bases:
IGeometryA 0-dimensional point. Mirrors C++
IPoint.- abstract property z: float#
z coordinate (when
IGeometry.is_3d).
- abstract property m: float#
m value (when
IGeometry.is_measured).
- class IMultiPoint[source]#
Bases:
IGeometryCollectionA collection of points. Mirrors C++
IMultiPoint.
- class IVertex[source]#
Bases:
IPointA point participating in topology. Mirrors C++
IVertex.- abstract property vertex_index: int#
Unique vertex index (C++
index(); renamed to avoid clashing withIGeometry.index).
- class IMultiCurve[source]#
Bases:
IGeometryCollectionA collection of curves. Mirrors C++
IMultiCurve.
- class ILineString[source]#
Bases:
ICurveA curve with linear interpolation between points.
Mirrors C++
ILineString.
- class IMultiLineString[source]#
Bases:
IMultiCurveA collection of line strings. Mirrors C++
IMultiLineString.
- class ILine[source]#
Bases:
ILineStringA line string with exactly two points. Mirrors C++
ILine.
- class ILinearRing[source]#
Bases:
ILineStringA closed, simple line string. Mirrors C++
ILinearRing.
- class IEdge[source]#
Bases:
ABCA quad-edge topology edge.
Mirrors C++
IEdge. Per-entity topology navigation is a convenience for spot queries and editing; bulk consumers must useIMeshView.
- class ISurface[source]#
Bases:
IGeometryA 2-dimensional geometry. Mirrors C++
ISurface.- abstract property boundary_multi_curve: IMultiCurve#
The boundary curves of the surface.
- class IMultiSurface[source]#
Bases:
IGeometryCollectionA collection of surfaces. Mirrors C++
IMultiSurface.
- class IPolygon[source]#
Bases:
ISurfaceA planar surface with an exterior ring and interior rings.
Mirrors C++
IPolygon.- abstract property exterior_ring: ILineString#
The exterior boundary ring.
- abstractmethod interior_ring(index)[source]#
The interior ring at the given index.
- Parameters:
index (int)
- Return type:
- 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:
IMultiSurfaceA collection of polygons. Mirrors C++
IMultiPolygon.
- class IMeshView[source]#
Bases:
ABCBulk, 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_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): edgeeconnectsedge_nodes[2*e]andedge_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:
IIdentityA graph of connected vertices and edges.
Mirrors C++
Spatial::INetwork.
- class IPolyhedralSurface[source]#
Bases:
ISurfaceA contiguous collection of polygon patches stitched along shared boundary edges.
Mirrors C++
Spatial::IPolyhedralSurface.
- class ITIN[source]#
Bases:
IPolyhedralSurfaceA triangulated irregular network of
ITrianglepatches.Mirrors C++
Spatial::ITIN.
- class IRaster[source]#
Bases:
IIdentityA raster spatial feature.
Mirrors C++
Spatial::IRaster.- 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
- class IRasterBand[source]#
Bases:
IIdentityOne 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 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 asget_values_into.
- class IRegularGrid2D[source]#
Bases:
IIdentityA 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.
- abstractmethod x_node_location(x_node_index, y_node_index)[source]#
x coordinate of a node (spot queries; bulk consumers use
node_xs).
- abstractmethod y_node_location(x_node_index, y_node_index)[source]#
y coordinate of a node (spot queries; bulk consumers use
node_ys).
- 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).
- abstract property active_cells: np.ndarray#
Bulk activity mask of all cells, row-major
[y][x]; nonzero means active (uint8).
- class IRegularGrid3D[source]#
Bases:
IIdentityA 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.
- abstractmethod x_node_location(x_node_index, y_node_index)[source]#
x coordinate of a node (spot queries).
- abstractmethod y_node_location(x_node_index, y_node_index)[source]#
y coordinate of a node (spot queries).
- abstractmethod z_node_location(x_node_index, y_node_index, z_node_index)[source]#
z coordinate of a node (spot queries).
- 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).
- abstract property active_cells: np.ndarray#
Bulk activity mask of all cells, row-major
[z][y][x](uint8).
- class IGeometryComponentDataItem[source]#
Bases:
IComponentDataItemData associated with a collection of geometries.
Mirrors C++
Spatial::IGeometryComponentDataItem. Canonical dimension ordering: the geometry dimension is dimension 0 ofshape; any additional dimensions follow.- abstract property geometry_type: GeometryType#
The type of the associated geometries.
- abstract property geometry_dimension: IDimension#
The geometry dimension (dimension 0 of
shape).
- class INetworkComponentDataItem[source]#
Bases:
IComponentDataItemData associated with the edges and/or vertices of a network.
Mirrors C++
Spatial::INetworkComponentDataItem. Canonical dimension ordering: the entity dimension selected bynetwork_data_type(edge or vertex) is dimension 0 ofshape.- 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:
IComponentDataItemData associated with the patches, edges, or vertices of a polyhedral surface.
Mirrors C++
Spatial::IPolyhedralSurfaceComponentDataItem. Canonical dimension ordering: the entity dimension selected bylocationis dimension 0 ofshape.- 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:
IPolyhedralSurfaceComponentDataItemA polyhedral-surface data item whose surface is a TIN.
Mirrors C++
Spatial::ITINComponentDataItem.
- class IRasterComponentDataItem[source]#
Bases:
IComponentDataItemData 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 ofshape.- 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:
IComponentDataItemData 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 ofshape; 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:
IComponentDataItemData 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 ofshape; 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:
ABCWhere 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 layerkmoves 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
ISpatialReferenceSystemdeclares. Interface 0 is the top of the column, so a column oflayer_countlayers haslayer_count + 1interfaces.- abstract property kind: VerticalCoordinateKind#
The coordinate family.
- 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_varyingis false.
- abstractmethod interface_elevation(cell_index, interface_index)[source]#
Elevation of one interface in one cell (spot queries).
interface_indexruns from 0 at the top tolayer_countat the bed. Bulk consumers useinterface_elevations.
- 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 untilgeometry_epochchanges; the accessor a remap uses.
- class ILayering[source]#
Bases:
ABCValues 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,ILayeringA polyhedral surface whose values are resolved into vertical layers.
Mirrors C++
Spatial::ILayeredMeshComponentDataItem. Values are indexed{face, layer}(then a Component dimension if any);locationisMeshLocation.Volumefor cell values andFacefor values on each face’s layer interfaces.
- class ICrossSection[source]#
Bases:
ABCThe 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_countis 0 for producers that hold no survey points.Conventions, as in the standard:
stageis 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. Belowinvert_elevationevery quantity is zero. At the invert the areas are zero buttop_width()andwetted_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.
- abstractmethod flow_area(stage)[source]#
The conveying part of that area; never above
storage_area().
- 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.
- 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 oflen(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
- abstractmethod stations()[source]#
The survey points, left bank to right bank.
Returns
(stations, elevations), two float64 arrays ofstation_countelements (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,ILayeringA 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 edgelocationreports.- abstractmethod cross_section(entity_index)[source]#
The channel shape at one entity, or
Nonewhere there is none.Nonesays 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,IGeometryComponentDataItemGeometry 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,INetworkComponentDataItemNetwork data varying in time.
Mirrors C++
SpatioTemporal::ITimeNetworkComponentDataItem. Canonical dimension ordering: time is dimension 0, the entity dimension selected bynetwork_data_typeis dimension 1.
- class ITimeSeriesPolyhedralSurfaceComponentDataItem[source]#
Bases:
ITimeSeriesComponentDataItem,IPolyhedralSurfaceComponentDataItemPolyhedral-surface data varying in time.
Mirrors C++
SpatioTemporal::ITimeSeriesPolyhedralSurfaceComponentDataItem. Canonical dimension ordering: time is dimension 0, the entity dimension selected bymesh_data_typeis dimension 1.
- class ITimeSeriesTINComponentDataItem[source]#
Bases:
ITimeSeriesPolyhedralSurfaceComponentDataItemA time-varying polyhedral-surface data item whose surface is a TIN.
Mirrors C++
SpatioTemporal::ITimeSeriesTINComponentDataItem.
- class ITimeSeriesRasterComponentDataItem[source]#
Bases:
ITimeSeriesComponentDataItem,IRasterComponentDataItemRaster 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,IRegularGrid2DComponentDataItem2D 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,IRegularGrid3DComponentDataItem3D 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,ILayeredMeshComponentDataItemA 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 whenmesh_data_typeis not Scalar. The vertical coordinate’sgeometry_epochtells a consumer whether the elevations it cached still describe the current time step.
- class ITimeLayeredNetworkComponentDataItem[source]#
Bases:
ITimeNetworkComponentDataItem,ILayeredNetworkComponentDataItemA 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 whennetwork_data_typeis 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:
ABCHandle to an asynchronous communication operation.
Mirrors C++
Distributed::IExchangeRequest. Returned by the asynchronousITransportoperations and byIPartitionedComponentDataItem.synchronize_async().- abstractmethod wait_for(timeout_seconds)[source]#
Block until the operation completes or the timeout elapses.
- class Endpoint(address='', rank=-1)[source]#
Bases:
objectOne participant reachable through a transport.
Mirrors C++
Distributed::ITransport::Endpoint.
- class ITransport[source]#
Bases:
IIdentityA 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
int64array – and then the payload itself as a 1-D array on the same tag; text travels as UTF-8 bytes in auint8array. A transport that can detect a lost peer completes every pending operation with it as failed; callers bound their waits with the asynchronous operations andIExchangeRequest.wait_for().- 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.
- abstractmethod receive(source, tag, into)[source]#
Receive a typed payload into a pre-allocated array, blocking.
- abstractmethod send_async(to, tag, payload)[source]#
Nonblocking send; the payload must stay valid until completion.
- Parameters:
- Return type:
- class IDistributedModelComponent[source]#
Bases:
IModelComponentAn
IModelComponentparticipating in distributed execution through a transport.Mirrors C++
Distributed::IDistributedModelComponent; advertisesDistributedExecution.- abstract property transport: ITransport#
The transport this component communicates through.
- class IProxyModelComponent[source]#
Bases:
IDistributedModelComponentA local stand-in for a remote model component.
Mirrors C++
Distributed::IProxyModelComponent. EveryIModelComponentmethod 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 toFailed, queues aFatalErrorEntry, 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.
- abstractmethod connect_remote()[source]#
Establish the connection to the remote component.
Mirrors C++
connectToPeer()(renamed there for the same reason this is not calledconnect: the inherited signal method).
- abstractmethod disconnect_remote()[source]#
Close the connection to the remote component.
- Return type:
None
- class IPartitionedComponentDataItem[source]#
Bases:
IComponentDataItemA data item whose entity dimension is decomposed across partitions, with local virtual (ghost/halo) representation of remote entities.
Mirrors C++
Distributed::IPartitionedComponentDataItem. The axispartitioned_dimensionindexes 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 advertisePartitionedData.- 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.
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, andUnknownhave 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.
- data_kind_of(dtype)[source]#
The
DataKindcorresponding to a NumPy dtype.Mirrors
Helpers::DataKindOf; unmapped dtypes areDataKind.Opaque. Byte-swapped (non-native-endian) dtypes are deliberately unmapped: the wire and memory formats of the standard are native-endian.
- dtype_of(kind)[source]#
The NumPy dtype for a numeric
DataKind.- Raises:
ValueError – for String, Opaque, and Unknown.
- Parameters:
kind (DataKind)
- Return type:
- 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 returnsFalse.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:
from_status (ComponentStatus)
to_status (ComponentStatus)
- Return type:
- is_valid_workflow_status_transition(from_status, to_status)[source]#
Whether a workflow status transition is legal.
Mirrors
Helpers::isValidWorkflowStatusTransition.- Parameters:
from_status (WorkflowStatus)
to_status (WorkflowStatus)
- Return type:
- get_value(item, index)[source]#
Read the single element at
index; returns(ok, value, message).Mirrors
Helpers::getValue.- Parameters:
item (IComponentDataItem)
index (Sequence[int])
- set_value(item, value, index)[source]#
Write the single element at
index; returns(ok, message).Mirrors
Helpers::setValue.- Parameters:
item (IComponentDataItem)
index (Sequence[int])
- Return type:
- get_values(item, start, count, out=None)[source]#
Read a hyperslab into a C-ordered array of shape
count.Mirrors
Helpers::getValues; allocatesoutwhen not supplied. :returns:(ok, values, message).
- set_values(item, values, start, count)[source]#
Write a hyperslab from
values; returns(ok, message).Mirrors
Helpers::setValues.
- get_values_or_raise(item, start, count, out=None)[source]#
Raising wrapper over
get_values().- Raises:
RuntimeError – with the item’s failure message on error.
- Parameters:
item (IComponentDataItem)
start (Sequence[int])
count (Sequence[int])
out (Optional[np.ndarray])
- Return type:
np.ndarray
- set_values_or_raise(item, values, start, count)[source]#
Raising wrapper over
set_values().- Raises:
RuntimeError – with the item’s failure message on error.
- Parameters:
item (IComponentDataItem)
values (np.ndarray)
start (Sequence[int])
count (Sequence[int])
- Return type:
None
- julian_day_to_datetime(julian_day)[source]#
Convert a Julian day value to a timezone-aware UTC datetime.
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 anIModelComponentInfo*. 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: