Benchmark datasets#

tfm.datasets provides published benchmark problem instances with known reference solutions, for validating and benchmarking routing and assignment methods. Small instances are vendored with the package; larger ones are downloaded on first use, verified against checksums, and cached in $TFM_CACHE_DIR (default ~/.cache/transport-flow-model).

>>> from transport_flow_model import datasets
>>> datasets.available()
['anaheim', 'barcelona', 'chicago-sketch', 'siouxfalls', 'usa-20-cities']

TNTP instances#

The Transportation Networks for Research repository publishes classic traffic assignment instances in TNTP format, each with best-known user-equilibrium link flows:

Name

Zones

Nodes

Links

License / provenance

siouxfalls

24

24

76

Open research data, TransportationNetworks/SiouxFalls (vendored with the package)

anaheim

38

416

914

Open research data, TransportationNetworks/Anaheim

barcelona

110

1020

2522

Open research data, TransportationNetworks/Barcelona

chicago-sketch

387

933

2950

Open research data, TransportationNetworks/Chicago-Sketch

Data are donated to the repository and provided as-is for research use; cite the repository (Transportation Networks for Research Core Team) when publishing results.

Load an instance as Network and OD objects with load_tntp():

>>> instance = datasets.load_tntp("siouxfalls")
>>> instance.n_zones, instance.n_nodes, instance.n_links
(24, 24, 76)
>>> network = instance.network.to_dataframe()
>>> list(network.columns)
['edge_from', 'edge_to', 'edge_id', 'capacity', 'cost', 'alpha', 'beta', 'length', 'speed', 'toll', 'link_type']
>>> float(instance.od.to_dataframe()["flow"].sum())
360600.0

cost is the link free-flow time; alpha and beta are the BPR volume-delay parameters, so the congested link cost at flow x is cost * (1 + alpha * (x / capacity)**beta).

Reading TNTP files directly#

tfm.io.read_tntp() reads any pair of _net.tntp / _trips.tntp files (for example from a local clone of the TransportationNetworks repository). It handles the TNTP conventions:

  • 1-based node ids, with zones (demand centroids) numbered first;

  • the <FIRST THRU NODE> convention: nodes below it are centroids that may start or end a trip but must not be routed through. Such centroids are split into an origin-only node (original id) and a destination-only node (original id plus centroid_offset), and OD destinations are remapped to match. Map result node ids back to zone ids with TNTPInstance.zone_ids().

>>> import transport_flow_model as tfm
>>> paths = datasets.fetch("siouxfalls")
>>> instance = tfm.io.read_tntp(paths["net"], paths["trips"])
>>> instance.first_thru_node  # 1: every node may be routed through
1

Reference solutions#

Each TNTP instance ships published best-known equilibrium link flows for use as regression fixtures:

>>> flows = datasets.best_known_flows("siouxfalls")
>>> list(flows.columns)
['edge_from', 'edge_to', 'flow', 'cost']

datasets.BEST_KNOWN records the Beckmann user-equilibrium objective evaluated on those flows (the published link costs are reproduced by the BPR function of each _net.tntp to ~1e-14; chicago-sketch uses generalized cost with an additional 0.04/mile distance term, recorded as distance_cost):

>>> datasets.BEST_KNOWN["siouxfalls"].objective
4231335.28710744

20-city US traffic assignment benchmark#

usa-20-cities fetches the unified and validated traffic dataset for 20 U.S. cities (San Francisco, Seattle, Chicago, New York, …): GMNS-style _link.csv / _node.csv / _od.csv inputs per city plus reference assignment results from TransCAD, AequilibraE and UXsim. It is a single 276 MB zip archive, extracted into the cache on first fetch:

paths = datasets.fetch("usa-20-cities")
paths["dir"]  # extracted root, one directory per city

License: CC BY 4.0. Provenance: figshare. Citation: Xu, X., Zheng, Z., Hu, Z. et al. A unified dataset for the city-scale traffic assignment model in 20 U.S. cities. Sci Data 11, 325 (2024). doi:10.1038/s41597-024-03149-8.