quimb.tensor.networking¶

Functionality for analyzing the structure of tensor networks, including finding paths, loops, connected components, hierarchical groupings and more.

Classes¶

NetworkPath

A simple class to represent a path through a tensor network, storing

Functions¶

`istree`(tn)	Check if this tensor network has a tree structure, (treating
`isconnected`(tn)	Check whether this tensor network is connected, i.e. whether
`subgraphs`(tn[, virtual])	Split this tensor network into disconneceted subgraphs.
`get_tree_span`(tn, tids[, min_distance, max_distance, ...])	Generate a tree on the tensor network graph, fanning out from the
`get_local_patch`(tn, tids, max_distance[, include, exclude])	Get the local patch of tids that is within `max_distance` of
`get_path_between_tids`(tn, tida, tidb)	Find a shortest path between `tida` and `tidb` in this tensor
`gen_all_paths_between_tids`(tn, tida, tidb)	Generate all shortest paths between `tida` and `tidb` in this
`gen_paths_loops`(tn[, max_loop_length, intersect, ...])	Generate all paths, up to a specified length, that represent loops in
`gen_patches`(tn, max_size[, tids, grow_from])	Generate sets of tids that represent 'patches' of the tensor network,
`gen_gloops`(tn[, max_size, tids, grow_from])	Generate sets of tids that represent 'generalized loops' where every
`gen_loops`(tn[, max_loop_length])	Generate sequences of tids that represent loops in the TN.
`get_loop_union`(tn, tids[, max_size, grow_from])	Find the union, in terms of tids, of all generliazed loops that pass
`gen_inds_connected`(tn, max_length)	Generate all index 'patches' of size up to `max_length`.
`tids_are_connected`(tn, tids)	Check whether nodes `tids` are connected.
`compute_shortest_distances`(tn[, tids, exclude_inds])	Compute the minimum graph distances between all or some nodes
`compute_hierarchical_linkage`(tn[, tids, method, ...])
`compute_hierarchical_ssa_path`(tn[, tids, method, ...])	Compute a hierarchical grouping of `tids`, as a `ssa_path`.
`compute_hierarchical_ordering`(tn[, tids, method, ...])	Compute a hierarchical ordering of `tids`.
`compute_hierarchical_grouping`(tn, max_group_size[, ...])	Group `tids` (by default, all tensors) into groups of size
`compute_centralities`(tn)	Compute a simple centrality measure for each tensor in the network. The
`most_central_tid`(tn)	Find the most central tensor in the network.
`least_central_tid`(tn)	Find the least central tensor in the network.

Module Contents¶

class quimb.tensor.networking.NetworkPath(tids, inds=())¶

A simple class to represent a path through a tensor network, storing both the tensor identifies (tids) and indices (inds) it passes through.

__slots__ = ('_tids', '_inds', '_key')¶

_tids¶

_inds = ()¶

_key = None¶

classmethod from_sequence(it)¶

property tids¶

property inds¶

property key¶

__len__()¶

__iter__()¶

__contains__(x)¶

__hash__()¶

__repr__()¶

extend(ind, tid)¶: Get a new path by extending this one with a new index and tensor id.

quimb.tensor.networking.istree(tn)¶

Check if this tensor network has a tree structure, (treating multibonds as a single edge).

Examples

>>> MPS_rand_state(10, 7).istree()
True

>>> MPS_rand_state(10, 7, cyclic=True).istree()
False

quimb.tensor.networking.isconnected(tn)¶: Check whether this tensor network is connected, i.e. whether there is a path between any two tensors, (including size 1 indices).

quimb.tensor.networking.subgraphs(tn, virtual=False)¶

Split this tensor network into disconneceted subgraphs.

Parameters:: virtual (bool, optional) – Whether the tensor networks should view the original tensors or not - by default take copies.
Return type:: list[TensorNetwork]

quimb.tensor.networking.get_tree_span(tn, tids, min_distance=0, max_distance=None, include=None, exclude=None, ndim_sort='max', distance_sort='min', sorter=None, weight_bonds=True, inwards=True)¶

Generate a tree on the tensor network graph, fanning out from the tensors identified by tids, up to a maximum of max_distance away. The tree can be visualized with draw_tree_span().

Parameters:

tids (sequence of str) – The nodes that define the region to span out of.
min_distance (int, optional) – Don’t add edges to the tree until this far from the region. For example, 1 will not include the last merges from neighboring tensors in the region defined by tids.
max_distance (None or int, optional) – Terminate branches once they reach this far away. If None there is no limit,
include (sequence of str, optional) – If specified, only tids specified here can be part of the tree.
exclude (sequence of str, optional) – If specified, tids specified here cannot be part of the tree.
ndim_sort ({'min', 'max', 'none'}, optional) – When expanding the tree, how to choose what nodes to expand to next, once connectivity to the current surface has been taken into account.
distance_sort ({'min', 'max', 'none'}, optional) – When expanding the tree, how to choose what nodes to expand to next, once connectivity to the current surface has been taken into account.
weight_bonds (bool, optional) – Whether to weight the ‘connection’ of a candidate tensor to expand out to using bond size as well as number of bonds.

Returns:

The ordered list of merges, each given as tuple (tid1, tid2, d) indicating merge tid1 -> tid2 at distance d.

Return type:

list[(str, str, int)]

See also

draw_tree_span

quimb.tensor.networking.get_local_patch(tn, tids, max_distance, include=None, exclude=None)¶

Get the local patch of tids that is within max_distance of the given tids. This is like an unordered version of get_tree_span.

Parameters:

tn (TensorNetwork) – The tensor network to get the local patch from.
tids (sequence of int) – The tensor ids to start from.
max_distance (int) – The maximum distance from tids to include, in terms of graph distance. 0 corresponds to the original tids, 1 to nearest neighbors and so on.
include (sequence of int, optional) – If specified, only tids from this set can be included in the patch.
exclude (sequence of int, optional) – If specified, tids from this set cannot be included in the patch.

Return type:

tuple[int]

quimb.tensor.networking.get_path_between_tids(tn, tida, tidb)¶

Find a shortest path between tida and tidb in this tensor network. Returns a NetworkPath if a path is found, otherwise None.

Currently ignores dangling and hyper indices.

Parameters:

tn (TensorNetwork) – The tensor network to find a path in.
tida (int) – The tensor id to start from.
tidb (int) – The tensor id to end at.

Return type:

NetworkPath or None

quimb.tensor.networking.gen_all_paths_between_tids(tn, tida, tidb)¶

Generate all shortest paths between tida and tidb in this tensor network. Returns a generator of NetworkPath objects, ignores dangling and hyper indices currently.

Parameters:

tn (TensorNetwork) – The tensor network to find paths in.
tida (int) – The tensor id to start from.
tidb (int) – The tensor id to end at.

Yields:

NetworkPath

quimb.tensor.networking.gen_paths_loops(tn, max_loop_length=None, intersect=False, tids=None, inds=None, paths=None)¶

Generate all paths, up to a specified length, that represent loops in this tensor network. Unlike gen_loops this function will yield a NetworkPath objects, allowing one to differentiate between e.g. a double loop and a ‘figure of eight’ loop. Dangling and hyper indices are ignored.

Parameters:

tn (TensorNetwork) – The tensor network to find loops in.
max_loop_length (None or int) – Set the maximum number of indices that can appear in a loop. If None, wait until any loop is found and set that as the maximum length.
intersect (bool, optional) – Whether to allow self-intersecting loops.
tids (None or sequence of int, optional) – If supplied, only consider loops containing one of these tensor ids.
inds (None or sequence of str, optional) – If supplied, only consider loops containing one of these indices.
paths (None or sequence of NetworkPath, optional) – If supplied, only consider loops starting from these paths.

Yields:

NetworkPath

See also

gen_loops, gen_inds_connected

quimb.tensor.networking.gen_patches(tn, max_size, tids=None, grow_from='all')¶: Generate sets of tids that represent ‘patches’ of the tensor network, where each patch is a connected subgraph of the tensor network. Unlike generalized loops, patches can contain dangling nodes.

quimb.tensor.networking.gen_gloops(tn, max_size=None, tids=None, grow_from='all')¶

Generate sets of tids that represent ‘generalized loops’ where every node is connected to at least two bonds, i.e. 2-degree connected subgraphs.

Parameters:

tn (TensorNetwork) – The tensor network to find loops in.
max_size (None or int) – Set the maximum number of tensors that can appear in a region. If None, wait until any valid region is found and set that as the maximum size.
tids (None or sequence of int, optional) – If supplied, only yield loops containing these tids, see grow_from.
grow_from ({'all', 'any', 'alldangle', 'anydangle'}, optional) – Only if tids is specified, this determines how to filter loops. If ‘all’, only yield loops containing all of the tids in tids, if ‘any’, yield loops containing any of the tids in tids. If ‘alldangle’ or ‘anydangle’, the tids are allowed to be dangling, i.e. 1-degree connected. This is useful for computing local expectations where the operator insertion breaks the loop assumption locally.

Yields:

tuple[int]

quimb.tensor.networking.gen_loops(tn, max_loop_length=None)¶

Generate sequences of tids that represent loops in the TN.

Parameters:: max_loop_length (None or int) – Set the maximum number of tensors that can appear in a loop. If None, wait until any loop is found and set that as the maximum length.
Yields:: tuple[int]

See also

gen_paths_loops

quimb.tensor.networking.get_loop_union(tn, tids, max_size=None, grow_from='all')¶

Find the union, in terms of tids, of all generliazed loops that pass through either all or at least one of the given tids, depending on grow_from.

Parameters:

tn (TensorNetwork) – The tensor network to find the loop union region in.
tids (sequence of int) – The tensor ids to consider.
max_size (None or int, optional) – The maximum number of tensors that can appear in the region. If None, wait until any valid region is found and set that as the maximum size.
grow_from ({'all', 'any', 'alldangle', 'anydangle'}, optional) – Only if tids is specified, this determines how to filter loops. If ‘all’, only take loops containing all of the tids in tids, if ‘any’, yield loops containing any of the tids in tids. If ‘alldangle’ or ‘anydangle’, the tids are allowed to be dangling, i.e. 1-degree connected.

Return type:

tuple[int]

quimb.tensor.networking.gen_inds_connected(tn, max_length)¶

Generate all index ‘patches’ of size up to max_length.

Parameters:: max_length (int) – The maximum number of indices in the patch.
Yields:: tuple[str]

See also

gen_paths_loops

quimb.tensor.networking.tids_are_connected(tn, tids)¶

Check whether nodes tids are connected.

Parameters:

tn (TensorNetwork) – The tensor network to check.
tids (sequence of int) – Nodes to check.

Return type:

bool

quimb.tensor.networking.compute_shortest_distances(tn, tids=None, exclude_inds=())¶

Compute the minimum graph distances between all or some nodes tids.

Parameters:

tn (TensorNetwork) – The tensor network to compute distances in.
tids (None or sequence of int, optional) – If supplied, only compute distances between these nodes.
exclude_inds (sequence of str, optional) – Exclude these indices when computing distances.

Return type:

dict[tuple[int, int], int]

quimb.tensor.networking.compute_hierarchical_linkage(tn, tids=None, method='weighted', optimal_ordering=True, exclude_inds=())¶

quimb.tensor.networking.compute_hierarchical_ssa_path(tn, tids=None, method='weighted', optimal_ordering=True, exclude_inds=(), are_sorted=False, linkage=None)¶: Compute a hierarchical grouping of tids, as a ssa_path.

quimb.tensor.networking.compute_hierarchical_ordering(tn, tids=None, method='weighted', optimal_ordering=True, exclude_inds=(), linkage=None)¶: Compute a hierarchical ordering of tids.

quimb.tensor.networking.compute_hierarchical_grouping(tn, max_group_size, tids=None, method='weighted', optimal_ordering=True, exclude_inds=(), linkage=None)¶: Group tids (by default, all tensors) into groups of size max_group_size or less, using a hierarchical clustering.

quimb.tensor.networking.compute_centralities(tn)¶

Compute a simple centrality measure for each tensor in the network. The values go from 0 to 1, with 1 being the most central tensor.

Parameters:: tn (TensorNetwork) – The tensor network to compute centralities for.
Return type:: dict[int, float]

quimb.tensor.networking.most_central_tid(tn)¶: Find the most central tensor in the network.

quimb.tensor.networking.least_central_tid(tn)¶: Find the least central tensor in the network.