classiq 0.80.0__py3-none-any.whl → 0.81.0__py3-none-any.whl

classiq/model_expansions/quantum_operations/call_emitter.py

@@ -29,6 +29,7 @@ from classiq.interface.generator.functions.port_declaration import (
     PortDeclarationDirection,
 )
 from classiq.interface.generator.functions.type_qualifier import TypeQualifier
+from classiq.interface.generator.types.compilation_metadata import CompilationMetadata
 from classiq.interface.helpers.backward_compatibility import zip_strict
 from classiq.interface.helpers.text_utils import are, readable_list, s
 from classiq.interface.model.classical_parameter_declaration import (
@@ -80,7 +81,7 @@ from classiq.model_expansions.scope import (
     Scope,
 )
 from classiq.model_expansions.transformers.type_qualifier_inference import (
-    TypeQualifierInference,
+    TypeQualifierValidation,
 )
 from classiq.model_expansions.transformers.var_splitter import VarSplitter
 from classiq.qmod.pretty_print.expression_to_python import transform_expression
@@ -290,6 +291,7 @@ class CallEmitter(Generic[QuantumStatementT], Emitter[QuantumStatementT], VarSpl
         context = self._expand_operation(function)
         function_context = cast(FunctionContext, context)
         function_def = self._create_function_definition(function_context, args)
+        self._validate_type_qualifiers(function_context, function_def)
         self._expanded_functions[cache_key] = function_def
         self._top_level_scope[function_def.name] = Evaluated(
             value=function_context.closure.with_new_declaration(function_def)
@@ -320,20 +322,14 @@ class CallEmitter(Generic[QuantumStatementT], Emitter[QuantumStatementT], VarSpl
         )
         captured_ports = captured_vars.get_captured_parameters()
         if len(captured_ports) == 0:
-            self._override_type_qualifier(function_context, func_def)
             return func_def
         func_def.positional_arg_declarations = list(
             chain.from_iterable((func_def.positional_arg_declarations, captured_ports))
         )
 
-        rewrite_mapping = dict(captured_vars.get_propagated_captured_mapping())
-        if function_context.is_lambda:
-            rewrite_mapping |= captured_vars.get_immediate_captured_mapping()
-            rewrite_mapping |= captured_vars.get_classical_captured_mapping()
+        rewrite_mapping = captured_vars.get_captured_mapping(function_context.is_lambda)
         func_def.body = self.rewrite(func_def.body, rewrite_mapping)
 
-        self._override_type_qualifier(function_context, func_def)
-
         return func_def
 
     @staticmethod
@@ -419,9 +415,21 @@ class CallEmitter(Generic[QuantumStatementT], Emitter[QuantumStatementT], VarSpl
             if var_state and param.direction == PortDeclarationDirection.Output:
                 raise ClassiqExpansionError(INITIALIZED_VAR_MESSAGE.format(var_name))
 
-    def _override_type_qualifier(
+    def _validate_type_qualifiers(
         self, func_context: FunctionContext, func_def: NativeFunctionDefinition
     ) -> None:
+        if self._should_override_type_qualifiers(func_context):
+            self._override_type_qualifiers(func_def)
+
+        unchecked = self._functions_compilation_metadata.get(
+            func_context.name, CompilationMetadata()
+        ).unchecked
+        TypeQualifierValidation().run(
+            func_def.port_declarations, func_def.body, unchecked
+        )
+
+    @staticmethod
+    def _should_override_type_qualifiers(func_context: FunctionContext) -> bool:
         """
         The type qualifier can be changed according to the operand passed to the
         function. For example,
@@ -434,29 +442,27 @@ class CallEmitter(Generic[QuantumStatementT], Emitter[QuantumStatementT], VarSpl
         """
 
         if func_context.is_lambda:
-            self._update_type_qualifiers(func_def)
-            return
+            return True
 
         orig_name = func_context.name
         if (
             orig_name == MAIN_FUNCTION_NAME
             or orig_name not in func_context.closure.scope
         ):
-            return
+            return False
 
         orig_func = func_context.closure.scope[orig_name].value
-        if isinstance(orig_func, Closure) and not any(
-            isinstance(param_decl, QuantumOperandDeclaration)
-            for param_decl in orig_func.positional_arg_declarations
-        ):
-            return
-
-        self._update_type_qualifiers(func_def)
+        return not (
+            isinstance(orig_func, Closure)
+            and not any(
+                isinstance(param_decl, QuantumOperandDeclaration)
+                for param_decl in orig_func.positional_arg_declarations
+            )
+        )
 
     @staticmethod
-    def _update_type_qualifiers(func_def: NativeFunctionDefinition) -> None:
+    def _override_type_qualifiers(func_def: NativeFunctionDefinition) -> None:
         # only override the qualifier if it's unspecified (not QFree or Const)
         for port in func_def.port_declarations:
             if port.type_qualifier is TypeQualifier.Quantum:
                 port.type_qualifier = TypeQualifier.Inferred
-        TypeQualifierInference().run(func_def.port_declarations, func_def.body)

classiq/model_expansions/quantum_operations/emitter.py

@@ -184,6 +184,8 @@ class Emitter(Generic[QuantumStatementT], ABC):
     def _update_captured_classical_vars_in_expression(self, expr: Expression) -> None:
         for var_name, var_type in self._get_classical_vars_in_expression(expr):
             self._capture_classical_var(var_name, var_type)
+        for handle in self._get_quantum_type_attributes_in_expression(expr):
+            self._capture_quantum_type_attribute(handle)
 
     def _update_captured_vars(self, op: QuantumOperation) -> None:
         for handle, direction in op.handles_with_directions:
@@ -223,6 +225,17 @@ class Emitter(Generic[QuantumStatementT], ABC):
             defining_function=defining_function,
         )
 
+    def _capture_quantum_type_attribute(self, handle: FieldHandleBinding) -> None:
+        if handle.name not in self._current_scope:
+            return
+        defining_function = self._current_scope[handle.name].defining_function
+        if defining_function is None:
+            raise ClassiqInternalExpansionError
+        self._builder.current_block.captured_vars.capture_quantum_type_attribute(
+            handle=handle,
+            defining_function=defining_function,
+        )
+
     def _get_symbols_in_expression(self, expr: Expression) -> list[QuantumSymbol]:
         vrc = VarRefCollector(ignore_duplicated_handles=True, unevaluated=True)
         vrc.visit(ast.parse(expr.expr))
@@ -258,3 +271,18 @@ class Emitter(Generic[QuantumStatementT], ABC):
                 )
             }.items()
         )
+
+    def _get_quantum_type_attributes_in_expression(
+        self, expr: Expression
+    ) -> list[FieldHandleBinding]:
+        vrc = VarRefCollector(ignore_duplicated_handles=True, unevaluated=True)
+        vrc.visit(ast.parse(expr.expr))
+        return list(
+            dict.fromkeys(
+                handle
+                for handle in vrc.var_handles
+                if isinstance(handle, FieldHandleBinding)
+                and handle.field in CLASSICAL_ATTRIBUTES
+                and isinstance(self._current_scope[handle.name].value, QuantumSymbol)
+            )
+        )

classiq/model_expansions/quantum_operations/function_calls_cache.py

@@ -11,10 +11,6 @@ from classiq.interface.generator.expressions.proxies.classical.classical_struct_
 from classiq.interface.generator.expressions.proxies.classical.utils import (
     get_proxy_type,
 )
-from classiq.interface.generator.functions.port_declaration import (
-    PortDeclarationDirection,
-)
-from classiq.interface.model.port_declaration import PortDeclaration
 from classiq.interface.model.quantum_function_declaration import (
     NamedParamsQuantumFunctionDeclaration,
 )
@@ -36,18 +32,7 @@ def get_func_call_cache_key(
         raise ClassiqInternalExpansionError(
             "Mismatch between number of args to number of arg declarations"
         )
-
-    # output arguments cannot affect the morphization of the function, as their
-    # attributes are defined locally by the function, according to other arguments
-    non_outputs_args = [
-        arg
-        for arg_decl, arg in zip(decl.positional_arg_declarations, args)
-        if not (
-            isinstance(arg_decl, PortDeclaration)
-            and arg_decl.direction is PortDeclarationDirection.Output
-        )
-    ]
-    return f"{decl.name}__{_evaluated_args_to_str(non_outputs_args)}"
+    return f"{decl.name}__{_evaluated_args_to_str(args)}"
 
 
 def _evaluated_args_to_str(evaluated_args: list[Evaluated]) -> str:

classiq/model_expansions/transformers/type_qualifier_inference.py

@@ -4,7 +4,10 @@ import itertools
 from collections.abc import Collection, Iterator, Sequence
 from contextlib import contextmanager
 
-from classiq.interface.exceptions import ClassiqInternalExpansionError
+from classiq.interface.exceptions import (
+    ClassiqExpansionError,
+    ClassiqInternalExpansionError,
+)
 from classiq.interface.generator.functions.type_qualifier import TypeQualifier
 from classiq.interface.model.allocate import Allocate
 from classiq.interface.model.bind_operation import BindOperation
@@ -30,7 +33,18 @@ from classiq.interface.model.within_apply_operation import WithinApply
 from classiq.model_expansions.visitors.variable_references import VarRefCollector
 
 
-class TypeQualifierInference(ModelVisitor):
+def _inconsistent_type_qualifier_error(
+    port_name: str, expected: TypeQualifier, actual: TypeQualifier
+) -> str:
+    return (
+        f"The type modifier of variable '{port_name}' does not conform to the function signature: "
+        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."
+    )
+
+
+class TypeQualifierValidation(ModelVisitor):
     """
     This class assumes that function calls are topologically sorted, so it traverses
     the list of function calls and infers the type qualifiers for each function call
@@ -41,23 +55,41 @@ class TypeQualifierInference(ModelVisitor):
     def __init__(self, support_unused_ports: bool = True) -> None:
         self._signature_ports: dict[str, PortDeclaration] = dict()
         self._inferred_ports: dict[str, PortDeclaration] = dict()
+        self._unchecked: set[str] = set()
+        self._conjugation_context: bool = False
         self._support_unused_ports = (
             support_unused_ports  # could be turned off for debugging
         )
 
     @contextmanager
-    def infer_ports(self, ports: Collection[PortDeclaration]) -> Iterator[bool]:
+    def validate_ports(
+        self, ports: Collection[PortDeclaration], unchecked: Collection[str]
+    ) -> Iterator[bool]:
         for port in ports:
             if port.type_qualifier is TypeQualifier.Inferred:
                 self._inferred_ports[port.name] = port
             else:
                 self._signature_ports[port.name] = port
+        self._unchecked.update(unchecked)
 
-        yield len(self._inferred_ports) > 0
+        yield len(self._inferred_ports) > 0 or any(
+            port.type_qualifier is not TypeQualifier.Quantum
+            for port in self._signature_ports.values()
+        )
 
         self._set_unused_as_const()
         self._signature_ports.clear()
         self._inferred_ports.clear()
+        self._unchecked.clear()
+
+    @contextmanager
+    def conjugation_context(self) -> Iterator[None]:
+        previous_context = self._conjugation_context
+        self._conjugation_context = True
+        try:
+            yield
+        finally:
+            self._conjugation_context = previous_context
 
     def _set_unused_as_const(self) -> None:
         unresolved_ports = [
@@ -73,30 +105,50 @@ class TypeQualifierInference(ModelVisitor):
         for port in unresolved_ports:
             port.type_qualifier = TypeQualifier.Const
 
-    def _reduce_qualifier(self, candidate: str, qualifier: TypeQualifier) -> None:
+    def _validate_qualifier(self, candidate: str, qualifier: TypeQualifier) -> None:
+        if self._conjugation_context and qualifier is TypeQualifier.QFree:
+            qualifier = TypeQualifier.Const
+
         if candidate in self._inferred_ports:
             self._inferred_ports[candidate].type_qualifier = TypeQualifier.and_(
                 self._inferred_ports[candidate].type_qualifier, qualifier
             )
+            return
+
+        if candidate not in self._signature_ports or candidate in self._unchecked:
+            return
+
+        signature_qualifier = self._signature_ports[candidate].type_qualifier
+        if signature_qualifier is not TypeQualifier.and_(
+            signature_qualifier, qualifier
+        ):
+            raise ClassiqExpansionError(
+                _inconsistent_type_qualifier_error(
+                    candidate, signature_qualifier, qualifier
+                )
+            )
 
     def run(
-        self, ports: Collection[PortDeclaration], body: Sequence[QuantumStatement]
+        self,
+        ports: Collection[PortDeclaration],
+        body: Sequence[QuantumStatement],
+        unchecked: Collection[str],
     ) -> None:
-        with self.infer_ports(ports) as should_infer:
-            if should_infer:
+        with self.validate_ports(ports, unchecked) as should_validate:
+            if should_validate:
                 self.visit(body)
 
     def visit_QuantumFunctionCall(self, call: QuantumFunctionCall) -> None:
         for handle, port in call.handles_with_params:
-            self._reduce_qualifier(handle.name, port.type_qualifier)
+            self._validate_qualifier(handle.name, port.type_qualifier)
 
     def visit_Allocate(self, alloc: Allocate) -> None:
-        self._reduce_qualifier(alloc.target.name, TypeQualifier.QFree)
+        self._validate_qualifier(alloc.target.name, TypeQualifier.QFree)
 
     def visit_BindOperation(self, bind_op: BindOperation) -> None:
         reduced_qualifier = self._get_reduced_qualifier(bind_op)
         for handle in itertools.chain(bind_op.in_handles, bind_op.out_handles):
-            self._reduce_qualifier(handle.name, reduced_qualifier)
+            self._validate_qualifier(handle.name, reduced_qualifier)
 
     def _get_reduced_qualifier(self, bind_op: BindOperation) -> TypeQualifier:
         handles = itertools.chain(bind_op.in_handles, bind_op.out_handles)
@@ -131,7 +183,7 @@ class TypeQualifierInference(ModelVisitor):
             itertools.chain(signature_ports.values(), known_inferred_ports.values())
         )
         if len(known_ports) == 0:
-            return TypeQualifier.Quantum
+            return TypeQualifier.Const
         elif len(known_ports) == 1:
             return known_ports[0].type_qualifier
         else:
@@ -149,25 +201,25 @@ class TypeQualifierInference(ModelVisitor):
 
     def visit_ArithmeticOperation(self, arith: ArithmeticOperation) -> None:
         result_var = arith.result_var.name
-        self._reduce_qualifier(result_var, TypeQualifier.QFree)
+        self._validate_qualifier(result_var, TypeQualifier.QFree)
         for expr_var in self._extract_expr_vars(arith):
-            self._reduce_qualifier(expr_var, TypeQualifier.Const)
+            self._validate_qualifier(expr_var, TypeQualifier.Const)
 
     def visit_AmplitudeLoadingOperation(
         self, amp_load: AmplitudeLoadingOperation
     ) -> None:
         result_var = amp_load.result_var.name
-        self._reduce_qualifier(result_var, TypeQualifier.Quantum)
+        self._validate_qualifier(result_var, TypeQualifier.Quantum)
         for expr_var in self._extract_expr_vars(amp_load):
-            self._reduce_qualifier(expr_var, TypeQualifier.Const)
+            self._validate_qualifier(expr_var, TypeQualifier.Const)
 
     def visit_PhaseOperation(self, phase_op: PhaseOperation) -> None:
         for expr_var in self._extract_expr_vars(phase_op):
-            self._reduce_qualifier(expr_var, TypeQualifier.Const)
+            self._validate_qualifier(expr_var, TypeQualifier.Const)
 
     def visit_Control(self, control: Control) -> None:
         for control_var in self._extract_expr_vars(control):
-            self._reduce_qualifier(control_var, TypeQualifier.Const)
+            self._validate_qualifier(control_var, TypeQualifier.Const)
         self.visit(control.body)
         if control.else_block is not None:
             self.visit(control.else_block)
@@ -179,5 +231,6 @@ class TypeQualifierInference(ModelVisitor):
         self.visit(power.body)
 
     def visit_WithinApply(self, within_apply: WithinApply) -> None:
-        self.visit(within_apply.compute)
+        with self.conjugation_context():
+            self.visit(within_apply.compute)
         self.visit(within_apply.action)

classiq/model_expansions/visitors/symbolic_param_inference.py

@@ -152,16 +152,10 @@ class SymbolicParamInference(ModelVisitor):
             ):
                 self._process_compile_time_expressions(arg)
             else:
-                if isinstance(arg, Expression):
-                    for expr_part in self.get_generative_expression_parts(arg.expr):
-                        self._process_compile_time_expression(expr_part)
                 for expr in _get_expressions(arg):
                     self._process_nested_compile_time_expression(expr.expr)
         self.generic_visit(call)
 
-    def get_generative_expression_parts(self, expr: str) -> list[str]:
-        return []
-
     def _get_params(self, call: QuantumFunctionCall) -> Sequence[AnonPositionalArg]:
         name = call.func_name
         if name in self._scope_operands:

classiq/open_library/functions/amplitude_amplification.py

@@ -1,5 +1,3 @@
-import numpy as np
-
 from classiq.open_library.functions.grover import grover_operator
 from classiq.qmod.builtins.functions.standard_gates import RY
 from classiq.qmod.builtins.operations import (
@@ -13,7 +11,7 @@ from classiq.qmod.cparam import CInt, CReal
 from classiq.qmod.qfunc import qfunc
 from classiq.qmod.qmod_variable import QArray, QBit
 from classiq.qmod.quantum_callable import QCallable
-from classiq.qmod.symbolic import acos, asin, ceiling, sin
+from classiq.qmod.symbolic import acos, asin, ceiling, pi, sin
 
 
 @qfunc
@@ -69,8 +67,8 @@ def exact_amplitude_amplification(
         packed_vars: The variable that holds the state to be amplified. Assumed to be in the zero state at the beginning of the algorithm.
     """
     aux = QBit()
-    k = ceiling((np.pi / (4 * asin(amplitude))) - 0.5)
-    theta = np.pi / (4 * k + 2)
+    k = ceiling((pi / (4 * asin(amplitude))) - 0.5)
+    theta = pi / (4 * k + 2)
     rot_phase = 2 * acos(sin(theta) / amplitude)
 
     extended_qvars: QArray = QArray()

classiq/open_library/functions/state_preparation.py

@@ -57,6 +57,10 @@ def allocate_num(
     """
     [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:
@@ -64,6 +68,11 @@ def allocate_num(
         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)
 
 
@@ -429,19 +438,14 @@ def _dicke_split_cycle_shift(k: int, qvar: QArray[QBit]) -> None:
 
 @qfunc
 def prepare_dicke_state_unary_input(max_k: int, qvar: QArray[QBit]) -> None:
-    """
-    assumes the input is encoded in qvar in unary encoding. should work for every value
-    smaller than max_k
-    """
     """
     [Qmod Classiq-library function]
 
     Prepares a Dicke state with a variable number of excitations based on an unary-encoded input.
 
     The Dicke state is defined to be:
-    $$
-    \\mathrm{Dicke}(n, k) = \frac{1}{\\sqrt{\binom{n}{k}}} \\sum_{x \\in \\{0,1\\}^n,\\, |x| = k} |x\rangle
-    $$
+
+    $$\\mathrm{Dicke}(n, k) = \\frac{1}{\\sqrt{\\binom{n}{k}}} \\sum_{x \\in \\{0,1\\}^n,\\, |x| = k} |x\\rangle$$
 
     The input register `qvar` is expected to already be initialized in a unary encoding:
     the value k is represented by a string of k ones followed by zeros, e.g., k = 3 -> |11100...0>.
@@ -465,14 +469,15 @@ def prepare_dicke_state(k: int, qvar: QArray[QBit]) -> None:
     Prepares a Dicke state with k excitations over the provided quantum register.
 
     A Dicke state of n qubits with k excitations is an equal superposition of all basis states
-    with exactly k qubits in the |1> state and (n - k) qubits in the |0? state.
-    For example, Dicke(2, 1) = (|01> + |10>) / sqrt(2). In the general case it is define to be:
-    $$
-    \\mathrm{Dicke}(n, k) = \frac{1}{\\sqrt{\binom{n}{k}}} \\sum_{x \\in \\{0,1\\}^n,\\, |x| = k} |x\rangle
-    $$
+    with exactly k qubits in the $|1\\rangle$ state and $(n - k)$ qubits in the $|0\\rangle$ state.
+    For example, $\\mathrm{Dicke}(2, 1) = (|01\\rangle + |10\\rangle) / \\sqrt(2)$.
+
+    In the general case it is defined to be:
+
+    $$\\mathrm{Dicke}(n, k) = \\frac{1}{\\sqrt{\\binom{n}{k}}} \\sum_{x \\in \\{0,1\\}^n,\\, |x| = k} |x\\rangle$$
 
     Args:
-        k: The number of excitations (i.e., number of qubits in state |1>).
+        k: The number of excitations (i.e., number of qubits in state $|1\\rangle$).
         qvar: The quantum register (array of qubits) to initialize. Must be uninitialized and have length >= k.
     """
     if k > 0:

classiq/qmod/builtins/functions/__init__.py

@@ -70,8 +70,9 @@ CORE_LIB_DECLS = [
         inplace_prepare_amplitudes_approx,
         single_pauli_exponent,
         commuting_paulis_exponent,
-        sparse_suzuki_trotter,
         suzuki_trotter,
+        parametric_suzuki_trotter,
+        sparse_suzuki_trotter,
         qdrift,
         exponentiation_with_depth_constraint,
         RESET,
@@ -131,6 +132,7 @@ __all__ = [  # noqa: RUF022
     "molecule_hartree_fock",
     "molecule_hva",
     "molecule_ucc",
+    "parametric_suzuki_trotter",
     "pauli_feature_map",
     "permute",
     "prepare_amplitudes",

classiq/qmod/builtins/functions/exponentiation.py

@@ -66,7 +66,9 @@ def suzuki_trotter(
     """
     [Qmod core-library function]
 
-    Applies the Suzuki-Trotter decomposition to a Pauli operator. The Suzuki-Trotter decomposition is a method for approximating the exponential of a sum of operators by a product of exponentials of each operator.
+    Applies the Suzuki-Trotter decomposition to a Pauli operator.
+
+    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.
 
@@ -80,6 +82,37 @@ def suzuki_trotter(
     pass
 
 
+@qfunc(external=True)
+def parametric_suzuki_trotter(
+    paulis: CArray[CArray[Pauli]],
+    coefficients: CArray[CReal, Literal["get_field(paulis, 'len')"]],
+    evolution_coefficient: CReal,
+    order: CInt,
+    repetitions: CInt,
+    qbv: QArray[QBit, Literal["get_field(paulis[0], 'len')"]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Applies the Suzuki-Trotter decomposition to a Pauli operator represented by two
+    separate lists of paulis and coefficients.
+    Supports symbolic coefficients, including execution parameters.
+
+    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:
+        paulis: The Paulis of the Pauli operator.
+        coefficients: The coefficients of the Pauli operator.
+        evolution_coefficient: A global evolution coefficient multiplying the Pauli operator.
+        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 sparse_suzuki_trotter(
     pauli_operator: SparsePauliOp,
@@ -89,8 +122,13 @@ def sparse_suzuki_trotter(
     qbv: QArray[QBit, Literal["get_field(pauli_operator, 'num_qubits')"]],
 ) -> None:
     """
-    Applies the Suzuki-Trotter decomposition to a sparse Pauli operator. For more details,
-    See about Suzuki-Trotter decomposition in `suzuki_trotter` `qfunc`.
+    [Qmod core-library function]
+
+    Applies the Suzuki-Trotter decomposition to a sparse Pauli operator.
+
+    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:
          pauli_operator: The Pauli operator to be exponentiated, in sparse representation (See: SparsePauliOp).