classiq 0.83.0__py3-none-any.whl → 0.85.0__py3-none-any.whl

classiq/_internals/api_wrapper.py

@@ -600,3 +600,30 @@ class ApiWrapper:
         )
 
         return [UserBudget.model_validate(info) for info in data]
+
+    @classmethod
+    async def call_set_budget_limit(
+        cls, provider: str, budget_limit: float
+    ) -> UserBudget:
+        data = await client().call_api(
+            http_method=HTTPMethod.PATCH,
+            url=routes.USER_BUDGET_SET_LIMIT_FULL_PATH,
+            body={
+                "provider": provider,
+                "budget_limit": budget_limit,
+            },
+        )
+
+        return UserBudget.model_validate(data)
+
+    @classmethod
+    async def call_clear_budget_limit(cls, provider: str) -> UserBudget:
+        data = await client().call_api(
+            http_method=HTTPMethod.PATCH,
+            url=routes.USER_BUDGET_CLEAR_LIMIT_FULL_PATH,
+            body={
+                "provider": provider,
+            },
+        )
+
+        return UserBudget.model_validate(data)

classiq/applications/chemistry/chemistry_model_constructor.py

@@ -254,7 +254,6 @@ def _summed_fermionic_operator_to_qmod_lader_terms(
 ) -> str:
     return "\t\t".join(
         [
-            # fmt: off
             f"""
             struct_literal(LadderTerm,
                 coefficient={fermionic_operator[1]},
@@ -263,7 +262,6 @@ def _summed_fermionic_operator_to_qmod_lader_terms(
                 ]
             ),"""
             for fermionic_operator in hamiltonian.op_list
-            # fmt: on
         ]
     )[:-1]
 

classiq/applications/chemistry/hartree_fock.py

@@ -0,0 +1,68 @@
+from collections.abc import Sequence
+
+from openfermion.ops import FermionOperator
+from openfermion.ops.operators.qubit_operator import QubitOperator
+
+from classiq.applications.chemistry.mapping import FermionToQubitMapper
+from classiq.applications.chemistry.problems import FermionHamiltonianProblem
+
+
+def get_hf_fermion_op(problem: FermionHamiltonianProblem) -> FermionOperator:
+    """
+    Constructs a fermion operator that creates the Hartree-Fock reference state in
+    block-spin ordering.
+
+    Args:
+        problem (FermionHamiltonianProblem): The fermion problem. The Hartree-Fock
+            fermion operator depends only on the number of spatial orbitals and the
+            number of alpha and beta particles.
+
+    Returns:
+        The Hartree-Fock fermion operator.
+    """
+    return FermionOperator(" ".join(f"{i}^" for i in problem.occupied))
+
+
+def get_hf_state(
+    problem: FermionHamiltonianProblem, mapper: FermionToQubitMapper
+) -> list[bool]:
+    """
+    Computes the qubits state after applying the Hartree-Fock operator defined by the
+    given problem and mapper.
+
+    The Qmod function `prepare_basis_state` can be used on the returned value to
+    allocate and initialize the qubits array.
+
+    Args:
+        problem (FermionHamiltonianProblem): The fermion problem.
+        mapper (FermionToQubitMapper): The mapper from fermion operator to qubits
+            operator.
+
+    Returns:
+        The qubits state, given as a list of boolean values for each qubit.
+    """
+    hf_qubit_op = _get_hf_qubit_op(problem, mapper)
+    num_qubits = mapper.get_num_qubits(problem)
+    if not hf_qubit_op.terms:
+        return [False] * num_qubits
+
+    # All terms map the zero state to the same basis state
+    first_term = next(iter(hf_qubit_op.terms.keys()))
+    return _apply_term_on_zero_state(first_term, num_qubits)
+
+
+def _get_hf_qubit_op(
+    problem: FermionHamiltonianProblem, mapper: FermionToQubitMapper
+) -> QubitOperator:
+    hf_fermion_op = get_hf_fermion_op(problem)
+    return mapper.map(hf_fermion_op)
+
+
+def _apply_term_on_zero_state(
+    term: Sequence[tuple[int, str]], num_qubits: int
+) -> list[bool]:
+    state = [False] * num_qubits
+    for qubit, pauli in term:
+        if pauli in ("X", "Y"):
+            state[qubit] = True
+    return state

classiq/applications/chemistry/mapping.py

@@ -0,0 +1,85 @@
+from typing import Any, NoReturn
+
+from openfermion.ops import FermionOperator, QubitOperator
+from openfermion.transforms import (
+    bravyi_kitaev,
+    jordan_wigner,
+)
+
+from classiq.interface.enum_utils import StrEnum
+from classiq.interface.exceptions import ClassiqValueError
+
+from classiq.applications.chemistry.problems import FermionHamiltonianProblem
+
+
+class MappingMethod(StrEnum):
+    """
+    Mapping methods from fermionic operators to qubits operators.
+    """
+
+    JORDAN_WIGNER = "jw"
+    BRAVYI_KITAEV = "bk"
+
+
+class FermionToQubitMapper:
+    """
+    Mapper between fermionic operators to qubits operators, using one of the supported
+    mapping methods (see `MappingMethod`).
+
+    Attributes:
+        method (MappingMethod): The mapping method.
+    """
+
+    def __init__(
+        self,
+        method: MappingMethod = MappingMethod.JORDAN_WIGNER,
+    ) -> None:
+        """
+        Initializes a `FermionToQubitMapper` object using the specified method.
+
+        Args:
+            method (MappingMethod): The mapping method.
+        """
+        self.method = method
+
+        if self.method is MappingMethod.JORDAN_WIGNER:
+            self._mapper = jordan_wigner
+        elif self.method is MappingMethod.BRAVYI_KITAEV:
+            self._mapper = bravyi_kitaev
+        else:
+            _raise_invalid_method(method)
+
+    def map(
+        self, fermion_op: FermionOperator, *args: Any, **kwargs: Any
+    ) -> QubitOperator:
+        """
+        Maps the given fermionic operator to a qubits operator using the mapper's
+        configuration.
+
+        Args:
+            fermion_op (FermionOperator): A fermionic operator.
+            *args: Extra parameters which are ignored, may be used in subclasses.
+            **kwargs: Extra parameters which are ignored, may be used in subclasses.
+
+        Returns:
+            The mapped qubits operator.
+        """
+        return self._mapper(fermion_op)
+
+    def get_num_qubits(self, problem: FermionHamiltonianProblem) -> int:
+        """
+        Gets the number of qubits after mapping the given problem into qubits space.
+
+        Args:
+            problem (FermionHamiltonianProblem): The fermion problem.
+
+        Returns:
+            The number of qubits.
+        """
+        return 2 * problem.n_orbitals
+
+
+# statically validate that we have exhaustively searched all methods by defining its type
+# as `NoReturn`, while dynamically raising an indicative error
+def _raise_invalid_method(method: NoReturn) -> NoReturn:
+    raise ClassiqValueError(f"Invalid mapping method: {method}")

classiq/applications/chemistry/op_utils.py

@@ -0,0 +1,79 @@
+from typing import Optional, cast
+
+import numpy as np
+from openfermion.ops.operators.qubit_operator import QubitOperator
+from openfermion.utils.operator_utils import count_qubits
+
+from classiq.interface.exceptions import ClassiqValueError
+
+from classiq.qmod.builtins.enums import Pauli
+from classiq.qmod.builtins.structs import IndexedPauli, SparsePauliOp, SparsePauliTerm
+
+
+def _get_n_qubits(qubit_op: QubitOperator, n_qubits: Optional[int]) -> int:
+    min_n_qubits = cast(int, count_qubits(qubit_op))
+    if n_qubits is None:
+        return min_n_qubits
+
+    if n_qubits < min_n_qubits:
+        raise ClassiqValueError(
+            f"The operator acts on {min_n_qubits} and cannot be cast to a PauliTerm on {n_qubits}"
+        )
+    return n_qubits
+
+
+def qubit_op_to_pauli_terms(
+    qubit_op: QubitOperator, n_qubits: Optional[int] = None
+) -> SparsePauliOp:
+    n_qubits = _get_n_qubits(qubit_op, n_qubits)
+    return SparsePauliOp(
+        terms=[  # type:ignore[arg-type]
+            SparsePauliTerm(
+                paulis=[  # type:ignore[arg-type]
+                    IndexedPauli(
+                        pauli=getattr(Pauli, pauli),
+                        index=n_qubits - qubit - 1,
+                    )
+                    for qubit, pauli in term[::-1]
+                ],
+                coefficient=coeff,
+            )
+            for term, coeff in qubit_op.terms.items()
+        ],
+        num_qubits=n_qubits,  # type:ignore[arg-type]
+    )
+
+
+_PAULIS_TO_XZ = {"I": (0, 0), "X": (1, 0), "Z": (0, 1), "Y": (1, 1)}
+_XZ_TO_PAULIS = {(0, 0): "I", (1, 0): "X", (0, 1): "Z", (1, 1): "Y"}
+
+
+def qubit_op_to_xz_matrix(
+    qubit_op: QubitOperator, n_qubits: Optional[int] = None
+) -> np.ndarray:
+    n_qubits = _get_n_qubits(qubit_op, n_qubits)
+    xz_mat = np.zeros((len(qubit_op.terms), 2 * n_qubits), dtype=np.int8)
+
+    for row, (term, _) in zip(xz_mat, qubit_op.terms.items()):
+        for qubit, pauli in term:
+            row[qubit], row[n_qubits + qubit] = _PAULIS_TO_XZ[pauli]
+
+    return xz_mat
+
+
+def xz_matrix_to_qubit_op(xz_mat: np.ndarray) -> QubitOperator:
+    if len(xz_mat.shape) == 1:
+        xz_mat = np.array([xz_mat])
+
+    qubit_op = QubitOperator()
+    n_qubits = xz_mat.shape[1] // 2
+    for row in xz_mat:
+        op = tuple(
+            (qubit, pauli)
+            for qubit in range(n_qubits)
+            if (pauli := _XZ_TO_PAULIS[(row[qubit], row[n_qubits + qubit])]) != "I"
+        )
+        if op:
+            qubit_op += QubitOperator(op, 1)
+
+    return qubit_op

classiq/applications/chemistry/problems.py

@@ -0,0 +1,195 @@
+from collections.abc import Sequence
+from typing import Optional, cast
+
+from openfermion import MolecularData
+from openfermion.ops import FermionOperator
+from openfermion.transforms import (
+    get_fermion_operator,
+    reorder,
+)
+from openfermion.utils import count_qubits
+
+from classiq.interface.exceptions import ClassiqValueError
+
+
+class FermionHamiltonianProblem:
+    """
+    Defines an electronic-structure problem using a Fermionic operator and electron count.
+    Can also be constructed from a `MolecularData` object using the `from_molecule`
+    method.
+
+    Attributes:
+        fermion_hamiltonian (FermionOperator): The fermionic hamiltonian of the problem.
+            Assumed to be in the block-spin labeling.
+        n_orbitals (int): Number of spatial orbitlas.
+        n_alpha (int): Number of alpha particles.
+        n_beta (int): Number of beta particles.
+        n_particles (tuple[int, int]): Number of alpha and beta particles.
+    """
+
+    def __init__(
+        self,
+        fermion_hamiltonian: FermionOperator,
+        n_particles: tuple[int, int],
+        n_orbitals: Optional[int] = None,
+    ) -> None:
+        """
+        Initializes a `FermionHamiltonianProblem` from the fermion hamiltonian, number
+        of alpha and beta particles, and optionally the number of orbitals.
+
+        Args:
+            fermion_hamiltonian (FermionHamiltonianProblem): The fermionic hamiltonian
+                of the problem. Assumed to be in the block-spin labeling.
+            n_particles (tuple[int, int]): Number of alpha and beta particles.
+            n_orbitals (int, optional): Number of spatial orbitals. If not specified,
+                the number is inferred from `fermion_hamiltonian`.
+        """
+        self.fermion_hamiltonian = fermion_hamiltonian
+        self.n_particles = n_particles
+        self.n_alpha, self.n_beta = n_particles
+
+        qubits = cast(int, count_qubits(fermion_hamiltonian))
+        min_n_orbitals = (qubits + 1) // 2
+        if n_orbitals is None:
+            self.n_orbitals = min_n_orbitals
+        else:
+            if n_orbitals < min_n_orbitals:
+                raise ClassiqValueError(
+                    f"n_orbitals ({n_orbitals}) is less than the minimum number of orbitals {min_n_orbitals} inferred from the hamiltonian"
+                )
+            self.n_orbitals = n_orbitals
+
+        if self.n_alpha > self.n_orbitals:
+            raise ClassiqValueError(
+                f"n_alpha ({self.n_alpha}) exceeds available orbitals ({self.n_orbitals})"
+            )
+        if self.n_beta > self.n_orbitals:
+            raise ClassiqValueError(
+                f"n_beta ({self.n_beta}) exceeds available orbitals ({self.n_orbitals})"
+            )
+
+    @property
+    def occupied_alpha(self) -> list[int]:
+        """
+        Indices list of occupied alpha particles.
+        """
+        return list(range(self.n_alpha))
+
+    @property
+    def virtual_alpha(self) -> list[int]:
+        """
+        Indices list of virtual alpha particles.
+        """
+        return list(range(self.n_alpha, self.n_orbitals))
+
+    @property
+    def occupied_beta(self) -> list[int]:
+        """
+        Indices list of occupied beta particles.
+        """
+        return list(range(self.n_orbitals, self.n_orbitals + self.n_beta))
+
+    @property
+    def virtual_beta(self) -> list[int]:
+        """
+        Indices list of virtual beta particles.
+        """
+        return list(range(self.n_orbitals + self.n_beta, 2 * self.n_orbitals))
+
+    @property
+    def occupied(self) -> list[int]:
+        """
+        Indices list of occupied alpha and beta particles.
+        """
+        return self.occupied_alpha + self.occupied_beta
+
+    @property
+    def virtual(self) -> list[int]:
+        """
+        Indices list of virtual alpha and beta particles.
+        """
+        return self.virtual_alpha + self.virtual_beta
+
+    @classmethod
+    def from_molecule(
+        cls,
+        molecule: MolecularData,
+        first_active_index: int = 0,
+        remove_orbitlas: Optional[Sequence[int]] = None,
+        op_compression_tol: float = 1e-13,
+    ) -> "FermionHamiltonianProblem":
+        """
+        Constructs a `FermionHamiltonianProblem` from a molecule data.
+
+        Args:
+            molecule (MolecularData): The molecule data.
+            first_active_index (int): The first active index, indicates all prior
+                indices are freezed.
+            remove_orbitlas (Sequence[int], optional): Active indices to be removed.
+            op_compression_tol (float): Tolerance for trimming the fermion operator.
+
+        Returns:
+            The fermion hamiltonian problem.
+        """
+        if molecule.n_orbitals is None:
+            raise ClassiqValueError(
+                "The molecular data is not populated. Hint: call `run_pyscf` with the molecule."
+            )
+
+        if first_active_index >= molecule.n_orbitals:
+            raise ClassiqValueError(
+                f"Invalid active space: got first_active_index={first_active_index} "
+                f", while the number of orbitals is {molecule.n_orbitals}."
+                f" Active space must be non-empty."
+            )
+
+        freezed_indices = list(range(first_active_index))
+        active_indices = list(range(first_active_index, molecule.n_orbitals))
+        if remove_orbitlas:
+            active_indices = list(set(active_indices) - set(remove_orbitlas))
+
+        molecular_hamiltonian = molecule.get_molecular_hamiltonian(
+            occupied_indices=freezed_indices,
+            active_indices=active_indices,
+        )
+
+        n_freezed_orbitals = len(freezed_indices)
+        n_orbitals = len(active_indices)
+        n_alpha, n_beta = (
+            molecule.get_n_alpha_electrons(),
+            molecule.get_n_beta_electrons(),
+        )
+        n_particles = (n_alpha - n_freezed_orbitals, n_beta - n_freezed_orbitals)
+
+        if n_orbitals <= 0 or min(n_particles) <= 0:
+            raise ClassiqValueError(
+                f"Degenerate active space: got {n_orbitals} spatial orbitals "
+                f"and {n_particles} electrons. "
+                f"This can happen if too many orbitals were frozen."
+                f"Before freezing number of particle was ({n_alpha, n_beta})."
+                f"Consider adjusting `first_active_index` or `remove_orbitlas` "
+                f"to ensure the active space is non-empty."
+            )
+
+        fermion_op = get_fermion_operator(molecular_hamiltonian)
+        # openfermion returns the operation in alternating-spin labeling, reorder to
+        # keep the convention of block-spin labeling.
+        fermion_op = _reorder_op_alternating_to_block(fermion_op)
+        fermion_op.compress(abs_tol=op_compression_tol)
+
+        return cls(
+            fermion_hamiltonian=fermion_op,
+            n_particles=n_particles,
+            n_orbitals=n_orbitals,
+        )
+
+
+def _reorder_op_alternating_to_block(op: FermionOperator) -> FermionOperator:
+    def _alternating_to_block(idx: int, num_modes: int) -> int:
+        """Map an alternating-spin mode index to block-spin order."""
+        n = num_modes // 2
+        spin = idx % 2  # 0 = alpha, 1 = beta
+        orbital = idx // 2
+        return orbital + spin * n
+
+    return reorder(op, _alternating_to_block)

classiq/applications/chemistry/ucc.py

@@ -0,0 +1,109 @@
+from collections.abc import Sequence
+from itertools import chain, combinations, product
+from math import factorial
+from typing import Union
+
+from openfermion.ops.operators.fermion_operator import FermionOperator
+from openfermion.ops.operators.qubit_operator import QubitOperator
+
+from classiq.applications.chemistry.mapping import FermionToQubitMapper
+from classiq.applications.chemistry.op_utils import qubit_op_to_pauli_terms
+from classiq.applications.chemistry.problems import FermionHamiltonianProblem
+from classiq.qmod.builtins.structs import (
+    SparsePauliOp,
+)
+
+
+def get_ucc_hamiltonians(
+    problem: FermionHamiltonianProblem,
+    mapper: FermionToQubitMapper,
+    excitations: Union[int, Sequence[int]],
+) -> list[SparsePauliOp]:
+    """
+    Computes the UCC hamiltonians of the given problem in the desired excitations,
+    using the given mapper.
+
+    Args:
+        problem (FermionHamiltonianProblem): The fermion problem.
+        mapper (FermionToQubitMapper): The mapper from fermion to qubits operators.
+        excitations (int, Sequence[int]): A single desired excitation or an excitations
+            list.
+
+    Returns:
+        The UCC hamiltonians.
+    """
+    if isinstance(excitations, int):
+        excitations = [excitations]
+
+    f_ops = (
+        _hamiltonian_from_excitations(
+            source, target, 1 / factorial(num_excitations) * 1j
+        )
+        for num_excitations in excitations
+        for source, target in get_excitations(problem, num_excitations)
+    )
+
+    n_qubits = mapper.get_num_qubits(problem)
+    return [
+        qubit_op_to_pauli_terms(q_op, n_qubits)
+        for f_op in f_ops
+        if (q_op := mapper.map(f_op))
+        not in (
+            QubitOperator(),
+            QubitOperator((), q_op.constant),
+        )
+    ]
+
+
+def _hamiltonian_from_excitations(
+    source: tuple[int, ...], target: tuple[int, ...], coeff: complex
+) -> FermionOperator:
+    op_string = " ".join(
+        chain(
+            (f"{i}^" for i in source),
+            (f"{i}" for i in target),
+        )
+    )
+    dagger_op_string = " ".join(
+        chain(
+            (f"{i}^" for i in reversed(target)),
+            (f"{i}" for i in reversed(source)),
+        )
+    )
+    return FermionOperator(op_string, coeff) - FermionOperator(dagger_op_string, coeff)
+
+
+def get_excitations(
+    problem: FermionHamiltonianProblem, num_excitations: int
+) -> set[tuple[tuple[int, ...], tuple[int, ...]]]:
+    """
+    Gets all the possible excitations of the given problem according to the
+    given number of excitations, preserving the particles spin.
+
+    Args:
+        problem (FermionHamiltonianProblem): The fermion problem.
+        num_excitations (int): Number of excitations.
+
+    Returns:
+        A set of all possible excitations, specified as a pair of source and target indices.
+    """
+    if num_excitations <= 0:
+        return set()
+
+    possible_excitations = chain(
+        product(problem.occupied_alpha, problem.virtual_alpha),
+        product(problem.occupied_beta, problem.virtual_beta),
+    )
+    single_excitations = combinations(possible_excitations, r=num_excitations)
+
+    excitations: set[tuple[tuple[int, ...], tuple[int, ...]]] = set()
+    for excitation in single_excitations:
+        # the zip converts a sequence of single excitations (e.g. [(0, 1), (2, 3), (4, 5)])
+        # to the sequence of combined excitations (e.g. [(0, 2, 4), (1, 3, 5)])
+        source, target = (set(gr) for gr in zip(*excitation))
+
+        # filter out excitations with repetitions in source/target
+        if len(source) == num_excitations and len(target) == num_excitations:
+            excitations.add((tuple(source), tuple(target)))
+
+    return excitations