【代码贡献】修复 QARM 支持度与关联规则结果错误

[OnerGit]

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

一、问题 / Problem

当前 QARM 实现在合法 transaction dataset 上可能返回错误的 frequent-itemset support 和 association rules，甚至产生大于 1 的支持度。

仓库自带 data2.txt 包含 10 条 transaction，其中“面包”实际出现 7 次，因此：

expected support(面包) = 7 / 10 = 0.7

修复前，QARM 的一阶搜索可能恢复出 57 个所谓 matching states：

observed support(面包) = 57 / 10 = 5.7

该错误会沿着：

_find_f1
→ F1
→ higher-order frequent itemsets
→ confidence
→ final association rules

继续传播。

例如：

牛奶 -> 面包

QARM before:      1.00
exact classical:  0.80

因此这不是显示或精度问题，而是最终关联规则结果的 correctness defect。

---

二、原因 / Root Cause

当前 QARM 的一阶搜索对不同 target item 使用同一套、与实际 marked-state 数量 M 无关的 amplitude-amplification schedule。

对当前 QARM 双索引寄存器线路的概率行为验证表明，奇数 t 对应：

t = 1 -> effective Grover k = 0
t = 3 -> effective Grover k = 1
t = 5 -> effective Grover k = 2
t = 7 -> effective Grover k = 3
t = 9 -> effective Grover k = 4

当 target item 较频繁时，原有较深 schedule 会发生 over-rotation，使 unmarked states 的概率反而高于 marked states。

以 data2.txt 的“面包”为例：

N = 64
M = 7

t=3 时 marked states 构成最大概率平台；原 schedule 使用 t=9 时则已经发生明显 over-rotation。

此外，原 _get_result()：

1. 将概率四舍五入到 4 位后判断最大值；
2. 根据 probability dictionary 中 value 的位置推导 basis state。

这会带来两个额外问题：

• 接近但不相等的 probability 可能被错误合并；
• 解码隐式依赖 dictionary enumeration order，而不是实际 basis-state key。

---

三、修复 / Fix

本 PR 保持现有 QARM architecture，只修改一阶搜索所需的最小范围。

1. 3 个及以上 item：固定浅层 t=3

QARM 后续需要的是完整 matching row set，而不是只采样出一个 marked state，因此这里的目标并不是最大化单次 Grover success probability，而是保证：

marked per-state probability
>
unmarked per-state probability

设：

r = M / N

一次有效 Grover rotation 后：

p_marked - p_unmarked = 8(1 - 2r) / N

因此只要：

r < 1/2

即可形成严格 probability separation。

对当前 QARM，当 item 数量不少于 3 时：

items_qubit_number >= 2

且：

M / N <= 1 / 2^items_qubit_number <= 1/4

因此 t=3 足以稳定区分 marked / unmarked states，而不需要预先知道 M 或额外执行 Quantum Counting。

2. 直接按 probability key 解码

_get_result() 现在：

• 使用实际 bit-string key 解码 basis state；
• 使用 math.isclose(..., rel_tol=1e-10) 聚合理论相等的最大概率 states；
• 不再依赖 dictionary value position；
• 过滤 padded transaction states；
• 显式验证 target-item index。

3. Two-item domain 使用 exact classical fallback

当只有两个 item 时：

items_qubit_number == 1

合法输入可能达到：

M / N = 1/2

此时 marked 和 unmarked per-state probability 无法通过 Grover rotation 分离。

因此该完整 domain 直接从 QARM 已有 transaction matrix 精确恢复 matching rows。

这样保持 downstream contract 不变：

matching rows
→ support
→ higher-order row intersection
→ confidence

而不引入 Quantum Counting、随机 unknown-M search 或更大的 architecture rewrite。

---

四、验证 / Validation

Committed regression tests

新增：

test/QARM/Test_QARM_search_correctness.py

覆盖：

• data2.txt 的“面包” row recovery / support；
• 牛奶 -> 面包 confidence；
• dense high-frequency case；
• two-item M/N = 1/2 boundary；
• probability-dictionary ordering；
• 4-decimal rounding impostor；
• padded states；
• existing valid behavior。

执行结果：

python -m pytest -o addopts="" \
  test/QARM/Test_QARM_search_correctness.py -q
# 11 passed

python -m pytest -o addopts="" test/QARM -q
# 12 passed

python -m pytest -o addopts="" \
  test --ignore=test/QARM/Test_QARM_search_correctness.py -q
# 18 passed

python -m pytest -o addopts="" test -q
# 29 passed

Focused regression 连续执行两次均为 11 passed。

Supplementary systematic validation

提交前另使用未随 PR 提交的 deterministic small-dataset validation，对修复进行了补充核验：

35 datasets
116 F1 row comparisons
188 frequent-itemset comparisons
110 pair-rule comparisons
0 mismatches
0 support invariant violations

并覆盖 support / confidence threshold 的 below / equal / above boundary。

上述 systematic sweep 属于补充验证；PR 中可直接复现的权威 regression 仍为本次提交的测试文件。

---

五、资源影响 / Resource Impact

修复后的 3+ item quantum path 固定使用：

t = 3

而原实现代表性 case 使用 t = 5 或 t = 9。

在 9 个 correctness-aware benchmark case 中：

fixed QARM: 9/9 correct
old QARM:   6/9 correct

在 old / fixed 都正确的 6 个 case 中，修复版本的 median runtime 均较低。

这里的主要目标仍然是 correctness；runtime 变化仅作为 resource impact 记录，不作为独立性能优化 claim。

---

六、兼容性与行为变化 / Compatibility

• Public constructor / run() API：不变；
• Return dictionary structure：不变；
• 新增第三方依赖：无；
• 3+ item path：继续使用 QARM quantum search；
• two-item path：改为 exact classical singleton-row recovery。

一个有意的细微行为差异是：

two-item F1 path 不再构建 quantum search circuit，因此该路径下 show / file_name 对 F1 circuit visualization 不生效。

CPUQVM 路径已实际验证。

QCloud full_amplitude 路径从源码和 probability-dictionary contract 上与本修复兼容，但本 PR 未使用实时 QCloud credentials 执行验证。

本修复依赖当前 QARM 使用的完整理想 probability distribution 来恢复最大概率平台，不声称等价适用于 finite-shot sampling。

---

七、已知限制 / Known Limitations

1. _get_all_conf() 的规则枚举范围

当前 _get_all_conf() 主要生成 (k-1) -> 1 类型规则，并不完整枚举所有 multi-item consequent。

这是与本次 F1 quantum-search correctness 独立的既有问题，本 PR 不扩大范围处理。

2. 本 PR 修复的是当前仓库实现

本 PR 的目标是：

fix the current pyqpanda-algorithm QARM implementation

不声称修改或修复原始 QARM 论文中的完整算法架构。

---

八、Related Work / Non-overlap

• 【代码贡献】修正 Grover 最优迭代次数计算，补充输入校验与依赖声明 #36 修正 generic Grover 在已知 marked-state 数量 M 时的最优 iteration selection。
  本 PR 中 QARM 的 M 未知，而且目标是从完整 probability distribution 恢复完整 matching row set，因此问题和 repair objective 不同。

• 【代码贡献】Add quantum counting (BHT) built on the existing Grover operator #47 新增 Quantum Counting，通过 phase estimation 估计 M。
  本 PR 利用当前 QARM domain 的 M/N 上界，在 3+ item 情况下无需先估计 M。

因此两者与本 PR 技术相关，但不存在直接实现重复。

---

English Summary

This PR fixes a correctness defect in the current QARM implementation that can produce impossible support values and incorrect association rules on valid transaction datasets.

• On the bundled data2.txt, bread appears in 7 of 10 transactions, so its exact support is 0.7; before the fix QARM can recover 57 states and report 5.7.
• The incorrect F1 result propagates into confidence values and final rules; for example, milk -> bread is reported as 1.00 instead of the exact 0.80.
• The main cause is an M-independent amplification schedule that can over-rotate dense marked sets. For the current two-index-register QARM circuit, odd t follows k=(t-1)/2 effective Grover rotations.
• For three or more items, M/N <= 1/4, so t=3 provides marked/unmarked probability separation without first estimating M. The two-item domain uses exact classical row recovery because M/N can reach 1/2.
• Probability results are now decoded from their actual bit-string keys, using a tight floating-point tolerance and explicit transaction/item filtering instead of rounded values and dictionary positions.
• The committed focused regression suite has 11 cases; the full explicit test tree is 29 passed. A separate deterministic 35-dataset validation produced zero F1, frequent-itemset or pair-rule mismatches against an exact classical reference.
• No public API or output-shape change is introduced, and no new third-party dependency is required.
• The repair assumes the current ideal full-probability-distribution execution model. QCloud full_amplitude compatibility was reviewed from the source path but was not live-tested with credentials. Higher-order consequent enumeration in _get_all_conf() remains a separate pre-existing limitation.