# 设备能力与设备选项

想知道一台机器能运行什么线路，先读设备能力；想设置这次任务怎样执行，再读设备选项。例如，门集与连接关系告诉你可以在哪些比特上编译，configuration_schema 告诉你 mapping 等配置怎么填写。本页解释共同概念，三个客户端专章给出可直接使用的查询代码。

## 先选择你使用的客户端

使用 Qiskit 或 PennyLane 编写线路时，选择对应插件；已有 OpenQASM 文件时，选择 Core SDK。SDK 和平台负责线路格式转换，下表列出各入口的能力查询和配置方法。

| 入口 | 用户编写的输入 | 当前上传格式 | 设备能力入口 | 设备配置入口 |
| --- | --- | --- | --- | --- |
| Qiskit 插件 | QuantumCircuit；Sampler / Estimator 的 PUB | 插件自动导出 OpenQASM 2 或 3 | backend.capabilities；backend.target；backend.configuration_schema | backend.set_options；单次 configuration_data；设备声明的动态关键字 |
| PennyLane 插件 | QNode / QuantumScript | 插件预处理测量后导出逻辑 OpenQASM 2 | dev.provider_capabilities；schema 经 SchedulerClient 查询 | 创建设备时的 configuration_data |
| Core SDK | OpenQASM 文件或 UTF-8 bytes | OpenQASM 2 或 3 | get_backend_class 返回设备模型；capabilities_from_backend / get_capabilities 解析能力 | JobSubmissionConfig.configuration_data |

- [Qiskit：设备详情、Options、Target 和物理布局](capabilities-qiskit.html)
- [PennyLane：平台能力、插件能力和设备配置](capabilities-pennylane.html)
- [Core：设备模型、配置 Schema 与 OpenQASM 提交](capabilities-core.html)

## 每一种查询结果解决什么问题

| 数据 | 回答的问题 | 怎样使用 |
| --- | --- | --- |
| 设备目录与状态 | 设备的 short_code、类型、规模和当前状态 | 选择账号可用的目标设备 |
| BackendCapabilities | 门、可用比特、连接、时长、误差和功能声明 | 规划线路和物理布局；可选字段为空时显示“未提供” |
| configuration_schema | 设备选项的名称、类型、允许值和默认值 | 将所选参数填写到客户端的设备配置入口 |
| 框架侧对象 | Qiskit Target 或 PennyLane 插件支持的编译与测量表示 | 交给框架编译器，或用于选择合适的线路写法 |

门集和连接关系用于了解硬件；设备选项用于调整实验的执行方式。本源真机提供的 mapping、optimization、amend 等布尔选项，可以在选定设备后通过 configuration_schema 查询和设置。

## 读懂 configuration_schema

每个专章都给出了读取 properties 的代码。找到要设置的字段后，查看它的类型、允许值、默认值和用途，再将所选值填入配置。下表说明各字段的读法。

| 字段 | 阅读方法 |
| --- | --- |
| properties | 字典中的键才是当前声明的选项；空字典表示当前响应未公开可调设备选项 |
| type | boolean 使用 Python True / False；其他类型按声明填写 |
| enum / const | enum 给出允许值集合；const 指定固定值 |
| default | 服务端声明的默认值。Qiskit 是否把字段放入 Options，还取决于插件实现；详见 Qiskit 专章 |
| minimum / maximum | 字段允许的数值范围 |
| description / title | 字段的用途说明或显示名称 |

本源逻辑线路可通过云端拓扑映射适配设备连接关系；Qiskit 固定物理布局使用 mapping=False、optimization=False，保持已编译的位置和线路。三个客户端专章分别展示具体写法。

## 读取时长、误差与功能信息

三个客户端都从平台读取统一的设备能力。平台整理厂商提供的硬件数据，SDK 将其呈现为 timing、noise、features 和 topology 等字段；显示已有对象时复用已读取的数据。

| 字段 | 当前本源 Adapter 的处理 | 用户解读 |
| --- | --- | --- |
| timing.durations | 从可读取的门时长整理，纳秒转换为秒 | 查看已提供门及比特位置的执行时长 |
| timing.dt | 采样周期；当前本源目录返回 None | None 表示当前未提供采样周期 |
| noise.gate_error | 可用保真度按 1 − fidelity 转为误差字段 | 了解平台记录的门误差估计 |
| features | 按测量流程和设备声明整理，如 measurement、barrier、reset | 结合所用插件的操作支持选择线路写法 |
| topology | 整理可用比特与连接关系 | 选择物理布局时同时查看连接关系和门的可用位置 |

可选信息以设备返回的数据为准。空字段显示为“当前未提供”；查询时间记录本次读取时间，校准时间使用设备明确提供的时间。各专章同时展示平台能力和框架视图，方便按需查看。

## 逻辑编号与物理编号要分别理解

| 写法 | 含义 |
| --- | --- |
| Qiskit：QuantumCircuit(2) 的 0、1 | 默认是两个逻辑比特；需要物理布局时使用该插件公开的 physical_qubits / initial_layout |
| PennyLane：wires=["a", "b"] | 两条逻辑 wire 的标签；插件生成连续逻辑编号，再交给厂商完成拓扑映射 |
| Core：qreg q[12]、h q[1] | OpenQASM 寄存器索引；物理程序还需按 Core 物理输入约定声明其表示方式 |

需要使用指定的一组物理比特时，使用 Qiskit 的 physical_qubits 或 initial_layout 布局入口。PennyLane 工作流提交逻辑线路，由云端拓扑映射将线路适配到设备连接关系。

## 查询时机、缓存和权限

Core 调用 get_backend_class / get_capabilities 可重新读取平台目录。Qiskit backend 和 PennyLane dev 会缓存各自的能力对象；需要按新数据准备实验时，创建新的框架对象。平台目录按服务端刷新策略更新。已有实验继续使用原准备对象查询结果。

能力查询用于读取设备信息。prepare 会上传线路、检查本次配置并生成报价；查看报价后，通过 confirm 执行实验。

## API 参考

设备能力对象的属性、查询方法和返回类型集中收录在 API 参考中；接口实现与测试依据可在同一文档中查阅。

- [BackendCapabilities 与能力查询](api.html#capabilities)
- [接口实现与测试依据](api.html#evidence)

- [开始阅读 Qiskit 专章](capabilities-qiskit.html)
- [开始阅读 PennyLane 专章](capabilities-pennylane.html)
- [开始阅读 Core 专章](capabilities-core.html)

## 下载本页 Jupyter Notebook

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

[下载《设备能力概念》Notebook（.ipynb）](../../notebooks/sdk_user_guide_capabilities.ipynb)