Rework of Stark module and workflow

docs/apidocs/index.rst

@@ -30,6 +30,7 @@ Experiment Modules
 
     mod_calibration
     mod_characterization
+    mod_driven_freq_tuning
     mod_randomized_benchmarking
     mod_tomography
     mod_quantum_volume

docs/apidocs/mod_driven_freq_tuning.rst

@@ -0,0 +1,6 @@
+.. _qiskit-experiments-driven-freq-tuning:
+
+.. automodule:: qiskit_experiments.library.driven_freq_tuning
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/manuals/characterization/stark_experiment.rst

@@ -211,6 +211,110 @@ In Qiskit Experiments, the experiment option ``stark_amp`` usually refers to
 the height of this GaussianSquare flat-top.
 
 
+Workflow
+--------
+
+In this example, you'll learn how to measure a spectrum of qubit relaxation versus
+frequency with fixed frequency transmons.
+As you already know, we give an offset to the qubit frequency with a Stark tone,
+and the workflow starts from characterizing the amount of the Stark shift against
+the Stark amplitude :math:`\bar{\Omega}` that you can experimentally control.
+
+.. jupyter-input::
+
+    from qiskit_experiments.library.driven_freq_tuning import StarkRamseyXYAmpScan
+
+    exp = StarkRamseyXYAmpScan((0,), backend=backend)
+    exp_data = exp.run().block_for_results()
+    coefficients = exp_data.analysis_results("stark_coefficients").value
+
+You first need to run the :class:`.StarkRamseyXYAmpScan` experiment that scans :math:`\bar{\Omega}`
+and estimates the amount of the resultant frequency shift.
+This experiment fits the frequency shift to a polynomial model which is a function of :math:`\bar{\Omega}`.
+You can obtain the :class:`.StarkCoefficients` object that contains
+all polynomial coefficients to map and reverse-map the :math:`\bar{\Omega}` to a corresponding frequency value.
+
+This object may be necessary for the following spectroscopy experiment.
+Since Stark coefficients are stable for a relatively long time,
+you may want to save the coefficient values and load them later when you run the experiment.
+If you have an access to the Experiment service, you can just save the experiment result.
+
+.. jupyter-input::
+
+    exp_data.save()
+
+.. jupyter-output::
+
+    You can view the experiment online at https://quantum.ibm.com/experiments/23095777-be28-4036-9c98-89d3a915b820
+
+
+Otherwise, you can dump the coefficient object into a file with JSON format.
+
+.. jupyter-input::
+
+    import json
+    from qiskit_experiments.framework import ExperimentEncoder
+
+    with open("coefficients.json", "w") as fp:
+        json.dump(ret_coeffs, fp, cls=ExperimentEncoder)
+
+The saved object can be retrieved either from the service or file, as follows.
+
+.. jupyter-input::
+
+    # When you have access to Experiment service
+    from qiskit_experiments.library.driven_freq_tuning import retrieve_coefficients_from_backend
+
+    coefficients = retrieve_coefficients_from_backend(backend, 0)
+
+    # Alternatively you can load from file
+    from qiskit_experiments.framework import ExperimentDecoder
+
+    with open("coefficients.json", "r") as fp:
+        coefficients = json.load(fp, cls=ExperimentDecoder)
+
+Now you can measure the qubit relaxation spectrum.
+The :class:`.StarkP1Spectroscopy` experiment also scans :math:`\bar{\Omega}`,
+but instead of measuring the frequency shift, it measures the excited state population P1
+after certain delay, :code:`t1_delay` in the experiment options, following the state population.
+You can scan the :math:`\bar{\Omega}` values either in the "frequency" or "amplitude" domain,
+but the :code:`stark_coefficients` option must be set to perform the frequency sweep.
+
+.. jupyter-input::
+
+    from qiskit_experiments.library.driven_freq_tuning import StarkP1Spectroscopy
+
+    exp = StarkP1Spectroscopy((0,), backend=backend)
+
+    exp.set_experiment_options(
+        t1_delay=20e-6,
+        min_xval=-20e6,
+        max_xval=20e6,
+        xval_type="frequency",
+        spacing="linear",
+        stark_coefficients=coefficients,
+    )
+
+    exp_data = exp.run().block_for_results()
+
+You may find notches in the P1 spectrum, which may indicate the existence of TLS's
+in the vicinity of your qubit drive frequency.
+
+.. jupyter-input::
+
+    exp_data.figure(0)
+
+.. image:: ./stark_experiment_example.png
+
+Note that this experiment doesn't yield any analysis result because the landscape of a P1 spectrum
+can not be predicted due to the random occurrences of the TLS and frequency collisions.
+If you have your own protocol to extract meaningful quantities from the data,
+you can write a custom analysis subclass and give it to the experiment instance before execution.
+See :class:`.StarkP1SpectAnalysis` for more details.
+
+This protocol can be parallelized among many qubits unless crosstalk matters.
+
+
 References
 ----------
 

qiskit_experiments/__init__.py

@@ -49,6 +49,7 @@
 
 - :mod:`qiskit_experiments.library.calibration`
 - :mod:`qiskit_experiments.library.characterization`
+- :mod:`qiskit_experiments.library.driven_freq_tuning`
 - :mod:`qiskit_experiments.library.randomized_benchmarking`
 - :mod:`qiskit_experiments.library.tomography`
 """

qiskit_experiments/library/__init__.py

@@ -76,8 +76,9 @@
     ~characterization.FineXDrag
     ~characterization.FineSXDrag
     ~characterization.MultiStateDiscrimination
-    ~characterization.StarkRamseyXY
-    ~characterization.StarkRamseyXYAmpScan
+    ~driven_freq_tuning.StarkRamseyXY
+    ~driven_freq_tuning.StarkRamseyXYAmpScan
+    ~driven_freq_tuning.StarkP1Spectroscopy
 
 .. _characterization two qubits:
 
@@ -160,7 +161,6 @@ class instance to manage parameters and pulse schedules.
 )
 from .characterization import (
     T1,
-    StarkP1Spectroscopy,
     T2Hahn,
     T2Ramsey,
     Tphi,
@@ -187,8 +187,6 @@ class instance to manage parameters and pulse schedules.
     CorrelatedReadoutError,
     ZZRamsey,
     MultiStateDiscrimination,
-    StarkRamseyXY,
-    StarkRamseyXYAmpScan,
 )
 from .randomized_benchmarking import StandardRB, InterleavedRB
 from .tomography import (
@@ -199,6 +197,11 @@ class instance to manage parameters and pulse schedules.
     MitigatedProcessTomography,
 )
 from .quantum_volume import QuantumVolume
+from .driven_freq_tuning import (
+    StarkRamseyXY,
+    StarkRamseyXYAmpScan,
+    StarkP1Spectroscopy,
+)
 
 # Experiment Sub-modules
 from . import calibration

qiskit_experiments/library/characterization/__init__.py

@@ -24,7 +24,6 @@
     :template: autosummary/experiment.rst
 
     T1
-    StarkP1Spectroscopy
     T2Ramsey
     T2Hahn
     Tphi
@@ -50,8 +49,6 @@
     ResonatorSpectroscopy
     MultiStateDiscrimination
     ZZRamsey
-    StarkRamseyXY
-    StarkRamseyXYAmpScan
 
 
 Analysis
@@ -63,15 +60,13 @@
 
     T1Analysis
     T1KerneledAnalysis
-    StarkP1SpectAnalysis
     T2RamseyAnalysis
     T2HahnAnalysis
     TphiAnalysis
     CrossResonanceHamiltonianAnalysis
     DragCalAnalysis
     FineAmplitudeAnalysis
     RamseyXYAnalysis
-    StarkRamseyXYAmpScanAnalysis
     ReadoutAngleAnalysis
     ResonatorSpectroscopyAnalysis
     LocalReadoutErrorAnalysis
@@ -85,8 +80,6 @@
     DragCalAnalysis,
     FineAmplitudeAnalysis,
     RamseyXYAnalysis,
-    StarkRamseyXYAmpScanAnalysis,
-    StarkP1SpectAnalysis,
     T2RamseyAnalysis,
     T1Analysis,
     T1KerneledAnalysis,
@@ -101,7 +94,7 @@
     MultiStateDiscriminationAnalysis,
 )
 
-from .t1 import T1, StarkP1Spectroscopy
+from .t1 import T1
 from .qubit_spectroscopy import QubitSpectroscopy
 from .ef_spectroscopy import EFSpectroscopy
 from .t2ramsey import T2Ramsey
@@ -111,7 +104,7 @@
 from .rabi import Rabi, EFRabi
 from .half_angle import HalfAngle
 from .fine_amplitude import FineAmplitude, FineXAmplitude, FineSXAmplitude, FineZXAmplitude
-from .ramsey_xy import RamseyXY, StarkRamseyXY, StarkRamseyXYAmpScan
+from .ramsey_xy import RamseyXY
 from .fine_frequency import FineFrequency
 from .drag import RoughDrag
 from .readout_angle import ReadoutAngle

qiskit_experiments/library/characterization/analysis/__init__.py

@@ -14,10 +14,10 @@
 
 from .drag_analysis import DragCalAnalysis
 from .fine_amplitude_analysis import FineAmplitudeAnalysis
-from .ramsey_xy_analysis import RamseyXYAnalysis, StarkRamseyXYAmpScanAnalysis
+from .ramsey_xy_analysis import RamseyXYAnalysis
 from .t2ramsey_analysis import T2RamseyAnalysis
 from .t2hahn_analysis import T2HahnAnalysis
-from .t1_analysis import T1Analysis, T1KerneledAnalysis, StarkP1SpectAnalysis
+from .t1_analysis import T1Analysis, T1KerneledAnalysis
 from .tphi_analysis import TphiAnalysis
 from .cr_hamiltonian_analysis import CrossResonanceHamiltonianAnalysis
 from .readout_angle_analysis import ReadoutAngleAnalysis