How yaraberkelmans/upgraded-fortnight works
1. Repository purpose
- This is an agent-based simulation project built on Mesa. The main domain is football-fan crowd dynamics: segregation on a grid, fight decisions, and police intervention. The repository also contains two smaller standalone models for segregation and civil/riot-like behavior.
2. Primary architecture: riot_model/
- riot_model/riot_model.py is the orchestration layer. It defines the core RiotModel plus the parameter objects SegregationParams and RiotParams.
- riot_model/fan.py holds the fan agent logic and related enums/strategy definitions.
- riot_model/police.py holds the police agent logic.
- This package is the canonical implementation used by both the UI and headless runs.
3. Core simulation boundaries
- The model maintains the grid, agent population, phase control, and metrics collection.
- Fan and police behavior is encapsulated inside agent classes; the model coordinates their interaction, placement, and replacement after arrests.
- The simulation is split into a warmup segregation phase and a main riot phase, controlled by the model rather than by external scripts.
4. Behavioral flow inside the riot model
- Fans first evaluate local neighborhood similarity and may move if unhappy.
- Once the main phase starts, fans also compute perceived win/arrest probabilities and decide whether to fight.
- Police patrol, move toward fighting fans, and arrest them.
- Arrested fans are replaced to keep population size stable, so the model preserves density while allowing group counts to drift.
5. Metrics and observability
- RiotModel uses a Mesa DataCollector to record step-level outputs such as happiness, segregation index, spatial entropy, moves, fighting fans, arrests, police count, and perception averages.
- These metrics are the primary data product of the model and are what the plotting/visualization layers consume.
6. Interactive runtime: server_riot_model.py
- This is the browser-facing entry point, intended to be run with Solara.
- It instantiates the model, exposes parameter sliders, and renders live charts and the grid.
- Architecturally, it is a thin presentation layer over the core model; it should not contain simulation logic.
7. Headless/batch runtime
- riot_model/run_aggression_and_plot.py is the non-UI execution path for running experiments and plotting results.
- The README’s example shows the intended usage pattern: create a RiotModel, call run_model(), then read model.datacollector.
- This makes the model reusable for automation, calibration, and analysis without the UI.
8. Standalone segregation model: SIMPLE_SEG/
- SIMPLE_SEG/segregation.py and SIMPLE_SEG/run_segregation.py form a simpler Schelling-style segregation-only simulation.
- This package is separate from the riot model and likely exists as a pedagogical or baseline subsystem.
- It is structurally parallel to the larger model: agent logic plus a run script.
9. Standalone civil model: SIMPLE_CIVIL/
- SIMPLE_CIVIL/civil.py and SIMPLE_CIVIL/run_civil.py provide another simplified simulation variant.
- Like SIMPLE_SEG, it appears to be a self-contained experiment rather than part of the main riot model pipeline.
10. Top-level legacy/shared modules
- fan.py, cop.py, and mixed_models.py at the repo root look like earlier or shared implementations outside the packaged riot_model/ namespace.
- For architecture diagrams, treat these as auxiliary/legacy code paths unless the application entry points import them directly.
11. Data and dependency flow
- External input is mostly configuration: model parameters, random seed, and UI slider values.
- The simulation produces stepwise metrics and visualization state; there is no indication of a database, message bus, or network service backend.
- The main runtime dependency is Mesa, with Solara used only for the interactive dashboard.
12. Suggested diagram focus
- Show three layers: entry points (server_riot_model.py, run_* scripts), model core (riot_model/), and supporting simulations (SIMPLE_SEG, SIMPLE_CIVIL, legacy root modules).
- Emphasize the one-way flow from UI/script → model parameters → step loop → datacollector/visualization outputs.
Main entry points: riot_model.py Riot model · server_riot_model.py Riot server · run_aggression_and_plot.py Batch run · mixed_models.py Mixed models
Components 17
Entry points
UI and batch scripts that start simulations and experiments.
- Riot server · Browser-facing dashboard and parameter controls for the main model.
server_riot_model.py - Seg server · Entry point for the standalone segregation simulation UI.
server_seg.py - Civil server · Entry point for the standalone civil simulation UI.
server_civ.py
Riot model
Canonical Mesa-based crowd simulation used by both UI and headless runs.
- Batch run · Headless execution path for running the riot model and plotting results.
riot_model/run_aggression_and_plot.py - Riot model · Orchestrates the main crowd simulation, phases, movement, fights, arrests, and metrics.
riot_model/riot_model.py - Fan agent · Fan behavior, neighborhood evaluation, movement, and fight decisions.
riot_model/fan.py - Police agent · Police movement, patrol, pursuit, and arrest behavior.
riot_model/police.py - Seg params · Parameters for the warmup segregation phase and related tuning.
riot_model/riot_model.py - Riot params · Parameters controlling the main riot phase, policing, and perceptions.
riot_model/riot_model.py - Metrics · Step-level outputs such as happiness, segregation, entropy, moves, arrests, and perceptions.
riot_model/riot_model.py
Supporting sims
Smaller standalone models and legacy shared modules.
- Segregation model · Standalone segregation-only simulation core.
SIMPLE_SEG/segregation.py - Seg run · Execution script for the standalone segregation model.
SIMPLE_SEG/run_segregation.py - Civil model · Standalone simplified civil or riot-like simulation core.
SIMPLE_CIVIL/civil.py - Civil run · Execution script for the standalone civil simulation.
SIMPLE_CIVIL/run_civil.py - Legacy fan · Top-level fan implementation outside the packaged riot model namespace.
fan.py - Legacy cop · Top-level police/cop implementation outside the packaged riot model namespace.
cop.py - Mixed models · Older or auxiliary model combinations and experiments.
mixed_models.py
Connections 19
- Riot server → Riot model: instantiates · Interactive runtime constructs and drives the canonical model.
- Batch run → Riot model: runs · Batch script executes the same model headlessly.
- Riot model → Seg params: uses · Model configuration for the segregation warmup phase.
- Riot model → Riot params: uses · Model configuration for the riot phase and policing behavior.
- Riot model → Fan agent: coordinates · Model creates, places, updates, and replaces fan agents.
- Riot model → Police agent: coordinates · Model manages police agents and their interaction with fans.
- Riot model → Metrics: records · Simulation state is summarized into step-level metrics.
- Fan agent → Riot model: acts in · Fan decisions are evaluated within the model grid and phase loop.
- Police agent → Riot model: acts in · Police behavior is executed under model control.
- Riot server → Metrics: visualizes · UI reads collected metrics for charts and live displays.
- Batch run → Metrics: plots · Headless workflow consumes collected outputs for analysis.
- Seg server → Segregation model: instantiates · Standalone segregation UI wraps its model core.
- Seg run → Segregation model: runs · Batch path for the segregation-only simulation.
- Civil server → Civil model: instantiates · Standalone civil UI wraps its model core.
- Civil run → Civil model: runs · Batch path for the civil simulation.
- Mixed models → Legacy fan: references · Legacy model compositions reuse the older fan implementation.
- Mixed models → Legacy cop: references · Legacy model compositions reuse the older cop implementation.
- Riot model → Legacy fan: parallel code · Top-level legacy modules appear to be auxiliary rather than canonical.
- Riot model → Legacy cop: parallel code · Top-level legacy modules appear to be auxiliary rather than canonical.