QuantumFerry 用户使用手册

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、featurescapabilities_from_backend(resource)BackendCapabilities:便于 Python 使用的能力对象
把设备选项用于自己的程序JobSubmissionConfig(configuration_data={...})本次任务的配置;再交给 prepare_submission 取得报价

开始前:创建客户端

先按连接与认证章节配置平台地址和 SDK Key。下面从 QUANTUM_SOURCE_API_URL 读取地址,SchedulerClient 自动读取已配置的凭据。使用 QUANTUM_SOURCE_SDK_KEY 指定密钥文件时,优先读取文件中的凭据。

python
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 字符串。

python
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。

python
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扩展能力信息需要详细分析设备数据时按字段读取。
python
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。

python
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 等提交选项。

python
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。需要详细查看设备声明时,读取下面的原始字段。

python
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 表示该项未提供。

python
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 等字段,读取它的类型与默认值。
typeJSON 值类型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 等名称直接作为键。

python
# 为本源真机的逻辑线路设置映射与优化选项。
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确定任务归属、访问权限与共享名额;费用由当前用户的钱包支付
shots128本次线路请求的测量次数
input_formatopenqasm2按 OpenQASM 2 解释随后上传的文本
configuration_data本次选择的设备选项字典携带厂商编译选项和平台线路表示信息

circuit_representation 标记线路采用逻辑比特还是已经编译好的物理位置,默认 logical。固定布局的程序使用 physical,详见后面的物理线路章节。

情况使用方法
显式选择设备选项把取值写入 configuration_data,平台按设备 schema 检查。
采用默认选项省略对应字段,平台在准备时应用设备及执行路径的默认值。
调整实验配置创建新的 config,再准备新的报价。
设置采样次数使用 shots=128;若同时在 configuration_data 中填写 shots,两处保持一致。

完整示例:为 Bell 线路准备报价

下面是可单独复制的 Core 示例。运行前配置平台地址和 SDK 凭据;运行时选择设备并输入组织 ID。示例根据设备公开的选项启用 mapping,完成线路上传并展示报价。

python
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 启用本源云端拓扑映射,把这条逻辑线路适配到芯片的物理比特和连接关系。

调用或返回值本例中的含义
qasmbytes 类型的 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,保留编译好的物理位置和线路。

重新查询与关闭连接

python
# 重新读取平台设备目录并解析能力。
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 为空表示该项信息暂未发布。

python
# 完成本章后释放本地 HTTP 连接。
scheduler.close()

API 参考

查询函数、能力字段、任务配置的完整签名与返回值统一收录在 API 参考中,可按接口名称查阅。

下载本页 Jupyter Notebook

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

下载《Core 设备配置》Notebook(.ipynb)

输入关键词;所有搜索都在本机完成。