pyroutingkit 0.1.0__tar.gz

pyroutingkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+name: Build & Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  wheels:
+    name: Build wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-14]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.22
+        env:
+          CIBW_BUILD: cp310-* cp311-* cp312-* cp313-*
+          CIBW_SKIP: "*-win32 *-manylinux_i686 *musllinux* pp*"
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux2014
+          CIBW_TEST_COMMAND: python -c "from pyroutingkit import CCH, INF_WEIGHT; print('OK')"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build sdist
+        run: uv build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [wheels, sdist]
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing (OIDC) — no API token needed.
+        # Configure at: https://pypi.org/manage/account/publishing/
+        # Publisher: GitHub, repo: nullbutt/pyroutingkit, workflow: publish.yml

pyroutingkit-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[oc]
+*.so
+*.dylib
+build/
+dist/
+*.egg-info
+.venv

pyroutingkit-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/RoutingKit"]
+	path = vendor/RoutingKit
+	url = https://github.com/RoutingKit/RoutingKit.git

pyroutingkit-0.1.0/CMakeLists.txt

@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.20)
+project(pyroutingkit LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+find_package(pybind11 REQUIRED)
+
+# RoutingKit source files (only what we need for CCH)
+set(ROUTINGKIT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/vendor/RoutingKit")
+
+set(ROUTINGKIT_SOURCES
+    ${ROUTINGKIT_DIR}/src/bit_select.cpp
+    ${ROUTINGKIT_DIR}/src/bit_vector.cpp
+    ${ROUTINGKIT_DIR}/src/customizable_contraction_hierarchy.cpp
+    ${ROUTINGKIT_DIR}/src/graph_util.cpp
+    ${ROUTINGKIT_DIR}/src/id_mapper.cpp
+    ${ROUTINGKIT_DIR}/src/nested_dissection.cpp
+    ${ROUTINGKIT_DIR}/src/contraction_hierarchy.cpp
+    ${ROUTINGKIT_DIR}/src/strongly_connected_component.cpp
+    ${ROUTINGKIT_DIR}/src/timer.cpp
+    ${ROUTINGKIT_DIR}/src/geo_position_to_node.cpp
+)
+
+# Build RoutingKit as a static library
+add_library(routingkit_static STATIC ${ROUTINGKIT_SOURCES})
+target_include_directories(routingkit_static PUBLIC ${ROUTINGKIT_DIR}/include)
+target_compile_options(routingkit_static PRIVATE -O3)
+
+if(APPLE)
+    target_compile_options(routingkit_static PRIVATE -Wno-deprecated -Wno-unused-parameter)
+endif()
+
+# pybind11 module
+pybind11_add_module(_core src/routingkit_module.cpp)
+target_link_libraries(_core PRIVATE routingkit_static)
+target_include_directories(_core PRIVATE ${ROUTINGKIT_DIR}/include)
+
+install(TARGETS _core DESTINATION pyroutingkit)

pyroutingkit-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+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.

pyroutingkit-0.1.0/README.md

@@ -0,0 +1,87 @@
+# 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.

pyroutingkit-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "pyroutingkit"
+version = "0.1.0"
+description = "Python bindings for RoutingKit Customizable Contraction Hierarchies (CCH)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Ryan Fisk" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.urls]
+Repository = "https://github.com/nullbutt/pyroutingkit"
+
+[build-system]
+requires = ["scikit-build-core>=0.10", "pybind11>=2.13"]
+build-backend = "scikit_build_core.build"
+
+[tool.scikit-build]
+cmake.source-dir = "."
+wheel.packages = ["src/pyroutingkit"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

pyroutingkit-0.1.0/src/pyroutingkit/__init__.py

@@ -0,0 +1,17 @@
+"""
+pyroutingkit: Python bindings for RoutingKit Customizable Contraction Hierarchies.
+
+Provides microsecond-scale shortest-path queries on large road networks.
+
+Usage:
+    from pyroutingkit import CCH, INF_WEIGHT
+
+    cch = CCH()
+    cch.build_topology(tail, head, latitude, longitude, node_count)
+    cch.customize_weights(weights_uint32)
+    distance, path = cch.query(source, target)
+"""
+
+from pyroutingkit._core import CCH, INF_WEIGHT
+
+__all__ = ["CCH", "INF_WEIGHT"]

pyroutingkit-0.1.0/src/routingkit_module.cpp

@@ -0,0 +1,263 @@
+/**
+ * pybind11 wrapper for RoutingKit's Customizable Contraction Hierarchy (CCH).
+ *
+ * Exposes:
+ *   - CCH topology construction (compute nested dissection order + build CCH)
+ *   - Metric customization (uint32 weights)
+ *   - Point-to-point query (distance + node path)
+ *   - Many-to-many distance matrix
+ *   - Topology serialization (save/load as binary vectors)
+ */
+
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include <pybind11/stl.h>
+
+#include <routingkit/customizable_contraction_hierarchy.h>
+#include <routingkit/nested_dissection.h>
+#include <routingkit/constants.h>
+#include <routingkit/vector_io.h>
+
+#include <vector>
+#include <string>
+#include <stdexcept>
+#include <fstream>
+#include <cstdint>
+
+namespace py = pybind11;
+
+class CCHWrapper {
+public:
+    CCHWrapper() : node_count_(0), built_(false), customized_(false) {}
+
+    /**
+     * Build CCH topology from graph arrays.
+     *
+     * Uses compute_nested_node_dissection_order_using_inertial_flow for the
+     * elimination order (requires node coordinates).
+     */
+    void build_topology(
+        py::array_t<uint32_t> tail_arr,
+        py::array_t<uint32_t> head_arr,
+        py::array_t<float> latitude_arr,
+        py::array_t<float> longitude_arr,
+        uint32_t node_count
+    ) {
+        auto tail_buf = tail_arr.request();
+        auto head_buf = head_arr.request();
+        auto lat_buf = latitude_arr.request();
+        auto lon_buf = longitude_arr.request();
+
+        if (tail_buf.size != head_buf.size) {
+            throw std::invalid_argument("tail and head must have same length");
+        }
+        if (lat_buf.size != (ssize_t)node_count || lon_buf.size != (ssize_t)node_count) {
+            throw std::invalid_argument("latitude/longitude must have length == node_count");
+        }
+
+        node_count_ = node_count;
+
+        // Copy into std::vector
+        auto* tail_ptr = static_cast<uint32_t*>(tail_buf.ptr);
+        auto* head_ptr = static_cast<uint32_t*>(head_buf.ptr);
+        auto* lat_ptr = static_cast<float*>(lat_buf.ptr);
+        auto* lon_ptr = static_cast<float*>(lon_buf.ptr);
+
+        tail_.assign(tail_ptr, tail_ptr + tail_buf.size);
+        head_.assign(head_ptr, head_ptr + head_buf.size);
+        std::vector<float> latitude(lat_ptr, lat_ptr + lat_buf.size);
+        std::vector<float> longitude(lon_ptr, lon_ptr + lon_buf.size);
+
+        // Compute nested dissection order using inertial flow
+        auto order = RoutingKit::compute_nested_node_dissection_order_using_inertial_flow(
+            node_count, tail_, head_, latitude, longitude
+        );
+
+        // Build CCH
+        cch_ = RoutingKit::CustomizableContractionHierarchy(order, tail_, head_);
+        built_ = true;
+        customized_ = false;
+    }
+
+    /**
+     * Customize weights (quantized uint32).
+     * Must be called after build_topology and before query.
+     */
+    void customize_weights(py::array_t<uint32_t> weights_arr) {
+        if (!built_) {
+            throw std::runtime_error("Must call build_topology before customize_weights");
+        }
+
+        auto buf = weights_arr.request();
+        if (buf.size != (ssize_t)tail_.size()) {
+            throw std::invalid_argument(
+                "weights length (" + std::to_string(buf.size) +
+                ") must equal arc count (" + std::to_string(tail_.size()) + ")"
+            );
+        }
+
+        auto* ptr = static_cast<uint32_t*>(buf.ptr);
+        weights_.assign(ptr, ptr + buf.size);
+
+        metric_ = RoutingKit::CustomizableContractionHierarchyMetric(cch_, weights_);
+        metric_.customize();
+        query_ = RoutingKit::CustomizableContractionHierarchyQuery(metric_);
+        customized_ = true;
+    }
+
+    /**
+     * Point-to-point query.
+     * Returns (distance, node_path) where distance is uint32
+     * and node_path is the list of original node indices.
+     */
+    py::tuple query(uint32_t source, uint32_t target) {
+        if (!customized_) {
+            throw std::runtime_error("Must call customize_weights before query");
+        }
+
+        query_.reset().add_source(source).add_target(target).run();
+        unsigned dist = query_.get_distance();
+
+        if (dist == RoutingKit::inf_weight) {
+            // Unreachable
+            return py::make_tuple(dist, py::list());
+        }
+
+        auto path = query_.get_node_path();
+        return py::make_tuple(dist, py::cast(path));
+    }
+
+    /**
+     * Many-to-many distance matrix.
+     * Uses one-to-many queries for each source.
+     * Returns a flattened uint32 array of shape (len(sources) * len(targets)).
+     */
+    py::array_t<uint32_t> distances_many_to_many(
+        py::array_t<uint32_t> sources_arr,
+        py::array_t<uint32_t> targets_arr
+    ) {
+        if (!customized_) {
+            throw std::runtime_error("Must call customize_weights before distances_many_to_many");
+        }
+
+        auto src_buf = sources_arr.request();
+        auto tgt_buf = targets_arr.request();
+        auto* src_ptr = static_cast<uint32_t*>(src_buf.ptr);
+        auto* tgt_ptr = static_cast<uint32_t*>(tgt_buf.ptr);
+
+        size_t n_src = src_buf.size;
+        size_t n_tgt = tgt_buf.size;
+
+        std::vector<uint32_t> targets(tgt_ptr, tgt_ptr + n_tgt);
+
+        // Result matrix
+        std::vector<uint32_t> result(n_src * n_tgt);
+
+        // Pin targets once, then iterate sources
+        query_.reset().pin_targets(targets);
+
+        for (size_t i = 0; i < n_src; i++) {
+            query_.reset_source().add_source(src_ptr[i]).run_to_pinned_targets();
+            auto dists = query_.get_distances_to_targets();
+            for (size_t j = 0; j < n_tgt; j++) {
+                result[i * n_tgt + j] = dists[j];
+            }
+        }
+
+        // Return as numpy array with shape (n_src, n_tgt)
+        auto result_arr = py::array_t<uint32_t>({(ssize_t)n_src, (ssize_t)n_tgt});
+        auto result_buf = result_arr.request();
+        std::memcpy(result_buf.ptr, result.data(), result.size() * sizeof(uint32_t));
+        return result_arr;
+    }
+
+    /**
+     * Save CCH topology + edge arrays to a directory.
+     */
+    void save_topology(const std::string& dir_path) {
+        if (!built_) {
+            throw std::runtime_error("Must call build_topology before save_topology");
+        }
+
+        RoutingKit::save_vector(dir_path + "/tail", tail_);
+        RoutingKit::save_vector(dir_path + "/head", head_);
+        RoutingKit::save_vector(dir_path + "/order", cch_.order);
+        RoutingKit::save_vector(dir_path + "/rank", cch_.rank);
+
+        // Save node count as a single-element vector
+        std::vector<uint32_t> nc = {node_count_};
+        RoutingKit::save_vector(dir_path + "/node_count", nc);
+    }
+
+    /**
+     * Load CCH topology from a directory (skips the expensive nested dissection).
+     */
+    void load_topology(const std::string& dir_path) {
+        tail_ = RoutingKit::load_vector<unsigned>(dir_path + "/tail");
+        head_ = RoutingKit::load_vector<unsigned>(dir_path + "/head");
+        auto order = RoutingKit::load_vector<unsigned>(dir_path + "/order");
+        auto nc = RoutingKit::load_vector<unsigned>(dir_path + "/node_count");
+
+        if (nc.empty()) {
+            throw std::runtime_error("Invalid topology: missing node_count");
+        }
+        node_count_ = nc[0];
+
+        cch_ = RoutingKit::CustomizableContractionHierarchy(order, tail_, head_);
+        built_ = true;
+        customized_ = false;
+    }
+
+    uint32_t get_node_count() const { return node_count_; }
+    size_t get_arc_count() const { return tail_.size(); }
+    bool is_built() const { return built_; }
+    bool is_customized() const { return customized_; }
+
+private:
+    uint32_t node_count_;
+    bool built_;
+    bool customized_;
+
+    std::vector<unsigned> tail_;
+    std::vector<unsigned> head_;
+    std::vector<unsigned> weights_;
+
+    RoutingKit::CustomizableContractionHierarchy cch_;
+    RoutingKit::CustomizableContractionHierarchyMetric metric_;
+    RoutingKit::CustomizableContractionHierarchyQuery query_;
+};
+
+
+PYBIND11_MODULE(_core, m) {
+    m.doc() = "RoutingKit CCH wrapper for Python";
+
+    py::class_<CCHWrapper>(m, "CCH")
+        .def(py::init<>())
+        .def("build_topology", &CCHWrapper::build_topology,
+             py::arg("tail"), py::arg("head"),
+             py::arg("latitude"), py::arg("longitude"),
+             py::arg("node_count"),
+             "Build CCH topology from graph arrays with inertial flow ordering")
+        .def("customize_weights", &CCHWrapper::customize_weights,
+             py::arg("weights"),
+             "Customize CCH with uint32 weights")
+        .def("query", &CCHWrapper::query,
+             py::arg("source"), py::arg("target"),
+             "Point-to-point query. Returns (distance, node_path)")
+        .def("distances_many_to_many", &CCHWrapper::distances_many_to_many,
+             py::arg("sources"), py::arg("targets"),
+             "Many-to-many distance matrix")
+        .def("save_topology", &CCHWrapper::save_topology,
+             py::arg("dir_path"),
+             "Save CCH topology to directory")
+        .def("load_topology", &CCHWrapper::load_topology,
+             py::arg("dir_path"),
+             "Load CCH topology from directory")
+        .def_property_readonly("node_count", &CCHWrapper::get_node_count)
+        .def_property_readonly("arc_count", &CCHWrapper::get_arc_count)
+        .def_property_readonly("is_built", &CCHWrapper::is_built)
+        .def_property_readonly("is_customized", &CCHWrapper::is_customized);
+
+    // Expose inf_weight constant
+    m.attr("INF_WEIGHT") = RoutingKit::inf_weight;
+}