Analysis

Phase detection, event lifecycle tracing, and LLM-ready simulation analysis.

Analysis tools for reasoning about simulation results.

This package provides utilities for understanding simulation behavior:

• phases: Detect regime changes in time-series data
• trace_analysis: Reconstruct event lifecycles from trace data
• report: Structured analysis output optimized for AI/LLM consumption

Phase dataclass

Phase(
    start_s: float,
    end_s: float,
    mean: float,
    std: float,
    label: str,
)

A detected phase/regime in the time series.

Anomaly dataclass

Anomaly(
    time_s: float,
    metric: str,
    description: str,
    severity: str,
    context: dict[str, Any] = dict(),
)

A detected anomaly with context for reasoning.

CausalChain dataclass

CausalChain(
    trigger_description: str,
    effects: list[str],
    duration_s: float,
)

A chain of causally-related observations.

MetricSummary dataclass

MetricSummary(
    name: str,
    count: int,
    mean: float,
    std: float,
    min: float,
    max: float,
    p50: float,
    p95: float,
    p99: float,
    by_phase: list[dict[str, Any]] = list(),
)

Pre-computed statistics for a named metric.

SimulationAnalysis dataclass

SimulationAnalysis(
    summary: SimulationSummary,
    phases: dict[str, list[Phase]] = dict(),
    metrics: dict[str, MetricSummary] = dict(),
    anomalies: list[Anomaly] = list(),
    causal_chains: list[CausalChain] = list(),
)

Structured analysis of a simulation run, designed for AI/LLM consumption.

to_prompt_context

to_prompt_context(max_tokens: int = 2000) -> str

Format as structured text for inclusion in an LLM prompt.

Automatically truncates/summarizes to fit within token budget. Prioritizes anomalies and phase transitions over steady-state data.

Parameters:

Name	Type	Description	Default
max_tokens	int	Approximate token budget (1 token ~= 4 chars).	2000

EventLifecycle dataclass

EventLifecycle(
    event_id: str,
    event_type: str | None = None,
    scheduled_at: Instant | None = None,
    dequeued_at: Instant | None = None,
    completed_at: Instant | None = None,
    child_event_ids: list[str] = list(),
)

Reconstructed lifecycle of a single event through the simulation.

wait_time property

wait_time: Duration | None

Time between scheduling and dequeue.

detect_phases

detect_phases(
    data: Data,
    *,
    window_s: float = 5.0,
    threshold: float = 2.0,
) -> list[Phase]

Detect phases where behavior changes significantly.

Uses a simple change-point detection approach: bucket the data into windows, compute per-window statistics, and identify transitions where the mean shifts by more than threshold standard deviations from the previous phase.

Parameters:

Name	Type	Description	Default
data	Data	Time-series data to analyze.	required
window_s	float	Window size for bucketing.	5.0
threshold	float	Number of standard deviations for a phase transition.	2.0

Returns:

Type	Description
list[Phase]	Ordered list of Phase objects with start/end times and summary
list[Phase]	statistics. Returns empty list if fewer than 2 windows of data.

analyze

analyze(
    summary: SimulationSummary,
    *,
    latency: Data | None = None,
    queue_depth: Data | None = None,
    throughput: Data | None = None,
    trace_recorder: InMemoryTraceRecorder | None = None,
    phase_window_s: float = 5.0,
    phase_threshold: float = 2.0,
    anomaly_threshold: float = 3.0,
    **named_metrics: Data,
) -> SimulationAnalysis

Run full analysis pipeline on simulation results.

Combines phase detection, anomaly detection, and causal chain extraction into a single structured result.

Parameters:

Name	Type	Description	Default
summary	SimulationSummary	SimulationSummary from Simulation.run().	required
latency	Data | None	Latency time-series data (e.g., from LatencyTracker.data).	None
queue_depth	Data | None	Queue depth time-series data (e.g., from Probe).	None
throughput	Data | None	Throughput time-series data (e.g., from ThroughputTracker.data).	None
trace_recorder	InMemoryTraceRecorder | None	Optional InMemoryTraceRecorder for causal analysis.	None
phase_window_s	float	Window size for phase detection.	5.0
phase_threshold	float	Sensitivity for phase transitions.	2.0
anomaly_threshold	float	Sensitivity for anomaly detection (std devs).	3.0
**named_metrics	Data	Additional named Data objects to analyze.	{}

Returns:

Type	Description
SimulationAnalysis	SimulationAnalysis with all detected patterns.

trace_event_lifecycle

trace_event_lifecycle(
    recorder: InMemoryTraceRecorder, event_id: str
) -> EventLifecycle | None

Reconstruct the full lifecycle of a single event from trace spans.

Parameters:

Name	Type	Description	Default
recorder	InMemoryTraceRecorder	The trace recorder that captured the simulation.	required
event_id	str	The event ID to look up.	required

Returns:

Type	Description
EventLifecycle | None	EventLifecycle with timing data, or None if event_id not found.