Colony Arena swarm-routing ⌥

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: Phase 2: skeleton with every CI gate

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-onlyplanned
model/ns-3 glue (today: kSwarmCoreApiVersion, SwarmCoreSeed)GPL-2.0-onlypresent
helper/ns-3 helpersGPL-2.0-onlyplanned
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. The five protocols link against swarm-core and register as arms in ns3-tools; 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 provides every repository's reusable CI.linkslinkslinkslinksextractsarmarmarmbuilds inruns inverdictscore/ → WASMleaderboardCIAntHocNetprotocol · 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

Sources

Facts as of 2026-11-08, from the repository's AGENTS.md and the org ROADMAP.