Merge branch 'main' into qctrl-integration-tests

docs/conf.py

@@ -42,7 +42,7 @@
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '0.14.1'
+release = '0.16.0'
 
 docs_url_prefix = "ecosystem/ibm-runtime"
 

docs/index.rst

@@ -1,5 +1,5 @@
 #########################################
-Qiskit Runtime 0.14.0 documentation
+Qiskit Runtime 0.15.0 documentation
 #########################################
 
 Overview
@@ -98,7 +98,7 @@ Next steps
     Use Sampler to design an algorithm <migrate/migrate-sampler>
     Update parameter values while running <migrate/migrate-update-parm>
     Algorithm tuning options (shots, transpilation, error mitigation) <migrate/migrate-tuning>
-
+    Migrate backend.run() from qiskit_ibm_provider to qiskit_ibm_runtime <migrate/backend_run_migration_guide>
 
 .. toctree::
    :maxdepth: 1

docs/migrate/backend_run_migration_guide.rst

@@ -0,0 +1,96 @@
+Migration guide: Migrate ``backend.run()`` from ``qiskit_ibm_provider`` to ``qiskit_ibm_runtime``
+=================================================================================================
+
+The Qiskit Runtime interface includes two packages:
+Qiskit IBM Provider (the ``qiskit_ibm_provider`` package) and
+Qiskit IBM Runtime (the ``qiskit_ibm_runtime`` package). Until now,
+primitives (``Sampler`` and ``Estimator``)
+were run in Runtime. Custom circuits that were manually transpiled and used ``IBMBackend.run()``
+were run in Provider.
+
+In this release, we add support for running custom circuits using ``IBMBackend.run()`` in Runtime,
+so users can run all programs through Runtime.
+
+This guide describes how to migrate code that implemented ``IBMBackend.run()``
+using Qiskit IBM Provider to use Qiskit IBM Runtime instead.
+
+**Example 1: Straightforward execution of IBMBackend.run()**
+
+.. code-block:: python
+
+    from qiskit import *
+    from qiskit.compiler import transpile, assemble
+    circuit = QuantumCircuit(2, 2)
+    circuit.h(0)
+    circuit.cx(0, 1)
+    circuit.measure_all()
+
+In Provider, the code is:
+
+.. code-block:: python
+
+    from qiskit_ibm_provider import IBMProvider
+    provider = IBMProvider()
+    backend = provider.get_backend("ibmq_qasm_simulator")
+    transpiled_circuit = transpile(circuit, backend=backend)
+    job = backend.run(transpiled_circuit)
+    print(job.result())
+
+In Runtime, the code is:
+
+.. code-block:: python
+
+    from qiskit_ibm_runtime import QiskitRuntimeService
+    service = QiskitRuntimeService(channel="ibm_quantum")
+    backend = service.backend("ibmq_qasm_simulator")
+    transpiled_circuit = transpile(circuit, backend=backend)
+    job = backend.run(transpiled_circuit)
+    print(job.result())
+
+**Example 2: Execution of backend.run() within a session:**
+
+This section of code is identical in Provider and in Runtime.
+
+.. code-block:: python
+
+    with backend.open_session() as session:
+        job1 = backend.run(transpiled_circuit)
+        job2 = backend.run(transpiled_circuit)
+        print(job1.session_id)
+        print(job2.session_id)
+    backend.cancel_session()
+
+Sessions are implemented differently in ``IBMBackend`` than when using primitives.
+Therefore, we cannot run a primitive and use backend.run() within a single session. If you specify both, one will be run outside of the session.
+
+**Example 3: Primitive session containing backend.run:**
+
+In this example, ``sampler`` is run within session, but ``backend`` is run independently
+of the session.
+
+.. code-block:: python
+
+    from qiskit_ibm_runtime import Session, Sampler
+    with Session(backend=backend) as session:
+        sampler = Sampler(session=session)
+        job1 = sampler.run(transpiled_circuit)
+        job2 = backend.run(transpiled_circuit) # runs outside the session
+        print(job1.session_id)
+        print(job2.session_id)  # is None
+
+**Example 4: Backend session containing Sampler:**
+
+In this example, ``backend`` is run within a session, but ``sampler`` is run independently
+of the session.
+
+.. code-block:: python
+
+    with backend.open_session() as session:
+        sampler = Sampler(backend=backend)
+        job1 = sampler.run(transpiled_circuit)  # runs outside the session
+        job2 = backend.run(transpiled_circuit)
+        session_id = session.session_id
+        print(job1.session_id)  # is None
+        print(job2.session_id)
+
+

qiskit_ibm_runtime/VERSION.txt

@@ -1 +1 @@
-0.14.1
+0.16.0

qiskit_ibm_runtime/accounts/management.py

@@ -15,8 +15,10 @@
 import os
 import ast
 from typing import Optional, Dict
+
 from qiskit_ibm_provider.proxies import ProxyConfiguration
 
+from qiskit_ibm_runtime.utils.deprecation import issue_deprecation_msg
 from .exceptions import AccountNotFoundError
 from .account import Account, ChannelType
 from .storage import save_config, read_config, delete_config, read_qiskitrc
@@ -195,6 +197,12 @@ def get(
                 return Account.from_saved_format(all_config[account_name])
 
         if os.path.isfile(_QISKITRC_CONFIG_FILE):
+            issue_deprecation_msg(
+                msg="Use of the ~/.qiskit/qiskitrc.json file is deprecated.",
+                version="0.15.0",
+                remedy="Please use the ~/.qiskit/qiskit-ibm.json file instead.",
+                period="1 month",
+            )
             return cls._from_qiskitrc_file()
 
         raise AccountNotFoundError("Unable to find account.")

qiskit_ibm_runtime/base_primitive.py

@@ -18,14 +18,17 @@
 import copy
 import logging
 from dataclasses import asdict
+import warnings
 
 from qiskit.providers.options import Options as TerraOptions
 
+from qiskit_ibm_provider.session import get_cm_session as get_cm_provider_session
+
 from .options import Options
 from .options.utils import set_default_error_levels
 from .runtime_job import RuntimeJob
 from .ibm_backend import IBMBackend
-from .session import get_cm_session
+from .utils.default_session import get_cm_session
 from .constants import DEFAULT_DECODERS
 from .qiskit_runtime_service import QiskitRuntimeService
 
@@ -118,6 +121,11 @@ def __init__(
                 raise ValueError(
                     "A backend or session must be specified when not using ibm_cloud channel."
                 )
+        # Check if initialized within a IBMBackend session. If so, issue a warning.
+        if get_cm_provider_session():
+            warnings.warn(
+                "A Backend.run() session is open but Primitives will not be run within this session"
+            )
 
     def _run_primitive(self, primitive_inputs: Dict, user_kwargs: Dict) -> RuntimeJob:
         """Run the primitive.

qiskit_ibm_runtime/fake_provider/__init__.py

@@ -0,0 +1,216 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022, 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+======================================================
+Fake Provider (:mod:`qiskit_ibm_runtime.fake_provider`)
+======================================================
+
+.. currentmodule:: qiskit_ibm_runtime.fake_provider
+
+Overview
+========
+
+The fake provider module contains fake providers and fake backends classes. The fake backends are
+built to mimic the behaviors of IBM Quantum systems using system snapshots. The system snapshots
+contain important information about the quantum system such as coupling map, basis gates, qubit
+properties (T1, T2, error rate, etc.) which are useful for testing the transpiler and performing
+noisy simulations of the system.
+
+Example Usage
+=============
+
+Here is an example of using a fake backend for transpilation and simulation.
+
+.. plot::
+   :include-source:
+
+   from qiskit import QuantumCircuit
+   from qiskit import transpile
+   from qiskit.tools.visualization import plot_histogram
+   from qiskit_ibm_runtime.fake_provider import FakeManilaV2
+
+   # Get a fake backend from the fake provider
+   backend = FakeManilaV2()
+
+   # Create a simple circuit
+   circuit = QuantumCircuit(3)
+   circuit.h(0)
+   circuit.cx(0,1)
+   circuit.cx(0,2)
+   circuit.measure_all()
+   circuit.draw('mpl')
+
+   # Transpile the ideal circuit to a circuit that can be directly executed by the backend
+   transpiled_circuit = transpile(circuit, backend)
+   transpiled_circuit.draw('mpl')
+
+   # Run the transpiled circuit using the simulated fake backend
+   job = backend.run(transpiled_circuit)
+   counts = job.result().get_counts()
+   plot_histogram(counts)
+
+.. important::
+
+    Please note that the simulation is done using a noise model generated from system snapshots
+    obtained in the past (sometimes a few years ago) and the results are not representative of the
+    latest behaviours of the real quantum system which the fake backend is mimicking. If you want to
+    run noisy simulations to compare with the real quantum system, you should use the ``qiskit_aer``
+    library. After installation, you can follow the steps below to generate a simulator that
+    mimics a real quantum system with the latest calibration results.
+
+    .. code-block:: python
+
+        from qiskit_ibm_runtime import QiskitRuntimeService
+        from qiskit_aer import AerSimulator
+
+        # get a real backend from the runtime service
+        service = QiskitRuntimeService()
+        backend = service.get_backend('ibmq_manila')
+
+        # generate a simulator that mimics the real quantum system with the latest calibration results
+        backend_sim = AerSimulator.from_backend(backend)
+
+
+Fake Providers
+==============
+
+Fake providers provide access to a list of fake backends.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    FakeProviderForBackendV2
+    FakeProvider
+
+Fake Backends
+=============
+
+Fake V2 Backends
+----------------
+
+Fake V2 backends are fake backends with IBM Quantum systems snapshots implemented with
+:mod:`~qiskit.providers.backend.BackendV2` interface.  They are all subclasses of
+:class:`FakeBackendV2`.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    FakeAlmadenV2
+    FakeArmonkV2
+    FakeAthensV2
+    FakeAuckland
+    FakeBelemV2
+    FakeBoeblingenV2
+    FakeBogotaV2
+    FakeBrooklynV2
+    FakeBurlingtonV2
+    FakeCairoV2
+    FakeCambridgeV2
+    FakeCasablancaV2
+    FakeEssexV2
+    FakeGeneva
+    FakeGuadalupeV2
+    FakeHanoiV2
+    FakeJakartaV2
+    FakeJohannesburgV2
+    FakeKolkataV2
+    FakeLagosV2
+    FakeLimaV2
+    FakeLondonV2
+    FakeManhattanV2
+    FakeManilaV2
+    FakeMelbourneV2
+    FakeMontrealV2
+    FakeMumbaiV2
+    FakeNairobiV2
+    FakeOslo
+    FakeOurenseV2
+    FakeParisV2
+    FakePerth
+    FakePrague
+    FakePoughkeepsieV2
+    FakeQuitoV2
+    FakeRochesterV2
+    FakeRomeV2
+    .. FakeRueschlikonV2 # no v2 version
+    FakeSantiagoV2
+    FakeSherbrooke
+    FakeSingaporeV2
+    FakeSydneyV2
+    .. FakeTenerifeV2 # no v2 version
+    .. FakeTokyoV2 # no v2 version
+    FakeTorontoV2
+    FakeValenciaV2
+    FakeVigoV2
+    FakeWashingtonV2
+    FakeYorktownV2
+
+Fake V1 Backends
+----------------
+
+Fake V1 backends are fake backends with IBM Quantum systems snapshots implemented with
+:mod:`~qiskit.providers.backend.BackendV1` interface.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    FakeAlmaden
+    FakeArmonk
+    FakeAthens
+    FakeBelem
+    FakeBoeblingen
+    FakeBogota
+    FakeBrooklyn
+    FakeBurlington
+    FakeCairo
+    FakeCambridge
+    FakeCasablanca
+    FakeEssex
+    FakeGuadalupe
+    FakeHanoi
+    FakeJakarta
+    FakeJohannesburg
+    FakeKolkata
+    FakeLagos
+    FakeLima
+    FakeLondon
+    FakeManhattan
+    FakeManila
+    FakeMelbourne
+    FakeMontreal
+    FakeMumbai
+    FakeNairobi
+    FakeOurense
+    FakeParis
+    FakePoughkeepsie
+    FakeQuito
+    FakeRochester
+    FakeRome
+    FakeRueschlikon
+    FakeSantiago
+    FakeSingapore
+    FakeSydney
+    FakeTenerife
+    FakeTokyo
+    FakeToronto
+    FakeValencia
+    FakeVigo
+    FakeWashington
+    FakeYorktown
+"""
+
+# Fake providers
+from .fake_provider import FakeProviderFactory, FakeProviderForBackendV2, FakeProvider
+
+# Standard fake backends with IBM Quantum systems snapshots
+from .backends import *