propaq.log_parser

Typed parsing of the JSON Lines event logs written by Logger.

See the logging and profiling guide.

log_parser

Parser for JSONL log files produced by the Logger class.

Propagation is Heisenberg-picture, so the engine walks

the circuit last-applied-gate-first. This index reflects that execution order, the reverse of the order the circuit

 was written in.

Classes:

Name	Description
LogParser	Parse a propaq JSONL log file into typed event lists.
GateEvent	Class representing a logged gate application event.
TruncationEvent	Class representing a logged truncation event (numerical propagators only).
SurrogateMergeEvent	Class representing a logged surrogate merge/truncation event.
EnginePhasesEvent	Class representing the closing per-run summary of the propagation engine.

LogParser

LogParser(filename: str)

Parse a propaq JSONL log file into typed event lists.

Build a LogParser for the given log file, reading all events into memory.

Methods:

Name	Description
reload	Re-read the log file, picking up any new events appended since construction.

Attributes:

Name	Type	Description
gate_events	list[GateEvent]	All gate events in file order.
truncation_events	list[TruncationEvent]	All truncation events in file order (numerical propagators only).
surrogate_merge_events	list[SurrogateMergeEvent]	All surrogate merge/truncation events in file order (surrogate propagators only).
engine_phases_events	list[EnginePhasesEvent]	The closing engine summary, one per run recorded in this file.
gate_indices	list[int]	Indices of gates at which events were logged.
terms	list[int]	Live term count sampled at each logged gate.
monomials	list[int | None]	Live monomial count sampled at each logged gate (surrogate propagators
terms_before	list[int]	Deduplicated term count before each truncation (numerical propagators only).
terms_after	list[int]	Term count after each truncation (numerical propagators only).
terms_gained	list[int]	New live-term keys created by branching at each gate (numerical propagators only).
terms_discarded	list[int]	Number of terms dropped at each truncation (numerical propagators only).
discarded_coeff_l1	list[float]	Sum of |coeff| discarded at each truncation (spectral weight lost).
discarded_coeff_max	list[float]	Largest |coeff| discarded at each truncation (worst-case information loss).
qiskit_gate_indices	list[int | None]	Qiskit gate index at each logged gate event, or None for non-Qiskit circuits.
ms_per_gate	list[float]	Wall time (ms) to apply each logged gate.
elapsed_ms	list[float]	Wall time (ms) for each truncation step (numerical propagators only).
monomials_before	list[int]	Exact total monomial count before each surrogate merge (surrogate propagators only).
monomials_after	list[int]	Exact total monomial count after each surrogate merge (surrogate propagators only).
monomials_discarded	list[int]	Number of monomials dropped at each surrogate merge (surrogate propagators only).

gate_events property

gate_events: list[GateEvent]

All gate events in file order.

truncation_events property

truncation_events: list[TruncationEvent]

All truncation events in file order (numerical propagators only).

surrogate_merge_events property

surrogate_merge_events: list[SurrogateMergeEvent]

All surrogate merge/truncation events in file order (surrogate propagators only).

engine_phases_events property

engine_phases_events: list[EnginePhasesEvent]

The closing engine summary, one per run recorded in this file.

gate_indices property

gate_indices: list[int]

Indices of gates at which events were logged.

terms property

terms: list[int]

Live term count sampled at each logged gate.

monomials property

monomials: list[int | None]

Live monomial count sampled at each logged gate (surrogate propagators only; None per entry for numerical propagators or old log files).

terms_before property

terms_before: list[int]

Deduplicated term count before each truncation (numerical propagators only).

terms_after property

terms_after: list[int]

Term count after each truncation (numerical propagators only).

terms_gained property

terms_gained: list[int]

New live-term keys created by branching at each gate (numerical propagators only).

terms_discarded property

terms_discarded: list[int]

Number of terms dropped at each truncation (numerical propagators only).

discarded_coeff_l1 property

discarded_coeff_l1: list[float]

Sum of |coeff| discarded at each truncation (spectral weight lost).

discarded_coeff_max property

discarded_coeff_max: list[float]

Largest |coeff| discarded at each truncation (worst-case information loss).

qiskit_gate_indices property

qiskit_gate_indices: list[int | None]

Qiskit gate index at each logged gate event, or None for non-Qiskit circuits.

ms_per_gate property

ms_per_gate: list[float]

Wall time (ms) to apply each logged gate.

elapsed_ms property

elapsed_ms: list[float]

Wall time (ms) for each truncation step (numerical propagators only).

monomials_before property

monomials_before: list[int]

Exact total monomial count before each surrogate merge (surrogate propagators only).

monomials_after property

monomials_after: list[int]

Exact total monomial count after each surrogate merge (surrogate propagators only).

monomials_discarded property

monomials_discarded: list[int]

Number of monomials dropped at each surrogate merge (surrogate propagators only).

reload

reload() -> None

Re-read the log file, picking up any new events appended since construction.

GateEvent dataclass

GateEvent(gate_idx: int, layer_idx: int, terms: int, ms_per_gate: float, qiskit_gate_idx: int | None, monomials: int | None)

Class representing a logged gate application event.

Attributes:

Name	Type	Description
gate_idx	int	Index of the gate in engine execution order, starting from 0.
layer_idx	int	Index of the layer in engine execution order, starting from 0.
terms	int	Live term count after this gate.
ms_per_gate	float	Wall time (ms) to apply this gate.
qiskit_gate_idx	int | None	Index of the originating Qiskit gate, or None for non-Qiskit circuits
monomials	int | None	Live monomial count (surrogate propagators only), or None for numerical propagators.

gate_idx instance-attribute

gate_idx: int

Index of the gate in engine execution order, starting from 0.

layer_idx instance-attribute

layer_idx: int

Index of the layer in engine execution order, starting from 0.

terms instance-attribute

terms: int

Live term count after this gate.

ms_per_gate instance-attribute

ms_per_gate: float

Wall time (ms) to apply this gate.

qiskit_gate_idx instance-attribute

qiskit_gate_idx: int | None

Index of the originating Qiskit gate, or None for non-Qiskit circuits or old log files.

monomials instance-attribute

monomials: int | None

Live monomial count (surrogate propagators only), or None for numerical propagators.

TruncationEvent dataclass

TruncationEvent(gate_idx: int, layer_idx: int, trigger: str, terms_before: int, terms_after: int, terms_gained: int, terms_discarded: int, discarded_coeff_l1: float, discarded_coeff_max: float, weight_cutoff: int | None, coeff_cutoff: float, elapsed_ms: float, qiskit_gate_idx: int | None)

Class representing a logged truncation event (numerical propagators only).

See SurrogateMergeEvent for the surrogate propagators' equivalent.

Attributes:

Name	Type	Description
gate_idx	int	Index of the gate at which truncation was triggered, in engine execution order.
layer_idx	int	Index of the layer at which truncation was triggered, in engine execution order.
trigger	str	Always "emit": the numerical propagators filter continuously at every
terms_before	int	Deduplicated term count before truncation.
terms_after	int	Term count after truncation.
terms_gained	int	New live-term keys created by branching this gate
terms_discarded	int	Branches the emit cutoff declined to form this gate.
discarded_coeff_l1	float	Sum of |coeff| discarded this gate
discarded_coeff_max	float	Largest |coeff| discarded this gate.
weight_cutoff	int | None	Weight cutoff used for truncation, if applicable.
coeff_cutoff	float	Coefficient cutoff used for truncation, if applicable.
elapsed_ms	float	Wall time (ms) for the full gate application
qiskit_gate_idx	int | None	Index of the originating Qiskit gate at time of truncation, or None

gate_idx instance-attribute

gate_idx: int

Index of the gate at which truncation was triggered, in engine execution order.

layer_idx instance-attribute

layer_idx: int

Index of the layer at which truncation was triggered, in engine execution order.

trigger instance-attribute

trigger: str

Always "emit": the numerical propagators filter continuously at every gate emission rather than via a periodic threshold-triggered pass.

terms_before instance-attribute

terms_before: int

Deduplicated term count before truncation.

terms_after instance-attribute

terms_after: int

Term count after truncation.

terms_gained instance-attribute

terms_gained: int

New live-term keys created by branching this gate

terms_discarded instance-attribute

terms_discarded: int

Branches the emit cutoff declined to form this gate.

discarded_coeff_l1 instance-attribute

discarded_coeff_l1: float

Sum of |coeff| discarded this gate

discarded_coeff_max instance-attribute

discarded_coeff_max: float

Largest |coeff| discarded this gate.

weight_cutoff instance-attribute

weight_cutoff: int | None

Weight cutoff used for truncation, if applicable.

coeff_cutoff instance-attribute

coeff_cutoff: float

Coefficient cutoff used for truncation, if applicable.

elapsed_ms instance-attribute

elapsed_ms: float

Wall time (ms) for the full gate application

qiskit_gate_idx instance-attribute

qiskit_gate_idx: int | None

Index of the originating Qiskit gate at time of truncation, or None for non-Qiskit circuits.

SurrogateMergeEvent dataclass

SurrogateMergeEvent(gate_idx: int, layer_idx: int, trigger: str, terms_before: int, terms_after: int, terms_discarded: int, monomials_before: int, monomials_after: int, monomials_discarded: int, frequency: int | None, weight: int | None, coefficient: float | None, elapsed_ms: float, qiskit_gate_idx: int | None)

Class representing a logged surrogate merge/truncation event.

Attributes:

Name	Type	Description
gate_idx	int	Index of the gate at which the merge was triggered, in engine execution order.
layer_idx	int	Index of the layer at which the merge was triggered, in engine execution order.
trigger	str	Always "emit": the surrogate build runs a truncation pass after every
terms_before	int	Deduplicated term count before truncation.
terms_after	int	Term count after truncation.
terms_discarded	int	terms_before - terms_after. See the class docstring: unlike
monomials_before	int	Exact total monomial count across all live coefficients before truncation.
monomials_after	int	Exact total monomial count across all live coefficients after truncation.
monomials_discarded	int	Number of monomials discarded.
frequency	int | None	FrequencyTruncator cutoff used, if applicable.
weight	int | None	WeightTruncator cutoff used, if applicable.
coefficient	float | None	CoefficientTruncator cutoff used, if applicable.
elapsed_ms	float	Wall time (ms) for the truncation pass alone (gate application timing
qiskit_gate_idx	int | None	Index of the originating Qiskit gate at time of the merge, or None

gate_idx instance-attribute

gate_idx: int

Index of the gate at which the merge was triggered, in engine execution order.

layer_idx instance-attribute

layer_idx: int

Index of the layer at which the merge was triggered, in engine execution order.

trigger instance-attribute

trigger: str

Always "emit": the surrogate build runs a truncation pass after every gate rather than via a periodic threshold-triggered merge.

terms_before instance-attribute

terms_before: int

Deduplicated term count before truncation.

terms_after instance-attribute

terms_after: int

Term count after truncation.

terms_discarded instance-attribute

terms_discarded: int

terms_before - terms_after. See the class docstring: unlike TruncationEvent.terms_discarded, this is a literal count difference, not a declined-branch count.

monomials_before instance-attribute

monomials_before: int

Exact total monomial count across all live coefficients before truncation.

monomials_after instance-attribute

monomials_after: int

Exact total monomial count across all live coefficients after truncation.

monomials_discarded instance-attribute

monomials_discarded: int

Number of monomials discarded.

frequency instance-attribute

frequency: int | None

FrequencyTruncator cutoff used, if applicable.

weight instance-attribute

weight: int | None

WeightTruncator cutoff used, if applicable.

coefficient instance-attribute

coefficient: float | None

CoefficientTruncator cutoff used, if applicable.

elapsed_ms instance-attribute

elapsed_ms: float

Wall time (ms) for the truncation pass alone (gate application timing is reported separately, on the corresponding GateEvent.ms_per_gate).

qiskit_gate_idx instance-attribute

qiskit_gate_idx: int | None

Index of the originating Qiskit gate at time of the merge, or None for non-Qiskit circuits.

EnginePhasesEvent dataclass

EnginePhasesEvent(partitions: int, scan_s: float, absorb_s: float, claims_s: float, scan_occupancy: float, absorb_occupancy: float, claims_occupancy: float, terms: int, inline_positions: int, overflow_rows: int, overflow_share: float, visited: int, emitted: int, declined: int, emitted_share: float, declined_share: float, exchange_hits: int, exchange_hit_share: float)

Class representing the closing per-run summary of the propagation engine.

Attributes:

Name	Type	Description
partitions	int	Hash partitions the run used, which is also its worker count.
scan_s	float	Wall seconds spent scanning rows and emitting branches.
absorb_s	float	Wall seconds spent absorbing the routing exchange.
claims_s	float	Wall seconds spent in the pair rule's rescue round.
scan_occupancy	float	Fraction of the pool busy during the scan phase, in [0, 1].
absorb_occupancy	float	Fraction of the pool busy during the absorb phase, in [0, 1].
claims_occupancy	float	Fraction of the pool busy during the pair rule's rescue round, in [0, 1].
terms	int	Live terms at the end of the run.
inline_positions	int	Inline key capacity per row the store settled on.
overflow_rows	int	Rows whose keys spilled past that capacity, costing a lookup per read.
overflow_share	float	overflow_rows as a fraction of terms.
visited	int	Rows the scan read across the run.
emitted	int	Branches the scan emitted.
declined	int	Branches the emit gate refused before forming them.
emitted_share	float	emitted as a fraction of visited.
declined_share	float	declined as a fraction of visited.
exchange_hits	int	Emitted branches that landed on a key the destination already held.
exchange_hit_share	float	exchange_hits as a fraction of emitted.

partitions instance-attribute

partitions: int

Hash partitions the run used, which is also its worker count.

scan_s instance-attribute

scan_s: float

Wall seconds spent scanning rows and emitting branches.

absorb_s instance-attribute

absorb_s: float

Wall seconds spent absorbing the routing exchange.

claims_s instance-attribute

claims_s: float

Wall seconds spent in the pair rule's rescue round.

scan_occupancy instance-attribute

scan_occupancy: float

Fraction of the pool busy during the scan phase, in [0, 1].

absorb_occupancy instance-attribute

absorb_occupancy: float

Fraction of the pool busy during the absorb phase, in [0, 1].

claims_occupancy instance-attribute

claims_occupancy: float

Fraction of the pool busy during the pair rule's rescue round, in [0, 1].

terms instance-attribute

terms: int

Live terms at the end of the run.

inline_positions instance-attribute

inline_positions: int

Inline key capacity per row the store settled on.

overflow_rows instance-attribute

overflow_rows: int

Rows whose keys spilled past that capacity, costing a lookup per read.

overflow_share instance-attribute

overflow_share: float

overflow_rows as a fraction of terms.

visited instance-attribute

visited: int

Rows the scan read across the run.

emitted instance-attribute

emitted: int

Branches the scan emitted.

declined instance-attribute

declined: int

Branches the emit gate refused before forming them.

emitted_share instance-attribute

emitted_share: float

emitted as a fraction of visited.

declined_share instance-attribute

declined_share: float

declined as a fraction of visited.

exchange_hits instance-attribute

exchange_hits: int

Emitted branches that landed on a key the destination already held.

exchange_hit_share instance-attribute

exchange_hit_share: float

exchange_hits as a fraction of emitted.