Metadata-Version: 2.4
Name: ssl_simulator
Version: 1.0.0
Summary: Swarm Systems Lab Python Simulator
Author-email: Jesus Bautista Villar <jesbauti20@gmail.com>, Jose Hinojosa <josehinojosa@ugr.es>
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: numpy>=1.23
Requires-Dist: tqdm>=4.50
Provides-Extra: all
Requires-Dist: h5py>=3.0; extra == 'all'
Requires-Dist: lieplusplus-py>=0.3; extra == 'all'
Requires-Dist: pandas>=1.5; extra == 'all'
Requires-Dist: scipy>=1.5; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: cibuildwheel>=2.23.3; extra == 'dev'
Requires-Dist: h5py>=3.0; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: ipython>=8.0; extra == 'dev'
Requires-Dist: lieplusplus-py>=0.3; extra == 'dev'
Requires-Dist: matplotlib-inline<0.3,>=0.1.6; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: mkdocs-material>=9.0.0; extra == 'dev'
Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'dev'
Requires-Dist: pandas>=1.5; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pyqt5>=5.15.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: scipy>=1.5; extra == 'dev'
Requires-Dist: tox-uv>=1.9; extra == 'dev'
Requires-Dist: tox>=4.18; extra == 'dev'
Requires-Dist: twine>=5.1.1; extra == 'dev'
Requires-Dist: ty>=0.0.14; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: examples
Requires-Dist: ipykernel; extra == 'examples'
Requires-Dist: ipython>=8.0; extra == 'examples'
Requires-Dist: matplotlib-inline<0.3,>=0.1.6; extra == 'examples'
Requires-Dist: matplotlib>=3.7; extra == 'examples'
Requires-Dist: pyqt5>=5.15.0; extra == 'examples'
Provides-Extra: fields
Requires-Dist: scipy>=1.5; extra == 'fields'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.0; extra == 'hdf5'
Provides-Extra: lie
Requires-Dist: lieplusplus-py>=0.3; extra == 'lie'
Provides-Extra: lint
Requires-Dist: ruff>=0.9.0; extra == 'lint'
Provides-Extra: pprz
Requires-Dist: pandas>=1.5; extra == 'pprz'
Provides-Extra: pre-commit
Requires-Dist: pre-commit>=3.0; extra == 'pre-commit'
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == 'release'
Requires-Dist: cibuildwheel>=2.23.3; extra == 'release'
Requires-Dist: twine>=5.1.1; extra == 'release'
Provides-Extra: tests
Requires-Dist: h5py>=3.0; extra == 'tests'
Requires-Dist: lieplusplus-py>=0.3; extra == 'tests'
Requires-Dist: pandas>=1.5; extra == 'tests'
Requires-Dist: pytest-benchmark>=4.0; extra == 'tests'
Requires-Dist: pytest-cov>=4.0; extra == 'tests'
Requires-Dist: pytest-xdist>=3.5; extra == 'tests'
Requires-Dist: pytest>=7.0; extra == 'tests'
Requires-Dist: scipy>=1.5; extra == 'tests'
Provides-Extra: type-checking
Requires-Dist: ty>=0.0.14; extra == 'type-checking'
Description-Content-Type: text/markdown

# 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/](docs/) - start with
[architecture](docs/architecture.md) and [usage](docs/usage.md).

## Installation

Requires Python >= 3.12.

```bash
pip install ssl_simulator
```

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

| Extra | What it adds |
|---|---|
| `lie` | SO(3) state and Lie-group retraction (via `lieplusplus`) |
| `fields` | Scalar fields (`scipy`) |
| `hdf5` | HDF5 logging and I/O |
| `examples` | Dependencies for running `examples/` |

## Quick example

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

```python
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:

```bash
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`.

```bash
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:

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

## Examples

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

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

## Visualization

Visualization lives in the separate
[ssl_vista](https://github.com/Swarm-Systems-Lab/ssl_simulator_vista) package, which reads the
logged data directly.

## License

MIT
