quimb.experimental.cluster_update.cxu ===================================== .. py:module:: quimb.experimental.cluster_update.cxu Classes ------- .. autoapisummary:: quimb.experimental.cluster_update.cxu.ClusterUpdateGen quimb.experimental.cluster_update.cxu.GLoopExpandUpdateGen Functions --------- .. autoapisummary:: quimb.experimental.cluster_update.cxu.compress_between_tids_bondenv_exact quimb.experimental.cluster_update.cxu.compress_between_tids_bondenv_cluster quimb.experimental.cluster_update.cxu.gate_cluster_ quimb.experimental.cluster_update.cxu.compress_between_tids_bondenv_gloop_expand quimb.experimental.cluster_update.cxu.gate_gloop_expand_ Module Contents --------------- .. py:function:: 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. :param tida: The identifier of the first tensor. :type tida: int :param tidb: The identifier of the second tensor. :type tidb: int :param max_bond: The maximum bond dimension to compress to. :type max_bond: int :param cutoff: The singular value cutoff to use. :type cutoff: float, optional :param absorb: How to absorb the effective singular values into the tensors. :type absorb: {'both', 'left', 'right', None}, optional :param max_iterations: The maximum number of iterations to use when fitting the projectors. :type max_iterations: int, optional :param tol: The target tolerance to reach when fitting the projectors. :type tol: float, optional :param solver: 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. :type solver: {'solve', None, str}, optional :param solver_maxiter: The maximum number of iterations to use for the *inner* solver, i.e. per fitting step, only for iterative `solver` args. :type solver_maxiter: int, optional :param prenormalize: Whether to prenormalize the environment tensor such that its full contraction before compression is 1. Recommended for stability when the normalization does not matter. :type prenormalize: bool, optional :param condition: 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. :type condition: bool or "iso", optional :param enforce_pos: Whether to enforce the environment tensor to be positive semi-definite by symmetrizing and clipping negative eigenvalues. Recommended for stability. :type enforce_pos: bool, optional :param pos_smudge: The value to clip negative eigenvalues to when enforcing positivity, relative to the largest eigenvalue. :type pos_smudge: float, optional :param init: 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. :type init: {'svd', 'eigh', 'random', 'reduced'}, optional :param info: 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. :type info: dict, optional :param optimize: Contraction path optimizer to use when forming the bond environment. :type optimize: str, optional :param contract_opts: Other contraction options to pass. .. py:function:: 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. :param tida: The identifier of the first tensor. :type tida: int :param tidb: The identifier of the second tensor. :type tidb: int :param max_bond: The maximum bond dimension to compress to. :type max_bond: int :param cutoff: The singular value cutoff to use, once the compressed projectors have been fitted. :type cutoff: float, optional :param gauges: Gauges, in terms of singular value vectors, to absorb around the cluster. :type gauges: dict[any, array], optional :param max_distance: The maximum distance to the initial tagged region, or if using 'loopunion' mode, the maximum size of any loop. :type max_distance: int, optional :param mode: How to select the local tensors, either by graph distance or by selecting the union of all loopy regions containing ``tids``. :type mode: {'graphdistance', 'loopunion'}, optional :param fillin: 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. :type fillin: bool or int, optional :param grow_from: 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. :type grow_from: {"all", "any", "alldangle", "anydangle"}, optional :param max_iterations: The maximum number of iterations to use when fitting the projectors. :type max_iterations: int, optional :param tol: The target tolerance to reach when fitting the projectors. :type tol: float, optional :param solver: 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. :type solver: {'solve', None, str}, optional :param solver_maxiter: The maximum number of iterations to use for the *inner* solver, i.e. per fitting step, only for iterative `solver` args. :type solver_maxiter: int, optional :param prenormalize: Whether to prenormalize the environment tensor such that its full contraction before compression is 1. Recommended for stability when the normalization does not matter. :type prenormalize: bool, optional :param condition: 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. :type condition: bool or "iso", optional :param enforce_pos: Whether to enforce the environment tensor to be positive semi-definite by symmetrizing and clipping negative eigenvalues. Recommended for stability. :type enforce_pos: bool, optional :param pos_smudge: The value to clip negative eigenvalues to when enforcing positivity, relative to the largest eigenvalue. :type pos_smudge: float, optional :param init: 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. :type init: {'svd', 'eigh', 'random', 'reduced'}, optional :param gauge_power: A power to raise the gauge vectors to when inserting. :type gauge_power: float, optional :param gauge_smudge: A small value to add to the gauge vectors to avoid singularities when inserting. :type gauge_smudge: float, optional :param optimize: Contraction path optimizer to use when forming the bond environment. :type optimize: str, optional :param info: 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. :type info: dict, optional :param contract_opts: Other contraction options to pass. .. py:function:: 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. :param G: The gate to apply. :type G: array :param where: The site(s) to apply the gate to. :type where: sequence of hashable :param max_bond: The maximum bond dimension to compress the bond to. :type max_bond: int :param cutoff: The singular value cutoff to use, once the compressed projectors have been fitted. :type cutoff: float, optional :param gauges: Gauges, in terms of singular value vectors, to absorb around the cluster. :type gauges: dict[any, array], optional :param max_distance: The maximum distance to the initial tagged region, or if using 'loopunion' mode, the maximum size of any loop. :type max_distance: int, optional :param mode: How to select the local tensors, either by graph distance or by selecting the union of all loopy regions containing ``tids``. :type mode: {'graphdistance', 'loopunion'}, optional :param fillin: 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. :type fillin: bool or int, optional :param grow_from: 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. :type grow_from: {"all", "any", "alldangle", "anydangle"}, optional :param max_iterations: The maximum number of iterations to use when fitting the projectors. :type max_iterations: int, optional :param tol: The target tolerance to reach when fitting the projectors. :type tol: float, optional :param solver: 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. :type solver: {'solve', None, str}, optional :param solver_maxiter: The maximum number of iterations to use for the *inner* solver, i.e. per fitting step, only for iterative `solver` args. :type solver_maxiter: int, optional :param prenormalize: Whether to prenormalize the environment tensor such that its full contraction before compression is 1. Recommended for stability when the normalization does not matter. :type prenormalize: bool, optional :param condition: 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. :type condition: bool or "iso", optional :param enforce_pos: Whether to enforce the environment tensor to be positive semi-definite by symmetrizing and clipping negative eigenvalues. Recommended for stability. :type enforce_pos: bool, optional :param pos_smudge: The value to clip negative eigenvalues to when enforcing positivity, relative to the largest eigenvalue. :type pos_smudge: float, optional :param init: 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. :type init: {'svd', 'eigh', 'random', 'reduced'}, optional :param gauge_power: A power to raise the gauge vectors to when inserting. :type gauge_power: float, optional :param gauge_smudge: A small value to add to the gauge vectors to avoid singularities when inserting. :type gauge_smudge: float, optional :param equalize_norms: Whether to equalize the norms of the two tensors after compression, stripping the exponent. :type equalize_norms: bool, optional :param optimize: Contraction path optimizer to use when forming the bond environment. :type optimize: str, optional :param info: 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. :type info: dict, optional :param contract_opts: Other contraction options to pass. .. py:class:: ClusterUpdateGen(psi0, ham, max_distance=1, mode='graphdistance', fillin=0, grow_from='all', gauge_power=1.0, **kwargs) Bases: :py:obj:`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. :param psi0: The initial state. :type psi0: TensorNetworkGenVector :param ham: The local hamiltonian. :type ham: LocalHamGen :param tau: The default time step to use. :type tau: float, optional :param D: The maximum bond dimension, by default the current maximum bond of ``psi0``. :type D: int, optional :param cutoff: The singular value cutoff to use when applying gates. :type cutoff: float, optional :param imag: Whether to evolve in imaginary time (default) or real time. :type imag: bool, optional :param gate_opts: Other options to supply to the gate application method, :meth:`quimb.tensor.tnag.core.TensorNetworkGenVector.gate_simple_`. :type gate_opts: dict, optional :param ordering: The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to :meth:`quimb.tensor.tnag.tebd.LocalHamGen.get_auto_ordering`, a callable which returns an ordering when called, or a fixed sequence of coordinate pairs. :type ordering: None, str or callable, optional :param second_order_reflect: Whether to use a second order Trotter decomposition by reflecting the ordering. :type second_order_reflect: bool, optional :param compute_energy_every: Compute the energy every this many steps. :type compute_energy_every: int, optional :param compute_energy_final: Whether to compute the energy at the end. :type compute_energy_final: bool, optional :param compute_energy_opts: Options to supply to the energy computation method, :func:`quimb.tensor.tnag.core.TensorNetworkGenVector.compute_local_expectation_cluster`. :type compute_energy_opts: dict, optional :param compute_energy_fn: A custom function to compute the energy, with signature ``fn(su: SimpleUpdateGen)``, where ``su`` is this instance. :type compute_energy_fn: callable, optional :param compute_energy_per_site: Whether to compute the energy per site. :type compute_energy_per_site: bool, optional :param tol: If not ``None``, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value. :type tol: float, optional :param tol_energy_diff: If not ``None``, stop when specifically the energy difference falls below this value. :type tol_energy_diff: float, optional :param equilibrate_every: Equilibrate the gauges every this many steps. :type equilibrate_every: int, optional :param equilibrate_start: Whether to equilibrate the gauges at the start, regardless of ``equilibrate_every``. :type equilibrate_start: bool, optional :param equilibrate_opts: Default options to supply to the gauge equilibration method, see :meth:`quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple`. By default `max_iterations` is set to 100 and `tol` to 1e-3. :type equilibrate_opts: dict, optional :param callback: A function to call after each step, with signature ``fn(su: SimpleUpdateGen)``. :type callback: callable, optional :param keep_best: 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. :type keep_best: bool, optional :param plot_every: Whether to plot the energy and energy difference every this many steps. :type plot_every: int, optional :param progbar: Whether to show a progress bar during evolution. :type progbar: bool, optional .. attribute:: state The current state. :type: TensorNetworkGenVector .. attribute:: D The maximum bond dimension. :type: int .. attribute:: n The number of sweeps performed. :type: int .. attribute:: energy The energy of the current state, computed only if necessary. :type: float .. attribute:: energies The history of computed energies. :type: list[float] .. attribute:: energy_diffs The history of energy differences. :type: list[float] .. attribute:: energy_ns The iteration numbers at which energies were computed. :type: list[int] .. attribute:: taus The time steps used at each energy computation. :type: list[float] .. attribute:: 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 .. attribute:: equilibration_ns The iteration numbers at which gauge equilibration was performed. :type: list[int] .. attribute:: equilibration_iterations The number of iterations taken during each gauge equilibration. :type: list[int] .. attribute:: equilibration_max_sdiffs The maximum singular value difference during each gauge equilibration. :type: list[float] .. attribute:: gauge_diffs The history of maximum gauge differences after each sweep. :type: list[float] .. seealso:: :py:obj:`TEBDGen` .. py:attribute:: max_fit_iterations .. py:attribute:: max_fit_distances .. py:method:: presweep(*args, **kwargs) Perform any computations required before the sweep (and energy computation). For the basic update is nothing. .. py:method:: gate(U, where) Application of a single gate ``G`` at ``where``. .. py:method:: assemble_plot_data() .. py:function:: 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. .. py:function:: 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. :param G: The gate to apply. :type G: array :param where: The site(s) to apply the gate to. :type where: sequence of hashable :param max_bond: The maximum bond dimension to compress the bond to. :type max_bond: int :param cutoff: The singular value cutoff to use, once the compressed projectors have been fitted. :type cutoff: float, optional :param gauges: If provided, the gauge tensors to use for each bond. :type gauges: dict[any, array], optional :param gloops: The maximum number of tensors to include in a single cluster. :type gloops: int, optional :param max_iterations: The maximum number of iterations to use when fitting the projectors. :type max_iterations: int, optional :param tol: The tolerance to use when fitting the projectors. :type tol: float, optional .. py:class:: 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: :py:obj:`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. :param psi0: The initial state. :type psi0: TensorNetworkGenVector :param ham: The local hamiltonian. :type ham: LocalHamGen :param tau: The default time step to use. :type tau: float, optional :param D: The maximum bond dimension, by default the current maximum bond of ``psi0``. :type D: int, optional :param cutoff: The singular value cutoff to use when applying gates. :type cutoff: float, optional :param imag: Whether to evolve in imaginary time (default) or real time. :type imag: bool, optional :param gate_opts: Other options to supply to the gate application method, :meth:`quimb.tensor.tnag.core.TensorNetworkGenVector.gate_simple_`. :type gate_opts: dict, optional :param ordering: The ordering of the terms to apply, by default this will be determined automatically. It can be a string to be supplied to :meth:`quimb.tensor.tnag.tebd.LocalHamGen.get_auto_ordering`, a callable which returns an ordering when called, or a fixed sequence of coordinate pairs. :type ordering: None, str or callable, optional :param second_order_reflect: Whether to use a second order Trotter decomposition by reflecting the ordering. :type second_order_reflect: bool, optional :param compute_energy_every: Compute the energy every this many steps. :type compute_energy_every: int, optional :param compute_energy_final: Whether to compute the energy at the end. :type compute_energy_final: bool, optional :param compute_energy_opts: Options to supply to the energy computation method, :func:`quimb.tensor.tnag.core.TensorNetworkGenVector.compute_local_expectation_cluster`. :type compute_energy_opts: dict, optional :param compute_energy_fn: A custom function to compute the energy, with signature ``fn(su: SimpleUpdateGen)``, where ``su`` is this instance. :type compute_energy_fn: callable, optional :param compute_energy_per_site: Whether to compute the energy per site. :type compute_energy_per_site: bool, optional :param tol: If not ``None``, stop when either energy difference falls below this value, or maximum singluar value changes fall below this value. :type tol: float, optional :param tol_energy_diff: If not ``None``, stop when specifically the energy difference falls below this value. :type tol_energy_diff: float, optional :param equilibrate_every: Equilibrate the gauges every this many steps. :type equilibrate_every: int, optional :param equilibrate_start: Whether to equilibrate the gauges at the start, regardless of ``equilibrate_every``. :type equilibrate_start: bool, optional :param equilibrate_opts: Default options to supply to the gauge equilibration method, see :meth:`quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple`. By default `max_iterations` is set to 100 and `tol` to 1e-3. :type equilibrate_opts: dict, optional :param callback: A function to call after each step, with signature ``fn(su: SimpleUpdateGen)``. :type callback: callable, optional :param keep_best: 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. :type keep_best: bool, optional :param plot_every: Whether to plot the energy and energy difference every this many steps. :type plot_every: int, optional :param progbar: Whether to show a progress bar during evolution. :type progbar: bool, optional .. attribute:: state The current state. :type: TensorNetworkGenVector .. attribute:: D The maximum bond dimension. :type: int .. attribute:: n The number of sweeps performed. :type: int .. attribute:: energy The energy of the current state, computed only if necessary. :type: float .. attribute:: energies The history of computed energies. :type: list[float] .. attribute:: energy_diffs The history of energy differences. :type: list[float] .. attribute:: energy_ns The iteration numbers at which energies were computed. :type: list[int] .. attribute:: taus The time steps used at each energy computation. :type: list[float] .. attribute:: 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 .. attribute:: equilibration_ns The iteration numbers at which gauge equilibration was performed. :type: list[int] .. attribute:: equilibration_iterations The number of iterations taken during each gauge equilibration. :type: list[int] .. attribute:: equilibration_max_sdiffs The maximum singular value difference during each gauge equilibration. :type: list[float] .. attribute:: gauge_diffs The history of maximum gauge differences after each sweep. :type: list[float] .. seealso:: :py:obj:`TEBDGen` .. py:attribute:: max_fit_iterations .. py:attribute:: max_fit_distances .. py:method:: presweep(*args, **kwargs) Perform any computations required before the sweep (and energy computation). For the basic update is nothing. .. py:method:: gate(U, where) Application of a single gate ``G`` at ``where``. .. py:method:: assemble_plot_data()