Struct SpatialGrid 

pub struct SpatialGrid { /* private fields */ }

Spatial hash grid for O(n) neighbor queries in particle simulations.

Divides space into a uniform 3D grid of grid_dim^3 cells. Uses a CSR (Compressed Sparse Row) flat-buffer layout: indices holds all particle indices packed contiguously, and cell_offsets[h]..cell_offsets[h+1] gives the slice for cell h. This eliminates per-cell heap allocations and improves cache locality for neighbor queries.

Build flow

1. Call clear() to reset counts.
2. Call insert() for each particle.
3. Call build() to finalize the CSR layout.
4. Call query_neighbors_into() for lookups.

Implementations

impl SpatialGrid

pub fn new(cell_size: Fix128, grid_dim: usize) -> Self

Create a new spatial grid.

• cell_size: Side length of each cubic cell (should match the interaction radius for best performance).
• grid_dim: Number of cells along each axis. Total cells = grid_dim^3.

pub fn clear(&mut self)

Reset the grid for a fresh build pass.

pub fn hash(&self, pos: Vec3Fix) -> usize

Compute the cell index for a given position.

Each axis is clamp(floor(x / cell_size) + grid_dim / 2, 0, grid_dim - 1) for every Fix128 input: positions far outside the grid (up to the ends of the Fix128 range, or with a cell size down to 2^-64) land in the border cell on their side, never panic and never wrap, in both debug and release builds.

A grid built with grid_dim = 0 has no cells; every position hashes to 0, and callers already guard h < total_cells (which is also 0) before using the result.

pub fn insert(&mut self, idx: usize, pos: Vec3Fix)

Record a particle insertion (pass 1: count only).

Call build() after all insertions to finalize the CSR layout.

pub fn build(&mut self)

Finalize the CSR layout after all insert() calls.

Converts the temporary (cell, particle) pairs into a proper prefix-sum offset table and sorted flat index buffer.

pub fn query_neighbors_into( &self, pos: Vec3Fix, _radius_sq: Fix128, neighbors: &mut Vec<usize>, )

Collect all particle indices in the 3x3x3 neighborhood of pos.

Results are appended to neighbors (which is cleared first). _radius_sq is reserved for future distance filtering.