One-shot neighbor discovery

简体中文

Distance-based neighbor discovery is an explicit authoring tool. It is not imported by the top-level package, called by Lattice, or used by predefined constructors.

from latticegeom import Site
from latticegeom.tools import discover_neighbors

draft = discover_neighbors(
    basis=((1.0, 0.0), (0.35, 0.9)),
    sites=[Site((0.0, 0.0), "A")],
    shells=2,
)
print(draft.summary())

Use exactly one criterion:

  • shells=n selects the first n global Cartesian distance shells;
  • max_distance=r selects every relation within an inclusive Cartesian cutoff;
  • omitting both defaults to shells=1.

Each NeighborCandidate exposes source, target, integer cell_shift, Cartesian vector, distance, and one-based shell. Only one deterministic orientation of each undirected geometric relation is returned.

Assign geometry types

Distance equality does not imply physical equivalence. Use a shell map for isotropic geometry:

bonds = draft.to_bonds(
    type_by_shell={1: "nearest", 2: "next_nearest"},
)

Use a classifier when directions or sublattices need distinct labels:

def classify(candidate):
    dx, dy = candidate.cell_shift
    return (candidate.shell, dx, dy)

bonds = draft.to_bonds(classify=classify)

With include_reverse=True, the classifier sees each forward and reverse candidate separately. Canonical orientation is deterministic but has no inferred physical meaning.

Freeze reviewed source

print(draft.render_python(type_by_shell={1: "nearest", 2: "next_nearest"}))

draft.freeze(
    "fixed_bonds.py",
    type_by_shell={1: "nearest", 2: "next_nearest"},
)

The generated file imports Bond and contains explicit declarations only. freeze() refuses to overwrite an existing file unless overwrite=True. Commit the reviewed result and remove discovery from normal construction code.

Every search emits NeighborDiscoveryWarning by default. warn=False is available for controlled authoring scripts, but it does not change the intended one-shot workflow.

Search completeness and tolerances

The tool expands integer translation shells until a lower bound based on the smallest singular value of the basis proves that no unseen image can enter the requested range. It therefore does not assume that searching adjacent cells is sufficient for a skew basis.

The default shell grouping uses relative tolerance (rtol=1e-8) and zero absolute tolerance, so changing between lattice units, angstroms, and metres does not merge all small distances. Coincident sites are excluded unless include_coincident=True. max_search_radius is a safety limit, not the normal stopping rule.