Skip to content

ssl_simulator

Swarm Systems Lab Python simulator - a data-oriented (ECS) simulation core for multi-agent robotics research.

All mutable simulation data lives in a World as struct-of-arrays component arrays. Behaviour is System callables that mutate those arrays in place, vectorized over the N agents. A scheduler orders systems by their declared reads/writes, and a thin Engine ticks them and logs.

Install

pip install ssl_simulator          # or: uv pip install ssl_simulator

Optional extras: lie (SO(3) state via lieplusplus), fields (scalar fields, scipy), hdf5, examples, all.

A first simulation

Eight agents running a consensus law on a single-integrator state:

import numpy as np
from ssl_simulator import World, System, IntegrationSystem, Engine

class Consensus(System):
    reads, writes = ("p",), ("u",)
    def __init__(self, laplacian, gain):
        self.L, self.gain = laplacian, gain
    def run(self, world, dt):
        world["u"][:] = -self.gain * (self.L @ world["p"])

world = World(n=8)
world.add_state("p", dim=2, init=np.random.default_rng(0).normal(size=(8, 2)))
world.add("u", dim=2)
world.add_system(Consensus(L, 1.0))
world.add_system(IntegrationSystem([("p", "u")]))   # ṗ = u

Engine(time_step=0.05, log_filename="run.csv").run(world, duration=5.0)

Read the run back with load_sim - logged names are flat (p, u, time):

from ssl_simulator import load_sim
data, settings = load_sim("run.csv")

Where to go next

  • Architecture - the World/Manifold/System/scheduler/Engine model, the Lie-group retraction primitive, the C++/Paparazzi seam, and why in-place numpy over JAX.
  • Usage - building worlds, writing systems, integration, observability, and I/O.
  • API Reference - generated from docstrings.

Visualization lives in the separate ssl_vista package, which consumes the logged data directly.

Support