Metadata-Version: 2.4
Name: pyroutingkit
Version: 0.1.0
Summary: Python bindings for RoutingKit Customizable Contraction Hierarchies (CCH)
Author: Ryan Fisk
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Project-URL: Repository, https://github.com/nullbutt/pyroutingkit
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Description-Content-Type: text/markdown

# pyroutingkit

Python bindings for [RoutingKit](https://github.com/RoutingKit/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

```bash
pip install pyroutingkit
```

## Usage

```python
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.

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

## License

MIT. RoutingKit is also MIT-licensed.
