umap-rs: Instructions file for Codex

Notes for future agents/developers

Critical things that look wrong but are correct

UnsafeSyncCell and data races

src/layout/optimize_layout_euclidean.rs:30-57 implements UnsafeSyncCell<T> which intentionally allows data races. This is correct for parallel SGD:

• Multiple threads write to the same embedding array without locks
• Races occur when two edges share a vertex (rare)
• Lost updates are acceptable because SGD is stochastic
• This matches Python UMAP's Numba parallel=True behavior
• Academic justification: Hogwild! algorithm (Recht et al., 2011)

Do NOT "fix" this by adding locks/atomics. Performance would tank and it's unnecessary.

ParallelVec and UnsafeCell usage

src/umap/fuzzy_simplicial_set.rs uses ParallelVec<T> for parallel CSR construction. This uses std::cell::UnsafeCell<Vec<T>> internally, which is required for correct unsafe code:

• UnsafeCell<T> is Rust's primitive for interior mutability
• It tells the compiler "the T inside may be mutated through shared references"
• Without it, the compiler assumes &Vec<T> means immutable contents and may optimize incorrectly (UB)
• Correct pattern: UnsafeCell<Vec<T>> - the Vec's contents may be mutated
• Wrong pattern: UnsafeCell<*mut T> - only wraps the pointer, not the data

struct ParallelVec<T> {
  data: UnsafeCell<Vec<T>>,  // Vec contents may be mutated through &self
}
unsafe impl<T: Send> Sync for ParallelVec<T> {}  // Safe if disjoint writes

impl<T> ParallelVec<T> {
  unsafe fn write(&self, index: usize, value: T) {
    let vec = &mut *self.data.get();  // UnsafeCell::get() → *mut Vec<T>
    *vec.get_unchecked_mut(index) = value;
  }
  fn into_inner(self) -> Vec<T> {
    self.data.into_inner()  // Extract Vec after parallel work
  }
}

Key invariant: Each row i writes only to [indptr[i]..indptr[i+1]], which are disjoint by construction of the prefix sum.

Lifetime patterns in fuzzy_simplicial_set.rs

FuzzySimplicialSet<'a, 'd> has two lifetimes but no bound between them. This is intentional: