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

Hands-On: Amazon Braket

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

One AWS account reaches IonQ, IQM, Rigetti, and QuEra. This walkthrough submits a circuit to a Braket device and retrieves the results from S3.

1 · AWS setup

  1. Configure AWS credentials: aws configure (or an IAM role).
  2. Enable Amazon Braket in your account and note the device ARNs.

2 · Validate locally

Validate the kernel for free on the CPU reference implementation before touching any AWS resource:

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

3 · Submit via the Braket adapter (planned)

Specification interface / planned · not in the open reference build
Braket submission — to the managed simulators (SV1, DM1) or to a QPU — is an adapter/export workflow requiring AWS credentials, an S3 output path, the device's region, an in-window device availability, and cost confirmation. It is not part of the open CPU reference implementation. The lines below are commented out to show the intended shape; QPU ARNs are region-qualified, while the on-demand simulator ARNs are region-less (you pass the region separately). 
# Managed simulator (still a remote AWS task):
# qalgora.set_target("braket",
#                    machine="arn:aws:braket:::device/quantum-simulator/amazon/sv1",
#                    region="us-east-1")
# print(qalgora.sample(bell, shots_count=1000))

# QPU (region-qualified ARN; pick the device's region):
# qalgora.set_target("braket",
#                    machine="arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet",
#                    region="eu-north-1")
# job = qalgora.sample_async(bell, shots_count=1000)
# print(job.status())     # queued — devices have availability windows
# 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 · Mind credentials, region & cost

  • Requires configured AWS credentials, an S3 bucket for output, and the device's region.
  • Devices are pinned to regions (IQM in eu-north-1, IonQ in us-east-1).
  • You pay a per-shot fee plus a per-task fee — keep shot counts sensible and confirm cost first.
  • Some devices run only during posted availability windows; check before submitting.
Tips
Bring existing Braket SDK circuits via Braket interop, and use the Hybrid Jobs pattern: iterate on qpp-cpu, validate the final run through the adapter on hardware.

实战：Amazon Braket

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

一个 AWS 账户即可访问 IonQ、IQM、Rigetti 和 QuEra。本指南演示如何向 Braket 设备提交线路并从 S3 中取回结果。

1 · 配置 AWS 环境

  1. 配置 AWS 凭据：aws configure（或使用 IAM 角色）。
  2. 在账户中启用 Amazon Braket，并记录设备 ARN。

2 · 本地验证

在动用任何 AWS 资源前，先在 CPU 参考实现上免费验证内核：

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

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

规范接口/规划中 · 参考实现暂未包含
Braket 提交——无论是托管模拟器（SV1、DM1）还是 QPU——都属于适配器/导出工作流，需 AWS 凭据、S3 输出路径、设备所在区域、设备开放时段内的可用性以及费用确认；开源 CPU 参考实现暂未包含。下方代码已注释，仅示意预期形态；QPU 的 ARN 带区域限定，按需模拟器的 ARN 则不带（区域另行传入）。
# 托管模拟器（仍是远程 AWS 任务）：
# qalgora.set_target("braket",
#                    machine="arn:aws:braket:::device/quantum-simulator/amazon/sv1",
#                    region="us-east-1")
# print(qalgora.sample(bell, shots_count=1000))

# QPU（带区域限定的 ARN；请选设备所在区域）：
# qalgora.set_target("braket",
#                    machine="arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet",
#                    region="eu-north-1")
# job = qalgora.sample_async(bell, shots_count=1000)
# print(job.status())     # queued — devices have availability windows
# print(job.get())        # 适配器 future；阻塞直到远程任务完成
参考实现仅本地运行 · 非真机
此示例虽指向远程云端/QPU，但开放参考实现不会真正提交到真机 —— 它会给出告警并回退到本地 CPU 态矢量模拟器，返回模拟结果，不会真正提交到天衍等真机。真正提交真机需使用对应厂商的 SDK 与凭证。
关于 job.get()
这是适配器层 job/future 的预期语义——它会阻塞直到远程任务完成；开放参考实现不会产生真实远程 job。

4 · 注意凭据、区域与费用

  • 需配置好的 AWS 凭据、用于输出的 S3 桶以及设备所在区域。
  • 设备绑定特定区域（IQM 在 eu-north-1，IonQ 在 us-east-1）。
  • 费用由按次采样费与每任务费用两部分构成——请合理控制采样次数并先确认费用。
  • 部分设备仅在特定开放时段运行，提交前请提前确认。
小贴士
可通过 Braket 互操作导入现有 Braket SDK 线路，并采用混合作业模式：在 qpp-cpu 上迭代调试，最终经适配器在真机上提交验证。