线路中测量与随机种子

测量算子对 SparseState 执行**非幺正**操作:Born 规则采样、主动复位与只读概率查询。它们是量子算法中线路中测量、动态分支与经典读出的构建模块。与把寄存器坍缩以提取读出值的 部分追迹算子 不同,MeasureZ 采样一个测量结果,Reset 制备确定的经典值,Probability 在不修改量子态的情况下查询结果分布。

所有采样算子都从一个**可设种子的全局随机引擎**中抽取随机数(见 随机种子函数),因此可以让运行结果可复现,便于测试。

概述

测量算子总览

算子

操作

是否修改态

MeasureZ

Z 基投影测量(Born 规则采样 + 坍缩)

是(坍缩并重新归一化)

Reset

主动复位:先测量,再强制为确定的经典值

是

Probability

对指定寄存器值的只读概率查询

否

基本用法

import pysparq as ps

ps.System.clear()
ps.System.add_register("q", ps.UnsignedInteger, 2)
state = ps.SparseState()
ps.Hadamard_Int("q", 2)(state)   # |0..3> 上的均匀叠加

# 可复现采样
ps.set_seed(0)
outcome, prob = ps.MeasureZ("q")(state)      # 采样 + 坍缩
print(outcome, prob)

# 主动复位为确定值(默认为 0)
measured = ps.Reset("q", 3)(state)           # 强制 q = 3

# 只读概率查询
p = ps.Probability("q", 3)(state)            # q == 3 的概率
dist = ps.Probability.distribution(state, "q")  # 完整结果分布

由于这些操作是非幺正的,它们不提供 dag(),也不能用于要求可逆性的 条件操作 块中。

API 参考

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

示例

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.

示例

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.

示例

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

随机种子函数

采样算子(MeasureZ 与 Reset)与 部分追迹算子 共用同一个全局随机引擎。采样前先设置种子即可让结果可复现——动态执行器的确定性重放与测试都依赖这一点。

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.

示例

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.