Replays a Q2NS simulation event stream and exposes the quantum state. More...

Public Member Functions
	reset (self)
	Clear all loaded state.

	load_events (self, str\|Path\|list[dict[str, Any]] source)
	Ingest a trace and build the simulation timeline.

None	seek (self, int t_ns)
	Position the replay state at t_ns without packaging a `Snapshot`.

Snapshot	snapshot_at (self, int t_ns)
	Advance or restore the replay state to t_ns and return a `Snapshot`.

dict[str, list[str]]	get_entanglement_groups (self)
	Return all entanglement components as `{root: [members]}`.

dict[str, list[str]]	get_entangled_states (self)
	Return entanglement components with two or more qubits.

int	log_count_at (self, int t_ns)
	Return how many `traceText` events have a timestamp <= t_ns.

list[dict[str, Any]]	get_log_events (self, int t_ns)
	Return all `traceText` events with timestamp <= t_ns, in time order.

Public Attributes
	log_events

	t_max

	events

	events_by_type

	time_array

	qubits

	cbits

	ent_graph

	measured_qubits

	removed_qubits

	discarded_qubits

	removed_cbits

Detailed Description

Replays a Q2NS simulation event stream and exposes the quantum state.

Usage pattern::

sm = SimulationStateManager()
sm.load_events(parsed_events)
snap = sm.snapshot_at(t_ns)
groups = snap.entangled_states

Key invariants

snapshot_at(t_ns) returns an immutable Snapshot carrying all per-instant state; prefer its fields over the query helpers. The helpers reflect the state positioned by the most recent snapshot_at() call; calling them on a fresh instance returns empty results silently.
ent_graph is restored or advanced to the requested time on every snapshot_at() call. Do not cache pointers to its contents.
The class is not thread-safe; all calls must originate from the Qt main thread.

JSON event types handled

createNode, createChannel, createQubit, sendQubit, removeQubit, createCbit, sendCbit, removeCbit, entangle, measure, graphMeasure, sendPacket, traceText.

Definition at line 255 of file logic.py.

Member Function Documentation

◆ get_entangled_states()

dict[str, list[str]] q2nsviz.logic.SimulationStateManager.get_entangled_states ( self )

Return entanglement components with two or more qubits.

Traverses only the entanglement graph, so the cost scales with the number of live entanglement edges rather than with every qubit created so far (get_entanglement_groups() also enrolls singleton components and therefore scans the full qubit registry).

Returns: {root: members} for every component with two or more qubits; equal, as member sets, to filtering get_entanglement_groups() by len(members) >= 2.

Definition at line 1222 of file logic.py.

References q2nsviz.logic._StateSnapshot.ent_graph, q2nsviz.logic.Snapshot.ent_graph, q2nsviz.logic.SimulationStateManager.ent_graph, q2nsviz.logic._StateSnapshot.measured_qubits, q2nsviz.logic.Snapshot.measured_qubits, q2nsviz.logic.SimulationStateManager.measured_qubits, q2nsviz.logic._StateSnapshot.removed_qubits, q2nsviz.logic.Snapshot.removed_qubits, q2nsviz.logic.SimulationStateManager.removed_qubits, and q2nsviz.ui.canvas.NetworkCanvas.removed_qubits.

◆ get_entanglement_groups()

dict[str, list[str]] q2nsviz.logic.SimulationStateManager.get_entanglement_groups ( self )

Return all entanglement components as {root: [members]}.

Must be called after snapshot_at(t_ns) so that ent_graph and qubits reflect the desired simulation time.

Computes connected components of ent_graph via UnionFind, excluding measured and removed qubits. The result therefore correctly reflects graph-state measurements (X/Y/Z) and any bridge qubits whose removal splits the graph.

Returns: Dictionary mapping each component root label to the sorted list of qubit labels in that component.

Definition at line 1195 of file logic.py.

◆ get_log_events()

list[dict[str, Any]] q2nsviz.logic.SimulationStateManager.get_log_events	(		self,
		int	t_ns
	)

Return all traceText events with timestamp <= t_ns, in time order.

Parameters

t_ns	Cut-off time in nanoseconds.

Returns: List of event dicts with type == "traceText".

Definition at line 1256 of file logic.py.

References q2nsviz.logic.SimulationStateManager.log_count_at(), and q2nsviz.logic.SimulationStateManager.log_events.

Here is the call graph for this function:

◆ load_events()

q2nsviz.logic.SimulationStateManager.load_events	(		self,
		str \| Path \| list[dict[str, Any]]	source
	)

Ingest a trace and build the simulation timeline.

Accepts either an already-parsed event list or a path to a trace file; a path is parsed with EventFileParser first, with any parse errors logged as warnings. Processes createNode and createChannel events immediately; all other event types are deferred to snapshot_at(). Runs _validate_events() and logs any detected issues as warnings.

Parameters

source List of raw event dictionaries from EventFileParser, or the path of a JSON/NDJSON trace file to load.

Calls reset() before loading, so any previously loaded state is discarded. Each call to load_events() always starts from a clean slate.

Definition at line 342 of file logic.py.

References q2nsviz.logic.SimulationStateManager.reset(), q2nsviz.ui.canvas.NetworkCanvas.reset(), and q2nsviz.ui.window.PlaybackController.reset().

Here is the call graph for this function: