HyDRA Identification¶
flowcean.hybrid.hydra is the curated facade for HyDRA identification, callbacks, trace schemas, simulations, and mode-selector APIs. Selector-specific types and helpers are also available from flowcean.hybrid.hydra.selector.
Curated HyDRA hybrid-system identification API.
Classes¶
PlotCallback(trace: Trace, dims: Sequence[int] | None = None, *, trace_index: int = 0, ax: Axes | None = None, show: bool = True, pause: float = 0.001)
HyDRALearner(regressor_factory: Callable[[], SupervisedIncrementalLearner], threshold: float, start_width: int = 10, step_width: int = 5, selector_learner: HybridDecisionTreeLearner | None = None, callback: HyDRACallback | None = None, trace_schema: HyDRATraceSchema | None = None)
Bases: SupervisedLearner
Identify hybrid-system modes from trace inputs and derivatives.
regressor_factory must create fresh incremental supervised learners.
The current learner supports single-output derivative training. When a
selector learner is provided, HyDRA labels accurate trace segments and
trains a selector to route future rows to learned modes.
Attributes¶
instance-attribute
¶
regressor_factory: Callable[[], SupervisedIncrementalLearner] = regressor_factory
instance-attribute
¶
selector_learner: HybridDecisionTreeLearner | None = selector_learner
Methods:¶
HyDRAModel(modes: list[Model], *, input_features: list[str], output_features: list[str], selector: HybridDecisionTreeModel | None = None, trace_schema: HyDRATraceSchema | None = None)
Bases: Model
Model composed of learned continuous modes and an optional selector.
A single-mode model predicts directly with that mode. A multi-mode model needs a selector for batch prediction. Model persistence uses Flowcean's trusted-only pickle-based model serialization.
Attributes¶
Methods:¶
simulate(t_span: tuple[float, float], x0: Iterable[float], *, input_stream: InputStream | None = None, capture_inputs: bool | None = None, sample_times: Iterable[float] | None = None, sample_dt: float | None = None, rtol: float = 1e-07, atol: float = 1e-09, max_step: float | None = None) -> Trace
predict_next_state(state: Iterable[float], *, t: float, dt: float, input_stream: InputStream | None = None, rtol: float = 1e-07, atol: float = 1e-09, max_step: float | None = None) -> ndarray
dataclass
¶
HyDRATraceSchema(time: str, state: tuple[str, ...], derivative: tuple[str, ...], inputs: tuple[str, ...] = ())
Column schema for HyDRA trace-based learning.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time
|
str
|
Time column name. |
required |
state
|
tuple[str, ...]
|
State column names used as model inputs. |
required |
derivative
|
tuple[str, ...]
|
Derivative column names used as model outputs. |
required |
inputs
|
tuple[str, ...]
|
Optional external input column names. |
()
|
HyDRA currently expects derivative columns to align with state columns and
supports single-output training in HyDRALearner.
HybridDecisionTreeLearner(feature_config: SelectorFeatureConfig, **tree_kwargs: Any)
Bases: SupervisedLearner
Attributes¶
instance-attribute
¶
Methods:¶
learn(inputs: DataFrame | LazyFrame, outputs: DataFrame | LazyFrame) -> HybridDecisionTreeModel
learn_from_traces(traces: list[DataFrame], mode_to_flow: dict[int, Model] | None = None) -> HybridDecisionTreeModel
HybridDecisionTreeModel(classifier: DecisionTreeClassifier, feature_columns: tuple[str, ...], feature_config: SelectorFeatureConfig, mode_to_flow: dict[int, Model] | None = None)
Bases: Model
Attributes¶
Methods:¶
predict_details(input_features: DataFrame | LazyFrame) -> list[ModePredictionResult]
dataclass
¶
ModePredictionResult(ready: bool, mode_id: int | None, probabilities: dict[int, float] = dict(), leaf_id: int | None = None, flow_model: Model | None = None)
dataclass
¶
dataclass
¶
SelectorFeatureConfig(state_features: tuple[str, ...] = (), input_features: tuple[str, ...] = (), derivative_features: tuple[str, ...] = (), state_history: int = 0, input_history: int = 0, derivative_history: int = 0, mode_history: int = 0)
Configuration for selector feature construction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state_features
|
tuple[str, ...]
|
State columns available to the selector. |
()
|
input_features
|
tuple[str, ...]
|
Raw input columns available to the selector. |
()
|
derivative_features
|
tuple[str, ...]
|
Derivative columns available to the selector. |
()
|
state_history
|
int
|
Number of previous state rows used for selector features. |
0
|
input_history
|
int
|
Number of previous input rows used for selector features. |
0
|
derivative_history
|
int
|
Number of previous derivative rows used for selector features. |
0
|
mode_history
|
int
|
Number of previous mode labels used for selector features. |
0
|
dataclass
¶
SelectorInspection(feature_columns: tuple[str, ...], classes: tuple[int, ...], max_depth: int, n_leaves: int, nodes: tuple[SelectorNodeInspection, ...], leaves: tuple[SelectorLeafInspection, ...], modes: tuple[SelectorModeInspection, ...])
Attributes¶
dataclass
¶
dataclass
¶
dataclass
¶
SelectorNodeInspection(node_id: int, sample_count: int, impurity: float, is_leaf: bool, predicted_mode_id: int, weighted_class_support: dict[int, float], feature_index: int | None = None, feature_name: str | None = None, threshold: float | None = None, left_child_id: int | None = None, right_child_id: int | None = None)
Attributes¶
StatefulHybridDecisionTreeSelector(model: HybridDecisionTreeModel, seed_modes: Sequence[int] = ())
dataclass
¶
Functions:¶
evaluate_selector_autoregressive(model: HybridDecisionTreeModel, traces: list[DataFrame], seed_modes: tuple[int, ...] | list[int] = ()) -> SelectorEvaluationReport
evaluate_selector_oracle(model: HybridDecisionTreeModel, traces: list[DataFrame]) -> SelectorEvaluationReport
compare_state_traces(reference: Trace, predicted: Trace) -> StateTraceComparison