quimb.tensor.tensor_arbgeom_tebd ================================ .. py:module:: quimb.tensor.tensor_arbgeom_tebd .. autoapi-nested-parse:: Tools for performing TEBD like algorithms on arbitrary lattices. Classes ------- .. autoapisummary:: quimb.tensor.tensor_arbgeom_tebd.LocalHamGen quimb.tensor.tensor_arbgeom_tebd.TEBDGen quimb.tensor.tensor_arbgeom_tebd.SimpleUpdateGen Functions --------- .. autoapisummary:: quimb.tensor.tensor_arbgeom_tebd.edge_coloring Module Contents --------------- .. py:function:: edge_coloring(edges, strategy='smallest_last', interchange=True, group=True) Generate an edge coloring for the graph given by ``edges``, using ``networkx.coloring.greedy_color``. :param edges: The edges of the graph. :type edges: sequence[tuple[hashable, hashable]] :param strategy: The strategy to use for coloring the edges. Can be: - 'largest_first' - 'smallest_last' - 'random_sequential' ... :type strategy: str or callable, optional :param interchange: Whether to use the interchange heuristic. Usually generates better colorings but can be slower. :type interchange: bool, optional :param group: Whether to group the edges by color or return a flat list. :type group: bool, optional .. py:class:: LocalHamGen(H2, H1=None) Representation of a local hamiltonian defined on a general graph. This combines all two site and one site terms into a single interaction per lattice pair, and caches operations on the terms such as getting their exponential. The sites (nodes) should be hashable and comparable. :param H2: The interaction terms, with each key being an tuple of nodes defining an edge and each value the local hamilotonian term for those two nodes. :type H2: dict[tuple[node], array_like] :param H1: The one site term(s). If a single array is given, assume to be the default onsite term for all terms. If a dict is supplied, the keys should represent specific coordinates like ``(i, j)`` with the values the array representing the local term for that site. A default term for all remaining sites can still be supplied with the key ``None``. :type H1: array_like or dict[node, array_like], optional .. attribute:: terms The total effective local term for each interaction (with single site terms appropriately absorbed). Each key is a pair of coordinates ``site_a, site_b`` with ``site_a < site_b``. :type: dict[tuple, array_like] .. py:attribute:: _op_cache .. py:attribute:: terms .. py:attribute:: sites .. py:attribute:: _sites_to_covering_terms .. py:property:: nsites The number of sites in the system. .. py:method:: items() Iterate over all terms in the hamiltonian. This is mostly for convenient compatibility with ``compute_local_expectation``. .. py:method:: _convert_from_qarray_cached(x) .. py:method:: _flip_cached(x) .. py:method:: _add_cached(x, y) .. py:method:: _div_cached(x, y) .. py:method:: _op_id_cached(x) .. py:method:: _id_op_cached(x) .. py:method:: _expm_cached(G, x) .. py:method:: get_gate(where) Get the local term for pair ``where``, cached. .. py:method:: get_gate_expm(where, x) Get the local term for pair ``where``, matrix exponentiated by ``x``, and cached. .. py:method:: apply_to_arrays(fn) Apply the function ``fn`` to all the arrays representing terms. .. py:method:: get_auto_ordering(order='sort', **kwargs) Get an ordering of the terms to use with TEBD, for example. The default is to sort the coordinates then greedily group them into commuting sets. :param order: How to order the terms *before* greedily grouping them into commuting (non-coordinate overlapping) sets: - ``'sort'`` will sort the coordinate pairs first. - ``None`` will use the current order of terms which should match the order they were supplied to this ``LocalHam2D`` instance. - ``'random'`` will randomly shuffle the coordinate pairs before grouping them - *not* the same as returning a completely random order. - ``'random-ungrouped'`` will randomly shuffle the coordinate pairs but *not* group them at all with respect to commutation. Any other option will be passed as a strategy to :func:`networkx.coloring.greedy_color` to generate the ordering. :type order: {'sort', None, 'random', str} :returns: Sequence of coordinate pairs. :rtype: list[tuple[node]] .. py:method:: __repr__() .. py:method:: draw(ordering='sort', show_norm=True, figsize=None, fontsize=8, legend=True, ax=None, **kwargs) Plot this Hamiltonian as a network. :param ordering: An ordering of the termns, or an argument to be supplied to :meth:`quimb.tensor.tensor_arbgeom_tebd.LocalHamGen.get_auto_ordering` to generate this automatically. :type ordering: {'sort', None, 'random'}, optional :param show_norm: Show the norm of each term as edge labels. :type show_norm: bool, optional :param figsize: Size of the figure, defaults to size of Hamiltonian. :type figsize: None or tuple[int], optional :param fontsize: Font size for norm labels. :type fontsize: int, optional :param legend: Whether to show the legend of which terms are in which group. :type legend: bool, optional :param ax: Add to a existing set of axes. :type ax: None or matplotlib.Axes, optional .. py:attribute:: graph .. py:class:: TEBDGen(psi0, ham, tau=0.01, D=None, cutoff=1e-10, imag=True, gate_opts=None, ordering=None, second_order_reflect=False, compute_energy_every=None, compute_energy_final=True, compute_energy_opts=None, compute_energy_fn=None, compute_energy_per_site=False, tol=None, callback=None, keep_best=False, progbar=True) Generic class for performing time evolving block decimation on an arbitrary graph, i.e. applying the exponential of a Hamiltonian using a product formula that involves applying local exponentiated gates only. .. py:attribute:: imag :value: True .. py:property:: state Return a copy of the current state. .. py:attribute:: ham .. py:attribute:: progbar :value: True .. py:attribute:: callback :value: None .. py:attribute:: tau :value: 0.01 .. py:attribute:: last_tau :value: 0.0 .. py:attribute:: gate_opts .. py:attribute:: compute_energy_opts .. py:attribute:: compute_energy_every :value: None .. py:attribute:: compute_energy_final :value: True .. py:attribute:: compute_energy_fn :value: None .. py:attribute:: compute_energy_per_site :value: False .. py:attribute:: tol :value: None .. py:attribute:: second_order_reflect :value: False .. py:attribute:: _n :value: 0 .. py:attribute:: its :value: [] .. py:attribute:: taus :value: [] .. py:attribute:: energies :value: [] .. py:attribute:: energy_diffs :value: [] .. py:attribute:: egrdm .. py:attribute:: keep_best :value: False .. py:attribute:: best .. py:attribute:: stop :value: False .. py:method:: sweep(tau) Perform a full sweep of gates at every pair. .. math:: \psi \rightarrow \prod_{\{ij\}} \exp(-\tau H_{ij}) \psi .. py:method:: _set_progbar_description(pbar) .. py:method:: evolve(steps, tau=None, progbar=None) Evolve the state with the local Hamiltonian for ``steps`` steps with time step ``tau``. .. py:property:: n The number of sweeps performed. .. py:property:: D The maximum bond dimension. .. py:method:: _check_energy() Logic for maybe computing the energy if needed. .. py:property:: energy Return the energy of current state, computing it only if necessary. .. py:method:: get_state() The default method for retrieving the current state - simply a copy. Subclasses can override this to perform additional transformations. .. py:method:: set_state(psi) The default method for setting the current state - simply a copy. Subclasses can override this to perform additional transformations. .. py:method:: presweep(i) Perform any computations required before the sweep (and energy computation). For the basic TEBD update is nothing. .. py:method:: postlayer() Perform any computations required after each layer of commuting gates. For the basic update this is nothing. .. py:method:: postsweep(i) Perform any computations required after the sweep (but before the energy computation). For the basic update this is nothing. .. py:method:: gate(U, where) Perform single gate ``U`` at coordinate pair ``where``. This is the the most common method to override. .. py:method:: compute_energy() Compute and return the energy of the current state. Subclasses can override this with a custom method to compute the energy. .. py:method:: plot(zoom='auto', xscale='symlog', xscale_linthresh=20, color_energy=(0.0, 0.5, 1.0), color_gauge_diff=(1.0, 0.5, 0.0), hlines=(), figsize=(8, 4)) Plot an overview of the evolution of the energy and gauge diffs. :param zoom: The number of iterations to zoom in on, or 'auto' to automatically choose a reasonable zoom level. :type zoom: int or 'auto', optional :param xscale: The x-axis scale, for the upper plot of the entire evolution. :type xscale: {'linear', 'log', 'symlog'}, optional :param xscale_linthresh: The linear threshold for the upper symlog scale. :type xscale_linthresh: float, optional :param color_energy: The color to use for the energy plot. :type color_energy: str or tuple, optional :param color_gauge_diff: The color to use for the gauge diff plot. :type color_gauge_diff: str or tuple, optional :param hlines: Add horizontal lines to the plot, with keys as labels and values as the y-values. :type hlines: dict, optional :param figsize: The size of the figure. :type figsize: tuple, optional :returns: **fig, axs** :rtype: matplotlib.Figure, tuple[matplotlib.Axes] .. py:method:: __repr__() .. py:class:: SimpleUpdateGen(psi0, ham, tau=0.01, D=None, cutoff=1e-10, imag=True, gate_opts=None, ordering=None, second_order_reflect=False, compute_energy_every=None, compute_energy_final=True, compute_energy_opts=None, compute_energy_fn=None, compute_energy_per_site=False, tol=None, equilibrate_every=0, equilibrate_start=True, equilibrate_opts=None, callback=None, keep_best=False, progbar=True) Bases: :py:obj:`TEBDGen` Simple update for arbitrary geometry hamiltonians. :param psi0: The initial state. :type psi0: TensorNetworkGenVector :param ham: The local hamiltonian. :type ham: LocalHamGen :param tau: The default time step to use. :type tau: float, optional :param D: The maximum bond dimension, by default the current maximum bond of ``psi0``. :type D: int, optional :param cutoff: The singular value cutoff to use when applying gates. :type cutoff: float, optional :param imag: Whether to evolve in imaginary time (default) or real time. :type imag: bool, optional :param gate_opts: Other options to supply to the gate application method, :meth:`quimb.tensor.tensor_arbgeom.TensorNetworkGenVector.gate_simple_`. :type gate_opts: dict, optional :param ordering: The ordering of the terms to apply, by default this will be determined automatically. :type ordering: None, str or callable, optional :param second_order_reflect: Whether to use a second order Trotter decomposition by reflecting the ordering. :type second_order_reflect: bool, optional :param compute_energy_every: Compute the energy every this many steps. :type compute_energy_every: int, optional :param compute_energy_final: Whether to compute the energy at the end. :type compute_energy_final: bool, optional :param compute_energy_opts: Options to supply to the energy computation method, :func:`quimb.tensor.tensor_arbgeom.TensorNetworkGenVector.compute_local_expectation_cluster`. :type compute_energy_opts: dict, optional :param compute_energy_fn: A custom function to compute the energy, with signature ``fn(su)``, where ``su`` is this instance. :type compute_energy_fn: callable, optional :param compute_energy_per_site: Whether to compute the energy per site. :type compute_energy_per_site: bool, optional :param tol: If not ``None``, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value. :type tol: float, optional :param equilibrate_every: Equilibrate the gauges every this many steps. :type equilibrate_every: int, optional :param equilibrate_start: Whether to equilibrate the gauges at the start, regardless of ``equilibrate_every``. :type equilibrate_start: bool, optional :param equilibrate_opts: Default options to supply to the gauge equilibration method, see :meth:`quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple`. By default `max_iterations` is set to 100 and `tol` to 1e-3. :type equilibrate_opts: dict, optional :param callback: A function to call after each step, with signature ``fn(su)``. :type callback: callable, optional :param keep_best: Whether to keep track of the best state and energy. :type keep_best: bool, optional :param progbar: Whether to show a progress bar during evolution. :type progbar: bool, optional .. py:attribute:: equilibrate_every :value: 0 .. py:attribute:: equilibrate_start :value: True .. py:attribute:: equilibrate_opts .. py:attribute:: gauges_prev :value: None .. py:attribute:: gauge_diffs :value: [] .. py:method:: gate(G, where) Application of a single gate ``G`` at ``where``. .. py:method:: equilibrate(**kwargs) Equilibrate the gauges with the current state (like evolving with tau=0). .. py:method:: postlayer() Performed after each layer of commuting gates. .. py:method:: postsweep(i) Performed after every full sweep. .. py:method:: normalize() Normalize the state and simple gauges. .. py:method:: compute_energy() Default estimate of the energy. .. py:method:: get_state(absorb_gauges=True) Return the current state, possibly absorbing the gauges. :param absorb_gauges: Whether to absorb the gauges into the state or not. If `True`, a standard PEPS is returned with the gauges absorbed. If `False``, the gauges are added to the tensor network but uncontracted. If "return", the gauges are returned separately. :type absorb_gauges: bool or "return", optional :returns: * **psi** (*TensorNetwork*) -- The current state. * **gauges** (*dict*) -- The current gauges, if ``absorb_gauges == "return"``. .. py:method:: set_state(psi, gauges=None) Set the current state and possibly the gauges.