quimb.tensor.tn2dinf.geometry

Geometry of infinite, translation-invariant 2D lattices: the unit cell of sites and bonds, with a GeometryInfinite2D.square builder for square lattices. See the subpackage __init__ for some shared definition.

Classes

GeometryInfinite2D

Helper class to represent the geometry of an infinite 2D lattice.

Functions

is_inf_2d_site(site)	Check if site is a valid 2d infinite site specifier, that is, it is
ensure_inf_2d_sites(where)	Ensure where (a single site or a sequence of sites) is a tuple of
get_bond_sorted(sitea, siteb)	Given a bond between two sites, simply return the sorted order of the
get_bond_type(sitea, siteb)	Given a bond between two sites, get its bond type: the canonical
_average_position(positions)	Return the average position of a sequence of 2d positions.
_half_grid(rmax)	Get all positive displacements ((dx, dy) > (0, 0)) with
_square_displacements([couplings, radius])	Calculate possible long range bonds on a square lattice, producing a
make_edges_inf_2d_square([Lx, Ly, couplings, radius])	Edges of an Lx by Ly square-lattice unit cell, with

Module Contents

quimb.tensor.tn2dinf.geometry.is_inf_2d_site(site)

Check if site is a valid 2d infinite site specifier, that is, it is tuple (cell, site_type) where cell is a tuple (x : int, y : int).

quimb.tensor.tn2dinf.geometry.ensure_inf_2d_sites(where)

Ensure where (a single site or a sequence of sites) is a tuple of sites.

quimb.tensor.tn2dinf.geometry.get_bond_sorted(sitea, siteb)

Given a bond between two sites, simply return the sorted order of the two, which is the canonical way to refer to it / use it as a key etc.

quimb.tensor.tn2dinf.geometry.get_bond_type(sitea, siteb)

Given a bond between two sites, get its bond type: the canonical representative of the bond’s translation class. The first endpoint is translated to cell (0, 0) and the orientation chosen so the two endpoints are in sorted order, i.e. cella < cellb, or (within-cell) site_type_a < site_type_b. Thus cells compare dx-first.

quimb.tensor.tn2dinf.geometry._average_position(positions)

Return the average position of a sequence of 2d positions.

class quimb.tensor.tn2dinf.geometry.GeometryInfinite2D(edges, basis=None, positions=None)

Helper class to represent the geometry of an infinite 2D lattice.

Parameters:

• edges (sequence[(((int, int), hashable), ((int, int), hashable)), ...]) – A sequence of edges, where each edge is a pair of sites. Each site is represented as a tuple of (cell, site_type), where cell is a tuple of integers representing the cell coordinates, and site_type is a hashable representing the type of site (e.g., an integer or string). Equivalent edges are automatically deduplicated and normalized to a canonical bond_type: the first endpoint translated to cell (0, 0) and the two endpoints in sorted order, i.e. cella < cellb, or (within-cell) site_type_a < site_type_b (cells compare dx-first).

• basis ((float, float), optional) – A pair of 2D vectors representing the lattice basis vectors. If not provided, the default basis is the standard square lattice basis.

• positions (dict, optional) – A dictionary mapping site types to their fractional positions within the unit cell. If not provided, the default position for each site type is (0.0, 0.0). Currently only used for drawing.

site_types

bond_types

site_type_neighbors

covering_sites

covering_bonds

basis

positions

classmethod square(Lx=2, Ly=None, *, couplings=None, radius=None, basis=None, **kwargs)

Build a square-lattice geometry on an Lx by Ly unit cell, with site_type = (subx, suby) sitting at the 0-based lattice points. By default builds the minimal 2x2 cell with nearest-neighbor bonds. Longer range bonds can be included by specifying couplings or radius.

Parameters:

• Lx (int) – The number of sites in the x-direction in the unit cell, default 2.

• Ly (int, optional) – The number of sites in the y-direction in the unit cell, default Lx.

• couplings (int or sequence[tuple[int, int]], optional) – Which neighbor shells to bond, in square-lattice distance: an int k for the first k shells (1 nearest-neighbor, 2 also diagonal next-nearest, …), or an explicit sequence of (dx, dy) site-step displacements. Mutually exclusive with radius, defaults to nearest-neighbor.

• radius (float, optional) – Alternatively, bond every neighbor within this square-lattice distance.

• basis (tuple[tuple[float, float], tuple[float, float]], optional) – Lattice vectors for the spatial embedding (drawing only), defaults to the unit square.

• kwargs – Passed to the GeometryInfinite2D constructor.

Return type:

GeometryInfinite2D

get_site_neighbors(site)

Generate the neighbors of a given site.

coordinate(site)

Map a site (cell, site_type) to its cartesian position: (cell + fractional_offset) @ basis, defining a spatial embedding.

get_graph_distance(sitea, siteb, max_hops=None)

Calculate the graph distance (number of hops) between two sites, found by BFS over the site graph. max_hops caps the search, guarding against an unreachable siteb (any connected pair terminates without it).

get_sites_within_radius(site, radius)

All sites within radius graph distance of site, inclusive.

get_cell_size()

Return (dx, dy), the ‘width’ and ‘height’ of the unit cell in terms of the minimum number of bond hops for any site_type to reach the same site_type in the neighboring cell in the x and y directions, respectively. Useful for computing necessary tiling sizes.

get_tiling_for_radius(radius)

Number of cells to tile out from the origin in each direction so that every site within radius bond-hops of the origin cell is contained. Returns (nx, ny), i.e. tile cells -nx..nx by -ny..ny. Explores the graph directly, so the tiling never undershoots (note an oversized fragment is usually harmless, the region of interest is generally subselected from it).

get_bond_sorted

get_bond_type

is_canonical_bond(sitea, siteb)

Whether the bond between sitea and siteb is already in canonical bond_type form, i.e. sorted with its first endpoint in the origin cell (0, 0).

get_auto_ordering(order='sort', group=False, interchange=True)

An ordering of the bond_types such that consecutive entries act on disjoint site_types where possible, i.e. grouped into commuting layers. Used to sequence gates in e.g. a simple-update sweep.

Parameters:

• order ({'sort', None, 'random', 'random-ungrouped', str}, optional) –

  How to order the bond_types before greedily grouping them into commuting (non site_type-overlapping) layers:

  • 'sort' sorts the bond_types first.

  • None uses their current order.

  • 'random' randomly shuffles them before grouping.

  • 'random-ungrouped' randomly shuffles them and does not group them at all. With group=True the shuffled bond_types are aggregated only with commuting neighbors.

  Any other value is passed as a strategy to networkx.coloring.greedy_color(), coloring the graph whose nodes are bond_types, linked when they share a site_type, so each color is a commuting layer.

• group (bool, optional) – If True, return a list of layers (tuples of bond_types), otherwise return a flat list of bond_types.

• interchange (bool, optional) – For the networkx coloring strategies, whether to use the interchange heuristic (usually better colorings, but slower).

Return type:

list[bond_type] or list[tuple[bond_type]]

draw(order=None, pos=None)

Draw the covering sites and bonds of the unit cell, with the cell boundary marked.

Parameters:

• order (str, optional) – If given, color the bonds by the commuting layer they fall into, as computed by get_auto_ordering() with this order strategy (e.g. "sort"). If None, each bond_type is colored by its own hash instead.

• pos (dict, optional) – A mapping of site_type to fractional position within the unit cell. If not given, the geometry’s own coordinate is used.

__repr__()

quimb.tensor.tn2dinf.geometry._half_grid(rmax)

Get all positive displacements ((dx, dy) > (0, 0)) with dx <= rmax and dy <= rmax.

quimb.tensor.tn2dinf.geometry._square_displacements(couplings=None, radius=None)

Calculate possible long range bonds on a square lattice, producing a sorted list of (dx, dy) site-step displacements, one per +/- pair, measured in square-lattice distance (independent of the drawing basis). At most one of couplings / radius may be given, defaulting to nearest-neighbor.

Parameters:

• couplings (int or sequence[tuple[int, int]], optional) – An int k for the first k neighbor shells (1 nearest-neighbor, 2 also diagonal next-nearest, …), or an explicit iterable of (dx, dy).

• radius (float, optional) – All displacements within this square-lattice distance.

Return type:

list[tuple[int, int]]

quimb.tensor.tn2dinf.geometry.make_edges_inf_2d_square(Lx=2, Ly=None, couplings=None, radius=None)

Edges of an Lx by Ly square-lattice unit cell, with site_type = (subx, suby). By default nearest-neighbor bonds only, with longer range bonds included by specifying couplings or radius.

Each bond must reach a different sublattice in a neighboring cell, else a ValueError asks to expand the cell (e.g. 3rd-NN (2, 0) invalidly links sites to themselves in only a 2x2 cell).

Parameters:

• Lx (int) – The number of sites in the x-direction in the unit cell, default 2.

• Ly (int, optional) – The number of sites in the y-direction in the unit cell, default Lx.

• couplings (int or sequence[tuple[int, int]], optional) – The neighbor shells to bond (see _square_displacements()).

• radius (float, optional) – A square-lattice distance cutoff, as an alternative to couplings.

Return type:

list[tuple[site, site]]