quimb.tensor.tn2d.tebd ====================== .. py:module:: quimb.tensor.tn2d.tebd .. autoapi-nested-parse:: Tools for performing TEBD like algorithms on a 2D lattice. Classes ------- .. autoapisummary:: quimb.tensor.tn2d.tebd.LocalHam2D quimb.tensor.tn2d.tebd.ComputeEnergyBoundary quimb.tensor.tn2d.tebd.TEBD2D quimb.tensor.tn2d.tebd.SimpleUpdate quimb.tensor.tn2d.tebd.FullUpdate Functions --------- .. autoapisummary:: quimb.tensor.tn2d.tebd.conditioner quimb.tensor.tn2d.tebd.gate_full_update_als quimb.tensor.tn2d.tebd.gate_full_update_autodiff_fidelity quimb.tensor.tn2d.tebd.get_default_full_update_fit_opts quimb.tensor.tn2d.tebd.parse_specific_gate_opts Module Contents --------------- .. py:class:: LocalHam2D(Lx, Ly, H2, H1=None, cyclic=False) Bases: :py:obj:`quimb.tensor.tnag.tebd.LocalHamGen` A 2D Hamiltonian represented as local terms. 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. :param Lx: The number of rows. :type Lx: int :param Ly: The number of columns. :type Ly: int :param H2: The two site term(s). If a single array is given, assume to be the default interaction for all nearest neighbours. If a dict is supplied, the keys should represent specific pairs of coordinates like ``((ia, ja), (ib, jb))`` with the values the array representing the interaction for that pair. A default term for all remaining nearest neighbours interactions can still be supplied with the key ``None``. :type H2: array_like or dict[tuple[tuple[int]], 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[tuple[int], 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 ``ija, ijb`` with ``ija < ijb``. :type: dict[tuple[tuple[int]], array_like] .. py:attribute:: Lx .. py:attribute:: Ly .. py:property:: nsites The number of sites in the system. .. py:method:: build_pepo_propagator_trotterized(x, ordering='sort', site_tag_id='I{},{}', tags=None, upper_ind_id='k{},{}', lower_ind_id='b{},{}', shape='urdlbk', contract_sites=True, **split_opts) Build a PEPO representation of ``expm(H * x)``, i.e. the imaginary or real time propagator of this local 2D hamiltonian, using a first order trotterized decomposition. :param x: The time to evolve for. Note this does **not** include the imaginary prefactor of the Schrodinger equation, so real ``x`` corresponds to imaginary time evolution, and vice versa. :type x: float :param site_tag_id: A string specifying how to tag the tensors at each site. Should contain two ``'{}'`` placeholders for (row, col). It is used to generate the actual tags like: ``site_tag_id.format(i, j)``. :type site_tag_id: str :param tags: Global tags to attach to all tensors. :type tags: str or sequence of str, optional :param upper_ind_id: A string specifying how to label the upper physical site indices. Should contain two ``'{}'`` placeholders for (row, col). :type upper_ind_id: str :param lower_ind_id: A string specifying how to label the lower physical site indices. Should contain two ``'{}'`` placeholders for (row, col). :type lower_ind_id: str :param shape: String specifying layout of the tensors. E.g. 'urdlbk' (the default) indicates the shape corresponds up-bond, right-bond, down-bond, left-bond, bra (lower) physical index, ket (upper) physical index. :type shape: str, optional :param contract_sites: Whether to contract all the decomposed factors at each site to yield a single tensor per site, by default True. :type contract_sites: bool, optional :param split_opts: Supplied to :func:`~quimb.tensor.tensor_core.tensor_split`. :rtype: PEPO .. 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.tn1d.tebd.LocalHam2D.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:: ComputeEnergyBoundary Bases: :py:obj:`quimb.tensor.tnag.tebd.ComputeEnergyMixin` Mixin class to add energy computation to TEBD2D classes. .. py:method:: setup_energy_opts(chi=None, compute_energy_every=None, compute_energy_final=True, compute_energy_opts=None, compute_energy_fn=None, compute_energy_per_site=False) .. py:property:: chi The bond dimensino to use for contracting the boundary for when computing the energy. .. py:method:: compute_energy() Compute and return the total energy of the current state, using boundary contraction. .. py:method:: _get_repr_info() .. py:class:: TEBD2D(psi0, ham, tau=0.01, D=None, cutoff=1e-10, chi=None, 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, tol_energy_diff=None, callback=None, keep_best=False, plot_every=None, progbar=True) Bases: :py:obj:`ComputeEnergyBoundary`, :py:obj:`quimb.tensor.tnag.tebd.GateBasicMixin`, :py:obj:`quimb.tensor.tnag.tebd.TEBDSweepMixin` Generic class for performing two dimensional time evolving block decimation, i.e. applying the exponential of a Hamiltonian using a product formula that involves applying local exponentiated gates only. The only difference between this and `TEBDGen` is that the default energy computation uses boundary contraction specific to 2D tensor networks, with a default boundary bond dimension of ``max(8, D**2)``. :param psi0: The initial state. :type psi0: PEPS :param ham: The local hamiltonian. :type ham: LocalHam2D :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.tnag.core.TensorNetworkGenVector.gate_`. :type gate_opts: dict, optional :param ordering: The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to :meth:`quimb.tensor.tnag.tebd.LocalHam2D.get_auto_ordering`, a callable which returns an ordering when called, or a fixed sequence of coordinate pairs. :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, :meth:`~quimb.tensor.tn2d.core.PEPS.compute_local_expectation`. :type compute_energy_opts: dict, optional :param compute_energy_fn: A custom function to compute the energy, with signature ``fn(tebd: TEBD2D)``, where ``tebd`` 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 tol_energy_diff: If not ``None``, stop when specifically the energy difference falls below this value. :type tol_energy_diff: float, optional :param callback: A function to call after each step, with signature ``fn(tebd: TEBD2D)``, where ``tebd`` is this instance. :type callback: callable, optional :param keep_best: Whether to keep track of the best state and energy. If ``True``, the best state found during evolution will be stored in the ``best`` attribute. :type keep_best: bool, optional :param plot_every: Whether to plot the energy and energy difference every this many steps. :type plot_every: int, optional :param progbar: Whether to show a progress bar during evolution. :type progbar: bool, optional .. attribute:: state The current state. :type: PEPS .. attribute:: D The maximum bond dimension. :type: int .. attribute:: n The number of sweeps performed. :type: int .. attribute:: energy The energy of the current state, computed only if necessary. :type: float .. attribute:: energies The history of computed energies. :type: list[float] .. attribute:: energy_diffs The history of energy differences. :type: list[float] .. attribute:: energy_ns The iteration numbers at which energies were computed. :type: list[int] .. attribute:: taus The time steps used at each energy computation. :type: list[float] .. attribute:: best If ``keep_best`` is ``True``, this dictionary will contain the best energy found during evolution under the key ``'energy'``, the state which achieved this energy under the key ``'state'``, and the iteration number under the key ``'it'``. :type: dict .. seealso:: :py:obj:`SimpleUpdate` .. py:function:: conditioner(tn, value=None, sweeps=2, balance_bonds=True) .. py:class:: SimpleUpdate(psi0: quimb.tensor.tn2d.core.PEPS, ham: LocalHam2D, tau=0.01, D=None, chi=None, cutoff=1e-10, imag=True, gate_opts=None, gauge_smudge=1e-06, ordering=None, second_order_reflect=False, update='sequential', compute_energy_every=None, compute_energy_final=True, compute_energy_opts=None, compute_energy_fn=None, compute_energy_per_site=False, tol=None, tol_energy_diff=None, equilibrate_every=None, equilibrate_start=True, equilibrate_opts=None, gauge_diff_period=None, callback=None, keep_best=False, plot_every=None, progbar=True) Bases: :py:obj:`ComputeEnergyBoundary`, :py:obj:`quimb.tensor.tnag.tebd.GateSimpleUpdateMixin`, :py:obj:`quimb.tensor.tnag.tebd.TEBDSweepMixin` Simple Update algorithm for OBC 2D PEPS, storing gauges separately, and using boundary contraction to compute energy. Reference: https://arxiv.org/abs/0806.3719. :param psi0: The initial state. :type psi0: PEPS :param ham: The local hamiltonian. :type ham: LocalHam2D :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 chi: The bond dimension to use when computing the energy. By default ``max(8, D**2)``. :type chi: 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.tnag.core.TensorNetworkGenVector.gate_simple_`. :type gate_opts: dict, optional :param ordering: The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to :meth:`quimb.tensor.tnag.tebd.LocalHamGen.get_auto_ordering`, a callable which returns an ordering when called, or a fixed sequence of coordinate pairs. :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, :meth:`~quimb.tensor.tn2d.core.PEPS.compute_local_expectation`. :type compute_energy_opts: dict, optional :param compute_energy_fn: A custom function to compute the energy, with signature ``fn(su: SimpleUpdate)``, 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 tol_energy_diff: If not ``None``, stop when specifically the energy difference falls below this value. :type tol_energy_diff: 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: SimpleUpdate)``. :type callback: callable, optional :param keep_best: Whether to keep track of the best state and energy. If ``True``, the best state found during evolution will be stored in the ``best`` attribute. :type keep_best: bool, optional :param plot_every: Whether to plot the energy and energy difference every this many steps. :type plot_every: int, optional :param progbar: Whether to show a progress bar during evolution. :type progbar: bool, optional .. attribute:: state The current state. :type: PEPS .. attribute:: D The maximum bond dimension. :type: int .. attribute:: n The number of sweeps performed. :type: int .. attribute:: energy The energy of the current state, computed only if necessary. :type: float .. attribute:: energies The history of computed energies. :type: list[float] .. attribute:: energy_diffs The history of energy differences. :type: list[float] .. attribute:: energy_ns The iteration numbers at which energies were computed. :type: list[int] .. attribute:: taus The time steps used at each energy computation. :type: list[float] .. attribute:: best If ``keep_best`` is ``True``, this dictionary will contain the best energy found during evolution under the key ``'energy'``, the state which achieved this energy under the key ``'state'``, and the iteration number under the key ``'it'``. :type: dict .. attribute:: equilibration_ns The iteration numbers at which gauge equilibration was performed. :type: list[int] .. attribute:: equilibration_iterations The number of iterations taken during each gauge equilibration. :type: list[int] .. attribute:: equilibration_max_sdiffs The maximum singular value difference during each gauge equilibration. :type: list[float] .. attribute:: gauge_diffs The history of maximum gauge differences after each sweep. :type: list[float] .. seealso:: :py:obj:`TEBD2D`, :py:obj:`SimpleUpdateGen` .. py:function:: gate_full_update_als(ket, env, bra, G, where, tags_plq, steps, tol, max_bond, optimize='auto-hq', solver='solve', dense=True, enforce_pos=False, pos_smudge=1e-06, init_simple_guess=True, condition_tensors=True, condition_maintain_norms=True, condition_balance_bonds=True) .. py:function:: gate_full_update_autodiff_fidelity(ket, env, bra, G, where, tags_plq, steps, tol, max_bond, optimize='auto-hq', autodiff_backend='autograd', autodiff_optimizer='L-BFGS-B', init_simple_guess=True, condition_tensors=True, condition_maintain_norms=True, condition_balance_bonds=True, **kwargs) .. py:function:: get_default_full_update_fit_opts() The default options for the full update gate fitting procedure. .. py:function:: parse_specific_gate_opts(strategy, fit_opts) Parse the options from ``fit_opts`` which are relevant for ``strategy``. .. py:class:: FullUpdate(psi0, ham, tau=0.01, D=None, chi=None, fit_strategy='als', fit_opts=None, compute_envs_every=1, pre_normalize=True, condition_tensors=True, condition_balance_bonds=True, contract_optimize='auto-hq', 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, callback=None, keep_best=False, progbar=True) Bases: :py:obj:`TEBD2D` Implements the 'Full Update' version of 2D imaginary time evolution, where each application of a gate is fitted to the current tensors using a boundary contracted environment. :param psi0: The initial state. :type psi0: TensorNetwork2DVector :param ham: The Hamtiltonian consisting of local terms. :type ham: LocalHam2D :param tau: The default local exponent, if considered as time real values here imply imaginary time. :type tau: float, optional :param max_bond: The maximum bond dimension to keep when applying each gate. :type max_bond: {'psi0', int, None}, optional :param gate_opts: Supplied to :meth:`quimb.tensor.tn2d.core.TensorNetwork2DVector.gate`, in addition to ``max_bond``. By default ``contract`` is set to 'reduce-split' and ``cutoff`` is set to ``0.0``. :type gate_opts: dict, optional :param ordering: How to order the terms, if a string is given then use this as the strategy given to :meth:`~quimb.tensor.tn1d.tebd.LocalHam2D.get_auto_ordering`. An explicit list of coordinate pairs can also be given. The default is to greedily form an 'edge coloring' based on the sorted list of Hamiltonian pair coordinates. If a callable is supplied it will be used to generate the ordering before each sweep. :type ordering: str, tuple[tuple[int]], callable, optional :param second_order_reflect: If ``True``, then apply each layer of gates in ``ordering`` forward with half the time step, then the same with reverse order. :type second_order_reflect: bool, optional :param compute_energy_every: How often to compute and record the energy. If a positive integer 'n', the energy is computed *before* every nth sweep (i.e. including before the zeroth). :type compute_energy_every: None or int, optional :param compute_energy_final: Whether to compute and record the energy at the end of the sweeps regardless of the value of ``compute_energy_every``. If you start sweeping again then this final energy is the same as the zeroth of the next set of sweeps and won't be recomputed. :type compute_energy_final: bool, optional :param compute_energy_opts: Supplied to :meth:`~quimb.tensor.tn2d.core.PEPS.compute_local_expectation`. By default ``max_bond`` is set to ``max(8, D**2)`` where ``D`` is the maximum bond to use for applying the gate, ``cutoff`` is set to ``0.0`` and ``normalized`` is set to ``True``. :type compute_energy_opts: dict, optional :param compute_energy_fn: Supply your own function to compute the energy, it should take the ``TEBD2D`` object as its only argument. :type compute_energy_fn: callable, optional :param callback: A custom callback to run after every sweep, it should take the ``TEBD2D`` object as its only argument. If it returns any value that boolean evaluates to ``True`` then terminal the evolution. :type callback: callable, optional :param progbar: Whether to show a live progress bar during the evolution. :type progbar: boolean, optional :param fit_strategy: Core method used to fit the gate application. * ``'als'``: alternating least squares * ``'autodiff-fidelity'``: local fidelity using autodiff :type fit_strategy: {'als', 'autodiff-fidelity'}, optional :param fit_opts: Advanced options for the gate application fitting functions. Defaults are inserted and can be accessed via the ``.fit_opts`` attribute. :type fit_opts: dict, optional :param compute_envs_every: How often to recompute the environments used to the fit the gate application: * ``'term'``: every gate * ``'group'``: every set of commuting gates (the default) * ``'sweep'``: every total sweep * int: every ``x`` number of total sweeps :type compute_envs_every: {'term', 'group', 'sweep', int}, optional :param pre_normalize: Actively renormalize the state using the computed environments. :type pre_normalize: bool, optional :param condition_tensors: Whether to actively equalize tensor norms for numerical stability. :type condition_tensors: bool, optional :param condition_balance_bonds: If and when equalizing tensor norms, whether to also balance bonds as an additional conditioning. :type condition_balance_bonds: bool, optional :param contract_optimize: Contraction path optimizer to use for gate + env + sites contractions. :type contract_optimize: str, optional .. attribute:: state The current state. :type: TensorNetwork2DVector .. attribute:: ham The Hamiltonian being used to evolve. :type: LocalHam2D .. attribute:: energy The current of the current state, this will trigger a computation if the energy at this iteration hasn't been computed yet. :type: float .. attribute:: energies The energies that have been computed, if any. :type: list[float] .. attribute:: its The corresponding sequence of iteration numbers that energies have been computed at. :type: list[int] .. attribute:: taus The corresponding sequence of time steps that energies have been computed at. :type: list[float] .. attribute:: best If ``keep_best`` was set then the best recorded energy and the corresponding state that was computed - keys ``'energy'`` and ``'state'`` respectively. :type: dict .. attribute:: fit_opts Detailed options for fitting the applied gate. :type: dict .. py:property:: fit_strategy .. py:attribute:: fit_opts .. py:attribute:: pre_normalize :value: True .. py:attribute:: contract_optimize :value: '' .. py:attribute:: condition_tensors :value: True .. py:attribute:: condition_balance_bonds :value: True .. py:property:: compute_envs_every .. 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:: _maybe_compute_plaquette_envs(force=False) Compute and store the plaquette environments for all local terms. .. py:method:: presweep(i=None) Full update presweep - compute envs and inject gate options. .. py:method:: compute_energy() Full update compute energy - use the (likely) already calculated plaquette environments. .. py:method:: gate(G, where) Apply the gate ``G`` at sites where, using a fitting method that takes into account the current environment.