AntHocNet

▶ Learn it by playing — a city-builder for networks and ants that runs this repository's routing core, compiled to WebAssembly, in your browser: place and move phones, break links, and watch the ants find the way. Code reference: API docs.

A paper-faithful AntHocNet you can install on a stock ns-3 tree in three commands — a drop-in contrib/ module, no forked simulator. It is benchmarked against AODV / OLSR / DSDV on identical scenarios under a fixed methodology (20-seed, 900 s runs; every published number carries a 95% confidence interval — methodology). The algorithm itself is simulator-independent C++ with its own unit-test suite: make test runs it with no simulator installed. Releases are archived on Zenodo with DOIs, so results can cite an exact, immutable version.

AntHocNet vs AODV / OLSR / DSDV across the six named MANET scenarios (error bars: 95% CI) — current numbers and per-scenario pages in docs/benchmarks.md.

An ant-colony-optimization routing protocol for mobile ad-hoc networks, implemented once as a simulator-agnostic algorithm core with a thin NS-3 adapter (and a browser adapter that runs the same core as WebAssembly on the learn site, the project's front page).

The repository does not bundle a copy of any simulator. You install AntHocNet onto your own NS-3 tree as an additive contrib/ module (ns-3.36+, with a wscript for older waf builds).

Note

NS-2 support was removed in v2.0.0 (#307). It was frozen at v1.2.0 and shipped through v1.9.0; where to get it, the images and the rationale are in docs/ns2-support.md.

core/   simulator-agnostic C++ (no simulator dependency) + unit tests
ns3/    native Ipv4RoutingProtocol module
web/    browser adapter: core/ compiled to WebAssembly + the learn site
docs/   architecture, configuration, benchmarks, fidelity, ADRs — map in docs/README.md

Why one core, thin adapters

Simulators differ in architecture, so there is no single universal patch. The algorithm (pheromone table, evaporation/reinforcement, ant construction, routing decisions) lives in core/ and is shared verbatim; each simulator gets only a thin adapter that converts packets and executes the decisions the core returns. See docs/architecture.md and ADR-0023 for why the split stays with one simulator adapter.

flowchart TB
    H["Benchmark harnesses (ns3/anthocnet/examples)<br/>anthocnet-compare · isl-grid · run-scenarios.py"]

    subgraph NS3["ns3/ — contrib module (supported)"]
        A3["RoutingProtocol : Ipv4RoutingProtocol<br/>~30 attributes = the config surface"]
    end
    subgraph WEB["web/ — browser adapter (WebAssembly)"]
        AW["ahn_web::World<br/>held to native by a trace parity gate"]
    end

    P["Ports: IClock · IRng · INeighborProvider · ITimerScheduler"]

    subgraph CORE["core/ — simulator-agnostic C++, unit-tested (make test)"]
        C1["AntRouterLogic → RouteDecision"]
        C2["PheromoneTable · PheromoneEngine"]
        C3["AntMessage codec (versioned wire format)"]
    end

    H --> A3
    A3 --> P
    AW --> P
    P --> C1
    C1 --- C2 --- C3

    style CORE fill:#e2f0ed,stroke:#0f7f70,stroke-width:2px

Loading

The full stack — every mechanism, the switch that gates it, and what is live/inert per network regime — is diagrammed in docs/software-layers.md.

Quick start

Run a simulation with zero setup (Codespaces / VS Code devcontainer)

One click gives you a container with ns-3.42 already built (.devcontainer/, on the pinned GHCR image); it installs this checkout's AntHocNet module and builds it for you. Locally: clone, then VS Code → Dev Containers: Reopen in Container. When the setup log finishes:

cd /opt/ns-3
./ns3 run anthocnet-example                          # your first simulation
./ns3 run "anthocnet-compare --nNodes=20 --time=30"  # vs AODV / OLSR / DSDV

Run the core unit tests

make test

(Builds core/ with CMake and runs the ctest suite — no simulator needed.)

Install on NS-3

From a checkout:

make doctor      NS3DIR=/path/to/ns-3      # checks the tree, ns-3 version, CMake, compiler
make install-ns3 NS3DIR=/path/to/ns-3      # BASELINES=0: AntHocNet alone, no comparison arms
cd /path/to/ns-3 && ./ns3 configure --enable-examples --enable-tests && ./ns3 build
./ns3 run anthocnet-example

Without a checkout: download anthocnet-ns3-modules-<version>.tar.gz from the latest release, then tar -xzf anthocnet-ns3-modules-<version>.tar.gz -C /path/to/ns-3/contrib and build as above. The same files are on the generated ns3-module branch.

With ns-3's installer, bake: each release from v2.3.0 on attaches anthocnet-<version>.bakeconf.xml. Copy it into your bake checkout's contrib/ directory, then run ./bake.py configure -e ns-3.42 -e anthocnet && ./bake.py download && ./bake.py build. Any ns-3 from 3.36 works. This builds AntHocNet alone, without the comparison modules. The recipe is built end to end weekly (bake.yml).

Uninstall: make uninstall-ns3 NS3DIR=.... Supported: ns-3.36 to ns-3.48. Details in ns3/README.md.

The NS-3 module also ships anthocnet-compare, which benchmarks AntHocNet against AODV / OLSR / DSDV on an identical scenario (delivery ratio, delay, throughput via FlowMonitor) — see ns3/README.md. Current results, regenerated on every merge to the default branch, are in docs/benchmarks.md; the commands to reproduce a run, and the validation anchors to check first, are in docs/benchmarks/methodology.md.

Tune the protocol

Every tunable parameter, its default, where that default came from, and the calibration loop (sweep one knob → A/B → noise verdict) are in docs/configuration.md. ns-3 exposes them as attributes:

./ns3 run "anthocnet-compare --scenario=paper --runs=5 \
  --ns3::anthocnet::RoutingProtocol::HopTime=0.003"

Container images

Prefer not to install a simulator yourself? Pre-built images are published to GHCR (ghcr.io/danieljoppi/…) — for each supported version, a plain simulator and the same simulator with AntHocNet built in (so you can compare against a clean baseline):

docker run --rm ghcr.io/danieljoppi/anthocnet-ns3:3.42 ./ns3 run anthocnet-example

Each image has three tag tiers: :<sim-version> (e.g. :3.42, latest build for that simulator version), :<sim-version>-<release> (e.g. :3.42-v0.3.0, immutable — pin this for reproducible / citable runs), and :latest (newest simulator version + latest AntHocNet). The :<sim-version> and :latest tiers track the default branch; the -<release> tier is fixed to a release.

AntHocNet images — the simulator with our protocol built in:

Image	Versions	Contents
ghcr.io/danieljoppi/anthocnet-ns3	3.36, 3.41, 3.42, 3.47, 3.48	ns-3 + the AntHocNet module

Plain images — a clean simulator (no AntHocNet) for baseline comparisons:

Image	Versions	Contents
ghcr.io/danieljoppi/ns3	3.36, 3.41, 3.42, 3.47, 3.48	plain ns-3 with the comparison protocols (AODV/OLSR/DSDV/…)

Build them yourself or see the full matrix in docker/README.md. The NS-2 images built through v1.9.0 stay pullable; see docs/ns2-support.md.

Supported network regimes

One protocol binary, unchanged defaults, five network families, each with a results page measured in ns-3:

family	how it runs	results
MANET (paper + thesis fields)	anthocnet-compare	grid
Static Wi-Fi mesh	anthocnet-compare (static cell)	static mesh
FANET, a 3-D UAV swarm	--scenario=fanet	FANET
VANET, vehicles on a Manhattan grid with building shadowing	--scenario=vanet	VANET (with the four-family ranking statement)
Satellite: the ISL +Grid snapshot and a moving Walker / Starlink shell	isl-grid, leo-walker	ISL grid, moving constellation
Disaster, first-responder teams in a partly walled incident area	--scenario=disaster	disaster

What is unknown in each regime decides which of AntHocNet's mechanisms matter there — the family table, the side-by-side harness comparison, and the mechanism-by-mechanism live/inert map are all in docs/network-regimes.md.

Roadmap

Accepted 2026-10-09 (roadmap, with the research behind it and the game campaign design). Every release has a release: label and filed issues.

flowchart LR
    V20["<b>v2.0.0</b> ✅<br/>moving constellation<br/>+ learn site"]
    V21["<b>v2.1.0</b><br/>the site is the game<br/>+ repo restructure"]
    V22["<b>v2.2.0</b><br/>fix the measured gaps<br/>· game: ad hoc + mesh"]
    V23["<b>v2.3.0</b><br/>opt-in tweaks per network<br/>· game: VANET, FANET, orbit"]
    V24["<b>v2.4.0</b><br/>disaster + space-air-ground<br/>· game: chapters 6–8"]
    V25["<b>v2.5.0</b><br/>ARA · Termite · learned<br/>comparators"]
    V30["<b>v3.0.0</b><br/>secured AntHocNet"]
    V31["<b>v3.1.0</b><br/>SAODV · SEAD · TAODV"]
    V32["<b>v3.2.0</b><br/>secure swarm<br/>comparators"]
    V33["<b>v3.3.0</b><br/>wormhole · Sybil ·<br/>pheromone poisoning"]
    V20 --> V21 --> V22 --> V23 --> V24 --> V25 --> V30 --> V31 --> V32 --> V33

Loading

What changed from the original

The original project was a whole vendored ns-allinone-2.34 snapshot with the protocol buried inside it. This refactor:

• extracts the algorithm into a portable, tested core/ library;
• replaces the NS-2-coupled, header-resident malloc'd pointer arrays with POD value types — removing a memory leak, a broadcast double-free, and an incorrect serialized packet size;
• fixes the pheromone-evaporation bug (competing links were never aged), widens the ant sequence number past 8 bits, and bounds the dedup history;
• shipped the NS-2 integration as an idempotent, anchor-based patch instead of a forked simulator tree (through v1.9.0; removed in v2.0.0);
• adds a native NS-3 module.

History of the work is in the per-phase commits; design rationale is in docs/:

• architecture.md — core/ports design and decision flow
• porting-notes.md — bug fixes, wire-format and version caveats
• configuration.md — every parameter, its provenance, how to calibrate
• benchmarks.md — AntHocNet vs AODV/OLSR/DSDV (auto-updated)
• ns2-support.md — the removed NS-2 target: where to get it, images, rationale

Documentation

Document	Purpose
docs/README.md	The docs map — every page in docs/, grouped by what you are trying to do.
docs/ant-colony-routing.md	Concepts primer: ant foraging → ACO → AntNet → AntHocNet, and how they map to the code. Start here for the idea.
docs/ant-types.md	The five ant types side by side: what triggers each, how it travels, what it writes, which switch gates it — plus lifecycle diagrams.
docs/architecture.md	Design, the core/adapter split, and the decision flow.
docs/roadmap.md	Where the project is going: release ladder, epic dependency graph, exit criteria per release, and what is deliberately not planned.
docs/software-layers.md	Diagrams: the software stack, ant mechanisms + their config switches, and what runs (live/inert/planned) in each network regime.
docs/porting-notes.md	Bugs fixed in extraction, wire format, version caveats.
docs/configuration.md	Every tunable parameter, its default and where that default came from, the ns-3 attribute for it, and the calibration loop. Read before changing a knob or trusting one.
docs/benchmarks.md	Results index → metrics, methodology, per-scenario and per-sweep pages.
docs/fidelity.md	What v1.0 reproduces from the 2004 paper and where it deliberately deviates.
docs/wire-format.md	Canonical on-wire ant layout, version byte, and diff vs. the original and the papers.
docs/publications/	Source-of-truth digests of the 2004 paper and 2007 thesis — what every fidelity claim is checked against.
docs/network-regimes.md	Why MANET and satellite/ISL routing are different problems (the satellite research track's ground rules), and which AntHocNet mechanism is live/inert in each regime (§6).
docs/adr/	Architecture Decision Records 0001–0023, indexed — the "why" behind the structure.
paper/	JOSS software-paper draft (paper.md/paper.bib), for submission against this repo.
CONTEXT.md	Project orientation: domain background, repo map, current state, glossary, open questions.
AGENTS.md	Build/verify/conventions and invariants for contributors and AI agents.
docs/ns2-support.md	The removed NS-2 target — which tags and images still carry it, and why it was retired.
ns3/README.md · web/README.md	Per-adapter install/run details.
docker/README.md	Pre-built container images (plain vs. AntHocNet, per simulator version).

Releases & citing

Versioning follows SemVer; see CHANGELOG.md. Each release publishes a lean install bundle zip and the drop-in ns-3 modules tarball on GitHub Releases (via .github/workflows/release.yml). There is no prebuilt simulator .so/installer by design — an ns-3 module is ABI/version-locked to the user's tree, so it is distributed as source (make install-ns3) plus the pre-built Docker images on GHCR (see docker/README.md).

To cite this implementation, use the “Cite this repository” button (from CITATION.cff). Each release is archived on Zenodo with its own DOI:

DOI	resolves to
10.5281/zenodo.20981979	concept DOI — always the latest release. This is the badge above, and the right citation when you mean "this project".
10.5281/zenodo.21795253	version DOI — v1.3.0. Cite this when reproducing a published number: every benchmark result in docs/benchmarks/ was measured at or before that tag, and main has since moved (see Provenance).

Both are recorded in CITATION.cff; the version DOI for a future release is added there when that release is archived. Please also cite the sources this implements:

• G. Di Caro, F. Ducatelle, L. M. Gambardella, AntHocNet: an Ant-Based Hybrid Routing Algorithm for Mobile Ad Hoc Networks, PPSN VIII, LNCS 3242, pp. 461–470, Springer, 2004 — the algorithm (digest).
• F. Ducatelle, Adaptive Routing in Ad Hoc Wireless Multi-hop Networks, PhD thesis, Università della Svizzera Italiana / IDSIA, 2007 — the designated primary source for parameters the paper leaves unspecified (status).

What this implementation reproduces from those sources — and every deliberate deviation — is stated in docs/fidelity.md.

Contributing

CONTRIBUTING.md has the build/test steps per component, the code style, and the Conventional-Commit PR-title rules; AGENTS.md has the golden rules (invariants) and verification workflow. Bugs and findings are tracked as GitHub issues with a label taxonomy (ADR-0013); changes to protocol behaviour are expected to carry an A/B benchmark verdict (docs/configuration.md §5). Security reports: SECURITY.md.

License

See LICENSE. Original implementation by Daniel Henrique Joppi.