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

classiq/qmod/qmod_variable.py

@@ -1,37 +1,49 @@
 import abc
 import sys
+from collections.abc import Iterator, Mapping
 from contextlib import contextmanager
-from typing import _GenericAlias  # type: ignore[attr-defined]
-from typing import (
+from typing import (  # type: ignore[attr-defined]
     TYPE_CHECKING,
+    Annotated,
     Any,
     ForwardRef,
     Generic,
-    Iterator,
     Literal,
     Optional,
-    Tuple,
-    Type,
     TypeVar,
     Union,
+    _GenericAlias,
+    cast,
     get_args,
     get_origin,
-    overload,
 )
 
-from typing_extensions import Annotated, ParamSpec, Self, _AnnotatedAlias
+from typing_extensions import ParamSpec, Self, _AnnotatedAlias
 
+from classiq.interface.exceptions import ClassiqValueError
 from classiq.interface.generator.expressions.expression import Expression
+from classiq.interface.generator.expressions.qmod_qarray_proxy import (
+    ILLEGAL_SLICE_MSG,
+    ILLEGAL_SLICING_STEP_MSG,
+)
 from classiq.interface.generator.functions.port_declaration import (
     PortDeclarationDirection,
 )
-from classiq.interface.model.handle_binding import HandleBinding, SlicedHandleBinding
-from classiq.interface.model.port_declaration import PortDeclaration
+from classiq.interface.generator.functions.type_name import TypeName
+from classiq.interface.generator.types.qstruct_declaration import QStructDeclaration
+from classiq.interface.model.handle_binding import (
+    FieldHandleBinding,
+    HandleBinding,
+    SlicedHandleBinding,
+    SubscriptHandleBinding,
+)
+from classiq.interface.model.port_declaration import AnonPortDeclaration
 from classiq.interface.model.quantum_expressions.amplitude_loading_operation import (
     AmplitudeLoadingOperation,
 )
 from classiq.interface.model.quantum_expressions.arithmetic_operation import (
     ArithmeticOperation,
+    ArithmeticOperationKind,
 )
 from classiq.interface.model.quantum_type import (
     QuantumBit,
@@ -39,17 +51,24 @@ from classiq.interface.model.quantum_type import (
     QuantumNumeric,
     QuantumType,
 )
+from classiq.interface.source_reference import SourceReference
 
-from classiq.exceptions import ClassiqValueError
-from classiq.qmod.qmod_parameter import ArrayBase, QParam, QParamScalar
+from classiq.qmod.cparam import ArrayBase, CInt, CParamScalar
+from classiq.qmod.generative import (
+    generative_mode_context,
+    interpret_expression,
+    is_generative_mode,
+)
+from classiq.qmod.model_state_container import QMODULE, ModelStateContainer
 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
-
-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"
-UNSUPPORTED_ELEMENT_TYPE = "Only QBit is supported as element type for QArray"
+from classiq.qmod.utilities import (
+    get_source_ref,
+    unwrap_forward_ref,
+    varname,
+    version_portable_get_args,
+)
 
 
 def _is_input_output_typehint(type_hint: Any) -> bool:
@@ -77,28 +96,59 @@ def _no_current_expandable() -> Iterator[None]:
         QCallable.CURRENT_EXPANDABLE = current_expandable
 
 
-class QVar:
-    def __init__(self, name: str) -> None:
-        self._name = name
-        if QCallable.CURRENT_EXPANDABLE is not None:
+def _infer_variable_name(name: Any, depth: int) -> Any:
+    if name is not None:
+        return name
+    name = varname(depth + 1)
+    if name is None:
+        raise ClassiqValueError(
+            "Could not infer variable name. Please specify the variable name explicitly"
+        )
+    return name
+
+
+class QVar(Symbolic):
+    CONSTRUCTOR_DEPTH: int = 1
+
+    def __init__(
+        self,
+        origin: Union[None, str, HandleBinding] = None,
+        *,
+        expr_str: Optional[str] = None,
+        depth: int = 2,
+    ) -> None:
+        name = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
+        super().__init__(str(name), True)
+        source_ref = (
+            get_source_ref(sys._getframe(depth))
+            if isinstance(name, str)
+            else name.source_ref
+        )
+        self._base_handle: HandleBinding = (
+            HandleBinding(name=name) if isinstance(name, str) else name
+        )
+        if isinstance(name, str) and QCallable.CURRENT_EXPANDABLE is not None:
             QCallable.CURRENT_EXPANDABLE.add_local_handle(
-                self._name, self.get_qmod_type()
+                name, self.get_qmod_type(), source_ref
             )
+        self._expr_str = expr_str if expr_str is not None else str(name)
 
-    @abc.abstractmethod
     def get_handle_binding(self) -> HandleBinding:
-        raise NotImplementedError()
+        return self._base_handle
 
     @abc.abstractmethod
     def get_qmod_type(self) -> QuantumType:
         raise NotImplementedError()
 
     @staticmethod
-    def from_type_hint(type_hint: Any) -> Optional[Type["QVar"]]:
+    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
 
@@ -107,6 +157,16 @@ class QVar:
     def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
         raise NotImplementedError()
 
+    @classmethod
+    @abc.abstractmethod
+    def to_qvar(
+        cls,
+        origin: Union[str, HandleBinding],
+        type_hint: Any,
+        expr_str: Optional[str],
+    ) -> Self:
+        raise NotImplementedError()
+
     @classmethod
     def port_direction(cls, type_hint: Any) -> PortDeclarationDirection:
         if _is_input_output_typehint(type_hint):
@@ -115,6 +175,16 @@ class QVar:
         assert type_hint == cls or get_origin(type_hint) == cls
         return PortDeclarationDirection.Inout
 
+    def __str__(self) -> str:
+        return self._expr_str
+
+    @property
+    def size(self) -> Union[CParamScalar, int]:
+        if is_generative_mode():
+            with generative_mode_context(False):
+                return interpret_expression(str(self.size))
+        return CParamScalar(f"get_field({self}, 'size')")
+
 
 _Q = TypeVar("_Q", bound=QVar)
 Output = Annotated[_Q, PortDeclarationDirection.Output]
@@ -122,11 +192,25 @@ Input = Annotated[_Q, PortDeclarationDirection.Input]
 
 
 class QScalar(QVar, SymbolicExpr):
-    def __init__(self, name: str) -> None:
-        QVar.__init__(self, name)
-        SymbolicExpr.__init__(self, name)
+    CONSTRUCTOR_DEPTH: int = 2
 
-    def _insert_arith_operation(self, expr: SymbolicTypes, inplace: bool) -> None:
+    def __init__(
+        self,
+        origin: Union[None, str, HandleBinding] = None,
+        *,
+        _expr_str: Optional[str] = None,
+        depth: int = 2,
+    ) -> None:
+        origin = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
+        QVar.__init__(self, origin, expr_str=_expr_str, depth=depth)
+        SymbolicExpr.__init__(self, str(origin), True)
+
+    def _insert_arith_operation(
+        self,
+        expr: SymbolicTypes,
+        kind: ArithmeticOperationKind,
+        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
@@ -134,30 +218,33 @@ class QScalar(QVar, SymbolicExpr):
             ArithmeticOperation(
                 expression=Expression(expr=str(expr)),
                 result_var=self.get_handle_binding(),
-                inplace_result=inplace,
+                operation_kind=kind,
+                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,
             )
         )
 
-    def get_handle_binding(self) -> HandleBinding:
-        return HandleBinding(name=self._name)
-
     def __ior__(self, other: Any) -> Self:
         if not isinstance(other, get_args(SymbolicTypes)):
             raise TypeError(
                 f"Invalid argument {other!r} for out-of-place arithmetic operation"
             )
 
-        self._insert_arith_operation(other, False)
+        self._insert_arith_operation(
+            other, ArithmeticOperationKind.Assignment, get_source_ref(sys._getframe(1))
+        )
         return self
 
     def __ixor__(self, other: Any) -> Self:
@@ -166,7 +253,20 @@ 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, ArithmeticOperationKind.InplaceXor, get_source_ref(sys._getframe(1))
+        )
+        return self
+
+    def __iadd__(self, other: Any) -> Self:
+        if not isinstance(other, get_args(SymbolicTypes)):
+            raise TypeError(
+                f"Invalid argument {other!r} for in-place arithmetic operation"
+            )
+
+        self._insert_arith_operation(
+            other, ArithmeticOperationKind.InplaceAdd, get_source_ref(sys._getframe(1))
+        )
         return self
 
     def __imul__(self, other: Any) -> Self:
@@ -175,7 +275,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
 
 
@@ -184,6 +284,15 @@ class QBit(QScalar):
     def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
         return QuantumBit()
 
+    @classmethod
+    def to_qvar(
+        cls,
+        origin: Union[str, HandleBinding],
+        type_hint: Any,
+        expr_str: Optional[str],
+    ) -> "QBit":
+        return QBit(origin, _expr_str=expr_str)
+
     def get_qmod_type(self) -> QuantumType:
         return QuantumBit()
 
@@ -192,80 +301,111 @@ _P = ParamSpec("_P")
 
 
 class QNum(Generic[_P], QScalar):
-    QMOD_TYPE = QuantumNumeric
-
-    @overload
-    def __init__(self, name: str):
-        pass
-
-    @overload
-    def __init__(
-        self,
-        name: str,
-        size: Union[int, QParam[int]],
-        is_signed: Union[bool, QParam[bool]],
-        fraction_digits: Union[int, QParam[int]],
-    ):
-        pass
+    CONSTRUCTOR_DEPTH: int = 3
 
     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,
+        name: Union[None, str, HandleBinding] = None,
+        size: Union[int, CInt, Expression, SymbolicExpr, None] = None,
+        is_signed: Union[bool, Expression, SymbolicExpr, None] = None,
+        fraction_digits: Union[int, CInt, Expression, None] = None,
+        _expr_str: Optional[str] = None,
     ):
-        if (
-            size is None
-            and (is_signed is not None or fraction_digits is not None)
-            or size is not None
-            and (is_signed is None or fraction_digits is None)
-        ):
+        if size is None and (is_signed is not None or fraction_digits is not None):
+            raise ClassiqValueError(
+                "Cannot assign 'is_signed' and 'fraction_digits' without 'size'"
+            )
+        if is_signed is not None and fraction_digits is None:
             raise ClassiqValueError(
-                "Assign none or all of size, is_signed, and fraction_digits"
+                "Cannot assign 'is_signed' without 'fraction_digits'"
             )
-        self._size = None if size is None else Expression(expr=str(size))
-        self._is_signed = None if is_signed is None else Expression(expr=str(is_signed))
+        if is_signed is None and fraction_digits is not None:
+            raise ClassiqValueError(
+                "Cannot assign 'fraction_digits' without 'is_signed'"
+            )
+        self._size = (
+            size
+            if size is None or isinstance(size, Expression)
+            else Expression(expr=str(size))
+        )
+        self._is_signed = (
+            is_signed
+            if is_signed is None or isinstance(is_signed, Expression)
+            else Expression(expr=str(is_signed))
+        )
         self._fraction_digits = (
-            None if fraction_digits is None else Expression(expr=str(fraction_digits))
+            fraction_digits
+            if fraction_digits is None or isinstance(fraction_digits, Expression)
+            else Expression(expr=str(fraction_digits))
         )
-        super().__init__(name)
+        super().__init__(name, _expr_str=_expr_str, depth=3)
 
     @classmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
-        type_args = get_args(type_hint)
+    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 cls.QMOD_TYPE()
-        type_args = type_args[0]
-        if len(type_args) != 3:
+            return None, None, None
+        if len(type_args) not in (1, 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])),
-            is_signed=Expression(expr=get_type_hint_expr(type_args[1])),
-            fraction_digits=Expression(expr=get_type_hint_expr(type_args[2])),
+        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,
+        origin: Union[str, HandleBinding],
+        type_hint: Any,
+        expr_str: Optional[str],
+    ) -> "QNum":
+        return QNum(origin, *cls._get_attributes(type_hint), _expr_str=expr_str)
+
     def get_qmod_type(self) -> QuantumType:
-        return self.QMOD_TYPE(
+        return QuantumNumeric(
             size=self._size,
             is_signed=self._is_signed,
             fraction_digits=self._fraction_digits,
         )
 
     @property
-    def size(self) -> QParamScalar:
-        return QParamScalar(f"len({self._name})")
+    def fraction_digits(self) -> Union[CParamScalar, int]:
+        if is_generative_mode():
+            with generative_mode_context(False):
+                return interpret_expression(str(self.fraction_digits))
+        return CParamScalar(f"get_field({self}, 'fraction_digits')")
 
     @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})")
+    def is_signed(self) -> Union[CParamScalar, bool]:
+        if is_generative_mode():
+            with generative_mode_context(False):
+                return interpret_expression(str(self.is_signed))
+        return CParamScalar(f"get_field({self}, 'is_signed')")
 
     # Support comma-separated generic args in older Python versions
     if sys.version_info[0:2] < (3, 10):
@@ -275,101 +415,274 @@ class QNum(Generic[_P], QScalar):
 
 
 class QArray(ArrayBase[_P], QVar):
+    CONSTRUCTOR_DEPTH: int = 3
+
+    # TODO [CAD-18620]: improve type hints
     def __init__(
         self,
-        name: str,
-        element_type: _GenericAlias = QBit,
-        length: Optional[Union[int, QParam[int]]] = None,
-        slice_: Optional[Tuple[int, int]] = None,
+        name: Union[None, str, HandleBinding] = None,
+        element_type: Union[_GenericAlias, QuantumType] = QBit,
+        length: Optional[Union[int, SymbolicExpr, Expression]] = None,
+        _expr_str: Optional[str] = None,
     ) -> None:
-        if element_type is not QBit:
-            raise ClassiqValueError(UNSUPPORTED_ELEMENT_TYPE)
         self._element_type = element_type
-        self._length = length
-        self._slice = slice_
-        super().__init__(name)
+        self._length = (
+            length
+            if length is None or isinstance(length, Expression)
+            else Expression(expr=str(length))
+        )
+        super().__init__(name, expr_str=_expr_str)
 
-    def get_handle_binding(self) -> HandleBinding:
-        if self._slice is None:
-            return HandleBinding(name=self._name)
-        return SlicedHandleBinding(
-            name=self._name,
-            start=Expression(expr=str(self._slice[0])),
-            end=Expression(expr=str(self._slice[1])),
+    def __getitem__(self, key: Union[slice, int, SymbolicExpr]) -> Any:
+        return (
+            self._get_slice(key) if isinstance(key, slice) else self._get_subscript(key)
         )
 
-    def __getitem__(self, key: Union[slice, int, QParam]) -> "QArray":
-        offset = self._slice[0] if self._slice is not None else 0
-        if isinstance(key, slice):
-            if key.step is not None:
-                raise ClassiqValueError(ILLEGAL_SLICING_STEP_MSG)
-            new_slice = (offset + key.start, offset + key.stop)
-        else:
-            if isinstance(key, QParam) and not isinstance(key, QParamScalar):
-                raise ClassiqValueError("Non-classical parameter for slicing")
-            new_slice = (offset + key, offset + key + 1)
-        if (
-            self._slice is not None
-            and not isinstance(new_slice[1], Symbolic)
-            and not isinstance(self._slice[1], Symbolic)
-            and new_slice[1] > self._slice[1]
-        ) or (
-            self._length is not None
-            and not isinstance(new_slice[1], Symbolic)
-            and not isinstance(self._length, Symbolic)
-            and new_slice[1] > self._length
+    def __setitem__(self, *args: Any) -> None:
+        pass
+
+    def _get_subscript(self, index: Union[slice, int, SymbolicExpr]) -> Any:
+        if isinstance(index, SymbolicExpr) and index.is_quantum:
+            raise ClassiqValueError("Non-classical parameter for slicing")
+
+        return _create_qvar_for_qtype(
+            self.get_qmod_type().element_type,
+            SubscriptHandleBinding(
+                base_handle=self._base_handle,
+                index=Expression(expr=str(index)),
+            ),
+            expr_str=f"{self}[{index}]",
+        )
+
+    def _get_slice(self, slice_: slice) -> Any:
+        if slice_.step is not None:
+            raise ClassiqValueError(ILLEGAL_SLICING_STEP_MSG)
+        if not isinstance(slice_.start, (int, SymbolicExpr)) or not isinstance(
+            slice_.stop, (int, SymbolicExpr)
         ):
-            raise ClassiqValueError(SLICE_OUT_OF_BOUNDS_MSG)
-        # prevent addition to local handles, since this is used for slicing existing local handles
-        with _no_current_expandable():
-            return QArray(self._name, length=self._length, slice_=new_slice)
+            raise ClassiqValueError(ILLEGAL_SLICE_MSG)
+
+        return QArray(
+            name=SlicedHandleBinding(
+                base_handle=self._base_handle,
+                start=Expression(expr=str(slice_.start)),
+                end=Expression(expr=str(slice_.stop)),
+            ),
+            element_type=self._element_type,
+            length=slice_.stop - slice_.start,
+            _expr_str=f"{self}[{slice_.start}:{slice_.stop}]",
+        )
 
     def __len__(self) -> int:
         raise ClassiqValueError(
-            "len(<var>) is not supported for quantum variables - use <var>.len() instead"
+            "len(<var>) is not supported for quantum variables - use <var>.len instead"
         )
 
     if TYPE_CHECKING:
 
+        @property
         def len(self) -> int: ...
 
     else:
 
-        def len(self) -> QParamScalar:
-            if self._length is not None:
-                return QParamScalar(f"{self._length}")
-            return QParamScalar(f"len({self._name})")
+        @property
+        def len(self) -> Union[CParamScalar, int]:
+            if is_generative_mode():
+                with generative_mode_context(False):
+                    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 len(version_portable_get_args(type_hint)) == 2:
-            length_expr = Expression(
-                expr=get_type_hint_expr(version_portable_get_args(type_hint)[1])
-            )
-        return QuantumBitvector(length=length_expr)
+        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,
+        origin: Union[str, HandleBinding],
+        type_hint: Any,
+        expr_str: Optional[str],
+    ) -> "QArray":
+        return QArray(origin, *cls._get_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,
+            length=self._length,
+        )
+
+
+class QStruct(QVar):
+    CONSTRUCTOR_DEPTH: int = 2
+
+    _struct_name: str
+    _fields: Mapping[str, QVar]
+
+    def __init__(
+        self,
+        origin: Union[None, str, HandleBinding] = None,
+        _struct_name: Optional[str] = None,
+        _fields: Optional[Mapping[str, QVar]] = None,
+        _expr_str: Optional[str] = None,
+    ) -> None:
+        name = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
+        if _struct_name is None or _fields is None:
+            with _no_current_expandable():
+                temp_var = QStruct.to_qvar(name, type(self), _expr_str)
+                _struct_name = temp_var._struct_name
+                _fields = temp_var._fields
+        self._struct_name = _struct_name
+        self._fields = _fields
+        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:
-        if self._length is not None:
-            return QuantumBitvector(length=Expression(expr=str(self._length)))
-        return QuantumBitvector()
+        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__)
 
-def create_qvar_for_port_decl(port: PortDeclaration) -> QVar:
+    @classmethod
+    def to_qvar(
+        cls,
+        origin: Union[str, HandleBinding],
+        type_hint: Any,
+        expr_str: Optional[str],
+    ) -> "QStruct":
+        field_types = {
+            field_name: (QVar.from_type_hint(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(
+                    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}')",
+                )
+                for field_name, (field_class, field_type) in field_types.items()
+            }
+        return QStruct(
+            origin,
+            _struct_name=type_hint.__name__,
+            _fields=field_vars,
+            _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))
+
+
+def _create_qvar_for_qtype(
+    qtype: QuantumType, origin: HandleBinding, expr_str: Optional[str] = None
+) -> QVar:
     # prevent addition to local handles, since this is used for ports
     with _no_current_expandable():
-        if _is_single_qbit_vector(port):
-            return QBit(port.name)
-        elif isinstance(port.quantum_type, QuantumNumeric):
-            return QNum(port.name)
-        return QArray(port.name)
-
-
-def _is_single_qbit_vector(port: PortDeclaration) -> bool:
-    return (
-        isinstance(port.quantum_type, QuantumBit)
-        or isinstance(port.quantum_type, QuantumBitvector)
-        and port.size is not None
-        and port.size.is_evaluated()
-        and port.size.to_int_value() == 1
-    )
+        if isinstance(qtype, QuantumBit):
+            return QBit(origin, _expr_str=expr_str)
+        elif isinstance(qtype, QuantumNumeric):
+            return QNum(
+                origin,
+                qtype.size,
+                qtype.is_signed,
+                qtype.fraction_digits,
+                _expr_str=expr_str,
+            )
+        elif isinstance(qtype, TypeName):
+            struct_decl = QMODULE.qstruct_decls[qtype.name]
+            return QStruct(
+                origin,
+                struct_decl.name,
+                {
+                    field_name: _create_qvar_for_qtype(
+                        field_type,
+                        FieldHandleBinding(base_handle=origin, field=field_name),
+                        f"get_field({expr_str if expr_str is not None else str(origin)}, '{field_name}')",
+                    )
+                    for field_name, field_type in struct_decl.fields.items()
+                },
+                _expr_str=expr_str,
+            )
+        if TYPE_CHECKING:
+            assert isinstance(qtype, QuantumBitvector)
+        return QArray(origin, qtype.element_type, qtype.length, _expr_str=expr_str)
+
+
+def get_qvar(qtype: QuantumType, origin: HandleBinding) -> "QVar":
+    if isinstance(qtype, QuantumBit):
+        return QBit(origin)
+    elif isinstance(qtype, QuantumBitvector):
+        return QArray(origin, qtype.element_type, qtype.length)
+    elif isinstance(qtype, QuantumNumeric):
+        return QNum(origin, qtype.size, qtype.is_signed, qtype.fraction_digits)
+    elif isinstance(qtype, TypeName):
+        return QStruct(
+            origin,
+            qtype.name,
+            {
+                field_name: get_qvar(
+                    field_type, FieldHandleBinding(base_handle=origin, field=field_name)
+                )
+                for field_name, field_type in qtype.fields.items()
+            },
+        )
+    raise NotImplementedError