0.5.1
pyqpanda3 v0.5.1（2026-10-27）是 0.5.0 的维护与云服务增强版本。此版本的主题是 QCloud 接入与纠错配置、失败任务的结果语义、遵循芯片拓扑的随机电路，以及 GPU 模拟器的初态接口；此外还包含若干不改变 Python API 的稳定性与回归测试改进。
1. QCloud 服务地址从 API key 解析
QCloudService(api_key) 新增单参构造：新格式 API key 自带服务域名，pyqpanda3 解析该域名并直接连接对应的服务。旧格式 API key 不携带域名，回退到历史默认云端端点。
QCloudService(api_key, url) 仍然可用，url 显式覆盖 API key 中编码的域名，用于测试或私有部署。0.5.1 绑定中 url 已无默认值：需要自行指定地址时必须显式传入。
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
上述示例需要云端凭据与真实任务，无法在本地执行。
2. 可配置的纠错模式与串扰抑制
QCloudOptions(...) 现在支持关键字构造，默认值为：amend_flag=1、use_cz_pattern=False、mapping=True、optimization=True、point_label=1、is_prob_counts=True、specified_block=[]。
amend_flag 选择结果纠错模式：0 关闭纠错，1 启用全局采样纠错，3 启用局部实时纠错。use_cz_pattern 控制串扰噪声抑制。
新增 set_amend_flag / amend_flag 与 set_use_cz_pattern / use_cz_pattern 方法；原有的 set_amend 及其他设置方法保持不变。
QCloudOptions.print() 的输出字段随之调整：现在输出 is_prob_counts、amend_flag、use_cz_pattern、mapping、optimization、point_label（以及自定义选项），不再输出 amend。
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()NOTE
上述示例中的选项对象可在本地构造；实际提交任务仍需云端凭据与真实任务，无法在本地执行。
3. 失败任务不再抛异常
QCloudJob.result() 只在任务状态为 WAITING / COMPUTING / QUEUING 时继续轮询；FINISHED / FAILED 会立即返回。
服务端报告的任务失败不再抛出 RuntimeError，而是返回一个 QCloudResult：其 job_status() == JobStatus.FAILED，error_message() 给出失败原因（优先取 obj.errInfo，其次取 message，最后取 errCode）。网络、协议或 HTTP 等传输层错误仍可能从底层请求抛出。
from pyqpanda3.qcloud import JobStatus
# job = backend.run(...)
result = job.result()
if result.job_status() == JobStatus.FAILED:
print("failed:", result.error_message())
else:
print(result.get_probs())NOTE
上述示例需要云端凭据与真实任务，无法在本地执行。
4. 随机电路遵循芯片拓扑
新增了带拓扑约束的随机电路生成：
random_qcircuit(qubits, depth, gate_type, topology)random_qprog(qubits, depth, gate_type)random_qprog(qubits, depth, gate_type, topology)
topology 是边列表，格式与 ChipInfo.get_chip_topology() 相同，例如 [[0, 1], [1, 2]]。生成时每个双比特门只会落在给定的边上，单比特门不受此限制。若某条边引用了 qubits 之外的比特，函数抛出 ValueError。
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())5. GPUQVM 支持指定初态
GPUQVM.init_state(state) 装入后续 run() 使用的初态矢量，长度必须是 2 的幂；init_state([]) 恢复默认 |0...0>。未调用 init_state 时，模拟器默认从 |0...0> 开始。非法长度、包含 NaN/Inf 或未归一化的状态抛出 RuntimeError。
GPUQVM 只在 CUDA 构建中可用；无 CUDA 构建中 pyqpanda3.core.GPUQVM 为 None（导入时发出 ImportWarning），无法构造。可用 simulator_capabilities("GPUQVM").available 判断当前构建是否提供该后端。
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}NOTE
上述示例需要启用 CUDA 的 pyqpanda3 构建，未在本机执行。
6. 其他修复与稳定性改进
- 光量子 pilot 后端将连续单门合并，避免逐个输出 U3 门。
- 转译器的内存归还与构建稳定性改进。
- 补充 API 契约、随机电路拓扑、QVM 初态与 QCloud API key 域名等回归测试。
API 变更
| 接口 | 0.5.1 变化 |
|---|---|
QCloudService(api_key) | 新增单参构造；从新格式 key 解析服务域名 |
QCloudService(api_key, url) | url 不再有默认值；显式覆盖 key 中的域名 |
QCloudOptions(...) | 支持关键字构造 |
QCloudOptions.set_amend_flag / amend_flag | 新增；0/1/3 |
QCloudOptions.set_use_cz_pattern / use_cz_pattern | 新增 |
QCloudJob.result() | 服务端报告的任务失败不再抛 RuntimeError；返回 FAILED 结果；传输层错误仍可能抛出 |
random_qcircuit(..., topology) | 新增重载 |
random_qprog(...) | 新增函数，含 topology 重载 |
GPUQVM.init_state(state) | 新增 |
升级提示
- 以前用
try/except RuntimeError捕获服务端任务失败的代码，应改为检查job_status() == JobStatus.FAILED并读取error_message()。 - 传输层异常仍然存在：网络、协议或 HTTP 错误仍可能从底层请求抛出，请不要移除对这些异常的
try/except处理。 QCloudService(api_key, url=...)写法仍然有效；单参写法现在会按 key 中的域名连接。- 只有依赖
result()抛异常的控制流需要调整。