Deprecate BasicAer and introduce BasicProvider (#11583)

* Add basic provider * Restore changes from main that shouldn't be in 0.46. * Fix style, docs * Apply inline suggestions from Julien's code review Co-authored-by: Julien Gacon <[email protected]> * Add suggestion from Julien's code review * Add release note * Add deprecation warnings and address in tests * Fix passmanager config test * Fix passmanager test again * Fix tests * Add opflow filter * Fix lint and docs * Fix opflow and algorithms tests * Remove execute log tests * Remove unused imports * Fix lint * Raise deprecation warning on BasicAer global instance import Co-authored-by: Julien Gacon <[email protected]> * Fix tests * Fix lint * Fix lint again * Apply suggestions from Matt's code review Co-authored-by: Matthew Treinish <[email protected]> * Remove BasicProvider global instance * Apply remaining review comments * Remove uses of _deprecated_backend_names() * Fix forgotten examples * Update reno * Fix examples * Remove comment Co-authored-by: Matthew Treinish <[email protected]> * Update random generator * Increase number of shots in failed tests * Update test_initializer.py * Fix black --------- Co-authored-by: Julien Gacon <[email protected]> Co-authored-by: Matthew Treinish <[email protected]>
Qiskit · Jan 29, 2024 · d71222f · d71222f
1 parent 0dd2212
commit d71222f
Show file tree

Hide file tree

Showing 100 changed files with 2,565 additions and 447 deletions.
diff --git a/docs/apidoc/index.rst b/docs/apidoc/index.rst
@@ -20,8 +20,9 @@ API Reference
    dagcircuit
    extensions
    passmanager
-   providers_basicaer
    providers
+   providers_basicaer
+   providers_basic_provider
    providers_fake_provider
    providers_models
    pulse

diff --git a/docs/apidoc/providers_basic_provider.rst b/docs/apidoc/providers_basic_provider.rst
@@ -0,0 +1,6 @@
+.. _qiskit-providers-basicprovider:
+
+.. automodule:: qiskit.providers.basic_provider
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/examples/python/ghz.py b/examples/python/ghz.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017.
+# (C) Copyright IBM 2017, 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
@@ -14,9 +14,8 @@
 GHZ state example. It also compares running on experiment and simulator.
 """
 
-from qiskit import QuantumCircuit
-from qiskit import BasicAer, transpile
-
+from qiskit import QuantumCircuit, transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 ###############################################################
 # Make a quantum circuit for the GHZ state.
@@ -34,8 +33,8 @@
 for i in range(num_qubits):
     qc.measure(i, i)
 
-sim_backend = BasicAer.get_backend("qasm_simulator")
+sim_backend = BasicSimulator()
 job = sim_backend.run(transpile(qc, sim_backend), shots=1024)
 result = job.result()
-print("Qasm simulator : ")
+print("Basic simulator : ")
 print(result.get_counts(qc))
diff --git a/examples/python/initialize.py b/examples/python/initialize.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017.
+# (C) Copyright IBM 2017, 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
@@ -15,7 +15,8 @@
 """
 
 import math
-from qiskit import QuantumCircuit, transpile, BasicAer
+from qiskit import QuantumCircuit, transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 
 ###############################################################
@@ -58,7 +59,7 @@
 print([format(abs(x * x), ".3f") for x in desired_vector])
 
 # Initialize on local simulator
-sim_backend = BasicAer.get_backend("qasm_simulator")
+sim_backend = BasicSimulator()
 job = sim_backend.run(transpile(circuit, sim_backend), shots=shots)
 result = job.result()
 

diff --git a/examples/python/load_qasm.py b/examples/python/load_qasm.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017, 2018.
+# (C) Copyright IBM 2017, 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
@@ -13,14 +13,13 @@
 """Example on how to load a file into a QuantumCircuit."""
 
 from qiskit import QuantumCircuit
-from qiskit import BasicAer
+from qiskit.providers.basic_provider import BasicSimulator
 
 circ = QuantumCircuit.from_qasm_file("examples/qasm/entangled_registers.qasm")
 print(circ)
 
 # See the backend
-sim_backend = BasicAer.get_backend("qasm_simulator")
-
+sim_backend = BasicSimulator()
 
 # Compile and run the Quantum circuit on a local simulator backend
 job_sim = sim_backend.run(circ)

diff --git a/examples/python/qft.py b/examples/python/qft.py
@@ -16,7 +16,8 @@
 
 import math
 from qiskit import QuantumCircuit
-from qiskit import transpile, BasicAer
+from qiskit import transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 
 ###############################################################
@@ -66,8 +67,8 @@ def qft(circ, n):
 print(qft4)
 print(qft5)
 
-print("Qasm simulator")
-sim_backend = BasicAer.get_backend("qasm_simulator")
+print("Basic simulator")
+sim_backend = BasicSimulator()
 job = sim_backend.run(transpile([qft3, qft4, qft5], sim_backend), shots=1024)
 result = job.result()
 print(result.get_counts(qft3))

diff --git a/examples/python/rippleadd.py b/examples/python/rippleadd.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017.
+# (C) Copyright IBM 2017, 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
@@ -16,13 +16,13 @@
 """
 
 from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
-from qiskit import BasicAer
 from qiskit import transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 ###############################################################
 # Set the backend name and coupling map.
 ###############################################################
-backend = BasicAer.get_backend("qasm_simulator")
+backend = BasicSimulator()
 coupling_map = [
     [0, 1],
     [0, 8],

diff --git a/examples/python/teleport.py b/examples/python/teleport.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017.
+# (C) Copyright IBM 2017, 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
@@ -18,14 +18,14 @@
 """
 
 from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
-from qiskit import BasicAer
 from qiskit import transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 ###############################################################
 # Set the backend name and coupling map.
 ###############################################################
 coupling_map = [[0, 1], [0, 2], [1, 2], [3, 2], [3, 4], [4, 2]]
-backend = BasicAer.get_backend("qasm_simulator")
+backend = BasicSimulator()
 
 ###############################################################
 # Make a quantum program for quantum teleportation.

diff --git a/examples/python/using_qiskit_terra_level_0.py b/examples/python/using_qiskit_terra_level_0.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017, 2018.
+# (C) Copyright IBM 2017, 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
@@ -11,19 +11,16 @@
 # that they have been altered from the originals.
 
 """
-Example showing how to use Qiskit at level 0 (no optimization).
-
-This example shows the most basic way to user Terra. It builds some circuits
-and runs them on both the BasicAer (local Qiskit provider) or IBM Quantum (remote IBM Quantum provider).
-
-To control the compile parameters we have provided a transpile function which can be used
-as a level 1 user.
+Example showing how to use Qiskit-Terra at level 0 (novice).
 
+This example shows the most basic way to use Qiskit. It builds some circuits
+and runs them on the BasicProvider (local Qiskit provider).
 """
 
 # Import the Qiskit modules
 from qiskit import QuantumCircuit
-from qiskit import transpile, BasicAer
+from qiskit import transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 # making first circuit: bell state
 qc1 = QuantumCircuit(2, 2)
@@ -36,12 +33,8 @@
 qc2.h([0, 1])
 qc2.measure([0, 1], [0, 1])
 
-# setting up the backend
-print("(BasicAER Backends)")
-print(BasicAer.backends())
-
 # running the job
-sim_backend = BasicAer.get_backend("qasm_simulator")
+sim_backend = BasicSimulator()
 job_sim = sim_backend.run(transpile([qc1, qc2], sim_backend))
 sim_result = job_sim.result()
 

diff --git a/qiskit/__init__.py b/qiskit/__init__.py
@@ -77,9 +77,6 @@
 # Remove this after 0.46.0 release
 __path__ = pkgutil.extend_path(__path__, __name__)
 
-# Please note these are global instances, not modules.
-from qiskit.providers.basicaer import BasicAer
-
 _config = _user_config.get_config()
 
 # Moved to after IBMQ and Aer imports due to import issues
@@ -189,7 +186,6 @@ def __getattr__(self, attr):
 __all__ = [
     "Aer",
     "AncillaRegister",
-    "BasicAer",
     "ClassicalRegister",
     "IBMQ",
     "MissingOptionalLibraryError",
@@ -202,3 +198,26 @@ def __getattr__(self, attr):
     "sequence",
     "transpile",
 ]
+
+# lazily deprecate BasicAer import (global instance)
+_DEPRECATED_NAMES = {
+    "BasicAer": "qiskit.providers.basicaer",
+}
+
+
+def __getattr__(name):
+    if name in _DEPRECATED_NAMES:
+        import importlib
+
+        module_name = _DEPRECATED_NAMES[name]
+        warnings.warn(
+            f"{name} is deprecated since Qiskit 0.46 and will be removed in Qiskit 1.0. "
+            f"The BasicAer (qiskit.providers.basicaer) module has been superseded by  "
+            f"qiskit.providers.basic_provider, and all its classes have been renamed "
+            f"to follow a new naming convention. More information and migration guidelines "
+            f"can be found in the 0.46 API docs for BasicAer.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(importlib.import_module(module_name), name)
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
diff --git a/qiskit/circuit/__init__.py b/qiskit/circuit/__init__.py
@@ -71,8 +71,7 @@
 .. plot::
    :include-source:
 
-   from qiskit import BasicAer, transpile, QuantumRegister, ClassicalRegister, QuantumCircuit
-
+   from qiskit import transpile, QuantumRegister, ClassicalRegister, QuantumCircuit
    qr = QuantumRegister(1)
    cr = ClassicalRegister(1)
    qc = QuantumCircuit(qr, cr)
@@ -82,7 +81,8 @@
 
 .. code-block::
 
-   backend = BasicAer.get_backend('qasm_simulator')
+   from qiskit.providers.basic_provider import BasicSimulator
+   backend = BasicSimulator()
    tqc = transpile(qc, backend)
    counts = backend.run(tqc).result().get_counts()
 
@@ -100,7 +100,7 @@
 .. plot::
    :include-source:
 
-   from qiskit import BasicAer, transpile, QuantumRegister, ClassicalRegister, QuantumCircuit
+   from qiskit import transpile, QuantumRegister, ClassicalRegister, QuantumCircuit
 
    qr = QuantumRegister(1)
    cr = ClassicalRegister(1)
@@ -115,7 +115,8 @@
 
 .. code-block::
 
-   backend = BasicAer.get_backend('qasm_simulator')
+   from qiskit.providers.basic_provider import BasicSimulator
+   backend = BasicSimulator()
    tqc = transpile(qc, backend)
    counts = backend.run(tqc).result().get_counts()
 

diff --git a/qiskit/opflow/expectations/expectation_factory.py b/qiskit/opflow/expectations/expectation_factory.py
@@ -15,7 +15,7 @@
 import logging
 from typing import Optional, Union
 
-from qiskit import BasicAer
+from qiskit.providers.basicaer import BasicAer  # pylint: disable=no-name-in-module
 from qiskit.opflow.expectations.aer_pauli_expectation import AerPauliExpectation
 from qiskit.opflow.expectations.expectation_base import ExpectationBase
 from qiskit.opflow.expectations.matrix_expectation import MatrixExpectation

diff --git a/qiskit/opflow/state_fns/circuit_state_fn.py b/qiskit/opflow/state_fns/circuit_state_fn.py
@@ -17,7 +17,13 @@
 
 import numpy as np
 
-from qiskit import BasicAer, ClassicalRegister, QuantumCircuit, transpile
+from qiskit import (  # pylint: disable=no-name-in-module
+    BasicAer,
+    ClassicalRegister,
+    QuantumCircuit,
+    transpile,
+)
+
 from qiskit.circuit import Instruction, ParameterExpression
 from qiskit.circuit.exceptions import CircuitError
 from qiskit.circuit.library import IGate, StatePreparation

diff --git a/qiskit/providers/basic_provider/__init__.py b/qiskit/providers/basic_provider/__init__.py
@@ -0,0 +1,66 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+
+"""
+===============================================================================
+BasicProvider: Python-based Simulators (:mod:`qiskit.providers.basic_provider`)
+===============================================================================
+
+.. currentmodule:: qiskit.providers.basic_provider
+
+A module of Python-based quantum simulators. Simulators can be accessed
+via the `BasicProvider` provider, e.g.:
+
+.. code-block::
+
+   from qiskit.providers.basic_provider import BasicProvider
+
+   backend = BasicProvider().get_backend('basic_simulator')
+
+
+Simulators
+==========
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   BasicSimulator
+
+Provider
+========
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   BasicProvider
+
+Job Class
+=========
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   BasicProviderJob
+
+Exceptions
+==========
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   BasicProviderError
+"""
+
+from .basic_provider import BasicProvider
+from .basic_provider_job import BasicProviderJob
+from .basic_simulator import BasicSimulator
+from .exceptions import BasicProviderError