几何使用指南¶

预定义晶格¶

所有构造函数都接受有限尺寸和边界条件。小写名称是规范 API，大写别名用于方便迁移。

构造函数	每原胞 site 数	内置 plaquette	`a` 的含义
`chain`	1	无	最近邻距离
`square`	1	正方形	最近邻距离
`triangular`	1	上/下三角	最近邻距离
`triangular_nnn`	1	上/下三角	最近邻距离
`honeycomb`	2	六边形	最近邻距离
`kagome`	3	上/下三角与六边形	最近邻距离
`grid` / `hypercubic`	1	无	各轴距离 / 公共距离
`bcc` / `fcc`	1	无	常规立方晶格常数
`diamond`	2	无	常规立方晶格常数
`pyrochlore`	4	带类型的四面体面	常规立方晶格常数

bond_types= 只重分类已声明的方向，不赋予耦合数值。

声明自定义原胞¶

from latticegeom import Bond, Lattice, Plaquette, Site, UnitCell

cell = UnitCell(
    sites=[Site((0.0, 0.0), "A"), Site((0.5, 0.0), "B")],
    bonds=[
        Bond(0, 1, (0, 0), "intracell"),
        Bond(1, 0, (1, 0), "intercell"),
    ],
    plaquettes=[
        Plaquette(
            [(0, (0, 0)), (1, (0, 0)), (0, (1, 0)), (1, (0, 1))],
            "loop",
        )
    ],
)

lat = Lattice(
    basis=((1.0, 0.0), (0.2, 1.0)),
    unit_cell=cell,
    extent=(8, 5),
    pbc=(True, False),
)

site 位置是相对于原胞原点的笛卡尔偏移。每个关系的 shift 都是原始基矢下的整数坐标。 plaquette 至少包含三个互不相同的顶点；不要重复首顶点来闭合。

边界条件¶

pbc=True 或 False 可应用于全部方向；布尔序列可表达混合边界。越过开放轴有限范围的关系会被丢弃。周期轴关系会折回，同时保留精确的周期像位移。

site = lat.site_id((7, 2), site=1)
cell_coord, sublattice = lat.cell_and_site(site)
unfolded = lat.position(site, super_idx=lat.super_index((1, 0)))

site_id(..., wrap=True) 可以折叠周期轴，但不会穿过开放边界。

查询 bond 与 plaquette¶

rows = lat.find_bonds(
    type="intercell",
    cell_shift=(1, 0),
    crossing=True,
)

plaquettes = lat.plaquettes.indices(type="loop", crossing=False)
sites, images = lat.plaquettes.vertices(plaquettes[0])
boundary = lat.plaquette_boundary(plaquettes[0])

bond 查询返回行索引，因为多重边是有意保留的。PlaquetteBoundary 返回有向边界端点、原胞位移与模拟超胞位移。plaquette_positions、plaquette_centers 和 plaquette_signed_areas 使用展开后的几何。

轻量图代码可使用 lat.edges(...) 与 lat.adjacency_list(...)；性能敏感代码应直接访问 lat.bonds。

组合原胞¶

UnitCellBuilder 只在建模阶段可变：

from latticegeom import UnitCellBuilder

builder = UnitCellBuilder(lower_cell)
upper = builder.extend(
    lower_cell,
    offset=(0.0, 0.0, 0.3),
    site_type_map=lambda label: ("upper", label),
)
builder.add_bond(0, upper[0], (0, 0), "interlayer")
bilayer = builder.build()

translate_unit_cell 平移笛卡尔 site 偏移，merge_unit_cells 合并声明并重编号。

放大或倾斜声明原胞¶

使用保向整数变换可精确构造晶体学或磁性超胞，而无需按距离重新搜索 bond：

from latticegeom import Lattice, make_unit_cell_supercell

new_basis, new_cell = make_unit_cell_supercell(
    lat.basis,
    lat.unit_cell,
    ((2, 1), (0, 1)),
)
enlarged = Lattice(new_basis, new_cell, (3, 3), pbc=True)

该变换会精确重映射 site 代表、bond shift 与 plaquette 顶点；行列式给出新声明原胞包含的旧原胞数。