Add full COMMAG publication benchmark on Python 3.13

[vtavakkoli]

Summary

Extends the compact COMMAG study into a publication-oriented multi-scenario benchmark with explicit seen/unseen evaluation, offline-RL baselines, policy-shortcut diagnostics, episode-paired statistical testing, and a clean Python 3.13 Docker workflow.

Full multi-scenario COMMAG preparation

• discovers the pinned upstream Git tree instead of hard-coding representative IMSIs
• includes every existing slice_traffic/.../*_metrics.csv file in configured cells
• covers all 18 published training configurations (tr0–tr17), both experiments, and BS1–BS4
• uses rome_static_close and rome_static_medium as seen conditions
• reserves tr0–tr11 for training, tr12–tr14 for validation, and tr15–tr17 for seen-condition testing
• evaluates RF-distance shift on rome_static_far
• evaluates mobility shift on rome_slow_close
• fails on missing configured cells or episode overlap rather than silently accepting a partial benchmark
• reuses cached non-empty raw COMMAG downloads

Reproducible baselines

The executable benchmark compares:

• proposed safety/OOD-aware multi-objective controller
• HistGradientBoosting behavior-cloning diagnostic
• Fitted Q Iteration (FQI)
• discrete linear CQL baseline using Bellman error plus a log-sum-exp conservative penalty

All of these are evaluated under the same held-out direct-method critics.

Original COMMAG PPO: paper reference only

The historical TensorFlow PPO runtime has been removed. There is no Dockerfile.ppo-legacy service and no model-export step.

Instead, the benchmark writes results/publication/literature_reference.json with the published results from:

L. Bonati, S. D'Oro, M. Polese, S. Basagni, T. Melodia, "Intelligence and Learning in O-RAN for Data-driven NextG Cellular Networks," IEEE Communications Magazine, 59(10), 21-27, 2021, DOI 10.1109/MCOM.101.2001120, arXiv:2012.01263.

The paper reports:

• eMBB spectral-efficiency gains up to 20% over the best-performing static scheduler
• URLLC average-buffer reductions of 37% vs RR, 5% vs WF, and 17% vs PF

These are explicitly marked literature-reference values and are not inserted into direct-method utility tables or paired statistical tests because the metrics, experimental conditions and action semantics differ.

Unseen-condition / OOD evaluation

Exports seen/unseen and per-scenario:

• mean OOD score
• p95 OOD score
• OOD fallback rate

This separates RF-distance shift (rome_static_far) from mobility shift (rome_slow_close).

Policy-shortcut test

Retrains the strongest behavior classifier with:

• full state
• current scheduler removed
• current PRB allocation removed
• both scheduler and PRB allocation removed

It also reports F1/agreement only on timestamps where the logged policy actually changes.

Paired statistics

Primary comparisons are paired by held-out episode and export:

• mean paired utility delta
• bootstrap 95% CI
• paired random-sign permutation p-value
• Cohen's dz

Seed refits are not described as independent network experiments.

Python 3.13 workflow

The main Dockerfile now uses python:3.13-slim for builder/runtime and CI includes Python 3.13.

Run the complete publication workflow with:

docker compose -f docker-compose.publication.yml up --build publication-test

Dependency chain:

prepare-full-commag -> publication-test

Main outputs under results/publication/:

• publication_baselines.csv
• publication_decisions.csv.gz
• ood_generalization.json
• policy_shortcut_test.csv
• paired_statistics.json
• literature_reference.json
• publication_summary.json

Scientific guardrails

• alternative-action outcomes remain direct-method critic estimates, not causal online intervention effects
• energy remains explicitly a normalized proxy
• original COMMAG PPO numbers are literature references, not reproduced results
• paper-reference values are excluded from apples-to-apples statistical comparisons

Validation still required before paper use

The full large COMMAG publication pipeline must be executed on the target Docker host and the generated results/publication/ evidence reviewed before publication claims are finalized. CI validates Python/static/unit/package/Docker compatibility but does not replace the full publication experiment.