DLSim4GMNS 0.1.0

DLSim4GMNS -- a physics-gated space-time-event freeway simulator on GMNS: FD, dynamic ODME, and a validator.

DLSim4GMNS

A physics-gated space-time-event freeway simulator on GMNS — predict density, let the fundamental diagram give speed and flow so q = k·v holds by construction, and a built-in physics gate validates every state. One pipeline runs on any GMNS network: a corridor, a whole region, or a new city built from OpenStreetMap.

Part of the ASU Trans-AI Lab GMNS toolchain alongside osm2gmns, Path4GMNS, and Vol2Timing.

Positioning (read this first)

DLSim4GMNS is a GMNS-first, freeway-and-corridor-oriented dynamic traffic simulator for MPO-scale workflow automation — fast enough for repeated scenario testing, physically constrained enough for planning credibility, and simple enough to run from standard GMNS networks without heavy microsimulation setup.

It is not a replacement for full microscopic simulators such as SUMO/VISSIM/Aimsun; it complements them for fast, reproducible, GMNS-native corridor and MPO scenario work. Use DLSim4GMNS to go from a GMNS network to a decision-ready scenario report; use SUMO for detailed microscopic, multimodal, or signal-control simulation.

→ docs/design_rationale.md · docs/benchmark_protocol.md · docs/positioning_vs_sumo.md · docs/assumptions.md

Install

pip install DLSim4GMNS               # core (numpy, pandas)
pip install "DLSim4GMNS[odme]"       # + dynamic ODME (scipy)
pip install "DLSim4GMNS[osm]"        # + OSMnx/Boeing transfer networks

Quickstart

import dlsim4gmns as dl

out = dl.run()                       # bundled sample corridor
print(out["gate"])                   # True — physics gate passed
print(out["state"].head())           # density-canonical state: q = k*v exact

or the CLI on any GMNS folder (node.csv, link.csv):

dlsim4gmns path/to/network           # load -> simulate -> physics gate

The MPO workflow (dr)

The workflow spine — GMNS network + dynamic OD demand → physics-checked dynamic state → report (see docs/demonstration_levels.md):

dr validate  examples/merge_bottleneck        # network/scenario complete + physical
dr run       examples/merge_bottleneck        # -> out/link_state.csv, bottleneck_report.csv, ...
dr calibrate examples/merge_bottleneck --observed 6473   # 1-parameter ODME
dr report    examples/merge_bottleneck/out    # -> out/scenario_report.md
dr field     examples/data/i210e_field        # validate REAL corridor data + rank bottlenecks

Level-2 field testbed (examples/data/i210e_field/): the real I-210E freeway (73 links, Caltrans PeMS, public). The validated result is that the density-canonical model predicts observed speed from observed density (via a per-link-calibrated triangular FD) to ~7% MAPE — a genuine model-vs-field test. (q = k·v also holds to ~100%, but that is internal consistency, not validation: PeMS density is derived as flow/speed, so the identity holds by construction.) The bottleneck ranking recovers the recurring I-210E congestion. See examples/06_corridor_i210e.py.

The Level-1 oracle (examples/merge_bottleneck/) is a 1-2-3 merge where a downstream incident forms a queue that spills back upstream — the whole causal chain (demand → capped discharge → queue → speed drop → spillback → travel time → ODME recovery), every state passing the physics gate. The freeway-junction toolkit (examples/freeway_junction/) adds an off-ramp diverge and a ramp meter (lane-proportional merge, non-blocking off-ramp, time-dependent metering — see docs/assumptions.md). Both run on the pure-Python engine (any platform) and match the native C++ engine bit-for-bit.

The four-step GMNS workflow

1. Network — build a GMNS network (osm2gmns from OpenStreetMap, or your own).
2. Load — dl.read_network(dir) → nodes, links, and the per-link fundamental diagram.
3. Simulate — dl.simulate(net) → a density-canonical state {speed, flow, density}.
4. Validate — dl.validate(state, fd) → the physics gate (q=k·v, FD-feasible, …).

What's inside

Module	Purpose
dlsim4gmns.fd	triangular fundamental diagram; q = k·v exact; speed→density inversion
dlsim4gmns.gmns	GMNS node/link readers; FD from link attributes
dlsim4gmns.dynamics	Newell KW dynamic loading — corridor + freeway-junction (merge/diverge) engine
dlsim4gmns.scenario	scenario driver: GMNS + dynamic OD + incidents/meters → physics-checked state
dlsim4gmns.native	the same engine in C++ (libdlsim), ctypes-loaded; bit-identical to Python
dlsim4gmns.control	Simulator — step-and-observe control interface (the TraCI analog)
dlsim4gmns.field	Level-2 field testbed: load real corridor data, validate physics, FD calibration
dlsim4gmns.validator	the physics gate (G0 schema, G1 q=k·v/FD-feasible)
dlsim4gmns.odme	dynamic ODME (Flow-Through-Tensor / GLS) — [odme] extra
dlsim4gmns.dr	the dr MPO workflow CLI (validate / run / calibrate / compare / report / field)
dlsim4gmns.simulator, .pipeline	light density-canonical reference producer + one-shot pipeline

Scope of v0.1.0 (be honest). The Newell kinematic-wave dynamic loader is real and resolves queues, spillback, lane-proportional merges, off-ramp diverges, and ramp meters — shipped in both pure Python and a native C++ backend (libdlsim), verified bit-identical, and validated on a real corridor (I-210E, 7% speed MAPE). It is not the full research STE kernel (movement-level signals, OpenMP determinism, the Chicago-Regional 39k-link stage runner) — that separate C++ codebase is referenced by the six xfail stubs in test_M3_backend.py, which carry its analytic values. See docs/assumptions.md for exactly what the engine models, and RELEASE_PLAN.md for the roadmap.

Feature gallery

Each feature is a runnable test (tests/features/) with a real assertion, plus a figure. Full map: FEATURES.md.

The whole thesis in one figure: predict density, and the FD gives speed and flow so q = k·v holds exactly. Space-time heatmap, network map, and ODME-fit plots are in examples/figures/.

Examples & data

examples/ has runnable scripts; examples/data/ieee_sample/ is a real corridor from the IEEE Big-Data TrafficFlowBench-CA competition (I-10E GMNS network). Run:

python examples/01_quickstart.py          # load -> simulate -> gate
python examples/04_merge_bottleneck.py    # Level-1 oracle: merge + incident causal chain
python examples/05_freeway_junction.py    # merge + off-ramp diverge + ramp meter
python examples/06_corridor_i210e.py      # Level-2: real I-210E, physics-validated
pytest                                     # the full suite (45 pass, 6 xfail = STE stage runner)

Documentation & citation

API reference (HTML): https://asu-trans-ai-lab.github.io/DLSim4GMNS/dlsim4gmns.html — auto-built from docstrings by pdoc and published to GitHub Pages on every push (.github/workflows/docs.yml; build locally with pip install -e ".[docs]" && pdoc dlsim4gmns -o site).

Design & method docs: docs/. Based on the Qu & Zhou (2017) space-time-event framework. Data samples are research-derived from public Caltrans PeMS + OpenStreetMap/GMNS. Apache-2.0. Contributions welcome — see RELEASE_PLAN.md.