antsim

01What this is, and why it's so COOL!

A toy that tells the truth. You can watch it, play with it, poke it, and enjoy it — and what you are seeing is an exact biological mechanism.

Ants leave the nest, walk a correlated random walk, encounter food, fill their crop, navigate home by path integration, and lay pheromone on the return trip in proportion to the quality of what they are carrying. Other ants sample that pheromone through a nonlinear choice function, which amplifies a chance difference into a committed trail. Food depletes, trails evaporate, the colony converts food into workers, and a colony that cannot reach food starves.

There is no way to author a trail. The scenario format cannot express one, and no function exists to paint one. Every trail that appears on screen is an emergent self-organized structure built from thousands of individual ant decisions.

• 9 / 7 Deneubourg's binary bridge (1990) Two identical arms: colony commits to one arm every time (9 vs 7 across 16 seeds). Symmetry breaking emerges naturally.
• 16 / 16 Goss's double bridge (1989) One arm 1.73× longer: short arm wins 16 out of 16 seeds. Shortest path is discovered purely through timing and positive feedback.
• 43 128 Core test suite checks Plus 95 renderer checks, 0 failures. Fully verified numerically and deterministically across all platforms.

02Visuals: OpenGL Vector Graphics & ASCII Terminal Mode

Two completely distinct, first-class ways to watch and interact with the simulation — from a high-fidelity OpenGL vector window to a zero-dependency terminal interface.

1. The OpenGL 4.5 Vector Engine — Close enough, an ant is an ant

At wide zoom, you see the macro-dynamics of the entire colony: living pheromone fields thickening and evaporating, colony counters, and foraging streams. Zoom in to 4.5 centimetres, and every ant becomes an articulated 2D vector creature.

No moonwalking: The stride phase advances with distance travelled rather than by the clock. During stance, the foot is planted in world space, so legs never slide. The gaster tip visibly flicks down at the exact moment of a pheromone packet deposit, turning an invisible mathematical event into a clear visual action.

2. The ASCII Terminal TUI — Zero GPU, zero graphics dependencies

antsim --tui (or make tui, or (ant:tui)): The entire colony simulation drawn inside your terminal. It needs no GPU, no OpenGL, and no external libraries — built using SBCL's built-in sb-posix subsystem.

This is the perfect way to run antsim over an SSH connection, inside a headless container, or on a minimal server. It dynamically detects your terminal size, redraws only changed cells for blazing performance, and supports full keyboard navigation.

Glyph legend: @ Nest entrance · o Food source · # Obstacle terrain · .,:;+* Shaded trail pheromone on a logarithmic scale · →↘↓↙←↖↑↗ Ants carrying their heading (or -\|/ with --ascii).

The single-tick superpower: In the TUI mode, pressing the . (period) key advances the simulation by exactly one tick. It is the easiest way to inspect and debug individual ant choices step-by-step without attaching a debugger.

03Getting it & Running it

You can run antsim as a standalone native application, through Common Lisp's Quicklisp/Ultralisp, or built straight from source.

1. Standalone Binaries (No Lisp setup required)

Pre-compiled standalone packages are attached to every GitHub Release:

# On Linux: make executable and launch
chmod +x antsim-1.1.1-x86_64.AppImage

./antsim-1.1.1-x86_64.AppImage                       # Launch OpenGL live demo
./antsim-1.1.1-x86_64.AppImage --tui                 # Launch ASCII terminal mode
./antsim-1.1.1-x86_64.AppImage goss-double-bridge    # Load specific scenario
./antsim-1.1.1-x86_64.AppImage --list                # List all available scenarios
./antsim-1.1.1-x86_64.AppImage --help                # Full command options & key legend

2. Running via Common Lisp (Ultralisp / Quicklisp)

antsim is published on Ultralisp. If you have SBCL and Quicklisp installed, launching it is two forms:

;; Install Ultralisp dist (only needed once):
(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)

;; Run the OpenGL Version (requires libglfw and OpenGL 4.5):
(ql:quickload :antsim/live)
(ant:live-demo)

;; Run the ASCII Terminal Version (no extra dependencies; POSIX):
(ql:quickload :antsim/tui)
(ant:tui)

;; Run a specific scenario with a fixed random seed:
(ant:live-scenario "scenarios/goss-double-bridge.json" :seed 12345)

3. Running from Source (Makefile)

Clone the repository. The Makefile automatically sets CL_SOURCE_REGISTRY so the systems build where they stand without manual symlinking.

git clone https://github.com/bonkzwonil/antsim.git
cd antsim

make live              # Launch interactive OpenGL window
make tui               # Launch interactive ASCII terminal simulation
make test              # Run core suite (43 383 checks, no GPU needed)
make acceptance        # Run double bridge & binary bridge 16-seed experiments
make test-render-mesa  # Headless software GL suite via Mesa llvmpipe

# Run specific scenarios or seeds:
SCENARIO=scenarios/antsim.json make live
SCENARIO=scenarios/goss-double-bridge.json make tui
SEED=42 make live      # Exact deterministic replay

Interactive Controls Cheat Sheet

Shipped Scenarios

04Published Experiments & Empirical Results

The point of building on real behavioural science is that results are empirically testable. Two founding experiments in the field run directly as acceptance tests scored against the papers' own published criteria.

1. Goss's Double Bridge (1989) — Shortest Path Selection

Two pathways connect the nest to food: one is 1.73× longer than the other. Nothing in the simulation measures distance or plans routes. Yet traffic rapidly consolidates on the shorter arm.

2. Deneubourg's Binary Bridge (1990) — Symmetry Breaking

Two arms of identical length and geometry connect nest and food. Because both arms are identical, a linear model would split traffic 50/50. In antsim, the colony spontaneously breaks symmetry and commits almost all traffic to a single arm.

3. The Density Window

The double bridge shortest-path selection works over a specific colony density window (roughly 250 to 900 ants). Above ~900 ants, physical crowding and congestion in the narrow corridors cause ants to spill into the longer arm, and the long arm wins. Quoting a bridge result without its colony size is scientifically under-specified.

4. Depletion, Starvation and Trail Evaporation

When a food source is exhausted, ants stop depositing pheromone. Without new deposits, the trail decays exponentially by evaporation alone. If no further food is reached, colony energy drops and workers starve to death, leaving corpses where they fell.

05The Science Model

5.1  Reference Species: Lasius niger

Calibrated against the black garden ant (Lasius niger), the most rigorously quantified mass recruiter in myrmecology literature.

5.2  Correlated Random Walk

In the absence of pheromone or home cues, foragers do not walk in Brownian noise; they execute a correlated random walk. Step turn angles follow a zero-centred wrapped Gaussian distribution, producing locally straight, globally diffusive exploratory trajectories.

5.3  Pheromone Fields & The Deneubourg Choice Function

Ants sample chemical concentrations ahead via left and right antennae. Direction choice is computed through the empirical nonlinear probability function established by Deneubourg:

P(i) = (k + C_i)^n / Σ_j (k + C_j)^n          n ≈ 2,  k ≈ 20

5.4  Path Integration & Route Memory

1. Path Integration (Home Vector): Ants continuously integrate movement vectors into a running home vector pointing back to the nest. This enables a forager in virgin territory to return home and deposit the seed trail.
2. Pheromone Trail Following: Follows active chemical gradients when concentration exceeds k.
3. Route Memory: When direct line-of-sight to the nest is blocked by concavities, ants retrace their outward path history to navigate around obstacles.

5.5  Internal State Machine

5.6  Disc Physics & Jacobi Relaxation

For physics, an ant is modelled as a 2D disc. Non-overlap constraints between ant discs, food discs, and polygon obstacle boundaries are resolved using Jacobi iteration: all overlaps accumulate correction vectors into a buffer before positions are updated. This guarantees order-independence, deterministic multi-threading, and natural crowding at food sources.

06Why Common Lisp & SBCL

Why build a high-performance simulation in Common Lisp? Four architectural properties of SBCL make it uniquely suited for scientific simulation:

1. Controlled Ad-Hoc Experiments via Dynamic Binding

All 65 simulation parameters are dynamic specials (defparameters). An A/B experiment is simply a let form wrapped around a run:

(let ((*resting-ants-block* t)
      (*trail-decay-scale* 3.0f0))
  (world-run! *world* 1200))

No global state is mutated, the rebinding is thread-local, and when the form exits, original parameters are restored automatically. Two threads can execute concurrent runs with differing physics without interfering with each other.

2. The Live SLIME REPL as a Scientific Instrument

A colony takes 20 simulated minutes to mature. In C++ or Rust, testing a new hypothesis means recompiling, restarting, and waiting another 20 minutes. With Common Lisp, attach a SLIME REPL to a live, running colony, recompile an individual function on the fly, and observe the new behaviour instantly in the same world.

3. Ahead-Of-Time Native Machine Code

SBCL does not interpret or use a bytecode VM; it compiles Common Lisp directly into native x86-64 machine code. With type declarations on structure-of-arrays vectors (f32v, u32v), tight inner physics loops run at C-level speed with zero garbage collection allocations.

4. Determinism by Construction

Global random state is strictly banned. Ant random numbers are computed via a pure hash function rnd01(id, tick). Identical seeds produce byte-identical runs across single-threaded and multi-threaded executions.

07Architecture & Scenarios

ASDF Modular System Architecture

Scenario Configuration (JSON)

Scenarios specify arena dimensions, obstacle polygons, nests, food sources, and parameter overrides:

{
  "name": "goss-double-bridge",
  "world":  { "width": 1.2, "height": 0.8, "cell": 0.005 },
  "choice": { "n": 2.0, "k": 20.0, "eavesdrop": 0.1 },
  "colonies": [
    { "id": "home", "nest": { "x": 0.10, "y": 0.40, "r": 0.03 }, "start": 400, "stock": 0.5 }
  ],
  "food": [
    { "x": 1.10, "y": 0.40, "r": 0.02, "amount": 500.0, "quality": 1.0 }
  ],
  "obstacles": [
    { "polygon": [[0.4,0.30],[0.8,0.30],[0.8,0.34],[0.4,0.34]] },
    { "polygon": [[0.4,0.46],[0.8,0.46],[0.8,0.50],[0.4,0.50]] }
  ]
}

08Milestones & Roadmap

1. M0
   Toolchain & Headless Stack done ASDF architecture, RNG, memory pool, headless EGL rendering to PNG.
2. M1
   Scientific Core & Acceptance Suite done Deneubourg choice function, path integration, foraging cycles, double bridge & binary bridge acceptance tests passing.
3. M2
   OpenGL Renderer & Live Window done Hardware-accelerated viewport, cursor-anchored zoom, pan, multisampling, headless CI suite.
4. M3
   Articulated Vector Ant & Gait done 6-legged alternating tripod gait articulated in vertex shader, sweeping antennae, gaster deposit flicks, LOD.
5. M4
   The Society & Terminal TUI done · v1.1.1 Multiple competing colonies, eavesdropping coefficient ε, necrophoresis corpse clearing, route memory around concavities, standalone AppImage/Windows shipping, and the POSIX ASCII terminal mode.
6. M5
   Live Interaction in progress Interactive ant inspection HUD, click-to-drop food sources, obstacle placement, alarm pheromone triggering.
7. M6
   Polish & Species Variations planned Time-lapse recording tools, Formica polyctena landmark-heavy species calibration set.

09Decisions & Sources

Core Scientific Citations

• Deneubourg, Aron, Goss & Pasteels (1990), The self-organizing exploratory pattern of the Argentine ant, J. Insect Behavior 3:159 — the binary bridge, and the nonlinear choice function.
• Goss, Aron, Deneubourg & Pasteels (1989), Self-organized shortcuts in the Argentine ant, Naturwissenschaften 76:579 — the double bridge and shortest-path selection.
• Beckers, Deneubourg & Goss (1992, 1993), Trail laying behaviour in Lasius niger — modulated deposition and sucrose threshold.
• Robinson, Jackson, Holcombe & Ratnieks (2005), “No entry” signal in ant foraging, Nature 438:442 — repellent pheromone signaling.
• Wilson, Durlach & Roth (1958), Chemical releasers of necrophoric behavior in ants — necrophoresis corpse clustering.
• Hölldobler & Wilson (1990), The Ants — general reference for age polyethism, trophallaxis, and morphology.