qpe_toolbox.estimation.lcu_walk_operator
========================================

.. py:module:: qpe_toolbox.estimation.lcu_walk_operator


Functions
---------

.. autoapisummary::

   qpe_toolbox.estimation.lcu_walk_operator.get_lcu_weights
   qpe_toolbox.estimation.lcu_walk_operator.build_lcu_prepare_state_mps
   qpe_toolbox.estimation.lcu_walk_operator.build_lcu_prepare_mpo
   qpe_toolbox.estimation.lcu_walk_operator.lcu_select_gates
   qpe_toolbox.estimation.lcu_walk_operator.build_lcu_select_mpo
   qpe_toolbox.estimation.lcu_walk_operator.build_lcu_reflection_mpo
   qpe_toolbox.estimation.lcu_walk_operator.run_qpe_lcu_walk_operator
   qpe_toolbox.estimation.lcu_walk_operator.qpe_first_stage_walk
   qpe_toolbox.estimation.lcu_walk_operator.get_energy_from_lcu_walk_phase
   qpe_toolbox.estimation.lcu_walk_operator.estimate_lcu_error


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

.. py:function:: get_lcu_weights(hamiltonian)

   Compute the LCU weights, normalization factor, and ancilla register size for a Hamiltonian.

   :param hamiltonian: Hamiltonian from the QPE-Toolbox ``Hamiltonian`` class.
   :type hamiltonian: Hamiltonian

   :returns: * **weights** (*list of float*) -- Absolute values of the Hamiltonian coefficients, extended with zeros to
               match a power-of-two length.
             * **lmb** (*float*) -- Sum of absolute values of Hamiltonian coefficients (normalization factor).
             * **L** (*int*) -- Number of original Hamiltonian terms.
             * **m_L** (*int*) -- Number of qubits required for the auxiliary L-register,
               i.e., ``ceil(log2(L))``.


.. py:function:: build_lcu_prepare_state_mps(hamiltonian, *, cutoff=1e-10)

   Construct the normalized MPS representing the L register state :math:`\ket{\mathcal{L}}`.

   .. math::
       \ket{\mathcal{L}} = \sum_\ell \sqrt{\frac{w_\ell}{\lambda}} \ket{\ell}

   :param hamiltonian: Hamiltonian to encode with LCU.
   :type hamiltonian: Hamiltonian
   :param cutoff: Singular value cutoff for MPS compression.
   :type cutoff: float, default ``1e-10``

   :returns: **L_mps** -- MPS representing the state :math:`\ket{\mathcal{L}}`.
   :rtype: :quimb-api:`MatrixProductState`


.. py:function:: build_lcu_prepare_mpo(hamiltonian, *, cutoff=1e-10)

   Construct the PREPARE oracle MPO :math:`\ket{0}\bra{\mathcal{L}}`.

   :param hamiltonian: Hamiltonian to encode with LCU.
   :type hamiltonian: Hamiltonian
   :param cutoff: Cutoff for MPO compression.
   :type cutoff: float, default ``1e-10``

   :returns: **prep_mpo** -- MPO implementing the PREPARE oracle.
   :rtype: :quimb-api:`MatrixProductOperator`


.. py:function:: lcu_select_gates(hamiltonian)

   Construct the full list of gate instructions for the SELECT oracle.

   :param hamiltonian: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class.
   :type hamiltonian: Hamiltonian

   :returns: **gates** -- Gate sequence implementing the SELECT oracle.
   :rtype: list of :quimb-api:`Gate`


.. py:function:: build_lcu_select_mpo(hamiltonian, *, cutoff=1e-10)

   Construct the MPO implementing the SELECT oracle.

   :param hamiltonian: Hamiltonian describing the system.
   :type hamiltonian: Hamiltonian
   :param cutoff: MPO compression cutoff.
   :type cutoff: float, default ``1e-10``

   :returns: **select_mpo** -- MPO implementing :math:`SELECT = \sum_\ell \ket{\ell}\bra{\ell} \otimes H_\ell`.
   :rtype: :quimb-api:`MatrixProductOperator`


.. py:function:: build_lcu_reflection_mpo(hamiltonian, *, cutoff=1e-10)

   Construct the reflection operator :math:`\mathcal{R}_L` for the L register.

   .. math::
       \mathcal{R}_L = 2 \ket{\mathcal{L}}\bra{\mathcal{L}}\otimes\mathbb{1} - \mathbb{1}

   :param hamiltonian: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class.
   :type hamiltonian: Hamiltonian
   :param cutoff: MPO compression cutoff.
   :type cutoff: float, default ``1e-10``

   :returns: **R_L** -- MPO representing the reflection.
   :rtype: :quimb-api:`MatrixProductOperator`


.. py:function:: run_qpe_lcu_walk_operator(H, psi0_mps, m_ph, *, max_bond=0, cutoff=1e-10, verbosity=0)

   Perform LCU and quantum phase estimation (QPE) using the walk operator.

   :param H: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class.
   :type H: Hamiltonian
   :param psi0_mps: Initial state of the physical register.
   :type psi0_mps: :quimb-api:`MatrixProductState`
   :param m_ph: Number of phase estimation qubits.
   :type m_ph: int
   :param max_bond: Maximum MPS bond dimension.
   :type max_bond: int, default ``0``
   :param cutoff: Truncation cutoff for MPS compression.
   :type cutoff: float, default ``1e-10``
   :param verbosity: Verbosity level. If >= 1, print result summary. If >= 2, print
                     detailed progress messages.
   :type verbosity: int, default ``0``

   :returns: * **traces** (*dict*) -- Contains timing information: {'ctimes': [...]}.
             * **theta** (*float*) -- Estimated phase from the walk operator.


.. py:function:: qpe_first_stage_walk(H, psi0_mps, m_ph, regs, *, max_bond=0, cutoff=1e-10, verbosity=0)

   LCU first stage of QPE: apply Hadamard wall and controlled-W sequence.

   :param H: Hamiltonian from the QPE-Toolbox ``Hamiltonian`` class.
   :type H: Hamiltonian
   :param psi0_mps: Initial state of the physical register.
   :type psi0_mps: :quimb-api:`MatrixProductState`
   :param m_ph: Number of phase qubits.
   :type m_ph: int
   :param regs: Dictionary with registers: {'phase':..., 'L':..., 'phys':...}.
   :type regs: dict
   :param max_bond: Maximum MPS bond dimension.
   :type max_bond: int, default ``0``
   :param cutoff: MPO/MPS compression cutoff.
   :type cutoff: float, default ``1e-10``
   :param verbosity: Verbosity level. If >= 2, print progress messages.
   :type verbosity: int, default ``0``

   :returns: * **traces** (*dict*) -- Contains timing information: {'ctimes': [...]}.
             * **circ** (:quimb-api:`CircuitMPS`) -- Circuit representing the applied QPE first stage.


.. py:function:: get_energy_from_lcu_walk_phase(theta, lmb)

   Get the energy from the eigenphase of the LCU Walk operator.

   .. math::
       E = \lambda \cos(2 \pi \theta)

   :param theta: Eigenphase of the Walk operator.
   :type theta: float
   :param lmb: One-norm of LCU weights.
   :type lmb: float

   :returns: **energy** -- Estimated energy.
   :rtype: float


.. py:function:: estimate_lcu_error(m_ph, E0, lmb)

   Estimate the error bound in energy in LCU QPE from finite number of phase qubits.

   :param m_ph: Number of phase estimation qubits.
   :type m_ph: int
   :param E0: Ground state energy estimate.
   :type E0: float
   :param lmb: LCU normalization factor.
   :type lmb: float

   :returns: **delta_E** -- Estimated upper bound on the energy error.
   :rtype: float