classiq 0.37.1__py3-none-any.whl → 0.65.3__py3-none-any.whl

classiq/qmod/builtins/functions/allocation.py

@@ -0,0 +1,150 @@
+from typing import Literal
+
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CArray, CInt, CReal
+from classiq.qmod.qmod_variable import Input, Output, QArray, QBit
+
+
+@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.
+
+    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 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.
+
+    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.
+
+    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.
+
+    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

classiq/qmod/builtins/functions/arithmetic.py

@@ -0,0 +1,55 @@
+from typing import Literal
+
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CArray, CReal
+from classiq.qmod.qmod_variable import Output, QArray, QBit, QNum
+
+
+@qfunc(external=True)
+def unitary(
+    elements: CArray[CArray[CReal]],
+    target: QArray[QBit, Literal["log(get_field(elements[0], 'len'), 2)"]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Applies a unitary matrix on a quantum state.
+
+    Args:
+        elements:  A 2d array of complex numbers representing the unitary matrix. This matrix must be unitary.
+        target: The quantum state to apply the unitary on. Should be of corresponding size.
+    """
+    pass
+
+
+@qfunc(external=True)
+def add(
+    left: QArray[QBit],
+    right: QArray[QBit],
+    result: Output[
+        QArray[
+            QBit, Literal["Max(get_field(left, 'len'), get_field(right, 'len')) + 1"]
+        ]
+    ],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def modular_add(left: QArray[QBit], right: QArray[QBit]) -> None:
+    pass
+
+
+@qfunc(external=True)
+def modular_add_constant(left: CReal, right: QNum) -> None:
+    pass
+
+
+@qfunc(external=True)
+def integer_xor(left: QArray[QBit], right: QArray[QBit]) -> None:
+    pass
+
+
+@qfunc(external=True)
+def real_xor_constant(left: CReal, right: QNum) -> None:
+    pass

classiq/qmod/builtins/functions/benchmarking.py

@@ -0,0 +1,8 @@
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CInt
+from classiq.qmod.qmod_variable import QArray, QBit
+
+
+@qfunc(external=True)
+def randomized_benchmarking(num_of_cliffords: CInt, target: QArray[QBit]) -> None:
+    pass

classiq/qmod/builtins/functions/chemistry.py

@@ -0,0 +1,91 @@
+from typing import Literal
+
+from classiq.qmod.builtins.structs import (
+    FockHamiltonianProblem,
+    MoleculeProblem,
+)
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CArray, CInt
+from classiq.qmod.qmod_variable import QArray, QBit
+
+
+@qfunc(external=True)
+def molecule_ucc(
+    molecule_problem: MoleculeProblem,
+    excitations: CArray[CInt],
+    qbv: QArray[
+        QBit,
+        Literal[
+            "get_field(get_field(molecule_problem_to_hamiltonian(molecule_problem)[0], 'pauli'), 'len')"
+        ],
+    ],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def molecule_hva(
+    molecule_problem: MoleculeProblem,
+    reps: CInt,
+    qbv: QArray[
+        QBit,
+        Literal[
+            "get_field(get_field(molecule_problem_to_hamiltonian(molecule_problem)[0], 'pauli'), 'len')"
+        ],
+    ],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def molecule_hartree_fock(
+    molecule_problem: MoleculeProblem,
+    qbv: QArray[
+        QBit,
+        Literal[
+            "get_field(get_field(molecule_problem_to_hamiltonian(molecule_problem)[0], 'pauli'), 'len')"
+        ],
+    ],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def fock_hamiltonian_ucc(
+    fock_hamiltonian_problem: FockHamiltonianProblem,
+    excitations: CArray[CInt],
+    qbv: QArray[
+        QBit,
+        Literal[
+            "get_field(get_field(fock_hamiltonian_problem_to_hamiltonian(fock_hamiltonian_problem)[0], 'pauli'), 'len')"
+        ],
+    ],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def fock_hamiltonian_hva(
+    fock_hamiltonian_problem: FockHamiltonianProblem,
+    reps: CInt,
+    qbv: QArray[
+        QBit,
+        Literal[
+            "get_field(get_field(fock_hamiltonian_problem_to_hamiltonian(fock_hamiltonian_problem)[0], 'pauli'), 'len')"
+        ],
+    ],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def fock_hamiltonian_hartree_fock(
+    fock_hamiltonian_problem: FockHamiltonianProblem,
+    qbv: QArray[
+        QBit,
+        Literal[
+            "get_field(get_field(fock_hamiltonian_problem_to_hamiltonian(fock_hamiltonian_problem)[0], 'pauli'), 'len')"
+        ],
+    ],
+) -> None:
+    pass

classiq/qmod/builtins/functions/exponentiation.py

@@ -0,0 +1,105 @@
+from typing import Literal
+
+from classiq.qmod.builtins.enums import Pauli
+from classiq.qmod.builtins.structs import (
+    PauliTerm,
+)
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CArray, CInt, CReal
+from classiq.qmod.qmod_variable import QArray, QBit
+
+
+@qfunc(external=True)
+def single_pauli_exponent(
+    pauli_string: CArray[Pauli],
+    coefficient: CReal,
+    qbv: QArray[QBit, Literal["get_field(pauli_string, 'len')"]],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Exponentiates the specified single Pauli operator multiplied by some coefficient.
+
+    Args:
+        pauli_string: The Pauli operator to be exponentiated.
+        coefficient: A coefficient multiplying the Pauli operator.
+        qbv: The target quantum variable of the exponentiation.
+    """
+    pass
+
+
+@qfunc(external=True)
+def suzuki_trotter(
+    pauli_operator: CArray[PauliTerm],
+    evolution_coefficient: CReal,
+    order: CInt,
+    repetitions: CInt,
+    qbv: QArray[
+        QBit, Literal["get_field(get_field(pauli_operator[0], 'pauli'), 'len')"]
+    ],
+) -> None:
+    """
+    [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.
+    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.
+        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 qdrift(
+    pauli_operator: CArray[PauliTerm],
+    evolution_coefficient: CReal,
+    num_qdrift: CInt,
+    qbv: QArray[
+        QBit, Literal["get_field(get_field(pauli_operator[0], 'pauli'), 'len')"]
+    ],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Exponentiates a Pauli operator using the QDrift method. The QDrift method is a stochastic method based on the Trotter decomposition for approximating the exponential of a sum of operators by a product of exponentials of each operator.
+    The QDrift method randomizes the order of the operators in the product of exponentials to stochastically reduce the error of the approximation.
+    The error of the QDrift method decreases as the number of QDrift steps increases.
+
+    Args:
+        pauli_operator: The Pauli operator to be exponentiated.
+        evolution_coefficient: A global evolution coefficient multiplying the Pauli operator.
+        num_qdrift : The number of QDrift steps.
+        qbv: The target quantum variable of the exponentiation.
+    """
+    pass
+
+
+@qfunc(external=True)
+def exponentiation_with_depth_constraint(
+    pauli_operator: CArray[PauliTerm],
+    evolution_coefficient: CReal,
+    max_depth: CInt,
+    qbv: QArray[
+        QBit, Literal["get_field(get_field(pauli_operator[0], 'pauli'), 'len')"]
+    ],
+) -> None:
+    """
+    [Qmod core-library function]
+
+    Exponentiates a Pauli operator via the Suzuki-Trotter decomposition with a depth constraint.
+    The Suzuki-Trotter decomposition is a method for approximating the exponential of a sum of operators by a product of exponentials of each operator.
+    This function automatically determines the order and number of repetitions of the Suzuki-Trotter decomposition to minimize the error given a depth constraint.
+
+    Args:
+        pauli_operator: The Pauli operator to be exponentiated.
+        evolution_coefficient: A global coefficient multiplying the Pauli operator.
+        max_depth: The maximum depth of the exponentiation.
+        qbv: The target quantum variable of the exponentiation.
+    """
+    pass

classiq/qmod/builtins/functions/finance.py

@@ -0,0 +1,34 @@
+from typing import Literal
+
+from classiq.qmod.builtins.structs import (
+    FinanceFunction,
+    GaussianModel,
+    LogNormalModel,
+)
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_variable import QArray, QBit
+
+
+@qfunc(external=True)
+def log_normal_finance(
+    finance_model: LogNormalModel,
+    finance_function: FinanceFunction,
+    func_port: QArray[QBit, Literal["get_field(finance_model, 'num_qubits')"]],
+    obj_port: QBit,
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def gaussian_finance(
+    finance_model: GaussianModel,
+    finance_function: FinanceFunction,
+    func_port: QArray[
+        QBit,
+        Literal[
+            "get_field(finance_model, 'num_qubits') + get_field(get_field(finance_model, 'rhos'), 'len') + floor(log(sum(get_field(finance_model, 'loss')), 2)) + 1"
+        ],
+    ],
+    obj_port: QBit,
+) -> None:
+    pass

classiq/qmod/builtins/functions/operators.py

@@ -0,0 +1,16 @@
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.quantum_callable import QCallable, QCallableList
+
+
+@qfunc(external=True)
+def permute(
+    functions: QCallableList,
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def apply(
+    operand: QCallable,
+) -> None:
+    pass

classiq/qmod/builtins/functions/qsvm.py

@@ -0,0 +1,24 @@
+from typing import Literal
+
+from classiq.qmod.builtins.structs import (
+    QSVMFeatureMapPauli,
+)
+from classiq.qmod.qfunc import qfunc
+from classiq.qmod.qmod_parameter import CInt
+from classiq.qmod.qmod_variable import QArray, QBit
+
+
+@qfunc(external=True)
+def pauli_feature_map(
+    feature_map: QSVMFeatureMapPauli,
+    qbv: QArray[QBit, Literal["get_field(feature_map, 'feature_dimension')"]],
+) -> None:
+    pass
+
+
+@qfunc(external=True)
+def bloch_sphere_feature_map(
+    feature_dimension: CInt,
+    qbv: QArray[QBit, Literal["ceiling(feature_dimension / 2)"]],
+) -> None:
+    pass