# crismicheli/swarmy architecture

> Architecture diagram of the GitHub repository crismicheli/swarmy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crismicheli/swarmy
- Repository: https://github.com/crismicheli/swarmy

## Overview

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: [`swarmy/core/simulation.py`](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/simulation.py) (Simulation), [`swarmy/core/agent.py`](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/agent.py) (Agents), [`tests/unit/test_simulation.py`](https://github.com/crismicheli/swarmy/blob/main/tests/unit/test_simulation.py) (Unit tests), [`swarmy/visualization/renderer_base.py`](https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/renderer_base.py) (Renderer API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core"]
  node_node_simulation["Simulation<br/>orchestrator<br/>[simulation.py]"]
  node_node_agent["Agents<br/>entity model<br/>[agent.py]"]
  node_node_queen["Queens<br/>entity model<br/>[queen.py]"]
  node_node_resource["Resources<br/>entity model<br/>[resource.py]"]
  node_node_core_utils["Core utils<br/>helpers<br/>[utils.py]"]
end

subgraph group_group_config["Config"]
  node_node_config["SimulationConfig<br/>parameter config<br/>[config.py]"]
end

subgraph group_group_viz["Visualization"]
  node_node_renderer_base["Renderer API<br/>render interface<br/>[renderer_base.py]"]
  node_node_pygame["Pygame renderer<br/>render backend<br/>[pygame_renderer.py]"]
  node_node_matplotlib["Matplotlib renderer<br/>render backend"]
end

subgraph group_group_usage["Usage"]
  node_node_examples_basic["Examples<br/>usage scripts"]
  node_node_examples_viz["Demo scripts<br/>usage scripts"]
  node_node_notebooks["Notebooks<br/>exploration"]
  node_node_docs["Docs<br/>documentation<br/>[index.rst]"]
end

subgraph group_group_quality["Quality"]
  node_node_tests_unit["Unit tests<br/>test suite<br/>[test_simulation.py]"]
  node_node_tests_integration["Integration tests<br/>test suite"]
  node_node_pyproject["Packaging<br/>build config<br/>[pyproject.toml]"]
end

subgraph group_group_support["Support"]
  node_node_utils_spatial["Spatial utils<br/>helper module<br/>[spatial.py]"]
  node_node_utils_metrics["Metrics<br/>helper module<br/>[metrics.py]"]
  node_node_utils_io["I/O utils<br/>helper module<br/>[io.py]"]
  node_node_analysis(("Analysis<br/>extension point<br/>[.gitkeep]"))
end

node_node_config -->|"configure"| node_node_simulation
node_node_simulation -->|"updates"| node_node_agent
node_node_simulation -->|"updates"| node_node_queen
node_node_simulation -->|"updates"| node_node_resource
node_node_agent -->|"seeks"| node_node_resource
node_node_agent -->|"reports"| node_node_queen
node_node_agent -->|"broadcasts"| node_node_agent
node_node_core_utils -.->|"supports"| node_node_agent
node_node_core_utils -.->|"supports"| node_node_simulation
node_node_renderer_base -->|"consumes state"| node_node_simulation
node_node_pygame -->|"implements"| node_node_renderer_base
node_node_matplotlib -->|"implements"| node_node_renderer_base
node_node_examples_basic -->|"runs"| node_node_simulation
node_node_examples_viz -->|"uses"| node_node_pygame
node_node_examples_viz -->|"uses"| node_node_matplotlib
node_node_notebooks -->|"explores"| node_node_simulation
node_node_notebooks -->|"explores"| node_node_pygame
node_node_docs -.->|"documents"| node_node_config
node_node_docs -.->|"documents"| node_node_simulation
node_node_tests_unit -.->|"verifies"| node_node_agent
node_node_tests_unit -.->|"verifies"| node_node_queen
node_node_tests_unit -.->|"verifies"| node_node_resource
node_node_tests_unit -.->|"verifies"| node_node_simulation
node_node_tests_integration -.->|"verifies"| node_node_simulation
node_node_pyproject -.->|"packages"| node_node_simulation
node_node_utils_spatial -.->|"supports"| node_node_simulation
node_node_utils_metrics -.->|"feeds"| node_node_analysis
node_node_utils_io -.->|"supports"| node_node_examples_basic

click node_node_simulation "https://github.com/crismicheli/swarmy/blob/main/swarmy/core/simulation.py"
click node_node_agent "https://github.com/crismicheli/swarmy/blob/main/swarmy/core/agent.py"
click node_node_queen "https://github.com/crismicheli/swarmy/blob/main/swarmy/core/queen.py"
click node_node_resource "https://github.com/crismicheli/swarmy/blob/main/swarmy/core/resource.py"
click node_node_core_utils "https://github.com/crismicheli/swarmy/blob/main/swarmy/core/utils.py"
click node_node_config "https://github.com/crismicheli/swarmy/blob/main/swarmy/config/config.py"
click node_node_renderer_base "https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/renderer_base.py"
click node_node_pygame "https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/pygame_renderer.py"
click node_node_matplotlib "https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/matplotlib_renderer.py"
click node_node_examples_basic "https://github.com/crismicheli/swarmy/blob/main/examples/basic_simulation.py"
click node_node_examples_viz "https://github.com/crismicheli/swarmy/blob/main/examples/visualization_demo.py"
click node_node_notebooks "https://github.com/crismicheli/swarmy/blob/main/notebooks/Swarmy_Matplotlib_Demo.ipynb"
click node_node_docs "https://github.com/crismicheli/swarmy/blob/main/docs/source/index.rst"
click node_node_tests_unit "https://github.com/crismicheli/swarmy/blob/main/tests/unit/test_simulation.py"
click node_node_tests_integration "https://github.com/crismicheli/swarmy/blob/main/tests/integration/test_full_simulation.py"
click node_node_pyproject "https://github.com/crismicheli/swarmy/blob/main/pyproject.toml"
click node_node_utils_spatial "https://github.com/crismicheli/swarmy/blob/main/swarmy/utils/spatial.py"
click node_node_utils_metrics "https://github.com/crismicheli/swarmy/blob/main/swarmy/utils/metrics.py"
click node_node_utils_io "https://github.com/crismicheli/swarmy/blob/main/swarmy/utils/io.py"
click node_node_analysis "https://github.com/crismicheli/swarmy/blob/main/swarmy/analysis/.gitkeep"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_simulation,node_node_agent,node_node_queen,node_node_resource,node_node_core_utils toneBlue
class node_node_config toneAmber
class node_node_renderer_base,node_node_pygame,node_node_matplotlib toneMint
class node_node_examples_basic,node_node_examples_viz,node_node_notebooks,node_node_docs toneRose
class node_node_tests_unit,node_node_tests_integration,node_node_pyproject toneIndigo
class node_node_utils_spatial,node_node_utils_metrics,node_node_utils_io,node_node_analysis toneTeal
```

## Components

### Core

Headless simulation engine and domain entities

- [Simulation](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/simulation.py): orchestrator · Advances the swarm one tick at a time and exposes simulation state. · `swarmy/core/simulation.py`
- [Agents](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/agent.py): entity model · Worker and scout agents with movement, counters, communication, and aging behavior. · `swarmy/core/agent.py`
- [Queens](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/queen.py): entity model · Base-like entities that receive resources, create agents, and can extend lifespan. · `swarmy/core/queen.py`
- [Resources](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/resource.py): entity model · Collectible environment objects that can be harvested and depleted. · `swarmy/core/resource.py`
- [Core utils](https://github.com/crismicheli/swarmy/blob/main/swarmy/core/utils.py): helpers · Shared core helpers used by simulation and entity logic. · `swarmy/core/utils.py`

### Config

Simulation parameter boundary

- [SimulationConfig](https://github.com/crismicheli/swarmy/blob/main/swarmy/config/config.py): parameter config · Central simulation parameters for world size, agents, communication, resources, and queens. · `swarmy/config/config.py`

### Visualization

Optional rendering backends

- [Renderer API](https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/renderer_base.py): render interface · Abstract rendering boundary consumed by concrete visualization backends. · `swarmy/visualization/renderer_base.py`
- [Pygame renderer](https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/pygame_renderer.py): render backend · Interactive visualization backend for simulated swarm state. · `swarmy/visualization/pygame_renderer.py`
- [Matplotlib renderer](https://github.com/crismicheli/swarmy/blob/main/swarmy/visualization/matplotlib_renderer.py): render backend · Static or notebook-friendly visualization backend for simulation state. · `swarmy/visualization/matplotlib_renderer.py`

### Usage

Examples, notebooks, and docs that exercise the library

- [Examples](https://github.com/crismicheli/swarmy/blob/main/examples/basic_simulation.py): usage scripts · Runnable scenarios such as basic runs, batch mode, sweeps, custom behavior, and multi-queen setups. · `examples/basic_simulation.py`
- [Demo scripts](https://github.com/crismicheli/swarmy/blob/main/examples/visualization_demo.py): usage scripts · Example entry points for visualization and API usage. · `examples/visualization_demo.py`
- [Notebooks](https://github.com/crismicheli/swarmy/blob/main/notebooks/Swarmy_Matplotlib_Demo.ipynb): exploration · Interactive demos for Matplotlib and Pygame workflows. · `notebooks/Swarmy_Matplotlib_Demo.ipynb`
- [Docs](https://github.com/crismicheli/swarmy/blob/main/docs/source/index.rst): documentation · Sphinx documentation for installation, quickstart, theory, tutorials, and API references. · `docs/source/index.rst`

### Quality

Tests and package automation

- [Unit tests](https://github.com/crismicheli/swarmy/blob/main/tests/unit/test_simulation.py): test suite · Focused tests for agents, queens, resources, and simulation behavior. · `tests/unit/test_simulation.py`
- [Integration tests](https://github.com/crismicheli/swarmy/blob/main/tests/integration/test_full_simulation.py): test suite · End-to-end verification of full simulation behavior. · `tests/integration/test_full_simulation.py`
- [Packaging](https://github.com/crismicheli/swarmy/blob/main/pyproject.toml): build config · Python packaging and project metadata entry point. · `pyproject.toml`

### Support

Cross-cutting utilities and analysis hooks

- [Spatial utils](https://github.com/crismicheli/swarmy/blob/main/swarmy/utils/spatial.py): helper module · Reusable spatial calculations and geometry helpers. · `swarmy/utils/spatial.py`
- [Metrics](https://github.com/crismicheli/swarmy/blob/main/swarmy/utils/metrics.py): helper module · Analysis-oriented metrics for evaluating swarm behavior. · `swarmy/utils/metrics.py`
- [I/O utils](https://github.com/crismicheli/swarmy/blob/main/swarmy/utils/io.py): helper module · File and data input/output helpers used across workflows. · `swarmy/utils/io.py`
- [Analysis](https://github.com/crismicheli/swarmy/blob/main/swarmy/analysis/.gitkeep): extension point · Placeholder package for future analytic extensions. · `swarmy/analysis/.gitkeep`

## Connections

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