Metadata-Version: 2.4
Name: pyscout-sim
Version: 2.0.0
Summary: 3D drone-swarm simulation with MPC coordination, REST API and Qt GUI (SIDDA project, FH SWF)
Project-URL: Homepage, https://gitlab.com/sixflows-group/PyScout
Project-URL: Repository, https://gitlab.com/sixflows-group/PyScout
Project-URL: Issues, https://gitlab.com/sixflows-group/PyScout/-/issues
Project-URL: sixflows.dev, https://sixflows.dev/
Project-URL: SIDDA project (IN-ML-1-013b), http://sidda.de/
Project-URL: FH Südwestfalen, https://www.fh-swf.de/
Author-email: Linda Mümken <linda.klesper@gmx.de>
Maintainer-email: Linda Mümken <linda.klesper@gmx.de>
License-Expression: MIT
License-File: LICENSE
Keywords: dmpc,drone,mpc,multi-agent,simulation,swarm,uav
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.6
Requires-Dist: scipy>=1.13
Requires-Dist: uvicorn[standard]>=0.27
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: gui
Requires-Dist: pyside6>=6.6; extra == 'gui'
Description-Content-Type: text/markdown

# PyScout

PyScout is a modular 3D drone-swarm simulation with model-predictive control
(MPC), a REST API, a Qt GUI, and live 3D visualization. It supports centralized
MPC as well as distributed and threaded DMPC/ADMM coordinators.

This README covers installation and how to run, serve, and visualize scenarios.
For the control model, the codebase architecture, and the paper evaluation, see
the [documentation](#documentation).

## 1. Setup

Requirement: Python 3.11+.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

The GUI is optional and pulls in PySide6; install it with the `gui` extra when
you need it:

```bash
pip install -e ".[dev,gui]"
```

Scenarios are JSON files under `configs/`, grouped by type:

| Directory | Scenarios |
|-----------|-----------|
| `configs/1_drones/` | centralized MPC (fixed safety zones) |
| `configs/2_adapted_spheres/` | adaptive safety spheres |
| `configs/dmpc/` | distributed MPC (ADMM) |
| `configs/threaded/` | threaded distributed MPC |

Each file defines the room, physics model, the per-drone controller, the
coordinator, and the drones/obstacles. See
[docs/architecture.md](docs/architecture.md) for the configuration schema.

## 2. Running a scenario offline

Run a scenario directly through the `Simulator`, without the REST API or GUI:

```bash
python -m tools.run_config --config configs/1_drones/2DronesHorizon4.json --steps 200
```

This prints the final time, each drone's position/velocity, and any reported
collisions. It works the same way for distributed scenarios, e.g.
`configs/dmpc/4DronesDMPC.json`.

## 3. GUI

If you only want to view an existing scenario, run the GUI (requires the `gui`
extra):

```bash
python -m sim.gui
```

<p align="center">
  <img src="docs/figures/main_window.png" width="400" height="300" alt="Main window">
</p>

In the main window, click **load config** and choose a JSON configuration file.
Start the scenario with **start**; **pause** (or space) pauses, **reset** resets.
Zoom with the mouse wheel, and orbit the camera by holding the left mouse button
and moving the mouse.

## 4. REST API

Start the REST server from the repository root:

```bash
uvicorn sim.api.app:app --reload
```

The server listens on `http://127.0.0.1:8000`. Load a scenario, step the
simulation, and read back the state:

```bash
curl -s -X POST http://127.0.0.1:8000/config \
  -H "Content-Type: application/json" \
  --data-binary @configs/1_drones/2DronesHorizon4.json

curl -s -X POST "http://127.0.0.1:8000/step?n=10"
curl -s http://127.0.0.1:8000/state
```

## 5. Live view and GIF generation

Step the simulator and render it in-process. Optionally write an animated GIF:

```bash
python -m tools.live_view \
  --config configs/1_drones/2DronesHorizon4.json \
  --steps 200 \
  --trace-len 100 \
  --gif results/2DronesHorizon2.gif \
  --gif-fps 20
```

Example results:

<p align="center">
  <img src="docs/figures/4DronesHorizon1.gif" width="250" height="250" alt="4 Drones Horizon 1" style="margin-right: 10px;">
  <img src="docs/figures/4DronesHorizon2.gif" width="250" height="250" alt="4 Drones Horizon 2" style="margin-right: 10px;">
</p>

<p align="center">
  <img src="docs/figures/6DronesHorizon4.gif" width="250" height="250" alt="6 Drones Horizon 4" style="margin-right: 10px;">
  <img src="docs/figures/6DronesHorizon10.gif" width="250" height="250" alt="6 Drones Horizon 10" style="margin-right: 10px;">
</p>

Four-drone scenarios are easily solvable, but the horizon should be neither too
small nor too large. Six-drone scenarios are solvable too; a small horizon
results in many calculation steps, while a large horizon slows down each
calculation. See [docs/architecture.md](docs/architecture.md#horizon-selection-paper-observations)
for details.

## Documentation

- [docs/architecture.md](docs/architecture.md) — how the MPC framework maps onto
  the codebase, plus the scenario configuration schema.
- [docs/model.md](docs/model.md) — the MPC formulation: dynamics, cost function,
  and constraints.
- [docs/evaluation.md](docs/evaluation.md) — constraint verification and the MPC
  weight / adaptive safety-sphere tuning reference from the paper.

## Citation

If you use this code or build upon our work, please cite our paper:

### release v1.1.0
```bibtex
@article{drones10020139,
    title={Geometric and Control-Theoretic Limits on Drone Density in Bounded Airspace},
    author={Mümken, Linda and Altinses, Diyar and Lier, Stefan and Schwung, Andreas},
    journal={Drones},
    year = {2026},
    issn = {2504-446X},
    doi = {10.3390/drones10020139}
}
```

### release v2.2.1
```bibtex
@article{muemken2026,
    title={},
    author={Mümken, Linda and Schwung, Andreas},
    journal={IEEE Transactions on Automation Science and Engineering},
    year = {2026},
    issn = {},
    doi = {}
}
```

## Acknowledgements

PyScout was developed as part of the research project
[**SIDDA — Sustainable Intermodal Drone Delivery Airline**](http://sidda.de/)
(grant no. `IN-ML-1-013b`) at [**South Westphalia University of Applied
Sciences**](https://www.fh-swf.de/) (Fachhochschule Südwestfalen, FH SWF).

Written and maintained by [Linda Mümken](https://sixflows.dev/).

## License

MIT — see [LICENSE](LICENSE).
