pyqpanda3 v0.3.5 是一个功能丰富的版本更新，带来了社区中最受期待的可视化模块、更好的云端任务执行可观测性，以及多个正确性 Bug 修复。

可视化模块

我们引入了 pyqpanda3.visualization 模块 —— 一个全面的工具包，用于渲染量子线路、绘制 Bloch 球以及可视化量子态向量和概率分布。该模块基于 matplotlib 构建，既支持简洁的单行函数调用，也提供详细的绘图 API：

from pyqpanda3 import visualization
from pyqpanda3.core import H, X, CNOT, measure, QProg

# 线路绘制（ASCII 图形）
prog = QProg()
prog << H(0) << X(1) << CNOT(0, 1) << measure(0, 0) << measure(1, 1)
print(prog.draw())

对于量子态可视化，你可以生成 city 图、密度矩阵和 Bloch 球表示：

from pyqpanda3.core import H, CNOT, QProg, CPUQVM

qvm = CPUQVM()
prog = QProg()
prog << H(0) << CNOT(0, 1)
qvm.run(prog)
state = qvm.get_qstate()

# City 图、密度矩阵或 Bloch 球
visualization.plot_state(state, kind='city', title='State City Plot')

可视化模块还包含线路统计功能 —— 门数量、深度和宽度 —— 可通过 circuit_info() 函数访问。完整参考请参阅可视化 API 文档。

改进的云服务错误处理

此前，当云端任务失败时，SDK 会抛出未处理的异常，使得在生产流水线中诊断问题变得困难。现在，错误信息存储在 QCloudResult 对象中，可以优雅地获取：

result = job.result()
if result.error_message():
    print(f"Job {result.job_id()} failed: {result.error_message()}")

我们还为 QCloudResult 添加了 job_id() 方法，让你始终能追踪哪个任务产生了给定的结果 —— 这在并行运行多个任务时特别有用。

ECHO 门支持时长参数

ECHO 门现在接受可选的 param 参数（默认值 0.0），使脉冲级线路设计更加灵活：

from pyqpanda3.core import ECHO
gate = ECHO(0, param=1.5)

转换器修复

本次发布修复了转换器流水线中的多个问题：

• QProg.remap() 现在在重映射前先展平嵌套程序，修复了包含子线路或条件块的程序中量子比特/经典比特映射不正确的问题。
• VF2 子图匹配 不再在具有非连续量子比特索引或断开拓扑节点的线路上失败。
• 路由阶段 现在能正确处理 BARRIER 门和未映射的辅助量子比特。
• 空拓扑 —— 当芯片没有连接边时，转换器现在自动跳过路由，而不是报错。

任务执行计时

当你向云端提交量子任务时，了解时间花在哪里对于优化至关重要。v0.3.5 为 QCloudResult 添加了 timing_info() 方法，返回一个包含量子任务执行时间信息的字典：

result = job.result()
timing = result.timing_info()

print(f"QPU runtime: {timing['qpuRunTime']} ms")

字典中包含 qpuRunTime（float）字段，记录任务在量子芯片上实际执行并完成测量所占用的时间，单位毫秒（ms）。如果特定任务的时间数据不可用，值默认为 0。

Bug 修复

本次发布修复了多个可能影响量子计算正确性的 Bug：

量子云错误报告。 错误消息现在包含任务 ID 以便于调试，大比特系统（32+ 量子比特）的结果计数不匹配问题也已解决。以前，例如当量子云返回 4000 条结果时，结果对象中只有 2600 条可用。

Measure 接口修复。 measure() 函数之前错误地将量子比特索引同时作为量子比特和经典比特参数传递。如果你将量子比特测量到不同的经典比特上，结果可能会悄无声息地出错。现已修正。

带噪声模型的期望值计算。 在没有 GPU 的机器上，使用噪声模型计算期望值（expval_hamiltonian 和 expval_pauli_operator）之前会失败。现在在纯 CPU 系统上也支持这种组合。

矩阵分解。 decompose 函数在处理 1-2 量子比特矩阵时会错误地对量子比特索引进行排序。现在对这些小矩阵跳过排序，修复了单量子比特门和双量子比特操作的分解结果。

IDLE 门序列化。 我们修复了 IDLE 门参数的两个问题：一个解码 Bug 错误地使用了基于角度的公式，以及一个将参数限制在 16 位的范围问题。参数现在支持完整的 32 位范围（0–4,294,967,295），对于超过 65535 的值使用双 uint64 编码。

空线路性能分析。 QCircuitFeatures 性能分析模块在计算空线路的指标时会因除零错误而崩溃。这些边界情况现在已正确处理。

破坏性变更

QCloudResult 构造函数现在需要两个参数：QCloudResult(result_string, job_id_str)。实际上，大多数用户通过 QCloudJob.result() 或 QCloudJob.query() 获取 QCloudResult 对象，因此这不应影响典型的工作流程。

API 变更

expval_hamiltonian 和 expval_pauli_operator 的第一个参数已从 node 重命名为 prog，以提高可读性：

# 更新后的关键字参数用法：
expval_hamiltonian(prog=prog, hamiltonian=ham, shots=1000)

这只是关键字参数的变更 —— 位置参数的用法仍然照常工作。

后续计划

我们正在专注于扩展可视化模块的新绘图类型，以及改进更大规模线路的仿真性能。同时，多个云服务改进也在进行中。