Core State Engine

Quantum network state engine: data types, replay logic, and trace parser. More...

Classes
class	q2nsviz.logic.Node
	A network node with a canvas-relative position. More...
class	q2nsviz.logic.Channel
	A directed communication link between two network nodes. More...
class	q2nsviz.logic.Qubit
	A qubit residing at a network node, tracked by label. More...
class	q2nsviz.logic.ClassicalBit
	A classical bit residing at a network node, tracked by label. More...
class	q2nsviz.logic.UnionFind
	Disjoint-set data structure with path compression and union by rank. More...
class	q2nsviz.logic.Snapshot
	Immutable view of the reconstructed network state at one instant. More...
class	q2nsviz.logic.SimulationStateManager
	Replays a Q2NS simulation event stream and exposes the quantum state. More...
class	q2nsviz.logic.EventFileParser
	Reads Q2NS simulation trace files in NDJSON or JSON-array format. More...

Functions
None	q2nsviz.logic.SimulationStateManager.seek (self, int t_ns)
	Position the replay state at t_ns without packaging a Snapshot.
Snapshot	q2nsviz.logic.SimulationStateManager.snapshot_at (self, int t_ns)
	Advance or restore the replay state to t_ns and return a Snapshot.

Detailed Description

Quantum network state engine: data types, replay logic, and trace parser.

Covers all symbols defined in q2nsviz/logic.py:

• q2nsviz.logic.Node, q2nsviz.logic.Channel, q2nsviz.logic.Qubit, q2nsviz.logic.ClassicalBit — lightweight dataclasses that mirror Q2NS network topology, qubit, and classical-bit state.
• q2nsviz.logic.UnionFind — disjoint-set structure used for computing entanglement components.
• q2nsviz.logic.Snapshot — immutable per-instant view of the reconstructed network state, returned by snapshot_at(t_ns) and dispatched by the controller to the views.
• q2nsviz.logic.SimulationStateManager — the central replay engine; ingests a trace (file path or parsed event list) and exposes the state via snapshot_at(t_ns) / seek(t_ns).
• q2nsviz.logic.EventFileParser — reads NDJSON and JSON-array trace files from disk.

Function Documentation

seek()

None q2nsviz.logic.SimulationStateManager.seek	(		self,
		int	t_ns
	)

Position the replay state at t_ns without packaging a Snapshot.

Moving forward in time continues incrementally from the last queried position; moving backward restores the nearest checkpoint at or before t_ns and replays the gap (at most _CHECKPOINT_INTERVAL actions after a restore). Valid for arbitrary timestamps, not only keyframes in time_array.

This is the O(advanced-actions) positioning primitive shared by snapshot_at(). Use it directly for bulk timeline scans where the O(#qubits) packaging cost of a full Snapshot per step would dominate, then read the query helpers (get_entangled_states() and friends) on the positioned state.

Parameters

t_ns	Simulation timestamp in nanoseconds.

Definition at line 902 of file logic.py.

References q2nsviz.logic.SimulationStateManager._actions, q2nsviz.logic.SimulationStateManager._apply_action(), q2nsviz.logic.SimulationStateManager._clear_replay_state(), q2nsviz.logic.SimulationStateManager._cursor, and q2nsviz.logic.SimulationStateManager._restore_snapshot().

Referenced by q2nsviz.logic.SimulationStateManager.snapshot_at().

Here is the call graph for this function:

Here is the caller graph for this function:

snapshot_at()

Snapshot q2nsviz.logic.SimulationStateManager.snapshot_at	(		self,
		int	t_ns
	)

Advance or restore the replay state to t_ns and return a Snapshot.

Positions the state via seek() and packages it as an immutable Snapshot. This is the per-instant entry point used by the QuantumVisualizerWindow controller and by scripts.

_snapshot_at_uncached() is retained as the from-scratch reference implementation and produces identical results for chronologically consistent traces.

Parameters

t_ns	Simulation timestamp in nanoseconds.

Returns

Snapshot of the reconstructed state at t_ns.

Definition at line 937 of file logic.py.

References q2nsviz.logic.SimulationStateManager._cursor, q2nsviz.logic.SimulationStateManager._ent_graph_add_edge(), q2nsviz.logic.SimulationStateManager._ent_graph_local_complement(), q2nsviz.logic.SimulationStateManager._ent_graph_remove_vertex(), q2nsviz.logic.SimulationStateManager._make_snapshot(), q2nsviz.logic.SimulationStateManager._perform_graph_measurement(), q2nsviz.logic.SimulationStateManager._win_gate, q2nsviz.logic.SimulationStateManager._win_graph_measuring, q2nsviz.logic.SimulationStateManager._win_inflight_cbits, q2nsviz.logic.SimulationStateManager._win_inflight_qubits, q2nsviz.logic.SimulationStateManager._win_measuring, q2nsviz.logic._StateSnapshot.cbits, q2nsviz.logic.Snapshot.cbits, q2nsviz.logic.SimulationStateManager.cbits, q2nsviz.logic._StateSnapshot.discarded_qubits, q2nsviz.logic.Snapshot.discarded_qubits, q2nsviz.logic.SimulationStateManager.discarded_qubits, q2nsviz.logic._StateSnapshot.ent_graph, q2nsviz.logic.Snapshot.ent_graph, q2nsviz.logic.SimulationStateManager.ent_graph, q2nsviz.logic.SimulationStateManager.events, q2nsviz.logic._StateSnapshot.measured_qubits, q2nsviz.logic.Snapshot.measured_qubits, q2nsviz.logic.SimulationStateManager.measured_qubits, q2nsviz.logic._StateSnapshot.qubits, q2nsviz.logic.Snapshot.qubits, q2nsviz.logic.SimulationStateManager.qubits, q2nsviz.logic._StateSnapshot.removed_cbits, q2nsviz.logic.Snapshot.removed_cbits, q2nsviz.logic.SimulationStateManager.removed_cbits, q2nsviz.ui.canvas.NetworkCanvas.removed_cbits, q2nsviz.logic._StateSnapshot.removed_qubits, q2nsviz.logic.Snapshot.removed_qubits, q2nsviz.logic.SimulationStateManager.removed_qubits, q2nsviz.ui.canvas.NetworkCanvas.removed_qubits, and q2nsviz.logic.SimulationStateManager.seek().

Here is the call graph for this function: