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(interleaved_gate: cirq.Gate | None = cirq.Z, num_qubits: int | None = 1, clifford_op_gateset: cirq.CompilationTargetGateset = cirq.CZTargetGateset(), *, random_seed: int | numpy.random.Generator | None = None)

   Bases: :py:obj:`supermarq.qcvv.base_experiment.BenchmarkingExperiment`\ [\ :py:obj:`Union`\ [\ :py:obj:`IRBResults`\ , :py:obj:`RBResults`\ ]\ ]


   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:: analyze_results(plot_results: bool = True) -> IRBResults | RBResults

      Analyse the experiment results and estimate the interleaved gate error.

      :param plot_results: Whether to generate plots of the results. Defaults to False.

      :returns: A named tuple of the final results from the experiment.



   .. py:method:: exp_decay(x: numpy.typing.NDArray[numpy.float_], A: float, alpha: float, B: float) -> numpy.typing.NDArray[numpy.float_]
      :staticmethod:


      Exponential decay of the form

      .. math::

          A \alpha^x + B

      :param x: x
      :param A: Decay constant
      :param alpha: Decay coefficient
      :param B: Additive constant

      :returns: Exponential decay applied to x.



   .. 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:: plot_results() -> None

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



   .. 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/pdf/1402.4848 & https://arxiv.org/pdf/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:`supermarq.qcvv.base_experiment.BenchmarkingResults`


   Data structure for the IRB experiment results.


   .. py:attribute:: average_interleaved_gate_error
      :type:  float | None

      Estimate of the interleaving gate error.


   .. py:attribute:: average_interleaved_gate_error_std
      :type:  float | None

      Standard deviation of the estimate for the interleaving gate error.


   .. py:attribute:: experiment_name
      :value: 'IRB'


      The name of the experiment.


   .. py:attribute:: irb_decay_coefficient
      :type:  float | None

      Decay coefficient estimate with the interleaving gate.


   .. py:attribute:: irb_decay_coefficient_std
      :type:  float | None

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


   .. py:attribute:: rb_decay_coefficient
      :type:  float

      Decay coefficient estimate without the interleaving gate.


   .. py:attribute:: rb_decay_coefficient_std
      :type:  float

      Standard deviation of the decay coefficient estimate without the interleaving gate.


.. py:class:: RBResults

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


   Data structure for the RB experiment results.


   .. py:attribute:: average_error_per_clifford
      :type:  float | None

      Estimate of the average error per Clifford operation.


   .. py:attribute:: average_error_per_clifford_std
      :type:  float | None

      Standard deviation of the the average error per Clifford operation.


   .. py:attribute:: experiment_name
      :value: 'RB'


      The name of the experiment.


   .. py:attribute:: rb_decay_coefficient
      :type:  float

      Decay coefficient estimate without the interleaving gate.


   .. py:attribute:: rb_decay_coefficient_std
      :type:  float

      Standard deviation of the decay coefficient estimate without the interleaving gate.