Skip to Content
ToolchainGossamer 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.

Install

pip install -r requirements.txt
pip install -e .
# Or from a pinned Artifact Registry wheel:
pip install --extra-index-url https://us-central1-python.pkg.dev/arboria-research/python-packages/simple/ \
    gossamer-threaded-intelligence==<version>

Minimal example

import numpy as np
from gossamer.algorithms.coordination.flocking import flock_step
from gossamer.utils.metrics import cohesion
 
rng = np.random.default_rng(0)
pos = rng.normal(scale=10, size=(200, 3))
vel = np.zeros_like(pos)
for _ in range(100):
    pos, vel = flock_step(pos, vel, dt=0.1, use_spatial=True)
print("cohesion:", cohesion(pos))

For GNN-style policies, use gossamer.graph.MessagePassingPolicy; for learned MARL, gossamer.learning.mappo; for the benchmark suite, gossamer.benchmarks.

Cite this tool

@software{arboria2026gossamer,
  title  = {Gossamer Threaded Intelligence: swarm coordination and metrics library},
  author = {{Arboria Labs}},
  year   = {2026},
  url    = {https://www.arborialabs.com/tools/gossamer_threaded_intelligence}
}

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 — Boids flocking, Laplacian consensus, Hungarian + ε-auction task allocation, potential fields, push/pull gossip, broadcast, and a complete voting suite (plurality, Borda, approval, Condorcet, Schulze).
  • Coordination policies for the swarm papers — gossamer.algorithms.coordination.{dmb, tfaco, iccd, hma} lifted out of the Maneuver.Map runner so policies are unit-testable independent of orchestration.
  • Graph substrate — gossamer.graph.InteractionGraph and MessagePassingPolicy ABC. Hand-crafted Boids and Laplacian consensus are also exposed as zero-parameter GNN layers (flocking_gnn, consensus_gnn), so a classical baseline and a learned MAPPO agent run under the same interface.
  • PyTorch MARL toolkit (gossamer.learning, optional dependency) — parameter-shared CTDE actor-critic (GraphActorCritic), learnable comm channel with bandwidth/latency/loss/energy accounting (CommChannel), reference MAPPO driver, domain-randomization wrapper.
  • Metrics suite — basic (cohesion, alignment, separation); information-theoretic (gossamer.metrics.info: transfer entropy, mutual information via histogram + KSG); criticality (gossamer.metrics.criticality: susceptibility, Binder cumulant, correlation length, branching ratio, avalanche statistics); spectral (gossamer.metrics.graph: algebraic connectivity, spectral gap).
  • Arboria Swarm Benchmark (gossamer.benchmarks) — canonical scenarios (dispersal, rendezvous, coverage, leader-follower, Byzantine) plus random / greedy / gossamer_flocking baselines; ships a Markdown leaderboard generator.
  • Reproducibility — every stochastic API takes an explicit rng: np.random.Generator | int | None. Module-level np.random.* and import random calls are gone; one seed produces byte-identical outputs.
  • Interfaces — adapter to run Gossamer logic against Leviathan (gossamer.interfaces.leviathan_interface.LeviathanInterface), and a small standalone gossamer.simulator.SwarmSimulator for quick prototypes that don’t need the C++ engine.

Quick Start

Standalone (no Leviathan):

import numpy as np
from gossamer.algorithms.coordination.flocking import flock_step
from gossamer.utils.metrics import cohesion
 
rng = np.random.default_rng(0)
pos = rng.normal(scale=10, size=(200, 3))
vel = np.zeros_like(pos)
for _ in range(100):
    pos, vel = flock_step(pos, vel, dt=0.1, use_spatial=True, rng=rng)
print("cohesion:", cohesion(pos))

Same step via the GNN interface:

from gossamer.graph import build_radius_graph
from gossamer.algorithms.coordination.flocking_gnn import FlockingGNN
 
policy = FlockingGNN(alignment_weight=1.0, cohesion_weight=1.0,
                     separation_weight=1.5, max_speed=5.0, dt=0.1)
graph = build_radius_graph(pos, radius=10.0, velocities=vel)
new_vel = policy.step(graph)

Run a benchmark sweep:

from gossamer.benchmarks import leaderboard, generate_leaderboard_md
results = leaderboard(num_seeds=3)  # default scenarios + baselines
print(generate_leaderboard_md(results))

Train a MAPPO baseline against Leviathan’s PettingZoo wrapper:

from leviathan_marl.env import LeviathanParallelEnv, LeviathanEnvConfig
from gossamer.learning.mappo import MAPPO
 
env = LeviathanParallelEnv(LeviathanEnvConfig(num_agents=128, dt=0.1))
trainer = MAPPO(env, hidden_dim=128, lr=3e-4)
trainer.fit(num_env_steps=1_000_000)

API Highlights

  • gossamer.algorithms.coordination.flocking.flock_step(positions, velocities, dt, *, rng=None, ...) -> (new_pos, new_vel)
  • gossamer.algorithms.coordination.{dmb, tfaco, iccd, hma} — the policies driving the swarm papers.
  • gossamer.graph.{InteractionGraph, MessagePassingPolicy, build_radius_graph} — the message-passing substrate shared by classical and learned policies.
  • gossamer.learning.{GraphActorCritic, CommChannel, mappo, domain_randomization} — PyTorch MARL toolkit (requires torch).
  • gossamer.metrics.info, gossamer.metrics.criticality, gossamer.metrics.graph — paper-grade analysis.
  • gossamer.benchmarks.{leaderboard, generate_leaderboard_md} — canonical scenario harness.
  • gossamer.utils.spatial — shared uniform-grid neighbor query (used both inside the library and by Maneuver.Map’s runner so there’s one implementation, not two).
  • gossamer.interfaces.leviathan_interface.LeviathanInterface(env) — adapter loop with reset / step / compute_metrics over a Leviathan environment.

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