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

classiq/interface/executor/execution_preferences.py

@@ -1,98 +1,56 @@
-from datetime import timedelta
-from typing import Any, Dict, List, Optional, TypeVar, Union
+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
-
-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
     BEST_FIT = 1
 
 
-class AmplitudeAmplification(pydantic.BaseModel):
-    iterations: List[int] = pydantic.Field(
-        default_factory=list,
-        description="Number or list of numbers of iteration to use",
-    )
-    growth_rate: float = pydantic.Field(
-        default=1.25,
-        description="Number of iteration used is set to round(growth_rate**iterations)",
-    )
-    sample_from_iterations: bool = pydantic.Field(
-        default=False,
-        description="If True, number of iterations used is picked randomly from "
-        "[1, iteration] range",
-    )
-    num_of_highest_probability_states_to_check: pydantic.PositiveInt = pydantic.Field(
-        default=1, description="Then number of highest probability states to check"
-    )
-
-    @pydantic.validator("iterations")
-    def _validate_iterations(cls, iterations: Union[List[int], int]) -> List[int]:
-        if isinstance(iterations, int):
-            return [iterations]
-        return iterations
-
-
 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.",
-    )
-    amplitude_amplification: AmplitudeAmplification = pydantic.Field(
-        default_factory=AmplitudeAmplification,
-        description="Settings related to amplitude amplification execution, used during the grover execution.",
-    )
-    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(
@@ -101,88 +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 ValueError(DIFFERENT_TIMEOUT_MSG)
-        if timeout > MAX_EXECUTION_TIMEOUT_SECONDS:
-            raise ValueError(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 ValueError(
-            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",
-    "AmplitudeAmplification",
-    "ErrorMitigationMethod",
     "NoiseProperties",
-    "OptimizerPreferences",
     "OptimizerType",
     "QaeWithQpeEstimationMethod",
 ]

classiq/interface/executor/execution_request.py

@@ -1,99 +1,79 @@
 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
+from pydantic import BaseModel, Field
 
-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_program import (
-    QuantumInstructionSet,
-    QuantumProgram,
-)
-from classiq.interface.generator.generated_circuit import GeneratedCircuit
+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
 
 
-class GeneratedCircuitExecution(GeneratedCircuit):
-    execution_type: Literal["generated_circuit"] = "generated_circuit"
+class QuantumProgramExecution(QuantumProgram):
+    execution_type: Literal["quantum_program2"] = "quantum_program2"
 
 
-class QuantumProgramExecution(QuantumProgram):
-    execution_type: Literal["quantum_program"] = "quantum_program"
+class QuantumCodeExecution(QuantumCode):
+    execution_type: Literal["quantum_code"] = "quantum_code"
 
 
 class EstimateOperatorsExecution(OperatorsEstimation):
     execution_type: Literal["estimate_operators"] = "estimate_operators"
 
 
-ExecutionPayloads = Union[
-    GeneratedCircuitExecution, QuantumProgramExecution, EstimateOperatorsExecution
+ExecutionPayloads = Annotated[
+    Union[QuantumProgramExecution, QuantumCodeExecution, EstimateOperatorsExecution],
+    Field(discriminator="execution_type"),
 ]
 
 
-class ExecutionRequest(BaseModel):
+class ExecutionRequest(BaseModel, json_encoders=CUSTOM_ENCODERS):
     execution_payload: ExecutionPayloads
     preferences: ExecutionPreferences = pydantic.Field(
         default_factory=ExecutionPreferences,
         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, QuantumProgram):
-            if (
-                quantum_program.syntax == QuantumInstructionSet.IONQ
-                and not is_ionq_backend
-            ):
-                raise ValueError("Can only execute IonQ code on IonQ backend.")
-        else:
-            # If we handle anything other than a program.
-            if is_ionq_backend:
-                raise ValueError(
-                    "IonQ backend supports only execution of QuantumPrograms"
-                )
-        return preferences
-
 
 class QuantumProgramExecutionRequest(ExecutionRequest):
-    execution_payload: QuantumProgramExecution
+    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]

classiq/interface/executor/optimizer_preferences.py

@@ -1,12 +1,13 @@
-from typing import List, Optional
+from typing import Optional
 
 import pydantic
 from pydantic import BaseModel
+from pydantic_core.core_schema import ValidationInfo
 
+from classiq.interface.enum_utils import StrEnum
+from classiq.interface.exceptions import ClassiqValueError
 from classiq.interface.helpers.custom_pydantic_types import PydanticAlphaParamCVAR
 
-from classiq._internals.enum_utils import StrEnum
-
 
 class CostType(StrEnum):
     MIN = "MIN"
@@ -33,10 +34,10 @@ class OptimizerPreferences(BaseModel):
     max_iteration: pydantic.PositiveInt = pydantic.Field(
         default=100, description="Maximal number of optimizer iterations"
     )
-    tolerance: pydantic.PositiveFloat = pydantic.Field(
+    tolerance: Optional[pydantic.PositiveFloat] = pydantic.Field(
         default=None, description="Final accuracy in the optimization"
     )
-    step_size: pydantic.PositiveFloat = pydantic.Field(
+    step_size: Optional[pydantic.PositiveFloat] = pydantic.Field(
         default=None,
         description="step size for numerically " "calculating the gradient",
     )
@@ -44,7 +45,7 @@ class OptimizerPreferences(BaseModel):
         default=None,
         description="The random seed used for the generation",
     )
-    initial_point: Optional[List[float]] = pydantic.Field(
+    initial_point: Optional[list[float]] = pydantic.Field(
         default=None,
         description="Initial values for the ansatz parameters",
     )
@@ -53,31 +54,39 @@ class OptimizerPreferences(BaseModel):
         description="If True, the optimizer will not compute the variance of the ansatz.",
     )
 
-    @pydantic.validator("tolerance", pre=True, always=True)
-    def check_tolerance(cls, tolerance, values):
-        optimizer_type = values.get("type")
+    @pydantic.field_validator("tolerance", mode="before")
+    @classmethod
+    def check_tolerance(
+        cls, tolerance: Optional[pydantic.PositiveFloat], info: ValidationInfo
+    ) -> Optional[pydantic.PositiveFloat]:
+        optimizer_type = info.data.get("type")
         if tolerance is not None and optimizer_type == OptimizerType.SPSA:
-            raise ValueError("No tolerance param for SPSA optimizer")
+            raise ClassiqValueError("No tolerance param for SPSA optimizer")
 
         if tolerance is None and optimizer_type != OptimizerType.SPSA:
-            tolerance = 0.001
+            tolerance = pydantic.PositiveFloat(0.001)
 
         return tolerance
 
-    @pydantic.validator("step_size", pre=True, always=True)
-    def check_step_size(cls, step_size, values):
-        optimizer_type = values.get("name")
+    @pydantic.field_validator("step_size", mode="before")
+    @classmethod
+    def check_step_size(
+        cls, step_size: Optional[pydantic.PositiveFloat], info: ValidationInfo
+    ) -> Optional[pydantic.PositiveFloat]:
+        optimizer_type = info.data.get("name")
         if step_size is not None and optimizer_type not in (
             OptimizerType.L_BFGS_B,
             OptimizerType.ADAM,
         ):
-            raise ValueError("Use step_size only for L_BFGS_B or ADAM optimizers.")
+            raise ClassiqValueError(
+                "Use step_size only for L_BFGS_B or ADAM optimizers."
+            )
 
         if step_size is None and optimizer_type in (
             OptimizerType.L_BFGS_B,
             OptimizerType.ADAM,
         ):
-            step_size = 0.05
+            step_size = pydantic.PositiveFloat(0.05)
 
         return step_size
 
@@ -91,7 +100,7 @@ class CombinatorialOptimizer(OptimizerPreferences):
         default=CostType.CVAR,
         description="Summarizing method of the measured bit strings",
     )
-    alpha_cvar: PydanticAlphaParamCVAR = pydantic.Field(
+    alpha_cvar: Optional[PydanticAlphaParamCVAR] = pydantic.Field(
         default=None, description="Parameter for the CVAR summarizing method"
     )
     is_maximization: bool = pydantic.Field(
@@ -103,13 +112,16 @@ class CombinatorialOptimizer(OptimizerPreferences):
         description="Whether to check if all the solutions satisfy the constraints",
     )
 
-    @pydantic.validator("alpha_cvar", pre=True, always=True)
-    def check_alpha_cvar(cls, alpha_cvar, values):
-        cost_type = values.get("cost_type")
+    @pydantic.field_validator("alpha_cvar", mode="before")
+    @classmethod
+    def check_alpha_cvar(
+        cls, alpha_cvar: Optional[PydanticAlphaParamCVAR], info: ValidationInfo
+    ) -> Optional[PydanticAlphaParamCVAR]:
+        cost_type = info.data.get("cost_type")
         if alpha_cvar is not None and cost_type != CostType.CVAR:
-            raise ValueError("Use CVAR params only for CostType.CVAR.")
+            raise ClassiqValueError("Use CVAR params only for CostType.CVAR.")
 
         if alpha_cvar is None and cost_type == CostType.CVAR:
-            alpha_cvar = 0.2
+            alpha_cvar = PydanticAlphaParamCVAR(0.2)
 
         return alpha_cvar