Add proper protocols documentation

doc/source/conf.py

@@ -33,6 +33,13 @@
 # master_doc = "index"
 
 autodoc_mock_imports = ["qm"]
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": True,
+    "inherited-members": True,
+    "exclude-members": "load, execution_parameters, classify",
+}
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

doc/source/getting-started/index.rst

@@ -11,5 +11,5 @@ your quantum hardware.
     installation
     interface
     runcard
-    protocols
+    ../protocols/index
     example

doc/source/getting-started/runcard.rst

@@ -1,7 +1,7 @@
 .. _runcard:
 
 How to execute calibration protocols in ``Qibocal``?
-================================================
+====================================================
 
 In ``Qibocal`` we adopt a declarative programming paradigm, i.e. the user should specify directly
 what he wants to do without caring about the underlying implementation.

doc/source/protocols/allxy.rst

@@ -0,0 +1,28 @@
+All-XY
+======
+
+The All-XY experiment is commonly used to evaluate the quality of the single qubit rotations :cite:p:`gao2021practical`. In this protocol, a sequence
+of single qubit rotations pairs are performed, such that the resulting states form a staircase pattern where only :math:`\ket{0}`,
+:math:`\ket{1}` or a superposition of the two are present.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass::
+	qibocal.protocols.allxy.allxy.AllXYParameters
+	:noindex:
+
+Example
+^^^^^^^
+It follows a runcard example of this experiment.
+
+.. code-block:: yaml
+
+    - id: allxy
+      operation: allxy
+      parameters:
+        nshots: 2000
+
+The expected output is the following:
+
+.. image:: allxy.png

doc/source/protocols/dispersive_shift.rst

@@ -0,0 +1,65 @@
+.. _dispersive_shift:
+
+Dispersive shift
+================
+
+In this section we present the dispersive shift routines provided by Qibocal.
+
+Theory
+------
+
+A system with a qubit and a resonator, interacting with each other, is described by the James-Cummings Hamiltonian.
+Restricting the qubit states to the first two levels, we get
+
+.. math::
+	\hat{H}_{\text{JC}} = \hbar \omega_r \hat{a}^\dagger \hat{a} + \frac{\hbar \omega_q}{2} \hat{\sigma}_z + \hbar g (\hat{a}^\dagger \hat{\sigma}_- + \hat{a} \hat{\sigma}_+)
+
+where :math:`\omega_r` and :math:`\omega_q` are respectively the resonator and the qubit frequencies, and :math:`g` is the coupling
+constant between the qubit and the resonator.
+In the dispersive regime :math:`g \ll \lvert \omega_r - \omega_q \rvert`, the Hamiltonian can be rewritten as
+
+.. math::
+	:label: eq_1
+
+	\hat{H}_{\text{eff}} = \hbar \hat{a}^\dagger \hat{a} (\omega_r - \chi \hat{\sigma}_z) + \frac{\hbar}{2} (\omega_q + \chi) \hat{\sigma}_z
+
+where we introduced the dispersive shift
+
+.. math::
+	\chi = \frac{g^2}{\lambda}.
+
+Equation :eq:`eq_1` shows that the resonator frequency is :math:`\omega_{r,0} = \omega_r - \chi` (:math:`\omega_{r,1} = \omega_r + \chi`) when the
+qubit is in the ground (excited) state. The separation between the two freqiencies is :math:`\lvert 2 \chi \rvert`.
+
+Routine description
+^^^^^^^^^^^^^^^^^^^
+After collecting the data from the two spectroscopies, for each readout frequency the distance of the centers of the blobs for
+:math:`\ket{0}` and :math:`\ket{1}` states are evaluated. The best readout frequency is the one maximizing the distance between the two blobs.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.dispersive_shift.DispersiveShiftParameters
+	:noindex:
+
+Example
+^^^^^^^
+It follows an example of the experiment parameters.
+
+.. code-block:: yaml
+
+    - id: dispersive shift qt
+      operation: dispersive_shift_qutrit
+      parameters:
+        freq_step: 200000
+        freq_width: 1000000
+
+
+After running `qq auto`, the experiment is executed and the result will looks like
+the following picture.
+
+.. image:: dispersive_shift.png
+
+Requirements
+^^^^^^^^^^^^
+- :ref:`rabi`

doc/source/protocols/flipping.rst

@@ -0,0 +1,56 @@
+Flipping
+========
+
+The flipping experiment corrects the amplitude in the qubit drive pulse. In this experiment,
+we applying an :math:`R_x(\pi/2)` rotation followed by :math:`N` flips (two :math:`R_x(\pi)` rotations)
+and we measure the qubit state.
+The first :math:`R_x(\pi/2)` is necessary to discriminate the over rotations and under rotations of the :math:`R_x(\pi)` pulse:
+without it the difference between the two cases is just a global phase, i.e., the
+probabilities are the same. With the :math:`R_x(\pi/2)` pulse, in case of under rotations the state will be closer to :math:`\ket{0}`
+after the initial flip, in the over rotations one the final state will be closer to :math:`\ket{1}`.
+
+By fitting the resulting data with a sinusoidal function, we can determine the delta amplitude, which allows us to refine the
+:math:`\pi` pulse amplitue.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.flipping.FlippingParameters
+	:noindex:
+
+Example
+^^^^^^^
+It follows a runcard example of this experiment.
+
+.. code-block:: yaml
+
+	- id: flipping
+	  operation: flipping
+	  parameters:
+	    detuning: 0.05
+	    nflips_max: 30
+	    nflips_step: 1
+
+The expected output is the following:
+
+.. image:: flipping.png
+
+Qibocal provides also a "signal" version of this routine, it follows a possible runcard
+with its report.
+
+.. code-block:: yaml
+
+    - id: flipping
+      operation: flipping_signal
+      parameters:
+        detuning: -0.5
+        nflips_max: 20
+        nflips_step: 1
+
+.. image:: flipping_signal.png
+
+Requirements
+^^^^^^^^^^^^
+
+- :ref:`rabi`
+- :ref:`single_shot`

doc/source/protocols/flux/crosstalk.rst

@@ -0,0 +1,111 @@
+Flux crosstalk experiments
+==========================
+
+In this section we show how to run flux crosstalk experiments.
+
+As we saw in :ref:`flux` the external flux affecting a qubit line :math:`i`
+will receive contributions from other qubits
+
+.. math::
+
+    \Phi_i = \sum_{j} C_{ij} V_j +  \Phi_i^{\text{offset}} \quad ,
+
+which means that the transmon frequency can change when current is applied
+on other qubits.
+
+.. _qubit_crosstalk:
+
+Qubit crosstalk
+---------------
+
+It is possible to measure qubit crosstalk by running a `qubit_crosstalk` experiment.
+Assuming that the target qubit is at the sweetspot, in order to measure crosstalk
+effects it is suggested to bias the qubit away.
+
+Here is a possible runcard where we measure the crosstalk on qubit 2
+caused by qubit 3 and 0.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.flux_dependence.qubit_crosstalk.QubitCrosstalkParameters
+  :noindex:
+
+Example
+^^^^^^^
+
+.. code-block:: yaml
+
+    - id: qubit crosstalk
+      operation: qubit_crosstalk
+      targets: [2]
+      parameters:
+        bias_point:
+            2: 0.25
+        bias_step: 0.001
+        bias_width: 0.05
+        drive_amplitude: 0.002
+        drive_duration: 4000
+        flux_qubits: [0, 3]
+        freq_step: 200000
+        freq_width: 10000000
+        nshots: 1024
+        relaxation_time: 20000
+
+
+.. image:: qubit_crosstalk.png
+
+The previous runcard aims at extracting the crosstalk coefficients
+:math:`C_{20}` and :math:`C_{23}`.
+
+Requirements
+^^^^^^^^^^^^
+
+- :ref:`qubit_flux`
+
+.. _resonator_crosstalk:
+
+Resonator crosstalk
+-------------------
+
+In a similar fashion it is possible to repeat the previous experiment
+by sweeping the readout frequency. Note that in this case it will be
+necessary to bias the qubit away from its sweetspot more to observe
+significant variations.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.flux_dependence.resonator_crosstalk.ResCrosstalkParameters
+  :noindex:
+
+Example
+^^^^^^^
+
+.. code-block:: yaml
+
+    - id: resonator crosstalk
+      operation: resonator_crosstalk
+      targets: [2]
+      parameters:
+        bias_point:
+            2: 0.5
+        bias_step: 0.01
+        bias_width: 0.4
+        flux_qubits: [0, 3]
+        freq_step: 100000
+        freq_width: 6000000
+        nshots: 2000
+
+.. image:: resonator_crosstalk.png
+
+As we can see, even by biasing the qubit away from its sweetspot we are not able to see
+a dependence ( a deviation from the straight line) but only a shift.
+
+The protocols aims at extracting the crosstalk coefficients
+:math:`C_{20}` and :math:`C_{23}`.
+
+Requirements
+^^^^^^^^^^^^
+
+- :ref:`resonator_flux`