Runtime service (#926)

* runtime service

* add directory

* use env var for file names

* add interim queue

* interim result

* add runtime options

* add circuits to encoder

* move encoder to utils

* reformat doc

* add whether parameter is required

* use real url

* get single program

* always use interim queue

* use dill

* use real url

* fix urls

* add logging

* use real coders

* add user messenger

* fix import

* fix setup

* add program backend

* add to_json in encoder

* interim results

* move json coder

* clarify docstring

* return program max_execution_time

* make max_execution_time required

* get runtime url from server

* update ws

* add job cancel

* add doc and tests

* fix lint

* fix doc

* fix doc

* add more tests

* fix mypy

* fix serializable class

* add release notes

* fix program name

* fix tests

* add metadata

* add result decoder

* add metadata

* add pagination

* use qobj

* remove unused code

* fix typo

* remove qobj

* add ws tests

* change program output format

* fix test job status

* remove update program

* fix run_circuits parameters

* doc update

* fix lint

* minor doc update

* more minor doc update

* fix doc link

Author: jyu00

.github/workflows/main.yml

@@ -78,7 +78,6 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -U -c constraints.txt -r requirements-dev.txt
-          pip install -U git+https://github.com/Qiskit/qiskit-aer.git
           pip install -c constraints.txt -e .
       - name: Run Tests
         run: make test

docs/apidocs/ibmq-provider.rst

@@ -14,3 +14,4 @@ Qiskit IBM Quantum Provider API Reference
    ibmq_utils
    ibmq_random
    ibmq_experiment
+   ibmq_runtime

docs/apidocs/ibmq_runtime.rst

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

qiskit/providers/ibmq/accountprovider.py

@@ -13,13 +13,18 @@
 """Provider for a single IBM Quantum Experience account."""
 
 import logging
-from typing import Dict, List, Optional, Any, Callable
+from typing import Dict, List, Optional, Any, Callable, Union
 from collections import OrderedDict
 import traceback
 
 from qiskit.providers import ProviderV1 as Provider  # type: ignore[attr-defined]
 from qiskit.providers.models import (QasmBackendConfiguration,
                                      PulseBackendConfiguration)
+from qiskit.circuit import QuantumCircuit
+from qiskit.providers.backend import BackendV1 as Backend
+from qiskit.providers.basebackend import BaseBackend
+from qiskit.transpiler import Layout
+from qiskit.providers.ibmq.runtime import runtime_job  # pylint: disable=unused-import
 
 from .api.clients import AccountClient
 from .ibmqbackend import IBMQBackend, IBMQSimulator
@@ -28,6 +33,7 @@
 from .utils.json_decoder import decode_backend_configuration
 from .random.ibmqrandomservice import IBMQRandomService
 from .experiment.experimentservice import ExperimentService
+from .runtime.ibm_runtime_service import IBMRuntimeService
 from .exceptions import IBMQNotAuthorizedError, IBMQInputValueError
 
 logger = logging.getLogger(__name__)
@@ -89,18 +95,16 @@ class AccountProvider(Provider):
         in Jupyter Notebook and the Python interpreter.
     """
 
-    def __init__(self, credentials: Credentials, access_token: str) -> None:
+    def __init__(self, credentials: Credentials) -> None:
         """AccountProvider constructor.
 
         Args:
             credentials: IBM Quantum Experience credentials.
-            access_token: IBM Quantum Experience access token.
         """
         super().__init__()
 
         self.credentials = credentials
-        self._api_client = AccountClient(access_token,
-                                         credentials,
+        self._api_client = AccountClient(credentials,
                                          **credentials.connection_parameters())
 
         # Initialize the internal list of backends.
@@ -109,14 +113,15 @@ def __init__(self, credentials: Credentials, access_token: str) -> None:
         self.backends = IBMQDeprecatedBackendService(self.backend)  # type: ignore[assignment]
 
         # Initialize other services.
-        self._random = IBMQRandomService(self, access_token) \
-            if credentials.extractor_url else None
-        self._experiment = ExperimentService(self, access_token) \
-            if credentials.experiment_url else None
+        self._random = IBMQRandomService(self) if credentials.extractor_url else None
+        self._experiment = ExperimentService(self) if credentials.experiment_url else None
+        self._runtime = IBMRuntimeService(self) \
+            if credentials.runtime_url else None
 
         self._services = {'backend': self._backend,
                           'random': self._random,
-                          'experiment': self._experiment}
+                          'experiment': self._experiment,
+                          'runtime': self._runtime}
 
     def backends(
             self,
@@ -188,6 +193,102 @@ def _discover_remote_backends(self, timeout: Optional[float] = None) -> Dict[str
 
         return ret
 
+    def run_circuits(
+            self,
+            circuits: Union[QuantumCircuit, List[QuantumCircuit]],
+            backend: Union[Backend, BaseBackend],
+            shots: Optional[int] = None,
+            initial_layout: Optional[Union[Layout, Dict, List]] = None,
+            layout_method: Optional[str] = None,
+            routing_method: Optional[str] = None,
+            translation_method: Optional[str] = None,
+            seed_transpiler: Optional[int] = None,
+            optimization_level: Optional[int] = None,
+            init_qubits: Optional[bool] = True,
+            rep_delay: Optional[float] = None,
+            transpiler_options: Optional[dict] = None,
+            measurement_error_mitigation: Optional[bool] = False,
+            **run_config: Dict
+    ) -> 'runtime_job.RuntimeJob':
+        """Execute the input circuit(s) on a backend using the runtime service.
+
+        Note:
+            This method uses the IBM Quantum runtime service which is not
+            available to all accounts.
+
+        Note:
+            This method returns a :class:``~qiskit.provider.ibmq.runtime.RuntimeJob``.
+            To get the job result, you'll need to use the
+            ``qiskit_runtime.circuit_runner.RunnerResult`` class
+            as the ``decoder``, e.g.::
+
+                result = provider.run_circuits(...).result(decoder=RunnerResult)
+
+            You can find more about the ``RunnerResult`` class in the
+            `qiskit-runtime repository <https://github.com/Qiskit-Partners/qiskit-runtime>`_.
+
+        Args:
+            circuits: Circuit(s) to execute.
+
+            backend: Backend to execute circuits on.
+                Transpiler options are automatically grabbed from backend configuration
+                and properties unless otherwise specified.
+
+            initial_layout: Initial position of virtual qubits on physical qubits.
+
+            layout_method: Name of layout selection pass ('trivial', 'dense',
+                'noise_adaptive', 'sabre').
+                Sometimes a perfect layout can be available in which case the layout_method
+                may not run.
+
+            routing_method: Name of routing pass ('basic', 'lookahead', 'stochastic', 'sabre')
+
+            translation_method: Name of translation pass ('unroller', 'translator', 'synthesis')
+
+            seed_transpiler: Sets random seed for the stochastic parts of the transpiler.
+
+            optimization_level: How much optimization to perform on the circuits.
+                Higher levels generate more optimized circuits, at the expense of longer
+                transpilation time.
+                If None, level 1 will be chosen as default.
+
+            shots: Number of repetitions of each circuit, for sampling. Default: 1024.
+
+            rep_delay: Delay between programs in seconds. Only supported on certain
+                backends (``backend.configuration().dynamic_reprate_enabled`` ). If supported,
+                ``rep_delay`` will be used instead of ``rep_time`` and must be from the
+                range supplied by the backend (``backend.configuration().rep_delay_range``).
+                Default is given by ``backend.configuration().default_rep_delay``.
+
+            init_qubits: Whether to reset the qubits to the ground state for each shot.
+
+            transpiler_options: Additional transpiler options.
+
+            measurement_error_mitigation: Whether to apply measurement error mitigation.
+
+            **run_config: Extra arguments used to configure the circuit execution.
+
+        Returns:
+            Runtime job.
+        """
+        inputs = {
+            'circuits': circuits,
+            'initial_layout': initial_layout,
+            'seed_transpiler': seed_transpiler,
+            'optimization_level': optimization_level,
+            'layout_method': layout_method,
+            'shots': shots,
+            'routing_method': routing_method,
+            'translation_method': translation_method,
+            'rep_delay': rep_delay,
+            'init_qubits': init_qubits,
+            'transpiler_options': transpiler_options,
+            'measurement_error_mitigation': measurement_error_mitigation
+        }
+        inputs.update(run_config)
+        options = {'backend_name': backend.name()}
+        return self.runtime.run('circuit-runner', options=options, inputs=inputs)
+
     def service(self, name: str) -> Any:
         """Return the specified service.
 
@@ -218,6 +319,26 @@ def services(self) -> Dict:
         """
         return {key: val for key, val in self._services.items() if val is not None}
 
+    def has_service(self, name: str) -> bool:
+        """Check if this provider has access to the service.
+
+        Args:
+            name: Name of the service.
+
+        Returns:
+            Whether the provider has access to the service.
+
+        Raises:
+            IBMQInputValueError: If an unknown service name is specified.
+        """
+        if name not in self._services:
+            raise IBMQInputValueError(f"Unknown service {name} specified.")
+
+        if self._services[name] is None:
+            return False
+
+        return True
+
     @property
     def backend(self) -> IBMQBackendService:
         """Return the backend service.
@@ -257,7 +378,22 @@ def random(self) -> IBMQRandomService:
         if self._random:
             return self._random
         else:
-            raise IBMQNotAuthorizedError("You are not authorized to use the random number service.")
+            raise IBMQNotAuthorizedError("You are not authorized to use the service.")
+
+    @property
+    def runtime(self) -> IBMRuntimeService:
+        """Return the runtime service.
+
+        Returns:
+            The runtime service instance.
+
+        Raises:
+            IBMQNotAuthorizedError: If the account is not authorized to use the service.
+        """
+        if self._runtime:
+            return self._runtime
+        else:
+            raise IBMQNotAuthorizedError("You are not authorized to use the runtime service.")
 
     def __eq__(
             self,

qiskit/providers/ibmq/api/clients/__init__.py

@@ -17,3 +17,5 @@
 from .auth import AuthClient
 from .version import VersionClient
 from .websocket import WebsocketClient
+from .runtime import RuntimeClient
+from .runtime_ws import RuntimeWebsocketClient

qiskit/providers/ibmq/api/clients/account.py

@@ -41,24 +41,23 @@ class AccountClient(BaseClient):
 
     def __init__(
             self,
-            access_token: str,
             credentials: Credentials,
             **request_kwargs: Any
     ) -> None:
         """AccountClient constructor.
 
         Args:
-            access_token: IBM Quantum Experience access token.
             credentials: Account credentials.
             **request_kwargs: Arguments for the request ``Session``.
         """
-        self._session = RetrySession(credentials.base_url, access_token, **request_kwargs)
+        self._session = RetrySession(
+            credentials.base_url, credentials.access_token, **request_kwargs)
         # base_api is used to handle endpoints that don't include h/g/p.
         # account_api is for h/g/p.
         self.base_api = Api(self._session)
         self.account_api = Account(session=self._session, hub=credentials.hub,
                                    group=credentials.group, project=credentials.project)
-        self.client_ws = WebsocketClient(credentials.websockets_url, access_token)
+        self.client_ws = WebsocketClient(credentials.websockets_url, credentials.access_token)
         self._use_websockets = (not credentials.proxies)
 
     # Backend-related public functions.

qiskit/providers/ibmq/api/clients/experiment.py

@@ -29,16 +29,14 @@ class ExperimentClient(BaseClient):
 
     def __init__(
             self,
-            access_token: str,
             credentials: Credentials
     ) -> None:
         """ExperimentClient constructor.
 
         Args:
-            access_token: IBM Quantum Experience access token.
             credentials: Account credentials.
         """
-        self._session = RetrySession(credentials.experiment_url, access_token,
+        self._session = RetrySession(credentials.experiment_url, credentials.access_token,
                                      **credentials.connection_parameters())
         self.base_api = Api(self._session)
 

qiskit/providers/ibmq/api/clients/random.py

@@ -28,16 +28,14 @@ class RandomClient:
 
     def __init__(
             self,
-            access_token: str,
             credentials: Credentials,
     ) -> None:
         """RandomClient constructor.
 
         Args:
-            access_token: IBM Quantum Experience access token.
             credentials: Account credentials.
         """
-        self._session = RetrySession(credentials.extractor_url, access_token,
+        self._session = RetrySession(credentials.extractor_url, credentials.access_token,
                                      **credentials.connection_parameters())
         self.random_api = Random(self._session)
 
@@ -47,7 +45,6 @@ def list_services(self) -> List[Dict[str, Any]]:
         Returns:
             RNG services available for this provider.
         """
-        # return [{'name': 'cqc', 'extractors': ['ext1', 'ext2']}]
         return self.random_api.list_services()
 
     def extract(