classiq 0.92.0__py3-none-any.whl → 0.99.0__py3-none-any.whl

classiq/open_library/functions/amplitude_loading.py

@@ -0,0 +1,81 @@
+from typing import cast
+
+import numpy as np
+from sympy import fwht
+
+from classiq.interface.exceptions import ClassiqValueError
+
+from classiq.qmod.builtins.functions import CX, RY
+from classiq.qmod.builtins.operations import skip_control
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import Const, QArray, QBit
+
+
+def _get_graycode(size: int, i: int) -> int:
+    if i == 2**size:
+        return _get_graycode(size, 0)
+    return i ^ (i >> 1)
+
+
+def _get_graycode_angles_wh(size: int, angles: list[float]) -> list[float]:
+    transformed_angles = fwht(np.array(angles) / 2**size)
+    return [transformed_angles[_get_graycode(size, j)] for j in range(2**size)]
+
+
+def _get_graycode_ctrls(size: int) -> list[int]:
+    return [
+        (_get_graycode(size, i) ^ _get_graycode(size, i + 1)).bit_length() - 1
+        for i in range(2**size)
+    ]
+
+
+@qfunc
+def assign_amplitude_table(
+    amplitudes: list[float], index: Const[QArray], indicator: QBit
+) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Load a specified list of real amplitudes into a quantum variable using an extra indicator qubit:
+    \\( |i\\rangle|0\\rangle \\rightarrow a(i)\\ |i\\rangle|1\\rangle + \\sqrt{1 - a(i)^2}\\ |i\\rangle|0\\rangle \\).
+    Here, \\(a(i)\\) is the i-th amplitude, determined by the QNum when the index is in state \\(i\\).
+    A list extracted from a given classical function \\(f(x)\\), with indexing according to a given QNum, can be obtained via the utility SDK function `lookup_table`.
+    This function expects the indicator qubit to be initialized to \\(|0\\rangle\\).
+
+    Args:
+        amplitudes: Real values for the amplitudes. Must be between -1 and 1
+        index: The quantum variable used for amplitude indexing
+        indicator: The quantum indicator qubit
+
+    Example:
+        ```python
+        from classiq import *
+
+
+        @qfunc
+        def main(x: Output[QNum[5, UNSIGNED, 5]], ind: Output[QBit]) -> None:
+            allocate(x)
+            hadamard_transform(x)
+            allocate(ind)
+
+            assign_amplitude_table(lookup_table(lambda x: x**2, x), x, ind)
+        ```
+    """
+    size = index.len
+    if len(amplitudes) != 2**size:
+        raise ClassiqValueError(
+            f"The number of amplitudes must be 2**index.size={2 ** size}, got "
+            f"{len(amplitudes)}"
+        )
+    if not all(-1 <= amp <= 1 for amp in amplitudes):
+        raise ClassiqValueError("All amplitudes must be between -1 and 1")
+
+    angles_to_load = cast(list[float], 2 * np.arcsin(amplitudes))
+    transformed_angles = _get_graycode_angles_wh(size, angles_to_load)
+    controllers = _get_graycode_ctrls(size)
+
+    for k in range(2**size):
+        RY(transformed_angles[k], indicator)
+        skip_control(
+            lambda k=k: CX(index[controllers[k]], indicator)  # type:ignore[misc]
+        )

classiq/open_library/functions/discrete_sine_cosine_transform.py

@@ -10,9 +10,10 @@ from classiq.qmod.builtins.operations import (
     repeat,
     within_apply,
 )
-from classiq.qmod.qfunc import qfunc
-from classiq.qmod.qmod_variable import Const, Permutable, QArray, QBit, QNum
+from classiq.qmod.qfunc import qfunc, qperm
+from classiq.qmod.qmod_variable import Const, QArray, QBit, QNum
 from classiq.qmod.symbolic import pi
+from classiq.qmod.utilities import suppress_return_value
 
 
 def _b_operator(q: QBit) -> None:
@@ -26,8 +27,8 @@ def _qct_d_operator(x: Const[QNum], q: QBit) -> None:
     control(x == 0, lambda: invert(lambda: _b_operator(q)))
 
 
-@qfunc
-def _qct_pi_operator(x: Permutable[QArray[QBit]], q: Const[QBit]) -> None:
+@qperm
+def _qct_pi_operator(x: QNum, q: Const[QBit]) -> None:
     control(
         q == 1,
         lambda: [
@@ -65,8 +66,8 @@ def _d1_operator(x: QArray[QBit], q: QBit) -> None:
     PHASE(-omega_exp, q)
 
 
-def _pi2_operator(x: QArray[QBit], q: QBit) -> None:
-    control(q == 1, lambda: inplace_add(1, x))  # type:ignore[arg-type]
+def _pi2_operator(x: QNum, q: QBit) -> None:
+    control(q == 1, lambda: inplace_add(1, x)),  # type:ignore[arg-type]
 
 
 def _j_operator(q: QBit) -> None:
@@ -78,19 +79,23 @@ def _b_t_operator(q: QBit) -> None:
     S(q)
 
 
-def _d0dt_operator(x: QArray, q: QBit) -> None:
-    x_num: QNum = QNum(size=x.len)
-    bind(x, x_num)
+@suppress_return_value
+def _d0dt_operator(x: QNum, q: QBit) -> None:
     _b_t_operator(q)
-    control(x_num == 0, lambda: _j_operator(q))
-    bind(x_num, x)
+    control(x == 0, lambda: _j_operator(q))
 
 
 def _un_dag_operator(x: QArray[QBit], q: QBit) -> None:
     _d1_operator(x, q)
     invert(lambda: _qct_pi_operator(x, q))
-    _d0dt_operator(x, q)
-    invert(lambda: _pi2_operator(x, q))
+    x_num: QNum = QNum(size=x.len)
+    within_apply(
+        lambda: bind(x, x_num),
+        lambda: [
+            _d0dt_operator(x_num, q),
+            invert(lambda: _pi2_operator(x_num, q)),
+        ],
+    )
 
 
 @qfunc
@@ -120,7 +125,7 @@ def qct_qst_type1(x: QArray[QBit]) -> None:
     within_apply(lambda: _t_operator(x), lambda: qft(x))
 
 
-@qfunc(unchecked=["q"])
+@qfunc(disable_const_checks=["q"])
 def qct_qst_type2(x: QArray[QBit], q: Const[QBit]) -> None:
     """
     [Qmod Classiq-library function]

classiq/open_library/functions/grover.py

@@ -8,23 +8,21 @@ from classiq.qmod.builtins.operations import (
     power,
     within_apply,
 )
-from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qfunc import qfunc, qperm
 from classiq.qmod.qmod_parameter import CInt
-from classiq.qmod.qmod_variable import Const, Permutable, QArray, QBit, QNum
-from classiq.qmod.quantum_callable import QCallable
+from classiq.qmod.qmod_variable import Const, QArray, QBit, QNum
+from classiq.qmod.quantum_callable import QCallable, QPerm
 from classiq.qmod.symbolic import pi
 
 
-@qfunc(unchecked=["target"])
-def _cond_phase_flip(
-    predicate: QCallable[Permutable[QBit]], target: Const[QBit]
-) -> None:
+@qperm(disable_perm_check=True, disable_const_checks=["target"])
+def _cond_phase_flip(predicate: QPerm[QBit], target: Const[QBit]) -> None:
     within_apply(lambda: H(target), lambda: predicate(target))
 
 
-@qfunc
+@qperm
 def phase_oracle(
-    predicate: QCallable[Const[QArray[QBit]], Permutable[QBit]],
+    predicate: QPerm[Const[QArray[QBit]], QBit],
     target: Const[QArray[QBit]],
 ) -> None:
     """
@@ -55,7 +53,7 @@ def phase_oracle(
     )
 
 
-@qfunc(unchecked=["packed_vars"])
+@qperm(disable_perm_check=True, disable_const_checks=["packed_vars"])
 def reflect_about_zero(packed_vars: Const[QArray[QBit]]) -> None:
     """
     [Qmod Classiq-library function]

classiq/open_library/functions/lcu.py

@@ -9,6 +9,7 @@ from classiq.open_library.functions.utility_functions import switch
 from classiq.qmod.builtins.functions import IDENTITY, X, Y, Z, inplace_prepare_state
 from classiq.qmod.builtins.operations import (
     control,
+    if_,
     repeat,
     within_apply,
 )
@@ -16,7 +17,7 @@ from classiq.qmod.builtins.structs import IndexedPauli, SparsePauliOp
 from classiq.qmod.cparam import CArray
 from classiq.qmod.qfunc import qfunc
 from classiq.qmod.qmod_variable import QArray, QBit, QNum
-from classiq.qmod.quantum_callable import QCallableList
+from classiq.qmod.quantum_callable import QCallable, QCallableList
 
 
 @qfunc
@@ -36,27 +37,23 @@ def apply_pauli_term(pauli_string: CArray[IndexedPauli], x: QArray[QBit]) -> Non
 
 
 @qfunc
-def lcu(
+def prepare_select(
     coefficients: list[float],
-    unitaries: QCallableList,
+    select: QCallable[QNum],
     block: QNum[Literal["max(ceiling(log(coefficients.len, 2)), 1)"]],
 ) -> None:
     """
     [Qmod Classiq-library function]
 
-    Implements a general linear combination of unitaries (LCU) procedure. The algorithm prepares a superposition
-    over the `unitaries` according to `magnitudes`, and then conditionally applies each unitary controlled by the `block`.
-
-    The operation is of the form:
-
-    $$\\sum_j \\alpha_j U_j$$
-
-    where $U_j$ is a unitary operation applied to `data`.
+    Applies the 'Prepare-Select' scheme used for Linear Combination of Unitaries (LCU).
+    Compared to the `lcu` function, here the Select operator should be provided directly, allowing to take advantage of some structure for
+    the unitaries of the LCU.
+    The select operator is defined by: $\\mathrm{SELECT} = \\sum_{j=0}^{m-1} |j\rangle\\!\\langle j|_{block} \\otimes U_j$.
 
     Args:
         coefficients: L1-normalized array of  $\\{ \\alpha_j \\}$ of the LCU coefficients.
-        unitaries: A list of quantum callable functions to be applied conditionally.
-        block: Quantum variable that holds the superposition index used for conditional application of each unitary.
+        select: A quantum callable to be applied between the state preparation and its inverse. Its input is the `block` variable, labeling the index of the unitaries in the LCU.
+        block: A Quantum variable that holds the index used as input for the 'select' operator.
     """
     coefficients = coefficients + [0] * (
         2**block.size - len(coefficients)  # type:ignore[operator]
@@ -68,16 +65,48 @@ def lcu(
     within_apply(
         lambda: inplace_prepare_state(magnitudes, 0, block),
         lambda: [
-            repeat(
-                count=unitaries.len,
-                iteration=lambda i: control(block == i, lambda: unitaries[i]()),
+            select(block),
+            if_(
+                not np.allclose(np.array(phases) % (2 * np.pi), 0),
+                lambda: apply_phase_table(phases, block),
             ),
-            # TODO: replace to sparse constant phase
-            apply_phase_table(phases, block),
         ],
     )
 
 
+@qfunc
+def lcu(
+    coefficients: list[float],
+    unitaries: QCallableList,
+    block: QNum[Literal["max(ceiling(log(coefficients.len, 2)), 1)"]],
+) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Implements a general linear combination of unitaries (LCU) procedure. The algorithm prepares a superposition
+    over the `unitaries` according to the given `coefficients`, and then conditionally applies each unitary controlled by the `block`.
+
+    The operation is of the form:
+
+    $$\\sum_j \\alpha_j U_j$$
+
+    where $U_j$ is a unitary operation applied to `data`.
+
+    Args:
+        coefficients: L1-normalized array of  $\\{ \\alpha_j \\}$ of the LCU coefficients.
+        unitaries: A list of quantum callable functions to be applied conditionally.
+        block: Quantum variable that holds the superposition index used for conditional application of each unitary.
+    """
+    prepare_select(
+        coefficients,
+        lambda _block: repeat(
+            count=unitaries.len,
+            iteration=lambda i: control(_block == i, lambda: unitaries[i]()),
+        ),
+        block,
+    )
+
+
 @qfunc
 def lcu_pauli(
     operator: SparsePauliOp,

classiq/open_library/functions/modular_exponentiation.py

@@ -8,11 +8,12 @@ from classiq.qmod.builtins.operations import (
     control,
     invert,
     repeat,
+    skip_control,
     within_apply,
 )
 from classiq.qmod.cparam import CInt
-from classiq.qmod.qfunc import qfunc
-from classiq.qmod.qmod_variable import Const, Permutable, QArray, QBit
+from classiq.qmod.qfunc import qfunc, qperm
+from classiq.qmod.qmod_variable import Const, QArray, QBit
 from classiq.qmod.symbolic import min, mod_inverse
 
 
@@ -51,9 +52,9 @@ def qft_space_add_const(value: CInt, phi_b: QArray[QBit]) -> None:
     )
 
 
-@qfunc(unchecked=["phi_b"])
+@qperm(disable_perm_check=True)
 def cc_modular_add(
-    n: CInt, a: CInt, phi_b: Permutable[QArray[QBit]], c1: Const[QBit], c2: Const[QBit]
+    n: CInt, a: CInt, phi_b: QArray[QBit], c1: Const[QBit], c2: Const[QBit]
 ) -> None:
     """
     [Qmod Classiq-library function]
@@ -91,11 +92,11 @@ def cc_modular_add(
     free(aux)
 
 
-@qfunc(unchecked=["b"])
+@qperm(disable_perm_check=True)
 def c_modular_multiply(
     n: CInt,
     a: CInt,
-    b: Permutable[QArray[QBit]],
+    b: QArray[QBit],
     x: Const[QArray[QBit]],
     ctrl: Const[QBit],
 ) -> None:
@@ -123,8 +124,8 @@ def c_modular_multiply(
     )
 
 
-@qfunc
-def multiswap(x: Permutable[QArray[QBit]], y: Permutable[QArray[QBit]]) -> None:
+@qperm
+def multiswap(x: QArray[QBit], y: QArray[QBit]) -> None:
     """
     [Qmod Classiq-library function]
 
@@ -164,6 +165,90 @@ def inplace_c_modular_multiply(n: CInt, a: CInt, x: QArray[QBit], ctrl: QBit) ->
     free(b)
 
 
+@qperm(disable_perm_check=True)
+def modular_add_qft_space(n: CInt, a: CInt, phi_b: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Adds a constant `a` to a quantum number `phi_b` modulo the constant `n`.
+    The quantum number `phi_b` is assumed to be in the QFT space.
+
+    Args:
+        n: The modulo number.
+        a: The constant to add to the quantum number.
+        phi_b: The quantum number to which the constant is added.
+
+    """
+    aux = QBit()
+
+    allocate(aux)
+    qft_space_add_const(a, phi_b),
+    skip_control(
+        lambda: (
+            invert(lambda: qft_space_add_const(n, phi_b)),
+            _check_msb(1, phi_b, aux),
+            control(aux, lambda: qft_space_add_const(n, phi_b)),
+        )
+    )
+    invert(lambda: qft_space_add_const(a, phi_b))
+    skip_control(lambda: _check_msb(0, phi_b, aux))
+    qft_space_add_const(a, phi_b)
+    free(aux)
+
+
+@qperm(disable_perm_check=True)
+def modular_multiply(
+    n: CInt,
+    a: CInt,
+    b: QArray[QBit],
+    x: Const[QArray[QBit]],
+) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Performs out-of-place multiplication of a quantum number `x` by a classical number `a` modulo classical number `n`,
+    and adds the result to a quantum array `b` (Applies $b += xa \\mod n$).
+
+    Args:
+        n: The modulo number. Should be non-negative.
+        a: The classical factor. Should be non-negative.
+        b: The quantum number added to the multiplication result. Stores the result of the multiplication.
+        x: The quantum factor.
+    """
+    within_apply(
+        lambda: qft(b),
+        lambda: repeat(
+            count=x.len,
+            iteration=lambda index: control(
+                x[index], lambda: modular_add_qft_space(n, (a * (2**index)) % n, b)
+            ),
+        ),
+    )
+
+
+@qfunc
+def inplace_modular_multiply(n: CInt, a: CInt, x: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Performs multiplication of a quantum number `x` by a classical number `a` modulo classical number `n`
+    (Applies $x=xa \\mod n$).
+
+    Args:
+        n: The modulo number. Should be non-negative.
+        a: The classical factor. Should be non-negative.
+        x: The quantum factor.
+
+    Comment: It is assumed that `a` has an inverse modulo `n`
+    """
+    b: QArray[QBit] = QArray(length=x.len + 1)
+    allocate(b)
+    modular_multiply(n, a, b, x)
+    multiswap(x, b)
+    invert(lambda: modular_multiply(n, mod_inverse(a, n), b, x))
+    free(b)
+
+
 @qfunc
 def modular_exp(n: CInt, a: CInt, x: QArray[QBit], power: QArray[QBit]) -> None:
     """