feat: add dtype-specific default max-depths + require max depth for inner quadtree creation

Author: Elan456

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "1.4.2"
+version = "1.4.3"
 edition = "2021"
 
 [lib]

Cargo.toml

@@ -525,5 +525,19 @@ def count_items(self) -> int:
         """
         return self._native.count_items()
 
+    def get_inner_max_depth(self) -> int:
+        """
+        Return the maximum depth of the quadtree core.
+        Useful if you let the core chose the default max depth based on dtype
+        by constructing with max_depth=None.
+
+        Example:
+            ```python
+            depth = qt.get_inner_max_depth()
+            assert isinstance(depth, int)
+            ```
+        """
+        return self._native.get_max_depth()
+
     def __len__(self) -> int:
         return self._count

pysrc/fastquadtree/_base_quadtree.py

@@ -25,6 +25,25 @@ fn rect_to_tuple<T: Coord + Copy>(r: Rect<T>) -> (T, T, T, T) {
     (r.min_x, r.min_y, r.max_x, r.max_y)
 }
 
+fn default_max_depth_for<T: 'static>() -> usize {
+    // Caps aligned with meaningful resolution per dtype.
+    // f32: 24 mantissa bits -> deeper splits stop helping.
+    // f64: 53 mantissa bits.
+    // ints: cap at bit width, beyond that subdivision degenerates anyway.
+    if TypeId::of::<T>() == TypeId::of::<f32>() {
+        24
+    } else if TypeId::of::<T>() == TypeId::of::<f64>() {
+        53
+    } else if TypeId::of::<T>() == TypeId::of::<i32>() {
+        32
+    } else if TypeId::of::<T>() == TypeId::of::<i64>() {
+        64
+    } else {
+        32
+    }
+}
+
+
 // Reusable core for point QuadTrees
 macro_rules! define_point_quadtree_pyclass {
     ($t:ty, $rs_name:ident, $py_name:literal) => {
@@ -41,8 +60,12 @@ macro_rules! define_point_quadtree_pyclass {
                 let (min_x, min_y, max_x, max_y) = bounds;
                 let rect = Rect { min_x, min_y, max_x, max_y };
                 let inner = match max_depth {
-                    Some(d) => QuadTree::new_with_max_depth(rect, capacity, d),
-                    None => QuadTree::new(rect, capacity),
+                    Some(d) => QuadTree::new(rect, capacity, d),
+                    None => QuadTree::new(
+                        rect,
+                        capacity,
+                        default_max_depth_for::<$t>(),
+                    ),
                 };
                 Self { inner }
             }
@@ -265,6 +288,10 @@ macro_rules! define_point_quadtree_pyclass {
             pub fn count_items(&self) -> usize {
                 self.inner.count_items()
             }
+
+            pub fn get_max_depth(&self) -> usize {
+                self.inner.get_max_depth()
+            }
         }
     };
 }
@@ -285,8 +312,12 @@ macro_rules! define_rect_quadtree_pyclass {
                 let (min_x, min_y, max_x, max_y) = bounds;
                 let rect = Rect { min_x, min_y, max_x, max_y };
                 let inner = match max_depth {
-                    Some(d) => RectQuadTree::new_with_max_depth(rect, capacity, d),
-                    None => RectQuadTree::new(rect, capacity),
+                    Some(d) => RectQuadTree::new(rect, capacity, d),
+                    None => RectQuadTree::new(
+                        rect,
+                        capacity,
+                        default_max_depth_for::<$t>(),
+                    ),
                 };
                 Self { inner }
             }
@@ -478,6 +509,10 @@ macro_rules! define_rect_quadtree_pyclass {
             pub fn count_items(&self) -> usize {
                 self.inner.count_items()
             }
+
+            pub fn get_max_depth(&self) -> usize {
+                self.inner.get_max_depth()
+            }
         }
     };
 }

src/lib.rs

@@ -37,18 +37,7 @@ fn child_index_for_point<T: Coord>(b: &Rect<T>, p: &Point<T>) -> usize {
 }
 
 impl<T: Coord> QuadTree<T> {
-    pub fn new(boundary: Rect<T>, capacity: usize) -> Self {
-        QuadTree {
-            boundary,
-            items: Vec::with_capacity(capacity),
-            capacity,
-            children: None,
-            depth: 0,
-            max_depth: usize::MAX,
-        }
-    }
-
-    pub fn new_with_max_depth(boundary: Rect<T>, capacity: usize, max_depth: usize) -> Self {
+    pub fn new(boundary: Rect<T>, capacity: usize, max_depth: usize) -> Self {
         QuadTree {
             boundary,
             items: Vec::with_capacity(capacity),
@@ -392,5 +381,9 @@ impl<T: Coord> QuadTree<T> {
         count
     }
 
+    pub fn get_max_depth(&self) -> usize {
+        self.max_depth
+    }
+
 
 }

src/quadtree.rs

@@ -52,18 +52,7 @@ fn rects_touch_or_intersect<T: Coord>(a: &Rect<T>, b: &Rect<T>) -> bool {
 }
 
 impl<T: Coord> RectQuadTree<T> {
-    pub fn new(boundary: Rect<T>, capacity: usize) -> Self {
-        RectQuadTree {
-            boundary,
-            items: Vec::with_capacity(capacity),
-            capacity,
-            children: None,
-            depth: 0,
-            max_depth: usize::MAX,
-        }
-    }
-
-    pub fn new_with_max_depth(boundary: Rect<T>, capacity: usize, max_depth: usize) -> Self {
+    pub fn new(boundary: Rect<T>, capacity: usize, max_depth: usize) -> Self {
         RectQuadTree {
             boundary,
             items: Vec::with_capacity(capacity),
@@ -301,4 +290,8 @@ impl<T: Coord> RectQuadTree<T> {
             }
         }
     }
+
+    pub fn get_max_depth(&self) -> usize {
+        self.max_depth
+    }
 }

src/rect_quadtree.rs

@@ -27,7 +27,7 @@ fn rect_contains_half_open() {
 
 #[test]
 fn insert_inside_leaf_until_capacity() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2, 8);
 
     let ok1 = qt.insert(Item { id: 1, point: pt(10.0, 10.0) });
     let ok2 = qt.insert(Item { id: 2, point: pt(20.0, 20.0) });
@@ -37,7 +37,7 @@ fn insert_inside_leaf_until_capacity() {
 
 #[test]
 fn insert_outside_returns_false() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2, 8);
 
     assert!(!qt.insert(Item { id: 1, point: pt(-1.0, 50.0) }));
     assert!(!qt.insert(Item { id: 2, point: pt(50.0, 101.0) }));
@@ -46,7 +46,7 @@ fn insert_outside_returns_false() {
 #[test]
 fn split_then_midline_inserts_succeed() {
     // capacity 1 forces a split on the second insert
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 1);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 1, 8);
 
     // first insert goes to parent as a leaf
     assert!(qt.insert(Item { id: 1, point: pt(25.0, 25.0) }));
@@ -66,7 +66,7 @@ fn split_then_midline_inserts_succeed() {
 
 #[test]
 fn many_inserts_all_succeed_when_inside() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 1000.0, 1000.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 1000.0, 1000.0), 4, 8);
 
     // generate a grid of interior points
     let mut ok = 0usize;
@@ -84,7 +84,7 @@ fn many_inserts_all_succeed_when_inside() {
 
 #[test]
 fn boundary_points_respect_half_open_rule() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2, 8);
 
     // Allowed: on min edges
     assert!(qt.insert(Item { id: 1, point: pt(0.0, 0.0) }));

tests/insertions.rs

@@ -18,28 +18,28 @@ fn dist2(a: Point<f32>, b: Point<f32>) -> f32 {
 #[test]
 fn nearest_neighbor_zero_poins() {
     // keep user's original test name
-    let qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4);
+    let qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4, 8);
     assert!(qt.nearest_neighbor(pt(10.0, 10.0)).is_none());
 }
 
 #[test]
 fn nearest_neighbor_one_point() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4, 8);
     qt.insert(Item { id: 1, point: pt(50.0, 50.0) });
     assert_eq!(qt.nearest_neighbor(pt(10.0, 10.0)).unwrap().id, 1);
 }
 
 #[test]
 fn nearest_neighbor_two_points() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4, 8);
     qt.insert(Item { id: 1, point: pt(50.0, 50.0) });
     qt.insert(Item { id: 2, point: pt(60.0, 60.0) });
     assert_eq!(qt.nearest_neighbor(pt(10.0, 10.0)).unwrap().id, 1);
 }
 
 #[test]
 fn nn_exact_hit_distance_zero() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 20.0, 20.0), 8);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 20.0, 20.0), 8, 8);
     qt.insert(Item { id: 7, point: pt(10.0, 10.0) });
     qt.insert(Item { id: 8, point: pt(3.0, 4.0) });
     let q = pt(10.0, 10.0);
@@ -56,7 +56,7 @@ fn nn_exact_hit_distance_zero() {
 #[test]
 fn knn_basic_ordering_no_split() {
     // capacity high so we do not split
-    let mut qt = QuadTree::new(r(0.0, 0.0, 40.0, 40.0), 16);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 40.0, 40.0), 16, 8);
     // unique distances from query (6, 6)
     qt.insert(Item { id: 1, point: pt(5.0, 5.0) });     // d2 = 2
     qt.insert(Item { id: 2, point: pt(6.5, 6.0) });     // d2 = 0.25
@@ -78,7 +78,7 @@ fn knn_basic_ordering_no_split() {
 #[test]
 fn knn_respects_capacity_and_split() {
     // capacity small so we force splits across all quadrants
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 1);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 1, 8);
     qt.insert(Item { id: 1, point: pt(10.0, 10.0) });
     qt.insert(Item { id: 2, point: pt(90.0, 10.0) });
     qt.insert(Item { id: 3, point: pt(10.0, 90.0) });
@@ -98,7 +98,7 @@ fn knn_respects_capacity_and_split() {
 
 #[test]
 fn knn_k_greater_than_len_no_duplicates() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 10.0, 10.0), 2);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 10.0, 10.0), 2, 8);
     qt.insert(Item { id: 1, point: pt(1.0, 1.0) });
     qt.insert(Item { id: 2, point: pt(2.0, 2.0) });
     qt.insert(Item { id: 3, point: pt(9.0, 9.0) });
@@ -115,7 +115,7 @@ fn knn_k_greater_than_len_no_duplicates() {
 #[test]
 fn within_strictly_less_than_max_distance() {
     // current implementation uses d2 < max_d2, not <=
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4, 8);
     let p = pt(10.0, 10.0);
     qt.insert(Item { id: 1, point: pt(13.0, 14.0) }); // distance = 5.0
     qt.insert(Item { id: 2, point: pt(30.0, 30.0) });
@@ -133,7 +133,7 @@ fn within_strictly_less_than_max_distance() {
 #[test]
 fn equidistant_tie_returns_one_of_the_candidates() {
     // two points equidistant from query
-    let mut qt = QuadTree::new(r(0.0, 0.0, 50.0, 50.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 50.0, 50.0), 4, 8);
     qt.insert(Item { id: 10, point: pt(10.0, 10.0) });
     qt.insert(Item { id: 20, point: pt(10.0, 12.0) });
     let q = pt(10.0, 11.0);
@@ -145,7 +145,7 @@ fn equidistant_tie_returns_one_of_the_candidates() {
 fn identical_locations_two_items_pick_one_due_to_strict_lt() {
     // both items at the same coordinates
     // with current algorithm and strict <, k=2 will only return one of them
-    let mut qt = QuadTree::new(r(0.0, 0.0, 10.0, 10.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 10.0, 10.0), 4, 8);
     qt.insert(Item { id: 1, point: pt(5.0, 5.0) });
     qt.insert(Item { id: 2, point: pt(5.0, 5.0) });
 
@@ -157,7 +157,7 @@ fn identical_locations_two_items_pick_one_due_to_strict_lt() {
 
 #[test]
 fn query_far_outside_root_works() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 4, 8);
     qt.insert(Item { id: 1, point: pt(0.0, 0.0) });
     qt.insert(Item { id: 2, point: pt(100.0, 100.0) });
     qt.insert(Item { id: 3, point: pt(100.0, 0.0) });
@@ -171,7 +171,7 @@ fn query_far_outside_root_works() {
 
 #[test]
 fn ordering_is_by_distance_even_after_splits() {
-    let mut qt = QuadTree::new(r(0.0, 0.0, 64.0, 64.0), 1); // force deep subdivisions
+    let mut qt = QuadTree::new(r(0.0, 0.0, 64.0, 64.0), 1, 8); // force deep subdivisions
     // place a small grid of points
     let mut id = 1u64;
     for y in (4..=60).step_by(8) {
@@ -200,7 +200,7 @@ fn ordering_is_by_distance_even_after_splits() {
 #[test]
 fn midline_and_center_points_are_handled() {
     // insert points that lie on child midlines and the exact center
-    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2);
+    let mut qt = QuadTree::new(r(0.0, 0.0, 100.0, 100.0), 2, 8);
     let center = pt(50.0, 50.0);
     qt.insert(Item { id: 1, point: center });
     qt.insert(Item { id: 2, point: pt(50.0, 10.0) }); // vertical midline