API 参考¶

本页概括 latticegeom 导出的公开 API。私有模块和编译器内部实现不属于兼容性承诺。

不可变声明¶

Site(position, type=0)
CellSite(site, cell_shift=None)
Bond(source, target, cell_shift=None, type=0)
Plaquette(vertices, type=0)
UnitCell(sites, bonds=(), plaquettes=())

Site.position 使用笛卡尔坐标。CellSite.cell_shift、Bond.cell_shift 与 plaquette 顶点 shift 使用整数原胞坐标。类型标签必须可哈希。

常用声明方法为 Bond.reversed()、Plaquette.reversed() 与 UnitCell.with_reverse_bonds()。

有限晶格¶

Lattice(basis, unit_cell, extent, *, pbc=True, name=None)

常用标量属性包括 ndim、embedding_dim、n_cells、n_sites、n_bonds 和 n_plaquettes。

属性	含义
`basis`	按行排列的原始正格矢
`extent`, `pbc`	有限原胞数与边界标志
`cells`	有限原胞坐标
`positions`	有限 site 的笛卡尔位置
`site_cells`, `sublattice`	site 到原胞和原胞内编号的映射
`site_type_id`, `site_types`	紧凑 site 类型与原始标签
`bonds`, `plaquettes`	编译后的关系表
`supercell_vectors`	有限模拟超胞正格矢
`supercell_shifts`	压缩后的整数周期像类别
`supercell_translations`	周期像的笛卡尔平移
`reverse_super_idx`	周期像类别反向映射
`reciprocal_vectors`	原始倒格矢
`supercell_reciprocal_vectors`	折叠后的倒格矢

坐标与关系¶

super_index(shift)
translation(cell_shift)
site_id(cell, site=0, *, wrap=False)
cell_and_site(site_id)
position(site_id, super_idx=0)
bond_vectors()
unit_bond_vectors()
reversed_bonds()
edge_conjugate(source, target, super_idx=0)

查询¶

edges(*, type=None, include_reverse=False, return_type=False, return_super_idx=False)
find_bonds(*, type=None, type_id=None, source=None, target=None,
           cell_shift=None, super_idx=None, unit_bond=None, crossing=None)
plaquette_positions(index)
plaquette_boundary(index)
plaquette_centers()
plaquette_signed_areas(*, projection=None)
adjacency_list(*, include_reverse=True)

倒空间¶

reciprocal_coordinates(k, *, cell="primitive", check_span=True, atol=1e-10)
k_from_coordinates(coordinates, *, cell="primitive")
sample_kmesh(shape, *, cell="primitive", centered=False, endpoint=False)
allowed_momenta(*, centered=False)
translation_phases(k, *, sign=-1.0)
unit_bond_phases(k, *, sign=-1.0, gauge="cell")
brillouin_zone(*, cell="primitive")

cell 可取 "primitive" 或 "supercell"；bond phase gauge 可取 "cell" 或 "position"。

绘图¶

lat.plot(**kwargs) 委托给 plot_lattice(lat, **kwargs)。显示模式和数值标注见可视化。

编译表¶

BondTable 每行保存一条规范有向有限 bond：

source, target, type_id, super_idx, unit_bond, cell_shift, type_labels

派生属性包括 pairs、types 与 crosses_boundary。indices(...) 接受与 Lattice.find_bonds 相同的精确筛选条件；reversed(reverse_super_idx) 派生共轭表。

PlaquetteTable 使用 CSR 风格存储：

offsets, sites, super_idx, type_id, unit_plaquette, anchor_cell, type_labels

使用 vertices(index) 与 indices(type=..., type_id=..., unit_plaquette=..., crossing=...)。PlaquetteBoundary 为一条有向边界提供 source、target、 cell_shift、supercell_shift 和 pairs。

预定义构造函数¶

chain(length, *, pbc=True, a=1.0, bond_type="a1")
square(extent, *, pbc=True, a=1.0, bond_types=None)
triangular(extent, *, pbc=True, a=1.0, bond_types=None)
triangular_nnn(extent, *, pbc=True, a=1.0, bond_types=None)
honeycomb(extent, *, pbc=True, a=1.0, bond_types=None)
kagome(extent, *, pbc=True, a=1.0, bond_types=None)
grid(extent, *, pbc=True, spacings=1.0, bond_types=None)
hypercubic(length, ndim=1, *, pbc=True, a=1.0, bond_types=None)
bcc(extent, *, pbc=True, a=1.0, bond_types=None)
fcc(extent, *, pbc=True, a=1.0, bond_types=None)
diamond(extent, *, pbc=True, a=1.0, bond_types=None)
pyrochlore(extent, *, pbc=True, a=1.0, bond_types=None)

大写别名（如 Square、Triangular）调用同一函数。

原胞构造器¶

UnitCellBuilder(unit_cell=None)
translate_unit_cell(unit_cell, offset)
merge_unit_cells(*unit_cells)
make_unit_cell_supercell(basis, unit_cell, transform)

UnitCellBuilder 提供 add_site、add_bond、add_plaquette、extend 与 build。组合示例见几何使用指南。

建模工具¶

以下名称位于 latticegeom.tools，不会从顶层命名空间导出：

discover_neighbors(basis, sites, *, shells=None, max_distance=None,
                   atol=0.0, rtol=1e-8, include_coincident=False,
                   max_search_radius=64, warn=True)
NeighborCandidate
NeighborSearchResult
NeighborDiscoveryWarning

NeighborSearchResult 提供 by_shell、summary、to_bonds、render_python 和 freeze。详见一次性近邻搜索。