pyqpanda3 v0.5.1：云服务接入、纠错配置与拓扑约束随机电路

0.5.0 把性能旋钮交给了使用者。v0.5.1 不追新的基准数字，而是回头补齐云服务接入与可配置性上的几个缺口：连接服务不再必须手写地址，纠错模式从布尔开关变成带语义的选项，失败任务改用结果状态表达，随机电路可以直接跟随芯片拓扑，GPU 模拟器也支持指定初态。

一个 API key，直接连到正确的服务

QCloudService(api_key) 现在可以只传一个参数。新格式 API key 自带服务域名，SDK 解析后直接连接对应服务；旧格式 key 不携带域名，回退到历史默认云端端点，已有代码不会因此失效。

需要测试环境或私有部署时，仍然可以用两参构造显式覆盖：

python

from pyqpanda3.qcloud import QCloudService

# 新格式 key：从 key 中解析服务域名
service = QCloudService(api_key="YOUR_API_KEY")

# 显式 URL：覆盖 key 中的域名
service = QCloudService(
    api_key="YOUR_API_KEY",
    url="https://custom-cloud.example.com",
)

NOTE

上述示例需要云端凭据与真实任务，无法在本地执行。

0.5.1 绑定中，两参构造的 url 已无默认值：需要自定义地址时必须显式传入。

纠错模式成为可配置项

QCloudOptions 现在支持关键字构造，并把纠错与串扰抑制从隐式行为变成可读写的配置：

python

from pyqpanda3.qcloud import QCloudOptions

options = QCloudOptions(
    amend_flag=3,          # 0：关闭；1：全局采样纠错；3：局部实时纠错
    use_cz_pattern=True,   # 启用串扰噪声抑制
    mapping=True,
    optimization=True,
    point_label=1,
    is_prob_counts=True,
    specified_block=[],
)
options.print()

amend_flag=0 关闭纠错，1 启用全局采样纠错，3 启用局部实时纠错。
use_cz_pattern 控制串扰噪声抑制。
新增 set_amend_flag / amend_flag 与 set_use_cz_pattern / use_cz_pattern；原有 set_amend 等 setter 保持不变。
print() 现在输出 is_prob_counts、amend_flag、use_cz_pattern、mapping、optimization、point_label，不再输出 amend。

选项对象可以在本地构造；真正提交任务仍需云端凭据。

失败任务不再用异常表达

QCloudJob.result() 以前在任务失败时抛 RuntimeError。0.5.1 改为用结果本身表达失败：result() 只在 WAITING / COMPUTING / QUEUING 时继续轮询，FINISHED / FAILED 立即返回；失败时 job_status() == JobStatus.FAILED，error_message() 给出原因。

python

from pyqpanda3.core import H, QProg, measure
from pyqpanda3.qcloud import JobStatus, QCloudService

service = QCloudService(api_key="YOUR_API_KEY")
backend = service.backend("full_amplitude")
prog = QProg() << H(0) << measure(0, 0)
job = backend.run(prog, shots=1000)

result = job.result()
if result.job_status() == JobStatus.FAILED:
    print("failed:", result.error_message())
else:
    print(result.get_probs())

error_message() 优先返回 obj.errInfo，其次 message，最后 errCode。网络、协议或 HTTP 等传输层错误仍可能从底层请求抛出，因此 try/except 不应整体移除。

NOTE

上述示例需要云端凭据与真实任务，无法在本地执行。

随机电路跟随芯片拓扑

random_qcircuit 与 random_qprog 新增 topology 重载。它接受与 ChipInfo.get_chip_topology() 相同格式的边列表，生成时每个双比特门只会落在给定边上：

python

from pyqpanda3.core import random_qcircuit, random_qprog

topology = [[0, 1], [1, 2]]
circ = random_qcircuit([0, 1, 2], 5, ["H", "CNOT"], topology)
prog = random_qprog([0, 1, 2], 5, ["H", "CNOT"], topology)
print(circ.gate_operations())
print(prog.gate_operations())

单比特门不受拓扑限制。若某条边引用了 qubits 之外的比特，函数抛出 ValueError，而不是静默生成一条无法映射的线路。

NOTE

本机没有 0.5.1 wheel，以上示例未执行；语义以绑定层与 test_random_circuit_topology.py 为准。

GPU 模拟器的初态

GPUQVM.init_state(state) 让 GPU 模拟器可以从指定初态开始，而不再只能从 |0...0> 起步：

python

from pyqpanda3.core import GPUQVM, QProg, measure

qvm = GPUQVM()
qvm.init_state([0, 1])          # |1>
prog = QProg(1)
prog << measure(0, 0)
qvm.run(prog, 16)
print(qvm.result().get_counts())  # {'1': 16}

init_state([]) 恢复默认 |0...0>；GPUQVM 没有无参重载。
长度必须是 2 的幂；空列表之外的尺寸小于 2、NaN/Inf、范数不为 1 都会抛出 RuntimeError（与 CPUQVM 共用同一套校验）。
GPUQVM 只在 CUDA 构建中绑定；无 CUDA 构建中 pyqpanda3.core.GPUQVM 为 None，用 simulator_capabilities("GPUQVM").available 判断。

NOTE

上述示例需要启用 CUDA 的 pyqpanda3 构建，未在本机执行。

升级提示

以前用 try/except RuntimeError 捕获服务端任务失败的代码，改为检查 job_status() == JobStatus.FAILED 并读取 error_message()。
传输层异常仍然存在：网络、协议或 HTTP 错误仍可能抛出，请保留对应的 try/except。
QCloudService(api_key, url=...) 写法仍然有效；单参写法现在会按 key 中的域名连接。
只有依赖 result() 抛异常的控制流需要调整。

完整的 API 变更清单见 v0.5.1 发布说明；云服务细节见 QCloudService 与 QCloudJob，随机电路见随机线路，GPU 初态见模拟器。

一个 API key，直接连到正确的服务 ​

纠错模式成为可配置项 ​

失败任务不再用异常表达 ​

随机电路跟随芯片拓扑 ​

GPU 模拟器的初态 ​

升级提示 ​

一个 API key，直接连到正确的服务

纠错模式成为可配置项

失败任务不再用异常表达

随机电路跟随芯片拓扑

GPU 模拟器的初态

升级提示