fastquadtree 0.9.1__tar.gz → 1.0.1__tar.gz

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/Cargo.lock

@@ -10,7 +10,7 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
 name = "fastquadtree"
-version = "0.9.1"
+version = "1.0.1"
 dependencies = [
  "pyo3",
  "smallvec",

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "0.9.1"
+version = "1.0.1"
 edition = "2021"
 readme = "README.md"
 

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 0.9.1
+Version: 1.0.1
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -69,6 +69,7 @@ Rust-optimized quadtree with a clean Python API
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
+- Offers a drop-in [pyqtree shim](https://elan456.github.io/fastquadtree/benchmark/#pyqtree-drop-in-shim-performance-gains) that is 6.567x faster while keeping the same API
 
 ----
 
@@ -86,6 +87,7 @@ pip install fastquadtree
 ```python
 from fastquadtree import QuadTree  # Point handling
 from fastquadtree import RectQuadTree  # Bounding box handling
+from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (6.567x faster while keeping the same API)
 ```
 
 ## Benchmarks

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/README.md

@@ -30,6 +30,7 @@ Rust-optimized quadtree with a clean Python API
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
+- Offers a drop-in [pyqtree shim](https://elan456.github.io/fastquadtree/benchmark/#pyqtree-drop-in-shim-performance-gains) that is 6.567x faster while keeping the same API
 
 ----
 
@@ -47,6 +48,7 @@ pip install fastquadtree
 ```python
 from fastquadtree import QuadTree  # Point handling
 from fastquadtree import RectQuadTree  # Bounding box handling
+from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (6.567x faster while keeping the same API)
 ```
 
 ## Benchmarks

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/benchmarks/benchmark_native_vs_shim.py

@@ -58,15 +58,15 @@ def bench_shim(points, queries, *, track_objects: bool, with_objs: bool):
     )
     if with_objs:
         for i, p in enumerate(points):
-            qt.insert(p, id_=i, obj=i)  # store a tiny object
+            qt.insert(p, obj=i)  # store a tiny object
     else:
-        for i, p in enumerate(points):
-            qt.insert(p, id_=i)
+        for _, p in enumerate(points):
+            qt.insert(p)
     t_build = now() - t0
 
     t0 = now()
     for q in queries:
-        _ = qt.query(q)  # tuples path for speed
+        _ = qt.query(q, as_items=track_objects)  # tuples path for speed
     t_query = now() - t0
     return t_build, t_query
 
@@ -188,18 +188,33 @@ def main():
 | Native | {fmt(n_build)} | {fmt(n_query)} | {fmt(n_build + n_query)} |
 | Shim (no tracking) | {fmt(s_build_no_map)} | {fmt(s_query_no_map)} | {fmt(s_build_no_map + s_query_no_map)} |
 | Shim (tracking) | {fmt(s_build_map)} | {fmt(s_query_map)} | {fmt(s_build_map + s_query_map)} |
-| pyqtree (fastquadtree) | {fmt(fqt_build)} | {fmt(fqt_query)} | {fmt(fqt_build + fqt_query)} |
-| pyqtree (original) | {fmt(p_build)} | {fmt(p_query)} | {fmt(p_build + p_query)} |
 
 ### Summary
 
 Using the shim with object tracking increases build time by {fmt(s_build_map / n_build)}x and query time by {fmt(s_query_map / n_query)}x.
 **Total slowdown = {fmt((s_build_map + s_query_map) / (n_build + n_query))}x.**
 
+Adding the object map tends to only impact the build time, not the query time.
+
+## pyqtree drop-in shim performance gains
+
+### Configuration
+- Points: {args.points:,}
+- Queries: {args.queries}
+- Repeats: {args.repeats}
+
+### Results
+
+| Variant | Build | Query | Total |
+|---|---:|---:|---:|
+| pyqtree (fastquadtree) | {fmt(fqt_build)} | {fmt(fqt_query)} | {fmt(fqt_build + fqt_query)} |
+| pyqtree (original) | {fmt(p_build)} | {fmt(p_query)} | {fmt(p_build + p_query)} |
+
+### Summary
+
 If you directly replace pyqtree with the drop-in `fastquadtree.pyqtree.Index` shim, you get a build time of {fmt(fqt_build)}s and query time of {fmt(fqt_query)}s.
-This is a total speedup of {fmt((p_build + p_query) / (fqt_build + fqt_query))}x compared to the original pyqtree and requires no code changes.
+This is a **total speedup of {fmt((p_build + p_query) / (fqt_build + fqt_query))}x** compared to the original pyqtree and requires no code changes.
 
-Adding the object map only impacts the build time, not the query time.
 """
     print(md.strip())
 

fastquadtree-1.0.1/docs/api/pyqtree.md

@@ -0,0 +1,4 @@
+# fastquadtree.pyqtree
+::: fastquadtree.pyqtree.Index
+    options:
+        inherited_members: true

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/docs/benchmark.md

@@ -46,16 +46,35 @@ Quadtrees are the focus of the benchmark, but Rtrees are included for reference.
 
 | Variant | Build | Query | Total |
 |---|---:|---:|---:|
-| Native | 0.181 | 2.024 | 2.205 |
-| Shim (no map) | 0.301 | 1.883 | 2.184 |
-| Shim (track+objs) | 0.651 | 2.016 | 2.667 |
+| Native | 0.134 | 1.873 | 2.007 |
+| Shim (no tracking) | 0.245 | 1.815 | 2.060 |
+| Shim (tracking) | 0.714 | 2.062 | 2.776 |
 
 ### Summary
 
-Using the shim with object tracking increases build time by 3.604x and query time by 0.996x.
-**Total slowdown = 1.210x.**
+Using the shim with object tracking increases build time by 5.345x and query time by 1.101x.
+**Total slowdown = 1.383x.**
 
-Adding the object map only impacts the build time, not the query time.
+Adding the object map tends to impact the build time more than query time.
+
+## pyqtree drop-in shim performance gains
+
+### Configuration
+- Points: 500,000
+- Queries: 500
+- Repeats: 5
+
+### Results
+
+| Variant | Build | Query | Total |
+|---|---:|---:|---:|
+| pyqtree (fastquadtree) | 0.443 | 2.007 | 2.450 |
+| pyqtree (original) | 3.233 | 12.857 | 16.091 |
+
+### Summary
+
+If you directly replace pyqtree with the drop-in `fastquadtree.pyqtree.Index` shim, you get a build time of 0.443s and query time of 2.007s.
+This is a **total speedup of 6.567x** compared to the original pyqtree and requires no code changes.
 
 ---------
 

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/docs/index.md

@@ -52,8 +52,10 @@ See examples of how fastquadtree can be used in the [runnables](runnables.md) se
 pip install fastquadtree
 ```
 
+## Import
+
 ```python
 from fastquadtree import QuadTree  # Point handling
 from fastquadtree import RectQuadTree  # Bounding box handling
-from fastquadtree.pyqtree import Index # Drop-in replacement for pyqtree
+from fastquadtree.pyqtree import Index # Drop-in replacement for pyqtree (6.567x faster while keeping the same API)
 ```

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/docs/quickstart.md

@@ -20,10 +20,10 @@ from fastquadtree import QuadTree
 # 1) Make a tree that covers your world
 qt = QuadTree(bounds=(0, 0, 1000, 1000), capacity=20)
 
-# 2) Add some stuff
-a = qt.insert((10, 10))                 # auto id
-b = qt.insert((200, 300))               # auto id
-_ = qt.insert((999, 500), id_=42)       # you can choose ids too
+# 2) Add some stuff (a, b, and c are auto-generated ids)
+a = qt.insert((10, 10))                 
+b = qt.insert((200, 300))              
+c = qt.insert((999, 500))     
 
 # 3) Ask spatial questions
 print("Range hits:", qt.query((0, 0, 250, 350)))  # -> [(id, x, y), ...]
@@ -100,7 +100,7 @@ Tip: leave `track_objects=False` for max speed when you do not need object mappi
 Keep the same `QuadTree` instance alive for UIs or game loops. Wipe contents and optionally reset ids.
 
 ```python
-qt.clear(reset_ids=True)  # tree is empty, auto ids start again at 1
+qt.clear()  # tree is empty, auto ids start again at 0, all objects forgotten
 ```
 
 ---

{fastquadtree-0.9.1 → fastquadtree-1.0.1}/mkdocs.yml

@@ -69,10 +69,11 @@ nav:
   - Runnables: runnables.md
   - Benchmark: benchmark.md
   - API:
-      - fastquadtree.QuadTree: api/quadtree.md
-      - fastquadtree.RectQuadTree: api/rect_quadtree.md
-      - fastquadtree.RectItem: api/rect_item.md
-      - fastquadtree.PointItem: api/point_item.md
+      - QuadTree: api/quadtree.md
+      - RectQuadTree: api/rect_quadtree.md
+      - pyqtree: api/pyqtree.md
+      - RectItem: api/rect_item.md
+      - PointItem: api/point_item.md
 
 extra:
   social:

fastquadtree-1.0.1/pysrc/fastquadtree/_base_quadtree.py

@@ -0,0 +1,258 @@
+# _abc_quadtree.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, Iterable, Tuple, TypeVar
+
+from ._item import Item  # base class for PointItem and RectItem
+from ._obj_store import ObjStore
+
+Bounds = Tuple[float, float, float, float]
+
+# Generic parameters
+G = TypeVar("G")  # geometry type, e.g. Point or Bounds
+HitT = TypeVar("HitT")  # raw native tuple, e.g. (id,x,y) or (id,x0,y0,x1,y1)
+ItemType = TypeVar("ItemType", bound=Item)  # e.g. PointItem or RectItem
+
+
+class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
+    """
+    Shared logic for Python QuadTree wrappers over native Rust engines.
+
+    Concrete subclasses must implement:
+      - _new_native(bounds, capacity, max_depth)
+      - _make_item(id_, geom, obj)
+    """
+
+    __slots__ = (
+        "_bounds",
+        "_capacity",
+        "_count",
+        "_max_depth",
+        "_native",
+        "_next_id",
+        "_store",
+        "_track_objects",
+    )
+
+    # ---- required native hooks ----
+
+    @abstractmethod
+    def _new_native(self, bounds: Bounds, capacity: int, max_depth: int | None) -> Any:
+        """Create the native engine instance."""
+
+    @abstractmethod
+    def _make_item(self, id_: int, geom: G, obj: Any | None) -> ItemType:
+        """Build an ItemType from id, geometry, and optional object."""
+
+    # ---- ctor ----
+
+    def __init__(
+        self,
+        bounds: Bounds,
+        capacity: int,
+        *,
+        max_depth: int | None = None,
+        track_objects: bool = False,
+    ):
+        self._bounds = bounds
+        self._max_depth = max_depth
+        self._capacity = capacity
+        self._native = self._new_native(bounds, capacity, max_depth)
+
+        self._track_objects = bool(track_objects)
+        self._store: ObjStore[ItemType] | None = ObjStore() if track_objects else None
+
+        # Auto ids when not using ObjStore.free slots
+        self._next_id = 0
+        self._count = 0
+
+    # ---- internal helper ----
+
+    def _ids_to_objects(self, ids: Iterable[int]) -> list[Any]:
+        """Map ids -> Python objects via ObjStore in a batched way."""
+        if self._store is None:
+            raise ValueError("Cannot map ids to objects when track_objects=False")
+        return self._store.get_many_objects(list(ids))
+
+    # ---- shared API ----
+
+    def insert(self, geom: G, *, obj: Any | None = None) -> int:
+        """
+        Insert a single item.
+
+        Args:
+            geom: Point (x, y) or Rect (x0, y0, x1, y1) depending on quadtree type.
+            obj: Optional Python object to associate with id if tracking is enabled.
+
+        Returns:
+            The id used for this insert.
+
+        Raises:
+            ValueError: If geometry is outside the tree bounds.
+        """
+        if self._store is not None:
+            # Reuse a dense free slot if available, else append
+            rid = self._store.alloc_id()
+        else:
+            rid = self._next_id
+            self._next_id += 1
+
+        if not self._native.insert(rid, geom):
+            bx0, by0, bx1, by1 = self._bounds
+            raise ValueError(
+                f"Geometry {geom!r} is outside bounds ({bx0}, {by0}, {bx1}, {by1})"
+            )
+
+        if self._store is not None:
+            self._store.add(self._make_item(rid, geom, obj))
+
+        self._count += 1
+        return rid
+
+    def insert_many(self, geoms: list[G], objs: list[Any] | None = None) -> int:
+        """
+        Bulk insert with auto-assigned contiguous ids. Faster than inserting one-by-one.<br>
+
+        If tracking is enabled, the objects will be bulk stored internally.
+        If no objects are provided, the items will have obj=None (if tracking).
+
+        Args:
+            geoms: List of geometries.
+            objs: Optional list of Python objects aligned with geoms.
+
+        Returns:
+            Number of items inserted.
+
+        Raises:
+            ValueError: If any geometry is outside bounds.
+        """
+        if not geoms:
+            return 0
+
+        if self._store is None:
+            # Simple contiguous path with native bulk insert
+            start_id = self._next_id
+            last_id = self._native.insert_many(start_id, geoms)
+            num = last_id - start_id + 1
+            if num < len(geoms):
+                raise ValueError("One or more items are outside tree bounds")
+            self._next_id = last_id + 1
+            self._count += num
+            return num
+
+        # With tracking enabled:
+        start_id = len(self._store._arr)  # contiguous tail position
+        last_id = self._native.insert_many(start_id, geoms)
+        num = last_id - start_id + 1
+        if num < len(geoms):
+            raise ValueError("One or more items are outside tree bounds")
+
+        # Add items to the store in one pass
+        if objs is None:
+            for off, geom in enumerate(geoms):
+                id_ = start_id + off
+                self._store.add(self._make_item(id_, geom, None))
+        else:
+            if len(objs) != len(geoms):
+                raise ValueError("objs length must match geoms length")
+            for off, (geom, o) in enumerate(zip(geoms, objs)):
+                id_ = start_id + off
+                self._store.add(self._make_item(id_, geom, o))
+
+        # Keep _next_id monotonic for the non-tracking path
+        self._next_id = max(self._next_id, last_id + 1)
+
+        self._count += num
+        return num
+
+    def delete(self, id_: int, geom: G) -> bool:
+        """
+        Delete an item by id and exact geometry.
+
+        Returns:
+            True if the item was found and deleted.
+        """
+        deleted = self._native.delete(id_, geom)
+        if deleted:
+            self._count -= 1
+            if self._store is not None:
+                self._store.pop_id(id_)
+        return deleted
+
+    def attach(self, id_: int, obj: Any) -> None:
+        """
+        Attach or replace the Python object for an existing id.
+        Tracking must be enabled.
+        """
+        if self._store is None:
+            raise ValueError("Cannot attach objects when track_objects=False")
+        it = self._store.by_id(id_)
+        if it is None:
+            raise KeyError(f"Id {id_} not found in quadtree")
+        # Preserve geometry from existing item
+        self._store.add(self._make_item(id_, it.geom, obj))  # type: ignore[attr-defined]
+
+    def delete_by_object(self, obj: Any) -> bool:
+        """
+        Delete an item by Python object identity. Tracking must be enabled.
+        """
+        if self._store is None:
+            raise ValueError("Cannot delete by object when track_objects=False")
+        it = self._store.by_obj(obj)
+        if it is None:
+            return False
+        return self.delete(it.id_, it.geom)  # type: ignore[arg-type]
+
+    def clear(self) -> None:
+        """
+        Empty the tree in place, preserving bounds, capacity, and max_depth.
+
+        If tracking is enabled, the id -> object mapping is also cleared.
+        The ids are reset to start at zero again.
+        """
+        self._native = self._new_native(self._bounds, self._capacity, self._max_depth)
+        self._count = 0
+        if self._store is not None:
+            self._store.clear()
+        self._next_id = 0
+
+    def get_all_objects(self) -> list[Any]:
+        """
+        Return all tracked Python objects in the tree.
+        """
+        if self._store is None:
+            raise ValueError("Cannot get objects when track_objects=False")
+        return [t.obj for t in self._store.items() if t.obj is not None]
+
+    def get_all_items(self) -> list[ItemType]:
+        """
+        Return all Item wrappers in the tree.
+        """
+        if self._store is None:
+            raise ValueError("Cannot get items when track_objects=False")
+        return list(self._store.items())
+
+    def get_all_node_boundaries(self) -> list[Bounds]:
+        """
+        Return all node boundaries in the tree. Useful for visualization.
+        """
+        return self._native.get_all_node_boundaries()
+
+    def get(self, id_: int) -> Any | None:
+        """
+        Return the object associated with id, if tracking is enabled.
+        """
+        if self._store is None:
+            raise ValueError("Cannot get objects when track_objects=False")
+        item = self._store.by_id(id_)
+        return None if item is None else item.obj
+
+    def count_items(self) -> int:
+        """
+        Return the number of items currently in the tree (native count).
+        """
+        return self._native.count_items()
+
+    def __len__(self) -> int:
+        return self._count

fastquadtree-1.0.1/pysrc/fastquadtree/_obj_store.py

@@ -0,0 +1,167 @@
+# _bimap.py
+from __future__ import annotations
+
+from operator import itemgetter
+from typing import Any, Generic, Iterable, Iterator, TypeVar
+
+from ._item import Item  # base class for PointItem and RectItem
+
+TItem = TypeVar("TItem", bound=Item)
+
+
+class ObjStore(Generic[TItem]):
+    """
+    High-performance id <-> object store for dense, auto-assigned ids.
+
+    Storage
+      - _arr[id]  -> Item or None
+      - _objs[id] -> Python object or None
+      - _obj_to_id: reverse identity map id(obj) -> id
+      - _free: LIFO free-list of reusable ids
+
+    Assumptions
+      - Ids are assigned by the shim and are dense [0..len) with possible holes
+        created by deletes. New inserts reuse holes via the free-list.
+    """
+
+    __slots__ = ("_arr", "_free", "_len", "_obj_to_id", "_objs")
+
+    def __init__(self, items: Iterable[TItem] | None = None) -> None:
+        self._arr: list[TItem | None] = []
+        self._objs: list[Any | None] = []
+        self._obj_to_id: dict[int, int] = {}
+        self._free: list[int] = []  # LIFO
+        self._len: int = 0  # live items
+
+        if items:
+            for it in items:
+                self.add(it)
+
+    # -------- core --------
+
+    def add(self, item: TItem) -> None:
+        """
+        Insert or replace the mapping at item.id_. Reverse map updated so obj points to id.
+        """
+        id_ = item.id_
+        obj = item.obj
+
+        # ids must be dense and assigned by the caller
+        if id_ > len(self._arr):
+            raise AssertionError(
+                "ObjStore.add received an out-of-order id, use alloc_id() to get the next available id"
+            )
+
+        if id_ == len(self._arr):
+            # append
+            self._arr.append(item)
+            self._objs.append(obj)
+            self._len += 1
+        else:
+            # replace or fill a hole
+            old = self._arr[id_]
+            if old is None:
+                self._len += 1
+            elif old.obj is not None:
+                self._obj_to_id.pop(id(old.obj), None)
+            self._arr[id_] = item
+            self._objs[id_] = obj
+
+        if obj is not None:
+            self._obj_to_id[id(obj)] = id_
+
+    def by_id(self, id_: int) -> TItem | None:
+        return self._arr[id_] if 0 <= id_ < len(self._arr) else None
+
+    def by_obj(self, obj: Any) -> TItem | None:
+        id_ = self._obj_to_id.get(id(obj))
+        return self.by_id(id_) if id_ is not None else None
+
+    def pop_id(self, id_: int) -> TItem | None:
+        """Remove by id. Dense ids go to the free-list for reuse."""
+        if not (0 <= id_ < len(self._arr)):
+            return None
+        it = self._arr[id_]
+        if it is None:
+            return None
+        self._arr[id_] = None
+        self._objs[id_] = None
+        if it.obj is not None:
+            self._obj_to_id.pop(id(it.obj), None)
+        self._free.append(id_)
+        self._len -= 1
+        return it
+
+    # -------- allocation --------
+
+    def alloc_id(self) -> int:
+        """
+        Get a reusable dense id. Uses free-list else appends at the tail.
+        Build your Item with this id then call add(item).
+        """
+        return self._free.pop() if self._free else len(self._arr)
+
+    # -------- fast batch gathers --------
+
+    def get_many_by_ids(self, ids: Iterable[int], *, chunk: int = 2048) -> list[TItem]:
+        """
+        Batch: return Items for ids, preserving order.
+        Uses C-level itemgetter on the dense array in chunks.
+        """
+        ids_list: list[int] = list(ids)
+        if not ids_list:
+            return []
+
+        out: list[TItem] = []
+        extend = out.extend
+        arr = self._arr
+        for i in range(0, len(ids_list), chunk):
+            block = ids_list[i : i + chunk]
+            vals = itemgetter(*block)(arr)  # tuple or single item
+            extend(vals if isinstance(vals, tuple) else (vals,))
+        return out
+
+    def get_many_objects(self, ids: Iterable[int], *, chunk: int = 2048) -> list[Any]:
+        """
+        Batch: return Python objects for ids, preserving order.
+        Mirrors get_many_by_ids but reads from _objs.
+        """
+        ids_list: list[int] = list(ids)
+        if not ids_list:
+            return []
+
+        out: list[Any] = []
+        extend = out.extend
+        objs = self._objs
+        for i in range(0, len(ids_list), chunk):
+            block = ids_list[i : i + chunk]
+            vals = itemgetter(*block)(objs)  # tuple or single object
+            extend(vals if isinstance(vals, tuple) else (vals,))
+        return out
+
+    # -------- convenience and iteration --------
+
+    def __len__(self) -> int:
+        return self._len
+
+    def clear(self) -> None:
+        self._arr.clear()
+        self._objs.clear()
+        self._obj_to_id.clear()
+        self._free.clear()
+        self._len = 0
+
+    def contains_id(self, id_: int) -> bool:
+        return 0 <= id_ < len(self._arr) and self._arr[id_] is not None
+
+    def contains_obj(self, obj: Any) -> bool:
+        return id(obj) in self._obj_to_id
+
+    def items_by_id(self) -> Iterator[tuple[int, TItem]]:
+        for i, it in enumerate(self._arr):
+            if it is not None:
+                yield i, it
+
+    def items(self) -> Iterator[TItem]:
+        for _, it in self.items_by_id():
+            yield it