Skip to contents

U-M4-01 设计备忘：ms_compare() 校准相似度库

Source: vignettes/articles/devlog-2026-10-04-M4-01-design-memo.qmd

日期：2026-10-04（夜间窗口批次）。状态：设计冻结 + 实现开工。 依据：CAPABILITY-MATRIX L-F 行（“cosine（零校准）/correlation/JSD/Hellinger ✅ M4、Hungarian 一对一（主）+ Islam 贪心 + Jiang 活性三协议 ✅ M4”）；ARCHITECTURE §指标（“主指标 = Hungarian 一对一匹配的 P/R/F1；贪心 max-cosine + 阈值扫 0.80–0.90 为鲁棒性附录；Jiang Combined Score 与 Islam 协议逐位复刻（语义层 golden）”）；research/07 §1.20 三协议精确定义；research/07 §3.3（“多度量 + 解析/经验零分布（按通道数×负荷）+ 三协议精确参考实现”）。 v0.2 验收门依赖：Jiang 协议（活性>0 匹配 + Combined Score）对标——本单元交付协议参考实现后，对标 bench 才有可跑的机器。

§1 估计对象与度量（全部冻结定义）

输入统一为列归一 share 向量（每签名先除以自身通道和；零向量保持零并记 degenerate，度量按 NaN 传播、由校验拦截）。矩阵口径：estimated m×k_est、reference m×k_ref。

度量 冻结定义 备注
cosine ⟨p,q⟩/(‖p‖‖q‖) 逐位主度量；零向量 → NaN
correlation Pearson(p,q)（在 share 上中心化） 常数向量 → NaN
jsd √(½KL(p‖m)+½KL(q‖m))，m=½(p+q)，log₂ 开方后是度量（metric）；0log0=0
hellinger (1/√2)‖√p−√q‖₂ 值域 [0,1]

【逐位】验收：四度量各有纯 R 孪生对拍（同数学量、双侧一致），与 BH 孪生模式同款。

§2 零分布（D13 口径：估计对象=零分布分位数；生成模型=下列冻结族；校准协议=MC；失败条件=MC-SE 超限结构化报错）

签名零分布（按通道数）——两个独立均匀 Dirichlet(1,…,1)（= 归一化 i.i.d. Exp(1)）签名的 cosine 分布： - 经验面：Rust MC（PCG64 冻结流；Exp(1)=−ln U，U 取自标准布局 uniform 面），返回 mean/sd/分位（type-7 经验分位，与 bootstrap percentile CI 同约定）。 - 解析锚（exact 矩恒等式）：E⟨x,y⟩=1/m、E‖x‖²=2/(m+1)；delta 近似 E[cos]≈(m+1)/(2m)（大 m 渐近，允许 O(1/m) 偏差，测试按 4·MC-SE 容差对拍）。 -Islam 2022 的”随机 96 向量机会基线 ≈0.75”不作为本零分布的锚——其构造与我们冻结的均匀单纯形族不同（0.505 vs 0.75 的差异正是”零分布依赖族选择”的实例）；备忘记录、不声称复刻。

目录零分布（按通道数×负荷）——真值签名 mu 在负荷 N 下多项重采目录的重构 cosine 分布（resample::multinomial 现有原语）： - 经验面：同 Rust 面，arm=“multinomial”（NB 臂 = κ 应力版，nb:<κ> 语法与校准驱动一致）。 - 用途：cosine 的零校准判定——cos > q_{0.999}(null(m,N)) ⇒ “优于该负荷下的机会水平”；这是”零校准 cosine”的落地语义。 - 解析锚：N→∞ cos→1（单调性钉测：mean(N=100) < mean(N=10000)）；不锚闭式（无）。

范围裁剪：熵匹配 Dirichlet(α·u) 零分布（Medo 式”按该签名熵校准的零分布”）需要 gamma/normal 采样原语（Marsaglia-Tsang + Box-Muller，PCG64 之上）——记为升级臂（分层 calibrated-percentile 同款模式），不在 U-M4-01 主交付；ffi-surface 新面文档明示。

§3 三匹配协议（语义逐位）

  1. Hungarian（主指标）：engine::consensus::match_solutions 零改动复用（U-M2-01 已审）。R 面装配：逐阈值 P/R/F1 + split/merge 计数 + 逐估计签名分类表 + 1-based 配对索引；τ 扫描默认 seq(0.80, 0.90, by=0.01)（鲁棒性附录口径，ARCH §指标）。
  2. Islam 贪心：逐提取签名对真值最大 cosine ≥ τ ⇒ TP（贪心、非一对一）；FP = 全体 max < τ 的估计签名；FN = 未被任何 TP 覆盖的真值。Precision=TP/(TP+FP)、敏感度=TP/|truth|、F1。R 纯实现（同 test-islam-xval.R 语义；在既有 fixture 上逐位复现其表）。
  3. Jiang 活性（bbaf042）：签名级活性 A=Σ_j h[·,j]（上游 share 清零后的活性矩阵，activity>0 即字面 >0，无 ε）——TP=真值活性>0 且估计活性>0；FP=真值 0 且估计>0；FN=真值>0 且估计 0；Specificity=(缺席且未归因)/缺席数；scaled Manhattan = Σ_{a,j}|â−a|/Σ_j N_j（突变单位，overall 口径；逐样本 N_j=0 跳过并计数）；Combined Score = (1−scaled Manhattan) + Precision + Recall；“合理重构”旗 = 逐样本 cosine(重构, 目录) > 0.969（bbaf042 真实归因中位数——引用值，非我方锚），输入目录可选、缺省记 NA。全纯 R（无 RNG、无浮点敏感性聚合除清单求和），golden 全数字钉测。

§4 API 与返回物 

ms_compare(estimated, reference, protocol = c("hungarian", "islam", "jiang"),
           metric = "cosine", thresholds = seq(0.80, 0.90, by = 0.01),
           exposures_est = NULL, exposures_ref = NULL, catalogs = NULL,
           burden = NULL, null_n = 20000, seed = 1)
  • 分派：matrix 方法（m×k 主路径）+ MsSignature 集 / MsFit（取 W/H）便捷方法。
  • Jiang 协议要求 exposures_est/exposures_ref（k×n 活性矩阵）；缺省时报错（argument，i/j 指明缺哪臂）。
  • 返回 S7 MsComparison：slots metrics（k_est×k_ref 矩阵列表，含 dimnames）、hungarian/islam/jiang（data.frame）、null（签名/目录零分布 mean/sd/分位 + seed/n_draws 回显）、meta（包版本、协议版本字符串）。print/summary/as.data.frame 复用注册。

§5 新 FFI 面

ms_compare_null_rust(family: String, m: i32, burden: f64, disp: f64, n_draws: i32, quantiles: Vec<f64>, seed: i32) -> List——family ∈ {“signature_uniform”, “catalog_multinomial”, “catalog_nb:<κ>”}；返回 {mean, sd, quantiles, n_draws, seed 回显, mc_se（batch means, 20 批）}。校验：m≥2、burden≥1、n_draws≥200、quantiles∈(0,1)、seed≥0。档位 kernel（真实校准协议）。中断/线程：有界单线程循环（n_draws 有帽），声明不可中断、threads 参数不设（与 ms_test_presence 同款文档化决策）。流布局：StreamId{replicate: 0, rank: family 枚举序, fold: 0} 独占带。

§6 验收锚（D11 双层）

  • 【逐位/整数】：四度量 R 孪生逐位；Islam 表在 test-islam-xval.R fixture 上逐位复现；Jiang 手造 3 签名 fixture 全数字 golden（含 Combined Score 全精度）；Hungarian 表与直调 ms_match_solutions_rust 一致。
  • 【数值协议等价】：签名零分布 exact 矩恒等式 4·MC-SE 内；目录零分布 N 单调；分位 type-7 与 R quantile(type=7) 一致。
  • 失败条件：mc_se > 冻结容差（0.01 绝对）→ structured error；度量输入 NaN/负 share → argument。

§7 文档联动

ffi-surface.md 新行（kernel 档）；CAPABILITY-MATRIX L-F 行 M4→交付中注记；ROADMAP M4 勾选待实现+审计后；devlog 实现批记录。对标 bench（Jiang 论文发表数字为参照表、Rozen-Lab 场景数据不联网拉取）独立为 bench/jiang/，随本单元后的批次。

§8 审计附记（2026-10-04 确认，对抗审计 REVISE：P0=0/P1=1/P2=6 全部处置）

  1. 流带碰撞（P1，已修）：首版 StreamId{replicate:0, rank:族带} 与 M3b MC 校准（replicate 0 起、rank=1-based cell_id）、thread probe、consensus restart 撞带。修复 = 独占高位带 replicate = u64::MAX−4+族带（compare.rs COMPARE_NULL_REPLICATE），其余面流零改动、无需 golden 再生；§2/§5 与 ffi 行声明同步改写。
  2. correlation 常数列（P2，已修）：colMeans ulp 噪声被除法放大成 ~1e-16 确定性垃圾 → 显式零方差守卫（中心化范数/未中心化范数 < 1e-12 → NaN）；四度量零列 NaN 全覆盖测试补齐。
  3. delta 锚校准（P2，已修）：审计 1e6 对独立 MC 实测偏差 +1/(3m)（m∈{12,48,96} 恒定；m=96 均值 0.508686 vs 97/192+1/288=0.508681）→ .ms_null_analytic 增 delta_mean_calibrated 锚，测试容差收紧至 0.004；§2 “4·MC-SE 对拍”措辞作废（偏差 > 4·SE），交付口径 = 校准锚 + 平容差。矩恒等式测试的 SE 公式同步修正（原稿 ~80× 过宽，“exact 矩”钉测形同虚设）。
  4. type-7 “逐位”声明降级（P2，已修）：审计对拍 3900 点 30.8% 差 1–2 ulp（R C 实现经 FMA 收缩）→ 声明改为”同约定、≤2 ulp”；memo §6 相应改写。
  5. Islam 双口径分裂（P2，记录 + 待 PI 裁决）：M4 R 贪心面 = zoo §1.20 字面（非独占 max-cos≥τ，fixture 上 5/5/4 TP）≠ M2 engine 面（Hungarian 指派 + split/merge 精化，matched-only，3 TP）。ffi-surface “M2 Islam 复现与 M4 ms_compare 共用”已改为仅 Hungarian 共用。v0.2 Jiang/Islam 对标 bench 以哪个口径为协议正身 = PI 裁决项；另注：贪心口径下 sensitivity = TP/|truth| 可 >1（fixture 5/3），bench 叙事需自知。
  6. memo §4 交付差（P2，以改 memo 处置）：summary/as.data.frame 未交付——§4 改为”print/format 复用注册（summary/as.data.frame 待 v0.3）“；burden 取整语义补入 ffi 行。