API reference¶

简体中文

This page summarizes the public API exported by latticegeom. Private modules and compiler internals are not compatibility surfaces.

Immutable declarations¶

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 is Cartesian. CellSite.cell_shift, Bond.cell_shift, and plaquette vertex shifts are integer primitive-cell coordinates. Type labels must be hashable.

Useful declaration methods:

Bond.reversed()
Plaquette.reversed()
UnitCell.with_reverse_bonds()

Finite lattice¶

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

Frequently used scalar properties are ndim, embedding_dim, n_cells, n_sites, n_bonds, and n_plaquettes.

Important arrays and values:

Attribute	Meaning
`basis`	primitive direct vectors, one per row
`extent`, `pbc`	finite cell counts and boundary flags
`cells`	finite primitive-cell coordinates
`positions`	finite Cartesian site positions
`site_cells`, `sublattice`	site-to-cell and site-in-cell mapping
`site_type_id`, `site_types`	compact and original site labels
`bonds`, `plaquettes`	compiled relation tables
`supercell_vectors`	finite simulation-cell direct vectors
`supercell_shifts`	compressed integer image classes
`supercell_translations`	Cartesian image translations
`reverse_super_idx`	image-class reversal map
`reciprocal_vectors`	primitive reciprocal vectors
`supercell_reciprocal_vectors`	folded reciprocal vectors

Coordinates and relations¶

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)

Queries¶

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 geometry¶

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 is "primitive" or "supercell"; bond phase gauge is "cell" or "position".

Plotting¶

lat.plot(**kwargs) delegates to plot_lattice(lat, **kwargs). See Visualization for display modes and value annotations.

Compiled tables¶

BondTable stores one row per canonical directed finite bond:

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

Derived properties are pairs, types, and crosses_boundary. indices(...) accepts the same exact filters as Lattice.find_bonds; reversed(reverse_super_idx) derives a conjugate table.

PlaquetteTable uses CSR-style storage:

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

Use vertices(index) and indices(type=..., type_id=..., unit_plaquette=..., crossing=...). PlaquetteBoundary exposes source, target, cell_shift, supercell_shift, and pairs for one directed perimeter.

Predefined constructors¶

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)

Capitalized aliases (Square, Triangular, and so on) call the same functions.

Unit-cell builders¶

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

UnitCellBuilder provides add_site, add_bond, add_plaquette, extend, and build. See the Geometry guide for composition examples.

Authoring tools¶

The following names live in latticegeom.tools, not the top-level namespace:

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 provides by_shell, summary, to_bonds, render_python, and freeze. See One-shot neighbor discovery.