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


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

.. py:class:: XEB(num_circuits: int, cycle_depths: collections.abc.Iterable[int], interleaved_layer: cirq.Gate | cirq.OP_TREE | None = cirq.CZ, single_qubit_gate_set: collections.abc.Sequence[cirq.Gate] | None = None, *, random_seed: int | numpy.random.Generator | None = None, _samples: list[supermarq.qcvv.base_experiment.Sample] | None = None, **kwargs: str)

   Bases: :py:obj:`supermarq.qcvv.base_experiment.QCVVExperiment`\ [\ :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.
   Cycles are made up of randomly selected single qubit gates and a constant layer of interest.
   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:: independent_qubit_groups() -> list[tuple[cirq.Qid, Ellipsis]]

      Get all independent subsets of qubits in this experiment.

      :returns: A list of disjoint tuples of `cirq.Qid` objects, each of which can be analyzed as an
                independent XEB experiment.



   .. py:attribute:: interleaved_layer
      :type:  cirq.OP_TREE | None

      The layer to interleave.


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

      The single qubit gates to randomly sample from


.. py:class:: XEBResults

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


   Results from an XEB experiment.


   .. py:method:: plot_results(filename: str | None = None) -> matplotlib.pyplot.Figure

      Plot the experiment data and the corresponding fits.

      :param filename: Optional argument providing a filename to save the plots to. Defaults to None,
                       indicating not to save the plot.

      :returns: A single matplotlib figure containing both the linear fit per cycle depth and the decay
                with cycle depth.

      :raises RuntimeError: If there is no data stored.



   .. py:method:: plot_speckle(filename: str | None = None) -> matplotlib.pyplot.Figure

      Creates the speckle plot of the XEB data. See Fig. S18 of
      https://arxiv.org/abs/1910.11333 for an explanation of this plot.

      :param filename: Optional argument providing a filename to save the plots to. Defaults to None,
                       indicating not to save the plot.

      :returns: A matplotlib figure with the speckle plot.

      :raises RuntimeError: If there is no data stored.



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

      Prints the key results data.



   .. py:property:: cycle_fidelity_estimate
      :type: float


      Estimated cycle fidelity.


   .. py:property:: cycle_fidelity_estimate_std
      :type: float


      Standard deviation for the cycle fidelity estimate.