gmnsopt 0.2.0__tar.gz

gmnsopt-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gmnsopt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gmnsopt-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: gmnsopt
+Version: 0.2.0
+Summary: GMNS-native transportation optimization testbed: reproducible, visual, data-grounded, progressively harder benchmark cases (shortest path -> assignment -> ODME -> signal -> resilience) for open-source & commercial solvers, ML-for-optimization, and RL/control.
+Author: gmnsopt contributors
+License: MIT
+Project-URL: Source, https://github.com/asu-trans-ai-lab/gmnsopt
+Keywords: GMNS,transportation,optimization,traffic-assignment,ODME,benchmark,operations-research,networkx,HiGHS
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Requires-Dist: networkx>=2.6
+Requires-Dist: PyYAML>=5.4
+Provides-Extra: viz
+Requires-Dist: pandas>=1.3; extra == "viz"
+Requires-Dist: matplotlib>=3.4; extra == "viz"
+Provides-Extra: solvers
+Requires-Dist: pyomo>=6.0; extra == "solvers"
+Requires-Dist: highspy>=1.5; extra == "solvers"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# gmnsopt
+
+[![CI](https://github.com/asu-trans-ai-lab/gmnsopt/actions/workflows/ci.yml/badge.svg)](https://github.com/asu-trans-ai-lab/gmnsopt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gmnsopt.svg)](https://pypi.org/project/gmnsopt/)
+[![Python](https://img.shields.io/pypi/pyversions/gmnsopt.svg)](https://pypi.org/project/gmnsopt/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**A GMNS-native transportation optimization testbed** — reproducible, visual, data-grounded, and
+progressively harder. It turns standardized [GMNS](https://github.com/zephyr-data-specs/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`):
+
+| model | family | class | case | solver |
+|---|---|---|---|---|
+| `shortest_path` | A routing | LP | `cases/00_shortest_path_toy` | networkx Dijkstra |
+| `min_cost_flow` | flow | LP | `cases/01_min_cost_flow_toy` | networkx |
+| `traffic_assignment` (UE) | B assignment | convex-NLP | `cases/02_sioux_falls_assignment` | Frank-Wolfe + BPR |
+| `system_optimal` (+ pricing) | B assignment | convex-NLP | `cases/03_system_optimal_pricing` | Frank-Wolfe (marginal cost) |
+| `accessibility` | A routing | LP | `cases/04_accessibility` | networkx skims |
+| `max_flow` (min-cut) | F resilience | LP | `cases/05_max_flow_evacuation` | networkx max-flow |
+| `odme` (inverse) | C ODME | QP/NNLS | `cases/06_odme_sioux_falls` | scipy NNLS |
+| `signal_timing` | D operations | LP | `cases/07_signal_timing_intersection` | scipy linprog (HiGHS) |
+| `network_design` | E design | **MILP** | `cases/08_network_design_toy` | **scipy milp (HiGHS)** |
+| `facility_location` (EV charging) | G siting | **MILP** | `cases/09_facility_location_charging` | **scipy milp (HiGHS)** |
+
+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
+```bash
+pip install -e .            # core
+pip install -e ".[viz,solvers,dev]"   # + pandas/matplotlib, Pyomo/HiGHS, pytest/ruff
+```
+
+## Quick start
+```bash
+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](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](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](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](docs/ml_for_optimization.md).
+- **GUI4GMNS visualization** — `gmns_opt.visualization.export_optimization_layers` → GeoJSON + decision/constraint/
+  trace/scenario CSVs. See [docs/gui4gmns_integration.md](docs/gui4gmns_integration.md).
+- **Case templates** — `case_templates/` (one per family) and 13 runnable/scaffold seed cases (`cases/00..12`).
+```python
+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:
+
+| level | what | purpose |
+|---|---|---|
+| 0 | formulation micro-cases (5–20 nodes, 1 signal) | teach variables/constraints; debug solvers; validate LLM-generated models |
+| 1 | classic research nets **as GMNS** (Sioux Falls, Anaheim, Chicago) | connect to the literature; algorithm comparison |
+| 2 | open-city OSM2GMNS (Tempe, Phoenix, Atlanta, LA, Bay Area) | geographically meaningful; GIS/planning + GUI4GMNS outreach |
+| 3 | dynamic corridor operations (signals, queues, work zones, incidents) | planning → operations (DTA/CBI/ODME) |
+| 4 | stochastic / robust (demand, capacity, incident, weather, CAV/UAM uncertainty) | research-grade OR/AI |
+| 5 | industrial-scale city (10⁴–10⁶ vars, multi-mode/period/scenario) | stress solvers + neural acceleration |
+
+## 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](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](docs/vision.md) · [application taxonomy](docs/application_taxonomy.md) ·
+[tensor framework](docs/tensor_framework.md) · [benchmark ladder](docs/benchmark_ladder.md) ·
+[solver tiers](docs/solver_tiers.md) · [ML for optimization](docs/ml_for_optimization.md) ·
+[GUI4GMNS integration](docs/gui4gmns_integration.md) · [open-science test cases](docs/open_science_test_cases.md) ·
+[benchmark spec](docs/BENCHMARK_SPEC.md) · [data contract](docs/data_contract.md) ·
+[roadmap](../dev/ROADMAP.md) · [references](../references/README.md)
+
+## License
+MIT — see [LICENSE](LICENSE). Bundled benchmark networks keep their own upstream licenses
+(see [references](../references/README.md)); Sioux Falls is from the public Transportation Networks repo.

gmnsopt-0.2.0/README.md

@@ -0,0 +1,119 @@
+# gmnsopt
+
+[![CI](https://github.com/asu-trans-ai-lab/gmnsopt/actions/workflows/ci.yml/badge.svg)](https://github.com/asu-trans-ai-lab/gmnsopt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gmnsopt.svg)](https://pypi.org/project/gmnsopt/)
+[![Python](https://img.shields.io/pypi/pyversions/gmnsopt.svg)](https://pypi.org/project/gmnsopt/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**A GMNS-native transportation optimization testbed** — reproducible, visual, data-grounded, and
+progressively harder. It turns standardized [GMNS](https://github.com/zephyr-data-specs/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`):
+
+| model | family | class | case | solver |
+|---|---|---|---|---|
+| `shortest_path` | A routing | LP | `cases/00_shortest_path_toy` | networkx Dijkstra |
+| `min_cost_flow` | flow | LP | `cases/01_min_cost_flow_toy` | networkx |
+| `traffic_assignment` (UE) | B assignment | convex-NLP | `cases/02_sioux_falls_assignment` | Frank-Wolfe + BPR |
+| `system_optimal` (+ pricing) | B assignment | convex-NLP | `cases/03_system_optimal_pricing` | Frank-Wolfe (marginal cost) |
+| `accessibility` | A routing | LP | `cases/04_accessibility` | networkx skims |
+| `max_flow` (min-cut) | F resilience | LP | `cases/05_max_flow_evacuation` | networkx max-flow |
+| `odme` (inverse) | C ODME | QP/NNLS | `cases/06_odme_sioux_falls` | scipy NNLS |
+| `signal_timing` | D operations | LP | `cases/07_signal_timing_intersection` | scipy linprog (HiGHS) |
+| `network_design` | E design | **MILP** | `cases/08_network_design_toy` | **scipy milp (HiGHS)** |
+| `facility_location` (EV charging) | G siting | **MILP** | `cases/09_facility_location_charging` | **scipy milp (HiGHS)** |
+
+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
+```bash
+pip install -e .            # core
+pip install -e ".[viz,solvers,dev]"   # + pandas/matplotlib, Pyomo/HiGHS, pytest/ruff
+```
+
+## Quick start
+```bash
+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](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](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](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](docs/ml_for_optimization.md).
+- **GUI4GMNS visualization** — `gmns_opt.visualization.export_optimization_layers` → GeoJSON + decision/constraint/
+  trace/scenario CSVs. See [docs/gui4gmns_integration.md](docs/gui4gmns_integration.md).
+- **Case templates** — `case_templates/` (one per family) and 13 runnable/scaffold seed cases (`cases/00..12`).
+```python
+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:
+
+| level | what | purpose |
+|---|---|---|
+| 0 | formulation micro-cases (5–20 nodes, 1 signal) | teach variables/constraints; debug solvers; validate LLM-generated models |
+| 1 | classic research nets **as GMNS** (Sioux Falls, Anaheim, Chicago) | connect to the literature; algorithm comparison |
+| 2 | open-city OSM2GMNS (Tempe, Phoenix, Atlanta, LA, Bay Area) | geographically meaningful; GIS/planning + GUI4GMNS outreach |
+| 3 | dynamic corridor operations (signals, queues, work zones, incidents) | planning → operations (DTA/CBI/ODME) |
+| 4 | stochastic / robust (demand, capacity, incident, weather, CAV/UAM uncertainty) | research-grade OR/AI |
+| 5 | industrial-scale city (10⁴–10⁶ vars, multi-mode/period/scenario) | stress solvers + neural acceleration |
+
+## 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](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](docs/vision.md) · [application taxonomy](docs/application_taxonomy.md) ·
+[tensor framework](docs/tensor_framework.md) · [benchmark ladder](docs/benchmark_ladder.md) ·
+[solver tiers](docs/solver_tiers.md) · [ML for optimization](docs/ml_for_optimization.md) ·
+[GUI4GMNS integration](docs/gui4gmns_integration.md) · [open-science test cases](docs/open_science_test_cases.md) ·
+[benchmark spec](docs/BENCHMARK_SPEC.md) · [data contract](docs/data_contract.md) ·
+[roadmap](../dev/ROADMAP.md) · [references](../references/README.md)
+
+## License
+MIT — see [LICENSE](LICENSE). Bundled benchmark networks keep their own upstream licenses
+(see [references](../references/README.md)); Sioux Falls is from the public Transportation Networks repo.

gmnsopt-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gmnsopt"
+version = "0.2.0"
+description = "GMNS-native transportation optimization testbed: reproducible, visual, data-grounded, progressively harder benchmark cases (shortest path -> assignment -> ODME -> signal -> resilience) for open-source & commercial solvers, ML-for-optimization, and RL/control."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "gmnsopt contributors" }]
+keywords = ["GMNS", "transportation", "optimization", "traffic-assignment", "ODME",
+            "benchmark", "operations-research", "networkx", "HiGHS"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering",
+    "Intended Audience :: Science/Research",
+]
+dependencies = ["numpy>=1.21", "scipy>=1.7", "networkx>=2.6", "PyYAML>=5.4"]
+
+[project.optional-dependencies]
+viz = ["pandas>=1.3", "matplotlib>=3.4"]
+solvers = ["pyomo>=6.0", "highspy>=1.5"]        # optional Tier-1 modeling + HiGHS bindings
+dev = ["pytest>=7.0", "ruff>=0.1"]
+
+[project.scripts]
+gmns-opt = "gmns_opt.cli:main"
+
+[project.urls]
+Source = "https://github.com/asu-trans-ai-lab/gmnsopt"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gmns_opt*"]

gmnsopt-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gmnsopt-0.2.0/src/gmns_opt/__init__.py

@@ -0,0 +1,17 @@
+"""gmnsopt — a GMNS-native transportation optimization testbed.
+
+Turns standardized GMNS networks + demand + operations data into reproducible optimization cases:
+    GMNS network + demand -> optimization model -> solver -> (simulation check) -> report.
+
+Public API:
+    read_gmns, build_graph, validate_gmns        (io)
+    shortest_path, min_cost_flow, traffic_assignment   (models)
+    run_case                                     (benchmark case runner)
+"""
+from .io import read_gmns, build_graph, validate_gmns
+from .models import shortest_path, min_cost_flow, traffic_assignment
+from .benchmark import run_case
+
+__version__ = "0.2.0"
+__all__ = ["read_gmns", "build_graph", "validate_gmns",
+           "shortest_path", "min_cost_flow", "traffic_assignment", "run_case"]

gmnsopt-0.2.0/src/gmns_opt/applications/__init__.py

@@ -0,0 +1,27 @@
+"""Application taxonomy — the ten transportation optimization families.
+
+Thin, registry-backed surface: the authoritative metadata lives in `gmns_opt.benchmark.registry`; this package
+exposes it for discovery and groups families by maturity. See docs/application_taxonomy.md.
+"""
+from __future__ import annotations
+from ..benchmark.registry import FAMILIES, list_families, get_family, ProblemFamily
+
+BY_ID = {f.id: f for f in FAMILIES}
+FAMILY_IDS = [f.id for f in FAMILIES]
+
+
+def by_maturity(maturity: str):
+    """Families at a given maturity: 'runnable' | 'scaffold' | 'planned'."""
+    return [f for f in FAMILIES if f.maturity == maturity]
+
+
+def runnable_models():
+    """All registered runnable problem_type ids across families."""
+    out = []
+    for f in FAMILIES:
+        out.extend(f.runnable_models)
+    return sorted(set(out))
+
+
+__all__ = ["FAMILIES", "FAMILY_IDS", "BY_ID", "list_families", "get_family", "ProblemFamily",
+           "by_maturity", "runnable_models"]

gmnsopt-0.2.0/src/gmns_opt/benchmark/__init__.py

@@ -0,0 +1,4 @@
+"""Benchmark harness: run a case folder (problem.yml + GMNS input) and write the standard output set."""
+from .case import run_case
+
+__all__ = ["run_case"]

gmnsopt-0.2.0/src/gmns_opt/benchmark/case.py

@@ -0,0 +1,84 @@
+"""Run a benchmark case: read `problem.yml` + GMNS `input/`, dispatch to a model, write `output/`.
+
+Output set (the open-science case contract):
+    output/solution.csv           per-link (or per-path) solution
+    output/objective_trace.csv    iteration, objective, gap, ...   (convergence)
+    output/constraint_status.csv  constraint, status               (feasibility)
+    output/summary.md             human-readable headline + KPIs
+"""
+from __future__ import annotations
+import os
+import yaml
+from ..io import read_gmns, validate_gmns
+from ..models import (shortest_path, accessibility, min_cost_flow, max_flow, traffic_assignment,
+                      system_optimal, odme, signal_timing, network_design, facility_location,
+                      resilience_scenario, multimodal_skeleton)
+from .report import write_outputs
+
+
+def _ml_features(net, p, cd):
+    from ..ml import extract_features
+    feat = extract_features(net, scenario=p.get("scenario", "normal"))
+    return {"objective": feat["stats"]["n_links"], "solution": [], "objective_trace": [],
+            "constraint_status": [{"constraint": "feature_extraction", "status": "ok"}],
+            "meta": {"feasible": True, "maturity": "scaffold", **feat["stats"],
+                     "note": "GMNS feature blocks for ML-for-optimization (see docs/ml_for_optimization.md)"},
+            "features": feat}
+
+# each entry: (net, params, case_dir) -> result dict
+DISPATCH = {
+    "shortest_path": lambda net, p, cd: shortest_path(net, p["origin"], p["destination"],
+                                                      weight=p.get("weight", "fftt_min"),
+                                                      by_zone=p.get("by_zone", True)),
+    "accessibility": lambda net, p, cd: accessibility(net, threshold_min=p.get("threshold_min", 30.0),
+                                                      weight=p.get("weight", "fftt_min"),
+                                                      decay=p.get("decay", 0.0)),
+    "min_cost_flow": lambda net, p, cd: min_cost_flow(net, p["supplies"], weight=p.get("weight", "fftt_min"),
+                                                      by_zone=p.get("by_zone", True), scale=p.get("scale", 1)),
+    "max_flow": lambda net, p, cd: max_flow(net, p["source"], p["sink"], by_zone=p.get("by_zone", True)),
+    "traffic_assignment": lambda net, p, cd: traffic_assignment(net, max_iter=p.get("max_iter", 60),
+                                                                gap_tol=p.get("gap_tol", 1e-4),
+                                                                by_zone=p.get("by_zone", True)),
+    "system_optimal": lambda net, p, cd: system_optimal(net, max_iter=p.get("max_iter", 80),
+                                                        gap_tol=p.get("gap_tol", 1e-4),
+                                                        by_zone=p.get("by_zone", True)),
+    "odme": lambda net, p, cd: odme(net, case_dir=cd, reg=p.get("reg", 0.1), by_zone=p.get("by_zone", True)),
+    "signal_timing": lambda net, p, cd: signal_timing(net, p["phases"], cycle=p.get("cycle", 90.0),
+                                                      lost_time_per_phase=p.get("lost_time_per_phase", 4.0),
+                                                      min_green=p.get("min_green", 7.0)),
+    "network_design": lambda net, p, cd: network_design(net, p["source"], p["sink"], p["flow"], p["budget"],
+                                                        by_zone=p.get("by_zone", True),
+                                                        candidate_link_ids=p.get("candidate_link_ids")),
+    "facility_location": lambda net, p, cd: facility_location(net, p["k"], candidates=p.get("candidates"),
+                                                             weight=p.get("weight", "fftt_min")),
+    "resilience_scenario": lambda net, p, cd: resilience_scenario(net, drop_link_ids=p.get("drop_link_ids"),
+                                                                 drop=p.get("drop", 0.5), case_dir=cd,
+                                                                 by_zone=p.get("by_zone", True)),
+    "multimodal_skeleton": lambda net, p, cd: multimodal_skeleton(net, modes=p.get("modes"),
+                                                                 time_stages=p.get("time_stages", 4),
+                                                                 scenarios=p.get("scenarios")),
+    "ml_features": _ml_features,
+}
+
+
+def run_case(case_dir: str, write: bool = True) -> dict:
+    """Run the case in `case_dir`. Returns the result dict; writes output/ when `write` is True."""
+    with open(os.path.join(case_dir, "problem.yml"), encoding="utf-8") as f:
+        problem = yaml.safe_load(f)
+    ptype = problem["problem_type"]
+    if ptype not in DISPATCH:
+        raise ValueError(f"unknown problem_type '{ptype}'. Available: {sorted(DISPATCH)}")
+
+    net = read_gmns(case_dir)
+    report = validate_gmns(net)
+    if not report["ok"]:
+        raise ValueError(f"GMNS validation failed for {case_dir}: {report['errors'][:5]}")
+
+    result = DISPATCH[ptype](net, problem.get("params", {}) or {}, case_dir)
+    result["problem"] = problem
+    result["network_stats"] = report["stats"]
+    if write:
+        out = os.path.join(case_dir, "output")
+        write_outputs(out, problem, result, report)
+        result["output_dir"] = out
+    return result

gmnsopt-0.2.0/src/gmns_opt/benchmark/registry.py

@@ -0,0 +1,129 @@
+"""Benchmark category registry — the machine-readable taxonomy of transportation optimization families.
+
+Each `ProblemFamily` records its formulation classes, required/optional GMNS files, required outputs, default
+solver tier, visualization type, and maturity (runnable | scaffold | planned) plus the implemented model
+templates (`problem_type` ids usable in a case `problem.yml`). This is the single source of truth surfaced by
+`gmns-opt list-families` / `describe-family` and by `gmns_opt.applications`.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass(frozen=True)
+class ProblemFamily:
+    id: str
+    name: str
+    formulation_classes: List[str]
+    required_files: List[str]
+    optional_files: List[str] = field(default_factory=list)
+    outputs: List[str] = field(default_factory=lambda: ["solution.csv", "objective_trace.csv",
+                                                        "constraint_status.csv", "summary.md"])
+    default_solver_tier: int = 0
+    visualization: str = "link_flow"
+    maturity: str = "planned"                       # runnable | scaffold | planned
+    runnable_models: List[str] = field(default_factory=list)   # registered problem_type ids
+    subtypes: List[str] = field(default_factory=list)
+
+
+FAMILIES: List[ProblemFamily] = [
+    ProblemFamily(
+        id="routing_accessibility", name="Routing & Accessibility",
+        formulation_classes=["LP", "network_flow"],
+        required_files=["node.csv", "link.csv"], optional_files=["zone.csv", "demand.csv", "transit_route.csv"],
+        default_solver_tier=0, visualization="path_highlight", maturity="runnable",
+        runnable_models=["shortest_path", "accessibility", "min_cost_flow"],
+        subtypes=["shortest_path", "multimodal_path", "accessibility", "equity_aware_access"]),
+    ProblemFamily(
+        id="traffic_assignment_pricing", name="Traffic Assignment & Pricing",
+        formulation_classes=["convex_NLP", "MIP", "dynamic", "stochastic"],
+        required_files=["node.csv", "link.csv", "demand.csv"], optional_files=["toll.csv", "scenario.csv"],
+        default_solver_tier=0, visualization="flow_height_speed_color", maturity="runnable",
+        runnable_models=["traffic_assignment", "system_optimal"],
+        subtypes=["user_equilibrium", "system_optimal", "dynamic_assignment", "congestion_pricing",
+                  "managed_lane_control"]),
+    ProblemFamily(
+        id="odme_inverse_optimization", name="ODME & Inverse Optimization",
+        formulation_classes=["LP", "QP", "NLP", "stochastic", "inverse"],
+        required_files=["node.csv", "link.csv", "demand.csv"],
+        optional_files=["counts.csv", "detector.csv", "trajectory.csv", "scenario.csv"],
+        default_solver_tier=0, visualization="desire_line_delta", maturity="runnable",
+        runnable_models=["odme"],
+        subtypes=["od_matrix_estimation", "path_flow_correction", "sensor_residual_min", "demand_tensor_calibration"]),
+    ProblemFamily(
+        id="signal_queue_control", name="Signal & Queue Spillback Control",
+        formulation_classes=["MIP", "dynamic", "stochastic", "RL_ready"],
+        required_files=["node.csv", "link.csv", "demand.csv"],
+        optional_files=["movement.csv", "signal_timing.csv", "detector.csv", "scenario.csv"],
+        outputs=["solution_signal.csv", "queue_profile.csv", "constraint_status.csv", "objective_trace.csv"],
+        default_solver_tier=0, visualization="phase_clock_queue_ribbon", maturity="runnable",
+        runnable_models=["signal_timing"],
+        subtypes=["signal_timing", "green_split_offset_phase", "queue_spillback", "corridor_mpc_milp_rl"]),
+    ProblemFamily(
+        id="resilience_workzone_incident", name="Resilience, Work-Zone & Incident",
+        formulation_classes=["MIP", "stochastic", "dynamic", "robust"],
+        required_files=["node.csv", "link.csv", "demand.csv"], optional_files=["scenario.csv", "resource.csv"],
+        outputs=["scenario_summary.csv", "solution.csv", "constraint_status.csv", "objective_trace.csv"],
+        default_solver_tier=0, visualization="warning_layer_before_after", maturity="runnable",
+        runnable_models=["resilience_scenario", "max_flow"],
+        subtypes=["incident_response", "work_zone_scheduling", "extreme_heat_weather_flood",
+                  "evacuation_recovery"]),
+    ProblemFamily(
+        id="cav_control", name="CAV Mixed-Traffic Control",
+        formulation_classes=["MIP", "QP", "NLP", "stochastic", "dynamic", "RL"],
+        required_files=["node.csv", "link.csv", "demand.csv"],
+        optional_files=["scenario.csv", "penetration.csv", "control_zone.csv"],
+        outputs=["decision_variable.csv", "constraint_status.csv", "objective_trace.csv", "summary.md"],
+        default_solver_tier=2, visualization="control_zone_speed", maturity="scaffold",
+        runnable_models=["multimodal_skeleton"],
+        subtypes=["mixed_traffic", "speed_advisory", "platooning", "lane_use_control", "ramp_metering",
+                  "communication_failure"]),
+    ProblemFamily(
+        id="uam_air_ground_coordination", name="UAM Air–Ground Coordination",
+        formulation_classes=["MIP", "stochastic", "dynamic", "RL"],
+        required_files=["node.csv", "link.csv", "demand.csv"],
+        optional_files=["vertiport.csv", "air_link.csv", "weather_scenario.csv", "charging_station.csv"],
+        outputs=["decision_variable.csv", "constraint_status.csv", "objective_trace.csv", "summary.md"],
+        default_solver_tier=2, visualization="vertiport_queue_3d", maturity="scaffold",
+        runnable_models=["multimodal_skeleton"],
+        subtypes=["vertiport_capacity", "dispatch_repositioning", "weather_uncertainty", "battery_charging",
+                  "ground_access_integration"]),
+    ProblemFamily(
+        id="freight_ev_logistics", name="Freight, EV & Logistics Routing",
+        formulation_classes=["MIP", "stochastic", "dynamic"],
+        required_files=["node.csv", "link.csv"],
+        optional_files=["vehicle.csv", "charging_station.csv", "delivery_demand.csv", "scenario.csv"],
+        default_solver_tier=1, visualization="route_energy", maturity="scaffold",
+        runnable_models=["facility_location"],
+        subtypes=["vrp", "ev_routing_charging", "time_windows", "curb_depot_fleet", "truck_drone_uam"]),
+    ProblemFamily(
+        id="transit_frequency_accessibility", name="Transit Frequency & Accessibility",
+        formulation_classes=["MIP", "LP", "stochastic"],
+        required_files=["node.csv", "link.csv", "demand.csv"],
+        optional_files=["transit_route.csv", "fleet.csv", "scenario.csv"],
+        default_solver_tier=1, visualization="frequency_accessibility", maturity="planned",
+        runnable_models=[],
+        subtypes=["bus_frequency", "fleet_allocation", "first_last_mile", "transfer_coordination",
+                  "equity_service"]),
+    ProblemFamily(
+        id="solver_learning_and_neural_optimization", name="Solver Learning & Neural Optimization",
+        formulation_classes=["ML", "RL", "surrogate"],
+        required_files=["node.csv", "link.csv", "demand.csv"], optional_files=["scenario.csv"],
+        outputs=["features.json", "warm_start.csv", "objective_trace.csv", "summary.md"],
+        default_solver_tier=3, visualization="convergence_panel", maturity="scaffold",
+        runnable_models=["ml_features"],
+        subtypes=["learning_to_warm_start", "learning_to_branch", "graph_neural_features", "neural_surrogate",
+                  "rl_policy_interface", "train_val_test_city_split"]),
+]
+
+_BY_ID = {f.id: f for f in FAMILIES}
+
+
+def list_families() -> List[ProblemFamily]:
+    return list(FAMILIES)
+
+
+def get_family(family_id: str) -> ProblemFamily:
+    if family_id not in _BY_ID:
+        raise KeyError(f"unknown family '{family_id}'. Known: {sorted(_BY_ID)}")
+    return _BY_ID[family_id]