Add minimal working code expample in experiment API docs (qiskit-comm…

…unity#1433)

### Summary

This change adds minimal working code examples to the API pages for each
experiment,especially in characterizaion experiments. The minimal
working code example is a code snippet which users can copy and paste to
run the experiment.

### Details and comments

- This change solves the `issue#1238` (See also the `issue#1221`).
- In the API pages, the documentation for each experiment has been
updated with its code example. Users are required to specify a backend
in the code example. As a default, the backend is a simulator such as
`GenericBackendV2(num_qubits=27)`.
- In some experiments,
`CorrelatedReadoutError` 
`ResonatorSpectroscopy` 
`CrossResonanceHamiltonian` and 
`EchoedCrossResonanceHamiltonian`, 
the backend is an IBM Quantum real device due to the
`backend.defaults()` dependence of the code example.
In these cases, the code example explicitly imports the module
`qiskit-ibm-provider` in order to retrieve the job on IBM Quantum real
devices.
Therefore, `requirements-dev.txt` has been updated to add the dependency
on `qiskit-ibm-provider` for running tests and building documentation.


### PR checklist (template)

- [x] I have read the contributing guide `CONTRIBUTING.md`.
- [ ] I have added the tests to cover my changes.
- [x] I have updated the documentation accordingly.
- [x] I have added a release note file using `reno` if this change needs
to be documented in the release notes.


### PR checklist (additional in CONTRIBUTING.md)

- [x] The code follows the code style of the project and successfully
passes the tests.
- [x] The API documentation has been updated accordingly.
- [x] You have updated the relevant documentation or written new docs.
In case the PR needs
to be merged without delay (e.g. for a high priority fix), open an issue
for updating
      or adding the documentation later.
- [] You've added tests that cover the changes you've made, if relevant.
- [] If your change has an end user facing impact (new feature,
deprecation, removal,
etc.), you've added or updated a reno release note for that change and
tagged the PR
     for the changelog.
- [x] If your code requires a change to dependencies, you've updated the
corresponding
      requirements file: `requirements.txt` for core dependencies,
`requirements-extras.txt` for dependencies for optional features, and
`requirements-dev.txt`
for dependencies required for running tests and building documentation.

---------

Co-authored-by: 中澤 直仁 <[email protected]>

qiskit_experiments/library/characterization/correlated_readout_error.py

@@ -73,6 +73,27 @@ class CorrelatedReadoutError(BaseExperiment):
     # section: analysis_ref
         :class:`CorrelatedReadoutErrorAnalysis`
 
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            from qiskit.providers.fake_provider import GenericBackendV2
+            from qiskit_aer import AerSimulator
+
+            num_qubits=5
+            backend = AerSimulator.from_backend(GenericBackendV2(num_qubits=num_qubits,
+                                                                 calibrate_instructions=True))
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library import CorrelatedReadoutError
+
+            exp = CorrelatedReadoutError(physical_qubits=(0,1,2), backend=backend)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+
     # section: manual
         :doc:`/manuals/measurement/readout_mitigation`
 

qiskit_experiments/library/characterization/drag.py

@@ -64,6 +64,34 @@ class RoughDrag(BaseExperiment, RestlessMixin):
     # section: analysis_ref
         :class:`DragCalAnalysis`
 
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=False, seed=101)
+
+        .. jupyter-execute::
+
+            import numpy as np
+            from qiskit import pulse
+            from qiskit.circuit import Parameter
+            from qiskit_experiments.library import RoughDrag
+
+            with pulse.build() as build_sched:
+                pulse.play(pulse.Drag(160, 0.50, 40, Parameter("beta")), pulse.DriveChannel(0))
+
+            exp = RoughDrag(physical_qubits=(0,),
+                            schedule=build_sched,
+                            betas = np.linspace(-4, 4, 51),
+                            backend=backend,)
+            exp.set_experiment_options(reps=[3, 5, 7])
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+
     # section: reference
         .. ref_arxiv:: 1 1011.1949
         .. ref_arxiv:: 2 0901.0534

qiskit_experiments/library/characterization/ef_spectroscopy.py

@@ -34,7 +34,32 @@ class EFSpectroscopy(QubitSpectroscopy):
                        └───┘└────────────┘ ░ └╥┘
             measure: 1/═══════════════════════╩═
                                               0
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
 
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, noise=False, seed=100)
+
+        .. jupyter-execute::
+
+            import numpy as np
+            from qiskit_experiments.library.characterization import EFSpectroscopy
+
+            qubit = 0
+            freq01_estimate = backend.defaults().qubit_freq_est[qubit]
+            frequencies = np.linspace(freq01_estimate-15e6, freq01_estimate+15e6, 51)
+
+            exp = EFSpectroscopy(physical_qubits = (0,),
+                                     frequencies = frequencies,
+                                     backend = backend,
+                                    )
+            exp.set_experiment_options(amp=0.005)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
     """
 
     def __init__(

qiskit_experiments/library/characterization/fine_amplitude.py

@@ -62,21 +62,25 @@ class FineAmplitude(BaseExperiment, RestlessMixin):
         in this case.
 
     # section: example
+        .. jupyter-execute::
+            :hide-code:
 
-        The steps to run a fine amplitude experiment are
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e6, noise=True, seed=185)
 
-        .. code-block:: python
+        .. jupyter-execute::
+
+            import numpy as np
+            from qiskit.circuit.library import XGate
+            from qiskit_experiments.library import FineAmplitude
 
-            qubit = 3
-            amp_cal = FineAmplitude([qubit], SXGate())
-            amp_cal.set_experiment_options(
-                angle_per_gate=np.pi/2,
-                phase_offset=np.pi
-            )
-            amp_cal.run(backend)
+            exp = FineAmplitude(physical_qubits=(0,), gate=XGate(), backend=backend)
+            exp.analysis.set_options(fixed_parameters={"angle_per_gate" : np.pi, "phase_offset" : np.pi})
 
-        Note that there are subclasses of :class:`FineAmplitude` such as :class:`FineSXAmplitude`
-        that set the appropriate options for specific gates by default.
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
 
     # section: analysis_ref
         :class:`FineAmplitudeAnalysis`
@@ -251,6 +255,24 @@ class FineXAmplitude(FineAmplitude):
 
         :class:`FineXAmplitude` is a subclass of :class:`FineAmplitude` and is used to set
         the appropriate values for the default options.
+
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=True, seed=198)
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library import FineXAmplitude
+
+            exp = FineXAmplitude(physical_qubits=(0,), backend=backend)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
     """
 
     def __init__(self, physical_qubits: Sequence[int], backend: Optional[Backend] = None):
@@ -289,6 +311,24 @@ class FineSXAmplitude(FineAmplitude):
 
         :class:`FineSXAmplitude` is a subclass of :class:`FineAmplitude` and is used to set
         the appropriate values for the default options.
+
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=True, seed=198)
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library import FineSXAmplitude
+
+            exp = FineSXAmplitude(physical_qubits=(0,), backend=backend)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
     """
 
     def __init__(self, physical_qubits: Sequence[int], backend: Optional[Backend] = None):

qiskit_experiments/library/characterization/fine_drag.py

@@ -127,6 +127,25 @@ class FineDrag(BaseExperiment, RestlessMixin):
     # section: analysis_ref
         :class:`.ErrorAmplificationAnalysis`
 
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=False, seed=199)
+
+        .. jupyter-execute::
+
+            from qiskit.circuit.library import XGate
+            from qiskit_experiments.library.characterization import FineDrag
+
+            exp = FineDrag(physical_qubits=(0,), gate=XGate(), backend=backend)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+
     # section: reference
         .. ref_arxiv:: 1 1612.00858
         .. ref_arxiv:: 2 1011.1949
@@ -235,7 +254,26 @@ def _metadata(self):
 
 
 class FineXDrag(FineDrag):
-    """Class to fine characterize the DRAG parameter of an X gate."""
+    """Class to fine characterize the DRAG parameter of an X gate.
+
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=False, seed=199)
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library.characterization import FineXDrag
+
+            exp = FineXDrag(physical_qubits=(0,), backend=backend)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+    """
 
     def __init__(self, physical_qubits: Sequence[int], backend: Optional[Backend] = None):
         """Initialize the experiment."""
@@ -260,7 +298,34 @@ def _pre_circuit() -> QuantumCircuit:
 
 
 class FineSXDrag(FineDrag):
-    """Class to fine characterize the DRAG parameter of an :math:`SX` gate."""
+    """Class to fine characterize the DRAG parameter of an :math:`SX` gate.
+
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=False, seed=199)
+
+        .. jupyter-execute::
+
+            import numpy as np
+            from qiskit_experiments.library.characterization import FineSXDrag
+
+            exp = FineSXDrag(physical_qubits=(0,), backend=backend)
+            exp.analysis.set_options(normalization= True,
+                                     fixed_parameters={
+                                         "angle_per_gate" : 0.0,
+                                         "phase_offset" : np.pi/2,
+                                         "amp" : 0.6
+                                         },
+                                    )
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+    """
 
     def __init__(self, physical_qubits: Sequence[int], backend: Optional[Backend] = None):
         """Initialize the experiment."""

qiskit_experiments/library/characterization/fine_frequency.py

@@ -48,6 +48,31 @@ class FineFrequency(BaseExperiment):
                                                                   0
     # section: analysis_ref
         :class:`~qiskit_experiments.curve_analysis.ErrorAmplificationAnalysis`
+
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_ibm_runtime.fake_provider import FakePerth
+            from qiskit_aer import AerSimulator
+            backend =AerSimulator.from_backend(FakePerth())
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library.characterization import FineFrequency
+
+            repetitions = list(range(40))
+
+            exp = FineFrequency((0,),
+                                delay_duration=320,
+                                backend=backend,
+                                repetitions=repetitions)
+            exp.set_transpile_options(optimization_level=0, basis_gates=['sx', 'rz', 'delay'])
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
     """
 
     def __init__(

qiskit_experiments/library/characterization/half_angle.py

@@ -89,6 +89,24 @@ class HalfAngle(BaseExperiment):
     # section: analysis_ref
         :class:`.ErrorAmplificationAnalysis`
 
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=False, seed=199)
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library.characterization import HalfAngle
+
+            exp = HalfAngle((0,), backend=backend)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+
     # section: reference
         .. ref_arxiv:: 1 1504.06597
     """

qiskit_experiments/library/characterization/local_readout_error.py

@@ -62,6 +62,28 @@ class LocalReadoutError(BaseExperiment):
     # section: analysis_ref
         :class:`LocalReadoutErrorAnalysis`
 
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_aer import AerSimulator
+            from qiskit_ibm_runtime.fake_provider import FakePerth
+            backend = AerSimulator.from_backend(FakePerth())
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library import LocalReadoutError
+
+            qubits = list(range(4))
+            exp = LocalReadoutError(physical_qubits=qubits, backend=backend)
+            exp.analysis.set_options(plot=True)
+            exp.set_run_options(shots=10000)
+
+            exp_data = exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+
     # section: manual
         :doc:`/manuals/measurement/readout_mitigation`
 

qiskit_experiments/library/characterization/multi_state_discrimination.py

@@ -53,6 +53,24 @@ class MultiStateDiscrimination(BaseExperiment):
     # section: analysis_ref
         :class:`MultiStateDiscriminationAnalysis`
 
+    # section: example
+        .. jupyter-execute::
+            :hide-code:
+
+            # backend
+            from qiskit_experiments.test.pulse_backend import SingleTransmonTestBackend
+            backend = SingleTransmonTestBackend(5.2e9,-.25e9, 1e9, 0.8e9, 1e4, noise=False, seed=199)
+
+        .. jupyter-execute::
+
+            from qiskit_experiments.library.characterization import MultiStateDiscrimination
+
+            exp=MultiStateDiscrimination((0,), backend=backend)
+
+            exp_data=exp.run().block_for_results()
+            display(exp_data.figure(0))
+            exp_data.analysis_results(dataframe=True)
+
     # section: reference
         `Qiskit Textbook\
         <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware-pulses/accessing_higher_energy_states.ipynb>`_