quimb.tensor.networking

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

Classes

NetworkPatch	A simple class to represent a patch of tensors and indices, storing
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_sloops(tn[, max_loop_length, num_joins, ...])
gen_patches(tn, max_size[, tids, grow_from])	Generate groups of tids that represent 'patches' of the tensor network,
connected_bipartitions(tn)	Generate all connected bipartitions of this tensor network, i.e.
_gen_gloops_single(tn[, max_size, tids, grow_from])
gen_gloops(tn[, max_size, tids, grow_from, num_joins, ...])	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.NetworkPatch(tids, inds)

A simple class to represent a patch of tensors and indices, storing both the tensor identifies (tids) and indices (inds) it contains.

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

_tids

_inds

_key = None

classmethod from_sequence(it)

property tids

property inds

__iter__()

property key

merge(other)

__contains__(x)

__hash__()

__eq__(other)

__repr__()

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

Bases: NetworkPatch

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

__len__()

__iter__()

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_sloops(tn, max_loop_length=None, num_joins=1, intersect=False, tids=None, inds=None, paths=None)

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

Generate groups 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.

Parameters:

• tn (TensorNetwork) – The tensor network to find patches in.

• max_size (int) – Set the maximum number of tensors that can appear in a region.

• tids (None or sequence of int, optional) – If supplied, only yield patches containing these tids, see grow_from.

• grow_from ({"all", "any"}, optional) – Whether to grow patches from all tids at once (“all”) or from any individual tid (“any”). The subsequent patches yielded will either contain all, or at least one of, tids specified respectively.

Yields:

tuple[int, …]

quimb.tensor.networking.connected_bipartitions(tn)

Generate all connected bipartitions of this tensor network, i.e. pairs of sets of tids (A, B) such that A U B is the full set of tids, A ∩ B = ∅, and both A and B are connected subgraphs.

Parameters:

tn (TensorNetwork) – The tensor network to find bipartitions in.

Returns:

The connected bipartitions found, each given as a tuple of frozensets of tids.

Return type:

tuple[(frozenset[int, …], frozenset[int, …]), …]

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

quimb.tensor.networking.gen_gloops(tn, max_size=None, tids=None, grow_from='all', num_joins=1, join_overlap=2)

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.

• num_joins (int, optional) – If larger than 1, repeatedly generate larger loops by joining together the initial set (individually with size up to max_size) of generalized loops. Each join combines loops that overlap on at least join_overlap tids.

• join_overlap ({1, 2}, optional) – When joining loops together, the minimum number of overlapping tids they much share. 1 allows merging on a single node, 2 requires sharing a bond, which leads to fewer but ‘denser’ loops.

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 base 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.