# northseawatch/honors-abm architecture

> Architecture diagram of the GitHub repository northseawatch/honors-abm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/northseawatch/honors-abm
- Repository: https://github.com/northseawatch/honors-abm

## Overview

##### Project type and purpose
- This is a Python-based Agent-Based Model (ABM) built on the Mesa framework.
- Purpose: simulate ship movements, port interactions, and scrubber-water discharge policies in the North Sea.
- It is best classified as an open-source simulation tool / research prototype.

##### File structure
- Top-level:
- README.md, requirements.txt
- mesa/ directory containing core code, data, experiments, and output folders.
- mesa/data/: input datasets (CSV, Parquet).
- mesa/graphs/: generated visualization outputs.
- mesa/mesa_model.py: the main simulation engine and Mesa ModularServer setup.
- mesa/ship.py, port.py, filtered_ports_with_x_y.csv: agent definitions and positioning data.
- Experiment scripts (sweden_denmark_ban_exp.py, all_countries_ban_exp.py, nl_ban.py) configure different policy scenarios.
- plot_comparison.py: post-processing and chart generation.

##### README for additional insights
- Architecture overview is implicit:
- Agent types: Port, Ship, ScrubberTrail, Terrain.
- Core simulation loop in mesa_model.py with scheduling, grid, data collectors, and server/visualization.
- Data I/O: CSV input for ports, Parquet output for experiment results, PNGs in graphs/.
- Experiments orchestrate parameter sets and invoke the model.
- Visualization via Mesa’s CanvasGrid in a browser.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Experiments
    subgraph "Experiment Orchestrator" 
        direction TB
        Sweden["Sweden & Denmark Ban"]:::experiments
        AllCountries["All Countries Ban"]:::experiments
        NL["Netherlands Ban"]:::experiments
    end

    %% Simulation Core
    subgraph "Simulation Engine" 
        direction TB
        Engine["mesa_model.py"]:::core
    end

    %% Agents
    subgraph "Agent Classes" 
        direction TB
        Ship["Ship Agent"]:::agent
        Port["Port Agent"]:::agent
        Scrubber["ScrubberTrail Agent"]:::agent
        Terrain["Terrain Agent"]:::agent
    end

    %% Data I/O
    subgraph "Data I/O" 
        direction TB
        CSV1["Port Coordinates CSV"]:::data
        CSV2["Alternate Port List CSV"]:::data
        Parquet["Parquet Results"]:::data
        Graphs["PNG Graph Outputs"]:::data
    end

    %% Visualization & Analysis
    subgraph "Visualization & Analysis" 
        direction TB
        Plot["plot_comparison.py"]:::viz
        BrowserUI["CanvasGrid Browser UI"]:::viz
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        MesaLib["Mesa Framework"]:::external
        Pandas["pandas & Parquet I/O"]:::external
        Matplotlib["matplotlib/ChartModule"]:::external
    end

    %% Connections
    Sweden -->|"parameters"| Engine
    AllCountries -->|"parameters"| Engine
    NL -->|"parameters"| Engine

    CSV1 -->|"load ports"| Engine
    CSV2 -->|"load alt ports"| Engine

    Engine -->|"init agents"| Port
    Engine -->|"init agents"| Terrain
    Engine -->|"spawn agents"| Ship
    Engine -->|"spawn trail"| Scrubber

    Engine -->|"collect metrics"| Parquet
    Parquet -->|"read results"| Plot
    Plot -->|"generate charts"| Graphs

    Engine -->|"serve UI"| BrowserUI

    BrowserUI -->|"uses"| MesaLib
    Engine -->|"uses"| MesaLib
    Engine -->|"uses"| Pandas
    Plot -->|"uses"| Matplotlib

    %% Click events
    click Engine "https://github.com/northseawatch/honors-abm/blob/main/mesa/mesa_model.py"
    click Ship "https://github.com/northseawatch/honors-abm/blob/main/mesa/ship.py"
    click Port "https://github.com/northseawatch/honors-abm/blob/main/mesa/port.py"
    click CSV1 "https://github.com/northseawatch/honors-abm/blob/main/mesa/filtered_ports_with_x_y.csv"
    click CSV2 "https://github.com/northseawatch/honors-abm/blob/main/mesa/filtered_port.csv"
    click Parquet "https://github.com/northseawatch/honors-abm/blob/main/mesa/data/all_countries_ban_exp_data.parquet"
    click Graphs "https://github.com/northseawatch/honors-abm/tree/main/mesa/graphs/"
    click Sweden "https://github.com/northseawatch/honors-abm/blob/main/mesa/sweden_denmark_ban_exp.py"
    click AllCountries "https://github.com/northseawatch/honors-abm/blob/main/mesa/all_countries_ban_exp.py"
    click NL "https://github.com/northseawatch/honors-abm/blob/main/mesa/nl_ban.py"
    click Plot "https://github.com/northseawatch/honors-abm/blob/main/mesa/plot_comparison.py"

    %% Styles
    classDef experiments fill:#f9f871,stroke:#333,stroke-width:1px
    classDef core fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef agent fill:#a8e6cf,stroke:#333,stroke-width:1px
    classDef data fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef viz fill:#cda4de,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
