qoro-divi 0.2.0b1__py3-none-any.whl → 0.6.0__py3-none-any.whl

divi/qprog/__init__.py

@@ -1,13 +1,32 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
-# isort: skip_file
 from .quantum_program import QuantumProgram
+from .variational_quantum_algorithm import VariationalQuantumAlgorithm, SolutionEntry
 from .batch import ProgramBatch
-from ._qaoa import QAOA, GraphProblem
-from ._vqe import VQE, VQEAnsatz
-from ._mlae import MLAE
-from ._graph_partitioning import GraphPartitioningQAOA, PartitioningConfig
-from ._vqe_sweep import VQEHyperparameterSweep
-from .optimizers import Optimizer
+from .algorithms import (
+    QAOA,
+    GraphProblem,
+    VQE,
+    PCE,
+    CustomVQA,
+    Ansatz,
+    UCCSDAnsatz,
+    QAOAAnsatz,
+    HardwareEfficientAnsatz,
+    HartreeFockAnsatz,
+    GenericLayerAnsatz,
+)
+from .workflows import (
+    GraphPartitioningQAOA,
+    PartitioningConfig,
+    QUBOPartitioningQAOA,
+    VQEHyperparameterSweep,
+    MoleculeTransformer,
+)
+from .optimizers import ScipyOptimizer, ScipyMethod, MonteCarloOptimizer
+from ._hamiltonians import (
+    convert_qubo_matrix_to_pennylane_ising,
+    convert_hamiltonian_to_pauli_string,
+)

divi/qprog/_expectation.py

@@ -0,0 +1,181 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from functools import lru_cache
+
+import numpy as np
+import numpy.typing as npt
+import pennylane as qml
+
+
+def _get_structural_key(obs: qml.operation.Operation) -> tuple[str, ...]:
+    """Generates a hashable, wire-independent key from an observable's structure.
+
+    This function is used to create a canonical representation of an observable
+    based on its constituent Pauli operators, ignoring the wires they act on.
+    This key is ideal for caching computed eigenvalues, as observables with the
+    same structure (e.g., PauliX(0) @ PauliZ(1) and PauliX(2) @ PauliZ(3))
+    share the same eigenvalues. It maps PauliX and PauliY to PauliZ because
+    they are all isospectral (have eigenvalues [1, -1]).
+
+    Args:
+        obs (qml.operation.Operation): A PennyLane observable (e.g., qml.PauliZ(0), qml.PauliX(0) @ qml.PauliY(1)).
+
+    Returns:
+        tuple[str, ...]: A tuple of strings representing the structure of the observable,
+            e.g., ('PauliZ',) or ('PauliZ', 'PauliZ').
+    """
+
+    # Pennylane returns the same eigenvalues for PauliX and PauliY
+    # since it handles diagonalizing gates internally anyway
+    name_map = {
+        "PauliY": "PauliZ",
+        "PauliX": "PauliZ",
+        "PauliZ": "PauliZ",
+        "Identity": "Identity",
+    }
+
+    if isinstance(obs, qml.ops.Prod):
+        # Recursively build a tuple of operator names
+        return tuple(name_map[o.name] for o in obs.operands)
+
+    # For single operators, return a single-element tuple
+    return (name_map[obs.name],)
+
+
+@lru_cache(maxsize=512)
+def _get_eigvals_from_key(key: tuple[str, ...]) -> npt.NDArray[np.int8]:
+    """Computes and caches eigenvalues based on a structural key.
+
+    This function takes a key generated by `_get_structural_key` and computes
+    the eigenvalues of the corresponding tensor product of operators. The results
+    are memoized using @lru_cache to avoid redundant calculations.
+
+    Args:
+        key (tuple[str, ...]): A tuple of strings representing the observable's structure.
+
+    Returns:
+        np.ndarray: A NumPy array containing the eigenvalues of the observable.
+    """
+
+    # Define a mapping from name to the base eigenvalue array
+    eigvals_map = {
+        "PauliZ": np.array([1, -1], dtype=np.int8),
+        "Identity": np.array([1, 1], dtype=np.int8),
+    }
+
+    # Start with the eigenvalues of the first operator in the key
+    final_eigvals = eigvals_map[key[0]]
+
+    # Iteratively compute the kronecker product for the rest
+    for op_name in key[1:]:
+        final_eigvals = np.kron(final_eigvals, eigvals_map[op_name])
+
+    return final_eigvals
+
+
+def _batched_expectation(
+    shots_dicts: list[dict[str, int]],
+    observables: list[qml.operation.Operation],
+    wire_order: tuple[int, ...],
+) -> npt.NDArray[np.float64]:
+    """Efficiently calculates expectation values for multiple observables across multiple shot histograms.
+
+    This function is optimized to compute expectation values in a fully vectorized
+    manner, minimizing Python loops. It operates in four main steps:
+    1. Aggregates all unique bitstrings measured across all histograms.
+    2. Builds a "reduced" eigenvalue matrix corresponding only to the unique states.
+    3. Builds a "reduced" probability matrix from the shot counts for each histogram.
+    4. Computes all expectation values with a single matrix multiplication.
+
+    Args:
+        shots_dicts (list[dict[str, int]]): A list of shot dictionaries (histograms),
+            where each dictionary maps a measured bitstring to its count.
+        observables (list[qml.operation.Operation]): A list of PennyLane observables
+            for which to calculate expectation values.
+        wire_order (tuple[int, ...]): A tuple defining the order of wires, which maps
+            the bitstring to the qubits. Note: This is typically the reverse of the
+            qubit indices (e.g., (2, 1, 0) for a 3-qubit system).
+
+    Returns:
+        npt.NDArray[np.float64]: A 2D NumPy array of shape (n_observables, n_shots) where
+            result[i, j] is the expectation value of observables[i] for the
+            histogram in shots_dicts[j].
+    """
+
+    n_histograms = len(shots_dicts)
+    n_total_wires = len(wire_order)
+    n_observables = len(observables)
+
+    # --- 1. Aggregate all unique measured states across all shots ---
+    all_measured_bitstrings = set()
+    for sd in shots_dicts:
+        all_measured_bitstrings.update(sd.keys())
+
+    unique_bitstrings = sorted(list(all_measured_bitstrings))
+    n_unique_states = len(unique_bitstrings)
+
+    bitstring_to_idx_map = {bs: i for i, bs in enumerate(unique_bitstrings)}
+
+    # --- 2. Build REDUCED Eigenvalue Matrix: (n_observables, n_unique_states) ---
+    # For systems with <=64 qubits, use fast integer conversion and bitwise operations.
+    # For larger systems, use character array to avoid integer overflow.
+    if n_total_wires <= 64:
+        # Fast path: convert to uint64 and use vectorized bitwise operations
+        unique_states_int = np.array(
+            [int(bs, 2) for bs in unique_bitstrings], dtype=np.uint64
+        )
+        use_integer_representation = True
+    else:
+        # Safe path: convert to character array for large qubit counts
+        bitstring_chars = np.array([list(bs) for bs in unique_bitstrings], dtype="U1")
+        use_integer_representation = False
+
+    reduced_eigvals_matrix = np.zeros((n_observables, n_unique_states))
+    wire_map = {w: i for i, w in enumerate(wire_order)}
+
+    powers_cache = {}
+
+    for obs_idx, observable in enumerate(observables):
+        obs_wires = observable.wires
+        n_obs_wires = len(obs_wires)
+
+        if n_obs_wires in powers_cache:
+            powers = powers_cache[n_obs_wires]
+        else:
+            powers = 2 ** np.arange(n_obs_wires - 1, -1, -1, dtype=np.intp)
+            powers_cache[n_obs_wires] = powers
+
+        obs_wire_indices = np.array([wire_map[w] for w in obs_wires], dtype=np.uint32)
+        eigvals = _get_eigvals_from_key(_get_structural_key(observable))
+
+        # Vectorized mapping, but on the *reduced* set of states
+        shifts = n_total_wires - 1 - obs_wire_indices
+
+        if use_integer_representation:
+            # Fast path: vectorized bitwise operations on integers
+            bits = ((unique_states_int[:, np.newaxis] >> shifts) & 1).astype(np.intp)
+        else:
+            # Safe path: extract bits from character array (vectorized)
+            bits = bitstring_chars[:, shifts].astype(np.intp)
+
+        obs_state_indices = np.dot(bits, powers)
+
+        reduced_eigvals_matrix[obs_idx, :] = eigvals[obs_state_indices]
+
+    # --- 3. Build REDUCED Probability Matrix: (n_shots, n_unique_states) ---
+    reduced_prob_matrix = np.zeros((n_histograms, n_unique_states), dtype=np.float32)
+    for i, shots_dict in enumerate(shots_dicts):
+        total = sum(shots_dict.values())
+
+        for bitstring, count in shots_dict.items():
+            col_idx = bitstring_to_idx_map[bitstring]
+            reduced_prob_matrix[i, col_idx] = count / total
+
+    # --- 4. Compute Final Expectation Values ---
+    # (n_shots, n_unique_states) @ (n_unique_states, n_observables)
+    result = reduced_prob_matrix @ reduced_eigvals_matrix.T
+
+    # Transpose to (n_observables, n_shots) as expected by the calling code
+    return result.T

divi/qprog/_hamiltonians.py

@@ -0,0 +1,281 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from functools import reduce
+from warnings import warn
+
+import numpy as np
+import numpy.typing as npt
+import pennylane as qml
+import scipy.sparse as sps
+
+
+def _clean_hamiltonian(
+    hamiltonian: qml.operation.Operator,
+) -> tuple[qml.operation.Operator, float]:
+    """Separate constant and non-constant terms in a Hamiltonian.
+
+    This function processes a PennyLane Hamiltonian to separate out any terms
+    that are constant (i.e., proportional to the identity operator). The sum
+    of these constant terms is returned, along with a new Hamiltonian containing
+    only the non-constant terms.
+
+    Args:
+        hamiltonian: The Hamiltonian operator to process.
+
+    Returns:
+        tuple[qml.operation.Operator, float]: A tuple containing:
+            - The Hamiltonian without the constant (identity) component.
+            - The summed value of all constant terms.
+    """
+    if hamiltonian is None:
+        return qml.Hamiltonian([], []), 0.0
+
+    terms = (
+        hamiltonian.operands if isinstance(hamiltonian, qml.ops.Sum) else [hamiltonian]
+    )
+
+    loss_constant = 0.0
+    non_constant_terms = []
+
+    for term in terms:
+        coeff = 1.0
+        base_op = term
+        if isinstance(term, qml.ops.SProd):
+            coeff = term.scalar
+            base_op = term.base
+
+        # Check for Identity term
+        is_constant = False
+        if isinstance(base_op, qml.Identity):
+            is_constant = True
+        elif isinstance(base_op, qml.ops.Prod) and all(
+            isinstance(op, qml.Identity) for op in base_op.operands
+        ):
+            is_constant = True
+
+        if is_constant:
+            loss_constant += coeff
+        else:
+            non_constant_terms.append(term)
+
+    if not non_constant_terms:
+        return qml.Hamiltonian([], []), float(loss_constant)
+
+    # Reconstruct the Hamiltonian from non-constant terms
+    if len(non_constant_terms) > 1:
+        new_hamiltonian = qml.sum(*non_constant_terms)
+    else:
+        new_hamiltonian = non_constant_terms[0]
+
+    return new_hamiltonian.simplify(), float(loss_constant)
+
+
+def convert_hamiltonian_to_pauli_string(
+    hamiltonian: qml.operation.Operator, n_qubits: int
+) -> str:
+    """
+    Convert a PennyLane Operator to a semicolon-separated string of Pauli operators.
+
+    Each term in the Hamiltonian is represented as a string of Pauli letters ('I', 'X', 'Y', 'Z'),
+    one per qubit. Multiple terms are separated by semicolons.
+
+    Args:
+        hamiltonian (qml.operation.Operator): The PennyLane Operator (e.g., Hamiltonian, PauliZ) to convert.
+        n_qubits (int): Number of qubits to represent in the string.
+
+    Returns:
+        str: The Hamiltonian as a semicolon-separated string of Pauli operators.
+
+    Raises:
+        ValueError: If an unknown Pauli operator is encountered or wire index is out of range.
+    """
+    pauli_letters = {"PauliX": "X", "PauliY": "Y", "PauliZ": "Z"}
+    identity_row = np.full(n_qubits, "I", dtype="<U1")
+
+    # Handle both single operators and sums of operators (like Hamiltonians)
+    terms_to_process = (
+        hamiltonian.operands if isinstance(hamiltonian, qml.ops.Sum) else [hamiltonian]
+    )
+
+    terms = []
+    for term in terms_to_process:
+        op = term
+        while isinstance(op, qml.ops.SProd):
+            op = op.base
+        ops = op.operands if isinstance(op, qml.ops.Prod) else [op]
+
+        paulis = identity_row.copy()
+        for p in ops:
+            if isinstance(p, qml.Identity):
+                continue
+            # Better fallback logic with validation
+            if p.name in pauli_letters:
+                pauli = pauli_letters[p.name]
+            else:
+                raise ValueError(
+                    f"Unknown Pauli operator: {p.name}. "
+                    "Expected 'PauliX', 'PauliY', or 'PauliZ'."
+                )
+
+            # Bounds checking for wire indices
+            if not p.wires:
+                raise ValueError(f"Pauli operator {p.name} has no wires")
+
+            wire = int(p.wires[0])
+            if wire < 0 or wire >= n_qubits:
+                raise ValueError(
+                    f"Wire index {wire} out of range for {n_qubits} qubits. "
+                    f"Valid range: [0, {n_qubits - 1}]"
+                )
+
+            paulis[wire] = pauli
+        terms.append("".join(paulis))
+
+    return ";".join(terms)
+
+
+def _is_sanitized(
+    qubo_matrix: npt.NDArray[np.float64] | sps.spmatrix,
+) -> npt.NDArray[np.float64] | sps.spmatrix:
+    """
+    Check if a QUBO matrix is either symmetric or upper triangular.
+
+    This function validates that the input QUBO matrix is in a proper format
+    for conversion to an Ising Hamiltonian. The matrix should be either
+    symmetric (equal to its transpose) or upper triangular.
+
+    Args:
+        qubo_matrix (npt.NDArray[np.float64] | sps.spmatrix): The QUBO matrix to validate.
+            Can be a dense NumPy array or a sparse SciPy matrix.
+
+    Returns:
+        bool: True if the matrix is symmetric or upper triangular, False otherwise.
+    """
+    is_sparse = sps.issparse(qubo_matrix)
+
+    return (
+        (
+            ((qubo_matrix != qubo_matrix.T).nnz == 0)
+            or ((qubo_matrix != sps.triu(qubo_matrix)).nnz == 0)
+        )
+        if is_sparse
+        else (
+            np.allclose(qubo_matrix, qubo_matrix.T)
+            or np.allclose(qubo_matrix, np.triu(qubo_matrix))
+        )
+    )
+
+
+def convert_qubo_matrix_to_pennylane_ising(
+    qubo_matrix: npt.NDArray[np.float64] | sps.spmatrix,
+) -> tuple[qml.operation.Operator, float]:
+    """
+    Convert a QUBO matrix to an Ising Hamiltonian in PennyLane format.
+
+    The conversion follows the mapping from QUBO variables x_i ∈ {0,1} to
+    Ising variables σ_i ∈ {-1,1} via the transformation x_i = (1 - σ_i)/2. This
+    transforms a QUBO minimization problem into an equivalent Ising minimization
+    problem.
+
+    The function handles both dense NumPy arrays and sparse SciPy matrices efficiently.
+    If the input matrix is neither symmetric nor upper triangular, it will be
+    symmetrized automatically with a warning.
+
+    Args:
+        qubo_matrix (npt.NDArray[np.float64] | sps.spmatrix): The QUBO matrix Q where the
+            objective is to minimize x^T Q x. Can be a dense NumPy array or a
+            sparse SciPy matrix (any format). Should be square and either
+            symmetric or upper triangular.
+
+    Returns:
+        tuple[qml.operation.Operator, float]: A tuple containing:
+            - Ising Hamiltonian as a PennyLane operator (sum of Pauli Z terms)
+            - Constant offset term to be added to energy calculations
+
+    Raises:
+        UserWarning: If the QUBO matrix is neither symmetric nor upper triangular.
+
+    Example:
+        >>> import numpy as np
+        >>> qubo = np.array([[1, 2], [0, 3]])
+        >>> hamiltonian, offset = convert_qubo_matrix_to_pennylane_ising(qubo)
+        >>> print(f"Offset: {offset}")
+    """
+
+    if not _is_sanitized(qubo_matrix):
+        warn(
+            "The QUBO matrix is neither symmetric nor upper triangular."
+            " Symmetrizing it for the Ising Hamiltonian creation."
+        )
+        qubo_matrix = (qubo_matrix + qubo_matrix.T) / 2
+
+    is_sparse = sps.issparse(qubo_matrix)
+    backend = sps if is_sparse else np
+
+    symmetrized_qubo = (qubo_matrix + qubo_matrix.T) / 2
+
+    # Gather non-zero indices in the upper triangle of the matrix
+    triu_matrix = backend.triu(
+        symmetrized_qubo,
+        **(
+            {"format": qubo_matrix.format if qubo_matrix.format != "coo" else "csc"}
+            if is_sparse
+            else {}
+        ),
+    )
+
+    if is_sparse:
+        coo_mat = triu_matrix.tocoo()
+        rows, cols, values = coo_mat.row, coo_mat.col, coo_mat.data
+    else:
+        rows, cols = triu_matrix.nonzero()
+        values = triu_matrix[rows, cols]
+
+    n = qubo_matrix.shape[0]
+    linear_terms = np.zeros(n)
+    constant_term = 0.0
+    ising_terms = []
+    ising_weights = []
+
+    for i, j, weight in zip(rows, cols, values):
+        weight = float(weight)
+        i, j = int(i), int(j)
+
+        if i == j:
+            # Diagonal elements
+            linear_terms[i] -= weight / 2
+            constant_term += weight / 2
+        else:
+            # Off-diagonal elements (i < j since we're using triu)
+            ising_terms.append([i, j])
+            ising_weights.append(weight / 4)
+
+            # Update linear terms
+            linear_terms[i] -= weight / 4
+            linear_terms[j] -= weight / 4
+
+            # Update constant term
+            constant_term += weight / 4
+
+    # Add the linear terms (Z operators)
+    for i, curr_lin_term in filter(lambda x: x[1] != 0, enumerate(linear_terms)):
+        ising_terms.append([i])
+        ising_weights.append(float(curr_lin_term))
+
+    # Construct the Ising Hamiltonian as a PennyLane operator
+    pauli_string = qml.Identity(0) * 0
+    for term, weight in zip(ising_terms, ising_weights):
+        if len(term) == 1:
+            # Single-qubit term (Z operator)
+            curr_term = qml.Z(term[0]) * weight
+        else:
+            # Two-qubit term (ZZ interaction)
+            curr_term = (
+                reduce(lambda x, y: x @ y, map(lambda x: qml.Z(x), term)) * weight
+            )
+
+        pauli_string += curr_term
+
+    return pauli_string.simplify(), constant_term

divi/qprog/algorithms/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ._ansatze import (
+    Ansatz,
+    GenericLayerAnsatz,
+    HardwareEfficientAnsatz,
+    HartreeFockAnsatz,
+    QAOAAnsatz,
+    UCCSDAnsatz,
+)
+from ._custom_vqa import CustomVQA
+from ._qaoa import QAOA, GraphProblem
+from ._vqe import VQE
+from ._pce import PCE