classiq 0.43.3__py3-none-any.whl → 0.45.0__py3-none-any.whl

classiq/qmod/qmod_variable.py

@@ -8,30 +8,41 @@ from typing import (  # type: ignore[attr-defined]
     Generic,
     Iterator,
     Literal,
+    Mapping,
     Optional,
     Tuple,
     Type,
     TypeVar,
     Union,
     _GenericAlias,
+    cast,
     get_args,
     get_origin,
-    overload,
 )
 
 from typing_extensions import Annotated, ParamSpec, Self, _AnnotatedAlias
 
-from classiq.interface.ast_node import SourceReference
+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_BOUNDS_MSG,
+    ILLEGAL_SLICE_MSG,
+    ILLEGAL_SLICING_STEP_MSG,
+    SLICE_OUT_OF_BOUNDS_MSG,
+    SUBSCRIPT_OUT_OF_BOUNDS_MSG,
+)
 from classiq.interface.generator.functions.port_declaration import (
     PortDeclarationDirection,
 )
+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 PortDeclaration
+from classiq.interface.model.port_declaration import AnonPortDeclaration
 from classiq.interface.model.quantum_expressions.amplitude_loading_operation import (
     AmplitudeLoadingOperation,
 )
@@ -44,18 +55,25 @@ 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, CBool, CInt, CParam, CParamScalar
+from classiq.qmod.model_state_container import QMODULE, ModelStateContainer
+from classiq.qmod.qmod_parameter import ArrayBase, CBool, CInt, 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 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"
-UNSUPPORTED_ELEMENT_TYPE = "Only QBit and QNum are supported as element type for QArray"
-QARRAY_ELEMENT_NOT_SUBSCRIPTABLE = "Subscripting an element in QArray is illegal"
+QVAR_PROPERTIES_ARE_SYMBOLIC = True
+
+
+@contextmanager
+def set_symbolic_qvar_properties(symbolic: bool) -> Iterator[None]:
+    global QVAR_PROPERTIES_ARE_SYMBOLIC
+    previous_symbolic = QVAR_PROPERTIES_ARE_SYMBOLIC
+    QVAR_PROPERTIES_ARE_SYMBOLIC = symbolic
+    yield
+    QVAR_PROPERTIES_ARE_SYMBOLIC = previous_symbolic
 
 
 def _is_input_output_typehint(type_hint: Any) -> bool:
@@ -84,18 +102,30 @@ def _no_current_expandable() -> Iterator[None]:
 
 
 class QVar(Symbolic):
-    def __init__(self, name: str, depth: int = 2) -> None:
-        super().__init__(name, True)
-        self._name = name
-        source_ref = get_source_ref(sys._getframe(depth))
-        if QCallable.CURRENT_EXPANDABLE is not None:
+    def __init__(
+        self,
+        origin: Union[str, HandleBinding],
+        *,
+        expr_str: Optional[str] = None,
+        depth: int = 2,
+    ) -> None:
+        super().__init__(str(origin), True)
+        source_ref = (
+            get_source_ref(sys._getframe(depth))
+            if isinstance(origin, str)
+            else origin.source_ref
+        )
+        self._base_handle: HandleBinding = (
+            HandleBinding(name=origin) if isinstance(origin, str) else origin
+        )
+        if isinstance(origin, str) and QCallable.CURRENT_EXPANDABLE is not None:
             QCallable.CURRENT_EXPANDABLE.add_local_handle(
-                self._name, self.get_qmod_type(), source_ref
+                origin, self.get_qmod_type(), source_ref
             )
+        self._expr_str = expr_str if expr_str is not None else str(origin)
 
-    @abc.abstractmethod
     def get_handle_binding(self) -> HandleBinding:
-        raise NotImplementedError()
+        return self._base_handle
 
     @abc.abstractmethod
     def get_qmod_type(self) -> QuantumType:
@@ -107,6 +137,9 @@ class QVar(Symbolic):
             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
 
@@ -115,6 +148,16 @@ class QVar(Symbolic):
     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):
@@ -124,7 +167,17 @@ class QVar(Symbolic):
         return PortDeclarationDirection.Inout
 
     def __str__(self) -> str:
-        return str(self.get_handle_binding())
+        return self._expr_str
+
+    @property
+    def size(self) -> Union[CParamScalar, int]:
+        if not QVAR_PROPERTIES_ARE_SYMBOLIC:
+            return self._evaluate_size()
+        return CParamScalar(f"get_field({self}, 'size')")
+
+    @abc.abstractmethod
+    def _evaluate_size(self) -> int:
+        raise NotImplementedError
 
 
 _Q = TypeVar("_Q", bound=QVar)
@@ -133,9 +186,15 @@ Input = Annotated[_Q, PortDeclarationDirection.Input]
 
 
 class QScalar(QVar, SymbolicExpr):
-    def __init__(self, name: str, depth: int = 2) -> None:
-        QVar.__init__(self, name, depth)
-        SymbolicExpr.__init__(self, name, True)
+    def __init__(
+        self,
+        origin: Union[str, HandleBinding],
+        *,
+        _expr_str: Optional[str] = None,
+        depth: int = 2,
+    ) -> None:
+        QVar.__init__(self, origin, expr_str=_expr_str, depth=depth)
+        SymbolicExpr.__init__(self, str(origin), True)
 
     def _insert_arith_operation(
         self, expr: SymbolicTypes, inplace: bool, source_ref: SourceReference
@@ -165,9 +224,6 @@ class QScalar(QVar, SymbolicExpr):
             )
         )
 
-    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(
@@ -201,36 +257,33 @@ 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()
 
+    def _evaluate_size(self) -> int:
+        return 1
+
 
 _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, CInt],
-        is_signed: Union[bool, CBool],
-        fraction_digits: Union[int, CInt],
-    ):
-        pass
-
-    def __init__(
-        self,
-        name: str,
-        size: Union[int, CInt, None] = None,
-        is_signed: Union[bool, CBool, None] = None,
-        fraction_digits: Union[int, CInt, None] = None,
+        name: Union[str, HandleBinding],
+        size: Union[int, CInt, Expression, None] = None,
+        is_signed: Union[bool, CBool, Expression, None] = None,
+        fraction_digits: Union[int, CInt, Expression, None] = None,
+        _expr_str: Optional[str] = None,
     ):
         if (
             size is None
@@ -241,48 +294,90 @@ class QNum(Generic[_P], QScalar):
             raise ClassiqValueError(
                 "Assign none or all of size, is_signed, and 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))
+        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, 3)
+        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]
+            return None, None, None
         if len(type_args) != 3:
             raise ClassiqValueError(
                 "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])),
+        return type_args[0], type_args[1], 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) -> CParamScalar:
-        return CParamScalar(f"get_field({self._name}, 'size')")
+    def _evaluate_size(self) -> int:
+        if TYPE_CHECKING:
+            assert self._size is not None
+        return self._size.to_int_value()
 
     @property
-    def fraction_digits(self) -> CParamScalar:
-        return CParamScalar(f"get_field({self._name}, 'fraction_digits')")
+    def fraction_digits(self) -> Union[CParamScalar, int]:
+        if not QVAR_PROPERTIES_ARE_SYMBOLIC:
+            if TYPE_CHECKING:
+                assert self._fraction_digits is not None
+            return self._fraction_digits.to_int_value()
+        return CParamScalar(f"get_field({self}, 'fraction_digits')")
 
     @property
-    def is_signed(self) -> CParamScalar:
-        return CParamScalar(f"get_field({self._name}, 'is_signed')")
+    def is_signed(self) -> Union[CParamScalar, bool]:
+        if not QVAR_PROPERTIES_ARE_SYMBOLIC:
+            if TYPE_CHECKING:
+                assert self._is_signed is not None
+            return self._is_signed.to_bool_value()
+        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):
@@ -292,84 +387,83 @@ class QNum(Generic[_P], QScalar):
 
 
 class QArray(ArrayBase[_P], QVar):
+    # TODO [CAD-18620]: improve type hints
     def __init__(
         self,
-        name: str,
-        element_type: _GenericAlias = QBit,
-        length: Optional[Union[int, CInt]] = None,
-        # TODO [CAD-18620]: improve type hints
-        slice_: Optional[Tuple[int, int]] = None,
-        index_: Optional[Union[int, CInt]] = None,
+        name: Union[str, HandleBinding],
+        element_type: Union[_GenericAlias, QuantumType] = QBit,
+        length: Optional[Union[int, SymbolicExpr, Expression]] = None,
+        _expr_str: Optional[str] = None,
     ) -> None:
-        if not issubclass(get_origin(element_type) or element_type, (QBit, QNum)):
-            raise ClassiqValueError(UNSUPPORTED_ELEMENT_TYPE)
         self._element_type = element_type
-        self._length = length
-        self._slice = slice_
-        self._index = index_
-        super().__init__(name)
-
-    def get_handle_binding(self) -> HandleBinding:
-        if self._index is not None:
-            return SubscriptHandleBinding(
-                name=self._name,
-                index=Expression(expr=str(self._index)),
-            )
-
-        if self._slice is not None:
-            return SlicedHandleBinding(
-                name=self._name,
-                start=Expression(expr=str(self._slice[0])),
-                end=Expression(expr=str(self._slice[1])),
-            )
-
-        return HandleBinding(name=self._name)
-
-    def __getitem__(self, key: Union[slice, int, CInt]) -> Any:
-        if self._index is not None:
-            raise ClassiqValueError(QARRAY_ELEMENT_NOT_SUBSCRIPTABLE)
-
-        # TODO [CAD-18620]: improve type hints
-        new_index: Optional[Any] = None
+        self._length = (
+            length
+            if length is None or isinstance(length, Expression)
+            else Expression(expr=str(length))
+        )
+        super().__init__(name, expr_str=_expr_str)
 
-        if isinstance(key, slice):
-            if key.step is not None:
-                raise ClassiqValueError(ILLEGAL_SLICING_STEP_MSG)
-            new_slice = self._get_new_slice(key.start, key.stop)
+    def __getitem__(self, key: Union[slice, int, SymbolicExpr]) -> Any:
+        return (
+            self._get_slice(key) if isinstance(key, slice) else self._get_subscript(key)
+        )
 
-        else:
-            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]
+    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")
+        if (
+            isinstance(index, int)
+            and self._length is not None
+            and self._length.is_evaluated()
+        ):
+            length = self._length.to_int_value()
+            if index < 0 or index >= length:
+                raise ClassiqValueError(SUBSCRIPT_OUT_OF_BOUNDS_MSG)
+
+        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(ILLEGAL_SLICE_MSG)
         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
+            isinstance(slice_.start, int)
+            and isinstance(slice_.stop, int)
+            and slice_.start >= slice_.stop
         ):
-            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():
-            if new_index is None:
-                array_class = QArray
-            else:
-                array_class = QArraySubscript
-            return array_class(
-                self._name, length=self._length, slice_=new_slice, index_=new_index
+            raise ClassiqValueError(
+                ILLEGAL_SLICE_BOUNDS_MSG.format(slice_.start, slice_.stop)
             )
-
-    # TODO [CAD-18620]: improve type hints
-    def _get_new_slice(self, start: Any, end: Any) -> Tuple[Any, Any]:
-        if self._slice is not None:
-            return (self._slice[0] + start, self._slice[0] + end)
-        return (start, end)
+        if self._length is not None and self._length.is_evaluated():
+            length = self._length.to_int_value()
+            if (
+                isinstance(slice_.start, int)
+                and slice_.start < 0
+                or isinstance(slice_.stop, int)
+                and slice_.stop > length
+            ):
+                raise ClassiqValueError(SLICE_OUT_OF_BOUNDS_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(
@@ -384,69 +478,206 @@ class QArray(ArrayBase[_P], QVar):
     else:
 
         @property
-        def len(self) -> CParamScalar:
+        def len(self) -> Union[CParamScalar, int]:
+            if not QVAR_PROPERTIES_ARE_SYMBOLIC:
+                return self._length.to_int_value()
             if self._length is not None:
                 return CParamScalar(f"{self._length}")
-            return CParamScalar(f"get_field({self._name}, 'len')")
+            return CParamScalar(f"get_field({self}, 'len')")
+
+    def _evaluate_size(self) -> int:
+        if TYPE_CHECKING:
+            assert self._length is not None
+        return self._element_type.size_in_bits * self._length.to_int_value()
 
     @classmethod
-    def to_qmod_quantum_type(cls, type_hint: Any) -> QuantumType:
+    def _get_attributes(cls, type_hint: Any) -> Tuple[Type[QVar], Any]:
         type_args = version_portable_get_args(type_hint)
-        if len(type_args) == 1 and isinstance(type_args[0], (str, int)):
-            type_args = (QBit, type_args[0])
+        if len(type_args) == 0:
+            return QBit, None
+        if len(type_args) == 1:
+            if isinstance(type_args[0], (str, int)):
+                return QBit, type_args[0]
+            return type_args[0], None
+        if len(type_args) != 2:
+            raise ClassiqValueError(
+                "QArray receives two type arguments: QArray[element_type: QVar, "
+                "length: int | CInt]"
+            )
+        return cast(Tuple[Type[QVar], Any], type_args)
 
-        api_element_type = QBit if len(type_args) == 0 else type_args[0]
+    @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(type_args) == 2:
-            length_expr = Expression(expr=get_type_hint_expr(type_args[1]))
+        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_qmod_type(self) -> QuantumType:
-        element_class = get_origin(self._element_type) or self._element_type
-        length = None
-        if self._length is not None:
-            length = Expression(expr=str(self._length))
+    @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_class.to_qmod_quantum_type(self._element_type),
-            length=length,
+            element_type=element_type,
+            length=self._length,
         )
 
 
-class QArraySubscript(QArray, QScalar):
-    @property
-    def size(self) -> CParamScalar:
-        return CParamScalar(f"get_field({self.get_handle_binding()}, 'size')")
+class QStruct(QVar):
+    _struct_name: str
+    _fields: Mapping[str, QVar]
 
-    @property
-    def fraction_digits(self) -> CParamScalar:
-        return CParamScalar(
-            f"get_field({self.get_handle_binding()}, 'fraction_digits')"
+    def __init__(
+        self,
+        name: Union[str, HandleBinding],
+        _struct_name: Optional[str] = None,
+        _fields: Optional[Mapping[str, QVar]] = None,
+        _expr_str: Optional[str] = None,
+    ) -> None:
+        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)
+        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,
+        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(
+            name=origin,
+            _struct_name=type_hint.__name__,
+            _fields=field_vars,
+            _expr_str=expr_str,
         )
 
-    @property
-    def is_signed(self) -> CParamScalar:
-        return CParamScalar(f"get_field({self.get_handle_binding()}, 'is_signed')")
+    def _add_qmod_qstruct(self, *, qmodule: ModelStateContainer) -> None:
+        if self._struct_name in qmodule.qstruct_decls:
+            return
+
+        qmodule.qstruct_decls[self._struct_name] = QStructDeclaration(
+            name=self._struct_name,
+            fields={name: qvar.get_qmod_type() for name, qvar in self._fields.items()},
+        )
+
+    def _evaluate_size(self) -> int:
+        return sum(var._evaluate_size() for var in self._fields.values())
+
 
+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_port_decl(port: PortDeclaration, name: str) -> QVar:
+
+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(name)
-        elif isinstance(port.quantum_type, QuantumNumeric):
-            return QNum(name)
-        return QArray(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