classiq 0.87.0__py3-none-any.whl → 0.88.0__py3-none-any.whl

classiq/qmod/builtins/enums.py

@@ -135,13 +135,6 @@ class FermionMapping(IntEnum):
     FAST_BRAVYI_KITAEV = 3
 
 
-class FinanceFunctionType(IntEnum):
-    VAR = 0
-    SHORTFALL = 1
-    X_SQUARE = 2
-    EUROPEAN_CALL_OPTION = 3
-
-
 class LadderOperator(IntEnum):
     PLUS = 0
     MINUS = 1
@@ -160,25 +153,39 @@ class Pauli(IntEnum):
     """
     Enumeration for the Pauli matrices used in quantum computing.
 
-    The Pauli matrices are fundamental operations in quantum computing, and this
-    enum assigns integer values to represent each matrix.
+    Represents the four Pauli matrices used in quantum mechanics: Identity (I), X, Y, and Z operators.
+    The Pauli matrices are defined as:
+
+    $$
+    I = \\begin{pmatrix} 1 & 0 \\\\ 0 & 1 \\end{pmatrix}
+    $$
+
+    $$
+    X = \\begin{pmatrix} 0 & 1 \\\\ 1 & 0 \\end{pmatrix}
+    $$
+
+    $$
+    Y = \\begin{pmatrix} 0 & -i \\\\ i & 0 \\end{pmatrix}
+    $$
+
+    $$
+    Z = \\begin{pmatrix} 1 & 0 \\\\ 0 & -1 \\end{pmatrix}
+    $$
+
+    Attributes:
+        I (int): The identity operator (value 0).
+        X (int): The Pauli-X operator (value 1).
+        Y (int): The Pauli-Y operator (value 2).
+        Z (int): The Pauli-Z operator (value 3).
     """
 
     I = 0  # noqa: E741
-    """I (int): Identity matrix, represented by the integer 0. \n
-    $I = \\begin{bmatrix} 1 & 0 \\\\ 0 & 1 \\end{bmatrix}$"""
 
     X = 1
-    """X (int): Pauli-X matrix, represented by the integer 1. \n
-    $X = \\begin{bmatrix} 0 & 1 \\\\ 1 & 0 \\end{bmatrix}$"""
 
     Y = 2
-    """Y (int): Pauli-Y matrix, represented by the integer 2. \n
-    $Y = \\begin{bmatrix} 0 & -i \\\\ i & 0 \\end{bmatrix}$"""
 
     Z = 3
-    """Z (int): Pauli-Z matrix, represented by the integer 3. \n
-    $Z = \\begin{bmatrix} 1 & 0 \\\\ 0 & -1 \\end{bmatrix}$"""
 
     def __call__(self, index: int) -> "SparsePauliOp":
         from classiq.qmod.builtins.structs import (
@@ -224,7 +231,6 @@ BUILTIN_ENUM_DECLARATIONS = {
 __all__ = [
     "Element",
     "FermionMapping",
-    "FinanceFunctionType",
     "LadderOperator",
     "Optimizer",
     "Pauli",

classiq/qmod/builtins/functions/__init__.py

@@ -3,7 +3,6 @@ from .arithmetic import *
 from .benchmarking import *
 from .chemistry import *
 from .exponentiation import *
-from .finance import *
 from .mid_circuit_measurement import *
 from .operators import *
 from .qsvm import *
@@ -18,8 +17,6 @@ CORE_LIB_DECLS = [
         fock_hamiltonian_ucc,
         fock_hamiltonian_hva,
         fock_hamiltonian_hartree_fock,
-        log_normal_finance,
-        gaussian_finance,
         pauli_feature_map,
         bloch_sphere_feature_map,
         H,
@@ -121,13 +118,11 @@ __all__ = [  # noqa: RUF022
     "fock_hamiltonian_hva",
     "fock_hamiltonian_ucc",
     "free",
-    "gaussian_finance",
     "inplace_prepare_amplitudes",
     "inplace_prepare_amplitudes_approx",
     "inplace_prepare_state",
     "inplace_prepare_state_approx",
     "integer_xor",
-    "log_normal_finance",
     "modular_add",
     "modular_add_constant",
     "molecule_hartree_fock",

classiq/qmod/builtins/operations.py

@@ -147,6 +147,22 @@ def bind(
     source: Union[Input[QVar], list[Input[QVar]]],
     destination: Union[Output[QVar], list[Output[QVar]]],
 ) -> None:
+    """
+    Reassign qubit or arrays of qubits by redirecting their logical identifiers.
+
+    This operation rewires the logical identity of the `source` qubits to new objects given in `destination`.
+    For example, an array of two qubits `X` can be mapped to individual qubits `Y` and `Z`.
+
+    Args:
+        source: A qubit or list of initialized qubits to reassign.
+        destination: A qubit or list of target qubits to bind to. Must match the number of qubits in `source`.
+
+    Notes:
+        - After this operation, `source` qubits are unbound and considered uninitialized.
+        - `source` and `destination` must be of the same length.
+
+    For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/statements/bind).
+    """
     assert QCallable.CURRENT_EXPANDABLE is not None
     source_ref = get_source_ref(sys._getframe(1))
     if not isinstance(source, list):
@@ -168,6 +184,18 @@ def if_(
     then: Union[QCallable, Callable[[], Statements]],
     else_: Union[QCallable, Callable[[], Statements], int] = _MISSING_VALUE,
 ) -> None:
+    """
+    Conditionally executes quantum operations based on a symbolic or boolean expression.
+
+    This function defines classical control flow within a quantum program. It allows quantum operations to be
+    conditionally executed based on symbolic expressions - such as parameters used in variational algorithms,
+    loop indices, or other classical variables affecting quantum control flow.
+
+    Args:
+        condition: A symbolic or boolean expression evaluated at runtime to determine the execution path.
+        then: A quantum operation executed when `condition` evaluates to True.
+        else_: (Optional) A quantum operation executed when `condition` evaluates to False.
+    """
     _validate_operand(then)
     if else_ != _MISSING_VALUE:
         _validate_operand(else_)
@@ -193,6 +221,22 @@ def control(
     stmt_block: Union[QCallable, Callable[[], Statements]],
     else_block: Union[QCallable, Callable[[], Statements], None] = None,
 ) -> None:
+    """
+    Conditionally executes quantum operations based on the value of quantum variables or expressions.
+
+    This operation enables quantum control flow similar to classical `if` statements. It evaluates a quantum condition
+    and executes one of the provided quantum code blocks accordingly.
+
+    Args:
+        ctrl: A quantum control expression, which can be a logical expression, a single `QBit`, or a `QArray[QBit]`.
+            If `ctrl` is a logical expression, `stmt_block` is executed when it evaluates to `True`.
+            If `ctrl` is a `QBit` or `QArray[QBit]`, `stmt_block` is executed if all qubits are in the |1> state.
+        stmt_block: The quantum operations to execute when the condition holds. This can be a `QCallable` or a function
+            returning a `Statements` block.
+        else_block: (Optional) Quantum operations to execute when the condition does not hold.
+
+    For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/statements/control).
+    """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
     source_ref = get_source_ref(sys._getframe(1))
@@ -308,6 +352,18 @@ def within_apply(
     within: Callable[[], Statements],
     apply: Callable[[], Statements],
 ) -> None:
+    r"""
+    Given two operations $U$ and $V$, performs the sequence of operations $U^{-1} V U$.
+
+    This operation is used to represent a sequence where the inverse gate `U^{-1}` is applied, followed by another operation `V`, and then `U` is applied to uncompute. This pattern is common in reversible
+    computation and quantum subroutines.
+
+    Args:
+        within: The unitary operation `U` to be computed and then uncomputed.
+        apply: The operation `V` to be applied within the `U` block.
+
+    For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/statements/within-apply).
+    """
     _validate_operand(within)
     _validate_operand(apply)
     assert QCallable.CURRENT_EXPANDABLE is not None
@@ -327,6 +383,29 @@ def within_apply(
 def repeat(
     count: Union[SymbolicExpr, int], iteration: Callable[[int], Statements]
 ) -> None:
+    """
+    Executes a quantum loop a specified number of times, applying a quantum operation on each iteration.
+
+    This operation provides quantum control flow similar to a classical `for` loop, enabling repeated
+    application of quantum operations based on classical loop variables.
+
+    Args:
+        count: An integer or symbolic expression specifying the number of loop iterations.
+        iteration: A callable that takes a single integer index and returns the quantum operations to
+                   be performed at each iteration.
+
+    Example:
+        ```python
+        from classiq import qfunc, Output, QArray, QBit, allocate, repeat, RX
+        from classiq.qmod.symbolic import pi
+
+
+        @qfunc
+        def main(x: Output[QArray[QBit]]):
+            allocate(10, x)
+            repeat(x.len, lambda i: RX(2 * pi * i / x.len, x[i]))
+        ```
+    """
     _validate_operand(iteration, num_params=1)
     assert QCallable.CURRENT_EXPANDABLE is not None
     source_ref = get_source_ref(sys._getframe(1))
@@ -362,6 +441,34 @@ def power(
     exponent: Union[SymbolicExpr, int],
     stmt_block: Union[QCallable, Callable[[], Statements]],
 ) -> None:
+    """
+    Apply a quantum operation raised to a symbolic or integer power.
+
+    This function enables exponentiation of a quantum gate, where the exponent can be a
+    symbolic expression or an integer. It is typically used within a quantum program
+    to repeat or scale quantum operations in a parameterized way.
+
+    Args:
+        exponent: The exponent value, either as an integer or a symbolic expression.
+        stmt_block: A callable that produces the quantum operation to be exponentiated.
+
+    Example:
+        ```python
+        from classiq import qfunc, Output, QArray, QBit, allocate, repeat, RX, power
+        from classiq.qmod.symbolic import pi
+
+
+        @qfunc
+        def my_RX(x: QArray[QBit], i: CInt):
+            RX(2 * pi / x.len, x[i])
+
+
+        @qfunc
+        def main(x: Output[QArray[QBit]]):
+            allocate(10, x)
+            repeat(x.len, lambda i: power(i, lambda: my_RX(x, i)))
+        ```
+    """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
     source_ref = get_source_ref(sys._getframe(1))
@@ -377,6 +484,27 @@ def power(
 
 @suppress_return_value
 def invert(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None:
+    """
+    Apply the inverse of a quantum gate.
+
+    This function allows inversion of a quantum gate. It is typically used within a quantum program
+    to invert a sequence of operations.
+
+    Args:
+        stmt_block: A callable that produces the quantum operation to be inverted.
+
+    Example:
+        ```python
+        from classiq import qfunc, Output, QArray, QBit, allocate, qft, invert
+        from classiq.qmod.symbolic import pi
+
+
+        @qfunc
+        def main(x: Output[QArray[QBit]]):
+            allocate(10, x)
+            invert(qft(x))
+        ```
+    """
     _validate_operand(stmt_block)
     assert QCallable.CURRENT_EXPANDABLE is not None
     source_ref = get_source_ref(sys._getframe(1))
@@ -390,6 +518,20 @@ def invert(stmt_block: Union[QCallable, Callable[[], Statements]]) -> None:
 
 @suppress_return_value
 def phase(expr: SymbolicExpr, theta: float = 1.0) -> None:
+    """
+    Applies a state-dependent phase shift to the quantum state.
+
+    This operation multiplies each basis state |x> by a complex phase factor `theta * expr(x)`,
+    where `expr` is a symbolic expression dependent on the state value `x`, and `theta` is a scalar multiplier.
+
+    Args:
+        expr: A symbolic expression that evaluates to an angle (in radians) as a function of the quantum state value `x`.
+        theta: (Optional) A scalar multiplier for the evaluated expression. Defaults to 1.0.
+
+    Note:
+        The `phase` operation is equivalent to a Z-rotation up to a global phase. It is commonly used
+        to apply relative phase shifts conditioned on the quantum state.
+    """
     assert QCallable.CURRENT_EXPANDABLE is not None
     source_ref = get_source_ref(sys._getframe(1))
     QCallable.CURRENT_EXPANDABLE.append_statement_to_body(

classiq/qmod/builtins/structs.py

@@ -205,16 +205,6 @@ class LogNormalModel:
     sigma: CReal
 
 
-@dataclass
-class FinanceFunction:
-    f: CInt
-    threshold: CReal
-    larger: CBool
-    polynomial_degree: CInt
-    use_chebyshev_polynomial_approximation: CBool
-    tail_probability: CReal
-
-
 @dataclass
 class QsvmResult:
     test_score: CReal
@@ -246,7 +236,6 @@ BUILTIN_STRUCT_DECLARATIONS = {
 __all__ = [
     "ChemistryAtom",
     "CombinatorialOptimizationSolution",
-    "FinanceFunction",
     "FockHamiltonianProblem",
     "GaussianModel",
     "IndexedPauli",

classiq/qmod/native/pretty_printer.py

@@ -111,7 +111,7 @@ class DSLPrettyPrinter(ModelVisitor):
 
     def visit_Model(self, model: Model) -> str:
         # FIXME - CAD-20149: Remove this line once the froggies are removed, and the visit of lambdas can be done without accessing the func_decl property (with rename_params values only).
-        resolve_function_calls(model, model.function_dict)
+        resolve_function_calls(model, model.function_dict, annotate_types=False)
         self._compilation_metadata = model.functions_compilation_metadata
 
         enum_decls = [self.visit(enum_decl) for enum_decl in model.enums]

classiq/qmod/pretty_print/expression_to_python.py

@@ -154,12 +154,9 @@ class ASTToQMODCode(ast.NodeVisitor):
             )
             return f"{self.visit(node.args[0])}({initializer_list})"
         else:
-            args = [self._cleaned_ast_to_code(arg) for arg in node.args]
-            kwargs = [
-                f"{kwarg.arg}={self._cleaned_ast_to_code(kwarg.value)}"
-                for kwarg in node.keywords
-            ]
-            return "{}({})".format(func, ", ".join(args + kwargs))
+            return "{}({})".format(
+                func, ", ".join(self._cleaned_ast_to_code(arg) for arg in node.args)
+            )
 
     def visit_Expr(self, node: ast.Expr) -> str:
         return self._cleaned_ast_to_code(node.value)

classiq/qmod/pretty_print/pretty_printer.py

@@ -303,10 +303,13 @@ class PythonPrettyPrinter(ModelVisitor):
             raise ClassiqInternalError
 
         is_unsigned = (
-            is_signed_expr.is_evaluated() and not is_signed_expr.to_bool_value()
+            is_signed_expr.is_evaluated()
+            and is_signed_expr.is_constant()
+            and not is_signed_expr.to_bool_value()
         ) or is_signed_expr.expr == "UNSIGNED"
         is_integer = (
             fraction_digits_expr.is_evaluated()
+            and fraction_digits_expr.is_constant()
             and fraction_digits_expr.to_int_value() == 0
         )
         if is_unsigned and is_integer:

classiq/qmod/qmod_variable.py

@@ -63,7 +63,7 @@ from classiq.interface.model.quantum_type import (
 )
 from classiq.interface.source_reference import SourceReference
 
-from classiq.qmod.cparam import ArrayBase, CInt, CParamScalar
+from classiq.qmod.cparam import ArrayBase, CBool, CInt, CParamScalar
 from classiq.qmod.generative import (
     generative_mode_context,
     interpret_expression,
@@ -270,6 +270,59 @@ class QScalar(QVar, SymbolicExpr):
 
 
 class QBit(QScalar):
+    """A type representing a single qubit.
+
+    `QBit` serves both as a placeholder for a temporary, non-allocated qubit
+    and as the type of an allocated physical or logical qubit.
+    Conceptually, a qubit is a two-level quantum system, described by the
+    superposition of the computational basis states:
+
+    $$
+    |0\\rangle = \\begin{pmatrix} 1 \\\\ 0 \\end{pmatrix},
+    \\quad
+    |1\\rangle = \\begin{pmatrix} 0 \\\\ 1 \\end{pmatrix}
+    $$
+
+    Therefore, a qubit state is a linear combination:
+
+    $$
+    |\\psi\\rangle = \\alpha |0\\rangle + \\beta |1\\rangle,
+    $$
+
+    where \\( \\alpha \\) and \\( \\beta \\) are complex numbers satisfying:
+
+    $$
+    |\\alpha|^2 + |\\beta|^2 = 1.
+    $$
+
+    Typical usage includes:
+
+    - Representing an unallocated qubit before its allocation.
+    - Acting as the output type for a qubit or an allocated qubit in the main function after calling an allocation function.
+
+    Examples:
+
+    Example 1: Unallocated qubit:
+        ```python
+        @qfunc
+        def my_func(x1: QBit):
+            # Defining x2 as an unallocated qubit, binding it to declared qubit
+            x2 = QBit()
+            bind(x1, x2)
+        ```
+
+    Example 2, output type for a qubit:
+        ```python
+        def main(q: Output[QBit]):
+            allocate(1, q)
+        ```
+
+    Attributes:
+        None
+
+    For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/quantum-types/#semantics).
+    """
+
     @classmethod
     def to_qvar(
         cls,
@@ -287,13 +340,52 @@ _P = ParamSpec("_P")
 
 
 class QNum(Generic[_P], QScalar):
+    """
+    QNum is a quantum variable that represents a numeric value, which can be either integer or fixed-point,
+    encoded within a quantum register. It consists of an array of qubits for quantum representation and
+    classical metadata (number of fraction digits, sign) to define its numeric behavior.
+
+    QNum enables numerical computation in quantum circuits, supporting both signed and unsigned
+    formats, as well as configurable fixed-point precision. It is a parameterizable scalar type,
+    meaning its behavior can depend on symbolic or compile-time values. The total number of
+    qubits (`size`) determines the resolution and range of representable values.
+
+    Args:
+        name (str, optional): Identifier for this quantum number.
+        size (int, CInt, optional): Number of qubits allocated for this number.
+            Must be defined if either `is_signed` or `fraction_digits` is set.
+        is_signed (Union[bool, Expression, SymbolicExpr], optional): Whether the number is signed (i.e., can be negative).
+            Can be defined by a bool variable, or an arithmetic expression.
+            Must be set in tandem with `fraction_digits`.
+        fraction_digits (Union[int, CInt, Expression], optional): Number of fractional binary digits.
+            Defines the fixed-point precision. Must be set along with `is_signed`.
+
+    Methods:
+        fraction_digits -> Union[CParamScalar, int]:
+            Property that retrieves the number of fractional digits. Defaults to 0 if not specified.
+
+        is_signed -> Union[CParamScalar, bool]:
+            Property that retrieves whether the number is signed. Defaults to unsigned if not specified.
+
+    Example:
+        Example 1
+        ```python
+        @qfunc
+        def main(x: Output[QNum], y: Output[QNum]):
+            x |= 3.5  # Allocate a quantum number
+            y |= 2 * x
+        ```
+
+    For more details, see [Qmod Reference](https://docs.classiq.io/latest/qmod-reference/language-reference/quantum-types/#semantics).
+    """
+
     CONSTRUCTOR_DEPTH: int = 3
 
     def __init__(
         self,
         name: Union[None, str, HandleBinding] = None,
         size: Union[int, CInt, Expression, SymbolicExpr, None] = None,
-        is_signed: Union[bool, Expression, SymbolicExpr, None] = None,
+        is_signed: Union[bool, CBool, Expression, SymbolicExpr, None] = None,
         fraction_digits: Union[int, CInt, Expression, None] = None,
         _expr_str: Optional[str] = None,
     ):

classiq/qmod/semantics/annotation/call_annotation.py

@@ -82,6 +82,7 @@ class _CallLambdaAnnotator(ModelVisitor):
 def resolve_function_calls(
     root: Any,
     quantum_function_dict: Optional[Mapping[str, QuantumFunctionDeclaration]] = None,
+    annotate_types: bool = True,
 ) -> None:
     if quantum_function_dict is None:
         quantum_function_dict = {}
@@ -93,6 +94,7 @@ def resolve_function_calls(
         **quantum_function_dict,
     }
     with ErrorManager().ignore_errors_context():
-        QStructAnnotator().visit(quantum_function_dict)
-        QStructAnnotator().visit(root)
+        if annotate_types:
+            QStructAnnotator().visit(quantum_function_dict)
+            QStructAnnotator().visit(root)
         _CallLambdaAnnotator(all_functions).visit(root)

classiq/qmod/semantics/annotation/qstruct_annotator.py

@@ -1,15 +1,30 @@
+from classiq.interface.exceptions import ClassiqExpansionError
 from classiq.interface.generator.functions.type_name import TypeName
 from classiq.interface.generator.types.struct_declaration import StructDeclaration
 from classiq.interface.model.model_visitor import ModelVisitor
 
+from classiq.qmod.builtins.enums import BUILTIN_ENUM_DECLARATIONS
+from classiq.qmod.builtins.structs import BUILTIN_STRUCT_DECLARATIONS
 from classiq.qmod.model_state_container import QMODULE
 
+IGNORED_MISSING_TYPES = {"MoleculeResult"}
+
 
 class QStructAnnotator(ModelVisitor):
     def __init__(self) -> None:
-        self._visited: set[TypeName] = set()
+        self._visited: set[int] = set()
+        self._defined_type_names = (
+            set(QMODULE.enum_decls)
+            | set(QMODULE.type_decls)
+            | set(QMODULE.qstruct_decls)
+            | set(BUILTIN_STRUCT_DECLARATIONS)
+            | set(BUILTIN_ENUM_DECLARATIONS)
+            | IGNORED_MISSING_TYPES
+        )
 
     def visit_TypeName(self, type_name: TypeName) -> None:
+        if type_name.name not in self._defined_type_names:
+            raise ClassiqExpansionError(f"Undefined type {type_name.name}")
         self._annotate_quantum_struct(type_name)
         self._annotate_classical_struct(type_name)
 
@@ -17,13 +32,13 @@ class QStructAnnotator(ModelVisitor):
         if (
             type_name.has_classical_struct_decl
             or type_name.has_fields
-            or type_name in self._visited
+            or id(type_name) in self._visited
         ):
             return
         decl = QMODULE.qstruct_decls.get(type_name.name)
         if decl is None:
             return
-        self._visited.add(type_name)
+        self._visited.add(id(type_name))
         new_fields = {
             field_name: field_type.model_copy()
             for field_name, field_type in decl.fields.items()
@@ -37,13 +52,13 @@ class QStructAnnotator(ModelVisitor):
         if (
             type_name.has_classical_struct_decl
             or type_name.has_fields
-            or type_name in self._visited
+            or id(type_name) in self._visited
         ):
             return
         decl = QMODULE.type_decls.get(type_name.name)
         if decl is None:
             return
-        self._visited.add(type_name)
+        self._visited.add(id(type_name))
         new_fields = {
             field_name: field_type.model_copy(deep=True)
             for field_name, field_type in decl.variables.items()

{classiq-0.87.0.dist-info → classiq-0.88.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: classiq
-Version: 0.87.0
+Version: 0.88.0
 Summary: Classiq's Python SDK for quantum computing
 License: Proprietary
 Keywords: quantum computing,quantum circuits,quantum algorithms,QAD,QDL
@@ -40,8 +40,8 @@ Requires-Dist: matplotlib (>=3.4.3,<4.0.0)
 Requires-Dist: networkx (>=3.2.0,<4.0.0)
 Requires-Dist: notebook ; extra == "analyzer-sdk"
 Requires-Dist: numexpr (>=2.7.3,<3.0.0)
-Requires-Dist: numpy (>=1.20.1,<2.0.0) ; python_version < "3.12"
-Requires-Dist: numpy (>=1.26.0,<2.0.0) ; python_version >= "3.12"
+Requires-Dist: numpy (<3.0.0) ; python_version >= "3.10"
+Requires-Dist: numpy (>=1.26.4,<2.0.0) ; python_version < "3.10"
 Requires-Dist: openfermion ; extra == "chemistry"
 Requires-Dist: openfermionpyscf ; extra == "chemistry"
 Requires-Dist: packaging (>=23.2,<24.0)