Migrate the GVL core to Rust (Phases 0–5): numba-free, byte-identical, cargo-standalone

[d-laub]

Migrate the GVL core to Rust (Phases 0–5)

This is the big integration merge of the rust-migration branch. It ports GenVarLoader's core read/write data structures and algorithms from Python/numba to a self-contained Rust crate wrapped by a thin PyO3 (abi3) binding, and deletes numba from GVL's own code entirely. Python keeps only the ergonomic surface — Dataset indexing sugar, torch integration, validation/error messages — and dispatches into Rust for everything else.

Scope: 50 commits, 197 files, +29,790 / −2,366. Docs-and-tests-heavy: most of the line count is the differential-parity test suite and the migration roadmap.

Source of truth: docs/roadmaps/rust-migration.md — phase-by-phase tasks, measurements, and the byte-identical parity contract. Every claim below is recorded there with its checkpoint.

Why

• Eliminate the ~35 numba kernels scattered across the read/write paths (collapses the bug surface and the ~3 GB llvmlite JIT cost that GVL itself contributed).
• A self-contained, cargo test-able Rust crate usable from Rust directly, with a type system that shrinks the code + testing surface.
• Faster gvl.write()/update() and parity-or-better Dataset.__getitem__, with headroom for batch parallelism.

The migration contract (strangler fig + byte-identical parity)

Every kernel followed the same loop: implement in Rust on the native ragged layout → expose through src/ffi/ behind a Python-side backend switch → differential-test byte-identical against the numba/Python impl on property-generated inputs → flip the default to Rust and delete the numba impl in the same bundled PR. main stayed shippable at every step; numba removal was continuous, not a big-bang. The ragged layout is consumed from seqpro-core (a pyo3-free rlib, crates.io 0.1.0), not reimplemented in GVL.

What landed, by phase

Phase	Scope	Status	PR(s)
0 — Foundation & harness	src/ffi/ seam + first live kernel (intervals_to_tracks); reusable run-both-assert-byte-identical differential harness + hypothesis generators; cargo test wired into pixi; abi3 wheel confirmed; Carter baselines captured	✅	#241
1 — Ragged primitives	Extracted pyo3-free seqpro-core rlib owning the Ragged layout; ported the last ragged numba ops (to_padded, reverse_complement) to Rust; GVL consumes it as a crates.io dep; dropped awkward from the foundation	✅	seqpro [ML4GLand/SeqPro#60], gvl #240
2 — Genotype assembly + variant gather	get_diffs_sparse, choose_exonic_variants, the flat-variant gather/fill kernels; dtype-preserving dispatch (int32/float32 hot cores + arbitrary-dtype fallback, after a naive port silently corrupted float32 dosage / int16 FORMAT fields)	✅	landed on rust-migration
3 — Reconstruction + track realignment	The numba bulk + the big read-path win: reference assembly, haplotype reconstruct (singular+batch), insertion-fill, track realignment, RLE; five fused __getitem__ kernels (plain/annotated/spliced haps, annotated-spliced, fused tracks) each crossing the FFI boundary once; format 2.0 zero-copy SoA storage + scale-guard	✅	#245, opt rounds #248 #249 #250 #252
4 — Write / update pipeline	gvl.write()/update() fully Rust-backed and numba-free: single-pass streaming bigWig writer (SoA starts/ends/values.npy), COITrees table/annot overlap engine; dead legacy write paths deleted	✅	#253
5 — Consolidation + thin-binding cleanup	Deleted all remaining core numba kernels (count = 0); added rayon batch parallelism gated byte-identical to the serial golden; thin-shim audit (verdict: shim already thin); cargo-standalone + seqpro-core-released verification; perf re-baseline	✅	#259 (W4 A/B), #260 (W5), #261 (W6)
6 — Absorb genoray	Variant IO (VCF/PGEN + sparse genotypes) into the Rust stack	⬜ future / out of scope	—

Performance

Final single-thread rust-vs-numba __getitem__ A/B (Phase 5 W4, the last apples-to-apples comparison before numba was deleted; Carter, chr22_geuv, NUMBA_NUM_THREADS=1, full tables in docs/roadmaps/phase-5-w4-final-ab.md) — rust is parity-or-better on every mode:

Mode	rust ÷ numba
tracks-only	1.07×
haplotypes / tracks-seqs	1.66×
annotated	1.43×
variants	1.38×
variant-windows	4.58×

The annotated path went from the close-out laggard (0.65×) to a clear rust win after zero-copy interval marshalling + uninit output buffers; tracks-only went from a 0.63× regression to 1.07× after replacing per-interval ndarray slicing with raw-slice writes (#248); variant-windows collapsed an entire Python assembly pass into Rust (#250).

Write path (Phase 4, Carter, chr22_geuv): gvl.write() 1.934 s / 3.520 GB peak RSS; gvl.update() 0.081 s. The bigWig write slice is ~1.88× faster with ~28% less total allocation vs. the legacy path.

Rayon batch parallelism (Phase 5 W5): every read kernel has a parallel gate (should_parallelize, threshold = GVL_NUM_THREADS × 1 MiB) that dispatches into_par_iter(), never a raw *mut across threads, and is gated byte-identical to the serial golden (tests/parity/test_rayon_equivalence.py). The W6 re-baseline corpus stayed below the threshold so rayon ran serial there (a documented finding, not a regression); production-scale batches (SEQLEN≥131072 or BATCH≥256) cross it.

On-disk format & API changes (reviewer note)

• Format 2.0 storage: track intervals are now stored struct-of-arrays (starts/ends/values.npy sharing offsets.npy) so the memmaps cross the Python→Rust boundary zero-copy. Opening is gated; existing datasets migrate in place via gvl.migrate. This also closes a rust-only OOM-at-scale defect where the AoS layout forced a full per-sample-scale np.ascontiguousarray copy every batch (locked by tests/integration/test_scale_guard.py).
• numba backend & dispatch removed: the GVL_BACKEND env var and python/genvarloader/_dispatch.py are gone — Python calls Rust directly. No runtime backend switch remains.
• Unsupported track types now raise TypeError (the dead custom-IntervalTrack write path was removed).
• Deps: seqpro ≥ 0.20 (Rust-backed Ragged) and the seqpro-core 0.1.0 crates.io crate; awkward dropped from hot paths.

Verification gate (2026-06-27, HEAD of branch)

• pytest whole tree: 973 passed / 44 skipped / 5 xfailed / 0 failed (parity + dataset + unit subset 692/35/2, matching the W5 baseline exactly).
• cargo test: 114 passed — and the crate is standalone-testable (cargo test --release from a clean shell, no pixi/PYO3_PYTHON needed).
• Lint/types: ruff check + ruff format clean; pyrefly clean; clippy clean (warnings only, 0 errors).
• Packaging: abi3 wheel builds clean.

Known caveats (not blockers)

• No more numba A/B. numba was deleted in W5, so the W4 table above is the last direct comparison; all later perf signals are rust serial-vs-rayon (same session) + deterministic counts.
• Peak RSS (~3.5 GB) is dominated by seqpro's transitive numba JIT (~3.2 GB), not GVL. seqpro's own numba removal is upstream (ML4GLand/SeqPro) and out of scope here.
• Two numba-bug sub-domains are excluded from the parity oracle (the #242-family start>=clen clip and a reconstruct trailing-under-write case): numba is the buggy side and is not a valid oracle there; rust is correct in both. Documented at the Phase 3 gate.
• Perf is on a shared HPC node (Carter); absolute wall-clock drifts ≥2× across sessions, so the durable signals are byte-identical parity + same-session ratios, not cross-session absolute numbers.
• Phase 6 (absorb genoray) is deliberately deferred — the crate still depends on Python genoray for variant IO.

Merge note

Per project policy this should land no-squash to preserve the per-phase commit history. After merge, backfill the Phase 5 _PR: link in docs/roadmaps/rust-migration.md (currently —), consistent with the prior-phase convention.

🤖 Generated with Claude Code