# dvidnguyen/mapf-benchmark-system architecture

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

- Interactive diagram: https://gitdiagram.com/dvidnguyen/mapf-benchmark-system
- Repository: https://github.com/dvidnguyen/mapf-benchmark-system

## Overview

This is an in-progress multi-agent pathfinding (MAPF) benchmark for comparing A*, tabular Q-learning, and DQN on grid maps. The main workflow configures a training run, steps agents through the collision-aware environment, updates learning agents, and logs episode metrics; evaluation runs trained or baseline agents and records benchmark results. Separate visual tools support algorithm comparison and step-by-step A* playback. The graph follows the sampled source and README; unsampled map/scenario loading and some view wiring are not expanded beyond documented or indexed relationships.

Main entry points: [`evaluate.py`](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/evaluate.py) (Evaluation CLI), [`main.py`](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/main.py) (Training CLI), [`envs/grid_env.py`](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/envs/grid_env.py) (Grid world), [`UI/compare_ui.py`](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/UI/compare_ui.py) (Algorithm comparison UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_trainer["Training CLI<br/>[main.py]"]
  node_evaluator["Evaluation CLI<br/>[evaluate.py]"]
  node_runner["Episode runner<br/>[simulation.py]"]
  node_metrics["Benchmark metrics<br/>[evaluate.py]"]
end

subgraph group_world["MAPF environment"]
  node_environment["Grid world<br/>[grid_env.py]"]
end

subgraph group_agents["Planning and learning"]
  node_base["Agent contract<br/>[base_agent.py]"]
  node_astar["A* planner<br/>[a_star.py]"]
  node_qlearning["Q-learning<br/>[q_learning.py]"]
  node_dqn["DQN agent<br/>[dqn.py]"]
end

subgraph group_interfaces["Views and comparison"]
  node_comparison["Algorithm comparison UI<br/>[compare_ui.py]"]
  node_canvas["Grid canvas viewer<br/>[canvas_viewer.py]"]
  node_astarview["A* visual runner"]
end

node_user(("Benchmark user"))

node_user -->|"starts training"| node_trainer
node_user -->|"runs evaluation"| node_evaluator
node_trainer -->|"configures world"| node_environment
node_trainer -->|"creates agents"| node_qlearning
node_trainer -->|"creates agents"| node_dqn
node_trainer -->|"runs episodes"| node_runner
node_runner -->|"resets and steps"| node_environment
node_runner -->|"calls agent methods"| node_base
node_evaluator -->|"configures world"| node_environment
node_evaluator -->|"creates planner"| node_astar
node_evaluator -->|"creates agent"| node_qlearning
node_evaluator -->|"creates agent"| node_dqn
node_evaluator -->|"runs test episodes"| node_runner
node_evaluator -->|"writes results"| node_metrics
node_comparison -->|"steps world"| node_environment
node_comparison -->|"compares planner"| node_astar
node_comparison -->|"compares agent"| node_qlearning
node_comparison -->|"compares agent"| node_dqn
node_astarview -->|"steps world"| node_environment
node_astarview -->|"uses planner"| node_astar

click node_trainer "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/main.py"
click node_evaluator "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/evaluate.py"
click node_runner "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/core/simulation.py"
click node_metrics "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/evaluate.py"
click node_environment "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/envs/grid_env.py"
click node_base "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/base_agent.py"
click node_astar "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/a_star.py"
click node_qlearning "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/q_learning.py"
click node_dqn "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/dqn.py"
click node_comparison "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/UI/compare_ui.py"
click node_canvas "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/gui/canvas_viewer.py"
click node_astarview "https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/run_astar_visual.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_trainer,node_evaluator,node_runner,node_metrics,node_user toneBlue
class node_environment toneAmber
class node_base,node_astar,node_qlearning,node_dqn toneMint
class node_comparison,node_canvas,node_astarview toneRose
```

## Components

### Run orchestration

- [Training CLI](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/main.py): `main.py`
- [Evaluation CLI](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/evaluate.py): `evaluate.py`
- [Episode runner](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/core/simulation.py): `core/simulation.py`
- [Benchmark metrics](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/evaluate.py): `evaluate.py`

### MAPF environment

- [Grid world](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/envs/grid_env.py): `envs/grid_env.py`

### Planning and learning

- [Agent contract](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/base_agent.py): `agents/base_agent.py`
- [A* planner](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/a_star.py): `agents/a_star.py`
- [Q-learning](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/q_learning.py): `agents/q_learning.py`
- [DQN agent](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/agents/dqn.py): `agents/dqn.py`

### Views and comparison

- [Algorithm comparison UI](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/UI/compare_ui.py): `UI/compare_ui.py`
- [Grid canvas viewer](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/gui/canvas_viewer.py): `gui/canvas_viewer.py`
- [A* visual runner](https://github.com/dvidnguyen/mapf-benchmark-system/blob/main/run_astar_visual.py): `run_astar_visual.py`

### Other components

- **Benchmark user**

## Connections

- Benchmark user → Training CLI: starts training (evidence: `README.md`)
- Benchmark user → Evaluation CLI: runs evaluation (evidence: `evaluate.py`)
- Training CLI → Grid world: configures world (evidence: `main.py`)
- Training CLI → Q-learning: creates agents (evidence: `main.py`)
- Training CLI → DQN agent: creates agents (evidence: `main.py`)
- Training CLI → Episode runner: runs episodes (evidence: `main.py`)
- Episode runner → Grid world: resets and steps (evidence: `core/simulation.py`)
- Episode runner → Agent contract: calls agent methods (evidence: `core/simulation.py`)
- Evaluation CLI → Grid world: configures world (evidence: `evaluate.py`)
- Evaluation CLI → A* planner: creates planner (evidence: `evaluate.py`)
- Evaluation CLI → Q-learning: creates agent (evidence: `evaluate.py`)
- Evaluation CLI → DQN agent: creates agent (evidence: `evaluate.py`)
- Evaluation CLI → Episode runner: runs test episodes (evidence: `evaluate.py`)
- Evaluation CLI → Benchmark metrics: writes results (evidence: `evaluate.py`)
- Algorithm comparison UI → Grid world: steps world (evidence: `UI/compare_ui.py`)
- Algorithm comparison UI → A* planner: compares planner (evidence: `UI/compare_ui.py`)
- Algorithm comparison UI → Q-learning: compares agent (evidence: `UI/compare_ui.py`)
- Algorithm comparison UI → DQN agent: compares agent (evidence: `UI/compare_ui.py`)
- A* visual runner → Grid world: steps world (evidence: `run_astar_visual.py`)
- A* visual runner → A* planner: uses planner (evidence: `run_astar_visual.py`)
