classiq 0.83.0__py3-none-any.whl → 0.85.0__py3-none-any.whl

classiq/{model_expansions/evaluators → evaluators}/parameter_types.py

@@ -12,7 +12,6 @@ from classiq.interface.generator.expressions.proxies.classical.any_classical_val
 )
 from classiq.interface.generator.functions.classical_type import (
     ClassicalArray,
-    ClassicalList,
     ClassicalTuple,
     ClassicalType,
 )
@@ -39,20 +38,20 @@ from classiq.interface.model.quantum_type import (
     QuantumType,
 )
 
-from classiq.model_expansions.closure import FunctionClosure
-from classiq.model_expansions.evaluators.arg_type_match import check_type_match
-from classiq.model_expansions.evaluators.classical_expression import (
+from classiq.evaluators.arg_type_match import check_type_match
+from classiq.evaluators.classical_expression import (
     evaluate_classical_expression,
 )
-from classiq.model_expansions.evaluators.classical_type_inference import (
+from classiq.evaluators.classical_type_inference import (
     infer_classical_type,
 )
-from classiq.model_expansions.evaluators.quantum_type_utils import (
+from classiq.evaluators.quantum_type_utils import (
     copy_type_information,
     set_element_type,
     set_length,
     set_size,
 )
+from classiq.model_expansions.closure import FunctionClosure
 from classiq.model_expansions.scope import (
     Evaluated,
     QuantumSymbol,
@@ -81,7 +80,10 @@ def evaluate_parameter_types_from_args(
 
     return [
         _evaluate_type_from_arg(
-            parameter, argument, Scope(parent=closure.scope | signature_scope)
+            parameter,
+            argument,
+            Scope(parent=closure.scope | signature_scope),
+            closure.name,
         )
         for parameter, argument in zip(parameters, arguments)
     ]
@@ -142,8 +144,14 @@ def _cast(
 
 
 def _evaluate_type_from_arg(
-    parameter: PositionalArg, argument: Evaluated, inner_scope: Scope
+    parameter: PositionalArg,
+    argument: Evaluated,
+    inner_scope: Scope,
+    function_name: str,
 ) -> PositionalArg:
+    # FIXME: Remove suzuki_trotter overloading (CLS-2912)
+    if function_name == "suzuki_trotter" and parameter.name == "pauli_operator":
+        return parameter
     if isinstance(parameter, ClassicalParameterDeclaration):
         updated_classical_type = evaluate_type_in_classical_symbol(
             parameter.classical_type.model_copy(), inner_scope, parameter.name
@@ -310,13 +318,7 @@ def evaluate_type_in_classical_symbol(
     type_to_update: ClassicalType, scope: Scope, param_name: str
 ) -> ClassicalType:
     updated_type: ClassicalType
-    if isinstance(type_to_update, ClassicalList):
-        updated_type = ClassicalArray(
-            element_type=evaluate_type_in_classical_symbol(
-                type_to_update.element_type, scope, param_name
-            )
-        )
-    elif isinstance(type_to_update, ClassicalArray):
+    if isinstance(type_to_update, ClassicalArray):
         length = type_to_update.length
         if length is not None:
             new_length = _eval_expr(

classiq/execution/__init__.py

@@ -11,7 +11,14 @@ from .execution_session import ExecutionSession
 from .iqcc import generate_iqcc_token, generate_iqcc_token_async
 from .jobs import ExecutionJob, get_execution_jobs, get_execution_jobs_async
 from .qnn import execute_qnn
-from .user_budgets import get_budget, get_budget_async
+from .user_budgets import (
+    clear_budget_limit,
+    clear_budget_limit_async,
+    get_budget,
+    get_budget_async,
+    set_budget_limit,
+    set_budget_limit_async,
+)
 
 __all__ = (
     _be_all
@@ -30,6 +37,10 @@ __all__ = (
         "generate_iqcc_token_async",
         "get_budget",
         "get_budget_async",
+        "set_budget_limit",
+        "set_budget_limit_async",
+        "clear_budget_limit",
+        "clear_budget_limit_async",
     ]
 )
 

classiq/execution/execution_session.py

@@ -1,24 +1,41 @@
+import inspect
 import random
+import warnings
 from types import TracebackType
-from typing import Callable, Optional, Union, cast
-
-import numpy as np
+from typing import Any, Callable, Optional, Union, cast
 
 from classiq.interface.chemistry.operator import PauliOperator, pauli_integers_to_str
-from classiq.interface.exceptions import ClassiqError, ClassiqValueError
-from classiq.interface.execution.primitives import EstimateInput, PrimitivesInput
+from classiq.interface.exceptions import (
+    ClassiqDeprecationWarning,
+    ClassiqError,
+    ClassiqValueError,
+)
+from classiq.interface.execution.primitives import (
+    EstimateInput,
+    MinimizeClassicalCostInput,
+    MinimizeQuantumCostInput,
+    PrimitivesInput,
+)
+from classiq.interface.executor.estimate_cost import estimate_cost
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.executor.execution_result import TaggedMinimizeResult
 from classiq.interface.executor.result import (
     EstimationResult,
     ExecutionDetails,
     ParsedState,
 )
 from classiq.interface.generator.arith import number_utils
+from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.generator.functions.qmod_python_interface import QmodPyStruct
 from classiq.interface.generator.quantum_program import (
     QuantumProgram,
 )
-from classiq.interface.model.quantum_type import QuantumBit, QuantumNumeric
+from classiq.interface.helpers.custom_pydantic_types import PydanticPauliList
+from classiq.interface.model.quantum_type import (
+    QuantumBit,
+    QuantumNumeric,
+    RegisterQuantumTypeDict,
+)
 
 from classiq._internals import async_utils
 from classiq._internals.api_wrapper import ApiWrapper
@@ -27,38 +44,24 @@ from classiq.applications.combinatorial_helpers.pauli_helpers.pauli_utils import
     _pauli_dict_to_pauli_terms,
 )
 from classiq.execution.jobs import ExecutionJob
-from classiq.qmod.builtins import PauliTerm
 from classiq.qmod.builtins.classical_execution_primitives import (
     CARRAY_SEPARATOR,
     ExecutionParams,
 )
+from classiq.qmod.builtins.structs import PauliTerm, SparsePauliOp
+from classiq.qmod.qmod_variable import (
+    QmodExpressionCreator,
+    create_qvar_from_quantum_type,
+)
 
-Hamiltonian = Union[list[QmodPyStruct], list[PauliTerm]]
-ParsedExecutionParams = dict[str, Union[float, int]]
+Hamiltonian = SparsePauliOp
 ExecutionParameters = Optional[Union[ExecutionParams, list[ExecutionParams]]]
+ParsedExecutionParams = dict[str, Union[float, int]]
 ParsedExecutionParameters = Optional[
     Union[ParsedExecutionParams, list[ParsedExecutionParams]]
 ]
 
 
-def hamiltonian_to_pauli_terms(hamiltonian: Hamiltonian) -> list[PauliTerm]:
-    if isinstance(hamiltonian[0], PauliTerm):
-        return cast(list[PauliTerm], hamiltonian)
-    else:
-        return _pauli_dict_to_pauli_terms(cast(list[QmodPyStruct], hamiltonian))
-
-
-def _hamiltonian_to_pauli_operator(hamiltonian: Hamiltonian) -> PauliOperator:
-    pauli_list = [
-        (
-            pauli_integers_to_str(elem.pauli),  # type: ignore[arg-type]
-            elem.coefficient,
-        )
-        for elem in hamiltonian_to_pauli_terms(hamiltonian)
-    ]
-    return PauliOperator(pauli_list=pauli_list)
-
-
 def parse_params(params: ExecutionParams) -> ParsedExecutionParams:
     result = {}
     for key, values in params.items():
@@ -73,6 +76,20 @@ def parse_params(params: ExecutionParams) -> ParsedExecutionParams:
     return result
 
 
+def _hamiltonian_deprecation_warning(hamiltonian: Any) -> None:
+    if isinstance(hamiltonian, list):
+        warnings.warn(
+            (
+                "Parameter type list[PauliTerm] to 'ExecutionSession' methods is "
+                "deprecated and will no longer be supported starting on 21/7/2025 "
+                "at the earliest. Instead, send a 'SparsePauliOp' (see "
+                "https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/#hamiltonians)."
+            ),
+            ClassiqDeprecationWarning,
+            stacklevel=3,
+        )
+
+
 class ExecutionSession:
     """
     A session for executing a quantum program.
@@ -230,11 +247,18 @@ class ExecutionSession:
         Returns:
             EstimationResult: The result of the estimation.
         """
-        job = self.submit_estimate(hamiltonian=hamiltonian, parameters=parameters)
+        _hamiltonian_deprecation_warning(hamiltonian)
+        job = self.submit_estimate(
+            hamiltonian=hamiltonian, parameters=parameters, _check_deprecation=False
+        )
         return job.get_estimate_result(_http_client=self._async_client)
 
     def submit_estimate(
-        self, hamiltonian: Hamiltonian, parameters: Optional[ExecutionParams] = None
+        self,
+        hamiltonian: Hamiltonian,
+        parameters: Optional[ExecutionParams] = None,
+        *,
+        _check_deprecation: bool = True,
     ) -> ExecutionJob:
         """
         Initiates an execution job with the `estimate` primitive.
@@ -249,9 +273,11 @@ class ExecutionSession:
         Returns:
             The execution job.
         """
+        if _check_deprecation:
+            _hamiltonian_deprecation_warning(hamiltonian)
         execution_primitives_input = PrimitivesInput(
             estimate=EstimateInput(
-                hamiltonian=_hamiltonian_to_pauli_operator(hamiltonian),
+                hamiltonian=self._hamiltonian_to_pauli_operator(hamiltonian),
                 parameters=(
                     [parse_params(parameters)] if parameters is not None else [{}]
                 ),
@@ -272,11 +298,18 @@ class ExecutionSession:
         Returns:
             List[EstimationResult]: The results of all the estimation iterations.
         """
-        job = self.submit_batch_estimate(hamiltonian=hamiltonian, parameters=parameters)
+        _hamiltonian_deprecation_warning(hamiltonian)
+        job = self.submit_batch_estimate(
+            hamiltonian=hamiltonian, parameters=parameters, _check_deprecation=False
+        )
         return job.get_batch_estimate_result(_http_client=self._async_client)
 
     def submit_batch_estimate(
-        self, hamiltonian: Hamiltonian, parameters: list[ExecutionParams]
+        self,
+        hamiltonian: Hamiltonian,
+        parameters: list[ExecutionParams],
+        *,
+        _check_deprecation: bool = True,
     ) -> ExecutionJob:
         """
         Initiates an execution job with the `batch_estimate` primitive.
@@ -291,14 +324,119 @@ class ExecutionSession:
         Returns:
             The execution job.
         """
+        if _check_deprecation:
+            _hamiltonian_deprecation_warning(hamiltonian)
         execution_primitives_input = PrimitivesInput(
             estimate=EstimateInput(
-                hamiltonian=_hamiltonian_to_pauli_operator(hamiltonian),
+                hamiltonian=self._hamiltonian_to_pauli_operator(hamiltonian),
                 parameters=[parse_params(params) for params in parameters],
             )
         )
         return self._execute(execution_primitives_input)
 
+    def minimize(
+        self,
+        cost_function: Union[Hamiltonian, QmodExpressionCreator],
+        initial_params: ExecutionParams,
+        max_iteration: int,
+        quantile: float = 1.0,
+    ) -> list[tuple[float, ExecutionParams]]:
+        """
+        Minimizes the given cost function using the quantum program.
+        Args:
+            cost_function: The cost function to minimize. It can be one of the following:
+                - A quantum cost function defined by a Hamiltonian.
+                - A classical cost function represented as a callable that returns a Qmod expression.
+                  The callable should accept `QVar`s as arguments and use names matching the Model outputs.
+            initial_params: The initial parameters for the minimization.
+                Only Models with exactly one execution parameter are supported. This parameter must be of type
+                `CReal` or `CArray`. The dictionary must contain a single key-value pair, where:
+                    - The key is the name of the parameter.
+                    - The value is either a float or a list of floats.
+            max_iteration: The maximum number of iterations for the minimization.
+            quantile: The quantile to use for cost estimation.
+        Returns:
+            A list of tuples, each containing the estimated cost and the corresponding parameters for that iteration.
+            `cost` is a float, and `parameters` is a dictionary matching the execution parameter format.
+        """
+        _hamiltonian_deprecation_warning(cost_function)
+        job = self.submit_minimize(
+            cost_function=cost_function,
+            initial_params=initial_params,
+            max_iteration=max_iteration,
+            quantile=quantile,
+            _check_deprecation=False,
+        )
+        result = job.get_minimization_result(_http_client=self._async_client)
+
+        return self._minimize_result_to_result(
+            result=result, initial_params=initial_params
+        )
+
+    def submit_minimize(
+        self,
+        cost_function: Union[Hamiltonian, QmodExpressionCreator],
+        initial_params: ExecutionParams,
+        max_iteration: int,
+        quantile: float = 1.0,
+        *,
+        _check_deprecation: bool = True,
+    ) -> ExecutionJob:
+        """
+        Initiates an execution job with the `minimize` primitive.
+
+        This is a non-blocking version of `minimize`: it gets the same parameters and initiates the same execution job, but instead
+        of waiting for the result, it returns the job object immediately.
+
+        Args:
+            cost_function: The cost function to minimize. It can be one of the following:
+                - A quantum cost function defined by a Hamiltonian.
+                - A classical cost function represented as a callable that returns a Qmod expression.
+                  The callable should accept `QVar`s as arguments and use names matching the Model outputs.
+            initial_params: The initial parameters for the minimization.
+                Only Models with exactly one execution parameter are supported. This parameter must be of type
+                `CReal` or `CArray`. The dictionary must contain a single key-value pair, where:
+                    - The key is the name of the parameter.
+                    - The value is either a float or a list of floats.
+            max_iteration: The maximum number of iterations for the minimization.
+            quantile: The quantile to use for cost estimation.
+
+        Returns:
+            The execution job.
+        """
+        if _check_deprecation:
+            _hamiltonian_deprecation_warning(cost_function)
+        if len(initial_params) != 1:
+            raise ClassiqValueError(
+                "The initial parameters must be a dictionary with a single key-value pair."
+            )
+
+        _cost_function: Union[PauliOperator, Expression]
+        _initial_params = parse_params(initial_params)
+        minimize: Union[MinimizeQuantumCostInput, MinimizeClassicalCostInput]
+        if callable(cost_function):
+            circuit_output_types = self.program.model.circuit_output_types
+            _cost_function = self._create_qmod_expression(
+                circuit_output_types, cost_function
+            )
+            minimize = MinimizeClassicalCostInput(
+                cost_function=_cost_function,
+                initial_params=_initial_params,
+                max_iteration=max_iteration,
+                quantile=quantile,
+            )
+        else:
+            _cost_function = self._hamiltonian_to_pauli_operator(cost_function)
+            minimize = MinimizeQuantumCostInput(
+                cost_function=_cost_function,
+                initial_params=_initial_params,
+                max_iteration=max_iteration,
+                quantile=quantile,
+            )
+
+        execution_primitives_input = PrimitivesInput(minimize=minimize)
+        return self._execute(execution_primitives_input)
+
     def estimate_cost(
         self,
         cost_func: Callable[[ParsedState], float],
@@ -319,23 +457,8 @@ class ExecutionSession:
         See Also:
             sample
         """
-        if quantile < 0 or quantile > 1:
-            raise ClassiqValueError("'quantile' must be between 0 and 1")
         res = self.sample(parameters)
-
-        counts = np.array(res.parsed_counts)
-        costs = np.vectorize(lambda sample: cost_func(sample.state))(counts)
-        shots = np.vectorize(lambda sample: sample.shots)(counts)
-
-        if quantile == 1:
-            return float(np.average(costs, weights=shots))
-        costs = np.repeat(costs, shots)
-        sort_idx = costs.argsort()
-        sort_idx = sort_idx[: int(quantile * len(costs))]
-        costs = costs[sort_idx]
-        if costs.size == 0:
-            return np.nan
-        return float(np.average(costs))
+        return estimate_cost(cost_func, res.parsed_counts, quantile=quantile)
 
     def set_measured_state_filter(
         self,
@@ -387,3 +510,69 @@ class ExecutionSession:
             )
 
         self.program.model.register_filter_bitstrings[output_name] = legal_bitstrings
+
+    @staticmethod
+    def _hamiltonian_to_pauli_operator(hamiltonian: Hamiltonian) -> PauliOperator:
+        pauli_list: PydanticPauliList
+        # FIXME: Remove compatibility (CLS-2912)
+        if isinstance(hamiltonian, list):  # type:ignore[unreachable]
+            pauli_list = [  # type:ignore[unreachable]
+                (
+                    pauli_integers_to_str(elem.pauli),
+                    cast(complex, elem.coefficient),
+                )
+                for elem in ExecutionSession._hamiltonian_to_pauli_terms(hamiltonian)
+            ]
+            return PauliOperator(pauli_list=pauli_list)
+        pauli_list = []
+        for term in cast(list, hamiltonian.terms):
+            paulis = ["I"] * cast(int, hamiltonian.num_qubits)
+            for indexed_pauli in term.paulis:
+                paulis[len(paulis) - indexed_pauli.index - 1] = indexed_pauli.pauli.name
+            pauli_list.append(("".join(paulis), term.coefficient))
+        return PauliOperator(pauli_list=pauli_list)
+
+    @staticmethod
+    def _create_qmod_expression(
+        circuit_output_types: RegisterQuantumTypeDict,
+        qmod_expression_creator: QmodExpressionCreator,
+    ) -> Expression:
+        symbolic_output = {
+            name: create_qvar_from_quantum_type(reg.quantum_types, name)
+            for name, reg in circuit_output_types.items()
+        }
+        for name in inspect.signature(qmod_expression_creator).parameters.keys():
+            if name not in symbolic_output:
+                raise ClassiqValueError(
+                    f"The provided QVar: {name} does not match the model outputs: {tuple(circuit_output_types.keys())}. "
+                )
+
+        qmod_expression = qmod_expression_creator(**symbolic_output)
+        return Expression(expr=str(qmod_expression))
+
+    @staticmethod
+    def _hamiltonian_to_pauli_terms(hamiltonian: list) -> list[PauliTerm]:
+        if isinstance(hamiltonian[0], PauliTerm):
+            return cast(list[PauliTerm], hamiltonian)
+        else:
+            return _pauli_dict_to_pauli_terms(cast(list[QmodPyStruct], hamiltonian))
+
+    @staticmethod
+    def _minimize_result_to_result(
+        result: TaggedMinimizeResult, initial_params: ExecutionParams
+    ) -> list[tuple[float, ExecutionParams]]:
+        param_name = next(iter(initial_params.keys()))
+        param_value = initial_params[param_name]
+        return [
+            (
+                res.expectation_value,
+                {
+                    param_name: (
+                        res.parameters[0]
+                        if isinstance(param_value, (float, int))
+                        else res.parameters
+                    )
+                },
+            )
+            for res in result.value
+        ]

classiq/execution/jobs.py

@@ -10,7 +10,10 @@ from classiq.interface.exceptions import (
     ClassiqError,
 )
 from classiq.interface.executor.execution_request import ExecutionJobDetails, JobCost
-from classiq.interface.executor.execution_result import ResultsCollection
+from classiq.interface.executor.execution_result import (
+    ResultsCollection,
+    TaggedMinimizeResult,
+)
 from classiq.interface.executor.result import (
     EstimationResult,
     EstimationResults,
@@ -244,6 +247,28 @@ class ExecutionJob:
 
         raise ClassiqExecutionResultError("batch_estimate")
 
+    def get_minimization_result(
+        self, _http_client: Optional[httpx.AsyncClient] = None
+    ) -> TaggedMinimizeResult:
+        """
+        Returns the job's result as a single minimization result after validation. If the result is not yet available, waits for it.
+
+        Returns:
+            The minimization result of the execution job.
+
+        Raises:
+            ClassiqExecutionResultError: In case the result does not contain a single minimization result.
+            ClassiqAPIError: In case the job has failed.
+        """
+        results = self.result(_http_client=_http_client)
+        if len(results) != 1:
+            raise ClassiqExecutionResultError("minimization")
+
+        result = results[0]
+        if isinstance(result, TaggedMinimizeResult):
+            return result
+        raise ClassiqExecutionResultError("minimization")
+
     async def poll_async(
         self,
         timeout_sec: Optional[float] = None,

classiq/execution/qnn.py

@@ -15,7 +15,7 @@ from classiq.interface.executor.quantum_code import Arguments, MultipleArguments
 
 from classiq import QuantumProgram
 from classiq.applications.combinatorial_helpers.pauli_helpers.pauli_utils import (
-    pauli_operator_to_hamiltonian,
+    pauli_operator_to_sparse_hamiltonian,
 )
 from classiq.execution.execution_session import ExecutionSession
 
@@ -27,7 +27,7 @@ def _execute_qnn_estimate(
     arguments: list[Arguments],
     observable: PauliOperator,
 ) -> ResultsCollection:
-    hamiltonian = pauli_operator_to_hamiltonian(observable.pauli_list)
+    hamiltonian = pauli_operator_to_sparse_hamiltonian(observable.pauli_list)
     return [
         TaggedEstimationResult(
             name=DEFAULT_RESULT_NAME,

classiq/execution/user_budgets.py

@@ -36,3 +36,42 @@ async def get_budget_async(
 
 
 get_budget = syncify_function(get_budget_async)
+
+
+async def set_budget_limit_async(
+    provider_vendor: ProviderVendor,
+    limit: float,
+) -> UserBudgets:
+    provider = PROVIDER_MAPPER.get(provider_vendor, None)
+    if not provider:
+        raise ValueError(f"Unsupported provider: {provider_vendor}")
+
+    budget = get_budget(provider_vendor)
+    if budget is None:
+        raise ValueError(f"No budget found for provider: {provider_vendor}")
+
+    if limit <= 0:
+        raise ValueError("Budget limit must be greater than zero.")
+
+    if limit > budget.budgets[0].available_budget:
+        print(  # noqa: T201
+            f"Budget limit {limit} exceeds available budget {budget.budgets[0].available_budget} for provider {provider_vendor}.\n"
+            "Setting budget limit to the maximum available budget."
+        )
+    budgets_list = await ApiWrapper().call_set_budget_limit(provider, limit)
+    return UserBudgets(budgets=[budgets_list])
+
+
+set_budget_limit = syncify_function(set_budget_limit_async)
+
+
+async def clear_budget_limit_async(provider_vendor: ProviderVendor) -> UserBudgets:
+    provider = PROVIDER_MAPPER.get(provider_vendor, None)
+    if not provider:
+        raise ValueError(f"Unsupported provider: {provider_vendor}")
+
+    budgets_list = await ApiWrapper().call_clear_budget_limit(provider)
+    return UserBudgets(budgets=[budgets_list])
+
+
+clear_budget_limit = syncify_function(clear_budget_limit_async)

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.83.0'
+SEMVER_VERSION = '0.85.0'
 VERSION = str(Version(SEMVER_VERSION))

classiq/interface/constants.py

@@ -0,0 +1 @@
+DEFAULT_DECIMAL_PRECISION = 4

classiq/interface/debug_info/debug_info.py

@@ -9,7 +9,6 @@ from classiq.interface.generator.generated_circuit_data import (
     FunctionDebugInfoInterface,
     StatementType,
 )
-from classiq.interface.model.block import Block
 from classiq.interface.model.handle_binding import ConcreteHandleBinding
 from classiq.interface.model.port_declaration import PortDeclaration
 from classiq.interface.model.quantum_function_call import ArgValue
@@ -82,9 +81,6 @@ def get_back_refs(
 ) -> list[ConcreteQuantumStatement]:
     back_refs: list[ConcreteQuantumStatement] = []
     while (node := debug_info.node) is not None:
-        #  For backwards compatibility, we make sure that the back_ref is not a block
-        #  Remove this check when we start saving blocks in the debug info collection.
-        assert not isinstance(node, Block)
         if len(back_refs) > 0 and node.back_ref == back_refs[0].back_ref:
             break
         back_refs.insert(0, node)

classiq/interface/execution/primitives.py

@@ -1,9 +1,10 @@
-from typing import Optional
+from typing import Annotated, Literal, Optional, Union
 
 from pydantic import BaseModel, Field
 
 from classiq.interface.chemistry.operator import PauliOperator
 from classiq.interface.executor.quantum_code import Arguments
+from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.helpers.custom_encoders import CUSTOM_ENCODERS
 
 
@@ -12,7 +13,34 @@ class EstimateInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
     parameters: list[Arguments]
 
 
+class MinimizeCostInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
+    initial_params: Arguments
+    max_iteration: int
+    quantile: float
+
+
+class MinimizeClassicalCostInput(MinimizeCostInput):
+    cost_function: Expression
+    kind: Literal["MinimizeClassicalCostInput"] = Field(
+        default="MinimizeClassicalCostInput"
+    )
+
+
+class MinimizeQuantumCostInput(MinimizeCostInput):
+    cost_function: PauliOperator
+    kind: Literal["MinimizeQuantumCostInput"] = Field(
+        default="MinimizeQuantumCostInput"
+    )
+
+
+ConcreteMinimizeCostInput = Annotated[
+    Union[MinimizeQuantumCostInput, MinimizeClassicalCostInput],
+    Field(discriminator="kind"),
+]
+
+
 class PrimitivesInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
     sample: Optional[list[Arguments]] = Field(default=None)
     estimate: Optional[EstimateInput] = Field(default=None)
+    minimize: Optional[ConcreteMinimizeCostInput] = Field(default=None)
     random_seed: Optional[int] = Field(default=None)