gmnsopt 0.2.0__py3-none-any.whl

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"]

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"]

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"]

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

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]

gmns_opt/benchmark/report.py

@@ -0,0 +1,44 @@
+"""Write the standard case output set (solution / objective_trace / constraint_status / summary.md)."""
+from __future__ import annotations
+import os
+import csv
+
+
+def _write_rows(path, rows):
+    if not rows:
+        open(path, "w").close(); return
+    keys = list(rows[0].keys())
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        w = csv.DictWriter(f, fieldnames=keys, extrasaction="ignore"); w.writeheader(); w.writerows(rows)
+
+
+def write_outputs(out_dir, problem, result, validation):
+    os.makedirs(out_dir, exist_ok=True)
+    _write_rows(os.path.join(out_dir, "solution.csv"), result.get("solution") or
+                ([{"path_node": n} for n in result.get("path", [])]))
+    _write_rows(os.path.join(out_dir, "objective_trace.csv"), result.get("objective_trace", []))
+    _write_rows(os.path.join(out_dir, "constraint_status.csv"), result.get("constraint_status", []))
+    if result.get("scenario_summary"):
+        _write_rows(os.path.join(out_dir, "scenario_summary.csv"), result["scenario_summary"])
+    if result.get("solution") and isinstance(result["solution"], list) and result["solution"] \
+            and isinstance(result["solution"][0], dict) and "variable" in result["solution"][0]:
+        _write_rows(os.path.join(out_dir, "decision_variable.csv"), result["solution"])
+
+    st = result.get("network_stats", {}); meta = result.get("meta", {})
+    lines = [f"# {problem.get('problem_name', 'case')} — result summary\n",
+             f"- **problem_type:** `{problem.get('problem_type')}`",
+             f"- **objective:** {result.get('objective')}",
+             f"- **network:** {st.get('nodes')} nodes, {st.get('links')} links, {st.get('zones')} zones, "
+             f"{st.get('od_pairs')} OD pairs (demand {st.get('total_demand')})"]
+    for k, v in meta.items():
+        lines.append(f"- **{k}:** {v}")
+    if result.get("objective_trace"):
+        last = result["objective_trace"][-1]
+        lines.append(f"- **converged trace (last):** {last}")
+    if validation.get("warnings"):
+        lines.append(f"\n> validation warnings: {len(validation['warnings'])} "
+                     f"(e.g. {validation['warnings'][0]})")
+    lines.append("\n*Outputs:* `solution.csv`, `objective_trace.csv`, `constraint_status.csv`. "
+                 "Visualize with `gmns_opt.viz` / GUI4GMNS.")
+    with open(os.path.join(out_dir, "summary.md"), "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")

gmns_opt/cli.py

@@ -0,0 +1,86 @@
+"""Command-line entry point.
+
+  gmns-opt run <case_dir>                     run a benchmark case (problem.yml + input/)
+  gmns-opt validate <case_dir>                validate a GMNS case against the data contract
+  gmns-opt list-families                      list the problem-family taxonomy
+  gmns-opt describe-family <family_id>        describe one problem family
+  gmns-opt generate-scenarios --case ...      write a scenario.csv perturbation
+  gmns-opt solver-status                      report available solver tiers
+"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="gmns-opt", description="GMNS-native transportation optimization testbed")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("run", help="run a benchmark case folder").add_argument("case_dir")
+    sub.add_parser("validate", help="validate a GMNS case").add_argument("case_dir")
+    sub.add_parser("list-families", help="list the problem-family taxonomy")
+    sub.add_parser("describe-family", help="describe one problem family").add_argument("family_id")
+    sub.add_parser("solver-status", help="report available solver tiers")
+    g = sub.add_parser("generate-scenarios", help="write a scenario.csv perturbation for a case")
+    g.add_argument("--case", required=True)
+    g.add_argument("--type", default="capacity_drop")
+    g.add_argument("--links", default="", help="comma-separated link ids")
+    g.add_argument("--drop", type=float, default=0.5)
+    g.add_argument("--factor", type=float, default=1.3)
+    g.add_argument("--seed", type=int, default=12345)
+    args = ap.parse_args(argv)
+
+    if args.cmd == "validate":
+        from .io import read_gmns, validate_gmns
+        rep = validate_gmns(read_gmns(args.case_dir))
+        print("OK" if rep["ok"] else "ERRORS", "|", rep["stats"])
+        for e in rep["errors"][:10]:
+            print("  error:", e)
+        return 0 if rep["ok"] else 1
+
+    if args.cmd == "run":
+        from .benchmark import run_case
+        res = run_case(args.case_dir)
+        print(f"[{os.path.basename(os.path.normpath(args.case_dir))}] objective = {res.get('objective')} | "
+              f"{res.get('meta', {})}")
+        print(f"outputs -> {res.get('output_dir')}")
+        return 0
+
+    if args.cmd == "list-families":
+        from .benchmark.registry import list_families
+        print(f"{'family_id':38s}{'maturity':10s}{'classes'}")
+        for f in list_families():
+            print(f"{f.id:38s}{f.maturity:10s}{','.join(f.formulation_classes)}")
+        return 0
+
+    if args.cmd == "describe-family":
+        from .benchmark.registry import get_family
+        f = get_family(args.family_id)
+        print(f"# {f.name}  ({f.id})  [maturity: {f.maturity}]")
+        print(f"formulation_classes : {', '.join(f.formulation_classes)}")
+        print(f"required_files      : {', '.join(f.required_files)}")
+        print(f"optional_files      : {', '.join(f.optional_files)}")
+        print(f"outputs             : {', '.join(f.outputs)}")
+        print(f"default_solver_tier : {f.default_solver_tier}")
+        print(f"visualization       : {f.visualization}")
+        print(f"runnable_models     : {', '.join(f.runnable_models) or '(none yet)'}")
+        print(f"subtypes            : {', '.join(f.subtypes)}")
+        return 0
+
+    if args.cmd == "solver-status":
+        from .solvers import solver_status
+        for s in solver_status():
+            print(f"tier {s['tier']}  {s['name']:14s} available={s['available']}  {','.join(s['classes'])}")
+        return 0
+
+    if args.cmd == "generate-scenarios":
+        from .scenarios import generate_scenarios
+        links = [int(x) for x in args.links.split(",") if x.strip()] or None
+        path = generate_scenarios(args.case, scenario_type=args.type, links=links, drop=args.drop,
+                                  factor=args.factor, seed=args.seed)
+        print(f"wrote {path}")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gmns_opt/io/__init__.py

@@ -0,0 +1,6 @@
+"""GMNS I/O: read node/link/demand, validate against the data contract, build a routable graph."""
+from .read_gmns import read_gmns, GMNSNetwork
+from .build_graph import build_graph
+from .validate_gmns import validate_gmns
+
+__all__ = ["read_gmns", "GMNSNetwork", "build_graph", "validate_gmns"]

gmns_opt/io/build_graph.py

@@ -0,0 +1,36 @@
+"""Build a routable networkx DiGraph from a GMNSNetwork (free-flow travel time as default weight)."""
+from __future__ import annotations
+import networkx as nx
+
+
+def build_graph(net, weight: str = "fftt_min"):
+    """Return a networkx.DiGraph. Each edge carries link attributes + `weight` (default free-flow minutes).
+
+    Parallel links (same from/to) are collapsed to the lowest-cost link for simple-graph algorithms; the
+    full link list is preserved on the graph as `graph['links']` for flow models that need every link.
+    """
+    G = nx.DiGraph()
+    for nid, a in net.nodes.items():
+        G.add_node(nid, **a)
+    best = {}
+    for lk in net.links:
+        key = (lk.from_node, lk.to_node)
+        w = getattr(lk, weight) if hasattr(lk, weight) else lk.fftt_min
+        if key not in best or w < best[key][0]:
+            best[key] = (w, lk)
+    for (u, v), (w, lk) in best.items():
+        G.add_edge(u, v, weight=w, link_id=lk.link_id, capacity=lk.capacity,
+                   fftt_min=lk.fftt_min, length=lk.length, alpha=lk.alpha, beta=lk.beta)
+    G.graph["links"] = net.links
+    G.graph["nodes"] = net.nodes
+    return G
+
+
+def zone_to_node(net):
+    """Map zone_id -> node_id (a zone is anchored at the node that declares it)."""
+    z2n = {}
+    for nid, a in net.nodes.items():
+        z = a.get("zone_id")
+        if z is not None and z not in z2n:
+            z2n[z] = nid
+    return z2n

gmns_opt/io/read_gmns.py

@@ -0,0 +1,88 @@
+"""Read a GMNS case directory (node.csv, link.csv, demand.csv) into plain Python structures.
+
+GMNS reference: https://github.com/zephyr-data-specs/GMNS . We use the minimal routable subset:
+  node.csv : node_id [, zone_id, x_coord, y_coord]
+  link.csv : link_id, from_node_id, to_node_id [, length, lanes, free_speed, capacity, vdf_alpha, vdf_beta]
+  demand.csv: o_zone_id, d_zone_id, volume
+Free-flow travel time is derived as length / free_speed when not given (consistent units are the caller's
+responsibility; the bundled cases use miles and mph -> hours, reported in minutes).
+"""
+from __future__ import annotations
+import csv
+import os
+from dataclasses import dataclass, field
+
+
+def _num(v, default=0.0):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return default
+
+
+@dataclass
+class Link:
+    link_id: int
+    from_node: int
+    to_node: int
+    length: float = 1.0
+    lanes: float = 1.0
+    free_speed: float = 30.0
+    capacity: float = 1000.0      # per the link (already lane-aggregated in the bundled cases)
+    alpha: float = 0.15           # BPR alpha
+    beta: float = 4.0             # BPR beta
+
+    @property
+    def fftt_min(self) -> float:
+        """free-flow travel time in minutes (length[mi] / speed[mph] * 60)."""
+        return (self.length / max(self.free_speed, 1e-6)) * 60.0
+
+
+@dataclass
+class GMNSNetwork:
+    nodes: dict = field(default_factory=dict)      # node_id -> {zone_id, x, y}
+    links: list = field(default_factory=list)      # list[Link]
+    demand: list = field(default_factory=list)     # list[(o_zone, d_zone, volume)]
+
+    @property
+    def zones(self):
+        z = {n["zone_id"] for n in self.nodes.values() if n.get("zone_id")}
+        return sorted(z)
+
+
+def read_gmns(case_dir: str) -> GMNSNetwork:
+    """Read node.csv / link.csv / demand.csv from `case_dir` (or `case_dir/input`)."""
+    base = case_dir
+    if os.path.isdir(os.path.join(case_dir, "input")):
+        base = os.path.join(case_dir, "input")
+    net = GMNSNetwork()
+
+    with open(os.path.join(base, "node.csv"), encoding="utf-8-sig") as f:
+        for r in csv.DictReader(f):
+            nid = int(_num(r.get("node_id")))
+            z = r.get("zone_id")
+            net.nodes[nid] = {"zone_id": (int(_num(z)) if z not in (None, "", "0") else None),
+                              "x": _num(r.get("x_coord")), "y": _num(r.get("y_coord"))}
+
+    with open(os.path.join(base, "link.csv"), encoding="utf-8-sig") as f:
+        for r in csv.DictReader(f):
+            net.links.append(Link(
+                link_id=int(_num(r.get("link_id"))),
+                from_node=int(_num(r.get("from_node_id"))),
+                to_node=int(_num(r.get("to_node_id"))),
+                length=_num(r.get("length"), 1.0) or 1.0,
+                lanes=_num(r.get("lanes"), 1.0) or 1.0,
+                free_speed=_num(r.get("free_speed"), 30.0) or 30.0,
+                capacity=_num(r.get("capacity"), 1000.0) or 1000.0,
+                alpha=_num(r.get("vdf_alpha"), 0.15) or 0.15,
+                beta=_num(r.get("vdf_beta"), 4.0) or 4.0))
+
+    dpath = os.path.join(base, "demand.csv")
+    if os.path.exists(dpath):
+        with open(dpath, encoding="utf-8-sig") as f:
+            for r in csv.DictReader(f):
+                vol = _num(r.get("volume"))
+                if vol > 0:
+                    net.demand.append((int(_num(r.get("o_zone_id"))),
+                                       int(_num(r.get("d_zone_id"))), vol))
+    return net

gmns_opt/io/validate_gmns.py

@@ -0,0 +1,33 @@
+"""Validate a GMNSNetwork against the minimal data contract; report problems instead of crashing."""
+from __future__ import annotations
+
+
+def validate_gmns(net) -> dict:
+    """Return a report dict: {ok, errors, warnings, stats}. `ok` is False if any error is found."""
+    errors, warnings = [], []
+    node_ids = set(net.nodes)
+
+    if not net.links:
+        errors.append("no links")
+    for lk in net.links:
+        if lk.from_node not in node_ids:
+            errors.append(f"link {lk.link_id}: from_node {lk.from_node} not in node.csv")
+        if lk.to_node not in node_ids:
+            errors.append(f"link {lk.link_id}: to_node {lk.to_node} not in node.csv")
+        if lk.capacity <= 0:
+            warnings.append(f"link {lk.link_id}: non-positive capacity")
+        if lk.free_speed <= 0:
+            warnings.append(f"link {lk.link_id}: non-positive free_speed")
+
+    zones = set(net.zones)
+    for (o, d, v) in net.demand:
+        if o not in zones:
+            warnings.append(f"demand origin zone {o} has no anchoring node")
+        if d not in zones:
+            warnings.append(f"demand destination zone {d} has no anchoring node")
+
+    stats = {"nodes": len(net.nodes), "links": len(net.links), "zones": len(zones),
+             "od_pairs": len(net.demand), "total_demand": sum(v for *_, v in net.demand)}
+    # de-duplicate but keep order
+    errors = list(dict.fromkeys(errors)); warnings = list(dict.fromkeys(warnings))[:50]
+    return {"ok": not errors, "errors": errors, "warnings": warnings, "stats": stats}

gmns_opt/ml/__init__.py

@@ -0,0 +1,8 @@
+"""ML-for-optimization readiness: feature extraction, warm-start interface, learning-to-branch dataset.
+ML SUPPORTS solvers and repeated scenarios; it does not replace rigorous optimization. See
+docs/ml_for_optimization.md."""
+from .features import extract_features
+from .warm_start import WarmStarter
+from .branching_dataset import BranchRecord, write_branching_dataset
+
+__all__ = ["extract_features", "WarmStarter", "BranchRecord", "write_branching_dataset"]

gmns_opt/ml/branching_dataset.py

@@ -0,0 +1,29 @@
+"""Learning-to-branch dataset scaffold (see docs/ml_for_optimization.md).
+
+Collects (state, candidate, label) records from MILP solves for imitation of strong branching. This scaffold
+defines the record schema and a writer; wiring it to scipy.milp / commercial callbacks is a TODO."""
+from __future__ import annotations
+from dataclasses import dataclass, asdict
+from typing import List
+import csv
+
+
+@dataclass
+class BranchRecord:
+    instance_id: str
+    node_id: int
+    variable_index: int
+    fractionality: float
+    pseudo_cost: float
+    strong_branch_score: float      # imitation label
+    chosen: int                     # 1 if selected by expert
+
+
+def write_branching_dataset(records: List[BranchRecord], path: str) -> str:
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        w = csv.DictWriter(f, fieldnames=list(BranchRecord.__annotations__))
+        w.writeheader()
+        for r in records:
+            w.writerow(asdict(r))
+    return path
+# TODO: collect records from MILP callbacks; train imitation model; evaluate with train/val/test CITY split.

gmns_opt/ml/features.py

@@ -0,0 +1,39 @@
+"""Feature extraction from a GMNS network for ML-for-optimization (see docs/ml_for_optimization.md).
+
+Produces node / link / demand / graph-adjacency features usable by GNN encoders, learning-to-warm-start, and
+learning-to-branch. This does NOT replace solvers — it supports repeated-scenario workflows.
+"""
+from __future__ import annotations
+from collections import defaultdict
+import numpy as np
+
+
+def extract_features(net, scenario: str = "normal") -> dict:
+    """Return numeric feature blocks + adjacency for the network (dependency-light, numpy only)."""
+    node_ids = sorted(net.nodes)
+    nidx = {n: i for i, n in enumerate(node_ids)}
+    indeg = defaultdict(int); outdeg = defaultdict(int)
+    link_feat = []
+    for lk in net.links:
+        outdeg[lk.from_node] += 1; indeg[lk.to_node] += 1
+        link_feat.append([lk.length, lk.lanes, lk.free_speed, lk.capacity, lk.fftt_min, lk.alpha, lk.beta])
+    node_feat = []
+    for n in node_ids:
+        a = net.nodes[n]
+        node_feat.append([a.get("x", 0.0), a.get("y", 0.0), float(a.get("zone_id") is not None),
+                          indeg[n], outdeg[n]])
+    prod = defaultdict(float); attr = defaultdict(float)
+    for (o, d, v) in net.demand:
+        prod[o] += v; attr[d] += v
+    demand_feat = {"total": sum(v for *_, v in net.demand), "n_od": len(net.demand),
+                   "max_production": max(prod.values()) if prod else 0.0,
+                   "max_attraction": max(attr.values()) if attr else 0.0}
+    edge_index = [[nidx[lk.from_node], nidx[lk.to_node]] for lk in net.links]
+    return {"scenario": scenario,
+            "node_features": np.asarray(node_feat, float).tolist(),
+            "node_feature_names": ["x", "y", "is_zone", "in_degree", "out_degree"],
+            "link_features": np.asarray(link_feat, float).tolist(),
+            "link_feature_names": ["length", "lanes", "free_speed", "capacity", "fftt_min", "alpha", "beta"],
+            "demand_features": demand_feat,
+            "edge_index": edge_index,
+            "stats": {"n_nodes": len(node_ids), "n_links": len(net.links)}}