classiq 0.92.0__py3-none-any.whl → 0.99.0__py3-none-any.whl

classiq/qmod/quantum_function.py

@@ -2,10 +2,11 @@ import ast
 import functools
 import warnings
 from abc import abstractmethod
+from collections.abc import Callable
 from dataclasses import is_dataclass
 from enum import EnumMeta
 from inspect import isclass
-from typing import Any, Callable, Optional, get_origin
+from typing import Any, get_origin
 
 from classiq.interface.exceptions import ClassiqDeprecationWarning, ClassiqError
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
@@ -30,7 +31,7 @@ from classiq.qmod.generative import set_frontend_interpreter
 from classiq.qmod.global_declarative_switch import get_global_declarative_switch
 from classiq.qmod.qmod_constant import QConstant
 from classiq.qmod.qmod_parameter import CArray, CParamList
-from classiq.qmod.quantum_callable import QCallable, QCallableList
+from classiq.qmod.quantum_callable import QCallable, QCallableList, QPerm, QPermList
 from classiq.qmod.quantum_expandable import QExpandable, QTerminalCallable
 from classiq.qmod.semantics.annotation.qstruct_annotator import QStructAnnotator
 from classiq.qmod.semantics.validation.main_validation import validate_main_function
@@ -41,11 +42,13 @@ class BaseQFunc(QExpandable):
     def __init__(
         self,
         py_callable: Callable,
-        compilation_metadata: Optional[CompilationMetadata] = None,
+        compilation_metadata: CompilationMetadata | None = None,
+        permutation: bool = False,
     ) -> None:
         super().__init__(py_callable)
         functools.update_wrapper(self, py_callable)
         self.compilation_metadata = compilation_metadata
+        self.permutation = permutation
 
     @property
     def func_decl(self) -> NamedParamsQuantumFunctionDeclaration:
@@ -84,10 +87,10 @@ class BaseQFunc(QExpandable):
     @abstractmethod
     def create_model(
         self,
-        constraints: Optional[Constraints] = None,
-        execution_preferences: Optional[ExecutionPreferences] = None,
-        preferences: Optional[Preferences] = None,
-        classical_execution_function: Optional[CFunc] = None,
+        constraints: Constraints | None = None,
+        execution_preferences: ExecutionPreferences | None = None,
+        preferences: Preferences | None = None,
+        classical_execution_function: CFunc | None = None,
     ) -> Model:
         pass
 
@@ -98,13 +101,17 @@ class QFunc(BaseQFunc):
     def __init__(
         self,
         py_callable: Callable,
-        compilation_metadata: Optional[CompilationMetadata] = None,
+        compilation_metadata: CompilationMetadata | None = None,
+        permutation: bool = False,
     ) -> None:
         _validate_no_gen_params(py_callable.__annotations__)
-        super().__init__(py_callable, compilation_metadata)
-        if compilation_metadata is not None and compilation_metadata.unchecked:
-            self.compilation_metadata: Optional[CompilationMetadata] = (
-                CompilationMetadata(unchecked=compilation_metadata.unchecked)
+        super().__init__(py_callable, compilation_metadata, permutation)
+        if (
+            compilation_metadata is not None
+            and compilation_metadata.has_user_directives
+        ):
+            self.compilation_metadata: CompilationMetadata | None = (
+                compilation_metadata.copy_user_directives()
             )
         else:
             self.compilation_metadata = None
@@ -114,7 +121,9 @@ class QFunc(BaseQFunc):
         name = self._py_callable.__name__
         if name in self._qmodule.native_defs:
             return self._qmodule.native_defs[name]
-        return infer_func_decl(self._py_callable, qmodule=self._qmodule)
+        return infer_func_decl(
+            self._py_callable, qmodule=self._qmodule, permutation=self.permutation
+        )
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:
         self.expand()
@@ -122,10 +131,10 @@ class QFunc(BaseQFunc):
 
     def create_model(
         self,
-        constraints: Optional[Constraints] = None,
-        execution_preferences: Optional[ExecutionPreferences] = None,
-        preferences: Optional[Preferences] = None,
-        classical_execution_function: Optional[CFunc] = None,
+        constraints: Constraints | None = None,
+        execution_preferences: ExecutionPreferences | None = None,
+        preferences: Preferences | None = None,
+        classical_execution_function: CFunc | None = None,
     ) -> Model:
         self._qmodule.reset()
         QConstant.set_current_model(self._qmodule)
@@ -222,9 +231,10 @@ class ExternalQFunc(QTerminalCallable):
     FRAME_DEPTH = 2  # FIXME: Remove (CLS-2912)
     _decl: NamedParamsQuantumFunctionDeclaration
 
-    def __init__(self, py_callable: Callable) -> None:
+    def __init__(self, py_callable: Callable, permutation: bool = False) -> None:
         self._py_callable = py_callable
-        decl = infer_func_decl(py_callable)
+        self.permutation = permutation
+        decl = infer_func_decl(py_callable, permutation=permutation)
 
         py_callable.__annotations__.pop("return", None)
         if py_callable.__annotations__.keys() != {
@@ -272,10 +282,39 @@ class ExternalQFunc(QTerminalCallable):
         ):
             warnings.warn(
                 (
-                    "Parameter type CArray[PauliTerm] to function 'suzuki_trotter' is "
-                    "deprecated and will no longer be supported starting on 21/7/2025 "
-                    "at the earliest. Instead, send a 'SparsePauliOp' (see "
-                    "https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/#hamiltonians)."
+                    "Function 'suzuki_trotter' now receives a sparse Hamiltonian "
+                    "('SparsePauliOp') instead of a list of non-sparse Pauli terms "
+                    "('CArray[PauliTerm]').\n"
+                    "Non-sparse pauli terms in 'suzuki_trotter' will no longer be "
+                    "supported starting on 2025-07-21 at the earliest.\n"
+                    "See https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/#hamiltonians"
+                ),
+                ClassiqDeprecationWarning,
+                stacklevel=2,
+            )
+        if (
+            self._py_callable.__name__ == "qdrift"
+            and len(args) > 0
+            and isinstance(args[0], (list, CParamList))
+        ):
+            warnings.warn(
+                (
+                    "Function 'qdrift' now receives a sparse Hamiltonian "
+                    "('SparsePauliOp') instead of a list of non-sparse Pauli terms "
+                    "('CArray[PauliTerm]').\n"
+                    "Non-sparse pauli terms in 'qdrift' will no longer be "
+                    "supported starting on 2025-12-03 at the earliest.\n"
+                    "See https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/#hamiltonians"
+                ),
+                ClassiqDeprecationWarning,
+                stacklevel=2,
+            )
+        if self._py_callable.__name__ == "exponentiation_with_depth_constraint":
+            warnings.warn(
+                (
+                    "Function 'exponentiation_with_depth_constraint' is deprecated and will no "
+                    "longer be supported starting on 2025-12-10 at the earliest. "
+                    "Instead, use 'exponentiate'."
                 ),
                 ClassiqDeprecationWarning,
                 stacklevel=2,
@@ -289,41 +328,48 @@ class GenerativeQFunc(BaseQFunc):
     def __init__(
         self,
         py_callable: Callable,
-        func_decl: Optional[NamedParamsQuantumFunctionDeclaration] = None,
-        compilation_metadata: Optional[CompilationMetadata] = None,
+        func_decl: NamedParamsQuantumFunctionDeclaration | None = None,
+        compilation_metadata: CompilationMetadata | None = None,
+        permutation: bool = False,
     ) -> None:
-        super().__init__(py_callable, compilation_metadata)
+        super().__init__(py_callable, compilation_metadata, permutation)
         self._func_decl = func_decl
-        self._inferred_func_decl: Optional[NamedParamsQuantumFunctionDeclaration] = None
+        self._inferred_func_decl: NamedParamsQuantumFunctionDeclaration | None = None
 
     @property
     def func_decl(self) -> NamedParamsQuantumFunctionDeclaration:
         if self._func_decl is not None:
             return self._func_decl
         if self._inferred_func_decl is None:
-            self._inferred_func_decl = infer_func_decl(self._py_callable, self._qmodule)
+            self._inferred_func_decl = infer_func_decl(
+                self._py_callable, self._qmodule, permutation=self.permutation
+            )
         return self._inferred_func_decl
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:
         if get_global_declarative_switch():
-            return QFunc(self._py_callable, self.compilation_metadata)(*args, **kwargs)
+            return QFunc(
+                self._py_callable,
+                self.compilation_metadata,
+                permutation=self.permutation,
+            )(*args, **kwargs)
         if self.func_decl.name not in self._qmodule.generative_functions:
             self._qmodule.generative_functions[self.func_decl.name] = self
             if self._func_decl is None:
                 self._inferred_func_decl = infer_func_decl(
-                    self._py_callable, self._qmodule
+                    self._py_callable, self._qmodule, permutation=self.permutation
                 )
         super().__call__(*args, **kwargs)
 
     def create_model(
         self,
-        constraints: Optional[Constraints] = None,
-        execution_preferences: Optional[ExecutionPreferences] = None,
-        preferences: Optional[Preferences] = None,
-        classical_execution_function: Optional[CFunc] = None,
+        constraints: Constraints | None = None,
+        execution_preferences: ExecutionPreferences | None = None,
+        preferences: Preferences | None = None,
+        classical_execution_function: CFunc | None = None,
     ) -> Model:
         if get_global_declarative_switch():
-            return QFunc(self._py_callable).create_model(
+            return QFunc(self._py_callable, permutation=self.permutation).create_model(
                 constraints,
                 execution_preferences,
                 preferences,
@@ -338,7 +384,7 @@ class GenerativeQFunc(BaseQFunc):
 
         _dec_main.__annotations__ = self._py_callable.__annotations__
 
-        return QFunc(_dec_main).create_model(
+        return QFunc(_dec_main, permutation=self.permutation).create_model(
             constraints=constraints,
             execution_preferences=execution_preferences,
             preferences=preferences,
@@ -371,6 +417,8 @@ 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 (get_origin(annotation) or annotation) is QPerm
+            or (get_origin(annotation) or annotation) is QPermList
             or is_qvar(annotation)
         )
     }

classiq/qmod/semantics/annotation/call_annotation.py

@@ -1,10 +1,10 @@
 from collections.abc import Iterator, Mapping
 from contextlib import contextmanager
-from typing import Any, Optional
+from typing import Any
 
 from classiq.interface.exceptions import ClassiqError
 from classiq.interface.model.model import Model
-from classiq.interface.model.model_visitor import ModelVisitor
+from classiq.interface.model.model_visitor import ModelStatementsVisitor
 from classiq.interface.model.native_function_definition import NativeFunctionDefinition
 from classiq.interface.model.quantum_function_call import QuantumFunctionCall
 from classiq.interface.model.quantum_function_declaration import (
@@ -47,7 +47,7 @@ def _annotate_function_call_decl(
                 qlambda.set_op_decl(param)
 
 
-class _CallLambdaAnnotator(ModelVisitor):
+class _CallLambdaAnnotator(ModelStatementsVisitor):
     def __init__(
         self, quantum_functions: Mapping[str, QuantumFunctionDeclaration]
     ) -> None:
@@ -76,12 +76,12 @@ class _CallLambdaAnnotator(ModelVisitor):
         _annotate_function_call_decl(
             call, self._quantum_functions | self._current_operands
         )
-        self.generic_visit(call)
+        self.visit(call.positional_args)
 
 
 def resolve_function_calls(
     root: Any,
-    quantum_function_dict: Optional[Mapping[str, QuantumFunctionDeclaration]] = None,
+    quantum_function_dict: Mapping[str, QuantumFunctionDeclaration] | None = None,
     annotate_types: bool = True,
 ) -> None:
     if quantum_function_dict is None:

classiq/qmod/semantics/error_manager.py

@@ -1,8 +1,6 @@
 from collections.abc import Iterator
 from contextlib import contextmanager
-from typing import Optional
 
-from classiq.interface.ast_node import ASTNode
 from classiq.interface.exceptions import CLASSIQ_SLACK_COMMUNITY_LINK
 from classiq.interface.source_reference import SourceReference, SourceReferencedError
 
@@ -19,14 +17,14 @@ class ErrorManager:
         self._instantiated = True
         self._errors: list[SourceReferencedError] = []
         self._warnings: list[SourceReferencedError] = []
-        self._current_nodes_stack: list[ASTNode] = []
+        self._current_refs_stack: list[SourceReference | None] = []
         self._call_stack: list[str] = []
         self._ignore_errors: bool = False
 
     @property
-    def _current_source_ref(self) -> Optional[SourceReference]:
-        if self._current_nodes_stack:
-            return self._current_nodes_stack[-1].source_ref
+    def _current_source_ref(self) -> SourceReference | None:
+        if self._current_refs_stack:
+            return self._current_refs_stack[-1]
         return None
 
     @contextmanager
@@ -50,8 +48,8 @@ class ErrorManager:
         self,
         error: str,
         *,
-        source_ref: Optional[SourceReference] = None,
-        function: Optional[str] = None,
+        source_ref: SourceReference | None = None,
+        function: str | None = None,
         warning: bool = False,
     ) -> None:
         if self._ignore_errors:
@@ -80,7 +78,7 @@ class ErrorManager:
         self.clear_warnings()
 
     def clear_errors(self) -> None:
-        self._current_nodes_stack = []
+        self._current_refs_stack = []
         self._errors = []
 
     def clear_warnings(self) -> None:
@@ -93,7 +91,7 @@ class ErrorManager:
         return len(self._warnings) > 0
 
     def report_errors(
-        self, error_type: type[Exception], mask: Optional[list[int]] = None
+        self, error_type: type[Exception], mask: list[int] | None = None
     ) -> None:
         if self.has_errors():
             errors = (
@@ -105,14 +103,14 @@ class ErrorManager:
             raise error_type("\n\t" + "\n\t".join(errors))
 
     @property
-    def current_function(self) -> Optional[str]:
+    def current_function(self) -> str | None:
         return self._call_stack[-1] if self._call_stack else None
 
     @contextmanager
-    def node_context(self, node: ASTNode) -> Iterator[None]:
-        self._current_nodes_stack.append(node)
+    def source_ref_context(self, ref: SourceReference | None) -> Iterator[None]:
+        self._current_refs_stack.append(ref)
         yield
-        self._current_nodes_stack.pop()
+        self._current_refs_stack.pop()
 
     @contextmanager
     def call(self, func_name: str) -> Iterator[None]:

classiq/qmod/semantics/lambdas.py

@@ -1,4 +1,3 @@
-from classiq.interface.helpers.backward_compatibility import zip_strict
 from classiq.interface.model.port_declaration import PortDeclaration
 from classiq.interface.model.quantum_function_declaration import (
     AnonQuantumOperandDeclaration,
@@ -15,7 +14,7 @@ def get_renamed_parameters(
     renamed_parameters: list[str] = []
     renamed_operands: dict[str, QuantumOperandDeclaration] = {}
     renamed_ports: list[PortDeclaration] = []
-    for param, param_name in zip_strict(
+    for param, param_name in zip(
         lambda_func.func_decl.positional_arg_declarations,
         lambda_func.pos_rename_params,
         strict=False,

classiq/qmod/semantics/validation/types_validation.py

@@ -1,5 +1,4 @@
 from collections.abc import Sequence
-from typing import Union
 
 from classiq.interface.exceptions import ClassiqExpansionError
 from classiq.interface.generator.functions.type_name import TypeName
@@ -16,7 +15,7 @@ TYPE_EXISTS_ERROR_MESSAGE = "Type {!r} already exists"
 
 
 def check_duplicate_types(
-    types: Sequence[Union[EnumDeclaration, StructDeclaration, QStructDeclaration]],
+    types: Sequence[EnumDeclaration | StructDeclaration | QStructDeclaration],
 ) -> None:
     known_types = {type_.name for type_ in BUILTIN_ENUM_DECLARATIONS.values()}
     known_types |= {type_.name for type_ in BUILTIN_STRUCT_DECLARATIONS.values()}

classiq/qmod/symbolic.py

@@ -2,9 +2,7 @@ import sys
 from typing import (
     TYPE_CHECKING,
     Any,
-    Optional,
     TypeVar,
-    Union,
     overload,
 )
 
@@ -52,7 +50,7 @@ def symbolic_function(*args: Any, return_type: None = None) -> CParamScalar: ...
 def symbolic_function(*args: Any, return_type: type[T]) -> T: ...
 
 
-def symbolic_function(*args: Any, return_type: Optional[type[T]] = None) -> CParam:
+def symbolic_function(*args: Any, return_type: type[T] | None = None) -> CParam:
     qmodule = (
         model_state_container.QMODULE
     )  # FIXME: https://classiq.atlassian.net/browse/CAD-15126
@@ -321,7 +319,7 @@ def _subscript_to_str(index: Any) -> str:
 
 
 def subscript(
-    array: Union[list, CArray[CReal], np.ndarray],
+    array: list | CArray[CReal] | np.ndarray,
     index: Any,
 ) -> CParamScalar:
     return CParamScalar(

classiq/qmod/symbolic_expr.py

@@ -6,6 +6,8 @@ from typing import Any
 
 import sympy
 
+from classiq.interface.exceptions import ClassiqTypeError
+
 from classiq.qmod.utilities import qmod_val_to_expr_str
 
 
@@ -24,7 +26,7 @@ class Symbolic:
         try:
             return bool(ast.literal_eval(self._expr))
         except ValueError:
-            raise TypeError(
+            raise ClassiqTypeError(
                 f"Symbolic expression {self._expr!r} cannot be converted to bool"
             ) from None
 
@@ -38,12 +40,16 @@ class SymbolicExpr(Symbolic):
         if not isinstance(
             lhs, (SymbolicExpr, int, float, bool, PythonEnum, sympy.Basic)
         ):
-            raise TypeError(f"Invalid lhs argument {lhs!r} for binary operation {op!r}")
+            raise ClassiqTypeError(
+                f"Invalid lhs argument {lhs!r} for binary operation {op!r}"
+            )
 
         if not isinstance(
             rhs, (SymbolicExpr, int, float, bool, PythonEnum, sympy.Basic)
         ):
-            raise TypeError(f"Invalid lhs argument {rhs!r} for binary operation {op!r}")
+            raise ClassiqTypeError(
+                f"Invalid lhs argument {rhs!r} for binary operation {op!r}"
+            )
 
         lhs_str = qmod_val_to_expr_str(lhs)
         if not isinstance(lhs, (int, float, bool, PythonEnum)):
@@ -62,7 +68,9 @@ class SymbolicExpr(Symbolic):
     @staticmethod
     def _unary_op(arg: Any, op: str) -> SymbolicExpr:
         if not isinstance(arg, (SymbolicExpr, int, float, bool)):
-            raise TypeError(f"Invalid argument {arg!r} for unary operation {op!r}")
+            raise ClassiqTypeError(
+                f"Invalid argument {arg!r} for unary operation {op!r}"
+            )
 
         arg_is_quantum = isinstance(arg, SymbolicExpr) and arg.is_quantum
 

classiq/qmod/utilities.py

@@ -3,17 +3,14 @@ import inspect
 import itertools
 import keyword
 import sys
-from collections import Counter
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from enum import Enum as PythonEnum
 from types import FrameType
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     ForwardRef,
     Literal,
-    Optional,
     Union,
     get_args,
     get_origin,
@@ -49,7 +46,7 @@ def unmangle_keyword(name: None) -> None:
     pass
 
 
-def unmangle_keyword(name: Optional[str]) -> Optional[str]:
+def unmangle_keyword(name: str | None) -> str | None:
     if name is None:
         return None
     if name[-1] == "_" and keyword.iskeyword(name[:-1]):
@@ -60,10 +57,7 @@ def unmangle_keyword(name: Optional[str]) -> Optional[str]:
 def version_portable_get_args(py_type: type) -> tuple:
     if get_origin(py_type) is None:
         return tuple()
-    if sys.version_info[0:2] < (3, 10):
-        type_args = get_args(py_type)  # The result of __class_getitem__
-    else:
-        type_args = get_args(py_type)[0]
+    type_args = get_args(py_type)[0]
     if not isinstance(type_args, tuple):
         return (type_args,)
     return tuple(
@@ -76,6 +70,12 @@ def version_portable_get_args(py_type: type) -> tuple:
     )
 
 
+def type_to_str(py_type: Any) -> str:
+    if isinstance(py_type, type):
+        return py_type.__name__
+    return str(py_type)
+
+
 def get_source_ref(frame: FrameType) -> SourceReference:
     filename = inspect.getfile(frame)
     lineno = frame.f_lineno
@@ -101,6 +101,8 @@ def get_source_ref(frame: FrameType) -> SourceReference:
 
 
 def qmod_val_to_expr_str(val: Any) -> str:
+    from classiq.qmod.qmod_parameter import CParamList
+
     if isinstance(val, sympy.Basic):
         return str(val)
 
@@ -122,7 +124,7 @@ def qmod_val_to_expr_str(val: Any) -> str:
         )
         return f"struct_literal({val.struct_declaration.name}, {kwargs_str})"
 
-    if isinstance(val, Iterable):
+    if isinstance(val, Iterable) and not isinstance(val, CParamList):
         elements_str = ", ".join([qmod_val_to_expr_str(elem) for elem in val])
         return f"[{elements_str}]"
 
@@ -138,7 +140,7 @@ def unwrap_forward_ref(x: Any) -> Any:
     return x
 
 
-def varname(depth: int) -> Optional[str]:
+def varname(depth: int) -> str | None:
     frame = sys._getframe(depth)
     codes = inspect.getframeinfo(frame).code_context
     if codes is None or len(codes) != 1:
@@ -192,13 +194,4 @@ def qnum_attributes(max_size: int) -> list[tuple[int, bool, int]]:
     ]
 
 
-_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]

classiq/qmod/write_qmod.py

@@ -1,6 +1,5 @@
 import json
 from pathlib import Path
-from typing import Optional, Union
 
 from classiq.interface.constants import DEFAULT_DECIMAL_PRECISION
 from classiq.interface.model.model import Model, SerializedModel
@@ -14,9 +13,9 @@ _SYNTHESIS_OPTIONS_SUFFIX = "synthesis_options.json"
 
 
 def write_qmod(
-    model: Union[SerializedModel, QFunc, GenerativeQFunc],
+    model: SerializedModel | QFunc | GenerativeQFunc,
     name: str,
-    directory: Optional[Path] = None,
+    directory: Path | None = None,
     decimal_precision: int = DEFAULT_DECIMAL_PRECISION,
     symbolic_only: bool = True,
 ) -> None:
@@ -58,7 +57,7 @@ def write_qmod(
 
 
 def prepare_write_qmod_model(
-    model: Union[SerializedModel, QFunc, GenerativeQFunc], symbolic_only: bool
+    model: SerializedModel | QFunc | GenerativeQFunc, symbolic_only: bool
 ) -> Model:
     if isinstance(model, str) and hasattr(model, "entry_point") and symbolic_only:
         model_obj = Model.model_validate_json(model)

classiq/quantum_program.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from classiq.interface.executor.quantum_program_params import (
     ParameterAssignmentsParams,
     TranspilationParams,
@@ -19,7 +17,7 @@ async def transpile_async(params: TranspilationParams) -> QuantumProgram:
 
 
 def transpile(
-    quantum_program: QuantumProgram, preferences: Optional[Preferences] = None
+    quantum_program: QuantumProgram, preferences: Preferences | None = None
 ) -> QuantumProgram:
     """
     Transpiles a quantum program.

classiq/synthesis.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional, Union
+from typing import Any
 
 from classiq.interface.analyzer.result import QasmCode, QmodCode
 from classiq.interface.exceptions import ClassiqError, ClassiqValueError
@@ -62,10 +62,10 @@ async def synthesize_async(
 
 
 def synthesize(
-    model: Union[SerializedModel, BaseQFunc],
+    model: SerializedModel | BaseQFunc,
     auto_show: bool = False,
-    constraints: Optional[Constraints] = None,
-    preferences: Optional[Preferences] = None,
+    constraints: Constraints | None = None,
+    preferences: Preferences | None = None,
 ) -> QuantumProgram:
     """
     Synthesize a model with the Classiq engine to receive a quantum program.
@@ -112,6 +112,10 @@ def qasm_to_qmod(qasm: str, qmod_format: QmodFormat) -> str:
     """
     Decompiles QASM to Native/Python Qmod.
 
+    Returns Qmod code as a string. Native Qmod can be synthesized in the Classiq IDE,
+    while Python Qmod can be copy-pasted to a Python file (`.py`) and synthesized by
+    calling `synthesize(main)`.
+
     Args:
         qasm: QASM 2 or QASM 3 code
         qmod_format: The requested output format
@@ -129,7 +133,7 @@ def qasm_to_qmod(qasm: str, qmod_format: QmodFormat) -> str:
 
 def set_preferences(
     serialized_model: SerializedModel,
-    preferences: Optional[Preferences] = None,
+    preferences: Preferences | None = None,
     **kwargs: Any,
 ) -> SerializedModel:
     """
@@ -177,7 +181,7 @@ def update_preferences(
 
 def set_constraints(
     serialized_model: SerializedModel,
-    constraints: Optional[Constraints] = None,
+    constraints: Constraints | None = None,
     **kwargs: Any,
 ) -> SerializedModel:
     """
@@ -225,7 +229,7 @@ def update_constraints(
 
 def set_execution_preferences(
     serialized_model: SerializedModel,
-    execution_preferences: Optional[ExecutionPreferences] = None,
+    execution_preferences: ExecutionPreferences | None = None,
     **kwargs: Any,
 ) -> SerializedModel:
     """