Mid-Circuit Measurement and Seeding¶
The measurement operators perform non-unitary operations on a SparseState: Born-rule sampling, active reset, and read-only probability queries. They are the building blocks for mid-circuit measurement, dynamic branching, and classical readout in quantum algorithms. Unlike the partial trace operators, which collapse registers to extract readout values, MeasureZ samples an outcome, Reset prepares a definite classical value, and Probability queries the outcome distribution without modifying the state.
All sampling operators draw from a seedable global random engine (see Seeding Functions), so runs can be made reproducible for testing.
Overview¶
Operator |
Operation |
Modifies the state? |
|---|---|---|
Projective Z-basis measurement (Born-rule sample + collapse) |
Yes (collapses and renormalizes) |
|
Active reset: measure, then force a definite classical value |
Yes |
|
Read-only probability of specific register values |
No |
Basic Usage¶
import pysparq as ps
ps.System.clear()
ps.System.add_register("q", ps.UnsignedInteger, 2)
state = ps.SparseState()
ps.Hadamard_Int("q", 2)(state) # uniform superposition over |0..3>
# Reproducible sampling
ps.set_seed(0)
outcome, prob = ps.MeasureZ("q")(state) # sample + collapse
print(outcome, prob)
# Active reset to a definite value (defaults to 0)
measured = ps.Reset("q", 3)(state) # force q = 3
# Read-only probability query
p = ps.Probability("q", 3)(state) # probability that q == 3
dist = ps.Probability.distribution(state, "q") # full outcome distribution
Because these operations are non-unitary, they provide no dag() and cannot be used inside conditional operations blocks that require reversibility.
API Reference¶
- class pysparq.MeasureZ¶
Projective Z-basis (computational basis) measurement.
Samples an outcome for one or more registers according to the Born rule, using the seedable global random engine (see set_seed()). Collapses the state onto the sampled branch and renormalizes it in place.
This operation is non-unitary and irreversible (no dag()).
Example
ps.set_seed(0) outcome, prob = ps.MeasureZ(“q”)(state)
- property registers¶
- class pysparq.Reset¶
Reset one or more registers to a definite classical value (default 0).
Implemented as measurement (collapse + renormalize) followed by a deterministic classical correction, matching hardware active-reset and OriginIR-ext RESET semantics. Returns the pre-reset measured outcome.
Example
ps.set_seed(0) measured = ps.Reset(“q”)(state) # reset “q” to 0 measured = ps.Reset(“q”, 3)(state) # reset “q” to 3
- property registers¶
- property target_values¶
- class pysparq.Probability¶
Read-only Born-rule probability query (does not modify the state).
Computes the probability that the given register(s) hold the given value(s). Useful for QIF/QWHILE-style dynamic branching conditions and for Born-rule conformance checks against a dense-state reference.
Example
p = ps.Probability(“q”, 5)(state) dist = ps.Probability.distribution(state, “q”) # full outcome distribution
- static distribution(*args, **kwargs)¶
Overloaded function.
distribution(state: pysparq._core.SparseState, register_id: typing.SupportsInt | typing.SupportsIndex) -> dict[int, float]
distribution(state: pysparq._core.SparseState, register_name: str) -> dict[int, float]
- property registers¶
- property values¶
Seeding Functions¶
The sampling operators (MeasureZ, Reset) and the partial trace operators share one global random engine. Seed it before sampling to make outcomes reproducible — this is required for deterministic replay and testing of dynamic executors.
- pysparq.set_seed(seed: SupportsInt | SupportsIndex) None¶
Seed the global random engine used by measurement/reset/PartialTrace.
Call before MeasureZ/Reset (or PartialTrace/PartialTraceSelect*) to make their sampled outcomes reproducible, which is required for deterministic replay/testing of a dynamic executor.
Example
ps.set_seed(12345) outcome, prob = ps.MeasureZ(‘q’)(state)