classiq 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

classiq/qmod/builtins/operations.py

@@ -1,18 +1,32 @@
 from typing import Callable, List, Union
 
 from classiq.interface.generator.expressions.expression import Expression
+from classiq.interface.generator.functions.core_lib_declarations.quantum_operators import (
+    OPERAND_FIELD_NAME,
+)
 from classiq.interface.model.bind_operation import BindOperation
-from classiq.interface.model.modular_addition_operation import ModularAdditionOperation
+from classiq.interface.model.inplace_binary_operation import (
+    BinaryOperation,
+    InplaceBinaryOperation,
+)
 from classiq.interface.model.numeric_reinterpretation import (
     NumericReinterpretationOperation,
 )
+from classiq.interface.model.quantum_function_declaration import (
+    QuantumOperandDeclaration,
+)
+from classiq.interface.model.quantum_if_operation import QuantumIfOperation
 
-from classiq.exceptions import ClassiqValueError
-from classiq.qmod.builtins.functions import control_with_value
+from classiq.qmod.builtins.functions import (
+    apply,
+    compute as compute_operator,
+    uncompute,
+)
 from classiq.qmod.qmod_parameter import QParam
 from classiq.qmod.qmod_variable import Input, Output, QNum, QVar
 from classiq.qmod.quantum_callable import QCallable
-from classiq.qmod.symbolic_expr import SymbolicEquality, SymbolicExpr
+from classiq.qmod.quantum_expandable import prepare_arg
+from classiq.qmod.symbolic_expr import SymbolicExpr
 
 
 def bind(source: Input[QVar], destination: Output[QVar]) -> None:
@@ -25,42 +39,22 @@ def bind(source: Input[QVar], destination: Output[QVar]) -> None:
     )
 
 
-QUANTUM_IF_CONDITION_ARG_ERROR_MESSAGE_PREFIX = (
-    "quantum_if condition must be of the form '<quantum-variable> == "
-    "<classical-integer-expression>', but "
-)
-
-
 def quantum_if(
     condition: SymbolicExpr, then: Union[QCallable, Callable[[], None]]
 ) -> None:
-    if not isinstance(condition, SymbolicEquality):
-        raise ClassiqValueError(
-            f"quantum_if condition must be an equality, was " f"{condition!r}"
-        )
-    ctrl, ctrl_val = condition.lhs, condition.rhs
-    if isinstance(ctrl, (int, SymbolicExpr)) and isinstance(ctrl_val, QNum):
-        ctrl, ctrl_val = ctrl_val, ctrl
-
-    if not isinstance(ctrl, QNum):
-        raise ClassiqValueError(
-            QUANTUM_IF_CONDITION_ARG_ERROR_MESSAGE_PREFIX
-            + f"condition's left-hand side was {ctrl!r} of type "
-            f"{type(ctrl)}"
-        )
-    if not isinstance(ctrl_val, (int, SymbolicExpr)):
-        raise ClassiqValueError(
-            QUANTUM_IF_CONDITION_ARG_ERROR_MESSAGE_PREFIX
-            + f"condition's right-hand side was {ctrl_val!r} of type "
-            f"{type(ctrl_val)}"
+    assert QCallable.CURRENT_EXPANDABLE is not None
+    QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
+        QuantumIfOperation(
+            expression=Expression(expr=str(condition)),
+            then=prepare_arg(QuantumOperandDeclaration(name=OPERAND_FIELD_NAME), then),
         )
-    control_with_value(ctrl_val, then, ctrl)
+    )
 
 
 def reinterpret_num(
+    is_signed: Union[QParam[bool], bool],
+    fraction_digits: Union[QParam[int], int],
     target: QNum,
-    is_signed: Union[QParam[bool], bool] = True,
-    fraction_digits: Union[QParam[int], int] = 0,
 ) -> None:
     assert QCallable.CURRENT_EXPANDABLE is not None
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
@@ -72,20 +66,51 @@ def reinterpret_num(
     )
 
 
-def modular_add(
+def inplace_add(
     value: QNum,
     target: QNum,
 ) -> None:
     assert QCallable.CURRENT_EXPANDABLE is not None
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
-        ModularAdditionOperation(
+        InplaceBinaryOperation(
             target=target.get_handle_binding(),
             value=value.get_handle_binding(),
+            operation=BinaryOperation.Addition,
         )
     )
 
 
-__all__ = ["bind", "quantum_if", "reinterpret_num", "modular_add"]
+def inplace_xor(
+    value: QNum,
+    target: QNum,
+) -> None:
+    assert QCallable.CURRENT_EXPANDABLE is not None
+    QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
+        InplaceBinaryOperation(
+            target=target.get_handle_binding(),
+            value=value.get_handle_binding(),
+            operation=BinaryOperation.Xor,
+        )
+    )
+
+
+def within_apply(
+    compute: Callable[[], None],
+    action: Callable[[], None],
+) -> None:
+    compute_operator(compute)
+    apply(action)
+    uncompute(compute)
+
+
+__all__ = [
+    "bind",
+    "quantum_if",
+    "reinterpret_num",
+    "inplace_add",
+    "inplace_xor",
+    "within_apply",
+]
 
 
 def __dir__() -> List[str]:

classiq/qmod/classical_function.py

@@ -0,0 +1,40 @@
+import ast
+import inspect
+import sys
+from textwrap import dedent
+from typing import Callable
+
+from classiq.exceptions import ClassiqValueError
+from classiq.qmod.builtins.classical_execution_primitives import sample, save
+
+
+def _unparse_function_body(code: str, func: ast.FunctionDef) -> str:
+    first_statement = func.body[0]
+    body_lines = list(code.split("\n"))[first_statement.lineno - 1 :]
+    body_lines[0] = body_lines[0][first_statement.col_offset :]
+    if len(body_lines) > 1:
+        body_lines = [body_lines[0], dedent("\n".join(body_lines[1:]))]
+    return "\n".join(body_lines).strip()
+
+
+class CFunc:
+    @staticmethod
+    def default_cmain() -> "CFunc":
+        @CFunc
+        def cmain() -> None:
+            result = sample()
+            save({"result": result})
+
+        return cmain
+
+    def __init__(self, py_callable: Callable[[], None]):
+        code = dedent(inspect.getsource(py_callable))
+        func = ast.parse(code).body[0]
+        if not isinstance(func, ast.FunctionDef):
+            raise ClassiqValueError(f"Use @{CFunc.__name__} to decorate a function")
+        if len(func.args.args) > 0:
+            raise ClassiqValueError(f"A @{CFunc.__name__} must receive no arguments")
+        if sys.version_info >= (3, 9):
+            self.code = "\n".join([ast.unparse(statement) for statement in func.body])
+        else:
+            self.code = _unparse_function_body(code, func)

classiq/qmod/declaration_inferrer.py

@@ -29,7 +29,7 @@ from classiq import StructDeclaration
 from classiq.qmod.model_state_container import ModelStateContainer
 from classiq.qmod.qmod_parameter import Array, QParam
 from classiq.qmod.qmod_variable import QVar, get_type_hint_expr
-from classiq.qmod.quantum_callable import QCallable
+from classiq.qmod.quantum_callable import QCallable, QCallableList
 from classiq.qmod.utilities import unmangle_keyword
 
 OPERAND_ARG_NAME = "arg{i}"
@@ -125,6 +125,7 @@ def _extract_operand_decl(
     return QuantumOperandDeclaration(
         name=name,
         positional_arg_declarations=_extract_positional_args(arg_dict, qmodule=qmodule),
+        is_list=(get_origin(py_type) or py_type) is QCallableList,
     )
 
 
@@ -141,7 +142,9 @@ def _extract_positional_args(
         elif QVar.from_type_hint(py_type) is not None:
             result.append(_extract_port_decl(name, py_type))
         else:
-            assert get_origin(py_type) or py_type is QCallable
+            assert (get_origin(py_type) or py_type) is QCallable or (
+                get_origin(py_type) or py_type
+            ) is QCallableList
             result.append(_extract_operand_decl(name, py_type, qmodule=qmodule))
     return result
 

classiq/qmod/qmod_variable.py

@@ -1,5 +1,4 @@
 import abc
-import ast
 from contextlib import contextmanager
 from typing import (
     TYPE_CHECKING,
@@ -41,16 +40,13 @@ from classiq.interface.model.quantum_type import (
 from classiq.exceptions import ClassiqValueError
 from classiq.qmod.qmod_parameter import ArrayBase, QParam, QParamScalar
 from classiq.qmod.quantum_callable import QCallable
-from classiq.qmod.symbolic_expr import SymbolicExpr, SymbolicTypes
+from classiq.qmod.symbolic_expr import SymbolicExpr
+from classiq.qmod.symbolic_type import SymbolicTypes
 
 ILLEGAL_SLICING_STEP_MSG = "Slicing with a step of a quantum variable is not supported"
 SLICE_OUT_OF_BOUNDS_MSG = "Slice end index out of bounds"
 
 
-def _python_expr(expr: SymbolicTypes) -> str:
-    return ast.unparse(ast.parse(str(expr)))
-
-
 def _is_input_output_typehint(type_hint: Any) -> bool:
     return isinstance(type_hint, _AnnotatedAlias) and isinstance(
         type_hint.__metadata__[0], PortDeclarationDirection
@@ -131,7 +127,7 @@ class QScalar(QVar, SymbolicExpr):
             assert QCallable.CURRENT_EXPANDABLE is not None
         QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
             ArithmeticOperation(
-                expression=Expression(expr=_python_expr(expr)),
+                expression=Expression(expr=str(expr)),
                 result_var=self.get_handle_binding(),
                 inplace_result=inplace,
             )
@@ -142,7 +138,7 @@ class QScalar(QVar, SymbolicExpr):
             assert QCallable.CURRENT_EXPANDABLE is not None
         QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
             AmplitudeLoadingOperation(
-                expression=Expression(expr=_python_expr(expr)),
+                expression=Expression(expr=str(expr)),
                 result_var=self.get_handle_binding(),
             )
         )
@@ -204,6 +200,18 @@ class QNum(Generic[_T], QScalar):
     def get_qmod_type(self) -> QuantumType:
         return self.QMOD_TYPE()
 
+    @property
+    def size(self) -> QParamScalar:
+        return QParamScalar(f"len({self._name})")
+
+    @property
+    def fraction_digits(self) -> QParamScalar:
+        return QParamScalar(f"fraction_digits({self._name})")
+
+    @property
+    def is_signed(self) -> QParamScalar:
+        return QParamScalar(f"is_signed({self._name})")
+
 
 _P = ParamSpec("_P")
 
@@ -245,8 +253,7 @@ class QArray(ArrayBase[_P], QVar):
 
     if TYPE_CHECKING:
 
-        def len(self) -> int:
-            ...
+        def len(self) -> int: ...
 
     else:
 

classiq/qmod/quantum_callable.py

@@ -1,7 +1,14 @@
 import sys
 from abc import ABC, abstractmethod
-from typing import _GenericAlias  # type: ignore[attr-defined]
-from typing import Any, ClassVar, Generic, Optional
+from typing import (  # type: ignore[attr-defined]
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Generic,
+    Optional,
+    Union,
+    _GenericAlias,
+)
 
 from typing_extensions import ParamSpec
 
@@ -12,6 +19,11 @@ from classiq.interface.model.quantum_function_declaration import (
 from classiq.interface.model.quantum_statement import QuantumStatement
 from classiq.interface.model.quantum_type import QuantumType
 
+from classiq.qmod.qmod_parameter import QParam
+
+if TYPE_CHECKING:
+    from classiq.qmod.quantum_expandable import QTerminalCallable
+
 P = ParamSpec("P")
 
 
@@ -25,7 +37,7 @@ class QExpandableInterface(ABC):
         raise NotImplementedError()
 
 
-class QCallable(Generic[P]):
+class QCallable(Generic[P], ABC):
     CURRENT_EXPANDABLE: ClassVar[Optional[QExpandableInterface]] = None
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:
@@ -51,3 +63,12 @@ class QCallable(Generic[P]):
         self, *args: Any, **kwargs: Any
     ) -> QuantumFunctionCall:
         raise NotImplementedError()
+
+
+class QCallableList(QCallable, Generic[P], ABC):
+    if TYPE_CHECKING:
+
+        def len(self) -> int: ...
+
+        def __getitem__(self, key: Union[slice, int, QParam]) -> "QTerminalCallable":
+            raise NotImplementedError()

classiq/qmod/quantum_expandable.py

@@ -1,6 +1,18 @@
 from abc import ABC
 from types import TracebackType
-from typing import Any, Callable, ClassVar, Dict, List, Optional, Type, Union
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Type,
+    Union,
+    cast,
+    overload,
+)
 
 from typing_extensions import Self
 
@@ -11,8 +23,10 @@ from classiq.interface.model.classical_parameter_declaration import (
 from classiq.interface.model.port_declaration import PortDeclaration
 from classiq.interface.model.quantum_function_call import (
     ArgValue,
+    OperandIdentifier,
     QuantumFunctionCall,
     QuantumLambdaFunction,
+    QuantumOperand,
 )
 from classiq.interface.model.quantum_function_declaration import (
     PositionalArg,
@@ -25,8 +39,9 @@ from classiq.interface.model.variable_declaration_statement import (
     VariableDeclarationStatement,
 )
 
+from classiq.exceptions import ClassiqValueError
 from classiq.qmod.model_state_container import QMODULE, ModelStateContainer
-from classiq.qmod.qmod_parameter import QParam, create_param
+from classiq.qmod.qmod_parameter import QParam, QParamScalar, create_param
 from classiq.qmod.qmod_variable import QVar, create_qvar_for_port_decl
 from classiq.qmod.quantum_callable import QCallable, QExpandableInterface
 from classiq.qmod.utilities import mangle_keyword
@@ -97,7 +112,7 @@ class QExpandable(QCallable, QExpandableInterface, ABC):
     def create_quantum_function_call(
         self, *args: Any, **kwargs: Any
     ) -> QuantumFunctionCall:
-        return _create_quantum_function_call(self.func_decl, *args, **kwargs)
+        return _create_quantum_function_call(self.func_decl, None, *args, **kwargs)
 
 
 class QLambdaFunction(QExpandable):
@@ -126,8 +141,42 @@ class QLambdaFunction(QExpandable):
 
 
 class QTerminalCallable(QCallable):
-    def __init__(self, decl: QuantumFunctionDeclaration) -> None:
+    def __init__(
+        self,
+        decl: QuantumFunctionDeclaration,
+        index_: Optional[Union[int, QParamScalar]] = None,
+    ) -> None:
         self._decl = decl
+        self._index = index_
+
+    @property
+    def is_list(self) -> bool:
+        return isinstance(self._decl, QuantumOperandDeclaration) and self._decl.is_list
+
+    def __getitem__(self, key: Union[slice, int, QParam]) -> "QTerminalCallable":
+        if not self.is_list:
+            raise ClassiqValueError("Cannot index a non-list operand")
+        if isinstance(key, slice):
+            raise NotImplementedError("Operand lists don't support slicing")
+        if isinstance(key, QParam) and not isinstance(key, QParamScalar):
+            raise ClassiqValueError("Non-classical parameter for slicing")
+        return QTerminalCallable(self._decl, key)
+
+    def __len__(self) -> int:
+        raise ValueError(
+            "len(<func>) is not supported for quantum callables - use <func>.len() instead (Only if it is an operand list)"
+        )
+
+    if TYPE_CHECKING:
+
+        def len(self) -> int: ...
+
+    else:
+
+        def len(self) -> QParamScalar:
+            if not self.is_list:
+                raise ClassiqValueError("Cannot get length of a non-list operand")
+            return QParamScalar(f"len({self.func_decl.name})")
 
     @property
     def func_decl(self) -> QuantumFunctionDeclaration:
@@ -136,15 +185,39 @@ class QTerminalCallable(QCallable):
     def create_quantum_function_call(
         self, *args: Any, **kwargs: Any
     ) -> QuantumFunctionCall:
-        return _create_quantum_function_call(self.func_decl, *args, **kwargs)
+        if self.is_list and self._index is None:
+            raise ClassiqValueError(
+                f"Quantum operand {self.func_decl.name!r} is a list and must be indexed"
+            )
+        return _create_quantum_function_call(
+            self.func_decl, self._index, *args, **kwargs
+        )
+
 
+@overload
+def prepare_arg(
+    arg_decl: PositionalArg, val: Union[QCallable, Callable[[Any], None]]
+) -> QuantumOperand: ...
 
-def _prepare_arg(arg_decl: PositionalArg, val: Any) -> ArgValue:
+
+@overload
+def prepare_arg(arg_decl: PositionalArg, val: Any) -> ArgValue: ...
+
+
+def prepare_arg(arg_decl: PositionalArg, val: Any) -> ArgValue:
     if isinstance(arg_decl, ClassicalParameterDeclaration):
         return Expression(expr=str(val))
     elif isinstance(arg_decl, PortDeclaration):
         return val.get_handle_binding()
     else:
+        if isinstance(val, list):
+            if not all(isinstance(v, QCallable) or callable(v) for v in val):
+                raise ClassiqValueError(
+                    f"Quantum operand {arg_decl.name!r} cannot be initialized with a list of non-callables"
+                )
+            val = cast(List[Union[QCallable, Callable[[Any], None]]], val)
+            return [prepare_arg(arg_decl, v) for v in val]
+
         if not isinstance(val, QCallable):
             val = QLambdaFunction(arg_decl, val)
 
@@ -157,6 +230,32 @@ def _prepare_arg(arg_decl: PositionalArg, val: Any) -> ArgValue:
         )
 
 
+def _get_operand_hint_args(
+    func: QuantumFunctionDeclaration, param: PositionalArg, param_value: str
+) -> str:
+    return ", ".join(
+        [
+            (
+                f"{decl.name}={param_value}"
+                if decl.name == param.name
+                else f"{decl.name}=..."
+            )
+            for decl in func.get_positional_arg_decls()
+        ]
+    )
+
+
+def _get_operand_hint(func: QuantumFunctionDeclaration, param: PositionalArg) -> str:
+    return (
+        f"\nHint: To create an operand, do not call quantum gates directly "
+        f"`{func.name}({_get_operand_hint_args(func, param, 'H(q)')})`. "
+        f"Instead, use a lambda function "
+        f"`{func.name}({_get_operand_hint_args(func, param, 'lambda: H(q)')})` "
+        f"or a quantum function "
+        f"`{func.name}({_get_operand_hint_args(func, param, 'my_func')})`"
+    )
+
+
 def _prepare_args(
     decl: QuantumFunctionDeclaration, arg_list: List[Any], kwargs: Dict[str, Any]
 ) -> List[ArgValue]:
@@ -166,35 +265,46 @@ def _prepare_args(
             arg = arg_list.pop(0)
         else:
             arg = kwargs.pop(mangle_keyword(arg_decl.name), None)
-            if arg is None:
-                raise ValueError(
-                    f"{decl.name}() missing required argument for {arg_decl.name!r}"
-                )
-        result.append(_prepare_arg(arg_decl, arg))
+        if arg is None:
+            error_message = (
+                f"{decl.name!r} is missing required argument for {arg_decl.name!r}"
+            )
+            if isinstance(arg_decl, QuantumOperandDeclaration):
+                error_message += _get_operand_hint(decl, arg_decl)
+            raise ClassiqValueError(error_message)
+        result.append(prepare_arg(arg_decl, arg))
 
     return result
 
 
 def _create_quantum_function_call(
-    decl: QuantumFunctionDeclaration, *args: Any, **kwargs: Any
+    decl_: QuantumFunctionDeclaration,
+    index_: Optional[Union[QParamScalar, int]] = None,
+    *args: Any,
+    **kwargs: Any,
 ) -> QuantumFunctionCall:
-    arg_decls = decl.get_positional_arg_decls()
+    arg_decls = decl_.get_positional_arg_decls()
     arg_list = list(args)
-    prepared_args = _prepare_args(decl, arg_list, kwargs)
+    prepared_args = _prepare_args(decl_, arg_list, kwargs)
 
     if kwargs:
         bad_kwarg = next(iter(kwargs))
         if not all(arg_decl.name == bad_kwarg for arg_decl in arg_decls):
-            raise ValueError(
-                f"{decl.name}() got an unexpected keyword argument {bad_kwarg!r}"
+            raise ClassiqValueError(
+                f"{decl_.name}() got an unexpected keyword argument {bad_kwarg!r}"
             )
         else:
-            raise ValueError(
-                f"{decl.name}() got multiple values for argument {bad_kwarg!r}"
+            raise ClassiqValueError(
+                f"{decl_.name}() got multiple values for argument {bad_kwarg!r}"
             )
     if arg_list:
-        raise ValueError(
-            f"{decl.name}() takes {len(arg_decls)} arguments but {len(args)} were given"
+        raise ClassiqValueError(
+            f"{decl_.name}() takes {len(arg_decls)} arguments but {len(args)} were given"
+        )
+    function_ident: Union[str, OperandIdentifier] = decl_.name
+    if index_ is not None:
+        function_ident = OperandIdentifier(
+            index=Expression(expr=str(index_)), name=function_ident
         )
 
-    return QuantumFunctionCall(function=decl.name, positional_args=prepared_args)
+    return QuantumFunctionCall(function=function_ident, positional_args=prepared_args)

classiq/qmod/quantum_function.py

@@ -11,10 +11,11 @@ from classiq.interface.model.quantum_function_declaration import (
 )
 
 from classiq.exceptions import ClassiqError
+from classiq.qmod.classical_function import CFunc
 from classiq.qmod.declaration_inferrer import infer_func_decl
 from classiq.qmod.qmod_parameter import QParam
 from classiq.qmod.qmod_variable import QVar
-from classiq.qmod.quantum_callable import QCallable
+from classiq.qmod.quantum_callable import QCallable, QCallableList
 from classiq.qmod.quantum_expandable import QExpandable, QTerminalCallable
 from classiq.qmod.utilities import mangle_keyword, unmangle_keyword
 
@@ -29,9 +30,10 @@ def create_model(
     constraints: Optional[Constraints] = None,
     execution_preferences: Optional[ExecutionPreferences] = None,
     preferences: Optional[Preferences] = None,
+    classical_execution_function: Optional[CFunc] = None,
 ) -> SerializedModel:
     return entry_point.create_model(
-        constraints, execution_preferences, preferences
+        constraints, execution_preferences, preferences, classical_execution_function
     ).get_model()
 
 
@@ -57,6 +59,7 @@ class QFunc(QExpandable):
         constraints: Optional[Constraints] = None,
         execution_preferences: Optional[ExecutionPreferences] = None,
         preferences: Optional[Preferences] = None,
+        classical_execution_function: Optional[CFunc] = None,
     ) -> Model:
         self._qmodule.type_decls = dict()
         self._qmodule.native_defs = dict()
@@ -66,9 +69,15 @@ class QFunc(QExpandable):
             ("execution_preferences", execution_preferences),
             ("preferences", preferences),
         ]
+        classical_execution_function = (
+            CFunc.default_cmain()
+            if classical_execution_function is None
+            else classical_execution_function
+        )
         return Model(
             functions=list(self._qmodule.native_defs.values()),
             types=list(self._qmodule.type_decls.values()),
+            classical_execution_code=classical_execution_function.code,
             **{key: value for key, value in model_extra_settings if value},
         )
 
@@ -116,6 +125,7 @@ def _validate_no_gen_params(annotations: Dict[str, Any]) -> None:
             name == "return"
             or get_origin(annotation) is QParam
             or (get_origin(annotation) or annotation) is QCallable
+            or (get_origin(annotation) or annotation) is QCallableList
             or QVar.from_type_hint(annotation) is not None
         )
     }