# QuantumFerry SDK 用户手册

通过 Python 连接 QuantumFerry，选择设备、提交量子线路并读取结果。你可以直接上传 OpenQASM，也可以使用熟悉的 Qiskit 或 PennyLane；SDK 负责连接平台、准备报价和管理任务。

## 选择适合你的入口

| 你已经在使用什么 | 从哪里开始 | SDK 为你完成什么 |
| --- | --- | --- |
| OpenQASM 文件或字符串 | Core SDK | 上传程序、准备报价、确认执行、查询任务和下载统一结果。 |
| Qiskit QuantumCircuit | Qiskit 插件 | 提供 BackendV2、Target 及 Sampler / Estimator，导出线路并返回 Qiskit 结果。 |
| PennyLane QNode / QuantumScript | PennyLane 插件 | 注册 quantum_source.device，预处理线路和测量，再还原 PennyLane 返回值。 |

- [Core 入门与示例](core.html)
- [Qiskit 入门与示例](qiskit.html)
- [PennyLane 入门与示例](pennylane.html)

## 第一次使用：三步开始

1. 安装：在 Python 3.12 环境安装 SDK 及所需框架扩展。2. 认证：配置平台地址和平台 SDK Key。3. 运行：用快速开始中的 Bell 线路完成第一次报价、提交与结果读取。各教程在代码前说明本步要做什么，在代码后解释关键参数与返回对象。

- [第 1 步 · 安装 SDK](install.html)
- [第 2 步 · 连接与认证](connection.html)
- [第 3 步 · 快速开始](quickstart.html)

## 几个常用对象分别负责什么

| 对象 | 职责 | 你会使用它的时机 |
| --- | --- | --- |
| SchedulerClient | 平台任务客户端 | 使用 Core，或需要查询原提交、任务和结果时。 |
| ManagementClient / scheduler.management | 平台目录客户端 | 列出设备、厂商和自己可用的组织时。 |
| QuantumSourceService | Qiskit 服务入口 | 发现设备并获得可运行 QuantumCircuit 的 backend 时。 |
| quantum_source.device | PennyLane 设备 | 把 QNode 交给平台执行时。 |
| prepared | 本次准备对象 | 审阅 quote，确认同一次实验，以及查询原提交时。 |

## 理解一次任务的基本流程

选择设备 → 构造线路 → prepare → 查看 quote → confirm → 读取结果。prepare 会上传线路并取得报价，confirm 才确认执行。Qiskit backend.run 和 Core submit_job 等便捷入口默认自动批准报价，适合已经接受这种执行方式的脚本；真机调用仍会实际消耗资源。

- [任务提交：参数、报价和返回对象](job-submission.html)
- [设备发现：列表、筛选与平台任务数](backend-discovery.html)

## 查询与使用设备专属功能

Qiskit 使用 schema、Options 和 Target；PennyLane 使用 provider_capabilities 与设备 configuration_data；Core 使用设备模型与 JobSubmissionConfig。需要 mapping、门集或物理连接时，阅读你正在使用的客户端专章。

- [Qiskit：设备、Options 与 Target](capabilities-qiskit.html)
- [PennyLane：设备选项与支持范围](capabilities-pennylane.html)
- [Core：设备模型与配置字典](capabilities-core.html)

## 当前平台的执行与计费约定

当前平台只支持 public + stand 单通道。SDK 默认使用 OPEN；需要 FULL 时，在创建 QuantumSourceService、SchedulerClient 或独立 PennyLane 设备时传 currency="FULL"。金额和币种在 prepare 时由服务端报价固定；OPEN 和 FULL 独立扣费，各自使用对应钱包的余额。历史记录按原通道、原报价和原币种展示。

设备的 platform_active_tasks 是该设备在我们平台的未结束任务总数。等待超时后，可以继续查询同一个任务并读取结果。

Core 的 timeout、interval 与 verbose 控制单次状态查询；Qiskit Backend 提供结果等待和进度显示设置。省略这些选项即可使用默认设置。

- [Core：timeout、interval 与 verbose](core.html#wait-options)
- [Qiskit：结果等待与进度设置](qiskit.html#wait-options)

## 按问题继续阅读

| 你要做的事 | 推荐阅读顺序 |
| --- | --- |
| 从程序到测量结果 | 快速开始 → 任务提交与报价 → 任务查询与分页。 |
| 使用芯片专属设置 | 设备发现 → 你使用的框架能力专章。 |
| Qiskit 估计期望值或采样 | Qiskit 入门 → Sampler 与 Estimator；固定物理位置另看编译与物理布局。 |
| PennyLane 概率、期望值或梯度 | PennyLane 入门 → 测量、shots 与梯度。 |
| 维护平台集成 | 底层提交协议 → 任务查询。 |

- [查询、分页与结果下载](job-query.html)
- [Qiskit Sampler / Estimator](qiskit-primitives.html)
- [PennyLane 测量与梯度](pennylane-measurements.html)
- [底层提交协议](low-level.html)

## 示例与参考

- [下载逐页 Notebook 与完整实验](testing.html)
- [固定物理布局](compilation.html)
- [结果与常见问题](results.html)
- [常用 API](api.html)
- [版本与验证范围](versions.html)

## 下载本页 Jupyter Notebook

收录本页 Python 示例与说明，便于在 Jupyter Notebook 中学习和运行；安装命令保留为说明。

[下载《SDK 概览》Notebook（.ipynb）](../../notebooks/sdk_user_guide_index.ipynb)