""" 论文 §4.3 修订方案(v2):角向预平滑 + 可选池化(max / mean / SP)。 与 section43.py 中 Section43Encoder(v1:直接抽帧 + MaxPool)并存,供消融对比。 默认:预平滑 + SP → f_ellipse∈R^512;可通过 use_pre_smooth / pool_mode 做 2×2 消融。 """ from __future__ import annotations from dataclasses import dataclass from typing import Dict, List, Literal, Optional, Union PoolMode = Literal["max", "mean", "sp"] POOL_MODES: tuple[str, ...] = ("max", "mean", "sp") import numpy as np import torch import torch.nn as nn import torch.nn.functional as F from section42 import responsibility_indices from section43 import ( DEFAULT_SCALES, FreqGuidedScaleAttention, Section43Config, SharedMultiscaleStem, align_H_to_segment, build_segment_geometry, multiscale_sample_indices, ) @dataclass class Section43ConfigV2(Section43Config): """§4.3 v2 超参(继承 v1,新增预平滑与可切换池化)。""" use_pre_smooth: bool = True pool_mode: PoolMode = "sp" pre_smooth_kernel: int = 7 pre_smooth_avg_kernel: int = 3 n_sp: int = 4 d_sp: int = 128 @property def d_ellipse(self) -> int: if self.pool_mode == "sp": return self.n_sp * self.d_sp return self.d_h def scheme_label(self) -> str: pre = "pre" if self.use_pre_smooth else "no-pre" return f"v2({pre}+{self.pool_mode})" def v2_needs_valid_mask(enc43: nn.Module) -> bool: """仅 SP 池化需要 valid 掩码。""" if not isinstance(enc43, Section43EncoderV2): return False return enc43.config.pool_mode == "sp" def _circular_pad1d(x: torch.Tensor, pad: int) -> torch.Tensor: """x: (B, C, L) → 圆周 padding。""" if pad <= 0: return x return torch.cat([x[..., -pad:], x, x[..., :pad]], dim=-1) class AngularPreSmooth(nn.Module): """§4.3.1.0:圆周 Conv1d + 残差 LN + stride=1 AvgPool。""" def __init__(self, d_seq: int, kernel: int = 7, avg_kernel: int = 3): super().__init__() self.pad = kernel // 2 self.conv = nn.Conv1d(d_seq, d_seq, kernel_size=kernel, padding=0, bias=True) self.norm = nn.LayerNorm(d_seq) self.avg_kernel = avg_kernel self.avg_pad = avg_kernel // 2 def forward(self, s_seq: torch.Tensor) -> torch.Tensor: """ s_seq: (B, N_theta, d_seq) 返回 s_smooth: 同形状 """ x = s_seq.transpose(1, 2) x = _circular_pad1d(x, self.pad) x = self.conv(x) x = x.transpose(1, 2) x = self.norm(x) out = s_seq + x out = out.transpose(1, 2) out = _circular_pad1d(out, self.avg_pad) out = F.avg_pool1d(out, kernel_size=self.avg_kernel, stride=1, padding=0) return out.transpose(1, 2) class SelectivePool1d(nn.Module): """ §4.3.3 SP 模块:N_sp 个子空间各自可学习 query,将 (B, L, C) 汇聚为 (B, N_sp*d_sp)。 """ def __init__(self, in_features: int, d_head: int, num_heads: int): super().__init__() self.keys = nn.Parameter(torch.empty(num_heads, d_head)) self.w_q = nn.Conv1d(in_features, d_head * num_heads, kernel_size=1) self.norm = 1.0 / np.sqrt(d_head) self.d_head = d_head self.num_heads = num_heads self._reset_parameters() def _reset_parameters(self) -> None: nn.init.orthogonal_(self.keys, gain=1.0) nn.init.kaiming_normal_(self.w_q.weight, a=1.0) nn.init.zeros_(self.w_q.bias) def forward( self, x: torch.Tensor, mask: Optional[torch.Tensor] = None, ) -> torch.Tensor: """ x: (B, L, C) mask: (B, L) 有效角位 1/0,可选 返回: (B, num_heads * d_head) """ x_ch = x.transpose(1, 2) qv = self.w_q(x_ch).transpose(1, 2).view(x.size(0), x.size(1), self.num_heads, self.d_head) logits = torch.sum(qv * self.keys.view(1, 1, self.num_heads, self.d_head), dim=-1) logits = logits * self.norm if mask is not None: logits = logits - (1.0 - mask.to(x.device)).unsqueeze(-1) * 1e3 attn = F.softmax(logits, dim=1) pooled = torch.sum(qv * attn.unsqueeze(-1), dim=1) return pooled.reshape(x.size(0), -1) def build_pool_valid_mask( valid: torch.Tensor, geom, n_segments: int, s_l: int, ) -> torch.Tensor: """ valid: (B, N_theta),1=实测角位 返回: (B, T_ell) 与 H_ell 行对齐 """ idx_list = [] for m in range(n_segments): idx_list.append(responsibility_indices(m, geom)) all_idx = np.concatenate(idx_list, axis=0) return valid[:, all_idx] def pool_sequence( H_ell: torch.Tensor, pool_mode: PoolMode, *, selective_pool: Optional[SelectivePool1d] = None, valid_mask: Optional[torch.Tensor] = None, ) -> torch.Tensor: """H_ell (B,L,D) → f_ellipse;max/mean 与 v1 对齐为 D_h,sp 为 N_sp*d_sp。""" if pool_mode == "max": return H_ell.max(dim=1).values if pool_mode == "mean": if valid_mask is not None: w = valid_mask.to(H_ell.device).unsqueeze(-1) denom = w.sum(dim=1).clamp(min=1.0) return (H_ell * w).sum(dim=1) / denom return H_ell.mean(dim=1) if pool_mode == "sp": if selective_pool is None: raise ValueError("pool_mode='sp' 需要 selective_pool 模块") return selective_pool(H_ell, valid_mask) raise ValueError(f"未知 pool_mode: {pool_mode}") class Section43EncoderV2(nn.Module): """§4.3 v2:可选预平滑 + 角向抽帧 + FiLM + Transformer + 可选池化。""" def __init__(self, config: Optional[Section43ConfigV2] = None): super().__init__() self.config = config or Section43ConfigV2() cfg = self.config if cfg.pool_mode not in POOL_MODES: raise ValueError(f"pool_mode 须为 {POOL_MODES},got {cfg.pool_mode!r}") self.scales = list(cfg.scales) self.n_scales = len(self.scales) self.geom = build_segment_geometry(cfg.n_theta, cfg.n_segments) self.s_l = self.geom.s_l self.M = self.geom.n_segments if cfg.use_pre_smooth: self.pre_smooth = AngularPreSmooth( cfg.d_seq, kernel=cfg.pre_smooth_kernel, avg_kernel=cfg.pre_smooth_avg_kernel, ) else: self.pre_smooth = None self.ms_stem = SharedMultiscaleStem(cfg, self.n_scales) self.scale_attn = FreqGuidedScaleAttention(cfg, self.n_scales) enc_layer = nn.TransformerEncoderLayer( d_model=cfg.d_h, nhead=cfg.n_heads_ell, dim_feedforward=cfg.ffn_ell, batch_first=True, norm_first=True, activation="gelu", ) self.ell_transformer = nn.TransformerEncoder(enc_layer, num_layers=cfg.l_ell) if cfg.pool_mode == "sp": self.selective_pool = SelectivePool1d(cfg.d_h, cfg.d_sp, cfg.n_sp) else: self.selective_pool = None def _encode_scale( self, s_smooth: torch.Tensor, k: int, scale_id: int, training: bool, ) -> torch.Tensor: n = s_smooth.shape[1] idx = multiscale_sample_indices(n, k, training=training).to(s_smooth.device) bar_s = s_smooth[:, idx, :] return self.ms_stem(bar_s, scale_id) def _align_all_segments(self, H_k: torch.Tensor, k: int) -> torch.Tensor: out = [] for m in range(self.M): seg_idx = responsibility_indices(m, self.geom) h_m = align_H_to_segment(H_k, seg_idx, self.config.n_theta, k) out.append(h_m.unsqueeze(1)) return torch.cat(out, dim=1) def forward( self, s_seq: torch.Tensor, f_freq: torch.Tensor, g_vec: torch.Tensor, e_pen: Optional[torch.Tensor] = None, *, valid_mask: Optional[torch.Tensor] = None, training: bool = False, return_details: bool = True, ) -> Dict[str, torch.Tensor]: cfg = self.config batched = s_seq.dim() == 3 if not batched: s_seq = s_seq.unsqueeze(0) f_freq = f_freq.unsqueeze(0) g_vec = g_vec.unsqueeze(0) if valid_mask is not None and valid_mask.dim() == 1: valid_mask = valid_mask.unsqueeze(0) b = s_seq.size(0) device = s_seq.device if e_pen is None: e_pen = torch.zeros(b, cfg.d_pen, device=device, dtype=s_seq.dtype) elif e_pen.dim() == 1: e_pen = e_pen.unsqueeze(0).expand(b, -1) s_smooth = self.pre_smooth(s_seq) if self.pre_smooth is not None else s_seq f_bar = f_freq.mean(dim=-1) H_aligned: List[torch.Tensor] = [] for sid, k in enumerate(self.scales): H_k = self._encode_scale(s_smooth, k, sid, training) H_tilde = self._align_all_segments(H_k, k) H_aligned.append(H_tilde) H_stack = torch.stack(H_aligned, dim=2) F_seg = torch.zeros(b, self.M, self.s_l, cfg.d_h, device=device, dtype=s_seq.dtype) W_all = torch.zeros(b, self.M, self.n_scales, device=device, dtype=s_seq.dtype) beta_all = torch.zeros(b, self.M, cfg.h_scale, self.n_scales, device=device) for m in range(self.M): t_stack = H_stack[:, m, :, :].mean(dim=2) W_m, beta_m = self.scale_attn(f_bar[:, m], g_vec, e_pen, t_stack) W_all[:, m] = W_m beta_all[:, m] = beta_m for sid in range(self.n_scales): F_seg[:, m] = F_seg[:, m] + W_m[:, sid : sid + 1, None] * H_stack[:, m, sid] H_ell = F_seg.reshape(b, self.M * self.s_l, cfg.d_h) H_ell = self.ell_transformer(H_ell) f_ellipse = pool_sequence( H_ell, cfg.pool_mode, selective_pool=self.selective_pool, valid_mask=valid_mask if cfg.pool_mode == "sp" else None, ) out: Dict[str, torch.Tensor] = { "f_ellipse": f_ellipse, "H_ell": H_ell, "F_segment": F_seg, "W_scale": W_all, "s_smooth": s_smooth, } if return_details: out["H_aligned"] = H_stack out["beta_heads"] = beta_all out["f_bar"] = f_bar if not batched: out = {k: v.squeeze(0) for k, v in out.items()} return out def forward_from_upstream( self, o41: Dict[str, torch.Tensor], o42: Dict[str, torch.Tensor], e_pen: Optional[torch.Tensor] = None, *, valid_mask: Optional[torch.Tensor] = None, training: bool = False, return_details: bool = True, ) -> Dict[str, torch.Tensor]: return self.forward( o41["s_seq"], o42["f_freq"], o41["g_vec"], e_pen, valid_mask=valid_mask, training=training, return_details=return_details, ) def save_checkpoint(self, path, extra: Optional[dict] = None) -> None: torch.save( {"config": self.config, "state_dict": self.state_dict(), "extra": extra or {}, "scheme": "v2"}, path, ) @classmethod def load_checkpoint(cls, path, map_location=None, strict: bool = True) -> "Section43EncoderV2": payload = torch.load(path, map_location=map_location, weights_only=False) cfg = payload.get("config") or Section43ConfigV2() if isinstance(cfg, dict): cfg = Section43ConfigV2(**cfg) elif isinstance(cfg, Section43Config) and not isinstance(cfg, Section43ConfigV2): cfg = Section43ConfigV2(**vars(cfg)) model = cls(cfg) model.load_state_dict(payload["state_dict"], strict=strict) return model def build_section43_encoder( config: Optional[Section43Config] = None, *, use_v2: bool = False, use_v3: bool = False, use_v3_1: bool = False, ) -> nn.Module: """兼容入口:实现见 section43_v3 / section43_v3_1。""" if use_v3_1: from section43_v3_1 import Section43ConfigV3_1, Section43EncoderV3_1 if config is None: return Section43EncoderV3_1() if isinstance(config, Section43ConfigV3_1): return Section43EncoderV3_1(config) return Section43EncoderV3_1( Section43ConfigV3_1( **{ k: v for k, v in vars(config).items() if k in Section43ConfigV3_1.__dataclass_fields__ } ) ) from section43_v3 import build_section43_encoder as _build return _build(config, use_v2=use_v2, use_v3=use_v3)