# skakim/braessparadox architecture

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

- Interactive diagram: https://gitdiagram.com/skakim/braessparadox
- Repository: https://github.com/skakim/braessparadox

## Overview

##### Project type and purpose
- This is a scientific/experimental Python project (“BraessParadox”) for running simulations and experiments on the Braess Paradox in traffic networks.
- It ingests network definitions and agent-based cost/choice files, runs path-finding and cost-evaluation algorithms, and outputs results for analysis.

##### File structure
Top-level directories and key files:
- network-files-master/
– Contains raw network definitions (.net) under subfolders (Bar-Gera TNTP, Braess-graphs, etc.).
– tools/: scripts to convert or validate network files (convert_bargera.py, validator.py, python_example.py).
- kspmaster/
– A small library for K-Shortest Paths (KSP.py, __init__.py), with an example caller (ksp_calling_example.py).
- py_expression_eval/
– A utility package for parsing/evaluating cost expressions.
- Agent.py
– Core agent logic for computing routes/costs.
- main.py
– Orchestrator script that ties together network loading, agent logic, KSP calls, and output generation.
- greedy_agents/
– Preset experiment results and inputs for a greedy-agent variant.
- Various text files at root (choices0.txt, cost0.txt, edges_usage8.txt, g_costs.txt)
– Example inputs or baseline outputs.

##### README
- Confirms the project is “Experiments on Braess Paradox.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    ND["Network Data Store"]:::datastore
    RI["Raw Experiment Inputs"]:::datastore

    %% Utilities / Preprocessing
    Conv["Network Conversion & Validation Tools"]:::util
    KSPExample["KSP Example Caller"]:::util

    %% Core Processing
    subgraph "Processing"
        Main["Orchestrator: main.py"]:::core
        Agent["Agent Logic: Agent.py"]:::core
        KSPEngine["KSP Engine Library"]:::core
        ExprEval["Expression Evaluator"]:::core
    end

    %% Outputs
    Out["Output Data Store"]:::datastore
    GV["Experiment Variants: greedy_agents"]:::datastore

    %% Data Flow
    ND -->|".net files"| Conv
    Conv -->|"validated graphs"| Main
    RI -->|"choices,costs"| Main

    %% Control Flow
    Main -->|"invoke KSP"| KSPEngine
    Main -->|"run agent logic"| Agent
    Main -->|"evaluate cost expressions"| ExprEval

    %% Output Flow
    Main -->|"write results"| Out
    Main -->|"write variant outputs"| GV

    %% Side Utilities
    KSPEngine -.-> KSPExample

    %% Click Events
    click ND "https://github.com/skakim/braessparadox/tree/master/network-files-master/"
    click Conv "https://github.com/skakim/braessparadox/tree/master/network-files-master/tools/"
    click KSPEngine "https://github.com/skakim/braessparadox/tree/master/kspmaster/"
    click KSPExample "https://github.com/skakim/braessparadox/blob/master/kspmaster/ksp_calling_example.py"
    click ExprEval "https://github.com/skakim/braessparadox/tree/master/py_expression_eval/"
    click Agent "https://github.com/skakim/braessparadox/blob/master/Agent.py"
    click Main "https://github.com/skakim/braessparadox/blob/master/main.py"
    click GV "https://github.com/skakim/braessparadox/tree/master/greedy_agents/"
    click Out "https://github.com/skakim/braessparadox/blob/master/choices0.txt"

    %% Styles
    classDef datastore fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef util fill:#FFD580,stroke:#333,stroke-width:1px;
```
