Module search 

Lattice neighbour search: the sites near a straight path segment, found by walking unit cells (step 20a of the M2 crystal plan).

Given an ion position, a direction, a search radius p_max and a segment length L, LatticeSearch::search returns every lattice site whose impact parameter against the segment is at most p_max, together with its distance along the path, ordered along the path. This is the geometric first step of a binary-collision search on explicit atom positions (Robinson and Torrens, Phys. Rev. B 9, 5008 (1974), doi:10.1103/PhysRevB.9.5008, describe the method; only the paper is used here, no code). The crystal flight model of the binary-collision engine (crate::ion::bca::crystal) calls it for every flight segment.

Geometry and units

Everything is in the crystal frame, metres (see the crystal module docs, “Frames”). The lattice is the infinite periodic crystal, tiled by the rectangular cell of Lattice::orthogonal_cell with edges (e_x, e_y, e_z): the conventional cube (e = (a, a, a)) for a cubic lattice, the orthohexagonal cell (e = (a, sqrt(3) a, c)) for a hexagonal one. Cell (i, j, k) holds the atoms (e_x (i + f_x), e_y (j + f_y), e_z (k + f_z)) for each fractional position f of that cell (site_position_in). There is no global atom list: the per-cell site list is built once in LatticeSearch::new, and memory use does not depend on how far from the origin the path lies.

For a unit direction d, a path start r0 and a site at r:

s  = (r - r0) . d             distance along the path
p² = | (r - r0) - s d |²      squared impact parameter

path_metrics is the single implementation of these two expressions; the cell walk and any reference scan must both go through it so that they agree bit for bit.

Boundary rule

A site is a candidate iff 0 <= s <= L and p² <= p_max² (evaluated in floating point exactly as written, on the values returned by path_metrics). Both ends are closed: a site exactly at the start of the segment (s = 0, e.g. the atom the ion starts on), exactly at its end (s = L) or exactly at the radius (p² = p_max²) is included. Sites behind the start (s < 0) are never returned. An empty result is not an error.

Ordering

Results are sorted by s ascending (f64::total_cmp); equal s (many sites at once for rays along low-index directions) is broken by the cell index (i, j, k) lexicographically and then the basis index. The order is a pure function of the inputs, so it is independent of thread count; a LatticeSearch is immutable after construction and holds no shared state.

Cell walk

The cell axis most parallel to the path is swept slab by slab. For each slab the path parameter range that can reach it (a cylinder point lies within p_max of the axis in every coordinate) is clipped to [0, L], which bounds the other two cell indices. Each cell in that box is skipped if its centre cannot be within p_max of the segment (the metrics are 1-Lipschitz in position, so a half-diagonal margin is conservative). All bounds are padded by 1e-6 times the longest cell edge so that rounding never drops a site that the exact comparison would keep.

Structs

Candidate

One lattice site found near the path.

LatticeSearch

Candidate-site search through an infinite periodic Lattice.

Functions

compare

The documented order: s, then cell index, then basis index.

path_metrics

Distance along the path and squared impact parameter of site for a path starting at origin with unit direction dir: s = (site - origin) . dir, p² = |(site - origin) - s dir|².

site_position

Position of basis site f (fractions of the cell edge) in cell cell of a cubic cell with edge a; site_position_in with three equal edges.

site_position_in

Position of site f (fractions of the cell edges) in cell cell of the rectangular cell with edges e: e_k (cell_k + f_k) per axis. Shared by the search and by reference scans.

unit_direction

The unit direction the search uses for direction (any finite, non-zero vector), computed exactly as in LatticeSearch::search_into, so that a caller can evaluate path_metrics on other points with the same bits.