quimb.tensor.belief_propagation.d2bp¶

Classes¶

D2BP

Dense (as in one tensor per site) 2-norm (as in for wavefunctions and

Functions¶

`_parse_global_gloops`(tn[, gloops])
`contract_d2bp`(tn, *[, messages, output_inds, ...])	Estimate the norm squared of `tn` using dense 2-norm belief
`compress_d2bp`(tn, max_bond[, cutoff, cutoff_mode, ...])	Compress the tensor network `tn` using dense 2-norm belief
`sample_d2bp`(tn[, output_inds, messages, ...])	Sample a configuration from `tn` using dense 2-norm belief

Module Contents¶

quimb.tensor.belief_propagation.d2bp._parse_global_gloops(tn, gloops=None)¶

class quimb.tensor.belief_propagation.d2bp.D2BP(tn, *, messages=None, output_inds=None, optimize='auto-hq', damping=0.0, update='sequential', normalize=None, distance=None, local_convergence=True, contract_every=None, inplace=False, **contract_opts)¶

Bases: quimb.tensor.belief_propagation.bp_common.BeliefPropagationCommon

Dense (as in one tensor per site) 2-norm (as in for wavefunctions and operators) belief propagation. Allows messages reuse. This version assumes no hyper indices (i.e. a standard PEPS like tensor network).

Potential use cases for D2BP and a PEPS like tensor network are:

globally compressing it from bond dimension D to D'

eagerly applying gates and locally compressing back to D

sampling configurations

estimating the norm of the tensor network

Parameters:

tn (TensorNetwork) – The tensor network to form the 2-norm of and run BP on.
messages (dict[(str, int), array_like], optional) – The initial messages to use, effectively defaults to all ones if not specified.
output_inds (set[str], optional) – The indices to consider as output (dangling) indices of the tn. Computed automatically if not specified.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the messages.
damping (float or callable, optional) – The damping factor to apply to messages. This simply mixes some part of the old message into the new one, with the final message being damping * old + (1 - damping) * new. This makes convergence more reliable but slower.
update ({'sequential', 'parallel'}, optional) – Whether to update messages sequentially (newly computed messages are immediately used for other updates in the same iteration round) or in parallel (all messages are comptued using messages from the previous round only). Sequential generally helps convergence but parallel can possibly converge to differnt solutions.
normalize ({'L1', 'L2', 'L2phased', 'Linf', callable}, optional) – How to normalize messages after each update. If None choose automatically. If a callable, it should take a message and return the normalized message. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phase of the message, by default used for complex dtypes.
distance ({'L1', 'L2', 'L2phased', 'Linf', 'cosine', callable}, optional) – How to compute the distance between messages to check for convergence. If None choose automatically. If a callable, it should take two messages and return the distance. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’, or ‘cosine’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phases of the messages, by default used for complex dtypes if phased normalization is not already being used.
local_convergence (bool, optional) – Whether to allow messages to locally converge - i.e. if all their input messages have converged then stop updating them.
contract_every (int, optional) – If not None, ‘contract’ (via BP) the tensor network every contract_every iterations. The resulting values are stored in zvals at corresponding points zval_its.
inplace (bool, optional) – Whether to perform any operations inplace on the input tensor network.
contract_opts – Other options supplied to cotengra.array_contract.

contract_opts¶

local_convergence = True¶

touch_map¶

touched¶

exprs¶

build_expr(ix)¶

update_touched_from_tids(*tids)¶: Specify that the messages for the given tids have changed.

update_touched_from_tags(tags, which='any')¶: Specify that the messages for the messages touching tags have changed.

update_touched_from_inds(inds, which='any')¶: Specify that the messages for the messages touching inds have changed.

iterate(tol=5e-06)¶: Perform a single iteration of dense 2-norm belief propagation.

compute_marginal(ind)¶: Compute the marginal for the index ind.

normalize_message_pairs()¶: Normalize a pair of messages such that <mi|mj> = 1 and <mi|mi> = <mj|mj> (but in general != 1).

local_tensor_contract(tid)¶: Contract the local region of the tensor at tid.

normalize_tensors(strip_exponent=True)¶: Normalize the tensors in the tensor network such that their 2-norm is 1. If strip_exponent is True then accrue the phase and exponent (log10) into the sign and exponent attributes of the D2BP object (the default), contract methods can then reinsert these factors when returning the final result.

contract(strip_exponent=False, check_zero=True)¶

Estimate the total contraction, i.e. the 2-norm.

Parameters:: strip_exponent (bool, optional) – Whether to strip the exponent from the final result. If True then the returned result is (mantissa, exponent).
Return type:: scalar or (scalar, float)

get_cluster_excited(tids=None, partial_trace_map=(), exclude=())¶

Get the local norm tensor network for tids with BP messages inserted on the boundary and excitation projectors inserted on the inner bonds. See arxiv.org/abs/2409.03108 for more details.

Parameters:

tids (iterable of hashable) – The tensor ids to include in the cluster.
partial_trace_map (dict[str, str], optional) – A remapping of ket indices to bra indices to perform an effective partial trace.
exclude (iterable of str, optional) – A set of bond indices to exclude from inserting excitation projectors on, e.g. when forming a reduced density matrix.

Return type:

TensorNetwork

contract_loop_series_expansion(gloops=None, multi_excitation_correct=True, tol_correction=1e-12, maxiter_correction=100, strip_exponent=False, optimize='auto-hq', **contract_opts)¶

Contract the norm of the tensor network using the same procedure as in https://arxiv.org/abs/2409.03108 - “Loop Series Expansions for Tensor Networks”.

Parameters:

gloops (int or iterable of tuples, optional) – The gloop sizes to use. If an integer, then generate all gloop sizes up to this size. If a tuple, then use these gloops.
multi_excitation_correct (bool, optional) – Whether to use the multi-excitation correction. If True, then the free energy is refined iteratively until self consistent.
tol_correction (float, optional) – The tolerance for the multi-excitation correction.
maxiter_correction (int, optional) – The maximum number of iterations for the multi-excitation correction.
strip_exponent (bool, optional) – Whether to strip the exponent from the final result. If True then the returned result is (mantissa, exponent).
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the messages.
contract_opts – Other options supplied to TensorNetwork.contract.

partial_trace_loop_series_expansion(where, gloops=None, normalized=True, grow_from='alldangle', strict_size=True, multi_excitation_correct=True, optimize='auto-hq', **contract_opts)¶

Compute the reduced density matrix for the sites specified by where using the loop series expansion method from https://arxiv.org/abs/2409.03108 - “Loop Series Expansions for Tensor Networks”.

Parameters:

where (sequence[hashable]) – The sites to from the reduced density matrix of.
gloops (int or iterable of tuples, optional) – The generalized loops to use, or an integer to automatically generate all up to a certain size. If none use the smallest non- trivial size.
normalized (bool, optional) – Whether to normalize the final density matrix.
grow_from ({'alldangle', 'all', 'any'}, optional) –
How to grow the generalized loops from the specified where:
- ’alldangle’: clusters up to max size, where target sites are allowed to dangle.
- ’all’: clusters where loop, up to max size, has to include all target sites.
- ’any’: clusters where loop, up to max size, can include any of the target sites. Remaining target sites are added as extras.
By default ‘alldangle’.
strict_size (bool, optional) – Whether to enforce the maximum size of the generalized loops, only relevant for grow_from=”any”.
multi_excitation_correct (bool, optional) – Whether to use the multi-excitation correction. If True, then the free energy is refined iteratively until self consistent.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the messages.
contract_opts – Other options supplied to TensorNetwork.contract.

contract_gloop_expand(gloops=None, autocomplete=True, optimize='auto-hq', strip_exponent=False, check_zero=True, info=None, progbar=False, **contract_opts)¶

compress(max_bond, cutoff=0.0, cutoff_mode=4, renorm=0, inplace=False)¶: Compress the initial tensor network using the current messages.

gauge_insert(tn, smudge=1e-12)¶

Insert the sqrt of messages on the boundary of a part of the main BP TN.

Parameters:

tn (TensorNetwork) – The tensor network to insert the messages into.
smudge (float, optional) – Smudge factor to avoid numerical issues, the eigenvalues of the messages are clipped to be at least the largest eigenvalue times this factor.

Returns:

The sequence of tensors, indices and inverse gauges to apply to reverse the gauges applied.

Return type:

list[tuple[Tensor, str, array_like]]

gauge_temp(tn, ungauge_outer=True)¶

Context manager to temporarily gauge a tensor network, presumably a subnetwork of the main BP network, using the current messages, and then un-gauge it afterwards.

Parameters:

tn (TensorNetwork) – The tensor network to gauge.
ungauge_outer (bool, optional) – Whether to un-gauge the outer indices of the tensor network.

gate_(G, where, max_bond=None, cutoff=0.0, cutoff_mode='rsum2', renorm=0, tn=None, **gate_opts)¶: Apply a gate to the tensor network at the specified sites, using the current messages to gauge the tensors.

get_cluster_norm(tids, partial_trace_map=())¶

Get the local norm tensor network for tids with BP messages inserted on the boundary. Optionally open some physical indices up to perform an effective partial trace.

Parameters:

tids (iterable of hashable) – The tensor ids to include in the cluster.
partial_trace_map (dict[str, str], optional) – A remapping of ket indices to bra indices to perform an effective partial trace.

Return type:

TensorNetwork

partial_trace(where, normalized=True, tids_region=None, get='matrix', bra_ind_id=None, optimize='auto-hq', **contract_opts)¶

Get the reduced density matrix for the sites specified by where, with the remaining network approximated by messages on the boundary.

Parameters:

where (sequence[hashable]) – The sites to from the reduced density matrix of.
get ({'tn', 'tensor', 'array', 'matrix'}, optional) – The type of object to return. If ‘tn’, return the uncontracted tensor network object. If ‘tensor’, return the labelled density operator as a Tensor. If ‘array’, return the unfused raw array with 2 * len(where) dimensions. If ‘matrix’, fuse the ket and bra indices and return this 2D matrix.
bra_ind_id (str, optional) – If get="tn", how to label the bra indices. If None, use the default based on the current site_ind_id.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the tensor network.
contract_opts – Other options supplied to TensorNetwork.contract.

Return type:

TensorNetwork or Tensor or array

partial_trace_gloop_expand(where, gloops=None, combine='sum', normalized=True, grow_from='alldangle', strict_size=True, optimize='auto-hq', **contract_opts)¶

Compute a reduced density matrix for the sites specified by where using the generalized loop cluster expansion.

Parameters:

where (sequence[hashable]) – The sites to from the reduced density matrix of.
gloops (int or iterable of tuples, optional) – The generalized loops to use, or an integer to automatically generate all up to a certain size. If none use the smallest non- trivial size.
combine ({'sum', 'prod'}, optional) – How to combine the contributions from each generalized loop. If ‘sum’, use coefficient weighted addition. If ‘prod’, use power weighted multiplication.
normalized (bool or {"local", "separate"}, optional) – Whether to normalize the density matrix. If True or “local”, normalize each cluster density matrix by its trace. If “separate”, normalize the final density matrix by its trace (usually less accurate). If False, do not normalize.
grow_from ({'alldangle', 'all', 'any'}, optional) –
How to grow the generalized loops from the specified where:
- ’alldangle’: clusters up to max size, where target sites are allowed to dangle.
- ’all’: clusters where loop, up to max size, has to include all target sites.
- ’any’: clusters where loop, up to max size, can include any of the target sites. Remaining target sites are added as extras.
By default ‘alldangle’.
strict_size (bool, optional) – Whether to enforce the maximum size of the generalized loops, only relevant for grow_from=”any”.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the tensor network.
contract_opts – Other options supplied to TensorNetwork.contract.

quimb.tensor.belief_propagation.d2bp.contract_d2bp(tn, *, messages=None, output_inds=None, max_iterations=1000, tol=5e-06, damping=0.0, diis=False, update='sequential', normalize=None, distance=None, tol_abs=None, tol_rolling_diff=None, local_convergence=True, optimize='auto-hq', strip_exponent=False, check_zero=True, info=None, progbar=False, **contract_opts)¶

Estimate the norm squared of tn using dense 2-norm belief propagation (no hyper indices).

Parameters:

tn (TensorNetwork) – The tensor network to form the 2-norm of and run BP on.
messages (dict[(str, int), array_like], optional) – The initial messages to use, effectively defaults to all ones if not specified.
output_inds (set[str], optional) – The indices to consider as output (dangling) indices of the tn. Computed automatically if not specified.
max_iterations (int, optional) – The maximum number of iterations to perform.
tol (float, optional) – The convergence tolerance for messages.
damping (float, optional) – The damping parameter to use, defaults to no damping.
diis (bool or dict, optional) – Whether to use direct inversion in the iterative subspace to help converge the messages by extrapolating to low error guesses. If a dict, should contain options for the DIIS algorithm. The relevant options are {max_history, beta, rcond}.
update ({'sequential', 'parallel'}, optional) – Whether to update messages sequentially or in parallel.
normalize ({'L1', 'L2', 'L2phased', 'Linf', callable}, optional) – How to normalize messages after each update. If None choose automatically. If a callable, it should take a message and return the normalized message. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phase of the message, by default used for complex dtypes.
distance ({'L1', 'L2', 'L2phased', 'Linf', 'cosine', callable}, optional) – How to compute the distance between messages to check for convergence. If None choose automatically. If a callable, it should take two messages and return the distance. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’, or ‘cosine’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phases of the messages, by default used for complex dtypes if phased normalization is not already being used.
tol_abs (float, optional) – The absolute convergence tolerance for maximum message update distance, if not given then taken as tol.
tol_rolling_diff (float, optional) – The rolling mean convergence tolerance for maximum message update distance, if not given then taken as tol. This is used to stop running when the messages are just bouncing around the same level, without any overall upward or downward trends, roughly speaking.
local_convergence (bool, optional) – Whether to allow messages to locally converge - i.e. if all their input messages have converged then stop updating them.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the messages.
strip_exponent (bool, optional) – Whether to return the mantissa and exponent separately.
check_zero (bool, optional) – Whether to check for zero values and return zero early.
info (dict, optional) – If supplied, the following information will be added to it: converged (bool), iterations (int), max_mdiff (float), rolling_abs_mean_diff (float).
progbar (bool, optional) – Whether to show a progress bar.
contract_opts – Other options supplied to cotengra.array_contract.

Return type:

scalar or (scalar, float)

quimb.tensor.belief_propagation.d2bp.compress_d2bp(tn, max_bond, cutoff=0.0, cutoff_mode='rsum2', renorm=0, messages=None, output_inds=None, max_iterations=1000, tol=5e-06, damping=0.0, diis=False, update='sequential', normalize=None, distance=None, tol_abs=None, tol_rolling_diff=None, local_convergence=True, optimize='auto-hq', inplace=False, info=None, progbar=False, **contract_opts)¶

Compress the tensor network tn using dense 2-norm belief propagation.

Parameters:

tn (TensorNetwork) – The tensor network to form the 2-norm of, run BP on and then compress.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – The cutoff to use when compressing.
cutoff_mode (int, optional) – The cutoff mode to use when compressing.
renorm (float, optional) – Whether to renormalize the singular values when compressing.
messages (dict[(str, int), array_like], optional) – The initial messages to use, effectively defaults to all ones if not specified.
output_inds (set[str], optional) – The indices to consider as output (dangling) indices of the tn. Computed automatically if not specified.
max_iterations (int, optional) – The maximum number of iterations to perform.
tol (float, optional) – The convergence tolerance for messages.
damping (float, optional) – The damping parameter to use, defaults to no damping.
diis (bool or dict, optional) – Whether to use direct inversion in the iterative subspace to help converge the messages by extrapolating to low error guesses. If a dict, should contain options for the DIIS algorithm. The relevant options are {max_history, beta, rcond}.
update ({'sequential', 'parallel'}, optional) – Whether to update messages sequentially or in parallel.
normalize ({'L1', 'L2', 'L2phased', 'Linf', callable}, optional) – How to normalize messages after each update. If None choose automatically. If a callable, it should take a message and return the normalized message. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phase of the message, by default used for complex dtypes.
distance ({'L1', 'L2', 'L2phased', 'Linf', 'cosine', callable}, optional) – How to compute the distance between messages to check for convergence. If None choose automatically. If a callable, it should take two messages and return the distance. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’, or ‘cosine’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phases of the messages, by default used for complex dtypes if phased normalization is not already being used.
tol_abs (float, optional) – The absolute convergence tolerance for maximum message update distance, if not given then taken as tol.
tol_rolling_diff (float, optional) – The rolling mean convergence tolerance for maximum message update distance, if not given then taken as tol. This is used to stop running when the messages are just bouncing around the same level, without any overall upward or downward trends, roughly speaking.
local_convergence (bool, optional) – Whether to allow messages to locally converge - i.e. if all their input messages have converged then stop updating them.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the messages.
inplace (bool, optional) – Whether to perform the compression inplace.
info (dict, optional) – If specified, update this dictionary with information about the belief propagation run.
progbar (bool, optional) – Whether to show a progress bar.
contract_opts – Other options supplied to cotengra.array_contract.

Return type:

TensorNetwork

quimb.tensor.belief_propagation.d2bp.sample_d2bp(tn, output_inds=None, messages=None, max_iterations=100, tol=0.01, bias=None, seed=None, optimize='auto-hq', damping=0.0, diis=False, update='sequential', normalize=None, distance=None, tol_abs=None, tol_rolling_diff=None, local_convergence=True, progbar=False, **contract_opts)¶

Sample a configuration from tn using dense 2-norm belief propagation.

Parameters:

tn (TensorNetwork) – The tensor network to sample from.
output_inds (set[str], optional) – Which indices to sample.
messages (dict[(str, int), array_like], optional) – The initial messages to use, effectively defaults to all ones if not specified.
max_iterations (int, optional) – The maximum number of iterations to perform, per marginal.
tol (float, optional) – The convergence tolerance for messages.
bias (float, optional) – Bias the sampling towards more locally likely bit-strings. This is done by raising the probability of each bit-string to this power.
seed (int, optional) – A random seed for reproducibility.
optimize (str or PathOptimizer, optional) – The path optimizer to use when contracting the messages.
damping (float, optional) – The damping parameter to use, defaults to no damping.
diis (bool or dict, optional) – Whether to use direct inversion in the iterative subspace to help converge the messages by extrapolating to low error guesses. If a dict, should contain options for the DIIS algorithm. The relevant options are {max_history, beta, rcond}.
update ({'sequential', 'parallel'}, optional) – Whether to update messages sequentially or in parallel.
normalize ({'L1', 'L2', 'L2phased', 'Linf', callable}, optional) – How to normalize messages after each update. If None choose automatically. If a callable, it should take a message and return the normalized message. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phase of the message, by default used for complex dtypes.
distance ({'L1', 'L2', 'L2phased', 'Linf', 'cosine', callable}, optional) – How to compute the distance between messages to check for convergence. If None choose automatically. If a callable, it should take two messages and return the distance. If a string, it should be one of ‘L1’, ‘L2’, ‘L2phased’, ‘Linf’, or ‘cosine’ for the corresponding norms. ‘L2phased’ is like ‘L2’ but also normalizes the phases of the messages, by default used for complex dtypes if phased normalization is not already being used.
tol_abs (float, optional) – The absolute convergence tolerance for maximum message update distance, if not given then taken as tol.
tol_rolling_diff (float, optional) – The rolling mean convergence tolerance for maximum message update distance, if not given then taken as tol. This is used to stop running when the messages are just bouncing around the same level, without any overall upward or downward trends, roughly speaking.
local_convergence (bool, optional) – Whether to allow messages to locally converge - i.e. if all their input messages have converged then stop updating them.
progbar (bool, optional) – Whether to show a progress bar.
contract_opts – Other options supplied to cotengra.array_contract.

Returns:

config (dict[str, int]) – The sampled configuration, a mapping of output indices to values.
tn_config (TensorNetwork) – The tensor network with the sampled configuration applied.
omega (float) – The BP probability of the sampled configuration.