This section describes the data sources, models, and assumptions behind the analysis presented in each dashboard.
pvmt.toml.The exact sources and endpoints used for a given example are listed in that example's Config tab.
Each road classification decays independently via
PCI(t) = PCI₀ · exp(−k · t)
where k is an annual decay constant that depends on the road
classification. Higher-class roads (motorway, trunk, primary) decay more
slowly than lower-class roads (residential, service) because they are
built to thicker, more rigorous design standards and typically receive
more frequent maintenance. Default values are derived from LTPP data
reported in FHWA-RD-01-156, Long-Term Pavement Performance and
ship as part of the forecast package; they are continental-US
averages and do not account for local climate, traffic, or
construction quality. A config may set a per-city decay_rate to tune
for local conditions (e.g. freeze/thaw or road salt); that override is
applied as the rate for a typical road and scales every road class
proportionally, so the per-class ordering (higher classes decay slower)
is preserved rather than flattened. Sidewalks
decay on a separate, slower track and are not treated as a highway class.
Treatment costs are banded by PCI: each band has a representative
$/sq m value, and costs between bands are linearly interpolated at the
tier midpoints, so the cost-versus-PCI curve is smooth rather than
step-shaped. Above the highest anchor (the midpoint of the preventive
tier) and below the lowest anchor (the midpoint of the reconstruction
tier), the cost is clamped to that anchor's value rather than
extrapolated. Default cost tiers are expressed in $/sq m and sourced
from FHWA treatment-selection guidance; they are calibration inputs, not
measurements, and local bid prices will differ. Roads and sidewalks use
independent cost tiers because the treatment economics differ
substantially.
A real network is a distribution of conditions — some segments excellent, some failed — not a single average. Because the cost-versus-PCI curve is non-linear, pricing everything at the network-average PCI under-states the true program cost (the failed/poor tail is disproportionately expensive). To correct this without requiring per-segment condition data the model does not have, PVMT spreads the single configured average PCI into a distribution around that average (a Beta distribution on the 0–100 scale, with the average preserved exactly) and prices each slice separately. The result is a more realistic — and modestly higher — cost than pricing the average alone. This is a deliberately conservative approximation of the real spread; it is applied automatically and moves the solvency dollars in the direction validated against published city data. When field-measured per-segment condition becomes available, it will replace this assumed spread.
Real pavement is maintained on a multi-year cycle: a city treats roughly
one slice of its network each year, not the whole network annually. The
model captures this with a treatment cycle of N years (default 12,
the midpoint of a typical 10–14 year municipal cycle, configurable via
treatment_cycle_years). Each forecast year only 1/N of the network is
scheduled for treatment, so the annual treatment need is the
full-network retreatment cost divided by N. This is what makes the
break-even budget a realistic annual program cost rather than the
one-off cost of rebuilding the entire network at once. A cycle of N = 1
reproduces the older behavior (the whole network priced every year), which
overstated the hold-steady budget several-fold.
The cost level and the cycle length are not independent — the break-even
budget scales as cost ÷ N, so a cheaper cost basis and a shorter cycle
trade off exactly. We anchor the cycle to the physical rate at which a
city actually repaves (lane-miles treated per year, not dollars): for
Berkeley that hold-steady cadence is ≈ 12 years, which is the default. With
the cycle fixed there, the default bare-construction cost tiers reproduce
the city's cited real hold-steady spend (~$5.6 per m² per year), so the
break-even dollars are calibrated to reality rather than chosen freely. See
the validation report for the derivation and the limits of this anchor.
PVMT ships with three comparison runs driven by annual funding level, all using the worst-first allocation strategy (budget is spent on the lowest-PCI segments first):
A do-nothing baseline (no spend, uncontrolled decay) is shown alongside the funded runs for comparison.
The forecast library also implements a preventive-first strategy (prioritize highest-PCI segments that are still in the preservation window), but the default UI comparisons do not exercise it. Preventive vs. worst-first allocation is governed by per-strategy efficiency multipliers; those multipliers are illustrative calibration constants chosen to reflect the direction and sign of the effect reported in FHWA-HIF-12-042, Pavement Preservation: Preserving our Investment — that $1 of preventive maintenance is reported to avoid $6–$10 of future reconstruction — not to reproduce that benefit-cost ratio as a single-year spending efficiency.
Optional compound annual growth applies to pavement area each year:
Area(y) = Area₀ · (1 + g)^y
where g is configured per city (default zero). This lets an example
model a city that is still expanding its street network; it does not
model demolition or removal.
The dashboard's Financials headline and the cross-city leaderboard report three solvency figures. They are computed on the roads/streets cohort only — the aggregate scenarios blend roads, parking, and sidewalks but cost the blend at road tiers, which would mis-price sidewalks, so an absolute dollar claim must be roads-only. They are derived from a worst-first run at the city's configured annual budget.
Insolvency year — the first forecast year in which the cumulative
deferred backlog reaches one full treatment cycle of deferred work
(N × the annual scheduled need — a whole network's worth of treatment).
Because the deferred backlog is a monotonically non-decreasing
accumulator (see below), once a city is an entire cycle behind it does
not recover within the model, so this is the "unrecoverable" threshold.
A do-nothing network defers a full slice every year and crosses around
year N; a city funding a fraction f of each slice crosses around
N / (1 − f), so well-funded cities never reach it and are reported as
solvent through the horizon. The metric therefore discriminates among
the genuinely underfunded; on the funded side, funding gap is the
primary signal. Reported only when a current budget is configured.
Hold-steady (break-even) budget — the smallest constant annual budget whose final deferred backlog is within a small relative tolerance (a fraction of the annual need) of zero: the budget that funds the network's annually-scheduled treatment slice and keeps pace with the cycle. Found by bisection over budget; the search's upper bound is the peak do-nothing annual need over the horizon, which is sufficient to fully fund every year.
Funding gap — (break-even − current budget) / current budget,
the primary cross-city ranking metric. Negative when a city already
budgets at or above its hold-steady level. Reported only when a current
budget is configured.
Three caveats apply to these figures specifically:
annual_spend series can exceed the configured budget. The
allocator routes leftover budget on a fully-funded cohort into extra
PCI recovery (a surplus branch), and that extra is counted as spend.
So an annual_spend above current_budget in early years is expected,
not an error.cost_tiers curve that violates this could make
the bisection overstate the break-even budget — a conservative
direction (it never understates the gap).The multi-city Compare view presents two distinct per-city scores:
current_budget / break_even_budget, rendered on a
0–100 scale: 100 = funded to hold the network steady, 50 ≈ needs
twice today's budget, 25 ≈ needs four times. Over-funded cities cap at
100 for display but keep their uncapped coverage as the ranking key, so
the most-surplus city ranks first (a single gold medal); ties break on
the later/absent insolvency year. Computed on roads/streets only and
only for cities with a cited current_budget — cities without one
cannot be scored and are shown N/A, unranked.docs/architecture.md
for the ingest and compute pipeline.# Portland Metro, OR — metric-units regional analysis
#
# Portland and its westside/eastside suburbs have excellent OSM coverage.
# This config renders all output in metric units and uses a moderately
# fine hex grid, with a long 25-year forecast horizon.
#
# Techniques demonstrated:
# - [display].units = "metric" for metric output everywhere.
# - hex_edge_m = 80 (a middle-ground grid resolution).
# - A 25-year forecast horizon.
#
# Overpass-only. Expect ~7 Nominatim + Overpass pulls for `pvmt all ingest`.
config_id = "portland-metro-or"
[display]
units = "metric"
[grid]
hex_edge_m = 80
[forecast]
years = 25
[export]
title = "Portland Metro Pavement Analysis"
[[cities]]
name = "Portland, OR"
#@cite PBOT citywide network PCI 53, Mar 2024 (down from 76 in 2008)
#@cite https://www.portland.gov/transportation/news/2024/3/1/news-release-pbot-launches-two-week-pothole-march-madness-campaign (accessed 2026-06-14)
forecast.initial_pci = 53
#@cite Fixing Our Streets gas-tax, $70.5M over FY2024-28 (4-yr program), annualized; dedicated program, not full PBOT budget
#@cite https://www.portland.gov/transportation/fixing-our-streets/projects-2024-2028 (accessed 2026-06-14)
forecast.current_budget = 17625000.0
overpass = true
[[cities]]
name = "Beaverton, OR"
overpass = true
[[cities]]
name = "Gresham, OR"
overpass = true
[[cities]]
name = "Hillsboro, OR"
#@cite city-maintained roadways average PCI 83, Pavement Management Program
#@cite https://www.hillsboro-oregon.gov/our-city/departments/public-works/transportation/street-and-road-maintenance/pavement-management (accessed 2026-06-14)
forecast.initial_pci = 83
overpass = true
[[cities]]
name = "Tigard, OR"
overpass = true
[[cities]]
name = "Lake Oswego, OR"
#@cite Network PCI 75 (2022), Pavement Mgmt Program statistics 2018-2022
#@cite https://www.ci.oswego.or.us/pavement (accessed 2026-06-14)
forecast.initial_pci = 75
overpass = true
[[cities]]
name = "Milwaukie, OR"
#@cite Street Surface Maintenance Program network-wide PCI 59
#@cite https://www.milwaukieoregon.gov/departments/engineering/programs/street_surface_maintenance_program.php (accessed 2026-06-14)
forecast.initial_pci = 59
overpass = true
[grid]
hex_edge_m = 80.0
[display]
units = "metric"
min_hex_area = 100.0
[export]
title = "Portland Metro Pavement Analysis"
coordinate_decimals = 0
[forecast]
initial_pci = 85.0
decay_rate = 0.035
growth_rate = 0.0
years = 25
treatment_cycle_years = 0.0
[[forecast.cost_tiers]]
min_pci = 70.0
max_pci = 101.0
cost_per_sqm = 5.0
label = "preventive"
[[forecast.cost_tiers]]
min_pci = 40.0
max_pci = 70.0
cost_per_sqm = 50.0
label = "rehab"
[[forecast.cost_tiers]]
min_pci = 0.0
max_pci = 40.0
cost_per_sqm = 150.0
label = "reconstruction"
[[cities]]
name = "Portland, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[cities.forecast]
initial_pci = 53.0
decay_rate = 0.0
growth_rate = 0.0
years = 0
treatment_cycle_years = 0.0
current_budget = 1.7625e+07
[[cities]]
name = "Beaverton, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[[cities]]
name = "Gresham, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[[cities]]
name = "Hillsboro, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[cities.forecast]
initial_pci = 83.0
decay_rate = 0.0
growth_rate = 0.0
years = 0
treatment_cycle_years = 0.0
[[cities]]
name = "Tigard, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[[cities]]
name = "Lake Oswego, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[cities.forecast]
initial_pci = 75.0
decay_rate = 0.0
growth_rate = 0.0
years = 0
treatment_cycle_years = 0.0
[[cities]]
name = "Milwaukie, OR"
overpass = true
arcgis_url = ""
hex_edge_m = 0.0
boundary_relation_id = 0
allow_private_arcgis = false
[cities.forecast]
initial_pci = 59.0
decay_rate = 0.0
growth_rate = 0.0
years = 0
treatment_cycle_years = 0.0