quimb.tensor.gating =================== .. py:module:: quimb.tensor.gating .. autoapi-nested-parse:: Functionality relating to *gating* tensor networks, i.e. applying a 'gate' - typically a local operator described by a raw array - to one or more indices in the network, maintaining the outer index structure by appropriate reindexing. Attributes ---------- .. autoapisummary:: quimb.tensor.gating._BASIC_GATE_CONTRACT quimb.tensor.gating._SPLIT_GATE_CONTRACT quimb.tensor.gating._VALID_GATE_CONTRACT Functions --------- .. autoapisummary:: quimb.tensor.gating._tensor_network_gate_inds_basic quimb.tensor.gating._tensor_network_gate_inds_eager_split quimb.tensor.gating._tensor_network_gate_inds_lazy_split quimb.tensor.gating.maybe_factor_gate quimb.tensor.gating.tensor_network_gate_inds quimb.tensor.gating._tensor_network_gate_sandwich_inds_eager_split quimb.tensor.gating.tensor_network_gate_sandwich_inds Module Contents --------------- .. py:function:: _tensor_network_gate_inds_basic(tn: quimb.tensor.tensor_core.TensorNetwork, G, inds, ng, tags, contract, isparam, info, **compress_opts) .. py:function:: _tensor_network_gate_inds_eager_split(tn, inds, contract, reindex_map, TG, info, compress_opts) .. py:function:: _tensor_network_gate_inds_lazy_split(tn: quimb.tensor.tensor_core.TensorNetwork, G, inds, ng, tags, contract, **compress_opts) .. py:data:: _BASIC_GATE_CONTRACT .. py:data:: _SPLIT_GATE_CONTRACT .. py:data:: _VALID_GATE_CONTRACT .. py:function:: maybe_factor_gate(G, inds, xp=None, tn=None) Possibly reshape gate ``G``, if it has been supplied as a matrix with 'fused' dimensions, into a tensor with separate physical dimensions. .. py:function:: tensor_network_gate_inds(self: quimb.tensor.tensor_core.TensorNetwork, G, inds, contract=False, tags=None, info=None, inplace=False, **compress_opts) Apply a local 'gate' ``G``, given as a raw array, to a group of indices ``inds``, as if applying ``G @ x``. The indices are propagated to the outside to maintain the original index structure of the tensor network. :param G: The gate array to apply, should match or be factorable into the shape ``(*phys_dims, *phys_dims)``. :type G: array_ike :param inds: The index or indices to apply the gate to. :type inds: str or sequence or str, :param contract: How to apply the gate: - ``False``: gate is added to network lazily and nothing is contracted, tensor network structure is thus not maintained. - ``True``: gate is contracted eagerly with all tensors involved, tensor network structure is thus only maintained if gate acts on a single site only. - ``'split'``: contract all involved tensors then split the result back into two. - ``'reduce-split'``: factor the two physical indices into 'R-factors' using QR decompositions on the original site tensors, then contract the gate, split it and reabsorb each side. Cheaper than ``'split'`` when the tensors on either side have at least 3 bonds. - ``'split-gate'``: lazily add the gate as with ``False``, but split the gate tensor spatially. - ``'swap-split-gate'``: lazily add the gate as with ``False``, but split the gate as if an extra SWAP has been applied. - ``'auto-split-gate'``: lazily add the gate as with ``False``, but maybe apply one of the above options depending on whether they result in a rank reduction. The named methods are relevant for two site gates only, for single site gates they use the ``contract=True`` option which also maintains the structure of the TN. See below for a pictorial description of each method. :type contract: bool or str, optional :param tags: Tags to add to the new gate tensor. :type tags: str or sequence of str, optional :param info: Used to store extra optional information such as the singular values if not absorbed. :type info: None or dict, optional :param inplace: Whether to perform the gate operation inplace on the tensor network or not. :type inplace: bool, optional :param compress_opts: Supplied to :func:`~quimb.tensor.tensor_core.tensor_split` for any ``contract`` methods that involve splitting. Ignored otherwise. Key options include `max_bond` and `cutoff`. :returns: **G_tn** :rtype: TensorNetwork .. rubric:: Notes The ``contract`` options look like the following (for two site gates). ``contract=False``:: . . <- inds │ │ GGGGG │╱ │╱ ──●───●── ╱ ╱ ``contract=True``:: │╱ │╱ ──GGGGG── ╱ ╱ ``contract='split'``:: │╱ │╱ │╱ │╱ ──GGGGG── ==> ──G┄┄┄G── ╱ ╱ ╱ ╱ ``contract='reduce-split'``:: │ │ │ │ GGGGG GGG │ │ │╱ │╱ ==> ╱│ │ ╱ ==> ╱│ │ ╱ │╱ │╱ ──●───●── ──▶─●─●─◀── ──▶─GGG─◀── ==> ──G┄┄┄G── ╱ ╱ ╱ ╱ ╱ ╱ ╱ ╱ For one site gates when one of the above 'split' methods is supplied ``contract=True`` is assumed. ``contract='split-gate'``:: │ │ G~~~G │╱ │╱ ──●───●── ╱ ╱ ``contract='swap-split-gate'``:: ╲ ╱ ╳ ╱ ╲ G~~~G │╱ │╱ ──●───●── ╱ ╱ ``contract='auto-split-gate'`` chooses between the above two and ``False``, depending on whether either results in a lower rank. .. py:function:: _tensor_network_gate_sandwich_inds_eager_split(tn, G, Gconj, inds_upper, inds_lower, contract, tags, info, **compress_opts) .. py:function:: tensor_network_gate_sandwich_inds(self: quimb.tensor.tensor_core.TensorNetwork, G, inds_upper, inds_lower, contract=False, tags=None, tags_upper=None, tags_lower=None, info=None, inplace=False, **compress_opts) Apply a 'sandwich' gate, ``G`` to two groups of indices in a tensor network, i.e. applying ``G @ x @ G†`` to the indices given respectively by ``inds_upper`` and ``inds_lower``, then propagating them to the outside, to maintain the original index structure. G : array_ike The gate array to apply, should match or be factorable into the shape ``(*phys_dims, *phys_dims)``. inds_upper : str or sequence or str, The upper (ket-like) index or indices to apply the gate to. inds_lower : str or sequence or str, The lower (bra-like) index or indices to apply the conjugate gate to. contract : bool or str, optional How to apply the gate, see :meth:`~quimb.tensor.gating.tensor_network_gate_inds` for details and pictorial representations. tags : str or sequence of str, optional Tags to add to both new gate tensors. tags_upper : str or sequence of str, optional Tags to add to the upper gate tensor only. tags_lower : str or sequence of str, optional Tags to add to the lower gate tensor only. 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 :func:`~quimb.tensor.tensor_core.tensor_split` for any ``contract`` methods that involve splitting. Ignored otherwise. Key options include `max_bond` and `cutoff`. :returns: **G_tn** :rtype: TensorNetwork