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

classiq/interface/debug_info/debug_info.py

@@ -0,0 +1,86 @@
+import json
+from collections.abc import Mapping
+from typing import Any, Optional, Union
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from classiq.interface.enum_utils import StrEnum
+from classiq.interface.generator.generated_circuit_data import (
+    FunctionDebugInfoInterface,
+    OperationLevel,
+)
+
+ParameterValue = Union[float, int, str, None]
+
+
+class StatementType(StrEnum):
+    CONTROL = "control"
+    POWER = "power"
+    INVERT = "invert"
+    WITHIN_APPLY = "within_apply"
+    ASSIGNMENT = "assignment"
+    REPEAT = "repeat"
+
+
+class FunctionDebugInfo(BaseModel):
+    name: str
+    # Parameters describe classical parameters passed to function
+    parameters: dict[str, str]
+    level: OperationLevel
+    statement_type: Union[StatementType, None] = None
+    is_allocate_or_free: bool = Field(default=False)
+    is_inverse: bool = Field(default=False)
+    port_to_passed_variable_map: dict[str, str] = Field(default_factory=dict)
+
+    @staticmethod
+    def param_controller(value: Any) -> str:
+        try:
+            return json.dumps(value)
+        except TypeError:
+            return repr(value)
+
+    def update_map_from_port_mapping(self, port_mapping: Mapping[str, str]) -> None:
+        new_port_to_passed_variable_map = self.port_to_passed_variable_map.copy()
+        for old_key, new_key in port_mapping.items():
+            if old_key in new_port_to_passed_variable_map:
+                new_port_to_passed_variable_map[new_key] = (
+                    new_port_to_passed_variable_map.pop(old_key)
+                )
+        self.port_to_passed_variable_map = new_port_to_passed_variable_map
+
+    def update_map_from_inout_port_mapping(
+        self, port_mapping: Mapping[str, tuple[str, str]]
+    ) -> None:
+        new_port_to_passed_variable_map = self.port_to_passed_variable_map.copy()
+        for old_key, (new_key1, new_key2) in port_mapping.items():
+            if old_key in new_port_to_passed_variable_map:
+                value = new_port_to_passed_variable_map.pop(old_key)
+                new_port_to_passed_variable_map[new_key1] = value
+                new_port_to_passed_variable_map[new_key2] = value
+        self.port_to_passed_variable_map = new_port_to_passed_variable_map
+
+
+class DebugInfoCollection(BaseModel):
+    # Pydantic only started supporting UUID as keys in Pydantic V2
+    # See https://github.com/pydantic/pydantic/issues/2096#issuecomment-814860206
+    # For now, we use strings as keys in the raw data and use UUID in the wrapper logic
+    data: dict[str, FunctionDebugInfo] = Field(default={})
+    blackbox_data: dict[str, FunctionDebugInfoInterface] = Field(default={})
+
+    def __setitem__(self, key: UUID, value: FunctionDebugInfo) -> None:
+        self.data[str(key)] = value
+
+    def get(self, key: UUID) -> Optional[FunctionDebugInfo]:
+        return self.data.get(str(key))
+
+    def __getitem__(self, key: UUID) -> FunctionDebugInfo:
+        return self.data[str(key)]
+
+    def __contains__(self, key: UUID) -> bool:
+        return str(key) in self.data
+
+    def get_blackbox_data(self, key: UUID) -> Optional[FunctionDebugInfoInterface]:
+        if (debug_info := self.get(key)) is None:
+            return None
+        return self.blackbox_data.get(debug_info.name)

classiq/{exceptions.py → interface/exceptions.py}

@@ -1,19 +1,21 @@
 import logging
-from typing import Iterable, List
+from collections.abc import Iterable
+from typing import Optional
 
 _logger = logging.getLogger(__name__)
 
 CLASSIQ_SLACK_COMMUNITY_LINK = (
-    "\nIf you need further assistance, please reach out on our Community Slack channel at: https://short.classiq.io/join-slack"
-    "\nIf the error persists feel free to open a ticket at: https://short.classiq.io/support"
+    "\nIf you need further assistance, please reach out on our Community Slack channel "
+    "at: https://short.classiq.io/join-slack"
 )
 
 
 class ClassiqError(Exception):
     def __init__(self, message: str) -> None:
-        message_with_link = message + CLASSIQ_SLACK_COMMUNITY_LINK
-        super().__init__(message_with_link)
         self._raw_message = message
+        if CLASSIQ_SLACK_COMMUNITY_LINK not in message:
+            message = message + CLASSIQ_SLACK_COMMUNITY_LINK
+        super().__init__(message)
 
     @property
     def raw_message(self) -> str:
@@ -25,7 +27,7 @@ class ClassiqExecutionError(ClassiqError):
 
 
 class ClassiqMissingOutputFormatError(ClassiqError):
-    def __init__(self, missing_formats: List[str]) -> None:
+    def __init__(self, missing_formats: list[str]) -> None:
         msg = (
             f"Cannot create program because output format is missing. "
             f"Expected one of the following formats: {missing_formats}"
@@ -45,12 +47,14 @@ class ClassiqAnalyzerError(ClassiqError):
     pass
 
 
-class ClassiqAnalyzerGraphError(ClassiqError):
+class ClassiqAnalyzerVisualizationError(ClassiqError):
     pass
 
 
 class ClassiqAPIError(ClassiqError):
-    pass
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        self.status_code = status_code
+        super().__init__(message)
 
 
 class ClassiqVersionError(ClassiqError):
@@ -143,7 +147,7 @@ class ClassiqCombOptNoSolutionError(ClassiqError):
 
 class ClassiqCombOptTrivialProblemError(ClassiqError):
 
-    def __init__(self, solution: List[int]) -> None:
+    def __init__(self, solution: list[int]) -> None:
         super().__init__(
             message=f"The problem doesn't have free decision variables. "
             f"The trivial solution is {solution}."
@@ -171,3 +175,27 @@ class ClassiqExecutorInvalidHamiltonianError(ClassiqCombOptError):
 
     def __init__(self) -> None:
         super().__init__("Invalid hamiltonian")
+
+
+class ClassiqSemanticError(ClassiqError):
+    pass
+
+
+class ClassiqDeprecationWarning(FutureWarning):
+    pass
+
+
+class ClassiqExpansionError(ClassiqError):
+    pass
+
+
+class ClassiqInternalError(ClassiqError):
+    def __init__(self, message: Optional[str] = None) -> None:
+        final_message = "Internal error occurred. Please contact Classiq support."
+        if message is not None:
+            final_message += f"\nError: {message}"
+        super().__init__(final_message)
+
+
+class ClassiqInternalExpansionError(ClassiqInternalError):
+    pass

classiq/interface/execution/iqcc.py

@@ -0,0 +1,19 @@
+from classiq.interface.helpers.versioned_model import VersionedModel
+
+
+class IQCCInitAuthData(VersionedModel):
+    auth_scope_id: str
+    auth_method_id: str
+
+
+class IQCCInitAuthResponse(VersionedModel):
+    auth_url: str
+    token_id: str
+
+
+class IQCCProbeAuthData(IQCCInitAuthData):
+    token_id: str
+
+
+class IQCCProbeAuthResponse(VersionedModel):
+    auth_token: str

classiq/interface/execution/jobs.py

@@ -1,28 +1,31 @@
 from datetime import datetime
-from typing import List, Optional
+from typing import Optional
 
-from pydantic import BaseModel, Extra
+from pydantic import BaseModel, Field
 
+from classiq.interface.executor.execution_request import JobCost
 from classiq.interface.jobs import JobStatus
 
 
-class ExecutionJobDetailsV1(BaseModel, extra=Extra.ignore):
+class ExecutionJobDetailsV1(BaseModel, extra="ignore"):
     id: str
 
-    name: Optional[str]
+    name: Optional[str] = None
     start_time: datetime
-    end_time: Optional[datetime]
+    end_time: Optional[datetime] = None
 
-    provider: Optional[str]
-    backend_name: Optional[str]
+    provider: Optional[str] = None
+    backend_name: Optional[str] = None
 
     status: JobStatus
 
-    num_shots: Optional[int]
-    program_id: Optional[str]
+    num_shots: Optional[int] = None
+    program_id: Optional[str] = None
 
-    error: Optional[str]
+    error: Optional[str] = None
 
+    cost: Optional[JobCost] = Field(default=None)
 
-class ExecutionJobsQueryResultsV1(BaseModel, extra=Extra.ignore):
-    results: List[ExecutionJobDetailsV1]
+
+class ExecutionJobsQueryResultsV1(BaseModel, extra="ignore"):
+    results: list[ExecutionJobDetailsV1]

classiq/interface/execution/primitives.py

@@ -0,0 +1,18 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from classiq.interface.chemistry.operator import PauliOperator
+from classiq.interface.executor.quantum_code import Arguments
+from classiq.interface.helpers.custom_encoders import CUSTOM_ENCODERS
+
+
+class EstimateInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
+    hamiltonian: PauliOperator
+    parameters: list[Arguments]
+
+
+class PrimitivesInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
+    sample: Optional[list[Arguments]] = Field(default=None)
+    estimate: Optional[EstimateInput] = Field(default=None)
+    random_seed: Optional[int] = Field(default=None)

classiq/interface/executor/constants.py

@@ -0,0 +1 @@
+DEFAULT_RESULT_NAME = "result"

classiq/interface/executor/execution_preferences.py

@@ -1,40 +1,22 @@
-from datetime import timedelta
-from typing import Any, Dict, Optional, TypeVar
+from typing import Optional
 
 import pydantic
 
 from classiq.interface.backend.backend_preferences import (
-    AWS_DEFAULT_JOB_TIMEOUT_SECONDS,
-    AwsBackendPreferences,
     BackendPreferencesTypes,
     backend_preferences_field,
 )
-from classiq.interface.backend.pydantic_backend import MAX_EXECUTION_TIMEOUT_SECONDS
-from classiq.interface.backend.quantum_backend_providers import ClassiqAerBackendNames
-from classiq.interface.executor.error_mitigation import ErrorMitigationMethod
-from classiq.interface.executor.optimizer_preferences import (
-    OptimizerPreferences,
-    OptimizerType,
+from classiq.interface.backend.quantum_backend_providers import (
+    ClassiqSimulatorBackendNames,
 )
+from classiq.interface.enum_utils import ReprEnum
+from classiq.interface.executor.optimizer_preferences import OptimizerType
 from classiq.interface.generator.model.preferences.preferences import (
     TranspilationOption,
 )
 from classiq.interface.generator.model.preferences.randomness import create_random_seed
 from classiq.interface.generator.noise_properties import NoiseProperties
 
-from classiq._internals.enum_utils import ReprEnum
-from classiq.exceptions import ClassiqValueError
-
-DIFFERENT_TIMEOUT_MSG = (
-    "Timeout is defined differently in the execution preferences and the "
-    "AWS Backend Preferences."
-)
-
-TIMEOUT_LARGE_FOR_AWS_MSG = (
-    "Timeout is larger than the current allowed limit of "
-    f"{timedelta(MAX_EXECUTION_TIMEOUT_SECONDS)}"
-)
-
 
 class QaeWithQpeEstimationMethod(int, ReprEnum):
     MAXIMUM_LIKELIHOOD = 0
@@ -42,29 +24,33 @@ class QaeWithQpeEstimationMethod(int, ReprEnum):
 
 
 class ExecutionPreferences(pydantic.BaseModel):
-    timeout_sec: Optional[pydantic.PositiveInt] = pydantic.Field(
-        default=None,
-        description="If set, limits the execution runtime. Value is in seconds. "
-        "Not supported on all platforms.",
-    )
-    optimizer_preferences: Optional[OptimizerPreferences] = pydantic.Field(
-        default_factory=None,
-        description="Settings related to VQE execution.",
-    )
-    error_mitigation_method: Optional[ErrorMitigationMethod] = pydantic.Field(
-        default=None,
-        description="Error mitigation method. Currently supports complete and tensored "
-        "measurement calibration.",
-    )
+    """
+    Represents the execution settings for running a quantum program.
+    Execution preferences for running a quantum program.
+
+    For more details, refer to:
+    `ExecutionPreferences example: [ExecutionPreferences](https://docs.classiq.io/latest/reference-manual/executor/?h=execution+pref#execution-preferences)..
+
+    Attributes:
+        noise_properties (Optional[NoiseProperties]): Properties defining the noise in the quantum circuit. Defaults to `None`.
+        random_seed (int): The random seed used for the execution. Defaults to a randomly generated seed.
+        backend_preferences (BackendPreferencesTypes): Preferences for the backend used to execute the circuit.
+            Defaults to the Classiq Simulator.
+        num_shots (Optional[pydantic.PositiveInt]): The number of shots (executions) to be performed.
+        transpile_to_hardware (TranspilationOption): Option to transpile the circuit to the hardware's basis gates
+            before execution. Defaults to `TranspilationOption.DECOMPOSE`.
+        job_name (Optional[str]): The name of the job, with a minimum length of 1 character.
+    """
+
     noise_properties: Optional[NoiseProperties] = pydantic.Field(
         default=None, description="Properties of the noise in the circuit"
     )
     random_seed: int = pydantic.Field(
-        default=None,
+        default_factory=create_random_seed,
         description="The random seed used for the execution",
     )
     backend_preferences: BackendPreferencesTypes = backend_preferences_field(
-        backend_name=ClassiqAerBackendNames.AER_SIMULATOR
+        backend_name=ClassiqSimulatorBackendNames.SIMULATOR
     )
     num_shots: Optional[pydantic.PositiveInt] = pydantic.Field(default=None)
     transpile_to_hardware: TranspilationOption = pydantic.Field(
@@ -73,87 +59,13 @@ class ExecutionPreferences(pydantic.BaseModel):
         title="Transpilation Option",
     )
     job_name: Optional[str] = pydantic.Field(
-        min_length=1,
-        description="The job name",
+        min_length=1, description="The job name", default=None
     )
 
-    def __init__(self, **kwargs: Any) -> None:
-        super().__init__(**kwargs)
-
-    @pydantic.validator("num_shots", always=True)
-    def validate_num_shots(
-        cls, original_num_shots: Optional[pydantic.PositiveInt], values: Dict[str, Any]
-    ) -> Optional[pydantic.PositiveInt]:
-        return _choose_original_or_optimizer_attribute(
-            original_num_shots, "num_shots", None, values
-        )
-
-    @pydantic.validator("backend_preferences", always=True)
-    def validate_timeout_for_aws(
-        cls, backend_preferences: BackendPreferencesTypes, values: Dict[str, Any]
-    ) -> BackendPreferencesTypes:
-        timeout = values.get("timeout_sec", None)
-        if (
-            not isinstance(backend_preferences, AwsBackendPreferences)
-            or timeout is None
-        ):
-            return backend_preferences
-        if (
-            timeout != backend_preferences.job_timeout
-            and backend_preferences.job_timeout != AWS_DEFAULT_JOB_TIMEOUT_SECONDS
-        ):
-            raise ClassiqValueError(DIFFERENT_TIMEOUT_MSG)
-        if timeout > MAX_EXECUTION_TIMEOUT_SECONDS:
-            raise ClassiqValueError(TIMEOUT_LARGE_FOR_AWS_MSG)
-
-        backend_preferences.job_timeout = timeout
-        return backend_preferences
-
-    @pydantic.validator("random_seed", always=True)
-    def validate_random_seed(
-        cls, original_random_seed: Optional[int], values: Dict[str, Any]
-    ) -> int:
-        return _choose_original_or_optimizer_attribute(
-            original_random_seed, "random_seed", create_random_seed(), values
-        )
-
-
-T = TypeVar("T")
-
-
-def _choose_original_or_optimizer_attribute(
-    original_attribute: Optional[T],
-    attribure_name: str,
-    default_value: T,
-    values: Dict[str, Any],
-) -> T:
-    optimizer_preferences = values.get("optimizer_preferences", None)
-    optimizer_attribute = getattr(optimizer_preferences, attribure_name, None)
-
-    if original_attribute is None and optimizer_attribute is None:
-        return default_value
-
-    elif optimizer_attribute is None:
-        # mypy doesn't understand that original_attribute is not None
-        return original_attribute  # type: ignore[return-value]
-
-    elif original_attribute is None:
-        return optimizer_attribute
-
-    elif original_attribute != optimizer_attribute:
-        raise ClassiqValueError(
-            f"Different {attribure_name} were given for ExecutionPreferences and OptimizerPreferences."
-        )
-
-    else:  # This case is original_num_shots == optimizer_num_shots != None
-        return original_attribute
-
 
 __all__ = [
     "ExecutionPreferences",
-    "ErrorMitigationMethod",
     "NoiseProperties",
-    "OptimizerPreferences",
     "OptimizerType",
     "QaeWithQpeEstimationMethod",
 ]

classiq/interface/executor/execution_request.py

@@ -1,21 +1,17 @@
 from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Union
+from typing import Annotated, Literal, Optional, Union
 
 import pydantic
 from pydantic import BaseModel, Field
-from typing_extensions import Annotated
 
-from classiq.interface.backend.backend_preferences import IonqBackendPreferences
 from classiq.interface.executor.estimation import OperatorsEstimation
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
-from classiq.interface.executor.quantum_code import QuantumCode, QuantumInstructionSet
+from classiq.interface.executor.quantum_code import QuantumCode
 from classiq.interface.generator.quantum_program import QuantumProgram
 from classiq.interface.helpers.custom_encoders import CUSTOM_ENCODERS
 from classiq.interface.helpers.versioned_model import VersionedModel
 from classiq.interface.jobs import JobStatus
 
-from classiq.exceptions import ClassiqValueError
-
 
 class QuantumProgramExecution(QuantumProgram):
     execution_type: Literal["quantum_program2"] = "quantum_program2"
@@ -42,60 +38,42 @@ class ExecutionRequest(BaseModel, json_encoders=CUSTOM_ENCODERS):
         description="preferences for the execution",
     )
 
-    @pydantic.validator("preferences")
-    def validate_ionq_backend(
-        cls, preferences: ExecutionPreferences, values: Dict[str, Any]
-    ) -> ExecutionPreferences:
-        """
-        This function implement the following check:
-        BE \\ payload | IonQ program | Qasm program | Other
-        --------------|--------------|--------------|------
-        IonQ backend  |       V      |      V       |   X
-        Other backend |       X      |      V       |   V
-        Since:
-        - We can't execute non-programs on the IonQ backends
-        - We can't execute IonQ programs on non-IonQ backends
-        """
-        quantum_program = values.get("execution_payload")
-        is_ionq_backend = isinstance(
-            preferences.backend_preferences, IonqBackendPreferences
-        )
-        if isinstance(quantum_program, QuantumCode):
-            if (
-                quantum_program.syntax == QuantumInstructionSet.IONQ
-                and not is_ionq_backend
-            ):
-                raise ClassiqValueError("Can only execute IonQ code on IonQ backend.")
-        else:
-            # If we handle anything other than a program.
-            if is_ionq_backend:
-                raise ClassiqValueError(
-                    "IonQ backend supports only execution of QuantumPrograms"
-                )
-        return preferences
-
 
 class QuantumProgramExecutionRequest(ExecutionRequest):
     execution_payload: QuantumCodeExecution
 
 
+class ProviderJobs(BaseModel):
+    provider_job_id: str = Field(default="DUMMY")
+    cost: float = Field(default=0)
+
+
+class JobCost(BaseModel):
+    total_cost: float = Field(default=0)
+    currency_code: str = Field(default="USD")
+    organization: Optional[str] = Field(default=None)
+    jobs: list[ProviderJobs] = Field(default=[])
+
+
 class ExecutionJobDetails(VersionedModel):
     id: str
 
-    name: Optional[str]
+    name: Optional[str] = Field(default=None)
     start_time: datetime
-    end_time: Optional[datetime]
+    end_time: Optional[datetime] = Field(default=None)
 
-    provider: Optional[str]
-    backend_name: Optional[str]
+    provider: Optional[str] = Field(default=None)
+    backend_name: Optional[str] = Field(default=None)
 
     status: JobStatus
 
-    num_shots: Optional[int]
-    program_id: Optional[str]
+    num_shots: Optional[int] = Field(default=None)
+    program_id: Optional[str] = Field(default=None)
+
+    error: Optional[str] = Field(default=None)
 
-    error: Optional[str]
+    cost: Optional[JobCost] = Field(default=None)
 
 
 class ExecutionJobsQueryResults(VersionedModel):
-    results: List[ExecutionJobDetails]
+    results: list[ExecutionJobDetails]

classiq/interface/executor/execution_result.py

@@ -1,15 +1,19 @@
-from typing import Any, List, Literal, Union
+from typing import Annotated, Any, Literal, Union
 
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, TypeAlias
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import TypeAlias
 
+from classiq.interface.enum_utils import StrEnum
 from classiq.interface.executor.iqae_result import IQAEResult
-from classiq.interface.executor.result import EstimationResult, ExecutionDetails
+from classiq.interface.executor.result import (
+    EstimationResult,
+    EstimationResults,
+    ExecutionDetails,
+    MultipleExecutionDetails,
+)
 from classiq.interface.executor.vqe_result import VQESolverResult
 from classiq.interface.helpers.versioned_model import VersionedModel
 
-from classiq._internals.enum_utils import StrEnum
-
 
 class SavedResultValueType(StrEnum):
     Integer = "int"
@@ -17,7 +21,9 @@ class SavedResultValueType(StrEnum):
     Boolean = "bool"
     VQESolverResult = "VQESolverResult"
     ExecutionDetails = "ExecutionDetails"
+    MultipleExecutionDetails = "MultipleExecutionDetails"
     EstimationResult = "EstimationResult"
+    EstimationResults = "EstimationResults"
     IQAEResult = "IQAEResult"
     Unstructured = "Unstructured"
 
@@ -52,12 +58,24 @@ class TaggedExecutionDetails(BaseModel):
     value: ExecutionDetails
 
 
+class TaggedMultipleExecutionDetails(BaseModel):
+    value_type: Literal[SavedResultValueType.MultipleExecutionDetails]
+    name: str
+    value: MultipleExecutionDetails
+
+
 class TaggedEstimationResult(BaseModel):
     value_type: Literal[SavedResultValueType.EstimationResult]
     name: str
     value: EstimationResult
 
 
+class TaggedEstimationResults(BaseModel):
+    value_type: Literal[SavedResultValueType.EstimationResults]
+    name: str
+    value: EstimationResults
+
+
 class TaggedIQAEResult(BaseModel):
     value_type: Literal[SavedResultValueType.IQAEResult]
     name: str
@@ -67,7 +85,7 @@ class TaggedIQAEResult(BaseModel):
 class TaggedUnstructured(BaseModel):
     value_type: Literal[SavedResultValueType.Unstructured]
     name: str
-    value: Any
+    value: Any = None
 
 
 SavedResult = Annotated[
@@ -77,15 +95,19 @@ SavedResult = Annotated[
         TaggedBoolean,
         TaggedVQESolverResult,
         TaggedExecutionDetails,
+        TaggedMultipleExecutionDetails,
         TaggedEstimationResult,
+        TaggedEstimationResults,
         TaggedIQAEResult,
         TaggedUnstructured,
     ],
     Field(..., discriminator="value_type"),
 ]
 
-ResultsCollection: TypeAlias = List[SavedResult]
+ResultsCollection: TypeAlias = list[SavedResult]
 
 
 class ExecuteGeneratedCircuitResults(VersionedModel):
     results: ResultsCollection
+
+    model_config = ConfigDict(extra="forbid")

classiq/interface/executor/iqae_result.py

@@ -1,6 +1,4 @@
-from typing import List, Tuple
-
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from classiq.interface.executor.result import ExecutionDetails
 from classiq.interface.generator.functions.classical_type import QmodPyObject
@@ -14,6 +12,6 @@ class IQAEIterationData(BaseModel):
 
 class IQAEResult(VersionedModel, QmodPyObject):
     estimation: float
-    confidence_interval: Tuple[float, float]
-    iterations_data: List[IQAEIterationData]
-    warnings: List[str]
+    confidence_interval: list[float] = Field(min_length=2, max_length=2)
+    iterations_data: list[IQAEIterationData]
+    warnings: list[str]