classiq 0.38.0__py3-none-any.whl → 0.65.4__py3-none-any.whl

classiq/open_library/functions/state_preparation.py

@@ -0,0 +1,301 @@
+import warnings
+from typing import Literal
+
+from classiq.interface.exceptions import ClassiqDeprecationWarning
+
+from classiq.open_library.functions.utility_functions import (
+    hadamard_transform,
+    modular_increment,
+)
+from classiq.qmod.builtins.functions.standard_gates import CX, IDENTITY, RY, H, X
+from classiq.qmod.builtins.operations import allocate, control, if_, repeat
+from classiq.qmod.cparam import CBool, CInt
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import Output, QArray, QBit, QNum
+from classiq.qmod.symbolic import (
+    asin,
+    atan,
+    exp,
+    floor,
+    log,
+    logical_or,
+    max as qmax,
+    min as qmin,
+    pi,
+    sqrt,
+)
+
+
+@qfunc
+def allocate_num(
+    num_qubits: CInt,
+    is_signed: CBool,
+    fraction_digits: CInt,
+    out: Output[
+        QNum[Literal["num_qubits"], Literal["is_signed"], Literal["fraction_digits"]]
+    ],
+) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum number with the given number of qubits, sign, and fractional digits.
+
+    Args:
+        num_qubits: The number of qubits to allocate.
+        is_signed: Whether the number is signed or unsigned.
+        fraction_digits: The number of fractional digits.
+    """
+    allocate(num_qubits, out)
+
+
+def prepare_uniform_trimmed_state_apply_rotation(
+    size_lsb: CInt, lsbs_val: CInt, rotation_var: QBit
+) -> None:
+    # max hold for the case where the value is on the left side
+    # the fraction in the sqrt is the wanted amount of probability
+    # in the left side divided by the total amount
+    RY(
+        -2 * (asin(sqrt(qmin((2 ** (size_lsb)) / lsbs_val, 1))) + pi / 4) + pi,
+        rotation_var,
+    )
+
+
+@qfunc
+def _prepare_uniform_trimmed_state_step(
+    size_lsb: CInt, ctrl_val: CInt, lsbs_val: CInt, ctrl_var: QNum, rotation_var: QBit
+) -> None:
+    if_(
+        lsbs_val != 0,  # stop condition
+        lambda: control(
+            ctrl_var == ctrl_val,
+            lambda: prepare_uniform_trimmed_state_apply_rotation(
+                size_lsb, lsbs_val, rotation_var
+            ),
+        ),
+    )
+
+
+@qfunc
+def prepare_uniform_trimmed_state(m: CInt, q: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable in a uniform superposition of the first `m` computational basis states:
+
+    $$
+        \\left|\\text{q}\\right\\rangle = \\frac{1}{\\sqrt{m}}\\sum_{i=0}^{m-1}{|i\\rangle}
+    $$
+
+    The number of allocated qubits would be $\\left\\lceil\\log_2{m}\\right\\rceil$.
+    The function is especially useful when `m` is not a power of 2.
+
+    Args:
+        m: The number of states to load in the superposition.
+        q: The quantum variable that will receive the initialized state. Must be uninitialized.
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+    """
+    hadamard_transform(q)
+
+    if_(
+        m < 2**q.len,
+        # initial step without control
+        lambda: prepare_uniform_trimmed_state_apply_rotation(
+            q.len - 1,  # type:ignore[arg-type]
+            m,
+            q[q.len - 1],
+        ),
+    )
+
+    repeat(
+        qmax(q.len - 1, 0),
+        lambda i: _prepare_uniform_trimmed_state_step(
+            q.len - i - 2,
+            floor(m / (2 ** (q.len - i - 1))),
+            m % (2 ** (q.len - i - 1)),
+            q[q.len - i - 1 : q.len],
+            q[q.len - i - 2],
+        ),
+    )
+
+
+@qfunc
+def prepare_uniform_interval_state(start: CInt, end: CInt, q: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable in a uniform superposition of the specified interval in the computational basis states:
+
+    $$
+        \\left|\\text{q}\\right\\rangle = \\frac{1}{\\sqrt{\\text{end} - \\text{start}}}\\sum_{i=\\text{start}}^{\\text{end}-1}{|i\\rangle}
+    $$
+
+    The number of allocated qubits would be $\\left\\lceil\\log_2{\\left(\\text{end}\\right)}\\right\\rceil$.
+
+    Args:
+        start: The lower bound of the interval to load (inclusive).
+        end: The upper bound of the interval to load (exclusive).
+        q: The quantum variable that will receive the initialized state. Must be uninitialized.
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+    """
+    prepare_uniform_trimmed_state(end - start, q)
+    modular_increment(start, q)
+
+
+@qfunc
+def prepare_ghz_state(size: CInt, q: Output[QArray[QBit]]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable in a Greenberger-Horne-Zeilinger (GHZ) state. i.e., a balanced superposition of all ones and all zeros, on an arbitrary number of qubits..
+
+    Args:
+        size: The number of qubits in the GHZ state. Must be a positive integer.
+        q: The quantum variable that will receive the initialized state. Must be uninitialized.
+
+    Notes:
+        The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+
+    """
+
+    def inner_lop(step: CInt) -> None:
+        repeat(
+            count=2**step,
+            iteration=lambda control_index: if_(
+                condition=control_index + 2**step >= size,
+                then=lambda: IDENTITY(q[0]),
+                else_=lambda: CX(q[control_index], q[control_index + 2**step]),
+            ),
+        )
+
+    allocate(size, q)
+    H(q[0])
+    repeat(floor(log(size - 1, 2)) + 1, inner_lop)  # type:ignore[arg-type]
+
+
+@qfunc
+def prepare_exponential_state(rate: CInt, q: QArray[QBit]) -> None:
+    """
+
+    [Qmod Classiq-library function]
+
+    Prepares a quantum state with exponentially decreasing amplitudes. The state is prepared in the computational basis, with the amplitudes of the states decreasing exponentially with the index of the state:
+
+    $$
+        P(n) = \\frac{1}{Z} e^{- \\text{rate} \\cdot n}
+    $$
+
+    Args:
+        rate: The rate of the exponential decay.
+        q: The quantum register to prepare.
+    """
+    repeat(q.len, lambda i: RY(2.0 * atan(exp((-rate * 2.0**i) / 2.0)), q[i]))
+
+
+@qfunc
+def prepare_bell_state(state_num: CInt, q: Output[QArray[QBit, Literal[2]]]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum array of size 2 in one of the four Bell states.
+
+    Args:
+        state_num: The number of the Bell state to be prepared. Must be an integer between 0 and 3.
+        q: The quantum variable that will receive the initialized state. Must be uninitialized.
+
+    Bell States:
+        The four Bell states are defined as follows (each state correlates to an integer between 0 and 3 as defined by the `state_num` argument):
+
+        If `state_num` = 0 the function prepares the Bell state:
+
+        $$
+            \\left|\\Phi^+\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 00 \\right\\rangle + \\left| 11 \\right\\rangle \\right)
+        $$
+
+        If `state_num` = 1 the function prepares the Bell state:
+
+        $$
+            \\left|\\Phi^-\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 00 \\right\\rangle - \\left| 11 \\right\\rangle \\right)
+        $$
+
+        If `state_num` = 2 the function prepares the Bell state:
+
+        $$
+            \\left|\\Psi^+\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 01 \\right\\rangle + \\left| 10 \\right\\rangle \\right)
+        $$
+
+        If `state_num` = 3 the function prepares the Bell state:
+
+        $$
+            \\left|\\Psi^-\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 01 \\right\\rangle - \\left| 10 \\right\\rangle \\right)
+        $$
+
+    Notes:
+        The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+
+    """
+    allocate(2, q)
+    if_(logical_or(state_num == 1, state_num == 3), lambda: X(q[0]))
+    if_(logical_or(state_num == 2, state_num == 3), lambda: X(q[1]))
+    H(q[0])
+    CX(q[0], q[1])
+
+
+@qfunc
+def inplace_prepare_int(value: CInt, target: QNum) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    This function is **deprecated**. Use in-place-xor assignment statement in the form _target-var_ **^=** _quantum-expression_ or **inplace_xor(**_quantum-expression_**,** _target-var_**)** instead.
+
+    Transitions a quantum variable in the zero state $|0\\rangle$ into the computational basis state $|\\text{value}\\rangle$.
+    In the general case, the function performs a bitwise-XOR, i.e. transitions the state $|\\psi\\rangle$ into $|\\psi \\oplus \\text{value}\\rangle$.
+
+    Args:
+        value: The value to assign to the quantum variable.
+        target: The quantum variable to act upon.
+
+    Note:
+        If the value cannot fit into the quantum variable, it is truncated, i.e. treated as the value modulo $2^\\text{target.size}$.
+    """
+    warnings.warn(
+        "Function 'inplace_prepare_int' is deprecated. Use in-place-xor assignment statement in the form '<var> ^= <expression>' or 'inplace_xor(<expression>, <var>)' instead.",
+        ClassiqDeprecationWarning,
+        stacklevel=1,
+    )
+    target ^= value
+
+
+@qfunc
+def prepare_int(
+    value: CInt,
+    out: Output[QNum[Literal["floor(log(value, 2)) + 1"]]],
+) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    This function is **deprecated**. Use assignment statement in the form _target-var_ **|=** _quantum-expression_ or **assign(**_quantum-expression_**,** _target-var_**)** instead.
+
+    Initializes a quantum variable to the computational basis state $|\\text{value}\\rangle$.
+    The number of allocated qubits is automatically computed from the value, and is the minimal number required for representation in the computational basis.
+
+    Args:
+        value: The value to assign to the quantum variable.
+        out: The allocated quantum variable. Must be uninitialized.
+
+    Note:
+        If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
+    """
+    warnings.warn(
+        "Function 'prepare_int' is deprecated. Use assignment statement in the form '<var> |= <expression>'  or 'assign(<expression>, <var>)' instead.",
+        ClassiqDeprecationWarning,
+        stacklevel=1,
+    )
+    out |= value

classiq/open_library/functions/swap_test.py

@@ -0,0 +1,27 @@
+from classiq.qmod.builtins.functions.standard_gates import SWAP, H
+from classiq.qmod.builtins.operations import allocate, control, repeat
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import Output, QArray, QBit
+
+
+@qfunc
+def swap_test(state1: QArray[QBit], state2: QArray[QBit], test: Output[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Tests the overlap (in terms of fidelity) of two quantum states.
+    The fidelity of `state1` and `state2` is calculated from the probability of measuring `test` qubit in the state 0 as follows:
+
+    $$
+        |\\langle state1 | state2 \\rangle |^2 = 2*Prob(test=0)-1
+    $$
+
+    Args:
+        state1: A quantum state to check its overlap with state2.
+        state2: A quantum state to check its overlap with state1.
+        test: A qubit for which the probability of measuring 0 is $0.5*(|\\langle state1 | state2 \\rangle |^2+1)$
+    """
+    allocate(1, test)
+    H(test)
+    control(test, lambda: repeat(state1.len, lambda i: SWAP(state1[i], state2[i])))
+    H(test)

classiq/open_library/functions/utility_functions.py

@@ -0,0 +1,81 @@
+from typing import Annotated
+
+from classiq.open_library.functions.qft_functions import qft
+from classiq.qmod.builtins.functions.standard_gates import PHASE, H
+from classiq.qmod.builtins.operations import bind, repeat, within_apply
+from classiq.qmod.cparam import CInt
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import QArray, QBit, QCallable, QNum
+from classiq.qmod.quantum_callable import QCallableList
+from classiq.qmod.symbolic import pi
+
+
+@qfunc
+def apply_to_all(
+    gate_operand: QCallable[Annotated[QBit, "target"]], target: QArray[QBit]
+) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Applies the single-qubit operand `gate_operand` to each qubit in the qubit
+    array `target`.
+
+    Args:
+        gate_operand: The single-qubit gate to apply to each qubit in the array.
+        target: The qubit array to apply the gate to.
+    """
+    repeat(target.len, lambda index: gate_operand(target[index]))
+
+
+@qfunc
+def hadamard_transform(target: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Applies Hadamard transform to the target qubits.
+
+    Corresponds to the braket notation:
+
+    $$
+     H^{\\otimes n} |x\rangle = \frac{1}{\\sqrt{2^n}} \\sum_{y=0}^{2^n - 1} (-1)^{x \\cdot y} |y\rangle
+    $$
+
+    Args:
+        target:  qubits to apply to Hadamard transform to.
+
+    """
+    apply_to_all(H, target)
+
+
+@qfunc
+def switch(selector: CInt, cases: QCallableList) -> None:
+    cases[selector]()
+
+
+@qfunc
+def modular_increment(a: CInt, x: QNum) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Adds $a$ to $x$ modulo the range of $x$, assumed that $x$ is a non-negative integer and $a$ is an integer.
+    Mathematically it is described as:
+
+    $$
+        x = (x+a)\\ \\mod \\ 2^{x.size}-1
+    $$
+
+    Args:
+        a: A classical integer to be added to x.
+        x: A quantum number that is assumed to be non-negative integer.
+
+    """
+    array_cast: QArray = QArray("array_cast")
+    within_apply(
+        lambda: (  # type:ignore[arg-type]
+            bind(x, array_cast),  # type:ignore[func-returns-value]
+            qft(array_cast),
+        ),
+        lambda: repeat(
+            x.size, lambda i: PHASE(a * 2 * pi * 2**i / (2**x.size), array_cast[i])
+        ),
+    )

classiq/open_library/functions/variational.py

@@ -0,0 +1,52 @@
+from classiq.qmod.builtins.functions.standard_gates import RX, RY, RZ
+from classiq.qmod.builtins.operations import allocate, repeat
+from classiq.qmod.cparam import CReal
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CArray
+from classiq.qmod.qmod_variable import Output, QArray, QBit
+from classiq.qmod.symbolic import ceiling, floor, pi
+
+
+@qfunc
+def encode_in_angle(data: CArray[CReal], qba: Output[QArray[QBit]]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Creates an angle encoding of n data points on n qubits.
+
+    Applies RY($\\pi$data[i]) on qba[i].
+
+    Args:
+        data: A classical array representing the data to encode.
+        qba: The array of qubits on which the data is encoded.
+    """
+    allocate(data.len, qba)
+    repeat(
+        count=data.len,
+        iteration=lambda index: RY(pi * data[index], qba[index]),
+    )
+
+
+@qfunc
+def encode_on_bloch(data: CArray[CReal], qba: Output[QArray]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Creates a dense angle encoding of n data points on n//2 qubits.
+
+    Encodes pairs of data points on a Bloch sphere, via RX($\\pi$data[2*i])RZ($\\pi$data[2*i+1]) on qba[i].
+    If the length of the data is odd then RX($\\pi$data[i]) is applied on the last qubit.
+
+    Args:
+        data: A classical array representing the data to encode.
+        qba: The QArray of QBits on which the data is encoded.
+    """
+    allocate(ceiling(data.len / 2), qba)
+    repeat(
+        count=ceiling(data.len / 2),
+        iteration=lambda index: RX(pi * data[2 * index], qba[index]),
+    )
+    repeat(
+        count=floor(data.len / 2),
+        iteration=lambda index: RZ(pi * data[2 * index + 1], qba[index]),
+    )

classiq/qmod/__init__.py

@@ -1,20 +1,21 @@
-from . import symbolic
 from .builtins import *  # noqa: F403
 from .builtins import __all__ as _builtins_all
 from .cfunc import cfunc
+from .create_model_function import create_model
 from .expression_query import get_expression_numeric_attributes
 from .qfunc import qfunc
 from .qmod_constant import QConstant
-from .qmod_parameter import Array, QParam
-from .qmod_struct import struct
-from .qmod_variable import Input, Output, QArray, QBit, QNum
+from .qmod_parameter import Array, CArray, CBool, CInt, CReal
+from .qmod_variable import Input, Output, QArray, QBit, QNum, QStruct
 from .quantum_callable import QCallable, QCallableList
-from .quantum_function import create_model
 from .write_qmod import write_qmod
 
 __all__ = [
-    "QParam",
     "Array",
+    "CArray",
+    "CBool",
+    "CInt",
+    "CReal",
     "Input",
     "Output",
     "QArray",
@@ -23,11 +24,10 @@ __all__ = [
     "QCallable",
     "QCallableList",
     "QConstant",
-    "struct",
-    "qfunc",
+    "QStruct",
     "cfunc",
     "create_model",
-    "symbolic",
-    "write_qmod",
     "get_expression_numeric_attributes",
+    "qfunc",
+    "write_qmod",
 ] + _builtins_all

classiq/qmod/builtins/__init__.py

@@ -1,20 +1,37 @@
+from classiq.interface.finance.function_input import FinanceFunctionInput
+
 from .classical_execution_primitives import *  # noqa: F403
 from .classical_execution_primitives import (
     __all__ as _builtin_classical_execution_primitives,
 )
 from .classical_functions import *  # noqa: F403
 from .classical_functions import __all__ as _builtin_classical_functions
+from .constants import *  # noqa: F403
+from .constants import __all__ as _builtin_constants
+from .enums import *  # noqa: F403
+from .enums import __all__ as _builtin_enums
 from .functions import *  # noqa: F403
 from .functions import __all__ as _builtin_functions
-from .operations import *  # noqa: F403
+from .operations import *  # type:ignore[assignment] # noqa: F403
 from .operations import __all__ as _builtin_operations
 from .structs import *  # noqa: F403
 from .structs import __all__ as _builtin_structs
 
+FinanceFunctionInput.model_rebuild()
+BUILTIN_CONSTANTS = [
+    constant._get_constant_node()
+    for constant in [
+        SIGNED,  # noqa: F405
+        UNSIGNED,  # noqa: F405
+    ]
+]
+
 __all__ = (
-    _builtin_structs
+    _builtin_enums
+    + _builtin_structs
     + _builtin_functions
     + _builtin_operations
     + _builtin_classical_execution_primitives
     + _builtin_classical_functions
+    + _builtin_constants
 )

classiq/qmod/builtins/classical_execution_primitives.py

@@ -1,21 +1,28 @@
-from typing import Dict, List, Optional, Union
+from typing import Final, Optional, Union
 
+from classiq.interface.exceptions import ClassiqError
 from classiq.interface.executor.execution_preferences import QaeWithQpeEstimationMethod
 from classiq.interface.executor.iqae_result import IQAEResult
-from classiq.interface.executor.result import EstimationResult, ExecutionDetails
+from classiq.interface.executor.result import (
+    EstimationResult,
+    EstimationResults,
+    ExecutionDetails,
+    MultipleExecutionDetails,
+)
 from classiq.interface.executor.vqe_result import VQESolverResult
-from classiq.interface.generator.expressions.enums import Optimizer
 from classiq.interface.generator.functions.qmod_python_interface import QmodPyStruct
 
 from classiq.applications.qsvm.qsvm import Data, Labels
-from classiq.exceptions import ClassiqError
+from classiq.qmod.builtins.enums import Optimizer
 
-ExecutionParams = Dict[str, Union[float, int]]
+ExecutionParams = dict[str, Union[float, int, list[int], list[float]]]
 
 _CALL_IN_QFUNC_ERROR = (
     'Cannot call "{}" in a quantum context. "{}" is a classical execution primitive.'
 )
 
+CARRAY_SEPARATOR: Final[str] = "_"
+
 
 def _raise_error(primitive_name: str) -> None:
     raise ClassiqError(_CALL_IN_QFUNC_ERROR.format(primitive_name, primitive_name))
@@ -31,16 +38,29 @@ def sample(  # type: ignore[return]
     _raise_error("sample")
 
 
+def batch_sample(  # type: ignore[return]
+    batch_execution_params: list[ExecutionParams],
+) -> MultipleExecutionDetails:
+    _raise_error("batch_sample")
+
+
 def estimate(  # type: ignore[return]
-    hamiltonian: List[QmodPyStruct], execution_params: Optional[ExecutionParams] = None
+    hamiltonian: list[QmodPyStruct], execution_params: Optional[ExecutionParams] = None
 ) -> EstimationResult:
     _raise_error("estimate")
 
 
+def batch_estimate(  # type: ignore[return]
+    hamiltonian: list[QmodPyStruct],
+    batch_execution_params: list[ExecutionParams],
+) -> EstimationResults:
+    _raise_error("batch_estimate")
+
+
 def vqe(  # type: ignore[return]
-    hamiltonian: List[QmodPyStruct],
+    hamiltonian: list[QmodPyStruct],
     maximize: bool,
-    initial_point: List[int],
+    initial_point: list[float],
     optimizer: Optimizer,
     max_iteration: int,
     tolerance: float,
@@ -85,16 +105,18 @@ def molecule_ground_state_solution_post_process(  # type: ignore[return]
 
 __all__ = [
     "ExecutionParams",
-    "save",
-    "sample",
+    "batch_estimate",
+    "batch_sample",
     "estimate",
-    "vqe",
-    "qae_with_qpe_result_post_processing",
-    "qsvm_full_run",
     "iqae",
     "molecule_ground_state_solution_post_process",
+    "qae_with_qpe_result_post_processing",
+    "qsvm_full_run",
+    "sample",
+    "save",
+    "vqe",
 ]
 
 
-def __dir__() -> List[str]:
+def __dir__() -> list[str]:
     return __all__