# 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 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` (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).

## Layout

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

## Study → script → data map

| Manuscript item | Script | Data |
|---|---|---|
| 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/betasweep.py etc.`, `simulation/plot_figures.py` | `simulation/results/` |
| Real-data validation (Fig. 5) | `simulation/realdata_train.py`, `simulation/realdata_plot.py` | `simulation/results/` |

## Running

```bash
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 study script is self-contained and writes its JSON into
`experiments/data/`.

## Independent verification

`experiments/verification/math_verify.py` re-derives every closed form and
inequality in the manuscript with standalone numpy code (no experiment code
reused): the relevance identity, the mutual-information correlation, the
subspace ceiling, the LMMSE receiver against an empirical Wiener solution
(0.1% MSE agreement; the blind form matches the OMA cosine to machine
precision), and the surrogate bound used in the appendix (uniform constant
0.97). Results: `experiments/verification/math_verify.json`.

## Citation and license

To be completed upon acceptance.