# UWCA Semantic Multiple Access — Reproducibility Package

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).

## Requirements

- Python 3.10+ with `torch` (CUDA optional; results generated on an NVIDIA
  RTX A4500, PyTorch 2.10, CUDA 12.8), `numpy`, `matplotlib`, and
  `scikit-learn` (real-data study only).
- 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).
- `fig/` — figure PDFs as included in the manuscript.

## Figure/number → 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/` |

## 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
```

Each experiment script is self-contained and writes its JSON into
`rev2/data/`.

## Citation and license

To be completed upon acceptance.