Measurement and Readout¶

Mid-Circuit Measurement (`SparQ/include/measurement.h`)¶

Seedable measurement / reset / probability query interfaces for sparse states.

Provides first-class, reproducible (seedable) sparse-state operations for dynamic executors (mid-circuit MEASURE / RESET / QIF, etc.):

MeasureZ: projective Z-basis measurement, samples according to the Born rule, collapses and renormalizes;
Reset: post-measurement classically conditioned flip, forcibly resets a register to a given classical value;
Probability: read-only probability query (does not modify the state), used for condition evaluation in dynamic control flow such as QIF/QWHILE, as well as for conformance/compliance tests.

Randomness comes from the qram_simulator::random_engine singleton and can be explicitly seeded via random_engine::set_seed(), making the sampling results of MeasureZ/Reset reproducible (essential for deterministic replay and unit tests of the dynamic executor).

Input validation contract (jointly guaranteed by the constructors and operator()):

Every register name/ID must resolve to a register that is currently active in System; unknown names, out-of-range IDs, or IDs already removed by RemoveRegister all throw invalid_argument (ValueError on the Python side) at construction time.
The register list within a single constructor call must not contain duplicate IDs (e.g. MeasureZ({"a", "a"})); otherwise invalid_argument is thrown.
The target values of Reset and the comparison values of Probability must be representable by the bit width of the corresponding register (i.e. less than 2^size_of(id); unrestricted when size_of(id) == 64), otherwise invalid_argument is thrown – such contradictory targets/values were silently truncated in the old implementation and are part of what this hardening fix covers.
MeasureZ (and hence Reset) explicitly validates, before sampling, that the total probability of the input state (the sum of abs(amplitude)^2 over all branches) is finite and deviates from 1 by less than kNormalizationThreshold; otherwise it throws runtime_error (RuntimeError on the Python side), instead of directly comparing the random_engine::uniform01() sample against [0, 1) as the old implementation did – that would silently pile the surplus/deficient probability mass onto the last branch (the fallback branch) when the total probability deviates significantly from 1, producing biased sampling without reporting any error.

Warning

Arbitrary C++ operators produced by pysparq.dynamic_operator.compile_operator() undergo no unitarity proof; it merely runtime-compiles an operator()/dag() pair, and the compiler/binding layer will not (and cannot) statically or dynamically verify that the operator is actually unitary. The QCFD support path (QECC.Lang-driven qfvm/qnls/qham) forbids using compile_operator; all semantics must be expressed through named, testable built-in operators such as the ones in this file, and verified via the conformance test matrix provided by pysparq.conformance.

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

Variables

constexpr double kNormalizationThreshold = 1e-5¶

Normalization check threshold.

Before sampling, MeasureZ requires |sum(|amplitude|^2) - 1| < kNormalizationThreshold, consistent with the default threshold (1e-5) of CheckNormalization.

struct MeasureZ¶

#include <measurement.h>

Projective Z-basis measurement.

Performs a computational-basis (Z-basis) measurement on one or more registers:

Validates that the total probability of the input state is finite and approximately 1 (see the file-level documentation);
Samples one outcome among the basis-state branches according to the Born rule using random_engine::uniform01() (seedable via set_seed);
Removes branches inconsistent with the sampled outcome and renormalizes the remaining amplitudes;
Returns the sampled register values together with the probability of that outcome.

This operation is non-unitary and irreversible (measurement collapse), so no dag() is provided.

Public Functions

MeasureZ(const std::vector<std::string> &register_names)¶

Constructor (register name list version)

Throws:: invalid_argument – Name not found, or the list contains duplicate registers

MeasureZ(const std::vector<size_t> &register_ids)¶

Constructor (register ID list version)

Throws:: invalid_argument – ID out of range/inactive, or the list contains duplicate registers

MeasureZ(std::string_view register_name)¶: Constructor (single register name version)

MeasureZ(size_t register_id)¶: Constructor (single register ID version)

std::pair<std::vector<uint64_t>, double> operator()(std::vector<System> &state) const¶

Perform the measurement.

Parameters:

state – System state vector (collapsed and renormalized in place)

Throws:

invalid_argument – When the state is empty
runtime_error – When the total probability is non-finite or clearly deviates from 1 (see file-level documentation)

Returns:

{list of sampled register values, probability of that outcome}

inline std::pair<std::vector<uint64_t>, double> operator()(SparseState &state) const¶: SparseState version.

Public Members

std::vector<size_t> registers¶: List of register IDs to measure.

struct Probability¶

#include <measurement.h>

Read-only Born probability query.

Computes the probability of the event that the given registers take the given values, without modifying the state in any way. Used for QIF/QWHILE condition evaluation in dynamic executors, Born-rule verification in conformance tests, and estimating branch probabilities before actually measuring/resetting.

Public Functions

explicit Probability(const std::map<std::string_view, uint64_t> &assignments)¶

Constructor (name -> value map version)

Throws:: invalid_argument – Name not found, or a value exceeds the corresponding register’s bit width

explicit Probability(const std::map<size_t, uint64_t> &assignments)¶

Constructor (ID -> value map version)

Throws:: invalid_argument – ID out of range/inactive, or a value exceeds the corresponding register’s bit width

Probability(const std::vector<std::string> &register_names, const std::vector<uint64_t> &target_values)¶

Constructor (name list + value list version)

Throws:: invalid_argument – Name not found, duplicate registers, or a value exceeds the bit width

Probability(const std::vector<size_t> &register_ids, const std::vector<uint64_t> &target_values)¶

Constructor (ID list + value list version)

Throws:: invalid_argument – ID out of range/inactive, duplicate registers, or a value exceeds the bit width

Probability(std::string_view register_name, uint64_t value)¶

Constructor (single register name + value)

Throws:: invalid_argument – Name not found, or the value exceeds the register’s bit width

Probability(size_t register_id, uint64_t value)¶

Constructor (single register ID + value)

Throws:: invalid_argument – ID out of range/inactive, or the value exceeds the register’s bit width

double operator()(const std::vector<System> &state) const¶

Compute the probability of this assignment combination.

Parameters:: state – System state vector (read-only, not modified)
Returns:: Probability (in [0, 1]; returns 1 for an empty constraint)

inline double operator()(const SparseState &state) const¶: SparseState version.

Public Members

std::vector<size_t> registers¶: List of register IDs involved in the query.

std::vector<uint64_t> values¶: List of target values (one-to-one with registers)

Public Static Functions

static std::map<uint64_t, double> distribution(const std::vector<System> &state, size_t register_id)¶

Compute the full outcome distribution of a single register (read-only)

Parameters:

state – System state vector
register_id – Register ID

Throws:

invalid_argument – ID out of range/inactive

Returns:

Mapping from register values to probabilities

static inline std::map<uint64_t, double> distribution(const SparseState &state, size_t register_id)¶: SparseState version (by ID)

static std::map<uint64_t, double> distribution(const std::vector<System> &state, std::string_view register_name)¶: By-register-name version.

static inline std::map<uint64_t, double> distribution(const SparseState &state, std::string_view register_name)¶: SparseState version (by name)

struct Reset¶

#include <measurement.h>

Seedable RESET (measurement + classically conditioned flip)

Physically, resetting a register that may be in a superposition can only be done by “conditionally flipping according to the classical result after measurement” (matching active reset on real hardware and the semantics of the OriginIR-ext RESET instruction):

Perform one projective measurement (collapse + renormalize) on the target register with MeasureZ;
Since after the collapse the register’s value in all remaining branches equals the measurement outcome, directly overwriting it with the target value is equivalent to a classical bit flip on a definite value; it cannot merge illegally with other branches and is therefore well-defined.

The default target value is 0 (corresponding to RESET to |0>).

Public Functions

explicit Reset(const std::vector<std::string> &register_names)¶

Constructor (name list, all reset to 0 by default)

Throws:: invalid_argument – Name not found, or the list contains duplicate registers

Reset(const std::vector<std::string> &register_names, const std::vector<uint64_t> &targets)¶

Constructor (name list + target value list)

Throws:: invalid_argument – Name not found, duplicate registers, or a target value outside the range representable by the corresponding register’s bit width

explicit Reset(const std::vector<size_t> &register_ids)¶

Constructor (ID list, all reset to 0 by default)

Throws:: invalid_argument – ID out of range/inactive, or the list contains duplicate registers

Reset(const std::vector<size_t> &register_ids, const std::vector<uint64_t> &targets)¶

Constructor (ID list + target value list)

Throws:: invalid_argument – ID out of range/inactive, duplicate registers, or a target value outside the range representable by the corresponding register’s bit width

explicit Reset(std::string_view register_name, uint64_t target = 0)¶

Constructor (single register name + target value, default 0)

Throws:: invalid_argument – Name not found, or the target value exceeds the register’s bit width

explicit Reset(size_t register_id, uint64_t target = 0)¶

Constructor (single register ID + target value, default 0)

Throws:: invalid_argument – ID out of range/inactive, or the target value exceeds the register’s bit width

std::vector<uint64_t> operator()(std::vector<System> &state) const¶

Perform the reset.

Parameters:: state – System state vector (collapsed, renormalized, and overwritten with target values in place)
Returns:: List of register values measured before the reset (for diagnostics/logging)

inline std::vector<uint64_t> operator()(SparseState &state) const¶: SparseState version.

Public Members

std::vector<size_t> registers¶: List of register IDs to reset.

std::vector<uint64_t> target_values¶: List of reset target values (one-to-one with registers)

Partial Trace and Readout (`SparQ/include/partial_trace.h`)¶

Partial trace operation definitions.

Implements partial trace operations on quantum states, used for reduced density matrices and probability computation

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

struct PartialTrace¶

#include <partial_trace.h>

Partial trace operation class.

Performs the partial trace operation on the specified registers

Public Functions

PartialTrace(const std::vector<std::string> &partial_trace_register_names)¶

Constructor (name list version)

Parameters:: partial_trace_register_names – List of register names

PartialTrace(const std::vector<size_t> &partial_trace_register_names)¶

Constructor (ID list version)

Parameters:: partial_trace_register_names – List of register IDs

PartialTrace(std::string_view partial_trace_register_name)¶

Constructor (single name version)

Parameters:: partial_trace_register_name – Register name

PartialTrace(size_t partial_trace_register_name)¶

Constructor (single ID version)

Parameters:: partial_trace_register_name – Register ID

std::pair<std::vector<uint64_t>, double> operator()(std::vector<System> &state) const¶

Apply the partial trace operation.

Parameters:: state – System state vector
Returns:: List of values and probability after the partial trace

inline std::pair<std::vector<uint64_t>, double> operator()(SparseState &state) const¶

Apply the partial trace operation (sparse state version)

Parameters:: state – Sparse state
Returns:: List of values and probability after the partial trace

Public Members

std::vector<size_t> partial_trace_registers¶: List of partial trace register IDs.

struct PartialTraceSelect¶

#include <partial_trace.h>

Selective partial trace operation class.

Performs the partial trace operation on the specified registers and selects specific values

Public Functions

PartialTraceSelect(const std::map<std::string_view, uint64_t> &partial_traces)¶

Constructor (name-to-value map version)

Parameters:: partial_traces – Map from register names to values

PartialTraceSelect(const std::map<size_t, uint64_t> &partial_traces)¶

Constructor (ID-to-value map version)

Parameters:: partial_traces – Map from register IDs to values

PartialTraceSelect(const std::vector<std::string> &partial_trace_regs_, const std::vector<uint64_t> &select_values_)¶

Constructor (name list and value list version)

Parameters:

partial_trace_regs_ – List of register names
select_values_ – List of selected values

PartialTraceSelect(const std::vector<size_t> &partial_trace_regs_, const std::vector<uint64_t> &select_values_)¶

Constructor (ID list and value list version)

Parameters:

partial_trace_regs_ – List of register IDs
select_values_ – List of selected values

double operator()(std::vector<System> &state) const¶

Apply the selective partial trace operation.

Parameters:: state – System state vector
Returns:: Probability of the selected states

inline double operator()(SparseState &state) const¶

Apply the selective partial trace operation (sparse state version)

Parameters:: state – Sparse state
Returns:: Probability of the selected states

Public Members

std::vector<size_t> partial_trace_registers¶: List of partial trace register IDs.

std::vector<uint64_t> select_values¶: List of selected values.

struct PartialTraceSelectRange¶

#include <partial_trace.h>

Range-selective partial trace operation class.

Performs the partial trace operation on the specified register and selects a range of values

Public Functions

inline PartialTraceSelectRange(std::string_view partial_trace_register_, std::pair<size_t, size_t> select_range_)¶

Constructor (name version)

Parameters:

partial_trace_register_ – Register name
select_range_ – Selection range [min, max]

inline PartialTraceSelectRange(size_t partial_trace_register_, std::pair<size_t, size_t> select_range_)¶

Constructor (ID version)

Parameters:

partial_trace_register_ – Register ID
select_range_ – Selection range [min, max]

double operator()(std::vector<System> &state) const¶

Apply the range-selective partial trace operation.

Parameters:: state – System state vector
Returns:: Probability of the selected states

inline double operator()(SparseState &state) const¶

Apply the range-selective partial trace operation (sparse state version)

Parameters:: state – Sparse state
Returns:: Probability of the selected states

Public Members

size_t partial_trace_register¶: Partial trace register ID.

std::pair<size_t, size_t> select_range¶: Selection range.

double r = 0.0¶: Result probability.

Measurement and Readout¶

Mid-Circuit Measurement (SparQ/include/measurement.h)¶

Partial Trace and Readout (SparQ/include/partial_trace.h)¶

Mid-Circuit Measurement (`SparQ/include/measurement.h`)¶

Partial Trace and Readout (`SparQ/include/partial_trace.h`)¶