classiq 0.45.1__py3-none-any.whl → 0.46.1__py3-none-any.whl

classiq/qmod/builtins/functions/state_preparation.py

@@ -0,0 +1,357 @@
+from typing import Literal
+
+from classiq.qmod.cparam import CArray, CBool, CInt, CReal
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import Input, Output, QArray, QBit, QNum
+
+
+@qfunc(external=True)
+def allocate(
+    num_qubits: CInt, out: Output[QArray[QBit, Literal["num_qubits"]]]
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Allocates the specified number of qubits to a given quantum variable and initializes
+    them in the zero state:
+
+    $$
+        \\left|\\text{out}\\right\\rangle = \\left|0\\right\\rangle^{\\otimes \\text{num_qubits}}
+    $$
+
+    Args:
+        num_qubits: The number of qubits to allocate. Must be a positive integer.
+        out: The quantum variable that will receive the allocated qubits. Must be uninitialized before allocation. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, the number of qubits allocated must match the declared number.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+    """
+    pass
+
+
+@qfunc(external=True)
+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]
+
+    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.
+
+    Further reading is available on the [reference manual](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-types#allocate-num)
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def free(in_: Input[QArray[QBit]]) -> None:
+    """
+    [Qmod core-library function]
+
+    Releases the qubits allocated to a quantum variable, allowing them to be reused.
+
+    Args:
+        in_: The quantum variable that will be freed. Must be initialized before. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Note:
+        This operation does not uncompute the qubits. It is the responsibility of the user to ensure that the qubits are at the zero state before freeing them.
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_state(
+    probabilities: CArray[CReal],
+    bound: CReal,
+    out: Output[QArray[QBit, Literal["log(get_field(probabilities, 'len'), 2)"]]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Initializes a quantum variable in a state corresponding to a given probability distribution:
+
+    $$
+        \\left|\\text{out}\\right\\rangle = \\sum_{i=0}^{\\text{len(probabilities)}-1} \\sqrt{\\text{probabilities}[i]} \\left|i\\right\\rangle
+    $$
+
+    with $i = 0, 1, 2, ..., \\text{len(amplitudes)}-1$ corresponding to computational basis states.
+
+    Args:
+        probabilities: The probability distribution to initialize the quantum variable. Must be a valid probability distribution, i.e., a list of non-negative real numbers that sum to 1. Must have a valid length (a power of 2).
+        bound: An error bound, expressed as the $L^{2}$ norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number.
+        out: The quantum variable that will receive the initialized state. Must be uninitialized. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, the number of qubits formed by the distribution must match the declared number.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_amplitudes(
+    amplitudes: CArray[CReal],
+    bound: CReal,
+    out: Output[QArray[QBit, Literal["log(get_field(amplitudes, 'len'), 2)"]]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Initializes a quantum variable in a state corresponding to the given amplitudes:
+
+    $$
+        \\left|\\text{out}\\right\\rangle = \\sum_{i=0}^{\\text{len(amplitudes)}-1} \\text{amplitudes}[i] \\left|i\\right\\rangle
+    $$
+
+    with $i = 0, 1, 2, ..., \\text{len(amplitudes)}-1$ corresponding to computational basis states.
+
+    Args:
+        amplitudes: The amplitudes to initialize the quantum variable. Must be a valid real quantum state vector, i.e., the sum of squares should be 1. Must have a valid length (a power of 2).
+        bound: An error bound, expressed as the $L^{2}$ norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number.
+        out: The quantum variable that will receive the initialized state. Must be uninitialized. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, the number of qubits formed by the distribution must match the declared number.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def inplace_prepare_state(
+    probabilities: CArray[CReal],
+    bound: CReal,
+    target: QArray[QBit, Literal["log(get_field(probabilities, 'len'), 2)"]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Transforms a given quantum variable in the state |0> to the state per the specified probability distribution
+    (similar to `prepare_state` but preformed on an initialized variable).
+
+    Args:
+        probabilities: The probability distribution corresponding to the quantum variable state. Must be a valid probability distribution, i.e., a list of non-negative real numbers that sum to 1. Must have a valid length (a power of 2).
+        bound: An error bound, expressed as the $L^{2}$ norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number.
+        target: The quantum variable to act upon.
+
+    This is useful as part of quantum building blocks like the Grover diffuser operator, $\\left|\\psi\\right\\rangle\\left\\langle\\psi\\right| \\left( 2\\left|0\\right\\rangle\\left\\langle0\\right| - \\mathcal{I} \\right)$, where the output state of the oracle is reflected about this state.
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def inplace_prepare_amplitudes(
+    amplitudes: CArray[CReal],
+    bound: CReal,
+    target: QArray[QBit, Literal["log(get_field(amplitudes, 'len'), 2)"]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Transforms a given quantum variable in the state |0> to the state per the specified amplitudes
+    (similar to `prepare_amplitudes` but preformed on an initialized variable).
+
+    Args:
+        amplitudes: The amplitudes to initialize the quantum variable. Must be a valid real quantum state vector, i.e., the sum of squares should be 1. Must have a valid length (a power of 2).
+        bound: An error bound, expressed as the $L^{2}$ norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number.
+        target: The quantum variable to act upon.
+
+    This is useful as part of quantum building blocks like the Grover diffuser operator, $\\left|\\psi\\right\\rangle\\left\\langle\\psi\\right| \\left( 2\\left|0\\right\\rangle\\left\\langle0\\right| - \\mathcal{I} \\right)$, where the output state of the oracle is reflected about this state.
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def _prepare_uniform_trimmed_state_step(
+    size_lsb: CInt, ctrl_val: CInt, lsbs_val: CInt, ctrl_var: QNum, rotation_var: QBit
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def prepare_uniform_trimmed_state(m: CInt, q: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable in a uniform superposition of the first `m` computational basis states:
+
+    $$
+        \\left|\\text{q}\\right\\rangle = \\frac{1}{\\sqrt{m}}\\sum_{i=0}^{m-1}{|i\\rangle}
+    $$
+
+    The number of allocated qubits would be $\\left\\lceil\\log_2{m}\\right\\rceil$.
+    The function is especially useful when `m` is not a power of 2.
+
+    Args:
+        m: The number of states to load in the superposition.
+        q: The quantum variable that will receive the initialized state. Must be uninitialized. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_uniform_interval_state(start: CInt, end: CInt, q: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable in a uniform superposition of the specified interval in the computational basis states:
+
+    $$
+        \\left|\\text{q}\\right\\rangle = \\frac{1}{\\sqrt{\\text{end} - \\text{start}}}\\sum_{i=\\text{start}}^{\\text{end}-1}{|i\\rangle}
+    $$
+
+    The number of allocated qubits would be $\\left\\lceil\\log_2{\\left(\\text{end}\\right)}\\right\\rceil$.
+
+    Args:
+        start: The lower bound of the interval to load (inclusive).
+        end: The upper bound of the interval to load (exclusive).
+        q: The quantum variable that will receive the initialized state. Must be uninitialized. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Notes:
+        1. If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
+        2. The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_ghz_state(size: CInt, q: Output[QArray[QBit]]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable in a Greenberger-Horne-Zeilinger (GHZ) state. i.e., a balanced superposition of all ones and all zeros, on an arbitrary number of qubits..
+
+    Args:
+        size: The number of qubits in the GHZ state. Must be a positive integer.
+        q: The quantum variable that will receive the initialized state. Must be uninitialized.
+
+    Notes:
+        The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_exponential_state(rate: CInt, q: QArray[QBit]) -> None:
+    """
+
+    [Qmod Classiq-library function]
+
+    Prepares a quantum state with exponentially decreasing amplitudes. The state is prepared in the computational basis, with the amplitudes of the states decreasing exponentially with the index of the state:
+
+    $$
+        P(n) = \\frac{1}{Z} e^{- \\text{rate} \\cdot n}
+    $$
+
+    Args:
+        rate: The rate of the exponential decay.
+        q: The quantum register to prepare.
+
+    Further reading is available on the [reference manual](https://docs.classiq.io/latest/explore/functions/qmod_library_reference/classiq_open_library/special_state_preparations/prepare_exponential_state)
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_bell_state(state_num: CInt, q: Output[QArray[QBit, Literal[2]]]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum array of size 2 in one of the four Bell states.
+
+    Args:
+        state_num: The number of the Bell state to be prepared. Must be an integer between 0 and 3.
+        q: The quantum variable that will receive the initialized state. Must be uninitialized.
+
+    Bell States:
+        The four Bell states are defined as follows (each state correlates to an integer between 0 and 3 as defined by the `state_num` argument):
+
+        If `state_num` = 0 the function prepares the Bell state:
+
+        $$
+            \\left|\\Phi^+\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 00 \\right\\rangle + \\left| 11 \\right\\rangle \\right)
+        $$
+
+        If `state_num` = 1 the function prepares the Bell state:
+
+        $$
+            \\left|\\Phi^-\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 00 \\right\\rangle - \\left| 11 \\right\\rangle \\right)
+        $$
+
+        If `state_num` = 2 the function prepares the Bell state:
+
+        $$
+            \\left|\\Psi^+\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 01 \\right\\rangle + \\left| 10 \\right\\rangle \\right)
+        $$
+
+        If `state_num` = 3 the function prepares the Bell state:
+
+        $$
+            \\left|\\Psi^-\\right\\rangle = \\frac{1}{\\sqrt{2}} \\left( \\left| 01 \\right\\rangle - \\left| 10 \\right\\rangle \\right)
+        $$
+
+    Notes:
+        The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
+
+
+    """
+    pass
+
+
+@qfunc(external=True)
+def inplace_prepare_int(value: CInt, target: QArray[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Transitions a quantum variable in the zero state $|0\\rangle$ into the computational basis state $|\\text{value}\\rangle$.
+    In the general case, the function performs a bitwise-XOR, i.e. transitions the state $|\\psi\\rangle$ into $|\\psi \\oplus \\text{value}\\rangle$.
+
+    Args:
+        value: The value to assign to the quantum variable.
+        target: The quantum variable to act upon.
+
+    Note:
+        If the value cannot fit into the quantum variable, it is truncated, i.e. treated as the value modulo $2^\\text{target.size}$.
+    """
+    pass
+
+
+@qfunc(external=True)
+def prepare_int(value: CInt, out: Output[QNum]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Initializes a quantum variable to the computational basis state $|\\text{value}\\rangle$.
+    The number of allocated qubits is automatically computed from the value, and is the minimal number required for representation in the computational basis.
+
+    Args:
+        value: The value to assign to the quantum variable.
+        out: The allocated quantum variable. Must be uninitialized. For more information on quantum variable initialization, see [here](https://docs.classiq.io/latest/reference-manual/qmod/language-reference/quantum-variables/).
+
+    Note:
+        If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
+    """
+    pass

classiq/qmod/builtins/functions/swap_test.py

@@ -0,0 +1,25 @@
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import Output, QArray, QBit
+
+
+@qfunc(external=True)
+def swap_test(state1: QArray[QBit], state2: QArray[QBit], test: Output[QBit]) -> None:
+    """
+    [Qmod Classiq-library function]
+
+    Tests the overlap (in terms of fidelity) of two quantum states.
+    The fidelity of `state1` and `state2` is calculated from the probability of measuring `test` qubit in the state 0 as follows:
+
+    $$
+        |\\langle state1 | state2 \\rangle |^2 = 2*Prob(test=0)-1
+    $$
+
+    Args:
+        state1: A quantum state to check its overlap with state2.
+        state2: A quantum state to check its overlap with state1.
+        test: A qubit for which the probability of measuring 0 is $0.5*(|\\langle state1 | state2 \\rangle |^2+1)$
+
+    Example:
+        Further reading in the Classiq library is found [here](https://docs.classiq.io/latest/explore/algorithms/swap_test/swap_test/).
+    """
+    pass

classiq/qmod/builtins/structs.py

@@ -1,64 +1,73 @@
-# This file was generated automatically - do not edit manually
+from dataclasses import dataclass, fields, is_dataclass
 
-from dataclasses import dataclass
+from classiq.interface.generator.types.struct_declaration import StructDeclaration
 
 from classiq.qmod.builtins.enums import LadderOperator, Pauli
-from classiq.qmod.qmod_parameter import CArray, CBool, CInt, CReal
+from classiq.qmod.cparam import CArray, CBool, CInt, CReal
+from classiq.qmod.python_classical_type import PythonClassicalType
 
 
 @dataclass
 class PauliTerm:
-    pauli: CArray[Pauli]
-    coefficient: CReal
+    """
+    A term in a Hamiltonian, represented as a product of Pauli operators.
 
+    Attributes:
+        pauli (CArray[Pauli]): The list of the chosen Pauli operators in the term, corresponds to a product of them.
+        coefficient (CReal): The coefficient of the term (floating number).
+    """
 
-@dataclass
-class MoleculeProblem:
-    mapping: CInt
-    z2_symmetries: CBool
-    molecule: "Molecule"
-    freeze_core: CBool
-    remove_orbitals: CArray[CInt]
+    pauli: CArray[Pauli]
+    coefficient: CReal
 
 
 @dataclass
-class Molecule:
-    atoms: CArray["ChemistryAtom"]
-    spin: CInt
-    charge: CInt
+class Position:
+    x: CReal
+    y: CReal
+    z: CReal
 
 
 @dataclass
 class ChemistryAtom:
     element: CInt
-    position: "Position"
+    position: Position
 
 
 @dataclass
-class Position:
-    x: CReal
-    y: CReal
-    z: CReal
+class Molecule:
+    atoms: CArray[ChemistryAtom]
+    spin: CInt
+    charge: CInt
 
 
 @dataclass
-class FockHamiltonianProblem:
+class MoleculeProblem:
     mapping: CInt
     z2_symmetries: CBool
-    terms: CArray["LadderTerm"]
-    num_particles: CArray[CInt]
+    molecule: Molecule
+    freeze_core: CBool
+    remove_orbitals: CArray[CInt]
+
+
+@dataclass
+class LadderOp:
+    op: LadderOperator
+    index: CInt
 
 
 @dataclass
 class LadderTerm:
     coefficient: CReal
-    ops: CArray["LadderOp"]
+    ops: CArray[LadderOp]
 
 
 @dataclass
-class LadderOp:
-    op: LadderOperator
-    index: CInt
+class FockHamiltonianProblem:
+    mapping: CInt
+    z2_symmetries: CBool
+    terms: CArray[LadderTerm]
+    num_particles: CArray[CInt]
 
 
 @dataclass
@@ -111,6 +120,19 @@ class QSVMFeatureMapPauli:
     paulis: CArray[CArray[Pauli]]
 
 
+BUILTIN_STRUCT_DECLARATIONS = {
+    struct_decl.__name__: StructDeclaration(
+        name=struct_decl.__name__,
+        variables={
+            field.name: PythonClassicalType().convert(field.type)
+            for field in fields(struct_decl)
+        },
+    )
+    for struct_decl in vars().values()
+    if is_dataclass(struct_decl)
+}
+
+
 __all__ = [
     "PauliTerm",
     "MoleculeProblem",

classiq/qmod/cparam.py

@@ -0,0 +1,64 @@
+import sys
+from typing import (  # type: ignore[attr-defined]
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Union,
+    _GenericAlias,
+)
+
+from typing_extensions import ParamSpec
+
+from classiq.qmod.symbolic_expr import Symbolic, SymbolicExpr
+
+if TYPE_CHECKING:
+    from classiq.qmod.qmod_variable import QNum
+
+    SymbolicSuperclass = SymbolicExpr
+else:
+    SymbolicSuperclass = Symbolic
+
+
+class CParam(SymbolicSuperclass):
+    def __init__(self, expr: str) -> None:
+        super().__init__(expr, False)
+
+
+class CInt(CParam):
+    pass
+
+
+class CReal(CParam):
+    pass
+
+
+class CBool(CParam):
+    pass
+
+
+_P = ParamSpec("_P")
+
+
+class ArrayBase(Generic[_P]):
+    # Support comma-separated generic args in older Python versions
+    if sys.version_info[0:2] < (3, 10):
+
+        def __class_getitem__(cls, args) -> _GenericAlias:
+            return _GenericAlias(cls, args)
+
+
+class CArray(CParam, ArrayBase[_P]):
+    if TYPE_CHECKING:
+
+        @property
+        def len(self) -> int: ...
+
+        def __getitem__(self, idx: Union[int, CInt, slice, "QNum"]) -> Any: ...
+
+
+Array = CArray
+
+
+class CParamScalar(CParam, SymbolicExpr):
+    def __hash__(self) -> int:
+        return hash(str(self))