classiq 0.102.0__py3-none-any.whl → 0.104.0__py3-none-any.whl

classiq/model_expansions/quantum_operations/assignment_result_processor.py

@@ -1,7 +1,15 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NoReturn, cast
 
-from classiq.interface.exceptions import ClassiqExpansionError
+from classiq.interface.exceptions import (
+    ClassiqExpansionError,
+)
 from classiq.interface.generator.expressions.expression import Expression
+from classiq.interface.generator.functions.classical_type import (
+    Bool,
+    ClassicalArray,
+    ClassicalTuple,
+    Integer,
+)
 from classiq.interface.model.allocate import Allocate
 from classiq.interface.model.bind_operation import BindOperation
 from classiq.interface.model.block import Block
@@ -20,9 +28,11 @@ from classiq.interface.model.quantum_expressions.quantum_expression import (
 )
 from classiq.interface.model.quantum_function_call import QuantumFunctionCall
 from classiq.interface.model.quantum_type import (
+    QuantumBit,
     QuantumBitvector,
     QuantumNumeric,
     QuantumScalar,
+    QuantumType,
 )
 from classiq.interface.model.statement_block import StatementBlock
 from classiq.interface.model.variable_declaration_statement import (
@@ -31,6 +41,18 @@ from classiq.interface.model.variable_declaration_statement import (
 from classiq.interface.model.within_apply_operation import WithinApply
 
 from classiq.evaluators.qmod_annotated_expression import QmodAnnotatedExpression
+from classiq.evaluators.qmod_node_evaluators.utils import (
+    QmodType,
+    array_len,
+    element_types,
+    is_numeric_type,
+)
+from classiq.evaluators.qmod_type_inference.classical_type_inference import (
+    infer_classical_type,
+)
+from classiq.evaluators.qmod_type_inference.quantum_type_comparison import (
+    compare_quantum_types,
+)
 from classiq.evaluators.qmod_type_inference.quantum_type_inference import (
     inject_quantum_type_attributes_inplace,
 )
@@ -43,13 +65,22 @@ from classiq.model_expansions.quantum_operations.arithmetic.explicit_boolean_exp
     validate_assignment_bool_expression,
 )
 from classiq.model_expansions.quantum_operations.emitter import Emitter
-from classiq.model_expansions.scope import ClassicalSymbol
+from classiq.model_expansions.scope import ClassicalSymbol, QuantumSymbol
 from classiq.qmod.builtins.functions.standard_gates import CX
 
 if TYPE_CHECKING:
     from classiq.model_expansions.interpreters.base_interpreter import BaseInterpreter
 
 
+def _get_expr_type(op: QuantumAssignmentOperation) -> QmodType:
+    expr_val = op.expression.value.value
+    if isinstance(expr_val, QmodAnnotatedExpression):
+        return expr_val.get_type(expr_val.root)
+    else:
+        expr_type = infer_classical_type(expr_val)
+    return expr_type
+
+
 class AssignmentResultProcessor(Emitter[QuantumAssignmentOperation]):
     def __init__(
         self, interpreter: "BaseInterpreter", replace_assignment_if_needed: bool = False
@@ -60,14 +91,26 @@ class AssignmentResultProcessor(Emitter[QuantumAssignmentOperation]):
     def emit(self, op: QuantumAssignmentOperation, /) -> bool:
         result_symbol = self._interpreter.evaluate(op.result_var).value
         if isinstance(result_symbol, ClassicalSymbol):
-            return False
+            return self._emit_classical_assignment(op)
+        if isinstance(result_symbol.quantum_type, QuantumScalar):
+            return self._emit_scalar_assignment(op)
+        expr_val = op.expression.value.value
+        if isinstance(expr_val, QmodAnnotatedExpression) and isinstance(
+            expr_val.get_type(expr_val.root), QuantumType
+        ):
+            return self._emit_quantum_var_quantum_expr_assignment(op)
+        return self._emit_quantum_var_classical_expr_assignment(op)
+
+    def _emit_classical_assignment(self, _: QuantumAssignmentOperation, /) -> bool:
+        return False
+
+    def _emit_scalar_assignment(self, op: QuantumAssignmentOperation, /) -> bool:
+        result_symbol = self._interpreter.evaluate(op.result_var).value
         result_type = result_symbol.quantum_type
-        if not isinstance(result_type, QuantumScalar):
-            raise ClassiqExpansionError(
-                f"Cannot assign into a non-scalar quantum variable "
-                f"{str(result_symbol.handle)!r} of type "
-                f"{result_type.raw_qmod_type_name}"
-            )
+
+        expr_type = _get_expr_type(op)
+        if not is_numeric_type(expr_type) and not isinstance(expr_type, Bool):
+            self._raise_type_error(result_symbol, expr_type)
 
         if not (
             isinstance(op, ArithmeticOperation)
@@ -82,36 +125,73 @@ class AssignmentResultProcessor(Emitter[QuantumAssignmentOperation]):
         )
         convert_assignment_bool_expression(op)
 
-        expression_type = self._infer_expression_type(op)
-        if expression_type is None:
+        quantum_expr_type = self._infer_scalar_expression_type(op)
+        if quantum_expr_type is None:
             return False
 
         if not result_type.is_instantiated:
-            if not inject_quantum_type_attributes_inplace(expression_type, result_type):
-                raise ClassiqExpansionError(
-                    f"Cannot assign expression of type "
-                    f"{expression_type.qmod_type_name} to variable "
-                    f"{str(result_symbol)!r} of type "
-                    f"{result_symbol.quantum_type.qmod_type_name}"
-                )
+            if not inject_quantum_type_attributes_inplace(
+                quantum_expr_type, result_type
+            ):
+                self._raise_type_error(result_symbol, expr_type)
             return False
 
-        if isinstance(result_type, QuantumNumeric) and isinstance(
-            expression_type, QuantumNumeric
+        if not isinstance(result_type, QuantumScalar) or not isinstance(
+            quantum_expr_type, QuantumScalar
         ):
-            result_type.set_bounds(expression_type.get_bounds())
-        if self._same_numeric_attributes(result_type, expression_type):
+            return False
+        if isinstance(result_type, QuantumNumeric):
+            result_type.set_bounds(quantum_expr_type.get_bounds())
+        if self._same_numeric_attributes(result_type, quantum_expr_type):
             return False
         self._validate_declared_attributes(
-            result_type, expression_type, str(op.result_var)
+            result_type, quantum_expr_type, str(op.result_var)
         )
         if not self._replace_assignment_if_needed:
             return False
 
-        self._assign_to_inferred_var_and_bind(op, result_type, expression_type)
+        self._assign_to_inferred_var_and_bind(op, result_type, quantum_expr_type)
         return True
 
-    def _infer_expression_type(self, op: ArithmeticOperation) -> QuantumScalar | None:
+    def _emit_quantum_var_quantum_expr_assignment(
+        self, op: QuantumAssignmentOperation, /
+    ) -> bool:
+        result_symbol = self._interpreter.evaluate(op.result_var).value
+        result_type = result_symbol.quantum_type
+        expr_type = cast(QuantumType, _get_expr_type(op))
+        if not inject_quantum_type_attributes_inplace(
+            expr_type, result_type
+        ) or not compare_quantum_types(result_type, expr_type):
+            self._raise_type_error(result_symbol, expr_type)
+        return False
+
+    def _emit_quantum_var_classical_expr_assignment(
+        self, op: QuantumAssignmentOperation, /
+    ) -> bool:
+        result_symbol = self._interpreter.evaluate(op.result_var).value
+        result_type = result_symbol.quantum_type
+
+        quantum_expr_type = self._infer_classical_array_expression_type(op)
+        if quantum_expr_type is None or not inject_quantum_type_attributes_inplace(
+            quantum_expr_type, result_type
+        ):
+            self._raise_type_error(result_symbol, _get_expr_type(op))
+
+        return False
+
+    def _raise_type_error(
+        self, result_symbol: QuantumSymbol, expr_type: QmodType
+    ) -> NoReturn:
+        raise ClassiqExpansionError(
+            f"Cannot assign expression of type "
+            f"{expr_type.qmod_type_name} to variable "
+            f"{str(result_symbol)!r} of type "
+            f"{result_symbol.quantum_type.qmod_type_name}"
+        )
+
+    def _infer_scalar_expression_type(
+        self, op: QuantumAssignmentOperation
+    ) -> QuantumType | None:
         expr = self._evaluate_expression(op.expression)
         expr_val = expr.value.value
         if isinstance(expr_val, QmodAnnotatedExpression):
@@ -129,9 +209,33 @@ class AssignmentResultProcessor(Emitter[QuantumAssignmentOperation]):
             ).to_quantum_numeric()
         return None
 
+    def _infer_classical_array_expression_type(
+        self, op: QuantumAssignmentOperation
+    ) -> QuantumType | None:
+        expr = self._evaluate_expression(op.expression)
+        expr_val = expr.value.value
+        if isinstance(expr_val, QmodAnnotatedExpression):
+            root_type = expr_val.get_type(expr_val.root)
+            if isinstance(root_type, (ClassicalArray, ClassicalTuple)) and all(
+                isinstance(element_type, Integer)
+                for element_type in element_types(root_type)
+            ):
+                list_len = array_len(root_type)
+                len_expr = (
+                    Expression(expr=str(list_len)) if list_len is not None else None
+                )
+                return QuantumBitvector(element_type=QuantumBit(), length=len_expr)
+            return None
+        if isinstance(expr_val, list) and all(
+            element in (0, 1) for element in expr_val
+        ):
+            length_expr = Expression(expr=str(len(expr_val)))
+            return QuantumBitvector(element_type=QuantumBit(), length=length_expr)
+        return None
+
     @staticmethod
     def _same_numeric_attributes(
-        result_type: QuantumNumeric, expression_type: QuantumScalar
+        result_type: QuantumScalar, expression_type: QuantumScalar
     ) -> bool:
         return (
             result_type.size_in_bits == expression_type.size_in_bits
@@ -142,7 +246,7 @@ class AssignmentResultProcessor(Emitter[QuantumAssignmentOperation]):
 
     @classmethod
     def _validate_declared_attributes(
-        cls, result_type: QuantumNumeric, expression_type: QuantumScalar, var: str
+        cls, result_type: QuantumScalar, expression_type: QuantumScalar, var: str
     ) -> None:
         result_size, result_sign, result_fractions = (
             result_type.size_in_bits,

classiq/model_expansions/quantum_operations/bind.py

@@ -97,6 +97,8 @@ class BindEmitter(Emitter[BindOperation]):
             state = self._builder.current_block.captured_vars.get_state(
                 var_name, inp.defining_function
             )
+            if state is None:
+                continue
             if not state:
                 raise ClassiqExpansionError(
                     f"Cannot use uninitialized quantum variable "
@@ -112,6 +114,8 @@ class BindEmitter(Emitter[BindOperation]):
             state = self._builder.current_block.captured_vars.get_state(
                 var_name, out.defining_function
             )
+            if state is None:
+                continue
             if state:
                 raise ClassiqExpansionError(
                     f"Cannot use initialized quantum variable "

classiq/model_expansions/quantum_operations/call_emitter.py

@@ -12,9 +12,6 @@ from classiq.interface.debug_info.debug_info import (
     new_function_debug_info_by_node,
 )
 from classiq.interface.exceptions import ClassiqExpansionError
-from classiq.interface.generator.functions.port_declaration import (
-    PortDeclarationDirection,
-)
 from classiq.interface.generator.types.compilation_metadata import CompilationMetadata
 from classiq.interface.helpers.text_utils import are, readable_list, s
 from classiq.interface.model.block import Block
@@ -45,8 +42,6 @@ from classiq.evaluators.parameter_types import (
 )
 from classiq.evaluators.qmod_annotated_expression import QmodAnnotatedExpression
 from classiq.model_expansions.capturing.captured_vars import (
-    INITIALIZED_VAR_MESSAGE,
-    UNINITIALIZED_VAR_MESSAGE,
     validate_args_are_not_propagated,
 )
 from classiq.model_expansions.closure import Closure, FunctionClosure
@@ -109,12 +104,14 @@ def _validate_gen_args(
         if (
             isinstance(param, ClassicalParameterDeclaration)
             and not param.classical_type.is_purely_declarative
-            and isinstance(arg.value, QmodAnnotatedExpression)
+            and isinstance(arg_val := arg.value, QmodAnnotatedExpression)
         ):
             readable_expr = transform_expression(str(arg.value), {}, {}, one_line=True)
+            expr_type = arg_val.get_type(arg_val.root)
             raise ClassiqExpansionError(
-                f"Cannot pass symbolic expression {readable_expr!r} as Python-type "
-                f"parameter {param.name!r}"
+                f"Cannot pass {readable_expr!r} of type {expr_type.qmod_type_name} as "
+                f"parameter {param.name!r} of Python-type "
+                f"{param.classical_type.python_type_name}"
             )
 
 
@@ -195,7 +192,6 @@ class CallEmitter(Generic[QuantumStatementT], Emitter[QuantumStatementT], ModelR
     ) -> QuantumFunctionCall:
         function = function.clone()
         function = function.set_depth(self._builder.current_function.depth + 1)
-        self._validate_call_args(function.positional_arg_declarations, args)
         evaluated_args = [self._interpreter.evaluate(arg) for arg in args]
         _validate_cloning(evaluated_args)
         _validate_runtime_args(evaluated_args, self._current_scope)
@@ -391,32 +387,6 @@ class CallEmitter(Generic[QuantumStatementT], Emitter[QuantumStatementT], ModelR
             permutation=function.permutation,
         )
 
-    def _validate_call_args(
-        self, params: Sequence[PositionalArg], args: list[ArgValue]
-    ) -> None:
-        for param, arg in zip(params, args):
-            if not isinstance(param, PortDeclaration) or not isinstance(
-                arg, HandleBinding
-            ):
-                continue
-            var_name = arg.name
-            symbol = self._interpreter.evaluate(var_name)
-            if (
-                not isinstance(symbol.value, QuantumSymbol)
-                or symbol.defining_function is None
-            ):
-                continue
-            var_state = self._builder.current_block.captured_vars.get_state(
-                var_name, symbol.defining_function
-            )
-            if not var_state and param.direction in (
-                PortDeclarationDirection.Inout,
-                PortDeclarationDirection.Input,
-            ):
-                raise ClassiqExpansionError(UNINITIALIZED_VAR_MESSAGE.format(var_name))
-            if var_state and param.direction == PortDeclarationDirection.Output:
-                raise ClassiqExpansionError(INITIALIZED_VAR_MESSAGE.format(var_name))
-
     def _validate_type_modifiers(
         self, func_context: FunctionContext, func_def: NativeFunctionDefinition
     ) -> None:

classiq/model_expansions/quantum_operations/emitter.py

@@ -144,11 +144,8 @@ class Emitter(Generic[QuantumStatementT], ABC):
         expression: Expression,
         *,
         simplify: bool = False,
-        treat_qnum_as_float: bool = False,
     ) -> Expression:
-        expr_val = self._interpreter.evaluate(
-            expression, simplify=simplify, treat_qnum_as_float=treat_qnum_as_float
-        ).value
+        expr_val = self._interpreter.evaluate(expression, simplify=simplify).value
         new_expr = Expression(expr=str(expr_val))
         new_expr._evaluated_expr = EvaluatedExpression(value=expr_val)
         return new_expr

classiq/model_expansions/quantum_operations/expression_evaluator.py

@@ -26,14 +26,12 @@ class ExpressionEvaluator(Emitter[QuantumOperation]):
         *,
         readable_expression_name: str | None = None,
         simplify: bool = False,
-        treat_qnum_as_float: bool = False,
         allow_link_time_vars: bool = True,
         allow_runtime_vars: bool = True,
     ) -> None:
         super().__init__(interpreter)
         self._expression_name = expression_name
         self._simplify = simplify
-        self._treat_qnum_as_float = treat_qnum_as_float
         self._allow_link_time_vars = allow_link_time_vars
         self._allow_runtime_vars = allow_runtime_vars
         if (
@@ -49,7 +47,6 @@ class ExpressionEvaluator(Emitter[QuantumOperation]):
         evaluated_expression = self._evaluate_expression(
             expression,
             simplify=self._simplify,
-            treat_qnum_as_float=self._treat_qnum_as_float,
         )
         for symbol in self._get_symbols_in_expression(evaluated_expression):
             self._capture_handle(symbol.handle, PortDeclarationDirection.Inout)

classiq/model_expansions/visitors/uncomputation_signature_inference.py

@@ -21,9 +21,6 @@ from classiq.interface.model.invert import Invert
 from classiq.interface.model.model_visitor import ModelStatementsVisitor
 from classiq.interface.model.native_function_definition import NativeFunctionDefinition
 from classiq.interface.model.power import Power
-from classiq.interface.model.quantum_expressions.amplitude_loading_operation import (
-    AmplitudeLoadingOperation,
-)
 from classiq.interface.model.quantum_expressions.arithmetic_operation import (
     ArithmeticOperation,
 )
@@ -147,12 +144,6 @@ class UncomputationSignatureInference(ModelStatementsVisitor):
         else:
             self._mark_as_non_const(arith.result_var.name, True)
 
-    def visit_AmplitudeLoadingOperation(
-        self, amp_load: AmplitudeLoadingOperation
-    ) -> None:
-        self._mark_as_non_permutation()
-        self._mark_as_non_const(amp_load.result_var.name, False)
-
     def visit_Control(self, control: Control) -> None:
         self.visit(control.body)
         if control.else_block is not None:

classiq/qmod/builtins/functions/__init__.py

@@ -48,6 +48,10 @@ CORE_LIB_DECLS = [
         integer_xor,
         modular_add_constant,
         real_xor_constant,
+        multiply,
+        multiply_constant,
+        canonical_multiply,
+        canonical_multiply_constant,
         U,
         CCX,
         free,
@@ -61,6 +65,7 @@ CORE_LIB_DECLS = [
         commuting_paulis_exponent,
         suzuki_trotter,
         unscheduled_suzuki_trotter,
+        sequential_suzuki_trotter,
         exponentiate,
         multi_suzuki_trotter,
         parametric_suzuki_trotter,
@@ -111,6 +116,10 @@ __all__ = [  # noqa: RUF022
     "add_inplace_right",
     "apply",
     "exponentiation_with_depth_constraint",
+    "multiply",
+    "multiply_constant",
+    "canonical_multiply",
+    "canonical_multiply_constant",
     "free",
     "drop",
     "inplace_prepare_amplitudes",

classiq/qmod/builtins/functions/arithmetic.py

@@ -1,5 +1,6 @@
 from typing import Literal
 
+from classiq.qmod.cparam import CInt
 from classiq.qmod.qfunc import qfunc, qperm
 from classiq.qmod.qmod_parameter import CArray, CBool, CReal
 from classiq.qmod.qmod_variable import (
@@ -83,3 +84,133 @@ def integer_xor(left: Const[QArray[QBit]], right: QArray[QBit]) -> None:
 @qperm(external=True)
 def real_xor_constant(left: CReal, right: QNum) -> None:
     pass
+
+
+@qperm(external=True)
+def multiply(left: Const[QNum], right: Const[QNum], result: Output[QNum]) -> None:
+    """
+    [Qmod core-library function]
+
+    Multiplies two quantum numeric variables:
+
+    $$
+        \\left|\\text{left}\\right\\rangle \\left|\\text{right}\\right\\rangle
+        \\mapsto
+        \\left|\\text{left}\\right\\rangle \\left|\\text{right}\\right\\rangle
+        \\left|\\text{left} \\cdot \\text{right} \\right\\rangle
+    $$
+
+    Args:
+        left: The first argument for the multiplication.
+        right: The second argument for the multiplication.
+        result: The quantum variable to hold the multiplication result.
+    """
+    pass
+
+
+@qperm(external=True)
+def multiply_constant(left: CReal, right: Const[QNum], result: Output[QNum]) -> None:
+    """
+    [Qmod core-library function]
+
+    Multiplies a quantum numeric variable with a constant:
+
+    $$
+        \\left|\\text{right}\\right\\rangle
+        \\mapsto
+        \\left|\\text{right}\\right\\rangle
+        \\left|\\text{left} \\cdot \\text{right} \\right\\rangle
+    $$
+
+    Args:
+        left: The constant argument for the multiplication.
+        right: The variable argument for the multiplication.
+        result: The quantum variable to hold the multiplication result.
+    """
+    pass
+
+
+@qperm(external=True)
+def canonical_multiply(
+    left: Const[QArray],
+    extend_left: CBool,
+    right: Const[QArray],
+    extend_right: CBool,
+    result: QArray,
+    trim_result_lsb: CBool,
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Multiplies two quantum variables representing integers (signed or unsigned) into the
+    result variable which is assumed to start in the $|0\\rangle$ state.
+
+    If `trim_result_lsb` is `False`, applies the transformation:
+
+    $$
+        \\left|\\text{left}\\right\\rangle \\left|\\text{right}\\right\\rangle
+        \\left|0\\right\\rangle \\mapsto \\left|\\text{left}\\right\\rangle
+        \\left|\\text{right}\\right\\rangle \\left|\\left( \\text{left} \\cdot
+        \\text{right} \\right) \\bmod 2^{\\text{result.size}} \\right\\rangle
+    $$
+
+    If `trim_result_lsb` is `True`, the function avoids computing the result's LSB and
+    applies the transformation:
+
+    $$
+        \\left|\\text{left}\\right\\rangle \\left|\\text{right}\\right\\rangle
+        \\left|0\\right\\rangle \\mapsto \\left|\\text{left}\\right\\rangle
+        \\left|\\text{right}\\right\\rangle \\left|\\left( \\text{left} \\cdot
+        \\text{right} \\right) \\gg 1 \\bmod 2^{\\text{result.size}} \\right\\rangle
+    $$
+
+    Args:
+        left: The first argument for the multiplication.
+        extend_left: Whether to sign-extend the left argument.
+        right: The second argument for the multiplication.
+        extend_right: Whether to sign-extend the right argument.
+        result: The quantum variable to hold the multiplication result.
+        trim_result_lsb: Whether to avoid computing the result's LSB.
+    """
+    pass
+
+
+@qperm(external=True)
+def canonical_multiply_constant(
+    left: CInt,
+    right: Const[QArray],
+    extend_right: CBool,
+    result: QArray,
+    trim_result_lsb: CBool,
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Multiplies a quantum variable representing an integer (signed or unsigned) with a
+    constant, into the result variable which is assumed to start in the $|0\\rangle$ state.
+
+    If `trim_result_lsb` is `False`, applies the transformation:
+
+    $$
+        \\left|\\text{right}\\right\\rangle \\left|0\\right\\rangle \\mapsto
+        \\left|\\text{right}\\right\\rangle \\left|\\left( \\text{left} \\cdot
+        \\text{right} \\right) \\bmod 2^{\\text{result.size}} \\right\\rangle
+    $$
+
+    If `trim_result_lsb` is `True`, the function avoids computing the result's LSB and
+    applies the transformation:
+
+    $$
+        \\left|\\text{right}\\right\\rangle \\left|0\\right\\rangle \\mapsto
+        \\left|\\text{right}\\right\\rangle \\left|\\left( \\text{left} \\cdot
+        \\text{right} \\right) \\gg 1 \\bmod 2^{\\text{result.size}} \\right\\rangle
+    $$
+
+    Args:
+        left: The constant argument for the multiplication.
+        right: The variable argument for the multiplication.
+        extend_right: Whether to sign-extend the right argument.
+        result: The quantum variable to hold the multiplication result.
+        trim_result_lsb: Whether to avoid computing the result's LSB.
+    """
+    pass

classiq/qmod/builtins/functions/exponentiation.py

@@ -99,7 +99,7 @@ def multi_suzuki_trotter(
     The error of a Suzuki-Trotter decomposition decreases as the order and number of repetitions increase.
 
     Args:
-        hamiltonians: The hamitonians to be exponentiated, in sparse representation.
+        hamiltonians: The hamiltonians to be exponentiated, in sparse representation.
         evolution_coefficients: The hamiltonian coefficients (can be link-time).
         order: The order of the Suzuki-Trotter decomposition.
         repetitions: The number of repetitions of the Suzuki-Trotter decomposition.
@@ -129,7 +129,37 @@ def unscheduled_suzuki_trotter(
     The error of a Suzuki-Trotter decomposition decreases as the order and number of repetitions increase.
 
     Args:
-        hamiltonians: The hamitonians to be exponentiated, in sparse representation.
+        hamiltonians: The hamiltonians to be exponentiated, in sparse representation.
+        evolution_coefficients: The hamiltonian coefficients (can be link-time).
+        order: The order of the Suzuki-Trotter decomposition.
+        repetitions: The number of repetitions of the Suzuki-Trotter decomposition.
+        qbv: The target quantum variable of the exponentiation.
+    """
+    pass
+
+
+@qfunc(external=True)
+def sequential_suzuki_trotter(
+    hamiltonians: CArray[SparsePauliOp],
+    evolution_coefficients: CArray[CReal],
+    order: CInt,
+    repetitions: CInt,
+    qbv: QArray,
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Applies the Suzuki-Trotter decomposition jointly to a sum of Hamiltonians
+    (represented as Pauli operators), each with its separate evolution coefficient,
+    approximating $\\exp{-iH_1t_1+H_2t_2+\\dots}$  with a specified order and number of
+    repetitions. Does not reorder the Pauli terms.
+
+    The Suzuki-Trotter decomposition is a method for approximating the exponential of a sum of operators by a product of exponentials of each operator.
+    The Suzuki-Trotter decomposition of a given order nullifies the error of the Taylor series expansion of the product of exponentials up to that order.
+    The error of a Suzuki-Trotter decomposition decreases as the order and number of repetitions increase.
+
+    Args:
+        hamiltonians: The hamiltonians to be exponentiated, in sparse representation.
         evolution_coefficients: The hamiltonian coefficients (can be link-time).
         order: The order of the Suzuki-Trotter decomposition.
         repetitions: The number of repetitions of the Suzuki-Trotter decomposition.