qpe_toolbox.estimation.hadamard_test
====================================

.. py:module:: qpe_toolbox.estimation.hadamard_test


Functions
---------

.. autoapisummary::

   qpe_toolbox.estimation.hadamard_test.build_hadamard_test_circuit
   qpe_toolbox.estimation.hadamard_test.run_hadamard_test


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

.. py:function:: build_hadamard_test_circuit(init_mps, U_gate, theta)

   Construct the quantum circuit implementing the Hadamard test.

   The circuit prepares an ancilla qubit, applies a controlled unitary
   :math:`U`, applies a phase rotation on the ancilla, and measures the
   ancilla in the X basis.

   This circuit can be used to estimate the real or imaginary part of
   :math:`\bra{\psi} U \ket{\psi}` by choosing appropriate
   values of ``theta``.

   :param init_mps: Initial state :math:`\ket{\psi}` of the data register.
   :type init_mps: :quimb-api:`MatrixProductState`
   :param U_gate: Unitary operator to be tested.
                  If a ``Gate`` instance is provided, it must act on all data qubits
                  and be controlled by the ancilla qubit.
                  If a list is provided, it is interpreted as a sequence of Trotter
                  slices, each slice being a list of gate specifications.
   :type U_gate: :quimb-api:`Gate` or list
   :param theta: Phase angle applied to the ancilla qubit.
                 Typical values:
                 - ``0`` for estimating the real part
                 - ``-π/2`` for estimating the imaginary part
   :type theta: float

   :returns: **circ** -- Circuit implementing the Hadamard test.
   :rtype: :quimb-api:`CircuitMPS`


.. py:function:: run_hadamard_test(init_mps, U_gate, theta, n_shots, *, seed=None)

   Run the Hadamard test circuit and estimate the expectation value :math:`Z(\theta)`.

   The returned value is

   .. math::

       Z(\theta) = P(0) - P(1)
                 = \mathrm{Re} \left[e^{i\theta} \bra{\psi} U \ket{\psi} \right]

   where :math:`P(0)` and :math:`P(1)` are the probabilities of measuring
   the ancilla qubit in states :math:`\ket{0}` and :math:`\ket{1}`.

   :param init_mps: Initial state :math:`\ket{\psi}` of the data register.
   :type init_mps: :quimb-api:`MatrixProductState`
   :param U_gate: Unitary operator used in the Hadamard test.
                  See ``build_circuit`` method for accepted formats.
   :type U_gate: :quimb-api:`Gate` or list
   :param theta: Phase angle applied to the ancilla qubit.
   :type theta: float
   :param n_shots: Number of measurement shots. If ``EXACT``, probabilities are computed exactly,
                   else probabilities are estimated by sampling.
   :type n_shots: int or qpe_toolbox.EXACT
   :param seed: A random seed, passed to ``numpy.random.seed`` if given.
   :type seed: None or int, optional

   :returns: **Z** -- Estimated value of :math:`Z(\theta) = P(0) - P(1)`.
   :rtype: float