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

classiq/qmod/quantum_function.py

@@ -1,60 +1,116 @@
 import ast
 import functools
-from typing import Any, Callable, Dict, List, Optional, Tuple, get_origin
+from abc import abstractmethod
+from collections import defaultdict
+from dataclasses import is_dataclass
+from enum import EnumMeta
+from inspect import isclass
+from typing import Any, Callable, Optional, get_origin
 
+from classiq.interface.exceptions import ClassiqError
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.functions.port_declaration import (
+    PortDeclarationDirection,
+)
 from classiq.interface.generator.model.constraints import Constraints
 from classiq.interface.generator.model.preferences.preferences import Preferences
-from classiq.interface.model.model import Model, SerializedModel
-from classiq.interface.model.native_function_definition import NativeFunctionDefinition
+from classiq.interface.generator.types.compilation_metadata import CompilationMetadata
+from classiq.interface.model.model import Model
+from classiq.interface.model.native_function_definition import (
+    NativeFunctionDefinition,
+)
 from classiq.interface.model.quantum_function_declaration import (
-    QuantumFunctionDeclaration,
+    NamedParamsQuantumFunctionDeclaration,
 )
 
-from classiq.exceptions import ClassiqError
 from classiq.qmod.classical_function import CFunc
 from classiq.qmod.declaration_inferrer import infer_func_decl
+from classiq.qmod.generative import set_frontend_interpreter
 from classiq.qmod.qmod_constant import QConstant
-from classiq.qmod.qmod_parameter import QParam
+from classiq.qmod.qmod_parameter import CArray, CParam
 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.utilities import mangle_keyword, unmangle_keyword
+from classiq.qmod.utilities import mangle_keyword
 
 
-def _lookup_qfunc(name: str) -> Optional[QuantumFunctionDeclaration]:
-    # FIXME: to be generalized to existing user-defined functions
-    return QuantumFunctionDeclaration.BUILTIN_FUNCTION_DECLARATIONS.get(name)
+class BaseQFunc(QExpandable):
+    def __init__(
+        self,
+        py_callable: Callable,
+        compilation_metadata: Optional[CompilationMetadata] = None,
+    ) -> None:
+        super().__init__(py_callable)
+        self.compilation_metadata = compilation_metadata
+
+    @property
+    def func_decl(self) -> NamedParamsQuantumFunctionDeclaration:
+        raise NotImplementedError
 
+    @property
+    def _has_inputs(self) -> bool:
+        return any(
+            port.direction == PortDeclarationDirection.Input
+            for port in self.func_decl.port_declarations
+        )
 
-def create_model(
-    entry_point: "QFunc",
-    constraints: Optional[Constraints] = None,
-    execution_preferences: Optional[ExecutionPreferences] = None,
-    preferences: Optional[Preferences] = None,
-    classical_execution_function: Optional[CFunc] = None,
-) -> SerializedModel:
-    return entry_point.create_model(
-        constraints, execution_preferences, preferences, classical_execution_function
-    ).get_model()
+    def update_compilation_metadata(self, **kwargs: Any) -> None:
+        if kwargs["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)
 
+    @property
+    def _compilation_metadata(self) -> CompilationMetadata:
+        if self.compilation_metadata is None:
+            return CompilationMetadata()
+        return self.compilation_metadata
 
-class QFunc(QExpandable):
-    def __init__(self, py_callable: Callable) -> None:
+    @abstractmethod
+    def create_model(
+        self,
+        constraints: Optional[Constraints] = None,
+        execution_preferences: Optional[ExecutionPreferences] = None,
+        preferences: Optional[Preferences] = None,
+        classical_execution_function: Optional[CFunc] = None,
+    ) -> Model:
+        pass
+
+
+class QFunc(BaseQFunc):
+    FRAME_DEPTH = 3
+
+    def __init__(
+        self,
+        py_callable: Callable,
+        compilation_metadata: Optional[CompilationMetadata] = None,
+    ) -> None:
         _validate_no_gen_params(py_callable.__annotations__)
-        super().__init__(py_callable)
+        super().__init__(py_callable, compilation_metadata)
         functools.update_wrapper(self, py_callable)
+        self.compilation_metadata: Optional[CompilationMetadata] = None
 
     @property
-    def func_decl(self) -> QuantumFunctionDeclaration:
-        return self._qmodule.native_defs.get(
-            self._py_callable.__name__,
-            infer_func_decl(self._py_callable, qmodule=self._qmodule),
+    def pure_decl(self) -> NamedParamsQuantumFunctionDeclaration:
+        if type(self.func_decl) is NamedParamsQuantumFunctionDeclaration:
+            return self.func_decl
+        return NamedParamsQuantumFunctionDeclaration(
+            **{
+                k: v
+                for k, v in self.func_decl.model_dump().items()
+                if k in NamedParamsQuantumFunctionDeclaration.model_fields
+            }
         )
 
+    @property
+    def func_decl(self) -> NamedParamsQuantumFunctionDeclaration:
+        name = self._py_callable.__name__
+        if hasattr(self._qmodule, "native_defs") and name in self._qmodule.native_defs:
+            return self._qmodule.native_defs[name]
+        return infer_func_decl(self._py_callable, qmodule=self._qmodule)
+
     def __call__(self, *args: Any, **kwargs: Any) -> None:
+        self.expand()
         super().__call__(*args, **kwargs)
-        self._add_native_func_def()
 
     def create_model(
         self,
@@ -63,12 +119,17 @@ class QFunc(QExpandable):
         preferences: Optional[Preferences] = None,
         classical_execution_function: Optional[CFunc] = None,
     ) -> Model:
+        self._qmodule.enum_decls = dict()
         self._qmodule.type_decls = dict()
+        self._qmodule.qstruct_decls = dict()
         self._qmodule.native_defs = dict()
         self._qmodule.constants = dict()
+        self._qmodule.functions_compilation_metadata = dict()
+        self._qmodule.generative_functions = dict()
+        self._qmodule.function_dependencies = defaultdict(list)
         QConstant.set_current_model(self._qmodule)
-        self._add_native_func_def()
-        model_extra_settings: List[Tuple[str, Any]] = [
+        self.expand()
+        model_extra_settings: list[tuple[str, Any]] = [
             ("constraints", constraints),
             ("execution_preferences", execution_preferences),
             ("preferences", preferences),
@@ -78,20 +139,51 @@ class QFunc(QExpandable):
             model_extra_settings.append(
                 ("classical_execution_code", classical_execution_function.code)
             )
-        return Model(
+        model = Model(
             constants=list(self._qmodule.constants.values()),
             functions=list(self._qmodule.native_defs.values()),
+            enums=list(self._qmodule.enum_decls.values()),
             types=list(self._qmodule.type_decls.values()),
+            qstructs=list(self._qmodule.qstruct_decls.values()),
+            functions_compilation_metadata=self._qmodule.functions_compilation_metadata,
             **{key: value for key, value in model_extra_settings if value},
         )
+        if len(self._qmodule.generative_functions) > 0:
+            return self._create_generative_model(model)
+        return model
+
+    def _create_generative_model(self, model_stub: Model) -> Model:
+        from classiq.model_expansions.interpreters.frontend_generative_interpreter import (
+            FrontendGenerativeInterpreter,
+        )
+        from classiq.qmod.semantics.annotation.call_annotation import (
+            resolve_function_calls,
+        )
 
-    def _add_native_func_def(self) -> None:
+        generative_functions = list(self._qmodule.generative_functions.values())
+        resolve_function_calls(
+            model_stub,
+            dict(model_stub.function_dict)
+            | {
+                gen_func.func_decl.name: gen_func.func_decl
+                for gen_func in generative_functions
+            },
+        )
+        interpreter = FrontendGenerativeInterpreter(model_stub, generative_functions)
+        set_frontend_interpreter(interpreter)
+        return interpreter.expand()
+
+    def expand(self) -> None:
         if self.func_decl.name in self._qmodule.native_defs:
             return
-        self.expand()
+        super().expand()
         self._qmodule.native_defs[self.func_decl.name] = NativeFunctionDefinition(
-            **self.func_decl.__dict__, body=self.body
+            **{**self.func_decl.model_dump(), **{"body": self.body}}
         )
+        if self.compilation_metadata is not None:
+            self._qmodule.functions_compilation_metadata[self.func_decl.name] = (
+                self.compilation_metadata
+            )
 
     def _add_constants_from_classical_code(
         self, classical_execution_function: CFunc
@@ -120,14 +212,15 @@ class QFunc(QExpandable):
 
 
 class ExternalQFunc(QTerminalCallable):
+    _decl: NamedParamsQuantumFunctionDeclaration
+
     def __init__(self, py_callable: Callable) -> None:
-        decl = _lookup_qfunc(unmangle_keyword(py_callable.__name__))
-        if decl is None:
-            raise ClassiqError(f"Definition of {py_callable.__name__!r} not found")
+        self._py_callable = py_callable
+        decl = infer_func_decl(py_callable)
 
         py_callable.__annotations__.pop("return", None)
         if py_callable.__annotations__.keys() != {
-            mangle_keyword(arg.name) for arg in decl.get_positional_arg_decls()
+            mangle_keyword(arg.name) for arg in decl.positional_arg_declarations
         }:
             raise ClassiqError(
                 f"Parameter type hints for {py_callable.__name__!r} do not match imported declaration"
@@ -135,24 +228,86 @@ class ExternalQFunc(QTerminalCallable):
         super().__init__(decl)
         functools.update_wrapper(self, py_callable)
 
+    @property
+    def func_decl(self) -> NamedParamsQuantumFunctionDeclaration:
+        return self._decl
+
+    @property
+    def pure_decl(self) -> NamedParamsQuantumFunctionDeclaration:
+        return self.func_decl
+
+    def get_implementation(self) -> NativeFunctionDefinition:
+        model = QFunc(self._py_callable).create_model()
+        return [
+            func for func in model.functions if func.name == self._py_callable.__name__
+        ][0]
+
+
+class GenerativeQFunc(BaseQFunc):
+    FRAME_DEPTH = 3
+
+    def __init__(
+        self,
+        py_callable: Callable,
+        func_decl: Optional[NamedParamsQuantumFunctionDeclaration] = None,
+        compilation_metadata: Optional[CompilationMetadata] = None,
+    ) -> None:
+        super().__init__(py_callable, compilation_metadata)
+        self._func_decl = func_decl
+
+    @property
+    def func_decl(self) -> NamedParamsQuantumFunctionDeclaration:
+        if self._func_decl is None:
+            self._func_decl = infer_func_decl(self._py_callable, self._qmodule)
+        return self._func_decl
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:
+        self._qmodule.generative_functions[self.func_decl.name] = self
+        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,
+    ) -> Model:
+        def _dec_main(*args: Any, **kwargs: Any) -> None:
+            self(*args, **kwargs)
+
+        _dec_main.__annotations__ = self._py_callable.__annotations__
+
+        return QFunc(_dec_main).create_model(
+            constraints=constraints,
+            execution_preferences=execution_preferences,
+            preferences=preferences,
+            classical_execution_function=classical_execution_function,
+        )
+
 
 ILLEGAL_PARAM_ERROR = "Unsupported type hint '{annotation}' for argument '{name}'."
 
 
 class IllegalParamsError(ClassiqError):
-    _HINT = "\nNote - QMOD functions can declare classical parameters using the type hint 'QParam'."
+    _HINT = (
+        "\nNote - QMOD functions can declare classical parameters using the type hints "
+        "'CInt', 'CReal', 'CBool', and 'CArray'."
+    )
 
     def __init__(self, message: str) -> None:
         super().__init__(message + self._HINT)
 
 
-def _validate_no_gen_params(annotations: Dict[str, Any]) -> None:
+def _validate_no_gen_params(annotations: dict[str, Any]) -> None:
     _illegal_params = {
         name: annotation
         for name, annotation in annotations.items()
         if not (
             name == "return"
-            or get_origin(annotation) is QParam
+            or (isclass(annotation) and issubclass(annotation, CParam))
+            or (isclass(annotation) and is_dataclass(annotation))
+            or (isclass(annotation) and isinstance(annotation, EnumMeta))
+            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

classiq/qmod/semantics/annotation/call_annotation.py

@@ -0,0 +1,92 @@
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+from classiq.interface.exceptions import ClassiqError
+from classiq.interface.generator.visitor import Visitor
+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 (
+    AnonQuantumOperandDeclaration,
+    QuantumFunctionDeclaration,
+    QuantumOperandDeclaration,
+)
+from classiq.interface.model.quantum_lambda_function import (
+    QuantumLambdaFunction,
+)
+
+from classiq.qmod.builtins.functions import BUILTIN_FUNCTION_DECLARATIONS
+from classiq.qmod.semantics.annotation.qstruct_annotator import QStructAnnotator
+from classiq.qmod.semantics.error_manager import ErrorManager
+from classiq.qmod.semantics.lambdas import get_renamed_parameters
+
+
+def _annotate_function_call_decl(
+    fc: QuantumFunctionCall,
+    function_dict: Mapping[str, QuantumFunctionDeclaration],
+) -> None:
+    if fc._func_decl is None:
+        func_decl = function_dict.get(fc.func_name)
+        if func_decl is None:
+            raise ClassiqError(
+                f"Error resolving function {fc.func_name}, the function is not found in included library."
+            )
+        fc.set_func_decl(func_decl)
+
+    for arg, param in zip(fc.positional_args, fc.func_decl.positional_arg_declarations):
+        if not isinstance(param, AnonQuantumOperandDeclaration):
+            continue
+        args: list
+        if isinstance(arg, list):
+            args = arg
+        else:
+            args = [arg]
+        for qlambda in args:
+            if isinstance(qlambda, QuantumLambdaFunction):
+                qlambda.set_op_decl(param)
+
+
+class _CallLambdaAnnotator(Visitor):
+    def __init__(
+        self, quantum_functions: Mapping[str, QuantumFunctionDeclaration]
+    ) -> None:
+        self._quantum_functions = dict(quantum_functions)
+        self._current_operands: dict[str, QuantumOperandDeclaration] = {}
+
+    @contextmanager
+    def set_operands(
+        self, operands: dict[str, QuantumOperandDeclaration]
+    ) -> Iterator[None]:
+        previous_operands = self._current_operands
+        self._current_operands = operands
+        yield
+        self._current_operands = previous_operands
+
+    def visit_NativeFunctionDefinition(self, func: NativeFunctionDefinition) -> None:
+        with self.set_operands(func.operand_declarations_dict):
+            self.generic_visit(func)
+
+    def visit_QuantumLambdaFunction(self, lambda_func: QuantumLambdaFunction) -> None:
+        lambda_operands = get_renamed_parameters(lambda_func)[1]
+        with self.set_operands(self._current_operands | lambda_operands):
+            self.generic_visit(lambda_func)
+
+    def visit_QuantumFunctionCall(self, call: QuantumFunctionCall) -> None:
+        _annotate_function_call_decl(
+            call, self._quantum_functions | self._current_operands
+        )
+        self.generic_visit(call)
+
+
+def resolve_function_calls(
+    root: Any,
+    quantum_function_dict: Mapping[str, QuantumFunctionDeclaration],
+) -> None:
+    all_functions: Mapping[str, QuantumFunctionDeclaration] = {
+        **BUILTIN_FUNCTION_DECLARATIONS,
+        **quantum_function_dict,
+    }
+    with ErrorManager().ignore_errors_context():
+        QStructAnnotator().visit(quantum_function_dict)
+        QStructAnnotator().visit(root)
+        _CallLambdaAnnotator(all_functions).visit(root)

classiq/qmod/semantics/annotation/qstruct_annotator.py

@@ -0,0 +1,23 @@
+from classiq.interface.generator.functions.type_name import TypeName
+from classiq.interface.generator.visitor import Visitor
+
+from classiq.qmod.model_state_container import QMODULE
+
+
+class QStructAnnotator(Visitor):
+    def __init__(self) -> None:
+        self._visited: set[TypeName] = set()
+
+    def visit_TypeName(self, type_name: TypeName) -> None:
+        decl = QMODULE.qstruct_decls.get(type_name.name)
+        if decl is None or type_name.has_fields or (type_name in self._visited):
+            return
+        self._visited.add(type_name)
+        new_fields = {
+            field_name: field_type.model_copy()
+            for field_name, field_type in decl.fields.items()
+        }
+        # We first visit the new fields and then set to deal with recursive
+        # qstructs
+        self.visit(new_fields)
+        type_name.set_fields(new_fields)

classiq/qmod/semantics/error_manager.py

@@ -0,0 +1,88 @@
+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 SourceReferencedError
+
+
+class ErrorManager:
+    def __new__(cls) -> "ErrorManager":
+        if not hasattr(cls, "_instance"):
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self) -> None:
+        if hasattr(self, "_instantiated"):
+            return
+        self._instantiated = True
+        self._errors: list[SourceReferencedError] = []
+        self._current_nodes_stack: list[ASTNode] = []
+        self._call_stack: list[str] = []
+        self._ignore_errors: bool = False
+
+    @contextmanager
+    def ignore_errors_context(self) -> Iterator[None]:
+        previous = self._ignore_errors
+        self._ignore_errors = True
+        try:
+            yield
+        finally:
+            self._ignore_errors = previous
+
+    @property
+    def annotated_errors(self) -> list[str]:
+        return [str(error) for error in self._errors]
+
+    def add_error(self, error: str) -> None:
+        if not self._ignore_errors:
+            self._errors.append(
+                SourceReferencedError(
+                    error=error.replace(CLASSIQ_SLACK_COMMUNITY_LINK, ""),
+                    source_ref=(
+                        self._current_nodes_stack[-1].source_ref
+                        if self._current_nodes_stack
+                        else None
+                    ),
+                    function=self.current_function,
+                )
+            )
+
+    def get_errors(self) -> list[SourceReferencedError]:
+        return self._errors
+
+    def clear(self) -> None:
+        self._current_nodes_stack = []
+        self._errors = []
+
+    def has_errors(self) -> bool:
+        return len(self._errors) > 0
+
+    def report_errors(self, error_type: type[Exception]) -> None:
+        if self.has_errors():
+            errors = self.annotated_errors
+            self.clear()
+            raise error_type("\n\t" + "\n\t".join(errors))
+
+    @property
+    def current_function(self) -> Optional[str]:
+        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)
+        yield
+        self._current_nodes_stack.pop()
+
+    @contextmanager
+    def call(self, func_name: str) -> Iterator[None]:
+        self._call_stack.append(func_name)
+        yield
+        self._call_stack.pop()
+
+
+def append_error(node: ASTNode, message: str) -> None:
+    instance = ErrorManager()
+    with instance.node_context(node):
+        instance.add_error(message)

classiq/qmod/semantics/lambdas.py

@@ -0,0 +1,25 @@
+from classiq.interface.model.port_declaration import PortDeclaration
+from classiq.interface.model.quantum_function_declaration import (
+    AnonQuantumOperandDeclaration,
+    QuantumOperandDeclaration,
+)
+from classiq.interface.model.quantum_lambda_function import QuantumLambdaFunction
+
+from classiq import AnonClassicalParameterDeclaration
+
+
+def get_renamed_parameters(
+    lambda_func: QuantumLambdaFunction,
+) -> tuple[list[str], dict[str, QuantumOperandDeclaration], list[PortDeclaration]]:
+    renamed_parameters: list[str] = []
+    renamed_operands: dict[str, QuantumOperandDeclaration] = {}
+    renamed_ports: list[PortDeclaration] = []
+    for idx, param in enumerate(lambda_func.func_decl.positional_arg_declarations):
+        param_name = lambda_func.pos_rename_params[idx]
+        if isinstance(param, AnonClassicalParameterDeclaration):
+            renamed_parameters.append(param_name)
+        elif isinstance(param, AnonQuantumOperandDeclaration):
+            renamed_operands[param_name] = param.rename(param_name)
+        else:
+            renamed_ports.append(param.rename(param_name))
+    return renamed_parameters, renamed_operands, renamed_ports