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

Hands-On: IBM Quantum

◐ Design-level API
This page documents qalgora-Q API design, architecture, or adaptation workflows. Code examples illustrate intended usage and are not guaranteed to run in the current reference implementation.

Prepare an IBM workflow framed as a Qiskit Runtime adapter — not native qalgora-Q submission. The open qalgora-Q reference build runs locally and does not submit directly; real execution requires a configured Qiskit Runtime account/service and an IBM Quantum account (the Open plan gives free monthly time).

1 · Get a token

  1. Create a free account at the IBM Quantum platform.
  2. Copy your API token from the dashboard.
  3. Export it: export QALGORA_IBM_TOKEN="..." (note: real execution still needs a configured Qiskit Runtime service).

2 · Validate locally

import qalgora

@qalgora.kernel
def bell():
    q = qalgora.qvector(2)
    h(q[0]); x.ctrl(q[0], q[1]); mz(q)

qalgora.set_target("qpp-cpu")                                # reference implementation, local validation
print(qalgora.sample(bell, shots_count=1000))

3 · Submit via the Qiskit Runtime adapter (planned)

Specification interface / planned · not in the open reference build
Submission to IBM hardware is a Qiskit Runtime adapter workflow: it requires a configured Qiskit Runtime account/service and credentials, and is not part of the open CPU reference implementation. The lines below are commented out to show the intended shape. 
# qalgora.set_target("ibm", machine="<ibm_backend_name>")   # planned adapter — needs Qiskit Runtime SDK + credentials
# job = qalgora.sample_async(bell, shots_count=4000)
# print(job.status())
# print(job.get())                                          # adapter future; blocks until the remote job finishes
Reference build runs locally — not real hardware
This example targets a remote cloud/QPU, but the open reference build does not submit to a real machine — it warns and falls back to the local CPU statevector simulator, returning simulated results. Submitting to an actual device (e.g. 天衍/TianYan, IBM, IonQ, Origin) requires the vendor’s own SDK and credentials.
On job.get()
This is the intended semantics of the adapter layer's job/future — it blocks until the remote job finishes. The open reference implementation does not produce a real remote job.

4 · Inspect the transpiled circuit (specification interface)

IBM chips are heavy-hex, so two-qubit gates may need SWAPs. The transpile check below is a specification interface; check the compiled depth before you spend a long queue:

compiled = qalgora.transpile(bell, optimization_level=3)   # 规范接口 / specification interface
print("depth:", compiled.depth(), " 2q-gates:", compiled.num_two_qubit_gates())
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.

5 · Variational loop in a session (adapter workflow · planned)

For VQE/QAOA, the adapter would open a session so iterations share a low-latency window. This is a planned adapter workflow (Qiskit Runtime session); shown commented out:

# with qalgora.Session(target="ibm", machine="<ibm_backend_name>"):   # planned adapter — Qiskit Runtime session
#     energy, params = qalgora.vqe(ansatz, hamiltonian, optimizer, parameter_count=n)
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.
Tips
Already on Qiskit? Bring circuits via Qiskit interop. Use resilience_level= on observe for error mitigation, and prefer the Open plan's smaller systems while debugging.

实操：IBM Quantum

◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。

把 IBM 工作流视作一个 Qiskit Runtime 适配器，而非 qalgora-Q 原生提交。开放的 qalgora-Q 参考实现在本地运行、不会直接提交；真机执行需要配置好的 Qiskit Runtime 账号/服务与 IBM Quantum 账号（Open 计划提供每月免费额度）。

1 · 获取令牌

  1. 在 IBM Quantum 平台注册免费账号。
  2. 从控制台复制你的 API 令牌。
  3. 导出令牌：export QALGORA_IBM_TOKEN="..."（注意：真机执行仍需配置好的 Qiskit Runtime 服务）。

2 · 本地验证

import qalgora

@qalgora.kernel
def bell():
    q = qalgora.qvector(2)
    h(q[0]); x.ctrl(q[0], q[1]); mz(q)

qalgora.set_target("qpp-cpu")                                # 参考实现本地验证
print(qalgora.sample(bell, shots_count=1000))

3 · 经 Qiskit Runtime 适配器提交（规划中）

规范接口/规划中 · 参考实现暂未包含
提交到 IBM 真机是 Qiskit Runtime 适配器工作流：需配置好的 Qiskit Runtime 账号/服务与凭据，开源 CPU 参考实现暂未包含。下方代码已注释，仅示意预期形态。
# qalgora.set_target("ibm", machine="<ibm_backend_name>")   # 规划中 / 适配示意：需 Qiskit Runtime SDK 与凭据
# job = qalgora.sample_async(bell, shots_count=4000)
# print(job.status())
# print(job.get())                                          # 适配器 future；阻塞直到远程任务完成
参考实现仅本地运行 · 非真机
此示例虽指向远程云端/QPU，但开放参考实现不会真正提交到真机 —— 它会给出告警并回退到本地 CPU 态矢量模拟器，返回模拟结果，不会真正提交到天衍等真机。真正提交真机需使用对应厂商的 SDK 与凭证。
关于 job.get()
这是适配器层 job/future 的预期语义——它会阻塞直到远程任务完成；开放参考实现不会产生真实远程 job。

4 · 查看转译后的电路（规范接口）

IBM 芯片采用重六边形拓扑，双比特门可能需要 SWAP 布线。下方的转译检查属于规范接口；在进入漫长排队前，先检查编译后的深度：

compiled = qalgora.transpile(bell, optimization_level=3)   # 规范接口
print("depth:", compiled.depth(), " 2q-gates:", compiled.num_two_qubit_gates())
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

5 · 在会话中运行变分循环（适配器工作流·规划中）

对于 VQE/QAOA，适配器会开启会话让每次迭代共享低延迟窗口。这是规划中的适配器工作流（Qiskit Runtime 会话），以下代码已注释：

# with qalgora.Session(target="ibm", machine="<ibm_backend_name>"):   # 规划中适配器 — Qiskit Runtime 会话
#     energy, params = qalgora.vqe(ansatz, hamiltonian, optimizer, parameter_count=n)
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。
小贴士
已在用 Qiskit？通过 Qiskit 互操作 直接导入电路。在 observe 上设置 resilience_level= 可开启纠错缓解；调试阶段优先使用 Open plan 的小规模系统。