quimb.tensor.tensor_arbgeom¶
Classes and algorithms related to arbitrary geometry tensor networks.
Attributes¶
Classes¶
A tensor network which notionally has a single tensor per 'site', 

A tensor network which notionally has a single tensor and outer index 

A tensor network which notionally has a single tensor and two outer 
Functions¶



Product of all elements in 

Align an arbitrary number of tensor networks in a stacklike geometry: 

Apply a general a general tensor network representing an operator (has 

Apply the operator (has upper and lower site inds) represented by tensor 

Given a tensor network, where each tensor is in exactly one group or 

Add two tensor networks with arbitrary, but matching, geometries. They 





Unified helper function for the various methods that compute many 

Define as function for pickleability. 

Define as function for pickleability. 

Define as function for pickleability. 

Define as function for pickleability. 

Define as function for pickleability. 
Module Contents¶
 quimb.tensor.tensor_arbgeom.tensor_network_align(*tns, ind_ids=None, trace=False, inplace=False)[source]¶
Align an arbitrary number of tensor networks in a stacklike geometry:
aaaaaaaaaaaaaaaaaa                   < ind_ids[0] (defaults to 1st id) bbbbbbbbbbbbbbbbbb                   < ind_ids[1] ...                   < ind_ids[2] yyyyyyyyyyyyyyyyyy                   < ind_ids[1] zzzzzzzzzzzzzzzzzz
 Parameters:
tns (sequence of TensorNetwork) – The TNs to align, should be structured and either effective ‘vectors’ (have a
site_ind_id
) or ‘operators’ (have aup_ind_id
andlower_ind_id
).ind_ids (None, or sequence of str) – String with format specifiers to id each level of sites with. Will be automatically generated like
(tns[0].site_ind_id, "__ind_a{}__", "__ind_b{}__", ...)
if not given.inplace (bool) – Whether to modify the input tensor networks inplace.
 Returns:
tns_aligned
 Return type:
sequence of TensorNetwork
 quimb.tensor.tensor_arbgeom.tensor_network_apply_op_vec(A, x, which_A='lower', contract=False, fuse_multibonds=True, compress=False, inplace=False, inplace_A=False, **compress_opts)[source]¶
Apply a general a general tensor network representing an operator (has
upper_ind_id
andlower_ind_id
) to a tensor network representing a vector (hassite_ind_id
), by contracting each pair of tensors at each site then compressing the resulting tensor network. How the compression takes place is determined by the type of tensor network passed in. The returned tensor network has the same site indices asx
, and it is thelower_ind_id
ofA
that is contracted.This is like performing
A.to_dense() @ x.to_dense()
, or the transpose thereof, depending on the value ofwhich_A
. Parameters:
A (TensorNetworkGenOperator) – The tensor network representing the operator.
x (TensorNetworkGenVector) – The tensor network representing the vector.
which_A ({"lower", "upper"}, optional) – Whether to contract the lower or upper indices of
A
with the site indices ofx
.contract (bool) – Whether to contract the tensors at each site after applying the operator, yielding a single tensor at each site.
fuse_multibonds (bool) – If
contract=True
, whether to fuse any multibonds after contracting the tensors at each site.compress (bool) – Whether to compress the resulting tensor network.
inplace (bool) – Whether to modify
x
, the input vector tensor network inplace.inplace_A (bool) – Whether to modify
A
, the operator tensor network inplace.compress_opts – Options to pass to
tn.compress
, wheretn
is the resulting tensor network, ifcompress=True
.
 Returns:
The same type as
x
. Return type:
 quimb.tensor.tensor_arbgeom.tensor_network_apply_op_op(A, B, which_A='lower', which_B='upper', contract=False, fuse_multibonds=True, compress=False, inplace=False, inplace_A=False, **compress_opts)[source]¶
Apply the operator (has upper and lower site inds) represented by tensor network
A
to the operator represented by tensor networkB
. The resulting tensor network has the same upper and lower indices asB
. Optionally contract the tensors at each site, fuse any multibonds, and compress the resulting tensor network.This is like performing
A.to_dense() @ B.to_dense()
, or various combinations of tranposes thereof, depending on the values ofwhich_A
andwhich_B
. Parameters:
A (TensorNetworkGenOperator) – The tensor network representing the operator to apply.
B (TensorNetworkGenOperator) – The tensor network representing the target operator.
which_A ({"lower", "upper"}, optional) – Whether to contract the lower or upper indices of
A
.which_B ({"lower", "upper"}, optional) – Whether to contract the lower or upper indices of
B
.contract (bool) – Whether to contract the tensors at each site after applying the operator, yielding a single tensor at each site.
fuse_multibonds (bool) – If
contract=True
, whether to fuse any multibonds after contracting the tensors at each site.compress (bool) – Whether to compress the resulting tensor network.
inplace (bool) – Whether to modify
B
, the target tensor network inplace.inplace_A (bool) – Whether to modify
A
, the applied operator tensor network inplace.compress_opts – Options to pass to
tn.compress
, wheretn
is the resulting tensor network, ifcompress=True
.
 Returns:
The same type as
B
. Return type:
 quimb.tensor.tensor_arbgeom.create_lazy_edge_map(tn, site_tags=None)[source]¶
Given a tensor network, where each tensor is in exactly one group or ‘site’, compute which sites are connected to each other, without checking each pair.
 Parameters:
tn (TensorNetwork) – The tensor network to analyze.
site_tags (None or sequence of str, optional) – Which tags to consider as ‘sites’, by default uses
tn.site_tags
.
 Returns:
edges (dict[tuple[str, str], list[str]]) – Each key is a sorted pair of tags, which are connected, and the value is a list of the indices connecting them.
neighbors (dict[str, list[str]]) – For each site tag, the other site tags it is connected to.
 quimb.tensor.tensor_arbgeom.tensor_network_ag_sum(tna, tnb, site_tags=None, negate=False, compress=False, inplace=False, **compress_opts)[source]¶
Add two tensor networks with arbitrary, but matching, geometries. They should have the same site tags, with a single tensor per site and sites connected by a single index only (but the name of this index can differ in the two TNs).
 Parameters:
tna (TensorNetworkGen) – The first tensor network to add.
tnb (TensorNetworkGen) – The second tensor network to add.
site_tags (None or sequence of str, optional) – Which tags to consider as ‘sites’, by default uses
tna.site_tags
.negate (bool, optional) – Whether to negate the second tensor network before adding.
compress (bool, optional) – Whether to compress the resulting tensor network, by calling the
compress
method with the given options.inplace (bool, optional) – Whether to modify the first tensor network inplace.
 Returns:
The resulting tensor network.
 Return type:
 class quimb.tensor.tensor_arbgeom.TensorNetworkGen(ts=(), *, virtual=False, check_collisions=True)[source]¶
Bases:
quimb.tensor.tensor_core.TensorNetwork
A tensor network which notionally has a single tensor per ‘site’, though these could be labelled arbitrarily could also be linked in an arbitrary geometry by bonds.
 _NDIMS = 1¶
 _EXTRA_PROPS = ('_sites', '_site_tag_id')¶
 _compatible_arbgeom(other)[source]¶
Check whether
self
andother
represent the same set of sites and are tagged equivalently.
 combine(other, *, virtual=False, check_collisions=True)[source]¶
Combine this tensor network with another, returning a new tensor network. If the two are compatible, cast the resulting tensor network to a
TensorNetworkGen
instance. Parameters:
other (TensorNetworkGen or TensorNetwork) – The other tensor network to combine with.
virtual (bool, optional) – Whether the new tensor network should copy all the incoming tensors (
False
, the default), or view them as virtual (True
).check_collisions (bool, optional) – Whether to check for index collisions between the two tensor networks before combining them. If
True
(the default), any inner indices that clash will be mangled.
 Return type:
 property nsites¶
The total number of sites.
 property sites¶
Tuple of the possible sites in this tensor network.
 gen_sites_present()[source]¶
Generate the sites which are currently present (e.g. if a local view of a larger tensor network), based on whether their tags are present.
Examples
>>> tn = qtn.TN3D_rand(4, 4, 4, 2) >>> tn_sub = tn.select_local('I1,2,3', max_distance=1) >>> list(tn_sub.gen_sites_present()) [(0, 2, 3), (1, 1, 3), (1, 2, 2), (1, 2, 3), (1, 3, 3), (2, 2, 3)]
 property site_tag_id¶
The string specifier for tagging each site of this tensor network.
 retag_sites(new_id, where=None, inplace=False)[source]¶
Modify the site tags for all or some tensors in this tensor network (without changing the
site_tag_id
).
 property site_tags¶
All of the site tags.
 property site_tags_present¶
All of the site tags still present in this tensor network.
 maybe_convert_coo(x)[source]¶
Check if
x
is a valid site and convert to the corresponding site tag if so, else returnx
.
 _get_tids_from_tags(tags, which='all')[source]¶
This is the function that lets coordinates such as
site
be used for many ‘tag’ based functions.
 _get_tid_to_site_map()[source]¶
Get a mapping from low level tensor id to the site it represents, assuming there is a single tensor per site.
 gen_regions_sites(max_region_size=None, sites=None)[source]¶
Generate sets of sites that represent ‘regions’ where every node is connected to at least two other region nodes. This is a simple wrapper around
TensorNewtork.gen_regions
that works with the sites rather thantids
. Parameters:
 Yields:
tuple[hashable]
 reset_cached_properties()[source]¶
Reset any cached properties, one should call this when changing the actual geometry of a TN inplace, for example.
 quimb.tensor.tensor_arbgeom.gauge_product_boundary_vector(tn, tags, which='all', max_bond=1, smudge=1e06, canonize_distance=0, select_local_distance=None, select_local_opts=None, **contract_around_opts)[source]¶
 quimb.tensor.tensor_arbgeom._VALID_GATE_PROPAGATE¶
 quimb.tensor.tensor_arbgeom._LAZY_GATE_CONTRACT¶
 class quimb.tensor.tensor_arbgeom.TensorNetworkGenVector(ts=(), *, virtual=False, check_collisions=True)[source]¶
Bases:
TensorNetworkGen
A tensor network which notionally has a single tensor and outer index per ‘site’, though these could be labelled arbitrarily and could also be linked in an arbitrary geometry by bonds.
 _EXTRA_PROPS = ('_sites', '_site_tag_id', '_site_ind_id')¶
 property site_ind_id¶
The string specifier for the physical indices.
 property site_inds¶
Return a tuple of all site indices.
 property site_inds_present¶
All of the site inds still present in this tensor network.
 reset_cached_properties()[source]¶
Reset any cached properties, one should call this when changing the actual geometry of a TN inplace, for example.
 reindex_sites(new_id, where=None, inplace=False)[source]¶
Modify the site indices for all or some tensors in this vector tensor network (without changing the
site_ind_id
).
 phys_dim(site=None)[source]¶
Get the physical dimension of
site
, defaulting to the first site if not specified.
 to_dense(*inds_seq, to_qarray=False, to_ket=None, **contract_opts)[source]¶
Contract this tensor network ‘vector’ into a dense array. By default, turn into a ‘ket’
qarray
, i.e. column vector of shape(d, 1)
. Parameters:
inds_seq (sequence of sequences of str) – How to group the site indices into the dense array. By default, use a single group ordered like
sites
, but only containing those sites which are still present.to_qarray (bool) – Whether to turn the dense array into a
qarray
, if the backend would otherwise be'numpy'
.to_ket (None or str) – Whether to reshape the dense array into a ket (shape
(d, 1)
array). IfNone
(default), do this only if theinds_seq
is not supplied.contract_opts – Options to pass to
contract()
.
 Return type:
array
 gate_with_op_lazy(A, transpose=False, inplace=False, **kwargs)[source]¶
Act lazily with the operator tensor network
A
, which should have matching structure, on this vector/state tensor network, likeA @ x
. The returned tensor network will have the same structure as this one, but with the operator gated in lazily, i.e. uncontracted.\[ x \rangle \rightarrow A  x \rangle\]or (if
transpose=True
):\[ x \rangle \rightarrow A^T  x \rangle\] Parameters:
A (TensorNetworkGenOperator) – The operator tensor network to gate with, or apply to this tensor network.
transpose (bool, optional) – Whether to contract the lower or upper indices of
A
with the site indices ofx
. IfFalse
(the default), the lower indices ofA
will be contracted with the site indices ofx
, ifTrue
the upper indices ofA
will be contracted with the site indices ofx
, which is like applyingA.T @ x
.inplace (bool, optional) – Whether to perform the gate operation inplace on this tensor network.
 Return type:
 gate(G, where, contract=False, tags=None, propagate_tags=False, info=None, inplace=False, **compress_opts)[source]¶
Apply a gate to this vector tensor network at sites
where
. This is essentially a wrapper aroundgate_inds()
apart fromwhere
can be specified as a list of sites, and tags can be optionally, intelligently propagated to the new gate tensor.\[ \psi \rangle \rightarrow G_\mathrm{where}  \psi \rangle\] Parameters:
G (array_ike) – The gate array to apply, should match or be factorable into the shape
(*phys_dims, *phys_dims)
.where (node or sequence[node]) – The sites to apply the gate to.
contract ({False, True, 'split', 'reducesplit', 'splitgate',) – ‘swapsplitgate’, ‘autosplitgate’}, optional How to apply the gate, see
gate_inds()
.tags (str or sequence of str, optional) – Tags to add to the new gate tensor.
propagate_tags ({False, True, 'register', 'sites'}, optional) –
Whether to propagate tags to the new gate tensor:
 False: no tags are propagated  True: all tags are propagated  'register': only site tags corresponding to ``where`` are added.  'sites': all site tags on the current sites are propgated, resulting in a lightcone like tagging.
info (None or dict, optional) – Used to store extra optional information such as the singular values if not absorbed.
inplace (bool, optional) – Whether to perform the gate operation inplace on the tensor network or not.
compress_opts – Supplied to
tensor_split()
for anycontract
methods that involve splitting. Ignored otherwise.
 Return type:
See also
TensorNetwork.gate_inds
 gate_simple_(G, where, gauges, renorm=True, smudge=1e12, power=1.0, **gate_opts)[source]¶
Apply a gate to this vector tensor network at sites
where
, using simple update style gauging of the tensors first, as supplied ingauges
. The new singular values for the bond are reinserted intogauges
. Parameters:
G (array_like) – The gate to be applied.
where (node or sequence[node]) – The sites to apply the gate to.
gauges (dict[str, array_like]) – The store of gauge bonds, the keys being indices and the values being the vectors. Only bonds present in this dictionary will be used.
renorm (bool, optional) – Whether to renormalise the singular after the gate is applied, before reinserting them into
gauges
.smudge (float, optional) – A small value to add to the gauges before multiplying them in and inverting them to avoid numerical issues.
power (float, optional) – The power to raise the singular values to before multiplying them in and inverting them.
gate_opts – Supplied to
gate_inds()
.
 make_reduced_density_matrix(where, allow_dangling=True, bra_ind_id='b{}', mangle_append='*', layer_tags=('KET', 'BRA'))[source]¶
Form the tensor network representation of the reduced density matrix, taking special care to handle potential hyper inner and outer indices.
 Parameters:
where (node or sequence[node]) – The sites to keep.
allow_dangling (bool, optional) – Whether to allow dangling indices in the resulting density matrix. These are nonphysical indices, that usually result from having cut a region of the tensor network.
bra_ind_id (str, optional) – The string format to use for the bra indices.
mangle_append (str, optional) – The string to append to indices that are not traced out.
layer_tags (tuple of str, optional) – The tags to apply to the ket and bra tensor network layers.
 local_expectation_cluster(G, where, normalized=True, max_distance=0, fillin=False, gauges=None, smudge=0.0, power=1.0, optimize='auto', max_bond=None, rehearse=False, **contract_opts)[source]¶
Approximately compute a single local expectation value of the gate
G
at siteswhere
, either treating the environment beyondmax_distance
as the identity, or using simple update style bond gauges as supplied ingauges
.This selects a local neighbourhood of tensors up to distance
max_distance
away fromwhere
, then traces over dangling bonds after potentially inserting the bond gauges, to form an approximate version of the reduced density matrix.\[\langle \psi  G  \psi \rangle \approx \frac{ \mathrm{Tr} [ G \tilde{\rho}_\mathrm{where} ] }{ \mathrm{Tr} [ \tilde{\rho}_\mathrm{where} ] }\]assuming
normalized==True
. Parameters:
G (array_like) – The gate to compute the expecation of.
where (node or sequence[node]) – The sites to compute the expectation at.
normalized (bool, optional) – Whether to locally normalize the result, i.e. divide by the expectation value of the identity.
max_distance (int, optional) – The maximum graph distance to include tensors neighboring
where
when computing the expectation. The default 0 means only the tensors at siteswhere
are used.fillin (bool or int, optional) – When selecting the local tensors, whether and how many times to ‘fillin’ corner tensors attached multiple times to the local region. On a lattice this fills in the corners. See
select_local()
.gauges (dict[str, array_like], optional) – The store of gauge bonds, the keys being indices and the values being the vectors. Only bonds present in this dictionary will be used.
optimize (str or PathOptimizer, optional) – The contraction path optimizer to use, when exactly contracting the local tensors.
max_bond (None or int, optional) – If specified, use compressed contraction.
rehearse ({False, 'tn', 'tree', True}, optional) –
Whether to perform the computations or not:
 False: perform the computation.  'tn': return the tensor networks of each local expectation, without running the path optimizer.  'tree': run the path optimizer and return the ``cotengra.ContractonTree`` for each local expectation.  True: run the path optimizer and return the ``PathInfo`` for each local expectation.
 Returns:
expectation
 Return type:
 compute_local_expectation_cluster(terms, *, max_distance=0, fillin=False, normalized=True, gauges=None, optimize='auto', max_bond=None, return_all=False, rehearse=False, executor=None, progbar=False, **contract_opts)[source]¶
Compute all local expectations of the given terms, either treating the environment beyond
max_distance
as the identity, or using simple update style bond gauges as supplied ingauges
.This selects a local neighbourhood of tensors up to distance
max_distance
away from each term’s sites, then traces over dangling bonds after potentially inserting the bond gauges, to form an approximate version of the reduced density matrix.\[\sum_\mathrm{i} \langle \psi  G_\mathrm{i}  \psi \rangle \approx \sum_\mathrm{i} \frac{ \mathrm{Tr} [ G_\mathrm{i} \tilde{\rho}_\mathrm{i} ] }{ \mathrm{Tr} [ \tilde{\rho}_\mathrm{i} ] }\]assuming
normalized==True
. Parameters:
terms (dict[node or (node, node), array_like]) – The terms to compute the expectation of, with keys being the sites and values being the local operators.
max_distance (int, optional) – The maximum graph distance to include tensors neighboring each term’s sites when computing the expectation. The default 0 means only the tensors at sites of each term are used.
fillin (bool or int, optional) – When selecting the local tensors, whether and how many times to ‘fillin’ corner tensors attached multiple times to the local region. On a lattice this fills in the corners. See
select_local()
.normalized (bool, optional) – Whether to locally normalize the result, i.e. divide by the expectation value of the identity. This implies that a different normalization factor is used for each term.
gauges (dict[str, array_like], optional) – The store of gauge bonds, the keys being indices and the values being the vectors. Only bonds present in this dictionary will be used.
optimize (str or PathOptimizer, optional) – The contraction path optimizer to use, when exactly contracting the local tensors.
max_bond (None or int, optional) – If specified, use compressed contraction.
return_all (bool, optional) – Whether to return all results, or just the summed expectation.
rehearse ({False, 'tn', 'tree', True}, optional) –
Whether to perform the computations or not:
 False: perform the computation.  'tn': return the tensor networks of each local expectation, without running the path optimizer.  'tree': run the path optimizer and return the ``cotengra.ContractonTree`` for each local expectation.  True: run the path optimizer and return the ``PathInfo`` for each local expectation.
executor (Executor, optional) – If supplied compute the terms in parallel using this executor.
progbar (bool, optional) – Whether to show a progress bar.
contract_opts – Supplied to
contract()
.
 Returns:
expecs – If
return_all==False
, return the summed expectation value of the given terms. Otherwise, return a dictionary mapping each term’s location to the expectation value. Return type:
 local_expectation_exact(G, where, optimize='autohq', normalized=True, rehearse=False, **contract_opts)[source]¶
Compute the local expectation of operator
G
at site(s)where
by exactly contracting the full overlap tensor network.
 compute_local_expectation_exact(terms, optimize='autohq', *, normalized=True, return_all=False, rehearse=False, executor=None, progbar=False, **contract_opts)[source]¶
Compute the local expectations of many operators, by exactly contracting the full overlap tensor network.
 Parameters:
terms (dict[node or (node, node), array_like]) – The terms to compute the expectation of, with keys being the sites and values being the local operators.
optimize (str or PathOptimizer, optional) – The contraction path optimizer to use, when exactly contracting the full tensor network.
normalized (bool, optional) – Whether to normalize the result.
return_all (bool, optional) – Whether to return all results, or just the summed expectation.
rehearse ({False, 'tn', 'tree', True}, optional) –
Whether to perform the computations or not:
 False: perform the computation.  'tn': return the tensor networks of each local expectation, without running the path optimizer.  'tree': run the path optimizer and return the ``cotengra.ContractonTree`` for each local expectation.  True: run the path optimizer and return the ``PathInfo`` for each local expectation.
executor (Executor, optional) – If supplied compute the terms in parallel using this executor.
progbar (bool, optional) – Whether to show a progress bar.
contract_opts – Supplied to
contract()
.
 Returns:
expecs – If
return_all==False
, return the summed expectation value of the given terms. Otherwise, return a dictionary mapping each term’s location to the expectation value. Return type:
 local_expectation_loop_expansion(G, where, loops=None, gauges=None, normalized=True, optimize='auto', intersect=False, use_all_starting_paths=False, info=None, progbar=False, **contract_opts)[source]¶
Compute the expectation of operator
G
at site(s)where
by expanding the expectation in terms of loops of tensors. Parameters:
G (array_like) – The operator to compute the expectation of.
where (node or sequence[node]) – The sites to compute the expectation at.
loops (None or sequence[NetworkPath], optional) – The loops to use. If an integer, all loops up to and including that length will be used if the loop passes through all sites in
where
. IfNone
the maximum loop length is set as the shortest loop found. If an explicit set of loops is given, only these loops are considered, but only if they pass through all sites inwhere
.intersect
is ignored.gauges (dict[str, array_like], optional) – The store of gauge bonds, the keys being indices and the values being the vectors. Only bonds present in this dictionary will be gauged.
normalized (bool or "local", optional) – Whether to normalize the result. If “local” each loop term is normalized separately. If
True
each term is normalized using a loop expansion estimate of the norm. IfFalse
no normalization is performed.optimize (str or PathOptimizer, optional) – The contraction path optimizer to use.
info (dict, optional) – A dictionary to store intermediate results in to avoid recomputing them. This is useful when computing various expectations with different sets of loops. This should only be reused when both the tensor network and gauges remain the same.
intersect (bool, optional) – If
loops
is not an explicit set of loops, whether to consider self intersecting loops in the search for loops passing throughwhere
.contract_opts – Supplied to
contract()
.
 Returns:
expec
 Return type:
scalar
 compute_local_expectation_loop_expansion(terms, loops=None, *, gauges=None, normalized=True, optimize='auto', info=None, intersect=False, return_all=False, executor=None, progbar=False, **contract_opts)[source]¶
 local_expectation_cluster_expansion(G, where, clusters=None, gauges=None, normalized=True, autocomplete=True, optimize='auto', info=None, **contract_opts)[source]¶
Compute the expectation of operator
G
at site(s)where
by expanding the expectation in terms of clusters of tensors. Parameters:
G (array_like) – The operator to compute the expectation of.
where (node or sequence[node]) – The sites to compute the expectation at.
clusters (None or sequence[sequence[node]], optional) – The clusters to use. If an integer, all cluster up to and including that size will be used if the cluster contains all sites in
where
. IfNone
the maximum cluster size is set as the smallest nontrivial cluster (2connected subgraph) found. If an explicit set of clusters is given, only these clusters are considered, but only if they contain all sites inwhere
.gauges (dict[str, array_like], optional) – The store of gauge bonds, the keys being indices and the values being the vectors. Only bonds present in this dictionary will be gauged.
normalized (bool or "local", optional) – Whether to normalize the result. If “local” each cluster term is normalized separately. If
True
each term is normalized using a loop expansion estimate of the norm. IfFalse
no normalization is performed.optimize (str or PathOptimizer, optional) – The contraction path optimizer to use.
info (dict, optional) – A dictionary to store intermediate results in to avoid recomputing them. This is useful when computing various expectations with different sets of loops. This should only be reused when both the tensor network and gauges remain the same.
contract_opts – Supplied to
contract()
.
 Returns:
expec
 Return type:
scalar
 norm_cluster_expansion(clusters=None, autocomplete=False, gauges=None, optimize='auto', **contract_opts)[source]¶
Compute the norm of this tensor network by expanding it in terms of clusters of tensors.
 compute_local_expectation_cluster_expansion(terms, clusters=None, *, gauges=None, normalized=True, autocomplete=True, optimize='auto', info=None, return_all=False, executor=None, progbar=False, **contract_opts)[source]¶
 partial_trace(keep, max_bond, optimize, flatten=True, reduce=False, normalized=True, symmetrized='auto', rehearse=False, method='contract_compressed', **contract_compressed_opts)[source]¶
Partially trace this tensor network state, keeping only the sites in
keep
, using compressed contraction. Parameters:
keep (iterable of hashable) – The sites to keep.
max_bond (int) – The maximum bond dimensions to use while compressed contracting.
optimize (str or PathOptimizer, optional) – The contraction path optimizer to use, should specifically generate contractions paths designed for compressed contraction.
flatten ({False, True, 'all'}, optional) – Whether to force ‘flattening’ (contracting all physical indices) of the tensor network before contraction, whilst this makes the TN generally more complex to contract, the accuracy is usually improved. If
'all'
also flatten the tensors inkeep
.reduce (bool, optional) – Whether to first ‘pull’ the physical indices off their respective tensors using QR reduction. Experimental.
normalized (bool, optional) – Whether to normalize the reduced density matrix at the end.
symmetrized ({'auto', True, False}, optional) – Whether to symmetrize the reduced density matrix at the end. This should be unecessary if
flatten
is set toTrue
.rehearse ({False, 'tn', 'tree', True}, optional) –
Whether to perform the computation or not:
 False: perform the computation.  'tn': return the tensor network without running the path optimizer.  'tree': run the path optimizer and return the ``cotengra.ContractonTree``..  True: run the path optimizer and return the ``PathInfo``.
contract_compressed_opts (dict, optional) – Additional keyword arguments to pass to
contract_compressed()
.
 Returns:
rho – The reduce density matrix of sites in
keep
. Return type:
array_like
 local_expectation(G, where, max_bond, optimize, flatten=True, normalized=True, symmetrized='auto', reduce=False, rehearse=False, **contract_compressed_opts)[source]¶
Compute the local expectation of operator
G
at site(s)where
by approximately contracting the full overlap tensor network. Parameters:
G (array_like) – The local operator to compute the expectation of.
where (node or sequence of nodes) – The sites to compute the expectation for.
max_bond (int) – The maximum bond dimensions to use while compressed contracting.
optimize (str or PathOptimizer, optional) – The contraction path optimizer to use, should specifically generate contractions paths designed for compressed contraction.
method ({'rho', 'rhoreduced'}, optional) – The method to use to compute the expectation value.
flatten (bool, optional) – Whether to force ‘flattening’ (contracting all physical indices) of the tensor network before contraction, whilst this makes the TN generally more complex to contract, the accuracy is usually much improved.
normalized (bool, optional) – If computing via partial_trace, whether to normalize the reduced density matrix at the end.
symmetrized ({'auto', True, False}, optional) – If computing via partial_trace, whether to symmetrize the reduced density matrix at the end. This should be unecessary if
flatten
is set toTrue
.rehearse ({False, 'tn', 'tree', True}, optional) –
Whether to perform the computation or not:
 False: perform the computation.  'tn': return the tensor network without running the path optimizer.  'tree': run the path optimizer and return the ``cotengra.ContractonTree``..  True: run the path optimizer and return the ``PathInfo``.
contract_compressed_opts (dict, optional) – Additional keyword arguments to pass to
contract_compressed()
.
 Returns:
expec
 Return type:
 compute_local_expectation(terms, max_bond, optimize, *, flatten=True, normalized=True, symmetrized='auto', reduce=False, return_all=False, rehearse=False, executor=None, progbar=False, **contract_compressed_opts)[source]¶
Compute the local expectations of many local operators, by approximately contracting the full overlap tensor network.
 Parameters:
terms (dict[node or (node, node), array_like]) – The terms to compute the expectation of, with keys being the sites and values being the local operators.
max_bond (int) – The maximum bond dimension to use during contraction.
optimize (str or PathOptimizer) – The compressed contraction path optimizer to use.
method ({'rho', 'rhoreduced'}, optional) –
The method to use to compute the expectation value.
’rho’: compute the expectation value via the reduced density matrix.
’rhoreduced’: compute the expectation value via the reduced density matrix, having reduced the physical indices onto the bonds first.
flatten (bool, optional) – Whether to force ‘flattening’ (contracting all physical indices) of the tensor network before contraction, whilst this makes the TN generally more complex to contract, the accuracy can often be much improved.
normalized (bool, optional) – Whether to locally normalize the result.
symmetrized ({'auto', True, False}, optional) – Whether to symmetrize the reduced density matrix at the end. This should be unecessary if
flatten
is set toTrue
.return_all (bool, optional) – Whether to return all results, or just the summed expectation. If
rehease is not False
, this is ignored and a dict is always returned.rehearse ({False, 'tn', 'tree', True}, optional) –
Whether to perform the computations or not:
 False: perform the computation.  'tn': return the tensor networks of each local expectation, without running the path optimizer.  'tree': run the path optimizer and return the ``cotengra.ContractonTree`` for each local expectation.  True: run the path optimizer and return the ``PathInfo`` for each local expectation.
executor (Executor, optional) – If supplied compute the terms in parallel using this executor.
progbar (bool, optional) – Whether to show a progress bar.
contract_compressed_opts – Supplied to
contract_compressed()
.
 Returns:
expecs – If
return_all==False
, return the summed expectation value of the given terms. Otherwise, return a dictionary mapping each term’s location to the expectation value. Return type:
 class quimb.tensor.tensor_arbgeom.TensorNetworkGenOperator(ts=(), *, virtual=False, check_collisions=True)[source]¶
Bases:
TensorNetworkGen
A tensor network which notionally has a single tensor and two outer indices per ‘site’, though these could be labelled arbitrarily and could also be linked in an arbitrary geometry by bonds. By convention, if converted to a dense matrix, the ‘upper’ indices would be on the left and the ‘lower’ indices on the right.
 _EXTRA_PROPS = ('_sites', '_site_tag_id', '_upper_ind_id', '_lower_ind_id')¶
 property upper_ind_id¶
The string specifier for the upper phyiscal indices.
 reindex_upper_sites(new_id, where=None, inplace=False)[source]¶
Modify the upper site indices for all or some tensors in this operator tensor network (without changing the
upper_ind_id
).
 property upper_inds¶
Return a tuple of all upper indices.
 property upper_inds_present¶
Return a tuple of all upper indices still present in the tensor network.
 property lower_ind_id¶
The string specifier for the lower phyiscal indices.
 reindex_lower_sites(new_id, where=None, inplace=False)[source]¶
Modify the lower site indices for all or some tensors in this operator tensor network (without changing the
lower_ind_id
).
 property lower_inds¶
Return a tuple of all lower indices.
 property lower_inds_present¶
Return a tuple of all lower indices still present in the tensor network.
 to_dense(*inds_seq, to_qarray=False, **contract_opts)[source]¶
Contract this tensor network ‘operator’ into a dense array.
 Parameters:
inds_seq (sequence of sequences of str) – How to group the site indices into the dense array. By default, use a single group ordered like
sites
, but only containing those sites which are still present.to_qarray (bool) – Whether to turn the dense array into a
qarray
, if the backend would otherwise be'numpy'
.contract_opts – Options to pass to
contract()
.
 Return type:
array
 gate_upper_with_op_lazy(A, transpose=False, inplace=False)[source]¶
Act lazily with the operator tensor network
A
, which should have matching structure, on this operator tensor network (B
), likeA @ B
. The returned tensor network will have the same structure as this one, but with the operator gated in lazily, i.e. uncontracted.\[B \rightarrow A B\]or (if
transpose=True
):\[B \rightarrow A^T B\] Parameters:
A (TensorNetworkGenOperator) – The operator tensor network to gate with, or apply to this tensor network.
transpose (bool, optional) – Whether to contract the lower or upper indices of
A
with the upper indices ofB
. IfFalse
(the default), the lower indices ofA
will be contracted with the upper indices ofB
, ifTrue
the upper indices ofA
will be contracted with the upper indices ofB
, which is like applying the transpose first.inplace (bool, optional) – Whether to perform the gate operation inplace on this tensor network.
 Return type:
 gate_lower_with_op_lazy(A, transpose=False, inplace=False)[source]¶
Act lazily ‘from the right’ with the operator tensor network
A
, which should have matching structure, on this operator tensor network (B
), likeB @ A
. The returned tensor network will have the same structure as this one, but with the operator gated in lazily, i.e. uncontracted.\[B \rightarrow B A\]or (if
transpose=True
):\[B \rightarrow B A^T\] Parameters:
A (TensorNetworkGenOperator) – The operator tensor network to gate with, or apply to this tensor network.
transpose (bool, optional) – Whether to contract the upper or lower indices of
A
with the lower indices of this TN. IfFalse
(the default), the upper indices ofA
will be contracted with the lower indices ofB
, ifTrue
the lower indices ofA
will be contracted with the lower indices of this TN, which is like applying the transpose first.inplace (bool, optional) – Whether to perform the gate operation inplace on this tensor network.
 Return type:
 gate_sandwich_with_op_lazy(A, inplace=False)[source]¶
Act lazily with the operator tensor network
A
, which should have matching structure, on this operator tensor network (B
), like \(B \rightarrow A B A^\dagger\). The returned tensor network will have the same structure as this one, but with the operator gated in lazily, i.e. uncontracted. Parameters:
A (TensorNetworkGenOperator) – The operator tensor network to gate with, or apply to this tensor network.
inplace (bool, optional) – Whether to perform the gate operation inplace on this tensor
 Return type:
 quimb.tensor.tensor_arbgeom._compute_expecs_maybe_in_parallel(fn, tn, terms, return_all=False, executor=None, progbar=False, **kwargs)[source]¶
Unified helper function for the various methods that compute many expectations, possibly in parallel, possibly with a progress bar.
 quimb.tensor.tensor_arbgeom._tn_local_expectation(tn, *args, **kwargs)[source]¶
Define as function for pickleability.
 quimb.tensor.tensor_arbgeom._tn_local_expectation_cluster(tn, *args, **kwargs)[source]¶
Define as function for pickleability.
 quimb.tensor.tensor_arbgeom._tn_local_expectation_exact(tn, *args, **kwargs)[source]¶
Define as function for pickleability.