quimb.tensor.environments

Helpers for planning reusable tensor network environments.

Attributes

EnvironmentKey

Classes

EnvironmentMove	A single environment construction or cache operation.
EnvironmentPlan	Plan reusable environments for consecutive blocks in one dimension.

Functions

execute_environment_plan(plan, blocks, init, contract)	Execute an environment plan with supplied numerical operations,
all_blocks(L, size[, cyclic])	Get every valid (start, size) block of one size.
find_1d_block(sites, L, cyclic)	Find the shortest consecutive interval containing specified sites.
gen_exact_environments(tn, plane_tags, blocks, *[, ...])	Yield exact environments for blocks of planes. Each plane is a group
gen_compressed_environments(tn, plane_tags, ...[, ...])	Yield compressed environments for blocks of planes. Each plane is a

Module Contents

quimb.tensor.environments.EnvironmentKey

class quimb.tensor.environments.EnvironmentMove

Bases: NamedTuple

A single environment construction or cache operation.

Parameters:

• kind ({'init', 'contract', 'output', 'delete'}) – init builds output_env from input_sites. contract builds it from cached input_envs and any input_sites. output returns input_envs as the environment of output_block. delete removes them after their last use.

• output_env (tuple[int, int], optional) – Cache key (lo, hi) for the result. The environment contains sites [i % L for i in range(lo, hi)]. The bounds can exceed L.

• input_envs (tuple[tuple[int, int], ...], optional) – Keys of cached input environments. A ‘tree’ contraction uses one environment and one site. A ‘cut’ contraction can also combine two environments without adding a site.

• input_sites (tuple[int, ...], optional) – Original sites for an init or contract, each reduced modulo the periodic length. The current schedules use at most one.

• output_block (tuple[int, int], optional) – The (start, size) target block of an output move.

kind: str

output_env: EnvironmentKey | None = None

input_envs: tuple[EnvironmentKey, ...] = ()

input_sites: tuple[int, ...] = ()

output_block: tuple[int, int] | None = None

class quimb.tensor.environments.EnvironmentPlan(L, cyclic=True, schedule='tree')

Plan reusable environments for consecutive blocks in one dimension.

The default ‘tree’ schedule adds one site at a time. It starts near the opposite side of each target block, and never combines two environments. This makes it suitable for approximate contraction, where combining two large environments can be costly or less accurate.

The ‘cut’ schedule grows environments from a fixed cut, using linear work for a full sweep. This produces two environments for each block. On a ring, it combines the environments either side of each block into one, which is fine for exact contraction. The ‘cutpair’ schedule keeps these separate, so most blocks have two environments, which also share bonds across the cut.

A visual representation of what environments are produced:

non-cyclic: ‘cutpair’: ‘tree’/’cut’:

envl envr env

envl envr ┏━█━█━┓ ┏━███━┓

█━░─░─░━█ ┃ ┃ ┃ ┃

….. ┗░─░─░┛ ┗░─░─░┛ block ….. …..

block block

Parameters:

• L (int) – The number of sites.

• cyclic (bool, optional) – Whether the sites have periodic boundary conditions.

• schedule ({'tree', 'cut', 'cutpair'}, optional) –

  How to share work between target blocks. For a full periodic sweep:

  • ’tree’: add one site at a time, using O(L log L) contractions and O(log L) cached environments. Each target has a single environment.

  • ’cut’: build left and right environments from a fixed cut, then combine them for each target. Uses about 3L contractions and O(L) cached environments.

  • ’cutpair’: as ‘cut’, but keep the left and right environments separate, using about 2L contractions. Blocks that touch or cross the cut have a single environment. Environments are never combined.

  Ignored for open boundaries, where environments grow from each end.

Examples

Plan the environment of the one-site block starting at site three in a six-site ring:

>>> plan = EnvironmentPlan(6)
>>> plan.show([(3, 1)])
 0: init      [I] .  .  .  .  .
 1: contract  [E++I] .  .  .  .
 2: delete    [D] .  .  .  .  .
 3: contract  +E--E] .  .  . [I+
 4: delete    [D--D] .  .  .  .
 5: contract  -E--E++I] .  . [E-
 6: delete    -D--D] .  .  . [D-
 7: contract  -E--E--E] . [I++E-
 8: delete    -D--D--D] .  . [D-
 9: output    -E--E--E] B [E--E-    => (3, 1)
10: delete    -D--D--D] . [D--D-

Plan every two-site block:

>>> plan.show([(i, 2) for i in range(6)])
 0: init       .  .  .  . [I] .
 1: contract   .  .  .  . [E++I]
 2: delete     .  .  .  . [D] .
 3: contract   .  .  . [I++E--E]
 4: contract   .  . [I++E--E--E]
 5: delete     .  .  . [D--D--D]
 6: output     B  B [E--E--E--E]    => (0, 2)
 7: delete     .  . [D--D--D--D]
 8: contract  +I] .  .  . [E--E+
 9: delete     .  .  .  . [D--D]
10: contract  -E] .  . [I++E--E-
11: output    -E] B  B [E--E--E-    => (1, 2)
12: delete    -D] .  . [D--D--D-
13: contract  -E++I] .  . [E--E-
14: delete    -D] .  .  . [D--D-
15: output    -E--E] B  B [E--E-    => (2, 2)
16: delete    -D--D] .  . [D--D-
17: init       . [I] .  .  .  .
18: contract   . [E++I] .  .  .
19: delete     . [D] .  .  .  .
20: contract  [I++E--E] .  .  .
21: contract  +E--E--E] .  . [I+
22: delete    [D--D--D] .  .  .
23: output    -E--E--E] B  B [E-    => (3, 2)
24: delete    -D--D--D] .  . [D-
25: contract   . [E--E++I] .  .
26: delete     . [D--D] .  .  .
27: contract  [I++E--E--E] .  .
28: output    [E--E--E--E] B  B     => (4, 2)
29: delete    [D--D--D--D] .  .
30: contract   . [E--E--E++I] .
31: delete     . [D--D--D] .  .
32: output     B [E--E--E--E] B     => (5, 2)
33: delete     . [D--D--D--D] .

L

cyclic = True

schedule = 'tree'

_init_tree_interval(lo, hi, moves)

Build an environment for [lo, hi), starting at its midpoint.

_extend_interval(env_key, target, moves)

Extend env_key to target, adding sites on alternate sides.

_build_cyclic_tree(blocks, moves)

_build_cut(blocks, moves)

_build_cyclic_cut(blocks, moves)

static _remove_redundant(moves)

Remove any environment moves that produce the same interval.

static _add_deletes(moves)

Add a delete move after each environment’s last use.

get_moves(blocks, include_deletes=True)

Get the sequence of operations needed to construct all environments for blocks.

Parameters:

• blocks (sequence of tuple[int, int]) – The (start, size) target blocks, which can have different sizes. Use all_blocks() to get every block of one size.

• include_deletes (bool, optional) – Whether to add delete moves after the last use of each cached environment.

Returns:

Operations in execution order.

Return type:

tuple[EnvironmentMove, …]

Examples

Select only the one-site environments at sites one and three:

>>> plan = EnvironmentPlan(4)
>>> moves = plan.get_moves([(1, 1), (3, 1)])
>>> [move.output_block for move in moves if move.kind == "output"]
[(1, 1), (3, 1)]

show(blocks, include_deletes=True)

Print a visual representation of the environment moves.

E marks an input environment, I an original input site, B a target block, and D an environment being deleted.

Parameters:

• blocks (sequence of tuple[int, int]) – The (start, size) target blocks to show.

• include_deletes (bool, optional) – Whether to show cache deletion moves.

quimb.tensor.environments.execute_environment_plan(plan, blocks, init, contract)

Execute an environment plan with supplied numerical operations, yielding each block’s environment as soon as it is ready. Every cached environment is dropped after its last use.

Parameters:

• plan (EnvironmentPlan) – The symbolic environment schedule to execute.

• blocks (sequence of tuple[int, int]) – The (start, size) target blocks to compute.

• init (callable) – Called as init(input_sites) for each 'init' move. It should construct an environment from the specified original sites.

• contract (callable) – Called as contract(input_envs, input_sites) for each 'contract' move. input_envs is a tuple of one or two cached values. input_sites is a tuple of original sites, one for a tree contraction and none for an environment-environment merge.

Yields:

• block (tuple[int, int]) – The (start, size) block.

• pieces (tuple) – The environment pieces for block.

quimb.tensor.environments.all_blocks(L, size, cyclic=True)

Get every valid (start, size) block of one size.

Parameters:

• L (int) – Total number of sites.

• size (int) – Number of consecutive sites in each block.

• cyclic (bool, optional) – Whether blocks can wrap around the periodic boundary.

Return type:

tuple[tuple[int, int], …]

quimb.tensor.environments.find_1d_block(sites, L, cyclic)

Find the shortest consecutive interval containing specified sites.

Parameters:

• sites (sequence of int) – Sites to cover. Periodic sites are reduced modulo L and duplicate sites are ignored.

• L (int) – Total number of sites.

• cyclic (bool) – Whether the interval is allowed to cross the periodic boundary.

Returns:

• start (int) – Start of the shortest covering interval.

• size (int) – Number of consecutive sites in the interval.

Notes

In the cyclic case this finds the largest gap between requested sites and returns its complement. Ties between equal-size intervals resolve to the smallest start.

quimb.tensor.environments.gen_exact_environments(tn, plane_tags, blocks, *, cyclic=True, schedule='auto', contract_opts=None)

Yield exact environments for blocks of planes. Each plane is a group of tensors selected by one tag, e.g. a site in 1D or a row in 2D. Yield each environment as soon as it is ready.

Parameters:

• tn (TensorNetwork) – Tensor network containing the planes to contract.

• plane_tags (sequence of str) – One tag per plane, in order along the contraction direction. The number of tags defines L. Plane i is site i in the EnvironmentPlan.

• blocks (sequence of tuple[int, int]) – The (start, size) target blocks of planes, which can have different sizes.

• cyclic (bool, optional) – Whether the planes wrap around periodically.

• schedule ({'auto', 'tree', 'cut', 'cutpair'}, optional) – Environment construction schedule, only relevant if cyclic. By default use ‘cut’, which uses linear work by permitting exact environment-environment contractions.

• contract_opts (dict, optional) – Supplied to TensorNetwork.contract(). Always uses preserve_tensor=True so even scalar environments remain tensors.

Yields:

• block (tuple[int, int]) – The (start, size) block.

• environment (TensorNetwork) – The exact environment of block.

Notes

An empty complement is represented by an empty tensor network.

quimb.tensor.environments.gen_compressed_environments(tn, plane_tags, transverse_tags, blocks, max_bond=None, *, cyclic=True, compress_fn='ag', schedule='auto', method=None, layer_tags=None, cutoff=None, canonize=True, optimize='auto-hq', equalize_norms=False, compress_opts=None, **compress_method_opts)

Yield compressed environments for blocks of planes. Each plane is a group of tensors selected by one tag, e.g. a row in 2D. Add planes along plane_tags and compress along transverse_tags, e.g. the columns. Yield each environment as soon as it is ready.

With rows R0 ... R5 and columns C0 ... C4, the environment of block (2, 2) is:

R0, R1  ●━━━━●━━━━●━━━━●━━━━●   compressed planes before the block
        │    │    │    │    │
R2      o────o────o────o────o   ┬
        │    │    │    │    │   ┊ the block, not included
R3      o────o────o────o────o   ┴
        │    │    │    │    │
R4, R5  ●━━━━●━━━━●━━━━●━━━━●   compressed planes after the block
        C0   C1   C2   C3   C4

If cyclic, the planes before and after the block form a single environment, connected to both the first and last plane of the block. The ‘cutpair’ schedule instead usually keeps them as two, which are also connected across the periodic boundary.

Parameters:

• tn (TensorNetwork) – Tensor network containing the planes to contract.

• plane_tags (sequence of str) – One tag per plane, in order along the contraction direction. The number of tags defines L. Plane i is site i in the EnvironmentPlan.

• transverse_tags (sequence of str) – Tags for sites within each plane, in compression order. Each tensor must have exactly one of these tags.

• blocks (sequence of tuple[int, int]) – The (start, size) target blocks of planes, which can have different sizes.

• max_bond (int, optional) – Maximum compressed bond dimension.

• cyclic (bool, optional) – Whether the planes wrap around periodically.

• compress_fn ({'ag', '1d', '2d'}, optional) –

  Which compression function to use, for the geometry of each environment along the transverse sites:

  • ’ag’: tensor_network_ag_compress(), for any geometry, such as a ring.

  • ’1d’: tensor_network_1d_compress(), for an open chain.

  • ’2d’: tensor_network_2d_compress(), for a 2D lattice.

• schedule ({'auto', 'tree', 'cut', 'cutpair'}, optional) – Environment construction schedule, only relevant if cyclic. By default use ‘tree’, which never compresses two environments together. The ‘cut’ schedule uses fewer compressions but combines two environments as its final step, which can be expensive in an approx contraction setting. The ‘cutpair’ schedule keeps these two environments separate.

• method (str or callable, optional) – The compression method, supplied to compress_fn. By default use its own default method.

• layer_tags (None or sequence of str, optional) – Tags identifying the layers, which are contracted one by one in this order. Use None to contract all layers together. Booleans and integers are not accepted. Compress after each layer. Tensors with several layer tags are assigned to the first matching layer.

• cutoff (float, optional) – Compression cutoff, supplied to compress_fn. By default use its own default cutoff.

• canonize (bool or str, optional) – Canonicalization option supplied to the compressor.

• optimize (str, optional) – Contraction path optimizer supplied to the compressor.

• equalize_norms (bool or float, optional) – Whether to equalize tensor norms after each compression.

• compress_opts (dict, optional) – Additional options supplied to the compressor.

• compress_method_opts – Additional options supplied to the compression method.

Yields:

• block (tuple[int, int]) – The (start, size) block.

• environment (TensorNetwork) – The compressed environment of block.