# aamirsahil/rl-ant-python architecture

> Architecture diagram of the GitHub repository aamirsahil/rl-ant-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aamirsahil/rl-ant-python
- Repository: https://github.com/aamirsahil/rl-ant-python

## Overview

This repository implements an ant pheromone-trail reinforcement-learning simulation. The principal workflow is to configure an experiment, create a cellular world and ants, step the world while ants sense pheromones and act, and collect per-agent simulation data for serialization. The sampled code also shows pheromone-cell behavior and hooks for Q-learning and neural-network components; those imported modules are not present in the supplied tree. The README documents only the project’s broad purpose, so details beyond the excerpts are limited.

Main entry points: [`internal_external_multi.py`](https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py) (Simulation loop), [`cellular.py`](https://github.com/aamirsahil/rl-ant-python/blob/main/cellular.py) (Cellular world), [`main.py`](https://github.com/aamirsahil/rl-ant-python/blob/main/main.py) (Experiment runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Experiment orchestration"]
  node_runner["Experiment runner<br/>[main.py]"]
  node_results["Serialized results<br/>[main.py]"]
end

subgraph group_simulation["Ant simulation"]
  node_sim["Simulation loop"]
  node_world["Cellular world<br/>[cellular.py]"]
  node_cells["Pheromone cells"]
  node_ants["Ant agents"]
  node_data["Run data capture"]
end

subgraph group_learning["Learning components"]
  node_qlearn["Q-learning"]
  node_backprop["Neural network"]
end

node_runner -->|"runs"| node_sim
node_runner -->|"serializes"| node_results
node_sim -->|"constructs"| node_world
node_sim -->|"loads map"| node_world
node_sim -->|"steps"| node_world
node_world -->|"updates"| node_ants
node_ants -->|"inherits movement"| node_world
node_sim -->|"creates"| node_ants
node_sim -->|"records"| node_data
node_ants -->|"uses"| node_qlearn
node_ants -->|"uses"| node_backprop

click node_runner "https://github.com/aamirsahil/rl-ant-python/blob/main/main.py"
click node_results "https://github.com/aamirsahil/rl-ant-python/blob/main/main.py"
click node_sim "https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py"
click node_world "https://github.com/aamirsahil/rl-ant-python/blob/main/cellular.py"
click node_cells "https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py"
click node_ants "https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py"
click node_data "https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py"

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_runner,node_results toneBlue
class node_sim,node_world,node_cells,node_ants,node_data toneAmber
class node_qlearn,node_backprop toneMint
```

## Components

### Experiment orchestration

- [Experiment runner](https://github.com/aamirsahil/rl-ant-python/blob/main/main.py): `main.py`
- [Serialized results](https://github.com/aamirsahil/rl-ant-python/blob/main/main.py): `main.py`

### Ant simulation

- [Simulation loop](https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py): `internal_external_multi.py`
- [Cellular world](https://github.com/aamirsahil/rl-ant-python/blob/main/cellular.py): `cellular.py`
- [Pheromone cells](https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py): `internal_external_multi.py`
- [Ant agents](https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py): `internal_external_multi.py`
- [Run data capture](https://github.com/aamirsahil/rl-ant-python/blob/main/internal_external_multi.py): `internal_external_multi.py`

### Learning components

- **Q-learning**
- **Neural network**

## Connections

- Experiment runner → Simulation loop: runs (evidence: `main.py`)
- Experiment runner → Serialized results: serializes (evidence: `main.py`)
- Simulation loop → Cellular world: constructs (evidence: `internal_external_multi.py`)
- Simulation loop → Cellular world: loads map (evidence: `internal_external_multi.py`)
- Simulation loop → Cellular world: steps (evidence: `internal_external_multi.py`)
- Cellular world → Ant agents: updates (evidence: `cellular.py`)
- Ant agents → Cellular world: inherits movement (evidence: `internal_external_multi.py`)
- Simulation loop → Ant agents: creates (evidence: `internal_external_multi.py`)
- Simulation loop → Run data capture: records (evidence: `internal_external_multi.py`)
- Ant agents → Q-learning: uses (evidence: `internal_external_multi.py`)
- Ant agents → Neural network: uses (evidence: `internal_external_multi.py`)
