Unified Lattice Representation API

[refraction-ray]

TEP - Unified Lattice Representation API

Author
@refraction-ray

Status

Created
2025-03-27

Abstract

This TEP proposes a unified and extensible API within the library for representing diverse lattice geometries. It introduces an AbstractLattice base class with derived classes for periodic (TILattice) and general (CustomizeLattice) structures. The API provides access to fundamental lattice properties like site coordinates, abstract identifiers, and methods for finding nearest and further neighbors (get_nearest_neighbors, get_neighbor_pairs). Crucially, it also includes a .show() method for easy visualization of the lattice structure and connectivity.

Motivation and Scope

Defining and working with lattice geometries is fundamental to modeling many physical systems. Currently, users often rely on:

• Ad-hoc Scripts: Writing custom code for each specific lattice, which is prone to errors and difficult to reuse.

• Implicit Representations: Defining lattices only through neighbor lists, or `nx.graph`` losing explicit geometric information crucial for visualization or defining distance-dependent interactions.

This proposal aims to provide a structured, reusable, geometrically explicit, and easily visualizable framework for lattice definition, ready for later development of Rydberg analog Hamiltonian simulation.

Scope:

Define an abstract base class AbstractLattice specifying the core interface for any lattice (site count, dimensionality, access to site info by index/identifier, neighbor finding).

Implement concrete lattice classes:

TILattice for systems with translational symmetry, defined by lattice vectors, basis sites, system size, and unit cells. Include specific examples like SquareLattice, HoneycombLattice.

CustomizeLattice for arbitrary geometries defined by explicit site coordinate and identifier lists, suitable for finite clusters, disordered systems, or custom structures.

Provide robust methods for finding neighbors: get_neighbor_pairs(k).

Implement a visualization method show() on the lattice classes

Usage and Impact

sq_lattice = SquareLattice(size=(3, 3), pbc=True, lattice_constant=1.0)

# Access lattice properties
print(f"Num sites: {sq_lattice.num_sites}")
print(f"Dimensionality: {sq_lattice.dimensionality}")

# Get info for site index 4 (center site)
idx, ident, coords = sq_lattice.get_site_info(4)
print(f"Site {idx}: ID={ident}, Coords={coords}")

# Get nearest neighbors (NN) of site 4
nn_indices = sq_lattice.get_neighbors(4, k=1)
print(f"NN of site {idx}: {nn_indices}")

# Get all unique NN pairs
nn_pairs = sq_lattice.get_neighbor_pairs(k=1, unique=True)

kag_coords = [ [0,0], [1,0], [0.5, np.sqrt(3)/2], # Triangle 1
               [2,0], [1.5, np.sqrt(3)/2],       # Triangle 2 base shifted
               [1, np.sqrt(3)] ]                 # Top site
kag_ids = list(range(len(kag_coords))) # Simple integer identifiers
kag_lattice = CustomizeLattice(dimensionality=2, identifiers=kag_ids, coordinates=kag_coords)
kag_lattice._build_neighbors(max_k=1)  # Calculate NN based on distance
print(f"\nKagome fragment NN of site 2: {kag_lattice.get_neighbors(2, k=1)}")

• Clear Geometric Definition: Provides a standardized way to define lattice geometries explicitly using coordinates and identifiers.

• Reduced Boilerplate: Eliminates the need for users to write custom code for common lattice types and neighbor finding.

• Foundation for Physics Models: Although this TEP doesn't include Hamiltonian construction, it provides the essential, reliable geometric foundation needed for defining physical models.

• Extensibility: Users can derive from AbstractLattice or CustomizeLattice to implement custom or more complex geometries.

Backward compatibility

Currently, there are some lattice class in templates.graphs module of tc. We will write a totally new module, maybe templates.lattice and make the old graphs submodule deprecated.

Related Work

• networkx
• bloquade-analog
• netket
• quspin
• quimb
• pennylane

Implementation

Alternatives

References