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.

Full documentation is in docs/ - start with architecture and usage.

Installation

Requires Python >= 3.12.

pip install ssl_simulator

Optional extras - pip install ssl_simulator[all] gets everything:

Quick example

A swarm of single integrators driven to the origin. A controller is just a system that writes a command component:

import numpy as np
from ssl_simulator import Engine, System, World, load_sim
from ssl_simulator.robot_models import single_integrator


class GoToOrigin(System):
    reads, writes = ("p",), ("u",)

    def __init__(self, gain):
        self.gain = gain

    def run(self, world, dt):
        world["u"][:] = -self.gain * world["p"]   # vectorized over all N agents


world = World(n=5)
integrator = single_integrator(world, state="p", cmd="u",
                               init=np.random.default_rng(0).random((5, 2)))
world.add_system(GoToOrigin(gain=1.0))
world.add_system(integrator)

Engine(time_step=0.01, log_filename="run.csv", log_time_step=0.1).run(world, duration=5.0)

data, settings = load_sim("run.csv")   # logged names are flat: data["p"] -> (T, 5, 2)

Quick Setup (Examples & Development)

Make sure uv and just are installed:

curl -LsSf https://astral.sh/uv/install.sh | sh
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

Both installers add themselves to ~/.local/bin, make sure that's on your PATH.

git clone https://github.com/Swarm-Systems-Lab/ssl_simulator
cd ssl_simulator

# One-command setup (installs ssl-pydev, creates .venv, installs dependencies)
just setup

# Optional: Install all extras for development
just sync

Common tasks - run just --list for the rest:

just test         # run the test suite
just lint         # ruff format + check
just docs         # serve the docs at http://localhost:8000

Examples

See the examples/ directory - it's a guided tour of the ECS core, meant to be read in order.

just example
# Or directly:
uv run python examples/basic_usage.py

Visualization

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

License

MIT