Merge branch 'main' into mermin

.github/workflows/deploy.yml

@@ -13,7 +13,7 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: [3.9, "3.10", "3.11"]
-    uses: qiboteam/workflows/.github/workflows/deploy-pip-poetry.yml@main
+    uses: qiboteam/workflows/.github/workflows/deploy-pip-poetry.yml@v1
     with:
       os: ${{ matrix.os }}
       python-version: ${{ matrix.python-version }}

.github/workflows/publish.yml

@@ -28,7 +28,7 @@ jobs:
 
   deploy-docs:
     needs: [evaluate-label]
-    uses: qiboteam/workflows/.github/workflows/deploy-ghpages-latest-stable.yml@main
+    uses: qiboteam/workflows/.github/workflows/deploy-ghpages-latest-stable.yml@v1
     with:
       python-version: "3.10"
       package-manager: "poetry"

.github/workflows/tests.yml

@@ -11,7 +11,7 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: [3.9, "3.10", "3.11"]
-    uses: qiboteam/workflows/.github/workflows/rules-poetry.yml@main
+    uses: qiboteam/workflows/.github/workflows/rules-poetry.yml@v1
     with:
       os: ${{ matrix.os }}
       python-version: ${{ matrix.python-version }}

.gitignore

@@ -3,6 +3,10 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# test outputs
+cls_result/
+qubit*/
+
 # C extensions
 *.so
 

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -11,7 +11,7 @@ repos:
       - id: check-merge-conflict
       - id: debug-statements
   - repo: https://github.com/psf/black
-    rev: 24.3.0
+    rev: 24.8.0
     hooks:
       - id: black
   - repo: https://github.com/pycqa/isort
@@ -20,7 +20,7 @@ repos:
       - id: isort
         args: ["--profile", "black"]
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.1
+    rev: v3.17.0
     hooks:
       - id: pyupgrade
   - repo: https://github.com/hadialqattan/pycln

README.md

@@ -7,8 +7,6 @@ Qibocal provides Quantum Characterization Validation and Verification protocols
 
 Qibocal key features:
 
-- Automatization of calibration protocols.
-
 - Declarative inputs using runcard.
 
 - Generation of a report.
@@ -47,18 +45,17 @@ For our purposes, we can use the following:
 ```yml
 platform: tii1q
 
-qubits: [0]
+targets: [0]
 
 - id: resonator spectroscopy high power
-  priority: 0
   operation: resonator_spectroscopy
   parameters:
     freq_width: 10_000_000
     freq_step: 500_000
     amplitude: 0.4
     power_level: high
     nshots: 1024
-    relaxation_time: 0
+    relaxation_time: 5_000
 
 ```
 ### How to run protocols

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/interface.rst

@@ -42,6 +42,11 @@ This command is used to perform a post-processing analysis on a given output fol
 
     qq fit <output_folder>
 
+If the ``<output-folder>`` already contains post-processing files they can be overwritten using ``-f``.
+It is also possible to generate a separate folder with the output folder generated by qibocal with
+the updated fitting parameters using ``-o <new_output_folder>``. If such folder exists it can be
+overwritten with ``-f``.
+
 
 
 ``qq report``
@@ -59,13 +64,26 @@ regarding the protocols executed.
 ^^^^^^^^^^^
 
 The previous commands are put together using ``qq auto`` which will perform data acquisition, post-processing and report generation.
-When executing multiple protocols they are executed following the graph described in the action runcard.
-The report is generated iteratively as soon as each protocol finished.
+When executing multiple protocols they are executed following the actions specified in the runcard.
 
 .. code-block::
 
     qq auto <path_to_runcard> -o <output_folder>
 
+``qq update``
+^^^^^^^^^^^^^
+Using ``qq update`` it is possible to update the platform calibrated by Qibocal.
+The correct syntax is the following
+
+.. code-block::
+
+    qq update <output_folder>
+
+which will copy the configuration of the platform in the corresponding
+directory specified using the environment variable  ``QIBOLAB_PLATFORMS``.
+See the Qibolab `documentation <https://qibo.science/qibolab/stable/tutorials/lab.html#how-to-connect-qibolab-to-your-lab>`_ for more details.
+
+
 ``qq upload``
 ^^^^^^^^^^^^^
 
@@ -84,3 +102,18 @@ your public ssh key (from the machine(s) you are planning to upload the report)
 use the ``qq upload <output_folder>`` command.
 You can also add a tag to be displayed on the server using ``qq upload <output_folder> --tag <tag_name>``.
 This program will upload your report to the server and generate an unique URL.
+
+
+``qq compare``
+^^^^^^^^^^^^^
+
+
+Using ``qq compare`` it is possible to compare together two ``Qibocal`` reports.
+
+.. code-block::
+
+    qq compare <output_folder_1> <output_folder_2>
+
+
+The folder with the report comparison can be specified with the option ``-o``, otherwise a default
+name will be assigned similarly to the ``qq acquire`` command.

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/index.rst

@@ -41,13 +41,17 @@ Contents
     :maxdepth: 2
     :caption: Introduction
 
-    getting-started/index
+    getting-started/installation
+    getting-started/interface
+    getting-started/runcard
+    getting-started/example
 
 .. toctree::
     :maxdepth: 2
-    :caption: Tutorials
+    :caption: Guides
 
     tutorials/index
+    protocols/index
 
 .. toctree::
     :maxdepth: 2

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`