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

Migration Guide

◐ 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.

Moving an existing Qiskit, Cirq, or Braket project to qalgora-Q? For standard gate-model circuits, adapters can reduce the rewriting work; complex control flow, noise models, pulses, vendor-proprietary gates, and photonic tasks usually need manual adjustment. Follow these three steps, then consult the API map and gotchas below.

Step 1 — Install & import

# reference-build source is in private beta — request access, then from your checkout:
pip install ./runtime

Step 2 — Adapt your circuits

Adapters are planned interfaces: instead of rebuilding circuits, wrap an existing one with the matching from_* adapter.

import qalgora

# Planned adapter:
# kernel = qalgora.from_qiskit(qiskit_circuit)   # or from_cirq / from_braket / from_qasm
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.

Step 3 — Point at a target

qalgora.set_target("qpp-cpu")                   # local validation in the open reference implementation
# optional: requires the qalgora-gpu plugin (planned)
# qalgora.set_target("gpu")
counts = qalgora.sample(kernel, shots_count=1000)
# Planned hardware targets:
# qalgora.set_target("ibm", ...) / ("origin", ...)
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.

API map

TaskQiskitqalgora-Q
Allocate qubitsQuantumCircuit(n)qalgora.qvector(n)
Run & histogramSampler.run()qalgora.sample()
Expectation valueEstimator.run()qalgora.observe()
StatevectorStatevector(qc)qalgora.get_state()
Choose backendQiskitRuntimeServiceqalgora.set_target()
Variational loopqiskit_algorithms.VQEqalgora.vqe()

Common gotchas

  • Qubit ordering — bitstrings read most-significant-first in qalgora-Q; reverse if you compare against Qiskit's little-endian output.
  • Measurement — add explicit mz() in a kernel; there is no implicit measure-all unless you call it.
  • Gate names — cx → x.ctrl, ccx → x.ctrl([c1,c2], t), sdg → s.adj.
  • Parameters — kernel arguments are typed; annotate them (theta: float).

Migration checklist

  • ☐ Get a small kernel running first with the open reference implementation and qpp-cpu.
  • ☐ Wrap circuits with the matching from_* adapter.
  • ☐ Replace run/estimator calls with sample / observe.
  • ☐ If the GPU backend plugin is installed, validate larger workloads on the gpu target.
  • ☐ Before hardware, check the target gate set, coupling map, dynamic-circuit support, credentials, cost, and queue.
  • ☐ GBS, neutral-atom analog, and other non-gate-model tasks use dedicated APIs — not the ordinary gate-circuit adapter.
  • ☐ Swap set_target to your chosen QPU and re-run.
Incremental
Migrate one module at a time — adapters let qalgora-Q and your old SDK coexist in the same program during the transition.

迁移指南

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

想把现有的 Qiskit、Cirq 或 Braket 项目迁到 qalgora-Q？对标准门模型电路，适配器可减少重写工作；复杂控制流、噪声模型、脉冲、厂商专有门和光量子任务通常需要人工调整。按下面三步走，再对照 API 映射表和几个常见坑就行。

第一步 —— 安装与导入

# 参考实现源码处于私有 beta——申请访问后，在你的 checkout 中：
pip install ./runtime

第二步 —— 适配你的电路

适配器为规划接口：不必重新搭电路，用对应的 from_* 适配器把现有电路包一层即可。

import qalgora

# 规划中的适配器：
# kernel = qalgora.from_qiskit(qiskit_circuit)   # or from_cirq / from_braket / from_qasm
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

第三步 —— 指向目标后端

qalgora.set_target("qpp-cpu")                   # 在开放参考实现中本地验证
# 可选：需安装 qalgora-gpu 插件（规划中）
# qalgora.set_target("gpu")
counts = qalgora.sample(kernel, shots_count=1000)
# 规划中的真机目标：
# qalgora.set_target("ibm", ...) / ("origin", ...)
参考实现仅本地运行 · 非真机
此示例虽指向远程云端/QPU，但开放参考实现不会真正提交到真机 —— 它会给出告警并回退到本地 CPU 态矢量模拟器，返回模拟结果，不会真正提交到天衍等真机。真正提交真机需使用对应厂商的 SDK 与凭证。

API 映射

任务Qiskitqalgora-Q
分配量子比特QuantumCircuit(n)qalgora.qvector(n)
运行并统计直方图Sampler.run()qalgora.sample()
期望值Estimator.run()qalgora.observe()
态矢量Statevector(qc)qalgora.get_state()
选择后端QiskitRuntimeServiceqalgora.set_target()
变分循环qiskit_algorithms.VQEqalgora.vqe()

常见坑

  • 量子比特顺序 —— qalgora-Q 的比特串按高位在前读取；若要和 Qiskit 的小端序输出对比，需先反转。
  • 测量 —— 内核里要显式写 mz()；不调用就不会隐式全测。
  • 门名称 —— cx → x.ctrl，ccx → x.ctrl([c1,c2], t)，sdg → s.adj。
  • 参数 —— 内核参数需带类型标注（theta: float）。

迁移清单

  • ☐ 先用开放参考实现和 qpp-cpu 跑通小规模 kernel。
  • ☐ 用对应的 from_* 适配器包好电路。
  • ☐ 把 run/estimator 调用换成 sample / observe。
  • ☐ 如已安装 GPU 后端插件，再用 gpu 验证更大规模任务。
  • ☐ 上硬件前，检查目标门集、耦合图、动态线路支持、凭据、费用和队列。
  • ☐ GBS / 中性原子 analog 等非门模型任务用专用 API，不要普通门电路适配器。
  • ☐ 把 set_target 换成选定的 QPU 重新运行。
渐进迁移
一次迁一个模块就好——有了适配器，过渡期内 qalgora-Q 和你的旧 SDK 可以在同一个程序里共存。