qlinks.lattice

qlinks.lattice#

class qlinks.lattice.BoundaryCondition(*values)[source]#

Bases: StrEnum

OPEN = 'open'#

PERIODIC = 'periodic'#

class qlinks.lattice.ChainLattice(length, boundary_condition=BoundaryCondition.OPEN)[source]#

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

Parameters:

length (int)
boundary_condition (BoundaryCondition | str)

__init__(length, boundary_condition=BoundaryCondition.OPEN)[source]#

Parameters:

length (int)
boundary_condition (BoundaryCondition | str)

Return type:

None

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)[source]#

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.

Parameters:

lx (int)
ly (int)
boundary_condition (BoundaryCondition | str)

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN)[source]#

Parameters:

lx (int)
ly (int)
boundary_condition (BoundaryCondition | str)

Return type:

None

site_id(x, y, sublattice)[source]#

Parameters:

x (int)
y (int)
sublattice (int)

Return type:

int

qdm_plaquette_ids()[source]#

qlm_plaquette_ids()[source]#

hexagon_plaquette_id(x, y)[source]#

Parameters:

x (int)
y (int)

Return type:

int

lx#

ly#

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

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.

Parameters:

sites (tuple[Site, ...])
links (tuple[Link, ...])
plaquettes (tuple[Plaquette, ...])
boundary_condition (BoundaryCondition | str)
translations (Mapping[tuple[int, tuple[int, ...]], int])

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)[source]#

Parameters:

cell (tuple[int, ...])
sublattice (int)

Return type:

tuple[float, …]

site_embedded_position(site_id)[source]#

Parameters:: site_id (int)
Return type:: tuple[float, …]

incidence_matrix()[source]#

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.

Return type:: csr_array

unoriented_adjacency_matrix()[source]#

Return symmetric site-site adjacency matrix.

Return type:: csr_array

incident_links(site_id)[source]#

Parameters:: site_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

incoming_links(site_id)[source]#

Parameters:: site_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

outgoing_links(site_id)[source]#

Parameters:: site_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

neighbors(site_id)[source]#

Parameters:: site_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

plaquette_links(plaquette_id)[source]#

Parameters:: plaquette_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

plaquette_orientations(plaquette_id)[source]#

Parameters:: plaquette_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

plaquette_boundary(plaquette_id)[source]#

Return the oriented boundary of a plaquette.

Parameters:: plaquette_id (int)
Return type:: tuple[OrientedLink, …]

plaquette_sites(plaquette_id)[source]#

Parameters:: plaquette_id (int)
Return type:: ndarray[tuple[Any, …], dtype[int64]]

plaquette_incidence_matrix()[source]#

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.

Return type:: csr_array

plaquette_anchor_cell(plaquette_id)[source]#

Parameters:: plaquette_id (int)
Return type:: tuple[int, …]

plaquette_id_from_anchor(cell, *, kind=None)[source]#

Parameters:

cell (tuple[int, ...])
kind (str | None)

Return type:

int

canonical_cell(cell)[source]#

Parameters:: cell (tuple[int, ...])
Return type:: tuple[int, …]

translate_site(site_id, displacement)[source]#

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.

Parameters:

site_id (int)
displacement (tuple[int, ...])

Return type:

int | None

oriented_link_between(source, target)[source]#

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.

Parameters:

source (int)
target (int)

Return type:

tuple[int, int]

as_metadata()[source]#

Return type:: dict[str, object]

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

Parameters:

sites (tuple[Site, ...])
links (tuple[Link, ...])
plaquettes (tuple[Plaquette, ...])
boundary_condition (BoundaryCondition | str)
translations (Mapping[tuple[int, tuple[int, ...]], int])

Return type:

None

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

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.

Parameters:

id (int)
source (int)
target (int)
kind (str)
wrap (bool)

id: int#

source: int#

target: int#

kind: str#

wrap: bool#

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

Parameters:

id (int)
source (int)
target (int)
kind (str)
wrap (bool)

Return type:

None

class qlinks.lattice.OrientedLink(link_id, orientation)[source]#

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.

Parameters:

link_id (int)
orientation (int)

link_id: int#

orientation: int#

__init__(link_id, orientation)#

Parameters:

link_id (int)
orientation (int)

Return type:

None

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

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.

Parameters:

id (int)
links (tuple[int, ...])
orientations (tuple[int, ...])
sites (tuple[int, ...])
kind (str)
anchor_cell (tuple[int, ...])

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=())#

Parameters:

id (int)
links (tuple[int, ...])
orientations (tuple[int, ...])
sites (tuple[int, ...])
kind (str)
anchor_cell (tuple[int, ...])

Return type:

None

class qlinks.lattice.Site(id, cell, sublattice=0, position=())[source]#

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.

Parameters:

id (int)
cell (tuple[int, ...])
sublattice (int)
position (tuple[float, ...])

id: int#

cell: tuple[int, ...]#

sublattice: int#

position: tuple[float, ...]#

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

Parameters:

id (int)
cell (tuple[int, ...])
sublattice (int)
position (tuple[float, ...])

Return type:

None

class qlinks.lattice.SquareLattice(lx, ly, boundary_condition=BoundaryCondition.OPEN)[source]#

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

Parameters:

lx (int)
ly (int)
boundary_condition (BoundaryCondition | str)

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN)[source]#

Parameters:

lx (int)
ly (int)
boundary_condition (BoundaryCondition | str)

Return type:

None

site_id(x, y)[source]#

Parameters:

x (int)
y (int)

Return type:

int

canonical_cell(cell)[source]#

Parameters:: cell (tuple[int, ...])
Return type:: tuple[int, …]

plaquette_id_from_cell(x, y)[source]#

Parameters:

x (int)
y (int)

Return type:

int

square_plaquette_id(x, y)[source]#

Parameters:

x (int)
y (int)

Return type:

int

lx#

ly#

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

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.

Parameters:

lx (int)
ly (int)
boundary_condition (BoundaryCondition | str)
include_triangles (bool)
include_rhombi (bool)

__init__(lx, ly, boundary_condition=BoundaryCondition.OPEN, *, include_triangles=True, include_rhombi=True)[source]#

Parameters:

lx (int)
ly (int)
boundary_condition (BoundaryCondition | str)
include_triangles (bool)
include_rhombi (bool)

Return type:

None

site_id(x, y)[source]#

Parameters:

x (int)
y (int)

Return type:

int

qdm_plaquette_ids()[source]#

qlm_plaquette_ids(*, use_triangles=False)[source]#

Parameters:: use_triangles (bool)

triangular_plaquette_id(x, y, *, kind)[source]#

Parameters:

x (int)
y (int)
kind (str)

Return type:

int

rhombus_plaquette_id(x, y, *, kind)[source]#

Parameters:

x (int)
y (int)
kind (str)

Return type:

int

lx#

ly#

qlinks.lattice

Contents

qlinks.lattice#