From 985f538116a459481e753358ad7992d722f58ddc Mon Sep 17 00:00:00 2001 From: Michael Recachinas Date: Tue, 22 Sep 2026 21:17:28 -0400 Subject: [PATCH] feat(catalog): Catalog with an optional multi-index hashing (MIH) index hexhamming.Catalog(records, width, index=False) copies and validates a fixed-width catalog once and serves first/best/all queries, single and many, with the free functions' results, sentinels and tie-breaking. With index=True it builds an MIH index: m flat CSR bucket tables of s ~ log2(N)+2 bits (capped at 22), with u32 record ids. A query probes every key within t = max_dist // m bits of each query substring. By pigeonhole that finds every record within max_dist; each candidate is then verified with the byte kernel. Candidates are not deduplicated or sorted. Ties go to the lower record index directly, and only all() sorts its matches. This avoids a per-query N-bit seen-set, which glibc would also have to zero. For each query, a cost model picks the index or a linear scan: probes times per-probe cost (rising with index size) against records times scan cost. It was fitted to a sweep of every probe radius 0..=4 on 8/16/32-byte catalogs of 10k-1M records. It chooses the faster path in all eight measured near-crossover cases; mispredictions elsewhere can only favour the linear scan. Python calls borrow exact bytes queries and detach the GIL only when the estimated work is at least 1 us, so small catalogs cost the same per call as the free functions. Apple M4 Max, 1M records, best_within, one query: width r free fn indexed speedup (build: 24 ms / 91 ms) 8 B 0 13.9 us 85 ns 164x (exact match early-exits) 8 B 2 114 us 82 ns 1392x 8 B 8 114 us 1.29 us 88x 8 B 12 108 us 56.4 us 1.9x 32 B 8 178 us 144 ns 1237x 32 B 32 177 us 5.77 us 31x 64x16 B catalog, no index: 59.8 ns vs free function 58.9 ns Index memory is sum_j 4 * (2^s_j + 1 + N) bytes: 45 MB for 1M x 8 B and 182 MB for 1M x 32 B. Tests: differential tests against the free functions across widths, radii and many-query variants. A new test drives the indexed paths directly at every probe radius 0..=4, with planted ties and repeated candidates, so the index path is covered even where the planner would scan. Python tests cover the class API, validation and the docs examples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: c7edd725-5714-4044-acf4-c9afc6ec8cf8 --- README.rst | 55 +++ src/catalog.rs | 727 ++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 2 + src/python.rs | 206 ++++++++++++ test/test_hexhamming.py | 121 ++++++- 5 files changed, 1109 insertions(+), 2 deletions(-) create mode 100644 src/catalog.rs diff --git a/README.rst b/README.rst index 218d5b4..2785156 100644 --- a/README.rst +++ b/README.rst @@ -238,6 +238,61 @@ Semantics match the single-query calls exactly: ``-1`` and ``(-1, -1)`` sentinels for no-match, lowest-index tie-breaking for ``best_many``, exact-match short-circuiting, and ascending index order for ``all_many``. +Catalog +~~~~~~~ + +If you query the same fixed-width byte catalog repeatedly, ``Catalog`` copies +and validates the records once and can optionally build a Multi-Index Hashing +(MIH) index for small-radius lookups: + +:: + + >>> import hexhamming + >>> records = b"\xaa\xaa\xbb\xbb\xcc\xcc\xdd\xdd\xee\xee\xff\xff" + >>> cat = hexhamming.Catalog(records, 2, index=True) + >>> len(cat), cat.width, cat.has_index + (6, 2, True) + >>> cat.first_within(b"\xff\xff", 4) + 1 + >>> cat.best_within(b"\xef\xfe", 4) + (2, 4) + >>> cat.all_within(b"\xff\xff", 4) + [(4, 1), (4, 3), (4, 4), (0, 5)] + +``Catalog(..., index=False)`` uses the same linear scanners as the free +functions while avoiding repeated catalog buffer acquisition. ``index=True`` is +best for large, mostly static catalogs queried repeatedly at small Hamming +radii, such as near-duplicate lookups on 64- or 256-bit perceptual hashes. For +each query the catalog estimates whether probing the index or scanning +linearly is faster and uses the cheaper one. Widths that cannot be indexed +within the memory cap always scan. Either way the results, including +tie-breaking, are identical to the free functions. + +Measured on an Apple M4 Max with 1M records, ``best_within`` for one query: + +====== ====== ============= =========== ======== +width radius free function indexed speedup +====== ====== ============= =========== ======== +8 B 2 114 µs 82 ns 1392x +8 B 8 114 µs 1.3 µs 88x +8 B 12 108 µs 56 µs 1.9x +32 B 8 178 µs 144 ns 1237x +32 B 32 177 µs 5.8 µs 31x +====== ====== ============= =========== ======== + +Building the index took 24 ms for the 8-byte catalog and 91 ms for the +32-byte one. + +The MIH index uses flat CSR substring tables, not hash maps. For ``N`` records +and ``m`` substring tables, memory overhead is approximately:: + + sum_j 4 * ((2 ** s_j + 1) + N) bytes + +where ``s_j`` is the bit width of substring ``j``. The planner chooses +``s_j`` near ``ceil(log2(N)) + 2`` and caps it at 22 bits; this keeps small +catalogs from allocating oversized tables and bounds million-record 256-bit +catalog overhead much lower than an uncapped 24-bit plan. + Dense/compact match transport for ``all_within_dist`` uses ``u16`` distances and ``u32`` indices instead of Python tuples: diff --git a/src/catalog.rs b/src/catalog.rs new file mode 100644 index 0000000..de8d794 --- /dev/null +++ b/src/catalog.rs @@ -0,0 +1,727 @@ +//! Persistent catalogs and optional multi-index hashing (MIH). +//! +//! `Catalog` owns a fixed-width byte catalog once and serves repeated queries +//! without reacquiring or revalidating the catalog buffer. `Catalog::with_index` +//! additionally builds a Multi-Index Hashing index using flat CSR bucket tables: +//! for each of `m` substrings, memory is +//! +//! `4 * ((2^s_j + 1) + N)` bytes, +//! +//! where `s_j` is that substring's bit width and `N` is the record count. The +//! default planner chooses `s ≈ ceil(log2(N)) + 2`, capped at 22 bits to keep +//! 256-bit million-record catalogs around half the prototype's memory while +//! still giving large wins for small radii. Widths that would require more +//! than the supported number of substring tables simply keep a linear catalog. + +use crate::{ + bytes_array_all_many_within_dist, bytes_array_all_within_dist, + bytes_array_best_many_within_dist, bytes_array_best_within_dist, + bytes_array_first_many_within_dist, bytes_array_first_within_dist, + select_bytes_kernel_for_width, BytesKernel, +}; +use std::mem::size_of; + +const MAX_M: usize = 64; +const MAX_SUB_BITS: usize = 22; +/// Largest per-substring probe radius `enumerate_neighbors` supports. +const MAX_PROBE_RADIUS: usize = 4; + +// Planner cost model, in nanoseconds per query. The constants are fitted to a +// sweep of probe radii 0..=4 on 8/16/32-byte catalogs of 10k-1M records +// (Apple M4 Max, block scanners): a bucket probe, including verifying its +// ~N/2^s records, costs 1.2-5.6 ns, rising with index size as probes miss +// cache and TLB. A linear scan costs about 0.11 ns per record or 0.0133 ns +// per byte, whichever is larger, and ~2.5x less once scans run in parallel. +// Slower linear scans elsewhere only make the planner more conservative. +const QUERY_OVERHEAD_NS: f64 = 50.0; +const PROBE_BASE_NS: f64 = 1.5; +const PROBE_CACHE_MISS_NS: f64 = 4.0; +const PROBE_MISS_SATURATION_BYTES: f64 = (128u64 << 20) as f64; +const SCAN_NS_PER_RECORD: f64 = 0.11; +const SCAN_NS_PER_BYTE: f64 = 0.0133; +const PARALLEL_SCAN_BYTES: usize = 16 << 20; +const PARALLEL_SCAN_SPEEDUP: f64 = 2.5; + +/// Estimated cost of scanning `n` records of `width` bytes linearly. +fn linear_scan_ns(n: usize, width: usize) -> f64 { + let bytes = n.saturating_mul(width); + let serial = (n as f64 * SCAN_NS_PER_RECORD).max(bytes as f64 * SCAN_NS_PER_BYTE); + if bytes >= PARALLEL_SCAN_BYTES { + serial / PARALLEL_SCAN_SPEEDUP + } else { + serial + } +} + +/// Number of keys within Hamming distance `t` of an `s`-bit key. +fn ball_size(s: u32, t: u32) -> f64 { + let mut term = 1.0; + let mut total = 1.0; + for i in 1..=t.min(s) { + term = term * f64::from(s - i + 1) / f64::from(i); + total += term; + } + total +} + +#[derive(Clone, Copy, Debug)] +struct MihParams { + m: usize, + s_bits: [u8; MAX_M], + s_off: [u16; MAX_M], +} + +impl MihParams { + fn plan(bits: usize, n: usize) -> Option { + if bits == 0 || bits > (u16::MAX as usize) || bits > MAX_M * MAX_SUB_BITS { + return None; + } + let log2n = ((n as f64).max(2.0)).log2().ceil() as usize; + let target = (log2n + 2).clamp(4, MAX_SUB_BITS); + let m = bits.div_ceil(target).clamp(1, MAX_M); + Self::with_m(bits, m) + } + + fn with_m(bits: usize, m: usize) -> Option { + if m == 0 || m > MAX_M || bits.div_ceil(m) > MAX_SUB_BITS { + return None; + } + let mut s_bits = [0u8; MAX_M]; + let mut s_off = [0u16; MAX_M]; + let base = bits / m; + let extra = bits % m; + let mut off = 0u16; + for j in 0..m { + let w = base + usize::from(j < extra); + s_bits[j] = w as u8; + s_off[j] = off; + off += w as u16; + } + Some(Self { m, s_bits, s_off }) + } +} + +#[inline] +fn extract_substring(code: &[u8], bit_off: usize, width: usize) -> u32 { + debug_assert!(width > 0 && width <= MAX_SUB_BITS); + let start_byte = bit_off / 8; + let bit_in_byte = bit_off & 7; + let end_bit = bit_off + width; + let end_byte = end_bit.div_ceil(8); + let mut acc = 0u64; + for &byte in &code[start_byte..end_byte] { + acc = (acc << 8) | u64::from(byte); + } + let total_bits = (end_byte - start_byte) * 8; + let shift = total_bits - bit_in_byte - width; + let mask = (1u32 << width) - 1; + ((acc >> shift) as u32) & mask +} + +struct BucketTable { + offsets: Vec, + records: Vec, + s_bits: u8, + bit_off: u16, +} + +impl BucketTable { + fn build(records: &[u8], width: usize, s_bits: u8, bit_off: u16) -> Self { + let n = records.len() / width; + let cardinality = 1usize << usize::from(s_bits); + let mut offsets = vec![0u32; cardinality + 1]; + for record in records.chunks_exact(width) { + let key = extract_substring(record, bit_off as usize, s_bits as usize) as usize; + offsets[key + 1] += 1; + } + for i in 1..=cardinality { + offsets[i] += offsets[i - 1]; + } + + let mut placed = offsets.clone(); + let mut ids = vec![0u32; n]; + for (record_id, record) in records.chunks_exact(width).enumerate() { + let key = extract_substring(record, bit_off as usize, s_bits as usize) as usize; + let slot = placed[key] as usize; + ids[slot] = record_id as u32; + placed[key] += 1; + } + Self { + offsets, + records: ids, + s_bits, + bit_off, + } + } + + #[inline] + fn bucket(&self, key: u32) -> &[u32] { + let start = self.offsets[key as usize] as usize; + let end = self.offsets[key as usize + 1] as usize; + &self.records[start..end] + } +} + +struct MihIndex { + params: MihParams, + tables: Vec, +} + +impl MihIndex { + fn build(records: &[u8], width: usize) -> Option { + let n = records.len() / width; + if n == 0 || n > u32::MAX as usize { + return None; + } + let params = MihParams::plan(width.checked_mul(8)?, n)?; + let mut tables = Vec::with_capacity(params.m); + for j in 0..params.m { + tables.push(BucketTable::build( + records, + width, + params.s_bits[j], + params.s_off[j], + )); + } + Some(Self { params, tables }) + } + + /// Estimated cost of one query probing every table at radius `t`. + fn query_ns(&self, t: u32) -> f64 { + let probes: f64 = self + .tables + .iter() + .map(|table| ball_size(u32::from(table.s_bits), t)) + .sum(); + let miss_share = + (self.memory_overhead_bytes() as f64 / PROBE_MISS_SATURATION_BYTES).min(1.0); + QUERY_OVERHEAD_NS + probes * (PROBE_BASE_NS + PROBE_CACHE_MISS_NS * miss_share) + } + + /// Probe radius to use for `max_dist`, or `None` when a linear scan of the + /// `n`-record catalog is expected to be at least as fast. Records within + /// `max_dist` differ from the query by at most `max_dist / m` bits in some + /// substring (pigeonhole), so that radius finds all of them. + fn probe_radius(&self, max_dist: i64, n: usize, width: usize) -> Option { + if max_dist < 0 { + return None; + } + let t = max_dist as usize / self.params.m; + if t > MAX_PROBE_RADIUS { + return None; + } + let t = t as u32; + (self.query_ns(t) < linear_scan_ns(n, width)).then_some(t) + } + + #[inline] + fn memory_overhead_bytes(&self) -> usize { + self.tables + .iter() + .map(|table| (table.offsets.len() + table.records.len()) * size_of::()) + .sum() + } + + #[inline] + fn extract_query_subs(&self, query: &[u8]) -> [u32; MAX_M] { + let mut subs = [0u32; MAX_M]; + for (j, table) in self.tables.iter().enumerate() { + subs[j] = extract_substring(query, table.bit_off as usize, table.s_bits as usize); + } + subs + } + + /// Calls `f` with every record that shares a substring within `t` bits + /// of the query's. By pigeonhole this includes every record within + /// `(t + 1) * m - 1` bits, in no particular order and possibly repeated. + #[inline] + fn for_each_candidate(&self, query: &[u8], t: u32, mut f: F) { + let subs = self.extract_query_subs(query); + for (j, table) in self.tables.iter().enumerate() { + enumerate_neighbors(subs[j], u32::from(table.s_bits), t, |key| { + for &record_id in table.bucket(key) { + f(record_id); + } + }); + } + } +} + +#[inline] +fn enumerate_neighbors(key: u32, width: u32, radius: u32, mut f: F) { + f(key); + if radius >= 1 { + for i in 0..width { + f(key ^ (1u32 << i)); + } + } + if radius >= 2 { + for i in 0..width { + for j in (i + 1)..width { + f(key ^ (1u32 << i) ^ (1u32 << j)); + } + } + } + if radius >= 3 { + for i in 0..width { + for j in (i + 1)..width { + for k in (j + 1)..width { + f(key ^ (1u32 << i) ^ (1u32 << j) ^ (1u32 << k)); + } + } + } + } + if radius >= 4 { + for i in 0..width { + for j in (i + 1)..width { + for k in (j + 1)..width { + for l in (k + 1)..width { + f(key ^ (1u32 << i) ^ (1u32 << j) ^ (1u32 << k) ^ (1u32 << l)); + } + } + } + } + } +} + +/// Owned fixed-width byte catalog with an optional MIH index. +pub struct Catalog { + records: Vec, + width: usize, + index: Option, +} + +impl Catalog { + /// Copy `records` into a reusable fixed-width catalog without an index. + pub fn new(records: &[u8], width: usize) -> Result { + validate_records(records, width)?; + Ok(Catalog { + records: records.to_vec(), + width, + index: None, + }) + } + + /// Copy `records` and build an MIH index when the planner can bound memory. + pub fn with_index(records: &[u8], width: usize) -> Result { + validate_records(records, width)?; + let index = MihIndex::build(records, width); + Ok(Catalog { + records: records.to_vec(), + width, + index, + }) + } + + #[inline] + pub fn len(&self) -> usize { + self.records.len() / self.width + } + + #[inline] + pub fn is_empty(&self) -> bool { + self.records.is_empty() + } + + #[inline] + pub fn width(&self) -> usize { + self.width + } + + #[inline] + pub fn has_index(&self) -> bool { + self.index.is_some() + } + + #[inline] + pub fn records(&self) -> &[u8] { + &self.records + } + + /// Bytes used by MIH CSR tables, excluding the owned record bytes. + #[inline] + pub fn index_memory_overhead_bytes(&self) -> usize { + self.index + .as_ref() + .map(MihIndex::memory_overhead_bytes) + .unwrap_or(0) + } + + pub fn first_within(&self, query: &[u8], max_dist: i64) -> Result, &'static str> { + self.validate_query(query)?; + if let Some((index, t)) = self.index_for_radius(max_dist) { + return Ok(self.indexed_first(index, query, max_dist, t)); + } + bytes_array_first_within_dist(&self.records, query, max_dist) + } + + pub fn best_within( + &self, + query: &[u8], + max_dist: i64, + ) -> Result, &'static str> { + self.validate_query(query)?; + if let Some((index, t)) = self.index_for_radius(max_dist) { + return Ok(self.indexed_best(index, query, max_dist, t)); + } + bytes_array_best_within_dist(&self.records, query, max_dist) + } + + pub fn all_within( + &self, + query: &[u8], + max_dist: i64, + ) -> Result, &'static str> { + self.validate_query(query)?; + if let Some((index, t)) = self.index_for_radius(max_dist) { + return Ok(self.indexed_all(index, query, max_dist, t)); + } + bytes_array_all_within_dist(&self.records, query, max_dist) + } + + pub fn first_many_within( + &self, + queries: &[u8], + max_dist: i64, + ) -> Result>, &'static str> { + self.validate_queries(queries)?; + if self.index_for_radius(max_dist).is_none() { + return bytes_array_first_many_within_dist( + &self.records, + queries, + self.width, + max_dist, + ); + } + queries + .chunks_exact(self.width) + .map(|query| self.first_within(query, max_dist)) + .collect() + } + + pub fn best_many_within( + &self, + queries: &[u8], + max_dist: i64, + ) -> Result>, &'static str> { + self.validate_queries(queries)?; + if self.index_for_radius(max_dist).is_none() { + return bytes_array_best_many_within_dist(&self.records, queries, self.width, max_dist); + } + queries + .chunks_exact(self.width) + .map(|query| self.best_within(query, max_dist)) + .collect() + } + + pub fn all_many_within( + &self, + queries: &[u8], + max_dist: i64, + ) -> Result>, &'static str> { + self.validate_queries(queries)?; + if self.index_for_radius(max_dist).is_none() { + return bytes_array_all_many_within_dist(&self.records, queries, self.width, max_dist); + } + queries + .chunks_exact(self.width) + .map(|query| self.all_within(query, max_dist)) + .collect() + } + + /// Estimated nanoseconds for one query at `max_dist` with the strategy the + /// catalog will choose (index or linear scan). + pub fn estimated_query_ns(&self, max_dist: i64) -> f64 { + match self.index_for_radius(max_dist) { + Some((index, t)) => index.query_ns(t), + None => linear_scan_ns(self.len(), self.width), + } + } + + #[inline] + fn validate_query(&self, query: &[u8]) -> Result<(), &'static str> { + if query.len() != self.width { + return Err("query size must equal catalog width"); + } + Ok(()) + } + + #[inline] + fn validate_queries(&self, queries: &[u8]) -> Result<(), &'static str> { + if queries.len() % self.width != 0 { + return Err("queries size must be multiplier of catalog width"); + } + Ok(()) + } + + #[inline] + fn index_for_radius(&self, max_dist: i64) -> Option<(&MihIndex, u32)> { + let index = self.index.as_ref()?; + let t = index.probe_radius(max_dist, self.len(), self.width)?; + Some((index, t)) + } + + #[inline] + fn record(&self, record_id: u32) -> &[u8] { + let start = record_id as usize * self.width; + &self.records[start..start + self.width] + } + + // Candidates arrive unordered and possibly repeated, so ties are broken + // by record index explicitly instead of sorting the candidate list. + + #[inline] + fn indexed_first( + &self, + index: &MihIndex, + query: &[u8], + max_dist: i64, + probe_radius: u32, + ) -> Option { + let kernel = select_bytes_kernel_for_width(self.width); + let mut first: Option = None; + index.for_each_candidate(query, probe_radius, |record_id| { + if first.is_some_and(|found| record_id >= found) { + return; + } + if kernel(self.record(record_id), query, max_dist) != u64::MAX { + first = Some(record_id); + } + }); + first.map(|record_id| record_id as usize) + } + + #[inline] + fn indexed_best( + &self, + index: &MihIndex, + query: &[u8], + max_dist: i64, + probe_radius: u32, + ) -> Option<(u64, usize)> { + let kernel = select_bytes_kernel_for_width(self.width); + let mut best: Option<(u64, u32)> = None; + index.for_each_candidate(query, probe_radius, |record_id| { + // Admit ties so a lower index at the same distance can win. + let limit = best.map_or(max_dist, |(distance, _)| distance as i64); + let distance = kernel(self.record(record_id), query, limit); + if distance == u64::MAX { + return; + } + let better = match best { + None => true, + Some((best_distance, best_id)) => { + distance < best_distance || (distance == best_distance && record_id < best_id) + } + }; + if better { + best = Some((distance, record_id)); + } + }); + best.map(|(distance, record_id)| (distance, record_id as usize)) + } + + #[inline] + fn indexed_all( + &self, + index: &MihIndex, + query: &[u8], + max_dist: i64, + probe_radius: u32, + ) -> Vec<(u64, usize)> { + let kernel: BytesKernel = select_bytes_kernel_for_width(self.width); + let mut matches = Vec::new(); + index.for_each_candidate(query, probe_radius, |record_id| { + let distance = kernel(self.record(record_id), query, max_dist); + if distance != u64::MAX { + matches.push((distance, record_id as usize)); + } + }); + matches.sort_unstable_by_key(|&(_, record_id)| record_id); + matches.dedup_by_key(|&mut (_, record_id)| record_id); + matches + } +} + +fn validate_records(records: &[u8], width: usize) -> Result<(), &'static str> { + if width == 0 { + return Err("width must be >0"); + } + if records.len() % width != 0 { + return Err("records size must be multiplier of width"); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::Catalog; + use crate::{ + bytes_array_all_many_within_dist, bytes_array_all_within_dist, + bytes_array_best_many_within_dist, bytes_array_best_within_dist, + bytes_array_first_many_within_dist, bytes_array_first_within_dist, + }; + + fn make_records(width: usize, count: usize, seed: u64) -> Vec { + let mut state = seed; + let mut out = vec![0u8; width * count]; + for byte in &mut out { + state = state + .wrapping_mul(6364136223846793005) + .wrapping_add(1442695040888963407); + *byte = (state >> 32) as u8; + } + out + } + + fn flip_bits(buf: &mut [u8], count: usize, seed: u64) { + let mut state = seed; + for _ in 0..count { + state = state + .wrapping_mul(2862933555777941757) + .wrapping_add(3037000493); + let bit = (state as usize) % (buf.len() * 8); + buf[bit / 8] ^= 1 << (bit & 7); + } + } + + // The planner only probes when it expects a win, which small test catalogs + // rarely trigger at larger radii. Drive the indexed paths directly at every + // probe radius, with duplicate records and near neighbours planted so ties + // and repeated candidates occur. + #[test] + fn indexed_paths_match_linear_at_every_probe_radius() { + for &(width, count) in &[(2usize, 300usize), (3, 257), (8, 400), (16, 300), (32, 200)] { + let mut records = make_records(width, count, 0x5EED ^ width as u64); + let query = records[7 * width..8 * width].to_vec(); + for (k, target) in [3usize, 40, 41, 150, count - 1].into_iter().enumerate() { + let mut near = query.clone(); + flip_bits(&mut near, k, 0xB17 + k as u64); + records[target * width..(target + 1) * width].copy_from_slice(&near); + } + let cat = Catalog::with_index(&records, width).unwrap(); + let index = cat.index.as_ref().expect("indexable width"); + let m = index.params.m; + for t in 0..=super::MAX_PROBE_RADIUS as u32 { + for max_dist in [t as i64 * m as i64, (t as i64 + 1) * m as i64 - 1] { + let label = format!("width={width} t={t} max_dist={max_dist}"); + assert_eq!( + cat.indexed_first(index, &query, max_dist, t), + bytes_array_first_within_dist(&records, &query, max_dist).unwrap(), + "first {label}" + ); + assert_eq!( + cat.indexed_best(index, &query, max_dist, t), + bytes_array_best_within_dist(&records, &query, max_dist).unwrap(), + "best {label}" + ); + assert_eq!( + cat.indexed_all(index, &query, max_dist, t), + bytes_array_all_within_dist(&records, &query, max_dist).unwrap(), + "all {label}" + ); + } + } + } + } + + #[test] + fn catalog_validation_and_accessors() { + assert!(Catalog::new(b"abc", 0).is_err()); + assert!(Catalog::new(b"abc", 2).is_err()); + let cat = Catalog::new(b"abcd", 2).unwrap(); + assert_eq!(cat.len(), 2); + assert!(!cat.is_empty()); + assert_eq!(cat.width(), 2); + assert_eq!(cat.records(), b"abcd"); + assert!(!cat.has_index()); + } + + #[test] + fn catalog_tie_breaks_match_linear() { + let width = 8; + let mut records = vec![0xFF; width * 8]; + records[3 * width..4 * width].fill(0); + records[6 * width..7 * width].fill(0); + let query = vec![0; width]; + let cat = Catalog::with_index(&records, width).unwrap(); + assert_eq!(cat.first_within(&query, 0).unwrap(), Some(3)); + assert_eq!(cat.best_within(&query, 0).unwrap(), Some((0, 3))); + assert_eq!(cat.all_within(&query, 0).unwrap(), vec![(0, 3), (0, 6)]); + } + + #[test] + fn catalog_differential_widths_and_radii() { + for &width in &[1usize, 2, 3, 7, 8, 16, 32, 33, 64] { + let count = if width <= 8 { 2048 } else { 768 }; + let mut records = make_records(width, count, width as u64 * 17 + 3); + let planted = count / 3; + let query_index = count / 2; + let mut query = records[query_index * width..(query_index + 1) * width].to_vec(); + flip_bits(&mut query, (width * 8 / 16).max(1), 99 + width as u64); + records[planted * width..(planted + 1) * width].copy_from_slice(&query); + + let cat_index = Catalog::with_index(&records, width).unwrap(); + let cat_linear = Catalog::new(&records, width).unwrap(); + let bits = (width * 8) as i64; + for radius in [0, 1, 2, 4, 8, bits / 4, bits, bits + 100, -1] { + let radius = radius.max(-1); + let expected_first = + bytes_array_first_within_dist(&records, &query, radius).unwrap(); + let expected_best = bytes_array_best_within_dist(&records, &query, radius).unwrap(); + let expected_all = bytes_array_all_within_dist(&records, &query, radius).unwrap(); + assert_eq!( + cat_index.first_within(&query, radius).unwrap(), + expected_first, + "first width={width} r={radius}" + ); + assert_eq!( + cat_index.best_within(&query, radius).unwrap(), + expected_best, + "best width={width} r={radius}" + ); + assert_eq!( + cat_index.all_within(&query, radius).unwrap(), + expected_all, + "all width={width} r={radius}" + ); + assert_eq!( + cat_linear.first_within(&query, radius).unwrap(), + expected_first + ); + assert_eq!( + cat_linear.best_within(&query, radius).unwrap(), + expected_best + ); + assert_eq!(cat_linear.all_within(&query, radius).unwrap(), expected_all); + } + } + } + + #[test] + fn catalog_many_variants_match_free_functions() { + let width = 8; + let records = make_records(width, 2048, 123); + let mut queries = Vec::new(); + queries.extend_from_slice(&records[10 * width..11 * width]); + let mut near = records[99 * width..100 * width].to_vec(); + flip_bits(&mut near, 2, 77); + queries.extend_from_slice(&near); + queries.extend_from_slice(&make_records(width, 1, 456)); + let cat = Catalog::with_index(&records, width).unwrap(); + for radius in [0, 2, 8, 64, -1] { + assert_eq!( + cat.first_many_within(&queries, radius).unwrap(), + bytes_array_first_many_within_dist(&records, &queries, width, radius).unwrap() + ); + assert_eq!( + cat.best_many_within(&queries, radius).unwrap(), + bytes_array_best_many_within_dist(&records, &queries, width, radius).unwrap() + ); + assert_eq!( + cat.all_many_within(&queries, radius).unwrap(), + bytes_array_all_many_within_dist(&records, &queries, width, radius).unwrap() + ); + } + } +} diff --git a/src/lib.rs b/src/lib.rs index 50175cd..ef46c90 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -21,6 +21,7 @@ use std::sync::atomic::{AtomicU8, Ordering}; // onto the same dispatch functions used by Rust callers. mod api; mod batch; +mod catalog; mod classic; mod hex; mod native; @@ -45,6 +46,7 @@ pub use batch::{ bytes_array_all_within_dist_packed, bytes_array_best_many_within_dist, bytes_array_first_many_within_dist, bytes_pairwise_distances, bytes_pairwise_distances_into, }; +pub use catalog::Catalog; /// Lookup table for popcount of 4-bit values (0-15). /// Hex string distance is computed one nibble at a time, so this avoids a diff --git a/src/python.rs b/src/python.rs index b341ccd..637197b 100644 --- a/src/python.rs +++ b/src/python.rs @@ -183,6 +183,211 @@ impl Drop for SimpleByteBuffer { } } +fn copy_byte_buffer(obj: &Bound<'_, PyAny>) -> PyResult> { + if let Some(slice) = exact_bytes(obj) { + return Ok(slice.to_vec()); + } + let mut buf = std::pin::pin!(SimpleByteBuffer::new()); + buf.as_mut().acquire(obj)?; + Ok(unsafe { buf.as_ref().as_slice() }.to_vec()) +} + +// --------------------------------------------------------------------------- +// Catalog — owned fixed-width records with optional MIH index +// --------------------------------------------------------------------------- + +/// Reusable fixed-width byte catalog. +/// +/// Construct with `Catalog(records, width, index=False)`. Records are copied +/// into Rust-owned storage, so query methods can release the GIL safely. +#[pyclass(frozen, module = "hexhamming", name = "Catalog")] +struct PyCatalog { + inner: crate::Catalog, +} + +/// Estimated work below which `Catalog` calls keep the GIL attached: roughly a +/// linear scan of `ARRAY_GIL_RELEASE_THRESHOLD` bytes, where the free +/// functions start detaching. Indexed lookups usually cost well under this, +/// and a detach/attach round trip would be a noticeable share of them. +const CATALOG_DETACH_NS: f64 = 1_000.0; + +/// Borrow exact `bytes` (immutable and kept alive by the caller) or copy any +/// other buffer, so either can be read with the GIL released. +fn catalog_query<'a>(obj: &'a Bound<'_, PyAny>) -> PyResult> { + match exact_bytes(obj) { + Some(slice) => Ok(std::borrow::Cow::Borrowed(slice)), + None => copy_byte_buffer(obj).map(std::borrow::Cow::Owned), + } +} + +fn catalog_max_dist(max_dist: i64) -> PyResult { + if max_dist < 0 { + return Err(PyValueError::new_err("`max_dist` must be >=0")); + } + Ok(max_dist) +} + +impl PyCatalog { + /// Run `f` detached from the interpreter only when `queries` queries at + /// `max_dist` are expected to cost more than a GIL round trip is worth. + fn run( + &self, + py: Python<'_>, + max_dist: i64, + queries: usize, + f: impl FnOnce() -> R + Send, + ) -> R { + if self.inner.estimated_query_ns(max_dist) * queries as f64 >= CATALOG_DETACH_NS { + py.detach(f) + } else { + f() + } + } + + fn query_count(&self, queries: &[u8]) -> usize { + queries.len() / self.inner.width().max(1) + } +} + +#[pymethods] +impl PyCatalog { + #[new] + #[pyo3(signature = (records, width, index=false))] + fn new(records: &Bound<'_, PyAny>, width: usize, index: bool) -> PyResult { + let records = copy_byte_buffer(records)?; + let inner = if index { + crate::Catalog::with_index(&records, width) + } else { + crate::Catalog::new(&records, width) + } + .map_err(PyValueError::new_err)?; + Ok(Self { inner }) + } + + fn __len__(&self) -> usize { + self.inner.len() + } + + #[getter] + fn width(&self) -> usize { + self.inner.width() + } + + #[getter] + fn has_index(&self) -> bool { + self.inner.has_index() + } + + #[pyo3(signature = (query, max_dist))] + fn first_within( + &self, + py: Python<'_>, + query: &Bound<'_, PyAny>, + max_dist: i64, + ) -> PyResult { + let max_dist = catalog_max_dist(max_dist)?; + let query = catalog_query(query)?; + self.run(py, max_dist, 1, || { + self.inner.first_within(&query, max_dist) + }) + .map(|match_index| match_index.map(|i| i as i64).unwrap_or(-1)) + .map_err(PyValueError::new_err) + } + + #[pyo3(signature = (query, max_dist))] + fn best_within( + &self, + py: Python<'_>, + query: &Bound<'_, PyAny>, + max_dist: i64, + ) -> PyResult<(i64, i64)> { + let max_dist = catalog_max_dist(max_dist)?; + let query = catalog_query(query)?; + self.run(py, max_dist, 1, || self.inner.best_within(&query, max_dist)) + .map(|best| best.map(|(d, i)| (d as i64, i as i64)).unwrap_or((-1, -1))) + .map_err(PyValueError::new_err) + } + + #[pyo3(signature = (query, max_dist))] + fn all_within( + &self, + py: Python<'_>, + query: &Bound<'_, PyAny>, + max_dist: i64, + ) -> PyResult> { + let max_dist = catalog_max_dist(max_dist)?; + let query = catalog_query(query)?; + self.run(py, max_dist, 1, || self.inner.all_within(&query, max_dist)) + .map(|matches| matches.into_iter().map(|(d, i)| (d, i as u64)).collect()) + .map_err(PyValueError::new_err) + } + + #[pyo3(signature = (queries, max_dist))] + fn first_many_within( + &self, + py: Python<'_>, + queries: &Bound<'_, PyAny>, + max_dist: i64, + ) -> PyResult> { + let max_dist = catalog_max_dist(max_dist)?; + let queries = catalog_query(queries)?; + let count = self.query_count(&queries); + self.run(py, max_dist, count, || { + self.inner.first_many_within(&queries, max_dist) + }) + .map(|matches| { + matches + .into_iter() + .map(|match_index| match_index.map(|i| i as i64).unwrap_or(-1)) + .collect() + }) + .map_err(PyValueError::new_err) + } + + #[pyo3(signature = (queries, max_dist))] + fn best_many_within( + &self, + py: Python<'_>, + queries: &Bound<'_, PyAny>, + max_dist: i64, + ) -> PyResult> { + let max_dist = catalog_max_dist(max_dist)?; + let queries = catalog_query(queries)?; + let count = self.query_count(&queries); + self.run(py, max_dist, count, || { + self.inner.best_many_within(&queries, max_dist) + }) + .map(|matches| { + matches + .into_iter() + .map(|best| best.map(|(d, i)| (d as i64, i as i64)).unwrap_or((-1, -1))) + .collect() + }) + .map_err(PyValueError::new_err) + } + + #[pyo3(signature = (queries, max_dist))] + fn all_many_within( + &self, + py: Python<'_>, + queries: &Bound<'_, PyAny>, + max_dist: i64, + ) -> PyResult>> { + let max_dist = catalog_max_dist(max_dist)?; + let queries = catalog_query(queries)?; + let count = self.query_count(&queries); + self.run(py, max_dist, count, || { + self.inner.all_many_within(&queries, max_dist) + }) + .map(|many| { + many.into_iter() + .map(|matches| matches.into_iter().map(|(d, i)| (d, i as u64)).collect()) + .collect() + }) + .map_err(PyValueError::new_err) + } +} + // --------------------------------------------------------------------------- // §10 + §14: hamming_distance_string — direct typed params // --------------------------------------------------------------------------- @@ -1170,6 +1375,7 @@ fn set_algo(_module: &Bound<'_, PyModule>, algo_name: &str) -> PyResult #[pymodule] fn hexhamming(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add("__version__", "3.0.0")?; + m.add_class::()?; m.add_function(wrap_pyfunction!(hamming_distance_string, m)?)?; m.add_function(wrap_pyfunction!(hamming_distance_bytes, m)?)?; m.add_function(wrap_pyfunction!(check_hexstrings_within_dist, m)?)?; diff --git a/test/test_hexhamming.py b/test/test_hexhamming.py index 9670e31..688ef5a 100644 --- a/test/test_hexhamming.py +++ b/test/test_hexhamming.py @@ -4,8 +4,12 @@ import pytest from hexhamming import ( + Catalog, + check_bytes_arrays_all_many_within_dist, check_bytes_arrays_all_within_dist, + check_bytes_arrays_best_many_within_dist, check_bytes_arrays_best_within_dist, + check_bytes_arrays_first_many_within_dist, check_bytes_arrays_first_within_dist, check_bytes_arrays_within_dist, check_bytes_within_dist, @@ -57,6 +61,116 @@ def test_hamming_distance_string(hex1, hex2, expected): assert expected == hamming_distance_string(hex1, hex2) +############################ +# Catalog API +############################ + + +def _lcg_bytes(size, seed): + state = seed + out = bytearray(size) + for i in range(size): + state = (state * 6364136223846793005 + 1442695040888963407) & ((1 << 64) - 1) + out[i] = (state >> 32) & 0xFF + return bytes(out) + + +def _flip_bits(buf, bits): + data = bytearray(buf) + for bit in bits: + data[bit // 8] ^= 1 << (bit & 7) + return bytes(data) + + +def test_catalog_api_matches_free_functions(): + width = 8 + records = bytearray(_lcg_bytes(width * 2048, 11)) + query = _flip_bits(records[123 * width : 124 * width], [1, 9]) + records[700 * width : 701 * width] = query + records = bytes(records) + + linear = Catalog(records, width) + indexed = Catalog(records, width, index=True) + assert len(linear) == 2048 + assert linear.width == width + assert not linear.has_index + assert indexed.has_index + + for radius in (0, 2, 8, 64): + expected_first = check_bytes_arrays_first_within_dist(records, query, radius) + expected_best = check_bytes_arrays_best_within_dist(records, query, radius) + expected_all = check_bytes_arrays_all_within_dist(records, query, radius) + assert linear.first_within(query, radius) == expected_first + assert indexed.first_within(query, radius) == expected_first + assert linear.best_within(query, radius) == expected_best + assert indexed.best_within(query, radius) == expected_best + assert linear.all_within(query, radius) == expected_all + assert indexed.all_within(query, radius) == expected_all + + +def test_catalog_many_api_matches_free_functions(): + width = 8 + records = _lcg_bytes(width * 2048, 21) + queries = ( + records[0:width] + + _flip_bits(records[99 * width : 100 * width], [0, 17]) + + _lcg_bytes(width, 22) + ) + cat = Catalog(records, width, index=True) + for radius in (0, 2, 8, 64): + assert cat.first_many_within( + queries, radius + ) == check_bytes_arrays_first_many_within_dist(records, queries, width, radius) + assert cat.best_many_within( + queries, radius + ) == check_bytes_arrays_best_many_within_dist(records, queries, width, radius) + assert cat.all_many_within( + queries, radius + ) == check_bytes_arrays_all_many_within_dist(records, queries, width, radius) + + +def test_catalog_buffer_inputs_and_errors(): + np = pytest.importorskip("numpy") + records = bytearray(b"\x00\x00\xff\xff\x0f\xf0") + cat = Catalog(memoryview(records), 2, index=True) + assert cat.first_within(bytearray(b"\xff\xff"), 0) == 1 + assert cat.best_within(np.frombuffer(b"\x0f\xf0", dtype=np.uint8), 0) == (0, 2) + assert cat.all_within(memoryview(b"\x00\x00"), 0) == [(0, 0)] + + with pytest.raises(ValueError, match="width must be >0"): + Catalog(b"abc", 0) + with pytest.raises(ValueError, match="records size must be multiplier"): + Catalog(b"abc", 2) + with pytest.raises(ValueError, match="query size must equal catalog width"): + cat.first_within(b"\x00", 0) + with pytest.raises(ValueError, match="queries size must be multiplier"): + cat.first_many_within(b"\x00", 0) + with pytest.raises(ValueError, match="`max_dist` must be >=0"): + cat.first_within(b"\x00\x00", -1) + + +def test_catalog_queries_release_gil_from_threads(): + from concurrent.futures import ThreadPoolExecutor + + width = 8 + records = _lcg_bytes(width * 4096, 31) + cat = Catalog(records, width, index=True) + queries = [records[i * width : (i + 1) * width] for i in range(0, 128, 7)] + + def run(query): + return ( + cat.first_within(query, 0), + cat.best_within(query, 0), + cat.all_within(query, 0), + ) + + with ThreadPoolExecutor(max_workers=4) as executor: + got = list(executor.map(run, queries * 20)) + assert all( + first >= 0 and best[0] == 0 and all_matches for first, best, all_matches in got + ) + + @pytest.mark.parametrize( "hex1,hex2,expected", ( @@ -815,7 +929,9 @@ def test_functions_are_bound_to_extension_module(): names = [ name for name in dir(ext) - if callable(getattr(ext, name)) and not name.startswith("_") + if callable(getattr(ext, name)) + and hasattr(getattr(ext, name), "__self__") + and not name.startswith("_") ] assert "hamming_distance_string" in names for name in names: @@ -881,7 +997,8 @@ def test_module_functions_pickle_by_reference(): assert set(RAW_FASTCALL_FUNCTIONS) <= set(names) for name in names: func = getattr(ext, name) - assert func.__module__ == ext.__name__, name + if inspect.isbuiltin(func): + assert func.__module__ == ext.__name__, name assert pickle.loads(pickle.dumps(func)) is func, name