TABenchmark

A shared benchmark for 50 years of traffic assignment models. One harness runs everything from Frank–Wolfe (1975) and bush-based equilibrium solvers to external simulators and learned GNN surrogates on identical networks, demand, data availability, and budgets — and the harness, never the model, recomputes every scored metric from the link flows a model emits.

This site renders the project documentation and the tutorial notebooks, executed at build (except the engine-gated torch/sumo/dtalite pages, which render un-executed). Start with the README for orientation and the repository map, walk the tutorials in order (simple → complex), and consult the architecture and model compendium for depth.

Overview

• TABenchmark
• TABenchmark Architecture
• The TABenchmark Model Compendium
• Numerical Validation
• Implementation Roadmap
• The TABenchmark Reference Canon
• Contributing to TABenchmark

Tutorials

• TABenchmark tutorials
• aon — All-or-nothing assignment on the Braess network
• msa — Method of successive averages (MSA) on the Braess network
• fw — Frank–Wolfe (LeBlanc et al. 1975) on the Braess network
• cfw — Conjugate Frank–Wolfe (Mitradjieva & Lindberg 2013) on the Braess network
• bfw — Bi-conjugate Frank–Wolfe on the Braess network
• gp — Gradient projection (Jayakrishnan et al. 1994) on the Braess network
• oba — Origin-based assignment (Bar-Gera 2002) on the Braess network
• algb — Algorithm B (Dial 2006) on the Braess network
• tapas — TAPAS — traffic assignment by paired alternative segments (Bar-Gera 2010) on the Braess network
• sue-msa — Logit stochastic user equilibrium by MSA on the two-route network
• sue-probit-msa — Probit SUE by MSA, certified by pinned Monte Carlo
• so-bfw — System optimum by bi-conjugate Frank–Wolfe on the Braess network
• fw-elastic — Elastic-demand user equilibrium (Florian & Nguyen 1974)
• evans — Combined trip distribution + assignment (Evans 1976)
• br-ue — Boundedly-rational user equilibrium (Mahmassani & Chang 1987)
• sc-tap — Side-constrained (capacitated) user equilibrium (Larsson & Patriksson 1995)
• vi-asym — Asymmetric variational-inequality UE (Dafermos 1980 / Smith 1979)
• multiclass — Multiclass-user equilibrium (Dafermos 1972)
• learned-surrogate — A learned UE surrogate, and how the harness CENSORS it
• dtd-swap — Smith’s (1984) route-swap day-to-day dynamics
• dtd-swap-sue — Smith & Watling’s (2016) route-swap SUE dynamics
• dtd-link — He, Guo & Liu’s (2010) link-based day-to-day dynamics
• dtd-friesz — Friesz et al.’s (1994) route-based projected dynamical system
• dtd-horowitz — Horowitz’s (1984) cost-smoothing SUE dynamics
• dtd-stochastic — Cascetta’s (1989) stochastic-process day-to-day model
• dtd-unifying — Cantarella & Cascetta’s (1995) unifying day-to-day process
• dtd-cumlog — Li, Wang & Nie’s (2024) cumulative-logit day-to-day dynamics
• gls — Generalized Least Squares OD estimation (covers prior)
• spiess — Spiess’s (1990) count-misfit-only OD estimation
• vzw-entropy — Van Zuylen & Willumsen’s (1980) entropy-balancing OD estimation
• od-congested — Yang, Sasaki, Iida & Asakura’s (1992) bilevel OD estimation
• spsa — Spall’s (1992) simultaneous perturbation stochastic approximation
• od-kalman — Davis & Nihan’s (1993) linear-Gaussian OD estimation
• od-dynamic — Cascetta, Inaudi & Marquis’s (1993) within-day dynamic OD estimation
• bo4mob-estimation — BO4Mob held-out-count OD estimation (D2 observational)
• odme-dtalite — DTALite’s static ODME as one more guarded T2 estimator (Zhou & Taylor 2014)
• transit-strategy — Spiess & Florian’s (1989) optimal strategies
• ctm — Daganzo’s (1994, 1995) Cell Transmission Model
• ltm — Yperman’s (2007) Link Transmission Model
• godunov — Lebacque’s (1996) Godunov scheme + the Greenshields FD
• node-model — Tampere et al.’s (2011) generic first-order node model
• vickrey — Vickrey’s (1969) single-bottleneck departure-time equilibrium
• vi-due — Friesz et al.’s (1993) variational-inequality dynamic user equilibrium
• merchant-nemhauser — Merchant & Nemhauser’s (1978) exit-function SO-DTA
• lp-so-dta — Ziliaskopoulos’s (2000) LP single-destination SO-DTA on CTM cells
• pm-td — Peeta & Mahmassani’s (1995) time-dependent UE and SO
• newell-3det — Newell’s (1993) interior kinematic-wave reconstruction
• implicit-ue-nn — user equilibrium as an implicit layer (act two)
• het-gnn — heterogeneous-GNN traffic assignment (act three)
• sumo-marouter — SUMO’s macroscopic assignment as an external-simulator adapter
• sumo-duaiterate — the first external-dynamic (EDOC-1) row
• dtalite-tap — DTALite’s static Frank-Wolfe, an IDENTITY compile map
• spsa-sumo — SPSA calibration against a production simulator (Balakrishna 2007)
• matsim — the first agent-based, stochastic-track EDOC row
• dtalite-simulation — the third EDOC row, the first DETERMINISTIC-track external engine
• xu2024 — the 20-US-city cross-domain axis (Honolulu / San Francisco)
• bo4mob — the BO4Mob San Jose freeway instances (stage 1: data + liveness)
• profiles — SimOpt-style progress curves and solvability profiles

API reference

• API reference
  • tabench.core
  • tabench.models
  • tabench.metrics
  • tabench.estimation
  • tabench.edoc

Design records (ADRs)

• ADR-001 — Logit SUE: Dial’s STOCH loading, MSA-SUE, and the fixed-point certificate
• ADR-002 — T2 estimation track: OD demand from link counts, and the pinned-assignment certificate
• ADR-003 — Probit SUE: Monte Carlo fixed-point certificate with a pinned evaluation stream
• ADR-004 — Route-flow proportionality: a diagnostic now, a scored certificate proposed
• ADR-005 — Elastic (variable) demand: a new problem class with a P1-pure certificate
• ADR-006 — Learned (black-box) models: certified by P1, gated by lineage
• ADR-007 — Combined trip distribution + assignment (Evans 1976): a P1-pure certificate
• ADR-008 — Boundedly-rational user equilibrium: a band-relaxed UE with a necessary link-flow certificate
• ADR-009 — Side-constrained UE: hard link capacities with a link-visible feasibility certificate
• ADR-010: dnl-core — generic supply/demand dynamic-network-loading foundation
• ADR-011: vi-asym — asymmetric variational-inequality UE (non-separable costs)
• ADR-012: od-kalman — Davis & Nihan (1993) linear-Gaussian OD estimation from a time series of link counts
• ADR-013: multiclass — Dafermos (1972) multiclass-user equilibrium
• ADR-014: transit-strategy — Spiess & Florian (1989) optimal-strategy transit assignment
• ADR-015: ctm — Daganzo (1994/1995) cell transmission model link
• ADR-016: ltm — Yperman (2007) link transmission model
• ADR-017: node-model — Tampère et al. (2011) generic first-order node model
• ADR-018: godunov — Lebacque (1996) Godunov scheme + the first non-triangular FD
• ADR-019: vickrey — Vickrey (1969) single-bottleneck departure-time equilibrium
• ADR-020: merchant-nemhauser — Merchant & Nemhauser (1978) exit-function SO-DTA
• ADR-021: lp-so-dta — Ziliaskopoulos (2000) LP single-destination SO-DTA on CTM cells
• ADR-022: vi-due — Friesz et al. (1993) VI dynamic user equilibrium
• ADR-023: od-dynamic — Cascetta, Inaudi & Marquis (1993) within-day dynamic OD estimation
• ADR-024: newell-3det — Newell (1993) three-detector interior reconstruction
• ADR-025 — Implicit-NN user equilibrium: the first torch model, feasibility as architecture
• ADR-026 — Heterogeneous-GNN traffic assignment: the third learned model, feasibility as a decode
• ADR-027 — SUMO marouter: the first external-simulator adapter, and the simulator-to-benchmark model gap
• ADR-028 — spsa-sumo: SPSA calibration against a production simulator, as one more estimator row
• ADR-029 — DTALite assignment(): the second external engine, and the identity-map static-UE row
• ADR-030 — MATSim / DynaMIT / DYNASMART adapters: measured deferral, and the ADR that unblocks them
• ADR-031: pm-td-ue / pm-td-so — Peeta & Mahmassani (1995) time-dependent SO/UE
• ADR-032: simopt-profiles — SimOpt-style progress curves and solvability profiles
• ADR-033: xu2024-dataset — the Xu et al. (2024) 20-US-city cross-domain axis
• ADR-034: bo4mob-scenarios — the BO4Mob San Jose freeway OD-estimation instances (stage 1)
• ADR-035: tutorials-visualizer — the house visualizer and the per-unit tutorial notebooks
• ADR-036: edoc-1 — the external-dynamic-engine observational certificate
• ADR-037 — sumo-duaiterate: the first EDOC-1 row, and the shipped external-dynamic substrate
• ADR-038 — Cumulative-logit day-to-day dynamics: boundedly-rational logit choice with an exact-Wardrop-UE limit
• ADR-039 — matsim: the second EDOC-1 row, the first agent-based / first stochastic-track external engine
• ADR-040 — dtalite-simulation: the third EDOC-1 row, the first deterministic-track external engine, closing the adr-029 honest-sourcing loop
• ADR-041 — bo4mob-estimation: the BO4Mob held-out-count OD-estimation family (stage 2), a D2 observational T2 certificate
• ADR-042 — odme-dtalite: DTALite’s static ODME as one more guarded T2 estimator row
• ADR-043 — bo4mob-joint-estimation: the joint (demand, supply) estimand is under-identified from counts+speeds — a measured deferral
• TABenchmark Angle A: A Scenario × Model Cross-Evaluation Matrix with SimOpt-Style Experiment Machinery
• TABenchmark — Angle A: The Scenario × Model Matrix
• TABenchmark: An Observability-First Benchmark for 50 Years of Traffic Assignment Models
• TABenchmark — Angle B: Observability-First Design
• TABenchmark Design Proposal — Contract/Plugin-First Extensibility (Angle C)
• TABenchmark: Contract-First Design Proposal (Angle C)