gmnsopt

A GMNS-native transportation optimization testbed — reproducible, visual, data-grounded, and progressively harder. It turns standardized GMNS networks + demand + operations data into mathematical-programming and network-optimization cases:

GMNS network + demand + operations data
  → optimization model template
  → solver / algorithm
  → (dynamic simulation check)
  → GUI4GMNS visualization
  → reproducible benchmark report

gmnsopt turns GMNS from a network data standard into a transportation optimization testbed for planning, operations, control, pricing, resilience, and multimodal decision-making — where open-source solvers, commercial solvers, ML-for-optimization, and RL/control methods can all be tested on realistic, dynamic, stochastic, visually explainable mobility problems.

What ships in v0.1 (working, dependency-light)

Core kernel + ten runnable cases across the model families and formulation classes (LP / MILP / convex-NLP / inverse), on the common case contract (problem.yml + GMNS input/ → output/solution.csv, objective_trace.csv, constraint_status.csv, summary.md):

Verified invariants: system-optimal total travel time < user-equilibrium; ODME count-RMSE 2720 → 185; MILP network design respects the budget; p-median opens exactly K hubs. Only numpy, scipy, networkx, PyYAML are required (MILP/LP use scipy's HiGHS backend — no commercial solver needed). Optional extras add Pyomo/HiGHS bindings, pandas/matplotlib.

Install

pip install -e .            # core
pip install -e ".[viz,solvers,dev]"   # + pandas/matplotlib, Pyomo/HiGHS, pytest/ruff

Quick start

gmns-opt run      cases/02_sioux_falls_assignment      # -> output/ (solution, trace, summary)
gmns-opt validate cases/02_sioux_falls_assignment
gmns-opt list-families                                 # the 10-family taxonomy (maturity + classes)
gmns-opt describe-family signal_queue_control
gmns-opt solver-status                                 # available solver tiers
gmns-opt generate-scenarios --case cases/11_resilience_capacity_drop_toy --type capacity_drop --links 1,2,3 --drop 0.5

Broader benchmark scaffold

Beyond the runnable models, the package is an open-science ecosystem scaffold:

• Application taxonomy — 10 families (gmns_opt.applications / benchmark.registry), each with formulation classes, required/optional GMNS files, outputs, solver tier, visualization, and maturity (runnable / scaffold / planned). See docs/application_taxonomy.md.
• Tensor framework — gmns_opt.tensor: sparse x[o,d,m,p,τ,s,a] + companion tensors (D/F/Q/U/C/R/V), GMNS→demand-tensor conversion, scenario expansion, CSV/JSON export. See docs/tensor_framework.md.
• Scenario generator — gmns_opt.scenarios: deterministic normal / capacity_drop / demand_surge / work_zone / weather / cav_penetration / uam_weather_restriction (fixed seeds).
• Solver tiers — gmns_opt.solvers: Tier 0 (networkx/scipy-HiGHS) → 1 (Pyomo) → 2 (commercial, optional) → 3 (GPU/neural/RL). No commercial dependency. See docs/solver_tiers.md.
• ML-for-optimization readiness — gmns_opt.ml: GMNS feature extraction (GNN-ready), learning-to-warm-start interface, learning-to-branch dataset schema. See docs/ml_for_optimization.md.
• GUI4GMNS visualization — gmns_opt.visualization.export_optimization_layers → GeoJSON + decision/constraint/ trace/scenario CSVs. See docs/gui4gmns_integration.md.
• Case templates — case_templates/ (one per family) and 13 runnable/scaffold seed cases (cases/00..12).

from gmns_opt import run_case
res = run_case("cases/02_sioux_falls_assignment")
print(res["objective"], res["meta"]["final_relative_gap"])   # UE Beckmann + FW gap

The benchmark ladder (design)

Not one benchmark — a ladder from transparent teaching cases to industrial-scale city cases:

Model families (implemented → planned)

A. shortest path / accessibility ✅ · B. traffic assignment & system-optimal ✅ (UE) · C. ODME / inverse optimization · D. signal timing & arterial control (MILP/MPC) · E. network design & capacity planning · F. resilience / work-zone / incident / extreme-heat · G. freight / EV charging / UAM / multimodal logistics · H. transit frequency & accessibility. See docs/BENCHMARK_SPEC.md.

Solver tiers

Tier 0 NetworkX / scipy / HiGHS / OR-Tools · Tier 1 Pyomo + HiGHS/CBC/Ipopt · Tier 2 Gurobi / CPLEX / COPT / Mosek · Tier 3 GPU / cuOpt / ADMM / RL / neural heuristics. Start license-free; scale up when needed.

Docs

vision · application taxonomy · tensor framework · benchmark ladder · solver tiers · ML for optimization · GUI4GMNS integration · open-science test cases · benchmark spec · data contract · roadmap · references

License

MIT — see LICENSE. Bundled benchmark networks keep their own upstream licenses (see references); Sioux Falls is from the public Transportation Networks repo.