qpe_toolbox.estimation.robust_phase_estimation
==============================================

.. py:module:: qpe_toolbox.estimation.robust_phase_estimation


Functions
---------

.. autoapisummary::

   qpe_toolbox.estimation.robust_phase_estimation.robust_phase_estimation
   qpe_toolbox.estimation.robust_phase_estimation.rpe_get_hadamard_output
   qpe_toolbox.estimation.robust_phase_estimation.rpe_distance
   qpe_toolbox.estimation.robust_phase_estimation.rpe_update_theta


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

.. py:function:: robust_phase_estimation(H, psi0, epsilon, sign_E0, n_steps, n_shots, *, trotter_order=2, verbosity=0)

   Perform the Robust Phase Estimation (RPE) algorithm.

   This routine estimates the phase associated with the unitary
   time evolution generated by a Hamiltonian using a sequence of
   Hadamard tests at increasing evolution times.

   The algorithm achieves a target precision ``epsilon`` by iteratively
   refining the phase estimate using powers of two evolution times.

   :param H: Hamiltonian object from the ``Hamiltonian`` class.
   :type H: Hamiltonian
   :param psi0: Initial quantum state :math:`\ket{\psi_0}` of the system.
   :type psi0: :quimb-api:`MatrixProductState`
   :param epsilon: Target precision for the phase estimate.
   :type epsilon: float
   :param sign_E0: Sign of the target energy eigenvalue.
   :type sign_E0: float
   :param n_steps: Number of Trotter steps used to approximate the time evolution.
                   Use ``EXACT`` for exact time evolution.
   :type n_steps: int or qpe_toolbox.EXACT
   :param n_shots: Number of measurement shots used in the Hadamard test.
                   Use ``EXACT`` to compute probabilities exactly.
   :type n_shots: int or EXACT
   :param trotter_order: Order of the Trotter-Suzuki decomposition.
   :type trotter_order: int, default ``2``
   :param verbosity: Verbosity level. If >= 1, print intermediate phase estimates.
   :type verbosity: int, default ``0``

   :returns: **theta_list** -- List of phase estimates at each iteration.
             The last element corresponds to the most accurate estimate.
   :rtype: list of float


.. py:function:: rpe_get_hadamard_output(H, psi0, m, n_steps, n_shots, *, trotter_order=2)

   Estimate the phase of :math:`\bra{\psi_0}\exp(-i H 2^m)\ket{\psi_0}` using Hadamard tests.

   This function computes the phase corresponding to the unitary
   evolution over time :math:`2^m` by evaluating real and imaginary parts
   via Hadamard tests.

   :param H: Hamiltonian object defining the system.
   :type H: Hamiltonian
   :param psi0: Initial quantum state :math:`\ket{\psi_0}`.
   :type psi0: :quimb-api:`MatrixProductState`
   :param m: Iteration index corresponding to evolution time ``2**m``.
   :type m: int
   :param n_steps: Number of Trotter steps. Use ``EXACT`` for exact time evolution.
   :type n_steps: int or qpe_toolbox.EXACT
   :param n_shots: Number of measurement shots used in the Hadamard test.
                   Use ``EXACT`` to compute probabilities exactly.
   :type n_shots: int or qpe_toolbox.EXACT
   :param trotter_order: Order of the Trotter-Suzuki decomposition.
   :type trotter_order: int, default ``2``

   :returns: **phi_m** -- Estimated phase angle in radians.
   :rtype: float


.. py:function:: rpe_distance(phi, theta)

   Compute the angular distance between two angles.

   The distance is defined modulo π and lies in the interval [0, π].

   :param phi: First angle in radians.
   :type phi: float
   :param theta: Second angle in radians.
   :type theta: float

   :returns: **d** -- Angular distance between ``phi`` and ``theta``.
   :rtype: float


.. py:function:: rpe_update_theta(S, theta_ref)

   Find the angle in a set closest to a reference angle.

   The comparison is performed using the angular distance
   modulo 2π.

   :param S: Candidate angles.
   :type S: list of float
   :param theta_ref: Reference angle.
   :type theta_ref: float

   :returns: * **theta_min** (*float*) -- Angle in ``S`` closest to ``theta_ref``.
             * **d_min** (*float*) -- Corresponding minimal angular distance.