核心概念¶

English

两层几何¶

UnitCell 是小型声明层，包含在原始平移下重复的 site、有向 bond 和有向 plaquette。Lattice 是给定 extent 与边界条件后编译得到的有限层。

UnitCell + basis + extent + pbc  ->  Lattice
声明                                  只读 NumPy 表

几何类型¶

site、bond 和 plaquette 都接受任意可哈希的 type 标签。标签描述几何而不是物理。 多个方向可以共享一种类型，等长方向也可以具有不同类型。下游模型自行决定标签如何 映射为耦合常数。

type_id 是编译表中存储的紧凑整数编码。unit_bond 与 unit_plaquette 标识精确 声明，因此几何方向与耦合类别无需合并成同一概念。

有向 bond¶

bond (source, target, cell_shift, type) 从原胞 R 中的 source 指向原胞 R + cell_shift 中的 target。反向 bond 不会自动插入，可通过 Bond.reversed()、UnitCell.with_reverse_bonds() 或 Lattice.reversed_bonds() 显式派生。

即使多个关系在小周期簇上折叠成相同有限 site 端点，它们也不会被去重。这对保留真实 的周期 bond 重数至关重要。

有向 plaquette¶

plaquette 是有序的 (site, cell_shift) 顶点序列，闭合边隐式存在。反转顺序会 改变方向，但不改变几何类型。因此，上/下三角可以是不同类型，而顺/逆时针遍历仍是 独立的方向选择。

有限 plaquette 的身份由原胞模板与 anchor cell 决定，绝不会由排序后的有限 site 编号集合决定。

cell_shift 与 super_idx¶

cell_shift 是与有限尺寸无关的原胞拓扑；super_idx 是某条编译后关系如何穿越 模拟盒的压缩索引。

shift = lat.bonds.cell_shift[i]
image = lat.bonds.super_idx[i]
integer_supercell_shift = lat.supercell_shifts[image]
cartesian_translation = lat.supercell_translations[image]

lat.reverse_super_idx 把每个周期像类别映射到其负值。索引零始终表示未跨越模拟超胞。

拓扑维数与嵌入维数¶

基矢行数为 lat.ndim，笛卡尔坐标宽度为 lat.embedding_dim，两者可以不同。 因此二维晶格可以嵌入三维空间。整数原胞关系长度始终为 ndim，位置和 bond 向量 长度则为 embedding_dim。

不可变性¶

声明对象是冻结的 dataclass，编译数组只读。这保护了查询表、周期像和倒空间数据之间 的一致性。需要临时可变构造时使用 UnitCellBuilder，完成后调用 build()。