pyroutingkit 0.2.0

Python bindings for RoutingKit Customizable Contraction Hierarchies (CCH)

pyroutingkit

Python bindings for RoutingKit Customizable Contraction Hierarchies (CCH).

Provides microsecond-scale shortest-path queries on large road networks (millions of nodes). Pre-compiled wheels for Linux (manylinux) and macOS — no C++ toolchain needed at install time.

Install

pip install pyroutingkit

Usage

import numpy as np
from pyroutingkit import CCH, INF_WEIGHT

# Build topology (one-time, expensive — can be saved/loaded)
cch = CCH()
tail = np.array([0, 1, 2], dtype=np.uint32)
head = np.array([1, 2, 0], dtype=np.uint32)
lat = np.array([9.0, 9.5, 9.2], dtype=np.float32)
lon = np.array([38.7, 39.0, 38.5], dtype=np.float32)
cch.build_topology(tail, head, lat, lon, node_count=3)

# Customize with weights (fast, can be called multiple times)
weights = np.array([100, 150, 120], dtype=np.uint32)
cch.customize_weights(weights)

# Query (microseconds)
distance, path = cch.query(0, 2)
print(f"Distance: {distance}, Path: {path}")

# Many-to-many matrix
sources = np.array([0, 1], dtype=np.uint32)
targets = np.array([1, 2], dtype=np.uint32)
matrix = cch.distances_many_to_many(sources, targets)

# Save/load topology (skip expensive build on next run)
cch.save_topology("/tmp/cch_cache")
cch2 = CCH()
cch2.load_topology("/tmp/cch_cache")
cch2.customize_weights(weights)  # Must re-customize after load

API

CCH class

Method	Description
build_topology(tail, head, lat, lon, node_count)	Build CCH from graph arrays. Uses inertial flow for node ordering.
customize_weights(weights)	Set edge weights (uint32). Can be called multiple times.
query(source, target)	Point-to-point query. Returns (distance, path).
distances_many_to_many(sources, targets)	NxM distance matrix.
save_topology(dir_path)	Save topology to disk (binary format).
load_topology(dir_path)	Load topology from disk (skips build).

Properties

Property	Type	Description
node_count	int	Number of nodes
arc_count	int	Number of directed edges
is_built	bool	Topology has been built or loaded
is_customized	bool	Weights have been set

Constants

Constant	Description
INF_WEIGHT	Sentinel value for unreachable pairs

Building from source

Requires CMake 3.20+ and a C++17 compiler.

git clone --recurse-submodules https://github.com/nullbutt/pyroutingkit
cd pyroutingkit
uv build

License

MIT. RoutingKit is also MIT-licensed.