tap-flows

Traffic Assignment Problem (TAP) tooling for:

• user equilibrium and social optimum flows on directed graphs,
• multicommodity flow optimization,
• social cost gradient analysis,
• figure generation for synthetic and OSM-based city networks.

Repository Layout

• src/: core library modules (optimization, graph generation, plotting, OSM processing).
• test/: automated tests.
• analysis/: canonical scripts used to generate publication figures.
• manuscript/: LaTeX manuscript sources and revision artifacts.
• notes/: non-code reference material (PDF notes and external documents).
• messy_code/: ad-hoc scratchpad/trash folder for informal experiments and one-off scripts.
• data/: cached graph inputs and experiment artifacts.
• figs/: generated outputs (PDF/PNG/GeoJSON).

Quick Start

1. Create and activate an environment (Python 3.9+).
2. Install dependencies:

python3 -m pip install -r requirements.txt

3. Run tests:

python3 -m pytest -q

Common Usage

Single-commodity TAP:

import numpy as np
from src import TAPOptimization as tap

G = tap.random_graph(num_nodes=20, num_edges=40, seed=42, alpha="random", beta="random")
P = np.zeros(G.number_of_nodes())
P[0] = 500
P[1:] = -500 / (G.number_of_nodes() - 1)

f_ue = tap.user_equilibrium(G, P)
f_so = tap.social_optimum(G, P)

Multicommodity TAP:

import numpy as np
from src import multiCommodityTAP as mc

G = mc.random_graph(num_nodes=15, num_edges=30, seed=42, alpha="random", beta="random")
od = -np.ones((G.number_of_nodes(), G.number_of_nodes()))
np.fill_diagonal(od, 0)
np.fill_diagonal(od, -np.sum(od, axis=0))
demands = [od[:, i] for i in range(G.number_of_nodes())]

flow = mc.solve_multicommodity_tap(G, demands)

Generate figures:

python3 analysis/fig_classic_braess_social_cost.py
python3 analysis/fig_classic_braess_scgc_validation.py
python3 analysis/fig_user_equilibrium_vs_social_optimum.py
python3 analysis/fig_multicommodity_decomposition.py
python3 analysis/fig_synthetic_gamma_scan.py
python3 analysis/fig_cologne_stadium_traffic.py --demand-multipliers 0.8,1.0,1.2
python3 analysis/fig_potsdam_braess_osm.py --demand-multipliers 0.9,1.0,1.1
python3 analysis/fig_lambda_inequality_diagram.py
python3 analysis/fig_intervention_validation.py --medium

Build manuscript:

cd manuscript
latexmk -pdf main.tex

Notes

• Some figure and OSM workflows need additional geospatial dependencies and external data.
• OSM workflows may require online geocoding/download if local boundary/graph caches are missing.

License

Source code in this repository is licensed under the MIT License. See LICENSE.

Non-code assets are excluded from that license unless explicitly stated otherwise, including:

• data/
• figs/
• notes/
• manuscript/
• literature/
• cache/