Slim to paper-essential code with explanatory README

README.md

@@ -5,46 +5,72 @@ Code and stored results for the manuscript
 (submitted to IEEE Journal on Selected Areas in Communications,
 Special Issue on Towards Open and Intelligent 6G RAN).
 
-All experiments use fixed random seeds, and every figure in the paper is
+This repository contains exactly the code needed to reproduce the
-regenerated by a single script from the stored CSV results in this
+experiments reported in the paper, together with the stored CSV
-repository, without rerunning the experiments.
+results from which every figure is regenerated. All experiments use
+fixed random seeds.
+
+## What each script does
+
+| Script | Role in the paper |
+|---|---|
+| `c11_doppler_csi.py` | Shared library. Implements the time-varying tapped-delay-line channel by sample-level time-domain convolution, so intra-symbol Doppler produces genuine inter-carrier interference, plus the pilot-aging frame structure and the aging-aware LMMSE front end of Section IV-A. |
+| `c13_mnist.py` | MNIST study of Sections V-A and V-B. Defines the signed user-wise attention receiver, the Transformer shared-embedding separator, and the per-user autoencoder, with joint training, warm-started first-order MAML meta-training, and the SNR-sweep evaluation behind Fig. 6. |
+| `c18_mnist_doppler.py` | Doppler sweep behind Fig. 7, with task-conditional decoder-side adaptation at every operating point. |
+| `c19_mnist_epoch.py` | Convergence study behind Fig. 5, recording the task-adapted SER at every training checkpoint. |
+| `c22_maml_epoch.py` | Budget-matched meta-training trajectory that forms the right-hand segment of Fig. 5. |
+| `c21_mnist_flat.py` | Flat Rayleigh study behind Table III, including the decoder-side first-order MAML variant. |
+| `c20_bert.py` | Concluding BERT/AG News text study behind Fig. 8, from feature caching to training and evaluation. |
+
+## Reproducing the figures
+
+Each figure regenerates from the stored CSV results without
+retraining.
+
+```bash
+python3 c19_mnist_epoch.py --mode fig      # Fig. 5
+python3 c13_mnist.py --mode fig            # Fig. 6
+python3 c18_mnist_doppler.py --mode fig    # Fig. 7
+python3 c20_bert.py --mode fig             # Fig. 8
+```
+
+Table III values are stored in `results_mnist/mnist_flat.csv`, and
+Table IV values come from `results_mnist/mnist_results.csv` and
+`results_mnist/mnist_doppler.csv`.
+
+## Rerunning the experiments
+
+Full reruns retrain from scratch on the same fixed seeds.
+
+```bash
+# MNIST time-varying study (Figs. 5-7, Table IV)
+python3 c13_mnist.py --mode train
+python3 c13_mnist.py --mode train-tf
+python3 c13_mnist.py --mode train-ae
+python3 c13_mnist.py --mode train-tx-cls
+python3 c13_mnist.py --mode train-maml
+python3 c13_mnist.py --mode eval
+python3 c18_mnist_doppler.py --mode run
+python3 c19_mnist_epoch.py --mode run
+python3 c19_mnist_epoch.py --mode run-maml --steps 7500
+python3 c22_maml_epoch.py --pretrain-steps 7500
+
+# Flat Rayleigh study (Table III)
+python3 c21_mnist_flat.py --mode run
+
+# BERT text study (Fig. 8)
+python3 c20_bert.py --mode cache
+python3 c20_bert.py --mode train-tx-cls
+python3 c20_bert.py --mode train
+python3 c20_bert.py --mode train-tf
+python3 c20_bert.py --mode train-ae
+python3 c20_bert.py --mode train-maml
+python3 c20_bert.py --mode eval
+```
 
 ## Environment
 
-- WSL2 Ubuntu, Python 3.14, PyTorch with CUDA (experiments ran on an
+WSL2 Ubuntu with Python 3 and CUDA-enabled PyTorch. The BERT study
-  NVIDIA GPU; CPU fallback works for plotting and evaluation)
+additionally needs `transformers` and `datasets`. MNIST downloads
-- `transformers` and `datasets` (BERT feature extraction only)
+automatically through `torchvision`, and AG News through `datasets`
-- MNIST downloads automatically via `torchvision`; AG News via
+(`fancyzhx/ag_news`).
-  `datasets` (`fancyzhx/ag_news`)
-
-## Figure and table map
-
-| Paper item | Regenerate figure (from stored CSV) | Full rerun |
-|---|---|---|
-| Table III (MNIST, flat Rayleigh) | values in `results_mnist/mnist_flat.csv` | `python3 c21_mnist_flat.py --mode run` |
-| Fig. 5 (convergence + MAML meta phase) | `python3 c19_mnist_epoch.py --mode fig` | `c19 --mode run`, `c19 --mode run-maml --steps 7500`, `c22_maml_epoch.py --pretrain-steps 7500` |
-| Fig. 6 (MNIST SER vs SNR) | `python3 c13_mnist.py --mode fig` | `c13 --mode train / train-tf / train-ae / train-tx-cls / train-maml / eval` |
-| Fig. 7 (MNIST SER vs Doppler) | `python3 c18_mnist_doppler.py --mode fig` | `c18 --mode run` |
-| Fig. 8 (BERT text SER vs SNR) | `python3 c20_bert.py --mode fig` | `c20 --mode cache / train-tx-cls / train / train-tf / train-ae / train-maml / eval` |
-| Table IV (summary) | values in `results_mnist/mnist_results.csv`, `mnist_doppler.csv` | see Fig. 6 and Fig. 7 rows |
-
-Run every command from the repository root. Trained checkpoints
-(`*.pt`) are included, so `--mode eval` and `--mode fig` work without
-retraining. The BERT feature cache (`results_bert/bert_feats.pt`,
-about 85 MB) is excluded and is regenerated by
-`python3 c20_bert.py --mode cache`.
-
-## Files
-
-- `c11_doppler_csi.py` shared library, time-varying TDL channel with
-  intra-symbol Doppler (genuine ICI), pilot aging, aging-aware LMMSE
-- `c13_mnist.py` MNIST models (signed, Transformer SE, per-user AE),
-  training, MAML meta-training, SNR-sweep evaluation
-- `c18_mnist_doppler.py` MNIST Doppler sweep
-- `c19_mnist_epoch.py` convergence study with task-adapted checkpoints
-- `c20_bert.py` BERT/AG News text study
-- `c21_mnist_flat.py` flat Rayleigh study with decoder-side
-  first-order MAML
-- `c22_maml_epoch.py` budget-matched meta-training trajectory
-- `results_mnist/`, `results_bert/` stored CSV results and checkpoints
-- `fig/` figure PDFs as used in the manuscript