classiq 0.83.0__py3-none-any.whl → 0.85.0__py3-none-any.whl

classiq/model_expansions/transformers/type_modifier_inference.py

@@ -4,6 +4,7 @@ import itertools
 import warnings
 from collections.abc import Collection, Iterator, Sequence
 from contextlib import contextmanager
+from typing import Optional, Union
 
 from classiq.interface.exceptions import (
     ClassiqDeprecationWarning,
@@ -18,6 +19,7 @@ from classiq.interface.model.bind_operation import BindOperation
 from classiq.interface.model.control import Control
 from classiq.interface.model.invert import Invert
 from classiq.interface.model.model_visitor import ModelVisitor
+from classiq.interface.model.native_function_definition import NativeFunctionDefinition
 from classiq.interface.model.phase_operation import PhaseOperation
 from classiq.interface.model.port_declaration import PortDeclaration
 from classiq.interface.model.power import Power
@@ -31,34 +33,43 @@ from classiq.interface.model.quantum_expressions.quantum_expression import (
     QuantumExpressionOperation,
 )
 from classiq.interface.model.quantum_function_call import QuantumFunctionCall
-from classiq.interface.model.quantum_statement import QuantumStatement
 from classiq.interface.model.within_apply_operation import WithinApply
+from classiq.interface.source_reference import SourceReference
 
 from classiq.model_expansions.visitors.variable_references import VarRefCollector
 
 
 def _inconsistent_type_modifier_error(
-    port_name: str, expected: TypeModifier, actual: TypeModifier
+    port_name: str,
+    expected: TypeModifier,
+    actual: TypeModifier,
+    source_ref: Optional[Union[SourceReference, str]] = None,
 ) -> str:
+    source_ref_str = f"\n\tat {source_ref}" if source_ref else ""
     return (
-        f"The type modifier of variable '{port_name}' does not conform to the function signature: "
+        f"The use of variable '{port_name}' does not conform to its declared modifier: "
         f"expected '{expected.name}', but found '{actual.name}'.\n"
-        f"Tip: If the final role of the variable in the function matches '{expected.name}', "
-        f"you may use the `unchecked` flag to instruct the compiler to disregard individual operations.\n"
-        # TODO add earliest date of enforcement. See https://classiq.atlassian.net/browse/CLS-2709.
+        f"Tip: If the cumulative use of the variable in the function matches '{expected.name}', "
+        f"use the `unchecked` flag to instruct the compiler to disregard individual operations."
+        f"{source_ref_str}\n"
+        "The deprecation warning will be elevated to an error starting July 23, 2025, at the earliest."
     )
 
 
 def _inconsistent_type_modifier_in_binding_error(
-    expected: TypeModifier, known_modifiers: dict[str, TypeModifier]
+    expected: TypeModifier,
+    known_modifiers: dict[str, TypeModifier],
+    source_ref: Optional[Union[SourceReference, str]] = None,
 ) -> str:
     actual = ", ".join(
         f"{name}: {modifier.name}" for name, modifier in known_modifiers.items()
     )
+    source_ref_str = f"\n\tat {source_ref}" if source_ref else ""
     return (
-        f"The variable binding has inconsistent type modifiers: "
+        f"Inconsistent modifiers in variable binding: "
         f"Expected modifier: {expected.name}, Actual modifiers: {actual}"
-        # TODO add earliest date of enforcement. See https://classiq.atlassian.net/browse/CLS-2709.
+        f"{source_ref_str}\n"
+        "The deprecation warning will be elevated to an error starting July 23, 2025, at the earliest."
     )
 
 
@@ -85,6 +96,7 @@ class TypeModifierValidation(ModelVisitor):
             support_unused_ports  # could be turned off for debugging
         )
         self._skip_validation = skip_validation
+        self._source_ref: Optional[Union[SourceReference, str]] = None
 
     @contextmanager
     def validate_ports(
@@ -119,6 +131,17 @@ class TypeModifierValidation(ModelVisitor):
         finally:
             self._conjugation_context = previous_context
 
+    @contextmanager
+    def source_reference_context(
+        self, source_ref: Optional[Union[SourceReference, str]]
+    ) -> Iterator[None]:
+        previous_source_ref = self._source_ref
+        self._source_ref = source_ref
+        try:
+            yield
+        finally:
+            self._source_ref = previous_source_ref
+
     def _set_unused_as_const(self) -> None:
         unresolved_ports = [
             port
@@ -161,7 +184,7 @@ class TypeModifierValidation(ModelVisitor):
         if signature_modifier is not TypeModifier.and_(signature_modifier, modifier):
             warnings.warn(
                 _inconsistent_type_modifier_error(
-                    candidate, signature_modifier, modifier
+                    candidate, signature_modifier, modifier, self._source_ref
                 ),
                 ClassiqDeprecationWarning,
                 stacklevel=1,
@@ -176,13 +199,17 @@ class TypeModifierValidation(ModelVisitor):
 
     def run(
         self,
-        ports: Collection[PortDeclaration],
-        body: Sequence[QuantumStatement],
+        func_def: NativeFunctionDefinition,
         unchecked: Collection[str],
     ) -> None:
-        with self.validate_ports(ports, unchecked) as should_validate:
+        with (
+            self.validate_ports(
+                func_def.port_declarations, unchecked
+            ) as should_validate,
+            self.source_reference_context(f"function '{func_def.name}'"),
+        ):
             if should_validate:
-                self.visit(body)
+                self.visit(func_def.body)
                 self._update_bound_vars()
 
     def _update_bound_vars(self) -> None:
@@ -193,16 +220,18 @@ class TypeModifierValidation(ModelVisitor):
                 self._validate_modifier(var, reduced_modifier)
 
     def visit_QuantumFunctionCall(self, call: QuantumFunctionCall) -> None:
-        for handle, port in call.handles_with_params:
-            self._validate_modifier(handle.name, port.type_modifier)
-            if port.direction is PortDeclarationDirection.Output:
-                self._add_initialized_modifier(handle.name, port.type_modifier)
+        with self.source_reference_context(call.source_ref):
+            for handle, port in call.handles_with_params:
+                self._validate_modifier(handle.name, port.type_modifier)
+                if port.direction is PortDeclarationDirection.Output:
+                    self._add_initialized_modifier(handle.name, port.type_modifier)
 
         if self._has_inputs(call):
             bound_vars = {
                 handle.name
                 for handle, port in call.handles_with_params
                 if port.direction is not PortDeclarationDirection.Inout
+                and handle.name not in self._unchecked
             }
             self._bound_vars.append(bound_vars)
 
@@ -214,13 +243,15 @@ class TypeModifierValidation(ModelVisitor):
         )
 
     def visit_Allocate(self, alloc: Allocate) -> None:
-        self._validate_modifier(alloc.target.name, TypeModifier.Permutable)
-        self._add_initialized_modifier(alloc.target.name, TypeModifier.Permutable)
+        with self.source_reference_context(alloc.source_ref):
+            self._validate_modifier(alloc.target.name, TypeModifier.Permutable)
+            self._add_initialized_modifier(alloc.target.name, TypeModifier.Permutable)
 
     def visit_BindOperation(self, bind_op: BindOperation) -> None:
         var_names = {
             handle.name
             for handle in itertools.chain(bind_op.in_handles, bind_op.out_handles)
+            if handle.name not in self._unchecked
         }
         self._bound_vars.append(var_names)
         for handle in bind_op.out_handles:
@@ -251,7 +282,7 @@ class TypeModifierValidation(ModelVisitor):
         ):
             warnings.warn(
                 _inconsistent_type_modifier_in_binding_error(
-                    min_modifier, known_modifiers
+                    min_modifier, known_modifiers, self._source_ref
                 ),
                 ClassiqDeprecationWarning,
                 stacklevel=1,
@@ -277,42 +308,49 @@ class TypeModifierValidation(ModelVisitor):
         return [handle.name for handle in vrc.var_handles]
 
     def visit_ArithmeticOperation(self, arith: ArithmeticOperation) -> None:
-        result_var = arith.result_var.name
-        self._validate_modifier(result_var, TypeModifier.Permutable)
-        for expr_var in self._extract_expr_vars(arith):
-            self._validate_modifier(expr_var, TypeModifier.Const)
-        if not arith.is_inplace:
-            self._add_initialized_modifier(result_var, TypeModifier.Permutable)
+        with self.source_reference_context(arith.source_ref):
+            result_var = arith.result_var.name
+            self._validate_modifier(result_var, TypeModifier.Permutable)
+            for expr_var in self._extract_expr_vars(arith):
+                self._validate_modifier(expr_var, TypeModifier.Const)
+            if not arith.is_inplace:
+                self._add_initialized_modifier(result_var, TypeModifier.Permutable)
 
     def visit_AmplitudeLoadingOperation(
         self, amp_load: AmplitudeLoadingOperation
     ) -> None:
-        result_var = amp_load.result_var.name
-        self._validate_modifier(result_var, TypeModifier.Mutable)
-        for expr_var in self._extract_expr_vars(amp_load):
-            self._validate_modifier(expr_var, TypeModifier.Const)
+        with self.source_reference_context(amp_load.source_ref):
+            result_var = amp_load.result_var.name
+            self._validate_modifier(result_var, TypeModifier.Mutable)
+            for expr_var in self._extract_expr_vars(amp_load):
+                self._validate_modifier(expr_var, TypeModifier.Const)
 
     def visit_PhaseOperation(self, phase_op: PhaseOperation) -> None:
-        for expr_var in self._extract_expr_vars(phase_op):
-            self._validate_modifier(expr_var, TypeModifier.Const)
+        with self.source_reference_context(phase_op.source_ref):
+            for expr_var in self._extract_expr_vars(phase_op):
+                self._validate_modifier(expr_var, TypeModifier.Const)
 
     def visit_Control(self, control: Control) -> None:
-        for control_var in self._extract_expr_vars(control):
-            self._validate_modifier(control_var, TypeModifier.Const)
-        self.visit(control.body)
-        if control.else_block is not None:
-            self.visit(control.else_block)
+        with self.source_reference_context(control.source_ref):
+            for control_var in self._extract_expr_vars(control):
+                self._validate_modifier(control_var, TypeModifier.Const)
+            self.visit(control.body)
+            if control.else_block is not None:
+                self.visit(control.else_block)
 
     def visit_Invert(self, invert: Invert) -> None:
-        self.visit(invert.body)
+        with self.source_reference_context(invert.source_ref):
+            self.visit(invert.body)
 
     def visit_Power(self, power: Power) -> None:
-        self.visit(power.body)
+        with self.source_reference_context(power.source_ref):
+            self.visit(power.body)
 
     def visit_WithinApply(self, within_apply: WithinApply) -> None:
-        with self.conjugation_context():
-            self.visit(within_apply.compute)
-        self.visit(within_apply.action)
+        with self.source_reference_context(within_apply.source_ref):
+            with self.conjugation_context():
+                self.visit(within_apply.compute)
+            self.visit(within_apply.action)
 
 
 def _merge_overlapping(bound_vars: Sequence[Collection[str]]) -> list[set[str]]:

classiq/model_expansions/transformers/var_splitter.py

@@ -218,7 +218,7 @@ class VarSplitter(ModelRenamer):
         return [
             VariableDeclarationStatement(
                 name=part.target_var_name,
-                quantum_type=part.target_var_type,
+                qmod_type=part.target_var_type,
             )
             for part in chain.from_iterable(symbol_parts.values())
         ]

classiq/model_expansions/visitors/symbolic_param_inference.py

@@ -10,7 +10,6 @@ from classiq.interface.generator.expressions.atomic_expression_functions import
 from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.generator.functions.classical_type import (
     ClassicalArray,
-    ClassicalList,
     ClassicalTuple,
     ClassicalType,
 )
@@ -53,7 +52,7 @@ def set_generative_recursively(classical_type: ClassicalType) -> None:
             set_generative_recursively(field_type)
         return
     classical_type.set_generative()
-    if isinstance(classical_type, (ClassicalArray, ClassicalList)):
+    if isinstance(classical_type, ClassicalArray):
         set_generative_recursively(classical_type.element_type)
     if isinstance(classical_type, ClassicalTuple):
         for element_type in classical_type.element_types:
@@ -155,7 +154,7 @@ class SymbolicParamInference(ModelVisitor):
         for param, arg in zip_longest(params, call.positional_args):
             if (
                 not isinstance(param, AnonClassicalParameterDeclaration)
-                or param.classical_type.is_purely_generative
+                or not param.classical_type.is_purely_declarative
             ):
                 self._process_compile_time_expressions(arg)
             else:

classiq/open_library/functions/__init__.py

@@ -6,6 +6,7 @@ from .amplitude_estimation import *
 from .discrete_sine_cosine_transform import *
 from .discrete_sine_cosine_transform import _qct_d_operator, _qct_pi_operator
 from .grover import *
+from .grover import _cond_phase_flip
 from .hea import *
 from .linear_pauli_rotation import *
 from .linear_pauli_rotation import _single_pauli
@@ -51,7 +52,6 @@ OPEN_LIBRARY_FUNCTIONS = [
     qsvt_inversion,
     qsvt_lcu,
     qsvt_lcu_step,
-    allocate_num,
     qaoa_mixer_layer,
     qaoa_cost_layer,
     qaoa_layer,
@@ -79,11 +79,11 @@ OPEN_LIBRARY_FUNCTIONS = [
     _check_msb,
     encode_in_angle,
     encode_on_bloch,
+    _cond_phase_flip,
 ]
 
 __all__ = [
     "_single_pauli",
-    "allocate_num",
     "amplitude_amplification",
     "amplitude_estimation",
     "apply_to_all",
@@ -105,6 +105,7 @@ __all__ = [
     "modular_increment",
     "multiswap",
     "phase_oracle",
+    "prepare_basis_state",
     "prepare_bell_state",
     "prepare_complex_amplitudes",
     "prepare_dicke_state",

classiq/open_library/functions/amplitude_amplification.py

@@ -1,11 +1,10 @@
 from classiq.open_library.functions.grover import grover_operator
+from classiq.qmod.builtins.functions.allocation import free
 from classiq.qmod.builtins.functions.standard_gates import RY
 from classiq.qmod.builtins.operations import (
     allocate,
-    bind,
     control,
     power,
-    within_apply,
 )
 from classiq.qmod.cparam import CInt, CReal
 from classiq.qmod.qfunc import qfunc
@@ -71,21 +70,14 @@ def exact_amplitude_amplification(
     theta = pi / (4 * k + 2)
     rot_phase = 2 * acos(sin(theta) / amplitude)
 
-    extended_qvars: QArray = QArray()
-    within_apply(
-        lambda: [
-            allocate(aux),
-            bind([aux, packed_qvars], extended_qvars),
+    allocate(aux)
+    amplitude_amplification(
+        k,
+        lambda qvars_: control(qvars_[0] == 0, lambda: oracle(qvars_[1 : qvars_.size])),
+        lambda qvars_: [
+            space_transform(qvars_[1 : qvars_.size]),
+            RY(rot_phase, qvars_[0]),
         ],
-        lambda: amplitude_amplification(
-            k,
-            lambda qvars_: control(
-                qvars_[0] == 0, lambda: oracle(qvars_[1 : qvars_.size])
-            ),
-            lambda qvars_: [
-                space_transform(qvars_[1 : qvars_.size]),
-                RY(rot_phase, qvars_[0]),
-            ],
-            extended_qvars,
-        ),
+        [aux, packed_qvars],
     )
+    free(aux)

classiq/open_library/functions/discrete_sine_cosine_transform.py

@@ -11,7 +11,7 @@ from classiq.qmod.builtins.operations import (
     within_apply,
 )
 from classiq.qmod.qfunc import qfunc
-from classiq.qmod.qmod_variable import QArray, QBit, QNum
+from classiq.qmod.qmod_variable import Const, Permutable, QArray, QBit, QNum
 from classiq.qmod.symbolic import pi
 
 
@@ -21,13 +21,13 @@ def _b_operator(q: QBit) -> None:
 
 
 @qfunc
-def _qct_d_operator(x: QNum, q: QBit) -> None:
+def _qct_d_operator(x: Const[QNum], q: QBit) -> None:
     _b_operator(q)
     control(x == 0, lambda: invert(lambda: _b_operator(q)))
 
 
 @qfunc
-def _qct_pi_operator(x: QArray[QBit], q: QBit) -> None:
+def _qct_pi_operator(x: Permutable[QArray[QBit]], q: Const[QBit]) -> None:
     control(
         q == 1,
         lambda: [
@@ -120,8 +120,8 @@ def qct_qst_type1(x: QArray[QBit]) -> None:
     within_apply(lambda: _t_operator(x), lambda: qft(x))
 
 
-@qfunc
-def qct_qst_type2(x: QArray[QBit], q: QBit) -> None:
+@qfunc(unchecked=["q"])
+def qct_qst_type2(x: QArray[QBit], q: Const[QBit]) -> None:
     """
     [Qmod Classiq-library function]
 

classiq/open_library/functions/grover.py

@@ -10,14 +10,22 @@ from classiq.qmod.builtins.operations import (
 )
 from classiq.qmod.qfunc import qfunc
 from classiq.qmod.qmod_parameter import CInt
-from classiq.qmod.qmod_variable import QArray, QBit, QNum
+from classiq.qmod.qmod_variable import Const, Permutable, QArray, QBit, QNum
 from classiq.qmod.quantum_callable import QCallable
 from classiq.qmod.symbolic import pi
 
 
+@qfunc(unchecked=["target"])
+def _cond_phase_flip(
+    predicate: QCallable[Permutable[QBit]], target: Const[QBit]
+) -> None:
+    within_apply(lambda: H(target), lambda: predicate(target))
+
+
 @qfunc
 def phase_oracle(
-    predicate: QCallable[QArray[QBit], QBit], target: QArray[QBit]
+    predicate: QCallable[Const[QArray[QBit]], Permutable[QBit]],
+    target: Const[QArray[QBit]],
 ) -> None:
     """
     [Qmod Classiq-library function]
@@ -42,13 +50,13 @@ def phase_oracle(
     """
     aux = QBit()
     within_apply(
-        within=lambda: (allocate(aux), X(aux), H(aux)),
-        apply=lambda: predicate(target, aux),
+        lambda: [allocate(aux), X(aux)],
+        lambda: _cond_phase_flip(lambda x: predicate(target, x), aux),
     )
 
 
-@qfunc
-def reflect_about_zero(packed_vars: QArray[QBit]) -> None:
+@qfunc(unchecked=["packed_vars"])
+def reflect_about_zero(packed_vars: Const[QArray[QBit]]) -> None:
     """
     [Qmod Classiq-library function]
 

classiq/open_library/functions/modular_exponentiation.py

@@ -1,5 +1,6 @@
 from classiq.open_library.functions.qft_functions import qft, qft_no_swap
 from classiq.qmod.builtins.classical_functions import qft_const_adder_phase
+from classiq.qmod.builtins.functions.allocation import free
 from classiq.qmod.builtins.functions.standard_gates import PHASE, SWAP, X
 from classiq.qmod.builtins.operations import (
     allocate,
@@ -11,7 +12,7 @@ from classiq.qmod.builtins.operations import (
 )
 from classiq.qmod.cparam import CInt
 from classiq.qmod.qfunc import qfunc
-from classiq.qmod.qmod_variable import QArray, QBit
+from classiq.qmod.qmod_variable import Const, Permutable, QArray, QBit
 from classiq.qmod.symbolic import min, mod_inverse
 
 
@@ -50,8 +51,10 @@ def qft_space_add_const(value: CInt, phi_b: QArray[QBit]) -> None:
     )
 
 
-@qfunc
-def cc_modular_add(n: CInt, a: CInt, phi_b: QArray[QBit], c1: QBit, c2: QBit) -> None:
+@qfunc(unchecked=["phi_b"])
+def cc_modular_add(
+    n: CInt, a: CInt, phi_b: Permutable[QArray[QBit]], c1: Const[QBit], c2: Const[QBit]
+) -> None:
     """
     [Qmod Classiq-library function]
 
@@ -69,11 +72,9 @@ def cc_modular_add(n: CInt, a: CInt, phi_b: QArray[QBit], c1: QBit, c2: QBit) ->
     ctrl: QArray[QBit] = QArray()
     aux = QBit()
 
+    allocate(aux)
     within_apply(
-        lambda: (
-            allocate(aux),
-            bind([c1, c2], ctrl),
-        ),
+        lambda: bind([c1, c2], ctrl),
         lambda: (
             control(ctrl, lambda: qft_space_add_const(a, phi_b)),
             invert(lambda: qft_space_add_const(n, phi_b)),
@@ -87,11 +88,16 @@ def cc_modular_add(n: CInt, a: CInt, phi_b: QArray[QBit], c1: QBit, c2: QBit) ->
             ),
         ),
     )
+    free(aux)
 
 
-@qfunc
+@qfunc(unchecked=["b"])
 def c_modular_multiply(
-    n: CInt, a: CInt, b: QArray[QBit], x: QArray[QBit], ctrl: QBit
+    n: CInt,
+    a: CInt,
+    b: Permutable[QArray[QBit]],
+    x: Const[QArray[QBit]],
+    ctrl: Const[QBit],
 ) -> None:
     """
     [Qmod Classiq-library function]
@@ -118,7 +124,7 @@ def c_modular_multiply(
 
 
 @qfunc
-def multiswap(x: QArray[QBit], y: QArray[QBit]) -> None:
+def multiswap(x: Permutable[QArray[QBit]], y: Permutable[QArray[QBit]]) -> None:
     """
     [Qmod Classiq-library function]
 
@@ -150,16 +156,12 @@ def inplace_c_modular_multiply(n: CInt, a: CInt, x: QArray[QBit], ctrl: QBit) ->
         x: The quantum factor.
         ctrl: The control bit.
     """
-    b: QArray[QBit] = QArray()
-
-    within_apply(
-        lambda: allocate(x.len + 1, b),
-        lambda: (
-            c_modular_multiply(n, a, b, x, ctrl),
-            control(ctrl, lambda: multiswap(x, b)),
-            invert(lambda: c_modular_multiply(n, mod_inverse(a, n), b, x, ctrl)),
-        ),
-    )
+    b: QArray[QBit] = QArray(length=x.len + 1)
+    allocate(b)
+    c_modular_multiply(n, a, b, x, ctrl)
+    control(ctrl, lambda: multiswap(x, b))
+    invert(lambda: c_modular_multiply(n, mod_inverse(a, n), b, x, ctrl))
+    free(b)
 
 
 @qfunc

classiq/open_library/functions/qaoa_penalty.py

@@ -1,5 +1,8 @@
+import warnings
 from typing import Literal
 
+from classiq.interface.exceptions import ClassiqDeprecationWarning
+
 from classiq.qmod.builtins.functions import RX, H, suzuki_trotter
 from classiq.qmod.builtins.operations import repeat
 from classiq.qmod.builtins.structs import PauliTerm
@@ -42,7 +45,11 @@ def qaoa_cost_layer(
         hamiltonian: The Hamiltonian terms for the QAOA model.
         target: The target quantum array variable.
     """
-    suzuki_trotter(hamiltonian, g, 1, 1, target)
+    with warnings.catch_warnings():  # FIXME: Remove (CLS-2912)
+        warnings.simplefilter(
+            "ignore", category=ClassiqDeprecationWarning
+        )  # FIXME: Remove (CLS-2912)
+        suzuki_trotter(hamiltonian, g, 1, 1, target)
 
 
 @qfunc

classiq/open_library/functions/state_preparation.py

@@ -27,7 +27,7 @@ from classiq.qmod.builtins.operations import (
     repeat,
     within_apply,
 )
-from classiq.qmod.cparam import CArray, CBool, CInt, CReal
+from classiq.qmod.cparam import CArray, CInt, CReal
 from classiq.qmod.qfunc import qfunc
 from classiq.qmod.qmod_variable import Output, QArray, QBit, QNum
 from classiq.qmod.symbolic import (
@@ -45,37 +45,6 @@ from classiq.qmod.symbolic import (
 )
 
 
-@qfunc
-def allocate_num(
-    num_qubits: CInt,
-    is_signed: CBool,
-    fraction_digits: CInt,
-    out: Output[
-        QNum[Literal["num_qubits"], Literal["is_signed"], Literal["fraction_digits"]]
-    ],
-) -> None:
-    """
-    [Qmod Classiq-library function]
-
-    This function is **deprecated** and will no longer be supported starting on
-    16/06/2025 at the earliest. Instead, use `allocate` which supports the same
-    parameters.
-
-    Initializes a quantum number with the given number of qubits, sign, and fractional digits.
-
-    Args:
-        num_qubits: The number of qubits to allocate.
-        is_signed: Whether the number is signed or unsigned.
-        fraction_digits: The number of fractional digits.
-    """
-    warnings.warn(
-        "Function `allocate_num` is deprecated and will no longer be supported starting on 16/06/2025 at the earliest. Instead, use `allocate` which supports the same parameters. ",
-        ClassiqDeprecationWarning,
-        stacklevel=1,
-    )
-    allocate(num_qubits, out)
-
-
 def _prepare_uniform_trimmed_state_apply_rotation(
     size_lsb: CInt, lsbs_val: CInt, rotation_var: QBit
 ) -> None:
@@ -483,3 +452,20 @@ def prepare_dicke_state(k: int, qvar: QArray[QBit]) -> None:
     if k > 0:
         apply_to_all(X, qvar[0:k])
         prepare_dicke_state_unary_input(k, qvar)
+
+
+@qfunc
+def prepare_basis_state(state: list[bool], arr: Output[QArray]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum array in the specified basis state.
+
+    Args:
+        values: The desired basis state, given as a list of boolean values for each qubit.
+        arr: The quantum array to prepare.
+    """
+    allocate(len(state), arr)
+    for idx, value in enumerate(state):
+        if value:
+            X(arr[idx])

classiq/qmod/__init__.py

@@ -1,6 +1,7 @@
 from .builtins import *  # noqa: F403
 from .builtins import __all__ as _builtins_all
 from .cfunc import cfunc
+from .classical_variable import measure
 from .create_model_function import create_model
 from .expression_query import get_expression_numeric_attributes
 from .qfunc import qfunc
@@ -29,6 +30,7 @@ __all__ = [
     "QStruct",
     "cfunc",
     "create_model",
+    "measure",
     "get_expression_numeric_attributes",
     "qfunc",
     "write_qmod",