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

classiq/qmod/semantics/static_semantics_visitor.py

@@ -0,0 +1,384 @@
+import ast
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from typing import (
+    Optional,
+)
+
+from classiq.interface.exceptions import ClassiqSemanticError
+from classiq.interface.generator.expressions.expression import Expression
+from classiq.interface.generator.function_params import PortDirection
+from classiq.interface.generator.functions.classical_type import CLASSICAL_ATTRIBUTES
+from classiq.interface.generator.functions.concrete_types import ConcreteQuantumType
+from classiq.interface.generator.functions.port_declaration import (
+    PortDeclarationDirection,
+)
+from classiq.interface.generator.visitor import Visitor
+from classiq.interface.model.handle_binding import (
+    FieldHandleBinding,
+    HandleBinding,
+    SlicedHandleBinding,
+    SubscriptHandleBinding,
+)
+from classiq.interface.model.inplace_binary_operation import InplaceBinaryOperation
+from classiq.interface.model.model import Model
+from classiq.interface.model.native_function_definition import NativeFunctionDefinition
+from classiq.interface.model.port_declaration import PortDeclaration
+from classiq.interface.model.quantum_expressions.quantum_expression import (
+    QuantumExpressionOperation,
+)
+from classiq.interface.model.quantum_function_call import QuantumFunctionCall
+from classiq.interface.model.quantum_function_declaration import (
+    QuantumFunctionDeclaration,
+    QuantumOperandDeclaration,
+)
+from classiq.interface.model.quantum_lambda_function import (
+    QuantumLambdaFunction,
+)
+from classiq.interface.model.quantum_statement import HandleMetadata, QuantumOperation
+from classiq.interface.model.validation_handle import HandleState
+from classiq.interface.model.variable_declaration_statement import (
+    VariableDeclarationStatement,
+)
+from classiq.interface.model.within_apply_operation import WithinApply
+
+from classiq.model_expansions.visitors.variable_references import VarRefCollector
+from classiq.qmod.builtins.functions import (
+    BUILTIN_FUNCTION_DECLARATIONS,
+)
+from classiq.qmod.semantics.annotation.call_annotation import resolve_function_calls
+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
+from classiq.qmod.semantics.validation.constants_validation import (
+    check_duplicate_constants,
+)
+from classiq.qmod.semantics.validation.func_call_validation import (
+    check_no_overlapping_quantum_args,
+    validate_call_arguments,
+)
+from classiq.qmod.semantics.validation.function_name_collisions_validation import (
+    _check_function_name_collisions,
+)
+from classiq.qmod.semantics.validation.handle_validation import resolve_handle
+from classiq.qmod.semantics.validation.main_validation import validate_main_function
+from classiq.qmod.semantics.validation.types_validation import (
+    check_cstruct_has_fields,
+    check_duplicate_types,
+    check_qstruct_fields_are_defined,
+    check_qstruct_flexibility,
+    check_qstruct_has_fields,
+    check_qstruct_is_not_recursive,
+)
+
+HANDLE_BINDING_PART_MESSAGE = {
+    SubscriptHandleBinding: "array subscript",
+    SlicedHandleBinding: "array slice",
+    FieldHandleBinding: "field access",
+}
+
+
+class StaticScope:
+    def __init__(
+        self,
+        parameters: list[str],
+        operands: dict[str, QuantumOperandDeclaration],
+        variables_to_states: dict[str, HandleState],
+        variables_to_types: dict[str, ConcreteQuantumType],
+    ) -> None:
+        self.parameters = parameters
+        self.operands = operands
+        self.variable_states = variables_to_states
+        self.variables_to_types = variables_to_types
+
+
+class StaticSemanticsVisitor(Visitor):
+    def __init__(
+        self,
+        functions_dict: Mapping[str, QuantumFunctionDeclaration],
+        constants: list[str],
+    ) -> None:
+        self._scope: list[StaticScope] = []
+        self._error_manager = ErrorManager()
+        self._functions_dict = functions_dict
+        self._constants = constants
+
+    @property
+    def current_scope(self) -> StaticScope:
+        return self._scope[-1]
+
+    @contextmanager
+    def scoped_visit(self, scope: StaticScope) -> Iterator[None]:
+        self._scope.append(scope)
+        yield
+        self._scope.pop()
+
+    def visit_Model(self, model: Model) -> None:
+        check_duplicate_types([*model.enums, *model.types, *model.qstructs])
+        check_duplicate_constants(model.constants)
+        for qstruct in model.qstructs:
+            check_qstruct_has_fields(qstruct)
+            if check_qstruct_fields_are_defined(
+                qstruct
+            ) and check_qstruct_is_not_recursive(qstruct):
+                check_qstruct_flexibility(qstruct)
+        for cstruct in model.types:
+            check_cstruct_has_fields(cstruct)
+        validate_main_function(model.main_func)
+        self.visit_BaseModel(model)
+
+    def visit_NativeFunctionDefinition(
+        self, func_def: NativeFunctionDefinition
+    ) -> None:
+        scope = StaticScope(
+            parameters=list(func_def.param_names) + self._constants,
+            operands=dict(func_def.operand_declarations_dict),
+            variables_to_states=initialize_variables_to_state(
+                func_def.port_declarations
+            ),
+            variables_to_types={
+                port.name: port.quantum_type for port in func_def.port_declarations
+            },
+        )
+        with self.scoped_visit(scope), self._error_manager.call(func_def.name):
+            parameter_declaration_names = [
+                decl.name for decl in func_def.positional_arg_declarations
+            ]
+            seen_names: set[str] = set()
+            for name in parameter_declaration_names:
+                if name in seen_names:
+                    self._error_manager.add_error(
+                        f"duplicate parameter declaration name {name!r}"
+                    )
+                seen_names.add(name)
+            if len(func_def.body) == 0:
+                return
+            self.visit(func_def.body)
+            with self._error_manager.node_context(func_def.body[-1]):
+                for port_decl in func_def.port_declarations:
+                    handle_state = self.current_scope.variable_states[port_decl.name]
+                    expected_terminal_state = EXPECTED_TERMINAL_STATES.get(
+                        port_decl.direction
+                    )
+                    if (
+                        expected_terminal_state is not None
+                        and handle_state is not expected_terminal_state
+                    ):
+                        self._error_manager.add_error(
+                            f"At the end of the function, port `{port_decl.name}` is expected to be {expected_terminal_state.name.lower()} but it isn't"
+                        )
+
+    def visit_WithinApply(self, within_apply: WithinApply) -> None:
+        initial_variables_to_state = self.current_scope.variable_states.copy()
+        scope = StaticScope(
+            parameters=self.current_scope.parameters,
+            operands=self.current_scope.operands,
+            variables_to_states=self.current_scope.variable_states.copy(),
+            variables_to_types=self.current_scope.variables_to_types.copy(),
+        )
+        with self.scoped_visit(scope):
+            self.visit(within_apply.compute)
+            compute_captured_variables = {
+                var
+                for var, state in self.current_scope.variable_states.items()
+                if var in initial_variables_to_state
+                and state != initial_variables_to_state[var]
+            }
+            self.visit(within_apply.action)
+            variables_to_state = self.current_scope.variable_states.copy()
+        self.current_scope.variable_states.update(
+            {
+                var: state
+                for var, state in variables_to_state.items()
+                if var in self.current_scope.variable_states
+                and var not in compute_captured_variables
+            }
+        )
+
+    def visit_QuantumOperation(self, op: QuantumOperation) -> None:
+        with self._error_manager.node_context(op):
+            if isinstance(op, QuantumFunctionCall):
+                validate_call_arguments(
+                    op,
+                    {
+                        **self._functions_dict,
+                        **self.current_scope.operands,
+                    },
+                )
+            elif isinstance(op, InplaceBinaryOperation) and isinstance(
+                op.value, HandleBinding
+            ):
+                check_no_overlapping_quantum_args(
+                    [op.target, op.value], op.operation.value
+                )
+            self._handle_inputs(op.readable_inputs)
+            self._handle_outputs(op.readable_outputs)
+            self._handle_inouts(op.readable_inouts)
+            self.generic_visit(op)
+
+    def visit_VariableDeclarationStatement(
+        self, declaration: VariableDeclarationStatement
+    ) -> None:
+        handle_wiring_state = self.current_scope.variable_states.get(declaration.name)
+        if handle_wiring_state is not None:
+            self._error_manager.add_error(
+                f"Trying to declare a variable of the same name as previously declared variable {declaration.name}"
+            )
+            return
+
+        self.current_scope.variable_states[declaration.name] = HandleState.UNINITIALIZED
+        self.current_scope.variables_to_types[declaration.name] = (
+            declaration.quantum_type
+        )
+
+    def visit_QuantumLambdaFunction(self, lambda_func: QuantumLambdaFunction) -> None:
+        renamed_parameters, renamed_operands, renamed_ports = get_renamed_parameters(
+            lambda_func
+        )
+        scope = StaticScope(
+            parameters=self.current_scope.parameters + renamed_parameters,
+            operands={**self.current_scope.operands, **renamed_operands},
+            variables_to_states={
+                **self.current_scope.variable_states.copy(),
+                **initialize_variables_to_state(renamed_ports),
+            },
+            variables_to_types=self.current_scope.variables_to_types
+            | {port.name: port.quantum_type for port in renamed_ports},
+        )
+        with self.scoped_visit(scope):
+            self.generic_visit(lambda_func)
+
+    def visit_HandleBinding(self, handle: HandleBinding) -> None:
+        resolve_handle(self.current_scope, handle)
+
+    def visit_Expression(self, expr: Expression) -> None:
+        if len(self._scope) == 0:
+            return
+        vrc = VarRefCollector(ignore_duplicated_handles=True, unevaluated=True)
+        vrc.visit(ast.parse(expr.expr))
+        handles = [
+            HandleMetadata(handle=handle)
+            for handle in vrc.var_handles
+            if handle.name in self.current_scope.variable_states
+            and (
+                not isinstance(handle, FieldHandleBinding)
+                or handle.field not in CLASSICAL_ATTRIBUTES
+            )
+        ]
+        self._handle_inouts(handles)
+
+    def visit_QuantumExpressionOperation(self, op: QuantumExpressionOperation) -> None:
+        self.visit_Expression(op.expression)
+        self.visit_QuantumOperation(op)
+
+    def _handle_state_changing_ios(
+        self,
+        ios: Sequence[HandleMetadata],
+        state: HandleState,
+        state_change_verb: str,
+    ) -> None:
+        for handle_metadata in ios:
+            handle_binding = handle_metadata.handle
+            if isinstance(
+                handle_binding,
+                (SubscriptHandleBinding, SlicedHandleBinding, FieldHandleBinding),
+            ):
+                self._error_manager.add_error(
+                    f"Cannot use {HANDLE_BINDING_PART_MESSAGE[type(handle_binding)]} of variable {handle_binding.name!r} in {state_change_verb} context"
+                )
+                continue
+            handle_wiring_state = self.current_scope.variable_states.get(
+                handle_binding.name
+            )
+            if handle_wiring_state is not state:
+                state_prefix = (
+                    ""
+                    if handle_wiring_state is None
+                    else f"{handle_wiring_state.name.lower()} "
+                )
+                location = (
+                    f" {handle_metadata.readable_location}"
+                    if handle_metadata.readable_location is not None
+                    else ""
+                )
+                self._error_manager.add_error(
+                    f"Cannot use {state_prefix}quantum variable {handle_binding.name!r}"
+                    f"{location}"
+                )
+
+            self.current_scope.variable_states[handle_binding.name] = ~state
+
+    def _handle_inputs(self, inputs: Sequence[HandleMetadata]) -> None:
+        self._handle_state_changing_ios(
+            inputs, HandleState.INITIALIZED, "uninitialization"
+        )
+
+    def _handle_outputs(self, outputs: Sequence[HandleMetadata]) -> None:
+        self._handle_state_changing_ios(
+            outputs, HandleState.UNINITIALIZED, "initialization"
+        )
+
+    def _handle_inouts(self, inouts: Sequence[HandleMetadata]) -> None:
+        for handle_metadata in inouts:
+            handle_binding = handle_metadata.handle
+
+            if handle_binding.name not in self.current_scope.variable_states:
+                ErrorManager().add_error(
+                    f"Variable {handle_binding.name!r} is not defined"
+                )
+                return
+            handle_wiring_state = self.current_scope.variable_states[
+                handle_binding.name
+            ]
+
+            if handle_wiring_state is not HandleState.INITIALIZED:
+                state_prefix = (
+                    ""
+                    if handle_wiring_state is None
+                    else f"{handle_wiring_state.name.lower()} "
+                )
+                location = (
+                    f" {handle_metadata.readable_location}"
+                    if handle_metadata.readable_location is not None
+                    else ""
+                )
+                self._error_manager.add_error(
+                    f"Cannot use {state_prefix}quantum variable {handle_binding.name!r}"
+                    f"{location}"
+                )
+
+
+def static_semantics_analysis_pass(
+    model: Model, error_type: Optional[type[Exception]] = ClassiqSemanticError
+) -> None:
+    _check_function_name_collisions(model, error_type)
+    QStructAnnotator().visit(model)
+    functions = {**BUILTIN_FUNCTION_DECLARATIONS, **model.function_dict}
+    resolve_function_calls(model, functions)
+    StaticSemanticsVisitor(
+        functions,
+        [const.name for const in model.constants],
+    ).visit(model)
+    if error_type is not None:
+        ErrorManager().report_errors(error_type)
+
+
+EXPECTED_TERMINAL_STATES: dict[PortDeclarationDirection, HandleState] = {
+    PortDeclarationDirection.Output: HandleState.INITIALIZED,
+    PortDeclarationDirection.Inout: HandleState.INITIALIZED,
+}
+
+
+def initialize_variables_to_state(
+    port_declarations: Sequence[PortDeclaration],
+) -> dict[str, HandleState]:
+    variables_to_state: dict[str, HandleState] = dict()
+
+    for port_decl in port_declarations:
+        variables_to_state[port_decl.name] = (
+            HandleState.INITIALIZED
+            if port_decl.direction.includes_port_direction(PortDirection.Input)
+            else HandleState.UNINITIALIZED
+        )
+
+    return variables_to_state

classiq/qmod/semantics/validation/constants_validation.py

@@ -0,0 +1,16 @@
+from collections.abc import Sequence
+
+from classiq.interface.generator.constant import Constant
+
+from classiq.qmod.builtins import BUILTIN_CONSTANTS
+from classiq.qmod.semantics.error_manager import ErrorManager
+
+
+def check_duplicate_constants(constants: Sequence[Constant]) -> None:
+    known_constants = {constant.name: constant for constant in BUILTIN_CONSTANTS}
+    for constant in constants:
+        if constant.name in known_constants:
+            with ErrorManager().node_context(constant):
+                ErrorManager().add_error(f"Constant {constant.name!r} already exists")
+        else:
+            known_constants[constant.name] = constant

classiq/qmod/semantics/validation/func_call_validation.py

@@ -0,0 +1,99 @@
+from collections.abc import Mapping
+
+from classiq.interface.exceptions import ClassiqError
+from classiq.interface.generator.expressions.expression import Expression
+from classiq.interface.model.handle_binding import HandleBinding
+from classiq.interface.model.quantum_function_call import QuantumFunctionCall
+from classiq.interface.model.quantum_function_declaration import (
+    AnonQuantumFunctionDeclaration,
+    AnonQuantumOperandDeclaration,
+    QuantumFunctionDeclaration,
+)
+from classiq.interface.model.quantum_lambda_function import (
+    OperandIdentifier,
+    QuantumLambdaFunction,
+    QuantumOperand,
+)
+
+from classiq.qmod.semantics.error_manager import ErrorManager
+
+
+def validate_call_arguments(
+    fc: QuantumFunctionCall,
+    function_dict: Mapping[str, QuantumFunctionDeclaration],
+) -> None:
+    pos_args = fc.positional_args
+    pos_params = fc.func_decl.positional_arg_declarations
+    if len(pos_args) != len(pos_params):
+        ErrorManager().add_error(
+            f"Function {fc.func_name} takes {len(pos_params)} arguments but "
+            f"{len(pos_args)} were given."
+        )
+    for arg, param in zip(pos_args, pos_params):
+        if not isinstance(arg, (Expression, HandleBinding)) and isinstance(
+            param, AnonQuantumOperandDeclaration
+        ):
+            _check_operand_against_declaration(param, arg, function_dict, fc.func_name)
+    check_no_overlapping_quantum_args(fc.ports, fc.func_name)
+
+
+def _check_operand_against_declaration(
+    operand_decl: AnonQuantumOperandDeclaration,
+    operand_argument: QuantumOperand,
+    function_dict: Mapping[str, QuantumFunctionDeclaration],
+    func_name: str,
+    in_list: bool = False,
+) -> None:
+    if isinstance(operand_argument, list):
+        if in_list:
+            ErrorManager().add_error(
+                f"{str(operand_argument)!r} argument to {func_name!r} is not "
+                f"a valid operand. Nested operand lists are not permitted."
+            )
+            return
+        for arg in operand_argument:
+            _check_operand_against_declaration(
+                operand_decl, arg, function_dict, func_name, in_list=True
+            )
+        return
+    operand_arg_decl: AnonQuantumFunctionDeclaration
+    operand_argument_for_decl = operand_argument
+    if isinstance(operand_argument_for_decl, OperandIdentifier):
+        operand_argument_for_decl = operand_argument_for_decl.name
+    if isinstance(operand_argument_for_decl, str):
+        if operand_argument_for_decl not in function_dict:
+            ErrorManager().add_error(
+                f"{operand_argument!r} argument to {func_name!r} is not a "
+                f"registered function."
+            )
+            return
+        operand_arg_decl = function_dict[operand_argument_for_decl]
+    elif isinstance(operand_argument_for_decl, QuantumLambdaFunction):
+        operand_arg_decl = operand_argument_for_decl.func_decl
+    else:
+        raise ClassiqError(
+            f"{str(operand_argument)!r} argument to {func_name!r} is not a "
+            f"valid operand."
+        )
+    num_arg_parameters = len(operand_arg_decl.positional_arg_declarations)
+    num_decl_parameters = len(operand_decl.positional_arg_declarations)
+    if num_arg_parameters != num_decl_parameters:
+        ErrorManager().add_error(
+            f"Signature of argument {operand_argument!r} to {func_name!r} "
+            f"does not match the signature of parameter {operand_decl.name!r}. "
+            f"{operand_decl.name!r} accepts {num_decl_parameters} parameters but "
+            f"{operand_argument!r} accepts {num_arg_parameters} parameters."
+        )
+
+
+def check_no_overlapping_quantum_args(
+    args: list[HandleBinding], func_name: str
+) -> None:
+    for idx, arg in enumerate(args):
+        for other_arg in args[idx + 1 :]:
+            if arg.overlaps(other_arg):
+                ErrorManager().add_error(
+                    f"Cannot use the same part of variable {arg.name!r} in multiple "
+                    f"arguments to function {func_name!r}."
+                )
+                break

classiq/qmod/semantics/validation/function_name_collisions_validation.py

@@ -0,0 +1,23 @@
+from typing import Optional
+
+from classiq.interface.model.model import Model
+
+from classiq.qmod.builtins.functions import CORE_LIB_DECLS
+
+
+def _check_function_name_collisions(
+    model: Model, error_type: Optional[type[Exception]]
+) -> None:
+    if error_type is None:
+        return
+    redefined_functions = [
+        function.name
+        for function in CORE_LIB_DECLS
+        if function.name in model.function_dict
+    ]
+    if len(redefined_functions) == 1:
+        raise error_type(
+            f"Cannot redefine built-in function {redefined_functions[0]!r}"
+        )
+    elif len(redefined_functions) > 1:
+        raise error_type(f"Cannot redefine built-in functions: {redefined_functions}")

classiq/qmod/semantics/validation/handle_validation.py

@@ -0,0 +1,85 @@
+from typing import TYPE_CHECKING, Optional, Union
+
+from classiq.interface.generator.functions.type_name import TypeName
+from classiq.interface.model.handle_binding import (
+    ConcreteHandleBinding,
+    FieldHandleBinding,
+    HandleBinding,
+    NestedHandleBinding,
+    SlicedHandleBinding,
+    SubscriptHandleBinding,
+)
+from classiq.interface.model.quantum_type import QuantumBitvector, QuantumType
+
+import classiq.qmod.semantics.error_manager as error_manager
+from classiq.qmod.model_state_container import QMODULE
+
+if TYPE_CHECKING:
+    from classiq.qmod.semantics.static_semantics_visitor import StaticScope
+
+
+def resolve_handle(scope: "StaticScope", handle: HandleBinding) -> None:
+    if handle.name not in scope.variables_to_types:
+        error_manager.append_error(handle, f"Variable {handle.name!r} is undefined.")
+        return
+    _resolve_handle_recursively(scope.variables_to_types[handle.name], handle)
+
+
+def _resolve_handle_recursively(
+    qtype: QuantumType, handle: ConcreteHandleBinding
+) -> Optional[QuantumType]:
+    if isinstance(handle, NestedHandleBinding):
+        return _resolve_nested_handle(qtype, handle)
+    return qtype
+
+
+def _resolve_nested_handle(
+    qtype: QuantumType, handle: NestedHandleBinding
+) -> Optional[QuantumType]:
+    nested_qtype = _resolve_handle_recursively(qtype, handle.base_handle)
+    if nested_qtype is None:
+        return None
+    if isinstance(handle, (SubscriptHandleBinding, SlicedHandleBinding)):
+        return _resolve_subscript_sliced_handle(nested_qtype, handle)
+    if TYPE_CHECKING:
+        assert isinstance(handle, FieldHandleBinding)
+    return _resolve_field_handle(nested_qtype, handle)
+
+
+def _resolve_subscript_sliced_handle(
+    qtype: QuantumType, handle: Union[SubscriptHandleBinding, SlicedHandleBinding]
+) -> Optional[QuantumType]:
+    if not isinstance(qtype, QuantumBitvector):
+        error_manager.append_error(handle, f"{qtype.type_name} is not subscriptable.")
+        return None
+    return qtype.element_type if isinstance(handle, SubscriptHandleBinding) else qtype
+
+
+def _validate_field_access(qtype: QuantumType, handle: FieldHandleBinding) -> bool:
+    if not isinstance(qtype, TypeName):
+        error_manager.append_error(handle, f"{qtype.type_name} has no fields.")
+        return False
+    if qtype.name not in QMODULE.qstruct_decls:
+        error_manager.append_error(
+            handle, f"{qtype.type_name} is not a quantum struct."
+        )
+        return False
+    if handle.field not in qtype.fields:
+        error_manager.append_error(
+            handle,
+            f"Struct {qtype.type_name} has no field {handle.field!r}. "
+            f"Available fields: {', '.join(qtype.fields.keys())}",
+        )
+        return False
+
+    return True
+
+
+def _resolve_field_handle(
+    qtype: QuantumType, handle: FieldHandleBinding
+) -> Optional[QuantumType]:
+    if _validate_field_access(qtype, handle):
+        if TYPE_CHECKING:
+            assert isinstance(qtype, TypeName)
+        return qtype.fields[handle.field]
+    return None

classiq/qmod/semantics/validation/main_validation.py

@@ -0,0 +1,33 @@
+from classiq.interface.generator.functions.classical_type import (
+    ClassicalArray,
+    ClassicalList,
+)
+from classiq.interface.generator.functions.concrete_types import ConcreteClassicalType
+from classiq.interface.model.native_function_definition import NativeFunctionDefinition
+from classiq.interface.model.quantum_function_declaration import PositionalArg
+
+from classiq import ClassicalParameterDeclaration
+from classiq.qmod.semantics.error_manager import append_error
+
+
+def validate_main_function(func: NativeFunctionDefinition) -> None:
+    for param in func.positional_arg_declarations:
+        _validate_main_param(param)
+
+
+def _validate_main_param(param: PositionalArg) -> None:
+    if isinstance(param, ClassicalParameterDeclaration):
+        _validate_main_classical_param_type(param.classical_type, param.name)
+
+
+def _validate_main_classical_param_type(
+    param: ConcreteClassicalType, param_name: str
+) -> None:
+    if isinstance(param, ClassicalList):
+        append_error(
+            param,
+            f"Classical array parameter {param_name!r} of function 'main' must must "
+            f"specify array length",
+        )
+    if isinstance(param, ClassicalArray):
+        _validate_main_classical_param_type(param.element_type, param_name)