# mesa/mesa-examples architecture

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

- Interactive diagram: https://gitdiagram.com/mesa/mesa-examples
- Repository: https://github.com/mesa/mesa-examples

## Overview

This repository packages Mesa user examples rather than one application. Its GIS examples let a user configure and run spatial simulations, then inspect map and metric visualizations; its reinforcement-learning examples demonstrate policy-driven agent simulations. The graph preserves the distinct GIS model families and the RL examples visible in the tree. Source sampling is limited to selected app and server files, so uncertain internal model-to-space and training wiring is omitted.

Main entry points: [`rl/epstein_civil_violence/server.py`](https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/server.py) (Civil violence server), [`gis/geo_schelling/app.py`](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling/app.py) (GeoSchelling app), [`gis/geo_schelling_points/app.py`](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/app.py) (Points app), [`gis/geo_sir/app.py`](https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/app.py) (GeoSIR app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vector["Vector GIS"]
  node_geo_model["Polygon Schelling<br/>[model.py]"]
  node_points_model["Points Schelling<br/>[model.py]"]
  node_points_agents["People and regions<br/>[agents.py]"]
  node_sir_model["GeoSIR simulation<br/>[model.py]"]
  node_sir_agents["SIR agents<br/>[agents.py]"]
  node_network_model["Agents and networks<br/>[model.py]"]
  node_commuters["Commuter agents<br/>[commuter.py]"]
  node_campus["Campus space<br/>[campus.py]"]
  node_road_network["Road network<br/>[road_network.py]"]
  node_population_model["Population simulation<br/>[model.py]"]
end

subgraph group_raster["Raster GIS"]
  node_rain_model["Rainfall simulation<br/>[model.py]"]
  node_rain_space["Lake cells<br/>[space.py]"]
  node_urban_model["Urban growth simulation<br/>[model.py]"]
  node_urban_space["Urban cells<br/>[space.py]"]
end

subgraph group_rl["RL Examples"]
  node_boltzmann_model["Boltzmann model<br/>[model.py]"]
  node_civil_model["Civil violence model<br/>[model.py]"]
  node_civil_agents["Citizen and cop agents<br/>[agent.py]"]
  node_civil_observations["Observation utilities<br/>[utility.py]"]
  node_wolf_model["Wolf-sheep RL model<br/>[model.py]"]
  node_wolf_agents["Wolf-sheep agents<br/>[agents.py]"]
end

subgraph group_interfaces["Run Interfaces"]
  node_geo_app["GeoSchelling app<br/>[app.py]"]
  node_points_app["Points app<br/>[app.py]"]
  node_sir_app["GeoSIR app<br/>[app.py]"]
  node_network_app["Campus app<br/>[app.py]"]
  node_population_app["Population app<br/>[app.py]"]
  node_rain_app["Rainfall app<br/>[app.py]"]
  node_urban_app["Urban growth app<br/>[app.py]"]
  node_boltzmann_server["Wealth interface<br/>[server.py]"]
  node_civil_server["Civil violence server<br/>[server.py]"]
  node_wolf_app["Wolf-sheep app<br/>[app.py]"]
end

node_user(("Example user"))
node_rl_user(("RL example user"))

node_user -->|"runs"| node_geo_app
node_geo_app -->|"creates"| node_geo_model
node_user -->|"runs"| node_points_app
node_points_app -->|"creates"| node_points_model
node_user -->|"runs"| node_sir_app
node_sir_app -->|"creates"| node_sir_model
node_user -->|"runs"| node_network_app
node_network_app -->|"creates"| node_network_model
node_user -->|"runs"| node_population_app
node_population_app -->|"creates"| node_population_model
node_user -->|"runs"| node_rain_app
node_rain_app -->|"creates"| node_rain_model
node_user -->|"runs"| node_urban_app
node_urban_app -->|"creates"| node_urban_model
node_rl_user -->|"runs"| node_boltzmann_server
node_boltzmann_server -->|"extends"| node_boltzmann_model
node_rl_user -->|"runs"| node_civil_server
node_civil_server -->|"extends"| node_civil_model
node_civil_server -->|"builds observations"| node_civil_observations
node_rl_user -->|"runs"| node_wolf_app
node_wolf_app -->|"imports"| node_wolf_model

click node_geo_app "https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling/app.py"
click node_geo_model "https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling/model.py"
click node_points_app "https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/app.py"
click node_points_model "https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/geo_schelling_points/model.py"
click node_points_agents "https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/geo_schelling_points/agents.py"
click node_sir_app "https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/app.py"
click node_sir_model "https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/geo_sir/model.py"
click node_sir_agents "https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/geo_sir/agents.py"
click node_network_app "https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/app.py"
click node_network_model "https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/model/model.py"
click node_commuters "https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/agent/commuter.py"
click node_campus "https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/space/campus.py"
click node_road_network "https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/space/road_network.py"
click node_population_app "https://github.com/mesa/mesa-examples/blob/main/gis/population/app.py"
click node_population_model "https://github.com/mesa/mesa-examples/blob/main/gis/population/population/model.py"
click node_rain_app "https://github.com/mesa/mesa-examples/blob/main/gis/rainfall/app.py"
click node_rain_model "https://github.com/mesa/mesa-examples/blob/main/gis/rainfall/rainfall/model.py"
click node_rain_space "https://github.com/mesa/mesa-examples/blob/main/gis/rainfall/rainfall/space.py"
click node_urban_app "https://github.com/mesa/mesa-examples/blob/main/gis/urban_growth/app.py"
click node_urban_model "https://github.com/mesa/mesa-examples/blob/main/gis/urban_growth/urban_growth/model.py"
click node_urban_space "https://github.com/mesa/mesa-examples/blob/main/gis/urban_growth/urban_growth/space.py"
click node_boltzmann_server "https://github.com/mesa/mesa-examples/blob/main/rl/boltzmann_money/server.py"
click node_boltzmann_model "https://github.com/mesa/mesa-examples/blob/main/rl/boltzmann_money/model.py"
click node_civil_server "https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/server.py"
click node_civil_model "https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/model.py"
click node_civil_agents "https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/agent.py"
click node_civil_observations "https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/utility.py"
click node_wolf_app "https://github.com/mesa/mesa-examples/blob/main/rl/wolf_sheep/app.py"
click node_wolf_model "https://github.com/mesa/mesa-examples/blob/main/rl/wolf_sheep/model.py"
click node_wolf_agents "https://github.com/mesa/mesa-examples/blob/main/rl/wolf_sheep/agents.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_geo_model,node_points_model,node_points_agents,node_sir_model,node_sir_agents,node_network_model,node_commuters,node_campus,node_road_network,node_population_model,node_user,node_rl_user toneBlue
class node_rain_model,node_rain_space,node_urban_model,node_urban_space toneAmber
class node_boltzmann_model,node_civil_model,node_civil_agents,node_civil_observations,node_wolf_model,node_wolf_agents toneMint
class node_geo_app,node_points_app,node_sir_app,node_network_app,node_population_app,node_rain_app,node_urban_app,node_boltzmann_server,node_civil_server,node_wolf_app toneRose
```

## Components

### Vector GIS

- [Polygon Schelling](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling/model.py): `gis/geo_schelling/model.py`
- [Points Schelling](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/geo_schelling_points/model.py): `gis/geo_schelling_points/geo_schelling_points/model.py`
- [People and regions](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/geo_schelling_points/agents.py): `gis/geo_schelling_points/geo_schelling_points/agents.py`
- [GeoSIR simulation](https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/geo_sir/model.py): `gis/geo_sir/geo_sir/model.py`
- [SIR agents](https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/geo_sir/agents.py): `gis/geo_sir/geo_sir/agents.py`
- [Agents and networks](https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/model/model.py): `gis/agents_and_networks/src/model/model.py`
- [Commuter agents](https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/agent/commuter.py): `gis/agents_and_networks/src/agent/commuter.py`
- [Campus space](https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/space/campus.py): `gis/agents_and_networks/src/space/campus.py`
- [Road network](https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/src/space/road_network.py): `gis/agents_and_networks/src/space/road_network.py`
- [Population simulation](https://github.com/mesa/mesa-examples/blob/main/gis/population/population/model.py): `gis/population/population/model.py`

### Raster GIS

- [Rainfall simulation](https://github.com/mesa/mesa-examples/blob/main/gis/rainfall/rainfall/model.py): `gis/rainfall/rainfall/model.py`
- [Lake cells](https://github.com/mesa/mesa-examples/blob/main/gis/rainfall/rainfall/space.py): `gis/rainfall/rainfall/space.py`
- [Urban growth simulation](https://github.com/mesa/mesa-examples/blob/main/gis/urban_growth/urban_growth/model.py): `gis/urban_growth/urban_growth/model.py`
- [Urban cells](https://github.com/mesa/mesa-examples/blob/main/gis/urban_growth/urban_growth/space.py): `gis/urban_growth/urban_growth/space.py`

### RL Examples

- [Boltzmann model](https://github.com/mesa/mesa-examples/blob/main/rl/boltzmann_money/model.py): `rl/boltzmann_money/model.py`
- [Civil violence model](https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/model.py): `rl/epstein_civil_violence/model.py`
- [Citizen and cop agents](https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/agent.py): `rl/epstein_civil_violence/agent.py`
- [Observation utilities](https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/utility.py): `rl/epstein_civil_violence/utility.py`
- [Wolf-sheep RL model](https://github.com/mesa/mesa-examples/blob/main/rl/wolf_sheep/model.py): `rl/wolf_sheep/model.py`
- [Wolf-sheep agents](https://github.com/mesa/mesa-examples/blob/main/rl/wolf_sheep/agents.py): `rl/wolf_sheep/agents.py`

### Run Interfaces

- [GeoSchelling app](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling/app.py): `gis/geo_schelling/app.py`
- [Points app](https://github.com/mesa/mesa-examples/blob/main/gis/geo_schelling_points/app.py): `gis/geo_schelling_points/app.py`
- [GeoSIR app](https://github.com/mesa/mesa-examples/blob/main/gis/geo_sir/app.py): `gis/geo_sir/app.py`
- [Campus app](https://github.com/mesa/mesa-examples/blob/main/gis/agents_and_networks/app.py): `gis/agents_and_networks/app.py`
- [Population app](https://github.com/mesa/mesa-examples/blob/main/gis/population/app.py): `gis/population/app.py`
- [Rainfall app](https://github.com/mesa/mesa-examples/blob/main/gis/rainfall/app.py): `gis/rainfall/app.py`
- [Urban growth app](https://github.com/mesa/mesa-examples/blob/main/gis/urban_growth/app.py): `gis/urban_growth/app.py`
- [Wealth interface](https://github.com/mesa/mesa-examples/blob/main/rl/boltzmann_money/server.py): `rl/boltzmann_money/server.py`
- [Civil violence server](https://github.com/mesa/mesa-examples/blob/main/rl/epstein_civil_violence/server.py): `rl/epstein_civil_violence/server.py`
- [Wolf-sheep app](https://github.com/mesa/mesa-examples/blob/main/rl/wolf_sheep/app.py): `rl/wolf_sheep/app.py`

### Other components

- **Example user**
- **RL example user**

## Connections

- Example user → GeoSchelling app: runs
- GeoSchelling app → Polygon Schelling: creates
- Example user → Points app: runs
- Points app → Points Schelling: creates
- Example user → GeoSIR app: runs
- GeoSIR app → GeoSIR simulation: creates
- Example user → Campus app: runs
- Campus app → Agents and networks: creates
- Example user → Population app: runs
- Population app → Population simulation: creates
- Example user → Rainfall app: runs
- Rainfall app → Rainfall simulation: creates
- Example user → Urban growth app: runs
- Urban growth app → Urban growth simulation: creates
- RL example user → Wealth interface: runs
- Wealth interface → Boltzmann model: extends
- RL example user → Civil violence server: runs
- Civil violence server → Civil violence model: extends
- Civil violence server → Observation utilities: builds observations
- RL example user → Wolf-sheep app: runs
- Wolf-sheep app → Wolf-sheep RL model: imports