classiq 0.38.0__py3-none-any.whl → 0.65.4__py3-none-any.whl

classiq/execution/jobs.py

@@ -1,24 +1,39 @@
 import webbrowser
 from datetime import datetime
-from typing import List, Optional, Union
+from typing import Any, Optional, Union
 from urllib.parse import urljoin
 
+import httpx
+
+from classiq.interface.exceptions import (
+    ClassiqAPIError,
+    ClassiqError,
+)
 from classiq.interface.execution.jobs import ExecutionJobDetailsV1
-from classiq.interface.executor.execution_request import ExecutionJobDetails
+from classiq.interface.executor.execution_request import ExecutionJobDetails, JobCost
 from classiq.interface.executor.execution_result import ResultsCollection
+from classiq.interface.executor.result import (
+    EstimationResult,
+    EstimationResults,
+    ExecutionDetails,
+    MultipleExecutionDetails,
+)
 from classiq.interface.jobs import JobStatus, JSONObject
-from classiq.interface.server.routes import EXECUTION_JOBS_NON_VERSIONED_FULL_PATH
+from classiq.interface.server.routes import EXECUTION_JOBS_FULL_PATH
 
-from classiq._internals.api_wrapper import CLASSIQ_ACCEPT_HEADER, ApiWrapper
+from classiq._internals.api_wrapper import ApiWrapper
 from classiq._internals.async_utils import syncify_function
 from classiq._internals.client import client
 from classiq._internals.jobs import JobID, JobPoller
-from classiq.exceptions import ClassiqAPIError
 
 _JobDetails = Union[ExecutionJobDetails, ExecutionJobDetailsV1]
 
-_JOB_DETAILS_VERSION = "v1"
-_JOB_RESULT_VERSION = "v1"
+
+class ClassiqExecutionResultError(ClassiqError):
+    def __init__(self, primitive: str) -> None:
+        super().__init__(
+            f"Execution job does not contain a single {primitive!r} result, make sure you use the 'get_*_result' method matching the primitive you executed. You can use the 'result' method to see the general result."
+        )
 
 
 class ExecutionJob:
@@ -76,23 +91,44 @@ class ExecutionJob:
         else:
             return f"{class_name}(name={self.name!r}, id={self.id!r})"
 
+    def cost(self, *, verbose: bool = False) -> Union[str, JobCost]:
+        if self._details.cost is None:
+            self._details.cost = JobCost()
+        if verbose:
+            return self._details.cost
+        return f"{self._details.cost.total_cost} {self._details.cost.currency_code}"
+
     @classmethod
-    async def from_id_async(cls, id: str) -> "ExecutionJob":
-        details = await ApiWrapper.call_get_execution_job_details(JobID(job_id=id))
+    async def from_id_async(
+        cls,
+        id: str,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> "ExecutionJob":
+        details = await ApiWrapper.call_get_execution_job_details(
+            JobID(job_id=id), http_client=_http_client
+        )
         return cls(details)
 
+    # `syncify_function` doesn't work well for class methods, so I wrote `from_id`
+    # explicitly
     @classmethod
-    def from_id(cls, id: str) -> "ExecutionJob":
-        return syncify_function(cls.from_id_async)(id)
+    def from_id(
+        cls,
+        id: str,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> "ExecutionJob":
+        return syncify_function(cls.from_id_async)(id, _http_client=_http_client)
 
     @property
     def _job_id(self) -> JobID:
         return JobID(job_id=self.id)
 
     async def result_async(
-        self, timeout_sec: Optional[float] = None
+        self,
+        timeout_sec: Optional[float] = None,
+        _http_client: Optional[httpx.AsyncClient] = None,
     ) -> ResultsCollection:
-        await self.poll_async(timeout_sec=timeout_sec)
+        await self.poll_async(timeout_sec=timeout_sec, _http_client=_http_client)
 
         if self.status == JobStatus.FAILED:
             raise ClassiqAPIError(self.error or "")
@@ -102,45 +138,181 @@ class ExecutionJob:
         if self._result is None:
             self._result = (
                 await ApiWrapper.call_get_execution_job_result(
-                    job_id=self._job_id, version=_JOB_RESULT_VERSION
+                    job_id=self._job_id,
+                    http_client=_http_client,
                 )
             ).results
         return self._result
 
     result = syncify_function(result_async)
 
-    async def poll_async(self, timeout_sec: Optional[float] = None) -> None:
+    def result_value(self, *args: Any, **kwargs: Any) -> Any:
+        return self.result(*args, **kwargs)[0].value
+
+    def get_sample_result(
+        self, _http_client: Optional[httpx.AsyncClient] = None
+    ) -> ExecutionDetails:
+        """
+        Returns the job's result as a single sample result after validation. If the result is not yet available, waits for it.
+
+        Returns:
+            The sample result of the execution job.
+
+        Raises:
+            ClassiqExecutionResultError: In case the result does not contain a single sample result.
+            ClassiqAPIError: In case the job has failed.
+        """
+        results = self.result(_http_client=_http_client)
+        if len(results) != 1:
+            raise ClassiqExecutionResultError("sample")
+
+        result = results[0].value
+        if isinstance(result, ExecutionDetails):
+            return result
+        if isinstance(result, MultipleExecutionDetails) and len(result.details) == 1:
+            return result.details[0]
+        raise ClassiqExecutionResultError("sample")
+
+    def get_batch_sample_result(
+        self, _http_client: Optional[httpx.AsyncClient] = None
+    ) -> list[ExecutionDetails]:
+        """
+        Returns the job's result as a single batch_sample result after validation. If the result is not yet available, waits for it.
+
+        Returns:
+            The batch_sample result of the execution job.
+
+        Raises:
+            ClassiqExecutionResultError: In case the result does not contain a single batch_sample result.
+            ClassiqAPIError: In case the job has failed.
+        """
+        results = self.result(_http_client=_http_client)
+        if len(results) != 1:
+            raise ClassiqExecutionResultError("batch_sample")
+
+        result = results[0].value
+        if isinstance(result, ExecutionDetails):
+            return [result]
+        if isinstance(result, MultipleExecutionDetails):
+            return result.details
+
+        raise ClassiqExecutionResultError("batch_sample")
+
+    def get_estimate_result(
+        self, _http_client: Optional[httpx.AsyncClient] = None
+    ) -> EstimationResult:
+        """
+        Returns the job's result as a single estimate result after validation. If the result is not yet available, waits for it.
+
+        Returns:
+            The estimate result of the execution job.
+
+        Raises:
+            ClassiqExecutionResultError: In case the result does not contain a single estimate result.
+            ClassiqAPIError: In case the job has failed.
+        """
+        results = self.result(_http_client=_http_client)
+        if len(results) != 1:
+            raise ClassiqExecutionResultError("estimate")
+
+        result = results[0].value
+        if isinstance(result, EstimationResult):
+            return result
+        if isinstance(result, EstimationResults) and len(result.results) == 1:
+            return result.results[0]
+        raise ClassiqExecutionResultError("estimate")
+
+    def get_batch_estimate_result(
+        self, _http_client: Optional[httpx.AsyncClient] = None
+    ) -> list[EstimationResult]:
+        """
+        Returns the job's result as a single batch_estimate result after validation. If the result is not yet available, waits for it.
+
+        Returns:
+            The batch_estimate result of the execution job.
+
+        Raises:
+            ClassiqExecutionResultError: In case the result does not contain a single batch_estimate result.
+            ClassiqAPIError: In case the job has failed.
+        """
+        results = self.result(_http_client=_http_client)
+        if len(results) != 1:
+            raise ClassiqExecutionResultError("batch_estimate")
+
+        result = results[0].value
+        if isinstance(result, EstimationResult):
+            return [result]
+        if isinstance(result, EstimationResults):
+            return result.results
+
+        raise ClassiqExecutionResultError("batch_estimate")
+
+    async def poll_async(
+        self,
+        timeout_sec: Optional[float] = None,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
         if not self.status.is_final():
-            await self._poll_job(timeout_sec=timeout_sec)
+            await self._poll_job(timeout_sec=timeout_sec, _http_client=_http_client)
 
     poll = syncify_function(poll_async)
 
-    async def _poll_job(self, timeout_sec: Optional[float] = None) -> None:
+    async def _poll_job(
+        self,
+        timeout_sec: Optional[float] = None,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
         def response_parser(json_response: JSONObject) -> Optional[bool]:
-            self._details = ExecutionJobDetails.parse_obj(json_response)
+            self._details = ExecutionJobDetails.model_validate(json_response)
             if self.status.is_final():
                 return True
             return None
 
         poller = JobPoller(
-            base_url=EXECUTION_JOBS_NON_VERSIONED_FULL_PATH,
-            use_versioned_url=False,
-            additional_headers={CLASSIQ_ACCEPT_HEADER: _JOB_DETAILS_VERSION},
+            base_url=EXECUTION_JOBS_FULL_PATH,
         )
         await poller.poll(
             job_id=self._job_id,
             response_parser=response_parser,
             timeout_sec=timeout_sec,
+            http_client=_http_client,
         )
 
-    async def rename_async(self, name: str) -> None:
-        self._details = await ApiWrapper.call_patch_execution_job(self._job_id, name)
+    async def rename_async(
+        self,
+        name: str,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._details = await ApiWrapper.call_patch_execution_job(
+            self._job_id,
+            name,
+            http_client=_http_client,
+        )
 
     rename = syncify_function(rename_async)
 
+    async def cancel_async(
+        self,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        """
+        Cancels the execution job. This implies the cancellation of any ongoing jobs
+        sent to the provider during this execution job.
+
+        The function returns without waiting to the actual cancellation. It is possible
+        to continue polling the job in order to ensure its cancellation, which might
+        not be immediate.
+        """
+        await ApiWrapper.call_cancel_execution_job(
+            self._job_id,
+            http_client=_http_client,
+        )
+
+    cancel = syncify_function(cancel_async)
+
     @property
     def ide_url(self) -> str:
-        base_url = client().config.ide
+        base_url = client().config.ide.unicode_string()
         return urljoin(base_url, f"jobs/{self.id}")
 
     def open_in_ide(self) -> None:
@@ -149,7 +321,7 @@ class ExecutionJob:
 
 async def get_execution_jobs_async(
     offset: int = 0, limit: int = 50
-) -> List[ExecutionJob]:
+) -> list[ExecutionJob]:
     result = await ApiWrapper().call_query_execution_jobs(offset=offset, limit=limit)
     return [ExecutionJob(details) for details in result.results]
 

classiq/execution/qnn.py

@@ -0,0 +1,79 @@
+import functools
+from typing import Optional
+
+import more_itertools
+
+from classiq.interface.chemistry.operator import PauliOperator
+from classiq.interface.executor.constants import DEFAULT_RESULT_NAME
+from classiq.interface.executor.execution_result import (
+    ResultsCollection,
+    SavedResultValueType,
+    TaggedEstimationResult,
+    TaggedExecutionDetails,
+)
+from classiq.interface.executor.quantum_code import Arguments, MultipleArguments
+
+from classiq.applications.combinatorial_helpers.pauli_helpers.pauli_utils import (
+    pauli_operator_to_hamiltonian,
+)
+from classiq.execution.execution_session import ExecutionSession
+from classiq.synthesis import SerializedQuantumProgram
+
+_MAX_ARGUMENTS_SIZE = 1024
+
+
+def _execute_qnn_estimate(
+    session: ExecutionSession,
+    arguments: list[Arguments],
+    observable: PauliOperator,
+) -> ResultsCollection:
+    hamiltonian = pauli_operator_to_hamiltonian(observable.pauli_list)
+    return [
+        TaggedEstimationResult(
+            name=DEFAULT_RESULT_NAME,
+            value=result,
+            value_type=SavedResultValueType.EstimationResult,
+        )
+        for result in session.batch_estimate(
+            hamiltonian=hamiltonian, parameters=arguments
+        )
+    ]
+
+
+def _execute_qnn_sample(
+    session: ExecutionSession,
+    arguments: list[Arguments],
+) -> ResultsCollection:
+    return [
+        TaggedExecutionDetails(
+            name=DEFAULT_RESULT_NAME,
+            value=result,
+            value_type=SavedResultValueType.ExecutionDetails,
+        )
+        for result in session.batch_sample(arguments)
+    ]
+
+
+def execute_qnn(
+    quantum_program: SerializedQuantumProgram,
+    arguments: MultipleArguments,
+    observable: Optional[PauliOperator] = None,
+) -> ResultsCollection:
+    with ExecutionSession(quantum_program) as session:
+        if observable:
+            execute_function = functools.partial(
+                _execute_qnn_estimate,
+                session=session,
+                observable=observable,
+            )
+        else:
+            execute_function = functools.partial(
+                _execute_qnn_sample,
+                session=session,
+            )
+
+        result: ResultsCollection = []
+        for chunk in more_itertools.chunked(arguments, _MAX_ARGUMENTS_SIZE):
+            chunk_result = execute_function(arguments=chunk)
+            result.extend(chunk_result)
+        return result

classiq/executor.py

@@ -1,135 +1,55 @@
 """Executor module, implementing facilities for executing quantum programs using Classiq platform."""
 
-import functools
-from typing import Optional, Tuple, Union
+from typing import Union
 
-import more_itertools
 from typing_extensions import TypeAlias
 
 from classiq.interface.backend.backend_preferences import BackendPreferencesTypes
-from classiq.interface.chemistry.operator import PauliOperators
 from classiq.interface.executor.estimation import OperatorsEstimation
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
-from classiq.interface.executor.execution_request import (
-    EstimateOperatorsExecution,
-    ExecutionRequest,
-    QuantumCodeExecution,
-)
-from classiq.interface.executor.execution_result import (
-    ResultsCollection,
-    SavedResultValueType,
-    TaggedEstimationResult,
-    TaggedExecutionDetails,
-)
-from classiq.interface.executor.quantum_code import MultipleArguments, QuantumCode
+from classiq.interface.executor.quantum_code import QuantumCode
 from classiq.interface.executor.quantum_instruction_set import QuantumInstructionSet
 from classiq.interface.executor.result import ExecutionDetails
 from classiq.interface.generator.quantum_program import QuantumProgram
 
+from classiq._internals import async_utils
 from classiq._internals.api_wrapper import ApiWrapper
-from classiq._internals.async_utils import syncify_function
 from classiq.execution.jobs import ExecutionJob
-from classiq.model.model import DEFAULT_RESULT_NAME
 from classiq.synthesis import SerializedQuantumProgram
 
 BatchExecutionResult: TypeAlias = Union[ExecutionDetails, BaseException]
-ProgramAndResult: TypeAlias = Tuple[QuantumCode, BatchExecutionResult]
-BackendPreferencesAndResult: TypeAlias = Tuple[
+ProgramAndResult: TypeAlias = tuple[QuantumCode, BatchExecutionResult]
+BackendPreferencesAndResult: TypeAlias = tuple[
     BackendPreferencesTypes, int, BatchExecutionResult
 ]
-_MAX_ARGUMENTS_SIZE = 1024
 
 
 def _parse_serialized_qprog(
     quantum_program: SerializedQuantumProgram,
 ) -> QuantumProgram:
-    return QuantumProgram.parse_raw(quantum_program)
+    return QuantumProgram.model_validate_json(quantum_program)
 
 
 async def execute_async(quantum_program: SerializedQuantumProgram) -> ExecutionJob:
     circuit = _parse_serialized_qprog(quantum_program)
-    result = await ApiWrapper.call_execute_generated_circuit(circuit)
+    execution_input = await ApiWrapper.call_convert_quantum_program(circuit)
+    result = await ApiWrapper.call_execute_execution_input(execution_input)
     return ExecutionJob(details=result)
 
 
-execute = syncify_function(execute_async)
-
-
-async def _execute_qnn_async_estimate(
-    quantum_program: QuantumCode,
-    execution_preferences: ExecutionPreferences,
-    observables: PauliOperators,
-) -> ResultsCollection:
-    request = ExecutionRequest(
-        execution_payload=EstimateOperatorsExecution(
-            quantum_program=quantum_program,
-            operators=observables,
-        ),
-        preferences=execution_preferences,
-    )
-
-    results = await ApiWrapper.call_execute_estimate(request)
-    return [
-        TaggedEstimationResult(
-            name=DEFAULT_RESULT_NAME,
-            value=result,
-            value_type=SavedResultValueType.EstimationResult,
-        )
-        for result in results
-    ]
-
-
-async def _execute_qnn_async_program(
-    quantum_program: QuantumCode,
-    execution_preferences: ExecutionPreferences,
-) -> ResultsCollection:
-    request = ExecutionRequest(
-        execution_payload=QuantumCodeExecution(**quantum_program.dict()),
-        preferences=execution_preferences,
-    )
-
-    api_result = await ApiWrapper.call_execute_quantum_program(request)
-    return [
-        TaggedExecutionDetails(
-            name=DEFAULT_RESULT_NAME,
-            value=result,
-            value_type=SavedResultValueType.ExecutionDetails,
-        )
-        for result in api_result.details
-    ]
-
-
-async def execute_qnn_async(
-    quantum_program: SerializedQuantumProgram,
-    arguments: MultipleArguments,
-    observables: Optional[PauliOperators] = None,
-) -> ResultsCollection:
-    circuit = _parse_serialized_qprog(quantum_program)
-    execution_preferences = circuit.model.execution_preferences
-
-    legacy_quantum_program = circuit.to_program()
-
-    if observables:
-        execute_function = functools.partial(
-            _execute_qnn_async_estimate,
-            execution_preferences=execution_preferences,
-            observables=observables,
-        )
-    else:
-        execute_function = functools.partial(
-            _execute_qnn_async_program,
-            execution_preferences=execution_preferences,
-        )
+def execute(quantum_program: SerializedQuantumProgram) -> ExecutionJob:
+    """
+    Execute a quantum program. The preferences for execution are set on the quantum program using the method `set_execution_preferences`.
 
-    result: ResultsCollection = []
-    for chunk in more_itertools.chunked(arguments, _MAX_ARGUMENTS_SIZE):
-        legacy_quantum_program.arguments = tuple(chunk)
-        chunk_result = await execute_function(quantum_program=legacy_quantum_program)
-        result.extend(chunk_result)
-    return result
+    Args:
+        quantum_program: The quantum program to execute. This is the result of the synthesize method.
 
+    Returns:
+        ExecutionJob: The result of the execution.
 
-execute_qnn = syncify_function(execute_qnn_async)
+    For examples please see [Execution Documentation](https://docs.classiq.io/latest/user-guide/execution/)
+    """
+    return async_utils.run(execute_async(quantum_program))
 
 
 def set_quantum_program_execution_preferences(
@@ -138,27 +58,12 @@ def set_quantum_program_execution_preferences(
 ) -> SerializedQuantumProgram:
     circuit = _parse_serialized_qprog(quantum_program)
     circuit.model.execution_preferences = preferences
-    return SerializedQuantumProgram(circuit.json())
-
-
-def set_initial_values(
-    quantum_program: SerializedQuantumProgram,
-    **kwargs: int,
-) -> SerializedQuantumProgram:
-    circuit = _parse_serialized_qprog(quantum_program)
-    circuit.initial_values = kwargs
-
-    # Validate the initial values by calling `get_registers_initialization`
-    circuit.get_registers_initialization(circuit.initial_values)
-
-    return SerializedQuantumProgram(circuit.json())
+    return SerializedQuantumProgram(circuit.model_dump_json())
 
 
 __all__ = [
+    "OperatorsEstimation",
     "QuantumCode",
     "QuantumInstructionSet",
-    "execute_qnn",
-    "OperatorsEstimation",
     "set_quantum_program_execution_preferences",
-    "set_initial_values",
 ]

classiq/interface/_version.py

@@ -3,5 +3,5 @@ from packaging.version import Version
 # This file was generated automatically
 # Please don't track in version control (DONTTRACK)
 
-SEMVER_VERSION = '0.38.0'
+SEMVER_VERSION = '0.65.4'
 VERSION = str(Version(SEMVER_VERSION))

classiq/interface/analyzer/analysis_params.py

@@ -1,8 +1,8 @@
-from typing import Dict, List, Optional
+from typing import Annotated, Optional
 
 import numpy
 import pydantic
-from pydantic import Field
+from pydantic import ConfigDict, Field, StringConstraints
 
 from classiq.interface.backend.quantum_backend_providers import AnalyzerProviderVendor
 from classiq.interface.chemistry.ground_state_problem import MoleculeProblem
@@ -17,22 +17,29 @@ from classiq.interface.helpers.custom_pydantic_types import PydanticNonEmptyStri
 MAX_KB_OF_FILE = 500
 MAX_FILE_LENGTH = MAX_KB_OF_FILE * 1024
 
+MAX_QUBITS = 100
+MIN_QUBITS = 0
+MAX_COUNTS = 1000
+MAX_NUM_CLIFFORD = 1000
+MAX_NAME_LENGTH = 100
+
 
 class AnalysisParams(pydantic.BaseModel):
     qasm: PydanticNonEmptyString = Field(..., max_length=MAX_FILE_LENGTH)
 
 
 class HardwareListParams(pydantic.BaseModel):
-    devices: Optional[List[PydanticNonEmptyString]] = pydantic.Field(
+    devices: Optional[list[PydanticNonEmptyString]] = pydantic.Field(
         default=None, description="Devices"
     )
-    providers: List[Provider]
+    providers: list[Provider]
     from_ide: bool = Field(default=False)
 
-    @pydantic.validator("providers", always=True)
+    @pydantic.field_validator("providers")
+    @classmethod
     def set_default_providers(
-        cls, providers: Optional[List[AnalyzerProviderVendor]]
-    ) -> List[AnalyzerProviderVendor]:
+        cls, providers: Optional[list[AnalyzerProviderVendor]]
+    ) -> list[AnalyzerProviderVendor]:
         if providers is None:
             providers = list(AnalyzerProviderVendor)
         return providers
@@ -40,12 +47,30 @@ class HardwareListParams(pydantic.BaseModel):
 
 class AnalysisOptionalDevicesParams(HardwareListParams):
     qubit_count: int = pydantic.Field(
-        default=..., description="number of qubits in the data"
+        default=...,
+        description="number of qubits in the data",
+        ge=MIN_QUBITS,
+        le=MAX_QUBITS,
+    )
+
+
+class GateNamsMapping(pydantic.BaseModel):
+    qasm_name: Annotated[
+        str, Annotated[str, StringConstraints(max_length=MAX_NAME_LENGTH)]
+    ]
+    display_name: Annotated[
+        str, Annotated[str, StringConstraints(max_length=MAX_NAME_LENGTH)]
+    ]
+
+
+class LatexParams(AnalysisParams):
+    gate_names: list[GateNamsMapping] = pydantic.Field(
+        default=..., description="List of gate names as apper in the qasm"
     )
 
 
 class AnalysisHardwareTranspilationParams(pydantic.BaseModel):
-    hardware_data: Optional[SynthesisHardwareData]
+    hardware_data: Optional[SynthesisHardwareData] = None
     random_seed: int
     transpilation_option: TranspilationOption
 
@@ -70,13 +95,18 @@ class CircuitAnalysisHardwareParams(AnalysisParams):
 
 class AnalysisRBParams(pydantic.BaseModel):
     hardware: str
-    counts: List[Dict[str, int]]
-    num_clifford: List[int]
+    counts: list[
+        dict[
+            str, Annotated[int, Annotated[int, Field(strict=True, gt=0, le=MAX_COUNTS)]]
+        ]
+    ]
+    num_clifford: list[
+        Annotated[int, Annotated[int, Field(strict=True, gt=0, le=MAX_NUM_CLIFFORD)]]
+    ]
 
 
 class ChemistryGenerationParams(pydantic.BaseModel):
-    class Config:
-        title = "Chemistry"
+    model_config = ConfigDict(title="Chemistry")
 
     molecule: MoleculeProblem = pydantic.Field(
         title="Molecule",