supermarq.qcvv.irb
==================

.. py:module:: supermarq.qcvv.irb

.. autoapi-nested-parse::

   Tooling for interleaved randomised benchmarking.



Classes
-------

.. autoapisummary::

   supermarq.qcvv.irb.IRB
   supermarq.qcvv.irb.IRBResults
   supermarq.qcvv.irb.RBResults


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

.. py:class:: IRB(num_circuits: int, cycle_depths: collections.abc.Iterable[int], interleaved_gate: cirq.Gate | cirq.Operation | None = cirq.Z, qubits: int | collections.abc.Sequence[cirq.Qid] | None = None, clifford_op_gateset: cirq.CompilationTargetGateset = cirq.CZTargetGateset(), *, 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:`_RBResultsBase`\ ]


   Interleaved random benchmarking (IRB) experiment.

   IRB estimates the gate error of specified Clifford gate, :math:`\mathcal{C}^*`.
   This is achieved by first choosing a random sequence, :math:`\{\mathcal{C_i}\}_m`
   of :math:`m` Clifford gates and then using this to generate two circuits. The first
   is generated by appending to this sequence the single gate that corresponds to the
   inverse of the original sequence. The second circuit it obtained by inserting the
   interleaving gate, :math:`\mathcal{C}^*` after each gate in the sequence and then
   again appending the corresponding inverse element of the new circuit. Thus both
   circuits correspond to the identity operation.

   We run both circuits on the specified target and calculate the probability of measuring
   the resulting state in the ground state, :math:`p(0...0)`. This gives the circuit fidelity

   .. math::

       f(m) = 2p(0...0) - 1

   We can then fit an exponential decay :math:`\log(f) \sim m` to this circuit fidelity
   for each circuit, with decay rates :math:`\alpha` and :math:`\tilde{\alpha}` for the circuit
   without and with interleaving respectively. Finally the gate error of the
   specified gate, :math:`\mathcal{C}^*` is estimated as

   .. math::

       e_{\mathcal{C}^*} = \frac{1}{2} \left(1 - \frac{\tilde{\alpha}}{\alpha}\right)

   For more details see: https://arxiv.org/abs/1203.4550


   .. py:method:: gates_per_clifford(samples: int = 500) -> dict[str, float]

      Samples a number of random Clifford operations and calculates the average number of
      single and two qubit gates used to implement them. Note this depends on the gateset chosen
      for the experiment.

      :param samples: Number of samples to use. Defaults to 500.

      :returns: A dictionary with the average number of one and two qubit gates used.



   .. py:method:: random_clifford() -> cirq.CliffordGate

      Returns:
      A random clifford gate with the correct number of qubits for the current experiment.



   .. py:method:: random_single_qubit_clifford() -> cirq.SingleQubitCliffordGate

      Choose a random single qubit clifford gate.

      :returns: The random clifford gate.



   .. py:method:: random_two_qubit_clifford() -> cirq.CliffordGate

      Choose a random two qubit clifford gate.

      For algorithm details see https://arxiv.org/abs/1402.4848 & https://arxiv.org/abs/1210.7011.

      :returns: The random clifford gate.



   .. py:attribute:: clifford_op_gateset

      The gateset to use when implementing Clifford operations.


.. py:class:: IRBResults

   Bases: :py:obj:`_RBResultsBase`


   Data structure for the IRB experiment results.


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

      Plot the exponential decay of the circuit fidelity with cycle depth.

      :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 the IRB and RB decay plots and the corresponding
                fits.

      :raises RuntimeError: If no data is stored.



   .. py:property:: average_interleaved_gate_error
      :type: float


      Returns:
      Estimate of the interleaving gate error.


   .. py:property:: average_interleaved_gate_error_std
      :type: float


      Returns:
      Standard deviation of the estimate for the interleaving gate error.


   .. py:property:: irb_decay_coefficient
      :type: float


      Returns:
      Decay coefficient estimate with the interleaving gate.


   .. py:property:: irb_decay_coefficient_std
      :type: float


      Returns:
      Standard deviation of the decay coefficient estimate with the interleaving gate.


.. py:class:: RBResults

   Bases: :py:obj:`_RBResultsBase`


   Data structure for the RB experiment results.


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

      Plot the exponential decay of the circuit fidelity with cycle depth.

      :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 the RB decay plot and the corresponding fit.

      :raises RuntimeError: If no data is stored.



   .. py:property:: average_error_per_clifford
      :type: float


      Returns:
      Estimate of the average error per Clifford operation.


   .. py:property:: average_error_per_clifford_std
      :type: float


      Returns:
      Standard deviation of the the average error per Clifford operation.