核心几何模型¶

English

两层结构¶

UnitCell 是小型声明层，保存 site、有向 bond 和有向 plaquette。Lattice 是针对 指定 extent 与边界条件编译得到的有限层。

两层都不保存模型参数。bond 的 type 是几何分类；下游模型自行决定它表示跃迁、 交换耦合还是其他参数。

模块边界¶

源码按职责划分：

definitions.py   不可变声明：Site、Bond、Plaquette、UnitCell
builders.py      临时 UnitCellBuilder 与精确原胞组合/变换
tables.py        只读 BondTable、PlaquetteTable 与 PlaquetteBoundary
_compiler.py     私有验证与有限几何编译流水线
lattice.py       公开 Lattice 对象、派生量与查询
predefined.py    常用晶格构造函数
reciprocal.py    倒空间坐标、相位、网格与可选 BZ 几何
plotting.py      基于编译几何的可选 Matplotlib 视图
tools/neighbors.py 显式的一次性近邻搜索与源码生成

_compiler.py 有意保持私有且内聚。只有某个阶段获得独立后端（例如 Rust 编译器） 或可被独立复用时，才值得继续拆分。

plotting.py 只消费公开编译数组并延迟导入 Matplotlib。它是诊断/视图层，不是 规范几何；Lattice 不保存颜色、artist 或渲染状态。

builders.py 只在声明阶段可变，输出仍是普通不可变 UnitCell。有限编译器因此 只有一种规范输入。make_unit_cell_supercell 接受保向整数矩阵，精确重映射所有 整数关系，而不是重新按笛卡尔距离搜索。

reciprocal.py 在每个相关方法中区分原胞与模拟超胞。坐标变换、规则网格、允许动量 和周期相位只依赖 NumPy。SciPy 仅在构造二维 Wigner--Seitz BrillouinZone 时 延迟导入。任何 Hamiltonian 系数都不会被接受或存储。

tools/neighbors.py 位于顶层公开 API 之外。只有作者显式请求时才搜索周期像，返回 可检查草稿并生成固定 Bond(...) 源码。UnitCell、Lattice 与预定义晶格都不 导入它。

近邻生成边界¶

自动近邻搜索按笛卡尔距离分组，适合为陌生结构生成初稿，但不能推断物理等价性。 等长方向可以具有不同跃迁，规范方向也不代表物理跃迁方向。因此作者必须使用分类函数 赋予类型，或手工修改生成声明。

搜索逐层枚举整数平移。访问半径 r 后，正格矢最小奇异值与原胞内最大 site 间距 给出所有未访问 bond 长度的下界。只有该下界超过目标壳层或 cutoff 后才终止，因此 对斜基矢和嵌入晶格也没有隐藏的固定周期像范围。

Bond 身份¶

原胞 bond 的身份为

(source site, target site, integer cell_shift, type)

它是有向的。反向关系交换端点并取 cell_shift 的负值。即使两个声明映射到相同 有限 site 对，也不会因此去重。

每条有限 bond 保存：

source, target, type_id, unit_bond, cell_shift, super_idx

unit_bond 区分共享同一类型的不同声明，type_id 则把用户认为几何等价的关系分组。 精确查询返回行索引而不是单条边，因为多重边是设计的一部分。

周期边界表示¶

设 E 为 extent，c 为有限 source cell，d 为声明的 cell_shift。对周期轴：

target_cell    = (c + d) mod E
boundary_shift = floor((c + d) / E)

所有不同的 boundary_shift 及其负值构成 Lattice.supercell_shifts。有限 bond 只存入这个小表的整数 super_idx。

因此展开后的笛卡尔端点为

positions[target] + supercell_translations[super_idx]

负向 shift、跨越多个有限超胞的长程 bond 和单原胞周期系统都保持精确。

Plaquette 存储¶

plaquette 是有序 (site, cell_shift) 顶点列表。有限 plaquette 使用 CSR 风格表示：

offsets, sites, super_idx, type_id, unit_plaquette, anchor_cell

因此一个晶格中可同时保存不同边数的多边形，同时仍使用平坦 NumPy 数组。方向和类型 绝不会从排序后的 site 编号集合推断。

PlaquetteBoundary 由编译后的整数坐标派生边界端点、原胞位移与模拟超胞位移， 不需要浮点位置查找。

性能边界¶

编译只循环遍历通常很少的原胞声明，有限原胞则由 NumPy 数组批量处理。图算法与第三方 格式转换未来可以作为可选适配器，但不应成为规范存储。

只有性能分析证明超大尺寸编译确实重要时，才应在同一 API 后面引入 Numba、Cython 或 Rust 后端。首个版本没有理由增加强制编译依赖。

发布边界¶

公开兼容面包括 latticegeom.__all__ 中的导出、文档化的 latticegeom.tools 建模 API，以及 Lattice、BondTable、PlaquetteTable 的公开只读列。 _compiler.py 与下划线开头的辅助函数保持私有。

发布前应运行完整测试、执行全部示例、构建发行包、在干净环境安装 wheel，并以 strict 模式构建本文档。可选功能必须继续延迟导入，使 NumPy-only 核心始终可用。