〖创新应用〗新增 PyBF-DCQO 算法族：原生 HUBO、自适应采样与组合优化应用

[QmuseAI]

概要

本 PR 为 pyqpanda-algorithm 新增 pyqpanda_alg.BFDCQO，提供模块化 BF-DCQO 算法族、QUBO/原生 HUBO 问题表示、组合优化应用、PyQPanda3 CPUQVM 后端和可复现的小规模验证。PR 以中文文档为主，并保留 NumPy 参考后端用于逐基态与概率分布交叉检查。

主要改动

• 新增统一 BFDCQOConfig / BFDCQOSolver API，以及 Basic、CVaR、自适应 shot、Adaptive-CVaR、Hybrid 变体。
• 新增 IsingProblem、PolynomialIsingProblem，支持二次 Ising/QUBO 与一般阶对角 Pauli-Z/HUBO。
• 新增加权 MaxCut、加权 MAX-3-SAT、MWIS 建模和精确小规模参照。
• PyQPanda3 后端使用 CPUQVM 理想概率执行 BF 电路，并用带种子的 NumPy multinomial 实现有限采样反馈。
• 对照路径直接调用仓库公开 pyqpanda_alg.QAOA 的 CPUQVM shot execution；适配器记录实际 optimizer/circuit 调用和观测 shots。
• 新增四个示例、中文模块 README、Sphinx AutoAPI 入口、CPUQVM 验证脚本、92 个 BF-DCQO 测试和聚合 benchmark 证据。

API 示例

from pyqpanda_alg.BFDCQO import BFDCQOConfig, BFDCQOSolver, MaxCutProblem

problem = MaxCutProblem.from_edges(
    5,
    [(0, 1), (1, 2), (2, 3), (3, 4), (4, 0)],
).to_ising()

config = BFDCQOConfig(
    variant="adaptive_cvar",
    iterations=6,
    shots=512,
    total_shot_budget=3072,
    cvar_alpha=0.10,
)
result = BFDCQOSolver(
    problem, config, backend="pyqpanda", seed=7
).solve()

CPUQVM 验证

本地环境为 Python 3.13.9、pyqpanda-algorithm 2.0.0、PyQPanda3 0.3.5。CPUQVM 验证覆盖：

• 非回文 bitstring 001 的 q0/小端序检查；
• NumPy 与 PyQPanda3 理想概率一致性；
• 真实 CPUQVM shot counts；
• 4 个示例的 BF 与上游 QAOA 路径；
• CPUQVM 直接 verifier 运行结果 PASS；
• 完整 BF-DCQO 测试 92 passed（含无 PYTHONPATH verifier 回归）、仓库 test 全量 110 passed in 36.44s。

BF benchmark 的执行模型是 PyQPanda3 CPUQVM ideal probabilities + seeded NumPy multinomial feedback sampling。BF 的 total_shots 是反馈采样预算/资源代理，并非 CPUQVM measurement 实测数。上游 QAOA 的执行模型是 pyqpanda_alg.QAOA.CPUQVM shot execution，其 total_shots 按 observed circuit_evaluations × shots 记录。

上游 QAOA 预算核算

官方小规模 benchmark 使用 3 个种子。目标预算为 (max_evals + 2) × shots，下表记录实际观测结果：

问题	backend	observed circuit evaluations	observed total shots	目标预算	delta
MaxCut	pyqpanda_alg.QAOA.CPUQVM	24	6144	6144	0
MAX-3-SAT	pyqpanda_alg.QAOA.CPUQVM	24	6144	6144	0
MWIS	pyqpanda_alg.QAOA.CPUQVM	6	72	72	0

Benchmark 边界

证据只覆盖允许精确求解校验的小实例，每组 3 个种子。MAX-3-SAT 的 native HUBO 在两个 fixture 中使用 5 个逻辑量子比特，而 Rosenberg 二次化 QAOA 使用 8–9 个量子比特和 3–4 个辅助变量；与此同时，native 路径观测到的最大 Pauli 权重为 3，QAOA 二次路径为 2，因此不能只以量子比特数判断总资源。

MWIS 等成本消融中，Hybrid-random 跨实例平均 best-weight ratio 为 0.970314，Hybrid-confidence 为 1.000000；两者使用相同的 72 shot 预算与每次 16 个局部评估。这只是固定小图上的观测结果，不外推到其他图族。

这些数据不构成量子优势证据，也不支持 BF-DCQO 对 QAOA 或其他优化器普遍优越的结论。

方法归属与贡献边界

• Basic BF-DCQO 核心协议归于 A. Gomez Cadavid 等人的 Bias-field digitized counterdiabatic quantum optimization（Physical Review Research 7, L022010, 2025；arXiv:2405.13898）；MWIS 也是该原始 BF-DCQO 工作已经展示的应用，本 PR 不主张首次将 BF-DCQO 应用于 MWIS。
• native HUBO、CVaR BF-DCQO 与 MAX-3-SAT 构造归于 S. V. Romero 等人的 Bias-Field Digitized Counterdiabatic Quantum Algorithm for Higher-Order Binary Optimization（Communications Physics 8, 348, 2025；arXiv:2409.04477）。
• 经典 refinement 的先行概念参见 Hybrid Sequential Quantum Computing（HSQC）；本 PR 提供受预算、可记录评估次数的工程化实现和等成本消融，不主张这些概念的原创性。

本 PR 的工程贡献是面向 PyQPanda 的独立实现、统一 API、通用多项式 Ising 表示、有限采样/预算记录、CPUQVM 交叉验证与可复现实验基础设施。

测试与工具状态

• python -m pytest -q -c NUL test/BFDCQO：92 passed（含无 PYTHONPATH verifier 回归）。
• python -m pytest -q -c NUL test：110 passed in 36.44s。
• python scripts/verify_pyqpanda_cpuqvm.py：PASS。
• compileall：通过。
• 公共 API docstring：缺失 []。
• 10 个数学冻结文件与原始交付 SHA-256 全部一致。
• 本地安装 sphinx-autoapi 和 sphinx-material 后，Sphinx HTML 构建退出码 0，BFDCQO 页面已生成。构建结果为 build succeeded, 222 warnings；警告主要来自全仓已有的旧模块 docstring、Graphviz 和静态资源问题。
• 包级 mypy 检查 34 个源文件；非冻结的 Pauli/CPUQVM recipe 类型告警已通过显式类型修复，剩余 7 个错误仅位于 applications/max3sat.py、applications/mwis.py、solvers/bfdcqo.py 三个数学冻结文件，未擅自修改算法。

扩展性限制

当前求解器保留完整概率分布和精确基态诊断，NumPy 参考路径使用完整状态向量。这些机制适用于小规模回归和研究 benchmark，但会随变量数指数增长。count-only 后端、可选精确诊断以及面向设备的编译/噪声评估不在本 PR 范围内。

Relates to #13