Metadata-Version: 2.4
Name: DLSim4GMNS
Version: 0.1.0
Summary: DLSim4GMNS -- a physics-gated space-time-event freeway simulator on GMNS: FD, dynamic ODME, and a validator.
Author: ASU Trans-AI Lab
License: Apache-2.0
Project-URL: Homepage, https://github.com/asu-trans-ai-lab/DLSim4GMNS
Project-URL: Repository, https://github.com/asu-trans-ai-lab/DLSim4GMNS
Keywords: traffic,simulation,GMNS,ODME,fundamental-diagram,DLSim,osm2gmns
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: odme
Requires-Dist: scipy>=1.10; extra == "odme"
Provides-Extra: osm
Requires-Dist: networkx>=3.0; extra == "osm"
Requires-Dist: geopandas>=0.14; extra == "osm"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == "viz"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: matplotlib>=3.6; extra == "test"
Provides-Extra: docs
Requires-Dist: pdoc>=14.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: matplotlib>=3.6; extra == "dev"
Requires-Dist: scipy>=1.10; extra == "dev"
Requires-Dist: pdoc>=14.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# DLSim4GMNS

[![CI](https://github.com/asu-trans-ai-lab/DLSim4GMNS/actions/workflows/ci.yml/badge.svg)](https://github.com/asu-trans-ai-lab/DLSim4GMNS/actions)
[![PyPI](https://img.shields.io/pypi/v/DLSim4GMNS.svg)](https://pypi.org/project/DLSim4GMNS/)
[![Python](https://img.shields.io/pypi/pyversions/DLSim4GMNS.svg)](https://pypi.org/project/DLSim4GMNS/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-API%20reference-brightgreen.svg)](https://asu-trans-ai-lab.github.io/DLSim4GMNS/dlsim4gmns.html)

**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`](https://github.com/jiawlu/OSM2GMNS),
[`Path4GMNS`](https://github.com/jdlph/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/design_rationale.md) · [`docs/benchmark_protocol.md`](docs/benchmark_protocol.md) · [`docs/positioning_vs_sumo.md`](docs/positioning_vs_sumo.md) · [`docs/assumptions.md`](docs/assumptions.md)

## Install

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

## Quickstart

```python
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`):
```bash
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`](docs/demonstration_levels.md)):

```bash
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`](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`](docs/assumptions.md) for exactly what the engine models, and
> [`RELEASE_PLAN.md`](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`](FEATURES.md).

![Fundamental diagram q = k·v](examples/figures/fd.png)

*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:

```bash
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/`](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`](RELEASE_PLAN.md).
