Restructure package: descriptive study documentation and clean layout
This commit is contained in:
Ki-Ho Lee
@@ -2,60 +2,67 @@
|
||||
|
||||
Simulation code, raw results, and figure sources for the manuscript
|
||||
"Relevance-Aware Semantic Multiple Access via Meta-Learned User-Wise
|
||||
Cross-Attention" (submitted to IEEE Transactions on Wireless Communications).
|
||||
Cross-Attention" (submitted to the IEEE Transactions on Communications).
|
||||
|
||||
The package contains everything needed to regenerate every number and
|
||||
figure in the manuscript: one script per study, the raw JSON/CSV results
|
||||
each script produced, and a single plotting script that rebuilds the figure
|
||||
PDFs from the stored results without rerunning any experiment.
|
||||
|
||||
**Detailed per-study documentation (question, setup, procedure, metrics,
|
||||
key results): [docs/EXPERIMENTS.md](docs/EXPERIMENTS.md).**
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.10+ with `torch` (CUDA optional; results generated on an NVIDIA
|
||||
RTX A4500, PyTorch 2.10, CUDA 12.8), `numpy`, `matplotlib`, and
|
||||
- Python 3.10+ with `torch` (results generated on an NVIDIA RTX A4500,
|
||||
PyTorch 2.10, CUDA 12.8; CPU fallback works), `numpy`, `matplotlib`, and
|
||||
`scikit-learn` (real-data study only).
|
||||
- All experiments use fixed seed 42 (auxiliary generators seeded as noted in
|
||||
each script).
|
||||
- All experiments use fixed seed 42 (auxiliary generators seeded as noted
|
||||
in each script).
|
||||
|
||||
## Layout
|
||||
|
||||
- `rev2/lib.py` — shared library: single-superimposed-signal channel
|
||||
(Rayleigh / Rician / Nakagami fading, complex phase residuals, timing
|
||||
offsets, CSI error), UWCA decoder (active-set masking, top-k masking,
|
||||
I/Q input), closed-form LMMSE receivers, training loops (multi-task
|
||||
meta-training and first-order MAML), evaluation metrics.
|
||||
- `rev2/e1_fair_baselines.py` … `rev2/e9_topk_online.py` — one script per
|
||||
experiment (see the table below). `*_v2/_v3` scripts supersede their
|
||||
earlier versions where present.
|
||||
- `rev2/data/` — raw JSON results behind every quoted number.
|
||||
- `rev2/plot_rev2.py` — regenerates every new figure from `rev2/data/`
|
||||
without rerunning experiments.
|
||||
- `legacy/` — scripts for the pre-revision figures (synthetic three-scenario
|
||||
study, attention maps, beta sweep, real-data study).
|
||||
- `experiments/lib.py` — shared library: the single-superimposed-signal
|
||||
uplink of the manuscript (Rayleigh / Rician / Nakagami fading, complex
|
||||
phase residuals, timing offsets, CSI error; fixed disjoint transmit block
|
||||
masks), the UWCA decoder (learned soft masks, active-set masking, top-k
|
||||
masking, optional I/Q input), closed-form LMMSE reference receivers,
|
||||
training loops, and evaluation metrics.
|
||||
- `experiments/e1_fair_baselines.py` … `experiments/e9_topk_online.py` —
|
||||
one self-contained script per study (see the table below).
|
||||
- `experiments/data/` — raw JSON results behind every quoted number.
|
||||
- `experiments/make_figures.py` — regenerates the figure PDFs from
|
||||
`experiments/data/` only.
|
||||
- `simulation/` — the three-scenario synthetic study, hyperparameter
|
||||
ablations, threshold sweeps, and the real-data study.
|
||||
- `fig/` — figure PDFs as included in the manuscript.
|
||||
|
||||
**Detailed per-experiment documentation (setup, procedure, metrics, key results, reviewer-concern map): [docs/EXPERIMENTS.md](docs/EXPERIMENTS.md).**
|
||||
|
||||
## Figure/number → script → data map
|
||||
## Study → script → data map
|
||||
|
||||
| Manuscript item | Script | Data |
|
||||
|---|---|---|
|
||||
| Fig. SER vs SNR (3 scenarios) | `legacy/semantic_correlation_sim.py`, `legacy/maml_semantic.py` | `legacy/results/` |
|
||||
| Fig. fairness vs optimal linear receivers | `rev2/e1_fair_baselines.py` | `rev2/data/e1_fair_baselines.json` |
|
||||
| Fig. residual orthogonality | `rev2/e6_residual_orth.py` | `rev2/data/e6_residual_orth.json` |
|
||||
| Phase-error robustness (complex model, CSI error) | `rev2/e2_phase_iui.py` | `rev2/data/e2_phase_iui.json` |
|
||||
| Timing-offset robustness | `rev2/e4_v3_async.py` | `rev2/data/e4_v3_async.json` |
|
||||
| Dynamic user population | `rev2/e3_dynamic_users.py` | `rev2/data/e3_dynamic_users.json` |
|
||||
| Nonlinear view-network study | `rev2/e5_nonlinear.py` | `rev2/data/e5_nonlinear.json` |
|
||||
| Meta-adaptation beyond SNR (OOD) | `rev2/e7_v2_meta.py` | `rev2/data/e7_v2_meta.json` |
|
||||
| End-to-end anti-collapse study | `rev2/e8_v2_e2e.py` | `rev2/data/e8_v2_e2e.json` |
|
||||
| Online top-k acquisition and timing | `rev2/e9_topk_online.py` | `rev2/data/e9_topk_online.json` |
|
||||
| Real-data validation | `legacy/revision_realdata_train.py`, `legacy/revision_realdata_plot.py` | `legacy/results/` |
|
||||
| SER vs SNR, three scenarios (Fig. 2) | `simulation/semantic_correlation_sim.py`, `simulation/maml_semantic.py` | `simulation/results/` |
|
||||
| Optimal-linear-receiver fairness (Fig. 3) | `experiments/e1_fair_baselines.py` | `experiments/data/e1_fair_baselines.json` |
|
||||
| Residual orthogonality (Fig. 4) | `experiments/e6_residual_orth.py` | `experiments/data/e6_residual_orth.json` |
|
||||
| Complex phase-error model, CSI error | `experiments/e2_phase_iui.py` | `experiments/data/e2_phase_iui.json` |
|
||||
| Timing offsets and realignment | `experiments/e4_async.py` | `experiments/data/e4_async.json` |
|
||||
| Dynamic user population | `experiments/e3_dynamic_users.py` | `experiments/data/e3_dynamic_users.json` |
|
||||
| Nonlinear view-network study | `experiments/e5_nonlinear.py` | `experiments/data/e5_nonlinear.json` |
|
||||
| Adaptation across fading families | `experiments/e7_meta.py` | `experiments/data/e7_meta.json` |
|
||||
| End-to-end training with anti-collapse | `experiments/e8_e2e.py` | `experiments/data/e8_e2e.json` |
|
||||
| Online top-k acquisition and timing | `experiments/e9_topk_online.py` | `experiments/data/e9_topk_online.json` |
|
||||
| beta sweep, attention maps, ablations | `simulation/revision_*.py`, `simulation/plot_figures.py` | `simulation/results/` |
|
||||
| Real-data validation (Fig. 5) | `simulation/revision_realdata_train.py`, `simulation/revision_realdata_plot.py` | `simulation/results/` |
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
python rev2/e1_fair_baselines.py # writes rev2/data/e1_fair_baselines.json
|
||||
python rev2/plot_rev2.py # regenerates the new figure PDFs
|
||||
python experiments/e1_fair_baselines.py # writes experiments/data/e1_fair_baselines.json
|
||||
python experiments/make_figures.py # rebuilds the figure PDFs from data/
|
||||
```
|
||||
|
||||
Each experiment script is self-contained and writes its JSON into
|
||||
`rev2/data/`.
|
||||
Each study script is self-contained and writes its JSON into
|
||||
`experiments/data/`.
|
||||
|
||||
## Citation and license
|
||||
|
||||
|
||||
Reference in New Issue
Block a user