classiq 0.93.0__py3-none-any.whl → 0.100.0__py3-none-any.whl

classiq/open_library/functions/encodings.py

@@ -0,0 +1,182 @@
+from typing import Literal
+
+import numpy as np
+
+from classiq.qmod.builtins.functions.allocation import free
+from classiq.qmod.builtins.functions.standard_gates import CX, SWAP, X
+from classiq.qmod.builtins.operations import allocate, bind, control, invert, repeat
+from classiq.qmod.qfunc import qperm
+from classiq.qmod.qmod_variable import Input, Output, QArray, QBit, QNum
+
+
+def get_rewire_list(qvars: list[QBit]) -> list[QBit]:
+    rewire_list = qvars[int(np.log2(len(qvars))) :]
+    for i, qvar in enumerate(qvars[: int(np.log2(len(qvars)))]):
+        rewire_list.insert(2 ** (i + 1) - 1, qvar)
+    return rewire_list
+
+
+@qperm
+def inplace_binary_to_one_hot(qvar: QArray) -> None:
+    """
+    Inplace conversion of binary encoded value to one-hot encoding.
+    The implementation is based on https://quantumcomputing.stackexchange.com/questions/5526/garbage-free-reversible-binary-to-unary-decoder-construction.
+    The input is assumed to be of size 2^n, where n is the number of bits in the binary representation.
+    For example, the state |01000>=|2> will be converted to |00100> (one-hot for 2).
+
+    Args:
+        qvar: binary input array padded with 0's to be converted to one-hot encoding.
+    """
+    temp_qvars = [QBit(f"x{i}") for i in range(qvar.len)]
+    bind(qvar, temp_qvars)  # type: ignore[arg-type]
+    bind(get_rewire_list(temp_qvars), qvar)  # type: ignore[arg-type]
+
+    # logic
+    X(qvar[0])
+    for i in range(int(np.log2(qvar.len))):
+        index = 2 ** (i + 1) - 1
+        for j in range(2**i - 1):
+            control(qvar[index], lambda i=i, j=j: SWAP(qvar[j], qvar[j + 2**i]))  # type: ignore[misc]
+        for j in range(2**i - 1):
+            CX(qvar[j + 2**i], qvar[index])
+
+        CX(qvar[index], qvar[index - 2**i])
+
+
+@qperm
+def inplace_one_hot_to_unary(qvar: QArray) -> None:
+    """
+    Inplace conversion of one-hot encoded value to unary encoding.
+    The input is assumed to be of size n, where n is the number of bits in the one-hot representation.
+    The remaining unary representation will at the higher n-1 bits, where the lsb is cleared to 0.
+    For example, the state |0010> (one-hot for 2) will be converted to |0>|110> (unary for 2).
+
+    Args:
+        qvar: one-hot input array to be converted to unary encoding.
+    """
+    # fill with 1s after the leading 1 bit
+    repeat(qvar.len - 1, lambda i: CX(qvar[qvar.len - i - 1], qvar[qvar.len - i - 2]))
+    # clear the 0 bit, to be excluded from the unary encoding
+    X(qvar[0])
+
+
+@qperm
+def one_hot_to_unary(one_hot: Input[QArray], unary: Output[QArray]) -> None:
+    """
+    Conversion of one-hot encoded value to unary encoding. The output `unary` variable
+    is smaller in 1 qubit than the input `one_hot` variable.
+    For example, the state |0010> (one-hot for 2) will be converted to |110> (unary for 2).
+
+    Args:
+        one_hot: one-hot input array to be converted to unary encoding.
+        unary: unary output array.
+    """
+    inplace_one_hot_to_unary(one_hot)
+    lsb: QBit = QBit()
+    bind(one_hot, [lsb, unary])
+    free(lsb)
+
+
+@qperm
+def one_hot_to_binary(
+    one_hot: Input[QArray],
+    binary: Output[QNum[Literal["ceiling(log(one_hot.len, 2))"]]],
+) -> None:
+    """
+    Conversion of one-hot encoded value to binary encoding. The output `binary` variable
+    is of size log2(one_hot.size) rounded up.
+    For example, the state |0010> (one-hot for 2) will be converted to |01>=|2>.
+
+    Args:
+        one_hot: one-hot input array to be converted to binary encoding.
+        binary: binary output variable.
+    """
+    extension: QArray = QArray()
+    invert(lambda: inplace_binary_to_one_hot(one_hot))
+    bind(one_hot, [binary, extension])
+    free(extension)
+
+
+@qperm
+def unary_to_binary(unary: Input[QArray], binary: Output[QNum]) -> None:
+    """
+    Conversion of unary encoded value to binary encoding.  The output `binary` variable
+    is of size log2(unary.size + 1) rounded up.
+    For example, the state |110> (unary for 2) will be converted to |01>=|2>.
+
+    Args:
+        unary: unary input array to be converted to binary encoding.
+        binary: binary output variable.
+    """
+    one_hot: QArray = QArray()
+    unary_to_one_hot(unary, one_hot)
+    one_hot_to_binary(one_hot, binary)
+
+
+@qperm
+def unary_to_one_hot(unary: Input[QArray], one_hot: Output[QArray]) -> None:
+    """
+    Conversion of unary encoded value to one-hot encoding. The output `one_hot` variable
+    is larger in 1 qubit than the input `unary` variable.
+    For example, the state |110> (unary for 2) will be converted to |0010> (one-hot for 2).
+
+    Args:
+        unary: unary input array to be converted to one-hot encoding.
+        one_hot: one-hot output array.
+    """
+    lsb: QBit = QBit()
+    allocate(lsb)
+    bind([lsb, unary], one_hot)
+    invert(lambda: inplace_one_hot_to_unary(one_hot))
+
+
+@qperm
+def binary_to_one_hot(binary: Input[QNum], one_hot: Output[QArray]) -> None:
+    """
+    Conversion of binary encoded value to one-hot encoding. The output `one_hot` variable
+    is of size 2^n, where n is the number of bits in the binary representation.
+    For example, the state |01>=|2> will be converted to |0010> (one-hot for 2).
+
+    Args:
+        binary: binary input variable to be converted to one-hot encoding.
+        one_hot: one-hot output array.
+    """
+    extension: QArray = QArray()
+    allocate(2**binary.size - binary.size, extension)
+    bind([binary, extension], one_hot)
+
+    inplace_binary_to_one_hot(one_hot)
+
+
+@qperm
+def binary_to_unary(binary: Input[QNum], unary: Output[QArray]) -> None:
+    """
+    Conversion of binary encoded value to unary encoding. The output `unary` variable
+    is of size 2^n - 1, where n is the number of bits in the binary representation.
+    For example, the state |01>=|2> will be converted to |110> (unary for 2).
+
+    Args:
+        binary: binary input variable to be converted to unary encoding.
+        unary: unary output array.
+    """
+    one_hot: QArray = QArray()
+    binary_to_one_hot(binary, one_hot)
+    one_hot_to_unary(one_hot, unary)
+
+
+@qperm
+def pad_zeros(total_size: int, qvar: Input[QArray], padded: Output[QArray]) -> None:
+    """
+    Pad the input qvar with additional qubits at the end to reach the total_size.
+
+    Args:
+        total_size: The desired total size after padding.
+        qvar: The input quantum array to be padded.
+        padded: The output quantum array after padding.
+    """
+    extension: QArray = QArray()
+    allocate(total_size - qvar.len, extension)
+    bind([qvar, extension], padded)
+
+
+# TODO: when the functions can have default arguments, add `pad` function with direction and value

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:
     """