Implement batch lookup and chunked data management
Introduces support for batched MPHF lookups, chunked data handling via `SlottedKmers`, and a comprehensive benchmarking suite to measure performance across the indexing and querying pipeline. This includes new layer functionality for batch operations, chunking logic in the query layer, and scripts to measure wall time and resource usage for various commands. Documentation related to specific implementation details has also been cleaned up.
This commit is contained in:
1 parent
8b87078478
commit
fe38424682
10 files changed
+520
-30
No files matched your search
@@ -199,6 +199,17 @@ impl KmerLayer {
|
||||
}
|
||||
}
|
||||
|
||||
/// Batch form of [`find_slot`](Self::find_slot): `out[i]` is
|
||||
/// `find_slot(kmers[i])`, MPHF lookups prefetched together. `out` is
|
||||
/// cleared and reused.
|
||||
pub fn find_slot_batch(&self, kmers: &[CanonicalKmer], out: &mut Vec<Option<usize>>) {
|
||||
match self {
|
||||
KmerLayer::Count { layer, .. } => layer.find_slot_batch(kmers, out),
|
||||
KmerLayer::Presence { layer, .. } => layer.find_slot_batch(kmers, out),
|
||||
KmerLayer::Empty { .. } => panic!("Layer::find_slot_batch() called on an Empty layer"),
|
||||
}
|
||||
}
|
||||
|
||||
/// Raw MPHF batch lookup: kmer → slot, no membership check — for
|
||||
/// callers that already know every kmer is a member of *this* layer, so
|
||||
/// the evidence check `find_slot`/`find` would perform is redundant.
|
||||
|
||||
@@ -3,6 +3,7 @@ pub mod evidence;
|
||||
pub mod fingerprint;
|
||||
pub mod meta;
|
||||
pub(crate) mod mphf_layer;
|
||||
pub(crate) mod slotted;
|
||||
pub mod typed_layer;
|
||||
pub(crate) mod utils;
|
||||
|
||||
|
||||
@@ -14,6 +14,7 @@ use crate::index::error::{OKIError, OKIResult};
|
||||
use crate::layer::evidence::{Evidence, EvidenceWriter};
|
||||
use crate::layer::fingerprint::{FingerprintVec, FingerprintVecWriter};
|
||||
use crate::layer::meta::IndexMode;
|
||||
use crate::layer::slotted::SlottedKmers;
|
||||
|
||||
pub(crate) const MPHF_FILE: &str = "mphf.bin";
|
||||
pub(crate) const UNITIGS_FILE: &str = "unitigs.bin";
|
||||
@@ -162,7 +163,7 @@ pub struct MphfLayer {
|
||||
/// not a bug).
|
||||
unitigs: Arc<UnitigFileReader>,
|
||||
|
||||
mphf: MemCase<Mphf>,
|
||||
mphf: MphfOnly,
|
||||
ev: OpenLayerEvidence,
|
||||
n: usize,
|
||||
}
|
||||
@@ -175,8 +176,7 @@ impl MphfLayer {
|
||||
/// not stored: `KmerLayer`, one level up, is what owns a layer's
|
||||
/// directory as a persistent field, not this type.
|
||||
pub fn open(dir: &Path) -> OKIResult<Self> {
|
||||
let mphf: MemCase<Mphf> = unsafe { Mphf::mmap(&dir.join(MPHF_FILE), Flags::empty()) }
|
||||
.map_err(|e| OKIError::InvalidData { context: "layer", detail: e.to_string() })?;
|
||||
let mphf = MphfOnly::open(dir)?;
|
||||
let unitigs = Arc::new(UnitigFileReader::open(&dir.join(UNITIGS_FILE))?);
|
||||
let ev = LayerEvidence::at(dir)?.open()?;
|
||||
let n = match &ev {
|
||||
@@ -195,7 +195,14 @@ impl MphfLayer {
|
||||
/// - Hybrid: fingerprint check (fast path), zero false positives via `find_strict`.
|
||||
#[inline]
|
||||
pub fn find(&self, kmer: CanonicalKmer) -> Option<usize> {
|
||||
let slot = self.mphf.uncase().index(&kmer.raw());
|
||||
self.confirm(self.mphf.index(kmer), kmer)
|
||||
}
|
||||
|
||||
/// Membership check of `kmer` against the slot the MPHF gave it — the
|
||||
/// mode-dependent half of [`find`](Self::find), shared with
|
||||
/// [`find_batch`](Self::find_batch).
|
||||
#[inline]
|
||||
fn confirm(&self, slot: usize, kmer: CanonicalKmer) -> Option<usize> {
|
||||
if slot >= self.n {
|
||||
return None;
|
||||
}
|
||||
@@ -219,13 +226,29 @@ impl MphfLayer {
|
||||
}
|
||||
}
|
||||
|
||||
/// Batch form of [`find`](Self::find): `out[i]` is `find(kmers[i])`.
|
||||
///
|
||||
/// The MPHF lookups of the whole slice go through `ptr_hash`'s prefetching
|
||||
/// stream (see [`MphfOnly::for_each_slot`]), so their random pilot reads
|
||||
/// overlap instead of being paid one after the other; the membership
|
||||
/// check runs on each slot as it comes out. `out` is cleared and reused.
|
||||
pub fn find_batch(&self, kmers: &[CanonicalKmer], out: &mut Vec<Option<usize>>) {
|
||||
out.clear();
|
||||
out.reserve(kmers.len());
|
||||
let mut i = 0;
|
||||
self.mphf.for_each_slot(kmers, |slot| {
|
||||
out.push(self.confirm(slot, kmers[i]));
|
||||
i += 1;
|
||||
});
|
||||
}
|
||||
|
||||
/// Always-exact lookup — zero false positives regardless of mode.
|
||||
///
|
||||
/// - Exact/Hybrid: O(1) via evidence + `verify_canonical_kmer`.
|
||||
/// - Approx: O(n) sequential scan of `unitigs.bin` to confirm the kmer
|
||||
/// that owns the slot, then exact comparison.
|
||||
pub fn find_strict(&self, kmer: CanonicalKmer) -> Option<usize> {
|
||||
let slot = self.mphf.uncase().index(&kmer.raw());
|
||||
let slot = self.mphf.index(kmer);
|
||||
if slot >= self.n {
|
||||
return None;
|
||||
}
|
||||
@@ -247,7 +270,7 @@ impl MphfLayer {
|
||||
// the second file-open + mmap + kmer-count scan a fresh
|
||||
// `open_sequential` call would repeat on every call.
|
||||
for (stored, _, _) in self.unitigs.iter_indexed_canonical_kmers() {
|
||||
if self.mphf.uncase().index(&stored.raw()) == slot {
|
||||
if self.mphf.index(stored) == slot {
|
||||
return if stored == kmer { Some(slot) } else { None };
|
||||
}
|
||||
}
|
||||
@@ -278,16 +301,16 @@ impl MphfLayer {
|
||||
/// when the kmer is actually present in the layer; callers that need an
|
||||
/// existence test should use [`find`](Self::find) instead.
|
||||
pub fn hash(&self, kmer: CanonicalKmer) -> usize {
|
||||
self.mphf.uncase().index(&kmer.raw())
|
||||
self.mphf.index(kmer)
|
||||
}
|
||||
|
||||
/// Batch raw MPHF lookup: kmers → slots.
|
||||
///
|
||||
/// Returns a [`Vec`] of slots, one per input kmer, in the same order as the
|
||||
/// input slice. Like [`index`](Self::index), no membership check is
|
||||
/// performed.
|
||||
/// input slice. Like [`hash`](Self::hash), no membership check is
|
||||
/// performed. Prefetching — see [`MphfOnly::index_batch`].
|
||||
pub fn hash_batch(&self, kmers: &[CanonicalKmer]) -> Vec<usize> {
|
||||
kmers.iter().map(|k| self.mphf.uncase().index(&k.raw())).collect()
|
||||
self.mphf.index_batch(kmers)
|
||||
}
|
||||
|
||||
/// Iterate over all canonical kmers in the layer, in deterministic order.
|
||||
@@ -445,10 +468,27 @@ impl MphfOnly {
|
||||
self.0.uncase().index(&kmer.raw())
|
||||
}
|
||||
|
||||
/// Batch form of [`index`](Self::index) — one MPHF lookup pass over the
|
||||
/// whole slice instead of one call per kmer.
|
||||
/// Batch form of [`index`](Self::index): one prefetching `ptr_hash`
|
||||
/// stream over the whole slice, so the random pilot reads of different
|
||||
/// kmers overlap instead of being paid one after the other.
|
||||
pub fn index_batch(&self, kmers: &[CanonicalKmer]) -> Vec<usize> {
|
||||
kmers.iter().map(|&k| self.index(k)).collect()
|
||||
let mut slots = Vec::with_capacity(kmers.len());
|
||||
self.for_each_slot(kmers, |slot| slots.push(slot));
|
||||
slots
|
||||
}
|
||||
|
||||
/// Calls `f(slot)` for each kmer of `kmers`, in order.
|
||||
///
|
||||
/// Callback-shaped on purpose: `ptr_hash`'s `index_stream` only
|
||||
/// implements `fold` (its `next()` is `unimplemented!`), so it cannot be
|
||||
/// returned as an ordinary iterator without a panic trap for callers.
|
||||
/// Look-ahead of 32 keys, as recommended by `ptr_hash`.
|
||||
#[inline]
|
||||
pub fn for_each_slot(&self, kmers: &[CanonicalKmer], f: impl FnMut(usize)) {
|
||||
self.0
|
||||
.uncase()
|
||||
.index_stream::<32, _>(kmers.iter().map(|k| k.raw()))
|
||||
.for_each(f);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -478,8 +518,7 @@ impl MphfLayer {
|
||||
let mut ev = EvidenceWriter::new(n);
|
||||
let mut seen = vec![0u8; (n + 7) / 8];
|
||||
|
||||
for (kmer, chunk_id, rank) in unitigs.iter_indexed_canonical_kmers() {
|
||||
let slot = mphf.index(&kmer.raw());
|
||||
for (slot, _, chunk_id, rank) in SlottedKmers::new(&mphf, unitigs.iter_indexed_canonical_kmers()) {
|
||||
if slot >= n {
|
||||
return Err(OKIError::InvalidData { context: "mphf", detail: "slot out of bounds".into() });
|
||||
}
|
||||
@@ -521,8 +560,7 @@ impl MphfLayer {
|
||||
|
||||
let mut fw = FingerprintVecWriter::new(n, b);
|
||||
|
||||
for (kmer, _, _) in unitigs.iter_indexed_canonical_kmers() {
|
||||
let slot = mphf.index(&kmer.raw());
|
||||
for (slot, kmer, _, _) in SlottedKmers::new(&mphf, unitigs.iter_indexed_canonical_kmers()) {
|
||||
if slot >= n {
|
||||
return Err(OKIError::InvalidData { context: "mphf", detail: "slot out of bounds".into() });
|
||||
}
|
||||
@@ -592,8 +630,7 @@ impl MphfLayer {
|
||||
match mode {
|
||||
IndexMode::Exact => {
|
||||
let mut ev = EvidenceWriter::new(n);
|
||||
for (kmer, chunk_id, rank) in unitigs2.iter_indexed_canonical_kmers() {
|
||||
let slot = mphf.index(&kmer.raw());
|
||||
for (slot, kmer, chunk_id, rank) in SlottedKmers::new(&mphf, unitigs2.iter_indexed_canonical_kmers()) {
|
||||
if slot >= n {
|
||||
return Err(OKIError::InvalidData { context: "mphf", detail: "slot out of bounds".into() });
|
||||
}
|
||||
@@ -612,8 +649,7 @@ impl MphfLayer {
|
||||
|
||||
IndexMode::Approx { b, .. } => {
|
||||
let mut fw = FingerprintVecWriter::new(n, *b);
|
||||
for (kmer, _, _) in unitigs2.iter_indexed_canonical_kmers() {
|
||||
let slot = mphf.index(&kmer.raw());
|
||||
for (slot, kmer, _, _) in SlottedKmers::new(&mphf, unitigs2.iter_indexed_canonical_kmers()) {
|
||||
if slot >= n {
|
||||
return Err(OKIError::InvalidData { context: "mphf", detail: "slot out of bounds".into() });
|
||||
}
|
||||
@@ -632,8 +668,7 @@ impl MphfLayer {
|
||||
IndexMode::Hybrid { b, .. } => {
|
||||
let mut ev = EvidenceWriter::new(n);
|
||||
let mut fw = FingerprintVecWriter::new(n, *b);
|
||||
for (kmer, chunk_id, rank) in unitigs2.iter_indexed_canonical_kmers() {
|
||||
let slot = mphf.index(&kmer.raw());
|
||||
for (slot, kmer, chunk_id, rank) in SlottedKmers::new(&mphf, unitigs2.iter_indexed_canonical_kmers()) {
|
||||
if slot >= n {
|
||||
return Err(OKIError::InvalidData { context: "mphf", detail: "slot out of bounds".into() });
|
||||
}
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
//! A layer's kmers streamed together with their MPHF slot — the shape every
|
||||
//! build pass needs (`slot` indexes evidence, fingerprint and bitmap writes).
|
||||
|
||||
use obikseq::CanonicalKmer;
|
||||
|
||||
use crate::layer::mphf_layer::Mphf;
|
||||
|
||||
/// Kmers per `ptr_hash` stream: large enough to amortise its ring-buffer
|
||||
/// start-up, small enough to stay in L1/L2 and never hold the layer.
|
||||
const CHUNK: usize = 4096;
|
||||
|
||||
/// `(slot, kmer, chunk_id, rank)` for every `(kmer, chunk_id, rank)` of the
|
||||
/// wrapped iterator, in the same order. The MPHF lookups are done a chunk at
|
||||
/// a time through `ptr_hash`'s prefetching stream, so their random pilot
|
||||
/// reads overlap; memory stays bounded by one chunk.
|
||||
pub(crate) struct SlottedKmers<'a, I> {
|
||||
mphf: &'a Mphf,
|
||||
kmers: I,
|
||||
chunk: Vec<(CanonicalKmer, usize, usize)>,
|
||||
slots: Vec<usize>,
|
||||
pos: usize,
|
||||
}
|
||||
|
||||
impl<'a, I: Iterator<Item = (CanonicalKmer, usize, usize)>> SlottedKmers<'a, I> {
|
||||
pub(crate) fn new(mphf: &'a Mphf, kmers: I) -> Self {
|
||||
Self {
|
||||
mphf,
|
||||
kmers,
|
||||
chunk: Vec::with_capacity(CHUNK),
|
||||
slots: Vec::with_capacity(CHUNK),
|
||||
pos: 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl<I: Iterator<Item = (CanonicalKmer, usize, usize)>> Iterator for SlottedKmers<'_, I> {
|
||||
type Item = (usize, CanonicalKmer, usize, usize);
|
||||
|
||||
fn next(&mut self) -> Option<Self::Item> {
|
||||
if self.pos == self.chunk.len() {
|
||||
self.chunk.clear();
|
||||
self.chunk.extend(self.kmers.by_ref().take(CHUNK));
|
||||
if self.chunk.is_empty() {
|
||||
return None;
|
||||
}
|
||||
self.slots.clear();
|
||||
let slots = &mut self.slots;
|
||||
self.mphf
|
||||
.index_stream::<32, _>(self.chunk.iter().map(|(k, _, _)| k.raw()))
|
||||
.for_each(|slot| slots.push(slot));
|
||||
self.pos = 0;
|
||||
}
|
||||
let (kmer, chunk_id, rank) = self.chunk[self.pos];
|
||||
let slot = self.slots[self.pos];
|
||||
self.pos += 1;
|
||||
Some((slot, kmer, chunk_id, rank))
|
||||
}
|
||||
}
|
||||
@@ -189,6 +189,13 @@ impl<D: LayerData> TypedLayer<D> {
|
||||
self.kmerstore.find(kmer)
|
||||
}
|
||||
|
||||
/// Batch form of [`find_slot`](Self::find_slot): `out[i]` is
|
||||
/// `find_slot(kmers[i])`, with the MPHF lookups prefetched together
|
||||
/// (see `MphfLayer::find_batch`). `out` is cleared and reused.
|
||||
pub fn find_slot_batch(&self, kmers: &[CanonicalKmer], out: &mut Vec<Option<usize>>) {
|
||||
self.kmerstore.find_batch(kmers, out)
|
||||
}
|
||||
|
||||
pub fn n(&self) -> usize {
|
||||
self.kmerstore.n()
|
||||
}
|
||||
|
||||
@@ -134,16 +134,48 @@ impl QueryPartition for IndexCache {
|
||||
let mut by_layer: Vec<HashMap<usize, &Vec<KmerDesc>>> =
|
||||
(0..n_layer).map(|_| HashMap::new()).collect();
|
||||
|
||||
for (kmer, descs) in kmers {
|
||||
stats.n_unique_kmers += 1;
|
||||
// Layer-major over fixed-size chunks of the (unordered) kmer map:
|
||||
// each layer sees the chunk's still-unresolved kmers as one batch, so
|
||||
// its MPHF lookups are prefetched together; a kmer found in an
|
||||
// earlier layer never reaches the later ones (first hit wins, as
|
||||
// before). Chunked, not collected — the map is never copied whole.
|
||||
const CHUNK: usize = 4096;
|
||||
let mut entries = kmers.iter();
|
||||
let mut pending: Vec<(CanonicalKmer, &Vec<KmerDesc>)> = Vec::with_capacity(CHUNK);
|
||||
let mut batch: Vec<CanonicalKmer> = Vec::with_capacity(CHUNK);
|
||||
let mut found: Vec<Option<usize>> = Vec::with_capacity(CHUNK);
|
||||
loop {
|
||||
pending.clear();
|
||||
pending.extend(entries.by_ref().take(CHUNK).map(|(k, d)| (*k, d)));
|
||||
if pending.is_empty() {
|
||||
break;
|
||||
}
|
||||
stats.n_unique_kmers += pending.len();
|
||||
for l in 0..n_layer {
|
||||
stats.n_mphf_calls += 1;
|
||||
if let Some(slot) = self.find_in_layer(part_idx, l, *kmer) {
|
||||
by_layer[l].insert(slot, descs);
|
||||
on_event(QueryHit::Found(descs));
|
||||
stats.n_hits += 1;
|
||||
if pending.is_empty() {
|
||||
break;
|
||||
}
|
||||
let layer = self
|
||||
.get_layer(part_idx, l)
|
||||
.expect("layer within n_layer(part_idx)");
|
||||
batch.clear();
|
||||
batch.extend(pending.iter().map(|&(k, _)| k));
|
||||
stats.n_mphf_calls += batch.len();
|
||||
layer.find_slot_batch(&batch, &mut found);
|
||||
let mut i = 0;
|
||||
pending.retain(|&(_, descs)| {
|
||||
let hit = found[i];
|
||||
i += 1;
|
||||
match hit {
|
||||
Some(slot) => {
|
||||
by_layer[l].insert(slot, descs);
|
||||
on_event(QueryHit::Found(descs));
|
||||
stats.n_hits += 1;
|
||||
false
|
||||
}
|
||||
None => true,
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user