quimb.tensor.tn2d.tebd¶

Tools for performing TEBD like algorithms on a 2D lattice.

Classes¶

`LocalHam2D`	A 2D Hamiltonian represented as local terms. This combines all two site
`ComputeEnergyBoundary`	Mixin class to add energy computation to TEBD2D classes.
`TEBD2D`	Generic class for performing two dimensional time evolving block
`SimpleUpdate`	Simple Update algorithm for OBC 2D PEPS, storing gauges separately, and
`FullUpdate`	Implements the 'Full Update' version of 2D imaginary time evolution,

Functions¶

`conditioner`(tn[, value, sweeps, balance_bonds])
`gate_full_update_als`(ket, env, bra, G, where, ...[, ...])
`gate_full_update_autodiff_fidelity`(ket, env, bra, G, ...)
`get_default_full_update_fit_opts`()	The default options for the full update gate fitting procedure.
`parse_specific_gate_opts`(strategy, fit_opts)	Parse the options from `fit_opts` which are relevant for `strategy`.

Module Contents¶

class quimb.tensor.tn2d.tebd.LocalHam2D(Lx, Ly, H2, H1=None, cyclic=False)[source]¶

Bases: 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.

Parameters:

Lx (int) – The number of rows.
Ly (int) – The number of columns.
H2 (array_like or dict[tuple[tuple[int]], array_like]) – 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.
H1 (array_like or dict[tuple[int], array_like], optional) – 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.

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]

Lx¶

Ly¶

property nsites¶: The number of sites in the system.

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)[source]¶

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.

Parameters:

x (float) – 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.
site_tag_id (str) – 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).
tags (str or sequence of str, optional) – Global tags to attach to all tensors.
upper_ind_id (str) – A string specifying how to label the upper physical site indices. Should contain two '{}' placeholders for (row, col).
lower_ind_id (str) – A string specifying how to label the lower physical site indices. Should contain two '{}' placeholders for (row, col).
shape (str, optional) – 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.
contract_sites (bool, optional) – Whether to contract all the decomposed factors at each site to yield a single tensor per site, by default True.
split_opts – Supplied to tensor_split().

Return type:

PEPO

__repr__()[source]¶

draw(ordering='sort', show_norm=True, figsize=None, fontsize=8, legend=True, ax=None, **kwargs)[source]¶

Plot this Hamiltonian as a network.

Parameters:

ordering ({'sort', None, 'random'}, optional) – An ordering of the termns, or an argument to be supplied to quimb.tensor.tn1d.tebd.LocalHam2D.get_auto_ordering() to generate this automatically.
show_norm (bool, optional) – Show the norm of each term as edge labels.
figsize (None or tuple[int], optional) – Size of the figure, defaults to size of Hamiltonian.
fontsize (int, optional) – Font size for norm labels.
legend (bool, optional) – Whether to show the legend of which terms are in which group.
ax (None or matplotlib.Axes, optional) – Add to a existing set of axes.

graph[source]¶

class quimb.tensor.tn2d.tebd.ComputeEnergyBoundary[source]¶

Bases: quimb.tensor.tnag.tebd.ComputeEnergyMixin

Mixin class to add energy computation to TEBD2D classes.

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)[source]¶

property chi¶: The bond dimensino to use for contracting the boundary for when computing the energy.

compute_energy()[source]¶: Compute and return the total energy of the current state, using boundary contraction.

_get_repr_info()[source]¶

class quimb.tensor.tn2d.tebd.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)[source]¶

Bases: ComputeEnergyBoundary, quimb.tensor.tnag.tebd.GateBasicMixin, 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).

Parameters:

psi0 (PEPS) – The initial state.
ham (LocalHam2D) – The local hamiltonian.
tau (float, optional) – The default time step to use.
D (int, optional) – The maximum bond dimension, by default the current maximum bond of psi0.
cutoff (float, optional) – The singular value cutoff to use when applying gates.
imag (bool, optional) – Whether to evolve in imaginary time (default) or real time.
gate_opts (dict, optional) – Other options to supply to the gate application method, quimb.tensor.tnag.core.TensorNetworkGenVector.gate_().
ordering (None, str or callable, optional) – The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to quimb.tensor.tnag.tebd.LocalHam2D.get_auto_ordering(), a callable which returns an ordering when called, or a fixed sequence of coordinate pairs.
second_order_reflect (bool, optional) – Whether to use a second order Trotter decomposition by reflecting the ordering.
compute_energy_every (int, optional) – Compute the energy every this many steps.
compute_energy_final (bool, optional) – Whether to compute the energy at the end.
compute_energy_opts (dict, optional) – Options to supply to the energy computation method, compute_local_expectation().
compute_energy_fn (callable, optional) – A custom function to compute the energy, with signature fn(tebd: TEBD2D), where tebd is this instance.
compute_energy_per_site (bool, optional) – Whether to compute the energy per site.
tol (float, optional) – If not None, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value.
tol_energy_diff (float, optional) – If not None, stop when specifically the energy difference falls below this value.
callback (callable, optional) – A function to call after each step, with signature fn(tebd: TEBD2D), where tebd is this instance.
keep_best (bool, optional) – 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.
plot_every (int, optional) – Whether to plot the energy and energy difference every this many steps.
progbar (bool, optional) – Whether to show a progress bar during evolution.

state¶

The current state.

Type:: PEPS

D¶

The maximum bond dimension.

Type:: int

n¶

The number of sweeps performed.

Type:: int

energy¶

The energy of the current state, computed only if necessary.

Type:: float

energies¶

The history of computed energies.

Type:: list[float]

energy_diffs¶

The history of energy differences.

Type:: list[float]

energy_ns¶

The iteration numbers at which energies were computed.

Type:: list[int]

taus¶

The time steps used at each energy computation.

Type:: list[float]

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

See also

SimpleUpdate

quimb.tensor.tn2d.tebd.conditioner(tn, value=None, sweeps=2, balance_bonds=True)[source]¶

class quimb.tensor.tn2d.tebd.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)[source]¶

Bases: ComputeEnergyBoundary, quimb.tensor.tnag.tebd.GateSimpleUpdateMixin, 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.

Parameters:

psi0 (PEPS) – The initial state.
ham (LocalHam2D) – The local hamiltonian.
tau (float, optional) – The default time step to use.
D (int, optional) – The maximum bond dimension, by default the current maximum bond of psi0.
chi (int, optional) – The bond dimension to use when computing the energy. By default max(8, D**2).
cutoff (float, optional) – The singular value cutoff to use when applying gates.
imag (bool, optional) – Whether to evolve in imaginary time (default) or real time.
gate_opts (dict, optional) – Other options to supply to the gate application method, quimb.tensor.tnag.core.TensorNetworkGenVector.gate_simple_().
ordering (None, str or callable, optional) – The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to quimb.tensor.tnag.tebd.LocalHamGen.get_auto_ordering(), a callable which returns an ordering when called, or a fixed sequence of coordinate pairs.
second_order_reflect (bool, optional) – Whether to use a second order Trotter decomposition by reflecting the ordering.
compute_energy_every (int, optional) – Compute the energy every this many steps.
compute_energy_final (bool, optional) – Whether to compute the energy at the end.
compute_energy_opts (dict, optional) – Options to supply to the energy computation method, compute_local_expectation().
compute_energy_fn (callable, optional) – A custom function to compute the energy, with signature fn(su: SimpleUpdate), where su is this instance.
compute_energy_per_site (bool, optional) – Whether to compute the energy per site.
tol (float, optional) – If not None, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value.
tol_energy_diff (float, optional) – If not None, stop when specifically the energy difference falls below this value.
equilibrate_every (int, optional) – Equilibrate the gauges every this many steps.
equilibrate_start (bool, optional) – Whether to equilibrate the gauges at the start, regardless of equilibrate_every.
equilibrate_opts (dict, optional) – Default options to supply to the gauge equilibration method, see quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple(). By default max_iterations is set to 100 and tol to 1e-3.
callback (callable, optional) – A function to call after each step, with signature fn(su: SimpleUpdate).
keep_best (bool, optional) – 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.
plot_every (int, optional) – Whether to plot the energy and energy difference every this many steps.
progbar (bool, optional) – Whether to show a progress bar during evolution.

state¶

The current state.

Type:: PEPS

D¶

The maximum bond dimension.

Type:: int

n¶

The number of sweeps performed.

Type:: int

energy¶

The energy of the current state, computed only if necessary.

Type:: float

energies¶

The history of computed energies.

Type:: list[float]

energy_diffs¶

The history of energy differences.

Type:: list[float]

energy_ns¶

The iteration numbers at which energies were computed.

Type:: list[int]

taus¶

The time steps used at each energy computation.

Type:: list[float]

best¶

Type:: dict

equilibration_ns¶

The iteration numbers at which gauge equilibration was performed.

Type:: list[int]

equilibration_iterations¶

The number of iterations taken during each gauge equilibration.

Type:: list[int]

equilibration_max_sdiffs¶

The maximum singular value difference during each gauge equilibration.

Type:: list[float]

gauge_diffs¶

The history of maximum gauge differences after each sweep.

Type:: list[float]

See also

TEBD2D, SimpleUpdateGen

quimb.tensor.tn2d.tebd.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)[source]¶

quimb.tensor.tn2d.tebd.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)[source]¶

quimb.tensor.tn2d.tebd.get_default_full_update_fit_opts()[source]¶: The default options for the full update gate fitting procedure.

quimb.tensor.tn2d.tebd.parse_specific_gate_opts(strategy, fit_opts)[source]¶: Parse the options from fit_opts which are relevant for strategy.

class quimb.tensor.tn2d.tebd.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)[source]¶

Bases: 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.

Parameters:

psi0 (TensorNetwork2DVector) – The initial state.
ham (LocalHam2D) – The Hamtiltonian consisting of local terms.
tau (float, optional) – The default local exponent, if considered as time real values here imply imaginary time.
max_bond ({'psi0', int, None}, optional) – The maximum bond dimension to keep when applying each gate.
gate_opts (dict, optional) – Supplied to 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.
ordering (str, tuple[tuple[int]], callable, optional) – How to order the terms, if a string is given then use this as the strategy given to 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.
second_order_reflect (bool, optional) – If True, then apply each layer of gates in ordering forward with half the time step, then the same with reverse order.
compute_energy_every (None or int, optional) – 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).
compute_energy_final (bool, optional) – 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.
compute_energy_opts (dict, optional) – Supplied to 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.
compute_energy_fn (callable, optional) – Supply your own function to compute the energy, it should take the TEBD2D object as its only argument.
callback (callable, optional) – 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.
progbar (boolean, optional) – Whether to show a live progress bar during the evolution.
fit_strategy ({'als', 'autodiff-fidelity'}, optional) –
Core method used to fit the gate application.
- 'als': alternating least squares
- 'autodiff-fidelity': local fidelity using autodiff
fit_opts (dict, optional) – Advanced options for the gate application fitting functions. Defaults are inserted and can be accessed via the .fit_opts attribute.
compute_envs_every ({'term', 'group', 'sweep', int}, optional) –
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
pre_normalize (bool, optional) – Actively renormalize the state using the computed environments.
condition_tensors (bool, optional) – Whether to actively equalize tensor norms for numerical stability.
condition_balance_bonds (bool, optional) – If and when equalizing tensor norms, whether to also balance bonds as an additional conditioning.
contract_optimize (str, optional) – Contraction path optimizer to use for gate + env + sites contractions.

state¶

The current state.

Type:: TensorNetwork2DVector

ham¶

The Hamiltonian being used to evolve.

Type:: LocalHam2D

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

energies¶

The energies that have been computed, if any.

Type:: list[float]

its¶

The corresponding sequence of iteration numbers that energies have been computed at.

Type:: list[int]

taus¶

The corresponding sequence of time steps that energies have been computed at.

Type:: list[float]

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

fit_opts¶

Detailed options for fitting the applied gate.

Type:: dict

property fit_strategy¶

fit_opts¶

pre_normalize = True¶

contract_optimize = ''¶

condition_tensors = True¶

condition_balance_bonds = True¶

property compute_envs_every¶

set_state(psi)[source]¶: The default method for setting the current state - simply a copy. Subclasses can override this to perform additional transformations.

_maybe_compute_plaquette_envs(force=False)[source]¶: Compute and store the plaquette environments for all local terms.

presweep(i=None)[source]¶: Full update presweep - compute envs and inject gate options.

compute_energy()[source]¶: Full update compute energy - use the (likely) already calculated plaquette environments.

gate(G, where)[source]¶: Apply the gate G at sites where, using a fitting method that takes into account the current environment.