QPilotServiceBase

QPilotServiceBase 是与 QPilot OS 量子计算平台交互的主要服务类。它提供了在各种后端（包括模拟器和真实量子芯片）上提交量子程序、查询结果和管理任务的方法。

签名

python

QPilotServiceBase(url: str, log_cout: bool = False, api_key: str = None)
QPilotServiceBase(url: str, log_cout: bool = False, username: str = None, password: str = None)

参数

参数	类型	默认值	描述
url	str	必填	QPilot OS 服务器的 URL
log_cout	bool	False	是否将日志输出到控制台
api_key	str	None	用于身份验证的 API 密钥
username	str	None	用于凭据认证的用户名
password	str	None	用于凭据认证的密码

支持两种身份验证模式：基于 API 密钥和基于用户名/密码。

方法

配置

init_config

python

init_config(url: str, log_cout: bool) -> None

初始化或重新配置服务连接。

参数	类型	描述
url	str	QPilot OS 服务器 URL
log_cout	bool	是否启用控制台日志

get_token

python

get_token(rep_json: str) -> str

从 JSON 响应字符串中提取身份验证令牌。

参数	类型	描述
rep_json	str	来自身份验证端点的 JSON 响应

消息构建

build_init_msg

python

build_init_msg(api_key: str) -> str

构建用于与 QPilot OS 服务器进行身份验证的初始化消息。

参数	类型	描述
api_key	str	用于身份验证的 API 密钥

build_task_msg

python

build_task_msg(prog: QProg, shot: int, chip_id: str, is_amend: bool,
               is_mapping: bool, is_optimization: bool,
               specified_block: list[int], task_describe: str,
               point_lable: int, priority) -> str

构建真实芯片测量任务消息体。

参数	类型	描述
prog	QProg	量子程序
shot	int	执行次数
chip_id	str	目标芯片标识符
is_amend	bool	是否应用修正
is_mapping	bool	是否应用量子比特映射
is_optimization	bool	是否应用线路优化
specified_block	list[int]	指定块约束
task_describe	str	任务描述
point_lable	int	任务的点标签
priority	int	任务优先级

build_task_proto_msg

python

build_task_proto_msg(shot: int, chip_id: str, is_amend: bool,
                     is_mapping: bool, is_optimization: bool,
                     specified_block: list[int], task_describe: str,
                     task_type, point_lable: int, priority) -> str

使用协议缓冲区（Protocol Buffer）格式构建真实芯片测量任务消息。

build_expectation_task_msg

python

build_expectation_task_msg(prog: QProg, hamiltonian,
                           qubits: list[int] = [], shot: int = 1000,
                           chip_id: str = "any_quantum_chip",
                           is_amend: bool = True, is_mapping: bool = True,
                           is_optimization: bool = True,
                           specified_block: list[int] = [],
                           task_describe: str = "") -> str

构建用于哈密顿量期望值计算的期望值任务消息。

参数	类型	默认值	描述
prog	QProg	必填	量子程序
hamiltonian	Hamiltonian	必填	目标哈密顿量
qubits	list[int]	[]	用于计算的量子比特子集
shot	int	1000	执行次数
chip_id	str	"any_quantum_chip"	目标芯片标识符
is_amend	bool	True	应用修正
is_mapping	bool	True	应用量子比特映射
is_optimization	bool	True	应用优化
specified_block	list[int]	[]	块约束
task_describe	str	""	任务描述

build_qst_task_msg

python

build_qst_task_msg(prog: QProg, shot: int = 1000,
                   chip_id: str = "any_quantum_chip",
                   is_amend: bool = True, is_mapping: bool = True,
                   is_optimization: bool = True,
                   specified_block: list[int] = [],
                   task_describe: str = "") -> str

构建量子态层析（Quantum State Tomography, QST）任务消息。

build_query_msg

python

build_query_msg(task_id: str) -> str

构建用于检查任务状态的查询消息。

参数	类型	描述
task_id	str	要查询的任务标识符

执行 -- 同步

run

提交量子程序并等待结果。多个重载版本支持 QProg、str（OriginIR）、list[QProg] 或 list[str] 作为输入。

python

# Single program
run(prog: QProg, shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# Single OriginIR string
run(ir: str, shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# Multiple programs
run(prog: list[QProg], shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# Multiple OriginIR strings
run(ir: list[str], shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# With configuration string
run(prog: list[QProg], config_str: str) -> str

参数	类型	默认值	描述
prog	QProg or list[QProg]	必填	要执行的量子程序
ir	str or list[str]	必填	要执行的 OriginIR 字符串
shot	int	1000	执行次数
chip_id	str	"any_quantum_chip"	目标芯片标识符
is_amend	bool	True	应用修正
is_mapping	bool	True	应用量子比特映射
is_optimization	bool	True	应用线路优化
specified_block	list[int]	[]	块约束
describe	str	""	任务描述
point_lable	int	0	点标签
config_str	str	必填	JSON 配置字符串

返回值： 结果字符串。

run_simulator

python

run_simulator(prog: QProg, shot: int) -> dict[str, float]
run_simulator(prog: QProg, qubit_vec: list[int]) -> dict[str, float]

在本地模拟器上运行量子程序。

参数	类型	描述
prog	QProg	要模拟的量子程序
shot	int	测量次数
qubit_vec	list[int]	要测量的量子比特（部分测量）

real_chip_measure_prob_count

提交真实芯片测量任务并返回概率计数。支持 QProg、str、list[QProg] 和 list[str] 输入。

python

real_chip_measure_prob_count(prog: QProg, shot: int = 1000,
                            chip_id: str = "any_quantum_chip",
                            is_mapping: bool = True, is_optimization: bool = True,
                            specified_block: list[int] = [], describe: str = "",
                            point_lable: int = 0) -> str

参数	类型	默认值	描述
prog	QProg or str or list	必填	量子程序或 OriginIR
shot	int	1000	执行次数
chip_id	str	"any_quantum_chip"	目标芯片
is_mapping	bool	True	应用量子比特映射
is_optimization	bool	True	应用线路优化
specified_block	list[int]	[]	块约束
describe	str	""	任务描述
point_lable	int	0	点标签

real_chip_expectation

python

real_chip_expectation(prog: QProg, hamiltonian, qubits: list[int] = [],
                      shot: int = 1000, chip_id: str = "any_quantum_chip",
                      is_amend: bool = True, is_mapping: bool = True,
                      is_optimization: bool = True,
                      specified_block: list[int] = [],
                      describe: str = "") -> str

在真实芯片上计算哈密顿量的期望值。此方法已弃用，请改用 run 或 async_run 方法。

执行 -- 异步

async_run

提交量子程序并立即返回任务 ID。支持与 run 相同的输入类型，并额外提供 is_prob_counts 参数。

python

# Single program
async_run(prog: QProg, shot: int = 1000, chip_id: str = "any_quantum_chip",
          is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
          specified_block: list[int] = [], is_prob_counts: bool = True,
          describe: str = "", point_lable: int = 0) -> str

# With configuration string
async_run(prog: list[QProg], config_str: str) -> str

参数	类型	默认值	描述
prog	QProg or str or list	必填	量子程序或 OriginIR
shot	int	1000	执行次数
chip_id	str	"any_quantum_chip"	目标芯片
is_amend	bool	True	应用修正
is_mapping	bool	True	应用量子比特映射
is_optimization	bool	True	应用优化
specified_block	list[int]	[]	块约束
is_prob_counts	bool	True	返回概率计数
describe	str	""	任务描述
point_lable	int	0	点标签
config_str	str	必填	JSON 配置字符串

返回值： 用于后续查询的任务 ID 字符串。

async_real_chip_expectation

python

async_real_chip_expectation(prog: QProg, hamiltonian, qubits: list[int] = [],
                            shot: int = 1000, chip_id: str = "any_quantum_chip",
                            is_amend: bool = True, is_mapping: bool = True,
                            is_optimization: bool = True,
                            specified_block: list[int] = [],
                            describe: str = "") -> str

在真实芯片上进行异步哈密顿量期望值计算。此方法已弃用，请改用 async_run。

量子态层析

async_real_chip_qst

python

async_real_chip_qst(prog: QProg, shot: int = 1000,
                    chip_id: str = "any_quantum_chip",
                    is_amend: bool = True, is_mapping: bool = True,
                    is_optimization: bool = True,
                    specified_block: list[int] = [],
                    describe: str = "", point_lable: int = 0) -> str

提交异步量子态层析（QST）任务。返回一个任务 ID。

async_real_chip_qst_density

python

async_real_chip_qst_density(prog: QProg, shot: int = 1000,
                            chip_id: str = "any_quantum_chip",
                            is_amend: bool = True, is_mapping: bool = True,
                            is_optimization: bool = True,
                            specified_block: list[int] = [],
                            describe: str = "", point_lable: int = 0) -> str

提交异步 QST 密度矩阵计算任务。返回一个任务 ID。

async_real_chip_qst_fidelity

python

async_real_chip_qst_fidelity(prog: QProg, shot: int = 1000,
                             chip_id: str = "any_quantum_chip",
                             is_amend: bool = True, is_mapping: bool = True,
                             is_optimization: bool = True,
                             specified_block: list[int] = [],
                             describe: str = "", point_lable: int = 0) -> str

提交异步 QST 保真度计算任务。返回一个任务 ID。

错误缓解

noise_learning

python

noise_learning(parameter_json: str) -> str

使用给定的 JSON 参数提交噪声学习任务。

em_compute

python

em_compute(parameter_json: str) -> str

使用给定的 JSON 参数同步运行错误缓解（Error Mitigation）计算。

async_em_compute

python

async_em_compute(parameter_json: str) -> str

异步提交错误缓解计算任务。

结果检索

query_result

python

query_result(task_id: str) -> list
query_result(task_id: str, is_save: bool, file_path: str = "") -> list

根据任务 ID 查询任务结果。

参数	类型	默认值	描述
task_id	str	必填	任务标识符
is_save	bool	必填	是否将结果保存到文件
file_path	str	""	用于保存结果的文件路径

返回值： 列表 [state, result_vec, err_code, err_info]，其中：

state (str)：任务状态 -- "2" 表示运行中，"3" 表示已完成，"4" 表示失败
result_vec (list)：结果数据字符串
err_code (ErrorCode)：错误代码（如有）
err_info (str)：错误信息字符串

query_task_state_vec

python

query_task_state_vec(task_id: str) -> list

查询任务状态和结果向量。返回格式与 query_result 相同。

query_compile_prog

python

query_compile_prog(task_id: str, without_compensate: bool = True) -> list

查询给定任务的编译后的程序。

参数	类型	默认值	描述
task_id	str	必填	任务标识符
without_compensate	bool	True	是否返回不带角度补偿的程序

返回值： 列表 [err_code, err_info, compile_prog]。

get_measure_result

python

get_measure_result(task_id: str) -> list

检索已完成任务的测量结果。

返回值： 列表 [result, err_code, err_info]，其中 result 是将态字符串映射到测量值的字典列表。

get_expectation_result

python

get_expectation_result(task_id: str) -> list

检索已完成任务的期望值结果。

返回值： 列表 [expectation, err_code, err_info]，其中 expectation 是浮点数。

_get_qst_result

python

_get_qst_result(task_id: str) -> list

检索已完成任务的 QST 测量结果。

返回值： 列表 [result, err_code, err_info]。

_get_qst_density_result

python

_get_qst_density_result(task_id: str) -> list

检索 QST 密度矩阵结果。

返回值： 列表 [density, err_code, err_info]。

_get_qst_fidelity_result

python

_get_qst_fidelity_result(task_id: str) -> list

检索 QST 保真度结果。

返回值： 列表 [fidelity, err_code, err_info]，其中 fidelity 是浮点数。

结果解析

parse_task_result

python

parse_task_result(result_str: str) -> dict[str, float]

将结果字符串解析为将态字符串映射到浮点值的字典。

parse_probability_result

python

parse_probability_result(result_str: list[str]) -> list[dict[str, float]]

将结果字符串列表解析为包含概率值的字典列表。

parse_prob_counts_result

python

parse_prob_counts_result(result_str: list[str]) -> list[dict[str, int]]

将结果字符串列表解析为包含整型计数值的字典列表。

parser_sync_result

python

parser_sync_result(json_str: str) -> list[dict[str, float]]

将同步结果 JSON 字符串解析为概率数据。

parser_expectation_result

python

parser_expectation_result(json_str: str) -> list[list[float]]

解析期望值结果 JSON 字符串。此方法已弃用，请改用 Python 的 json 库。

网络

tcp_recv

python

tcp_recv(ip: str, port: int, task_id: str) -> list

通过 TCP 连接接收任务结果。

参数	类型	描述
ip	str	TCP 服务器 IP 地址
port	int	TCP 服务器端口
task_id	str	要检索的任务标识符

返回值： 列表 [is_ok, response]，其中 is_ok 是布尔值，response 是结果字符串。

工具

output_version

python

output_version() -> str

返回 QPilot OS 服务的版本字符串。

示例

python

from pyqpanda3.pilot_service import QPilotService
from pyqpanda3.core import QCircuit, H, CNOT, measure

# 使用 API 密钥初始化
service = QPilotService(
    url="https://qpilot.originquantum.cn",
    api_key="your_api_key"
)

# 创建量子程序
circuit = QCircuit(2)
circuit << H(0) << CNOT(0, 1)
prog = QProg()
prog << circuit << measure([0, 1], [0, 1])

# 同步执行
result = service.run(prog, shot=1000, chip_id="simulation")

# 异步执行
task_id = service.async_run(prog, shot=1000, chip_id="real_chip")

# 查询结果
result_dict = service.query_result(task_id)
print(f"State: {result_dict['taskState']}, Results: {result_dict['taskResult']}")

# 解析结果
if result_dict['taskState'] == "3":  # 已完成
    parsed = service.parse_probability_result(result_dict['taskResult'])
    print(f"Parsed results: {parsed}")

另见

PilotNoiseParams -- 噪声参数配置
ErrorCode -- 错误代码枚举
qcloud 模块 -- 更高层的云服务接口

QPilotServiceBase ​

签名 ​

参数 ​

方法 ​

配置 ​

init_config ​

get_token ​

消息构建 ​

build_init_msg ​

build_task_msg ​

build_task_proto_msg ​

build_expectation_task_msg ​

build_qst_task_msg ​

build_query_msg ​

执行 -- 同步 ​

run ​

run_simulator ​

real_chip_measure_prob_count ​

real_chip_expectation ​

执行 -- 异步 ​

async_run ​

async_real_chip_expectation ​

量子态层析 ​

async_real_chip_qst ​

async_real_chip_qst_density ​

async_real_chip_qst_fidelity ​

错误缓解 ​

noise_learning ​

em_compute ​

async_em_compute ​

结果检索 ​

query_result ​

query_task_state_vec ​

query_compile_prog ​

get_measure_result ​

get_expectation_result ​

_get_qst_result ​

_get_qst_density_result ​

_get_qst_fidelity_result ​

结果解析 ​

parse_task_result ​

parse_probability_result ​

parse_prob_counts_result ​

parser_sync_result ​

parser_expectation_result ​

网络 ​

tcp_recv ​

工具 ​

output_version ​

示例 ​

另见 ​

QPilotServiceBase

签名

参数

方法

配置

init_config

get_token

消息构建

build_init_msg

build_task_msg

build_task_proto_msg

build_expectation_task_msg

build_qst_task_msg

build_query_msg

执行 -- 同步

run

run_simulator

real_chip_measure_prob_count

real_chip_expectation

执行 -- 异步

async_run

async_real_chip_expectation

量子态层析

async_real_chip_qst

async_real_chip_qst_density

async_real_chip_qst_fidelity

错误缓解

noise_learning

em_compute

async_em_compute

结果检索

query_result

query_task_state_vec

query_compile_prog

get_measure_result

get_expectation_result

_get_qst_result

_get_qst_density_result

_get_qst_fidelity_result

结果解析

parse_task_result

parse_probability_result

parse_prob_counts_result

parser_sync_result

parser_expectation_result

网络

tcp_recv

工具

output_version

示例

另见