classiq 0.104.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

classiq/interface/qubits_mapping/slices.py

@@ -0,0 +1,112 @@
+from collections import deque
+from collections.abc import Iterable, Reversible
+from itertools import chain
+
+from typing_extensions import override
+
+
+class Slices(deque[tuple[int, int]]):
+    """A deque of slice objects that automatically merges adjacent slices.
+
+    Slices represent a collection of non-overlapping, potentially non-contiguous
+    slice ranges. When slices are appended or prepended, adjacent slices are
+    automatically merged to maintain a compact representation. Methods use virtual
+    notation, access the elements in the object as if all slices were explicitly
+    written out contiguously.
+
+    The class is primarily used for managing qubit allocations and mappings in
+    quantum circuit synthesis, where it tracks which physical qubit ranges
+    correspond to logical variable ranges.
+    """
+
+    @override
+    def append(self, physical_slice: tuple[int, int]) -> None:
+        if self and self[-1][1] == physical_slice[0]:
+            last_physical_slice = self.pop()
+            new_physical_slice = (last_physical_slice[0], physical_slice[1])
+        else:
+            new_physical_slice = physical_slice
+        super().append(new_physical_slice)
+
+    @override
+    def appendleft(self, physical_slice: tuple[int, int]) -> None:
+        if self and self[0][0] == physical_slice[1]:
+            first_physical_slice = self.popleft()
+            new_physical_slice = (physical_slice[0], first_physical_slice[1])
+        else:
+            new_physical_slice = physical_slice
+        super().appendleft(new_physical_slice)
+
+    def _multiple_appendleft(
+        self, physical_slices: Reversible[tuple[int, int]]
+    ) -> None:
+        for physical_slice in reversed(physical_slices):
+            self.appendleft(physical_slice)
+
+    @override
+    def extend(self, physical_slices: Iterable[tuple[int, int]]) -> None:
+        for physical_slice in physical_slices:
+            self.append(physical_slice)
+
+    def pop_prefix_virtual_slice(self, virtual_end: int) -> "Slices":
+        result = Slices()
+        current_virtual_end, result_physical_end, physical_slice_end = 0, 0, 0
+        while current_virtual_end < virtual_end:
+            physical_slice_start, physical_slice_end = self.popleft()
+            current_virtual_end += physical_slice_end - physical_slice_start
+            overlap_virtual_end = min(virtual_end, current_virtual_end)
+            result_physical_end = physical_slice_end + (
+                overlap_virtual_end - current_virtual_end
+            )
+            result.append((physical_slice_start, result_physical_end))
+        if result_physical_end != physical_slice_end:
+            self.appendleft((result_physical_end, physical_slice_end))
+        return result
+
+    def get_virtual_slice(self, virtual_start: int, virtual_end: int) -> "Slices":
+        result = Slices()
+        current_virtual_start = 0
+        for physical_slice in self:
+            physical_slice_start, physical_slice_end = physical_slice
+            current_virtual_end = current_virtual_start + (
+                physical_slice_end - physical_slice_start
+            )
+            overlap_virtual_start = max(virtual_start, current_virtual_start)
+            overlap_virtual_end = min(virtual_end, current_virtual_end)
+            if overlap_virtual_start < overlap_virtual_end:
+                new_physical_start = physical_slice_start + (
+                    overlap_virtual_start - current_virtual_start
+                )
+                new_physical_end = physical_slice_end + (
+                    overlap_virtual_end - current_virtual_end
+                )
+                result.append((new_physical_start, new_physical_end))
+            if current_virtual_end >= virtual_end:
+                break
+            current_virtual_start = current_virtual_end
+        return result
+
+    def update_virtual_slice(
+        self, virtual_start: int, virtual_end: int, new: "Slices"
+    ) -> None:
+        start = self.pop_prefix_virtual_slice(virtual_start)
+        self.pop_prefix_virtual_slice(virtual_end - virtual_start)
+        self._multiple_appendleft(new)
+        self._multiple_appendleft(start)
+
+    def mapping_virtual_slices(self, virtual_slices: "Slices") -> "Slices":
+        mappings = Slices()
+        for virtual_slice in virtual_slices:
+            virtual_start, virtual_end = virtual_slice
+            for mapped_slice in self.get_virtual_slice(virtual_start, virtual_end):
+                mappings.append(mapped_slice)
+        return mappings
+
+    def size(self) -> int:
+        return sum(_slice[1] - _slice[0] for _slice in self)
+
+    @property
+    def indices(self) -> tuple[int, ...]:
+        return tuple(
+            chain.from_iterable(range(_slice[0], _slice[1]) for _slice in self)
+        )

classiq/model_expansions/arithmetic.py

@@ -88,6 +88,12 @@ class NumericAttributes:
             return self.lb
         return None
 
+    def fits_in(self, other: "NumericAttributes") -> bool:
+        return (
+            self.integer_digits <= other.integer_digits
+            and self.fraction_digits <= other.fraction_digits
+        )
+
     @classmethod
     def from_bounds(
         cls,

classiq/qmod/builtins/functions/__init__.py

@@ -2,7 +2,8 @@ from .allocation import *
 from .arithmetic import *
 from .benchmarking import *
 from .exponentiation import *
-from .mcx_func import mcx
+from .gray_code import *
+from .mcx_func import *
 from .mid_circuit_measurement import *
 from .operators import *
 from .standard_gates import *
@@ -38,12 +39,12 @@ CORE_LIB_DECLS = [
         SWAP,
         IDENTITY,
         prepare_state,
-        prepare_state_approx,
         prepare_amplitudes,
-        prepare_amplitudes_approx,
         unitary,
         add,
         add_inplace_right,
+        canonical_add,
+        canonical_add_constant,
         modular_add,
         integer_xor,
         modular_add_constant,
@@ -58,9 +59,7 @@ CORE_LIB_DECLS = [
         drop,
         randomized_benchmarking,
         inplace_prepare_state,
-        inplace_prepare_state_approx,
         inplace_prepare_amplitudes,
-        inplace_prepare_amplitudes_approx,
         single_pauli_exponent,
         commuting_paulis_exponent,
         suzuki_trotter,
@@ -74,7 +73,10 @@ CORE_LIB_DECLS = [
         exponentiation_with_depth_constraint,
         RESET,
         mcx,
+        mcx_gray_code,
+        mcx_hybrid_rec,
         SX,
+        select_rotation,
     )
 ]
 
@@ -94,6 +96,8 @@ __all__ = [  # noqa: RUF022
     "I",
     "IDENTITY",
     "mcx",
+    "mcx_gray_code",
+    "mcx_hybrid_rec",
     "PHASE",
     "R",
     "RX",
@@ -114,6 +118,8 @@ __all__ = [  # noqa: RUF022
     "SX",
     "add",
     "add_inplace_right",
+    "canonical_add",
+    "canonical_add_constant",
     "apply",
     "exponentiation_with_depth_constraint",
     "multiply",
@@ -123,9 +129,7 @@ __all__ = [  # noqa: RUF022
     "free",
     "drop",
     "inplace_prepare_amplitudes",
-    "inplace_prepare_amplitudes_approx",
     "inplace_prepare_state",
-    "inplace_prepare_state_approx",
     "integer_xor",
     "modular_add",
     "modular_add_constant",
@@ -133,9 +137,7 @@ __all__ = [  # noqa: RUF022
     "parametric_suzuki_trotter",
     "permute",
     "prepare_amplitudes",
-    "prepare_amplitudes_approx",
     "prepare_state",
-    "prepare_state_approx",
     "qdrift",
     "randomized_benchmarking",
     "real_xor_constant",
@@ -144,6 +146,7 @@ __all__ = [  # noqa: RUF022
     "suzuki_trotter",
     "unitary",
     "RESET",
+    "select_rotation",
 ]
 BUILTIN_FUNCTION_DECLARATIONS = {
     func_decl.name: func_decl for func_decl in STD_QMOD_OPERATORS + CORE_LIB_DECLS

classiq/qmod/builtins/functions/allocation.py

@@ -144,39 +144,3 @@ def inplace_prepare_amplitudes(
 
     """
     pass
-
-
-@qfunc(external=True)
-def inplace_prepare_amplitudes_approx(
-    amplitudes: CArray[CReal],
-    bound: CReal,
-    target: QArray[QBit, Literal["log(amplitudes.len, 2)"]],
-) -> None:
-    pass
-
-
-@qfunc(external=True)
-def prepare_amplitudes_approx(
-    amplitudes: CArray[CReal],
-    bound: CReal,
-    out: Output[QArray[QBit, Literal["log(amplitudes.len, 2)"]]],
-) -> None:
-    pass
-
-
-@qfunc(external=True)
-def inplace_prepare_state_approx(
-    probabilities: CArray[CReal],
-    bound: CReal,
-    target: QArray[QBit, Literal["log(probabilities.len, 2)"]],
-) -> None:
-    pass
-
-
-@qfunc(external=True)
-def prepare_state_approx(
-    probabilities: CArray[CReal],
-    bound: CReal,
-    out: Output[QArray[QBit, Literal["log(probabilities.len, 2)"]]],
-) -> None:
-    pass

classiq/qmod/builtins/functions/arithmetic.py

@@ -66,6 +66,58 @@ def add_inplace_right(
     pass
 
 
+@qperm(external=True)
+def canonical_add(
+    left: Const[QArray],
+    extend_left: CBool,
+    right: QArray,
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Adds two quantum variables representing integers (signed or unsigned), storing the
+    result in the second variable (in-place):
+
+    $$
+        \\left|\\text{left}\\right\\rangle \\left|\\text{right}\\right\\rangle
+        \\mapsto
+        \\left|\\text{left}\\right\\rangle \\left|\\left(\\text{right} +
+        \\text{left}\\right) \\bmod 2^{\\text{right.size}} \\right\\rangle
+    $$
+
+    Args:
+        left: The out-of-place argument for the addition.
+        extend_left: Whether to sign-extend the left argument.
+        right: The in-place argument for the addition, holds the final result.
+    """
+    pass
+
+
+@qperm(external=True)
+def canonical_add_constant(
+    left: CInt,
+    right: QArray,
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Adds an integer constant to a quantum variable representing an integer (signed or
+    unsigned):
+
+    $$
+        \\left|\\text{right}\\right\\rangle
+        \\mapsto
+        \\left|\\left(\\text{right} +
+        \\text{left}\\right) \\bmod 2^{\\text{right.size}} \\right\\rangle
+    $$
+
+    Args:
+        left: The constant argument for the addition.
+        right: The quantum argument for the addition, holds the final result.
+    """
+    pass
+
+
 @qperm(external=True)
 def modular_add(left: Const[QArray[QBit]], right: QArray[QBit]) -> None:
     pass

classiq/qmod/builtins/functions/gray_code.py

@@ -0,0 +1,23 @@
+from classiq.qmod.builtins.enums import Pauli
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CArray, CReal
+from classiq.qmod.qmod_variable import QBit, QNum
+
+
+@qfunc(external=True)
+def select_rotation(
+    basis: Pauli, angles: CArray[CReal], selector: QNum, target: QBit
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Applies a set of controlled single-qubit rotations to a target qubit, using
+    a specified rotation axis and a list of rotation angles.
+
+    Args:
+        basis: The Pauli operator defining the rotation axis.
+        angles: The list of rotation angles in radians. The list must have length 2**selector.size.
+        selector: The qubits that act as the selection register.
+        target: The qubit on which the selected rotation is applied.
+    """
+    pass

classiq/qmod/builtins/functions/mcx_func.py

@@ -5,3 +5,13 @@ from classiq.qmod.qmod_variable import Const, QArray, QBit
 @qperm(external=True)
 def mcx(ctrl: Const[QArray[QBit]], target: QBit) -> None:
     pass
+
+
+@qperm(external=True)
+def mcx_gray_code(ctrl: Const[QArray[QBit]], target: QBit) -> None:
+    pass
+
+
+@qperm(external=True)
+def mcx_hybrid_rec(ctrl: Const[QArray[QBit]], target: QBit, aux: QArray[QBit]) -> None:
+    pass

classiq/qmod/builtins/structs.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, fields, is_dataclass
-from typing import Union
+from typing import Any, Union
 
 from classiq.interface.exceptions import ClassiqValueError
 from classiq.interface.generator.types.struct_declaration import StructDeclaration
@@ -117,13 +117,21 @@ class SparsePauliOp:
     def __rmul__(self, obj: Union[float, "SparsePauliOp"]) -> "SparsePauliOp":
         return self.__mul__(obj)
 
-    def __add__(self, other: "SparsePauliOp") -> "SparsePauliOp":
+    def __add__(self, other: Any) -> "SparsePauliOp":
+        if not isinstance(other, SparsePauliOp):
+            raise ClassiqValueError(
+                f"Cannot add an object of type {type(other).__name__} to SparsePauliOp"
+            )
         return SparsePauliOp(
             terms=LenList(self.terms + other.terms),
             num_qubits=max(self.num_qubits, other.num_qubits),
         )
 
-    def __sub__(self, other: "SparsePauliOp") -> "SparsePauliOp":
+    def __sub__(self, other: Any) -> "SparsePauliOp":
+        if not isinstance(other, SparsePauliOp):
+            raise ClassiqValueError(
+                f"Cannot substruct an object of type {type(other).__name__} to SparsePauliOp"
+            )
         return self + -1.0 * other
 
     def __str__(self) -> str:
@@ -136,6 +144,17 @@ class SparsePauliOp:
             for term in self.terms
         )
 
+    def __truediv__(self, other: Any) -> "SparsePauliOp":
+        if not isinstance(other, (int, float)):
+            raise ClassiqValueError(
+                f"Cannot divide SparsePauliOp by object of type {type(other).__name__}"
+            )
+        if other == 0:
+            raise ClassiqValueError("Cannot divide by zero")
+        return SparsePauliOp(terms=self.terms, num_qubits=self.num_qubits) * float(
+            1 / other
+        )
+
 
 @dataclass
 class CombinatorialOptimizationSolution: