Move qiskit.test.mock to qiskit.providers.fake_provider and deprecate

MANIFEST.in

@@ -7,7 +7,7 @@ include qiskit/VERSION.txt
 recursive-include qiskit *.pyx
 recursive-include qiskit *.pxd
 include qiskit/visualization/styles/*.json
-recursive-include qiskit/test/mock/backends *.json
+recursive-include qiskit/providers/fake_provider/backends *.json
 
 # Include the tests files.
 recursive-include test *.py

docs/apidocs/providers_fake_provider.rst

@@ -0,0 +1,6 @@
+.. _qiskit-providers-fakeprovider:
+
+.. automodule:: qiskit.providers.fake_provider
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/terra.rst

@@ -18,6 +18,7 @@ Qiskit Terra API Reference
    extensions
    providers_basicaer
    providers
+   providers_fake_provider
    providers_models
    pulse
    scheduler

qiskit/providers/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/providers/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