qiboteam · jevillegasdatTII · Nov 20, 2024 · Nov 20, 2024 · Nov 20, 2024 · Nov 20, 2024
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
diff --git a/.pre-commit-config.yaml b/.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.6.0
+    rev: v5.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -11,20 +11,20 @@ repos:
       - id: check-merge-conflict
       - id: debug-statements
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 25.1.0
     hooks:
       - id: black
   - repo: https://github.com/pycqa/isort
-    rev: 5.13.2
+    rev: 6.0.0
     hooks:
       - id: isort
         args: ["--profile", "black"]
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.17.0
+    rev: v3.19.1
     hooks:
       - id: pyupgrade
   - repo: https://github.com/hadialqattan/pycln
-    rev: v2.4.0
+    rev: v2.5.0
     hooks:
       - id: pycln
         args:

diff --git a/README.md b/README.md
@@ -59,9 +59,9 @@ targets: [0]
 
 ```
 ### How to run protocols
-To run the protocols specified in the ```runcard```, Qibocal uses the `qq auto` command
+To run the protocols specified in the ```runcard```, Qibocal uses the `qq run` command
 ```sh
-qq auto <runcard> -o <output_folder>
+qq run <runcard> -o <output_folder>
 ```
 if ```<output_folder>``` is specified, the results will be saved in it, otherwise ```qq``` will automatically create a default folder containing the current date and the username.
 
@@ -81,5 +81,9 @@ Feel free to check
 [![DOI](https://zenodo.org/badge/511836317.svg)](https://zenodo.org/badge/latestdoi/511836317)
 
 
-
 If you use the package please refer to [the documentation](https://qibo.science/qibo/stable/appendix/citing-qibo.html#publications) for citation instructions
+
+## Ongoing development
+
+A non-exhaustive list of possible protocols to be implemented in Qibocal is collected
+[here](doc/dev/README.md).
diff --git a/runcards/.gitignore → calibration_scripts/.gitignore b/runcards/.gitignore → calibration_scripts/.gitignore
diff --git a/calibration_scripts/README.md b/calibration_scripts/README.md
@@ -0,0 +1,3 @@
+# Runcards
+
+The following folder contains examples of Qibocal scripts.
diff --git a/runcards/rx_calibration.py → calibration_scripts/rx_calibration.py b/runcards/rx_calibration.py → calibration_scripts/rx_calibration.py
diff --git a/runcards/single_shot.py → calibration_scripts/single_shot.py b/runcards/single_shot.py → calibration_scripts/single_shot.py
diff --git a/doc/dev/README.md b/doc/dev/README.md
@@ -0,0 +1,39 @@
+# Qibocal Roadmap
+
+### High Priority
+#### Single qubit
+
+- Rabi and flipping to calibrate pi/2 rotations (https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf par. 5.9)
+- Kernels for integration
+- Drag with detuning  (https://arxiv.org/pdf/1904.06560)
+- Cross-entropy benchmarking
+- SNR in spectroscopies and SNR in the IQ plane
+  https://dsp.stackexchange.com/questions/24372/what-is-the-connection-between-analog-signal-to-noise-ratio-and-signal-to-noise.
+  https://arxiv.org/pdf/2106.06173.pdf
+- Improve readout amplitude optimization with the outliers probability
+(https://escholarship.org/content/qt0g29b4p0/qt0g29b4p0.pdf?t=prk0gj)
+- Cryoscope (https://arxiv.org/pdf/1907.04818, https://github.com/qua-platform/qua-libs/blob/main/Quantum-Control-Applications/Superconducting/Single-Flux-Tunable-Transmon/Use%20Case%201%20-%20Paraoanu%20Lab%20-%20Cryoscope/readme.md)
+- Optimal control with randomize benchmarking (https://arxiv.org/pdf/1403.0035)
+
+#### Two qubits
+
+- Cross resonance gates (https://journals.aps.org/prb/abstract/10.1103/PhysRevB.81.134507)
+- SNZ / Martini Ansatz (https://arxiv.org/pdf/2008.07411 https://arxiv.org/pdf/1402.5467)
+- Improve and test coupler routines
+- Measure ZZ coupling in couplers (flux amplitude vs coupling) (Manenti Motta, par. 14.8.4)
+- Improve and test iSWAP implementation
+
+### Low Priority
+#### Single Qubit
+
+- Calibrate the other qubit states
+- Carr-Purcell-Meiboom_Gill sequence
+- Explore cosine pulse as X pulse (https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf par. 5.4)
+- Active reset
+- Measurement tomography https://arxiv.org/pdf/1310.6448.pdf
+- XY-Z timing
+(https://escholarship.org/content/qt0g29b4p0/qt0g29b4p0.pdf?t=prk0gj par. 5.10)
+- Quantum volume
+- Gate Set Tomography
+- Process Tomography
+- Study Qubit AC-Stark effect
diff --git a/doc/source/getting-started/example.rst b/doc/source/getting-started/example.rst
@@ -24,11 +24,9 @@ presented in :ref:`runcard`, we can use this runcard.
               power_level: high
               nshots: 1024
 
-More examples of runcards are available on `Github <https://github.com/qiboteam/qibocal/tree/main/runcards>`_ .
-
 Run the routine
 ^^^^^^^^^^^^^^^
 
 .. code-block::
 
-    qq auto example.yml -o resonator_spectroscopy_routine
+    qq run example.yml -o resonator_spectroscopy_routine
diff --git a/doc/source/getting-started/interface.rst b/doc/source/getting-started/interface.rst
@@ -60,15 +60,15 @@ regarding the protocols executed.
     qq report <output_folder>
 
 
-``qq auto``
+``qq run``
 ^^^^^^^^^^^
 
-The previous commands are put together using ``qq auto`` which will perform data acquisition, post-processing and report generation.
+The previous commands are put together using ``qq run`` which will perform data acquisition, post-processing and report generation.
 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 run <path_to_runcard> -o <output_folder>
 
 ``qq update``
 ^^^^^^^^^^^^^

diff --git a/doc/source/getting-started/qq_qibocal.svg b/doc/source/getting-started/qq_qibocal.svg
diff --git a/doc/source/protocols/avoided_crossing.png b/doc/source/protocols/avoided_crossing.png
diff --git a/doc/source/protocols/avoided_crossing.rst b/doc/source/protocols/avoided_crossing.rst
@@ -0,0 +1,55 @@
+Avoided crossing
+================
+
+In the avoided crossing experiment the goal is to study the qubit-flux dependency
+of a couple of qubits to precisely tune the interaction between them at specific
+frequencies in order to calibrate the CZ and the iSWAP gates.
+
+In the avoided crossing experiment for CZ qubit gates, the interaction between
+two qubits is controlled by tuning their energy levels such that the :math:`\ket{11}`
+(both qubits in the excited state) and :math:`\ket{02}` (one qubit in the ground state and
+the other in the second excited state) states come into resonance.
+At this resonance point, the energy levels of these states experience an avoided
+crossing, a key phenomenon that enables the controlled-Z (CZ) gate operation.
+By observing the avoided crossing, one can confirm that the coupling between the
+qubits is strong enough to facilitate the necessary interaction for the CZ gate.
+Hence, precise tuning of these states is essential for achieving the correct gate
+operation.
+
+In the avoided crossing experiment for iSWAP qubit gates, the key focus is on
+the interaction between the :math:`\ket{10}` and :math:`\ket{01}` states.
+When tuning the qubits' energy levels, these two states come into resonance,
+creating an avoided crossing, which is the fundamental operation of
+the iSWAP gate.
+
+In this protocol, for each qubit pair we execute a qubit flux dependency of the
+01 and 02 transitions on the qubit with higher frequency and we fit the data to
+find the flux-frequency relationship that we use to estimate the bias needed to
+reach the CZ and iSWAP interaction points.
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass::
+	qibocal.protocols.flux_dependence.avoided_crossing.AvoidedCrossingParameters
+	:noindex:
+
+Example
+^^^^^^^
+
+It follows a runcard example of this experiment.
+
+.. code-block:: yaml
+
+    - id: avoided crossing
+      operation: avoided_crossing
+      parameters:
+        bias_step: 0.01
+        bias_width: 0.2
+        drive_amplitude: 0.5
+        freq_step: 500000
+        freq_width: 100000000
+
+The expected output is the following:
+
+.. image:: avoided_crossing.png
diff --git a/doc/source/protocols/chevron.png b/doc/source/protocols/chevron.png
diff --git a/doc/source/protocols/chevron.rst b/doc/source/protocols/chevron.rst
@@ -0,0 +1,30 @@
+Chevron
+=======
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass::
+    qibocal.protocols.two_qubit_interaction.chevron.chevron.ChevronParameters
+    :noindex:
+
+Example
+^^^^^^^
+
+Below is an example runcard for this experiment.
+
+.. code-block:: yaml
+
+    - id: chevron
+      operation: chevron
+      parameters:
+        amplitude_max_factor: 1.1
+        amplitude_min_factor: 0.9
+        amplitude_step_factor: 0.01
+        duration_max: 51
+        duration_min: 4
+        duration_step: 2
+
+The expected output is the following:
+
+.. image:: chevron.png
diff --git a/doc/source/protocols/coupler/chevron.png b/doc/source/protocols/coupler/chevron.png
diff --git a/doc/source/protocols/coupler/chevron.rst b/doc/source/protocols/coupler/chevron.rst
@@ -0,0 +1,35 @@
+Coupler Chevron
+===============
+
+Parameters
+^^^^^^^^^^
+
+.. autoclass::
+   qibocal.protocols.two_qubit_interaction.chevron.chevron.ChevronParameters
+   :noindex:
+
+
+Example
+^^^^^^^
+
+Below is an example runcard for this experiment.
+
+.. code-block:: yaml
+
+    - id: coupler chevron
+      operation: coupler_chevron
+      parameters:
+        amplitude_max_factor: 1.5
+        amplitude_min_factor: 0.4
+        amplitude_step_factor: 0.005
+        duration_max: 100
+        duration_min: 10
+        duration_step: 2
+        native: CZ
+        nshots: 256
+        relaxation_time: 100000
+
+
+The expected output is the following:
+
+.. image:: chevron.png
diff --git a/doc/source/protocols/dispersive_shift.rst b/doc/source/protocols/dispersive_shift.rst
@@ -55,7 +55,7 @@ It follows an example of the experiment parameters.
         freq_width: 1000000
 
 
-After running `qq auto`, the experiment is executed and the result will looks like
+After running `qq run`, the experiment is executed and the result will looks like
 the following picture.
 
 .. image:: dispersive_shift.png

diff --git a/doc/source/protocols/flux/single.rst b/doc/source/protocols/flux/single.rst
@@ -16,9 +16,8 @@ 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} \,
+.. 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} \,
+    :label: transmon
 
 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,
@@ -76,6 +75,14 @@ The expected output is the following:
 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}`.
+
+.. note::
+
+    From the cosinusoidal term in the transmon equation :math:numref:`transmon`, it is clear that the
+    sweetspot is not unique.
+    In this protocol, Qibocal returns the sweetspot that is closest to the bias
+    that is in the middle of the swept interval.
+
 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`:
 

diff --git a/doc/source/protocols/index.rst b/doc/source/protocols/index.rst
@@ -27,4 +27,12 @@ In this section we introduce the basics of all protocols supported by ``qibocal`
     dispersive_shift
     allxy
     flipping
+    readout_mitigation_matrix
+    avoided_crossing
+    readout_optimization
+    standard_rb
+    chevron
+    virtual_z
+    state_tomographies
+    coupler/chevron
     references
diff --git a/doc/source/protocols/qubit_spectroscopy/qubit_spectroscopy.rst b/doc/source/protocols/qubit_spectroscopy/qubit_spectroscopy.rst
@@ -27,7 +27,7 @@ Parameters
 ^^^^^^^^^^
 
 .. autoclass:: qibocal.protocols.qubit_spectroscopy.QubitSpectroscopyParameters
-
+  :noindex:
 
 How to execute a qubit spectroscopy experiment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -96,6 +96,7 @@ Parameters
 ^^^^^^^^^^
 
 .. autoclass:: qibocal.protocols.qubit_spectroscopy_ef.QubitSpectroscopyEFParameters
+  :noindex:
 
 How to execute a qubit spectroscopy experiment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/doc/source/protocols/rabi/rabi.rst b/doc/source/protocols/rabi/rabi.rst
@@ -60,7 +60,7 @@ It follows an example of the experiment parameters.
 To run properly this experiment it is important to set the
 `relaxation_time` higher than the qubit `T1`.
 
-After running `qq auto`, the experiment is executed and the result will looks like
+After running `qq run`, the experiment is executed and the result will looks like
 the following picture.
 
 .. image:: rabi_amplitude.png
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Runcards

		The following folder contains examples of Qibocal scripts.