Examples

The repository includes ten examples. Six are self-contained, three build model inputs from hash-pinned external sources, and one preserves an inconsistent empirical baseline as a validation diagnostic. All use the public API and versioned TOML schema.

Replace decompose ... above with julia --project=. bin/tnw.jl decompose ... at the repository root. The self-contained examples ordinarily finish in under a minute after Julia has precompiled the package. Runtime depends on Julia version and hardware.

Self-contained generic examples

The three-location toy is the smallest complete input contract. Road is available on every reciprocal link, rail is available on two links, and rail loads explicit endpoint terminals. Hand-written positive activity and edge-mode value shares make it possible to inspect every input directly. The example exercises parsing, normalization, mode ordering, edge and terminal congestion, policy units, decomposition, and sensitivity paths.

grid_multimodal is generated by build_inputs.jl. Reciprocal roads connect adjacent locations on a five-by-five lattice, while transit operates on the four links along the middle row. The generator writes symmetric directional flows and positive activity that satisfy the recursive accounting identities without estimator-side balancing. This is the practitioner guide's worked example.

Braess-style network

The Braess-style example has two parallel routes and a connector. It produces a nonzero route wedge by comparing flexible routing with the FR closure that holds baseline physical-edge use fixed. It is not a Wardrop assignment and does not claim to reproduce Braess's paradox.

Urban commuting

urban_toy is the self-contained one-mode Allen–Arkolakis regression fixture. Its node file records separate residence and workplace masses, and its edge file records model-consistent commuter traffic. The efficient limit reproduces the commuter-traffic welfare statistic, while the exact-hat solver supplies an independent finite-difference check.

urban_multimodal adds road and transit on every directed edge, alternative routes, road-edge congestion, and transit-terminal congestion. Residence, workplace, OD, and edge-mode flows are generated from one contractive route kernel. The example checks that the economic-geography and urban models use the same route, mode, congestion, and pass-through operators.

seattle_urban diagnoses the published 217-location Seattle inputs after verifying their hashes. seattle_multimodal constructs a separate candidate from LODES commuters, ACS commute-mode shares, and historical GTFS service. The Seattle sources remain external to Git.

Sioux Falls

Sioux Falls is the standard small transportation benchmark: 24 nodes, 76 directed arcs, and 38 reciprocal physical links. The builder pins the upstream TransportationNetworks commit and four file hashes. The source files are not redistributed because their terms limit use to academic research.

julia --project=. examples/sioux_falls/prepare.jl
julia --project=. bin/tnw.jl validate examples/sioux_falls/config_extended.toml
julia --project=. bin/tnw.jl decompose examples/sioux_falls/config_extended.toml

The published OD and assigned-flow files have small, matching node imbalances. The builder averages production with attraction and reciprocal link flows, records the raw imbalances, and verifies exact accounting after balancing. It then computes each link's local BPR log elasticity. This imports an assigned baseline into the package's recursive-routing model; it does not re-solve the original Wardrop problem.

Cow network

The cow-shaped example uses original deterministic three-dimensional node geometry. Alternative neck routes connect a high-activity head and body. Its traffic-only and extended top-five rankings differ, and the exact route and congestion channels explain the change. The plotting script can add either an original procedural surface or a hash-verified, on-demand PLY mesh behind the network. The third-party mesh is not distributed with the repository.

Render any example from validated CSV outputs:

python examples/cow/prepare_surface.py
python plots/network_example.py \
  examples/cow/data/nodes.csv examples/cow/data/edge_modes.csv \
  examples/cow/output/decomposition_physical.csv examples/cow/output/cow.pdf \
  --metric primitive_F --label-top 5 --transparent \
  --three-dimensional --surface-ply examples/cow/assets/cow.ply \
  --elevation-angle 14 --azimuth -70

The plotting script writes PDF or transparent PNG output and adds no title or subtitle. elevation is plotting metadata and does not enter the model. Use --cow-surface in place of --surface-ply ... for the offline procedural fallback.

All 2,903 mesh vertices

An optional larger variant makes every PLY vertex a model location and every mesh edge a bidirectional road link. The generated baseline has 2,903 locations, 8,706 physical links, and 17,412 directed arcs. Positive body/head activity weights provide labor and income. Symmetric matrix scaling constructs balanced value flows with a common traffic-to-income ratio.

python examples/cow/prepare_surface.py
julia --project=. examples/cow/build_mesh_network.jl
julia --project=. bin/tnw.jl analyze-edge-local \
  examples/cow/config_mesh_edge_local.toml

The sparse edge-local command computes the primitive-cost spatial-equilibrium derivative for every link. It does not report the route-consistent realized- friction diagnostic or build the FM and FR closures: the dense OD-by-edge incidence matrix would occupy about 1.09 TiB. The generated baseline is a calibrated sufficient-statistic equilibrium rather than a global level solution from exogenous productivity and amenity primitives.

Seattle urban commuting

The 217-location Seattle exercise in Allen and Arkolakis combines 2017 LODES residence/workplace data with 2016 HPMS/HERE road inputs. It contains no route-level public-transit network or ridership input. The hash-verified seattle_urban adapter preserves those inputs as a diagnostic, but it fails the strict recursive-flow accounting gate because AADT and LODES measure different traffic populations.

The seattle_multimodal adapter instead routes the same LODES commuter matrix over road and transit networks. Origin transit shares come from 2017 ACS table B08301, while the exact June 2017 King County GTFS version supplies service, mode labels, and paths. This construction passes the accounting gate by design. It is a candidate model rather than a reproduction: GTFS does not contain ridership, ACS does not identify routes, and the modal elasticity must be supplied explicitly. The builder records transit-path failures, source and output hashes, and all transformations. See its README and Urban commuting model for the data contract and model boundary.

The exact-2017 workflow has a credential-safe acquisition command and produces separate road, bus, rail/streetcar, and ferry policy configurations. The baseline uses ChoiceLogsum(1.099), transferred from the economic-geography application and labeled as such rather than as a Seattle estimate. It evaluates one-percent edge-mode improvements, reciprocal corridor sums, and coordinated GTFS route-corridor bundles. The public Mobility Database copy of the exact June 2017 TransitFeeds archive is hash-pinned; current service is never substituted for that feed.

The artifact builder also produces Allen–Arkolakis-style maps of the observed and constructed networks, mode-specific welfare effects on a common scale, and traditional versus extended transit effects. These maps use the full 2017 GTFS shape geometry for the observed network and the model's edge-mode support for the constructed network.

Westeros economic geography

The Westeros example uses the locations, roads, and continent polygon in CreativeCarto's public Game of Thrones ArcGIS map. The ArcGIS layers provide geography and location types, but not labor, income, trade, or traffic. All economic quantities in the example are therefore synthetic. The construction is intended to show how a user can turn a geographic network into model-ready inputs, not to estimate the economy of Westeros.

Geography and the model network

The builder converts the source road polylines into an undirected graph whose edge lengths are geographic distances. It joins road components separated by at most 10 km and retains the largest resulting component. A mapped location enters the economic model if its type appears in the table below, it lies inside the Westeros polygon, and it is within 50 km of the retained road network.

The model does not use all road-polyline vertices as economic locations. Instead, it calculates shortest-road distances between the selected settlements. Each settlement is joined to its three nearest neighbors by that distance, after which the shortest additional links needed for connectivity are added. With the pinned source files and default settings, this procedure produces 105 locations, 213 reciprocal physical links, and 426 directed road arcs. The plotted geometry follows the underlying source roads, even though the model is solved on this reduced settlement network.

Labor and income

Let $w_i$ denote the weight assigned to settlement $i$'s ArcGIS location type. The default weights are:

The builder normalizes these weights to obtain a common activity share,

\[a_i=\frac{w_i}{\sum_h w_h}.\]

It then sets both model margins to that share:

\[\frac{L_i}{\bar L}=a_i, \qquad \frac{Y_i}{Y^W}=a_i.\]

Thus labor and income are identical in nodes.csv, each sums to one, and settlements of the same type receive the same baseline share. The example imposes this equality; it does not estimate local productivity, amenities, wages, or population.

Bilateral value flows and edge traffic

The same activity shares are used as the origin and destination margins of a doubly constrained gravity calculation. Let $d_{ij}$ be the shortest-road distance between settlements and let $\widetilde d$ be the median positive bilateral distance. The default gravity kernel is

\[g_{ij}= \begin{cases} 3, & i=j,\\ \exp\left(-3d_{ij}/\widetilde d\right), & i\ne j. \end{cases}\]

Iterative proportional fitting selects row and column factors $r_i$ and $c_j$ so that

\[X_{ij}=r_i g_{ij}c_j, \qquad \sum_j X_{ij}=a_i, \qquad \sum_i X_{ij}=a_j.\]

The kernel is symmetric and the two margins are equal, so the balanced matrix is symmetric up to numerical precision. $X_{ij}$ is a synthetic bilateral value-flow share. The diagonal $X_{ii}$ is local absorption and does not use the road network.

For each $i\ne j$, the builder sends $X_{ij}$ along a shortest path $p_{ij}$ on the reduced settlement graph. Directed edge traffic is therefore

\[\Xi_{uv} =\sum_{i\ne j}X_{ij}\, \mathbf 1\{(u,v)\in p_{ij}\}.\]

Because bilateral flows and routes are symmetric, the two directions of every physical link carry the same baseline value flow. The flow column in edge_modes.csv records $\Xi_{uv}$ as a share of world income; it is not a vehicle count. Its sum across links can exceed one because a shipment is counted on every edge it traverses. The builder verifies both trade margins and node-level flow conservation before writing the files.

Model and policy experiment

The generated configuration uses the economic-geography model with $(\alpha,\beta,\sigma,\eta)=(0.10,-0.30,9,1.099)$, one active road mode, and an edge-local road-congestion elasticity of 0.092. With one mode, the modal logsum is present but has no substitution margin. The policy experiment lowers the primitive transport cost by one percent in both directions of each physical link, one link at a time. Distances determine the synthetic network and baseline flows; the sufficient-statistic calculation then uses the resulting income, labor, and traffic shares rather than treating distance as an additional model input.

python3 examples/westeros/prepare.py
julia --project=. bin/tnw.jl validate examples/westeros/generated/config.toml
julia --project=. bin/tnw.jl decompose examples/westeros/generated/config.toml
julia --project=. examples/westeros/verify.jl
python3 examples/westeros/plot.py

The source responses are hash-pinned but remain outside Git because the ArcGIS item does not list a reuse license. The exact source URLs and hashes are in examples/westeros/sources.toml; the generated network_summary.json records the selected thresholds, gravity parameters, network counts, and accounting errors.