supermarq.qcvv.xeb
==================

.. py:module:: supermarq.qcvv.xeb

.. autoapi-nested-parse::

   Tooling for cross entropy benchmark experiments.



Classes
-------

.. autoapisummary::

   supermarq.qcvv.xeb.XEB
   supermarq.qcvv.xeb.XEBResults
   supermarq.qcvv.xeb.XEBSample


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

.. py:class:: XEB(single_qubit_gate_set: list[cirq.Gate] | None = None, two_qubit_gate: cirq.Gate | None = cirq.CZ, *, random_seed: int | numpy.random.Generator | None = None)

   Bases: :py:obj:`supermarq.qcvv.base_experiment.BenchmarkingExperiment`\ [\ :py:obj:`XEBResults`\ ]


   Cross-entropy benchmarking (XEB) experiment.

   The XEB experiment can be used to estimate the combined fidelity of a repeating
   cycle of gates. In our case, where we restrict ourselves to two qubits, we use
   cycles made up of two randomly selected single qubit phased XZ gates and a constant
   two qubit gate. This is illustrated as follows:

   For each randomly generated circuit, with a given number of cycle, we compare the
   simulated state probabilities, :math:`p(x)` with those achieved by running the circuit
   on a given target, :math:`\hat{p}(x)`. The fidelity of a circuit containing :math:`d`
   cycles, :math:`f_d` can then be estimated as

   .. math::

       \sum_{x \in \{0, 1\}^n} p(x) \hat{p}(x) - \frac{1}{2^n} =
       f_d \left(\sum_{x \in \{0, 1\}^n} p(x)^2 -  \frac{1}{2^n}\right)

   We can therefore fit a linear model to estimate the value of :math:`f_d`. We the estimate
   the fidelity of the cycle, :math:`f_{\mathrm{cycle}}` as

   .. math::

       f_d = A(f_{cycle})^d

   Thus fitting another linear model to :math:`\log(f_d) \sim d` provides us with an estimate
   of the cycle fidelity.

   For more details see: https://www.nature.com/articles/s41586-019-1666-5


   .. py:method:: analyze_results(plot_results: bool = True) -> XEBResults

      Analyse the results and calculate the estimated circuit fidelity.

      :param plot_results: Whether to generate the data plots. Defaults to True.
      :type plot_results: optional

      :returns: The final results from the experiment.



   .. py:method:: plot_results() -> None

      Plot the experiment data and the corresponding fits.



   .. py:property:: circuit_fidelities
      :type: pandas.DataFrame

      The circuit fidelity calculations from the most recently run experiment.

      :raises RuntimeError: If no data is available.


   .. py:property:: samples
      :type: collections.abc.Sequence[XEBSample]

      The samples generated during the experiment.

      :raises RuntimeError: If no samples are available.


   .. py:attribute:: single_qubit_gate_set
      :type:  list[cirq.Gate]

      The single qubit gates to randomly sample from


   .. py:attribute:: two_qubit_gate
      :type:  cirq.Gate | None

      The two qubit gate to use for interleaving.


.. py:class:: XEBResults

   Bases: :py:obj:`supermarq.qcvv.base_experiment.BenchmarkingResults`


   Results from an XEB experiment.


   .. py:attribute:: cycle_fidelity_estimate
      :type:  float

      Estimated cycle fidelity.


   .. py:attribute:: cycle_fidelity_estimate_std
      :type:  float

      Standard deviation for the cycle fidelity estimate.


   .. py:attribute:: experiment_name
      :value: 'XEB'



.. py:class:: XEBSample

   Bases: :py:obj:`supermarq.qcvv.base_experiment.Sample`


   The samples used in XEB experiments.


   .. py:method:: sum_target_cross_sample_probs() -> float

      Compute the dot product between the sample and target probabilities

      :raises RuntimeError: If either the target or sample probabilities have not yet been
          initialised.

      :returns: The dot product between the sample and target probabilities.
      :rtype: float



   .. py:method:: sum_target_probs_square() -> float

      Compute the sum of the squared target probabilities.

      :raises RuntimeError: If no target probabilities have been initialised.

      :returns: The sum of squared target probabilities.
      :rtype: float



   .. py:attribute:: sample_probabilities
      :type:  dict[str, float] | None
      :value: None


      The sample probabilities obtained from the chosen target


   .. py:attribute:: target_probabilities
      :type:  dict[str, float] | None
      :value: None


      The target probabilities obtained through a noiseless simulator