quimb.experimental.cluster_update.cxu¶

Classes¶

`ClusterUpdateGen`	Simple update for arbitrary geometry hamiltonians, storing gauges
`GLoopExpandUpdateGen`	Simple update for arbitrary geometry hamiltonians, storing gauges

Functions¶

`compress_between_tids_bondenv_exact`(self, tida, tidb, ...)	Compress the bond between the two tensors identified by `tida` and
`compress_between_tids_bondenv_cluster`(self, tida, ...)	Compress the bond between the two tensors identified by `tida` and
`gate_cluster_`(self, G, where, max_bond[, cutoff, ...])	Apply a gate to this tensor network, using a single cluster around the
`compress_between_tids_bondenv_gloop_expand`(self, tida, ...)	Compress the bond between the two tensors identified by `tida` and
`gate_gloop_expand_`(self, G, where, max_bond[, cutoff, ...])	Apply a gate to a pair of tensors, then compress the bond between them

Module Contents¶

quimb.experimental.cluster_update.cxu.compress_between_tids_bondenv_exact(self: quimb.tensor.TensorNetwork, tida, tidb, max_bond, cutoff=0.0, absorb='both', max_iterations=100, tol=1e-10, solver='solve', solver_maxiter=4, prenormalize=False, condition=True, enforce_pos=True, pos_smudge=1e-10, init='svd', info=None, optimize='auto-hq', **contract_opts)¶

Compress the bond between the two tensors identified by tida and tidb exactly, by computing the full bond environment tensor and iteratively fitting compressed (low-rank) projectors to it.

Parameters:

tida (int) – The identifier of the first tensor.
tidb (int) – The identifier of the second tensor.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – The singular value cutoff to use.
absorb ({'both', 'left', 'right', None}, optional) – How to absorb the effective singular values into the tensors.
max_iterations (int, optional) – The maximum number of iterations to use when fitting the projectors.
tol (float, optional) – The target tolerance to reach when fitting the projectors.
solver ({'solve', None, str}, optional) – The solver to use inside the fitting loop. If None will use a custom conjugate gradient method. Else can be any of the iterative solvers supported by scipy.sparse.linalg such as ‘gmres’, ‘bicgstab’, etc.
solver_maxiter (int, optional) – The maximum number of iterations to use for the inner solver, i.e. per fitting step, only for iterative solver args.
prenormalize (bool, optional) – Whether to prenormalize the environment tensor such that its full contraction before compression is 1. Recommended for stability when the normalization does not matter.
condition (bool or "iso", optional) – Whether to condition the projectors after each fitting step. If True, their norms will be simply matched. If "iso", then they are gauged each time such that the previous tensor is isometric. Recommended for stability.
enforce_pos (bool, optional) – Whether to enforce the environment tensor to be positive semi-definite by symmetrizing and clipping negative eigenvalues. Recommended for stability.
pos_smudge (float, optional) – The value to clip negative eigenvalues to when enforcing positivity, relative to the largest eigenvalue.
init ({'svd', 'eigh', 'random', 'reduced'}, optional) –
How to initialize the compression projectors. The options are:
- ’svd’: use a truncated SVD of the environment tensor with the bra bond traced out.
- ’eigh’: use a similarity compression of the environment tensor with the bra bond traced out.
- ’random’: use random projectors.
- ’reduced’: split the environment into bra and ket parts, then canonize one half left and right to get the reduced factors.
info (dict, optional) – If provided, will store information about the fitting process here. The keys ‘iterations’ and ‘distance’ will contain the final number of iterations and distance reached respectively.
optimize (str, optional) – Contraction path optimizer to use when forming the bond environment.
contract_opts – Other contraction options to pass.

quimb.experimental.cluster_update.cxu.compress_between_tids_bondenv_cluster(self: quimb.tensor.TensorNetwork, tida, tidb, max_bond, cutoff=0.0, gauges=None, max_distance=1, mode='graphdistance', fillin=False, grow_from='all', max_iterations=100, tol=1e-10, solver='solve', solver_maxiter=4, prenormalize=False, condition=True, enforce_pos=True, pos_smudge=1e-10, init='svd', gauge_power=1.0, gauge_smudge=1e-10, optimize='auto-hq', info=None, **contract_opts)¶

Compress the bond between the two tensors identified by tida and tidb using a cluster of tensors around them to approximate the bond environment tensor.

Parameters:

tida (int) – The identifier of the first tensor.
tidb (int) – The identifier of the second tensor.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – The singular value cutoff to use, once the compressed projectors have been fitted.
gauges (dict[any, array], optional) – Gauges, in terms of singular value vectors, to absorb around the cluster.
max_distance (int, optional) – The maximum distance to the initial tagged region, or if using ‘loopunion’ mode, the maximum size of any loop.
mode ({'graphdistance', 'loopunion'}, optional) – How to select the local tensors, either by graph distance or by selecting the union of all loopy regions containing tids.
fillin (bool or int, optional) – Whether to fill in the local patch with additional tensors, or not. fillin tensors are those connected by two or more bonds to the original local patch, the process is repeated int(fillin) times.
grow_from ({"all", "any", "alldangle", "anydangle"}, optional) – If mode is ‘loopunion’, whether each loop should contain all of the initial tids, or just any of them (generating a larger region). If ‘alldangle’ or ‘anydangle’, then the individual loops can contain the target tids even if they are dangling.
max_iterations (int, optional) – The maximum number of iterations to use when fitting the projectors.
tol (float, optional) – The target tolerance to reach when fitting the projectors.
solver ({'solve', None, str}, optional) – The solver to use inside the fitting loop. If None will use a custom conjugate gradient method. Else can be any of the iterative solvers supported by scipy.sparse.linalg such as ‘gmres’, ‘bicgstab’, etc.
solver_maxiter (int, optional) – The maximum number of iterations to use for the inner solver, i.e. per fitting step, only for iterative solver args.
prenormalize (bool, optional) – Whether to prenormalize the environment tensor such that its full contraction before compression is 1. Recommended for stability when the normalization does not matter.
condition (bool or "iso", optional) – Whether to condition the projectors after each fitting step. If True, their norms will be simply matched. If "iso", then they are gauged each time such that the previous tensor is isometric. Recommended for stability.
enforce_pos (bool, optional) – Whether to enforce the environment tensor to be positive semi-definite by symmetrizing and clipping negative eigenvalues. Recommended for stability.
pos_smudge (float, optional) – The value to clip negative eigenvalues to when enforcing positivity, relative to the largest eigenvalue.
init ({'svd', 'eigh', 'random', 'reduced'}, optional) –
How to initialize the compression projectors. The options are:
- ’svd’: use a truncated SVD of the environment tensor with the bra bond traced out.
- ’eigh’: use a similarity compression of the environment tensor with the bra bond traced out.
- ’random’: use random projectors.
- ’reduced’: split the environment into bra and ket parts, then canonize one half left and right to get the reduced factors.
gauge_power (float, optional) – A power to raise the gauge vectors to when inserting.
gauge_smudge (float, optional) – A small value to add to the gauge vectors to avoid singularities when inserting.
optimize (str, optional) – Contraction path optimizer to use when forming the bond environment.
info (dict, optional) – If provided, will store information about the fitting process here. The keys ‘iterations’ and ‘distance’ will contain the final number of iterations and distance reached respectively.
contract_opts – Other contraction options to pass.

quimb.experimental.cluster_update.cxu.gate_cluster_(self: quimb.tensor.tnag.core.TensorNetworkGenVector, G, where, max_bond, cutoff=0.0, gauges=None, max_distance=1, mode='graphdistance', fillin=False, grow_from='all', max_iterations=100, tol=1e-10, solver='solve', solver_maxiter=4, prenormalize=False, condition=True, enforce_pos=True, pos_smudge=1e-10, init='svd', gauge_power=1.0, gauge_smudge=1e-10, equalize_norms=None, optimize='auto-hq', info=None, **contract_opts)¶

Apply a gate to this tensor network, using a single cluster around the target sites to then compress the increased bond dimension.

Parameters:

G (array) – The gate to apply.
where (sequence of hashable) – The site(s) to apply the gate to.
max_bond (int) – The maximum bond dimension to compress the bond to.
cutoff (float, optional) – The singular value cutoff to use, once the compressed projectors have been fitted.
gauges (dict[any, array], optional) – Gauges, in terms of singular value vectors, to absorb around the cluster.
max_distance (int, optional) – The maximum distance to the initial tagged region, or if using ‘loopunion’ mode, the maximum size of any loop.
mode ({'graphdistance', 'loopunion'}, optional) – How to select the local tensors, either by graph distance or by selecting the union of all loopy regions containing tids.
fillin (bool or int, optional) – Whether to fill in the local patch with additional tensors, or not. fillin tensors are those connected by two or more bonds to the original local patch, the process is repeated int(fillin) times.
grow_from ({"all", "any", "alldangle", "anydangle"}, optional) – If mode is ‘loopunion’, whether each loop should contain all of the initial tids, or just any of them (generating a larger region). If ‘alldangle’ or ‘anydangle’, then the individual loops can contain the target tids even if they are dangling.
max_iterations (int, optional) – The maximum number of iterations to use when fitting the projectors.
tol (float, optional) – The target tolerance to reach when fitting the projectors.
solver ({'solve', None, str}, optional) – The solver to use inside the fitting loop. If None will use a custom conjugate gradient method. Else can be any of the iterative solvers supported by scipy.sparse.linalg such as ‘gmres’, ‘bicgstab’, etc.
solver_maxiter (int, optional) – The maximum number of iterations to use for the inner solver, i.e. per fitting step, only for iterative solver args.
prenormalize (bool, optional) – Whether to prenormalize the environment tensor such that its full contraction before compression is 1. Recommended for stability when the normalization does not matter.
condition (bool or "iso", optional) – Whether to condition the projectors after each fitting step. If True, their norms will be simply matched. If "iso", then they are gauged each time such that the previous tensor is isometric. Recommended for stability.
enforce_pos (bool, optional) – Whether to enforce the environment tensor to be positive semi-definite by symmetrizing and clipping negative eigenvalues. Recommended for stability.
pos_smudge (float, optional) – The value to clip negative eigenvalues to when enforcing positivity, relative to the largest eigenvalue.
init ({'svd', 'eigh', 'random', 'reduced'}, optional) –
How to initialize the compression projectors. The options are:
- ’svd’: use a truncated SVD of the environment tensor with the bra bond traced out.
- ’eigh’: use a similarity compression of the environment tensor with the bra bond traced out.
- ’random’: use random projectors.
- ’reduced’: split the environment into bra and ket parts, then canonize one half left and right to get the reduced factors.
gauge_power (float, optional) – A power to raise the gauge vectors to when inserting.
gauge_smudge (float, optional) – A small value to add to the gauge vectors to avoid singularities when inserting.
equalize_norms (bool, optional) – Whether to equalize the norms of the two tensors after compression, stripping the exponent.
optimize (str, optional) – Contraction path optimizer to use when forming the bond environment.
info (dict, optional) – If provided, will store information about the fitting process here. The keys ‘iterations’ and ‘distance’ will contain the final number of iterations and distance reached respectively.
contract_opts – Other contraction options to pass.

class quimb.experimental.cluster_update.cxu.ClusterUpdateGen(psi0, ham, max_distance=1, mode='graphdistance', fillin=0, grow_from='all', gauge_power=1.0, **kwargs)¶

Bases: quimb.tensor.tnag.tebd.SimpleUpdateGen

Simple update for arbitrary geometry hamiltonians, storing gauges separately and using them and the cluster approximation to compute energies. Reference: https://arxiv.org/abs/0806.3719.

Parameters:

psi0 (TensorNetworkGenVector) – The initial state.
ham (LocalHamGen) – The local hamiltonian.
tau (float, optional) – The default time step to use.
D (int, optional) – The maximum bond dimension, by default the current maximum bond of psi0.
cutoff (float, optional) – The singular value cutoff to use when applying gates.
imag (bool, optional) – Whether to evolve in imaginary time (default) or real time.
gate_opts (dict, optional) – Other options to supply to the gate application method, quimb.tensor.tnag.core.TensorNetworkGenVector.gate_simple_().
ordering (None, str or callable, optional) – The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to quimb.tensor.tnag.tebd.LocalHamGen.get_auto_ordering(), a callable which returns an ordering when called, or a fixed sequence of coordinate pairs.
second_order_reflect (bool, optional) – Whether to use a second order Trotter decomposition by reflecting the ordering.
compute_energy_every (int, optional) – Compute the energy every this many steps.
compute_energy_final (bool, optional) – Whether to compute the energy at the end.
compute_energy_opts (dict, optional) – Options to supply to the energy computation method, quimb.tensor.tnag.core.TensorNetworkGenVector.compute_local_expectation_cluster().
compute_energy_fn (callable, optional) – A custom function to compute the energy, with signature fn(su: SimpleUpdateGen), where su is this instance.
compute_energy_per_site (bool, optional) – Whether to compute the energy per site.
tol (float, optional) – If not None, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value.
tol_energy_diff (float, optional) – If not None, stop when specifically the energy difference falls below this value.
equilibrate_every (int, optional) – Equilibrate the gauges every this many steps.
equilibrate_start (bool, optional) – Whether to equilibrate the gauges at the start, regardless of equilibrate_every.
equilibrate_opts (dict, optional) – Default options to supply to the gauge equilibration method, see quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple(). By default max_iterations is set to 100 and tol to 1e-3.
callback (callable, optional) – A function to call after each step, with signature fn(su: SimpleUpdateGen).
keep_best (bool, optional) – Whether to keep track of the best state and energy. If True, the best state found during evolution will be stored in the best attribute.
plot_every (int, optional) – Whether to plot the energy and energy difference every this many steps.
progbar (bool, optional) – Whether to show a progress bar during evolution.

state¶

The current state.

Type:: TensorNetworkGenVector

D¶

The maximum bond dimension.

Type:: int

n¶

The number of sweeps performed.

Type:: int

energy¶

The energy of the current state, computed only if necessary.

Type:: float

energies¶

The history of computed energies.

Type:: list[float]

energy_diffs¶

The history of energy differences.

Type:: list[float]

energy_ns¶

The iteration numbers at which energies were computed.

Type:: list[int]

taus¶

The time steps used at each energy computation.

Type:: list[float]

best¶

If keep_best is True, this dictionary will contain the best energy found during evolution under the key 'energy', the state which achieved this energy under the key 'state', and the iteration number under the key 'it'.

Type:: dict

equilibration_ns¶

The iteration numbers at which gauge equilibration was performed.

Type:: list[int]

equilibration_iterations¶

The number of iterations taken during each gauge equilibration.

Type:: list[int]

equilibration_max_sdiffs¶

The maximum singular value difference during each gauge equilibration.

Type:: list[float]

gauge_diffs¶

The history of maximum gauge differences after each sweep.

Type:: list[float]

See also

TEBDGen

max_fit_iterations¶

max_fit_distances¶

presweep(*args, **kwargs)¶: Perform any computations required before the sweep (and energy computation). For the basic update is nothing.

gate(U, where)¶: Application of a single gate G at where.

assemble_plot_data()¶

quimb.experimental.cluster_update.cxu.compress_between_tids_bondenv_gloop_expand(self: quimb.tensor.TensorNetwork, tida, tidb, max_bond, cutoff=0.0, gauges=None, gloops=None, autocomplete=True, grow_from='all', normalized=False, combine='sum', max_iterations=100, tol=1e-06, gauge_power=1.0, gauge_smudge=1e-06, prenormalize=False, condition=True, enforce_pos=True, pos_smudge=1e-06, solver='solve', solver_maxiter=4, init='svd', equalize_norms=None, optimize='auto-hq', info=None, **contract_opts)¶: Compress the bond between the two tensors identified by tida and tidb using a generalized loop expansion approximation of the bond environment tensor.

quimb.experimental.cluster_update.cxu.gate_gloop_expand_(self: quimb.tensor.tnag.core.TensorNetworkGenVector, G, where, max_bond, cutoff=0.0, gauges=None, gloops=None, autocomplete=True, grow_from='all', normalized=False, combine='sum', max_iterations=100, tol=1e-06, gauge_power=1.0, gauge_smudge=1e-06, prenormalize=False, condition=True, enforce_pos=True, pos_smudge=1e-06, solver='solve', solver_maxiter=4, equalize_norms=None, optimize='auto-hq', info=None, **contract_opts)¶

Apply a gate to a pair of tensors, then compress the bond between them using a generalized loop expansion approximation of the bond environment tensor.

Parameters:

G (array) – The gate to apply.
where (sequence of hashable) – The site(s) to apply the gate to.
max_bond (int) – The maximum bond dimension to compress the bond to.
cutoff (float, optional) – The singular value cutoff to use, once the compressed projectors have been fitted.
gauges (dict[any, array], optional) – If provided, the gauge tensors to use for each bond.
gloops (int, optional) – The maximum number of tensors to include in a single cluster.
max_iterations (int, optional) – The maximum number of iterations to use when fitting the projectors.
tol (float, optional) – The tolerance to use when fitting the projectors.

class quimb.experimental.cluster_update.cxu.GLoopExpandUpdateGen(psi0, ham, gloops=None, grow_from='all', normalized=False, combine='sum', enforce_pos=True, pos_smudge=1e-06, gauge_power=1.0, **kwargs)¶

Bases: quimb.tensor.tnag.tebd.SimpleUpdateGen

Simple update for arbitrary geometry hamiltonians, storing gauges separately and using them and the cluster approximation to compute energies. Reference: https://arxiv.org/abs/0806.3719.

Parameters:

psi0 (TensorNetworkGenVector) – The initial state.
ham (LocalHamGen) – The local hamiltonian.
tau (float, optional) – The default time step to use.
D (int, optional) – The maximum bond dimension, by default the current maximum bond of psi0.
cutoff (float, optional) – The singular value cutoff to use when applying gates.
imag (bool, optional) – Whether to evolve in imaginary time (default) or real time.
gate_opts (dict, optional) – Other options to supply to the gate application method, quimb.tensor.tnag.core.TensorNetworkGenVector.gate_simple_().
ordering (None, str or callable, optional) – The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to quimb.tensor.tnag.tebd.LocalHamGen.get_auto_ordering(), a callable which returns an ordering when called, or a fixed sequence of coordinate pairs.
second_order_reflect (bool, optional) – Whether to use a second order Trotter decomposition by reflecting the ordering.
compute_energy_every (int, optional) – Compute the energy every this many steps.
compute_energy_final (bool, optional) – Whether to compute the energy at the end.
compute_energy_opts (dict, optional) – Options to supply to the energy computation method, quimb.tensor.tnag.core.TensorNetworkGenVector.compute_local_expectation_cluster().
compute_energy_fn (callable, optional) – A custom function to compute the energy, with signature fn(su: SimpleUpdateGen), where su is this instance.
compute_energy_per_site (bool, optional) – Whether to compute the energy per site.
tol (float, optional) – If not None, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value.
tol_energy_diff (float, optional) – If not None, stop when specifically the energy difference falls below this value.
equilibrate_every (int, optional) – Equilibrate the gauges every this many steps.
equilibrate_start (bool, optional) – Whether to equilibrate the gauges at the start, regardless of equilibrate_every.
equilibrate_opts (dict, optional) – Default options to supply to the gauge equilibration method, see quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple(). By default max_iterations is set to 100 and tol to 1e-3.
callback (callable, optional) – A function to call after each step, with signature fn(su: SimpleUpdateGen).
keep_best (bool, optional) – Whether to keep track of the best state and energy. If True, the best state found during evolution will be stored in the best attribute.
plot_every (int, optional) – Whether to plot the energy and energy difference every this many steps.
progbar (bool, optional) – Whether to show a progress bar during evolution.