【代码贡献】优化 QSEncode Walsh 变换与 Top-K 筛选性能

[omegaxyv]

关联 Issue：#13（2026 本源杯开源创新赛道｜代码贡献）
参赛队伍：Basia

简介

QSpare_Code 在 Walsh 稀疏编码预处理中存在两个性能热点：

1. sympy.fwht 会将纯数值输入带入 SymPy 符号对象流水线，带来较高的 Python 对象与内存分配开销。
2. 原 Top-K 筛选使用完整 numpy.argsort，即使只保留少量系数，仍需对所有 N 个幅值排序。

本 PR 将两条热路径改为原生 NumPy 数值实现，并增加独立正确性测试和可复现基准。

主要修改

• 新增 _fast_walsh_hadamard_transform：
  • 使用 NumPy ufunc 和可复用 scratch 缓冲区执行蝶形计算；
  • 保持非 2 的幂输入补零语义；
  • 保持原生数值 dtype，不产生 object 数组；
  • 时间复杂度 O(N log N)，辅助空间 O(N)。
• 将 Top-K 选择由完整 argsort 替换为 argpartition，平均时间复杂度由 O(N log N) 降为 O(N)。
• 等幅值跨越 Top-K 截断边界时，明确按较大原索引优先保留，保证结果可重现。
• 增加一维/数值/有限值校验，以及空输入、n >= N 快路径。
• 新增 30 个参数化用例和一个旧/新实现性能基准脚本。

注：原 sympy.fwht 本身也是 O(N log N) 快速变换。FWHT 加速主要来自减少符号对象、Python 常数和临时分配，而不是改变渐进时间复杂度。

正确性与测试

• 使用独立 Sylvester Hadamard 稠密矩阵对拍 FWHT；
• 覆盖空/单元素/非 2 的幂/实数/复数输入和长度 1–64；
• 覆盖 0–12 比特归一化变换的范数保持与自反演；
• 覆盖 Top-K 复数、并列边界、快路径与非法输入；
• 覆盖 2 组 Quantum_Res() 端到端概率分布对拍。

本地定向测试（新增 30 例 + 原有 1 例）：

31 passed in 0.87s

性能数据

环境：Python 3.11.6，NumPy 2.4.6，SymPy 1.14.0，PyQPanda3 0.3.2。每组重复 3 次取中位数，最小采样时间 0.02 s。结果为单机参考，不作为跨平台保证。

FWHT N	SymPy 基线	NumPy 优化	加速比
256	16.020 ms	55.6 µs	287.9×
1,024	74.826 ms	87.4 µs	856.3×
4,096	427.510 ms	193.3 µs	2,211.3×
16,384	1.915 s	627.3 µs	3,052.7×

N=4,096 时，tracemalloc 跟踪的 Python 峰值分配由 0.855 MiB 降为 0.080 MiB，约降低 10.7 倍。

Top-K N	K	完整 argsort	argpartition	加速比
16,384	163	377.6 µs	135.9 µs	2.8×
262,144	2,621	9.728 ms	2.362 ms	4.1×
1,048,576	10,485	68.358 ms	15.736 ms	4.3×

N	电路构建加速	Quantum_Res 加速	最大误差
256	9.9×	4.9×	0.0e+00
1,024	11.3×	6.0×	0.0e+00

兼容性说明

• QSpare_Code 公共 API 和方法签名不变。
• Fourier 模式未修改。
• Walsh 对常规一维有限数值输入保持算法语义，只可能存在浮点舍入差异。
• 输入更严格：多维数组、NaN 和 Inf 现在会抛出明确异常。
• 并列幅值跨越 Top-K 边界时，新实现使用明确的较大索引优先策略；该边界下的系数选择可能与旧的默认非稳定排序不同。
• 本 PR 只从 QSEncode Walsh 热路径移除 sympy.fwht，不移除整个项目的 SymPy 依赖。

复现

PYTHONPATH=pyqpanda-algorithm python -m pytest \
  -c test/pytest.ini -o addopts='' -p no:cacheprovider \
  test/QAlgBase/Test_QSEncode_numeric_pipeline.py \
  test/QAlgBase/Test_class_basic_sparecode_QSpare_Code.py -q

python benchmarks/benchmark_qsencode.py \
  --repeats 3 \
  --minimum-sample-time 0.02

变更文件

• pyqpanda-algorithm/pyqpanda_alg/QSEncode/QSEncode.py
• test/QAlgBase/Test_QSEncode_numeric_pipeline.py