Add lightweight v2 provider interface starter

qiskit/compiler/assemble.py

@@ -26,6 +26,7 @@
 from qiskit.qobj.utils import MeasLevel, MeasReturnType
 from qiskit.validation.jsonschema import SchemaValidationError
 from qiskit.providers import BaseBackend
+from qiskit.providers.backend import Backend
 from qiskit.pulse.channels import PulseChannel
 from qiskit.pulse import Schedule
 
@@ -39,7 +40,7 @@ def _log_assembly_time(start_time, end_time):
 
 # TODO: parallelize over the experiments (serialize each separately, then add global header/config)
 def assemble(experiments: Union[QuantumCircuit, List[QuantumCircuit], Schedule, List[Schedule]],
-             backend: Optional[BaseBackend] = None,
+             backend: Optional[Union[Backend, BaseBackend]] = None,
              qobj_id: Optional[str] = None,
              qobj_header: Optional[Union[QobjHeader, Dict]] = None,
              shots: Optional[int] = None, memory: Optional[bool] = False,

qiskit/compiler/schedule.py

@@ -23,6 +23,7 @@
 from qiskit.exceptions import QiskitError
 from qiskit.pulse import InstructionScheduleMap, Schedule
 from qiskit.providers import BaseBackend
+from qiskit.providers.backend import Backend
 from qiskit.scheduler import ScheduleConfig
 from qiskit.scheduler.schedule_circuit import schedule_circuit
 
@@ -35,7 +36,7 @@ def _log_schedule_time(start_time, end_time):
 
 
 def schedule(circuits: Union[QuantumCircuit, List[QuantumCircuit]],
-             backend: Optional[BaseBackend] = None,
+             backend: Optional[Union[Backend, BaseBackend]] = None,
              inst_map: Optional[InstructionScheduleMap] = None,
              meas_map: Optional[List[List[int]]] = None,
              dt: Optional[float] = None,

qiskit/compiler/sequence.py

@@ -18,13 +18,14 @@
 from qiskit.circuit.quantumcircuit import QuantumCircuit
 from qiskit.exceptions import QiskitError
 from qiskit.providers import BaseBackend
+from qiskit.providers.backend import Backend
 from qiskit.pulse import InstructionScheduleMap, Schedule
 from qiskit.scheduler import ScheduleConfig
 from qiskit.scheduler.sequence import sequence as _sequence
 
 
 def sequence(scheduled_circuits: Union[QuantumCircuit, List[QuantumCircuit]],
-             backend: Optional[BaseBackend] = None,
+             backend: Optional[Union[Backend, BaseBackend]] = None,
              inst_map: Optional[InstructionScheduleMap] = None,
              meas_map: Optional[List[List[int]]] = None,
              dt: Optional[float] = None) -> Union[Schedule, List[Schedule]]:

qiskit/compiler/transpile.py

@@ -22,6 +22,7 @@
 from qiskit.converters import isinstanceint, isinstancelist, dag_to_circuit, circuit_to_dag
 from qiskit.dagcircuit import DAGCircuit
 from qiskit.providers import BaseBackend
+from qiskit.providers.backend import Backend
 from qiskit.providers.models import BackendProperties
 from qiskit.providers.models.backendproperties import Gate
 from qiskit.pulse import Schedule
@@ -41,7 +42,7 @@
 
 
 def transpile(circuits: Union[QuantumCircuit, List[QuantumCircuit]],
-              backend: Optional[BaseBackend] = None,
+              backend: Optional[Union[Backend, BaseBackend]] = None,
               basis_gates: Optional[List[str]] = None,
               coupling_map: Optional[Union[CouplingMap, List[List[int]]]] = None,
               backend_properties: Optional[BackendProperties] = None,

qiskit/execute.py

@@ -23,6 +23,8 @@
 from time import time
 from qiskit.circuit import QuantumCircuit
 from qiskit.compiler import transpile, assemble, schedule
+from qiskit.providers import BaseBackend
+from qiskit.providers.backend import Backend
 from qiskit.qobj.utils import MeasLevel, MeasReturnType
 from qiskit.pulse import Schedule
 from qiskit.exceptions import QiskitError
@@ -58,7 +60,7 @@ def execute(experiments, backend,
         experiments (QuantumCircuit or list[QuantumCircuit] or Schedule or list[Schedule]):
             Circuit(s) or pulse schedule(s) to execute
 
-        backend (BaseBackend):
+        backend (BaseBackend or Backend):
             Backend to execute circuits on.
             Transpiler options are automatically grabbed from
             backend.configuration() and backend.properties().
@@ -272,33 +274,56 @@ def execute(experiments, backend,
                                meas_map=meas_map,
                                method=scheduling_method)
 
-    # assembling the circuits into a qobj to be run on the backend
-    qobj = assemble(experiments,
-                    qobj_id=qobj_id,
-                    qobj_header=qobj_header,
-                    shots=shots,
-                    memory=memory,
-                    max_credits=max_credits,
-                    seed_simulator=seed_simulator,
-                    default_qubit_los=default_qubit_los,
-                    default_meas_los=default_meas_los,
-                    schedule_los=schedule_los,
-                    meas_level=meas_level,
-                    meas_return=meas_return,
-                    memory_slots=memory_slots,
-                    memory_slot_size=memory_slot_size,
-                    rep_time=rep_time,
-                    rep_delay=rep_delay,
-                    parameter_binds=parameter_binds,
-                    backend=backend,
-                    init_qubits=init_qubits,
-                    **run_config)
-
-    # executing the circuits on the backend and returning the job
-    start_time = time()
-    job = backend.run(qobj, **run_config)
-    end_time = time()
-    _log_submission_time(start_time, end_time)
+    if isinstance(backend, BaseBackend):
+        # assembling the circuits into a qobj to be run on the backend
+        qobj = assemble(experiments,
+                        qobj_id=qobj_id,
+                        qobj_header=qobj_header,
+                        shots=shots,
+                        memory=memory,
+                        max_credits=max_credits,
+                        seed_simulator=seed_simulator,
+                        default_qubit_los=default_qubit_los,
+                        default_meas_los=default_meas_los,
+                        schedule_los=schedule_los,
+                        meas_level=meas_level,
+                        meas_return=meas_return,
+                        memory_slots=memory_slots,
+                        memory_slot_size=memory_slot_size,
+                        rep_time=rep_time,
+                        rep_delay=rep_delay,
+                        parameter_binds=parameter_binds,
+                        backend=backend,
+                        init_qubits=init_qubits,
+                        **run_config)
+
+        # executing the circuits on the backend and returning the job
+        start_time = time()
+        job = backend.run(qobj, **run_config)
+        end_time = time()
+        _log_submission_time(start_time, end_time)
+    elif isinstance(backend, Backend):
+        start_time = time()
+        job = backend.run(experiments,
+                          shots=shots,
+                          memory=memory,
+                          seed_simulator=seed_simulator,
+                          default_qubit_los=default_qubit_los,
+                          default_meas_los=default_meas_los,
+                          schedule_los=schedule_los,
+                          meas_level=meas_level,
+                          meas_return=meas_return,
+                          memory_slots=memory_slots,
+                          memory_slot_size=memory_slot_size,
+                          rep_time=rep_time,
+                          rep_delay=rep_delay,
+                          parameter_binds=parameter_binds,
+                          init_qubits=init_qubits,
+                          **run_config)
+        end_time = time()
+        _log_submission_time(start_time, end_time)
+    else:
+        raise QiskitError("Invalid backend type %s" % type(backend))
     return job
 
 

qiskit/providers/__init__.py

@@ -11,9 +11,109 @@
 # that they have been altered from the originals.
 
 """
-======================================
-Base Objects (:mod:`qiskit.providers`)
-======================================
+================================================
+Providers Interface (:mod:`qiskit.providers`)
+================================================
+
+.. currentmodule:: qiskit.providers
+
+This module contains the classes used to build external providers for Terra. A
+provider is anything that provides an external service to Terra. The typical
+example of this is a Backend provider which provides
+:class:`~qiskit.providers.Backend` objects which can be used for executing
+:class:`~qiskit.circuits.QuantumCircuit` and/or :class:`~qiskit.pulse.Schedule`
+objects. This module contains the abstract classes which are used to define the
+interface between a provider and terra.
+
+Version Support
+===============
+
+Each providers interface abstract class is individually versioned. When we
+need to make a change to an interface a new abstract class will be created to
+define the new interface. These interface changes are not guaranteed to be
+backwards compatible between versions.
+
+Version Changes
+----------------
+
+Each minor version release of qiskit-terra **may** increment the version of any
+providers interface a single version number. It will be an aggreagate of all
+the interface changes for that release on that interface.
+
+Version Support Policy
+----------------------
+
+To enable providers to have time to adjust to changes in this interface
+Terra will support support multiple versions of each class at once. Given the
+nature of one version per release the version deprecation policy is a bit
+more conservative than the standard deprecation policy. Terra will support a
+provider interface version for a minimum of 3 minor releases or the first
+release after 6 months from the release that introduced a version, whichever is
+longer, prior to a potential deprecation. After that the standard deprecation
+policy will apply to that interface version. This will give providers and users
+sufficient time to adapt to potential breaking changes in the interface. So for
+example lets say in 0.19.0 ``BackendV2`` is introduced and in the 3 months after
+the release of 0.19.0 we release 0.20.0, 0.21.0, and 0.22.0, then 7 months after
+0.19.0 we release 0.23.0. In 0.23.0 we can deprecate BackendV2, and it needs to
+still be supported and can't be removed until the deprecation policy completes.
+
+It's worth pointing out that Terra's version support policy doesn't mean
+providers themselves will have the same support story, they can (and arguably
+should) update to newer versions as soon as they can, the support window is
+just for Terra's supported versions. Part of this lengthy window prior to
+deprecation is to give providers enough time to do their own deprecation of a
+potential end user impacting change in a user facing part of the interface
+prior to bumping their version. For example, lets say we changed the signature
+to `Backend.run()` in ``BackendV34`` in a backwards incompatible way, before
+Aer could update its ``AerBackend`` class to use version 34 they'd need to
+deprecate the old signature prior to switching over. The changeover for Aer is
+not guaranteed to be lockstep with Terra so we need to ensure there is a
+sufficient amount of time for Aer to complete it's deprecation cycle prior to
+removing version 33 (ie making version 34 mandatory/the minimum version).
+
+
+Abstract Classes
+================
+
+Provider
+--------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Provider
+   ProviderV1
+
+Backend
+-------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Backend
+   BackendV1
+
+Options
+-------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Options
+
+Job
+---
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Job
+   JobV1
+
+
+================================================================
+Legacy Provider Interface Base Objects (:mod:`qiskit.providers`)
+================================================================
 
 .. currentmodule:: qiskit.providers
 
@@ -49,12 +149,21 @@
 
 import pkgutil
 
-from .basebackend import BaseBackend
-from .baseprovider import BaseProvider
-from .basejob import BaseJob
-from .exceptions import (JobError, JobTimeoutError, QiskitBackendNotFoundError,
-                         BackendPropertyError, BackendConfigurationError)
-from .jobstatus import JobStatus
+# Providers interface
+from qiskit.providers.provider import Provider
+from qiskit.providers.provider import ProviderV1
+from qiskit.providers.backend import Backend
+from qiskit.providers.backend import BackendV1
+from qiskit.providers.options import Options
+from qiskit.providers.job import Job
+from qiskit.providers.job import JobV1
+# Legacy providers interface
+from qiskit.providers.basebackend import BaseBackend
+from qiskit.providers.baseprovider import BaseProvider
+from qiskit.providers.basejob import BaseJob
+from qiskit.providers.exceptions import (JobError, JobTimeoutError, QiskitBackendNotFoundError,
+                                         BackendPropertyError, BackendConfigurationError)
+from qiskit.providers.jobstatus import JobStatus
 
 
 # Allow extending this namespace.