Gravel
Getting Started
Installation
pip (recommended)
Optional extras
From source
Verify installation
Requirements
Troubleshooting
gravel.HAS_OSM
is
False
Build fails on Windows
Python import fails with “module _gravel not found”
Quick Start
1. Load a road network
From an OSM PBF file (requires libosmium)
From a CSV edge list
Programmatically
2. Build a contraction hierarchy
3. Compute isolation fragility
Interpret the result
4. Assign regions and analyze counties
5. Scenario analysis
6. Progressive elimination
Next Steps
User Guide
Gravel — Product Requirements Document
Executive Summary
Problem Statement
Users and Use Cases
Primary users
Primary use cases
What Gravel Computes Today (current capability, 2.2.3)
Current limitations
Architecture Overview
Sub-library structure
Core data model
Analysis pipeline
Functional Requirements
FR-1: Graph Loading
FR-2: Routing
FR-3: Fragility Analysis
FR-4: Geographic Analysis
FR-5: US-Specific Support
FR-6: Python Bindings
Non-Functional Requirements
Performance
Quality
Portability
Documentation
Key Design Decisions
DD-1: Reverse-incremental SSSP over forward approach
DD-2: Simplify before analyze
DD-3: Sample-based scoring
DD-4: Composite score formula
DD-5: Graph coarsening for inter-county
DD-6: Topology, not flow (and why)
Version History
v2.4.0 (2026-07-01) — Phase 2A research depth
v2.3.0 (June 2026)
v2.2.3 (June 2026)
v2.2.2 (April 2026)
v2.2.1 (April 2026)
v2.2.0 (April 2026)
v2.1 (April 2026)
v2.0
v1.0
Roadmap
Phase 1 — Interop keystone ✅ shipped in 2.3.0
Performance hardening ✅ shipped in 2.3.0
Phase 2A — Research depth (capacity → stochastic → cascade) ✅ shipped in 2.4.0
Phase 2B — Adoption polish
Hardening & operational (surfaced during the 2.3.0 release)
Longer-horizon / research-track
Non-Goals
API Reference
Python API Reference
Core
Routing
Fragility
Route Fragility
Location Fragility
County Fragility
Scenario Fragility
Progressive Elimination
Network Analysis
Geographic Analysis
Region Assignment
Border Edges & Coarsening
US-Specific (TIGER/FIPS)
OSM Loading (optional)
Edge Sampling
Snapping & Elevation
Gravel
Index
Index