【代码贡献】修复 QAOA 环形 XY mixer 的单比特守恒与奇数环闭合

[youshen2025]

【代码贡献】修复 QAOA 环形 XY mixer 的单比特守恒与奇数环闭合

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

问题与修复

parity_partition_xy_mixer 用于在固定激发数子空间内混合候选，但两个边界不符合
其环形 XY 定义：单比特域使用 RX，会改变激发数；奇数比特域没有加入首尾作用，
实际构造的是一条开放链。两者都可通过 xy_mixer(..., 'PXY') 影响调用者。

例如在 |1> 上使用 beta=0.37，旧实现产生约 0.1307657206 的 |0> 概率；
三个比特的旧线路只有两次 XY 作用（4 个 CNOT），缺少第三次首尾作用。

本 PR 限定修改两个现有文件：

• 空域与单比特域返回恒等线路；单比特不再离开原激发数子空间。
• 奇数环的最后一对放在第三分区执行；偶数环的原有作用次序与角度保留。
• 双比特仍只作用一次，不重复加入首尾边。
• 更新函数类型标注与文档，明确分区次序、退化边界和沿用的角度符号。
• 将原本全部注释的 Test_parity_partition_xy_mixer.py 替换为可自动收集的回归测试。

数学依据与兼容边界

令 H_ij = X_i X_j + Y_i Y_j，每个两比特作用保持激发数。沿用当前库的角度约定，
调用 iswap(i, j, -2*beta) 对应 exp(+i*beta*H_ij)，本次不改变其符号或归一化。
先执行互不重叠的偶起点边，再执行奇起点边；奇数环的首尾边单独执行。
参考 Hadfield 等论文第 4.1.1 节、公式 (7)–(9) 的
parity ring 分区定义。

分区乘积一般不等于整个环哈密顿量之和的精确指数，测试比较的是正确的分区乘积。
单比特域的 XY 边集合为空，因此是恒等作用。修复会有意改变单比特和奇数环的
旧输出；不改变 complete_xy_mixer、优化器、风险目标或其他算法。

验证

测试用独立稠密矩阵表达 XX+YY，通过 SciPy expm 构造参考分区演化，
在真实 PyQPanda3 CPUQVM 上逐个计算基态运行线路，比较全部复数振幅。
覆盖 1–6 比特、正/负/零角度、奇偶环、非连续/乱序比特及旁观比特，
并覆盖整数分组和显式混合大小分组，检查每个域的激发数守恒。
无真实硬件、API Key、测量统计容差或模拟器 mock。

• 上游未修改基线：18 项测试通过。
• 新回归在修复前：13 失败、11 通过；修复后：24 项全部通过。
• Python 3.12.3 常规完整测试收集：42 项通过（18 原有 + 24 新增），8.01 s。
• Python 3.11.16 / 3.13.11：同一修复源码的 24 项 CPU 回归分别通过。
  使用已有项目虚拟环境，以 PYTHONPATH 指向独立修复 checkout，并核验实际导入路径。
• 新测试 Ruff lint/format、环境 pip check 通过。保留源文件原有 CRLF，
  使用 git -c core.whitespace=cr-at-eol diff --check 核查补丁空白。
• Python 3.11 仍有 15 项已有文档字符串转义弃用警告，未扩大范围修改其他函数。

主要环境：PyQPanda3 0.4.1、NumPy 2.5.3、SciPy 1.18.1；Python 3.11 环境为
NumPy 2.4.6、SciPy 1.17.1。全部为本地 Linux 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_parity_partition_xy_mixer.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

无依赖环境时，可先在仓库根目录使用 Python 3.12 创建 .venv，安装本地包、
PyQPanda3 0.4.1、pytest、pytest-timeout、allure-pytest，以及现有上游导入链
所需的 pandas/scikit-learn。此 PR 不调整全仓库依赖，避免重复已有依赖修复 PR。

查重与范围

2026-09-22 检查开放/近期关闭 PR，检索函数名和 XY mixer，并核对涉及 QAOA
的 #6/#7/#40/#61 文件范围；未发现相同修复。分支直接基于官方 develop
5f973efccb84bc193157d1ccebe32137e307293b，不包含独立调度应用 PR #92 的改动。
本贡献是库函数正确性修复，不宣称新算法或量子优势，也不预设多 PR 对应多份奖励。

附加集成验证：独立本地 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。