h3-boundary 0.1.0__tar.gz

h3_boundary-0.1.0/CMakeLists.txt

@@ -0,0 +1,70 @@
+cmake_minimum_required(VERSION 3.14)
+project(h3_toolkit)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Set by setup.py: builds only the Python extension (no tests/benchmarks).
+option(H3_BOUNDARY_PIP_BUILD "Building via pip/setup.py" OFF)
+
+include(FetchContent)
+
+FetchContent_Declare(
+  h3
+  GIT_REPOSITORY https://github.com/uber/h3.git
+  GIT_TAG        v4.1.0
+)
+
+FetchContent_MakeAvailable(h3)
+
+# Boost.Geometry (header-only, used for polygon buffering)
+find_package(Boost REQUIRED)
+
+include_directories(${h3_SOURCE_DIR}/src/h3lib/include src/cpp/include)
+
+add_library(h3_toolkit STATIC
+    src/cpp/src/h3_toolkit.cpp
+)
+
+# Link against h3 target (h3 usually exposes 'h3' target) and Boost
+target_link_libraries(h3_toolkit PUBLIC h3 Boost::headers)
+target_include_directories(h3_toolkit PUBLIC src/cpp/include ${Boost_INCLUDE_DIRS})
+
+if(NOT H3_BOUNDARY_PIP_BUILD)
+  # Tests
+  enable_testing()
+  add_executable(h3_toolkit_test tests/cpp/test_h3_toolkit.cpp)
+  target_link_libraries(h3_toolkit_test h3_toolkit )
+  add_test(NAME h3_toolkit_test COMMAND h3_toolkit_test)
+
+  # Benchmark
+  add_executable(bench_pure_cpp benchmarks/bench_pure_cpp.cpp)
+  target_link_libraries(bench_pure_cpp h3_toolkit)
+
+  # Verification
+  add_executable(verify_cpp benchmarks/verify_cpp.cpp)
+  target_link_libraries(verify_cpp h3_toolkit)
+endif()
+
+# Python bindings: prefer the pybind11 from the build environment (pip build
+# requirement passes -Dpybind11_DIR); fall back to FetchContent for bare
+# CMake builds.
+find_package(pybind11 CONFIG QUIET)
+if(NOT pybind11_FOUND)
+  FetchContent_Declare(
+      pybind11
+      GIT_REPOSITORY https://github.com/pybind/pybind11.git
+      GIT_TAG        v2.11.1
+  )
+  FetchContent_MakeAvailable(pybind11)
+endif()
+
+pybind11_add_module(_h3_boundary_cpp src/bindings/python_bindings.cpp)
+target_link_libraries(_h3_boundary_cpp PRIVATE h3_toolkit h3)
+target_include_directories(_h3_boundary_cpp PRIVATE src/cpp/include ${h3_SOURCE_DIR}/src/h3lib/include)
+
+# Dev convenience: `cmake --install` drops the module into the source package
+# (pip builds instead copy from the build dir into build_lib via setup.py).
+install(TARGETS _h3_boundary_cpp DESTINATION ${CMAKE_SOURCE_DIR}/src/python/h3_boundary)
+message(STATUS "Building Python bindings with pybind11")

h3_boundary-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 H3-Toolkit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

h3_boundary-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include CMakeLists.txt
+include LICENSE
+include README.md
+recursive-include src/cpp *.cpp *.hpp
+recursive-include src/bindings *.cpp
+recursive-include tests *.py *.cpp
+recursive-include benchmarks *.py *.cpp
+global-exclude *.so *.pyd *.dylib *.pyc
+prune src/python/h3_boundary/__pycache__

h3_boundary-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: h3-boundary
+Version: 0.1.0
+Summary: H3 cell boundary tracing and buffered polygons across resolution hierarchies, with optional C++ acceleration
+Author: Kaveh Khoshkhah
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Khoshkhah/h3-boundary
+Project-URL: Documentation, https://khoshkhah.github.io/h3-boundary/
+Project-URL: Repository, https://github.com/Khoshkhah/h3-boundary
+Project-URL: Issues, https://github.com/Khoshkhah/h3-boundary/issues
+Keywords: h3,hexagon,geospatial,spatial-index,boundary,gis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h3>=4.0.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: geojson>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: folium; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Dynamic: license-file
+
+# H3-Boundary
+
+**Boundary cells and boundary polygons for Uber's H3 grid.**
+
+[![PyPI](https://img.shields.io/pypi/v/h3-boundary.svg)](https://pypi.org/project/h3-boundary/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An H3 cell at one resolution contains thousands — or billions — of cells at finer resolutions. H3-Boundary works with the ones **on its edge**: it lists them, traces their outline, and builds polygons that safely contain them. Cost scales with the boundary, never with the interior.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Khoshkhah/h3-boundary/master/docs/assets/boundary_children.png"
+       alt="A resolution-5 H3 cell traced at resolution 8: its 78 boundary cells highlighted, its 265 interior cells greyed out"
+       width="720">
+</p>
+
+<p align="center"><em>A resolution-5 cell traced at resolution 8: 78 boundary cells computed, 265 interior cells never generated.</em></p>
+
+```bash
+pip install h3-boundary
+```
+
+## Quick start
+
+Start from any H3 cell. Here we index downtown San Francisco at resolution 6 — a district-sized cell of about 36 km² — using `latlng_to_cell` from [h3-py](https://uber.github.io/h3-py/), which H3-Boundary already depends on.
+
+```python
+import h3
+import h3_boundary as h3b
+
+cell = h3.latlng_to_cell(lat=37.7759, lng=-122.4180, res=6)
+
+# 1. Its boundary cells: the descendants at resolution 10 (block-sized cells)
+#    that lie on its edge
+edge = h3b.children_on_boundary_faces(cell, target_res=10)
+len(edge)                                                # 240, out of 2,401 descendants
+
+# 2. Its exact outline — the shape those descendants actually fill
+outline = h3b.cell_boundary_from_children(cell, target_res=10)
+
+# 3. That same outline, grown by a safety margin
+safe = h3b.get_buffered_boundary_polygon(cell, intermediate_res=10)
+safe["properties"]["buffer_meters"]                      # 75.9 — the margin added
+```
+
+Both polygons are GeoJSON Features, and both trace the boundary at resolution 10 — the difference is what they are for. The **outline** is the exact shape: draw it. On its own it is not safe to filter with, because cells finer than resolution 10 still poke slightly past it; **safe** pushes the edges out by one resolution-10 edge length (75.9 m), after which nothing can fall outside at *any* resolution. That is also why its parameter is called `intermediate_res` — there, tracing is only an intermediate step.
+
+Why not just use the hexagon H3 draws for the cell? Because that hexagon is **not** where the descendants sit — they straddle it, as the figure above shows. Filtering fine-resolution data with it silently loses the cells along the edge (about 7% of them).
+
+## Working at scale
+
+Interiors explode; boundaries stay manageable. Boundary size has a closed form — `3**(depth + 1) - 3`, where `depth` is how many resolution levels you descend — so it is known before computing anything. A resolution-2 cell has close to two billion descendants at resolution 13, but only 531,438 of them lie on its boundary, and you never need to build even those to use them:
+
+```python
+res, target = 2, 13                          # a country-sized cell, traced with ~44 m² cells
+big = h3.latlng_to_cell(lat=37.7759, lng=-122.4180, res=res)
+
+depth = target - res                         # 11 levels of subdivision between the two
+total = 3 ** (depth + 1) - 3                 # 531,438 boundary cells, known without counting
+
+ids = h3b.boundary_cell_ids(big, target_res=target)               # all of them, uint64, ~4 ms
+mid = h3b.boundary_cell_at(big, target_res=target, n=total // 2)  # any one, in microseconds
+h3b.boundary_rank(big, mid)                                       # the inverse — also a membership test
+h3b.boundary_range(big, target_res=target, start=0, stop=100)     # any slice — stream it, or shard it
+```
+
+Disjoint slices reassemble into exactly the full boundary, so parallel workers need no coordination.
+
+## Output formats
+
+- **Cells**: hex strings (`children_on_boundary_faces`) or NumPy `uint64` arrays (`boundary_cell_ids`) — ready for h3-py, dataframes, or database joins.
+- **Polygons**: GeoJSON Features — ready for folium, Leaflet, or PostGIS.
+
+The package ships as a source distribution: it compiles a C++ extension during install when a toolchain is available (`cmake`, C++17, Boost headers) and falls back to pure Python otherwise. Same results either way, verified by a parity test suite.
+
+## Documentation
+
+**[khoshkhah.github.io/h3-boundary](https://khoshkhah.github.io/h3-boundary/)** — concepts, algorithm comparisons, benchmarks, and the full API.
+
+Three runnable notebooks live in [`notebook/`](https://github.com/Khoshkhah/h3-boundary/tree/master/notebook): boundary tracing on a map, working with half-million-cell boundaries, and the buffering modes compared.
+
+## Development
+
+```bash
+git clone https://github.com/Khoshkhah/h3-boundary.git
+cd h3-boundary
+conda env create -f environment.yml && conda activate h3-boundary
+pip install -e .
+pytest tests/python -v
+```
+
+Contributions welcome — see [CONTRIBUTING.md](https://github.com/Khoshkhah/h3-boundary/blob/master/CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/Khoshkhah/h3-boundary/blob/master/LICENSE). Built on [Uber H3](https://h3geo.org/), [Boost.Geometry](https://www.boost.org/doc/libs/release/libs/geometry/) and [pybind11](https://github.com/pybind/pybind11).

h3_boundary-0.1.0/README.md

@@ -0,0 +1,96 @@
+# H3-Boundary
+
+**Boundary cells and boundary polygons for Uber's H3 grid.**
+
+[![PyPI](https://img.shields.io/pypi/v/h3-boundary.svg)](https://pypi.org/project/h3-boundary/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An H3 cell at one resolution contains thousands — or billions — of cells at finer resolutions. H3-Boundary works with the ones **on its edge**: it lists them, traces their outline, and builds polygons that safely contain them. Cost scales with the boundary, never with the interior.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Khoshkhah/h3-boundary/master/docs/assets/boundary_children.png"
+       alt="A resolution-5 H3 cell traced at resolution 8: its 78 boundary cells highlighted, its 265 interior cells greyed out"
+       width="720">
+</p>
+
+<p align="center"><em>A resolution-5 cell traced at resolution 8: 78 boundary cells computed, 265 interior cells never generated.</em></p>
+
+```bash
+pip install h3-boundary
+```
+
+## Quick start
+
+Start from any H3 cell. Here we index downtown San Francisco at resolution 6 — a district-sized cell of about 36 km² — using `latlng_to_cell` from [h3-py](https://uber.github.io/h3-py/), which H3-Boundary already depends on.
+
+```python
+import h3
+import h3_boundary as h3b
+
+cell = h3.latlng_to_cell(lat=37.7759, lng=-122.4180, res=6)
+
+# 1. Its boundary cells: the descendants at resolution 10 (block-sized cells)
+#    that lie on its edge
+edge = h3b.children_on_boundary_faces(cell, target_res=10)
+len(edge)                                                # 240, out of 2,401 descendants
+
+# 2. Its exact outline — the shape those descendants actually fill
+outline = h3b.cell_boundary_from_children(cell, target_res=10)
+
+# 3. That same outline, grown by a safety margin
+safe = h3b.get_buffered_boundary_polygon(cell, intermediate_res=10)
+safe["properties"]["buffer_meters"]                      # 75.9 — the margin added
+```
+
+Both polygons are GeoJSON Features, and both trace the boundary at resolution 10 — the difference is what they are for. The **outline** is the exact shape: draw it. On its own it is not safe to filter with, because cells finer than resolution 10 still poke slightly past it; **safe** pushes the edges out by one resolution-10 edge length (75.9 m), after which nothing can fall outside at *any* resolution. That is also why its parameter is called `intermediate_res` — there, tracing is only an intermediate step.
+
+Why not just use the hexagon H3 draws for the cell? Because that hexagon is **not** where the descendants sit — they straddle it, as the figure above shows. Filtering fine-resolution data with it silently loses the cells along the edge (about 7% of them).
+
+## Working at scale
+
+Interiors explode; boundaries stay manageable. Boundary size has a closed form — `3**(depth + 1) - 3`, where `depth` is how many resolution levels you descend — so it is known before computing anything. A resolution-2 cell has close to two billion descendants at resolution 13, but only 531,438 of them lie on its boundary, and you never need to build even those to use them:
+
+```python
+res, target = 2, 13                          # a country-sized cell, traced with ~44 m² cells
+big = h3.latlng_to_cell(lat=37.7759, lng=-122.4180, res=res)
+
+depth = target - res                         # 11 levels of subdivision between the two
+total = 3 ** (depth + 1) - 3                 # 531,438 boundary cells, known without counting
+
+ids = h3b.boundary_cell_ids(big, target_res=target)               # all of them, uint64, ~4 ms
+mid = h3b.boundary_cell_at(big, target_res=target, n=total // 2)  # any one, in microseconds
+h3b.boundary_rank(big, mid)                                       # the inverse — also a membership test
+h3b.boundary_range(big, target_res=target, start=0, stop=100)     # any slice — stream it, or shard it
+```
+
+Disjoint slices reassemble into exactly the full boundary, so parallel workers need no coordination.
+
+## Output formats
+
+- **Cells**: hex strings (`children_on_boundary_faces`) or NumPy `uint64` arrays (`boundary_cell_ids`) — ready for h3-py, dataframes, or database joins.
+- **Polygons**: GeoJSON Features — ready for folium, Leaflet, or PostGIS.
+
+The package ships as a source distribution: it compiles a C++ extension during install when a toolchain is available (`cmake`, C++17, Boost headers) and falls back to pure Python otherwise. Same results either way, verified by a parity test suite.
+
+## Documentation
+
+**[khoshkhah.github.io/h3-boundary](https://khoshkhah.github.io/h3-boundary/)** — concepts, algorithm comparisons, benchmarks, and the full API.
+
+Three runnable notebooks live in [`notebook/`](https://github.com/Khoshkhah/h3-boundary/tree/master/notebook): boundary tracing on a map, working with half-million-cell boundaries, and the buffering modes compared.
+
+## Development
+
+```bash
+git clone https://github.com/Khoshkhah/h3-boundary.git
+cd h3-boundary
+conda env create -f environment.yml && conda activate h3-boundary
+pip install -e .
+pytest tests/python -v
+```
+
+Contributions welcome — see [CONTRIBUTING.md](https://github.com/Khoshkhah/h3-boundary/blob/master/CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/Khoshkhah/h3-boundary/blob/master/LICENSE). Built on [Uber H3](https://h3geo.org/), [Boost.Geometry](https://www.boost.org/doc/libs/release/libs/geometry/) and [pybind11](https://github.com/pybind/pybind11).

h3_boundary-0.1.0/benchmarks/bench_cpp_binding.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+Benchmark: C++ bindings (pybind11)
+"""
+import time
+import h3
+from h3_boundary._h3_boundary_cpp import children_on_boundary_faces
+
+TARGET_RES = 15
+
+def main():
+    print("=" * 50)
+    print("C++ BINDINGS (pybind11) Benchmark")
+    print("=" * 50)
+    
+    cell_res0 = h3.get_res0_cells()[0]
+    print(f"Base cell: {cell_res0}")
+    print(f"Target resolution: {TARGET_RES}")
+    print()
+    print("Computing...")
+    
+    start = time.perf_counter()
+    result = children_on_boundary_faces(cell_res0, TARGET_RES)
+    elapsed = time.perf_counter() - start
+    
+    print(f"Count: {len(result):,}")
+    print(f"Time:  {elapsed:.3f} seconds")
+    print(f"Rate:  {len(result)/elapsed:,.0f} cells/sec")
+
+if __name__ == "__main__":
+    main()

h3_boundary-0.1.0/benchmarks/bench_pure_cpp.cpp

@@ -0,0 +1,36 @@
+#include "h3_toolkit.hpp"
+#include <h3api.h>
+#include <iostream>
+#include <chrono>
+#include <set>
+
+const int TARGET_RES = 15;
+
+int main() {
+    std::cout << "==================================================" << std::endl;
+    std::cout << "PURE C++ Benchmark" << std::endl;
+    std::cout << "==================================================" << std::endl;
+    
+    H3Index base_cells[122];
+    getRes0Cells(base_cells);
+    H3Index cell_res0 = base_cells[0];
+    
+    std::cout << "Base cell: " << std::hex << cell_res0 << std::dec << std::endl;
+    std::cout << "Target resolution: " << TARGET_RES << std::endl;
+    std::cout << std::endl;
+    std::cout << "Computing..." << std::endl;
+    
+    std::set<int> all_faces = {1, 2, 3, 4, 5, 6};
+    
+    auto start = std::chrono::high_resolution_clock::now();
+    auto result = h3_toolkit::children_on_boundary_faces(cell_res0, TARGET_RES, all_faces);
+    auto end = std::chrono::high_resolution_clock::now();
+    
+    std::chrono::duration<double> elapsed = end - start;
+    
+    std::cout << "Count: " << result.size() << std::endl;
+    std::cout << "Time:  " << elapsed.count() << " seconds" << std::endl;
+    std::cout << "Rate:  " << (result.size() / elapsed.count()) << " cells/sec" << std::endl;
+    
+    return 0;
+}

h3_boundary-0.1.0/benchmarks/bench_pure_python.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+Benchmark: Pure Python implementation
+"""
+import time
+import h3
+from h3_boundary.utils import children_on_boundary_faces
+
+TARGET_RES = 15
+
+def main():
+    print("=" * 50)
+    print("PURE PYTHON Benchmark")
+    print("=" * 50)
+    
+    cell_res0 = h3.get_res0_cells()[0]
+    print(f"Base cell: {cell_res0}")
+    print(f"Target resolution: {TARGET_RES}")
+    print()
+    print("Computing...")
+    
+    start = time.perf_counter()
+    result = children_on_boundary_faces(cell_res0, TARGET_RES)
+    elapsed = time.perf_counter() - start
+    
+    print(f"Count: {len(result):,}")
+    print(f"Time:  {elapsed:.3f} seconds")
+    print(f"Rate:  {len(result)/elapsed:,.0f} cells/sec")
+
+if __name__ == "__main__":
+    main()

h3_boundary-0.1.0/benchmarks/benchmark_backends.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+Benchmark comparing Python vs C++ backends for children_on_boundary_faces
+"""
+import time
+import h3
+
+# Configuration
+TARGET_RES = 15  # Change this to test different resolutions
+
+def benchmark_python(cell_res0, target_res):
+    """Run with pure Python backend"""
+    from h3_boundary.utils import children_on_boundary_faces as py_children
+    
+    start = time.perf_counter()
+    result = py_children(cell_res0, target_res)
+    elapsed = time.perf_counter() - start
+    
+    return result, elapsed
+
+def benchmark_cpp(cell_res0, target_res):
+    """Run with C++ backend"""
+    try:
+        from h3_boundary._h3_boundary_cpp import children_on_boundary_faces as cpp_children
+    except ImportError as e:
+        return None, None, str(e)
+    
+    start = time.perf_counter()
+    result = cpp_children(cell_res0, target_res)
+    elapsed = time.perf_counter() - start
+    
+    return result, elapsed, None
+
+def main():
+    print("=" * 60)
+    print("H3-Boundary Backend Benchmark")
+    print("=" * 60)
+    print()
+    
+    cell_res0 = h3.get_res0_cells()[0]
+    print(f"Base cell: {cell_res0}")
+    print(f"Target resolution: {TARGET_RES}")
+    print()
+    
+    # Python benchmark
+    print("Running Python backend...")
+    py_result, py_time = benchmark_python(cell_res0, TARGET_RES)
+    py_count = len(py_result)
+    print(f"  Count: {py_count:,}")
+    print(f"  Time:  {py_time:.3f}s")
+    if py_time > 0:
+        print(f"  Rate:  {py_count/py_time:,.0f} cells/sec")
+    print()
+    
+    # C++ benchmark
+    print("Running C++ backend...")
+    cpp_result, cpp_time, error = benchmark_cpp(cell_res0, TARGET_RES)
+    
+    if error:
+        print(f"  ERROR: {error}")
+        print()
+        print("To build C++ bindings:")
+        print("  cd ~/projects/h3-toolkit")
+        print("  rm -rf build && mkdir build && cd build")
+        print("  cmake .. && make _h3_boundary_cpp")
+        print("  cp _h3_boundary_cpp*.so ../src/python/h3_boundary/")
+    else:
+        cpp_count = len(cpp_result)
+        print(f"  Count: {cpp_count:,}")
+        print(f"  Time:  {cpp_time:.3f}s")
+        if cpp_time > 0:
+            print(f"  Rate:  {cpp_count/cpp_time:,.0f} cells/sec")
+        print()
+        
+        # Comparison
+        print("-" * 60)
+        if cpp_time > 0 and py_time > 0:
+            speedup = py_time / cpp_time
+            print(f"C++ is {speedup:.1f}x faster than Python")
+        
+        results_match = py_count == cpp_count
+        print(f"Results match: {results_match}")
+        
+        if not results_match:
+            print()
+            print("DEBUG: Checking first 5 results...")
+            py_sorted = sorted(py_result)[:5]
+            cpp_sorted = sorted(cpp_result)[:5]
+            print(f"  Python: {py_sorted}")
+            print(f"  C++:    {cpp_sorted}")
+
+if __name__ == "__main__":
+    main()

h3_boundary-0.1.0/benchmarks/benchmark_cpp.cpp

@@ -0,0 +1,40 @@
+#include "h3_toolkit.hpp"
+#include <h3api.h>
+#include <iostream>
+#include <chrono>
+#include <set>
+
+int main() {
+    // Get a resolution 0 cell (base cell)
+    // Get first base cell
+    int num_base_cells = 122;
+    H3Index base_cells[122];
+    getRes0Cells(base_cells);
+    
+    H3Index cell_res0 = base_cells[0];
+    
+    std::cout << "Base cell: " << std::hex << cell_res0 << std::dec << std::endl;
+    std::cout << "Resolution: " << getResolution(cell_res0) << std::endl;
+    std::cout << std::endl;
+    
+    int target_res = 15;
+    
+    std::cout << "Computing boundary children from res 0 to res " << target_res << "..." << std::endl;
+    std::cout << "This may take a while..." << std::endl;
+    std::cout << std::endl;
+    
+    auto start = std::chrono::high_resolution_clock::now();
+    
+    std::set<int> all_faces = {1, 2, 3, 4, 5, 6};
+    auto boundary_children = h3_toolkit::children_on_boundary_faces(cell_res0, target_res, all_faces);
+    
+    auto end = std::chrono::high_resolution_clock::now();
+    std::chrono::duration<double> elapsed = end - start;
+    
+    std::cout << "Results:" << std::endl;
+    std::cout << "  Number of boundary children: " << boundary_children.size() << std::endl;
+    std::cout << "  Time elapsed: " << elapsed.count() << " seconds" << std::endl;
+    std::cout << "  Rate: " << (boundary_children.size() / elapsed.count()) << " cells/second" << std::endl;
+    
+    return 0;
+}

h3_boundary-0.1.0/benchmarks/benchmark_python.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+Benchmark: children_on_boundary_faces from res 0 to res 15
+"""
+import time
+import h3
+from h3_boundary.utils import children_on_boundary_faces
+
+def benchmark():
+    # Get a resolution 0 cell (base cell)
+    # There are 122 base cells, pick one
+    cell_res0 = h3.get_res0_cells()[0]
+    print(f"Base cell: {cell_res0}")
+    print(f"Resolution: {h3.get_resolution(cell_res0)}")
+    print()
+    
+    target_res = 15
+    
+    print(f"Computing boundary children from res 0 to res {target_res}...")
+    print("This may take a while...")
+    print()
+    
+    start_time = time.perf_counter()
+    
+    boundary_children = children_on_boundary_faces(cell_res0, target_res)
+    
+    end_time = time.perf_counter()
+    elapsed = end_time - start_time
+    
+    print(f"Results:")
+    print(f"  Number of boundary children: {len(boundary_children):,}")
+    print(f"  Time elapsed: {elapsed:.3f} seconds")
+    print(f"  Rate: {len(boundary_children) / elapsed:,.0f} cells/second")
+
+if __name__ == "__main__":
+    benchmark()

h3_boundary-0.1.0/benchmarks/check_readme_snippets.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""
+Executes every ```python block in README.md and the docs, in order, so a
+snippet cannot ship broken or reference an undefined name.
+
+Blocks in one file share a namespace, the way a reader reading top to bottom
+would experience them. Lines that are obviously illustrative rather than
+runnable (a bare `...`) are skipped.
+
+    PYTHONPATH=src/python python benchmarks/check_readme_snippets.py
+"""
+import pathlib
+import re
+import sys
+import traceback
+
+FILES = ["README.md", "docs/index.md"]
+BLOCK = re.compile(r"```python\n(.*?)```", re.DOTALL)
+
+
+def check(path):
+    text = pathlib.Path(path).read_text()
+    blocks = BLOCK.findall(text)
+    if not blocks:
+        print(f"  {path}: no python blocks")
+        return 0
+
+    ns = {}
+    failures = 0
+    for i, block in enumerate(blocks, 1):
+        if block.strip() in ("", "..."):
+            continue
+        try:
+            exec(compile(block, f"{path}#block{i}", "exec"), ns)
+        except Exception:
+            failures += 1
+            print(f"  {path} block {i} FAILED:")
+            print("    " + "\n    ".join(block.strip().splitlines()))
+            print("    " + traceback.format_exc().strip().replace("\n", "\n    "))
+    status = "ok" if not failures else f"{failures} FAILED"
+    print(f"  {path}: {len(blocks)} blocks — {status}")
+    return failures
+
+
+def main():
+    print("checking documentation snippets")
+    failures = sum(check(p) for p in FILES)
+    if failures:
+        print(f"\n{failures} snippet(s) failed")
+        sys.exit(1)
+    print("\nall snippets run")
+
+
+if __name__ == "__main__":
+    main()