Skip to Content
Our ToolsGossamer Threaded Intelligence

Gossamer Threaded Intelligence

Lightweight Python library of swarm intelligence algorithms and utilities that drive agent behavior inside the Leviathan Engine and visualize via Maneuver.Map. Use it standalone for algorithm prototyping, or plug it into Leviathan for high‑performance, multi‑agent simulations at scale.

How It Fits With Leviathan + Maneuver.Map

  • Gossamer: Implements agent decision logic (e.g., flocking, task allocation) and metrics.
  • Leviathan: High‑performance C++ simulator that executes actions from Gossamer and logs state.
  • Maneuver.Map: Orchestrates experiments, tunes parameters, stores data, and renders 3D visualizations.

Features

  • Coordination algorithms: flocking, task allocation, consensus, navigation, resilience.
  • Metrics: cohesion, alignment, separation, and helpers for evaluation.
  • Interfaces: adapter to run Gossamer logic against Leviathan (LeviathanInterface).
  • Examples: quick demos and integration scripts.

Install

pip install -r requirements.txt
pip install -e .

Quick Start

Standalone prototype:

from gossamer.simulator import SwarmSimulator
 
sim = SwarmSimulator(n_agents=30, dt=0.1)
sim.run(50, callback=lambda s,p,v,m: print(s, m))

Run against Leviathan (Python bindings):

cd examples
PYTHONPATH=../../leviathan-engine python run_with_leviathan.py --steps 200 \
  --config ../../leviathan-engine/examples/simple_flock/minimal.cfg

API Highlights

  • gossamer.algorithms.coordination.flocking.flock_step(positions, velocities, dt, ...) -> (new_pos, new_vel)
  • gossamer.utils.metrics.{cohesion, alignment, separation}
  • gossamer.interfaces.leviathan_interface.LeviathanInterface(env) implements a sim‑like loop over a Leviathan environment with reset/step/compute_metrics methods.

Use Cases

  • Research and teach swarm behaviors with reproducible metrics.
  • Rapidly iterate on agent algorithms before scaling to millions of agents in Leviathan.
  • Plug into Maneuver.Map’s evolutionary tuner to find optimal parameters across generations.

Algorithm Parameters

These are the common parameters you’ll pass when coupling Gossamer with Leviathan via Maneuver.Map (or when calling algorithms directly).

Flocking (baseline)

  • alignment_weight: Steer toward average neighbor velocity (coherence of headings).
  • cohesion_weight: Steer toward neighbor center of mass (grouping tendency).
  • separation_weight: Steer away from too‑close neighbors (collision avoidance).
  • neighbor_radius: Sensing radius for neighbors used in the above terms.
  • separation_distance: Distance threshold for repulsion.
  • max_speed: Speed cap (affects acceleration limits in coupled loop).

Density‑Modulated Boids (DMB)

  • w_align0, w_coh0, w_sep0: Baseline weights modulated by density.
  • alpha, beta: Slope parameters for logistic schedules of alignment/separation vs. density.
  • d0, d1: Density midpoints for the logistic schedules.
  • neighbor_radius, separation_distance, max_speed: As above; used for local estimates and limits.

Effect: weights are reduced/increased as density changes, stabilizing patterns at high density and reducing collisions.

Task‑Field Ant Colony Optimization (TF‑ACO)

  • grid_resolution: Cell size (world units) for the pheromone grid over X‑Y.
  • max_grid: Cap on grid dimension to bound memory (e.g., 2048).
  • pheromone_evap_lambda: Evaporation factor per step (0..1 range typical after mapping to 1−λ per step).
  • deposit_rate: Amount of pheromone deposited per step.
  • heuristic_weight: Relative weight of distance heuristic vs. pheromone when choosing target cells.

Effect: agents bias motion toward lower pheromone regions (coverage) while evaporation and deposits balance revisits.

ICCD / DTN Simplifications

  • iccd.initial_aoi: Initial age‑of‑information per agent (seconds).
  • iccd.relay_rotation: Enable simple relay rotation behavior across roles.
  • dtn.contact_density: Contacts per agent per hour (stochastic).
  • dtn.bandwidth_kbps: Link capacity for transfer accounting.
  • dtn.one_way_delay_sec: One‑way delay (propagation) used in AoI/contact updates.
  • dtn.custody_transfer: Simulate custody semantics in store‑and‑forward.

Effect: adds per‑agent attributes like AoI/SoC and simple communications effects for higher‑level behaviors.

Heterogeneous Macro‑Micro (HMA)

  • agents.micro.count: Number of micro agents (e.g., prospectors, scouts).
  • agents.macro.haulers: Hauler agents moving material from depots to printers.
  • agents.macro.printers: Printer agents (fixed/slow) consuming material.
  • depots.count: Supply nodes distributed around the environment.
  • hma.*: Additional task/role knobs as supported by scenarios.

Effect: introduces roles and simple logistics (depot pickup, printer delivery) with throughput and idle metrics.

Metrics Reference

  • cohesion(positions): Mean inverse distance to neighbors; higher is more clustered.
  • alignment(velocities): Magnitude of mean normalized velocity; 1.0 is perfect alignment.
  • separation(positions): Mean crowdedness (e.g., inverse distance below a threshold); lower implies fewer near collisions.

These metrics inform objective functions in Maneuver.Map’s evolutionary tuner (e.g., maximize cohesion + alignment − separation) and can be logged per sample interval for analysis.

Integration Tips

  • Use LeviathanInterface to wire flock_step (or custom policies) against the engine for rapid prototypes.
  • In Maneuver.Map, pass the above parameters in the “Algorithm params (JSON)” box; they are merged into the request and applied per step in the runner.
  • Start with moderate neighbor_radius and increase separation_weight if collision rate is high; use DMB at high densities to stabilize.
Last updated on
Leviathan EngineManeuver Map