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

Measurement operators overview

Operator

Operation

Modifies the state?

MeasureZ

Projective Z-basis measurement (Born-rule sample + collapse)

Yes (collapses and renormalizes)

Reset

Active reset: measure, then force a definite classical value

Yes

Probability

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.

  1. distribution(state: pysparq._core.SparseState, register_id: typing.SupportsInt | typing.SupportsIndex) -> dict[int, float]

  2. 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)

pysparq.get_seed() → int

Return the current seed of the global random engine.

pysparq.reseed() → int

Reseed the global random engine from its own randomness and return the new seed.

pysparq.time_seed() → int

Seed the global random engine from the current wall-clock time and return the seed.

Use set_seed() instead when reproducibility is required.