[WIP] measurement level 1 for T1 experiment (#857)

* Added check for the metadata as it can be either 'int' or 'tuple'

* Added test to t1 to test level_1_measurment analysis

* fixed test_t1

* Added Kerneled data analysis to t1_analysis

* Added the kerneled analysis to the __init__ files

* Fixed bug in parallel experiments were the key can either be 'qibit' or 'qubits'

* Fixed test for kerneled T1 experiment to use new analysis.

* Added to T1 tutorial section about T1 experiment with kermeled measurement

* fixed indents to match

* fixed lint

* fixed bug in name of the helper

* updated documentation.

* updated per @yaelbh review

* Added extreme delay so the fitting quality will rise

* T1 test kerneled measurement - changed number of shots and delays

* Added to the quality check for the case where a=-1 and b=1

* updated tutorial

* added to the analysis '_format_data'

* changed tests

* fixed normalization bug

fixed normalization calculation
changed the criteria to re-normalization to be average slope greater than 0.

* black

* updated analysis

* added release notes

* fixed releasenotes

Author: ItamarGoldman

docs/tutorials/t1.rst

@@ -31,13 +31,19 @@ for qubit 0.
 .. jupyter-execute::
 
     import numpy as np
+    from qiskit.qobj.utils import MeasLevel
     from qiskit_experiments.framework import ParallelExperiment
     from qiskit_experiments.library import T1
-    
+    from qiskit_experiments.library.characterization.analysis.t1_analysis import T1KerneledAnalysis
+
     # A T1 simulator
     from qiskit.providers.fake_provider import FakeVigo
     from qiskit.providers.aer import AerSimulator
     from qiskit.providers.aer.noise import NoiseModel
+
+    # A kerneled data simulator
+    from qiskit_experiments.test.mock_iq_backend import MockIQBackend
+    from qiskit_experiments.test.mock_iq_helpers import MockIQT1Helper
 
     # Create a pure relaxation noise model for AerSimulator
     noise_model = NoiseModel.from_backend(
@@ -102,6 +108,62 @@ using ``child_data``
         for result in sub_data.analysis_results():
             print(result)
 
+:math:`T_1` experiments with kerneled measurement
+---------------------------------------------------
+:math:`T_1` experiments can also be done with kerneled measurements.
+If we set the run option `meas_level=MeasLevel.KERNELED`, the job
+will not discriminate the data and will not label it. In the T1 experiment,
+since we know that :math:`P(1|t=0)=1`, we will add a circuit with delay=0,
+and another circuit with a very large delay. In this configuration we know that the data starts from
+a point [I,Q] that is close to a logical value '1' and ends at a point [I,Q]
+that is close to a logical value '0'.
+
+
+.. jupyter-execute::
+
+    # Experiment
+    ns = 1e-9
+    mu = 1e-6
+
+    # qubit properties
+    t1 = [45 * mu, 45 * mu]
+    t2 = [value/2 for value in t1]
+
+    # we will guess that our guess is 10% off the exact value of t1 for qubit 0.
+    t1_estimated_shift = t1[0]/10
+
+    # We use log space for the delays because of the noise properties
+    delays = np.logspace(1, 11, num=23, base=np.exp(1))
+    delays *= ns
+
+    # Adding circuits with delay=0 and long delays so the centers in the IQ plane won't be misplaced.
+    # Without this, the fitting can provide wrong results.
+    delays = np.insert(delays, 0, 0)
+    delays = np.append(delays, [t1[0]*3])
+
+    num_qubits = 2
+    num_shots = 2048
+
+    backend = MockIQBackend(
+        MockIQT1Helper(t1=t1, iq_cluster_centers=[((-5.0, -4.0), (-5.0, 4.0)), ((3.0, 1.0), (5.0, -3.0))]
+                           , iq_cluster_width=[1.0, 2.0])
+    )
+
+    # Creating a T1 experiment
+    expT1_kerneled = T1(0, delays)
+    expT1_kerneled.analysis = T1KerneledAnalysis()
+    expT1_kerneled.analysis.set_options(p0={"amp": 1, "tau": t1[0] + t1_estimated_shift, "base": 0})
+
+    # Running the experiment
+    expdataT1_kerneled = expT1_kerneled.run(backend=backend, meas_return="avg",
+                                            meas_level=MeasLevel.KERNELED,
+                                            shots=num_shots).block_for_results()
+
+    # Displaying results
+    display(expdataT1_kerneled.figure(0))
+    for result in expdataT1_kerneled.analysis_results():
+        print(result)
+
 .. jupyter-execute::
 
     import qiskit.tools.jupyter

qiskit_experiments/library/characterization/__init__.py

@@ -57,6 +57,7 @@
     :template: autosummary/analysis.rst
 
     T1Analysis
+    T1KerneledAnalysis
     T2RamseyAnalysis
     T2HahnAnalysis
     TphiAnalysis
@@ -81,6 +82,7 @@
     RamseyXYAnalysis,
     T2RamseyAnalysis,
     T1Analysis,
+    T1KerneledAnalysis,
     T2HahnAnalysis,
     TphiAnalysis,
     CrossResonanceHamiltonianAnalysis,

qiskit_experiments/library/characterization/analysis/__init__.py

@@ -21,6 +21,7 @@
 from .t2ramsey_analysis import T2RamseyAnalysis
 from .t2hahn_analysis import T2HahnAnalysis
 from .t1_analysis import T1Analysis
+from .t1_analysis import T1KerneledAnalysis
 from .tphi_analysis import TphiAnalysis
 from .cr_hamiltonian_analysis import CrossResonanceHamiltonianAnalysis
 from .readout_angle_analysis import ReadoutAngleAnalysis

qiskit_experiments/library/characterization/analysis/t1_analysis.py

@@ -14,8 +14,12 @@
 """
 from typing import Union
 
+import numpy as np
+from uncertainties import unumpy as unp
+
 import qiskit_experiments.curve_analysis as curve
 from qiskit_experiments.framework import Options
+from qiskit_experiments.curve_analysis.curve_data import CurveData
 
 
 class T1Analysis(curve.DecayAnalysis):
@@ -67,3 +71,84 @@ def _evaluate_quality(self, fit_data: curve.CurveFitResult) -> Union[str, None]:
             return "good"
 
         return "bad"
+
+
+class T1KerneledAnalysis(curve.DecayAnalysis):
+    r"""A class to analyze T1 experiments with kerneled data.
+
+    # section: see_also
+        qiskit_experiments.curve_analysis.standard_analysis.decay.DecayAnalysis
+
+    """
+
+    @classmethod
+    def _default_options(cls) -> Options:
+        """Default analysis options."""
+        options = super()._default_options()
+        options.curve_drawer.set_options(
+            xlabel="Delay",
+            ylabel="Normalized Projection on the Main Axis",
+            xval_unit="s",
+        )
+        options.result_parameters = [curve.ParameterRepr("tau", "T1", "s")]
+        options.normalization = True
+
+        return options
+
+    def _evaluate_quality(self, fit_data: curve.CurveFitResult) -> Union[str, None]:
+        """Algorithmic criteria for whether the fit is good or bad.
+
+        A good fit has:
+            - a reduced chi-squared lower than three
+            - absolute amp is within [0.9, 1.1]
+            - base is less than 0.1
+            - amp error is less than 0.1
+            - tau error is less than its value
+            - base error is less than 0.1
+        """
+        amp = fit_data.ufloat_params["amp"]
+        tau = fit_data.ufloat_params["tau"]
+        base = fit_data.ufloat_params["base"]
+
+        criteria = [
+            fit_data.reduced_chisq < 3,
+            abs(amp.nominal_value - 1.0) < 0.1,
+            abs(base.nominal_value) < 0.1,
+            curve.utils.is_error_not_significant(amp, absolute=0.1),
+            curve.utils.is_error_not_significant(tau),
+            curve.utils.is_error_not_significant(base, absolute=0.1),
+        ]
+
+        if all(criteria):
+            return "good"
+
+        return "bad"
+
+    def _format_data(
+        self,
+        curve_data: curve.CurveData,
+    ) -> curve.CurveData:
+        """Postprocessing for the processed dataset.
+
+        Args:
+            curve_data: Processed dataset created from experiment results.
+
+        Returns:
+            Formatted data.
+        """
+        # check if the SVD decomposition categorized 0 as 1 by calculating the average slope
+        diff_y = np.diff(unp.nominal_values(curve_data.y), axis=0)
+        avg_slope = sum(diff_y) / len(diff_y)
+        if avg_slope[0] > 0:
+            new_y_data = 1 - curve_data.y
+            new_curve_data = CurveData(
+                x=curve_data.x,
+                y=new_y_data,
+                y_err=curve_data.y_err,
+                shots=curve_data.shots,
+                data_allocation=curve_data.data_allocation,
+                labels=curve_data.labels,
+            )
+
+            return super()._format_data(new_curve_data)
+        return super()._format_data(curve_data)

qiskit_experiments/test/mock_iq_helpers.py

@@ -378,6 +378,7 @@ def _parallel_exp_circ_splitter(self, qc_list: List[QuantumCircuit]):
         Raises:
             QiskitError: If an instruction is applied with qubits that don't belong to the same
             experiment.
+            TypeError: The data type provided doesn't match the expected type (`tuple` or `int`).
         """
         # exp_idx_map connects an experiment to its circuit in the output.
         exp_idx_map = {exp: exp_idx for exp_idx, exp in enumerate(self.exp_list)}
@@ -401,8 +402,22 @@ def _parallel_exp_circ_splitter(self, qc_list: List[QuantumCircuit]):
 
             # fixing metadata
             for exp_metadata in qc.metadata["composite_metadata"]:
-                # getting a qubit of one of the experiments that we ran in parallel
-                exp = qubit_exp_map[exp_metadata["qubits"][0]]
+                # getting a qubit of one of the experiments that we ran in parallel. The key in the
+                # metadata is different for different experiments.
+                qubit_metadata = (
+                    exp_metadata.get("qubit")
+                    if exp_metadata.get("qubit") is not None
+                    else exp_metadata.get("qubits")
+                )
+                if isinstance(qubit_metadata, tuple):
+                    exp = qubit_exp_map[qubit_metadata[0]]
+                elif isinstance(qubit_metadata, int):
+                    exp = qubit_exp_map[qubit_metadata]
+                else:
+                    raise TypeError(
+                        f"The qubit information in the metadata is of type {type(qubit_metadata)}."
+                        f" Supported formats are `tuple` and `int`"
+                    )
                 # using the qubit to access the experiment. Then, we go to the last circuit in
                 # `exp_circuit` of the corresponding experiment, and we overwrite the metadata.
                 exp_circuits_list[exp_idx_map[exp]][-1].metadata = exp_metadata.copy()
@@ -823,3 +838,35 @@ def compute_probabilities(self, circuits: List[QuantumCircuit]) -> List[Dict[str
             output_dict_list.append(probability_output_dict)
 
         return output_dict_list
+
+
+class MockIQT1Helper(MockIQExperimentHelper):
+    """Functions needed for T1 experiment on mock IQ backend"""
+
+    def __init__(
+        self,
+        t1: List[float] = None,
+        iq_cluster_centers: Optional[List[Tuple[IQPoint, IQPoint]]] = None,
+        iq_cluster_width: Optional[List[float]] = None,
+    ):
+        super().__init__(iq_cluster_centers, iq_cluster_width)
+        self._t1 = t1 or [90e-6]
+
+    def compute_probabilities(self, circuits: List[QuantumCircuit]) -> List[Dict[str, float]]:
+        """Return the probability of being in the excited state."""
+        output_dict_list = []
+        for circuit in circuits:
+            probability_output_dict = {}
+
+            # extracting information from the circuit.
+            qubit_idx = circuit.metadata["qubit"]
+            delay = circuit.metadata["xval"]
+
+            # creating a probability dict.
+            if qubit_idx >= len(self._t1):
+                raise QiskitError(f"There is no 'T1' value for qubit index {qubit_idx}.")
+            probability_output_dict["1"] = np.exp(-delay / self._t1[qubit_idx])
+            probability_output_dict["0"] = 1 - probability_output_dict["1"]
+            output_dict_list.append(probability_output_dict)
+
+        return output_dict_list

releasenotes/notes/T1_experiment_level_1_mesurment_analysis-078db79e3b0c16b9.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Added new class :class:`.T1KerneledAnalysis`. This class is used for T1
+    Experiment with the option `meas_level=MeasLevel.KERNELED`. The analysis
+    normalizes the data and fixes its orientation.