【代码贡献】修复 QAOA 寄存器宽度及 Hamiltonian 输入

[youshen2025]

队伍 youshen，关联本源杯任务 #13，目标分支 develop。

问题与行为变化

QAOA(PauliOperator({'Z2': 1.0})) 原来只分配 1 比特，随后访问 qlist[2]
抛出 IndexError；Z0 Z3 同样只分配 2 比特而需要 4。构造器用出现的索引
数量作为宽度，但能量计算和成本线路使用原始索引，二者不一致。

QUBO 适配器还会丢失零系数变量：声明两个变量、线性系数 [0, 1] 时，只返回
'0' / '1'；系数 [0, 0] 时返回 {'': 1.0}。修复后保留声明的全部变量，
这些例子均返回两位字符串。多项式中的系数相消也不再缩短输出。

同一构造路径上的 QAOA(Hamiltonian({'Z0': 1.0})) 原来调用不存在的
Hamiltonian.terms()；实际项迭代接口属于已转换出的 self.operator。

改动

• PauliOperator / Hamiltonian 输入以 max(indices, default=-1) + 1 分配寄存器。
• Hamiltonian 项迭代改用 self.operator.terms()。
• QUBO 适配器明确传递已知的变量数量，保留目标函数没有用到的变量及其位置。
• 更新输入、宽度与 QUBO 返回值文档；激活能量测试，增加 QUBO 端到端回归。

没有重新编号算符。Z2 使用 3 比特，Z0 Z3 使用 4 比特；自定义线路仍接收
原始地址。QUBO 返回字符串左侧对应第一个变量，仍包含全部声明变量。

验证原理

算符测试独立计算全部基态的 Z 奇偶能量，用解析对角相位和 RX(-2 beta)
演化状态向量，与真实 CPUQVM 完整概率比较，绝对容差 1e-12；另验证能量接口。

QUBO 测试直接从输入矩阵计算每个原始赋值的 x^T A x + b^T x + c，再构造
稠密相位和张量积混合矩阵。固定种子 7、将 SLSQP 迭代预算设为 0，比较初始
参数下真实成本线路、混合线路和 CPU 结果的全部概率；未 mock 优化器或模拟器，
没有以经典答案替换量子结果。测试后恢复随机状态。

覆盖两种算符输入、前端/内部地址空位、Z10 的 11 比特寄存器、一层/两层、
常数偏移、连续编号、自定义初态、恒等算符的零宽度构造与能量计算；QUBO
另覆盖首尾及多个无效变量、二次项、系数相消、常数目标和普通稠密问题。

测试结果

• 算符回归在原上游上 21 失败 / 3 通过；QUBO 回归在适配器修复前 6 失败 / 2 通过。
• Python 3.12.3 完整测试 50 通过（7.79 s：18 原有 + 32 新增）。
• Python 3.11.16 / 3.13.11 各 32 项新回归通过（2.13 / 2.10 s）。
• 新测试 Ruff lint/format、依赖兼容及保留 CRLF 的 diff 检查通过。

环境为 PyQPanda3 0.4.1；3.12/3.13 使用 NumPy 2.5.3、SciPy 1.18.1，3.11
使用 NumPy 2.4.6、SciPy 1.17.1。3.11 本轮有 7 条原有文档转义弃用警告。
跨版本复用项目虚拟环境，以 PYTHONPATH 指向此次独立 checkout。
以上为本地 CPU 验证，尚无本 PR 的远程 CI 结果。

在安装本项目和测试依赖的项目 .venv 中运行：

OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 .venv/bin/python -m pytest -c test/pytest.ini -o addopts='' test/QAOA/Test_qaoa_QAOA_calculate_energy.py test/QAlgBase/Test_QUBO_QAOA_register.py --timeout=60 -q
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 .venv/bin/python -m pytest -c test/pytest.ini -o addopts='' test --timeout=60 -q

测试依赖 pytest、pytest-timeout、allure-pytest 及上游导入链所需的
pandas/scikit-learn 安装在项目虚拟环境。本次没有包级依赖改动。

范围与查重

基于官方 develop 5f973ef，四个文件只涉及上述输入/寄存器语义及回归。
2026-09-22 检索 sparse、problem_dimension、Hamiltonian terms，并核对
#39/#40/#45/#61 的实际修改范围：#40 的风险目标、#45 的默认层数与本修复
不同。本次测试显式传入 layer=1，没有包含默认层数、mixer 或 GAS 的独立修复。

这是正确性修复，最高地址很大时仍有指数级模拟开销。未扩展一般非对角算符、
真实硬件或全局最优保证。纯恒等算符本身没有声明变量数量；只在具有显式变量
数量的 QUBO 输入路径保留常数目标的全部赋值。

附加集成验证：独立本地 checkout 合并应用 #92 与 #95/#96/#97/#98 的当前
修复后，Python 3.11 / 3.12 / 3.13 各 242 项测试全部通过（26.28 / 29.41 /
25.09 s），应用覆盖率均为 98.92%。其他 PR 的改动没有加入本分支；这些是
本地兼容性证据，不代替上游审核或 CI。

合并交互检查：另在本地合并第三方开放 #45（f829357）、#69（6f0fcb2）、
#36（e1992fb），均自动合并无冲突；Python 3.12 的 264 项测试通过（37.15 s），
应用覆盖率 98.92%。该记录仅覆盖这些提交的本地兼容性；他人的代码不进入本 PR。