classiq 0.76.0__py3-none-any.whl → 0.78.0__py3-none-any.whl

classiq/applications/chemistry/chemistry_model_constructor.py

@@ -53,6 +53,7 @@ from classiq.qmod.builtins.structs import (
     MoleculeProblem as QmodMoleculeProblem,
     Position as QmodPosition,
 )
+from classiq.qmod.global_declarative_switch import set_global_declarative_switch
 from classiq.qmod.utilities import qmod_val_to_expr_str
 
 # isort: split
@@ -60,6 +61,11 @@ from classiq.qmod.utilities import qmod_val_to_expr_str
 # This import causes a circular import if done earlier. We use isort: split to avoid it
 from classiq.open_library.functions.hea import full_hea
 
+with set_global_declarative_switch():
+    _FULL_HEA = cast(
+        NativeFunctionDefinition, full_hea.create_model().function_dict["full_hea"]
+    )
+
 _LADDER_OPERATOR_TYPE_INDICATOR_TO_QMOD_MAPPING: dict[str, str] = {
     "+": "PLUS",
     "-": "MINUS",
@@ -506,12 +512,7 @@ def construct_chemistry_model(
         )
     ]
     if isinstance(ansatz_parameters, HEAParameters):
-        chemistry_functions.append(
-            cast(
-                NativeFunctionDefinition,
-                full_hea.create_model().function_dict["full_hea"],
-            )
-        )
+        chemistry_functions.append(_FULL_HEA)
     model = Model(
         functions=chemistry_functions,
         classical_execution_code=_get_chemistry_classical_code(

classiq/applications/combinatorial_optimization/combinatorial_optimization_model_constructor.py

@@ -36,6 +36,14 @@ from classiq.applications.combinatorial_helpers.pauli_helpers.pauli_utils import
 )
 from classiq.applications.combinatorial_optimization import OptimizerConfig, QAOAConfig
 from classiq.open_library.functions.qaoa_penalty import qaoa_penalty
+from classiq.qmod.global_declarative_switch import set_global_declarative_switch
+
+with set_global_declarative_switch():
+    _LIBRARY_FUNCTIONS = [
+        f.model_dump()
+        for f in qaoa_penalty.create_model().functions
+        if f.name != "main"
+    ]
 
 
 def construct_combi_opt_py_model(
@@ -107,7 +115,7 @@ def construct_combi_opt_py_model(
                     ),
                 ],
             ),
-            *[f for f in qaoa_penalty.create_model().functions if f.name != "main"],
+            *_LIBRARY_FUNCTIONS,
         ],
         classical_execution_code=f"""
 vqe_result = vqe(

classiq/applications/combinatorial_optimization/combinatorial_problem.py

@@ -24,6 +24,7 @@ from classiq.open_library.functions.utility_functions import (
 from classiq.qmod.builtins.functions import RX
 from classiq.qmod.builtins.operations import allocate, phase, repeat
 from classiq.qmod.cparam import CReal
+from classiq.qmod.create_model_function import create_model
 from classiq.qmod.qfunc import qfunc
 from classiq.qmod.qmod_parameter import CArray
 from classiq.qmod.qmod_variable import Output, QVar
@@ -80,9 +81,9 @@ class CombinatorialProblem:
                 ],
             )
 
-        self.model_ = main.create_model(
-            constraints=constraints, preferences=preferences
-        ).get_model()  # type:ignore[assignment]
+        self.model_ = create_model(
+            main, constraints=constraints, preferences=preferences
+        )  # type:ignore[assignment]
         return self.model_  # type:ignore[return-value]
 
     def get_qprog(self) -> QuantumProgram:

classiq/applications/iqae/iqae.py

@@ -0,0 +1,207 @@
+from typing import Literal, Optional, cast
+
+from classiq.interface.applications.iqae.generic_iqae import GenericIQAE
+from classiq.interface.applications.iqae.iqae_result import (
+    IQAEIterationData,
+    IQAEResult,
+)
+from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.model import Constraints, Preferences
+from classiq.interface.generator.quantum_program import QuantumProgram
+from classiq.interface.model.model import SerializedModel
+
+from classiq.execution import ExecutionSession
+from classiq.open_library import amplitude_amplification
+from classiq.qmod import (
+    CInt,
+    Output,
+    QArray,
+    QBit,
+    QCallable,
+)
+from classiq.qmod.builtins import Z, allocate, bind, within_apply
+from classiq.qmod.create_model_function import create_model
+from classiq.qmod.qfunc import qfunc
+from classiq.synthesis import synthesize
+
+
+class IQAE:
+    """
+    Implementation of Iterative Quantum Amplitude Estimation [1].
+    Given $A$ s.t. $A|0>_n|0> = \\sqrt{1-a}|\\psi_0>_n|0> + \\sqrt{a}|\\psi_1>_n|1>$, the algorithm estimates
+    $a$ by iteratively sampling $Q^kA$, where $Q=AS_0A^{\\dagger}S_{\\psi_0}$, and $k$ is an integer variable.
+
+    For estimating $a$, The algorithm estimates $\\theta_a$ which is defined by $a = sin^2(\\theta_a)$, so it starts with a
+    confidence interval $(0, \\pi/2)$ and narrows down this interval on each iteration according to the sample results.
+
+    References:
+        [1]: Grinko, D., Gacon, J., Zoufal, C., & Woerner, S. (2019).
+             Iterative Quantum Amplitude Estimation.
+             `arXiv:1912.05559 <https://arxiv.org/abs/1912.05559>`.
+    """
+
+    _NUM_SHOUTS = 2048
+
+    def __init__(
+        self,
+        state_prep_op: QCallable[QArray[QBit, Literal["problem_vars_size"]], QBit],
+        problem_vars_size: int,
+        constraints: Optional[Constraints] = None,
+        preferences: Optional[Preferences] = None,
+    ) -> None:
+        self._state_prep_op = state_prep_op
+        self._problem_vars_size: int = problem_vars_size
+        self._constraints: Optional[Constraints] = constraints
+        self._preferences: Optional[Preferences] = preferences
+        self._model: Optional[SerializedModel] = None
+        self._qprog: Optional[QuantumProgram] = None
+
+        """
+        Args:
+            state_prep_op (Qfunc): implementation of the operator $A$ in Qmod.
+            problem_vars_size (int): The size of the problem in terms of the number of qubits, e.g., $n$ of the first register A works on.
+            constraints (Constraints): Constraints for the synthesis of the model. See Constraints (Optional).
+            preferences (Preferences): Preferences for the synthesis of the model. See Preferences (Optional).
+        """
+
+    def get_model(self) -> SerializedModel:
+        """
+        Implement the quantum part of IQAE in terms of the Qmod Model
+
+        Args:
+
+
+        Returns:
+            SerializedModel (str): A serialized model.
+
+        """
+
+        state_prep_op = self._state_prep_op
+        problem_vars_size = self._problem_vars_size
+
+        @qfunc
+        def space_transform(est_reg: QArray) -> None:
+            state_prep_op(est_reg[0 : est_reg.len - 1], est_reg[est_reg.len - 1])
+
+        @qfunc
+        def oracle(est_reg: QArray) -> None:
+            Z(est_reg[est_reg.len - 1])
+
+        @qfunc
+        def main(
+            k: CInt,
+            indicator: Output[QBit],
+        ) -> None:
+            est_reg: QArray = QArray("est_reg")
+            problem_vars: QArray = QArray("problem_vars", length=problem_vars_size)
+            allocate(problem_vars)
+            allocate(indicator)
+            within_apply(
+                lambda: bind([problem_vars, indicator], est_reg),
+                lambda: amplitude_amplification(
+                    k,
+                    oracle,
+                    space_transform,
+                    est_reg,
+                ),
+            )
+
+        if self._model is None:
+            self._model = create_model(
+                main,
+                constraints=self._constraints,
+                preferences=self._preferences,
+            )
+        return self._model
+
+    def get_qprog(self) -> QuantumProgram:
+        """
+        Create an executable quantum Program for IQAE.
+
+        Args:
+
+        Returns:
+            QuantumProgram (QuantumProgram): Quantum program. See QuantumProgram.
+        """
+
+        if self._qprog is None:
+            model = self.get_model()
+            self._qprog = synthesize(model)
+        return self._qprog
+
+    def run(
+        self,
+        epsilon: float,
+        alpha: float,
+        execution_preferences: Optional[ExecutionPreferences] = None,
+    ) -> IQAEResult:
+        """
+        Executes IQAE's quantum program with the provided epsilon, alpha, and execution
+        preferences.
+        If execution_preferences has been proved, or if it does not contain num_shot, then num_shot is set to 2048.
+
+        Args:
+            epsilon (float): Target accuracy in therm of $\\theta_a$ e.g $a = sin^2(\\theta_a \\pm \\epsilon)$ .
+            alpha (float): Specifies the confidence level (1 - alpha)
+            execution_preferences (Preferences): Preferences for the execution of the model. See ExecutionPreferences (Optional).
+        Returns:
+            IQAEResult (IQAEResult): A result of the IQAE algorithm. See IQAEResult.
+        """
+
+        if self._qprog is None:
+            self._qprog = self.get_qprog()
+
+        if execution_preferences is None:
+            execution_preferences = ExecutionPreferences(
+                num_shots=self._NUM_SHOUTS,
+            )
+        elif execution_preferences.num_shots is None:
+            execution_preferences.num_shots = self._NUM_SHOUTS
+
+        return self._run(
+            epsilon=epsilon,
+            alpha=alpha,
+            execution_preferences=execution_preferences,
+            quantum_program=self._qprog,
+        )
+
+    def _run(
+        self,
+        epsilon: float,
+        alpha: float,
+        execution_preferences: ExecutionPreferences,
+        quantum_program: QuantumProgram,
+    ) -> IQAEResult:
+
+        iterations_data: list[IQAEIterationData] = []
+        warnings: list[str] = []
+        with ExecutionSession(quantum_program, execution_preferences) as executor:
+
+            def _iqae_sample(k: int, _: int) -> int:
+                sample_results = executor.sample({"k": k})
+                iterations_data.append(
+                    IQAEIterationData(
+                        grover_iterations=k,
+                        sample_results=sample_results,
+                    )
+                )
+                return sample_results.counts_of_output("indicator").get("1", 0)
+
+            iqae = GenericIQAE(
+                epsilon=epsilon,
+                alpha=alpha,
+                num_shots=cast(int, execution_preferences.num_shots),
+                sample_callable=_iqae_sample,
+            )
+
+            try:
+                iqae.run()
+            except RuntimeError as ex:
+                warnings.append(f"Algorithm error: {ex.args[0]}")
+
+        return IQAEResult(
+            estimation=iqae.current_estimation(),
+            confidence_interval=iqae.current_estimation_confidence_interval().tolist(),
+            iterations_data=iterations_data,
+            warnings=warnings,
+        )

classiq/execution/__init__.py

@@ -1,10 +1,10 @@
 from ..executor import *  # noqa: F403
 from ..executor import __all__ as _exec_all
+from ..interface.applications.iqae.iqae_result import IQAEResult
 from ..interface.backend.backend_preferences import *  # noqa: F403
 from ..interface.backend.backend_preferences import __all__ as _be_all
 from ..interface.executor.execution_preferences import *  # noqa: F403
 from ..interface.executor.execution_preferences import __all__ as _ep_all
-from ..interface.executor.iqae_result import IQAEResult
 from ..interface.executor.result import ExecutionDetails
 from ..interface.executor.vqe_result import VQESolverResult
 from .execution_session import ExecutionSession

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

classiq/interface/applications/iqae/generic_iqae.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+
+MAX_ITERATIONS_NUMBER = 1000
+
+
+class GenericIQAE:
+    """
+    The implementation is based on Algorithm 1 & Algorithm 2 in [1], with the intent of demistifying variables names
+    and simplifying the code flow.
+    Moreover, we separated the algorithm flow from quantum execution to allow migrating this code to any execution
+    interface and to improve its testability.
+
+    References:
+        [1]: Grinko, D., Gacon, J., Zoufal, C., & Woerner, S. (2019).
+             Iterative Quantum Amplitude Estimation.
+             `arXiv:1912.05559 <https://arxiv.org/abs/1912.05559>`.
+    """
+
+    def __init__(
+        self,
+        epsilon: float,
+        alpha: float,
+        num_shots: int,
+        sample_callable: Callable[[int, int], int],
+    ) -> None:
+        """
+        Parameters:
+            epsilon: Target accuracy.
+            alpha: Specifies the confidence level (1 - alpha).
+            num_shots: The maximum number of shots in each iteration.
+            sample_callable: A callable which gets k and num_shots, and returns the count of good states for $Q^kA$
+                (states with 1 in the last qubit).
+                This callable is responsible for the quantum execution and the results parsing.
+        """
+        self._epsilon = epsilon
+        self._alpha = alpha
+        self._num_shots = num_shots
+        self._sample_callable = sample_callable
+
+        self.iterations: list[IterationInfo] = []
+
+        # Prepare initial values (lines 2-6, Algorithm 1, [1])
+        self._new_iteration()
+        self._current().k = 0
+        self._current().is_upper_plane = True
+        self._current().confidence_interval = np.array([0, np.pi / 2])
+
+        self._max_rounds = np.ceil(np.log2(np.pi / (8 * self._epsilon)))
+
+    def _new_iteration(self) -> None:
+        if len(self.iterations) > MAX_ITERATIONS_NUMBER:
+            raise RuntimeError(
+                f"Maximum number of iterations ({MAX_ITERATIONS_NUMBER}) achieved."
+            )
+        self.iterations.append(IterationInfo())
+
+    def _current(self) -> IterationInfo:
+        return self.iterations[-1]
+
+    def _prev(self) -> IterationInfo:
+        return self.iterations[-2]
+
+    def run(self) -> float:
+        """
+        Execute the estimation algorithm.
+        See Algorithm 1, [1].
+        """
+        while interval_len(self._current().confidence_interval) > 2 * self._epsilon:
+            self._new_iteration()
+            self._find_next_K()
+            self._sample()
+            self._calculate_confidence_interval()
+
+        return self.current_estimation()
+
+    def current_estimation_confidence_interval(self) -> np.ndarray:
+        return np.sin(self._current().confidence_interval) ** 2
+
+    def current_estimation(self) -> float:
+        return self.current_estimation_confidence_interval().mean()
+
+    def _find_next_K(self, r: int = 2) -> None:  # noqa: N802
+        self._current().K, self._current().is_upper_plane = self.find_next_K(
+            K=self._prev().K,
+            is_upper_plane=self._prev().is_upper_plane,
+            confidence_interval=self._prev().confidence_interval,
+            r=r,
+        )
+
+    @staticmethod
+    def find_next_K(  # noqa: N802
+        K: int,  # noqa: N803
+        is_upper_plane: bool,
+        confidence_interval: np.ndarray,
+        r: int = 2,
+    ) -> tuple[int, bool]:
+        """
+        We want to find the largest K (with some lower and upper bounds) such that the K-scaled confidence interval
+        lies completely in the upper or lower half planes.
+        See Algorithm 2, [1].
+        """
+        K_max = int(np.pi // interval_len(confidence_interval))  # noqa: N806
+        K_max = K_max - (K_max - 2) % 4  # noqa: N806
+        K_min = r * K  # noqa: N806
+
+        for K_cand in range(K_max, K_min - 1, -4):  # noqa: N806
+            scaled_confidence_interval = (K_cand * confidence_interval) % (2 * np.pi)
+
+            if all(scaled_confidence_interval <= np.pi):
+                return K_cand, True
+            if all(scaled_confidence_interval >= np.pi):
+                return K_cand, False
+
+        return K, is_upper_plane
+
+    def _sample(self) -> None:
+        """
+        Use the external sample callable to get the count of good states for $Q^kA$ (states with 1 in the last qubit).
+        Effectively implements line 16, Algorithm 1, [1].
+        """
+        # To optimize results, the paper's algorithm applies the "no-overshooting condition" which limits
+        # the number of shots in each iteration (lines 12-15, Algorithm 1, [1]). As the calculation is not very
+        # simple, we currently don't support this and use constant number of shots.
+        self._current().num_shots = self._num_shots
+
+        self._current().good_counts = self._sample_callable(
+            self._current().k, self._current().num_shots
+        )
+
+    def _calculate_confidence_interval(self) -> None:
+        """
+        Calculate the next confidence interval based on the last sample's results.
+        Effectively implements lines 17-28, Algorithm 1, [1].
+        """
+        prob = self._current().good_counts / self._current().num_shots
+
+        # The paper specifies two possibles confidence interval methods: Clopper-Perason or Chernoff-Hoeffding.
+        # We currently support only the latter.
+        prob_min, prob_max = self._chernoff_hoeffding(prob)
+
+        if self._current().is_upper_plane:
+            theta = np.arccos(1 - 2 * np.array([prob_min, prob_max]))
+        else:
+            theta = 2 * np.pi - np.arccos(1 - 2 * np.array([prob_max, prob_min]))
+
+        scaled_confidence_interval = (
+            self._current().K * self._prev().confidence_interval
+        )
+        number_of_wraps = scaled_confidence_interval // (2 * np.pi)
+
+        # Sometimes we have edge cases where the lower or upper bound of the scaled interval fall exactly
+        # on 2pi*T for some integer T, and the number of wraps might be rounded up or down wrongfuly.
+        # To fix it, use the number of wraps of the middle point in the scaled interval.
+        if number_of_wraps[0] + 1 == number_of_wraps[1]:
+            number_of_wraps_of_middle = np.mean(scaled_confidence_interval) // (
+                2 * np.pi
+            )
+            number_of_wraps = np.array(
+                [number_of_wraps_of_middle, number_of_wraps_of_middle]
+            )
+
+        if number_of_wraps[0] != number_of_wraps[1]:
+            raise RuntimeError(
+                f"Number of wraps of the lower and upper bounds should be equal, got {number_of_wraps}"
+            )
+
+        self._current().confidence_interval = (
+            2 * np.pi * number_of_wraps + theta
+        ) / self._current().K
+
+    def _chernoff_hoeffding(self, prob: float) -> tuple[float, float]:
+        """
+        The Chernoff-Hoeffding confidence interval method.
+        Effectively implements lines 20-22, Algorithm 1, [1].
+        """
+        epsilon = np.sqrt(
+            np.log(2 * self._max_rounds / self._alpha)
+            / (2 * self._accumulated_num_shots())
+        )
+        return max(0, prob - epsilon), min(1, prob + epsilon)
+
+    def _accumulated_num_shots(self) -> int:
+        num_shots = 0
+        for iteration in reversed(self.iterations):
+            if iteration.K == self._current().K:
+                num_shots += iteration.num_shots
+            else:
+                break
+        return num_shots
+
+
+@dataclass(init=False, repr=False, eq=False)
+class IterationInfo:
+    """
+    The information stored on each iteration of IQAE.
+    """
+
+    K: int  # K = 4k + 2 where k is the power of Q on each iteration
+    is_upper_plane: bool  # Wheter the scaled confidence interval is in the upper or lower half plane (in the paper: "up")
+    confidence_interval: (
+        np.ndarray
+    )  # The current confidence interval (in the paper: "(theta_l, theta_u)")
+
+    good_counts: int
+    num_shots: int = 0
+
+    @property
+    def k(self) -> int:
+        return (self.K - 2) // 4
+
+    @k.setter
+    def k(self, k: int) -> None:
+        self.K = 4 * k + 2
+
+
+def interval_len(interval: np.ndarray) -> float:
+    return interval[1] - interval[0]

classiq/interface/applications/iqae/iqae_result.py

@@ -0,0 +1,45 @@
+from pydantic import BaseModel, Field
+
+from classiq.interface.executor.result import ExecutionDetails
+from classiq.interface.generator.functions.classical_type import QmodPyObject
+from classiq.interface.helpers.versioned_model import VersionedModel
+
+
+class IQAEIterationData(BaseModel):
+    """
+    Handles the data storage for a single iteration of the Iterative Quantum Amplitude
+    Estimation algorithm.
+
+    This class is intended to represent the results and state of a single Grover iteration
+    of the IQAE process.
+
+    Attributes:
+        grover_iterations (int): The iteration number of Grover's algorithm.
+        sample_results (ExecutionDetails): The `ExecutionDetails` of Grover iteration. See ExecutionDetails.
+    """
+
+    grover_iterations: int
+    sample_results: ExecutionDetails
+
+
+class IQAEResult(VersionedModel, QmodPyObject):
+    """
+    Represents the result of an Iterative Quantum Amplitude Estimation (IQAE)
+    process.
+
+    This class encapsulates the output of the IQAE algorithm, including the
+    estimated value, confidence interval, intermediate iteration data, and
+    any warnings generated during the computation.
+
+    Attributes:
+        estimation (float): Estimation of the amplitude.
+        confidence_interval (list[float]): The interval in which the amplitude is within, with a probability equal to epsilon.
+        iterations_data (list[IQAEIterationData]): List of `IQAEIterationData` of each Grover iteration.
+        See IQAEIterationData.
+        warnings (list[str]): List of warnings generated during the IQAE process of each Grover iteration.
+    """
+
+    estimation: float
+    confidence_interval: list[float] = Field(min_length=2, max_length=2)
+    iterations_data: list[IQAEIterationData]
+    warnings: list[str]

classiq/interface/debug_info/debug_info.py

@@ -24,6 +24,7 @@ class FunctionDebugInfo(BaseModel):
     statement_type: Union[StatementType, None] = None
     is_inverse: bool = Field(default=False)
     release_by_inverse: bool = Field(default=False)
+    control_variable: Optional[str] = Field(default=None)
     port_to_passed_variable_map: dict[str, str] = Field(default_factory=dict)
     node: Optional[ConcreteQuantumStatement] = None
 
@@ -85,6 +86,8 @@ def get_back_refs(
         #  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)
         if node.back_ref is None:
             break

classiq/interface/executor/execution_result.py

@@ -3,8 +3,8 @@ from typing import Annotated, Any, Literal, Union
 from pydantic import BaseModel, ConfigDict, Field
 from typing_extensions import TypeAlias
 
+from classiq.interface.applications.iqae.iqae_result import IQAEResult
 from classiq.interface.enum_utils import StrEnum
-from classiq.interface.executor.iqae_result import IQAEResult
 from classiq.interface.executor.result import (
     EstimationResult,
     EstimationResults,

classiq/interface/executor/user_budget.py

@@ -29,7 +29,7 @@ class UserBudgets(VersionedModel):
         def format_row(
             provider: str, available: float, used: float, currency: str
         ) -> str:
-            return f"| {provider:<20} | {available:<18.0f} | {used:<18.0f} | {currency:<8} |"
+            return f"| {provider:<20} | {available:<18.3f} | {used:<18.3f} | {currency:<8} |"
 
         table_data: dict = defaultdict(
             lambda: {"used": 0.0, "available": 0.0, "currency": "USD"}

classiq/interface/generator/expressions/proxies/classical/any_classical_value.py

@@ -1,5 +1,5 @@
 import inspect
-from typing import Any
+from typing import Any, NoReturn
 
 import sympy
 
@@ -37,5 +37,11 @@ class AnyClassicalValue(sympy.Symbol):
             return super().__getattribute__(attr)
         return AnyClassicalValue(f"get_field({self}, '{attr}')")
 
-    def __len__(self) -> "AnyClassicalValue":
-        return self.len
+    def __len__(self) -> NoReturn:
+        raise TypeError("object of type 'AnyClassicalValue' has no len()")
+
+    def __iter__(self) -> NoReturn:
+        raise TypeError("'AnyClassicalValue' object is not iterable")
+
+    def __bool__(self) -> bool:
+        return True