Neighbor lists (vesin)¶

eOn uses vesin as the neighbor-list engine wherever the code owns pair finding itself. Do not reintroduce pot-local Verlet tables or O(N²) MIC loops for new work.

Layers¶

Layer	API	Backend
Python server geometry	`eon.geometry.neighbors.neighbor_list`	`vesin.NeighborList`
Process-atom shells / displace	`eon.atoms` / `get_process_atoms`	same
Classical C++ pair pots (LJ, Morse, LJCluster, QSC)	`eonc::VesinNeighbors`	`vesin_neighbors` (C)
Metatomic	pot-local call into vesin C	same `libvesin` / vendored TU
External engines (LAMMPS, VASP, ASE, …)	engine-owned	not eOn’s NL
Legacy Fortran pots (SW, FeHe, …)	still pot-local	migrate via vesin Fortran (`module vesin`)

Python¶

from eon.geometry import neighbor_list
nl = neighbor_list(structure, cutoff=4.0)

brute=True is API-compat only; the algorithm is always vesin.

C++¶

#include "eon/VesinNeighbors.h"
eonc::VesinNeighbors nl;
eonc::VesinNeighbors::Options opt{.cutoff = 5.0, .full = false,
                                  .return_distances = true, .return_vectors = true};
nl.compute(R, nAtoms, box9, opt);

Vector convention matches vesin: r_ij = r_j − r_i + S·H. eoncbase always links vesin (pkg-config / system / vendored).

How we measure (ASV, not one-off scripts)¶

Institutional timing is the existing ASV suite under benchmarks/:

ASV class	Fixture	Hits vesin-backed pot?
`TimePointMorsePt`	`data/point_morse_pt`	Morse force pairs
`TimeMinimizationLJCluster`	`data/min_lj_cluster`	LJCluster force pairs (many force evals)
`TimeSaddleSearchMorseDimer`	`data/one_pt_saddle_search`	Morse + saddle path
`TimeNEBMorsePt`	`data/neb_morse_pt`	Morse band forces

Mechanism (already in CI):

PR — Benchmark PR workflow builds eonclient on base SHA and head SHA with the PR’s benchmarks/ tree, runs asv run --set-commit-hash … --quick, then asv-perch comments the main→PR comparison.
main — ASV dashboard restores orphan branch asv-results, runs history, publishes with asv-tachyon → eondocs.org/bench / bench.eondocs.org.

Local (same as benchmarks/README.md):

pixi run meson setup bbdir --prefix=$CONDA_PREFIX --libdir=lib --buildtype release
pixi run meson install -C bbdir
pixi run bash -c 'pip install asv asv-tachyon'
pixi run asv machine --yes
pixi run asv run -E "existing:$(which python)" --quick

To compare a vesin-NL branch to main without waiting for GHA: build+install both commits’ clients (or sequential install) and use the same ASV class names; the PR workflow is the authoritative pair-wise run.

Not yet unified¶

Fortran Stillinger–Weber / FeHe / Aluminum / EDIP still build neighbors inside .f/.f90. Upstream vesin provides fortran/src/vesin.f90; wire under with_fortran and port pot generators next.