diff --git a/README.md b/README.md index bbc74e9..3d5277e 100755 --- a/README.md +++ b/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 -regenerated by a single script from the stored CSV results in this -repository, without rerunning the experiments. +This repository contains exactly the code needed to reproduce the +experiments reported in the paper, together with the stored CSV +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 - NVIDIA GPU; CPU fallback works for plotting and evaluation) -- `transformers` and `datasets` (BERT feature extraction only) -- MNIST downloads automatically via `torchvision`; AG News via - `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 +WSL2 Ubuntu with Python 3 and CUDA-enabled PyTorch. The BERT study +additionally needs `transformers` and `datasets`. MNIST downloads +automatically through `torchvision`, and AG News through `datasets` +(`fancyzhx/ag_news`). diff --git a/fig/bert_ser_vs_snr_fd0.05.pdf b/fig/bert_ser_vs_snr_fd0.05.pdf deleted file mode 100755 index 827b096..0000000 Binary files a/fig/bert_ser_vs_snr_fd0.05.pdf and /dev/null differ diff --git a/fig/mnist_epoch_convergence.pdf b/fig/mnist_epoch_convergence.pdf deleted file mode 100755 index 7c5ea49..0000000 Binary files a/fig/mnist_epoch_convergence.pdf and /dev/null differ diff --git a/fig/mnist_ser_vs_doppler_snr15.pdf b/fig/mnist_ser_vs_doppler_snr15.pdf deleted file mode 100755 index 15fb2d0..0000000 Binary files a/fig/mnist_ser_vs_doppler_snr15.pdf and /dev/null differ diff --git a/fig/mnist_ser_vs_snr_fd0.05.pdf b/fig/mnist_ser_vs_snr_fd0.05.pdf deleted file mode 100755 index 132780f..0000000 Binary files a/fig/mnist_ser_vs_snr_fd0.05.pdf and /dev/null differ diff --git a/results_bert/bert_ae.pt b/results_bert/bert_ae.pt deleted file mode 100755 index 20b8846..0000000 Binary files a/results_bert/bert_ae.pt and /dev/null differ diff --git a/results_bert/bert_maml.pt b/results_bert/bert_maml.pt deleted file mode 100755 index ef866fe..0000000 Binary files a/results_bert/bert_maml.pt and /dev/null differ diff --git a/results_bert/bert_sem.pt b/results_bert/bert_sem.pt deleted file mode 100755 index c8dd638..0000000 Binary files a/results_bert/bert_sem.pt and /dev/null differ diff --git a/results_bert/bert_tf.pt b/results_bert/bert_tf.pt deleted file mode 100755 index 5f4917a..0000000 Binary files a/results_bert/bert_tf.pt and /dev/null differ diff --git a/results_bert/bert_txcls.pt b/results_bert/bert_txcls.pt deleted file mode 100755 index 4953e7a..0000000 Binary files a/results_bert/bert_txcls.pt and /dev/null differ diff --git a/results_mnist/flat_maml.pt b/results_mnist/flat_maml.pt deleted file mode 100755 index 3033790..0000000 Binary files a/results_mnist/flat_maml.pt and /dev/null differ diff --git a/results_mnist/flat_signed.pt b/results_mnist/flat_signed.pt deleted file mode 100755 index a3b4bee..0000000 Binary files a/results_mnist/flat_signed.pt and /dev/null differ diff --git a/results_mnist/mnist_ae.pt b/results_mnist/mnist_ae.pt deleted file mode 100755 index c6be5ce..0000000 Binary files a/results_mnist/mnist_ae.pt and /dev/null differ diff --git a/results_mnist/mnist_maml.pt b/results_mnist/mnist_maml.pt deleted file mode 100755 index 801ad62..0000000 Binary files a/results_mnist/mnist_maml.pt and /dev/null differ diff --git a/results_mnist/mnist_semantic.pt b/results_mnist/mnist_semantic.pt deleted file mode 100755 index 0684520..0000000 Binary files a/results_mnist/mnist_semantic.pt and /dev/null differ diff --git a/results_mnist/mnist_tf.pt b/results_mnist/mnist_tf.pt deleted file mode 100755 index 1946b7d..0000000 Binary files a/results_mnist/mnist_tf.pt and /dev/null differ diff --git a/results_mnist/mnist_txcls.pt b/results_mnist/mnist_txcls.pt deleted file mode 100755 index bc9b432..0000000 Binary files a/results_mnist/mnist_txcls.pt and /dev/null differ