taplite4mpo 0.2.0__tar.gz

taplite4mpo-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xuesong (Simon) Zhou and the DTALite/TAPLite 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.

taplite4mpo-0.2.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# Files needed to BUILD the package from an sdist (the C++ kernel source + binding).
+include README.md LICENSE pyproject.toml setup.py
+include kernel/src/TAPLite.cpp kernel/src/TAPLite.h
+include kernel/python/binding.cpp kernel/python/CMakeLists.txt
+include kernel/python/build_native.sh kernel/python/build_shared.sh
+include kernel/CMakeLists.txt build.sh
+recursive-include dtalite_qa *.yml
+include docs/ARCHITECTURE.md docs/GOLDEN_PATH_CHECKLIST.md pytaplite/README.md
+
+# Keep the sdist small — exclude the large example / benchmark / agency data.
+prune examples
+prune test_networks
+prune kernel/data_sets
+prune nvta_run
+prune private
+prune .github
+global-exclude *.pyc
+global-exclude __pycache__/*
+global-exclude *.pyd *.so *.dll *.dylib *.egg-info

taplite4mpo-0.2.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: taplite4mpo
+Version: 0.2.0
+Summary: Open C++ static traffic-assignment kernel (GMNS) for MPO/DOT models, with a Python QA/orchestration layer (dtalite_qa) and a kernel driver (pytaplite).
+Author: ASU Trans-AI Lab
+License: MIT
+Project-URL: Homepage, https://github.com/asu-trans-ai-lab/TAPLite4MPO
+Project-URL: Repository, https://github.com/asu-trans-ai-lab/TAPLite4MPO
+Project-URL: Documentation, https://github.com/asu-trans-ai-lab/TAPLite4MPO/blob/main/docs/ARCHITECTURE.md
+Project-URL: Issues, https://github.com/asu-trans-ai-lab/TAPLite4MPO/issues
+Keywords: traffic-assignment,transportation,user-equilibrium,frank-wolfe,gmns,dtalite,taplite,mpo,travel-demand-model,vdf,qvdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: data
+Requires-Dist: pandas; extra == "data"
+Provides-Extra: science
+Requires-Dist: numpy; extra == "science"
+Requires-Dist: scipy; extra == "science"
+Provides-Extra: gis
+Requires-Dist: pyshp; extra == "gis"
+Requires-Dist: pandas; extra == "gis"
+Provides-Extra: all
+Requires-Dist: pandas; extra == "all"
+Requires-Dist: numpy; extra == "all"
+Requires-Dist: scipy; extra == "all"
+Requires-Dist: pyshp; extra == "all"
+Dynamic: license-file
+
+# TAPLite4MPO — open C++ static traffic assignment for MPOs
+
+[![build-and-test](../../actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A single-file, reproducible **C++ (CMake) static user-equilibrium traffic-assignment
+kernel** (Frank–Wolfe) for GMNS networks — with the VDF library, generalized cost,
+peak-load-factor, and solver options that **MPO/DOT static highway assignments** need —
+plus a Python QA/automation package, open benchmark networks, and a two-volume user
+guide. Built for teaching and for reproducing agency assignments (ARC, SERPM, TRPA,
+MTC, SANDAG, MWCOG, VDOT, ODOT).
+
+![TAPLite4MPO at a glance — the Golden Path (collect → GMNS → declare → run → validate → advanced), the three gates (can I run / trust / improve), why a shapefile is not yet a model, the dataset ladder (Sketch → Regional → ARC Atlanta → OSM), super-zone compression (~2× faster), and recovering the original-resolution zone-to-zone skim (R²=0.99).](workflow_diagram.png)
+
+> The whole pipeline at a glance. Start with **[docs/GOLDEN_PATH_CHECKLIST.md](docs/GOLDEN_PATH_CHECKLIST.md)**.
+> (Figure generated from `docs/IMAGE_PROMPTS.md`.)
+
+> ### ⚙️ Which part solves the assignment?
+> The **C++ kernel** (`bin/DTALite.exe`, `kernel/src/TAPLite.cpp`) is the **solver** —
+> Frank–Wolfe equilibrium, the VDF library, OpenMP, the scale. The **`dtalite_qa` Python
+> package is QA/orchestration only**: it validates inputs, builds scenarios, and *invokes* the
+> kernel — **it does not compute the assignment.** So you **must build the kernel**
+> (`bash build.sh`); running only Python assigns nothing. This is not a pure-Python solver.
+> Full explanation, environment matrix, and how to call the kernel from Python:
+> **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
+
+**Features**
+- Frank–Wolfe with an exact cost-based line search; **conjugate / bi-conjugate FW**
+  (`assignment_method`) for faster convergence on congested networks.
+- **VDF library:** BPR, modified-BPR (linear term), conical (Spiess), QVDF (queue),
+  BPR2, INRETS, Akcelik, SANDAG signal-delay, SCAG piecewise-BPR, SCAG ramp-meter
+  (`vdf_type` 0–8).
+- **QVDF congestion duration** — a D/C-consistent queue output (`P`, severe-congestion
+  duration, queue speeds), calibrated from corridor speeds by the **CBI sister project**.
+- Multiclass: per-mode demand, **VOT**, **PCE**, occupancy, per-mode toll + distance
+  operating cost (generalized cost), `allowed_use` (HOV/truck/managed lanes).
+- **Peak-Load-Factor / period-capacity** convention (`vdf_plf = φ/L`).
+- Relative-gap stop (N consecutive iters), binary demand fast-load, OpenMP parallel.
+
+> **Start with the flagship example → [`examples/arc_atlanta/`](examples/arc_atlanta/):**
+> a complete end-to-end MPO run — reproduce the Atlanta Regional Commission's AM highway
+> assignment and **validate it against ARC's own count benchmark** (region %RMSE 22 %,
+> target ~38 %; re-baselined 2026-07 from 23 % after the Dijkstra-default and gap-metric
+> kernel updates). It shows every MPO feature wired up, with a clean ARC-requirement →
+> kernel-setting mapping. Background: [`docs/mpo_spec/`](docs/mpo_spec/) (the design spec
+> + multi-agency survey).
+
+---
+
+## 1. Build the kernel (the solver — required)
+
+`bin/DTALite.exe` is the C++ engine that actually runs the assignment; the Python tools just
+drive it. Build it first:
+```bash
+bash build.sh          # -> bin/DTALite.exe   (CMake + g++/MinGW, OpenMP, Release)
+```
+Requires CMake, a C++17 compiler (g++/clang/MSVC), and OpenMP. Output: `bin/DTALite.exe`.
+(See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for why this is mandatory.)
+
+### Install the Python packages
+```bash
+pip install .            # installs dtalite_qa + pytaplite; compiles the in-process kernel binding
+```
+This builds `pytaplite._native` from the bundled kernel source (falls back to subprocess if no
+compiler). Multi-platform PyPI wheels (`pip install taplite4mpo`) are produced by cibuildwheel
+on a version tag — see **[RELEASE.md](RELEASE.md)**.
+
+Then call the kernel from Python:
+```python
+import pytaplite
+r = pytaplite.assign("kernel/data_sets/02_Sioux_Falls")   # runs the C++ kernel
+print(r.summary())                                         # links, VMT, VHT, returncode
+```
+Runnable demo: **[`examples/pytaplite_quickstart.py`](examples/pytaplite_quickstart.py)**
+(`python examples/pytaplite_quickstart.py`).
+
+## 2. Reproduce a run (open benchmark networks — no extra data needed)
+
+```bash
+cd kernel/data_sets/02_Sioux_Falls       # or 03_chicago_sketch, 04_chicago_regional
+cp ../../../bin/DTALite.exe .
+./DTALite.exe                            # reads node/link/demand/settings, writes link_performance.csv
+```
+
+Or via the Python QA wrapper (validates inputs first, then runs):
+```bash
+pip install -e .
+python -m dtalite_qa run kernel/data_sets/02_Sioux_Falls --exe bin/DTALite.exe
+```
+
+## 3. Regression / self-test
+
+```bash
+python test_networks/run_regression.py   # builds & checks BPR/conic/QVDF, multimodal, turn restrictions
+```
+
+---
+
+## 4. Documentation
+- **[HANDOFF/](HANDOFF/)** — ⭐ **new engineer? start here.** The onboarding & handoff folder:
+  the ordered reading path, the runs to reproduce, the "which agency taught us this" issue
+  index, a **[BPR/VDF/PLF config-rules card](HANDOFF/BPR_AND_VDF_CONFIG_RULES.md)**, and a
+  **[hands-on lab](HANDOFF/REPRODUCE_THE_ISSUES.md)** that trips each classic conversion error
+  on the open networks so you learn to recognize it.
+- **[docs/CONVERSION_ERRORS_CATALOG.md](docs/CONVERSION_ERRORS_CATALOG.md)** — the
+  **lessons-learned / error-source** reference: every way an MPO hand-off goes wrong
+  (capacity, PLF, units, demand, zones, VDF, truncation, allowed-use, count basis, build),
+  symptom → cause → fix → *which agency*.
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — **the C++ kernel solves; the Python
+  package orchestrates.** Which part runs what, the environment matrix, and how to call the
+  kernel from Python. Read it if you're unsure what's doing the assignment.
+- **[docs/GOLDEN_PATH_CHECKLIST.md](docs/GOLDEN_PATH_CHECKLIST.md)** — ⭐ **READ THIS FIRST.**
+  The Golden Path: from agency files to a trusted assignment, in 6 stages, framed by three
+  questions — *can I run? can I trust it? can I improve it?* Simple first, advanced later.
+- **[docs/DATASET_LADDER.md](docs/DATASET_LADDER.md)** — which example to start with
+  (Chicago Sketch → Chicago Regional → ARC Atlanta → OSM quick start).
+- **[docs/onboarding_guide.html](docs/onboarding_guide.html)** — **the visual onboarding guide**:
+  open in a browser for the staged journey (GIS field-map → declare → convert → intake →
+  quality → run → traceable workflow), each with its gate and a progress tracker. Generate
+  it anytime with `python -m dtalite_qa guide`.
+- **[docs/MPO_ONBOARDING_GUIDE.md](docs/MPO_ONBOARDING_GUIDE.md)** — **start here for a new
+  agency model.** The process to turn a raw hand-off (shapefile + matrix + "alpha/beta")
+  into a trustworthy run: declare → convert → **intake audit** → resolve → validate. The
+  intake (`dtalite_qa intake`) never guesses a convention — it blocks on anything the MPO
+  didn't declare (capacity basis/period, PLF, units, trip kind) and produces an issue
+  report + conversion log + a guided HTML dashboard. The MPO fills
+  [`submission.yml`](dtalite_qa/templates/mpo_submission_template.yml) (the README for the
+  data; ARC's is in `examples/arc_atlanta/gmns/`).
+- **[USER_GUIDE.md](USER_GUIDE.md)** — Volume 1: kernel reference (input schema, settings,
+  VDFs, outputs).
+- **[USER_GUIDE_VOL2_MPO.md](USER_GUIDE_VOL2_MPO.md)** — Volume 2: static highway assignment
+  for MPOs (period capacity / PLF, generalized cost, convergence/solver, validation,
+  per-agency recipes).
+- `examples/arc_atlanta/` — **complete worked MPO example** (ARC AM assignment, calibrate
+  → run → validate vs the agency benchmark) with the ARC→kernel mapping.
+- `docs/mpo_spec/` — design spec + **multi-agency survey/conformance** (ARC, SERPM, TRPA,
+  MTC, SANDAG, MWCOG, VDOT, ODOT): requirement → kernel feature → how to verify.
+- `docs/qvdf_congestion_duration.md` — QVDF as the D/C-consistent congestion-**duration**
+  output, and the **CBI sister-project pipeline** (corridor speeds → QVDF params → kernel).
+- `docs/` — methodology notes (peak load factor, super-zone aggregation, 4-step
+  integration, OD-compression operators).
+- `docs/IMAGE_PROMPTS.md` — copy-paste prompts for GPT image tools to generate the
+  easy-to-follow figures (Golden Path, the 3 gates, super-zones, the skim advantage).
+- `.claude/skills/taplite4mpo-pipeline/` — a Claude Code **skill** encoding the whole
+  pipeline (gates, stages, conventions, the ARC loop) for agent-assisted work in this repo.
+- `dtalite_qa/` — Python package: `guide`, `intake`, `workflow`, `validate`, `fill`, `inventory`,
+  `accessibility`, `report`, `demand-bin`, `plf`, `adapt`, `run` (see `python -m dtalite_qa -h`).
+- **[`pytaplite/`](pytaplite/)** — Python interface that **drives the C++ kernel**:
+  `pytaplite.assign(scenario)` → runs `DTALite.exe`, returns `link_performance` (subprocess, or
+  the in-process `_native` binding from [`kernel/python/`](kernel/python/) if built).
+
+## 5. Folder map
+```
+TAPLite4MPO/
+├── kernel/            C++ kernel (src/TAPLite.cpp, CMakeLists.txt) + open data_sets/
+├── examples/
+│   └── arc_atlanta/   complete end-to-end MPO example (ARC AM, validated)
+├── dtalite_qa/        Python QA / control package
+├── test_networks/     open test/benchmark networks + regression harness
+├── schemas/           GMNS field schema (JSON)
+├── docs/              methodology docs
+│   └── mpo_spec/      design spec + multi-agency survey & conformance mapping
+├── nvta_run/          NVTA run-configs + helper scripts (bring-your-own-data, §6)
+├── USER_GUIDE.md      Volume 1 (kernel)
+├── USER_GUIDE_VOL2_MPO.md   Volume 2 (MPOs)
+└── build.sh
+```
+
+## 6. NVTA reproduction (bring-your-own-data)
+
+The **NVTA dataset is agency-restricted and is NOT included** in this repository.
+`nvta_run/` ships the run-configs and helper scripts (network prep, settings, conic/QVDF
+staging). To run it, point the scripts at your own copy of the data:
+
+```bash
+# option A: environment variable
+export DTALITE_NVTA_INTERNAL=/path/to/nvta/_internal
+# option B: nvta_run/local_config.json -> {"internal": "...", "subarea": "..."}
+# option C: place the data in  data/nvta_internal/
+python nvta_run/run_nvta.py
+```
+If unconfigured, the runner prints a clear message. **All of §2–§3 reproduces fully
+without it** using the open benchmark networks.
+
+> Course note: instructors distribute the NVTA data to students through a separate
+> channel (not this public repo); students set one of the options above.
+
+---
+
+## Continuous integration
+`.github/workflows/ci.yml` builds the kernel (CMake + MSVC on `windows-latest`) and runs
+the full regression suite on every push / pull request.
+
+## License & citation
+**MIT** — see `LICENSE`. If you use this kernel in research or coursework, please cite the
+DTALite / TAPLite project. (Some `docs/` notes reference internal companion files that are
+not part of this public release.)

taplite4mpo-0.2.0/README.md

@@ -0,0 +1,197 @@
+# TAPLite4MPO — open C++ static traffic assignment for MPOs
+
+[![build-and-test](../../actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A single-file, reproducible **C++ (CMake) static user-equilibrium traffic-assignment
+kernel** (Frank–Wolfe) for GMNS networks — with the VDF library, generalized cost,
+peak-load-factor, and solver options that **MPO/DOT static highway assignments** need —
+plus a Python QA/automation package, open benchmark networks, and a two-volume user
+guide. Built for teaching and for reproducing agency assignments (ARC, SERPM, TRPA,
+MTC, SANDAG, MWCOG, VDOT, ODOT).
+
+![TAPLite4MPO at a glance — the Golden Path (collect → GMNS → declare → run → validate → advanced), the three gates (can I run / trust / improve), why a shapefile is not yet a model, the dataset ladder (Sketch → Regional → ARC Atlanta → OSM), super-zone compression (~2× faster), and recovering the original-resolution zone-to-zone skim (R²=0.99).](workflow_diagram.png)
+
+> The whole pipeline at a glance. Start with **[docs/GOLDEN_PATH_CHECKLIST.md](docs/GOLDEN_PATH_CHECKLIST.md)**.
+> (Figure generated from `docs/IMAGE_PROMPTS.md`.)
+
+> ### ⚙️ Which part solves the assignment?
+> The **C++ kernel** (`bin/DTALite.exe`, `kernel/src/TAPLite.cpp`) is the **solver** —
+> Frank–Wolfe equilibrium, the VDF library, OpenMP, the scale. The **`dtalite_qa` Python
+> package is QA/orchestration only**: it validates inputs, builds scenarios, and *invokes* the
+> kernel — **it does not compute the assignment.** So you **must build the kernel**
+> (`bash build.sh`); running only Python assigns nothing. This is not a pure-Python solver.
+> Full explanation, environment matrix, and how to call the kernel from Python:
+> **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
+
+**Features**
+- Frank–Wolfe with an exact cost-based line search; **conjugate / bi-conjugate FW**
+  (`assignment_method`) for faster convergence on congested networks.
+- **VDF library:** BPR, modified-BPR (linear term), conical (Spiess), QVDF (queue),
+  BPR2, INRETS, Akcelik, SANDAG signal-delay, SCAG piecewise-BPR, SCAG ramp-meter
+  (`vdf_type` 0–8).
+- **QVDF congestion duration** — a D/C-consistent queue output (`P`, severe-congestion
+  duration, queue speeds), calibrated from corridor speeds by the **CBI sister project**.
+- Multiclass: per-mode demand, **VOT**, **PCE**, occupancy, per-mode toll + distance
+  operating cost (generalized cost), `allowed_use` (HOV/truck/managed lanes).
+- **Peak-Load-Factor / period-capacity** convention (`vdf_plf = φ/L`).
+- Relative-gap stop (N consecutive iters), binary demand fast-load, OpenMP parallel.
+
+> **Start with the flagship example → [`examples/arc_atlanta/`](examples/arc_atlanta/):**
+> a complete end-to-end MPO run — reproduce the Atlanta Regional Commission's AM highway
+> assignment and **validate it against ARC's own count benchmark** (region %RMSE 22 %,
+> target ~38 %; re-baselined 2026-07 from 23 % after the Dijkstra-default and gap-metric
+> kernel updates). It shows every MPO feature wired up, with a clean ARC-requirement →
+> kernel-setting mapping. Background: [`docs/mpo_spec/`](docs/mpo_spec/) (the design spec
+> + multi-agency survey).
+
+---
+
+## 1. Build the kernel (the solver — required)
+
+`bin/DTALite.exe` is the C++ engine that actually runs the assignment; the Python tools just
+drive it. Build it first:
+```bash
+bash build.sh          # -> bin/DTALite.exe   (CMake + g++/MinGW, OpenMP, Release)
+```
+Requires CMake, a C++17 compiler (g++/clang/MSVC), and OpenMP. Output: `bin/DTALite.exe`.
+(See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for why this is mandatory.)
+
+### Install the Python packages
+```bash
+pip install .            # installs dtalite_qa + pytaplite; compiles the in-process kernel binding
+```
+This builds `pytaplite._native` from the bundled kernel source (falls back to subprocess if no
+compiler). Multi-platform PyPI wheels (`pip install taplite4mpo`) are produced by cibuildwheel
+on a version tag — see **[RELEASE.md](RELEASE.md)**.
+
+Then call the kernel from Python:
+```python
+import pytaplite
+r = pytaplite.assign("kernel/data_sets/02_Sioux_Falls")   # runs the C++ kernel
+print(r.summary())                                         # links, VMT, VHT, returncode
+```
+Runnable demo: **[`examples/pytaplite_quickstart.py`](examples/pytaplite_quickstart.py)**
+(`python examples/pytaplite_quickstart.py`).
+
+## 2. Reproduce a run (open benchmark networks — no extra data needed)
+
+```bash
+cd kernel/data_sets/02_Sioux_Falls       # or 03_chicago_sketch, 04_chicago_regional
+cp ../../../bin/DTALite.exe .
+./DTALite.exe                            # reads node/link/demand/settings, writes link_performance.csv
+```
+
+Or via the Python QA wrapper (validates inputs first, then runs):
+```bash
+pip install -e .
+python -m dtalite_qa run kernel/data_sets/02_Sioux_Falls --exe bin/DTALite.exe
+```
+
+## 3. Regression / self-test
+
+```bash
+python test_networks/run_regression.py   # builds & checks BPR/conic/QVDF, multimodal, turn restrictions
+```
+
+---
+
+## 4. Documentation
+- **[HANDOFF/](HANDOFF/)** — ⭐ **new engineer? start here.** The onboarding & handoff folder:
+  the ordered reading path, the runs to reproduce, the "which agency taught us this" issue
+  index, a **[BPR/VDF/PLF config-rules card](HANDOFF/BPR_AND_VDF_CONFIG_RULES.md)**, and a
+  **[hands-on lab](HANDOFF/REPRODUCE_THE_ISSUES.md)** that trips each classic conversion error
+  on the open networks so you learn to recognize it.
+- **[docs/CONVERSION_ERRORS_CATALOG.md](docs/CONVERSION_ERRORS_CATALOG.md)** — the
+  **lessons-learned / error-source** reference: every way an MPO hand-off goes wrong
+  (capacity, PLF, units, demand, zones, VDF, truncation, allowed-use, count basis, build),
+  symptom → cause → fix → *which agency*.
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — **the C++ kernel solves; the Python
+  package orchestrates.** Which part runs what, the environment matrix, and how to call the
+  kernel from Python. Read it if you're unsure what's doing the assignment.
+- **[docs/GOLDEN_PATH_CHECKLIST.md](docs/GOLDEN_PATH_CHECKLIST.md)** — ⭐ **READ THIS FIRST.**
+  The Golden Path: from agency files to a trusted assignment, in 6 stages, framed by three
+  questions — *can I run? can I trust it? can I improve it?* Simple first, advanced later.
+- **[docs/DATASET_LADDER.md](docs/DATASET_LADDER.md)** — which example to start with
+  (Chicago Sketch → Chicago Regional → ARC Atlanta → OSM quick start).
+- **[docs/onboarding_guide.html](docs/onboarding_guide.html)** — **the visual onboarding guide**:
+  open in a browser for the staged journey (GIS field-map → declare → convert → intake →
+  quality → run → traceable workflow), each with its gate and a progress tracker. Generate
+  it anytime with `python -m dtalite_qa guide`.
+- **[docs/MPO_ONBOARDING_GUIDE.md](docs/MPO_ONBOARDING_GUIDE.md)** — **start here for a new
+  agency model.** The process to turn a raw hand-off (shapefile + matrix + "alpha/beta")
+  into a trustworthy run: declare → convert → **intake audit** → resolve → validate. The
+  intake (`dtalite_qa intake`) never guesses a convention — it blocks on anything the MPO
+  didn't declare (capacity basis/period, PLF, units, trip kind) and produces an issue
+  report + conversion log + a guided HTML dashboard. The MPO fills
+  [`submission.yml`](dtalite_qa/templates/mpo_submission_template.yml) (the README for the
+  data; ARC's is in `examples/arc_atlanta/gmns/`).
+- **[USER_GUIDE.md](USER_GUIDE.md)** — Volume 1: kernel reference (input schema, settings,
+  VDFs, outputs).
+- **[USER_GUIDE_VOL2_MPO.md](USER_GUIDE_VOL2_MPO.md)** — Volume 2: static highway assignment
+  for MPOs (period capacity / PLF, generalized cost, convergence/solver, validation,
+  per-agency recipes).
+- `examples/arc_atlanta/` — **complete worked MPO example** (ARC AM assignment, calibrate
+  → run → validate vs the agency benchmark) with the ARC→kernel mapping.
+- `docs/mpo_spec/` — design spec + **multi-agency survey/conformance** (ARC, SERPM, TRPA,
+  MTC, SANDAG, MWCOG, VDOT, ODOT): requirement → kernel feature → how to verify.
+- `docs/qvdf_congestion_duration.md` — QVDF as the D/C-consistent congestion-**duration**
+  output, and the **CBI sister-project pipeline** (corridor speeds → QVDF params → kernel).
+- `docs/` — methodology notes (peak load factor, super-zone aggregation, 4-step
+  integration, OD-compression operators).
+- `docs/IMAGE_PROMPTS.md` — copy-paste prompts for GPT image tools to generate the
+  easy-to-follow figures (Golden Path, the 3 gates, super-zones, the skim advantage).
+- `.claude/skills/taplite4mpo-pipeline/` — a Claude Code **skill** encoding the whole
+  pipeline (gates, stages, conventions, the ARC loop) for agent-assisted work in this repo.
+- `dtalite_qa/` — Python package: `guide`, `intake`, `workflow`, `validate`, `fill`, `inventory`,
+  `accessibility`, `report`, `demand-bin`, `plf`, `adapt`, `run` (see `python -m dtalite_qa -h`).
+- **[`pytaplite/`](pytaplite/)** — Python interface that **drives the C++ kernel**:
+  `pytaplite.assign(scenario)` → runs `DTALite.exe`, returns `link_performance` (subprocess, or
+  the in-process `_native` binding from [`kernel/python/`](kernel/python/) if built).
+
+## 5. Folder map
+```
+TAPLite4MPO/
+├── kernel/            C++ kernel (src/TAPLite.cpp, CMakeLists.txt) + open data_sets/
+├── examples/
+│   └── arc_atlanta/   complete end-to-end MPO example (ARC AM, validated)
+├── dtalite_qa/        Python QA / control package
+├── test_networks/     open test/benchmark networks + regression harness
+├── schemas/           GMNS field schema (JSON)
+├── docs/              methodology docs
+│   └── mpo_spec/      design spec + multi-agency survey & conformance mapping
+├── nvta_run/          NVTA run-configs + helper scripts (bring-your-own-data, §6)
+├── USER_GUIDE.md      Volume 1 (kernel)
+├── USER_GUIDE_VOL2_MPO.md   Volume 2 (MPOs)
+└── build.sh
+```
+
+## 6. NVTA reproduction (bring-your-own-data)
+
+The **NVTA dataset is agency-restricted and is NOT included** in this repository.
+`nvta_run/` ships the run-configs and helper scripts (network prep, settings, conic/QVDF
+staging). To run it, point the scripts at your own copy of the data:
+
+```bash
+# option A: environment variable
+export DTALITE_NVTA_INTERNAL=/path/to/nvta/_internal
+# option B: nvta_run/local_config.json -> {"internal": "...", "subarea": "..."}
+# option C: place the data in  data/nvta_internal/
+python nvta_run/run_nvta.py
+```
+If unconfigured, the runner prints a clear message. **All of §2–§3 reproduces fully
+without it** using the open benchmark networks.
+
+> Course note: instructors distribute the NVTA data to students through a separate
+> channel (not this public repo); students set one of the options above.
+
+---
+
+## Continuous integration
+`.github/workflows/ci.yml` builds the kernel (CMake + MSVC on `windows-latest`) and runs
+the full regression suite on every push / pull request.
+
+## License & citation
+**MIT** — see `LICENSE`. If you use this kernel in research or coursework, please cite the
+DTALite / TAPLite project. (Some `docs/` notes reference internal companion files that are
+not part of this public release.)

taplite4mpo-0.2.0/build.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Canonical build for the consolidated DTALite/TAPLite C++ kernel.
+# Self-contained: builds kernel/src/TAPLite.cpp -> bin/DTALite.exe via CMake.
+#
+# Output: a stripped Release standalone executable (App-Control-clean, ~1.5 MB).
+# For gdb source debugging, turn OFF Windows Smart App Control, then build with
+#   -DCMAKE_BUILD_TYPE=RelWithDebInfo  (larger binary, App Control may block it).
+set -e
+export PATH="/c/Users/xzhou/AppData/Local/Microsoft/WinGet/Packages/BrechtSanders.WinLibs.POSIX.UCRT_Microsoft.Winget.Source_8wekyb3d8bbwe/mingw64/bin:$PATH"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SRC="$HERE/kernel"
+BUILD="$HERE/cmake_build_rel"
+mkdir -p "$HERE/bin"
+echo "[build] configure (Release, stripped, exe target)"
+cmake -S "$SRC" -B "$BUILD" -G Ninja \
+    -DCMAKE_CXX_COMPILER=x86_64-w64-mingw32-g++.exe \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_CXX_FLAGS="-fopenmp -O2 -DNDEBUG" \
+    -DCMAKE_EXE_LINKER_FLAGS="-s" >/dev/null
+echo "[build] build DTALite_exe"
+cmake --build "$BUILD" --target DTALite_exe
+cp "$BUILD/DTALite_exe.exe" "$HERE/bin/DTALite.exe"
+echo "[build] kernel -> $HERE/bin/DTALite.exe ($(stat -c%s "$HERE/bin/DTALite.exe") bytes)"

taplite4mpo-0.2.0/docs/ARCHITECTURE.md

@@ -0,0 +1,116 @@
+# Architecture — what actually solves the assignment
+
+**Read this if you're unsure which part does the work.** TAPLite4MPO is **two layers**, and it
+matters which one you're using:
+
+```
+   ┌──────────────────────────────────────────────────────────────────┐
+   │  dtalite_qa  (Python package)  —  QA / orchestration ONLY         │
+   │  validates inputs · fills defaults · intake audit · builds        │
+   │  scenarios · runs the R1-R6 workflow · super-zones · skims        │
+   │  >>> it does NOT solve the assignment <<<                         │
+   └───────────────────────────────┬──────────────────────────────────┘
+                                    │  prepares CSVs, then invokes ↓ (subprocess)
+   ┌───────────────────────────────▼──────────────────────────────────┐
+   │  THE KERNEL  (C++17, bin/DTALite.exe)  —  the SOLVER / engine     │
+   │  reads node/link/demand/settings CSV → Frank-Wolfe / conjugate /  │
+   │  bi-conjugate user equilibrium (OpenMP, scalable) → writes        │
+   │  link_performance.csv (volumes, V/C, speed, VMT/VHT, QVDF)        │
+   └──────────────────────────────────────────────────────────────────┘
+```
+
+**The C++ kernel is the engine.** All assignment math, the VDF library, the line search, the
+parallelism, and the scale live in `kernel/src/TAPLite.cpp`. The Python package is a
+*controller*: it never computes an equilibrium — it prepares the inputs the kernel reads and
+then **shells out to `DTALite.exe`** (`dtalite_qa/control.py` → `subprocess.run`). If you run
+only Python and never build the kernel, **nothing is assigned.** This is also why
+`python -m dtalite_qa run` **requires `--exe`**, and why it now fails loudly with a pointer
+here if the kernel binary is missing.
+
+> Not the same as a pure-Python solver. Some traffic-assignment tools are entirely Python; this
+> one is not. Python is the convenience/QA layer; the **C++ kernel does the assignment** and is
+> what makes it scalable to a 145k-link / 6k-zone network in minutes.
+
+---
+
+## Two ways to run — and which environment each needs
+
+| Path | What runs | You need |
+|---|---|---|
+| **A. Kernel directly** | the C++ solver only | a built `DTALite.exe`; nothing else |
+| **B. Python-orchestrated** (recommended) | Python validates/builds, then calls the kernel | Python 3.8+ **and** a built `DTALite.exe` |
+
+**A — run the kernel directly** (no Python at all):
+```bash
+cd kernel/data_sets/03_chicago_sketch
+cp ../../../bin/DTALite.exe .
+./DTALite.exe          # reads the CSVs here, writes link_performance.csv
+```
+
+**B — Python orchestrates the kernel** (QA gate first, then the same kernel):
+```bash
+pip install -e .
+python -m dtalite_qa run <scenario> --exe bin/DTALite.exe
+#   = validate inputs → fill defaults → invoke DTALite.exe → check outputs
+```
+Either way **the C++ kernel does the assignment.** Path B just wraps it with validation and
+reporting.
+
+## Environment requirements
+
+| To do this | You need |
+|---|---|
+| **Build the kernel** (once) | a C++17 compiler (g++/clang/MSVC) + CMake + OpenMP — `bash build.sh` → `bin/DTALite.exe` |
+| Run the kernel | the built `DTALite.exe` (Windows/Linux/macOS); no runtime deps |
+| Use `dtalite_qa` (intake/check/run/workflow/guide) | Python 3.8+ (standard library only) |
+| Drive the kernel from Python (`pytaplite`) | Python 3.8+ (+ `pandas` for `to_pandas`) + a built `DTALite.exe` |
+| Build the **native in-process binding** (optional) | `pybind11` + the C++ toolchain — `bash kernel/python/build_native.sh` |
+| Super-zone encoders / skim recovery | Python + `numpy`, `scipy` (and `scikit-learn` for `demand_kmeans`) |
+| Read agency shapefiles in the example converters | `pyshp` / `pyogrio` / `pandas` (provenance scripts only) |
+
+CI (`.github/workflows/ci.yml`) builds the kernel with MSVC on `windows-latest` and runs the
+regression — proof the C++ layer is the thing under test.
+
+## Calling the C++ kernel from Python — two ways, both shipped
+
+**1. `pytaplite` — the clean Python interface (recommended).**
+```python
+import pytaplite
+r = pytaplite.assign("examples/arc_atlanta/gmns_calibrated")   # runs the C++ kernel
+print(r.summary())        # {'links': ..., 'total_VMT': ..., 'returncode': 0}
+df = r.to_pandas()        # link_performance as a DataFrame
+```
+It locates the binary, runs the assignment, and loads `link_performance.csv` back. It picks
+the fastest of three execution paths automatically (all call the same C++ kernel):
+
+**2. ctypes shared library — the Path4GMNS / DTALite pattern (in-process, no pybind11).**
+The kernel exports the C-ABI symbols `DTA_AssignmentAPI()` / `DTA_SimulationAPI()`
+(`extern "C"` in `kernel/src/TAPLite.h`), so it builds as a shared library that Python loads
+with stdlib **`ctypes`** — exactly how [Path4GMNS](https://github.com/jdlph/Path4GMNS) ships
+the `DTALite` engine:
+```bash
+bash kernel/python/build_shared.sh    # -> pytaplite/DTALite.dll | libDTALite.so | libDTALite.dylib
+```
+`pytaplite.assign(...)` then loads it and calls `DTA_AssignmentAPI()` **in-process**. (CMake's
+`add_library(DTALite SHARED ...)` target builds the same library.)
+
+**3. pybind11 binding — `pytaplite._native` (alternative in-process; releases the GIL).**
+`pip install pybind11 && bash kernel/python/build_native.sh`.
+
+**Caveat (both in-process paths):** the kernel keeps global state, so run **one assignment
+per process**; for many runs use a fresh `work_dir` per call, `multiprocessing`, or
+`prefer_inproc=False` to use the subprocess path. The shared lib / native module are optional
+and git-ignored; **subprocess works with no library build.**
+
+Lowest level — just launch the binary yourself (any language can):
+```python
+import subprocess
+subprocess.run(["bin/DTALite.exe"], cwd="my_scenario")        # the solver, in that folder
+```
+
+The kernel is a **self-contained binary**, deliberately: it stays fast and dependency-free,
+
+## Where each part lives
+- `kernel/src/TAPLite.cpp`, `kernel/CMakeLists.txt`, `build.sh` — **the solver**.
+- `dtalite_qa/` — the Python controller (`control.py` is where it invokes the kernel).
+- `examples/`, `test_networks/`, `kernel/data_sets/` — inputs the kernel reads.