azure-quantum 0.29.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

azure/quantum/_client/_version.py

@@ -6,4 +6,4 @@
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 
-VERSION = "0.29.2"
+VERSION = "1.0.0"

azure/quantum/cirq/service.py

@@ -43,6 +43,13 @@ class AzureQuantumService:
         :param default_target: Default target name, defaults to None
         :type default_target: Optional[str], optional
         """
+        if kwargs is not None and len(kwargs) > 0:
+            from warnings import warn
+            warn(f"""Consider passing \"workspace\" argument explicitly. 
+                 The ability to initialize AzureQuantumService with arguments {', '.join(f'"{argName}"' for argName in kwargs)} is going to be deprecated in future versions.""", 
+                 DeprecationWarning, 
+                 stacklevel=2)
+
         if workspace is None:
             workspace = Workspace(**kwargs)
 

azure/quantum/cirq/targets/quantinuum.py

@@ -91,7 +91,7 @@ class QuantinuumTarget(Quantinuum, CirqTarget):
         serialized_program = self._translate_circuit(program)
         return super().estimate_cost(
             circuit=serialized_program,
-            num_shots=repetitions
+            shots=repetitions
         )
 
     def submit(

azure/quantum/job/__init__.py

@@ -4,6 +4,7 @@
 ##
 
 from azure.quantum.job.job import Job
+from azure.quantum.job.job_failed_with_results_error import JobFailedWithResultsError
 from azure.quantum.job.workspace_item import WorkspaceItem
 from azure.quantum.job.workspace_item_factory import WorkspaceItemFactory
 from azure.quantum.job.session import Session, SessionHost

azure/quantum/job/base_job.py

@@ -11,7 +11,7 @@ from urllib.parse import urlparse
 from typing import Any, Dict, Optional, TYPE_CHECKING
 from azure.storage.blob import BlobClient
 
-from azure.quantum.storage import upload_blob, download_blob, ContainerClient
+from azure.quantum.storage import upload_blob, download_blob, download_blob_properties, ContainerClient
 from azure.quantum._client.models import JobDetails
 from azure.quantum.job.workspace_item import WorkspaceItem
 
@@ -26,6 +26,7 @@ DEFAULT_TIMEOUT = 300  # Default timeout for waiting for job to complete
 
 class ContentType(str, Enum):
     json = "application/json"
+    text_plain = "text/plain"
 
 class BaseJob(WorkspaceItem):
     # Optionally override these to create a Provider-specific Job subclass
@@ -261,6 +262,7 @@ class BaseJob(WorkspaceItem):
         )
         return uploaded_blob_uri
 
+
     def download_data(self, blob_uri: str) -> dict:
         """Download file from blob uri
 
@@ -269,23 +271,26 @@ class BaseJob(WorkspaceItem):
         :return: Payload from blob
         :rtype: dict
         """
-        url = urlparse(blob_uri)
-        if url.query.find("se=") == -1:
-            # blob_uri does not contains SAS token,
-            # get sas url from service
-            blob_client = BlobClient.from_blob_url(
-                blob_uri
-            )
-            blob_uri = self.workspace._get_linked_storage_sas_uri(
-                blob_client.container_name, blob_client.blob_name
-            )
-            payload = download_blob(blob_uri)
-        else:
-            # blob_uri contains SAS token, use it
-            payload = download_blob(blob_uri)
+        
+        blob_uri_with_sas_token = self._get_blob_uri_with_sas_token(blob_uri)
+        payload = download_blob(blob_uri_with_sas_token)
 
         return payload
 
+
+    def download_blob_properties(self, blob_uri: str):
+        """Download Blob properties
+
+        :param blob_uri: Blob URI
+        :type blob_uri: str
+        :return: Blob properties
+        :rtype: dict
+        """
+
+        blob_uri_with_sas_token = self._get_blob_uri_with_sas_token(blob_uri)
+        return download_blob_properties(blob_uri_with_sas_token)
+
+
     def upload_attachment(
         self,
         name: str,
@@ -345,3 +350,24 @@ class BaseJob(WorkspaceItem):
         blob_client = container_client.get_blob_client(name)
         response = blob_client.download_blob().readall()
         return response
+
+
+    def _get_blob_uri_with_sas_token(self, blob_uri: str) -> str:
+        """Get Blob URI with SAS-token if one was not specified in blob_uri parameter
+        :param blob_uri: Blob URI
+        :type blob_uri: str
+        :return: Blob URI with SAS-token
+        :rtype: str
+        """
+        url = urlparse(blob_uri)
+        if url.query.find("se=") == -1:
+            # blob_uri does not contains SAS token,
+            # get sas url from service
+            blob_client = BlobClient.from_blob_url(
+                blob_uri
+            )
+            blob_uri = self.workspace._get_linked_storage_sas_uri(
+                blob_client.container_name, blob_client.blob_name
+            )
+
+        return blob_uri

azure/quantum/job/job.py

@@ -11,6 +11,7 @@ import json
 from typing import TYPE_CHECKING
 
 from azure.quantum._client.models import JobDetails
+from azure.quantum.job.job_failed_with_results_error import JobFailedWithResultsError
 from azure.quantum.job.base_job import BaseJob, ContentType, DEFAULT_TIMEOUT
 from azure.quantum.job.filtered_job import FilteredJob
 
@@ -117,6 +118,12 @@ class Job(BaseJob, FilteredJob):
             self.wait_until_completed(timeout_secs=timeout_secs)
 
         if not self.details.status == "Succeeded":
+            if self.details.status == "Failed" and self._allow_failure_results():
+                job_blob_properties = self.download_blob_properties(self.details.output_data_uri)
+                if job_blob_properties.size > 0:
+                    job_failure_data = self.download_data(self.details.output_data_uri)
+                    raise JobFailedWithResultsError("An error occurred during job execution.", job_failure_data)
+
             raise RuntimeError(
                 f'{"Cannot retrieve results as job execution failed"}'
                 + f"(status: {self.details.status}."
@@ -126,7 +133,34 @@ class Job(BaseJob, FilteredJob):
         payload = self.download_data(self.details.output_data_uri)
         try:
             payload = payload.decode("utf8")
-            return json.loads(payload)
+            results = json.loads(payload)
+
+            if self.details.output_data_format == "microsoft.quantum-results.v1":
+                if "Histogram" not in results:
+                    raise f"\"Histogram\" array was expected to be in the Job results for \"{self.details.output_data_format}\" output format."
+                
+                histogram_values = results["Histogram"]
+
+                if len(histogram_values) % 2 == 0:
+                    # Re-mapping {'Histogram': ['[0]', 0.50, '[1]', 0.50] } to {'[0]': 0.50, '[1]': 0.50}
+                    return {histogram_values[i]: histogram_values[i + 1] for i in range(0, len(histogram_values), 2)}
+                else: 
+                    raise f"\"Histogram\" array has invalid format. Even number of items is expected."
+            
+            return results
         except:
             # If errors decoding the data, return the raw payload:
             return payload
+
+
+    @classmethod
+    def _allow_failure_results(cls) -> bool: 
+        """
+        Allow to download job results even if the Job status is "Failed".
+
+        This method can be overridden in derived classes to alter the default
+        behaviour.
+
+        The default is False.
+        """
+        return False

azure/quantum/job/job_failed_with_results_error.py

@@ -0,0 +1,41 @@
+import json
+from typing import Any, Dict, Union
+
+class JobFailedWithResultsError(RuntimeError):
+    """
+    Error produced when Job completes with status "Failed" and the Job
+    supports producing failure results.
+
+    The failure results can be accessed with get_failure_results() method
+    """
+    
+    def __init__(self, message: str, failure_results: Any, *args: object) -> None:
+        self._set_error_details(message, failure_results)
+        super().__init__(message, *args)
+
+
+    def _set_error_details(self, message: str, failure_results: Any) -> None:
+        self._message = message
+        try:
+            decoded_failure_results = failure_results.decode("utf8")
+            self._failure_results: Dict[str, Any] = json.loads(decoded_failure_results)
+        except:
+            self._failure_results = failure_results
+
+
+    def get_message(self) -> str:
+        """
+        Get error message.
+        """
+        return self._message
+
+
+    def get_failure_results(self) -> Union[Dict[str, Any], str]:
+        """
+        Get failure results produced by the job.
+        """
+        return self._failure_results
+    
+
+    def __str__(self) -> str:
+        return f"{self._message}\nFailure results: {self._failure_results}"

azure/quantum/qiskit/backends/backend.py

@@ -10,7 +10,7 @@ import warnings
 
 logger = logging.getLogger(__name__)
 
-from typing import Any, Dict, Tuple, Union, List
+from typing import Any, Dict, Tuple, Union, List, Optional
 from azure.quantum.version import __version__
 from azure.quantum.qiskit.job import (
     MICROSOFT_OUTPUT_DATA_FORMAT,
@@ -38,6 +38,11 @@ To install run: pip install azure-quantum[qiskit]"
 
 
 class AzureBackendBase(Backend, SessionHost):
+
+    # Name of the provider's input parameter which specifies number of shots for a submitted job.
+    # If None, backend will not pass this input parameter. 
+    _SHOTS_PARAM_NAME = None
+
     @abstractmethod
     def __init__(
         self,
@@ -46,6 +51,41 @@ class AzureBackendBase(Backend, SessionHost):
         **fields
     ):
         super().__init__(configuration, provider, **fields)
+    
+    @abstractmethod
+    def run(
+        self,
+        run_input: Union[QuantumCircuit, List[QuantumCircuit]] = [],
+        shots: int = None, 
+        **options,
+    ) -> AzureQuantumJob:
+        """Run on the backend.
+
+        This method returns a
+        :class:`~azure.quantum.qiskit.job.AzureQuantumJob` object
+        that runs circuits. 
+
+        Args:
+            run_input (QuantumCircuit or List[QuantumCircuit]): An individual or a
+            list of :class:`~qiskit.circuits.QuantumCircuit` to run on the backend.
+            shots (int, optional): Number of shots, defaults to None.
+            options: Any kwarg options to pass to the backend for running the
+            config. If a key is also present in the options
+            attribute/object then the expectation is that the value
+            specified will be used instead of what's set in the options
+            object.
+
+        Returns:
+            Job: The job object for the run
+        """
+        pass
+
+    @classmethod
+    def _can_send_shots_input_param(cls) -> bool:
+        """
+        Tells if provider's backend class is able to specify shots number for its jobs.
+        """
+        return cls._SHOTS_PARAM_NAME is not None
 
     @classmethod
     @abstractmethod
@@ -80,30 +120,47 @@ class AzureBackendBase(Backend, SessionHost):
         output_data_format = options.pop("output_data_format", azure_defined_override)
 
         return output_data_format
-
-    def _get_input_params(self, options) -> Dict[str, Any]:
+    
+    def _get_input_params(self, options, shots: int = None) -> Dict[str, Any]:
         # Backend options are mapped to input_params.
         input_params: Dict[str, Any] = vars(self.options).copy()
 
-        # The shots/count number can be specified in different ways for different providers,
-        # so let's get it first. Values in 'kwargs' take precedence over options, and to keep
-        # the convention, 'count' takes precedence over 'shots' afterwards.
-        shots_count = (
-            options["count"]
-            if "count" in options
-            else options["shots"]
-            if "shots" in options
-            else input_params["count"]
-            if "count" in input_params
-            else input_params["shots"]
-            if "shots" in input_params
-            else None
-        )
+        # Determine shots number, if needed.
+        if self._can_send_shots_input_param():
+            options_shots = options.pop(self.__class__._SHOTS_PARAM_NAME, None)
+
+            # First we check for the explicitly specified 'shots' parameter, then for a provider-specific
+            # field in options, then for a backend's default value. 
+
+            # Warn abount options conflict, default to 'shots'.
+            if shots is not None and options_shots is not None:
+                warnings.warn(
+                    f"Parameter 'shots' conflicts with the '{self.__class__._SHOTS_PARAM_NAME}' parameter. "
+                    "Please, provide only one option for setting shots. Defaulting to 'shots' parameter."
+                )
+                final_shots = shots
+            
+            elif shots is not None:
+                final_shots = shots
+            else:
+                warnings.warn(
+                    f"Parameter '{self.__class__._SHOTS_PARAM_NAME}' is subject to change in future versions. "
+                    "Please, use 'shots' parameter instead."
+                )
+                final_shots = options_shots
+            
+            # If nothing is found, try to get from default values.
+            if final_shots is None:
+                final_shots = input_params.get(self.__class__._SHOTS_PARAM_NAME)
+
+            # Also add all possible shots options into input_params to make sure 
+            # that all backends covered. 
+            # TODO: Double check all backends for shots options in order to remove this extra check.
+            input_params["shots"] = final_shots
+            input_params["count"] = final_shots
 
-        # Let's clear the options of both properties regardless of which one was used to prevent
-        # double specification of the value.
-        options.pop("shots", None)
-        options.pop("count", None)
+            input_params[self.__class__._SHOTS_PARAM_NAME] = final_shots
+            
 
         if "items" in options:
             input_params["items"] = options.pop("items")
@@ -114,9 +171,6 @@ class AzureBackendBase(Backend, SessionHost):
             if opt in input_params:
                 input_params[opt] = options.pop(opt)
 
-        input_params["count"] = shots_count
-        input_params["shots"] = shots_count
-
         return input_params
 
     def _run(self, job_name, input_data, input_params, metadata, **options):
@@ -223,18 +277,21 @@ class AzureQirBackend(AzureBackendBase):
         }
 
     def run(
-        self, run_input: Union[QuantumCircuit, List[QuantumCircuit]] = [], **options
+        self,
+        run_input: Union[QuantumCircuit, List[QuantumCircuit]] = [],
+        shots: int = None, 
+        **options,
     ) -> AzureQuantumJob:
         """Run on the backend.
 
         This method returns a
         :class:`~azure.quantum.qiskit.job.AzureQuantumJob` object
-        that runs circuits. This is an async call.
+        that runs circuits.
 
         Args:
             run_input (QuantumCircuit or List[QuantumCircuit]): An individual or a
             list of :class:`~qiskit.circuits.QuantumCircuit` to run on the backend.
-
+            shots (int, optional): Number of shots, defaults to None.
             options: Any kwarg options to pass to the backend for running the
             config. If a key is also present in the options
             attribute/object then the expectation is that the value
@@ -261,13 +318,18 @@ class AzureQirBackend(AzureBackendBase):
             )
 
         # config normalization
-        input_params = self._get_input_params(options)
+        input_params = self._get_input_params(options, shots=shots)
+        
+        shots_count = None
 
-        shots_count = input_params["count"]
+        if self._can_send_shots_input_param():
+            shots_count = input_params.get(self.__class__._SHOTS_PARAM_NAME)
 
         job_name = ""
         if len(circuits) > 1:
-            job_name = f"batch-{len(circuits)}-{shots_count}"
+            job_name = f"batch-{len(circuits)}"
+            if shots_count is not None:
+                job_name = f"{job_name}-{shots_count}"
         else:
             job_name = circuits[0].name
         job_name = options.pop("job_name", job_name)
@@ -386,9 +448,13 @@ class AzureBackend(AzureBackendBase):
     def _translate_input(self, circuit):
         pass
 
-    def run(self, run_input=None, **kwargs):
-        """Submits the given circuit to run on an Azure Quantum backend."""
-        options = kwargs
+    def run(
+            self, 
+            run_input: Union[QuantumCircuit, List[QuantumCircuit]] = [],
+            shots: int = None,
+            **options,
+        ):
+        """Submits the given circuit to run on an Azure Quantum backend.""" 
         circuit = self._normalize_run_input_params(run_input, **options)
         options.pop("run_input", None)
         options.pop("circuit", None)
@@ -417,16 +483,45 @@ class AzureBackend(AzureBackendBase):
         job_name = options.pop("job_name", circuit.name)
         metadata = options.pop("metadata", self._prepare_job_metadata(circuit))
 
-        input_params = self._get_input_params(options)
+        input_params = self._get_input_params(options, shots=shots)
 
         input_data = self._translate_input(circuit)
 
         job = super()._run(job_name, input_data, input_params, metadata, **options)
 
-        shots_count = input_params["count"]
+        shots_count = None
+        if self._can_send_shots_input_param():
+            shots_count = input_params.get(self.__class__._SHOTS_PARAM_NAME)
+
         logger.info(
             f"Submitted job with id '{job.id()}' for circuit '{circuit.name}' with shot count of {shots_count}:"
         )
         logger.info(input_data)
 
         return job
+
+def _get_shots_or_deprecated_count_input_param(
+        param_name: str,
+        shots: int = None, 
+        count: int = None,
+    ) -> Optional[int]:
+    """
+    This helper function checks if the deprecated 'count' option is specified.
+    In earlier versions it was possible to pass this option to specify shots number for a job,
+    but now we only check for it for compatibility reasons.  
+    """
+
+    final_shots = None
+
+    if shots is not None:
+        final_shots = shots
+    
+    elif count is not None:
+        final_shots = count
+        warnings.warn(
+            "The 'count' parameter will be deprecated. "
+            f"Please, use '{param_name}' parameter instead.",
+            category=DeprecationWarning,
+        )
+    
+    return final_shots

azure/quantum/qiskit/backends/ionq.py

@@ -2,12 +2,19 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 ##
-from typing import TYPE_CHECKING, Dict
+from typing import TYPE_CHECKING, Dict, List, Union
 from azure.quantum import __version__
+from azure.quantum.qiskit.job import AzureQuantumJob
 from azure.quantum.target.ionq import IonQ
 from abc import abstractmethod
 
-from .backend import AzureBackend, AzureQirBackend
+from qiskit import QuantumCircuit
+
+from .backend import (
+    AzureBackend, 
+    AzureQirBackend, 
+    _get_shots_or_deprecated_count_input_param
+)
 
 from qiskit.providers.models import BackendConfiguration
 from qiskit.providers import Options, Provider
@@ -42,10 +49,14 @@ __all__ = [
     "IonQForteNativeBackend",
 ]
 
+_IONQ_SHOTS_INPUT_PARAM_NAME = "shots"
+_DEFAULT_SHOTS_COUNT = 500
 
 class IonQQirBackendBase(AzureQirBackend):
     """Base class for interfacing with an IonQ QIR backend"""
 
+    _SHOTS_PARAM_NAME = _IONQ_SHOTS_INPUT_PARAM_NAME
+
     @abstractmethod
     def __init__(
         self, configuration: BackendConfiguration, provider: Provider = None, **fields
@@ -54,7 +65,12 @@ class IonQQirBackendBase(AzureQirBackend):
 
     @classmethod
     def _default_options(cls) -> Options:
-        return Options(shots=500, targetCapability="BasicExecution")
+        return Options(
+            **{
+                cls._SHOTS_PARAM_NAME: _DEFAULT_SHOTS_COUNT,
+            },
+            targetCapability="BasicExecution",
+            )
 
     def _azure_config(self) -> Dict[str, str]:
         config = super()._azure_config()
@@ -64,6 +80,25 @@ class IonQQirBackendBase(AzureQirBackend):
             }
         )
         return config
+    
+    def run(
+        self, 
+        run_input: Union[QuantumCircuit, List[QuantumCircuit]] = [],
+        shots: int = None,
+        **options,
+    ) -> AzureQuantumJob:
+        
+        # In earlier versions, backends for all providers accepted the 'count' option,
+        # but now we accept it only for a compatibility reasons and do not recommend using it.
+        count = options.pop("count", None)
+
+        final_shots = _get_shots_or_deprecated_count_input_param(
+            param_name=self.__class__._SHOTS_PARAM_NAME,
+            shots=shots,
+            count=count,
+        )
+        
+        return super().run(run_input, shots=final_shots, **options)
 
 
 class IonQSimulatorQirBackend(IonQQirBackendBase):
@@ -199,15 +234,40 @@ class IonQBackend(AzureBackend):
 
     backend_name = None
 
+    _SHOTS_PARAM_NAME = _IONQ_SHOTS_INPUT_PARAM_NAME
+
     @abstractmethod
     def __init__(
         self, configuration: BackendConfiguration, provider: Provider = None, **fields
     ):
         super().__init__(configuration, provider, **fields)
 
+    def run(
+        self, 
+        run_input=None,
+        shots: int = None,
+        **options,
+    ) -> AzureQuantumJob:
+        
+        # In earlier versions, backends for all providers accepted the 'count' option,
+        # but now we accept it only for a compatibility reasons and do not recommend using it.
+        count = options.pop("count", None)
+
+        final_shots = _get_shots_or_deprecated_count_input_param(
+            param_name=self.__class__._SHOTS_PARAM_NAME,
+            shots=shots,
+            count=count,
+        )
+        
+        return super().run(run_input, shots=final_shots, **options)
+
     @classmethod
     def _default_options(cls):
-        return Options(shots=500)
+        return Options(
+            **{
+                cls._SHOTS_PARAM_NAME: _DEFAULT_SHOTS_COUNT,
+            },
+        )
 
     def _azure_config(self) -> Dict[str, str]:
         return {
@@ -249,7 +309,7 @@ class IonQBackend(AzureBackend):
         }
         workspace = self.provider().get_workspace()
         target = workspace.get_targets(self.name())
-        return target.estimate_cost(input_data, num_shots=shots)
+        return target.estimate_cost(input_data, shots=shots)
 
 
 class IonQSimulatorBackend(IonQBackend):

azure/quantum/qiskit/backends/qci.py

@@ -5,8 +5,12 @@
 
 from typing import TYPE_CHECKING, Dict
 from azure.quantum.version import __version__
+from azure.quantum.qiskit.job import AzureQuantumJob
 from abc import abstractmethod
-from .backend import AzureQirBackend
+from .backend import (
+    AzureQirBackend, 
+    _get_shots_or_deprecated_count_input_param,
+)
 
 from qiskit.providers.models import BackendConfiguration
 from qiskit.providers import Options, Provider
@@ -43,7 +47,12 @@ logger = logging.getLogger(__name__)
 __all__ = ["QCISimulatorBackend" "QCIQPUBackend"]
 
 
+_DEFAULT_SHOTS_COUNT = 500
+
 class QCIBackend(AzureQirBackend):
+
+    _SHOTS_PARAM_NAME = "shots"
+
     @abstractmethod
     def __init__(
         self, configuration: BackendConfiguration, provider: Provider = None, **fields
@@ -52,7 +61,12 @@ class QCIBackend(AzureQirBackend):
 
     @classmethod
     def _default_options(cls) -> Options:
-        return Options(shots=500, targetCapability="AdaptiveExecution")
+        return Options(
+            **{
+                cls._SHOTS_PARAM_NAME: _DEFAULT_SHOTS_COUNT, 
+            },
+            targetCapability="AdaptiveExecution",
+        )
 
     def _azure_config(self) -> Dict[str, str]:
         config = super()._azure_config()
@@ -62,6 +76,25 @@ class QCIBackend(AzureQirBackend):
             }
         )
         return config
+    
+    def run(
+        self, 
+        run_input=None,
+        shots: int = None,
+        **options,
+    ) -> AzureQuantumJob:
+        
+        # In earlier versions, backends for all providers accepted the 'count' option,
+        # but now we accept it only for a compatibility reasons and do not recommend using it.
+        count = options.pop("count", None)
+
+        final_shots = _get_shots_or_deprecated_count_input_param(
+            param_name=self.__class__._SHOTS_PARAM_NAME,
+            shots=shots,
+            count=count,
+        )
+        
+        return super().run(run_input, shots=final_shots, **options)
 
 
 class QCISimulatorBackend(QCIBackend):