classiq 0.39.0__py3-none-any.whl → 0.40.0__py3-none-any.whl

classiq/qmod/qmod_parameter.py

@@ -26,21 +26,54 @@ _T = TypeVar("_T")
 
 
 if TYPE_CHECKING:
+    SymbolicSuperclass = SymbolicExpr
+else:
+    SymbolicSuperclass = Symbolic
 
-    class QParam(SymbolicExpr, Generic[_T]):
-        pass
 
-else:
+class CParam(SymbolicSuperclass):
+    pass
+
+
+class QParam(CParam, Generic[_T]):
+    pass
+
+
+class CInt(CParam):
+    pass
+
+
+class CReal(CParam):
+    pass
+
+
+class CBool(CParam):
+    pass
+
+
+_P = ParamSpec("_P")
+
+
+class ArrayBase(Generic[_P]):
+    # Support comma-separated generic args in older Python versions
+    if sys.version_info[0:2] < (3, 10):
+
+        def __class_getitem__(cls, args) -> _GenericAlias:
+            return _GenericAlias(cls, args)
+
+
+class CArray(CParam, ArrayBase[_P]):
+    if TYPE_CHECKING:
 
-    class QParam(Symbolic, Generic[_T]):
-        pass
+        @property
+        def len(self) -> int: ...
 
 
-class QParamScalar(QParam, SymbolicExpr):
+class CParamScalar(CParam, SymbolicExpr):
     pass
 
 
-class QParamList(QParam):
+class CParamList(CParam):
     def __init__(
         self,
         expr: str,
@@ -51,7 +84,7 @@ class QParamList(QParam):
         self._qmodule = qmodule
         self._list_type = list_type
 
-    def __getitem__(self, key: Any) -> QParam:
+    def __getitem__(self, key: Any) -> CParam:
         return create_param(
             f"({self})[{key}]",
             self._list_type.element_type,
@@ -64,11 +97,11 @@ class QParamList(QParam):
         )
 
     @property
-    def len(self) -> QParamScalar:
-        return QParamScalar(f"len({self})")
+    def len(self) -> CParamScalar:
+        return CParamScalar(f"get_field({self}, 'len')")
 
 
-class QParamStruct(QParam):
+class CParamStruct(CParam):
     def __init__(
         self, expr: str, struct_type: Struct, *, qmodule: ModelStateContainer
     ) -> None:
@@ -76,8 +109,8 @@ class QParamStruct(QParam):
         self._qmodule = qmodule
         self._struct_type = struct_type
 
-    def __getattr__(self, field_name: str) -> QParam:
-        return QParamStruct.get_field(
+    def __getattr__(self, field_name: str) -> CParam:
+        return CParamStruct.get_field(
             self._qmodule, str(self), self._struct_type.name, field_name
         )
 
@@ -87,7 +120,7 @@ class QParamStruct(QParam):
         variable_name: str,
         struct_name: str,
         field_name: str,
-    ) -> QParam:
+    ) -> CParam:
         struct_decl = StructDeclaration.BUILTIN_STRUCT_DECLARATIONS.get(
             struct_name, qmodule.type_decls.get(struct_name)
         )
@@ -105,27 +138,15 @@ class QParamStruct(QParam):
         )
 
 
-_P = ParamSpec("_P")
-
-
-class ArrayBase(Generic[_P]):
-    # Support comma-separated generic args in older Python versions
-    if sys.version_info[0:2] < (3, 10):
-
-        def __class_getitem__(cls, args) -> _GenericAlias:
-            return _GenericAlias(cls, args)
-
-
-class Array(ArrayBase[_P]):
-    pass
-
-
 def create_param(
     expr_str: str, ctype: ClassicalType, qmodule: ModelStateContainer
-) -> QParam:
+) -> CParam:
     if isinstance(ctype, (ClassicalList, ClassicalArray)):
-        return QParamList(expr_str, ctype, qmodule=qmodule)
+        return CParamList(expr_str, ctype, qmodule=qmodule)
     elif isinstance(ctype, Struct):
-        return QParamStruct(expr_str, ctype, qmodule=qmodule)
+        return CParamStruct(expr_str, ctype, qmodule=qmodule)
     else:
-        return QParamScalar(expr_str)
+        return CParamScalar(expr_str)
+
+
+Array = CArray

classiq/qmod/qmod_struct.py

@@ -3,7 +3,7 @@ from typing import Any, Type
 
 from typing_extensions import dataclass_transform
 
-from classiq.interface.generator.functions.classical_type import QStructBase
+from classiq.interface.generator.functions.classical_type import CStructBase
 
 
 def _qmod_val_to_expr_str(val: Any) -> str:
@@ -30,7 +30,7 @@ def struct(user_class: Type) -> Type:
 
     user_dataclass = type(
         user_class.__name__,
-        (QStructBase, dataclasses.dataclass(user_class)),
+        (CStructBase, dataclasses.dataclass(user_class)),
         dict(),
     )
     user_dataclass.__repr__ = _new_repr  # type:ignore[assignment]

classiq/qmod/qmod_variable.py

@@ -21,6 +21,7 @@ from typing import (  # type: ignore[attr-defined]
 
 from typing_extensions import Annotated, ParamSpec, Self, _AnnotatedAlias
 
+from classiq.interface.ast_node import SourceReference
 from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.generator.functions.port_declaration import (
     PortDeclarationDirection,
@@ -45,11 +46,11 @@ from classiq.interface.model.quantum_type import (
 )
 
 from classiq.exceptions import ClassiqValueError
-from classiq.qmod.qmod_parameter import ArrayBase, QParam, QParamScalar
+from classiq.qmod.qmod_parameter import ArrayBase, CBool, CInt, CParam, CParamScalar
 from classiq.qmod.quantum_callable import QCallable
 from classiq.qmod.symbolic_expr import Symbolic, SymbolicExpr
 from classiq.qmod.symbolic_type import SymbolicTypes
-from classiq.qmod.utilities import version_portable_get_args
+from classiq.qmod.utilities import get_source_ref, version_portable_get_args
 
 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"
@@ -82,8 +83,9 @@ def _no_current_expandable() -> Iterator[None]:
         QCallable.CURRENT_EXPANDABLE = current_expandable
 
 
-class QVar:
+class QVar(Symbolic):
     def __init__(self, name: str) -> None:
+        super().__init__(name)
         self._name = name
         if QCallable.CURRENT_EXPANDABLE is not None:
             QCallable.CURRENT_EXPANDABLE.add_local_handle(
@@ -120,6 +122,9 @@ class QVar:
         assert type_hint == cls or get_origin(type_hint) == cls
         return PortDeclarationDirection.Inout
 
+    def __str__(self) -> str:
+        return str(self.get_handle_binding())
+
 
 _Q = TypeVar("_Q", bound=QVar)
 Output = Annotated[_Q, PortDeclarationDirection.Output]
@@ -131,7 +136,9 @@ class QScalar(QVar, SymbolicExpr):
         QVar.__init__(self, name)
         SymbolicExpr.__init__(self, name)
 
-    def _insert_arith_operation(self, expr: SymbolicTypes, inplace: bool) -> None:
+    def _insert_arith_operation(
+        self, expr: SymbolicTypes, inplace: bool, source_ref: SourceReference
+    ) -> None:
         # Fixme: Arithmetic operations are not yet supported on slices (see CAD-12670)
         if TYPE_CHECKING:
             assert QCallable.CURRENT_EXPANDABLE is not None
@@ -140,16 +147,20 @@ class QScalar(QVar, SymbolicExpr):
                 expression=Expression(expr=str(expr)),
                 result_var=self.get_handle_binding(),
                 inplace_result=inplace,
+                source_ref=source_ref,
             )
         )
 
-    def _insert_amplitude_loading(self, expr: SymbolicTypes) -> None:
+    def _insert_amplitude_loading(
+        self, expr: SymbolicTypes, source_ref: SourceReference
+    ) -> None:
         if TYPE_CHECKING:
             assert QCallable.CURRENT_EXPANDABLE is not None
         QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
             AmplitudeLoadingOperation(
                 expression=Expression(expr=str(expr)),
                 result_var=self.get_handle_binding(),
+                source_ref=source_ref,
             )
         )
 
@@ -162,7 +173,7 @@ class QScalar(QVar, SymbolicExpr):
                 f"Invalid argument {other!r} for out-of-place arithmetic operation"
             )
 
-        self._insert_arith_operation(other, False)
+        self._insert_arith_operation(other, False, get_source_ref(sys._getframe(1)))
         return self
 
     def __ixor__(self, other: Any) -> Self:
@@ -171,7 +182,7 @@ class QScalar(QVar, SymbolicExpr):
                 f"Invalid argument {other!r} for in-place arithmetic operation"
             )
 
-        self._insert_arith_operation(other, True)
+        self._insert_arith_operation(other, True, get_source_ref(sys._getframe(1)))
         return self
 
     def __imul__(self, other: Any) -> Self:
@@ -180,7 +191,7 @@ class QScalar(QVar, SymbolicExpr):
                 f"Invalid argument {other!r} for out of ampltiude encoding operation"
             )
 
-        self._insert_amplitude_loading(other)
+        self._insert_amplitude_loading(other, get_source_ref(sys._getframe(1)))
         return self
 
 
@@ -207,18 +218,18 @@ class QNum(Generic[_P], QScalar):
     def __init__(
         self,
         name: str,
-        size: Union[int, QParam[int]],
-        is_signed: Union[bool, QParam[bool]],
-        fraction_digits: Union[int, QParam[int]],
+        size: Union[int, CInt],
+        is_signed: Union[bool, CBool],
+        fraction_digits: Union[int, CInt],
     ):
         pass
 
     def __init__(
         self,
         name: str,
-        size: Union[int, QParam[int], None] = None,
-        is_signed: Union[bool, QParam[bool], None] = None,
-        fraction_digits: Union[int, QParam[int], None] = None,
+        size: Union[int, CInt, None] = None,
+        is_signed: Union[bool, CBool, None] = None,
+        fraction_digits: Union[int, CInt, None] = None,
     ):
         if (
             size is None
@@ -244,8 +255,8 @@ class QNum(Generic[_P], QScalar):
         type_args = type_args[0]
         if len(type_args) != 3:
             raise ClassiqValueError(
-                "QNum receives three type arguments: QNum[size: int | QParam[int], "
-                "is_signed: bool | QParam[bool], fraction_digits: int | QParam[int]]"
+                "QNum receives three type arguments: QNum[size: int | CInt, "
+                "is_signed: bool | CBool, fraction_digits: int | CInt]"
             )
         return cls.QMOD_TYPE(
             size=Expression(expr=get_type_hint_expr(type_args[0])),
@@ -261,16 +272,16 @@ class QNum(Generic[_P], QScalar):
         )
 
     @property
-    def size(self) -> QParamScalar:
-        return QParamScalar(f"len({self._name})")
+    def size(self) -> CParamScalar:
+        return CParamScalar(f"get_field({self._name}, 'size')")
 
     @property
-    def fraction_digits(self) -> QParamScalar:
-        return QParamScalar(f"fraction_digits({self._name})")
+    def fraction_digits(self) -> CParamScalar:
+        return CParamScalar(f"get_field({self._name}, 'fraction_digits')")
 
     @property
-    def is_signed(self) -> QParamScalar:
-        return QParamScalar(f"is_signed({self._name})")
+    def is_signed(self) -> CParamScalar:
+        return CParamScalar(f"get_field({self._name}, 'is_signed')")
 
     # Support comma-separated generic args in older Python versions
     if sys.version_info[0:2] < (3, 10):
@@ -284,10 +295,10 @@ class QArray(ArrayBase[_P], QVar):
         self,
         name: str,
         element_type: _GenericAlias = QBit,
-        length: Optional[Union[int, QParam[int]]] = None,
+        length: Optional[Union[int, CInt]] = None,
         # TODO [CAD-18620]: improve type hints
         slice_: Optional[Tuple[int, int]] = None,
-        index_: Optional[Union[int, QParam[int]]] = None,
+        index_: Optional[Union[int, CInt]] = None,
     ) -> None:
         if element_type is not QBit:
             raise ClassiqValueError(UNSUPPORTED_ELEMENT_TYPE)
@@ -313,7 +324,7 @@ class QArray(ArrayBase[_P], QVar):
 
         return HandleBinding(name=self._name)
 
-    def __getitem__(self, key: Union[slice, int, QParam]) -> "QArray":
+    def __getitem__(self, key: Union[slice, int, CInt]) -> "QArray":
         if self._index is not None:
             raise ClassiqValueError(QARRAY_ELEMENT_NOT_SUBSCRIPTABLE)
 
@@ -326,7 +337,7 @@ class QArray(ArrayBase[_P], QVar):
             new_slice = self._get_new_slice(key.start, key.stop)
 
         else:
-            if isinstance(key, QParam) and not isinstance(key, QParamScalar):
+            if isinstance(key, CParam) and not isinstance(key, CParamScalar):
                 raise ClassiqValueError("Non-classical parameter for slicing")
             new_slice = self._get_new_slice(key, key + 1)
             new_index = new_slice[0]
@@ -368,10 +379,10 @@ class QArray(ArrayBase[_P], QVar):
     else:
 
         @property
-        def len(self) -> QParamScalar:
+        def len(self) -> CParamScalar:
             if self._length is not None:
-                return QParamScalar(f"{self._length}")
-            return QParamScalar(f"len({self._name})")
+                return CParamScalar(f"{self._length}")
+            return CParamScalar(f"get_field({self._name}, 'len')")
 
     @classmethod
     def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:

classiq/qmod/quantum_callable.py

@@ -12,6 +12,7 @@ from typing import (  # type: ignore[attr-defined]
 
 from typing_extensions import ParamSpec
 
+from classiq.interface.ast_node import SourceReference
 from classiq.interface.model.quantum_function_call import QuantumFunctionCall
 from classiq.interface.model.quantum_function_declaration import (
     QuantumFunctionDeclaration,
@@ -19,7 +20,8 @@ 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
+from classiq.qmod.qmod_parameter import CInt
+from classiq.qmod.utilities import get_source_ref
 
 if TYPE_CHECKING:
     from classiq.qmod.quantum_expandable import QTerminalCallable
@@ -42,8 +44,9 @@ class QCallable(Generic[P], ABC):
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:
         assert QCallable.CURRENT_EXPANDABLE is not None
+        source_ref = get_source_ref(sys._getframe(1))
         QCallable.CURRENT_EXPANDABLE.append_statement_to_body(
-            self.create_quantum_function_call(*args, **kwargs)
+            self.create_quantum_function_call(source_ref, *args, **kwargs)
         )
         return
 
@@ -60,7 +63,7 @@ class QCallable(Generic[P], ABC):
 
     @abstractmethod
     def create_quantum_function_call(
-        self, *args: Any, **kwargs: Any
+        self, source_ref_: SourceReference, *args: Any, **kwargs: Any
     ) -> QuantumFunctionCall:
         raise NotImplementedError()
 
@@ -71,5 +74,5 @@ class QCallableList(QCallable, Generic[P], ABC):
         @property
         def len(self) -> int: ...
 
-        def __getitem__(self, key: Union[slice, int, QParam]) -> "QTerminalCallable":
+        def __getitem__(self, key: Union[slice, int, CInt]) -> "QTerminalCallable":
             raise NotImplementedError()

classiq/qmod/quantum_expandable.py

@@ -17,6 +17,7 @@ from typing import (
 
 from typing_extensions import Self
 
+from classiq.interface.ast_node import SourceReference
 from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.model.classical_parameter_declaration import (
     ClassicalParameterDeclaration,
@@ -42,12 +43,12 @@ from classiq.interface.model.variable_declaration_statement import (
 from classiq.exceptions import ClassiqValueError
 from classiq.qmod.model_state_container import QMODULE, ModelStateContainer
 from classiq.qmod.qmod_constant import QConstant
-from classiq.qmod.qmod_parameter import QParam, QParamScalar, create_param
+from classiq.qmod.qmod_parameter import CInt, CParam, CParamScalar, 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
 
-ArgType = Union[QParam, QVar, QCallable]
+ArgType = Union[CParam, QVar, QCallable]
 
 
 class QExpandable(QCallable, QExpandableInterface, ABC):
@@ -109,9 +110,11 @@ class QExpandable(QCallable, QExpandableInterface, ABC):
         return result
 
     def create_quantum_function_call(
-        self, *args: Any, **kwargs: Any
+        self, source_ref_: SourceReference, *args: Any, **kwargs: Any
     ) -> QuantumFunctionCall:
-        return _create_quantum_function_call(self.func_decl, None, *args, **kwargs)
+        return _create_quantum_function_call(
+            self.func_decl, None, source_ref_, *args, **kwargs
+        )
 
 
 class QLambdaFunction(QExpandable):
@@ -138,7 +141,7 @@ class QTerminalCallable(QCallable):
     def __init__(
         self,
         decl: QuantumFunctionDeclaration,
-        index_: Optional[Union[int, QParamScalar]] = None,
+        index_: Optional[Union[int, CParamScalar]] = None,
     ) -> None:
         self._decl = decl
         self._index = index_
@@ -147,12 +150,12 @@ class QTerminalCallable(QCallable):
     def is_list(self) -> bool:
         return isinstance(self._decl, QuantumOperandDeclaration) and self._decl.is_list
 
-    def __getitem__(self, key: Union[slice, int, QParam]) -> "QTerminalCallable":
+    def __getitem__(self, key: Union[slice, int, CInt]) -> "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):
+        if isinstance(key, CParam) and not isinstance(key, CParamScalar):
             raise ClassiqValueError("Non-classical parameter for slicing")
         return QTerminalCallable(self._decl, key)
 
@@ -169,24 +172,24 @@ class QTerminalCallable(QCallable):
     else:
 
         @property
-        def len(self) -> QParamScalar:
+        def len(self) -> CParamScalar:
             if not self.is_list:
                 raise ClassiqValueError("Cannot get length of a non-list operand")
-            return QParamScalar(f"len({self.func_decl.name})")
+            return CParamScalar(f"{self.func_decl.name}.len")
 
     @property
     def func_decl(self) -> QuantumFunctionDeclaration:
         return self._decl
 
     def create_quantum_function_call(
-        self, *args: Any, **kwargs: Any
+        self, source_ref_: SourceReference, *args: Any, **kwargs: Any
     ) -> QuantumFunctionCall:
         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
+            self.func_decl, self._index, source_ref_, *args, **kwargs
         )
 
 
@@ -278,7 +281,8 @@ def _prepare_args(
 
 def _create_quantum_function_call(
     decl_: QuantumFunctionDeclaration,
-    index_: Optional[Union[QParamScalar, int]] = None,
+    index_: Optional[Union[CParamScalar, int]] = None,
+    source_ref_: Optional[SourceReference] = None,
     *args: Any,
     **kwargs: Any,
 ) -> QuantumFunctionCall:
@@ -306,4 +310,6 @@ def _create_quantum_function_call(
             index=Expression(expr=str(index_)), name=function_ident
         )
 
-    return QuantumFunctionCall(function=function_ident, positional_args=prepared_args)
+    return QuantumFunctionCall(
+        function=function_ident, positional_args=prepared_args, source_ref=source_ref_
+    )

classiq/qmod/quantum_function.py

@@ -1,8 +1,11 @@
 import ast
 import functools
+import warnings
+from inspect import isclass
 from typing import Any, Callable, Dict, List, Optional, Tuple, get_origin
 
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.functions.classical_type import CStructBase
 from classiq.interface.generator.model.constraints import Constraints
 from classiq.interface.generator.model.preferences.preferences import Preferences
 from classiq.interface.model.model import Model, SerializedModel
@@ -15,7 +18,7 @@ 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_constant import QConstant
-from classiq.qmod.qmod_parameter import QParam
+from classiq.qmod.qmod_parameter import CArray, CParam, QParam
 from classiq.qmod.qmod_variable import QVar
 from classiq.qmod.quantum_callable import QCallable, QCallableList
 from classiq.qmod.quantum_expandable import QExpandable, QTerminalCallable
@@ -46,6 +49,18 @@ def create_model(
 class QFunc(QExpandable):
     def __init__(self, py_callable: Callable) -> None:
         _validate_no_gen_params(py_callable.__annotations__)
+        if any(
+            get_origin(annotation) == QParam
+            for annotation in py_callable.__annotations__.values()
+        ):
+            warnings.warn(
+                "QParam is deprecated and will be removed in a future release. Use the "
+                "new classical parameter types instead:\n    * QParam[int] -> CInt\n    * QParam[float] "
+                "-> CReal\n    * QParam[bool] -> CBool\n    * QParam[list[int]] -> "
+                "CArray[CInt]",
+                category=DeprecationWarning,
+                stacklevel=4,
+            )
         super().__init__(py_callable)
         functools.update_wrapper(self, py_callable)
 
@@ -144,7 +159,10 @@ ILLEGAL_PARAM_ERROR = "Unsupported type hint '{annotation}' for argument '{name}
 
 
 class IllegalParamsError(ClassiqError):
-    _HINT = "\nNote - QMOD functions can declare classical parameters using the type hint 'QParam'."
+    _HINT = (
+        "\nNote - QMOD functions can declare classical parameters using the type hints "
+        "'CInt', 'CReal', 'CBool', and 'CArray'."
+    )
 
     def __init__(self, message: str) -> None:
         super().__init__(message + self._HINT)
@@ -157,6 +175,11 @@ def _validate_no_gen_params(annotations: Dict[str, Any]) -> None:
         if not (
             name == "return"
             or get_origin(annotation) is QParam
+            or isclass(annotation)
+            and issubclass(annotation, CParam)
+            or isclass(annotation)
+            and issubclass(annotation, CStructBase)
+            or get_origin(annotation) is CArray
             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