玉佩2 双层网络（配对互补）——口径冻结稿 v1
冻结时间 2026-10-08 23:xx，冻结人：主会话。改动这个文件必须同步改所有下游。

================================================================
0. 这次要回答什么
================================================================

用户构造：对股票 B、C，把两者成交按时间拼成 U_BC，量 X 与 U_BC 的距离。
若 X 与 U_BC 近、但分别与 B、C 都不近，则 B、C 是"互补品"。
最后把每对 (B,C) 压成一个互补分数，得到 N×N 矩阵。

两个待实现的量（ChatGPT 提的两个版本）：
  版本一 组合形状增益 G（求和核，可以直接复用已有备份矩阵，不用重算逐笔）
  版本二 互补覆盖增益 Gcov（取最大近邻的覆盖核，必须回到逐笔）

================================================================
1. 已有的逐笔算子（核实过，见 experiments/yupei2/kernel_spec.txt）
================================================================

10ms 桶，BUCKET_US=10000，桶基准 = 当日 09:30 的微秒差（下午已整体前移 90 分钟）。
每只股票 Y 的桶场：u_Y[k] = 落在第 k 桶的成交权重之和（cnt 族 w=1，即笔数；
vol 族 w=sqrt(volume)；下面默认 cnt）。
d(tau) = exp(-0.01 / tau)   每桶一步的衰减乘子。

有向矩阵（备份 mats/<name>.bin，N×N f32 行主序）：
  S_dir[i][j] = sum_k u_i[k] * ( sum_{l<k} u_j[l]*d^(k-l) + 0.5*u_j[k] )
  语义：行 i 的成交时间在后、列 j 的成交时间在前（kernel_spec 第 1.4 节钉死）。
  同一 10ms 桶内的成交对按 50/50 折半计入两个方向。

生产实现丢掉最后一段：参与计算的桶 k < 1421312（= 347*4096），不是全部 1422000。

由此可直接推出（下游全部用这个）：
  对称核  S[i][j] = sum_k sum_l u_i[k] u_j[l] d^|k-l|      （i 不等于 j）
  自能量  E_i = S[i][i] = 2 * S_dir[i][i]                  （含同桶自配对）
  因为 S_dir[i][i] = sum_k u_i[k](sum_{l<k} u_i[l] d^(k-l) + 0.5 u_i[k])，
  乘 2 以后有序对 i!=j 的部分各被数一次、对角部分 2*0.5=1 次，正好等于上式。

注意：库里的 ctx.symmetric() 会把对角强制置 0，所以别拿它当 E_i，用 2*S_dir[i][i]。

================================================================
2. 版本一：组合形状增益 G（求和核）
================================================================

归一化相似度（对数似然比式的相关系数，Cauchy-Schwarz 保证 |rho| <= 1）：
  rho[i][j] = S[i][j] / sqrt(E_i * E_j)，  rho[i][i] = 1

设 eB = E_B, eC = E_C, r = rho[B][C]，定义
  D(B,C) = sqrt( eB + eC + 2 * r * sqrt(eB*eC) )          (= sqrt(E_{U_BC}))
  wB = sqrt(eB) / D ,   wC = sqrt(eC) / D

则对任意 X（X 不等于 B、C）：
  rho[X][U_BC] = wB * rho[X][B] + wC * rho[X][C]          <-- 精确等式，已推导
（因为 S[X][U_BC] = S[X][B] + S[X][C] 是双线性的，U_BC 的自能量 = eB+eC+2S[B][C]。）
注意权重只依赖 (B,C)，不依赖 X，所以下面的 argmax 只是两列的线性组合。

用户的选股规则：
  X0(B,C) = argmax_{X 不属于 {B,C}}  rho[X][U_BC]        （并列取代码序最小的）
  rhoU    = rho[X0][U_BC]
  single  = max( rho[X0][B], rho[X0][C] )
  G       = rhoU - single                                （组合形状增益）

实现的化简（必须按这个算，不要真的拼数据）：
  h[X] = wB * rho[X][B] + wC * rho[X][C] 对所有 X 一次扫过，取 argmax。
  复杂度 N^3 但每对只需一趟 5000 长的 max-scan，内存带宽受限，不是计算受限。

空模型（关键，见第 5 节）：G 对随机配对也是正的（两个 ρ 相等的伙伴，
r=0 时 rhoU = (p+q)/sqrt(2) = sqrt(2)*p，G = 0.414*p > 0）。所以必须配一个零基线。

================================================================
3. 版本二：互补覆盖增益 Gcov（取最大近邻的覆盖核）
================================================================

把"求和"换成"取最大近邻"，衰减场递推从加改成 max：
  nsum_Y[k] = nsum_Y[k-1]*d + u_Y[k-1]                  （严格在前，求和核）
  nmax_Y[k] = max( nmax_Y[k-1]*d, u_Y[k-1] )            （严格在前，取最大）
  覆盖场取两侧最近：near_Y[k] = max( nmax_Y[k], nmax_rev_Y[k] )
  其中 nmax_rev_Y 是把 u_Y 时间倒过来再跑一遍同样的递推。

  逐笔语义：A 在桶 k 的成交，去找 B（或 C）中离它最近的那一笔成交，
  按 e^{-|dt|/tau} 衰减，再乘那一桶的权重。同一个池子里两笔都近时只算最近那笔。

覆盖核与覆盖相似度：
  cov(A,B)  = sum_k u_A[k] * near_B[k]
  covrho(A,B) = cov(A,B) / sqrt( cov(A,A) * cov(B,B) )     （任一分母 <= 0 记为无效）

用户的规则同样搬过来：
  X0cov(B,C) = argmax_{X} covrho(X, U_BC)
  covrho(X,U_BC) = sum_k u_X[k] * max( near_B[k], near_C[k] ) / sqrt(cov(X,X)*cov(U,U))
  Gcov = covrho(X0cov,U_BC) - max( covrho(X0cov,B), covrho(X0cov,C) )

  化简：写 max(b,c) = b + relu(c-b)，则分子 = cov(X,B) + sum_k u_X[k]*relu(near_C[k]-near_B[k])。
  仍然需要 B、C 两个近邻场同时在场，所以必须回到逐笔，不能只读备份矩阵。

注意 A 桶里 u_A[k] 是权重和，同一桶多笔会各算一次（对 cnt 就是笔数），这与求和核的口径一致。

================================================================
4. 输出 schema（冻结）
================================================================

所有矩阵都是 N×N f32 行主序，按 codes.txt 的行序，对角写 0，对称量两边都写。

  <outdir>/codes.txt        代码列表（每行一个）
  <outdir>/rho.bin          rho（N×N f32，对角写 1）
  <outdir>/E.bin            自能量 E（N 个 f64 裸写）
  <outdir>/G.bin            G[B*N+C]，对称
  <outdir>/RHO_U.bin        rho[X0][U_BC]
  <outdir>/SINGLE.bin       max(rho[X0][B], rho[X0][C])
  <outdir>/X0.bin           X0 的行下标，写成 f32
  <outdir>/Z.bin            G 相对空模型的标准化偏离（见第 5 节）
  <outdir>/summary.json     {"n":..,"date":..,"mat":"..","argmax_hist":[...],
                             "null":{"strata":[[lo,hi,mean,std,count],...]} }

  可选（加了 --tau 就有）：<outdir>/G_<mat>.bin 等多时标版本。

================================================================
5. 空模型怎么建（版本一）
================================================================

问题：G 对随机配对也是正的，所以"G 大"本身不是证据。
      两个都与 X 有 ρ=p 的独立伙伴，r=0 时 G = (sqrt(2)-1)*p ≈ 0.414p。
做法：蒙特卡洛配对空模型。按 (B 的活跃度档, C 的活跃度档) 分 10×10 = 100 层
      （活跃度用当日成交笔数 stats.n_trades 的十分位）。
      每层抽 M 个随机配对，按第 2 节同样的流程算出 G，得到该层的均值与标准差。
      对每个真实配对，用它所处层的均值/标准差算 Z = (G - mean) / std。
      M 默认 20000 总样本，按层数均分，最少每层 50 个。
      抽不到样本的层（真实的边界层）用全局池兜底，并在 summary.json 里标出来。

纪律：Z 只是把"两个平庸伙伴"这个效果扣掉，它不证明互补来自交易需求。
      要说到"溢出"，还得看有向矩阵（谁先谁后）与跨日稳定性，这两件不在本文件范围。

================================================================
6. 下游降维（不在本文件的冻结范围，另开文件）
================================================================

主会话负责设计，pair_reduce.py 负责实现。至少要覆盖：
  R1 每只股票的最佳配对与角色（best_complement / explain_count / supply-demand）
  R2 每只 X 的最佳伙伴对（三分解，不是把 N×N 压成行和）
  R3 带冗余惩罚的贪心篮子（子模最大化，等价于用户构造从 2 只推广到 k 只）
  R4 互补图 vs 替代图（rho 图）的结构对照
  R5 残差互补（对 rho、规模、活跃度正交化后剩下的部分）
  R6 多时标一致性

================================================================
7. v1 冻结稿之后的修正（2026-10-09 补，实测依据）
================================================================

这三条都是跑完机制样本以后发现 v1 写错或者写漏的，下游要按这里改。

7.1 空模型 Z 其实不构成检验（v1 第 5 节错了）
    实测：股票-股票 6,784,086 对，按 (B 笔数十分位, C 笔数十分位) 100 层、每层几百个
    随机配对做空模型，逐层真实 G 的均值/标准差与空模型的均值/标准差都对得上
    （差出 3 个标准误的层数 = 0），于是 Z 的均值必然 0、标准差必然 1.01。
    空模型抽的配对本就来自同一个分布，所以 Z 只是把数据标准化了一遍，
    P(Z>2)=0.12% 是「G 分布右尾比正态薄」的表现，不是互补性的证据。
    能构成检验的对照是条件冗余基线，见 experiments/yupei2/pair_conditional.py：
        r_hat(p,q) = E[ rho(B,C) | rho(X0,B)=p, rho(X0,C)=q ]   （(p,q) 分位网格）
        excess     = G(p,q,r) - G(p,q,r_hat)
    实测：G 的 p10-p90 是 0.091，excess 只有 0.0081，std 比 0.094，
    即 G 的 99.1% 方差可以由 (p,q) 这个「各自跟 X0 有多像」的剖面解释掉，
    excess 与 G 的 Spearman 只有 0.013。也就是说用户这条规则算出来的 N×N 矩阵，
    主要不是配对 (B,C) 的性质，而是两只股票各自跟 X0 的相似度水平。
    excess 的跨日 Spearman 0.301（G 本身 0.440）。

7.2 用户原规则的 X0 被少数股票垄断（v1 没料到）
    白名单口径、20241231：X0 只用到 922 只股票，前 10 名占全部配对的 50.6%，
    前 100 名占 92.6%，第一名是平安银行 000001。所以 G(B,C) 很大程度是
    「这对股票对最典型的那些股票拟合得怎么样」。
    替代口径 X0* = argmax_X [rho(X,U_BC) - max(rho(X,B),rho(X,C))]（输出 GSTAR/ZS/X0STAR）：
    用到 3544 只，前 10 名占 20.7%，且跨日全配对 Spearman(ZS)=0.684 对 Spearman(Z)=0.499。
    两路都要算，不要只留一路。

7.3 股票白名单（v1 漏了，是 cross-section-explore 的硬要求）
    旧备份 codes.txt 里混了 280 个不在 /ssd_data/data/basic_info/symbol_map.csv 的代码
    （276 个 5 开头 ETF + 4 个 019xxx 债券）。因为这条规则取 argmax，
    非个股特别容易被挑成 X0：511090 这个 ETF 占了 7.1% 的配对，排第三。
    加了 --stocks-only 之后 Z>2 占比从 0.317% 掉到 0.104%，Spearman(Z) 从 0.426 升到 0.499，
    Spearman(ZS) 从 0.557 升到 0.684。基金与债券必须在计算之前筛掉，不能最后再筛输出。

7.4 求和核的核对口径（覆盖核那条支线踩到的坑）
    g_j[k] = Σ_{l<k} u_j[l]·d^(k-l) + 0.5·u_j[k]，其中前缀项已经含到第 k 桶的衰减。
    实现里再乘一次 d 会整体缩小，相对误差上限恰好是 1-d：
    τ=1 是 0.995%（实测 max 0.9952%），τ=0.05 是 18.13%（实测 max 18.127%）。
    两处数字对得上，可以据此定位。
