quimb.tensor.circuit.peps ========================= .. py:module:: quimb.tensor.circuit.peps .. autoapi-nested-parse:: PEPS simple-update circuit simulator. Classes ------- .. autoapisummary:: quimb.tensor.circuit.peps.CircuitPEPSSimpleUpdate Module Contents --------------- .. py:class:: CircuitPEPSSimpleUpdate(N=None, *, edges=None, gates=None, psi0=None, max_bond=None, cutoff=1e-10, renorm=False, gauge_smudge=1e-12, equilibrate_every=None, equilibrate_opts=None, gate_opts=None, dtype=None, to_backend=None, convert_eager=True, **circuit_opts) Bases: :py:obj:`quimb.tensor.circuit.simple_update.CircuitSimpleUpdate` Quantum circuit simulation keeping the state as a generic tensor network (a "PEPS" defined by an arbitrary graph of ``edges``) and applying gates with the simple update rule. The state always keeps a single tensor per site, with bonds only along the supplied edges; two-qubit gates are only supported on those edges. Bond singular values are tracked as Vidal-style gauges, which makes gate application and the computation of local expectations cheap and approximate. This is useful for circuits on lattices that build up more than 1D worth of entanglement, where an exact or MPS simulation is intractable but a truncated, gauged tensor network state is a good approximation. :param N: The number of qubits in the circuit. If not given it is inferred from the geometry. Supply it to pad the geometry up to ``N`` sites, including any that have no edges. :type N: int, optional :param edges: The edges defining the geometry of the PEPS. A bond is placed between each pair of sites, and two-qubit gates are only supported on these edges. Every site appearing in ``edges`` is included. If not given the geometry is taken from ``gates`` or ``psi0`` instead. :type edges: sequence[tuple[int, int]], optional :param gates: If ``edges`` is not given, infer the geometry from the two-qubit gates in this sequence. The gates are only inspected here, not applied, so you still pass them to :meth:`apply_gates` afterwards. :type gates: sequence, optional :param psi0: Supply the initial state directly instead of starting from the ``|00...0>`` product state. If ``edges`` is not given the geometry is read from the bonds of this state, and the bond gauges are seeded from it. Only a single seeding sweep is performed; unlike imaginary time simple update the gauge matters immediately, so for an arbitrary ``psi0`` you may want to call :meth:`equilibrate` once before applying gates. :type psi0: TensorNetworkGenVector, optional :param max_bond: The maximum bond dimension to truncate to when applying gates. :type max_bond: int, optional :param cutoff: The singular value cutoff to use when truncating after applying gates. :type cutoff: float, optional :param renorm: Whether to renormalize the singular values of a bond after each gate. The default ``False`` tracks the norm of the state rather than forcing it to one, which is the sensible choice for real time and general circuit dynamics. Set ``True`` to instead keep the state normalized after every gate, e.g. for the near-identity gates of imaginary time evolution. :type renorm: bool, optional :param gauge_smudge: Small value, relative to the largest gauge value, added before the gauges are multiplied in and inverted. :type gauge_smudge: float, optional :param equilibrate_every: If given, automatically call :meth:`equilibrate` after every this many gates have been applied. :type equilibrate_every: int, optional :param equilibrate_opts: Default options forwarded to :meth:`equilibrate`. :type equilibrate_opts: dict, optional :param gate_opts: Default options to pass to ``gate_simple_`` such as ``max_bond`` and ``cutoff``. :type gate_opts: dict, optional :param dtype: If given, ensure the state tensors are cast to this data type. :type dtype: str, optional :param to_backend: If given, apply this function to the state tensors to convert them to a particular array backend. :type to_backend: callable, optional :param convert_eager: Whether to apply the ``dtype`` and ``to_backend`` conversions eagerly as each gate is applied. The default ``True`` matches the other running simulators (e.g. :class:`CircuitMPS`), since the simple update rule contracts each gate into the state immediately rather than building a lazy network to contract later. :type convert_eager: bool, optional .. attribute:: edges The unique edges defining the PEPS geometry. :type: tuple[tuple[hashable, hashable]] .. attribute:: sites The sites (qubit labels) of the PEPS. :type: tuple[hashable] .. attribute:: gauges The current Vidal-style bond gauges (singular values), keyed by bond index, updated in place as gates are applied. :type: dict[str, array] .. rubric:: Notes The gates applied must address qubits using the same labels that appear in ``edges``. Two-qubit gates are only supported along an existing edge. .. rubric:: Examples >>> import quimb.tensor as qtn >>> edges = [(0, 1), (1, 2), (0, 3), (1, 4), (2, 5), (3, 4), (4, 5)] >>> circ = qtn.CircuitPEPSSimpleUpdate(edges=edges, max_bond=8) >>> circ.apply_gates(gates) >>> peps = circ.psi .. seealso:: :py:obj:`CircuitMPS`, :py:obj:`CircuitDense` .. py:attribute:: gauges .. py:attribute:: _equilibrate_every :value: None .. py:attribute:: _equilibrate_opts .. py:method:: copy() Copy the circuit, including its state, gauges and geometry. The base :class:`CircuitSimpleUpdate` copy carries the geometry; the gauges and equilibrate options are copied here so the two circuits can be evolved independently. .. py:method:: _init_state(N, dtype='complex128') .. py:method:: _apply_gate(gate, tags=None, **gate_opts) Apply a ``Gate`` to this ``Circuit``. This is the main method that all calls to apply a gate should go through. :param gate: The gate to apply. :type gate: Gate :param tags: Tags to add to the gate tensor(s). :type tags: str or sequence of str, optional .. py:method:: apply_gates(gates, progbar=False, **gate_opts) Apply a sequence of gates to this tensor network quantum circuit. :param gates: The sequence of gates to apply. :type gates: Sequence[Gate] or Sequence[Tuple] :param gate_opts: Supplied to :meth:`~quimb.tensor.circuit.Circuit.apply_gate`. .. py:method:: equilibrate(**gauge_opts) Re-gauge the whole state with the simple update rule, improving the consistency of the tracked bond gauges. This does not change the state represented, only the gauge, and can be called periodically between rounds of gates to keep the simple update approximation well behaved. The default options given at construction via ``equilibrate_opts`` are applied first, with any keyword arguments here taking precedence. :param gauge_opts: Supplied to :meth:`~quimb.tensor.tensor_core.TensorNetwork.gauge_all_simple_`, for example ``max_iterations`` and ``tol``. .. py:method:: local_expectation(G, where, *, max_distance=0, normalized=True, **contract_opts) Compute the local expectation value of operator ``G`` at the site(s) ``where``, using the simple update bond gauges to approximate the environment beyond ``max_distance``. :param G: The local operator. :type G: array_like :param where: The site or sites to compute the expectation at. A single site label (which may itself be a tuple, e.g. a 2D coordinate) is detected by membership in the set of sites. :type where: hashable or sequence[hashable] :param max_distance: How many graph hops of neighboring tensors to include in the local cluster used to approximate the reduced density matrix. The default ``0`` uses only the target site(s) and their gauges, matching :meth:`~quimb.tensor.tnag.core.TensorNetworkGenVector.compute_local_expectation_cluster`. :type max_distance: int, optional :param normalized: Whether to normalize by the local norm. :type normalized: bool, optional :param contract_opts: Supplied to :meth:`~quimb.tensor.tnag.core.TensorNetworkGenVector.compute_local_expectation_cluster`. :rtype: float .. py:method:: get_state(absorb_gauges=True) Return the current PEPS state, optionally absorbing the bond gauges. :param absorb_gauges: How to handle the tracked Vidal-style bond gauges. If ``True`` (the default) the gauges are absorbed, so the returned tensor network is the actual wavefunction (up to the simple update approximation). If ``False`` the gauges are added to the network as uncontracted diagonal tensors. If ``"return"`` the raw gauged network and a copy of the gauges are returned separately. The internal state is left untouched in every case. :type absorb_gauges: bool or "return", optional :returns: * **psi** (*TensorNetwork*) -- The current state. * **gauges** (*dict*) -- The current gauges, only if ``absorb_gauges == "return"``. .. py:method:: get_psi() Get the PEPS tensor network state, with the simple update bond gauges absorbed back in so that it represents the actual wavefunction (a proper contraction of it gives the state, up to the simple update approximation). The internal gauged form is left untouched. Shorthand for ``get_state(absorb_gauges=True)``. .. py:method:: to_dense(*args, **kwargs) Contract the gauged PEPS into a dense wavefunction, a column-vector ``qarray`` of length ``2**N`` ordered like :attr:`sites`, matching the output of :meth:`Circuit.to_dense`. This is the actual (approximate) state, so the cost grows exponentially with the number of qubits. Arguments are forwarded to :meth:`~quimb.tensor.tnag.core.TensorNetworkGenVector.to_dense`. .. py:method:: _unsupported(name) :abstractmethod: