Visual Debugger

Browser-based simulation debugger with charts, entity graphs, and event logs.

Browser-based simulation debugger.

Usage::

from happysimulator.visual import serve, Chart

sim = Simulation(sources=[source], entities=[server, sink])
serve(sim)  # opens browser, step through interactively

Chart dataclass

Chart(
    data: Data,
    title: str = "",
    y_label: str = "",
    x_label: str = "Time (s)",
    color: str = "#3b82f6",
    transform: str = "raw",
    window_s: float = 1.0,
    y_min: float | None = None,
    y_max: float | None = None,
)

A predefined dashboard chart backed by a Data object.

Parameters:

Name	Type	Description	Default
data	Data	The Data object to read samples from.	required
title	str	Chart title shown in the title bar.	''
y_label	str	Y-axis label text.	''
x_label	str	X-axis label text.	'Time (s)'
color	str	Line color as CSS hex string.	'#3b82f6'
transform	str	One of "raw", "mean", "p50", "p99", "p999", "max", "rate".	'raw'
window_s	float	Bucket window size for aggregated transforms.	1.0
y_min	float | None	Fixed Y-axis minimum (None for auto-scale).	None
y_max	float | None	Fixed Y-axis maximum (None for auto-scale).	None

from_probe classmethod

from_probe(probe: Probe, **kwargs: Any) -> Chart

Create a Chart from a Probe, deriving title and data automatically.

to_config

to_config() -> dict[str, Any]

Serialize display config (everything except the data reference).

get_data

get_data(
    start_s: float | None = None, end_s: float | None = None
) -> dict[str, Any]

Read from the Data object and apply the transform.

Parameters:

Name	Type	Description	Default
start_s	float | None	Optional start time filter (inclusive).	None
end_s	float | None	Optional end time filter (exclusive).	None

serve

serve(
    sim: Simulation,
    *,
    charts: list[Chart] | None = None,
    host: str = "127.0.0.1",
    port: int = 8765,
    open_browser: bool = True,
    time_unit: str = "s",
) -> None

Launch the simulation debugger in a browser.

Pauses the simulation at t=0, starts a local web server, and opens the debugger UI. Blocks until the server is stopped (Ctrl+C).

Parameters:

Name	Type	Description	Default
sim	Simulation	A simulation that has NOT been run yet.	required
charts	list[Chart] | None	Optional list of predefined Chart objects to show on the Dashboard.	None
host	str	Bind address for the web server.	'127.0.0.1'
port	int	Port for the web server.	8765
open_browser	bool	Whether to open the default browser automatically.	True
time_unit	str	Display unit for time axes — "s" (seconds), "min" (minutes), or "h" (hours).	's'