Pilot2Beam

面向 FDD Massive MIMO-OFDM 的前沿实验项目：从 UE 接收到的下行导频出发，经过有限比特 CSI 反馈，在 BS 侧重建信道或直接生成预编码向量，并以频谱效率、GMI/BLER 和反馈开销作为主要指标。

Pilot2Beam 在已验证的 Sionna + TensorFlow 通信仿真基础上独立构建，从统一的多天线系统模型重新定义输入、输出、反馈接口和验收标准；训练运行、权重和实验结论均由本仓库单独追踪。

核心问题

在固定下行导频开销和有限上行反馈预算下，能否联合学习：

1. 从带噪导频中提取有效信道表示；
2. 将表示压缩为真实、可计数的反馈 bitstream；
3. 在 BS 侧恢复 CSI 或直接生成波束；
4. 最大化下行频谱效率并降低链路 BLER；
5. 在未见信道、SNR、速度和反馈预算下保持泛化能力。

第一版范围

• 单小区、单用户、FDD、32 天线 BS、单天线 UE；
• 3GPP CDL-A/CDL-C/CDL-D 与 OFDM；
• DFT 波束导频和可配置的导频子载波；
• 固定码率 VQ 与熵约束可变码率反馈；
• 可选有噪数字反馈信道；DJSCC 保留为 V2 独立对照；
• BS 侧 CSI 重建头与直接预编码头；
• NMSE、SGCS、波束增益、频谱效率、GMI、BLER、反馈 bit、复杂度和延迟评估。

多用户 MU-MIMO、Diffusion 生成式解码器和无线基础模型预训练属于后续扩展，不进入第一版关键路径。

设计原则

• 不使用 UE 样本最大值等未计费 side information；
• 不把连续浮点 latent 当作数字反馈；
• 不用“观察到零错误”代替 BLER 上界；
• 所有比较固定导频开销、反馈 bit、信道样本和随机种子；
• 训练目标面向下游通信性能，NMSE 只是辅助指标；
• Smoke 流程与正式 Reference 流程严格分开；
• 在 RTX 4060 8GB 上可训练、可评估、可导出。

实现与系统位置

V1 已实现 CDL 信道、导频、传统基线、Pilot-native VQ、任务导向双输出、多码率、按 token 位置建模的真实算术编码、QPSK/16QAM 5G LDPC、OOD 评分和轻量 adapter。Smoke、Reference、OOD/adapter 三类命令相互独立，每次训练创建不可变 run 目录并记录配置、环境、seed、参数量和权重 SHA-256。验证协议、回归范围和结果解释见 验证文档。

Reference-development 评估使用：3 个 seed × 5000 steps，Reference 张量规模，每 seed 300 行 × 2048 样本；代表 seed 由相对 Perfect-CSI MRT 任务比的中位数规则确定为 43，而非挑选最好结果。learned MRT 的跨 seed 平均 SE 为 6.150±0.108，高于 LS-scalar 的 4.610±0.009，但低于 DFT codebook 的 6.442±0.001。共享 position entropy model 的实际独立 wire length 比 128/256/512/768-bit 固定 payload 平均节省约 20–24%，但预算单调性仍有 90/810 个相邻比较违例。

代表 seed 的正式编码评估覆盖 60 条件 × 5 方法 × 256 blocks，QPSK 与 16QAM 各累计 76,800 blocks；learned MRT/direct 的平均 QPSK BLER 为 0.0118，LS 为 0.0568，DFT/Perfect 的观测值为 0（CSV 保留非零置信上界）。OOD 三策略在 5 场景 × 4 预算 × 512 样本上完成：180 参数 adapter 在 16/20 条件改善 MRT SE，而 full 微调虽在 20/20 条件改善 NMSE，却仅在 4/20 条件改善 MRT/direct SE，并产生明显遗忘。最终全量回归为 130 passed。

本项目位于通信系统的物理层 CSI 获取、反馈与预编码控制链路：覆盖下行参考信号、UE 测量/压缩、上行 CSI 反馈接口和 BS 预编码决策，并提供下行数据链路仿真。它不是完整基站协议栈，不实现 MAC 调度、HARQ、RLC/PDCP、射频前端或真实空口。

Sionna CDL H
  -> DFT beam pilots + AWGN
  -> UE features [Re(Yp),Im(Yp),frequency,beam]
  -> UE encoder + optional adapter
  -> VQ integer indices
  -> fixed bit pack / arithmetic-coded wire stream
  -> BS H_hat + MRT / direct precoder
  -> QPSK/16QAM + 5G LDPC
  -> NMSE / SGCS / gain / SE / GMI / BER / BLER + exact CI

UE 推理接口没有真实 CSI、真实 SNR、样本最大值或未计费 scale。训练时真实 H 仅作为监督标签和物理链路评估真值。

快速开始（WSL）

项目默认使用仓库内 .venv；也可通过 PILOT2BEAM_VENV 指向已有虚拟环境。

git clone https://github.com/C10udsea/pilot2beam.git
cd pilot2beam

python -m venv .venv
source scripts/setenv.sh
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
pytest -q

完整 Smoke（测试、三步 GPU 训练、五方法配对评估、报告）：

bash scripts/run_smoke.sh

Reference-development 复现实验（3 seed × 5000 steps、2048 样本、代表 seed 编码与 OOD）：

bash scripts/run_reference_development.sh
bash scripts/run_reference_development_eval.sh
bash scripts/run_reference_development_coded.sh
bash scripts/run_reference_development_ood.sh

大规模 Reference 配置（50,000 步、16,384 样本）：

bash scripts/run_reference.sh

分步运行：

python -m pilot2beam.train.train_joint \
  --config configs/task_oriented.yaml --run-name task

python -m pilot2beam.eval.evaluate \
  --config configs/task_oriented.yaml \
  --weights runs/<run-id>/best.weights.h5 \
  --output results/tables/task.csv

python -m pilot2beam.eval.report \
  --input results/tables/task.csv \
  --output-dir runs/<run-id>/report

VQ 优化消融配置：

configs/task_smoke_legacy.yaml          # 优化前 gradient VQ 配方
configs/task_smoke_ema_only.yaml        # 只启用 EMA
configs/task_smoke_staged_gradient.yaml # 只启用 staged objective + usage floor
configs/task_smoke.yaml                 # 完整优化配方

轻量适配与 OOD 冒烟：

bash scripts/run_ood_smoke.sh runs/<base-run>/best.weights.h5

正式 OOD 方案使用 configs/ood.yaml，应分别运行 none、adapter_only、full 冻结策略。

代表 seed 的 batch=1 延迟复现：

python -m pilot2beam.eval.benchmark \
  --config runs/20260823T100922.439219637Z-reference-dev-seed-43/resolved_config.yaml \
  --weights runs/20260823T100922.439219637Z-reference-dev-seed-43/best.weights.h5 \
  --output results/reference-development-latency-batch1.json

RTX 4060 batch=1 基准中，compiled UE 平均延迟为 7.83 ms、p95 为 10.27 ms，完整端到端 compiled 平均延迟为 20.45 ms。

结果解释规则

• feedback_payload_bits 是真正发送的固定码率 payload；算术编码另行报告 entropy、payload、一次性协议表和 amortized wire bits；
• Perfect-CSI 是 oracle 上界，不伪装成可实现反馈方法；
• NMSE 先逐样本在线性域聚合，再转 dB；
• 观察到 0 个错误不等于真实 BLER=0，CSV 始终保存错误数、块数和 Clopper–Pearson 区间；
• OOD 的 id_confidence 是基于 VQ distortion z-score 的单调诊断，不是后验概率；
• 三步 Smoke 权重只证明链路可执行，不代表收敛结果或方法优越性。

详细系统边界和张量见 docs/ARCHITECTURE.md，验证矩阵见 docs/VALIDATION.md。

使用许可

本仓库目前未授予代码复用或再分发许可。Sionna、TensorFlow 和其他依赖遵循各自许可证。