Queen's chamber · Shared module · swarm-routing/ns3-swarm-core

swarm-core

What two or more protocols share: the swarm-core contrib module every protocol links against.

Under construction: v0.2.0 released, 1 epic planned Computed from its 2 epics · release v0.2.0, as they stood on .

RepositoryEpic ns3-swarm-core#6

What it does

swarm-core is the shared ns-3 contrib module (libns3.<ver>-swarm-core, #include "ns3/swarm-core-module.h"). Its core/ will hold simulator-free C++20 primitives extracted from AntHocNet's dual-licensed core: the bounded VisitedPath, little-endian wire helpers, PheromoneTable, RouteDecision, the ILinkState / ILinkMetric seams, evaporation and roulette selection.

Its model/ will hold the ns-3 glue: SwarmRoutingBase, a DeferredPacketQueue, WifiLinkMonitor, EnergyMetricHook over ns3::EnergySource, and IslLinkMonitor for satellite links. Nothing protocol-specific lands here: code is promoted only when a second protocol needs it.

Today the skeleton is in place (kSwarmCoreApiVersion, SwarmCoreSeed) and CI already runs every org quality gate on it: strict warnings, debug and sanitized builds, coverage, format, licence headers, and the determinism gate (same seed twice byte-identical, another seed different).

Diagrams

swarm-core: planned primitives and glue (UML class diagram)Class diagram of swarm-core's planned API. In core, simulator-free: VisitedPath, PheromoneTable, RouteDecision, the ILinkState and ILinkMetric interfaces, evaporation and roulette selection. In model, the ns-3 glue: SwarmRoutingBase, DeferredPacketQueue, WifiLinkMonitor realising ILinkState, EnergyMetricHook and IslLinkMonitor.core«MIT OR GPL-2.0-only»VisitedPath+ push(node) : bool+ contains(node) : bool- cap : size_tPheromoneTable+ get(dst, via) : double+ deposit(dst, via, Δτ)+ evaporate(ρ)RouteDecision+ action : Forward|Drop|Queue+ nextHop : NodeId«function»roulette+ pick(weights, rng)«interface»ILinkState+ isUp(nbr) : bool«interface»ILinkMetric+ cost(nbr) : doublemodel«GPL-2.0-only · ns-3»SwarmRoutingBasens3::Ipv4RoutingProtocol+ execute(RouteDecision)DeferredPacketQueue+ enqueue(p, dst)- cap : size_tWifiLinkMonitorMAC tx-failure tracesIslLinkMonitorsatellite ISL stateEnergyMetricHookns3::EnergySource«use»
Class diagram (UML) of the planned API (dashed: not written yet; ns3-swarm-core#8, #9). Hollow triangles: interface realisation; open arrows: «use». Only model includes ns3/*.
swarm-core: the determinism gateThe determinism gate: build swarm-core-seed, run it with seed 1 twice and compare the output byte for byte, then run seed 2 and require a difference.buildns3-build-contrib--strict-warningsseed=1run Aseed=1run Bcmp A Bbyte-identicalseed=2must differ
The determinism gate every run of its CI has (org invariant 5).

Package structure

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

Directories of swarm-routing/ns3-swarm-core
PathWhatLicenceState
CMakeLists.txtbuild_lib(LIBNAME swarm-core ...); ns-3 generates ns3/swarm-core-module.hGPL-2.0-onlypresent
core/simulator-free primitives, injected ports, carries core/LICENSEMIT OR GPL-2.0-onlypresent
model/ns-3 glue: SwarmRoutingBase, DeferredPacketQueue, the link monitors, EnergyMetricHookGPL-2.0-onlypresent
helper/SwarmRoutingHelper, SwarmMonitorHelper, SwarmLifecycleHelperGPL-2.0-onlypresent
test/swarm-core test suite: roundtrip, fuzz, primitives, glueGPL-2.0-onlypresent
examples/swarm-core-seed: the determinism gate's programGPL-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
swarm-core and its neighbours in the organisation.

Quests

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

Closed: 1 epic

Cite this project

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

Text

Joppi, Daniel Henrique (n.d.). ns3-swarm-core (version 0.2.0) [Computer software]. https://doi.org/10.5281/zenodo.24138628

BibTeX

@software{ns3swarmcore,
  author  = {Joppi, Daniel Henrique},
  title   = {ns3-swarm-core},
  version = {0.2.0},
  doi     = {10.5281/zenodo.24138628},
  url     = {https://github.com/swarm-routing/ns3-swarm-core}
}

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

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

References

The 3 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.

Implemented

Software it builds on

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