Field lab · Tooling · swarm-routing/ns3-tools

ns3-tools

Protocol-agnostic comparison: the harness every arm registers with, and the scripts that judge the runs.

Unlocked: v1.0.0 released, 1 epic in progress, 4 planned Computed from its 5 epics · release v1.0.0, as they stood on .

RepositoryMarker contractComparators ns3-tools#15

What it does

ns3-tools is where protocols meet on equal terms. The routing-bench module (moved from AntHocNet as-is) is the comparison harness: every protocol, ours or a comparator, registers as an arm through its own helper/<module>-bench-arms.cc, and no arm is special-cased. It also holds the measurement itself today: the topology oracle (BFS-reachable delivery ratio, path stretch) and the drop book (PHY/MAC/ARP/TTL/loop root causes). A run prints the versioned marker lines ##CONFIG##, ##RUN##, ##BENCH##, ##DIAG## and ##PROV##.

The ns3-tool CLI (compare, sweep, diagnose, scaffold) fronts the Python readers (stdlib only): they parse those lines and do the statistics, per-seed paired deltas over at least 20 seeds and a scripted noise verdict, never an eyeballed one, checked byte-identical against fixture cells from AntHocNet. ns3-campaign runs a multi-protocol campaign: one image, every cell pulled by digest, each keyed over every pinned input. The CLI and marker contract v1 are frozen: fields, commands and options are only appended, and a breaking change waits for contract v2.

Planned next: non-intrusive probes as their own module (the oracle and the drop book extracted), the satellite harnesses on the arm registry, and the non-swarm comparator arms, each its own module under ns3/arms/. Whether the universal arenas of the original plan stay is an open decision.

Diagrams

ns3-tools: from an arm to a verdictData flow through ns3-tools: a protocol's module registers an arm through its bench-arms helper; routing-bench runs the scenario over at least twenty seeds per arm and prints the versioned marker lines; the stdlib readers parse them, pair runs by seed and compute deltas and a noise verdict; the result is written into the benchmarks repository with its manifest.armhelper/<m>-bench-arms.ccrouting-benchrouting-compare≥ 20 seedsmarker lines##CONFIG## ##RUN####BENCH## ##DIAG##ns3_toolbench_parsestats_util, pool_runsverdictpaired Δ per seednoise callbenchmarksruns/ + manifestverdicts/
Data flow: the marker lines are a versioned contract (fields only appended), and every verdict is a script's output, never an eyeballed number.
ns3-tools: package diagramUML package diagram of ns3-tools: the routing-bench harness module, the planned comparator arm modules and probes, the ns3_tool Python readers and their tests, and the ns3-dev images they run in.registers«use»parses lines«use»builds inns3::routing-bench«GPL-2.0-only»routing-comparearm registrymarker emittersns3/arms/<name>«GPL-2.0-only»SAODV, SEAD, TAODVDRL, DTNone module eachns3 probes + arenas«GPL-2.0-only»TopologyOracleDropCauseClassifiermanet-, leo-walker-arenapython/ns3_tool«MIT OR GPL-2.0-only»bench_parse, stats_utilpool_runs, sweep_summarynative / comparator viewspython/tests«MIT OR GPL-2.0-only»self-tests13 AntHocNet cellsbyte-identical outputns3-dev image«ns3-containers»latest-debuglatest-sanitized
Package diagram (UML). Each comparator arm is its own module that registers exactly as an out-of-repo arm does; no code outside its directory names it. Dashed: planned.

Package structure

The repository's layout, its licence per directory (LICENSING.md) and what exists today.

Directories of swarm-routing/ns3-tools
PathWhatLicenceState
ns3/routing-bench/the comparison harness module (routing-compare, anthocnet-compare alias; topology oracle, drop book)GPL-2.0-onlypresent
ns3/arms/<name>/non-swarm comparator arms (SAODV, SEAD, TAODV, DRL, DTN), one module eachGPL-2.0-onlyplanned
ns3/ (probes, satellite harnesses)the probe module (oracle and drop book extracted); satellite harnesses on the arm registryGPL-2.0-onlyplanned
python/ns3_tool/the ns3-tool CLI, readers and statistics, scenario_check, ns3-campaign and its change-test plansMIT OR GPL-2.0-onlypresent
python/tests/self-tests; fixtures/cells/: 14 AntHocNet cellsMIT OR GPL-2.0-onlypresent
campaigns/campaign plans (TOML), each campaign's pre-registrationGPL-2.0-onlypresent
tools/checks/CI scripts: stock arms, arm delivery, ##PERF##, the scaffolded armMIT OR GPL-2.0-onlypresent
tools/release/dist.sh: the release assets (routing-bench tarball, ns3-tool wheel and sdist)MIT OR GPL-2.0-onlypresent
docs/markers.md (the marker contract), profiling.md, roadmap.md, references.bibGPL-2.0-onlypresent

Where it sits in the colony

The swarm-routing organisation: who depends on whomDependency graph of the swarm-routing organisation. ARA, BeeAdHoc, Termite and HOPNET link against swarm-core, which was extracted from AntHocNet, and register as arms in ns3-tools; AntHocNet runs its benchmarks on ns3-tools' harness; swarm-core and ns3-tools build and run inside the ns3-containers images; ns3-tools writes verdicts into benchmarks; the Colony Arena site builds AntHocNet's core to WebAssembly and will render the benchmarks leaderboard; the .github repository's reusable CI runs inside the ns3-containers images.linkslinkslinkslinksextractsarmarmarmarmbenchbuilds inruns inverdictscore/ → WASMleaderboard (planned)CI imagesAntHocNetprotocol · liveARAprotocolBeeAdHocprotocolTermiteprotocolHOPNETprotocolswarm-coreshared modulens3-toolsharness · readersns3-containersns3-dev imagesbenchmarksdatasets · verdictsColony Arenathis site.githubreusable CI · templatesdashed arrow: «use» dependency (UML); highlighted: this project and its neighbours
ns3-tools and its neighbours in the organisation.

Quests

The repository's epics and their sub-issues, as the issues stood on 2026-11-13: 3 of 31 sub-issues closed.

Cite this project

Using ns3-tools in a paper? Cite the project as below, and the works it rests on from its references.

Text

Joppi, Daniel Henrique (n.d.). ns3-tools (version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.24136068

BibTeX

@software{ns3tools,
  author  = {Joppi, Daniel Henrique},
  title   = {ns3-tools},
  version = {1.0.0},
  doi     = {10.5281/zenodo.24136068},
  url     = {https://github.com/swarm-routing/ns3-tools}
}

Version
1.0.0
Author
Daniel Henrique Joppi · ORCID
DOI
10.5281/zenodo.24136068
Licence
GPL-2.0-only

Read from CITATION.cff at main when this site was built.

References

The 5 works docs/references.bib lists, read at main when this site was built. Each links its DOI; a work with none links its publisher's or institution's page.

Datasets

Software it builds on

Background

Sources

The status and the quests come from the repository's issues and releases (2026-11-13); the other facts on this page are kept by hand from its AGENTS.md (as of 2026-11-08).