plotting

Plotting helpers for hybrid system traces.

plot_trace(trace, dims=None, *, location_colors=None, show_locations=True, show_location_labels=False, show_events=True, show_event_labels=True, show=False, ax=None)

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.

Source code in src/flowcean/ode/plotting.py

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

    Args:
        trace: Trace to visualize.
        dims: State indices to plot.
        location_colors: Optional color mapping for locations.
        show_locations: Whether to shade location regions.
        show_location_labels: Whether to label locations above the trace.
        show_events: Whether to show transition events.
        show_event_labels: Whether to label transition events.
        show: Whether to call matplotlib show().
        ax: Optional axis to draw into.

    Returns:
        Matplotlib axes containing the plot.
    """
    if dims is None:
        dims = list(range(trace.x.shape[1]))

    if ax is None:
        _, ax = plt.subplots()
    if ax is None:
        message = "Failed to create matplotlib axes."
        raise RuntimeError(message)

    for dim in dims:
        ax.plot(trace.t, trace.x[:, dim], label=f"x{dim}")

    if show_locations:
        _plot_location_spans(
            trace,
            ax=ax,
            location_colors=location_colors,
            show_labels=show_location_labels,
        )

    if show_events:
        _plot_events(trace, ax=ax, show_labels=show_event_labels)

    ax.set_xlabel("t")
    ax.set_ylabel("state")
    ax.legend(loc="best")

    if show:
        plt.show()

    return ax

plot_phase(trace, x_dim=0, y_dim=1, *, location_colors=None, show_location_legend=True, show=False, ax=None)

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.

Source code in src/flowcean/ode/plotting.py

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

    Args:
        trace: Trace to visualize.
        x_dim: State index on the x-axis.
        y_dim: State index on the y-axis.
        location_colors: Optional color mapping for locations.
        show_location_legend: Whether to show location labels in legend.
        show: Whether to call matplotlib show().
        ax: Optional axis to draw into.

    Returns:
        Matplotlib axes containing the plot.
    """
    if ax is None:
        _, ax = plt.subplots()
    if ax is None:
        message = "Failed to create matplotlib axes."
        raise RuntimeError(message)

    segments, locations = _location_segments(trace)
    colors = _location_color_map(locations, location_colors)

    for start, end, location in segments:
        ax.plot(
            trace.x[start:end, x_dim],
            trace.x[start:end, y_dim],
            color=colors[location],
            label=f"{location}",
        )
    ax.set_xlabel(f"x{x_dim}")
    ax.set_ylabel(f"x{y_dim}")

    if show_location_legend:
        _dedupe_legend(ax)

    if show:
        plt.show()

    return ax