quimb.tensor.tensor_2d#

Classes and algorithms related to 2D tensor networks.

Functions

calc_plaquette_map(plaquettes)

Generate a dictionary of all the coordinate pairs in plaquettes mapped to the 'best' (smallest) rectangular plaquette that contains them.

calc_plaquette_sizes(coo_groups[, autogroup])

Find a sequence of plaquette blocksizes that will cover all the terms (coordinate pairs) in pairs.

gate_string_reduce_split_(TG, where, string, ...)

gate_string_split_(TG, where, string, ...)

gen_2d_bonds(Lx, Ly, steppers[, coo_filter])

Convenience function for tiling pairs of bond coordinates on a 2D lattice given a function like lambda i, j: (i + 1, j + 1).

gen_long_range_path(ij_a, ij_b[, sequence])

Generate a string of coordinates, in order, from ij_a to ij_b.

gen_long_range_swap_path(ij_a, ij_b[, sequence])

Generate the coordinates or a series of swaps that would bring ij_a and ij_b together.

get_swap(dp, dtype, backend)

is_lone_coo(where)

Check if where has been specified as a single coordinate pair.

manhattan_distance(coo_a, coo_b)

nearest_neighbors(coo)

plaquette_to_sites(p)

Turn a plaquette ((i0, j0), (di, dj)) into the sites it contains.

show_2d(tn_2d[, show_lower, show_upper])

Base function for printing a unicode schematic of flat 2D TNs.

swap_path_to_long_range_path(swap_path, ij_a)

Generates the ordered long-range path - a sequence of coordinates - from a (long-range) swap path - a sequence of coordinate pairs.

Classes

PEPO(arrays, *[, shape, tags, upper_ind_id, ...])

Projected Entangled Pair Operator object.

PEPS(arrays, *[, shape, tags, site_ind_id, ...])

Projected Entangled Pair States object (2D).

Rotator2D(tn, xrange, yrange, from_which)

Object for rotating coordinates and various contraction functions so that the core algorithms only have to written once, but nor does the actual TN have to be modified.

TensorNetwork2D(ts, *[, virtual, ...])

Mixin class for tensor networks with a square lattice two-dimensional structure, indexed by [{row},{column}] so that.

TensorNetwork2DFlat(ts, *[, virtual, ...])

Mixin class for a 2D square lattice tensor network with a single tensor per site, for example, both PEPS and PEPOs.

TensorNetwork2DOperator(ts, *[, virtual, ...])

Mixin class for a 2D square lattice TN operator, i.e. one with both 'upper' and 'lower' site (physical) indices.

TensorNetwork2DVector(ts, *[, virtual, ...])

Mixin class for a 2D square lattice vector TN, i.e. one with a single physical index per site.

class quimb.tensor.tensor_2d.PEPO(arrays, *, shape='urdlbk', tags=None, upper_ind_id='k{},{}', lower_ind_id='b{},{}', site_tag_id='I{},{}', row_tag_id='ROW{}', col_tag_id='COL{}', **tn_opts)[source]#

Projected Entangled Pair Operator object:

             ...
 │╱   │╱   │╱   │╱   │╱   │╱
 ●────●────●────●────●────●──
╱│   ╱│   ╱│   ╱│   ╱│   ╱│
 │╱   │╱   │╱   │╱   │╱   │╱
 ●────●────●────●────●────●──
╱│   ╱│   ╱│   ╱│   ╱│   ╱│
 │╱   │╱   │╱   │╱   │╱   │╱   ...
 ●────●────●────●────●────●──
╱│   ╱│   ╱│   ╱│   ╱│   ╱│
 │╱   │╱   │╱   │╱   │╱   │╱
 ●────●────●────●────●────●──
╱    ╱    ╱    ╱    ╱    ╱
Parameters
  • arrays (sequence of sequence of array) – The core tensor data arrays.

  • shape (str, optional) – Which order the dimensions of the arrays are stored in, the default 'urdlbk' stands for (‘up’, ‘right’, ‘down’, ‘left’, ‘bra’, ‘ket’). Arrays on the edge of lattice are assumed to be missing the corresponding dimension.

  • tags (set[str], optional) – Extra global tags to add to the tensor network.

  • upper_ind_id (str, optional) – String specifier for naming convention of upper site indices.

  • lower_ind_id (str, optional) – String specifier for naming convention of lower site indices.

  • site_tag_id (str, optional) – String specifier for naming convention of site tags.

  • row_tag_id (str, optional) – String specifier for naming convention of row tags.

  • col_tag_id (str, optional) – String specifier for naming convention of column tags.

add_PEPO(other, inplace=False)[source]#

Add this PEPO with another.

apply(other, compress=False, **compress_opts)[source]#

Act with this PEPO on other, returning a new TN like other with the same outer indices.

Parameters
  • other (PEPS) – The TN to act on.

  • compress (bool, optional) – Whether to compress the resulting TN.

  • compress_opts – Supplied to compress().

Return type

TensorNetwork2DFlat

classmethod rand(Lx, Ly, bond_dim, phys_dim=2, herm=False, dtype=<class 'float'>, seed=None, **pepo_opts)[source]#

Create a random PEPO.

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • bond_dim (int) – The bond dimension.

  • physical (int, optional) – The physical index dimension.

  • herm (bool, optional) – Whether to symmetrize the tensors across the physical bonds to make the overall operator hermitian.

  • dtype (dtype, optional) – The dtype to create the arrays with, default is real double.

  • seed (int, optional) – A random seed.

  • pepo_opts – Supplied to PEPO.

Returns

X

Return type

PEPO

rand_herm(Ly, bond_dim, phys_dim=2, *, herm=True, dtype=<class 'float'>, seed=None, **pepo_opts)#

Create a random PEPO.

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • bond_dim (int) – The bond dimension.

  • physical (int, optional) – The physical index dimension.

  • herm (bool, optional) – Whether to symmetrize the tensors across the physical bonds to make the overall operator hermitian.

  • dtype (dtype, optional) – The dtype to create the arrays with, default is real double.

  • seed (int, optional) – A random seed.

  • pepo_opts – Supplied to PEPO.

Returns

X

Return type

PEPO

show()[source]#

Print a unicode schematic of this PEPO and its bond dimensions.

class quimb.tensor.tensor_2d.PEPS(arrays, *, shape='urdlp', tags=None, site_ind_id='k{},{}', site_tag_id='I{},{}', row_tag_id='ROW{}', col_tag_id='COL{}', **tn_opts)[source]#

Projected Entangled Pair States object (2D):

             ...
 │    │    │    │    │    │
 ●────●────●────●────●────●──
╱│   ╱│   ╱│   ╱│   ╱│   ╱│
 │    │    │    │    │    │
 ●────●────●────●────●────●──
╱│   ╱│   ╱│   ╱│   ╱│   ╱│
 │    │    │    │    │    │   ...
 ●────●────●────●────●────●──
╱│   ╱│   ╱│   ╱│   ╱│   ╱│
 │    │    │    │    │    │
 ●────●────●────●────●────●──
╱    ╱    ╱    ╱    ╱    ╱
Parameters
  • arrays (sequence of sequence of array) – The core tensor data arrays.

  • shape (str, optional) – Which order the dimensions of the arrays are stored in, the default 'urdlp' stands for (‘up’, ‘right’, ‘down’, ‘left’, ‘physical’). Arrays on the edge of lattice are assumed to be missing the corresponding dimension.

  • tags (set[str], optional) – Extra global tags to add to the tensor network.

  • site_ind_id (str, optional) – String specifier for naming convention of site indices.

  • site_tag_id (str, optional) – String specifier for naming convention of site tags.

  • row_tag_id (str, optional) – String specifier for naming convention of row tags.

  • col_tag_id (str, optional) – String specifier for naming convention of column tags.

add_PEPS(other, inplace=False)[source]#

Add this PEPS with another.

classmethod empty(Lx, Ly, bond_dim, phys_dim=2, like='numpy', **peps_opts)[source]#

Create an empty 2D PEPS.

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • bond_dim (int) – The bond dimension.

  • physical (int, optional) – The physical index dimension.

  • peps_opts – Supplied to PEPS.

Returns

psi

Return type

PEPS

classmethod from_fill_fn(fill_fn, Lx, Ly, bond_dim, phys_dim=2, **peps_opts)[source]#

Create a 2D PEPS from a filling function with signature fill_fn(shape).

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • bond_dim (int) – The bond dimension.

  • physical (int, optional) – The physical index dimension.

  • peps_opts – Supplied to PEPS.

Returns

psi

Return type

PEPS

classmethod ones(Lx, Ly, bond_dim, phys_dim=2, like='numpy', **peps_opts)[source]#

Create a 2D PEPS whose tensors are filled with ones.

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • bond_dim (int) – The bond dimension.

  • physical (int, optional) – The physical index dimension.

  • peps_opts – Supplied to PEPS.

Returns

psi

Return type

PEPS

classmethod rand(Lx, Ly, bond_dim, phys_dim=2, dtype=<class 'float'>, seed=None, **peps_opts)[source]#

Create a random (un-normalized) PEPS.

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • bond_dim (int) – The bond dimension.

  • physical (int, optional) – The physical index dimension.

  • dtype (dtype, optional) – The dtype to create the arrays with, default is real double.

  • seed (int, optional) – A random seed.

  • peps_opts – Supplied to PEPS.

Returns

psi

Return type

PEPS

show()[source]#

Print a unicode schematic of this PEPS and its bond dimensions.

class quimb.tensor.tensor_2d.Rotator2D(tn, xrange, yrange, from_which)[source]#

Object for rotating coordinates and various contraction functions so that the core algorithms only have to written once, but nor does the actual TN have to be modified.

get_contract_boundary_fn()[source]#

Get the function that contracts the boundary in by a single step.

get_opposite_env_fn()[source]#

Get the function and location label for contracting boundaries in the opposite direction to main sweep.

get_sweep_directions(compress_sweep=None)[source]#

Get the default compress and canonize sweep directions.

get_sweep_fns(compress_sweep)[source]#

Get functions that compress or canonize a single rotated, ‘row’.

class quimb.tensor.tensor_2d.TensorNetwork2D(ts, *, virtual=False, check_collisions=True)[source]#

Mixin class for tensor networks with a square lattice two-dimensional structure, indexed by [{row},{column}] so that:

             'COL{j}'
                v

i=Lx-1 ●──●──●──●──●──●──   ──●
       |  |  |  |  |  |       |
             ...
       |  |  |  |  |  | 'I{i},{j}' = 'I3,5' e.g.
i=3    ●──●──●──●──●──●──
       |  |  |  |  |  |       |
i=2    ●──●──●──●──●──●──   ──●    <== 'ROW{i}'
       |  |  |  |  |  |  ...  |
i=1    ●──●──●──●──●──●──   ──●
       |  |  |  |  |  |       |
i=0    ●──●──●──●──●──●──   ──●

     j=0, 1, 2, 3, 4, 5    j=Ly-1

This implies the following conventions:

  • the ‘up’ bond is coordinates (i, j), (i + 1, j)

  • the ‘down’ bond is coordinates (i, j), (i - 1, j)

  • the ‘right’ bond is coordinates (i, j), (i, j + 1)

  • the ‘left’ bond is coordinates (i, j), (i, j - 1)

property Lx#

The number of rows.

property Ly#

The number of columns.

canonize_column(j, sweep, xrange=None, **canonize_opts)[source]#

Canonize all or part of a column.

If sweep='up' then:

 |  |  |         |  |  |
─●──●──●─       ─●──●──●─
 |  |  |         |  |  |
─●──●──●─       ─●──o──●─ istop
 |  |  |   ==>   |  |  |
─●──●──●─       ─●──^──●─
 |  |  |         |  |  |
─●──●──●─       ─●──^──●─ istart
 |  |  |         |  |  |
─●──●──●─       ─●──●──●─
 |  |  |         |  |  |
    .               .
    j               j

If sweep='down' then:

 |  |  |         |  |  |
─●──●──●─       ─●──●──●─
 |  |  |         |  |  |
─●──●──●─       ─●──v──●─ istart
 |  |  |   ==>   |  |  |
─●──●──●─       ─●──v──●─
 |  |  |         |  |  |
─●──●──●─       ─●──o──●─ istop
 |  |  |         |  |  |
─●──●──●─       ─●──●──●─
 |  |  |         |  |  |
    .               .
    j               j

Does not yield an orthogonal form in the same way as in 1D.

Parameters
  • j (int) – Which column to canonize.

  • sweep ({'up', 'down'}) – Which direction to sweep in.

  • xrange (None or (int, int), optional) – The range of columns to canonize.

  • canonize_opts – Supplied to canonize_between.

canonize_row(i, sweep, yrange=None, **canonize_opts)[source]#

Canonize all or part of a row.

If sweep == 'right' then:

 |  |  |  |  |  |  |         |  |  |  |  |  |  |
─●──●──●──●──●──●──●─       ─●──●──●──●──●──●──●─
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
─●──●──●──●──●──●──●─  ==>  ─●──>──>──>──>──o──●─ row=i
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
─●──●──●──●──●──●──●─       ─●──●──●──●──●──●──●─
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
    .           .               .           .
    jstart      jstop           jstart      jstop

If sweep == 'left' then:

 |  |  |  |  |  |  |         |  |  |  |  |  |  |
─●──●──●──●──●──●──●─       ─●──●──●──●──●──●──●─
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
─●──●──●──●──●──●──●─  ==>  ─●──o──<──<──<──<──●─ row=i
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
─●──●──●──●──●──●──●─       ─●──●──●──●──●──●──●─
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
    .           .               .           .
    jstop       jstart          jstop       jstart

Does not yield an orthogonal form in the same way as in 1D.

Parameters
  • i (int) – Which row to canonize.

  • sweep ({'right', 'left'}) – Which direction to sweep in.

  • jstart (int or None) – Starting column, defaults to whole row.

  • jstop (int or None) – Stopping column, defaults to whole row.

  • canonize_opts – Supplied to canonize_between.

property col_tag_id#

The string specifier for tagging each column of this 2D TN.

property col_tags#

A tuple of all of the Ly different column tags.

compress_column(j, sweep, xrange=None, max_bond=None, cutoff=1e-10, equalize_norms=False, compress_opts=None)[source]#

Compress all or part of a column.

If sweep='up' then:

 ┃  ┃  ┃         ┃  ┃  ┃
─●──●──●─       ─●──●──●─
 ┃  ┃  ┃         ┃  ┃  ┃
─●──●──●─       ─●──o──●─  .
 ┃  ┃  ┃   ==>   ┃  |  ┃   .
─●──●──●─       ─●──^──●─  . xrange
 ┃  ┃  ┃         ┃  |  ┃   .
─●──●──●─       ─●──^──●─  .
 ┃  ┃  ┃         ┃  ┃  ┃
─●──●──●─       ─●──●──●─
 ┃  ┃  ┃         ┃  ┃  ┃
    .               .
    j               j

If sweep='down' then:

 ┃  ┃  ┃         ┃  ┃  ┃
─●──●──●─       ─●──●──●─
 ┃  ┃  ┃         ┃  ┃  ┃
─●──●──●─       ─●──v──●─ .
 ┃  ┃  ┃   ==>   ┃  |  ┃  .
─●──●──●─       ─●──v──●─ . xrange
 ┃  ┃  ┃         ┃  |  ┃  .
─●──●──●─       ─●──o──●─ .
 ┃  ┃  ┃         ┃  ┃  ┃
─●──●──●─       ─●──●──●─
 ┃  ┃  ┃         ┃  ┃  ┃
    .               .
    j               j

Does not yield an orthogonal form in the same way as in 1D.

Parameters
  • j (int) – Which column to compress.

  • sweep ({'up', 'down'}) – Which direction to sweep in.

  • xrange (None or (int, int), optional) – The range of rows to compress.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

compress_row(i, sweep, yrange=None, max_bond=None, cutoff=1e-10, equalize_norms=False, compress_opts=None)[source]#

Compress all or part of a row.

If sweep == 'right' then:

 |  |  |  |  |  |  |         |  |  |  |  |  |  |
━●━━●━━●━━●━━●━━●━━●━       ━●━━●━━●━━●━━●━━●━━●━
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
━●━━●━━●━━●━━●━━●━━●━  ━━>  ━●━━>──>──>──>──o━━●━ row=i
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
━●━━●━━●━━●━━●━━●━━●━       ━●━━●━━●━━●━━●━━●━━●━
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
    .           .               .           .
    jstart      jstop           jstart      jstop

If sweep == 'left' then:

 |  |  |  |  |  |  |         |  |  |  |  |  |  |
━●━━●━━●━━●━━●━━●━━●━       ━●━━●━━●━━●━━●━━●━━●━
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
━●━━●━━●━━●━━●━━●━━●━  ━━>  ━●━━o──<──<──<──<━━●━ row=i
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
━●━━●━━●━━●━━●━━●━━●━       ━●━━●━━●━━●━━●━━●━━●━
 |  |  |  |  |  |  |         |  |  |  |  |  |  |
    .           .               .           .
    jstop       jstart          jstop       jstart

Does not yield an orthogonal form in the same way as in 1D.

Parameters
  • i (int) – Which row to compress.

  • sweep ({'right', 'left'}) – Which direction to sweep in.

  • yrange (tuple[int, int] or None) – The range of columns to compress.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

compute_bottom_environments(*, from_which='bottom', xrange=None, yrange=None, max_bond=None, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, dense=False, compress_opts=None, envs=None, **contract_boundary_opts)#

Compute the self.Lx 1D boundary tensor networks describing the lower environments of each row in this 2D tensor network. See compute_row_environments() for full details.

compute_col_environments(max_bond=None, *, cutoff=1e-10, canonize=True, dense=False, mode='mps', layer_tags=None, compress_opts=None, envs=None, **contract_boundary_opts)[source]#

Compute the 2 * self.Ly 1D boundary tensor networks describing the left and right environments of each column in this 2D tensor network, assumed to represent the norm.

The ‘left’ environment for column j will be a contraction of all columns j - 1, j - 2, ... etc:

●<
┃
●<
┃
●<
┃
●<

The ‘right’ environment for row j will be a contraction of all rows j + 1, j + 2, ... etc:

>●
 ┃
>●
 ┃
>●
 ┃
>●

Such that envs['left', j] & self.select(self.col_tag(j)) & envs['right', j] would look like:

   ╱o
●< o| >●
┃  |o  ┃
●< o| >●
┃  |o  ┃
●< o| >●
┃  |o  ┃
●< o╱ >●

And be (an approximation of) the norm centered around column j

Parameters
  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • dense (bool, optional) – If true, contract the boundary in as a single dense tensor.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the boundary compression.

  • layer_tags (None or sequence[str], optional) – If None, all tensors at each coordinate pair [(i, j), (i + 1, j)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i + 1, j), layer_tag], for each layer_tag in layer_tags.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • contract_boundary_opts – Supplied to contract_boundary_from_left() and contract_boundary_from_right() .

Returns

col_envs – The two environment tensor networks of column j will be stored in row_envs['left', j] and row_envs['right', j].

Return type

dict[(str, int), TensorNetwork]

compute_environments(from_which, xrange=None, yrange=None, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, dense=False, compress_opts=None, envs=None, **contract_boundary_opts)[source]#

Compute the self.Lx 1D boundary tensor networks describing the environments of rows and columns.

compute_left_environments(*, from_which='left', xrange=None, yrange=None, max_bond=None, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, dense=False, compress_opts=None, envs=None, **contract_boundary_opts)#

Compute the self.Ly 1D boundary tensor networks describing the left environments of each column in this 2D tensor network. See compute_col_environments() for full details.

compute_plaquette_environments(x_bsz=2, y_bsz=2, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, first_contract=None, second_dense=None, compress_opts=None, **compute_environment_opts)[source]#

Compute all environments like:

second_dense=False   second_dense=True (& first_contract='columns')

  ●──●                  ╭───●───╮
 ╱│  │╲                 │  ╱ ╲  │
●─.  .─●    ┬           ●─ . . ─●    ┬
│      │    ┊ x_bsz     │       │    ┊ x_bsz
●─.  .─●    ┴           ●─ . . ─●    ┴
 ╲│  │╱                 │  ╲ ╱  │
  ●──●                  ╰───●───╯

  <-->                    <->
 y_bsz                   y_bsz

Use two boundary contractions sweeps.

Parameters
  • x_bsz (int, optional) – The size of the plaquettes in the x-direction (number of rows).

  • y_bsz (int, optional) – The size of the plaquettes in the y-direction (number of columns).

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the boundary compression.

  • layer_tags (None or sequence[str], optional) – If None, all tensors at each coordinate pair [(i, j), (i + 1, j)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i + 1, j), layer_tag], for each layer_tag in layer_tags.

  • first_contract ({None, 'rows', 'columns'}, optional) – The environments can either be generated with initial sweeps in the row or column direction. Generally it makes sense to perform this approximate step in whichever is smaller (the default).

  • second_dense (None or bool, optional) – Whether to perform the second set of contraction sweeps (in the rotated direction from whichever first_contract is) using a dense tensor or boundary method. By default this is only turned on if the bsz in the corresponding direction is 1.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • compute_environment_opts – Supplied to compute_col_environments() or compute_row_environments() .

Returns

The plaquette environments. The key is two tuples of ints, the startings coordinate of the plaquette being the first and the size of the plaquette being the second pair.

Return type

dict[((int, int), (int, int)), TensorNetwork]

compute_right_environments(*, from_which='right', xrange=None, yrange=None, max_bond=None, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, dense=False, compress_opts=None, envs=None, **contract_boundary_opts)#

Compute the self.Ly 1D boundary tensor networks describing the right environments of each column in this 2D tensor network. See compute_col_environments() for full details.

compute_row_environments(max_bond=None, *, cutoff=1e-10, canonize=True, dense=False, mode='mps', layer_tags=None, compress_opts=None, envs=None, **contract_boundary_opts)[source]#

Compute the 2 * self.Lx 1D boundary tensor networks describing the lower and upper environments of each row in this 2D tensor network, assumed to represent the norm.

The ‘top’ environment for row i will be a contraction of all rows i + 1, i + 2, ... etc:

 ●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●
╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲

The ‘bottom’ environment for row i will be a contraction of all rows i - 1, i - 2, ... etc:

╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱
 ●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●

Such that envs['top', i] & self.select(self.row_tag(i)) & envs['bottom', i] would look like:

 ●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●
╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲
o─o─o─o─o─o─o─o─o─o─o─o─o─o─o─o─o─o─o─o
╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ ╱
 ●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●━━━●

And be (an approximation of) the norm centered around row i

Parameters
  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • dense (bool, optional) – If true, contract the boundary in as a single dense tensor.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the boundary compression.

  • layer_tags (None or sequence[str], optional) – If None, all tensors at each coordinate pair [(i, j), (i + 1, j)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i + 1, j), layer_tag], for each layer_tag in layer_tags.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • envs (dict, optional) – Supply an existing dictionary to store the environments in.

  • contract_boundary_opts – Supplied to contract_boundary_from_bottom() and contract_boundary_from_top() .

Returns

row_envs – The two environment tensor networks of row i will be stored in row_envs['bottom', i] and row_envs['top', i].

Return type

dict[(str, int), TensorNetwork]

compute_top_environments(*, from_which='top', xrange=None, yrange=None, max_bond=None, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, dense=False, compress_opts=None, envs=None, **contract_boundary_opts)#

Compute the self.Lx 1D boundary tensor networks describing the upper environments of each row in this 2D tensor network. See compute_row_environments() for full details.

contract_boundary(around=None, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, max_separation=1, sequence=None, bottom=None, top=None, left=None, right=None, compress_opts=None, equalize_norms=False, inplace=False, **contract_boundary_opts)[source]#

Contract the boundary of this 2D tensor network inwards:

●──●──●──●       ●──●──●──●       ●──●──●
│  │  │  │       │  │  │  │       ║  │  │
●──●──●──●       ●──●──●──●       ^──●──●       >══>══●       >──v
│  │ij│  │  ==>  │  │ij│  │  ==>  ║ij│  │  ==>  │ij│  │  ==>  │ij║
●──●──●──●       ●══<══<══<       ^──<──<       ^──<──<       ^──<
│  │  │  │
●──●──●──●

Optionally from any or all of the boundary, in multiple layers, and stopping around a region.

Parameters
  • around (None or sequence of (int, int), optional) – If given, don’t contract the square of sites bounding these coordinates.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or sequence of str, optional) – If given, perform a multilayer contraction, contracting the inner sites in each layer into the boundary individually.

  • max_separation (int, optional) – If around is None, when any two sides become this far apart simply contract the remaining tensor network.

  • sequence (sequence of {'b', 'l', 't', 'r'}, optional) – Which directions to cycle throught when performing the inwards contractions: ‘b’, ‘l’, ‘t’, ‘r’ corresponding to from the bottom, left, top and right respectively. If around is specified you will likely need all of these!

  • bottom (int, optional) – The initial bottom boundary row, defaults to 0.

  • top (int, optional) – The initial top boundary row, defaults to Lx - 1.

  • left (int, optional) – The initial left boundary column, defaults to 0.

  • right (int, optional) – The initial right boundary column, defaults to Ly - 1..

  • inplace (bool, optional) – Whether to perform the contraction in place or not.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • contract_boundary_opts – Supplied to contract_boundary_from_bottom(), contract_boundary_from_left(), contract_boundary_from_top(), or contract_boundary_from_right(), including compression and canonization options.

contract_boundary_from(xrange, yrange, from_which, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, compress_sweep=None, compress_opts=None, inplace=False, **contract_boundary_opts)[source]#

Unified entrypoint for contracting any rectangular patch of tensors from any direction, with any boundary method.

contract_boundary_from_bottom(xrange, yrange=None, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, compress_sweep='left', compress_opts=None, inplace=False, **contract_boundary_opts)[source]#

Contract a 2D tensor network inwards from the bottom, canonizing and compressing (left to right) along the way. If layer_tags is None this looks like:

a) contract

│  │  │  │  │
●──●──●──●──●       │  │  │  │  │
│  │  │  │  │  -->  ●══●══●══●══●
●──●──●──●──●

b) optionally canonicalize

│  │  │  │  │
●══●══<══<══<

c) compress in opposite direction

│  │  │  │  │  -->  │  │  │  │  │  -->  │  │  │  │  │
>──●══●══●══●  -->  >──>──●══●══●  -->  >──>──>──●══●
.  .           -->     .  .        -->        .  .

If layer_tags is specified, each then each layer is contracted in and compressed separately, resulting generally in a lower memory scaling. For two layer tags this looks like:

a) first flatten the outer boundary only

│ ││ ││ ││ ││ │       │ ││ ││ ││ ││ │
●─○●─○●─○●─○●─○       ●─○●─○●─○●─○●─○
│ ││ ││ ││ ││ │  ==>   ╲│ ╲│ ╲│ ╲│ ╲│
●─○●─○●─○●─○●─○         ●══●══●══●══●

b) contract and compress a single layer only

│ ││ ││ ││ ││ │
│ ○──○──○──○──○
│╱ │╱ │╱ │╱ │╱
●══<══<══<══<

c) contract and compress the next layer

╲│ ╲│ ╲│ ╲│ ╲│
 >══>══>══>══●
Parameters
  • xrange ((int, int)) – The range of rows to compress (inclusive).

  • yrange ((int, int) or None, optional) – The range of columns to compress (inclusive), sweeping along with canonization and compression. Defaults to all columns.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or sequence[str], optional) – If None, all tensors at each coordinate pair [(i, j), (i + 1, j)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i + 1, j), layer_tag], for each layer_tag in layer_tags.

  • compress_sweep ({'left', 'right'}, optional) – Which way to perform the compression sweep, which has an effect on which tensors end up being canonized.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • inplace (bool, optional) – Whether to perform the contraction inplace or not.

contract_boundary_from_left(yrange, xrange=None, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, compress_sweep='up', compress_opts=None, inplace=False, **contract_boundary_opts)[source]#

Contract a 2D tensor network inwards from the left, canonizing and compressing (bottom to top) along the way. If layer_tags is None this looks like:

a) contract

●──●──       ●──
│  │         ║
●──●──  ==>  ●──
│  │         ║
●──●──       ●──

b) optionally canonicalize

●──       v──
║         ║
●──  ==>  v──
║         ║
●──       ●──

c) compress in opposite direction

v──       ●──
║         │
v──  ==>  ^──
║         │
●──       ^──

If layer_tags is specified, each then each layer is contracted in and compressed separately, resulting generally in a lower memory scaling. For two layer tags this looks like:

a) first flatten the outer boundary only

○──○──           ●──○──
│╲ │╲            │╲ │╲
●─○──○──         ╰─●──○──
 ╲│╲╲│╲     ==>    │╲╲│╲
  ●─○──○──         ╰─●──○──
   ╲│ ╲│             │ ╲│
    ●──●──           ╰──●──

b) contract and compress a single layer only

   ○──
 ╱╱ ╲
●─── ○──
 ╲ ╱╱ ╲
  ^─── ○──
   ╲ ╱╱
    ^─────

c) contract and compress the next layer

●──
│╲
╰─●──
  │╲
  ╰─●──
    │
    ╰──
Parameters
  • yrange ((int, int)) – The range of columns to compress (inclusive).

  • xrange ((int, int) or None, optional) – The range of rows to compress (inclusive), sweeping along with canonization and compression. Defaults to all rows.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or str, optional) – If None, all tensors at each coordinate pair [(i, j), (i, j + 1)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i + 1, j), layer_tag], for each layer_tag in layer_tags.

  • compress_sweep ({'up', 'down'}, optional) – Which way to perform the compression sweep, which has an effect on which tensors end up being canonized.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • inplace (bool, optional) – Whether to perform the contraction inplace or not.

contract_boundary_from_right(yrange, xrange=None, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, compress_sweep='down', compress_opts=None, inplace=False, **contract_boundary_opts)[source]#

Contract a 2D tensor network inwards from the left, canonizing and compressing (top to bottom) along the way. If layer_tags is None this looks like:

a) contract

──●──●       ──●
  │  │         ║
──●──●  ==>  ──●
  │  │         ║
──●──●       ──●

b) optionally canonicalize

──●       ──v
  ║         ║
──●  ==>  ──v
  ║         ║
──●       ──●

c) compress in opposite direction

──v       ──●
  ║         │
──v  ==>  ──^
  ║         │
──●       ──^

If layer_tags is specified, each then each layer is contracted in and compressed separately, resulting generally in a lower memory scaling. For two layer tags this looks like:

a) first flatten the outer boundary only

    ──○──○           ──○──●
     ╱│ ╱│            ╱│ ╱│
  ──○──○─●         ──○──●─╯
   ╱│╱╱│╱   ==>     ╱│╱╱│
──○──○─●         ──○──●─╯
  │╱ │╱            │╱ │
──●──●           ──●──╯

b) contract and compress a single layer only

    ──○
     ╱ ╲╲
  ──○────v
   ╱ ╲╲ ╱
──○────v
   ╲╲ ╱
─────●

c) contract and compress the next layer

       ╲
    ────v
     ╲ ╱
  ────v
   ╲ ╱
────●
Parameters
  • yrange ((int, int)) – The range of columns to compress (inclusive).

  • xrange ((int, int) or None, optional) – The range of rows to compress (inclusive), sweeping along with canonization and compression. Defaults to all rows.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or str, optional) – If None, all tensors at each coordinate pair [(i, j), (i, j - 1)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i + 1, j), layer_tag], for each layer_tag in layer_tags.

  • compress_sweep ({'down', 'up'}, optional) – Which way to perform the compression sweep, which has an effect on which tensors end up being canonized.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • inplace (bool, optional) – Whether to perform the contraction inplace or not.

contract_boundary_from_top(xrange, yrange=None, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=None, inplace=False, compress_sweep='right', compress_opts=None, **contract_boundary_opts)[source]#

Contract a 2D tensor network inwards from the top, canonizing and compressing (right to left) along the way. If layer_tags is None this looks like:

a) contract

●──●──●──●──●
|  |  |  |  |  -->  ●══●══●══●══●
●──●──●──●──●       |  |  |  |  |
|  |  |  |  |

b) optionally canonicalize

●══●══<══<══<
|  |  |  |  |

c) compress in opposite direction

>──●══●══●══●  -->  >──>──●══●══●  -->  >──>──>──●══●
|  |  |  |  |  -->  |  |  |  |  |  -->  |  |  |  |  |
.  .           -->     .  .        -->        .  .

If layer_tags is specified, each then each layer is contracted in and compressed separately, resulting generally in a lower memory scaling. For two layer tags this looks like:

a) first flatten the outer boundary only

●─○●─○●─○●─○●─○         ●══●══●══●══●
│ ││ ││ ││ ││ │  ==>   ╱│ ╱│ ╱│ ╱│ ╱│
●─○●─○●─○●─○●─○       ●─○●─○●─○●─○●─○
│ ││ ││ ││ ││ │       │ ││ ││ ││ ││ │

b) contract and compress a single layer only

●══<══<══<══<
│╲ │╲ │╲ │╲ │╲
│ ○──○──○──○──○
│ ││ ││ ││ ││ │

c) contract and compress the next layer

 ●══●══●══●══●
╱│ ╱│ ╱│ ╱│ ╱│
Parameters
  • xrange ((int, int)) – The range of rows to compress (inclusive).

  • yrange ((int, int) or None, optional) – The range of columns to compress (inclusive), sweeping along with canonization and compression. Defaults to all columns.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or str, optional) – If None, all tensors at each coordinate pair [(i, j), (i - 1, j)] will be first contracted. If specified, then the outer tensor at (i, j) will be contracted with the tensor specified by [(i - 1, j), layer_tag], for each layer_tag in layer_tags.

  • compress_sweep ({'right', 'left'}, optional) – Which way to perform the compression sweep, which has an effect on which tensors end up being canonized.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

  • inplace (bool, optional) – Whether to perform the contraction inplace or not.

flatten(fuse_multibonds=True, inplace=False)[source]#

Contract all tensors corresponding to each site into one.

gen_bond_coos()[source]#

Generate pairs of coordinates for all the bonds in this 2D TN.

gen_diagonal_bond_coos()[source]#

Generate all next nearest neighbor diagonal coordinate pairs.

gen_diagonal_left_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j - 1).

gen_diagonal_left_even_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j - 1) where j is even, which thus don’t overlap at all.

gen_diagonal_left_odd_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j - 1) where j is odd, which thus don’t overlap at all.

gen_diagonal_right_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j + 1).

gen_diagonal_right_even_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j + 1) where i is even, which thus don’t overlap at all.

gen_diagonal_right_odd_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j + 1) where i is odd, which thus don’t overlap at all.

gen_horizontal_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i, j + 1).

gen_horizontal_even_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i, j + 1) where j is even, which thus don’t overlap at all.

gen_horizontal_odd_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i, j + 1) where j is odd, which thus don’t overlap at all.

gen_site_coos()[source]#

Generate coordinates for all the sites in this 2D TN.

gen_vertical_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j).

gen_vertical_even_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j) where i is even, which thus don’t overlap at all.

gen_vertical_odd_bond_coos()[source]#

Generate all coordinate pairs like (i, j), (i + 1, j) where i is odd, which thus don’t overlap at all.

maybe_convert_coo(x)[source]#

Check if x is a tuple of two ints and convert to the corresponding site tag if so.

property nsites#

The total number of sites.

property row_tag_id#

The string specifier for tagging each row of this 2D TN.

property row_tags#

A tuple of all of the Lx different row tags.

show()[source]#

Print a unicode schematic of this 2D TN and its bond dimensions.

site_tag(i, j)[source]#

The name of the tag specifiying the tensor at site (i, j).

property site_tag_id#

The string specifier for tagging each site of this 2D TN.

property site_tags#

All of the Lx * Ly site tags.

valid_coo(ij)[source]#

Test whether ij is in grid for this 2D TN.

class quimb.tensor.tensor_2d.TensorNetwork2DFlat(ts, *, virtual=False, check_collisions=True)[source]#

Mixin class for a 2D square lattice tensor network with a single tensor per site, for example, both PEPS and PEPOs.

bond(coo1, coo2)[source]#

Get the name of the index defining the bond between sites at coo1 and coo2.

bond_size(coo1, coo2)[source]#

Return the size of the bond between sites at coo1 and coo2.

compress(max_bond=None, cutoff=1e-10, equalize_norms=False, row_sweep='right', col_sweep='up', **compress_opts)[source]#

Compress all bonds in this flat 2D tensor network.

Parameters
  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • compress_opts (None or dict, optional) – Supplied to compress_between().

expand_bond_dimension(new_bond_dim, inplace=True, bra=None, rand_strength=0.0)[source]#

Increase the bond dimension of this flat, 2D, tensor network, padding the tensor data with either zeros or random entries.

Parameters
  • new_bond_dim (int) – The new dimension. If smaller or equal to the current bond dimension nothing will happend.

  • inplace (bool, optional) – Whether to expand in place (the default), or return a new TN.

  • bra (TensorNetwork2DFlat, optional) – Expand this TN with the same data also, assuming it to be the conjugate, bra, TN.

  • rand_strength (float, optional) – If greater than zero, pad the data arrays with gaussian noise of this strength.

Returns

tn

Return type

TensorNetwork2DFlat

class quimb.tensor.tensor_2d.TensorNetwork2DOperator(ts, *, virtual=False, check_collisions=True)[source]#

Mixin class for a 2D square lattice TN operator, i.e. one with both ‘upper’ and ‘lower’ site (physical) indices.

property lower_ind_id#

The string specifier for the lower phyiscal indices

property lower_inds#

All of the lower inds.

phys_dim(i=0, j=0, which='upper')[source]#

Get a physical index size of this 2D operator.

reindex_lower_sites(new_id, where=None, inplace=False)[source]#

Update the lower site index labels to a new string specifier.

Parameters
  • new_id (str) – A string with a format placeholder to accept an int, e.g. "ket{},{}".

  • where (None or slice) – Which sites to update the index labels on. If None (default) all sites.

  • inplace (bool) – Whether to reindex in place.

reindex_upper_sites(new_id, where=None, inplace=False)[source]#

Update the upper site index labels to a new string specifier.

Parameters
  • new_id (str) – A string with a format placeholder to accept an int, e.g. "ket{},{}".

  • where (None or slice) – Which sites to update the index labels on. If None (default) all sites.

  • inplace (bool) – Whether to reindex in place.

to_dense(*inds_seq, **contract_opts)[source]#

Return the dense matrix version of this 2D operator, i.e. a qarray with shape (d, d).

property upper_ind_id#

The string specifier for the upper phyiscal indices

property upper_inds#

All of the upper inds.

class quimb.tensor.tensor_2d.TensorNetwork2DVector(ts, *, virtual=False, check_collisions=True)[source]#

Mixin class for a 2D square lattice vector TN, i.e. one with a single physical index per site.

compute_local_expectation(terms, max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=('KET', 'BRA'), normalized=False, autogroup=True, contract_optimize='auto-hq', return_all=False, plaquette_envs=None, plaquette_map=None, **plaquette_env_options)[source]#

Compute the sum of many local expecations by essentially forming the reduced density matrix of all required plaquettes. If you supply normalized=True each expecation is locally normalized, which a) is usually more accurate and b) doesn’t require a separate normalization boundary contraction.

Parameters
  • terms (dict[tuple[tuple[int], array]) – A dictionary mapping site coordinates to raw operators, which will be supplied to gate(). The keys should either be a single coordinate - (i, j) - describing a single site operator, or a pair of coordinates - ((i_a, j_a), (i_b, j_b)) describing a two site operator.

  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or sequence of str, optional) – If given, perform a multilayer contraction, contracting the inner sites in each layer into the boundary individually.

  • normalized (bool, optional) – If True, normalize the value of each local expectation by the local norm: $langle O_i rangle = Tr[rho_p O_i] / Tr[rho_p]$.

  • autogroup (bool, optional) – If True (the default), group terms into horizontal and vertical sets to be computed separately (usually more efficient) if possible.

  • contract_optimize (str, optional) – Contraction path finder to use for contracting the local plaquette expectation (and optionally normalization).

  • return_all (bool, optional) – Whether to the return all the values individually as a dictionary of coordinates to tuple[local_expectation, local_norm].

  • plaquette_envs (None or dict, optional) – Supply precomputed plaquette environments.

  • plaquette_map (None, dict, optional) – Supply the mapping of which plaquettes (denoted by ((x0, y0), (dx, dy))) to use for which coordinates, it will be calculated automatically otherwise.

  • plaquette_env_options – Supplied to compute_plaquette_environments() to generate the plaquette environments, equivalent to approximately performing the partial trace.

Return type

scalar or dict

compute_norm(layer_tags=('KET', 'BRA'), **contract_opts)[source]#

Compute the norm of this vector via boundary contraction.

gate(G, where, contract=False, tags=None, propagate_tags='sites', inplace=False, info=None, long_range_use_swaps=False, long_range_path_sequence=None, **compress_opts)[source]#

Apply the dense gate G, maintaining the physical indices of this 2D vector tensor network.

Parameters
  • G (array_like) – The gate array to apply, should match or be factorable into the shape (phys_dim,) * (2 * len(where)).

  • where (sequence of tuple[int, int] or tuple[int, int]) – Which site coordinates to apply the gate to.

  • contract ({'reduce-split', 'split', False, True}, optional) –

    How to contract the gate into the 2D tensor network:

    • False: gate is added to network and nothing is contracted, tensor network structure is thus not maintained.

    • True: gate is contracted with all tensors involved, tensor network structure is thus only maintained if gate acts on a single site only.

    • ’split’: contract all involved tensors then split the result back into two.

    • ’reduce-split’: factor the two physical indices into ‘R-factors’ using QR decompositions on the original site tensors, then contract the gate, split it and reabsorb each side. Much cheaper than 'split'.

    The final two methods are relevant for two site gates only, for single site gates they use the contract=True option which also maintains the structure of the TN. See below for a pictorial description of each method.

  • tags (str or sequence of str, optional) – Tags to add to the new gate tensor.

  • propagate_tags ({'sites', 'register', True, False}, optional) –

    If contract==False, which tags to propagate to the new gate tensor from the tensors it was applied to:

    • If 'sites', then only propagate tags matching e.g. ‘I{},{}’ and ignore all others. I.e. assuming unitary gates just propagate the causal lightcone.

    • If 'register', then only propagate tags matching the sites of where this gate was actually applied. I.e. ignore the lightcone, just keep track of which ‘registers’ the gate was applied to.

    • If False, propagate nothing.

    • If True, propagate all tags.

  • inplace (bool, optional) – Whether to perform the gate operation inplace on the tensor network or not.

  • info (None or dict, optional) – Used to store extra optional information such as the singular values if not absorbed.

  • compress_opts – Supplied to tensor_split() for any contract methods that involve splitting. Ignored otherwise.

Returns

G_psi – The new 2D vector TN like IIIGII @ psi etc.

Return type

TensorNetwork2DVector

Notes

The contract options look like the following (for two site gates).

contract=False:

  │   │
  GGGGG
  │╱  │╱
──●───●──
 ╱   ╱

contract=True:

  │╱  │╱
──GGGGG──
 ╱   ╱

contract='split':

  │╱  │╱          │╱  │╱
──GGGGG──  ==>  ──G┄┄┄G──
 ╱   ╱           ╱   ╱
 <SVD>

contract='reduce-split':

   │   │             │ │
   GGGGG             GGG               │ │
   │╱  │╱   ==>     ╱│ │  ╱   ==>     ╱│ │  ╱          │╱  │╱
 ──●───●──       ──>─●─●─<──       ──>─GGG─<──  ==>  ──G┄┄┄G──
  ╱   ╱           ╱     ╱           ╱     ╱           ╱   ╱
<QR> <LQ>                            <SVD>

For one site gates when one of the ‘split’ methods is supplied contract=True is assumed.

normalize(max_bond=None, *, cutoff=1e-10, canonize=True, mode='mps', layer_tags=('KET', 'BRA'), balance_bonds=False, equalize_norms=False, inplace=False, **contract_boundary_opts)[source]#

Normalize this PEPS.

Parameters
  • max_bond (int, optional) – The maximum boundary dimension, AKA ‘chi’. The default of None means truncation is left purely to cutoff and is not recommended in 2D.

  • cutoff (float, optional) – Cut-off value to used to truncate singular values in the boundary contraction.

  • canonize (bool, optional) – Whether to sweep one way with canonization before compressing.

  • mode ({'mps', 'full-bond'}, optional) – How to perform the compression on the boundary.

  • layer_tags (None or sequence of str, optional) – If given, perform a multilayer contraction, contracting the inner sites in each layer into the boundary individually.

  • balance_bonds (bool, optional) – Whether to balance the bonds after normalization, a form of conditioning.

  • equalize_norms (bool, optional) – Whether to set all the tensor norms to the same value after normalization, another form of conditioning.

  • inplace (bool, optional) – Whether to perform the normalization inplace or not.

  • contract_boundary_opts – Supplied to contract_boundary(), by default, two layer contraction will be used.

phys_dim(i=None, j=None)[source]#

Get the size of the physical indices / a specific physical index.

property site_inds#

All of the site inds.

to_dense(*inds_seq, **contract_opts)[source]#

Return the dense ket version of this 2D vector, i.e. a qarray with shape (-1, 1).

quimb.tensor.tensor_2d.calc_plaquette_map(plaquettes)[source]#

Generate a dictionary of all the coordinate pairs in plaquettes mapped to the ‘best’ (smallest) rectangular plaquette that contains them.

Examples

Consider 4 sites, with one 2x2 plaquette and two vertical (2x1) and horizontal (1x2) plaquettes each:

>>> plaquettes = [
...     # 2x2 plaquette covering all sites
...     ((0, 0), (2, 2)),
...     # horizontal plaquettes
...     ((0, 0), (1, 2)),
...     ((1, 0), (1, 2)),
...     # vertical plaquettes
...     ((0, 0), (2, 1)),
...     ((0, 1), (2, 1)),
... ]
>>> calc_plaquette_map(plaquettes)
{((0, 0), (0, 1)): ((0, 0), (1, 2)),
 ((0, 0), (1, 0)): ((0, 0), (2, 1)),
 ((0, 0), (1, 1)): ((0, 0), (2, 2)),
 ((0, 1), (1, 0)): ((0, 0), (2, 2)),
 ((0, 1), (1, 1)): ((0, 1), (2, 1)),
 ((1, 0), (1, 1)): ((1, 0), (1, 2))}

Now every of the size coordinate pairs is mapped to one of the plaquettes, but to the smallest one that contains it. So the 2x2 plaquette (specified by ((0, 0), (2, 2))) would only used for diagonal terms here.

quimb.tensor.tensor_2d.calc_plaquette_sizes(coo_groups, autogroup=True)[source]#

Find a sequence of plaquette blocksizes that will cover all the terms (coordinate pairs) in pairs.

Parameters
  • coo_groups (sequence of tuple[tuple[int]] or tuple[int]) – The sequence of 2D coordinates pairs describing terms. Each should either be a single 2D coordinate or a sequence of 2D coordinates.

  • autogroup (bool, optional) – Whether to return the minimal sequence of blocksizes that will cover all terms or merge them into a single ((x_bsz, y_bsz),).

Returns

bszs – Pairs of blocksizes.

Return type

tuple[tuple[int]]

Examples

Some nearest neighbour interactions:

>>> H2 = {None: qu.ham_heis(2)}
>>> ham = qtn.LocalHam2D(10, 10, H2)
>>> calc_plaquette_sizes(ham.terms.keys())
((1, 2), (2, 1))
>>> calc_plaquette_sizes(ham.terms.keys(), autogroup=False)
((2, 2),)

If we add any next nearest neighbour interaction then we are going to need the (2, 2) blocksize in any case:

>>> H2[(1, 1), (2, 2)] = 0.5 * qu.ham_heis(2)
>>> ham = qtn.LocalHam2D(10, 10, H2)
>>> calc_plaquette_sizes(ham.terms.keys())
((2, 2),)

If we add longer range interactions (non-diagonal next nearest) we again can benefit from multiple plaquette blocksizes:

>>> H2[(1, 1), (1, 3)] = 0.25 * qu.ham_heis(2)
>>> H2[(1, 1), (3, 1)] = 0.25 * qu.ham_heis(2)
>>> ham = qtn.LocalHam2D(10, 10, H2)
>>> calc_plaquette_sizes(ham.terms.keys())
((1, 3), (2, 2), (3, 1))

Or choose the plaquette blocksize that covers all terms:

>>> calc_plaquette_sizes(ham.terms.keys(), autogroup=False)
((3, 3),)
quimb.tensor.tensor_2d.gen_2d_bonds(Lx, Ly, steppers, coo_filter=None)[source]#

Convenience function for tiling pairs of bond coordinates on a 2D lattice given a function like lambda i, j: (i + 1, j + 1).

Parameters
  • Lx (int) – The number of rows.

  • Ly (int) – The number of columns.

  • steppers (callable or sequence of callable) – Function(s) that take args (i, j) and generate another coordinate, thus defining a bond.

  • coo_filter (callable) – Function that takes args (i, j) and only returns True if this is to be a valid starting coordinate.

Yields

bond (tuple[tuple[int, int], tuple[int, int]]) – A pair of coordinates.

Examples

Generate nearest neighbor bonds:

>>> for bond in gen_2d_bonds(2, 2, [lambda i, j: (i, j + 1),
>>>                                 lambda i, j: (i + 1, j)]):
>>>     print(bond)
((0, 0), (0, 1))
((0, 0), (1, 0))
((0, 1), (1, 1))
((1, 0), (1, 1))

Generate next nearest neighbor digonal bonds:

>>> for bond in gen_2d_bonds(2, 2, [lambda i, j: (i + 1, j + 1),
>>>                                 lambda i, j: (i + 1, j - 1)]):
>>>     print(bond)
((0, 0), (1, 1))
((0, 1), (1, 0))
quimb.tensor.tensor_2d.gen_long_range_path(ij_a, ij_b, sequence=None)[source]#

Generate a string of coordinates, in order, from ij_a to ij_b.

Parameters
  • ij_a ((int, int)) – Coordinate of site ‘a’.

  • ij_b ((int, int)) – Coordinate of site ‘b’.

  • sequence (None, iterable of {'v', 'h'}, or 'random', optional) – What order to cycle through and try and perform moves in, ‘v’, ‘h’ standing for move vertically and horizontally respectively. The default is ('v', 'h').

Returns

The path, each element is a single coordinate.

Return type

generator[tuple[int]]

quimb.tensor.tensor_2d.gen_long_range_swap_path(ij_a, ij_b, sequence=None)[source]#

Generate the coordinates or a series of swaps that would bring ij_a and ij_b together.

Parameters
  • ij_a ((int, int)) – Coordinate of site ‘a’.

  • ij_b ((int, int)) – Coordinate of site ‘b’.

  • sequence (None, it of {'av', 'bv', 'ah', 'bh'}, or 'random', optional) – What order to cycle through and try and perform moves in, ‘av’, ‘bv’, ‘ah’, ‘bh’ standing for move ‘a’ vertically, ‘b’ vertically, ‘a’ horizontally’, and ‘b’ horizontally respectively. The default is ('av', 'bv', 'ah', 'bh').

Returns

The path, each element is two coordinates to swap.

Return type

generator[tuple[tuple[int]]]

quimb.tensor.tensor_2d.is_lone_coo(where)[source]#

Check if where has been specified as a single coordinate pair.

quimb.tensor.tensor_2d.plaquette_to_sites(p)[source]#

Turn a plaquette ((i0, j0), (di, dj)) into the sites it contains.

Examples

>>> plaquette_to_sites([(3, 4), (2, 2)])
((3, 4), (3, 5), (4, 4), (4, 5))
quimb.tensor.tensor_2d.show_2d(tn_2d, show_lower=False, show_upper=False)[source]#

Base function for printing a unicode schematic of flat 2D TNs.

quimb.tensor.tensor_2d.swap_path_to_long_range_path(swap_path, ij_a)[source]#

Generates the ordered long-range path - a sequence of coordinates - from a (long-range) swap path - a sequence of coordinate pairs.