Gravel

Fast road network fragility analysis at scale.

Gravel is a C++ library (with Python bindings) for computing how vulnerable road networks are to edge failures. Given a graph, it answers questions like:

"How isolated does this location become when 10% of its roads fail?"
"Which counties are most dependent on a single critical route?"
"What's the composite fragility score for every US county?"

The library is built around contraction hierarchies for fast shortest-path queries, and a Dijkstra + incremental SSSP pipeline for edge-removal analysis. On a 200K-node county graph, it computes isolation fragility in ~2 seconds.

Installation

pip

pip install gravel-fragility

Binary wheels for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (AMD64) × Python 3.10–3.13. OSM loaders (load_osm_graph, OSMConfig, SpeedProfile) ship enabled on every wheel from v2.2.2 onward — no extra system dependencies required.

conda-forge

Not currently available. The conda-forge feedstock is out of date and does not track recent releases — install via pip (above) for the current version. (If the feedstock is revived, a conda install path will return here.)

From source

git clone https://github.com/rhoekstr/gravel.git
cd gravel
cmake -B build -DGRAVEL_BUILD_PYTHON=ON
cmake --build build -j

The default GRAVEL_USE_OSMIUM=AUTO enables OSM loaders when libosmium is present on the system and disables them gracefully when it isn't. CMake prints a clear status message either way. To hard-require libosmium (fail configure if missing), pass -DGRAVEL_USE_OSMIUM=ON. To opt out entirely, -DGRAVEL_USE_OSMIUM=OFF.

Install libosmium with:

macOS: brew install libosmium protozero
Debian/Ubuntu: sudo apt install libosmium2-dev
conda: conda install -c conda-forge libosmium
vcpkg (Windows): vcpkg install libosmium protozero

Checking OSM availability at runtime

import gravel
if gravel.HAS_OSM:
    graph = gravel.load_osm_graph("county.osm.pbf", gravel.SpeedProfile.car())
else:
    # Running on a build without OSM support (e.g., source build without libosmium).
    raise RuntimeError("gravel was built without OSM support")

Quick Start

Python

import gravel

# Load a road network (from OSM PBF)
graph = gravel.load_osm_graph("county.osm.pbf", gravel.SpeedProfile.car())

# Build contraction hierarchy (one-time cost)
ch = gravel.build_ch(graph)

# Compute isolation fragility for a location
cfg = gravel.LocationFragilityConfig()
cfg.center = gravel.Coord(35.43, -83.45)  # Bryson City, NC
cfg.radius_meters = 30000  # 30km
cfg.monte_carlo_runs = 20

result = gravel.location_fragility(graph, ch, cfg)
print(f"Isolation risk: {result.isolation_risk:.3f}")
print(f"Reachable nodes: {result.reachable_nodes}")
print(f"Directional coverage: {result.directional_coverage:.2f}")

Datasets (2.7.0)

import gravel

# Browse the catalog of supported datasets
gravel.datasets.list()          # -> list[Dataset]
print(gravel.datasets.summary())  # prints (and returns) a feature matrix

# Load a road network via the OSM submodule
graph = gravel.datasets.osm.load("county.osm.pbf")

# Fetch a hazard footprint (needs the gravel[datasets] extra)
gdf, provenance = gravel.datasets.nfhl.fetch(bbox=(-83.6, 35.3, -83.3, 35.6))
print(provenance.summary())  # {dataset_id, endpoint, resolved_version, pulled_at}

The hazard fetchers (nfhl, shakemap, usdm, nri) require the gravel[datasets] extra (geopandas + shapely + pyproj); their edge_probabilities(...) output feeds stochastic_fragility.

Network substrates (2.7.0)

Beyond roads, gravel.datasets onboards five infrastructure networks — power grids, internet router topology, air routes, and transit — each load(...) returning (Graph, capacity) where capacity is a per-edge numpy array (empty when the source has no native capacity). Fragility analyses consume these graphs and their capacity vector, and the (topological) cascade runs on the graph structure, exactly like a road graph.

import gravel

# Power grid (thermal limits in MVA; node coords)
graph, capacity = gravel.datasets.gridsfm.load("case.json")

# Air network via OpenFlights: fetch the raw tables, then load
(airports, routes), prov = gravel.datasets.openflights.fetch("data/")
graph, capacity = gravel.datasets.openflights.load(airports, routes, with_codes=False)

# ...or with IATA codes, to key-join a BTS T-100 seat-capacity overlay
graph, capacity, node_iata = gravel.datasets.openflights.load(airports, routes, with_codes=True)
seats = gravel.datasets.t100.load("t100_segment.csv", value_field="SEATS")
capacity = gravel.datasets.t100.edge_capacity(graph, node_iata, seats)

The network loaders need only numpy; fetchers use stdlib urllib (gridsfm optionally huggingface_hub; gtfs needs a free Transitland API key). caida (internet) and t100 are bring-your-own-data — no fetcher — per their source licenses.

C++

#include <gravel/gravel.h>

auto graph = gravel::load_osm_graph({"county.osm.pbf", gravel::SpeedProfile::car()});
auto ch = gravel::build_ch(*graph);

gravel::LocationFragilityConfig cfg;
cfg.center = {35.43, -83.45};
cfg.radius_meters = 30000;
cfg.monte_carlo_runs = 20;

auto result = gravel::location_fragility(*graph, ch, cfg);
std::cout << "Isolation risk: " << result.isolation_risk << "\n";

Key Features

Sub-library architecture

Seven independent libraries with a strict dependency DAG — link only what you need:

Library	Purpose	Dependencies
`gravel-core`	Graph representation, basic routing	stdlib, OpenMP
`gravel-ch`	Contraction hierarchy + blocked queries	gravel-core
`gravel-simplify`	Graph simplification, bridges	+ gravel-ch
`gravel-fragility`	All fragility analysis (Eigen/Spectra)	+ gravel-simplify
`gravel-geo`	Regions, snapping, point-in-polygon	+ gravel-simplify
`gravel-datasets`	Dataset onboarding: OSM/TIGER loaders + catalog (libosmium)	+ gravel-core, gravel-simplify, gravel-geo
`gravel-us`	US TIGER/Census specializations	+ gravel-geo, gravel-datasets

Analysis modules

Route fragility — per-edge replacement path analysis
Location fragility — isolation risk for a geographic point (new Dijkstra+IncrementalSSSP)
County fragility — composite index combining bridges, connectivity, accessibility, fragility
Scenario fragility — event-conditional analysis (hazard footprints)
Progressive elimination — degradation curve with Monte Carlo / greedy strategies
Tiled analysis — spatial fragility fields for visualization
Region assignment — node-to-polygon mapping (point-in-polygon)
Graph coarsening — collapse regions into meta-nodes
Research depth (2.4.0) — capacity-aware importance (HCM PCE from OSM tags), stochastic fragility (Monte Carlo over per-edge failure probabilities, e.g. floodplain / FEMA-NFHL hazards), and experimental Motter–Lai cascading failure — all as disclosed, sweepable inputs
Visualization (2.5.0) — real per-edge road geometry plus static (plot_fragility), interactive (interactive_map), and animated (animate_failure, self-contained deck.gl HTML) maps via gravel-fragility[viz]
Dataset onboarding (2.6.0) — a unified gravel.datasets layer: a queryable catalog (list()/info()/summary()) plus per-dataset submodules with a consistent interface — osm and tiger loaders, and nfhl/shakemap/usdm/nri hazard overlays whose fetch(...) returns (GeoDataFrame, Provenance) and whose edge_probabilities(...) feeds stochastic_fragility. Hazard fetchers need the gravel[datasets] extra (geopandas + shapely + pyproj)
Network substrates (2.7.0) — five non-road infrastructure networks in gravel.datasets, each load(...) returning (Graph, capacity): gridsfm and opfdata (power grids, capacity in MVA), caida (internet router topology), openflights (air routes), and gtfs (transit, persons/hour capacity), plus the t100 BTS seat-capacity overlay for air graphs. Fragility analyses run on these graphs and their per-edge capacity, and the topological cascade on the graph structure, exactly like a road graph. The catalog now spans 12 datasets; loaders need only numpy
Flow layer (3.0.0, experimental) — gravel.flow, a demand-driven traffic-assignment layer on top of the topological core: stochastic User Equilibrium (BPR congestion + logit route choice), flow_fragility for the region-wide delay cost of a failure (ΔTSTT + stranded demand), and a θ-calibration harness against real closure-induced slowdowns. The solver is exact (Sioux Falls) and recovers a known θ synthetically, but real θ does not identify at corridor scale — it ships experimental, with the gap and the regional-ODME path documented in docs/FLOW_LAYER.md. The gravel.datasets.chicago_traffic adapter and example 10 walk the real-data study. Breaking: the 2.6 deprecation shims (gravel.hazards, top-level load_osm_graph/load_tiger_*) are removed — use gravel.datasets.*

Performance

Measured on an Apple M-series laptop, 10 cores, Release build (2026-07-01; see bench/baselines/routing_performance.md):

Operation	200K-node graph (Swain Co.)	593K-node graph (Buncombe Co.)
OSM PBF load	0.43s	0.96s
CH build	0.78s	3.81s
CH distance query	3.5 µs	7.8 µs
CH route (with path unpacking)	80.5 µs	112.8 µs
Distance matrix cell (OpenMP, 10 threads)	0.6 µs	1.3 µs
Route fragility (per path edge, OpenMP)	~13 ms	~28 ms
Location fragility (MC=20, 50-mi radius)	0.11 s	1.0 s

The parallel kernels (distance matrix, route fragility) scale ~5× from 1→10 threads on this machine. macOS builds only gained working OpenMP in 2.3.0 (Apple Clang needs Homebrew libomp) and route_fragility was parallelized in the same release — so on macOS those two rows are roughly 5–9× faster than pre-2.3.0. Single-threaded operations (load, CH build, point queries) are unchanged. Numbers vary by CPU; the perf_baseline.json Google-Benchmark regression gate is refreshed separately via gravel_perf.

At-scale benchmarks:

National per-county isolation fragility (3,221 counties): 3.1 hours
National inter-county fragility (8,547 adjacent pairs incl. cross-state): ~22 hours

Documentation

REFERENCE.md — complete API reference (all functions, all types)
docs/PRD.md — product requirements and architecture
docs/ — full documentation site (also on GitHub Pages)
examples/ — Python notebooks and C++ sample programs

Example: National US County Analysis

# Run fragility analysis on all ~3,221 US counties
python scripts/national_fragility.py --output-dir output/

# Results are in output/county_isolation_fragility.csv
# Visualize with:
python scripts/visualize_results.py

Sample findings from the national run (April 2026):

Most vulnerable states	Mean risk
New Hampshire	0.638
Maine	0.571
Rhode Island	0.570
Connecticut	0.563

Most resilient states	Mean risk
Kansas	0.146
Nebraska	0.162
Iowa	0.163
North Dakota	0.165

The Great Plains grid-states score lowest — flat land with rectangular road networks have extensive redundancy. Mountain and coastal states score highest — constrained geography forces single-path corridors.

Requirements

Runtime:

C++20 compiler (GCC 11+, Clang 14+, MSVC 2022+)
CMake 3.24+
Python 3.10+ (for bindings)

Optional:

libosmium (for OSM PBF loading)
Apache Arrow (for Parquet output)

Bundled (via CMake FetchContent):

pybind11
Eigen + Spectra
nlohmann/json
Catch2 (tests)

Contributing

See CONTRIBUTING.md. Bug reports and feature requests welcome via GitHub Issues.

License

Apache 2.0 — see LICENSE. Free for commercial and research use.

Citation

If you use Gravel in academic work, please cite:

@software{gravel2026,
  author = {Hoekstra, Robert},
  title = {Gravel: Fast Road Network Fragility Analysis},
  year = {2026},
  url = {https://github.com/rhoekstr/gravel},
  version = {3.0.0}
}

About

Gravel is an Awry Labs project — see the Gravel project page for an overview. Also from Awry Labs: Kindling.

Built by Robert Hoekstra — more projects and writing at awrylabs.com.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gravel_fragility-3.0.0.tar.gz (1.9 MB view details)

Uploaded Jul 14, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

gravel_fragility-3.0.0-cp313-cp313-win_amd64.whl (5.1 MB view details)

Uploaded Jul 14, 2026 CPython 3.13Windows x86-64

gravel_fragility-3.0.0-cp313-cp313-manylinux_2_28_x86_64.whl (5.4 MB view details)

Uploaded Jul 14, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

gravel_fragility-3.0.0-cp313-cp313-manylinux_2_28_aarch64.whl (4.9 MB view details)

Uploaded Jul 14, 2026 CPython 3.13manylinux: glibc 2.28+ ARM64

gravel_fragility-3.0.0-cp313-cp313-macosx_11_0_arm64.whl (4.1 MB view details)

Uploaded Jul 14, 2026 CPython 3.13macOS 11.0+ ARM64

gravel_fragility-3.0.0-cp312-cp312-win_amd64.whl (4.3 MB view details)

Uploaded Jul 14, 2026 CPython 3.12Windows x86-64

gravel_fragility-3.0.0-cp312-cp312-manylinux_2_28_x86_64.whl (4.1 MB view details)

Uploaded Jul 14, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

gravel_fragility-3.0.0-cp312-cp312-manylinux_2_28_aarch64.whl (3.8 MB view details)

Uploaded Jul 14, 2026 CPython 3.12manylinux: glibc 2.28+ ARM64

gravel_fragility-3.0.0-cp312-cp312-macosx_11_0_arm64.whl (3.2 MB view details)

Uploaded Jul 14, 2026 CPython 3.12macOS 11.0+ ARM64

gravel_fragility-3.0.0-cp311-cp311-win_amd64.whl (3.4 MB view details)

Uploaded Jul 14, 2026 CPython 3.11Windows x86-64

gravel_fragility-3.0.0-cp311-cp311-manylinux_2_28_x86_64.whl (2.9 MB view details)

Uploaded Jul 14, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

gravel_fragility-3.0.0-cp311-cp311-manylinux_2_28_aarch64.whl (2.6 MB view details)

Uploaded Jul 14, 2026 CPython 3.11manylinux: glibc 2.28+ ARM64

gravel_fragility-3.0.0-cp311-cp311-macosx_11_0_arm64.whl (2.3 MB view details)

Uploaded Jul 14, 2026 CPython 3.11macOS 11.0+ ARM64

gravel_fragility-3.0.0-cp310-cp310-win_amd64.whl (2.5 MB view details)

Uploaded Jul 14, 2026 CPython 3.10Windows x86-64

gravel_fragility-3.0.0-cp310-cp310-manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Jul 14, 2026 CPython 3.10manylinux: glibc 2.28+ x86-64

gravel_fragility-3.0.0-cp310-cp310-manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded Jul 14, 2026 CPython 3.10manylinux: glibc 2.28+ ARM64

gravel_fragility-3.0.0-cp310-cp310-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded Jul 14, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file gravel_fragility-3.0.0.tar.gz.

File metadata

Download URL: gravel_fragility-3.0.0.tar.gz
Upload date: Jul 14, 2026
Size: 1.9 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for gravel_fragility-3.0.0.tar.gz
Algorithm	Hash digest
SHA256	`823fd17a3329e493e4a0db1f7d008f98ba178db1b440daf27f9c9a19e6e65804`
MD5	`96d67af698f27b9bd162e43e7b70135b`
BLAKE2b-256	`76f5795c3ba6277024f782543fac25f1410a6c4ba0de8350efd633c6b6d843ec`

Algorithm	Hash digest
SHA256	`23032f3b86c2818fd8bd23e8728e1a8392ec764b39b62a9d6b7a5895b040edc5`
MD5	`84fe778884ec8ccd080d8e1f8039ab27`
BLAKE2b-256	`a3a64cc1728ad0cf8faeea22a766537db4c0e2231b768d0954391337dfbf1c42`

Algorithm	Hash digest
SHA256	`ec315fa624ca25ab3b5c8603458f55fe4291c846203231d96bbeec77182687f7`
MD5	`f47d4ad490618ae392e26c584faa92a6`
BLAKE2b-256	`6dc50722b2f4dfe248c56240b6a1e41da6a50e769bfcab8ff441eb9b23adb2d2`

Algorithm	Hash digest
SHA256	`f1f53d1ff0c089a500e8fc27b64692501ad9f9bfb87aac36f3c53093275d927f`
MD5	`55caff1a85e07450e7c6a9552fd11008`
BLAKE2b-256	`28eb83462d763b99f722bddf3b76adbb2ed9afee210b6d5cdf019e32a3aabdce`

Algorithm	Hash digest
SHA256	`4c95e57b054a8a46b72b952e51071a8d0638a892b0b383fe980d7f71a95e73e7`
MD5	`bcb7e5d82b692ec181b319cf96e2ac7a`
BLAKE2b-256	`5df9a613940fd21619abe6ef801811ae248afc22e1aba3f399e15154bb33501a`

Algorithm	Hash digest
SHA256	`d2b8354f2133de589e714ef65ed3bb38487e7482126ee495fed468f2366f0005`
MD5	`38242230d79b194dc1089597156210ec`
BLAKE2b-256	`80a9fd90eb6d2ba002cc8d0b73c279ba65eb2b44262026d93ba26f6ea39ec5c0`

Algorithm	Hash digest
SHA256	`e09ce2f1a958d23ab522a859fb0980bab7bc8ddbff9bda461b1911e8d8070883`
MD5	`a4ffb5c4fa00b9a873d0c27726c031ee`
BLAKE2b-256	`138de83c726da884b791d3ec8a8829832b21e836b0d304895c6d9940c0bccf72`

Algorithm	Hash digest
SHA256	`5026f4f72a6adc48e02b53363a78363ed0e0b99b92a540d5a217f3fee5abadaf`
MD5	`eedb85f093fb58de3c386e1fea879df3`
BLAKE2b-256	`45bdcc70f54c0375a3f663c6ed216874adfb1526154d6eb582a7dff7caa63532`

Algorithm	Hash digest
SHA256	`888364781594913716a1c1ac1c48a96bd1e649f1d1575448634b2354eab208a3`
MD5	`5fc0f37fdbe0409a0e3c0ef565ef4e1d`
BLAKE2b-256	`01909980eb5e632f39ff8ed8841593cb5c987af4a2aa8360b2864084b4ead8c8`

Algorithm	Hash digest
SHA256	`f1185db286476af2a492c92f15a06d3c0395c4b2467d18477ef424935c516f80`
MD5	`a53978c84bcee51af193965131fddac5`
BLAKE2b-256	`71c1cd20c31854d88b9549603b81568328cb0147448bbe442a46d51be4b40295`

Algorithm	Hash digest
SHA256	`f9990cf24c864e56779986c89c3b68325b8fc2240b0dc41164e8832ddbd8b2e9`
MD5	`85599a41da35411216da3670b3073c37`
BLAKE2b-256	`320eafcf9a55fe4e8478d2d58b41a9bf36f7ed8a1f6a22fc330930de4094556f`

Algorithm	Hash digest
SHA256	`96ccf1742960de509e4c3be3abff9195f2a3b5acfd19c1e0eec47b6d701c5722`
MD5	`89a6ffe4384525f5bcbdcdca418c0dc3`
BLAKE2b-256	`738bbe7468513172a7ec3cd5bfab774d37290025e7720f938db5637d54102881`

Algorithm	Hash digest
SHA256	`46bb9b274368fc690802ac735eeef7abf3604acfad87c42d6c635d5095b118f2`
MD5	`7b0ac4f7a0bf2205a671dfa31639ddda`
BLAKE2b-256	`e366ae82d99987b0db8292f23f258643ab9e3595feb4616be0c2e13b64e1e70d`

Algorithm	Hash digest
SHA256	`5ee8a97493528ca92666298dc3cffaa825f2c68f91920c116dd8ad07456b83a8`
MD5	`90a49fe520646fab7f6cbc82cfb848a3`
BLAKE2b-256	`91df4f64b839db79010d8d129a442c062645b7b0202e479e154dcdc5ffe85a0a`

Algorithm	Hash digest
SHA256	`923afc97657c01ed1761707e9b71af9867349da0af2ea5486ef78c1a3a3d2a12`
MD5	`7ba3b044919a76efb43a2c4aaf692380`
BLAKE2b-256	`6878ff9cac912816ce60dc6339a4a581f56b80e4ec3b3ee9843ecb935306d1f7`

Algorithm	Hash digest
SHA256	`98ec2ad05235313d05571a2048e5e48b78b7fb9093162b5d82b402f76805b7a0`
MD5	`5195269314d5bd35f3f5bb4f37f5bab1`
BLAKE2b-256	`40fe294ec1f0d39850b54e40bb06fa73e8155e491841b9852a6aab1e980f36e7`

Algorithm	Hash digest
SHA256	`0f656cfd5c1880f5adc471506b0e0137e48e7e9a96543ebf7f03694e3b453b3c`
MD5	`d7b271cb8efd51b726f9afe51f17325f`
BLAKE2b-256	`56e30c29168c4bde49691e31239e8336ebed04156af863a7e98b3b0ec9b59031`

gravel-fragility 3.0.0

Gravel

Installation

pip

conda-forge

From source

Checking OSM availability at runtime

Quick Start

Python

Datasets (2.7.0)

Network substrates (2.7.0)

C++

Key Features

Sub-library architecture

Analysis modules

Performance

Documentation

Example: National US County Analysis

Requirements

Contributing

License

Citation

About

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance