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

classiq/qmod/qfunc.py

@@ -35,6 +35,7 @@ def qfunc(
     *,
     external: Literal[True],
     synthesize_separately: Literal[False] = False,
+    atomic_qualifiers: Optional[list[str]] = None,
 ) -> Callable[[Callable], ExternalQFunc]: ...
 
 
@@ -43,11 +44,22 @@ def qfunc(
     *,
     generative: Literal[True],
     synthesize_separately: bool = False,
+    atomic_qualifiers: Optional[list[str]] = None,
 ) -> Callable[[Callable], GenerativeQFunc]: ...
 
 
 @overload
-def qfunc(*, synthesize_separately: bool) -> Callable[[Callable], QFunc]: ...
+def qfunc(
+    *, synthesize_separately: bool, atomic_qualifiers: Optional[list[str]] = None
+) -> Callable[[Callable], QFunc]: ...
+
+
+@overload
+def qfunc(
+    *,
+    synthesize_separately: bool = False,
+    atomic_qualifiers: Optional[list[str]] = None,
+) -> Callable[[Callable], QFunc]: ...
 
 
 def qfunc(
@@ -56,24 +68,37 @@ def qfunc(
     external: bool = False,
     generative: bool = False,
     synthesize_separately: bool = False,
+    atomic_qualifiers: Optional[list[str]] = None,
 ) -> Union[Callable[[Callable], QCallable], QCallable]:
     def wrapper(func: Callable) -> QCallable:
         qfunc: BaseQFunc
+
+        if external:
+            _validate_directives(synthesize_separately, atomic_qualifiers)
+            return ExternalQFunc(func)
+
         if generative or _GENERATIVE_SWITCH:
             qfunc = GenerativeQFunc(func)
-        elif external:
-            if synthesize_separately:
-                raise ClassiqInternalError(
-                    "External functions can't be marked as synthesized separately"
-                )
-            return ExternalQFunc(func)
         else:
             qfunc = QFunc(func)
         if synthesize_separately:
             qfunc.update_compilation_metadata(should_synthesize_separately=True)
+        if atomic_qualifiers is not None and len(atomic_qualifiers) > 0:
+            qfunc.update_compilation_metadata(atomic_qualifiers=atomic_qualifiers)
         return qfunc
 
     if func is not None:
         return wrapper(func)
-
     return wrapper
+
+
+def _validate_directives(
+    synthesize_separately: bool, atomic_qualifiers: Optional[list[str]] = None
+) -> None:
+    error_msg = ""
+    if synthesize_separately:
+        error_msg += "External functions can't be marked as synthesized separately. \n"
+    if atomic_qualifiers is not None and len(atomic_qualifiers) > 0:
+        error_msg += "External functions can't have atomic qualifiers."
+    if error_msg:
+        raise ClassiqInternalError(error_msg)

classiq/qmod/qmod_variable.py

@@ -10,17 +10,19 @@ 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.proxies.quantum.qmod_qarray_proxy import (
@@ -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,15 +75,6 @@ from classiq.qmod.utilities import (
 )
 
 
-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
@@ -135,26 +129,6 @@ class QVar(Symbolic):
     def get_qmod_type(self) -> QuantumType:
         raise NotImplementedError()
 
-    @staticmethod
-    def from_type_hint(type_hint: Any) -> Optional[type["QVar"]]:
-        non_annotated_type = (
-            type_hint.__origin__
-            if isinstance(type_hint, _AnnotatedAlias)
-            else type_hint
-        )
-        type_ = get_origin(non_annotated_type) or non_annotated_type
-        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(
@@ -165,14 +139,6 @@ class QVar(Symbolic):
     ) -> Self:
         raise NotImplementedError()
 
-    @classmethod
-    def port_direction(cls, type_hint: Any) -> PortDeclarationDirection:
-        if isinstance(type_hint, _AnnotatedAlias):
-            for metadata in type_hint.__metadata__:
-                if isinstance(metadata, PortDeclarationDirection):
-                    return metadata
-        return PortDeclarationDirection.Inout
-
     def __str__(self) -> str:
         return self._expr_str
 
@@ -191,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):
@@ -282,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,
@@ -342,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,
@@ -386,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(
@@ -494,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,
@@ -531,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,
         )
 
@@ -558,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():
@@ -569,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,
@@ -588,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}')",
@@ -619,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))
@@ -688,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/validation/type_hints.py

@@ -6,11 +6,7 @@ from classiq.interface.exceptions import ClassiqValueError
 from classiq.interface.generator.functions.port_declaration import (
     PortDeclarationDirection,
 )
-
-annotation_map: dict[PortDeclarationDirection, str] = {
-    PortDeclarationDirection.Input: PortDeclarationDirection.Input.name,
-    PortDeclarationDirection.Output: PortDeclarationDirection.Output.name,
-}
+from classiq.interface.generator.functions.type_qualifier import TypeQualifier
 
 
 def validate_annotation(type_hint: Any) -> None:
@@ -21,9 +17,22 @@ def validate_annotation(type_hint: Any) -> None:
         for direction in type_hint.__metadata__
         if isinstance(direction, PortDeclarationDirection)
     ]
-    if len(directions) <= 1:
+    qualifiers: list[TypeQualifier] = [
+        qualifier
+        for qualifier in type_hint.__metadata__
+        if isinstance(qualifier, TypeQualifier)
+    ]
+    if len(directions) <= 1 and len(qualifiers) <= 1:
         return
-    raise ClassiqValueError(
-        f"Multiple directions are not allowed in a single type hint: "
-        f"[{', '.join(annotation_map[direction] for direction in reversed(directions))}]\n"
-    )
+    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-0.70.0.dist-info → classiq-0.71.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: classiq
-Version: 0.70.0
+Version: 0.71.0
 Summary: Classiq's Python SDK for quantum computing
 License: Proprietary
 Keywords: quantum computing,quantum circuits,quantum algorithms,QAD,QDL