Core concepts¶

简体中文

Two geometry layers¶

UnitCell is the small declarative layer. It contains sites, directed bonds, and oriented plaquettes that repeat under primitive translations. Lattice is the compiled finite layer for one extent and boundary condition.

UnitCell + basis + extent + pbc  ->  Lattice
declarations                       read-only NumPy tables

Geometry types¶

Every site, bond, and plaquette accepts an arbitrary hashable type label. Labels describe geometry, not physics. Several bond directions may share one type, or equal- length directions may use different types. A downstream model decides how labels map to couplings.

type_id is the compact integer code stored in compiled tables. unit_bond and unit_plaquette identify the exact declaration, so geometry direction and coupling class do not have to be the same concept.

Directed bonds¶

A bond (source, target, cell_shift, type) points from source in cell R to target in cell R + cell_shift. Reverse bonds are not inserted automatically. Derive them with Bond.reversed(), UnitCell.with_reverse_bonds(), or Lattice.reversed_bonds().

Duplicate finite endpoints are retained. This is essential when different periodic images collapse onto the same pair of site IDs in a small cluster.

Oriented plaquettes¶

A plaquette is an ordered sequence of (site, cell_shift) vertices. Closure is implicit. Reversing the order changes orientation while keeping the geometry type. Consequently, up/down triangles can be different types, and clockwise/counterclockwise traversal remains an independent orientation choice.

Finite plaquettes are identified by their unit-cell template and anchor cell, never by a sorted set of wrapped site IDs.

cell_shift versus super_idx¶

cell_shift is primitive-cell topology and does not depend on finite size. super_idx is a compressed index describing how one compiled relation crosses the simulation box.

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 maps every image class to its negative. Index zero always represents no simulation-supercell crossing.

Topological and embedding dimensions¶

The number of basis rows is lat.ndim; the Cartesian width is lat.embedding_dim. They may differ, so a two-dimensional lattice can be embedded in three-dimensional space. Integer cell relations always have length ndim, while positions and bond vectors have length embedding_dim.

Immutability¶

Declarations are frozen dataclasses and compiled arrays are read-only. This protects the relation between lookup tables, periodic images, and reciprocal data. Use UnitCellBuilder for temporary mutable construction, then call build().