uwca-semantic-mac/README.md

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.

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/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

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

Citation and license

To be completed upon acceptance.