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

classiq/qmod/builtins/operations.py

@@ -1,15 +1,16 @@
 import inspect
 import sys
 import warnings
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
+from functools import wraps
+from itertools import product
 from types import FrameType
 from typing import (
     Any,
-    Callable,
     Final,
     NoReturn,
-    Optional,
-    Union,
+    ParamSpec,
+    TypeVar,
     overload,
 )
 
@@ -49,19 +50,40 @@ from classiq.interface.model.skip_control import SkipControl
 from classiq.interface.model.statement_block import StatementBlock
 from classiq.interface.model.within_apply_operation import WithinApply
 
+from classiq.qmod.builtins.functions import H, S
 from classiq.qmod.generative import is_generative_mode
 from classiq.qmod.qmod_constant import QConstant
 from classiq.qmod.qmod_variable import Input, Output, QArray, QBit, QNum, QScalar, QVar
 from classiq.qmod.quantum_callable import QCallable
 from classiq.qmod.quantum_expandable import prepare_arg
+from classiq.qmod.semantics.error_manager import ErrorManager
 from classiq.qmod.symbolic_expr import SymbolicExpr
-from classiq.qmod.utilities import Statements, get_source_ref, suppress_return_value
+from classiq.qmod.utilities import (
+    RealFunction,
+    Statements,
+    get_source_ref,
+    qnum_values,
+    suppress_return_value,
+)
 
 _MISSING_VALUE: Final[int] = -1
 
+_Params = ParamSpec("_Params")
+_RetType = TypeVar("_RetType")
+
+
+def qmod_statement(func: Callable[_Params, _RetType]) -> Callable[_Params, _RetType]:
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        source_ref = get_source_ref(sys._getframe(1))
+        with ErrorManager().source_ref_context(source_ref):
+            return func(*args, **kwargs)
+
+    return wrapper
+
 
 @overload
-def allocate(num_qubits: Union[int, SymbolicExpr], out: Output[QVar]) -> None:
+def allocate(num_qubits: int | SymbolicExpr, out: Output[QVar]) -> None:
     pass
 
 
@@ -72,15 +94,16 @@ def allocate(out: Output[QVar]) -> None:
 
 @overload
 def allocate(
-    num_qubits: Union[int, SymbolicExpr],
-    is_signed: Union[bool, SymbolicExpr],
-    fraction_digits: Union[int, SymbolicExpr],
+    num_qubits: int | SymbolicExpr,
+    is_signed: bool | SymbolicExpr,
+    fraction_digits: int | SymbolicExpr,
     out: Output[QVar],
 ) -> None:
     pass
 
 
 @suppress_return_value
+@qmod_statement
 def allocate(*args: Any, **kwargs: Any) -> None:
     """
     Initialize a quantum variable to a new quantum object in the zero state:
@@ -104,29 +127,34 @@ def allocate(*args: Any, **kwargs: Any) -> None:
         2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
     """
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     if len(args) == 0:
         size = kwargs.get("num_qubits", None)
         is_signed = kwargs.get("is_signed", None)
         fraction_digits = kwargs.get("fraction_digits", None)
-        target = kwargs["out"]
+        out = kwargs["out"]
     elif len(args) == 1:
         if "out" in kwargs:
             size = args[0]
             is_signed = kwargs.get("is_signed", None)
             fraction_digits = kwargs.get("fraction_digits", None)
-            target = kwargs["out"]
+            out = kwargs["out"]
         else:
             size = None
             is_signed = None
             fraction_digits = None
-            target = args[0]
+            out = args[0]
     elif len(args) == 2:
-        size, target = args
+        size, out = args
         is_signed = kwargs.get("is_signed", None)
         fraction_digits = kwargs.get("fraction_digits", None)
     else:
-        size, is_signed, fraction_digits, target = args
+        size, is_signed, fraction_digits, out = args
+    if not isinstance(out, QVar):
+        raise ClassiqValueError(
+            f"Argument 'out' of operator 'allocate' must be a quantum variable, got "
+            f"{type(out).__name__}"
+        )
     if isinstance(size, QConstant):
         size.add_to_model()
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
@@ -138,16 +166,17 @@ def allocate(*args: Any, **kwargs: Any) -> None:
                 if fraction_digits is None
                 else Expression(expr=str(fraction_digits))
             ),
-            target=target.get_handle_binding(),
+            target=out.get_handle_binding(),
             source_ref=source_ref,
         )
     )
 
 
 @suppress_return_value
+@qmod_statement
 def bind(
-    source: Union[Input[QVar], list[Input[QVar]]],
-    destination: Union[Output[QVar], list[Output[QVar]]],
+    source: Input[QVar] | list[Input[QVar]],
+    destination: Output[QVar] | list[Output[QVar]],
 ) -> None:
     """
     Reassign qubit or arrays of qubits by redirecting their logical identifiers.
@@ -166,7 +195,7 @@ def bind(
     For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/statements/bind).
     """
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     if not isinstance(source, list):
         source = [source]
     if not isinstance(destination, list):
@@ -181,10 +210,11 @@ def bind(
 
 
 @suppress_return_value
+@qmod_statement
 def if_(
-    condition: Union[SymbolicExpr, bool],
-    then: Union[QCallable, Callable[[], Statements]],
-    else_: Union[QCallable, Callable[[], Statements], int] = _MISSING_VALUE,
+    condition: SymbolicExpr | bool,
+    then: QCallable | Callable[[], Statements],
+    else_: QCallable | Callable[[], Statements] | int = _MISSING_VALUE,
 ) -> None:
     """
     Conditionally executes quantum operations based on a symbolic or boolean expression.
@@ -202,7 +232,7 @@ def if_(
     if else_ != _MISSING_VALUE:
         _validate_operand(else_)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
 
     if_stmt = ClassicalIf(
         condition=Expression(expr=str(condition)),
@@ -218,10 +248,11 @@ def if_(
 
 
 @suppress_return_value
+@qmod_statement
 def control(
-    ctrl: Union[SymbolicExpr, QBit, QArray[QBit], list[QVar]],
-    stmt_block: Union[QCallable, Callable[[], Statements]],
-    else_block: Union[QCallable, Callable[[], Statements], None] = None,
+    ctrl: SymbolicExpr | QBit | QArray[QBit] | list[QVar],
+    stmt_block: QCallable | Callable[[], Statements],
+    else_block: QCallable | Callable[[], Statements] | None = None,
 ) -> None:
     """
     Conditionally executes quantum operations based on the value of quantum variables or expressions.
@@ -241,7 +272,7 @@ def control(
     """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     control_stmt = Control(
         expression=Expression(expr=str(ctrl)),
         body=_operand_to_body(stmt_block, "stmt_block"),
@@ -256,10 +287,19 @@ def control(
 
 
 @suppress_return_value
-def skip_control(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None:
+@qmod_statement
+def skip_control(stmt_block: QCallable | Callable[[], Statements]) -> None:
+    """
+    Applies quantum statements unconditionally.
+
+    Args:
+        stmt_block: A callable that produces a quantum operation.
+
+    For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/statements/skip-control).
+    """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     sc_stmt = SkipControl(
         body=_operand_to_body(stmt_block, "stmt_block"),
         source_ref=source_ref,
@@ -270,6 +310,7 @@ def skip_control(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None
 
 
 @suppress_return_value
+@qmod_statement
 def assign(expression: SymbolicExpr, target_var: QScalar) -> None:
     """
     Initialize a scalar quantum variable using an arithmetic expression.
@@ -283,7 +324,7 @@ def assign(expression: SymbolicExpr, target_var: QScalar) -> None:
         target_var: An uninitialized scalar quantum variable
     """
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
         ArithmeticOperation(
             expression=Expression(expr=str(expression)),
@@ -295,6 +336,7 @@ def assign(expression: SymbolicExpr, target_var: QScalar) -> None:
 
 
 @suppress_return_value
+@qmod_statement
 def assign_amplitude(expression: SymbolicExpr, target_var: QScalar) -> None:
     """
     Perform an amplitude-encoding assignment operation on a quantum variable and a
@@ -306,8 +348,15 @@ def assign_amplitude(expression: SymbolicExpr, target_var: QScalar) -> None:
         expression: A quantum arithmetic expression
         target_var: A scalar quantum variable
     """
+    warnings.warn(
+        "The 'assign_amplitude' function is deprecated and will no longer be "
+        "supported starting on 2025-12-03 at the earliest. Use 'assign_amplitude_table' "
+        "instead",
+        ClassiqDeprecationWarning,
+        stacklevel=3,
+    )
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
         AmplitudeLoadingOperation(
             expression=Expression(expr=str(expression)),
@@ -318,6 +367,7 @@ def assign_amplitude(expression: SymbolicExpr, target_var: QScalar) -> None:
 
 
 @suppress_return_value
+@qmod_statement
 def inplace_add(expression: SymbolicExpr, target_var: QScalar) -> None:
     """
     Add an arithmetic expression to a quantum variable.
@@ -329,7 +379,7 @@ def inplace_add(expression: SymbolicExpr, target_var: QScalar) -> None:
         target_var: A scalar quantum variable
     """
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
         ArithmeticOperation(
             expression=Expression(expr=str(expression)),
@@ -341,6 +391,7 @@ def inplace_add(expression: SymbolicExpr, target_var: QScalar) -> None:
 
 
 @suppress_return_value
+@qmod_statement
 def inplace_xor(expression: SymbolicExpr, target_var: QScalar) -> None:
     """
     Bitwise-XOR a quantum variable with an arithmetic expression.
@@ -352,7 +403,7 @@ def inplace_xor(expression: SymbolicExpr, target_var: QScalar) -> None:
         target_var: A scalar quantum variable
     """
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
         ArithmeticOperation(
             expression=Expression(expr=str(expression)),
@@ -364,6 +415,7 @@ def inplace_xor(expression: SymbolicExpr, target_var: QScalar) -> None:
 
 
 @suppress_return_value
+@qmod_statement
 def within_apply(
     within: Callable[[], Statements],
     apply: Callable[[], Statements],
@@ -383,7 +435,7 @@ def within_apply(
     _validate_operand(within)
     _validate_operand(apply)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     within_apply_stmt = WithinApply(
         compute=_operand_to_body(within, "within"),
         action=_operand_to_body(apply, "apply"),
@@ -396,9 +448,8 @@ def within_apply(
 
 
 @suppress_return_value
-def repeat(
-    count: Union[SymbolicExpr, int], iteration: Callable[[int], Statements]
-) -> None:
+@qmod_statement
+def repeat(count: SymbolicExpr | int, iteration: Callable[[int], Statements]) -> None:
     """
     Executes a quantum loop a specified number of times, applying a quantum operation on each iteration.
 
@@ -424,7 +475,7 @@ def repeat(
     """
     _validate_operand(iteration, num_params=1)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     iteration_operand = prepare_arg(
         QuantumOperandDeclaration(
             name=REPEAT_OPERATOR_NAME,
@@ -453,9 +504,10 @@ def repeat(
 
 
 @suppress_return_value
+@qmod_statement
 def power(
-    exponent: Union[SymbolicExpr, int],
-    stmt_block: Union[QCallable, Callable[[], Statements]],
+    exponent: SymbolicExpr | int,
+    stmt_block: QCallable | Callable[[], Statements],
 ) -> None:
     """
     Apply a quantum operation raised to a symbolic or integer power.
@@ -487,7 +539,7 @@ def power(
     """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     power_stmt = Power(
         power=Expression(expr=str(exponent)),
         body=_operand_to_body(stmt_block, "stmt_block"),
@@ -499,7 +551,8 @@ def power(
 
 
 @suppress_return_value
-def invert(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None:
+@qmod_statement
+def invert(stmt_block: QCallable | Callable[[], Statements]) -> None:
     """
     Apply the inverse of a quantum gate.
 
@@ -523,7 +576,7 @@ def invert(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None:
     """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     invert_stmt = Invert(
         body=_operand_to_body(stmt_block, "stmt_block"), source_ref=source_ref
     )
@@ -532,25 +585,11 @@ def invert(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None:
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(invert_stmt)
 
 
-@overload
-def phase(
-    phase_expr: Union[SymbolicExpr, float], theta: Union[SymbolicExpr, float] = 1.0
-) -> None:
-    pass
-
-
-@overload
-def phase(
-    *, expr: Union[SymbolicExpr, float], theta: Union[SymbolicExpr, float] = 1.0
-) -> None:
-    pass
-
-
 @suppress_return_value
+@qmod_statement
 def phase(
-    phase_expr: Union[SymbolicExpr, float, None] = None,
-    theta: Union[SymbolicExpr, float] = 1.0,
-    expr: Any = None,
+    phase_expr: SymbolicExpr | float | None = None,
+    theta: SymbolicExpr | float = 1.0,
 ) -> None:
     """
     Applies a state-dependent or fixed phase shift (Z rotation) to the quantum state.
@@ -570,17 +609,7 @@ def phase(
         they are equivalent when the phase_expr is a single-qubit variable.
     """
     assert QCallable.CURRENT_EXPANDABLE is not None
-    if expr is not None:
-        warnings.warn(
-            "Parameter 'expr' of function 'phase' has been renamed to "
-            "'phase_expr'. Parameter 'expr' will no longer be supported starting on "
-            "2025-09-19 at the earliest.\nHint: Change `phase(expr=..., theta=...)` to "
-            "`phase(phase_expr=..., theta=...)` or `phase(..., ...)`.",
-            category=ClassiqDeprecationWarning,
-            stacklevel=2,
-        )
-        phase_expr = expr
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
         PhaseOperation(
             expression=Expression(expr=str(phase_expr)),
@@ -591,12 +620,13 @@ def phase(
 
 
 @suppress_return_value
+@qmod_statement
 def block(
-    statements: Union[QCallable, Callable[[], Statements]],
+    statements: QCallable | Callable[[], Statements],
 ) -> None:
     _validate_operand(statements)
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
 
     block_stmt = Block(
         statements=_operand_to_body(statements, "statements"),
@@ -617,20 +647,21 @@ def reset_bounds(
 @overload
 def reset_bounds(
     target_var: QNum,
-    lower_bound: Union[float, SymbolicExpr],
-    upper_bound: Union[float, SymbolicExpr],
+    lower_bound: float | SymbolicExpr,
+    upper_bound: float | SymbolicExpr,
 ) -> None:
     pass
 
 
 @suppress_return_value
+@qmod_statement
 def reset_bounds(
     target_var: QNum,
-    lower_bound: Optional[Union[float, SymbolicExpr]] = None,
-    upper_bound: Optional[Union[float, SymbolicExpr]] = None,
+    lower_bound: float | SymbolicExpr | None = None,
+    upper_bound: float | SymbolicExpr | None = None,
 ) -> None:
     assert QCallable.CURRENT_EXPANDABLE is not None
-    source_ref = get_source_ref(sys._getframe(1))
+    source_ref = get_source_ref(sys._getframe(2))
 
     lower_bound_expr = (
         None if lower_bound is None else Expression(expr=str(lower_bound))
@@ -660,6 +691,14 @@ def _validate_operand(stmt_block: Any, num_params: int = 0) -> None:
         )
     if isinstance(stmt_block, QCallable):
         return
+    if not callable(stmt_block):
+        _raise_operand_error(
+            lambda operation_name, operand_arg_name: (
+                f"Argument {operand_arg_name!r} to {operation_name!r} must be a "
+                f"callable object"
+            ),
+            num_params,
+        )
     op_spec = inspect.getfullargspec(stmt_block)
     params = op_spec.args[: len(op_spec.args) - len(op_spec.defaults or ())]
     if len(params) > num_params or (
@@ -726,7 +765,7 @@ def _get_operand_hint(
 
 
 def _operand_to_body(
-    callable_: Union[QCallable, Callable[[], Statements]], param_name: str
+    callable_: QCallable | Callable[[], Statements], param_name: str
 ) -> StatementBlock:
     op_name = sys._getframe(1).f_code.co_name
     if (
@@ -748,10 +787,64 @@ def _operand_to_body(
         raise ValueError(f"Unexpected operand type: {type(to_operand)}")
 
 
+def assign_amplitude_poly_sin(indicator: QBit, expr: SymbolicExpr) -> None:
+    """
+    Encodes the value of the sine/cosine of a polynomial into the amplitude of the
+    respective computational basis state:
+    \\( |x_1, x_2, \\ldots, x_n\\rangle|0\\rangle \\rightarrow cos(poly(x_1, x_2, \\ldots, x_n))|x_1, x_2, \\ldots, x_n\\rangle|0\\rangle + sin(poly(x_1, x_2, \\ldots, x_n))|x_1, x_2, \\ldots, x_n\\rangle|1\\rangle \\)
+
+    Args:
+        indicator: The quantum indicator qubit
+        expr: A polynomial expression over quantum scalars x_1, x_2, \\ldots, x_n
+    """
+    phase(-expr)
+    within_apply(
+        lambda: H(indicator),
+        lambda: control(indicator, lambda: phase(2 * expr)),
+    )
+    S(indicator)
+
+
+def _get_qnum_values(num: QNum) -> list[float]:
+    size = num.size
+    is_signed = num.is_signed
+    fraction_digits = num.fraction_digits
+    if (
+        not isinstance(size, int)
+        or not isinstance(is_signed, bool)
+        or not isinstance(fraction_digits, int)
+    ):
+        raise ClassiqValueError(f"QNum argument {str(num)!r} has symbolic attributes")
+
+    return qnum_values(size, is_signed, fraction_digits)
+
+
+def lookup_table(func: RealFunction, targets: QNum | list[QNum]) -> list[float]:
+    """
+    Reduces a classical function into a lookup table over all the possible values
+    of the quantum numbers.
+
+    Args:
+        func: A Python function
+        targets: One or more initialized quantum numbers
+
+    Returns:
+        The function's lookup table
+
+    Notes:
+        The QNum arguments must have generative attributes
+    """
+    if not isinstance(targets, list):
+        targets = [targets]
+    target_vals = [_get_qnum_values(target) for target in targets]
+    return [func(*vals[::-1]) for vals in product(*target_vals[::-1])]
+
+
 __all__ = [
     "allocate",
     "assign",
     "assign_amplitude",
+    "assign_amplitude_poly_sin",
     "bind",
     "block",
     "control",
@@ -759,6 +852,7 @@ __all__ = [
     "inplace_add",
     "inplace_xor",
     "invert",
+    "lookup_table",
     "phase",
     "power",
     "repeat",