qpe_toolbox.tensor.mpomps_tools
===============================

.. py:module:: qpe_toolbox.tensor.mpomps_tools


Functions
---------

.. autoapisummary::

   qpe_toolbox.tensor.mpomps_tools.kron_mpos
   qpe_toolbox.tensor.mpomps_tools.kron_mps
   qpe_toolbox.tensor.mpomps_tools.apply_gate_from_mpo
   qpe_toolbox.tensor.mpomps_tools.add_creg_mpo
   qpe_toolbox.tensor.mpomps_tools.add_cqubit_mpo
   qpe_toolbox.tensor.mpomps_tools.controlled_mpo


Module Contents
---------------

.. py:function:: kron_mpos(mpo1, mpo2)

   Construct the Kronecker (tensor) product of two MPOs.

   This returns an MPO representing :math:`\mathrm{MPO}_1 \otimes \mathrm{MPO}_2`,
   with tensors arranged in the left, right, up, down index ordering

   The function supports both single-site and multi-site MPOs and handles
   boundary tensor reshaping explicitly.

   :param mpo1: First MPO operand.
   :type mpo1: :quimb-api:`MatrixProductOperator`
   :param mpo2: Second MPO operand.
   :type mpo2: :quimb-api:`MatrixProductOperator`

   :returns: The Kronecker product MPO acting on the concatenated Hilbert space.
   :rtype: :quimb-api:`MatrixProductOperator`

   :raises ValueError: If the tensor shapes of either MPO are not compatible with the expected
       MPO boundary conventions.


.. py:function:: kron_mps(mps1, mps2, *, verbosity=0)

   Construct the Kronecker (tensor) product of two MPS objects.

   This returns an MPS representing :math:`\mathrm{MPS}_1 \otimes \mathrm{MPS}_2`,
   with tensors arranged in the left, right, physical index ordering.

   :param mps1: First MPS operand.
   :type mps1: :quimb-api:`MatrixProductState`
   :param mps2: Second MPS operand.
   :type mps2: :quimb-api:`MatrixProductState`
   :param verbosity: If ``> 0``, print the shapes of the resulting tensors.
   :type verbosity: int, default ``0``

   :returns: The Kronecker product MPS on the combined physical register.
   :rtype: :quimb-api:`MatrixProductState`

   :raises ValueError: If the tensor shapes of either MPS are not compatible with the expected
       MPS boundary conventions.


.. py:function:: apply_gate_from_mpo(circ, mpo, *, compress=False, cutoff=1e-10, max_bond=0)

   Apply an MPO-defined gate to a circuit state and return a new CircuitMPS.

   The MPO is applied to the circuit wavefunction ``circ.psi``. Optional
   compression can be performed during and/or after application.

   :param circ: Input circuit whose state will be acted on.
   :type circ: :quimb-api:`Circuit` or :quimb-api:`CircuitMPS`
   :param mpo: MPO representing the quantum gate or evolution operator.
   :type mpo: :quimb-api:`MatrixProductOperator`
   :param compress: Whether to compress the resulting MPS during application.
   :type compress: bool, default ``False``
   :param cutoff: Singular value cutoff used during compression.
   :type cutoff: float, default ``1e-10``
   :param max_bond: Maximum allowed bond dimension. ``0`` means no explicit limit.
   :type max_bond: int, default ``0``

   :returns: New circuit with the updated MPS state.
   :rtype: :quimb-api:`CircuitMPS`

   .. rubric:: Notes

   This function does not modify the input circuit in place.


.. py:function:: add_creg_mpo(mpo, mpo_reg, creg, cket)

   Add multiple control qubits to an MPO.

   The resulting MPO represents a controlled operation acting on the original
   MPO, conditioned on the control register being in a specified computational
   basis state.

   :param mpo: Base MPO representing the target operation.
   :type mpo: :quimb-api:`MatrixProductOperator`
   :param mpo_reg: Indices of the physical register acted on by ``mpo``.
   :type mpo_reg: list[int]
   :param creg: Control qubit indices, indexed with respect to the MPO ordering.
   :type creg: list[int]
   :param cket: Control state. Can be a bitstring (e.g. ``"11"``) or an integer encoding
                the computational basis state.
   :type cket: str or int

   :returns: MPO with added control qubits.
   :rtype: :quimb-api:`MatrixProductOperator`

   :raises ValueError: If an unsupported control state is requested.
   :raises TypeError: If ``cket`` is neither ``str`` nor ``int``.

   .. rubric:: Notes

   This function is not fully tested and should be used with care for
   multi-control configurations.


.. py:function:: add_cqubit_mpo(mpo, location)

   Add a single control qubit to an MPO.

   The control qubit is added either before or after the existing MPO,
   depending on register ordering.

   :param mpo: Base MPO representing the target operation.
   :type mpo: :quimb-api:`MatrixProductOperator`
   :param location: Whether to add the control qubit before or after the MPO qubits.
   :type location: {"before", "after"}

   :returns: MPO augmented with a single control qubit.
   :rtype: :quimb-api:`MatrixProductOperator`

   :raises ValueError: If ``location`` is not one of ``"before"`` or ``"after"``.


.. py:function:: controlled_mpo(mpo, phys_reg, aux_reg, k_ctrl, *, ctrl=1)

   Construct an MPO controlled on an auxiliary qubit being in a given state.

   The MPO is assumed to be of the form ``Id ⊗ U``, where ``Id`` acts on the
   auxiliary register and ``U`` acts on the physical register.

   :param mpo: Input MPO in the form ``Id ⊗ U``.
   :type mpo: :quimb-api:`MatrixProductOperator`
   :param phys_reg: Indices of the physical register qubits.
   :type phys_reg: list[int]
   :param aux_reg: Indices of the auxiliary (control) register qubits.
   :type aux_reg: list[int]
   :param k_ctrl: Index of the control qubit relative to ``aux_reg``.
   :type k_ctrl: int
   :param ctrl: Control value (``0`` or ``1``) conditioning the operation.
   :type ctrl: int, default ``1``

   :returns: Controlled MPO.
   :rtype: :quimb-api:`MatrixProductOperator`

   :raises ValueError: If the register ordering assumption is violated.

   .. rubric:: Notes

   This implementation assumes that all auxiliary-register tensors initially
   correspond to identity operators.