GitHub - ninjahawk/swarmsim: Computational simulations of emergent flocking, phase transitions, and predator-prey dynamics

Model

N agents move on a periodic unit square under four forces each timestep:

Key analytical result: equilibrium cruise speed is v_eq = v₀ + α/μ — not v₀. Derived from force balance in an aligned flock; verified experimentally to within 0.002 across four α values.

Default parameters: N=350, r₀=0.005, ε=0.1, r_f=0.1, α=1.0, v₀=1.0, μ=10.0, η=0.5, dt=0.01

Code Architecture

The codebase has two layers.

Core layer (model.py) — object-oriented foundation for all current and future experiments.

Flock          — holds prey positions, velocities, and all physics parameters
                 flock.evolve(predators=[...]) advances one timestep
Predator       — configurable predator agent; strategy='naive'|'encircle',
                 coord_alpha for predator-predator repulsion, enc_radius for encirclement
simulate()     — runs a full experiment, returns Phi and distance timeseries

New experiments import from model.py. To add a new experiment: import Flock, Predator, and simulate from model.py, set parameters, call simulate().

Legacy layer (flocking.py) — procedural implementation that predates the OOP refactor. The earlier experiment scripts (predator.py, multi_predator.py, encirclement.py, etc.) import from here. They are retained intact for reproducibility and are not broken by the model.py refactor.

Repository Layout

root/
  model.py          ← current API. New experiments import from here.
  geometry.py       ← shared helpers (Rg, AR) — used by both old and new scripts.

  flocking.py       ← legacy: procedural baseline.        [keep for reproducibility]
  analysis.py       ← legacy: validation sweeps.          [keep for reproducibility]
  predator.py       ← legacy: single-predator API.        [keep for reproducibility]
  multi_predator.py ← legacy: multi-predator helpers.     [keep for reproducibility]
  encirclement.py   ← legacy: encirclement scaffolding.   [keep for reproducibility]

predator/    predator strategy experiments
contagion/   panic, epidemic, and vaccination experiments
phase/       phase-transition and statistical-mechanics experiments
3d/          three-dimensional extension experiments
figures/     output PNG figures
outputs/     captured text/log output from runs

The five legacy scripts at root are intentionally retained: every numbered finding F5 through F16 was generated by them, and rerunning them must produce identical figures. New experiments should not import from them — they have no if __name__ == "__main__" guard and will side-effect on import. Use model.py instead.

Experiment scripts in subfolders automatically add the project root to sys.path so they can import the core library files above.

Investigation Progression

The experiments follow a logical arc, each motivated by the result before it:

Results

Flock Formation & Coherence

Flock forms reliably above α ≈ 0.1. With all forces active, the order parameter Φ stays above 0.97 up to noise η ≈ 10, then collapses near η ≈ 20. The alignment force makes the system dramatically more noise-resistant than the repulsion-only case.

Phase Transition Analysis

Finite-size scaling across N = 25–200 (with compactness fixed via r₀ = √(C/πN)) shows KE/N curves are N-independent and susceptibility χ = N·Var(KE/N) increases monotonically at every tested compactness value (C = 0.10–0.78). No diverging peak appears anywhere. The solid-to-fluid transition is a smooth crossover throughout — a consequence of the soft repulsion potential used in this model. A true phase transition would require hard-core exclusion.

Predator Strategy Hierarchy

Flocking prey maintain Φ ≈ 1.0 under sustained predator pressure; non-flocking prey scatter to Φ ≈ 0.1 almost immediately. A minimum evasion buffer distance (~0.10) persists regardless of predator aggression.

With multiple predators, flock coherence remains high (Φ > 0.97) because all predators independently target the same center of mass and co-localize (measured separation ~0.001). This self-undermining behavior was confirmed in evasion_analysis.py.

Adding predator-predator repulsion (coordinated predators) successfully spreads predators out — separation rises to 0.29 — but Φ never drops below 0.92. The flock absorbs distributed pressure from multiple directions without breaking.

Encirclement (each predator assigned a fixed compass angle, targeting CoM offset by R_enc in that direction) is the first strategy to substantially disrupt the flock. At n_pred = 6, Φ drops to 0.77. The minimum predator-prey distance falls to 0.050 vs 0.105 for naive predators.

This Φ = 0.77 does not represent dissolution. fragmentation.py shows that encirclement divides the flock: predators compress agents spatially (60 clusters → 24 larger clusters) while splitting them directionally — each sub-flock escapes through a gap between predators and remains internally coherent (sub-flock Φ = 0.997). This is analogous to wolf-pack herding.

Key Findings

40 findings documented — full evidence and figures: findings.md

Selected highlights:

Full documentation, evidence, and figures for each finding: findings.md

Repository

Core

Experiments (legacy — procedural, import from flocking.py)

Experiments (new — import from model.py)

Supporting files

Run

# Validation and parameter sweeps
python analysis.py

# Phase transition analysis
python phase_transition.py
python compactness_phase.py
python compactness_search.py

# Predator strategy hierarchy
python predator.py
python multi_predator.py
python evasion_analysis.py
python coordinated_predators.py
python encirclement.py
python encirclement_scaling.py
python fragmentation.py

# Panic and contagion
python panic.py
python panic_contagion.py
python contagion_sis.py

# Hybrid stressors
python hybrid_stressors.py
python hybrid_sis.py
python outbreak_removal.py

# Scaling and herd immunity
python large_N_encirclement.py
python renc_scaling.py
python critical_shift.py
python herd_immunity.py
python targeted_immunity.py

# Long-time and adaptive dynamics
python long_encirclement.py
python encirclement_gap.py
python adaptive_encirclement.py

Open sim_demo.html in a browser for a real-time interactive simulation with adjustable parameters.

Tools

• Language: Python 3 — numpy, matplotlib, reportlab
• AI assistance: Claude (Anthropic) — code generation, debugging, research guidance. All AI use documented in research log.

Charbonneau, P. (2017). Natural Complexity: A Modeling Handbook. Princeton University Press.
Silverberg et al. (2013). Collective motion of humans in mosh and circle pits. Physical Review Letters, 110, 228701.