Executing Kernels
Each execution primitive has a synchronous and an asynchronous form, so you can overlap quantum submission with classical work.
The four primitives
| Call | Returns | Current status |
|---|---|---|
qalgora.sample(k) | A SampleResult of measured bitstrings | Reference build: available (参考实现已支持) |
qalgora.run(k) | A list of typed return values from the kernel | Spec interface — not yet bundled (规范接口·暂未实现) |
qalgora.observe(k, op) | An ObserveResult with expectation values | Reference build: available (参考实现已支持) |
qalgora.get_state(k) | The full simulated State | Reference build: available (参考实现已支持) |
Sample — measurement statistics
Returns a SampleResult. Inspect it with most_probable(),
count(bits), probability(bits), expectation(), or iterate
items(). Tag mid-circuit measurements to read them back separately.
counts = qalgora.sample(bell, shots_count=2000)
print(counts.most_probable(), counts.probability("11"))
for bits, n in counts.items():
print(bits, n)Run — typed return values
Unlike sample, run returns whatever the kernel returns, with its
declared type — booleans, ints, tuples, or custom dataclasses — one entry per shot.
qalgora.run is a documented specification interface; the open reference build does
not bundle it yet. Use sample / observe / get_state to run
code today.
@qalgora.kernel
def coin() -> bool:
q = qalgora.qubit(); h(q)
return mz(q)
flips = qalgora.run(coin, shots_count=20) # list[bool]
print("heads:", sum(flips))Observe — expectation values
import qalgora
from qalgora import spin
@qalgora.kernel
def ansatz(theta: float):
q = qalgora.qvector(2)
ry(theta, q[0])
x.ctrl(q[0], q[1])
res = qalgora.observe(ansatz, spin.z(0) * spin.z(1), 0.5)
print(res.expectation())Get state — raw amplitudes
Simulation only. Returns a State you can index, dump, or feed into another kernel.
state = qalgora.get_state(bell)
print(state) # raw amplitudes (index or dump the State)Asynchronous execution
sample_async and observe_async return a future — launch work without
blocking, then collect with .get(). Both are available in the reference build, so you
can overlap classical compute with simulation today. Fanning out across
multiple QPUs maps onto the planned multi-QPU backend (规划中).
sample_async and observe_async run today. run (and its
run_async form) is a spec interface (规范接口·暂未实现) and is not bundled yet.
f1 = qalgora.sample_async(bell, shots_count=10000)
f2 = qalgora.observe_async(ansatz, hamiltonian, theta)
# ... classical work proceeds here ...
counts = f1.get()
energy = f2.get().expectation()
# run also has an async form (run_async); run/run_async is a spec interface,
# not yet bundled in the reference build.执行内核
每种执行原语都有同步和异步两种形式，方便你一边提交量子任务，一边跑经典计算。
四种原语
| 调用 | 返回值 | 当前状态 |
|---|---|---|
qalgora.sample(k) | 包含已测量比特串的 SampleResult | 参考实现已支持 |
qalgora.run(k) | 内核返回值的有类型列表 | 规范接口·暂未实现 |
qalgora.observe(k, op) | 包含期望值的 ObserveResult | 参考实现已支持 |
qalgora.get_state(k) | 完整的模拟 State | 参考实现已支持 |
Sample — 测量统计
返回 SampleResult，用 most_probable()、
count(bits)、probability(bits)、expectation() 查看结果，也可以用
items() 逐项遍历。给线路里的测量打上标签，就能单独读取对应的结果。
counts = qalgora.sample(bell, shots_count=2000)
print(counts.most_probable(), counts.probability("11"))
for bits, n in counts.items():
print(bits, n)Run — 有类型返回值
和 sample 不同，run 直接返回内核本身的返回值，类型和声明的一致——布尔值、整数、元组或自定义数据类——每次采样对应一个条目。
qalgora.run 属于规范中的接口，开放参考实现目前尚未内置；如需立即运行，请使用
sample / observe / get_state。
@qalgora.kernel
def coin() -> bool:
q = qalgora.qubit(); h(q)
return mz(q)
flips = qalgora.run(coin, shots_count=20) # list[bool]
print("heads:", sum(flips))Observe — 期望值
import qalgora
from qalgora import spin
@qalgora.kernel
def ansatz(theta: float):
q = qalgora.qvector(2)
ry(theta, q[0])
x.ctrl(q[0], q[1])
res = qalgora.observe(ansatz, spin.z(0) * spin.z(1), 0.5)
print(res.expectation())Get state — 原始振幅
仅限模拟器。返回 State，可以索引、导出，或传给另一个内核。
state = qalgora.get_state(bell)
print(state) # 原始振幅（可索引或导出 State）异步执行
sample_async 和 observe_async 返回一个 future（异步句柄）——发起任务后不必阻塞等待，稍后用 .get() 取回结果。两者在参考实现中均已支持，现在就能一边跑模拟、一边跑经典计算。把任务扇出到多个 QPU 对应的是规划中的多 QPU 后端（规划中）。
sample_async 与 observe_async 现已可用；run（及其 run_async 形式）属于规范接口·暂未实现，尚未内置。
f1 = qalgora.sample_async(bell, shots_count=10000)
f2 = qalgora.observe_async(ansatz, hamiltonian, theta)
# ……此处继续进行经典计算……
counts = f1.get()
energy = f2.get().expectation()
# run 也有异步形式（run_async）；run/run_async 属于规范接口，参考实现尚未内置。