Struct HyperbolicHashTable 

pub struct HyperbolicHashTable { /* private fields */ }

Hyperbolic Hash Table for O(1) lookups in hyperbolic space.

Buckets partition the Poincaré disk into ~61 fixed regions. Each bucket contains a VP-tree that provides O(log n) spatial queries within the bucket. Combined with the O(1) bucket selection, total query time is O(log(n/B)) where B is the bucket count.

Implementations

impl HyperbolicHashTable

pub fn new(dimension: usize) -> Self

Create a new hyperbolic hash table with the specified dimension.

pub fn find_bucket(&self, point: &HyperbolicPoint) -> Option<String>

Find the bucket containing a point.

Uses a three-pass strategy:

1. Exact signature match (O(1) HashMap lookup)
2. Euclidean-distance prefilter: sort buckets by cheap Euclidean² distance to their center, then check hyperbolic containment starting from the nearest. Typically finds the match in 1-3 checks (~20-60µs) instead of scanning all ~61 buckets (~1.2ms).
3. quick_validate fallback for edge cases.

pub fn create_signature( &self, point: &HyperbolicPoint, level: u32, ) -> Option<GeometricSignature>

Create a geometric signature for a point.

Uses the point’s actual coordinates for the position signature (not the bucket center), ensuring unique signatures for distinct points even when they fall in the same geometric bucket. The hash field identifies the bucket for O(1) locality lookup.

pub fn validate_point(&self, point: &HyperbolicPoint) -> bool

Check if a hyperbolic point is valid.

pub fn poincare_disk(&self) -> &PoincareDisk

Get the Poincaré disk.

pub fn bucket_count(&self) -> usize

Get the number of buckets.

pub fn register_node( &self, point: &HyperbolicPoint, unique_id: &str, level: u32, ) -> Option<String>

Register a node in the spatial index. Returns the bucket hash the node was placed in.

pub fn register_node_with_hint( &self, point: &HyperbolicPoint, unique_id: &str, level: u32, bucket_hint: Option<&str>, ) -> Option<String>

Register a node in the spatial index with an optional bucket hash hint.

When bucket_hint is provided (e.g. from a prior create_signature call), skips the expensive find_bucket lookup entirely. Falls back to find_bucket if the hint is invalid.

pub fn unregister_node(&self, unique_id: &str)

Remove a node from the spatial index. O(1) via node_to_bucket reverse map — only touches the correct bucket.

pub fn find_nodes_in_radius( &self, center: &HyperbolicPoint, radius: FixedPoint, ) -> Vec<(String, FixedPoint)>

Find all nodes within a hyperbolic radius of a center point.

1. Quick-reject entire buckets whose centers are beyond radius + bucket_radius.
2. Within each candidate bucket, use the VP-tree’s O(log n) range query.

pub fn find_nearest_nodes( &self, point: &HyperbolicPoint, k: usize, ) -> Vec<(String, FixedPoint)>

Find the k nearest nodes to a point.

Sorts buckets by distance to query point, queries each bucket’s VP-tree for its k-nearest, and merges results with proper early termination: stops when the next bucket’s minimum possible distance exceeds the k-th candidate’s distance.

pub fn verify_integrity(&self) -> bool

Verify the integrity of the hash table.

Trait Implementations

impl Clone for HyperbolicHashTable

fn clone(&self) -> HyperbolicHashTable

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HyperbolicHashTable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.