tensorcircuit.templates.lattice¶

The lattice module for defining and manipulating lattice geometries.

class tensorcircuit.templates.lattice.AbstractLattice(dimensionality: int)[source]¶

Bases: ABC

Abstract base class for describing lattice systems.

This class defines the common interface for all lattice structures, providing access to fundamental properties like site information (count, coordinates, identifiers) and neighbor relationships. Subclasses are responsible for implementing the specific logic for generating the lattice points and calculating neighbor connections.

Parameters:: dimensionality (int) – The spatial dimension of the lattice (e.g., 1, 2, 3).

__init__(dimensionality: int)[source]¶: Initializes the base lattice class.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]][source]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Note on Differentiability: This method provides a static list of index pairs and is not differentiable itself. However, it is designed to be used in combination with the fully differentiable distance_matrix property. By using the pairs from this method to index into the distance_matrix, one can construct differentiable objective functions based on all-pair interactions, effectively bypassing the non-differentiable get_neighbor_pairs method for geometry optimization tasks.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any[source]¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable[source]¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int[source]¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]][source]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int][source]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any][source]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

show(show_indices: bool = False, show_identifiers: bool = False, show_bonds_k: int | None = None, ax: matplotlib.axes.Axes | None = None, bond_kwargs: Dict[str, Any] | None = None, **kwargs: Any) → None[source]¶

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]][source]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.ChainLattice(size: Tuple[int], lattice_constant: float | Any = 1.0, pbc: bool = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 1D chain (simple Bravais lattice).

Parameters:

size (Tuple[int]) – A tuple (N,) specifying the number of sites in the chain.
lattice_constant (float, optional) – The distance between two adjacent sites. Defaults to 1.0.
pbc (bool, optional) – Specifies if periodic boundary conditions are applied. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int], lattice_constant: float | Any = 1.0, pbc: bool = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.CheckerboardLattice(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D checkerboard lattice (a square lattice with an AB sublattice).

The unit cell is a square rotated by 45 degrees, containing two sites.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of unit cells. Total sites will be 2*Nx*Ny.
lattice_constant (float, optional) – The bond length between nearest neighbors. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.CubicLattice(size: Tuple[int, int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 3D cubic lattice.

This is a simple Bravais lattice, the 3D generalization of SquareLattice.

Parameters:

size (Tuple[int, int, int]) – A tuple (Nx, Ny, Nz) specifying the number of sites.
lattice_constant (float, optional) – The distance between adjacent sites. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.CustomizeLattice(dimensionality: int, identifiers: List[Hashable], coordinates: Any, precompute_neighbors: int | None = None)[source]¶

Bases: AbstractLattice

A general lattice built from an explicit list of sites and coordinates.

This class is suitable for creating lattices with arbitrary geometries, such as finite clusters, disordered systems, or any custom structure that does not have translational symmetry. The lattice is defined simply by providing lists of identifiers and coordinates for each site.

Parameters:

dimensionality (int) – The spatial dimension of the lattice.
identifiers (List[SiteIdentifier]) – A list of unique, hashable identifiers for the sites. The length must match coordinates.
coordinates (List[Union[List[float], Coordinates]]) – A list of site coordinates. Each coordinate should be a list of floats or a NumPy array.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

Raises:

ValueError – If the lengths of identifiers and coordinates lists do not match, or if a coordinate’s dimension is incorrect.

__init__(dimensionality: int, identifiers: List[Hashable], coordinates: Any, precompute_neighbors: int | None = None)[source]¶: Initializes the CustomizeLattice.

add_sites(identifiers: List[Hashable], coordinates: Any) → None[source]¶

Adds new sites to the lattice.

This operation modifies the lattice in-place. After adding sites, any previously computed neighbor information is cleared and must be recalculated.

Parameters:

identifiers (List[SiteIdentifier]) – A list of unique identifiers for the new sites.
coordinates (Any) – The coordinates for the new sites. Can be a list of lists, a NumPy array, or a backend-compatible tensor (e.g., jax.numpy.ndarray).

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

classmethod from_lattice(lattice: AbstractLattice) → CustomizeLattice[source]¶

Creates a CustomizeLattice instance from any existing lattice object.

This is useful for ‘detaching’ a procedurally generated lattice (like a SquareLattice) into a customizable one for further modifications, such as adding defects or extra sites.

Parameters:: lattice (AbstractLattice) – An instance of any AbstractLattice subclass.
Returns:: A new CustomizeLattice instance with the same sites.
Return type:: CustomizeLattice

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

remove_sites(identifiers: List[Hashable]) → None[source]¶

Removes specified sites from the lattice.

This operation modifies the lattice in-place. After removing sites, all site indices are re-calculated, and any previously computed neighbor information is cleared.

Parameters:: identifiers (List[SiteIdentifier]) – A list of identifiers for the sites to be removed.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.DimerizedChainLattice(size: Tuple[int], lattice_constant: float | Any = 1.0, pbc: bool = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 1D chain with an AB sublattice (dimerized chain).

The unit cell contains two sites, A and B. The bond length is uniform.

Parameters:

size (Tuple[int]) – A tuple (N,) specifying the number of unit cells. The total number of sites in the chain will be 2 * N, as each unit cell contains two sites.
lattice_constant (float, optional) – The distance between two adjacent sites (bond length). Defaults to 1.0.
pbc (bool, optional) – Specifies if periodic boundary conditions are applied. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int], lattice_constant: float | Any = 1.0, pbc: bool = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.HoneycombLattice(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D honeycomb lattice.

This is a classic example of a composite lattice. It consists of a two-site basis (sublattices A and B) on an underlying triangular Bravais lattice.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of unit cells along the two lattice vector directions.
lattice_constant (float, optional) – The bond length, i.e., the distance between two nearest neighbor sites. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the HoneycombLattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.KagomeLattice(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D Kagome lattice.

This is a lattice with a three-site basis on a triangular Bravais lattice.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of unit cells. Total sites will be 3*Nx*Ny.
lattice_constant (float, optional) – The bond length. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.LiebLattice(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D Lieb lattice.

This is a lattice with a three-site basis on a square Bravais lattice. It has sites at the corners and centers of the edges of a square.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of unit cells. Total sites will be 3*Nx*Ny.
lattice_constant (float, optional) – The bond length. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the LiebLattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.RectangularLattice(size: Tuple[int, int], lattice_constants: Tuple[float, float] | Any = (1.0, 1.0), pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D rectangular lattice.

This is a generalization of the SquareLattice where the lattice constants in the x and y directions can be different.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of sites in x and y.
lattice_constants (Tuple[float, float], optional) – The distance between adjacent sites in the x and y directions, e.g., (ax, ay). Defaults to (1.0, 1.0).
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constants: Tuple[float, float] | Any = (1.0, 1.0), pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.SquareLattice(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D square lattice.

This is a concrete implementation of a translationally invariant lattice representing a simple square grid. It is a Bravais lattice with a single-site basis.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of unit cells (sites) in the x and y directions.
lattice_constant (float, optional) – The distance between two adjacent sites. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Can be a single boolean for all dimensions or a tuple of booleans for each dimension individually. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the SquareLattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.TILattice(dimensionality: int, lattice_vectors: Any, basis_coords: Any, size: Tuple[int, ...], pbc: bool | Tuple[bool, ...] = True, precompute_neighbors: int | None = None)[source]¶

Bases: AbstractLattice

Describes a periodic lattice with translational invariance.

This class serves as a base for any lattice defined by a repeating unit cell. The geometry is specified by lattice vectors, the coordinates of basis sites within a unit cell, and the total size of the lattice in terms of unit cells.

The site identifier for this class is a tuple in the format of (uc_coord_1, …, uc_coord_d, basis_index), where uc_coord represents the integer coordinate of the unit cell and basis_index is the index of the site within that unit cell’s basis.

Parameters:

dimensionality (int) – The spatial dimension of the lattice.
lattice_vectors (np.ndarray) – The lattice vectors defining the unit cell, given as row vectors. Shape: (dimensionality, dimensionality). For example, in 2D: np.array([[ax, ay], [bx, by]]).
basis_coords (np.ndarray) – The Cartesian coordinates of the basis sites within the unit cell. Shape: (num_basis_sites, dimensionality). For a simple Bravais lattice, this would be np.array([[0, 0]]).
size (Tuple[int, ...]) – A tuple specifying the number of unit cells to generate in each lattice vector direction (e.g., (Nx, Ny)).
pbc (Union[bool, Tuple[bool, ...]], optional) – Specifies whether periodic boundary conditions are applied. Can be a single boolean for all dimensions or a tuple of booleans for each dimension individually. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(dimensionality: int, lattice_vectors: Any, basis_coords: Any, size: Tuple[int, ...], pbc: bool | Tuple[bool, ...] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the Translationally Invariant Lattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

class tensorcircuit.templates.lattice.TriangularLattice(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶

Bases: TILattice

A 2D triangular lattice.

This is a Bravais lattice where each site has 6 nearest neighbors.

Parameters:

size (Tuple[int, int]) – A tuple (Nx, Ny) specifying the number of unit cells along the two lattice vector directions.
lattice_constant (float, optional) – The bond length, i.e., the distance between two nearest neighbor sites. Defaults to 1.0.
pbc (Union[bool, Tuple[bool, bool]], optional) – Specifies periodic boundary conditions. Defaults to True.
precompute_neighbors (Optional[int], optional) – If specified, pre-computes neighbor relationships up to the given order k upon initialization. Defaults to None.

__init__(size: Tuple[int, int], lattice_constant: float | Any = 1.0, pbc: bool | Tuple[bool, bool] = True, precompute_neighbors: int | None = None)[source]¶: Initializes the TriangularLattice.

property dimensionality: int¶: Returns the spatial dimension of the lattice.

property distance_matrix: Any¶: Returns the full N x N distance matrix. The matrix is computed on the first access and then cached for subsequent calls. This computation can be expensive for large lattices.

get_all_pairs() → List[Tuple[int, int]]¶

Returns a list of all unique pairs of site indices (i, j) where i < j.

This method provides all-to-all connectivity, useful for Hamiltonians where every site interacts with every other site.

Returns:: A list of tuples, where each tuple is a unique pair of site indices.
Return type:: List[Tuple[SiteIndex, SiteIndex]]

get_coordinates(index: int) → Any¶

Gets the spatial coordinates of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The spatial coordinates as a NumPy array.
Return type:: Coordinates

get_identifier(index: int) → Hashable¶

Gets the abstract identifier of a site by its integer index.

Parameters:: index (SiteIndex) – The integer index of the site.
Raises:: IndexError – If the site index is out of range.
Returns:: The unique, hashable identifier of the site.
Return type:: SiteIdentifier

get_index(identifier: Hashable) → int¶

Gets the integer index of a site by its unique identifier.

Parameters:: identifier (SiteIdentifier) – The unique identifier of the site.
Raises:: ValueError – If the identifier is not found in the lattice.
Returns:: The corresponding integer index of the site.
Return type:: SiteIndex

get_neighbor_pairs(k: int = 1, unique: bool = True) → List[Tuple[int, int]]¶

Gets all pairs of k-th nearest neighbors, representing bonds.

Parameters:

k (int, optional) – The order of the neighbors to consider. Defaults to 1.
unique (bool, optional) – If True, returns only one representation for each pair (i, j) such that i < j, avoiding duplicates like (j, i). If False, returns all directed pairs. Defaults to True.

Returns:

A list of tuples, where each tuple is a pair of neighbor indices.

Return type:

List[Tuple[SiteIndex, SiteIndex]]

get_neighbors(index: int, k: int = 1) → List[int]¶

Gets the list of k-th nearest neighbor indices for a given site.

Parameters:

index (SiteIndex) – The integer index of the center site.
k (int, optional) – The order of the neighbors, where k=1 corresponds to nearest neighbors (NN), k=2 to next-nearest neighbors (NNN), and so on. Defaults to 1.

Returns:

A list of integer indices for the neighboring sites. Returns an empty list if neighbors for the given k have not been pre-calculated or if the site has no such neighbors.

Return type:

List[SiteIndex]

get_site_info(index_or_identifier: int | Hashable) → Tuple[int, Hashable, Any]¶

Gets all information for a single site.

This method provides a convenient way to retrieve all relevant data for a site (its index, identifier, and coordinates) by using either its integer index or its unique identifier.

Parameters:

index_or_identifier (Union[SiteIndex, SiteIdentifier]) – The integer index or the unique identifier of the site to look up.

Raises:

IndexError – If the given index is out of bounds.
ValueError – If the given identifier is not found in the lattice.

Returns:

A tuple containing: - The site’s integer index. - The site’s unique identifier. - The site’s coordinates as a NumPy array.

Return type:

Tuple[SiteIndex, SiteIdentifier, Coordinates]

property num_sites: int¶: Returns the total number of sites (N) in the lattice.

Visualizes the lattice structure using Matplotlib.

This method supports 1D, 2D, and 3D plotting. For 1D lattices, sites are plotted along the x-axis.

Parameters:

show_indices (bool, optional) – If True, displays the integer index next to each site. Defaults to False.
show_identifiers (bool, optional) – If True, displays the unique identifier next to each site. Defaults to False.
show_bonds_k (Optional[int], optional) – Specifies which order of neighbor bonds to draw (e.g., 1 for NN, 2 for NNN). If None, no bonds are drawn. If the specified neighbors have not been calculated, a warning is printed. Defaults to None.
ax (Optional["matplotlib.axes.Axes"], optional) – An existing Matplotlib Axes object to plot on. If None, a new Figure and Axes are created automatically. Defaults to None.
bond_kwargs (Optional[Dict[str, Any]], optional) – A dictionary of keyword arguments for customizing bond appearance, passed directly to the Matplotlib plot function. Defaults to None.
kwargs – Additional keyword arguments to be passed directly to the matplotlib.pyplot.scatter function for customizing site appearance.

sites() → Iterator[Tuple[int, Hashable, Any]]¶

Returns an iterator over all sites in the lattice.

This provides a convenient way to loop through all sites, for example: for idx, ident, coords in my_lattice.sites(): …

Returns:: An iterator where each item is a tuple containing the site’s index, identifier, and coordinates.
Return type:: Iterator[Tuple[SiteIndex, SiteIdentifier, Coordinates]]

tensorcircuit.templates.lattice.get_compatible_layers(bonds: List[Tuple[int, int]]) → List[List[Tuple[int, int]]][source]¶

Partitions a list of pairs (bonds) into compatible layers for parallel gate application using a greedy edge-coloring algorithm.

This function takes a list of pairs, representing connections like nearest-neighbor (NN) or next-nearest-neighbor (NNN) bonds, and partitions them into the minimum number of sets (“layers”) where no two pairs in a set share an index. This is a general utility for scheduling non-overlapping operations.

Example:

>>> from tensorcircuit.templates.lattice import SquareLattice
>>> sq_lattice = SquareLattice(size=(2, 2), pbc=False)
>>> nn_bonds = sq_lattice.get_neighbor_pairs(k=1, unique=True)

>>> gate_layers = get_compatible_layers(nn_bonds)
>>> print(gate_layers)
[[[0, 1], [2, 3]], [[0, 2], [1, 3]]]

Parameters:: bonds (List[Tuple[int, int]]) – A list of tuples, where each tuple represents a bond (i, j) of site indices to be scheduled.
Returns:: A list of layers. Each layer is a list of tuples, where each tuple represents a bond. All bonds within a layer are non-overlapping.
Return type:: List[List[Tuple[int, int]]]