Resolves #262: add qiskit.backend methods...

qiskit/__init__.py

@@ -45,4 +45,6 @@
 from ._quantumprogram import QuantumProgram
 from ._result import Result
 
+from . import backends
+
 __version__ = '0.5.0'

qiskit/_util.py

@@ -16,8 +16,10 @@
 # =============================================================================
 """Common utilities for QISKit."""
 
-import sys
 import logging
+import re
+import sys
+import warnings
 
 API_NAME = 'IBMQuantumExperience'
 logger = logging.getLogger(__name__)
@@ -85,5 +87,27 @@ def _check_ibmqx_version():
                    str(ibmqx_require))
 
 
+def _enable_deprecation_warnings():
+    """
+    Force the `DeprecationWarning` warnings to be displayed for the qiskit
+    module, overriding the system configuration as they are ignored by default
+    [1] for end-users.
+
+    TODO: on Python 3.7, this might not be needed due to PEP-0565 [2].
+
+    [1] https://docs.python.org/3/library/warnings.html#default-warning-filters
+    [2] https://www.python.org/dev/peps/pep-0565/
+    """
+    # pylint: disable=invalid-name
+    deprecation_filter = ('always', None, DeprecationWarning,
+                          re.compile(r'^qiskit\.*', re.UNICODE), 0)
+
+    # Instead of using warnings.simple_filter() directly, the internal
+    # _add_filter() function is used for being able to match against the
+    # module.
+    warnings._add_filter(*deprecation_filter, append=False)
+
+
 _check_python_version()
 _check_ibmqx_version()
+_enable_deprecation_warnings()

qiskit/backends/__init__.py

@@ -19,7 +19,10 @@
 from ._basebackend import BaseBackend
 from ._backendutils import (get_backend_class,
                             get_backend_instance,
-                            get_backend_configuration,
+                            configuration,
+                            calibration,
+                            parameters,
+                            status,
                             local_backends,
                             remote_backends,
                             register_backend,

qiskit/backends/_backendutils.py

@@ -25,7 +25,7 @@
 import re
 from collections import namedtuple
 
-from qiskit import mapper
+import qiskit
 from ._basebackend import BaseBackend
 from .. import QISKitError
 
@@ -89,41 +89,36 @@ def discover_local_backends(directory=os.path.dirname(__file__)):
 
 
 def discover_remote_backends(api):
-    """Discover backends available on the Quantum Experience
+    """Discover backends available from IBM Q
 
     Args:
-        api (IBMQuantumExperience): Quantum Experience API
+        api (IBMQuantumExperience): IBM Q API
     Returns:
         list: list of discovered backend names
     """
     from ._qeremote import QeRemote
     QeRemote.set_api(api)
-    configuration_list = api.available_backends()
+    config_list = api.available_backends()
     backend_name_list = []
-    for configuration in configuration_list:
-        configuration_edit = {}
-        backend_name = configuration['name']
+    for config in config_list:
+        config_edit = {}
+        backend_name = config['name']
         backend_name_list.append(backend_name)
-        configuration_edit['local'] = False
-        for key in configuration.keys():
+        config_edit['local'] = False
+        for key in config.keys():
             new_key = _snake_case_to_camel_case(key)
             if new_key not in ['id', 'serial_number', 'topology_id', 'status']:
-                configuration_edit[new_key] = configuration[key]
-            if new_key == 'coupling_map':
-                if isinstance(configuration[key], list):
-                    cmap = mapper.coupling_list2dict(configuration[key])
-                    configuration_edit[new_key] = cmap
+                config_edit[new_key] = config[key]
         # online_qasm_simulator uses different name for basis_gates
-        if 'gateSet' in configuration:
-            configuration_edit['basis_gates'] = configuration['gateSet']
-            del configuration_edit['gate_set']
+        if 'gateSet' in config:
+            config_edit['basis_gates'] = config['gateSet']
+            del config_edit['gate_set']
         # ibmqx_qasm_simulator doesn't report coupling_map
-        if ('coupling_map' not in configuration_edit.keys() and
-                configuration['simulator']):
-            configuration_edit['coupling_map'] = 'all-to-all'
+        if 'coupling_map' not in config_edit.keys() and config['simulator']:
+            config_edit['coupling_map'] = 'all-to-all'
         registered_backend = RegisteredBackend(backend_name,
                                                QeRemote,
-                                               configuration_edit)
+                                               config_edit)
         _REGISTERED_BACKENDS[backend_name] = registered_backend
     return backend_name_list
 
@@ -153,7 +148,7 @@ def update_backends(api=None):
     return backend_name_list
 
 
-def register_backend(cls, configuration=None):
+def register_backend(cls, configuration_=None):
     """Register a backend in the list of available backends.
 
     Register a `cls` backend in the `_REGISTERED_BACKENDS` dict, validating
@@ -164,7 +159,7 @@ def register_backend(cls, configuration=None):
 
     Args:
         cls (class): a subclass of BaseBackend that contains a backend
-        configuration (dict): backend configuration to use instead of class'
+        configuration_ (dict): backend configuration to use instead of class'
             default.
 
     Returns:
@@ -184,7 +179,7 @@ def register_backend(cls, configuration=None):
         raise QISKitError('Could not register backend: %s is not a subclass '
                           'of BaseBackend' % cls)
     try:
-        backend_instance = cls(configuration=configuration)
+        backend_instance = cls(configuration=configuration_)
     except Exception as err:
         raise QISKitError('Could not register backend: %s could not be '
                           'instantiated: %s' % (cls, err))
@@ -207,7 +202,7 @@ def deregister_backend(backend_name):
     """Remove backend from list of available backens
 
     Args:
-        backend_name (str): name of backend to unregister
+        backend_name (str): name of backend to deregister
 
     Raises:
         KeyError if backend_name is not registered.
@@ -247,13 +242,13 @@ def get_backend_instance(backend_name):
     """
     try:
         registered_backend = _REGISTERED_BACKENDS[backend_name]
+        return registered_backend.cls(
+            configuration=registered_backend.configuration)
     except KeyError:
         raise LookupError('backend "{}" is not available'.format(backend_name))
-    return registered_backend.cls(
-        configuration=registered_backend.configuration)
 
 
-def get_backend_configuration(backend_name):
+def configuration(backend_name):
     """Return the configuration for the named backend.
 
     Args:
@@ -271,6 +266,65 @@ def get_backend_configuration(backend_name):
         raise LookupError('backend "{}" is not available'.format(backend_name))
 
 
+def calibration(backend_name):
+    """Return the calibration for the named backend.
+
+    Args:
+        backend_name (str): the backend name
+
+    Returns:
+        dict: calibration dict
+
+    Raises:
+        LookupError: if backend is unavailable
+    """
+    try:
+        backend = qiskit.backends.get_backend_instance(backend_name)
+        return backend.calibration
+    except KeyError:
+        raise LookupError('backend "{}" is not available'.format(backend_name))
+
+
+def parameters(backend_name):
+    """Return the online backend parameters.
+
+    Args:
+        backend_name (str):  Name of the backend.
+
+    Returns:
+        dict: The parameters of the named backend.
+
+    Raises:
+        ConnectionError: if the API call failed.
+        LookupError: If parameters for the named backend can't be
+            found.
+    """
+    try:
+        backend = qiskit.backends.get_backend_instance(backend_name)
+        return backend.parameters
+    except KeyError:
+        raise LookupError('backend "{}" is not available'.format(backend_name))
+
+
+def status(backend_name):
+    """Return the status for the named backend.
+
+    Args:
+        backend_name (str): the backend name
+
+    Returns:
+        dict: status dict
+
+    Raises:
+        LookupError: if backend is unavailable
+    """
+    try:
+        backend = qiskit.backends.get_backend_instance(backend_name)
+        return backend.status
+    except KeyError:
+        raise LookupError('backend "{}" is not available'.format(backend_name))
+
+
 def local_backends():
     """Get the local backends."""
     return [backend.name for backend in _REGISTERED_BACKENDS.values()

qiskit/backends/_basebackend.py

@@ -50,3 +50,20 @@ def run(self, q_job):
     def configuration(self):
         """Return backend configuration"""
         return self._configuration
+
+    @property
+    def calibration(self):
+        """Return backend calibration"""
+        backend_name = self.configuration['name']
+        return {'backend': backend_name, 'calibrations': None}
+
+    @property
+    def parameters(self):
+        """Return backend parameters"""
+        backend_name = self.configuration['name']
+        return {'backend': backend_name, 'parameters': None}
+
+    @property
+    def status(self):
+        """Return backend status"""
+        return {'available': True}

qiskit/backends/_qeremote.py

@@ -21,6 +21,7 @@
 import time
 import logging
 import pprint
+import re
 from qiskit.backends._basebackend import BaseBackend
 from qiskit import _openquantumcompiler as openquantumcompiler
 from qiskit import QISKitError
@@ -29,6 +30,9 @@
 
 logger = logging.getLogger(__name__)
 
+FIRST_CAP_RE = re.compile('(.)([A-Z][a-z]+)')
+ALL_CAP_RE = re.compile('([a-z0-9])([A-Z])')
+
 
 class QeRemote(BaseBackend):
     """Backend class interfacing with the Quantum Experience remotely.
@@ -115,6 +119,87 @@ def set_api(cls, api):
         """Associate API with class"""
         cls._api = api
 
+    @property
+    def calibration(self):
+        """Return the online backend calibrations.
+
+        The return is via QX API call.
+
+        Returns:
+            dict: The calibration of the backend.
+
+        Raises:
+            ConnectionError: if the API call failed.
+            LookupError: If a configuration for the backend can't be found.
+        """
+        if not self._api:
+            raise ConnectionError('API not set')
+
+        try:
+            backend_name = self.configuration['name']
+            calibrations = self._api.backend_calibration(backend_name)
+        except Exception as ex:
+            raise LookupError(
+                "Couldn't get backend calibration: {0}".format(ex))
+
+        calibrations_edit = {}
+        for key, vals in calibrations.items():
+            new_key = _snake_case_to_camel_case(key)
+            calibrations_edit[new_key] = vals
+
+        return calibrations_edit
+
+    @property
+    def parameters(self):
+        """Return the online backend parameters.
+
+        Returns:
+            dict: The parameters of the backend.
+
+        Raises:
+            ConnectionError: if the API call faled.
+            LookupError: If parameters for the backend can't be found.
+        """
+        if not self._api:
+            raise ConnectionError('API not set')
+
+        try:
+            backend_name = self.configuration['name']
+            parameters = self._api.backend_parameters(backend_name)
+        except Exception as ex:
+            raise LookupError(
+                "Couldn't get backend parameters: {0}".format(ex))
+
+        parameters_edit = {}
+        for key, vals in parameters.items():
+            new_key = _snake_case_to_camel_case(key)
+            parameters_edit[new_key] = vals
+
+        return parameters_edit
+
+    @property
+    def status(self):
+        """Return the online backend status.
+
+        Returns:
+            dict: The status of the backend.
+
+        Raises:
+            ConnectionError: if the API call failed.
+            LookupError: If status for the backend can't be found.
+        """
+        if not self._api:
+            raise ConnectionError('API not set')
+
+        try:
+            backend_name = self.configuration['name']
+            status = self._api.backend_status(backend_name)
+        except Exception as ex:
+            raise LookupError(
+                "Couldn't get backend status: {0}".format(ex))
+
+        return status
+
 
 def _wait_for_job(jobid, api, wait=5, timeout=60):
     """Wait until all online ran circuits of a qobj are 'COMPLETED'.
@@ -161,3 +246,10 @@ def _wait_for_job(jobid, api, wait=5, timeout=60):
                                   'status': job_result['qasms'][index]['status']})
     return {'job_id': jobid, 'status': job_result['status'],
             'result': job_result_return}
+
+
+# this is also in _backendutils but using that was creating cyclic import.
+def _snake_case_to_camel_case(name):
+    """Return a snake case string from a camelcase string."""
+    string_1 = FIRST_CAP_RE.sub(r'\1_\2', name)
+    return ALL_CAP_RE.sub(r'\1_\2', string_1).lower()