How crismicheli/swarmy works
1. What this repo is
- Swarmy is a Python package for swarm-intelligence simulation, not an app server or web service.
- The runtime center is a headless simulation engine that can optionally be paired with visualization.
2. Primary architectural boundary
- The repo is split into three main layers:
- swarmy.core for simulation logic
- swarmy.config for parameter management
- swarmy.visualization for rendering
- The important constraint is that core simulation has no dependency on rendering, so it can run in batch mode, tests, notebooks, or optimization workflows.
3. Simulation engine
- swarmy/core/simulation.py is the orchestrator.
- SwarmSimulation owns the entity collections, advances the world one tick at a time, and exposes step() and get_state().
- It is the main integration point where agents, queens, and resources interact.
4. Agent subsystem
- swarmy/core/agent.py defines the worker/scout agents.
- Agents maintain position, heading, speed, objective, age, and a counter map used for navigation.
- The agent loop is: move, update counters, detect collisions, broadcast/receive messages, adjust direction, age out.
5. Communication and emergent pathing
- The system’s key algorithmic flow is local message passing between nearby agents.
- Agents broadcast “shouts” within a communication radius; receivers update counters only if the new value is better.
- This creates an emergent gradient field that guides agents toward resources and queens without centralized pathfinding.
6. Queen subsystem
- swarmy/core/queen.py models the base-like entity that receives resources and can create new agents or extend its own lifespan.
- Queens act as a resource sink and population control mechanism.
- The README also describes dynamic queen emergence when agents are sufficiently isolated, making queens part of the evolving swarm structure rather than a fixed control node.
7. Resource subsystem
- swarmy/core/resource.py defines collectible resource objects.
- Resources have position, type, capacity, and depletion state; they can move and be harvested.
- Resources are part of the environment state that agents discover and exploit over time.
8. Configuration boundary
- swarmy/config/config.py centralizes simulation parameters in SimulationConfig.
- This is where environment size, wrap/boundary behavior, agent counts, speeds, communication radius, resource counts, and queen thresholds are defined.
- The config layer is what makes the simulation reusable across examples, notebooks, and batch studies.
9. Visualization as an optional consumer
- swarmy/visualization is intentionally separate from the algorithmic core.
- renderer_base.py defines the rendering abstraction, while pygame_renderer.py and matplotlib_renderer.py are concrete backends.
- The data flow is one-way: simulation state is produced by core, then consumed by renderers; rendering does not feed back into the simulation.
10. Utilities and analysis support
- swarmy/utils contains support code such as spatial helpers, metrics, and I/O helpers.
- These are cross-cutting helpers rather than primary domain logic.
- swarmy/analysis exists as a placeholder for analytic extensions, which fits the repo’s research/experimentation orientation.
11. Examples and notebooks
- examples/ contains runnable scenarios such as basic simulation, batch runs, parameter sweeps, custom behavior, and multi-queen setups.
- notebooks/ provides exploratory demos for Matplotlib and Pygame.
- These entry points are the main consumer-facing surfaces for exercising different slices of the architecture.
12. Tests, docs, and packaging
- tests/unit covers core entities and simulation behavior; tests/integration verifies full-system behavior.
- docs/ is Sphinx-based and documents installation, quickstart, theory, and tutorials.
- Packaging is standard Python packaging via pyproject.toml, setup.py, and requirements.txt, with GitHub Actions workflows for tests and docs.
13. How to read the system diagrammatically
- Think of the repo as a stateful simulation core at the center, fed by config and interacting entities.
- Surround that with optional renderers and external scripts/notebooks that only observe state.
- The main data flow is: config → simulation initialization → per-step entity updates and communication → state snapshot → optional visualization/analysis.
Main entry points: simulation.py Simulation · agent.py Agents · test_simulation.py Unit tests · renderer_base.py Renderer API
Components 20
Core
Headless simulation engine and domain entities
- Simulation · Advances the swarm one tick at a time and exposes simulation state.
swarmy/core/simulation.py - Agents · Worker and scout agents with movement, counters, communication, and aging behavior.
swarmy/core/agent.py - Queens · Base-like entities that receive resources, create agents, and can extend lifespan.
swarmy/core/queen.py - Resources · Collectible environment objects that can be harvested and depleted.
swarmy/core/resource.py - Core utils · Shared core helpers used by simulation and entity logic.
swarmy/core/utils.py
Config
Simulation parameter boundary
- SimulationConfig · Central simulation parameters for world size, agents, communication, resources, and queens.
swarmy/config/config.py
Visualization
Optional rendering backends
- Renderer API · Abstract rendering boundary consumed by concrete visualization backends.
swarmy/visualization/renderer_base.py - Pygame renderer · Interactive visualization backend for simulated swarm state.
swarmy/visualization/pygame_renderer.py - Matplotlib renderer · Static or notebook-friendly visualization backend for simulation state.
swarmy/visualization/matplotlib_renderer.py
Usage
Examples, notebooks, and docs that exercise the library
- Examples · Runnable scenarios such as basic runs, batch mode, sweeps, custom behavior, and multi-queen setups.
examples/basic_simulation.py - Demo scripts · Example entry points for visualization and API usage.
examples/visualization_demo.py - Notebooks · Interactive demos for Matplotlib and Pygame workflows.
notebooks/Swarmy_Matplotlib_Demo.ipynb - Docs · Sphinx documentation for installation, quickstart, theory, tutorials, and API references.
docs/source/index.rst
Quality
Tests and package automation
- Unit tests · Focused tests for agents, queens, resources, and simulation behavior.
tests/unit/test_simulation.py - Integration tests · End-to-end verification of full simulation behavior.
tests/integration/test_full_simulation.py - Packaging · Python packaging and project metadata entry point.
pyproject.toml
Support
Cross-cutting utilities and analysis hooks
- Spatial utils · Reusable spatial calculations and geometry helpers.
swarmy/utils/spatial.py - Metrics · Analysis-oriented metrics for evaluating swarm behavior.
swarmy/utils/metrics.py - I/O utils · File and data input/output helpers used across workflows.
swarmy/utils/io.py - Analysis · Placeholder package for future analytic extensions.
swarmy/analysis/.gitkeep
Connections 28
- SimulationConfig → Simulation: configure · Simulation parameters initialize and tune the engine.
- Simulation → Agents: updates · Each step advances agent movement, messaging, and aging.
- Simulation → Queens: updates · Queens participate in resource intake and population control.
- Simulation → Resources: updates · Resources are tracked as part of world state and depletion.
- Agents → Resources: seeks · Agents discover and exploit nearby resources through local signals.
- Agents → Queens: reports · Agents can deliver resources or reinforce queen-related gradients.
- Agents → Agents: broadcasts · Nearby agents exchange shouts and update counters locally.
- Core utils → Agents: supports · Shared helpers support agent movement and spatial logic.
- Core utils → Simulation: supports · Common helpers assist orchestration and world calculations.
- Renderer API → Simulation: consumes state · Renderers observe snapshots produced by the simulation.
- Pygame renderer → Renderer API: implements · Pygame backend conforms to the rendering abstraction.
- Matplotlib renderer → Renderer API: implements · Matplotlib backend conforms to the rendering abstraction.
- Examples → Simulation: runs · Example scripts drive the core simulation in different modes.
- Demo scripts → Pygame renderer: uses · Visualization demos exercise the interactive backend.
- Demo scripts → Matplotlib renderer: uses · Visualization demos exercise the notebook-friendly backend.
- Notebooks → Simulation: explores · Notebooks interact with the engine for experimentation.
- Notebooks → Pygame renderer: explores · Notebook demos can render swarm state interactively.
- Docs → SimulationConfig: documents · Docs cover setup and configurable simulation parameters.
- Docs → Simulation: documents · Docs explain the core architecture and usage flow.
- Unit tests → Agents: verifies · Unit tests cover agent behavior and state transitions.
- Unit tests → Queens: verifies · Unit tests cover queen behavior.
- Unit tests → Resources: verifies · Unit tests cover resource lifecycle.
- Unit tests → Simulation: verifies · Unit tests cover orchestration and step behavior.
- Integration tests → Simulation: verifies · Integration tests validate full-system simulation behavior.
- Packaging → Simulation: packages · Project metadata packages the library for reuse.
- Spatial utils → Simulation: supports · Spatial helpers underpin world and entity calculations.
- Metrics → Analysis: feeds · Metrics provide a base for analysis workflows.
- I/O utils → Examples: supports · I/O helpers can be used by batch and export-oriented examples.