q2ns-beyondlayering-dev

This repository contains the reproducibility artifact for the ICNS3 submission:

A Dynamic-Kernel/QPacket Executable for Quantum Repeater Chains in Q2NS/ns-3

The artifact includes a self-contained ns-3.47 + Q2NS simulation substrate, one ns-3 experiment program, the final summary dataset used for the paper figures, an exact simulation-task manifest, a smoke-test manifest, a data-collection script, and an analysis/plotting script.

The included paper figures can be regenerated from the included summary data without rerunning the full simulation campaign. The main summary dataset, data/summary_all.csv, is stored with Git LFS and must be pulled before running the analysis commands below.

Requirements

Docker with Docker Compose support is the recommended workflow. No local installation of ns-3, Q2NS, Python, CMake, or C++ build tools is required when using Docker.

Verify Docker is available with:

docker --version
docker compose version

Large data files and Git LFS

This repository uses Git Large File Storage (Git LFS) for the large released data file:

data/summary_all.csv

This file is required to regenerate the paper figures without rerunning the full data collection.

Before cloning the repository, install Git LFS. You can find full installation instructions on the Git LFS wiki.

Then clone the repository normally:

git clone https://github.com/QuantumInternet-it/q2ns-beyond-layering-dev.git
cd q2ns-beyond-layering-dev
git lfs pull

If the repository was cloned before Git LFS was installed, run this from the repository root:

git lfs install
git lfs pull

To verify that the full dataset was downloaded correctly, check the file size:

ls -lh data/summary_all.csv

The file should be hundreds of MB. If it is only a few hundred bytes and contains text beginning with:

version https://git-lfs.github.com/spec/v1

then Git LFS has not downloaded the actual dataset yet. Run:

git lfs pull

The Docker analysis workflow assumes that the real data/summary_all.csv file is present, not just the Git LFS pointer file.

Repository layout

q2ns-beyondlayering-dev/
├── Dockerfile
├── docker-compose.yml
├── README.md
├── LICENSE
├── requirements.txt
├── assets/
│   ├── Q2NS Logo Large.png
│   ├── logo-erc.png
│   └── logo-full.png
├── ns-3.47/
│   ├── scratch/
│   │   └── qkernel.cc
│   └── contrib/
│       └── q2ns/
├── scripts/
│   ├── collect_data.sh
│   └── analyze_data.py
└── data/
    ├── summary_all.csv
    ├── tasks/
    │   ├── all_tasks.tsv
    │   └── smoke_tasks.tsv
    └── analysis/
        ├── data/
        ├── paper_figures/
        └── extra_figures/

The main ns-3 experiment source is:

ns-3.47/scratch/qkernel.cc

Q2NS is included as an ns-3 contrib module at:

ns-3.47/contrib/q2ns/

The final paper dataset is:

data/summary_all.csv

The exact task manifest corresponding to the paper dataset is:

data/tasks/all_tasks.tsv

The quick smoke-test manifest is:

data/tasks/smoke_tasks.tsv

Build the container

From the repository root:

docker compose build

The Docker build compiles ns-3.47 and Q2NS inside the container. The built ns-3 tree is available at:

/opt/ns-3.47

The repository workspace is available at:

/workspace

Regenerate the included paper figures

The repository already includes the final summary dataset used for the paper figures. Make sure Git LFS has downloaded data/summary_all.csv before running this command; otherwise the analyzer will receive only the small LFS pointer file.

To regenerate the analysis outputs from the included dataset:

docker compose run --rm q2ns python3 /workspace/scripts/analyze_data.py /workspace/data/summary_all.csv

This writes outputs under:

data/analysis/
├── data/
├── paper_figures/
└── extra_figures/

The main sanity-check report is:

data/analysis/data/checks.md

The analysis report is:

data/analysis/data/analysis_report.md

Smoke test

The smoke test runs a very small set of simulations. It is intended only to verify that the simulator, collection script, and analysis script work end-to-end. The resulting plots are expected to be noisy.

collect_data.sh calls ./ns3 run, so it must be launched from an ns-3 root directory. In Docker, use the prebuilt ns-3 tree at /opt/ns-3.47 and write outputs to /workspace/data/runs/....

docker compose run --rm q2ns bash -lc \
  'cd /opt/ns-3.47 && BUILD=0 OUTDIR=/workspace/data/runs/smoke /workspace/scripts/collect_data.sh /workspace/data/tasks/smoke_tasks.tsv'

Analyze the smoke-test output:

docker compose run --rm q2ns python3 /workspace/scripts/analyze_data.py /workspace/data/runs/smoke

The smoke-test outputs are written under:

data/runs/smoke/
├── README.txt
├── summary_all.csv
├── tasks/
├── run_csv/
├── logs/
└── analysis/

Full data regeneration

The full paper dataset can be regenerated from the exact task manifest:

docker compose run --rm q2ns bash -lc \
  'cd /opt/ns-3.47 && BUILD=0 OUTDIR=/workspace/data/runs/full /workspace/scripts/collect_data.sh /workspace/data/tasks/all_tasks.tsv'

Then analyze the regenerated dataset:

docker compose run --rm q2ns python3 /workspace/scripts/analyze_data.py /workspace/data/runs/full

The full run can take a long time. The repository includes data/summary_all.csv so that users can reproduce the figures without rerunning the full simulation campaign.

Custom or default data collection

The collection script can also be run without a task manifest. It should still be launched from /opt/ns-3.47 or another directory containing the ./ns3 executable. In that case, it runs the script's built-in default sweep, which is intended to be easy to modify for exploratory runs.

docker compose run --rm q2ns bash -lc \
  'cd /opt/ns-3.47 && BUILD=0 OUTDIR=/workspace/data/runs/default /workspace/scripts/collect_data.sh'

Useful environment-variable overrides include:

JOBS=4
OUTDIR=/workspace/data/runs/my_run
QKERNEL_TARGET=qkernel
BUILD=0
VERBOSE=false
QUANTUM_DELAY_MS=0.5
CLASSICAL_DELAY_MS=0.5
QPACKET_EMIT_INTERVAL_NS=1.0

For example:

docker compose run --rm q2ns bash -lc \
  'cd /opt/ns-3.47 && JOBS=4 BUILD=0 OUTDIR=/workspace/data/runs/my_run /workspace/scripts/collect_data.sh /workspace/data/tasks/smoke_tasks.tsv'

Note: The simulator exposes optional extra command-line outputs for per-node metrics and QPacket trace dumps. These were not required for the paper figures and can result in extremely large data files, so the collection script does not collect them by default.

Output conventions

For a newly collected run, collect_data.sh creates an output directory such as:

data/runs/smoke/
├── README.txt
├── summary_all.csv
├── tasks/
│   └── all_tasks.tsv
├── run_csv/
│   └── *.summary.csv
└── logs/
    └── *.log

The analysis script accepts either a summary_all.csv file directly or a directory containing summary_all.csv:

python3 ./scripts/analyze_data.py data/runs/smoke/summary_all.csv
python3 ./scripts/analyze_data.py data/runs/smoke

The included paper dataset is named data/summary_all.csv; after Git LFS has pulled the full file, pass it directly to the analyzer:

python3 ./scripts/analyze_data.py data/summary_all.csv

Cleaning generated outputs

To remove generated runs while keeping the included paper dataset and checked-in analysis outputs:

rm -rf data/runs

To regenerate the checked-in analysis from the included summary data, first make sure Git LFS has pulled the full data/summary_all.csv file:

git lfs pull
rm -rf data/analysis
python3 ./scripts/analyze_data.py data/summary_all.csv

Do not remove these files unless you intend to replace the released dataset:

data/summary_all.csv
data/tasks/all_tasks.tsv
data/tasks/smoke_tasks.tsv

Simulation substrate

This artifact vendors a prepared ns-3.47 source tree.

• ns-3 version: 3.47
• Q2NS source: https://github.com/QuantumInternet-it/q2ns
• Q2NS commit: 5c7be8f0f06460ad6c2112683f4dc40cd125b8f6

The Docker build does not clone ns-3 or Q2NS from the internet. The build may still download Ubuntu and Python packages unless a prebuilt image is used.

Native ns-3 build without Docker

Docker is the recommended path. A native build should work on Linux/macOS if the usual ns-3 build dependencies are installed, but this path is provided mainly for users already familiar with ns-3.

From the repository root:

cd ns-3.47
./ns3 configure
./ns3 build qkernel -j 2
cd ..

Run the smoke-test manifest natively:

cd ns-3.47
OUTDIR="$PWD/../data/runs/smoke_native" \
  ../scripts/collect_data.sh ../data/tasks/smoke_tasks.tsv
cd ..
python3 ./scripts/analyze_data.py data/runs/smoke_native

The Docker workflow is the primary tested artifact workflow. Native execution is expected to be fairly easy on Linux, okay but more fragile on macOS, and not worth supporting directly on Windows except through WSL2.

Acknowledgements

This work has been funded by the European Union under Horizon Europe ERC-CoG grant QNattyNet, n.101169850. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency. Neither the European Union nor the granting authority can be held responsible for them.

    

---

License: This project is licensed under the GNU General Public License v2.0 only (GPL-2.0-only). See the LICENSE file for details.