qalgora-Q Docs Hub量子文档 ✦ Ask AI✦ 问问文档
/

Measuring & Sampling

Extract classical information from a quantum state.

Measurement bases

  • mz(q) — measure in the computational (Z) basis. This is the runnable measurement in the open reference build.
  • mx(q) / my(q) — measure in the X or Y basis.
mx / my via a basis change
Where mx / my are not native, an X- or Y-basis measurement is equivalent to a basis-change rotation before a Z-basis measurement: apply h before measuring to read the X basis (apply s.adj then h for the Y basis). 
@qalgora.kernel
def measure_x():
    q = qalgora.qvector(1)
    ry(0.5, q[0])          # ... some state preparation ...
    h(q[0]); mz(q[0])      # X-basis measurement == H then Z-basis measure

Sampling a circuit

counts = qalgora.sample(kernel, shots_count=2000)
for bits, n in counts.items():
    print(bits, n)
print("most probable:", counts.most_probable())
print("P(00):", counts.probability("00"))
⟨Z⟩ from counts is single-qubit by convention
counts.expectation() returns a Z-basis expectation, but for a multi-qubit register which parity/observable it implies is ambiguous. For anything beyond a single qubit prefer qalgora.observe with an explicit spin operator (below), which defines the observable unambiguously. Read the distribution directly with counts.most_probable() and counts.probability("00").

Measurement handles

Assign a measurement to a variable to tag it. You can then read that register's statistics separately from the full counts with get_marginal_counts.

规范接口·参考实现暂未包含 — handles, mid-circuit branch & marginals
Tagging a measurement handle, branching on it mid-circuit, and reading a register's marginal with get_marginal_counts are specification interfaces; the open reference build does not ship the marginal helper or this mid-circuit conditional form yet, so the snippet below is illustrative. 
@qalgora.kernel
def tagged():
    q = qalgora.qvector(2)
    h(q[0])
    aux = mz(q[0])         # a named measurement handle
    if aux:
        x(q[1])
    mz(q[1])

res = qalgora.sample(tagged)
print(res.get_marginal_counts([0]))   # marginal over qubit index 0 (the tagged qubit)
Specification API — not in the open reference build yet
This example shows a qalgora-Q specification API (or a third-party library) that the open reference build does not bundle today. It documents the intended interface; to run code now, use the reference build’s supported core API.

Mid-circuit measurement

Measuring partway through a kernel and branching on the result is its own topic — see Mid-Circuit Measurement and Dynamic Circuits.

Computing observables

For expectation values, prefer qalgora.observe with a spin operator over manual basis-change sampling — it handles the rotations and averaging for you:

from qalgora import spin

hamiltonian = spin.z(0) + 0.5 * spin.x(1)
result = qalgora.observe(kernel, hamiltonian)
print(result.expectation())

测量与采样

从量子态中提取经典信息。

测量基

  • mz(q) — 在计算基（Z 基）下测量。这是开放参考实现中可运行的测量。
  • mx(q) / my(q) — 在 X 基或 Y 基下测量。
mx / my 可由基变换实现
当 mx / my 非原生支持时，X 基或 Y 基测量可通过测量前的基变换加 Z 基测量等效实现：测量前先施加 h 即可读取 X 基（读取 Y 基则先 s.adj 再 h）。 
@qalgora.kernel
def measure_x():
    q = qalgora.qvector(1)
    ry(0.5, q[0])          # ... 某种态制备 ...
    h(q[0]); mz(q[0])      # X 基测量 == 先 H 再 Z 基测量

对线路采样

counts = qalgora.sample(kernel, shots_count=2000)
for bits, n in counts.items():
    print(bits, n)
print("most probable:", counts.most_probable())
print("P(00):", counts.probability("00"))
由 counts 得到的 ⟨Z⟩ 按约定是单比特量
counts.expectation() 返回的是 Z 基期望值，但对多比特寄存器而言，它所指的宇称/可观测量是有歧义的。超出单比特的场景，请优先使用带显式自旋算符的 qalgora.observe（见下），它能无歧义地定义可观测量。要直接读取分布，可用 counts.most_probable() 与 counts.probability("00")。

测量句柄

将测量赋值给变量即可为其添加标签，之后可通过 get_marginal_counts 单独读取该寄存器的统计结果，与完整计数分开查看。

规范接口·参考实现暂未包含 — 句柄、线路中分支与边缘分布
为测量打标签、在线路中根据其结果分支，以及用 get_marginal_counts 读取某寄存器的边缘分布，都属于规范接口；开放参考实现尚未内置该边缘分布辅助函数，也尚未支持此种线路中条件形式，故下面的片段仅作示意。 
@qalgora.kernel
def tagged():
    q = qalgora.qvector(2)
    h(q[0])
    aux = mz(q[0])         # a named measurement handle
    if aux:
        x(q[1])
    mz(q[1])

res = qalgora.sample(tagged)
print(res.get_marginal_counts([0]))   # 对量子比特索引 0（被打标签的比特）求边缘分布
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

线路中测量

在内核执行过程中进行测量并根据结果分支是一个独立主题——详见 线路中测量与动态线路。

计算可观测量

若要获取期望值，优先使用带自旋算符的 qalgora.observe，而非手动换基采样——它会自动处理旋转和平均：

from qalgora import spin

hamiltonian = spin.z(0) + 0.5 * spin.x(1)
result = qalgora.observe(kernel, hamiltonian)
print(result.expectation())