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

azure/quantum/target/ionq.py

@@ -3,8 +3,12 @@
 # Licensed under the MIT License.
 ##
 from typing import Any, Dict, List
+from warnings import warn
 
-from azure.quantum.target.target import Target
+from azure.quantum.target.target import (
+    Target,
+    _determine_shots_or_deprecated_num_shots,
+)
 from azure.quantum.job.job import Job
 from azure.quantum.workspace import Workspace
 from azure.quantum._client.models import CostEstimate, UsageEvent
@@ -50,6 +54,8 @@ class IonQ(Target):
         "ionq.qpu.forte-1"
     )
 
+    _SHOTS_PARAM_NAME = "shots"
+
     def __init__(
         self,
         workspace: Workspace,
@@ -78,7 +84,7 @@ class IonQ(Target):
         self,
         circuit: Dict[str, Any] = None,
         name: str = "ionq-job",
-        num_shots: int = None,
+        shots: int = None,
         input_params: Dict[str, Any] = None,
         **kwargs
     ) -> Job:
@@ -89,8 +95,8 @@ class IonQ(Target):
         :type circuit: Dict[str, Any]
         :param name: Job name
         :type name: str
-        :param num_shots: Number of shots, defaults to None
-        :type num_shots: int
+        :param shots: Number of shots, defaults to None
+        :type shots: int
         :param input_params: Optional input params dict
         :type input_params: Dict[str, Any]
         :return: Azure Quantum job
@@ -103,13 +109,18 @@ class IonQ(Target):
             )
         if input_params is None:
             input_params = {}
-        if num_shots is not None:
-            input_params = input_params.copy()
-            input_params["shots"] = num_shots
 
+        num_shots = kwargs.pop("num_shots", None)
+
+        shots = _determine_shots_or_deprecated_num_shots(
+            shots=shots,
+            num_shots=num_shots,
+        )
+        
         return super().submit(
             input_data=input_data,
             name=name,
+            shots=shots,
             input_params=input_params,
             **kwargs
         )
@@ -117,10 +128,11 @@ class IonQ(Target):
     def estimate_cost(
         self,
         circuit: Dict[str, Any],
-        num_shots: int,
+        num_shots: int = None,
         price_1q: float = None,
         price_2q: float = None,
-        min_price: float = None
+        min_price: float = None,
+        shots: int = None
     ) -> CostEstimate:
         """Estimate the cost of submitting a circuit to IonQ targets.
         Optionally, you can provide the number of gate and measurement operations
@@ -156,7 +168,20 @@ class IonQ(Target):
         :type price_2q: float, optional
         :param min_price: The minimum price for running a job.
         :type min_price: float, optional
+        :param shots: Number of shots, defaults to None
+        :type shots: int
         """
+
+        if num_shots is None and shots is None:
+             raise ValueError("The 'shots' parameter has to be specified")
+
+        if num_shots is not None:
+            warn(
+                "The 'num_shots' parameter will be deprecated. Please, use 'shots' parameter instead.",
+                category=DeprecationWarning,
+            )
+            shots = num_shots
+
         def is_1q_gate(gate: Dict[str, Any]):
             return "controls" not in gate and "control" not in gate
 
@@ -185,7 +210,7 @@ class IonQ(Target):
         N_1q = sum(map(is_1q_gate, gates))
         N_2q = sum(map(num_2q_gates, filter(is_multi_q_gate, gates)))
 
-        price = (price_1q * N_1q + price_2q * N_2q) * num_shots
+        price = (price_1q * N_1q + price_2q * N_2q) * shots
         price = max(price, min_price)
 
         return CostEstimate(
@@ -195,7 +220,7 @@ class IonQ(Target):
                     dimension_name="1Q Gate Shot",
                     measure_unit="1q gate shot",
                     amount_billed=0.0,
-                    amount_consumed=N_1q * num_shots,
+                    amount_consumed=N_1q * shots,
                     unit_price=0.0
                 ),
                 UsageEvent(
@@ -203,7 +228,7 @@ class IonQ(Target):
                     dimension_name="2Q Gate Shot",
                     measure_unit="2q gate shot",
                     amount_billed=0.0,
-                    amount_consumed=N_2q * num_shots,
+                    amount_consumed=N_2q * shots,
                     unit_price=0.0
                 )
             ],

azure/quantum/target/microsoft/elements/dft/target.py

@@ -1,3 +1,5 @@
+import warnings
+
 from azure.quantum.job.base_job import ContentType
 from azure.quantum.job.job import Job
 from azure.quantum.target.target import Target
@@ -43,10 +45,20 @@ class MicrosoftElementsDft(Target):
     def submit(self,
                input_data: Any,
                name: str = "azure-quantum-dft-job",
+               shots: int = None,
                input_params: Union[Dict[str, Any], InputParams, None] = None,
                **kwargs) -> MicrosoftElementsDftJob:
+
+        if shots is not None:
+            warnings.warn("The 'shots' parameter is ignored in Microsoft Elements Dft job.")
         
-        return super().submit(input_data, name, input_params, **kwargs)
+        return super().submit(
+            input_data=input_data,
+            name=name, 
+            shots=shots, 
+            input_params=input_params,
+            **kwargs
+        )
 
 
     @classmethod

azure/quantum/target/microsoft/target.py

@@ -3,8 +3,10 @@
 # Licensed under the MIT License.
 ##
 import re
+import warnings
 from dataclasses import dataclass, field
-from typing import Any, Dict, Optional, Type, Union
+from typing import Any, Dict, Optional, Type, Union, List
+
 from ...job import Job
 from ...job.base_job import ContentType
 from ...workspace import Workspace
@@ -12,8 +14,6 @@ from ..params import InputParams, InputParamsItem, AutoValidatingParams, \
     validating_field
 from ..target import Target
 from . import MicrosoftEstimatorJob
-from typing import List
-
 
 class QubitParams:
     GATE_US_E3 = "qubit_gate_us_e3"
@@ -377,11 +377,32 @@ class MicrosoftEstimator(Target):
             **kwargs
         )
 
-    def submit(self,
-               input_data: Any,
-               name: str = "azure-quantum-job",
-               input_params: Union[Dict[str, Any], InputParams, None] = None,
-               **kwargs) -> Job:
+    def submit(
+        self,
+        input_data: Any,
+        name: str = "azure-quantum-job",
+        shots: int = None,
+        input_params: Union[Dict[str, Any], InputParams, None] = None,
+        **kwargs,
+    ) -> Job:
+        """
+        Submit an estimation job
+
+        :param input_data: Input data
+        :type input_data: Any
+        :param name: Job name
+        :type name: str
+        :param shots: Number of shots. Ignored in estimation. Defaults to None
+        :type shots: int
+        :param input_params: Input parameters
+        :type input_params: Dict[str, Any]
+        :return: Azure Quantum job
+        :rtype: Job
+        """
+
+        if shots is not None:
+            warnings.warn("The 'shots' parameter is ignored in resource estimation job.")
+
         try:
             from qiskit import QuantumCircuit, transpile
             from qiskit_qir import to_qir_module
@@ -393,7 +414,13 @@ class MicrosoftEstimator(Target):
                 (module, _) = to_qir_module(input_data, record_output=False)
                 input_data = module.bitcode
         finally:
-            return super().submit(input_data, name, input_params, **kwargs)
+            return super().submit(
+                input_data=input_data, 
+                name=name, 
+                shots=shots,
+                input_params=input_params, 
+                **kwargs
+            )
 
     @classmethod
     def _get_job_class(cls) -> Type[Job]:

azure/quantum/target/params.py

@@ -180,7 +180,7 @@ class InputParams(InputParamsItem):
     """
     Class to define input parameters.
 
-    This class allows to define inout parameters for non-batching and batching
+    This class allows to define input parameters for non-batching and batching
     jobs.  The instance represents a batching job, if and only if num_items is
     set to some positive number less or equal to MAX_NUM_ITEMS.
 

azure/quantum/target/pasqal/target.py

@@ -64,6 +64,8 @@ class Pasqal(Target):
 
     target_names = tuple(target.value for target in PasqalTarget)
 
+    _SHOTS_PARAM_NAME = "count"
+
     def __init__(
         self,
         workspace: Workspace,
@@ -91,6 +93,7 @@ class Pasqal(Target):
         self,
         input_data: Any,
         name: str = "azure-quantum-job",
+        shots: int = None,
         input_params: Union[InputParams, None, Dict[str, Any]] = None,
         **kwargs,
     ) -> Job:
@@ -103,15 +106,26 @@ class Pasqal(Target):
         :type input_data: Any
         :param name: Job name
         :type name: str
+        :param shots: Number of shots, defaults to None
+        :type shots: int
         :param input_params: Input parameters, see :class:`azure.quantum.target.pasqal.InputParams` for details.
         :type input_params: Union[InputParams, None, Dict[str, Any]]
         :return: Azure Quantum job
         :rtype: Job
         """
+
         if isinstance(input_params, InputParams):
             typed_input_params = input_params
             input_params = {
-                "runs": typed_input_params.runs,
+                self.__class__._SHOTS_PARAM_NAME: typed_input_params.runs,
             }
+        
+        input_params = input_params or {}
 
-        return super().submit(input_data, name, input_params, **kwargs)
+        return super().submit(
+            input_data=input_data, 
+            name=name,
+            shots=shots, 
+            input_params=input_params, 
+            **kwargs
+        )

azure/quantum/target/quantinuum.py

@@ -3,8 +3,12 @@
 # Licensed under the MIT License.
 ##
 from typing import Any, Dict
+from warnings import warn
 
-from azure.quantum.target.target import Target
+from azure.quantum.target.target import (
+    Target,
+    _determine_shots_or_deprecated_num_shots,
+)
 from azure.quantum.job.job import Job
 from azure.quantum.workspace import Workspace
 from azure.quantum._client.models import CostEstimate, UsageEvent
@@ -25,6 +29,8 @@ class Quantinuum(Target):
         "quantinuum.sim.h2-1e",
     )
 
+    _SHOTS_PARAM_NAME = "count"
+
     def __init__(
         self,
         workspace: Workspace,
@@ -53,7 +59,7 @@ class Quantinuum(Target):
         self,
         circuit: str = None,
         name: str = "quantinuum-job",
-        num_shots: int = None,
+        shots: int = None,
         input_params: Dict[str, Any] = None,
         **kwargs
     ) -> Job:
@@ -63,8 +69,8 @@ class Quantinuum(Target):
         :type circuit: str
         :param name: Job name
         :type name: str
-        :param num_shots: Number of shots, defaults to None
-        :type num_shots: int
+        :param shots: Number of shots, defaults to None
+        :type shots: int
         :param input_params: Optional input params dict
         :type input_params: Dict[str, Any]
         :return: Azure Quantum job
@@ -77,13 +83,18 @@ class Quantinuum(Target):
             )
         if input_params is None:
             input_params = {}
-        if num_shots is not None:
-            input_params = input_params.copy()
-            input_params["count"] = num_shots
+
+        num_shots = kwargs.pop("num_shots", None)
+
+        shots = _determine_shots_or_deprecated_num_shots(
+            shots=shots,
+            num_shots=num_shots,
+        )
 
         return super().submit(
             input_data=input_data,
             name=name,
+            shots=shots,
             input_params=input_params,
             **kwargs
         )
@@ -94,7 +105,8 @@ class Quantinuum(Target):
         num_shots: int = None,
         N_1q: int = None,
         N_2q: int = None,
-        N_m: int = None
+        N_m: int = None,
+        shots: int = None,
     ) -> CostEstimate:
         """Estimate the cost in HQC for a given circuit.
         Optionally, you can provide the number of gate and measurement operations
@@ -119,9 +131,22 @@ class Quantinuum(Target):
         :param N_m: Number of measurement operations, if not specified,
             this is estimated from the circuit
         :type N_m: int, optional
+        :param shots: Number of shots for which to estimate costs
+        :type shots: int, optional
         :raises ImportError: If N_1q, N_2q and N_m are not specified,
             this will require a qiskit installation.
         """
+
+        if num_shots is None and shots is None:
+             raise ValueError("The 'shots' parameter has to be specified")
+
+        if num_shots is not None:
+            warn(
+                "The 'num_shots' parameter will be deprecated. Please, use 'shots' parameter instead.",
+                category=DeprecationWarning,
+            )
+            shots = num_shots
+
         if circuit is not None and (N_1q is None or N_2q is None or N_m is None):
             try:
                 from qiskit.circuit.quantumcircuit import Qasm
@@ -160,7 +185,7 @@ class Quantinuum(Target):
         if is_syntax_checker_regex.match(self.name):
             HQC = 0.0
         else:
-            HQC = 5 + num_shots * (N_1q + 10 * N_2q + 5 * N_m) / 5000
+            HQC = 5 + shots * (N_1q + 10 * N_2q + 5 * N_m) / 5000
 
         return CostEstimate(
             events=[

azure/quantum/target/rigetti/target.py

@@ -134,6 +134,8 @@ class Rigetti(Target):
 
     target_names = tuple(target.value for target in RigettiTarget)
 
+    _SHOTS_PARAM_NAME = "count"
+
     def __init__(
         self,
         workspace: Workspace,
@@ -161,6 +163,7 @@ class Rigetti(Target):
         self,
         input_data: Any,
         name: str = "azure-quantum-job",
+        shots: int = None,
         input_params: Union[InputParams, None, Dict[str, Any]] = None,
         **kwargs,
     ) -> Job:
@@ -173,6 +176,8 @@ class Rigetti(Target):
         :type input_data: Any
         :param name: Job name
         :type name: str
+        :param shots: Number of shots, defaults to None
+        :type shots: int
         :param input_params: Input parameters, see :class:`azure.quantum.target.rigetti.InputParams` for details.
         :type input_params: Union[InputParams, None, Dict[str, Any]]
         :return: Azure Quantum job
@@ -181,10 +186,18 @@ class Rigetti(Target):
         if isinstance(input_params, InputParams):
             typed_input_params = input_params
             input_params = {
-                "count": typed_input_params.count,
+                Rigetti._SHOTS_PARAM_NAME: typed_input_params.count,
                 "skipQuilc": typed_input_params.skip_quilc,
             }
             if typed_input_params.substitutions is not None:
                 input_params["substitutions"] = typed_input_params.substitutions
+        elif input_params is None:
+            input_params = {}
 
-        return super().submit(input_data, name, input_params, **kwargs)
+        return super().submit(
+            input_data=input_data, 
+            name=name,
+            shots=shots,
+            input_params=input_params, 
+            **kwargs
+        )

azure/quantum/target/solvers.py

@@ -98,7 +98,10 @@ class Solver(Target):
         return data.to_blob()
 
     def submit(
-        self, problem: Union[str, "Problem"]) -> Job:
+        self, 
+        problem: Union[str, "Problem"],
+        shots: int = None
+    ) -> Job:
         """Submits a job to execution to the associated
         Azure Quantum Workspace.
 
@@ -107,6 +110,9 @@ class Solver(Target):
             or the URL of an Azure Storage Blob where the serialized version
             of a Problem has been uploaded.
         """
+        if shots is not None:
+            warnings.warn("The 'shots' parameter is ignored for solver job.")
+
         from azure.quantum.optimization import Problem
         if isinstance(problem, Problem):
             return super().submit(

azure/quantum/target/target.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any, Dict, Optional, Union, Type,  Protocol, r
 import io
 import json
 import abc
+import warnings
 
 from azure.quantum._client.models import TargetStatus, SessionDetails
 from azure.quantum._client.models._enums import SessionJobFailurePolicy
@@ -27,6 +28,9 @@ class QirRepresentable(Protocol):
 
 
 class Target(abc.ABC, SessionHost):
+
+    _QSHARP_USER_AGENT = "azure-quantum-qsharp"
+
     """Azure Quantum Target."""
     # Target IDs that are compatible with this Target class.
     # This variable is used by TargetFactory. To set the default
@@ -39,6 +43,10 @@ class Target(abc.ABC, SessionHost):
     # submit and get_job method.
     target_names = ()
 
+    # Name of the provider's input parameter which specifies number of shots for a submitted job.
+    # If None, target will not pass this input parameter. 
+    _SHOTS_PARAM_NAME = None
+
     def __init__(
         self,
         workspace: "Workspace",
@@ -101,6 +109,13 @@ avg. queue time={self._average_queue_time} s, {self._current_availability}>"
         The job class used by submit and get_job.  The default is Job.
         """
         return Job
+    
+    @classmethod
+    def _can_send_shots_input_param(cls) -> bool:
+        """
+        Tells if provider's target class is able to specify shots number for its jobs.
+        """
+        return cls._SHOTS_PARAM_NAME is not None
 
     def refresh(self):
         """Update the target availability and queue time"""
@@ -150,6 +165,7 @@ target '{self.name}' of provider '{self.provider_id}' not found."
         self,
         input_data: Any,
         name: str = "azure-quantum-job",
+        shots: int = None,
         input_params: Union[Dict[str, Any], InputParams, None] = None,
         **kwargs
     ) -> Job:
@@ -162,6 +178,8 @@ target '{self.name}' of provider '{self.provider_id}' not found."
         :type input_data: Any
         :param name: Job name
         :type name: str
+        :param shots: Number of shots, defaults to None
+        :type shots: int
         :param input_params: Input parameters
         :type input_params: Dict[str, Any]
         :return: Azure Quantum job
@@ -182,6 +200,10 @@ target '{self.name}' of provider '{self.provider_id}' not found."
             input_data_format = kwargs.pop("input_data_format", "qir.v1")
             output_data_format = kwargs.pop("output_data_format", self._qir_output_data_format())
             content_type = kwargs.pop("content_type", "qir.v1")
+            # setting UserAgent header to indicate Q# submission
+            # TODO: this is a temporary solution. We should be setting the User-Agent header
+            # on per-job basis as targets of different types could be submitted using the same Workspace object
+            self.workspace.append_user_agent(self._QSHARP_USER_AGENT)
 
             def _get_entrypoint(input_data):
                 # TODO: this method should be part of QirRepresentable protocol
@@ -200,6 +222,36 @@ target '{self.name}' of provider '{self.provider_id}' not found."
             input_data_format = kwargs.pop("input_data_format", self.input_data_format)
             output_data_format = kwargs.pop("output_data_format", self.output_data_format)
             content_type = kwargs.pop("content_type", self.content_type)
+            # re-setting UserAgent header to None for passthrough
+            self.workspace.append_user_agent(None)
+        
+        # Set shots number, if possible.
+        if self._can_send_shots_input_param():
+            input_params_shots = input_params.pop(self.__class__._SHOTS_PARAM_NAME, None)
+
+            # If there is a parameter conflict, choose 'shots'.
+            if shots is not None and input_params_shots is not None:
+                warnings.warn(
+                    f"Parameter 'shots' conflicts with the '{self.__class__._SHOTS_PARAM_NAME}' field of the 'input_params' "
+                    "parameter. Please, provide only one option for setting shots. Defaulting to 'shots' parameter."
+                )
+                final_shots = shots
+            
+            # The 'shots' parameter has highest priority.
+            elif shots is not None:
+                final_shots = shots
+            # if 'shots' parameter is not specified, try a provider-specific option.
+            elif input_params_shots is not None:
+                warnings.warn(
+                    f"Field '{self.__class__._SHOTS_PARAM_NAME}' from the 'input_params' parameter is subject to change in future versions. "
+                    "Please, use 'shots' parameter instead."
+                )
+                final_shots = input_params_shots
+            else:
+                final_shots = None
+            
+            if final_shots is not None:
+                input_params[self.__class__._SHOTS_PARAM_NAME] = final_shots
 
         encoding = kwargs.pop("encoding", self.encoding)
         blob = self._encode_input_data(data=input_data)
@@ -241,3 +293,33 @@ target '{self.name}' of provider '{self.provider_id}' not found."
 
     def _get_azure_provider_id(self) -> str:
         return self.provider_id
+
+
+def _determine_shots_or_deprecated_num_shots(
+    shots: int = None,
+    num_shots: int = None,
+) -> int:
+    """
+    This helper function checks if the deprecated 'num_shots' parameter is specified.
+    In earlier versions it was possible to pass this parameter 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 and num_shots is not None:
+        warnings.warn(
+            "Both 'shots' and 'num_shots' parameters were specified. Defaulting to 'shots' parameter. "
+            "Please, use 'shots' since 'num_shots' will be deprecated.",
+            category=DeprecationWarning,
+        )
+        final_shots = shots
+        
+    elif shots is not None:
+        final_shots = shots
+    elif num_shots is not None:
+        warnings.warn(
+            "The 'num_shots' parameter will be deprecated. Please, use 'shots' parameter instead.",
+            category=DeprecationWarning,
+        )
+        final_shots = num_shots
+
+    return final_shots

azure/quantum/target/target_factory.py

@@ -3,7 +3,6 @@
 # Licensed under the MIT License.
 ##
 import warnings
-import asyncio
 from typing import Any, Dict, List, TYPE_CHECKING, Union, Type
 from azure.quantum.target import *
 
@@ -63,7 +62,6 @@ class TargetFactory:
             for _t in t.__subclasses__() + [t]
             if hasattr(_t, "target_names")
             for name in _t.target_names
-            if not asyncio.iscoroutinefunction(_t.submit)
         }
 
     def _target_cls(self, provider_id: str, name: str):

azure/quantum/version.py

@@ -5,4 +5,4 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 ##
-__version__ = "0.30.0"
+__version__ = "1.0.0"

azure/quantum/workspace.py

@@ -218,21 +218,24 @@ class Workspace:
             full_user_agent = f"{full_user_agent}-{env_app_id}" if full_user_agent else env_app_id
         return full_user_agent
 
-    def append_user_agent(self, value: str):
+    def append_user_agent(self, value: Union[str, None]):
         """
         Append a new value to the Workspace's UserAgent and re-initialize the
         QuantumClient. The values are appended using a dash.
 
         :param value: UserAgent value to add, e.g. "azure-quantum-<plugin>"
         """
-        if value not in (self._user_agent or ""):
+        new_user_agent = None
+
+        if value is not None and value not in (self._user_agent or ""):
             new_user_agent = f"{self._user_agent}-{value}" if self._user_agent else value
-            if new_user_agent != self._user_agent:
-                self._user_agent = new_user_agent
-                # We need to recreate the client for it to
-                # pick the new UserAgent
-                if self._client is not None:
-                    self._client = self._create_client()
+
+        if new_user_agent != self._user_agent:
+            self._user_agent = new_user_agent
+            # We need to recreate the client for it to
+            # pick the new UserAgent
+            if self._client is not None:
+                self._client = self._create_client()
 
     def _get_top_level_items_client(self) -> TopLevelItemsOperations:
         return self._client.top_level_items