Core SDK:发现设备与配置任务
用 Core SDK 列出设备、查询门集和连接关系,并为自己的 OpenQASM 程序设置设备选项。本章从查找设备开始,最后准备一条 Bell 线路的报价。
Core SDK 通过 Python 管理任务,上传的线路使用 OpenQASM。你可以沿章节逐步查询,也可以直接使用后面的完整示例。prepare_submission 完成上传和报价,确认执行的流程见 Core 主教程。
| 你想完成的操作 | 使用的入口 | 得到的内容 |
|---|---|---|
| 找到设备标识 | list_backends(scheduler=scheduler) | 可用于后续选择的 short_code 列表 |
| 查看某台设备及可选配置 | scheduler.get_backend_class(backend_code) | BackendClassRead:目录字段与 configuration_schema |
| 读取门、拓扑、timing、noise、features | capabilities_from_backend(resource) | BackendCapabilities:便于 Python 使用的能力对象 |
| 把设备选项用于自己的程序 | JobSubmissionConfig(configuration_data={...}) | 本次任务的配置;再交给 prepare_submission 取得报价 |
开始前:创建客户端
先按连接与认证章节配置平台地址和 SDK Key。下面从 QUANTUM_SOURCE_API_URL 读取地址,SchedulerClient 自动读取已配置的凭据。使用 QUANTUM_SOURCE_SDK_KEY 指定密钥文件时,优先读取文件中的凭据。
import os
from quantum_source_sdk import (
SchedulerClient,
JobSubmissionConfig,
list_backends,
get_capabilities,
capabilities_from_backend,
)
scheduler = SchedulerClient(
base_url=os.environ["QUANTUM_SOURCE_API_URL"],
)
SchedulerClient 是查询设备和准备任务的入口,base_url 填写平台 API 根地址。本章共用一个 scheduler,完成后调用 close() 关闭连接。
创建客户端时用 currency 选择钱包,默认 OPEN;需要 FULL 时加入 currency="FULL"。通过 scheduler.currency 查看当前选择,后续新准备的报价使用该币种。
列出设备
用 list_backends(scheduler=...) 获取设备标识列表。它自动读取目录中的全部分页,返回去重、排序后的 short_code 字符串。
backend_codes = list_backends(scheduler=scheduler)
for code in backend_codes:
print(code)
backend_code = input("复制要查询的设备 short_code:").strip()
resource = scheduler.get_backend_class(backend_code)
backend_codes 是 list[str],每一项都是可用于选择设备的 short_code。将其中一项传给 get_backend_class 后,resource 就代表这台设备。input() 只是本教程让你选择设备的交互方式;在自己的程序里可以把 backend_code 直接设为目录中实际返回的标识。
按页读取设备属性
需要比较设备名称、类型和在线状态时,使用 scheduler.management 的分页目录接口。下面的代码依次读取全部页面。
cursor 标记下一页的位置,None 表示从第一页开始。每次读取后,将 page.pagination.next_cursor 传给下一次查询;其值为空时结束。只查看第一页时,调用 list_backend_classes(limit=100) 并读取 page.backend_classes。
cursor = None
while True:
page = scheduler.management.list_backend_classes(limit=100, cursor=cursor)
for item in page.backend_classes:
print(item.short_code, item.type, item.status, item.num_qubits,
item.platform_active_tasks)
cursor = page.pagination.next_cursor
if not cursor:
break
platform_active_tasks 是该设备在本平台已经接受、尚未确认完成、失败或取消的任务总数,用于了解平台任务负载。返回 None 时表示暂无统计。准备和确认任务时,平台会检查账号权限、余额及额度。
设备详情:BackendClassRead
将上一步取得的 short_code 传给 scheduler.get_backend_class(identifier),得到 BackendClassRead。这个对象包含设备身份、目录状态和公开的配置选项。
| 读取位置 | 含义 | 使用注意 |
|---|---|---|
| resource.id / resource.short_code / resource.name | 资源 ID、设备标识和显示名称 | 任务的 backend_class_id 使用 id 或 short_code。 |
| resource.type / resource.is_hardware | 设备类别与真机声明 | is_hardware 为 None 时表示类型尚未明确。 |
| resource.status / resource.num_qubits | 目录状态与设备宽度 | 可用物理位置通过能力模型的 available_qubits 查看。 |
| resource.supported_formats | 目录声明的输入格式 | 按自己使用的 Core、Qiskit 或 PennyLane 入口编写程序。 |
| resource.configuration_schema | 该设备公开任务配置的 schema | 读取 properties 查看设备选项。 |
| resource.metadata / resource.extra | 扩展能力信息 | 需要详细分析设备数据时按字段读取。 |
print("设备:", resource.short_code, resource.name)
print("类别:", resource.type)
print("在线状态:", resource.status)
print("目录格式:", resource.supported_formats)
print("编译方式:", resource.compilation_mode)
查询门集与连接关系
已有 resource 时,用 capabilities_from_backend(resource) 在本地解析设备能力。需要重新从平台读取时,使用 get_capabilities(backend_code, scheduler=scheduler)。两种方式都返回 BackendCapabilities。
caps = capabilities_from_backend(resource)
print("设备宽度:", caps.num_qubits)
print("支持操作:", sorted(caps.supported_gate_names))
print("原生操作:", sorted(caps.native_gate_names))
print("当前可用位置:", caps.available_qubits)
print("连接边:", caps.topology.coupling_map)
print("连接有方向:", caps.topology.is_directed)
print("任务限制:", caps.limits)
print("功能声明:", sorted(caps.features))
print("平台是否声明可接收逻辑线路:", caps.supports_execution_path("logical"))
print("平台是否声明可接收已编译的物理线路:", caps.supports_execution_path("physical"))
supported_gate_names 展示可表达的操作,native_gate_names 展示设备公开的原生门。coupling_map 中的每一对物理比特编号表示一条连接边;is_directed 表示是否区分连接方向。固定布局时,结合 client_instructions 查看各个门允许使用的位置。
supports_execution_path 是只读能力查询,返回 True 或 False。上面两个 print 用于了解平台接受哪一种线路:logical 表示提交逻辑线路,由平台对应的编译流程适配设备;physical 表示提交已经确定物理比特位置并完成编译的线路。两项可以同时为 True,你按本次线路的准备方式选择。
| 查询 | True 的含义 | 接下来怎样使用 |
|---|---|---|
| caps.supports_execution_path("logical") | 当前目录明确声明接收逻辑线路 | 编写使用逻辑比特的 OpenQASM,configuration_data 使用 circuit_representation="logical";本源真机由云端完成拓扑映射。 |
| caps.supports_execution_path("physical") | 当前目录明确声明接收已编译的物理线路 | 按设备门集与连接关系完成物理编译,configuration_data 使用 circuit_representation="physical"。 |
False 表示当前目录没有明确声明支持该提交方式,包括声明缺失的情况。可以重新查询设备详情,或选择已声明支持所需方式的设备。真正选择提交方式的是任务配置中的 circuit_representation;调用查询方法会保持现有配置不变。
| 字段或方法 | 内容 | 如何使用 |
|---|---|---|
| supported_gate_names / supported_ops | 支持的操作名称、门元数及参数名 | 了解线路可用的操作;缺少 supported_ops 时解析器可回退到 native_ops。 |
| native_gate_names / native_ops | 设备公开的原生门集 | 结合具体操作的 qargs 查看物理放置位置。 |
| topology.coupling_map / is_directed | 连接关系与方向标记 | 查看量子比特连接图。 |
| available_qubits | 解析后的可用物理位置 | 精确分析时核对原始声明;兼容旧目录时可能按设备宽度补齐。 |
| limits / max_shots | 设备执行范围 | 设置符合设备范围的线路宽度与采样次数。 |
| features / supports_feature(name) | 平台明确声明的功能 | True 表示已声明支持,False 表示当前目录未声明。 |
| client_instructions | 各个操作及允许的 qargs | 为固定物理布局提供逐门位置数据。 |
通过 caps.supports_feature("reset") 或 caps.allows_reset() 查询线路功能;通过 configuration_schema 查询 mapping 等提交选项。
print("reset 已声明:", caps.allows_reset())
print("中途测量已声明:", caps.allows_mid_circuit_measure())
print("动态线路已声明:", caps.allows_dynamic_circuits())
for instruction in caps.client_instructions:
print(instruction.name, instruction.arity,
instruction.parameters, instruction.qargs)
读取 timing、noise 与 features
资源中的 constraint_data 保存平台发布的能力数据;capabilities_from_backend 合并这些数据与目录字段,生成 caps。需要详细查看设备声明时,读取下面的原始字段。
raw_capabilities = (
resource.extra.get("constraint_data")
or resource.metadata.get("constraint_data")
or resource.extra.get("capabilities")
or resource.metadata.get("capabilities")
or {}
)
raw_topology = raw_capabilities.get("topology", {})
print("原始可用位置声明:",
raw_topology.get("available_qubits",
raw_capabilities.get("available_qubits")))
print("原始 timing:", raw_capabilities.get("timing"))
print("原始 noise:", raw_capabilities.get("noise"))
print("原始 features:", raw_capabilities.get("features"))
print("解析后的 timing:", dict(caps.timing))
print("解析后的 noise:", dict(caps.noise))
timing 包含设备公布的时间信息,noise 包含可用的噪声或错误率信息,features 列出已识别的线路功能。空值表示当前平台尚未提供该项数据;例如 dt=None 表示采样周期未知。
使用自己的 OpenQASM 程序
Core SDK 读取 OpenQASM 文件或 UTF-8 字节内容。按程序头部的版本选择 input_format,平台负责转换为设备执行格式。使用 Qiskit 或 PennyLane 编写线路时,可直接使用对应插件完成提交。
| Core input_format | 文件内容 |
|---|---|
| openqasm2 | 以 OPENQASM 2.0; 开头的程序 |
| openqasm3 | 以 OPENQASM 3 开头的程序 |
设备的 configuration_schema 用于查询 mapping 等执行选项,OpenQASM 2 和 3 使用同一份设备配置说明。高级查询中的 caps.supports_format() 按语言家族归类;具体程序由准备接口检查。
发现设备专属选项
读取 resource.configuration_schema 后,逐项查看名称、类型、范围、默认值和说明。下面把常用字段整理成简短的字典;None 表示该项未提供。
schema = resource.configuration_schema
properties = schema.get("properties", {})
required = set(schema.get("required", []))
for name, definition in properties.items():
print({
"name": name,
"type": definition.get("type"),
"enum": definition.get("enum"),
"const": definition.get("const"),
"default": definition.get("default"),
"minimum": definition.get("minimum"),
"maximum": definition.get("maximum"),
"required": name in required,
"description": definition.get("description"),
})
例如,name=mapping、type=boolean、default=True 表示该设备的映射选项默认开启。希望显式选择这个值时,在任务中填写 configuration_data={"mapping": True}。其他选项同样根据查询到的类型和取值范围填写。
| schema 字段 | 读法 | 示例含义 |
|---|---|---|
| properties | 可选择的设备参数及定义 | 查找 mapping 等字段,读取它的类型与默认值。 |
| type | JSON 值类型 | boolean 在 Python 中填写 True 或 False。 |
| enum / const | 候选值列表 / 固定值 | enum=[False, True] 可选择布尔值;const=False 表示该上下文只允许 False。 |
| default | 设备声明的默认值 | 采用默认行为时可省略对应选项。 |
| minimum / maximum | 数值范围 | 选择此区间内的数值。 |
| required | 必填的设备选项名称 | 在任务的 configuration_data 中填写这些选项。 |
选择本源真机后,可以从 schema 查看 amend、mapping、optimization 等设备选项。设置本次实验需要调整的选项即可,其余沿用默认行为。
| 本源设备选项 | 用途 | 使用方式 |
|---|---|---|
| mapping | 启用本源云端拓扑映射,完成逻辑比特到物理比特的映射,并适配芯片连接关系 | 逻辑线路设为 True;已经完成物理编译的线路设为 False。 |
| optimization | 开启或关闭本源云端线路优化 | True 开启,False 关闭;当前固定物理线路使用 False 保留已编译的线路。 |
| amend | 开启或关闭本源云端修正功能 | True 启用,False 关闭。 |
mapping 是云端编译中的拓扑映射开关。开启后,本源将逻辑线路的比特和门操作安排到芯片可执行的连接关系上。需要指定物理比特时,先完成下面介绍的固定布局流程,再关闭云端映射。
设置 configuration_data
把设备选项放进 JobSubmissionConfig 的 configuration_data。这个字典使用平铺结构,mapping、optimization 等名称直接作为键。
# 为本源真机的逻辑线路设置映射与优化选项。
configuration = {
"circuit_representation": "logical",
"mapping": True,
"optimization": False,
}
config = JobSubmissionConfig(
backend_class_id=resource.short_code,
organization_id="替换为平台返回的组织 ID",
name="bell-core-logical",
shots=128,
input_format="openqasm2",
configuration_data=configuration,
)
| 示例参数 | 填写内容 | 作用 |
|---|---|---|
| backend_class_id | 刚查询到的 resource.short_code | 将任务发送到你已检查能力的同一台设备 |
| organization_id | 平台返回的组织 ID | 确定任务归属、访问权限与共享名额;费用由当前用户的钱包支付 |
| shots | 128 | 本次线路请求的测量次数 |
| input_format | openqasm2 | 按 OpenQASM 2 解释随后上传的文本 |
| configuration_data | 本次选择的设备选项字典 | 携带厂商编译选项和平台线路表示信息 |
circuit_representation 标记线路采用逻辑比特还是已经编译好的物理位置,默认 logical。固定布局的程序使用 physical,详见后面的物理线路章节。
| 情况 | 使用方法 |
|---|---|
| 显式选择设备选项 | 把取值写入 configuration_data,平台按设备 schema 检查。 |
| 采用默认选项 | 省略对应字段,平台在准备时应用设备及执行路径的默认值。 |
| 调整实验配置 | 创建新的 config,再准备新的报价。 |
| 设置采样次数 | 使用 shots=128;若同时在 configuration_data 中填写 shots,两处保持一致。 |
完整示例:为 Bell 线路准备报价
下面是可单独复制的 Core 示例。运行前配置平台地址和 SDK 凭据;运行时选择设备并输入组织 ID。示例根据设备公开的选项启用 mapping,完成线路上传并展示报价。
import os
from quantum_source_sdk import SchedulerClient, JobSubmissionConfig, list_backends
qasm = b'''OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
'''
with SchedulerClient(base_url=os.environ["QUANTUM_SOURCE_API_URL"]) as client:
print("设备:", list_backends(scheduler=client))
selected_code = input("设备 short_code:").strip()
selected = client.get_backend_class(selected_code)
print("格式:", selected.supported_formats)
print("设备参数:", selected.configuration_schema.get("properties", {}))
organization = input("平台组织 ID:").strip()
configuration = {"circuit_representation": "logical"}
if "mapping" in selected.configuration_schema.get("properties", {}):
configuration["mapping"] = True
config = JobSubmissionConfig(
backend_class_id=selected.short_code,
organization_id=organization,
name="bell-core-logical",
shots=128,
input_format="openqasm2",
configuration_data=configuration,
)
prepared = client.prepare_submission(config, file_content=qasm)
print("准备记录:", prepared.preparation.id)
print("报价:", prepared.quote)
# 本例完成报价准备,执行流程见 Core 主教程。
理解示例与返回值
线路先对逻辑 q[0] 应用 H 门,再用 CX 关联 q[0] 与 q[1],最后测量两个逻辑比特。mapping=True 启用本源云端拓扑映射,把这条逻辑线路适配到芯片的物理比特和连接关系。
| 调用或返回值 | 本例中的含义 |
|---|---|
| qasm | bytes 类型的 OpenQASM 文件内容;若原始程序是 str,使用 .encode("utf-8") 转换 |
| client.prepare_submission(config, file_content=qasm) | 上传程序、进行准备并获取报价,返回 PreparedSubmission |
| prepared.preparation.id | 本次准备记录的标识,用于后续确认和查询 |
| prepared.quote | 这次程序、设备、shots 与配置对应的报价对象 |
继续执行时,参考 Core 主教程中的报价确认步骤,并保持创建 prepared 的客户端连接有效。本独立示例使用 with,在代码块结束时自动关闭连接。
使用已编译的物理线路
需要在指定物理比特上运行时,先根据设备连接图和逐门位置完成布局编译,再通过 Core 提交物理 OpenQASM 程序。使用 Qiskit 的 physical_qubits 或 initial_layout 可以完成这一流程,详见编译与物理布局章节。
设备提供物理执行路径时,已编译的物理程序使用 circuit_representation="physical"、mapping=False、optimization=False,保留编译好的物理位置和线路。
重新查询与关闭连接
# 重新读取平台设备目录并解析能力。
resource = scheduler.get_backend_class(backend_code)
caps = capabilities_from_backend(resource)
schema = resource.configuration_schema
# 或直接重新取得能力模型:
caps = get_capabilities(backend_code, scheduler=scheduler)
重新查询会得到平台当前发布的目录数据,再生成新的 caps 对象。平台可能缓存设备信息;需要校准时间时,读取设备实际提供的时间字段。schema.properties、timing 或 noise 为空表示该项信息暂未发布。
# 完成本章后释放本地 HTTP 连接。
scheduler.close()
API 参考
查询函数、能力字段、任务配置的完整签名与返回值统一收录在 API 参考中,可按接口名称查阅。
下载本页 Jupyter Notebook
收录本页 Python 示例与说明,便于在 Jupyter Notebook 中学习和运行;安装命令保留为说明。