quimb.tensor.tn2dinf.geometry ============================= .. py:module:: quimb.tensor.tn2dinf.geometry .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: quimb.tensor.tn2dinf.geometry.GeometryInfinite2D Functions --------- .. autoapisummary:: quimb.tensor.tn2dinf.geometry.is_inf_2d_site quimb.tensor.tn2dinf.geometry.ensure_inf_2d_sites quimb.tensor.tn2dinf.geometry.get_bond_sorted quimb.tensor.tn2dinf.geometry.get_bond_type quimb.tensor.tn2dinf.geometry._average_position quimb.tensor.tn2dinf.geometry._half_grid quimb.tensor.tn2dinf.geometry._square_displacements quimb.tensor.tn2dinf.geometry.make_edges_inf_2d_square Module Contents --------------- .. py:function:: 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)`. .. py:function:: ensure_inf_2d_sites(where) Ensure ``where`` (a single site or a sequence of sites) is a tuple of sites. .. py:function:: 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. .. py:function:: 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. .. py:function:: _average_position(positions) Return the average position of a sequence of 2d positions. .. py:class:: GeometryInfinite2D(edges, basis=None, positions=None) Helper class to represent the geometry of an infinite 2D lattice. :param edges: 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). :type edges: sequence[(((int, int), hashable), ((int, int), hashable)), ...] :param basis: A pair of 2D vectors representing the lattice basis vectors. If not provided, the default basis is the standard square lattice basis. :type basis: (float, float), optional :param positions: 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. :type positions: dict, optional .. py:attribute:: site_types .. py:attribute:: bond_types .. py:attribute:: site_type_neighbors .. py:attribute:: covering_sites .. py:attribute:: covering_bonds .. py:attribute:: basis .. py:attribute:: positions .. py:method:: square(Lx=2, Ly=None, *, couplings=None, radius=None, basis=None, **kwargs) :classmethod: 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``. :param Lx: The number of sites in the x-direction in the unit cell, default 2. :type Lx: int :param Ly: The number of sites in the y-direction in the unit cell, default ``Lx``. :type Ly: int, optional :param couplings: 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. :type couplings: int or sequence[tuple[int, int]], optional :param radius: Alternatively, bond every neighbor within this square-lattice distance. :type radius: float, optional :param basis: Lattice vectors for the spatial embedding (drawing only), defaults to the unit square. :type basis: tuple[tuple[float, float], tuple[float, float]], optional :param kwargs: Passed to the ``GeometryInfinite2D`` constructor. :rtype: GeometryInfinite2D .. py:method:: get_site_neighbors(site) Generate the neighbors of a given site. .. py:method:: coordinate(site) Map a site ``(cell, site_type)`` to its cartesian position: ``(cell + fractional_offset) @ basis``, defining a spatial embedding. .. py:method:: 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). .. py:method:: get_sites_within_radius(site, radius) All sites within ``radius`` graph distance of ``site``, inclusive. .. py:method:: 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. .. py:method:: 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). .. py:attribute:: get_bond_sorted .. py:attribute:: get_bond_type .. py:method:: 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). .. py:method:: 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. :param order: 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 :func:`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. :type order: {'sort', None, 'random', 'random-ungrouped', str}, optional :param group: If ``True``, return a list of layers (tuples of ``bond_types``), otherwise return a flat list of ``bond_types``. :type group: bool, optional :param interchange: For the networkx coloring strategies, whether to use the interchange heuristic (usually better colorings, but slower). :type interchange: bool, optional :rtype: list[bond_type] or list[tuple[bond_type]] .. py:method:: draw(order=None, pos=None) Draw the covering sites and bonds of the unit cell, with the cell boundary marked. :param order: If given, color the bonds by the commuting layer they fall into, as computed by :meth:`get_auto_ordering` with this ``order`` strategy (e.g. ``"sort"``). If ``None``, each ``bond_type`` is colored by its own hash instead. :type order: str, optional :param pos: A mapping of ``site_type`` to fractional position within the unit cell. If not given, the geometry's own ``coordinate`` is used. :type pos: dict, optional .. py:method:: __repr__() .. py:function:: _half_grid(rmax) Get all positive displacements (``(dx, dy) > (0, 0)``) with ``dx <= rmax`` and ``dy <= rmax``. .. py:function:: _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. :param couplings: An int ``k`` for the first ``k`` neighbor shells (``1`` nearest-neighbor, ``2`` also diagonal next-nearest, ...), or an explicit iterable of ``(dx, dy)``. :type couplings: int or sequence[tuple[int, int]], optional :param radius: All displacements within this square-lattice distance. :type radius: float, optional :rtype: list[tuple[int, int]] .. py:function:: 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). :param Lx: The number of sites in the x-direction in the unit cell, default 2. :type Lx: int :param Ly: The number of sites in the y-direction in the unit cell, default ``Lx``. :type Ly: int, optional :param couplings: The neighbor shells to bond (see :func:`_square_displacements`). :type couplings: int or sequence[tuple[int, int]], optional :param radius: A square-lattice distance cutoff, as an alternative to ``couplings``. :type radius: float, optional :rtype: list[tuple[site, site]]