classiq 0.69.0__py3-none-any.whl → 0.71.0__py3-none-any.whl

classiq/qmod/qmod_variable.py

@@ -10,20 +10,22 @@ from typing import (  # type: ignore[attr-defined]
     Generic,
     Literal,
     Optional,
+    Protocol,
     TypeVar,
     Union,
     _GenericAlias,
     cast,
     get_args,
     get_origin,
+    runtime_checkable,
 )
 
 from typing_extensions import ParamSpec, Self, _AnnotatedAlias
 
-from classiq.interface.exceptions import ClassiqValueError
+from classiq.interface.exceptions import ClassiqInternalError, ClassiqValueError
 from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.generator.expressions.non_symbolic_expr import NonSymbolicExpr
-from classiq.interface.generator.expressions.qmod_qarray_proxy import (
+from classiq.interface.generator.expressions.proxies.quantum.qmod_qarray_proxy import (
     ILLEGAL_SLICE_MSG,
     ILLEGAL_SLICING_STEP_MSG,
 )
@@ -31,6 +33,7 @@ from classiq.interface.generator.functions.port_declaration import (
     PortDeclarationDirection,
 )
 from classiq.interface.generator.functions.type_name import TypeName
+from classiq.interface.generator.functions.type_qualifier import TypeQualifier
 from classiq.interface.generator.types.qstruct_declaration import QStructDeclaration
 from classiq.interface.model.handle_binding import (
     FieldHandleBinding,
@@ -72,21 +75,6 @@ from classiq.qmod.utilities import (
 )
 
 
-def _is_input_output_typehint(type_hint: Any) -> bool:
-    return isinstance(type_hint, _AnnotatedAlias) and isinstance(
-        type_hint.__metadata__[0], PortDeclarationDirection
-    )
-
-
-def get_type_hint_expr(type_hint: Any) -> str:
-    if isinstance(type_hint, ForwardRef):  # expression in string literal
-        return str(type_hint.__forward_arg__)
-    if get_origin(type_hint) == Literal:  # explicit numeric literal
-        return str(get_args(type_hint)[0])
-    else:
-        return str(type_hint)  # implicit numeric literal
-
-
 @contextmanager
 def _no_current_expandable() -> Iterator[None]:
     current_expandable = QCallable.CURRENT_EXPANDABLE
@@ -141,23 +129,6 @@ class QVar(Symbolic):
     def get_qmod_type(self) -> QuantumType:
         raise NotImplementedError()
 
-    @staticmethod
-    def from_type_hint(type_hint: Any) -> Optional[type["QVar"]]:
-        if _is_input_output_typehint(type_hint):
-            return QVar.from_type_hint(type_hint.__args__[0])
-        type_ = get_origin(type_hint) or type_hint
-        if issubclass(type_, QVar):
-            if issubclass(type_, QStruct):
-                with _no_current_expandable():
-                    type_("DUMMY")._add_qmod_qstruct(qmodule=QMODULE)
-            return type_
-        return None
-
-    @classmethod
-    @abc.abstractmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
-        raise NotImplementedError()
-
     @classmethod
     @abc.abstractmethod
     def to_qvar(
@@ -168,14 +139,6 @@ class QVar(Symbolic):
     ) -> Self:
         raise NotImplementedError()
 
-    @classmethod
-    def port_direction(cls, type_hint: Any) -> PortDeclarationDirection:
-        if _is_input_output_typehint(type_hint):
-            assert len(type_hint.__metadata__) >= 1
-            return type_hint.__metadata__[0]
-        assert type_hint == cls or get_origin(type_hint) == cls
-        return PortDeclarationDirection.Inout
-
     def __str__(self) -> str:
         return self._expr_str
 
@@ -194,6 +157,12 @@ class QVar(Symbolic):
 _Q = TypeVar("_Q", bound=QVar)
 Output = Annotated[_Q, PortDeclarationDirection.Output]
 Input = Annotated[_Q, PortDeclarationDirection.Input]
+Const = Annotated[
+    _Q, TypeQualifier.Const
+]  # A constant variable, up to a phase dependent on the computational basis state
+QFree = Annotated[
+    _Q, TypeQualifier.QFree
+]  # A quantum free variable, up to a phase dependent on the computational basis state
 
 
 class QScalar(QVar, SymbolicExpr):
@@ -285,10 +254,6 @@ class QScalar(QVar, SymbolicExpr):
 
 
 class QBit(QScalar):
-    @classmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
-        return QuantumBit()
-
     @classmethod
     def to_qvar(
         cls,
@@ -345,43 +310,6 @@ class QNum(Generic[_P], QScalar):
         )
         super().__init__(name, _expr_str=_expr_str, depth=3)
 
-    @classmethod
-    def _get_attributes(cls, type_hint: Any) -> tuple[Any, Any, Any]:
-        type_args = version_portable_get_args(type_hint)
-        if len(type_args) == 0:
-            return None, None, None
-        if len(type_args) not in (1, 3):
-            raise ClassiqValueError(
-                "QNum receives three type arguments: QNum[size: int | CInt, "
-                "is_signed: bool | CBool, fraction_digits: int | CInt]"
-            )
-        if len(type_args) == 1:
-            return unwrap_forward_ref(type_args[0]), None, None
-        return (
-            unwrap_forward_ref(type_args[0]),
-            unwrap_forward_ref(type_args[1]),
-            unwrap_forward_ref(type_args[2]),
-        )
-
-    @classmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
-        size, is_signed, fraction_digits = cls._get_attributes(type_hint)
-        return QuantumNumeric(
-            size=(
-                Expression(expr=get_type_hint_expr(size)) if size is not None else None
-            ),
-            is_signed=(
-                Expression(expr=get_type_hint_expr(is_signed))
-                if is_signed is not None
-                else None
-            ),
-            fraction_digits=(
-                Expression(expr=get_type_hint_expr(fraction_digits))
-                if fraction_digits is not None
-                else None
-            ),
-        )
-
     @classmethod
     def to_qvar(
         cls,
@@ -389,7 +317,7 @@ class QNum(Generic[_P], QScalar):
         type_hint: Any,
         expr_str: Optional[str],
     ) -> "QNum":
-        return QNum(origin, *cls._get_attributes(type_hint), _expr_str=expr_str)
+        return QNum(origin, *_get_qnum_attributes(type_hint), _expr_str=expr_str)
 
     def get_qmod_type(self) -> QuantumType:
         return QuantumNumeric(
@@ -497,36 +425,6 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
                     return interpret_expression(str(self.len))
             return CParamScalar(f"get_field({self}, 'len')")
 
-    @classmethod
-    def _get_attributes(cls, type_hint: Any) -> tuple[type[QVar], Any]:
-        type_args = version_portable_get_args(type_hint)
-        if len(type_args) == 0:
-            return QBit, None
-        first_arg = unwrap_forward_ref(type_args[0])
-        if len(type_args) == 1:
-            if isinstance(first_arg, (str, int)):
-                return QBit, first_arg
-            return first_arg, None
-        if len(type_args) != 2:
-            raise ClassiqValueError(
-                "QArray receives two type arguments: QArray[element_type: QVar, "
-                "length: int | CInt]"
-            )
-        second_arg = unwrap_forward_ref(type_args[1])
-        return cast(tuple[type[QVar], Any], (first_arg, second_arg))
-
-    @classmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
-        api_element_type, length = cls._get_attributes(type_hint)
-        api_element_class = get_origin(api_element_type) or api_element_type
-        element_type = api_element_class.to_qmod_quantum_type(api_element_type)
-
-        length_expr: Optional[Expression] = None
-        if length is not None:
-            length_expr = Expression(expr=get_type_hint_expr(length))
-
-        return QuantumBitvector(element_type=element_type, length=length_expr)
-
     @classmethod
     def to_qvar(
         cls,
@@ -534,16 +432,15 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
         type_hint: Any,
         expr_str: Optional[str],
     ) -> "QArray":
-        return QArray(origin, *cls._get_attributes(type_hint), _expr_str=expr_str)
+        return QArray(origin, *_get_qarray_attributes(type_hint), _expr_str=expr_str)
 
     def get_qmod_type(self) -> QuantumBitvector:
-        if isinstance(self._element_type, QuantumType):
-            element_type = self._element_type
-        else:
-            element_class = get_origin(self._element_type) or self._element_type
-            element_type = element_class.to_qmod_quantum_type(self._element_type)
         return QuantumBitvector(
-            element_type=element_type,
+            element_type=(
+                self._element_type
+                if isinstance(self._element_type, QuantumType)
+                else _to_quantum_type(self._element_type)
+            ),
             length=self._length,
         )
 
@@ -561,6 +458,7 @@ class QStruct(QVar):
         _fields: Optional[Mapping[str, QVar]] = None,
         _expr_str: Optional[str] = None,
     ) -> None:
+        _register_qstruct(type(self), qmodule=QMODULE)
         name = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
         if _struct_name is None or _fields is None:
             with _no_current_expandable():
@@ -572,17 +470,10 @@ class QStruct(QVar):
         for field_name, var in _fields.items():
             setattr(self, field_name, var)
         super().__init__(name, expr_str=_expr_str)
-        self._add_qmod_qstruct(qmodule=QMODULE)
 
     def get_qmod_type(self) -> QuantumType:
         return TypeName(name=self._struct_name)
 
-    @classmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
-        with _no_current_expandable():
-            type_hint("DUMMY")
-        return TypeName(name=type_hint.__name__)
-
     @classmethod
     def to_qvar(
         cls,
@@ -591,24 +482,13 @@ class QStruct(QVar):
         expr_str: Optional[str],
     ) -> "QStruct":
         field_types = {
-            field_name: (QVar.from_type_hint(field_type), field_type)
+            field_name: (_get_root_type(field_type), field_type)
             for field_name, field_type in type_hint.__annotations__.items()
         }
-        illegal_fields = [
-            (field_name, field_type)
-            for field_name, (field_class, field_type) in field_types.items()
-            if field_class is None
-        ]
-        if len(illegal_fields) > 0:
-            raise ClassiqValueError(
-                f"Field {illegal_fields[0][0]!r} of quantum struct "
-                f"{type_hint.__name__} has a non-quantum type "
-                f"{illegal_fields[0][1].__name__}."
-            )
         base_handle = HandleBinding(name=origin) if isinstance(origin, str) else origin
         with _no_current_expandable():
             field_vars = {
-                field_name: cast(type[QVar], field_class).to_qvar(
+                field_name: field_class.to_qvar(
                     FieldHandleBinding(base_handle=base_handle, field=field_name),
                     field_type,
                     f"get_field({expr_str if expr_str is not None else str(origin)}, '{field_name}')",
@@ -622,16 +502,6 @@ class QStruct(QVar):
             _expr_str=expr_str,
         )
 
-    def _add_qmod_qstruct(self, *, qmodule: ModelStateContainer) -> None:
-        if self._struct_name in qmodule.qstruct_decls:
-            return
-
-        struct_decl = QStructDeclaration(
-            name=self._struct_name,
-            fields={name: qvar.get_qmod_type() for name, qvar in self._fields.items()},
-        )
-        qmodule.qstruct_decls[self._struct_name] = struct_decl
-
 
 def create_qvar_for_port_decl(port: AnonPortDeclaration, name: str) -> QVar:
     return _create_qvar_for_qtype(port.quantum_type, HandleBinding(name=name))
@@ -691,3 +561,171 @@ def get_qvar(qtype: QuantumType, origin: HandleBinding) -> "QVar":
             },
         )
     raise NotImplementedError
+
+
+def get_port_from_type_hint(
+    py_type: Any,
+) -> tuple[QuantumType, PortDeclarationDirection, TypeQualifier]:
+    direction = PortDeclarationDirection.Inout  # default
+    qualifier = TypeQualifier.Quantum  # default
+
+    if isinstance(py_type, _AnnotatedAlias):
+        quantum_type = _to_quantum_type(py_type.__origin__)
+        for metadata in py_type.__metadata__:
+            if isinstance(metadata, PortDeclarationDirection):
+                direction = metadata
+            elif isinstance(metadata, TypeQualifier):
+                qualifier = metadata
+    else:
+        quantum_type = _to_quantum_type(py_type)
+
+    return quantum_type, direction, qualifier
+
+
+def _to_quantum_type(py_type: Any) -> QuantumType:
+    root_type = _get_root_type(py_type)
+    if not issubclass(root_type, QVar):
+        raise ClassiqInternalError(f"Invalid quantum type {py_type}")
+    if issubclass(root_type, QBit):
+        return QuantumBit()
+    elif issubclass(root_type, QNum):
+        return _get_quantum_numeric(py_type)
+    elif issubclass(root_type, QArray):
+        return _get_quantum_bit_vector(py_type)
+    elif issubclass(root_type, QStruct):
+        return _get_quantum_struct(py_type)
+    else:
+        raise ClassiqInternalError(f"Invalid quantum type {py_type}")
+
+
+def _get_quantum_numeric(type_hint: type[QNum]) -> QuantumNumeric:
+    size, is_signed, fraction_digits = _get_qnum_attributes(type_hint)
+    return QuantumNumeric(
+        size=(Expression(expr=_get_type_hint_expr(size)) if size is not None else None),
+        is_signed=(
+            Expression(expr=_get_type_hint_expr(is_signed))
+            if is_signed is not None
+            else None
+        ),
+        fraction_digits=(
+            Expression(expr=_get_type_hint_expr(fraction_digits))
+            if fraction_digits is not None
+            else None
+        ),
+    )
+
+
+def _get_qnum_attributes(type_hint: type[QNum]) -> tuple[Any, Any, Any]:
+    type_args = version_portable_get_args(type_hint)
+    if len(type_args) == 0:
+        return None, None, None
+    if len(type_args) not in (1, 3):
+        raise ClassiqValueError(
+            "QNum receives three type arguments: QNum[size: int | CInt, "
+            "is_signed: bool | CBool, fraction_digits: int | CInt]"
+        )
+    if len(type_args) == 1:
+        return unwrap_forward_ref(type_args[0]), None, None
+    return (
+        unwrap_forward_ref(type_args[0]),
+        unwrap_forward_ref(type_args[1]),
+        unwrap_forward_ref(type_args[2]),
+    )
+
+
+def _get_qarray_attributes(type_hint: type[QArray]) -> tuple[Any, Any]:
+    type_args = version_portable_get_args(type_hint)
+    if len(type_args) == 0:
+        return QBit, None
+    first_arg = unwrap_forward_ref(type_args[0])
+    if len(type_args) == 1:
+        if isinstance(first_arg, (str, int)):
+            return QBit, first_arg
+        return first_arg, None
+    if len(type_args) != 2:
+        raise ClassiqValueError(
+            "QArray receives two type arguments: QArray[element_type: QVar, "
+            "length: int | CInt]"
+        )
+    second_arg = unwrap_forward_ref(type_args[1])
+    return cast(tuple[type[QVar], Any], (first_arg, second_arg))
+
+
+def _get_quantum_bit_vector(type_hint: type[QArray]) -> QuantumBitvector:
+    api_element_type, length = _get_qarray_attributes(type_hint)
+    element_type = _to_quantum_type(api_element_type)
+
+    length_expr: Expression | None = None
+    if length is not None:
+        length_expr = Expression(expr=_get_type_hint_expr(length))
+
+    return QuantumBitvector(element_type=element_type, length=length_expr)
+
+
+def _get_quantum_struct(type_hint: type[QStruct]) -> TypeName:
+    _register_qstruct(type_hint, qmodule=QMODULE)
+    return TypeName(name=type_hint.__name__)
+
+
+def _register_qstruct(
+    type_hint: type[QStruct], *, qmodule: ModelStateContainer
+) -> None:
+    struct_name = type_hint.__name__
+    if type_hint is QStruct or struct_name in qmodule.qstruct_decls:
+        return
+
+    _validate_fields(type_hint)
+    struct_decl = QStructDeclaration(
+        name=struct_name,
+        fields={
+            field_name: _to_quantum_type(field_type)
+            for field_name, field_type in type_hint.__annotations__.items()
+        },
+    )
+    qmodule.qstruct_decls[struct_name] = struct_decl
+
+
+def _validate_fields(type_hint: type[QStruct]) -> None:
+    field_types = {
+        field_name: (_get_root_type(field_type), field_type)
+        for field_name, field_type in type_hint.__annotations__.items()
+    }
+    illegal_fields = [
+        (field_name, field_type)
+        for field_name, (field_class, field_type) in field_types.items()
+        if field_class is None
+    ]
+    if len(illegal_fields) > 0:
+        raise ClassiqValueError(
+            f"Field {illegal_fields[0][0]!r} of quantum struct "
+            f"{type_hint.__name__} has a non-quantum type "
+            f"{illegal_fields[0][1].__name__}."
+        )
+
+
+@runtime_checkable
+class _ModelConstant(Protocol):
+    # Applies to QConstant
+    def add_to_model(self) -> None: ...
+
+
+def _get_type_hint_expr(type_hint: Any) -> str:
+    if isinstance(type_hint, ForwardRef):  # expression in string literal
+        return str(type_hint.__forward_arg__)
+    if get_origin(type_hint) == Literal:  # explicit numeric literal
+        return str(get_args(type_hint)[0])
+    if isinstance(
+        type_hint, _ModelConstant
+    ):  # the Protocol is to prevent circular imports
+        type_hint.add_to_model()
+    return str(type_hint)  # implicit numeric literal
+
+
+def _get_root_type(py_type: Any) -> type[QVar]:
+    non_annotated_type = (
+        py_type.__origin__ if isinstance(py_type, _AnnotatedAlias) else py_type
+    )
+    root_type = get_origin(non_annotated_type) or non_annotated_type
+    if not issubclass(root_type, QVar):
+        raise ClassiqInternalError(f"Invalid quantum type {root_type}")
+    return root_type

classiq/qmod/quantum_function.py

@@ -25,11 +25,10 @@ from classiq.interface.model.quantum_function_declaration import (
 
 from classiq.qmod.classical_function import CFunc
 from classiq.qmod.cparam import CParamAbstract
-from classiq.qmod.declaration_inferrer import infer_func_decl
+from classiq.qmod.declaration_inferrer import infer_func_decl, is_qvar
 from classiq.qmod.generative import set_frontend_interpreter
 from classiq.qmod.qmod_constant import QConstant
 from classiq.qmod.qmod_parameter import CArray
-from classiq.qmod.qmod_variable import QVar
 from classiq.qmod.quantum_callable import QCallable, QCallableList
 from classiq.qmod.quantum_expandable import QExpandable, QTerminalCallable
 from classiq.qmod.semantics.annotation.qstruct_annotator import QStructAnnotator
@@ -57,7 +56,7 @@ class BaseQFunc(QExpandable):
         )
 
     def update_compilation_metadata(self, **kwargs: Any) -> None:
-        if kwargs["should_synthesize_separately"] and self._has_inputs:
+        if kwargs.get("should_synthesize_separately") and self._has_inputs:
             raise ClassiqError("Can't synthesize separately a function with inputs")
         self.compilation_metadata = self._compilation_metadata.model_copy(update=kwargs)
 
@@ -315,7 +314,7 @@ def _validate_no_gen_params(annotations: dict[str, Any]) -> None:
             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
+            or is_qvar(annotation)
         )
     }
     if _illegal_params:

classiq/qmod/semantics/annotation/call_annotation.py

@@ -3,18 +3,9 @@ from contextlib import contextmanager
 from typing import Any, Optional
 
 from classiq.interface.exceptions import ClassiqError
-from classiq.interface.generator.expressions.expression import Expression
-from classiq.interface.generator.functions.classical_type import Integer
-from classiq.interface.generator.functions.port_declaration import (
-    PortDeclarationDirection,
-)
-from classiq.interface.model.classical_parameter_declaration import (
-    ClassicalParameterDeclaration,
-)
 from classiq.interface.model.model import Model
 from classiq.interface.model.model_visitor import ModelVisitor
 from classiq.interface.model.native_function_definition import NativeFunctionDefinition
-from classiq.interface.model.port_declaration import PortDeclaration
 from classiq.interface.model.quantum_function_call import QuantumFunctionCall
 from classiq.interface.model.quantum_function_declaration import (
     AnonQuantumOperandDeclaration,
@@ -24,36 +15,17 @@ from classiq.interface.model.quantum_function_declaration import (
 from classiq.interface.model.quantum_lambda_function import (
     QuantumLambdaFunction,
 )
-from classiq.interface.model.quantum_type import QuantumBitvector
 
 from classiq.qmod.builtins.functions import BUILTIN_FUNCTION_DECLARATIONS
 from classiq.qmod.semantics.annotation.qstruct_annotator import QStructAnnotator
 from classiq.qmod.semantics.error_manager import ErrorManager
 from classiq.qmod.semantics.lambdas import get_renamed_parameters
 
-ALLOCATE_DECL_FOR_COMPATIBILITY = QuantumFunctionDeclaration(
-    name="allocate",
-    positional_arg_declarations=[
-        ClassicalParameterDeclaration(
-            name="num_qubits",
-            classical_type=Integer(),
-        ),
-        PortDeclaration(
-            name="out",
-            quantum_type=QuantumBitvector(length=Expression(expr="num_qubits")),
-            direction=PortDeclarationDirection.Output,
-        ),
-    ],
-)
-
 
 def _annotate_function_call_decl(
     fc: QuantumFunctionCall,
     function_dict: Mapping[str, QuantumFunctionDeclaration],
 ) -> None:
-    if fc.function == "allocate":  # FIXME: Remove compatibility (CAD-25935)
-        fc.set_func_decl(ALLOCATE_DECL_FOR_COMPATIBILITY)
-        return
     if fc._func_decl is None:
         func_decl = function_dict.get(fc.func_name)
         if func_decl is None:

classiq/qmod/semantics/annotation/qstruct_annotator.py

@@ -9,8 +9,18 @@ class QStructAnnotator(ModelVisitor):
         self._visited: set[TypeName] = set()
 
     def visit_TypeName(self, type_name: TypeName) -> None:
+        self._annotate_quantum_struct(type_name)
+        self._annotate_classical_struct(type_name)
+
+    def _annotate_quantum_struct(self, type_name: TypeName) -> None:
+        if (
+            type_name.has_classical_struct_decl
+            or type_name.has_fields
+            or type_name in self._visited
+        ):
+            return
         decl = QMODULE.qstruct_decls.get(type_name.name)
-        if decl is None or type_name.has_fields or (type_name in self._visited):
+        if decl is None:
             return
         self._visited.add(type_name)
         new_fields = {
@@ -21,3 +31,13 @@ class QStructAnnotator(ModelVisitor):
         # qstructs
         self.visit(new_fields)
         type_name.set_fields(new_fields)
+
+    def _annotate_classical_struct(self, type_name: TypeName) -> None:
+        if type_name.has_classical_struct_decl or type_name.has_fields:
+            return
+        decl = QMODULE.type_decls.get(type_name.name)
+        if decl is None:
+            return
+        type_name.set_classical_struct_decl(decl)
+        for field_type in decl.variables.values():
+            self.visit(field_type)

classiq/qmod/semantics/validation/main_validation.py

@@ -25,7 +25,7 @@ def _validate_main_classical_param_type(
 ) -> None:
     if isinstance(param, ClassicalList):
         raise ClassiqExpansionError(
-            f"Classical array parameter {param_name!r} of function 'main' must must "
+            f"Classical array parameter {param_name!r} of function 'main' must "
             f"specify array length",
         )
     if isinstance(param, ClassicalArray):

classiq/qmod/semantics/validation/type_hints.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from typing_extensions import _AnnotatedAlias
+
+from classiq.interface.exceptions import ClassiqValueError
+from classiq.interface.generator.functions.port_declaration import (
+    PortDeclarationDirection,
+)
+from classiq.interface.generator.functions.type_qualifier import TypeQualifier
+
+
+def validate_annotation(type_hint: Any) -> None:
+    if not isinstance(type_hint, _AnnotatedAlias):
+        return
+    directions: list[PortDeclarationDirection] = [
+        direction
+        for direction in type_hint.__metadata__
+        if isinstance(direction, PortDeclarationDirection)
+    ]
+    qualifiers: list[TypeQualifier] = [
+        qualifier
+        for qualifier in type_hint.__metadata__
+        if isinstance(qualifier, TypeQualifier)
+    ]
+    if len(directions) <= 1 and len(qualifiers) <= 1:
+        return
+    error_message = ""
+    if len(directions) > 1:
+        error_message += (
+            f"Multiple directions are not allowed in a single type hint: "
+            f"[{', '.join(direction.name for direction in reversed(directions))}]\n"
+        )
+    if len(qualifiers) > 1:
+        error_message += (
+            f"Multiple qualifiers are not allowed in a single type hint: "
+            f"[{', '.join(qualifier.name for qualifier in reversed(qualifiers))}]\n"
+        )
+    raise ClassiqValueError(error_message)

classiq/qmod/utilities.py

@@ -3,6 +3,7 @@ import inspect
 import itertools
 import keyword
 import sys
+from collections import Counter
 from collections.abc import Iterable
 from enum import Enum as PythonEnum
 from types import FrameType
@@ -21,7 +22,7 @@ from typing import (
 
 from typing_extensions import ParamSpec
 
-from classiq.interface.generator.expressions.qmod_struct_instance import (
+from classiq.interface.generator.expressions.proxies.classical.qmod_struct_instance import (
     QmodStructInstance,
 )
 from classiq.interface.source_reference import SourceReference
@@ -160,3 +161,39 @@ def suppress_return_value(func: Callable[Params, None]) -> Callable[Params, None
 
 
 Statements = Union[None, list[Union[None, "QVar"]], tuple[Union[None, "QVar"], ...]]
+
+
+def _eval_qnum(val: int, size: int, is_signed: bool, fraction_digits: int) -> float:
+    if val < 0 or val >= 2**size:
+        raise ValueError
+    if size == 1 and is_signed and fraction_digits == 1:
+        return -0.5 if val == 1 else 0
+    if is_signed and val & (1 << (size - 1)) > 0:
+        val ^= 1 << (size - 1)
+        val -= 1 << (size - 1)
+    return val * 2**-fraction_digits
+
+
+def qnum_values(size: int, is_signed: bool, fraction_digits: int) -> list[float]:
+    return [_eval_qnum(i, size, is_signed, fraction_digits) for i in range(2**size)]
+
+
+def qnum_attributes(max_size: int) -> list[tuple[int, bool, int]]:
+    return [(1, True, 1)] + [
+        (size, is_signed, fraction_digits)
+        for size in range(1, max_size + 1)
+        for is_signed in (False, True)
+        for fraction_digits in range(size - int(is_signed) + 1)
+    ]
+
+
+_VAR_NAME_COUNTER: Counter[str] = Counter()
+
+
+def get_temp_var_name(var_name: str = "temp") -> str:
+    n = _VAR_NAME_COUNTER[var_name]
+    _VAR_NAME_COUNTER[var_name] += 1
+    return f"{var_name}_{n}"
+
+
+RealFunction = Callable[Params, float]