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

Hands-On: IonQ

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

Run on an IonQ trapped-ion system (Aria / Forte) with all-to-all connectivity — reachable directly or through Braket / Azure.

1 · Credentials

Get an API key from the IonQ cloud and export it: export QALGORA_IONQ_API_KEY="..." (or use AWS / Azure credentials if going through a broker).

2 · Validate locally, then submit (adapter workflow · planned)

import qalgora

@qalgora.kernel
def ghz(n: int):
    q = qalgora.qvector(n)
    h(q[0])
    for i in range(1, n):
        x.ctrl(q[0], q[i])
    mz(q)

qalgora.set_target("qpp-cpu")                                # reference implementation, local validation
print(qalgora.sample(ghz, 4, shots_count=1000))
Specification interface / planned · not in the open reference build
IonQ submission is an adapter/export workflow requiring the IonQ SDK and credentials (or AWS/Azure credentials through a broker), plus shots, cost, and queue handling. It is not part of the open CPU reference implementation. The lines below are commented out to show the intended shape.
# qalgora.set_target("ionq", machine="forte")              # planned adapter — needs vendor SDK + credentials
# job = qalgora.sample_async(ghz, 4, shots_count=1000)
# 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.

3 · Less routing — but still gate-set translation

Because every ion couples to every other, all-to-all connectivity reduces SWAP networks, so circuits stay shallow. Your two-qubit gates are still realized by compiling to IonQ's native gate set (the adapter handles gate-set translation, shots, cost, queue, and SDK auth). A GHZ chain that needs routing on a grid chip maps more directly here.

4 · Error mitigation

IonQ supports debiasing/symmetrization to average out coherent errors; request mitigation through the resilience level when computing expectation values:

e = qalgora.observe(ansatz, hamiltonian, theta, resilience_level=2).expectation()
Tips
IonQ reports usable scale as #AQ (algorithmic qubits), not raw count. Pick the smallest system that fits your circuit, and validate on qpp-cpu first — trapped-ion shots are slower than superconducting ones.

实操:IonQ

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

在 IonQ 离子阱系统(Aria / Forte)上运行电路,支持全连接拓扑 —— 可直接访问,也可通过 Braket / Azure 接入。

1 · 凭据配置

从 IonQ 云端获取 API 令牌并导出:export QALGORA_IONQ_API_KEY="..." (若通过中间平台接入,也可使用 AWS / Azure 凭据)。

2 · 本地验证,然后提交(适配器工作流·规划中)

import qalgora

@qalgora.kernel
def ghz(n: int):
    q = qalgora.qvector(n)
    h(q[0])
    for i in range(1, n):
        x.ctrl(q[0], q[i])
    mz(q)

qalgora.set_target("qpp-cpu")                                # 参考实现本地验证
print(qalgora.sample(ghz, 4, shots_count=1000))
规范接口/规划中 · 参考实现暂未包含
IonQ 提交属于适配器/导出工作流,需 IonQ SDK 与凭据(或经中间平台使用 AWS/Azure 凭据),并涉及采样次数、费用与排队处理;开源 CPU 参考实现暂未包含。下方代码已注释,仅示意预期形态。
# qalgora.set_target("ionq", machine="forte")              # 规划中 / 适配示意:需厂商 SDK 与凭据
# job = qalgora.sample_async(ghz, 4, shots_count=1000)
# print(job.get())                                         # 适配器 future;阻塞直到远程任务完成
参考实现仅本地运行 · 非真机
此示例虽指向远程云端/QPU,但开放参考实现不会真正提交到真机 —— 它会给出告警并回退到本地 CPU 态矢量模拟器,返回模拟结果,不会真正提交到天衍等真机。真正提交真机需使用对应厂商的 SDK 与凭证。
关于 job.get()
这是适配器层 job/future 的预期语义——它会阻塞直到远程任务完成;开放参考实现不会产生真实远程 job。

3 · 更少布线——但仍需门集编译

由于每个离子与其他所有离子都相互耦合,全连接拓扑可减少 SWAP 网络,电路深度保持浅层。你的双比特门仍需通过编译到 IonQ 原生门集来实现(适配器负责门集编译、采样次数、费用、排队与 SDK 鉴权)。在网格芯片上需要布线的 GHZ 链,在这里映射更直接。

4 · 纠错缓解

IonQ 支持去偏与对称化,以平均消除相干误差;在计算期望值时,通过韧性等级请求纠错缓解:

e = qalgora.observe(ansatz, hamiltonian, theta, resilience_level=2).expectation()
小贴士
IonQ 用 #AQ(算法量子比特)衡量可用规模,而非原始比特数。选择能容纳你电路的最小系统,并先在 qpp-cpu 上验证 —— 离子阱的采样速度比超导慢。