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/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`

doc/source/protocols/flux/single.rst

@@ -0,0 +1,173 @@
+.. _flux:
+
+Frequency vs flux experiments
+=============================
+
+In this section we show how to run experiments to study
+the flux dependence.
+
+Flux-tunable transmons
+----------------------
+
+It can be shown for flux-tunable transmons that applying an external flux
+:math:`\Phi` induces to a detuning on the transmon frequency :cite:p:`Koch_2007`.
+By applying short flux pulses it is possible to tune the transmon frequency in order
+of GHz, which leads to several applications including quantum logical gates.
+
+The transmon frequency as a function of the external flux can be expressed as :cite:p:`Barrett_2023`
+
+.. math::
+
+    f_q(\Phi) = \Bigg( f_q^{\text{max}} + \frac{E_C}{h} \Bigg)  \sqrt[4]{d^2 + (1-d^2)\cos^2\Big( \pi \frac{\Phi}{\Phi_0}\Big)} - \frac{E_C}{h} \,
+
+where :math:`f_{\text{max}} = ( \sqrt{8 E_C E_J} - E_C) / h` is the maximum qubit frequency,
+:math:`d` is the junctions asymmetry, :math:`E_C` is the charging energy,
+:math:`E_J` is the Josephson energy and :math:`\Phi_0 = h / (2e)` is the flux quanta.
+
+The resonator detuning in the transmon regime :math:`E_J \gg E_C` can be computed as
+
+.. math::
+
+    f_r(\Phi) = f_r^{\text{bare}} + g_0^2 \frac{\sqrt[4]{d^2 + (1-d^2)\cos^2\Big( \pi \frac{\Phi}{\Phi_0}\Big)}}{f_r^{\text{bare}} - f_q(\Phi)} \,
+
+where :math:`f_r^{\text{bare}}` is the bare frequency of the resonator and :math:`g_0^2` is the
+coupling between the transmon and the resonator.
+
+In Qibocal we provide two experiments to measure and fit the curves described by the two equations
+above. To measure the qubit detuning a 2D sweep is performed probing the systems at different drive frequencies
+and at different flux (bias) offset values. For the resonator we perform the same experiment
+by sweeping the readout frequency instead of the drive frequency.
+
+.. _qubit_flux:
+
+Qubit flux dependence
+---------------------
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.flux_dependence.qubit_flux_dependence.QubitFluxParameters
+  :noindex:
+
+Example
+^^^^^^^
+
+A possible runcard to assess how the qubit frequency changes by varying flux is the following:
+
+.. code-block:: yaml
+
+    - id: qubit flux dependence
+      operation: qubit_flux
+      parameters:
+        bias_step: 0.001
+        bias_width: 0.05
+        drive_amplitude: 0.002
+        drive_duration: 4000
+        freq_step: 200000
+        freq_width: 10000000
+        nshots: 1024
+        relaxation_time: 20000
+
+
+The expected output is the following:
+
+.. image:: qubit_flux.png
+
+From the acquired data this protocol estimates the flux insensitive point "sweetspot",
+which corresponds to the flux value where the frequency is maximed, as well as the drive frequency
+and the diagonal crosstalk coefficient :math:`V_{ii}`.
+Both the sweetspot and the :math:`C_{ii}` can be understood by writing the full expression for
+the flux felt by qubit :math:`i` :cite:p:`Barrett_2023`:
+
+.. math::
+
+    \Phi_i = \sum_{j} C_{ij} V_j +  \Phi_i^{\text{offset}} \,
+
+where :math:`C_{ij}` is known in the literature as the crosstalk matrix, while
+:math:`V_{i}` is the applied voltage.
+
+Requirements
+^^^^^^^^^^^^
+
+- :ref:`qubit_spectroscopy`
+
+.. _resonator_flux:
+
+Resonator flux dependence
+-------------------------
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.flux_dependence.resonator_flux_dependence.ResonatorFluxParameters
+  :noindex:
+
+Example
+^^^^^^^
+
+A possible runcard to assess how the resonator frequency changes by varying flux is the following:
+
+.. code-block:: yaml
+
+    - id: resonator flux dependence
+      operation: resonator_flux
+      parameters:
+        bias_step: 0.01
+        bias_width: 0.4
+        freq_step: 100000
+        freq_width: 6000000
+        nshots: 2000
+        relaxation_time: 1000
+
+
+From this protocol it is possible to extract both the bare and the dressed resonator frequency
+as well as an estimate for the coupling :math:`g_0`.
+It is suggested to run this protocol only after executing the qubit flux dependence experiment
+since some of the coefficients required can be computed with that experiment.
+
+
+.. image:: resonator_flux.png
+
+Requirements
+^^^^^^^^^^^^
+
+- :ref:`resonator_punchout`
+- :ref:`qubit_flux`
+
+Qubit flux dependence (tracking)
+--------------------------------
+
+As we saw above both the resonator and the qubit are affected by an external flux.
+In the qubit flux dependence the measurement is performed at fixed readout frequency.
+To take into account how the transmon shifts in frequency when probing the qubit we have
+another experiment `qubit_flux_tracking`.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass:: qibocal.protocols.flux_dependence.qubit_flux_tracking.QubitFluxTrackParameters
+  :noindex:
+
+Example
+^^^^^^^
+
+Here is a possible runcard:
+
+.. code-block:: yaml
+
+    - id: qubit flux dependence
+      operation: qubit_flux_tracking
+      parameters:
+        bias_step: 0.001
+        bias_width: 0.05
+        drive_amplitude: 0.002
+        drive_duration: 4000
+        freq_step: 200000
+        freq_width: 10000000
+        nshots: 1024
+        relaxation_time: 20000
+
+Requirements
+^^^^^^^^^^^^
+
+- :ref:`resonator_flux`

doc/source/protocols/index.rst

@@ -1,10 +1,25 @@
 Protocols
 =========
 
+Here is a scheme with the protocols currently available in Qibocal.
+
+
+.. image:: ../getting-started/qpu_characterization.svg
+
 In this section we introduce the basics of all protocols supported by ``qibocal``.
 
 .. toctree::
     :maxdepth: 1
 
+    signal/time_of_flight
+    signal/calibrate_kernel
     resonator_spectroscopy
     resonator_punchout
+    qubit_spectroscopy/qubit_spectroscopy
+    ramsey/ramsey
+    t1/t1
+    t2/t2
+    t2_echo/t2_echo
+    flux/single
+    flux/crosstalk
+    references