Move qiskit.test.mock to qiskit.providers.fake_provider and depre…

…cate (Qiskit/qiskit#8121)

* redirect imports from qiskit.test.mock to qiskit.providers.fake_provider

* import the rest of classes in fake_backend_v2 to fake_provider

* redirect imports to fake_provider

Anything that can be imported from fake_provider root are imported from there instead of sub files.

* change jupyter-execute to code-block

* redirect import

* Combine multiple imports into one

* Add missing )

* move all files except __init__ from qiskit.test.mock to qiskit.providers.fake_provider

* redirect imports in fake_provider.__init__.py

* redirect imports in mock.__init__.py

* Use relative imports in fake_provider.__init__.py

* redirect .utlis imports

* Don't import fake_backend_v2.py in __init__ to avoid clashes of FakeBackendV2 names

* Match imports from the old and new __init__

* Organize imports

* black linting

* Fix FakePulseBackend import order dependency

* fix cyclic import

* move relative import after absolute import

* fix cyclic import

* Update MANIFEST.ini with new path

* add deprecation warning

* add deprecation test

* add release note

* move test files from test.python.mock to test.python.providers.fake_provider

* linting

* linting

* change deprecation warning location

* update path for tools/update_fake_backends.py

* rename docstrings

* Update ibmq_mock.py

* import back FakeBackendV2 and FakeBackend5QV2 in __init__

* Modify release note

* reformat release note

* remove unnecessary tests

These two tests were introduced in PR Qiskit/qiskit#7437 to test the new imports which are not needed any more: Qiskit/qiskit#7437 (comment)

* Use relative imports

* redirect import in test_schedular.py

* first draft of module level doc

* Update docstring of fake provider v1 and v2

* Update wording of module level doc

* add fake V1 and V2 backends

* Correct fake v1 and v2 backends in the list

* comment on backends that do not have V2 versions

* list special fake backends

* Add descriptions for sections

* add code example using jupyter execute

* Update code example and improve descriptions of the module

* not using fake provider before fake provider get backend name is fixed

* modify comment

* formating fix

* Remove fake backend coupling map from docstrings

* linting

* remove coupling map of Pooughkeepsie

* add qiskit-aer to tox.ini as deps for docs build

* Revert "remove coupling map of Pooughkeepsie"

This reverts commit 45607489303fde0e65e550f117735ec4f468ff3d.

* Revert "linting"

This reverts commit eddfa65bf6f65f076c7eff4d1a20bb251c56658b.

* Revert "Remove fake backend coupling map from docstrings"

This reverts commit 3aee7a8b57e8ea248ede0bec9db67e02dcb08eed.

* fix coupling maps

* Fix minor typos

* Issue deprecation warnings from all levels of package

The previous commits in this PR did not maintain the old import paths
for submodules of `qisit.test.mock`.  This re-instatates them, with
suitable deprecation warnings.  Hopefully nobody is using these anyway,
but it's better to be on the safe side.

* Import from the correct location

Co-authored-by: Jake Lishman <[email protected]>
Co-authored-by: Jake Lishman <[email protected]>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

qiskit_ibm_provider/fake_provider/__init__.py

@@ -11,32 +11,241 @@
 # that they have been altered from the originals.
 
 """
-Utilities for mocking the IBMQ provider, including job responses and backends.
+======================================================
+Fake Provider (:mod:`qiskit.providers.fake_provider`)
+======================================================
 
-The module includes dummy provider, backends, and jobs.
-The purpose of these classes is to fake backends for testing purposes:
-testing local timeouts, arbitrary responses or behavior, etc.
+.. currentmodule:: qiskit.providers.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 simulation of the system.
+
+Example Usage
+=============
+
+Here is an example of using a fake backend for transpilation and simulation.
+
+.. jupyter-execute::
+
+    from qiskit import QuantumCircuit
+    from qiskit.providers.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()
+
+.. jupyter-execute::
+
+    from qiskit import transpile
+
+    # Transpile the ideal circuit to a circuit that can be directly executed by the backend
+    transpiled_circuit = transpile(circuit, backend)
+    transpiled_circuit.draw()
+
+.. jupyter-execute::
+
+    from qiskit.tools.visualization import plot_histogram
+
+    # 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, please follow steps below to
+    generate a simulator mimics a real quantum system with the latest calibration results.
+
+    .. code-block:: python
+
+        from qiskit import IBMQ
+        from qiskit.providers.aer import AerSimulator
+
+        # get a real backend from a real provider
+        provider = IBMQ.load_account()
+        backend = provider.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.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    FakeAlmadenV2
+    FakeArmonkV2
+    FakeAthensV2
+    FakeBelemV2
+    FakeBoeblingenV2
+    FakeBogotaV2
+    FakeBrooklynV2
+    FakeBurlingtonV2
+    FakeCairoV2
+    FakeCambridgeV2
+    FakeCasablancaV2
+    FakeEssexV2
+    FakeGuadalupeV2
+    FakeHanoiV2
+    FakeJakartaV2
+    FakeJohannesburgV2
+    FakeKolkataV2
+    FakeLagosV2
+    FakeLimaV2
+    FakeLondonV2
+    FakeManhattanV2
+    FakeManilaV2
+    FakeMelbourneV2
+    FakeMontrealV2
+    FakeMumbaiV2
+    FakeNairobiV2
+    FakeOurenseV2
+    FakeParisV2
+    FakePoughkeepsieV2
+    FakeQuitoV2
+    FakeRochesterV2
+    FakeRomeV2
+    .. FakeRueschlikonV2 # no v2 version
+    FakeSantiagoV2
+    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
+
+Special Fake Backends
+=====================
+
+Special fake backends are fake backends that were created for special testing purposes.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    FakeQasmSimulator
+    FakeOpenPulse2Q
+    FakeOpenPulse3Q
+    Fake1Q
+    FakeBackendV2
+    FakeBackend5QV2
+    FakeMumbaiFractionalCX
+    ConfigurableFakeBackend
 
-The mock devices are mainly for testing the compiler.
 """
 
-from qiskit.test.mock.fake_provider import (
-    FakeProviderForBackendV2,
-    FakeProvider,
-)
-from qiskit.test.mock.fake_provider import FakeProviderFactory
-from qiskit.test.mock.fake_backend import FakeBackend
-from qiskit.test.mock.fake_pulse_backend import FakePulseBackend
-from qiskit.test.mock.fake_qasm_backend import FakeQasmBackend
-from qiskit.test.mock.utils.configurable_backend import ConfigurableFakeBackend
-from qiskit.test.mock.fake_backend_v2 import FakeBackendV2, FakeBackend5QV2
-from qiskit.test.mock.fake_mumbai_v2 import FakeMumbaiFractionalCX
-from qiskit.test.mock.fake_job import FakeJob
-from qiskit.test.mock.fake_qobj import FakeQobj
-
-from qiskit.test.mock.backends import *
-
-from qiskit.test.mock.fake_qasm_simulator import FakeQasmSimulator
-from qiskit.test.mock.fake_openpulse_2q import FakeOpenPulse2Q
-from qiskit.test.mock.fake_openpulse_3q import FakeOpenPulse3Q
-from qiskit.test.mock.fake_1q import Fake1Q
+# Fake job and qobj classes
+from .fake_job import FakeJob
+from .fake_qobj import FakeQobj
+
+# Base classes for fake backends
+from .fake_backend import FakeBackend
+from .fake_qasm_backend import FakeQasmBackend
+from .fake_pulse_backend import FakePulseBackend
+
+# Fake providers
+from .fake_provider import FakeProviderFactory, FakeProviderForBackendV2, FakeProvider
+
+# Standard fake backends with IBM Quantum systems snapshots
+from .backends import *
+
+# Special fake backends for special testing perpurposes
+from .fake_qasm_simulator import FakeQasmSimulator
+from .fake_openpulse_2q import FakeOpenPulse2Q
+from .fake_openpulse_3q import FakeOpenPulse3Q
+from .fake_1q import Fake1Q
+from .fake_backend_v2 import FakeBackendV2, FakeBackend5QV2
+from .fake_mumbai_v2 import FakeMumbaiFractionalCX
+
+# Configurable fake backend
+from .utils.configurable_backend import ConfigurableFakeBackend

qiskit_ibm_provider/fake_provider/backends/__init__.py

@@ -0,0 +1,104 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# 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.
+
+
+"""
+Mocked versions of real quantum backends.
+"""
+
+# BackendV2 Backends
+from .almaden import FakeAlmadenV2
+from .armonk import FakeArmonkV2
+from .athens import FakeAthensV2
+from .belem import FakeBelemV2
+from .boeblingen import FakeBoeblingenV2
+from .bogota import FakeBogotaV2
+from .brooklyn import FakeBrooklynV2
+from .burlington import FakeBurlingtonV2
+from .cairo import FakeCairoV2
+from .cambridge import FakeCambridgeV2
+from .casablanca import FakeCasablancaV2
+from .essex import FakeEssexV2
+from .guadalupe import FakeGuadalupeV2
+from .hanoi import FakeHanoiV2
+from .jakarta import FakeJakartaV2
+from .johannesburg import FakeJohannesburgV2
+from .kolkata import FakeKolkataV2
+from .lagos import FakeLagosV2
+from .lima import FakeLimaV2
+from .london import FakeLondonV2
+from .manhattan import FakeManhattanV2
+from .manila import FakeManilaV2
+from .melbourne import FakeMelbourneV2
+from .montreal import FakeMontrealV2
+from .mumbai import FakeMumbaiV2
+from .nairobi import FakeNairobiV2
+from .ourense import FakeOurenseV2
+from .paris import FakeParisV2
+from .poughkeepsie import FakePoughkeepsieV2
+from .quito import FakeQuitoV2
+from .rochester import FakeRochesterV2
+from .rome import FakeRomeV2
+from .santiago import FakeSantiagoV2
+from .singapore import FakeSingaporeV2
+from .sydney import FakeSydneyV2
+from .toronto import FakeTorontoV2
+from .valencia import FakeValenciaV2
+from .vigo import FakeVigoV2
+from .washington import FakeWashingtonV2
+from .yorktown import FakeYorktownV2
+
+# BackendV1 Backends
+from .almaden import FakeAlmaden
+from .armonk import FakeArmonk
+from .athens import FakeAthens
+from .belem import FakeBelem
+from .boeblingen import FakeBoeblingen
+from .bogota import FakeBogota
+from .brooklyn import FakeBrooklyn
+from .burlington import FakeBurlington
+from .cairo import FakeCairo
+from .cambridge import FakeCambridge
+from .cambridge import FakeCambridgeAlternativeBasis
+from .casablanca import FakeCasablanca
+from .essex import FakeEssex
+from .guadalupe import FakeGuadalupe
+from .hanoi import FakeHanoi
+from .jakarta import FakeJakarta
+from .johannesburg import FakeJohannesburg
+from .kolkata import FakeKolkata
+from .lagos import FakeLagos
+from .lima import FakeLima
+from .london import FakeLondon
+from .manhattan import FakeManhattan
+from .manila import FakeManila
+from .melbourne import FakeMelbourne
+from .montreal import FakeMontreal
+from .mumbai import FakeMumbai
+from .nairobi import FakeNairobi
+from .ourense import FakeOurense
+from .paris import FakeParis
+from .poughkeepsie import FakePoughkeepsie
+from .quito import FakeQuito
+from .rochester import FakeRochester
+from .rome import FakeRome
+from .rueschlikon import FakeRueschlikon
+from .santiago import FakeSantiago
+from .singapore import FakeSingapore
+from .sydney import FakeSydney
+from .tenerife import FakeTenerife
+from .tokyo import FakeTokyo
+from .toronto import FakeToronto
+from .valencia import FakeValencia
+from .vigo import FakeVigo
+from .washington import FakeWashington
+from .yorktown import FakeYorktown

qiskit_ibm_provider/fake_provider/backends/almaden/__init__.py

@@ -0,0 +1,16 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# 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.
+
+"""Mock almaden backend"""
+
+from .fake_almaden import FakeAlmadenV2
+from .fake_almaden import FakeAlmaden