Visualisation

6.4 Visualisation

The SDK provides a declarative visualisation system with two backends: Matplotlib (static, publication-quality) and Plotly (interactive, browser-based). Both backends support all 15 chart types through a unified Chart / Dashboard API.

15 Chart Types

Chart Type	Description	Best For
LINE	Time series line chart	Accumulator dynamics, prices, populations
AREA	Stacked area chart	Composition over time (SIR compartments)
BAR	Bar chart (per-step or final)	Agent type counts, final metrics
HISTOGRAM	Value distribution	Return distributions, state distributions
SCATTER	2D scatter plot	Phase diagrams, agent-level relationships
NETWORK	Network topology graph	Interbank networks, social graphs
GRID_HEATMAP	2D grid heatmap	Fire spread, cell states, density maps
PHASE_DIAGRAM	2D phase space trajectory	System dynamics, limit cycles
AGENT_TIMELINE	Per-agent state over time	Individual agent behaviour tracking
MC_ENVELOPE	Mean ± std envelope from MC runs	Monte Carlo summary visualisation
ANIMATED_LINE	Frame-by-frame animation	Dynamic process visualisation
BOX_PLOT	Box-and-whisker plot	MC distribution comparison
VIOLIN	Violin plot (distribution + density)	Rich distribution visualisation
PARALLEL_COORDINATES	High-dimensional parallel axes	Parameter sweep exploration
SANKEY	Flow diagram with weighted edges	Resource flows, market share flows

Usage

from simudyne.engine.viz import Dashboard, Chart, ChartType, VizBackend

viz = Dashboard(
    title="Gai-Kapadia Results",
    charts=[
        Chart("Cascade", ChartType.LINE, fields=["total_defaults", "solvent_count"]),
        Chart("Default Distribution", ChartType.HISTOGRAM, field="total_defaults"),
    ],
    backend=VizBackend.MATPLOTLIB,
)

# Record from model history
for step in model.history:
    viz.record_step(model, tick=step["tick"])

viz.show()                     # Display in window
viz.save_png("output/", dpi=150)   # Save as PNG files
viz.to_html("output/")         # Export as interactive HTML (Plotly)

The ModelVisualizer factory class provides convenience constructors:

from simudyne.engine.viz import ModelVisualizer

# From a SimulationRecorder (auto-detect chart types from recorded fields)
viz = ModelVisualizer.from_recorder(recorder, title="Recorded Data")

# From an MCResult (MC envelope + distribution charts)
viz = ModelVisualizer.from_mc_result(mc_result, fields=["price", "volatility"])

# From a live model (current agent state)
viz = ModelVisualizer.from_model(model, agent_type="Bank")

---