Merge branch 'main' of github.com:Qiskit/qiskit-experiments into clea…

…nup/circuit_metadata

.github/workflows/cron-staging.yml

@@ -5,7 +5,8 @@ on:
   workflow_dispatch:
 
 jobs:
-  terra-main-tests:
+  qiskit-main-tests:
+    if: github.repository_owner == 'Qiskit-Extensions'
     name: tests-python${{ matrix.python-version }}-${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -37,15 +38,15 @@ jobs:
       - name: Install Deps
         run: python -m pip install -U tox setuptools virtualenv wheel
       - name: Install and Run Tests (Windows and Linux)
-        run: tox -e terra-main
+        run: tox -e qiskit-main
         if: runner.os != 'macOS'
       - name: Install and Run Tests (Macs only)
-        run: tox -e terra-main
+        run: tox -e qiskit-main
         if: runner.os == 'macOS'
         env:
           TEST_TIMEOUT: 120
-          OMP_NUM_THREADS: 1
   docs:
+    if: github.repository_owner == 'Qiskit-Extensions'
     name: docs
     runs-on: ubuntu-latest
     steps:
@@ -66,7 +67,7 @@ jobs:
           python -m pip install -U tox
           sudo apt-get install -y pandoc graphviz
       - name: Build Docs
-        run: tox -edocs-terra-main
+        run: tox -edocs-qiskit-main
       - name: Compress Artifacts
         run: |
           mkdir artifacts
@@ -75,4 +76,4 @@ jobs:
       - uses: actions/upload-artifact@v3
         with:
           name: html_docs
-          path: artifacts
+          path: artifacts

.github/workflows/docs.yml

@@ -7,6 +7,7 @@ on:
 
 jobs:
   deploy:
+    if: github.repository_owner == 'Qiskit-Extensions'
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3

.github/workflows/docs_dev.yml

@@ -6,6 +6,7 @@ on:
 
 jobs:
   deploy:
+    if: github.repository_owner == 'Qiskit-Extensions'
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3

.github/workflows/main.yml

@@ -11,6 +11,7 @@ concurrency:
   cancel-in-progress: true
 jobs:
   tests:
+    if: github.repository_owner == 'Qiskit-Extensions'
     name: tests-python${{ matrix.python-version }}-${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -57,11 +58,11 @@ jobs:
         if: runner.os == 'macOS'
         env:
           TEST_TIMEOUT: 120
-          OMP_NUM_THREADS: 1
       - name: Clean up stestr cache
         run: stestr history remove all
 
   lint:
+    if: github.repository_owner == 'Qiskit-Extensions'
     name: lint
     runs-on: ubuntu-latest
     steps:
@@ -80,6 +81,7 @@ jobs:
       - name: Run lint
         run: tox -elint
   docs:
+    if: github.repository_owner == 'Qiskit-Extensions'
     name: docs
     runs-on: ubuntu-latest
     steps:

.github/workflows/neko.yml

@@ -8,6 +8,7 @@ concurrency:
   cancel-in-progress: true
 jobs:
   neko:
+    if: github.repository_owner == 'Qiskit-Extensions'
     name: Qiskit Neko Integration Tests
     runs-on: ubuntu-latest
     steps:

.pylintrc

@@ -73,7 +73,7 @@ disable=fixme,              # disabled as TODOs would show up as warnings
     cyclic-import,  # This checker raises on all module pairs that import each other,
                     # even submodules that only import already loaded objects from a
                     # parent module, a common pattern in qiskit-experiments.
-    assigning-non-slot  # https://github.com/Qiskit/qiskit-terra/pull/7347#issuecomment-985007311
+    assigning-non-slot  # https://github.com/Qiskit/qiskit/pull/7347#issuecomment-985007311
 
 
 

CONTRIBUTING.md

@@ -104,29 +104,25 @@ https://stestr.readthedocs.io/en/stable/MANUAL.html#test-selection
 If you want to run a single test module, test class, or individual test method you can
 do this faster with the `-n`/`--no-discover` option. For example, to run a module:
 ```
-tox -- -n test.python.test_examples
+tox -epy310 -- -n test.framework.test_composite
 ```
-Or to run the same module by path:
 
-```
-tox -- -n test/python/test_examples.py
-```
 To run a class:
-
 ```
-tox -- -n test.python.test_examples.TestPythonExamples
+tox -epy310 -- -n test.framework.test_composite.TestCompositeExperimentData
 ```
+
 To run a method:
 ```
-tox -- -n test.python.test_examples.TestPythonExamples.test_all_examples
+tox -epy310 -- -n test.framework.test_composite.TestCompositeExperimentData.test_composite_save_load
 ```
 
 Note that tests will fail automatically if they do not finish execution within 60 seconds.
 
 #### STDOUT/STDERR and logging capture
 
-When running tests in parallel using `stestr` either via tox, the Makefile (`make
-test_ci`), or in CI, we set the env variable `QISKIT_TEST_CAPTURE_STREAMS`, which will
+When running tests in parallel using `stestr` either via tox
+or in CI, we set the env variable `QISKIT_TEST_CAPTURE_STREAMS`, which will
 capture any text written to stdout, stderr, and log messages and add them as attachments
 to the tests run so output can be associated with the test case it originated from.
 However, if you run tests with `stestr` outside of these mechanisms, by default the
@@ -138,6 +134,18 @@ stdlib unittest runner, a similar result can be accomplished by using the
 [`--buffer`](https://docs.python.org/3/library/unittest.html#command-line-options)
 option (e.g. `python -m unittest discover --buffer ./test/python`).
 
+#### Other testing related settings
+
+The test code defines some environment variables that may occasionally be useful to set:
+
++ `TEST_TIMEOUT`: An integer representing the maximum time a test can take
+  before it is considered a failure.
++ `QE_USE_TESTTOOLS`: Set this variable to `FALSE`, `0`, or `NO` to have the
+  tests use `unittest.TestCase` as the base class. Otherwise, the default is
+`testtools.TestCase` which is an extension of `unittest.TestCase`. In some
+situations, a developer may wish to use a workflow that is not compatible with
+the `testtools` extensions.
+
 ### Code style
 
 The qiskit-experiments repository uses `black` for code formatting and style and

constraints.txt

@@ -1,4 +0,0 @@
-# Numpy 1.25 deprecated some behaviours that we used, and caused some
-# tests to flake. See https://github.com/Qiskit/qiskit-terra/issues/10305,
-# remove pin when resolving that.
-numpy<1.25

docs/_ext/custom_styles/formatter.py

@@ -38,7 +38,7 @@ def format_header(self, lines: List[str]) -> List[str]:
     def format_overview(self, lines: List[str]) -> List[str]:
         """Format overview section."""
         format_lines = [
-            ""
+            "",
             ".. rubric:: Overview",
             "",
         ]
@@ -167,7 +167,7 @@ def format_analysis_opts(self, lines: List[str]) -> List[str]:
         format_lines = [
             ".. rubric:: Analysis options",
             "",
-            "These are the keyword arguments of :meth:`run` method.",
+            "These are the keyword arguments of the :meth:`run` method.",
             "",
         ]
         for line in _write_options(lines, self.indent):

docs/conf.py

@@ -174,6 +174,7 @@
     "qiskit_ibm_provider": ("https://qiskit.org/ecosystem/ibm-provider/", None),
     "qiskit_aer": ("https://qiskit.org/ecosystem/aer", None),
     "qiskit_dynamics": ("https://qiskit.org/documentation/dynamics", None),
+    "qiskit_ibm_runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None),
 }
 
 

docs/howtos/cloud_service.rst

@@ -4,7 +4,7 @@ Save and load experiment data with the cloud service
 .. note::
     This guide is only for those who have access to the cloud service. You can 
     check whether you do by logging into the IBM Quantum interface 
-    and seeing if you can see the `database <https://quantum-computing.ibm.com/experiments>`__.
+    and seeing if you can see the `database <https://quantum.ibm.com/experiments>`__.
 
 Problem
 -------
@@ -44,13 +44,13 @@ backend and not a simulator to be able to save the experiment data. This is done
 .. jupyter-output::
 
     You can view the experiment online at 
-    https://quantum-computing.ibm.com/experiments/10a43cb0-7cb9-41db-ad74-18ea6cf63704
+    https://quantum.ibm.com/experiments/10a43cb0-7cb9-41db-ad74-18ea6cf63704
 
 Loading
 ~~~~~~~
 
 Let's load a `previous T1
-experiment <https://quantum-computing.ibm.com/experiments/9640736e-d797-4321-b063-d503f8e98571>`__ 
+experiment <https://quantum.ibm.com/experiments/9640736e-d797-4321-b063-d503f8e98571>`__ 
 (requires login to view), which we've made public by editing the ``Share level`` field:
 
 .. jupyter-input::
@@ -59,13 +59,11 @@ experiment <https://quantum-computing.ibm.com/experiments/9640736e-d797-4321-b06
     service = ExperimentData.get_service_from_backend(backend)
     load_expdata = ExperimentData.load("9640736e-d797-4321-b063-d503f8e98571", service)
 
-To display the figure, which is serialized into a string, we need the
-``SVG`` library:
+Now we can display the figure from the loaded experiment data:
 
 .. jupyter-input::
 
-    from IPython.display import SVG
-    SVG(load_expdata.figure(0).figure)
+    load_expdata.figure(0)
 
 .. image:: ./experiment_cloud_service/t1_loaded.png
 
@@ -143,7 +141,7 @@ The :meth:`~.ExperimentData.auto_save` feature automatically saves changes to th
 
 .. jupyter-output::
 
-    You can view the experiment online at https://quantum-computing.ibm.com/experiments/cdaff3fa-f621-4915-a4d8-812d05d9a9ca
+    You can view the experiment online at https://quantum.ibm.com/experiments/cdaff3fa-f621-4915-a4d8-812d05d9a9ca
     <ExperimentData[T1], backend: ibmq_lima, status: ExperimentStatus.DONE, experiment_id: cdaff3fa-f621-4915-a4d8-812d05d9a9ca>
 
 Setting ``auto_save = True`` works by triggering :meth:`.ExperimentData.save`.
@@ -188,12 +186,5 @@ Web interface
 ~~~~~~~~~~~~~
 
 You can also view experiment results as well as change the tags and share level at the `IBM Quantum Experiments
-pane <https://quantum-computing.ibm.com/experiments?date_interval=last-90-days&owner=me>`__
-on the cloud. The documentation below explains how to view, search, and share experiment
-data entries.
-
-See also
---------
-
-* `Experiments web interface documentation <https://quantum-computing.ibm.com/lab/docs/iql/manage/experiments/>`__ 
-
+pane <https://quantum.ibm.com/experiments?date_interval=last-90-days&owner=me>`__
+on the cloud.

docs/howtos/experiment_times.rst

@@ -24,7 +24,7 @@ are all of type ``datetime.datetime`` and in your local timezone:
 .. note::
     The below attributes are only relevant for those who have access to the cloud service. You can 
     check whether you do by logging into the IBM Quantum interface 
-    and seeing if you can see the `database <https://quantum-computing.ibm.com/experiments>`__.
+    and seeing if you can see the `database <https://quantum.ibm.com/experiments>`__.
 
 - :attr:`.ExperimentData.creation_datetime` is the time when the experiment data was saved via the
   service. This defaults to ``None`` if experiment data has not yet been saved.

docs/howtos/rerun_analysis.rst

@@ -37,12 +37,14 @@ job IDs:
 
     expdata = ExperimentData(experiment = experiment)
     expdata.add_jobs([provider.retrieve_job(job_id) for job_id in job_ids])
-    experiment.analysis.run(expdata)
+    experiment.analysis.run(expdata, replace_results=True)
 
     # Block execution of subsequent code until analysis is complete
     expdata.block_for_results()
 
-``expdata`` will be the new experiment data object containing results of the rerun analysis.
+``expdata`` will be the new experiment data object containing results of the rerun analysis. Note that if
+``replace_results`` isn't set, running the analysis will return a new :class:`.ExperimentData` object
+instead of overwriting the existing one.
 
 If you have the job data in the form of a :class:`~qiskit.result.Result` object, you can
 invoke the :meth:`.add_data` method instead of :meth:`.add_jobs`:
@@ -66,7 +68,7 @@ contain correct results.
 
 In the case where jobs are not directly accessible from the provider but you've
 downloaded the jobs from the 
-`IQS dashboard <https://quantum-computing.ibm.com/jobs>`_, you can load them from
+`IQS dashboard <https://quantum.ibm.com/jobs>`_, you can load them from
 the downloaded directory into :class:`~qiskit.result.Result` objects with this code:
 
 .. jupyter-input::
@@ -115,7 +117,7 @@ first component experiment.
 
     data = ExperimentData(experiment=pexp)
     data.add_jobs([provider.retrieve_job(job_id) for job_id in job_ids])
-    pexp.analysis.run(data)
+    pexp.analysis.run(data, replace_results=True)
 
 See Also
 --------

docs/howtos/runtime_sessions.rst

@@ -0,0 +1,41 @@
+Use Experiments with Runtime sessions
+=====================================
+
+Problem
+-------
+
+You want to run experiments in a `Runtime session
+<https://docs.quantum.ibm.com/run/sessions>`_ so that jobs can run in close temporal proximity.
+
+Solution
+--------
+
+Use the :class:`~qiskit_ibm_provider.IBMBackend` object in ``qiskit-ibm-provider``, which supports sessions.
+
+In this example, we will set the ``max_circuits`` property to an artificially low value so that the experiment will be
+split into multiple jobs that run sequentially in a single session. When running real experiments with a
+large number of circuits that can't fit in a single job, it may be helpful to follow this usage pattern:
+
+.. jupyter-input::
+
+    from qiskit_ibm_provider import IBMProvider
+    from qiskit_experiments.library.tomography import ProcessTomography
+    from qiskit import QuantumCircuit
+
+    provider = IBMProvider()
+    backend = provider.get_backend("ibm_nairobi")
+    qc = QuantumCircuit(1)
+    qc.x(0)
+
+    with backend.open_session() as session:
+        exp = ProcessTomography(qc)
+        exp.set_experiment_options(max_circuits=3)
+        exp_data = exp.run(backend)
+        exp_data.block_for_results()
+        # Calling cancel because session.close() is not available for qiskit-ibm-provider<=0.7.2.
+        # It is safe to call cancel since block_for_results() ensures there are no outstanding jobs 
+        # still running that would be canceled.
+        session.cancel()
+
+Note that runtime primitives are not currently supported natively in Qiskit Experiments, so  
+the ``backend.run()`` path is required to run experiments.

docs/manuals/measurement/readout_mitigation.rst

@@ -180,4 +180,4 @@ See also
 
 * API documentation: :mod:`~qiskit_experiments.library.characterization.LocalReadoutError`, 
   :mod:`~qiskit_experiments.library.characterization.CorrelatedReadoutError`
-* Qiskit Textbook: `Measurement Error Mitigation <https://qiskit.org/textbook/ch-quantum-hardware/measurement-error-mitigation.html>`__
+* Qiskit Textbook: `Measurement Error Mitigation <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measurement-error-mitigation.ipynb>`__

docs/manuals/verification/quantum_volume.rst

@@ -8,7 +8,7 @@ that the computer successfully implements. Quantum computing systems
 with high-fidelity operations, high connectivity, large calibrated gate
 sets, and circuit rewriting toolchains are expected to have higher
 quantum volumes. See the `Qiskit
-Textbook <https://learn.qiskit.org/course/quantum-hardware/measuring-quantum-volume>`__
+Textbook <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measuring-quantum-volume.ipynb>`__
 for an explanation on the QV method, which is described in Refs. [1]_ [2]_.
 
 The Quantum Volume is determined by the largest successful circuit depth
@@ -20,8 +20,8 @@ a random permutation on the :math:`d` qubit. Then these circuits run on
 the quantum backend and on an ideal simulator (either :class:`qiskit_aer.AerSimulator`
 or :class:`qiskit.quantum_info.Statevector`).
 
-A depth :math:`d` QV circuit is successful if it has ‘mean heavy-output
-probability’ > 2/3 with confidence level > 0.977 (corresponding to
+A depth :math:`d` QV circuit is successful if it has `mean heavy-output
+probability` > 2/3 with confidence level > 0.977 (corresponding to
 z_value = 2), and at least 100 trials have been ran.
 
 .. note::
@@ -68,7 +68,7 @@ more trials may reduce the error bars to allow passing the threshold.
 
 The analysis results of the QV Experiment are:
 
--  The mean heavy output probabilities (HOP) and standard deviation
+-  The mean heavy-output probabilities (HOP) and standard deviation
 
 -  The calculated quantum volume, which will be None if the experiment
    does not pass the threshold
@@ -190,5 +190,5 @@ See also
 --------
 
 * API documentation: :mod:`~qiskit_experiments.library.quantum_volume`
-* Qiskit Textbook: `Measuring Quantum Volume <https://qiskit.org/textbook/ch-quantum-hardware/measuring-quantum-volume.html>`__
+* Qiskit Textbook: `Measuring Quantum Volume <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measuring-quantum-volume.ipynb>`__