classiq 0.77.0__py3-none-any.whl → 0.79.0__py3-none-any.whl

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.77.0'
+SEMVER_VERSION = '0.79.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/arith/arithmetic.py

@@ -122,12 +122,16 @@ def get_arithmetic_params(
 def compute_arithmetic_result_type(
     expr_str: str, var_types: dict[str, QuantumType], machine_precision: int
 ) -> QuantumNumeric:
-    if is_zero(expr_str) or is_bool(expr_str):
-        return QuantumNumeric(
-            size=Expression(expr="1"),
-            is_signed=Expression(expr="False"),
-            fraction_digits=Expression(expr="0"),
-        )
+    one_qbit_qnum = QuantumNumeric(
+        size=Expression(expr="1"),
+        is_signed=Expression(expr="False"),
+        fraction_digits=Expression(expr="0"),
+    )
+    if is_zero(expr_str):
+        one_qbit_qnum.set_bounds((0, 0))
+        return one_qbit_qnum
+    if is_bool(expr_str):
+        return one_qbit_qnum
     arith_param = get_arithmetic_params(expr_str, var_types, machine_precision)
     return register_info_to_quantum_type(
         arith_param.outputs[ARITHMETIC_EXPRESSION_RESULT_NAME]

classiq/interface/generator/arith/binary_ops.py

@@ -535,14 +535,11 @@ class Multiplier(BinaryOpWithFloatInputs):
         elif isinstance(right_arg, float) and right_arg == 1.0:
             assert isinstance(left_arg, RegisterArithmeticInfo)
             return left_arg.size
-        largest_bound = max(bounds, key=abs)
-        integer_places = int(largest_bound).bit_length() + int(largest_bound < 0)
-        extra_sign_bit = int(
-            argument_utils.is_signed(left_arg)
-            and argument_utils.is_signed(right_arg)
-            and largest_bound > 0
-        )
-        return max(1, integer_places + fraction_places + extra_sign_bit)
+        if bounds[0] == 0 and bounds[1] == 0:
+            return max(1, fraction_places)
+
+        integer_part_size = number_utils.bounds_to_integer_part_size(*bounds)
+        return integer_part_size + fraction_places
 
     def garbage_output_size(self) -> pydantic.NonNegativeInt:
         return max(
@@ -610,7 +607,7 @@ class Power(BinaryOpParams[RegisterArithmeticInfo, pydantic.PositiveInt]):
             )
             for bound in self.left_arg.bounds
         ]
-        if (self.right_arg % 2) or min(bounds) >= 0:
+        if (self.right_arg % 2) or min(bounds) >= 0 or max(bounds) <= 0:
             return (
                 number_utils.limit_fraction_places(
                     bounds[0] ** self.right_arg,
@@ -633,8 +630,8 @@ class Power(BinaryOpParams[RegisterArithmeticInfo, pydantic.PositiveInt]):
         fraction_places = min(self.machine_precision, self.expected_fraction_places())
         bounds = self._get_result_bounds()
         size = number_utils.bounds_to_integer_part_size(*bounds) + fraction_places
-        if bounds[0] == bounds[1]:
-            size = 1
+        if bounds[0] == 0 and bounds[1] == 0:
+            size = max(1, fraction_places)
         return RegisterArithmeticInfo(
             size=size,
             is_signed=self.left_arg.is_signed and (self.right_arg % 2 == 1),

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