qlinks.lattice

class qlinks.lattice.BoundaryCondition(*values)

Bases: StrEnum

Supported lattice boundary conditions.

OPEN = 'open'

PERIODIC = 'periodic'

class qlinks.lattice.ChainLattice(length, boundary_condition=BoundaryCondition.OPEN)

Bases: LatticeGraph

One-dimensional chain.

Sites:

i = 0, …, L - 1

Open boundary:

links i -> i + 1 for i = 0, …, L - 2

Periodic boundary:

same as open, plus L - 1 -> 0

__init__(length, boundary_condition=BoundaryCondition.OPEN)

sites: tuple[Site, ...]

links: tuple[Link, ...]

plaquettes: tuple[Plaquette, ...]

boundary_condition: BoundaryCondition | str

translations: Mapping[tuple[int, tuple[int, ...]], int]

class qlinks.lattice.HoneycombLattice(lx, ly, boundary_condition=BoundaryCondition.OPEN)

Bases: LatticeGraph

Honeycomb lattice in a brick-wall representation.

Unit cell:

A(x, y), sublattice 0 B(x, y), sublattice 1

Site id:

site_id(x, y, sublattice) = 2 * (x * ly + y) + sublattice

Links:

z: A(x, y) -> B(x, y) x: A(x, y) -> B(x - 1, y) y: A(x, y) -> B(x, y - 1)

Hexagon plaquette around cell (x, y):

A(x,y) B(x,y) A(x+1,y) B(x+1,y-1) A(x+1,y-1) B(x,y-1)

This representation is convenient for QDM/QLM hexagon ring exchange.

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN)

site_id(x, y, sublattice)

qdm_plaquette_ids()

qlm_plaquette_ids()

hexagon_plaquette_id(x, y)

lx

ly

class qlinks.lattice.KagomeLattice(lx, ly, boundary_condition=BoundaryCondition.OPEN, *, include_triangles=True, include_hexagons=True)

Bases: LatticeGraph

Two-dimensional kagome lattice with a three-site triangular unit cell.

Unit cell:

A(x, y), sublattice 0 B(x, y), sublattice 1 C(x, y), sublattice 2

Primitive vectors:

a1 = (1, 0) a2 = (1/2, sqrt(3)/2)

Link convention:

Each unit cell contributes six nearest-neighbor bonds:

ab : A(x, y) -> B(x, y) ab_prev : A(x, y) -> B(x - 1, y) ac : A(x, y) -> C(x, y) ac_prev : A(x, y) -> C(x, y - 1) bc : B(x, y) -> C(x, y) bc_next : B(x, y) -> C(x + 1, y - 1)

Plaquettes:

triangle_up / triangle_down are included for visualization and local geometry diagnostics. Kagome QDM/QLM resonance terms use only the hexagon plaquettes returned by qdm_plaquette_ids() and qlm_plaquette_ids().

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN, *, include_triangles=True, include_hexagons=True)

site_id(x, y, sublattice)

classmethod link_cell_displacement(kind)

qdm_plaquette_ids()

qlm_plaquette_ids()

hexagon_plaquette_id(x, y)

lx

ly

class qlinks.lattice.LatticeGraph(sites, links, plaquettes=(), boundary_condition=BoundaryCondition.OPEN, translations=<factory>)

Bases: object

Pure geometry/topology object.

This class knows only about sites, links, incidence, adjacency, plaquettes, and translations. It knows nothing about physical variables, Gauss laws, dimers, spins, Hamiltonians, or constraints.

sites: tuple[Site, ...]

links: tuple[Link, ...]

plaquettes: tuple[Plaquette, ...]

boundary_condition: BoundaryCondition | str

translations: Mapping[tuple[int, tuple[int, ...]], int]

property ndim: int

property num_sites: int

property num_links: int

property num_plaquettes: int

property site_ids: ndarray[tuple[Any, ...], dtype[int64]]

property link_ids: ndarray[tuple[Any, ...], dtype[int64]]

property plaquette_ids: ndarray[tuple[Any, ...], dtype[int64]]

property link_endpoints: ndarray[tuple[Any, ...], dtype[int64]]

Array of shape (num_links, 2), with columns [source, target].

property site_cells: ndarray[tuple[Any, ...], dtype[int64]]

property site_positions: ndarray[tuple[Any, ...], dtype[float64]]

property primitive_vectors: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]

property basis_offsets: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]

embedded_position(cell, sublattice=0)

site_embedded_position(site_id)

incidence_matrix()

Return the oriented site-link incidence matrix B.

Convention:

B[source, link] = -1 B[target, link] = +1

This is the natural convention for divergence-like constraints.

unoriented_adjacency_matrix()

Return symmetric site-site adjacency matrix.

incident_links(site_id)

incoming_links(site_id)

outgoing_links(site_id)

neighbors(site_id)

plaquette_links(plaquette_id)

plaquette_orientations(plaquette_id)

plaquette_boundary(plaquette_id)

Return the oriented boundary of a plaquette.

plaquette_sites(plaquette_id)

plaquette_incidence_matrix()

Return oriented link-plaquette incidence matrix.

The matrix has shape (num_links, num_plaquettes) and entries

B[link, plaquette] = +1 or -1

depending on the orientation of the link in the plaquette boundary.

plaquette_anchor_cell(plaquette_id)

plaquette_id_from_anchor(cell, *, kind=None)

canonical_cell(cell)

translate_site(site_id, displacement)

Translate a site by an integer lattice displacement.

Returns None if the translation is not defined, e.g. for an open-boundary site translated out of the system.

oriented_link_between(source, target)

Return (link_id, orientation) for a directed traversal source -> target.

orientation = +1 means traversal agrees with stored link orientation. orientation = -1 means traversal is opposite to stored link orientation.

as_metadata()

__init__(sites, links, plaquettes=(), boundary_condition=BoundaryCondition.OPEN, translations=<factory>)

class qlinks.lattice.Link(id, source, target, kind='', wrap=False)

Bases: object

Oriented link metadata.

The link orientation is source -> target.

This orientation defines the sign convention in the incidence matrix:

incidence[source, link] = -1 incidence[target, link] = +1

kind:

A geometry-dependent link type, e.g. “x”, “y”, “diag”, etc.

wrap:

True if this link crosses a periodic boundary.

id: int

source: int

target: int

kind: str

wrap: bool

__init__(id, source, target, kind='', wrap=False)

qlinks.lattice.LinkId

alias of int

class qlinks.lattice.OrientedLink(link_id, orientation)

Bases: object

A link with an orientation relative to a plaquette boundary.

orientation = +1 means the plaquette traverses the link along its stored source -> target direction.

orientation = -1 means the plaquette traverses the link opposite to its stored source -> target direction.

link_id: int

orientation: int

__init__(link_id, orientation)

class qlinks.lattice.Plaquette(id, links, orientations, sites, kind='', anchor_cell=())

Bases: object

Oriented elementary loop.

links:

Link ids around the loop.

orientations:

For each link in the loop:

+1 if traversed along the stored link orientation, -1 if traversed opposite to the stored link orientation.

sites:

Site ids around the loop. This is metadata useful for debugging, plotting, and later local operator construction.

kind: Geometry-dependent plaquette type.

anchor_cell: Unit-cell coordinate used to label this plaquette.

id: int

links: tuple[int, ...]

orientations: tuple[int, ...]

sites: tuple[int, ...]

kind: str

anchor_cell: tuple[int, ...]

property boundary: tuple[OrientedLink, ...]

Return the oriented boundary links of this plaquette.

__init__(id, links, orientations, sites, kind='', anchor_cell=())

qlinks.lattice.PlaquetteId

alias of int

class qlinks.lattice.Site(id, cell, sublattice=0, position=())

Bases: object

Geometry-level site metadata.

id:

Consecutive integer site id.

cell:

Unit-cell coordinate, e.g. (x,), (x, y), etc.

sublattice:

Sublattice label. For Bravais lattices, this can be 0.

position:

Real-space embedding coordinate. This is for geometry/debugging/plotting. It should not be used as the primary index in performance-sensitive code.

id: int

cell: tuple[int, ...]

sublattice: int

position: tuple[float, ...]

__init__(id, cell, sublattice=0, position=())

qlinks.lattice.SiteId

alias of int

class qlinks.lattice.SquareLattice(lx, ly, boundary_condition=BoundaryCondition.OPEN)

Bases: LatticeGraph

Two-dimensional square lattice.

Site id convention:

site_id(x, y) = x * Ly + y

Link orientation convention:

x-link: (x, y) -> (x + 1, y) y-link: (x, y) -> (x, y + 1)

Plaquette orientation convention:

counter-clockwise loop:

bottom edge: +x right edge: +y top edge: -x left edge: -y

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN)

site_id(x, y)

canonical_cell(cell)

plaquette_id_from_cell(x, y)

square_plaquette_id(x, y)

lx

ly

class qlinks.lattice.TriangularLattice(lx, ly, boundary_condition=BoundaryCondition.OPEN, *, include_triangles=True, include_rhombi=True)

Bases: LatticeGraph

2D triangular lattice.

Site convention:

site_id(x, y) = x * ly + y

Primitive vectors:

a1 = (1, 0) a2 = (1/2, sqrt(3)/2)

Link directions:

a: (x, y) -> (x + 1, y) b: (x, y) -> (x, y + 1) c: (x, y) -> (x - 1, y + 1)

Plaquettes:

triangle_up / triangle_down:

elementary triangular loops.

rhombus_ab / rhombus_bc / rhombus_ca:

four-link lozenge loops. These are the natural QDM resonance plaquettes on triangular lattices.

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN, *, include_triangles=True, include_rhombi=True)

site_id(x, y)

qdm_plaquette_ids()

qlm_plaquette_ids(*, use_triangles=False)

triangular_plaquette_id(x, y, *, kind)

rhombus_plaquette_id(x, y, *, kind)

lx

ly