Implementation Roadmap

The tier-1 canon (64 must-implement references from REFERENCES.md), staged by version. Checked items ship in the current release (v0 also ships MSA and all-or-nothing as baselines).

Version staging: v0 core harness + link-based solvers -> v0.x accelerated FW, logit SUE, Anaheim/Barcelona/Winnipeg rungs (this release; plugin registry and profiles still open) -> v1 bush-based solvers, SUE variants, static extensions, T2 estimation track -> v2 DTA, network loading, engine adapters, day-to-day, T3 interventions.

Foundations — v0-v1 (formulations underpin metrics)

  • [x] Wardrop (1952) — Some Theoretical Aspects of Road Traffic Research (metric/protocol) — shipped in v0 (equilibrium conditions in the certified gap)

  • [x] Beckmann et al. (1956) — Studies in the Economics of Transportation (white-box solver) — shipped in v0 (Beckmann objective in metrics)

  • [x] Bureau of Public Roads (1964) — Traffic Assignment Manual (network-loading component) — shipped in v0 (BPR link performance function (Network.link_cost))

  • [x] Dafermos (1972) — The Traffic Assignment Problem for Multiclass-User Transportation Networks (white-box solver) — shipped as multiclass (adr-013)

  • [ ] Smith (1979) — The Existence, Uniqueness and Stability of Traffic Equilibria (metric/protocol)

  • [x] Dafermos (1980) — Traffic Equilibrium and Variational Inequalities (white-box solver) — shipped as vi-asym

Path/bush-based UE algorithms — v1

  • [x] Jayakrishnan et al. (1994) — A faster path-based algorithm for traffic assignment (white-box solver) — shipped in v1 (path-based gradient projection solver (gp))

  • [x] Bar-Gera (2002) — Origin-based algorithm for the traffic assignment problem (white-box solver) — shipped as oba (origin-based M/D-label proportion solver)

  • [x] Dial (2006) — A path-based user-equilibrium traffic assignment algorithm that obviates path storage and enumeration (white-box solver) — shipped in v1 (Algorithm B bush-based solver (algb))

  • [x] Bar-Gera (2010) — Traffic assignment by paired alternative segments (white-box solver) — shipped in v1 (TAPAS paired-alternative-segment solver (tapas) + proportionality diagnostic (ADR-004))

Stochastic UE & route choice — v0.x (Dial, logit-SUE MSA) / v1 (probit)

  • [x] Dial (1971) — A probabilistic multipath traffic assignment model which obviates path enumeration (network-loading component) — shipped in v0.x (STOCH loading map (models/_stoch.py))

  • [x] Daganzo & Sheffi (1977) — On stochastic models of traffic assignment (white-box solver) — shipped in v1 (SUE definition underlying the probit task)

  • [x] Fisk (1980) — Some developments in equilibrium traffic assignment (white-box solver) — shipped in v0.x (logit SUE task (fixed-point certificate, ADR-001))

  • [x] Powell & Sheffi (1982) — The convergence of equilibrium algorithms with predetermined step sizes (white-box solver) — shipped in v0.x (MSA-SUE solver step sizes)

  • [x] Sheffi & Powell (1982) — An algorithm for the equilibrium assignment problem with random link times (white-box solver) — shipped in v1 (probit SUE solver (sue-probit-msa) + MC certificate (ADR-003))

System optimum & pricing — v1

  • [x] Yang & Huang (1998) — Principle of Marginal-Cost Pricing: How Does It Work in a General Road Network? (white-box solver) — shipped in v1 (first-best marginal-cost tolls (metrics.so))

  • [x] Roughgarden & Tardos (2002) — How Bad Is Selfish Routing? (metric/protocol) — shipped in v1 (price-of-anarchy protocol + certified SO gap)

Static extensions — v1

  • [x] Florian & Nguyen (1974) — A Method for Computing Network Equilibrium with Elastic Demands (white-box solver) — shipped in v1 (elastic (variable) demand UE task/problem (ADR-005))

  • [x] Evans (1976) — Derivation and analysis of some models for combining trip distribution and assignment (white-box solver) — shipped as evans (ADR-007)

  • [x] Mahmassani & Chang (1987) — On Boundedly Rational User Equilibrium in Transportation Systems (route-choice component) — shipped as br-ue (indifference-band relaxation, ADR-008)

  • [x] Spiess & Florian (1989) — Optimal strategies: A new assignment model for transit networks (white-box solver) — shipped as transit-strategy (adr-014, parallel transit/ module)

  • [x] Larsson & Patriksson (1995) — An augmented Lagrangean dual algorithm for link capacity side constrained traffic assignment problems (white-box solver) — shipped as sc-tap (ADR-009)

Analytical DTA — v2

  • [x] Vickrey (1969) — Congestion Theory and Transport Investment (white-box solver) — shipped as vickrey (adr-019, the first departure-time equilibrium — a parallel bottleneck/ module with a closed-form UE/SO and a P1 certifier that recomputes the point queue + generalized costs from the emitted departure curve; equilibrium_gap=0 for the UE, PoA=2)

  • [x] Merchant & Nemhauser (1978) — A Model and an Algorithm for the Dynamic Traffic Assignment Problems (white-box solver) — shipped as merchant-nemhauser (adr-020, the first network DTA model — a parallel dta/ module: exit-function scenario, Carey(1987)-relaxed canonical LP with terminal clearance, and a P1 certifier that recomputes conservation/node-balance/exit-bounds/cost, resolves the LP optimum harness-side, and arithmetically verifies emitted LP-duality certificates; two hand-derived anchors incl. one where holding back is strictly optimal)

  • [x] Friesz et al. (1993) — A Variational Inequality Formulation of the Dynamic Network User Equilibrium Problem (white-box solver) — shipped as vi-due (adr-022, the simultaneous route-and-departure-time DUE closing the analytical-DTA track — the Friesz VI instantiated with generalized-Vickrey point-queue loading on parallel routes: exact closed form C=(δN+αΣs·f)/Σs with greedy used-set, single-route f=0 reduction certified by the adr-019 BottleneckEvaluator at 1e-13, and a P1 DUEEvaluator whose marginal-insertion reference scan catches the all-on-one-route false equilibrium the single-route certifier cannot see)

  • [x] Ziliaskopoulos (2000) — A Linear Programming Model for the Single Destination System Optimum Dynamic Traffic Assignment Problem (white-box solver) — shipped as lp-so-dta (adr-021, cell-level SO-DTA with finite storage/spillback — the CTM min-flux relaxed to four linear families over CellSODTAScenario; hand-derived diverge/spillback anchor J*=26 via the storage pair lemma, holding-on-the-optimal-face demonstrated, and the corridor LP == the repo’s own CTMLink loading exactly; P1 CellSODTAEvaluator with the adr-020 hardening + LP-duality certificates)

Dynamic network loading — v2

  • [x] Newell (1993) — A simplified theory of kinematic waves in highway traffic, part I: General theory (network-loading component) — shipped as newell-3det (adr-024, the interior minimum-principle three-detector reconstruction — the benchmark’s FIRST traffic-state-estimation task: given noisy/partial boundary detector curves, reconstruct the interior cumulative field N(x,t) = min(N_up(t−x/vf), N_dn(t−(L−x)/w) + κ(L−x)) at a fixed hashed query grid, scored against the harness-regenerated closed-form min. Newell’s LOADING content — the minimum principle at the link ENDS — already shipped as ltm (adr-016), so this ships the unshipped INTERIOR content, NOT a third LinkModel; the oracle and certifier are the paper’s minimum principle, the observation dials are the repo’s own P3 conventions (the paper contains no estimation numerics), and the clean level is an oracle row (ranking lives on the noisy levels where the naive/isotonic pair discriminates))

  • [x] Daganzo (1994) — The cell transmission model: A dynamic representation of highway traffic consistent with the hydrodynamic theory (network-loading component) — shipped as ctm (adr-015, the first DNL LinkModel on the dnl-core; Godunov cell dynamics at CFL=1, free-flow translation bit-exact + RH shock/spillback anchors)

  • [ ] Daganzo (1995) — The cell transmission model, part II: Network traffic (network-loading component)

  • [x] Lebacque (1996) — The Godunov scheme and what it means for first order traffic flow models (network-loading component) — shipped as godunov (adr-018, GodunovLink + GreenshieldsFD; the general-FD Godunov scheme on the first non-triangular FD — the first rarefaction physics in the benchmark, CTM being its triangular special case)

  • [x] Yperman (2007) — The Link Transmission Model for dynamic network loading (network-loading component) — shipped as ltm (adr-016, the second DNL LinkModel; stateless Newell-Daganzo cumulative-curve method, matches CTM byte-for-byte on aligned grids + runs on non-cell-aligned grids CTM rejects)

  • [x] Tampère et al. (2011) — A generic class of first order node models for dynamic macroscopic simulation of traffic flows (network-loading component) — shipped as node-model (adr-017, TampereNode; the general merge/diverge solver — oriented-capacity-proportional with FIFO, satisfies node axioms N1–N6 — that unlocks network loading for ctm/ltm)

Simulation-based DTA & software — v2 (adapters)

  • [ ] Jayakrishnan et al. (1994) — An evaluation tool for advanced traffic information and management systems in urban networks (black-box wrapper) — adapter path deferred (adr-030): FHWA DYNASMART-P is McTrans/FHWA-licensed with no public artifact, which bars a public CI row; the Peeta & Mahmassani (1995) white-box SO/UE time-dependent row below needs no binary and stays live

  • [x] Peeta & Mahmassani (1995) — System optimal and user equilibrium time-dependent traffic assignment in congested networks (white-box solver) — shipped as pm-td-ue / pm-td-so (parallel tdta/ module, adr-031): the first iterative, simulation-based time-dependent route-choice equilibrium in the benchmark — fixed-departure TD-UE and its TD-SO twin, MSA over an enumerated per-OD path set, the repo’s own CTM/LTM loading substituted for the licensing-deferred DYNASMART (adr-030) as the constraint evaluator. TDPathFlows carries only the decision variable (per-path, per-departure-interval flow); the harness reruns its own per-path loading (a private first link per path + TampereNode merges, on an interior-diverge-free topology that keeps per-commodity experienced times exactly decidable) and scores tdue_gap (the experienced-time route-swap residual, 0 iff the discrete Wardrop conditions hold) and so_bound_gap ((TSTT − Z*)/Z* against the lp-so-dta LP optimum on the CTM-cell instance derived from the same grid). Anchors derived from scratch (the paper’s 50-node DYNASMART numerics are engine-bound/irreproducible): a single-path corridor whose loaded TSTT equals the ADR-021 zil_corridor optimum 33 exactly through the new code path, a symmetric diamond whose exact TD-UE certifies tdue_gap=0 (all-on-one control 0.75), an SO≠UE wedge where the SO split attains the LP bound and beats UE TSTT (23 < 24 — the paper’s headline made executable), a merge for attribution, ltm==ctm, and the aggregate loader passing dnl_gaps C0–C8. Primary READ IN FULL (a first for a DTA row); the MSA solvers are non-certified (the certifier arbitrates). Single class, fixed departures, NOT rolling-horizon (reserved for the TR-C sibling)

  • [ ] Ben-Akiva et al. (2001) — Network State Estimation and Prediction for Real-Time Traffic Management (black-box wrapper) — deferred (adr-030): no public DynaMIT artifact exists to adapt (historically distributed by the MIT ITS Lab on request; the successor SimMobility is public but SPDX NOASSERTION) — artifact-blocked until upstream publishes one

  • [x] Zhou & Taylor (2014) — DTALite: A queue-based mesoscopic traffic simulator for fast model evaluation and calibration (black-box wrapper) — shipped as dtalite-tap (the second external engine; behind the optional DTALite extra, guarded-imported so the numpy/scipy core stays dependency-free, with a fifth CI job pinning DTALite==0.8.1): the PyPI DTALite wheel’s static Frank-Wolfe assignment() (a Bar-Gera FW.zip-derived TAPLite loop, NOT the 2014 paper’s mesoscopic queue DUE, which is the separate simulation() entry — now shipped on the observational track as dtalite-simulation, adr-040), wrapped by compiling a fixed-demand scenario into GMNS CSVs (dtalite_tap.py) whose per-link vdf_fftt/vdf_alpha/vdf_beta map the repo BPR t = fft·(1 + b·(v/cap)^power) EXACTLY — the compile map is the identity, so unlike marouter there is no mapping floor and BPR power=4 encodes directly. The emitted flows are certified under the declared BPR (P1): Braess relative_gap ≈ 1.2e-2 and Sioux Falls power-4 ≈ 5.0e-3, both frozen at the engine’s Armijo line-search stall (the honest ceiling — the wheel-engine-as-shipped, not the mapping; a converged bfw beats it by orders of magnitude), with a MANDATORY cost-matched anchor proving the engine’s own travel_time equals the repo BPR at the emitted flows on every link (max relative ~2e-5, the identity map’s payoff). The first external engine on the power-4 ladder (Sioux Falls, the marquee — marouter’s linear vdf refused it). The subprocess wrapper is mandatory (the engine’s ExitMessage does getchar()+exit() in-process — a bad input would hang or kill the host — and a second call in one process doubles the flows), the module never imports DTALite at scope (banner + in-host OpenMP load), and a read-back verifies the engine parsed every VDF parameter as declared (returncode==0 is never trusted — the engine exits 0 on missing/garbage input). Refused traps named by field: tolls (unvalidated vot conversion), sue_theta/elastic/combined/br/side-cap/link-interaction/multiclass, and an sp_calls-only budget. zhou2014dtalite anchors the software lineage (tool-paper discipline, the lopez2018 precedent) — the row validates ADAPTER + engine fidelity, never the paper’s numerics (ADR-029). A SECOND DTALite row now ships from the same wheel — dtalite-simulation, the third EDOC-1 external-dynamic observational row (ADR-036 certificate + ADR-040 row, closing the simulation() honest-sourcing loop and the first deterministic-track external row): the 2014 paper’s actual mesoscopic queue-DNL simulation() (Zhou & Taylor 2014), a sub-second vehicle.csv → trajectory.csv map where there is no declared cost law, so the engine IS the instance and the certifier re-derives the score by re-running the pinned OMP_NUM_THREADS=1 engine on the model’s emitted MSA plans (G1 replay fidelity, byte-exact on trajectory.csv). It scores the frozen-field best-response gap RG_D1 (shipped estimator, 2026-07-17: converged 0.05031 vs the step-0 Frank-Wolfe split 0.37224, 7.40× floor-displayed separation — declared ≥ 5×), which is NOT the Wardrop relative_gap of dtalite-tap (same wheel, different engine) nor of sumo-marouter, and lives on the same separate EDOC leaderboard table as the other observational rows (R8 non-comparability). The engine re-seeds an LCG per time step so it consumes no seed (seedable=False, seed_list=(), no macroreps — the deterministic track, disclosed); byte-determinism pinned on linux-x86_64. Its tutorial notebook ships with the 11-external tutorials track (06-dtalite-simulation.ipynb). A THIRD DTALite row now ships from the same wheel — odme-dtalite, a guarded static T2 ESTIMATOR (ADR-042): the wheel hides an Origin-Destination Matrix Estimation routine (performODME) INSIDE the same static assignment() entry dtalite-tap wraps (it fires when settings.csv carries odme_mode=1), a gradient-descent OD calibrator that re-weights the base assignment’s route-flows to match sensor obs_volume counts. It ships as a guarded estimator in ESTIMATOR_REGISTRY riding the EXISTING pinned-bfw ODCertifier UNCHANGED (the adr-028 zero-certifier-change ideal, the spsa-sumo precedent — emit an OD, the model-blind certifier re-assigns it under the declared BPR; zero task/runner/certifier changes). Marquee (measured, siouxfalls power-4, sensors cov 0.5 / stale prior cv 0.3): the certifier reports obs_count_rmse 994.8→365.3 (0.37×) and the ranking heldout_count_rmse 816.5→556.6 (0.68×) over the prior baseline, with the ODME descent running 69 gradient iterations (a real “estimator beats prior” row, not a no-op). The engine envelope is disclosed as a pinned-0.8.1 identity (the marouter-vdf precedent): route_output=1 is REQUIRED (with the lean route_output=0 the ODME reconstruction collapses and inflates the OD +40 %, measured — the non-obvious pilot finding); a hardcoded [0.5,1.5]×-of-(seed,target) recovery box (demand_target_frac is a documented one-sided widening dial); hardcoded penalty weights + an ABSOLUTE tol=1 convergence floor (so the marquee MUST be Sioux-Falls-scale, not Braess, to clear it); and link_performance.csv is CORRUPTED under odme_mode=1, so the OD is sourced EXCLUSIVELY from od_performance.csv (never the T1 adapter’s odme_mode=0 cost-match/mass gates). Anti-laundering holds by construction (the certifier reads only the emitted OD, never DTALite’s rosy self-report — measured self 8 vs certified 365, the engine-in-the-loop bias). Single-mode demand-only (multiclass ODME via mode_type.csv deferred); additive, golden Braess hash cf00f411… byte-identical; rides the existing dtalite CI job. Its tutorial notebook ships with the 03-estimation track (09-odme-dtalite.ipynb).

  • [x] Horni et al. (2016) — The Multi-Agent Transport Simulation MATSim (black-box wrapper) — shipped as matsim (the third external engine and the second EDOC-1 observational row — adr-036 certificate / adr-039 row, superseding the adr-030 deferral): the first agent-based, first stochastic-track external engine. The adr-030 blocker stands in its own terms — QSim has NO static latency function, so the A2 cost-matched anchor stays impossible in kind; A2’s role is instead played by the pinned engine itself under G1 replay fidelity (lastIteration = firstIteration on the emitted plans is a zero-replanning replay), and the certifier re-derives the frozen-field best-response gap RG_D1 entirely from its own replay events (per-link flows from entered-link + vehicle-enters-traffic events; output_links.csv is never a flow source — it undercounts the arrival link to zero, measured). Java-only engine with no pip extra (PyPI matsim is an unrelated neuronal simulator, adr-030): pinned matsim-2025.0-release.zip (md5 c65f35ea…) on Temurin 21.0.11+10, addressed only via TABENCH_MATSIM_HOME/TABENCH_JAVA_HOME, with a dedicated CI job installing both against hard checksums (md5/sha256 verified before unzip). Scored on the R5 stochastic track — the P8 macrorep harness (tabench.edoc.macrorep) over the pinned 5-seed list, mean RG_D1 + bootstrap CI; measured reference (shipped estimator, 2026-07-17): converged mean 0.0861 (CI [0.071, 0.102]) vs the deterministic AON control 0.4591 → 5.33× displayed-value negative-control separation; numberOfThreads=1 pinned in global/qsim/eventsManager — the same-timestamp event-tie permutation is a measured multithreading artifact (the corrected R10 record, adr-039), and the G1 hash is the tie-sorted canonical stream. RG_D1 is a frozen-field BR gap w.r.t. the engine’s own frozen realized field, NOT the static Wardrop relative_gap — it lives on a separate leaderboard table (R8) and is never compared to the static rows. Tutorial: tutorials/11-external/05-matsim.ipynb

  • [x] Lopez et al. (2018) — Microscopic Traffic Simulation using SUMO (black-box wrapper) — shipped as sumo-marouter (the first Phase-4 external-simulator adapter; behind the optional eclipse-sumo extra, guarded-imported so the numpy/scipy core stays dependency-free, with a fourth CI job pinning eclipse-sumo==1.27.1): SUMO’s macroscopic marouter SUE assignment, wrapped by compiling a fixed-demand power=1 scenario into a SUMO network (_sumo_io.py) whose edges match the repo BPR to machine precision on representable links — marouter’s cost law is a hardcoded linear-in-flow class function (PTV-Validate / VISUM-Cologne, not the ITSC paper), so two representability floors are documented and measured (a forced intercept eps=B·(200/6)/s on zero-intercept links, a parasitic slope A·K·s/C on zero-slope links). The per-edge flows are certified under the declared BPR costs (P1): Braess relative_gap ≈ 1.7e-4 (the analytic mapping floor), with a MANDATORY cost-matched anchor separating that floor from solver error. The certified row is act four of the accuracy-vs-certificate story — an industrially converged assignment, perfectly demand-feasible, that certifies a real small gap: the first number for the simulator-to-benchmark model gap practitioners implicitly set to zero (ADR-027). The refused traps are documented: marouter’s UE silently falls back to SUE, its DEFAULT incremental is non-equilibrium, and BPR power!=1 (Sioux Falls) is UNREPRESENTABLE in its linear vdf. This overturns the earlier “cannot validate in CI” assumption — the eclipse-sumo wheel ships the binaries inside the package, so the row is fully CI-validated. A SECOND SUMO row now ships from the same wheel — sumo-duaiterate, the first EDOC-1 external-dynamic observational row (ADR-036 certificate + ADR-037 row, resolving the ADR-027 duaIterate deferral): SUMO’s dynamic mesoscopic user-assignment driver duaIterate.py, where there is no declared cost law, so the engine IS the instance and the certifier re-derives the score by re-running the pinned engine in zero-replanning replay (G1) on the model’s emitted plans. It scores the frozen-field best-response gap RG_D1 (measured converged ≈ 0.02 vs an AON negative control ≈ 0.14, ~6.5× separation), which is NOT the Wardrop relative_gap of sumo-marouter and lives on a separate leaderboard table (R8 non-comparability). Its tutorial notebook ships with the 11-external tutorials track.

Day-to-day dynamics — v2

  • [x] Horowitz (1984) — The stability of stochastic equilibrium in a two-link transportation network (white-box solver) — shipped as dtd-horowitz (the perceived-cost-state day-to-day model: travelers carry a perceived link-cost vector exponentially smoothed toward the experienced costs p ← (1−w)p + w·t(v) and logit-load at it via the pinned Dial-STOCH map, reaching the same logit-SUE fixed point as sue-msa/dtd-swap-sue; certified by the existing logit-SUE fixed-point residual (ADR-001, no new scenario field); uniquely among the day-to-day models NO damping is added, so above the task-dependent stability threshold w* ≈ 0.81 the process settles into a period-2 limit cycle instead of converging — the very (in)stability Horowitz set out to study)

  • [x] Smith (1984) — The stability of a dynamic model of traffic assignment — an application of a method of Lyapunov (white-box solver) — shipped as dtd-swap (first day-to-day model)

  • [x] Cascetta (1989) — A stochastic process approach to the analysis of temporal dynamics in transportation networks (white-box solver) — shipped as dtd-stochastic (the benchmark’s first genuinely stochastic day-to-day model: a finite-population Markov chain — each day N_od = max(1, round(population_scale·d_od)) travelers per OD pair draw routes by multinomial sampling from the Dial-STOCH logit fractions at the exponentially smoothed perceived costs p ← (1−w)p + w·t(v), driven by the realized daily flow, so “equilibrium” is the chain’s stationary distribution, not a fixed point; daily flows keep a persistent O(1/√N) variability while the emitted burnt-in time average converges (ergodic theorem) to the stationary mean ≈ logit SUE (Davis & Nihan 1993 large-population limit); certified by the existing logit-SUE fixed-point residual (ADR-001, no new scenario field), which honestly floors at O(finite-population bias + sampling SE); deterministic=False routes it onto the existing macrorep stochastic track; the exponential filter is the canonical Cantarella & Cascetta (1995) special case of Cascetta’s original m-day moving-average filter — a flagged, documented variant)

  • [x] Friesz et al. (1994) — Day-to-day dynamic network disequilibria and idealized traveler information systems (white-box solver) — shipped as dtd-friesz (route-flow-state day-to-day: the state is per-OD route flows evolved by the projected dynamical system ḣ = P_K(h, −c(h)), discretized by the Bertsekas & Gafni (1982) projection step h_{k+1} = P_K(h_k − α c(h_k)); because ∂Z/∂h_p = c_p exactly for the Beckmann objective Z, this is projected gradient descent on Beckmann in route space, projecting the whole route-flow vector against today’s frozen costs at once (Jacobi) via an exact Euclidean simplex projection that conserves each OD’s demand every day; reaches the identical certified UE as the route-swap dtd-swap and the link-based dtd-link via the same monotone Beckmann descent, certified by the standard UE relative gap — no new scenario field)

  • [x] Cantarella & Cascetta (1995) — Dynamic processes and equilibrium in transportation networks: towards a unifying theory (white-box solver) — shipped as dtd-unifying (the unifying-theory node realized as a per-scenario mode gate: one two-equation process — exponential cost-learning filter p ← (1−w)p + w·t(v) plus choice update v ← v + αₙ(ChoiceLoad(p) − v) where a fraction αₙ of travelers reconsiders at the forecast costs — whose choice map is the all-or-nothing best response on deterministic scenarios (fixed point = Wardrop UE, annealed α/n step, standard relative-gap certificate) and the pinned Dial-STOCH logit load on SUE scenarios (fixed point = logit SUE, constant α, existing ADR-001 residual — no new scenario field); exact reductions regression-tested to float precision (stochastic α=1 ≡ dtd-horowitz, deterministic w=1, α=1 ≡ msa), and the re-derived joint (α, w) flip boundary (2−w)(2−α) = αw|φ′| confirms C&C’s headline on the anchor: (1,1) period-2 limit-cycles while either form of inertia — cost memory or choice inertia — restores convergence, reducing at α=1 to dtd-horowitz’s documented w* ≈ 0.81)

  • [x] He et al. (2010) — A link-based day-to-day traffic assignment model (white-box solver) — shipped as dtd-link (link-flow-state day-to-day: the state is the aggregate link-flow vector, adjusted toward the frozen-cost proximal target projected onto the feasible link polytope; reaches the identical certified UE as the route-swap dtd-swap via the same monotone Beckmann descent)

  • [x] Smith & Watling (2016) — A route-swapping dynamical system and Lyapunov function for stochastic user equilibrium (white-box solver) — shipped as dtd-swap-sue (logit-SUE sibling of dtd-swap: the same proportional route-swap day-to-day dynamics driven by the Fisk-generalized cost c_k + (1/θ) ln h_k, so the rest point is the logit stochastic user equilibrium (Fisk 1980), not deterministic UE; certified by the existing logit-SUE fixed-point residual (ADR-001, no new scenario field) with Fisk’s SUE convex objective as the monotone day-to-day Lyapunov function)

  • [x] Li et al. (2024) — Wardrop Equilibrium Can Be Boundedly Rational: A New Behavioral Theory of Route Choice (white-box solver) — shipped as dtd-cumlog (the cumulative-logit model — the first boundedly-rational logit day-to-day process whose limit is exact deterministic Wardrop UE at a finite exploitation r, filling the empty cell in the shipped matrix where every other logit-choice day-to-day row rests at SUE: travelers carry a per-OD route-valuation vector s over column-generated working sets, choose by the logit map p = softmax(−r s), and accumulate experienced route costs s ← s + ηₜ c(p) (Eq. 6) — the one-line change from the classical successive-average scheme s ← (1−ηₜ)s + ηₜ c(p) (Eq. 4, whose limit is the logit SUE) with a categorically different limit; the accumulate flag makes that Remark 3 contrast executable on one instance and identical machinery — accumulation drives the UE gap to ~0 (f_A → 2.5) while averaging rests at the analytic binary-logit SUE to 6 digits (f_A → 2.3739 at r=1); certified by the standard UE relative gap (fixed point = Wardrop UE, no new scenario field, golden Braess hash byte-identical); the harmonic schedule ηₜ = 1/(t+1) converges for any r (Theorem 1(i), asymptotically) while the constant schedule can diverge at a too-large step (preserved not damped) — Theorem 1(ii)’s eta0 < 1/(2rL) is sufficient-only and the reported eta_heuristic_scale is a flow-independent step-scale reference, not that bound; the divergent cumulative valuations resolve Harsanyi’s instability — equal-cost WE routes carry unequal, finitely-differing valuations while dropped routes diverge — and its bounded rationality is process-level (the adjustment path is imperfect), disjoint from br-ue’s concept-level indifference band (ADR-038 vs ADR-008); the primary was read in full, the strongest sourcing in the dtd family)

ML-based traffic assignment — v1 (baseline wrappers)

  • [x] Liu et al. (2023) — End-to-end learning of user equilibrium with implicit neural networks (black-box wrapper) — shipped as implicit-ue-nn, the first torch model (optional [torch] extra, ADR-025). A lean variant (the TR-C primary is paywalled/unread; formulation cross-verified from the authors’ open hEART 2024 paper + two posters): a flow-monotone MLP cost head inside a differentiable logit route-choice fixed-point layer over PathEngine column-generated route sets, trained by an exact IMD/adjoint hypergradient on the synthetic-net family against bfw reference equilibria. Its emission v = Δᵀh is demand-feasible by construction, so it clears the audit the ridge surrogate is censored by (act two of ADR-006: feasibility is architectural, equilibrium quality is not) — bfw still certifies a better gap at matched budget, and the held-out identifiability caveat is documented honestly. Anchors: A1 Braess identity (4,2,2,2,4)/route time 92, A2 IMD hypergradient vs central FD < 1e-5, A4 feasible=1 at random θ.

  • [x] Rahman & Hasan (2023) — Data-Driven Traffic Assignment: A Novel Approach for Learning Traffic Flow Patterns Using Graph Convolutional Neural Network (black-box wrapper) — shipped in v1 (learned-model wrapper + a ridge reference surrogate (not the GCN itself) certified by P1 (learned-surrogate, ADR-006))

  • [x] Liu & Meidani (2024) — End-to-end heterogeneous graph neural networks for traffic assignment (black-box wrapper) — shipped as het-gnn, the second torch model (same optional [torch] extra, ADR-026), closing Phase 3. A lean variant (the TR-C primary is paywalled/unread; formulation cross-verified with zero discrepancies from arXiv:2310.13193v3 + the NSF PAR accepted manuscript, both read in full): hand-rolled heterogeneous message passing (V/R-Encoder segment-softmax attention over real + virtual OD edges, plain-torch scatter — no torch-geometric) with size-agnostic node-kernel features [production, attraction, in/out-degree] replacing the paper’s non-permutation-equivariant |V|+2 OD-row featurization (verified: 21.5 vs 1.1e-16 under relabeling — the property that lets one trained model transfer across graph sizes without the paper’s dummy-node homogenization), an edge-MLP flow/capacity-ratio head, and the paper’s composite loss (1.0, 0.005, 0.05) trained by plain backprop. Two harness-certified checkpoints: the paper-faithful raw emission (sp_calls=0) is censored — its conservation loss L_c is the L1 form of the harness node_balance_residual, 3–5 orders above tolerance (act three of ADR-006: soft conservation is not a constraint) — and a flagged repo-extension route-decode projects the raw flows onto the per-OD scaled-simplex product over implicit-ue’s column-generated routes, earning a real certified gap. Honest held-out (scoped in-family): implicit-ue-nn’s learned-cost fixed point certifies a better gap than the GNN-regression+projection at matched route sets, and a converged solver beats both. Anchors: A2 raw-censored + decoded-feasible, A4 permutation equivariance 1e-8, decode-as-projection + no-limit-cycle, in-family loss reduction + conservation ablation.

  • [x] Xu et al. (2024) — A unified dataset for the city-scale traffic assignment model in 20 U.S. cities (data/scenario) — shipped as the cross-domain axis (ADR-033): 17 of 20 real US-city instances integrated download-on-demand (HTTP byte-range extraction of only the per-city AequilibraE trio from the CC-BY figshare zip; never vendored, per-file SHA-256), with Honolulu + San Francisco as CI-sized rungs. Shipped AS-PUBLISHED with the dataset’s wrong-centroid defect documented (demand injected at node ids 1..Z, not the tract centroids — the 3 excluded cities are named); the published AequilibraE flows are a loose reference (own gap ~1e-3), never a best-known oracle, and cross-solver TransCAD agreement is not claimed (the repo’s own bfw gives cross-implementation agreement instead: Honolulu rgap 1.07e-4, correlation 0.99992).

Data, estimation & benchmarking — v1 (T2 estimation track)

  • [x] Van Zuylen & Willumsen (1980) — The most likely trip matrix estimated from traffic counts (white-box solver) — shipped in v1 (T2 entropy estimator (vzw-entropy, ADR-002))

  • [x] Cascetta (1984) — Estimation of trip matrices from traffic counts and survey data: A generalized least squares estimator (white-box solver) — shipped in v1 (T2 GLS estimator (gls, ADR-002))

  • [x] Spiess (1990) — A gradient approach for the O-D matrix adjustment problem (white-box solver) — shipped in v1 (T2 gradient OD adjustment (spiess, ADR-002))

  • [x] Spall (1992) — Multivariate stochastic approximation using a simultaneous perturbation gradient approximation (white-box solver) — shipped in v1 (T2 SPSA calibration baseline (spsa, ADR-002))

  • [x] Yang et al. (1992) — Estimation of origin-destination matrices from link traffic counts on congested networks (white-box solver) — shipped as od-congested

  • [x] Cascetta et al. (1993) — Dynamic Estimators of Origin-Destination Matrices Using Traffic Counts (white-box solver) — shipped as od-dynamic-sim / od-dynamic-seq (adr-023, the within-day time-sliced OD estimator — the third leg of the T2 temporal triangle, distinct from gls (time = replication) and od-kalman (time = day-to-day noise): the estimand is the (H, Z, Z) departure-slice profile, recovered from time-sliced link counts linked by a frozen exogenous free-flow two-interval-split lag map M[l] (congestion feedback out of scope, cascetta2001fixed), via the paper’s SIMULTANEOUS (all slices jointly, efficient) and SEQUENTIAL (slice-by-slice, earlier estimates frozen, online-capable but provably less efficient) GLS pair; a bfw-free EXACT linear certifier regenerates the full-network map from the hashed recipe and scores per-interval obs/held-out count RMSE (ranking = heldout_count_rmse) with descriptive OD/profile columns and an exact stacked-map identifiability report whose new edges are horizon truncation and cross-slice temporal confounding — the latter a genuinely new false-accept surface because held-out sensors share the lag structure; five hand-derived anchors including the fractional-lag instance where simultaneous strictly dominates sequential (128/35, 142/35) vs (16/5, 94/25) against truth (4,6) and a mean-collapse witness proving distinctness from gls; additive, golden Braess hash cf00f411… byte-identical)

  • [x] Balakrishna et al. (2007) — Offline calibration of dynamic traffic assignment: Simultaneous demand-and-supply estimation (black-box wrapper) — shipped as spsa-sumo (adr-028, the first guarded T2 estimator: a SumoSPSAEstimator(SPSAEstimator) whose inner assignment oracle is the shipped sumo-marouter adapter (adr-027) — a subprocess production engine, not the repo’s own MSA — making the black-box simulator-in-the-loop calibration loop REAL and certified through the UNCHANGED pinned-bfw certifier (P1, zero task/runner/certifier changes; the certifier recomputes count-fit from the emitted OD regardless of which simulator produced it). Scope is demand-only on the unchanged EstimationTask: the paper’s JOINT demand+supply title contribution is honestly not shipped (it changes what truth is, needs a new emitted artifact + certificate surface — an entire task-family ADR of its own), and the “DTA” of the title is the paper’s setting (marouter is static, the within-day duaIterate analogue deferred; counts only, not speeds). marouter exposes no shortest-path count, so sp_calls is DISCLOSED as 0 via a _sp_cost_per_eval() hook (the fabricated-sp_calls trap) and an sp_calls-only budget is refused up front; one wall deadline threads all 2I+1 inner solves (a mid-loop engine RuntimeError aborts — crash discipline, never feasible=0); the P1 self-vs-certified honesty diff is reframed as the MEASURED simulator-in-the-loop bias (SPSA descends marouter’s mapped law, the certificate re-assigns under the declared BPR — the same ORDER as the ~1.7e-4/5.4e-4 mapping floor, not a hard bound), never estimator dishonesty. Demand is box-projected in BOTH the thesis’s evaluation step (parent-loop _project, so emitted==evaluated==in-box: the P1 fix a three-lens review confirmed) and the iterate step (_project_log, no frozen corner), via identity hooks that leave the spsa row byte-identical. 13 two-route-only tests (pinned-seed clean-count recovery with a loose improves-on-prior bound, a poisson negative-control disclosing that anchor’s noise fragility, delegated power/toll refusals, bit-reproducibility + macrorep divergence, wall-kill, the box-binding regression that fails under a clip-removal mutation, sparse checkpointing); spsa.py gains three behavior-identical hooks, cli.py passes T2 iterations/wall_seconds through; additive, golden Braess hash cf00f411… byte-identical). The JOINT demand+supply title contribution is DEFERRED on a measured NEGATIVE — ADR-043, an ADR-only measured-deferral / under-identifiability record (the adr-030 precedent) on the BO4Mob D2 track: a sprint that set out to design+validate a separated-evidence joint certificate found, and independently reproduced, that the joint (demand, supply) estimand is UNDER-IDENTIFIED from counts+speeds. On congested 3junction the naive “supply→speed, demand→counts” physical separation is REFUTED (every meso knob moves counts — tauff rel-L2 0.47; a demand error moves speeds ~2 mph mean / ~25 mph max), so BOTH observables are moved by BOTH estimands. The decisive reverse launder: a substantially wrong supply (tauff=0.90, ~20% off) with tuned demand (od=0.95) fits both channels to max(count,speed)=0.0522 (control at true OD/default supply reproduces max=0.0000) — a third of the 0.155 an earlier draft mis-read as an “irreducible margin” over the supply axis alone (RETRACTED: that 0.155 was a single 1-D slice, not the estimator’s (OD,supply) move set). “Report both NRMSE channels, never combine” is thus necessary but NOT sufficient — a low pair does not imply correct demand OR correct supply, and heldout_speed_nrmse is a jointly-observed speed-fit column, not separated supply evidence. The scored row is DEFERRED (not authorized); the named unblocker is supply evidence taken where demand does not leak into speed — off-peak/uncongested-window speeds, a free-flow-speed measurement, or a supply-known controlled sub-instance — each UNMEASURED, requiring its own pilot. The design SUBSTRATE (composition/type-gate task, two-channel non-combining certifier, mandatory supply_bounds, the dead-speed-path port, the swept-supply determinism result) is PRESERVED as what an unblocked row would build on, but is insufficient alone; sim→real is a hypothesis (engine drift + PeMS noise could make laundering EASIER). All numbers 3junction/seed-0 only, not generalized; dual-benchmark R8/forbidden-clause carried)

  • [x] Stabler et al. (2016) — Transportation Networks for Research (data/scenario) — shipped in v0.x (checksummed TNTP fetcher + 4 registered networks)

  • [x] Eckman et al. (2023) — SimOpt: A testbed for simulation-optimization experiments (metric/protocol) — shipped as experiments.profiles (adr-032, the SimOpt diagnostics layer: progress curves, α-solve-time cdf/quantile solvability profiles, Moré-Wild data profiles, difference profiles, functional bootstrap bands, and a certified profiles.json artifact — pure post-hoc arithmetic over already-certified rows, redeeming the P5/P6 progress-curve/solvability-profile promise with zero changes to any solver/certifier/runner. The machinery is defined in the companion Eckman et al. (2023) “Diagnostic Tools” (IJoC 35(2):350-367) and Moré & Wild (2009); strict-< crossing, censored-in-denominator cdfs, the SimOpt-exact exclusive β-quantile (checked against statistics.quantiles, with a censoring-robust opt-in), inf-honest quantiles/bands/differences, the full-cross-design refusal for incongruent model sets, and the braess {msa:5, fw:24, bfw:4} α-solve anchor are pinned by ~48 closed-form tests; golden Braess hash byte-identical)

  • [x] Ryu et al. (2025) — BO4Mob: Bayesian Optimization Benchmarks for High-Dimensional Urban Mobility Problem (data/scenario) — stage 1 shipped as the BO4Mob scenario family (ADR-034): the lab’s OWN NeurIPS-2025 D&B benchmark (UMN-Choi-Lab/BO4Mob, MIT) — five San Jose freeway OD-estimation instances scored by NRMSE of mesoscopic-SUMO counts vs real Caltrans PeMS data, integrated as scenarios/data only under a central dual-benchmark honesty contract (never validation of TABench methods; the paper’s numbers never claimed reproduced — the shipped eclipse-sumo 1.27.1 wheel drifts from the paper’s SUMO 1.12, a MEASURED edgeData schema change where meso drops nVehContrib but BO4Mob’s own arrived+left convention still holds, so the instances transfer and the values do not). Stage 1 = data availability + pipeline liveness only: a P9 commit-pinned per-file-SHA-256 fetcher for the four small instances (1ramp/2corridor/3junction/4smallRegion, < 1.2 MB of single-evaluation bundles) on a SEPARATE registry never in the CI-prefetched REGISTRY, with 5fullRegion (10,100 OD pairs, 74 MB, ~11 h/eval) registered metadata-only and refusing to fetch (a named HPC-only refusal); the pandas-free BO4Mob count/NRMSE transforms; and a guarded sumo-extra smoke test running od2trips + mesoscopic SUMO end-to-end on 1ramp (measured NRMSE 2.4325 with the load-bearing od_end_time OD-window fill, byte-identical across seeds 0/1/2, ~0.41 s/run — pinned LOOSE, band 1.5–3.5, as engine-drift provenance, NOT a paper number). BO4Mob keys are NOT load_scenario scenarios (a meso net with no BPR network and no true OD — data, never a Scenario); NO task/certificate/estimator (the bo4mob_estimation T2 family with a pinned-engine held-out-date observational certificate is a NAMED stage-2 follow-up). Additive, no new dependency/CI job, golden Braess hash cf00f411… byte-identical. Stage 2 shipped as the bo4mob-estimation T2 family (ADR-041): a NEW T2 sibling family (the ADR-023 pattern, NOT a guarded estimator — EstimationTask/ODCertifier/run_estimation_experiment all hard-require a BPR network + true OD + bfw pin BO4Mob structurally lacks) scored by a D2 OBSERVATIONAL certificate — the harness re-runs the pinned eclipse-sumo 1.27.1 od2trips+meso pipeline ONCE on the EMITTED OD and scores heldout_nrmse (the ranking column: the MEAN of BO4Mob’s count NRMSE over 13 same-hour-window 06-07, different-DATE held-out real PeMS dates 221009–221021; TRAIN = the anchor 221008), equilibrium NEVER claimed (no true OD, no BPR, no bfw). Held-out is a SEPARATE checksummed on-demand panel (52 new SHA-256 pins) whose bytes/dates NEVER enter the task — only their heldout_digest does (P7). Reuses assert_engine_pin (RAISES on engine drift) + the adr-027/029 subprocess discipline verbatim; deliberately does NOT reuse EDOC-1’s EdocEvaluator/G1 (no per-agent self-report — a category-error boundary). Demand-only; identifiability is provenance-only (no declared assignment for Hazelton’s rank test). Rides the EXISTING sumo CI job (1ramp full certify + 2corridor/3junction liveness, ~24 s; 4smallRegion opt-in). Same dual-benchmark honesty contract on every surface (extended forbidden clause 3: does NOT reproduce BO4Mob’s own SPSA/BO leaderboard rankings)

The tier-1 rows are HAND-MAINTAINED: each is flipped to [x] with its shipped annotation when its method ships. tools/generate_references.py regenerates this skeleton from the verified canon references.json and carries the SHIPPED dict forward — every shipped bibkey MUST stay in SHIPPED, or a regen would uncheck its row. Use the generator to add NEW canon entries; do not let it overwrite the hand-written shipped prose.