Environments#

Contractions of PEPS lattice are supported by environment classes. Those include:

yastn.tn.fpeps.EnvNTU supports a family of NTU approximations of the bond metric for time evolution.
yastn.tn.fpeps.EnvCTM CTMRG for finite or infinite lattices. Supports local expectation values, bond metric, etc.
yastn.tn.fpeps.EnvBoundaryMps BoundaryMPS for contracting finite lattice. It supports expectation values, including long-range correlations, sampling, etc.
yastn.tn.fpeps.EnvApproximate Supports calculation of bond metric for larger clusters that are contracted approximately.

Neighberhood tensor update environments#

class yastn.tn.fpeps.EnvNTU(psi, which='NN')[source]#

NTU environments for truncation of PEPS tensors during time evolution.

Parameters:

psi (yastn.tn.Peps) – State being evolved.
which (str) – Type of environment from ‘NN’, ‘NN+’, ‘NN++’, ‘NNN’, ‘NNN+’, ‘NNN++’

bond_metric(Q0, Q1, s0, s1, dirn)[source]#

Calculate bond metric, with the size of environment controlled by which.

Below, double lines indicate core bonds that are contracted exactly. Single lines indicate tree-like approximations of border tensors resulting from their rank-one SVD decomposition.

If which == 'NN':
         (-1, +0)==(-1, +1)
            ||        ||
(+0, -1) == Q0++    ++Q1 == (+0, +2)
            ||        ||
         (+1, +0)==(+1, +1)

If which == 'NN+':
                  (-2, +0)  (-2, +1)
                     ||        ||
         (-1, -1)-(-1, +0)==(-1, +1)-(-1, +2)
               :       ||        ||       :
(+0, -2)=(+0, -1) == Q0++    ++Q1 == (+0, +2)=(+0, +3)
               :       ||        ||       :
         (+1, -1)-(+1, +0)==(+1, +1)-(+1, +2)
                     ||        ||
                  (+2, +0)  (+2, +1)

If which == 'NN++':
                           (-3, +0)--(-3, +1)
                              :         :
                  (-2, -1)-(-2, +0)--(-2, +1)-(-2, +2)
                        :       :         :        :
         (-1, -2)-(-1, -1)-(-1, +0)==(-1, +1)-(-1, +2)-(-1, +3)
               :        :       ||        ||       :        :
(+0, -3)=(+0, -2)=(+0, -1) == Q0++    ++Q1 == (+0, +2)=(+0, +3)=(+0, +4)
               :        :       ||        ||       :        :
         (+1, -2)-(+1, -1)-(+1, +0)==(+1, +1)-(+1, +2)-(+1, +3)
                        :       :         :        :
                  (+2, -1)-(+2, +0)--(+2, +1)-(+2, +2)
                              :         :
                           (+3, +0)--(+3, +1)

If which == 'NNN':
(-1, -1)=(-1, +0)==(-1, +1)=(-1, +2)
   ||       ||        ||       ||
(+0, -1) == GA++    ++GB == (+0, +2)
   ||       ||        ||       ||
(+1, -1)=(+1, +0)==(+1, +1)=(+1, +2)

If which == 'NNN+':
         (-2, -1) (-2, +0)  (-2, +1) (-2, +2)
            ||       ||        ||       ||
(-1, -2)=(-1, -1)=(-1, +0)==(-1, +1)=(-1, +2)=(-1, +3)
            ||       ||        ||       ||
(+0, -2)=(+0, -1) == GA++    ++GB == (+0, +2)=(+0, +3)
            ||       ||        ||       ||
(+1, -2)=(+1, -1)=(+1, +0)==(+1, +1)=(+1, +2)=(+1, +3)
            ||       ||        ||       ||
         (+2, -1) (+2, +0)  (+2, +1) (+2, +2)

If which == 'NNN++':
         (-3, -2)-(-3, -1)-(-3, +0)--(-3, +1)-(-3, +2)-(-3, +3)
            :        :        :         :        :        :
(-2, -3)-(-2, -2)-(-2, -1)-(-2, +0)--(-2, +1)-(-2, +2)-(-2, +3)-(-2, +4)
   :        :        :        :         :        :        :        :
(-1, -3)-(-1, -2)-(-1, -1)=(-1, +0)==(-1, +1)=(-1, +2)-(-1, +3)-(-1, +4)
   :        :        ||       ||        ||       ||       :        :
(+0, -3)=(+0, -2)=(+0, -1) == GA++    ++GB == (+0, +2)=(+0, +3)=(+0, +4)
   :        :        ||       ||        ||       ||       :        :
(+1, -3)-(+1, -2)-(+1, -1)=(+1, +0)==(+1, +1)=(+1, +2)-(+1, +3)-(+1, +4)
   :        :        :        :         :        :        :        :
(+2, -3)-(+2, -2)-(+2, -1)-(+2, +0)--(+2, +1)-(+2, +2)-(+2, +3)-(+2, +4)
            :        :        :         :        :        :
         (+3, -2)-(+3, -1)-(+3, +0)--(+3, +1)-(+3, +2)-(+3, +3)

Corner transfer matrix renormalization group (CTMRG)#

yastn.tn.fpeps.EnvCTM associates with each lattice site a local CTM environment, that can be accessed via [], and contracted PEPS of rank-4 tensors available via atribute psi. The convention for ordering the indices in the CTMRG environment tensors are:

 _______             _______             _______
|       |           |       |           |       |
|  C_nw |--1     0--|  T_n  |--2     0--|  C_ne |
|_______|           |_______|           |_______|
    |                   |                   |
    0                   1                   1

    2                   0                   0
 ___|___             ___|___             ___|___
|       |           |       |           |       |
|  T_w  |--1     1--|   O   |--3     1--|  T_e  |
|_______|           |_______|           |_______|
    |                   |                   |
    0                   2                   2

    1                   1                   0
 ___|___             ___|___             ___|___
|       |           |       |           |       |
|  C_sw |--0     2--|  T_s  |--0     1--|  C_se |
|_______|           |_______|           |_______|

A single iteration of the CTMRG update, consisting of horizontal and vertical moves, is performed with yastn.tn.fpeps.EnvCTM.update_(). One can stop the CTM after a fixed number of iterations, or e.g., convergence of corner singular values. Stopping criteria can also be set based on the convergence of one or more observables, for example, total energy. Once the CTMRG converges, it is straightforward to obtain one-site yastn.tn.fpeps.EnvCTM.measure_1site() and two-site nearest-neighbor observables yastn.tn.fpeps.EnvCTM.measure_nn().

class yastn.tn.fpeps.EnvCTM(psi, init='rand', leg=None)[source]#

Environment used in Corner Transfer Matrix Renormalization algorithm.

Parameters:

psi (yastn.tn.Peps) – Peps lattice to be contracted using CTM. If psi has physical legs, a double-layer PEPS with no physical legs is formed.
init (str) – None, ‘eye’ or ‘rand’. Initialization scheme, see yastn.tn.fpeps.EnvCTM.reset_().
leg (yastn.Leg | None) – Passed to yastn.tn.fpeps.EnvCTM.reset_().

bond_metric(Q0, Q1, s0, s1, dirn)[source]#

Calculates Full-Update metric tensor.

If dirn == 'h':
    tl == tt  ==  tt == tr
    |     |        |     |
    ll == GA-+  +-GB == rr
    |     |        |     |
    bl == bb  ==  bb == br

If dirn == 'v':
    tl == tt == tr
    |     |      |
    ll == GA == rr
    |     ++     |
    ll == GB == rr
    |     |      |
    bl == bb == br

ctmrg_(opts_svd=None, method='2site', max_sweeps=1, iterator_step=None, corner_tol=None)[source]#

Perform CTMRG updates yastn.tn.fpeps.EnvCTM.update_() until convergence. Convergence is measured based on singular values of CTM environment corner tensors.

Outputs iterator if iterator_step is given, which allows inspecting env, e.g., calculating expectation values, outside of ctmrg_ function after every iterator_step sweeps.

Parameters:

opts_svd (dict) – A dictionary of options to pass to the SVD algorithm.
method (str) – ‘2site’ or ‘1site’. The default is ‘2site’. ‘2site’ uses the standard 4x4 enlarged corners, allowing to enlarge EnvCTM bond dimension. ‘1site’ uses smaller 4x2 corners. It is significantly faster, but is less stable and does not allow to grow EnvCTM bond dimension.
max_sweeps (int) – Maximal number of sweeps.
iterator_step (int) – If int, ctmrg_ returns a generator that would yield output after every iterator_step sweeps. Default is None, in which case ctmrg_ sweeps are performed immediately.
corner_tol (float) – Convergence tolerance for the change of singular values of all corners in a single update. The default is None, in which case convergence is not checked.

Returns:

Generator if iterator_step is not None.
CTMRG_out(NamedTuple) –

NamedTuple including fields:
- sweeps number of performed ctmrg updates.
- max_dsv norm of singular values change in the worst corner in the last sweep.
- converged whether convergence based on conrer_tol has been reached.

measure_1site(op, site=None) → dict[source]#

Calculate local expectation values within CTM environment.

Returns a number if site is provided. If None, returns a dictionary {site: value} for all unique lattice sites.

Parameters:

env (class EnvCtm) – class containing ctm environment tensors along with lattice structure data
op (single site operator)

measure_nn(O0, O1, bond=None) → dict[source]#

Calculate nearest-neighbor expectation values within CTM environment.

Return a number if the nearest-neighbor bond is provided. If None, returns a dictionary {bond: value} for all unique lattice bonds.

Parameters:

O0, O1 (yastn.Tensor) – Calculate <O0_s0 O1_s1>. O1 is applied first, which might matter for fermionic operators.
bond (yastn.tn.fpeps.Bond | tuple[tuple[int, int], tuple[int, int]]) – Bond of the form (s0, s1). Sites s0 and s1 should be nearest-neighbors on the lattice.

reset_(init='rand', leg=None)[source]#

Initialize random CTMRG environments of PEPS tensors.

Parameters:

init (str) – ‘eye’ or ‘rand’. - If eye, it starts with identity environments of dimension 1. - If rand, environmental tensors are set randomly.
leg (None | yastn.Leg) – Specifies the leg structure for CTMRG virtual legs during initialization. - If None, sets the CTMRG bond dimension to 1 in random initialization. - If yastn.Leg, uses the provided leg for initializing CTMRG virtual legs.

sample(xrange, yrange, projectors, number=1, opts_svd=None, opts_var=None, progressbar=False, return_info=False) → dict[Site, list][source]#

Sample random configurations from PEPS. Output a dictionary linking sites with lists of sampled projectors` keys for each site.

It does not check whether projectors sum up to identity – probabilities of provided projectors get normalized to one. If negative probabilities are observed (signaling contraction errors), error = max(abs(negatives)), and all probabilities below that error level are fixed to error (before consecutive renormalization of probabilities to one).

Parameters:

xrange (tuple[int, int]) – range of rows to sample from, [r0, r1); r0 included, r1 excluded.
yrange (tuple[int, int]) – range of columns to sample from.
projectors (Dict[Any, yast.Tensor] | Sequence[yast.Tensor] | Dict[Site, Dict[Any, yast.Tensor]]) – Projectors to sample from. We can provide a dict(key: projector), where the sampled results will be given as keys, and the same set of projectors is used at each site. For a list of projectors, the keys follow from enumeration. Finally, we can provide a dictionary between each site and sets of projectors.
number (int) – Number of drawn samples.
opts_svd (dict) – Options passed to yastn.linalg.svd() used to truncate virtual spaces of boundary MPSs used in sampling. The default is None, in which case take D_total as the largest dimension from CTM environment.
opts_var (dict) – Options passed to yastn.tn.mps.compression_() used in the refining of boundary MPSs. The default is None, in which case make 2 variational sweeps.
progressbar (bool) – Whether to display progressbar. The default is False.
return_info (bool) – Whether to include in the outputted dictionary a field info with dictionary that contains information about the amplitude of contraction errors (largest negative probability), D_total, etc. The default is False.

save_to_dict() → dict[source]#: Serialize EnvCTM into a dictionary.

update_(opts_svd, method='2site')[source]#

Perform one step of CTMRG update. Environment tensors are updated in place.

The function performs a CTMRG update for a square lattice using the corner transfer matrix renormalization group (CTMRG) algorithm. The update is performed in two steps: a horizontal move and a vertical move. The projectors for each move are calculated first, and then the tensors in the CTM environment are updated using the projectors. The boundary conditions of the lattice determine whether trivial projectors are needed for the move.

Parameters:

opts_svd (dict) – A dictionary of options to pass to the SVD algorithm.
method (str) – ‘2site’ or ‘1site’. The default is ‘2site’. ‘2site’ uses the standard 4x4 enlarged corners, allowing to enlarge EnvCTM bond dimension. ‘1site’ uses smaller 4x2 corners. It is significantly faster, but is less stable and does not allow to grow EnvCTM bond dimension.

Returns:

proj

Return type:

Peps structure loaded with CTM projectors related to all lattice site.

class yastn.tn.fpeps.EnvCTM_local[source]#

Dataclass for CTM environment tensors associated with Peps lattice site.

Contains fields ‘tl’, ‘t’, ‘tr’, ‘r’, ‘br’, ‘b’, ‘bl’, ‘l’

Boundary MPS#

class yastn.tn.fpeps.EnvBoundaryMps(psi, opts_svd, setup='l', opts_var=None)[source]#

Boundary MPS class for finite PEPS contraction.

measure_1site(op)[source]#

Calculate all 1-point expectation values <o> in a finite peps.

Takes CTM environments and operators.

o1 are given as dict[tuple[int, int], dict[int, operators]], mapping sites with list of operators at each site.

measure_2site(op1, op2, opts_svd, opts_var=None)[source]#

Calculate all 2-point correlations <op1 op2> in a finite peps.

Takes CTM environments and operators.

o1 and o2 are given as dict[tuple[int, int], dict[int, operators]], mapping sites with list of operators at each site.

sample(projectors, opts_svd=None, opts_var=None)[source]#

Sample a random configuration from a finite PEPS.

Takes CTM environments and a complete list of projectors to sample from.

sample_MC_(st0, st1, st2, psi, projectors, opts_svd, opts_var, trial='local')[source]#

Monte Carlo steps in a finite peps. Makes two steps while sweeping finite lattice back and forth.

Takes environments and a complete list of projectors to sample from.

proj_env, st1, st2 are updated in place

Approximate cluster update#

class yastn.tn.fpeps.EnvApproximate(psi, which='65', opts_svd=None, opts_var=None, update_sweeps=None)[source]#

bond_metric(QA, QB, s0, s1, dirn)[source]#

Calculates bond metric.

If which=='65':
    (-2,-2)==(-2,-1)==(-2,0)==(-2,1)==(-2,2)==(-2,3)
       ||      ||       ||      ||      ||      ||
    (-1,-2)==(-1,-1)==(-1,0)==(-1,1)==(-1,2)==(-1,3)
       ||      ||       ||      ||      ||      ||
    (0, -2)==(0, -1)=== GA  ++  GB ===(0, 2)==(0, 3)
       ||      ||       ||      ||      ||      ||
    (1, -2)==(1, -1)==(1, 0)==(1, 1)==(1, 2)==(1, 3)
       ||      ||       ||      ||      ||      ||
    (2, -2)==(2, -1)==(2, 0)==(2, 1)==(2, 2)==(2, 3)