一次性近邻搜索¶

基于距离的近邻搜索是显式的建模期工具。顶层包不会导入它，Lattice 不会调用它，预定义晶格也不会在运行时使用它。

搜索¶

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())

只使用一种搜索条件：

shells=n 选择全局最短的前 n 个笛卡尔距离壳层；
max_distance=r 选择不超过闭区间 cutoff 的全部关系；
两者都省略时默认为 shells=1。

每个 NeighborCandidate 提供 source、target、整数 cell_shift、笛卡尔 vector、distance 和从一开始的 shell。每个无向几何关系只返回一个确定性方向。

分配几何类型¶

等距离不代表物理等价。各向同性几何可以按壳层分配：

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

方向或子晶格需要区分时使用分类函数：

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

bonds = draft.to_bonds(classify=classify)

include_reverse=True 时，分类函数会分别看到正、反候选。规范方向只保证确定性，不携带推断出的物理意义。

冻结审查后的源码¶

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"},
)

生成文件导入 Bond 并只包含显式声明。freeze() 默认拒绝覆盖已有文件；只有显式设置 overwrite=True 才会覆盖。应提交审查后的结果，并从正常构造代码中移除搜索。

每次搜索默认发出 NeighborDiscoveryWarning。受控的建模脚本可以设置 warn=False，但这不会改变它只应运行一次的工作流边界。

完备性与容差¶

工具逐层扩大整数平移范围，直到由基矢最小奇异值给出的下界证明：未访问的周期像不可能进入目标距离范围。因此即使基矢高度倾斜，也不假设相邻原胞搜索已经足够。

默认壳层分组采用相对容差 rtol=1e-8 和零绝对容差，因此在晶格单位、埃和米之间切换不会把所有短距离合并。重合 site 默认排除，只有 include_coincident=True 时包含。max_search_radius 是安全上限，不是正常终止条件。