UECCT 代码说明
========================

1. 项目定位
-----------
本项目实现了 Unified Error Correction Code Transformer（UECCT）相关实验代码。


2. 主要入口文件
---------------
- 单机训练/测试入口：src/main_ecct.py


3. ECCT 代码结构
----------------
- src/main_ecct.py
  - 参数解析、日志初始化、FEC 列表构建
  - 训练与测试流程控制（train/test）
- src/scripts/ecct_model.py
  - EcctDataset：生成训练/测试样本（info, llr, syndrome, mask 等）
  - ECCT：UECCT 模型主体
- src/lib/transformer_lib.py
  - Transformer 编码器实现
  - UECCT 注意力实现（MultiHeadAttention）
- src/scripts/fec.py
  - FEC 基础类及 G/H 矩阵构建


4. 当前模型行为
----------------------
- dec_method 在运行时固定为 UECCT。
- df 会在 main_ecct.py 中被设置为 fec_Smax（最大校验方程数量）。
- 训练目标为信息位（K 维）预测，loss/ber 也按 K 维 mask 计算。


5. 运行环境建议
--------------
- Python 3.9+
- PyTorch（支持 CUDA 时自动使用 GPU）
- numpy
- joblib

如果环境中缺少依赖，请先安装对应包。


6. 快速开始
-----------
在项目根目录执行：

1) 使用默认参数训练并测试
   python src/main_ecct.py

2) 仅测试模式（加载已有模型）
   python src/main_ecct.py --test_mode True --test_model_path ./results/best_model/best_model.pth


7. 常用参数说明（main_ecct.py）
------------------------------
- --num_epochs：训练轮数
- --learning_rate：学习率
- --train_batch_size：训练 batch size
- --test_batch_size：测试 batch size
- --test_blocks：每个码型最少测试块数
- --dec_n：Transformer 编码层数
- --mh：多头注意力头数
- --dk：每个头的维度
- --dropout：dropout 比例
- --mixed_precision_training：是否混合精度
- --fine_tuning：是否加载预训练权重继续训练


8. 数据与日志
-------------
- fec_db/：存放码本相关矩阵（alist）
- results/：训练日志与模型输出目录
- log_info.txt：批量实验时记录日志目录和进程号


9. 开发备注
-----------
- FEC 配置列表在 src/main_ecct.py 中的 fec_params 变量内定义。
- 如果需要新增码型，请确保 fec_db 中存在对应 alist，或在 fec.py 中补全生成逻辑。
- 若要比较不同训练配置，建议先复制 main_ecct.py 再做实验配置修改，避免影响基线。

