Skip to content

Hybrid Systems

flowcean.hybrid provides hybrid-system definitions, simulation, trace I/O, and plotting. Reusable systems live in the hybrid benchmarks API, and identification lives in the HyDRA API. See the hybrid systems guide for modeling concepts and examples.

hybrid

Hybrid-system modeling, simulation, trace I/O, and plotting.

Attributes

Input module-attribute 

Input = np.ndarray

InputStream module-attribute 

InputStream = Callable[[float], Input]

Parameters module-attribute 

Parameters = Mapping[str, float]

Classes

ContinuousDynamics dataclass 

ContinuousDynamics(flow: Callable[..., Derivative], label: str | None = None)

Reusable continuous dynamics definition.

Parameters:

Name Type Description Default
flow Callable[..., Derivative]

Dynamics function returning the state derivative. Scalar derivative returns are accepted only for single-state systems, both during solver evaluation and when derivatives are captured on the returned trace grid.

 required
label str | None

Optional display label.

 None
Attributes
flow instance-attribute 
flow: Callable[..., Derivative]
label class-attribute instance-attribute 
label: str | None = None

CrossingDirection

Bases: IntEnum

Direction in which an event surface must cross zero.

Attributes
FALLING class-attribute instance-attribute 
FALLING = -1
EITHER class-attribute instance-attribute 
EITHER = 0
RISING class-attribute instance-attribute 
RISING = 1

Event dataclass 

Event(time: float, source_location: str, target_location: str, event_surface: str, reset: str | None, state_before: State, state_after: State, microstep: int)

Transition event information for a trace.

Attributes
time instance-attribute 
time: float
source_location instance-attribute 
source_location: str
target_location instance-attribute 
target_location: str
event_surface instance-attribute 
event_surface: str
reset instance-attribute 
reset: str | None
state_before instance-attribute 
state_before: State
state_after instance-attribute 
state_after: State
microstep instance-attribute 
microstep: int

EventSurface dataclass 

EventSurface(fn: Callable[..., float], direction: CrossingDirection = EITHER, label: str | None = None)

Scalar event surface defining a simulated transition event.

Flowcean transitions fire when fn reaches zero in direction. This is event-surface semantics, not Boolean guard-region semantics.

Parameters:

Name Type Description Default
fn Callable[..., float]

Root function; transitions when it crosses zero.

 required
direction CrossingDirection

Crossing direction. Defaults to either direction.

 EITHER
label str | None

Optional display label.

 None
Attributes
fn instance-attribute 
fn: Callable[..., float]
direction class-attribute instance-attribute 
direction: CrossingDirection = CrossingDirection.EITHER
label class-attribute instance-attribute 
label: str | None = None

EventSurfaceFunction

Bases: Protocol

Scalar event-surface callback.

FlowFunction

Bases: Protocol

Continuous dynamics callback.

HybridSystem dataclass 

HybridSystem(locations: Sequence[Location], transitions: Sequence[Transition], initial_location: Location, initial_state: State, parameters: Parameters = dict())

Hybrid system with locations and transitions.

Parameters:

Name Type Description Default
locations Sequence[Location]

Location objects in this system.

 required
transitions Sequence[Transition]

Transition list defining event surfaces and resets.

 required
initial_location Location

Starting location object.

 required
initial_state State

Initial state vector.

 required
parameters Parameters

Global parameter map passed to callbacks.

 dict()
Attributes
locations instance-attribute 
locations: Sequence[Location]
transitions instance-attribute 
transitions: Sequence[Transition]
initial_location instance-attribute 
initial_location: Location
initial_state instance-attribute 
initial_state: State
parameters class-attribute instance-attribute 
parameters: Parameters = field(default_factory=dict)
Methods:
transitions_from 
transitions_from(location: Location) -> list[Transition]

Return transitions leaving the given location.

Location dataclass 

Location(dynamics: ContinuousDynamics, *, label: str | None = None, parameters: Parameters | None = None)

Location(dynamics: Callable[..., Derivative], *, label: str | None = None, parameters: Parameters | None = None)

Location(dynamics: ContinuousDynamics | Callable[..., Derivative], *, label: str | None = None, parameters: Parameters | None = None)

Discrete hybrid-automaton location.

Parameters:

Name Type Description Default
dynamics ContinuousDynamics | Callable[..., Derivative]

Continuous dynamics or bare flow callback active here.

 required
label str | None

Optional display label.

 None
parameters Parameters | None

Location-local parameter map.

 None
Attributes
dynamics instance-attribute 
dynamics: ContinuousDynamics
label instance-attribute 
label: str | None
parameters instance-attribute 
parameters: Parameters

Reset dataclass 

Reset(fn: Callable[..., State], label: str | None = None)

State reset applied on a transition.

Parameters:

Name Type Description Default
fn Callable[..., State]

Reset function applied at the event time.

 required
label str | None

Optional display label.

 None
Attributes
fn instance-attribute 
fn: Callable[..., State]
label class-attribute instance-attribute 
label: str | None = None

ResetFunction

Bases: Protocol

State reset callback.

SurfaceEntryPolicy

Bases: StrEnum

Behavior when a transition surface is zero on location entry.

Attributes
ERROR class-attribute instance-attribute 
ERROR = 'error'
TRIGGER class-attribute instance-attribute 
TRIGGER = 'trigger'
CONTINUE class-attribute instance-attribute 
CONTINUE = 'continue'

Trace dataclass 

Trace(t: ndarray, x: ndarray, location: ndarray, events: Sequence[Event], u: ndarray | None = None, dx: ndarray | None = None)

Simulation trace with time, state, and location labels.

Attributes
t instance-attribute 
t: ndarray
x instance-attribute 
x: ndarray
location instance-attribute 
location: ndarray
events instance-attribute 
events: Sequence[Event]
u class-attribute instance-attribute 
u: ndarray | None = None
dx class-attribute instance-attribute 
dx: ndarray | None = None
Methods:
as_dict 
as_dict() -> dict[str, object]

Return a dictionary view of the trace.

Transition dataclass 

Transition(source: Location, target: Location, event: EventSurface | Callable[..., float], reset: Reset | Callable[..., State] | None = None, *, entry_policy: SurfaceEntryPolicy = ERROR)

Discrete event-triggered transition between locations.

event is a scalar zero-crossing surface.

Parameters:

Name Type Description Default
source Location

Source location.

 required
target Location

Target location.

 required
event EventSurface | Callable[..., float]

Event surface that triggers the transition.

 required
reset Reset | Callable[..., State] | None

Optional reset applied upon transition.

 None
entry_policy SurfaceEntryPolicy

Behavior when the event surface is exactly zero upon entry to the source location.

 ERROR
Attributes
source instance-attribute 
source: Location
target instance-attribute 
target: Location
event instance-attribute 
event: EventSurface
reset class-attribute instance-attribute 
reset: Reset | None = None
entry_policy class-attribute instance-attribute 
entry_policy: SurfaceEntryPolicy = SurfaceEntryPolicy.ERROR

AmbiguousTransitionError

Bases: HybridSimulationError

Raised when multiple TRIGGER surfaces are zero on location entry.

HybridSimulationError

Bases: RuntimeError

Base class for hybrid simulation runtime failures.

InvalidEventSurfaceValueError

Bases: HybridSimulationError

Raised when an event surface returns NaN.

SimulationProgressError

Bases: HybridSimulationError

Raised when a solver event does not advance physical time.

SurfaceEntryError

Bases: HybridSimulationError

Raised when an ERROR surface is zero on location entry.

Functions:

save_traces_csv 

save_traces_csv(traces: Sequence[Trace], path: str, *, trace_metadata: Sequence[Mapping[str, object] | None] | None = None) -> None

Write traces to a directory with one CSV file per trace.

save_traces_parquet 

save_traces_parquet(traces: Sequence[Trace], path: str, *, trace_metadata: Sequence[Mapping[str, object] | None] | None = None) -> None

Write traces to a directory with one Parquet file per trace.

trace_to_polars 

trace_to_polars(trace: Trace, *, state_names: Sequence[str] | None = None, derivative_names: Sequence[str] | None = None, input_names: Sequence[str] | None = None) -> DataFrame

Convert a single trace into a Polars DataFrame.

traces_to_polars 

traces_to_polars(traces: Sequence[Trace], *, state_names: Sequence[str] | None = None, derivative_names: Sequence[str] | None = None, input_names: Sequence[str] | None = None) -> list[DataFrame]

Convert traces into per-trace Polars DataFrames.

Parameters:

Name Type Description Default
traces Sequence[Trace]

Sequence of traces to convert.

 required
state_names Sequence[str] | None

Optional names for state dimensions.

 None
derivative_names Sequence[str] | None

Optional names for derivative dimensions.

 None
input_names Sequence[str] | None

Optional names for input dimensions.

 None

Returns:

Type Description
list[DataFrame]

List of per-trace DataFrames in trace order.

plot_phase 

plot_phase(trace: Trace, x_dim: int = 0, y_dim: int = 1, *, location_colors: Mapping[str, str] | None = None, show_location_legend: bool = True, show: bool = False, ax: Axes | None = None) -> Axes

Plot phase portrait segments colored by location.

Parameters:

Name Type Description Default
trace Trace

Trace to visualize.

 required
x_dim int

State index on the x-axis.

 0
y_dim int

State index on the y-axis.

 1
location_colors Mapping[str, str] | None

Optional color mapping for locations.

 None
show_location_legend bool

Whether to show location labels in legend.

 True
show bool

Whether to call matplotlib show().

 False
ax Axes | None

Optional axis to draw into.

 None

Returns:

Type Description
Axes

Matplotlib axes containing the plot.

plot_trace 

plot_trace(trace: Trace, dims: Sequence[int] | None = None, *, location_colors: Mapping[str, str] | None = None, show_locations: bool = True, show_location_labels: bool = False, show_events: bool = True, show_event_labels: bool = True, show: bool = False, ax: Axes | None = None) -> Axes

Plot state trajectories with location shading and event markers.

Parameters:

Name Type Description Default
trace Trace

Trace to visualize.

 required
dims Sequence[int] | None

State indices to plot.

 None
location_colors Mapping[str, str] | None

Optional color mapping for locations.

 None
show_locations bool

Whether to shade location regions.

 True
show_location_labels bool

Whether to label locations above the trace.

 False
show_events bool

Whether to show transition events.

 True
show_event_labels bool

Whether to label transition events.

 True
show bool

Whether to call matplotlib show().

 False
ax Axes | None

Optional axis to draw into.

 None

Returns:

Type Description
Axes

Matplotlib axes containing the plot.

generate_traces 

generate_traces(system: HybridSystem, t_span: tuple[float, float], initial_states: Iterable[Iterable[float]], *, input_stream: InputStream | None = None, capture_inputs: bool | None = None, capture_derivatives: bool = False, max_jumps: int = 256, rtol: float = 1e-07, atol: float = 1e-09, max_step: float | None = None, dense_output: bool = False, sample_times: Iterable[float] | None = None, sample_dt: float | None = None) -> list[Trace]

Simulate a batch of traces for a set of initial states.

The input stream and capture semantics match :func:simulate, including the requirement that capture_derivatives=True assumes pure flow callbacks under repeated evaluation on the returned trace grid. Scalar derivative returns are accepted only for single-state systems.

simulate 

simulate(system: HybridSystem, t_span: tuple[float, float], x0: Iterable[float] | None = None, location0: Location | None = None, *, input_stream: InputStream | None = None, capture_inputs: bool | None = None, capture_derivatives: bool = False, max_jumps: int = 256, rtol: float = 1e-07, atol: float = 1e-09, max_step: float | None = None, dense_output: bool = False, sample_times: Iterable[float] | None = None, sample_dt: float | None = None) -> Trace

Simulate a hybrid system and return a trace.

Parameters:

Name Type Description Default
system HybridSystem

Hybrid system to simulate.

 required
t_span tuple[float, float]

Start and end time for integration.

 required
x0 Iterable[float] | None

Optional initial state override.

 None
location0 Location | None

Optional initial location override.

 None
input_stream InputStream | None

Optional input stream accessor for callbacks.

 None
capture_inputs bool | None

Input capture mode. If None, capture iff an input stream is provided.

 None
capture_derivatives bool

Whether to re-evaluate Location.dynamics.flow on the returned trace grid and store the sampled derivatives in Trace.dx. This assumes pure flow callbacks under repeated evaluation. Scalar derivative returns are accepted only for single-state systems.

 False
max_jumps int

Maximum number of transitions allowed.

 256
rtol float

Relative tolerance for the solver.

 1e-07
atol float

Absolute tolerance for the solver.

 1e-09
max_step float | None

Optional maximum step size.

 None
dense_output bool

Whether to build a continuous solution per segment.

 False
sample_times Iterable[float] | None

Monotone time grid to sample from the dense solution.

 None
sample_dt float | None

Fixed sampling interval to generate a time grid.

 None

Returns:

Name Type Description
Trace Trace

The simulation trace with location labels and events.