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

divi/qprog/algorithms/_ansatze.py

@@ -0,0 +1,368 @@
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from abc import ABC, abstractmethod
+from itertools import tee
+from typing import Literal, Sequence
+from warnings import warn
+
+import pennylane as qml
+
+
+def _require_trainable_params(n_params: int, ansatz_name: str) -> int:
+    if n_params <= 0:
+        raise ValueError(
+            f"{ansatz_name} must define at least one trainable parameter. "
+            "Parameter-free circuits are not supported."
+        )
+    return n_params
+
+
+class Ansatz(ABC):
+    """Abstract base class for all VQE ansätze."""
+
+    @property
+    def name(self) -> str:
+        """Returns the human-readable name of the ansatz."""
+        return self.__class__.__name__
+
+    @staticmethod
+    @abstractmethod
+    def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """Returns the number of parameters required by the ansatz for one layer."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def build(
+        self, params, n_qubits: int, n_layers: int, **kwargs
+    ) -> list[qml.operation.Operator]:
+        """
+        Builds the ansatz circuit and returns a list of operations.
+
+        Args:
+            params: Parameter array for the ansatz.
+            n_qubits (int): Number of qubits in the circuit.
+            n_layers (int): Number of ansatz layers.
+            **kwargs: Additional arguments specific to the ansatz.
+
+        Returns:
+            list[qml.operation.Operator]: List of PennyLane operations representing the ansatz.
+        """
+        raise NotImplementedError
+
+
+# --- Template Ansaetze ---
+
+
+class GenericLayerAnsatz(Ansatz):
+    """
+    A flexible ansatz alternating single-qubit gates with optional entanglers.
+    """
+
+    def __init__(
+        self,
+        gate_sequence: list[qml.operation.Operator],
+        entangler: qml.operation.Operator | None = None,
+        entangling_layout: (
+            Literal["linear", "brick", "circular", "all-to-all"]
+            | Sequence[tuple[int, int]]
+            | None
+        ) = None,
+    ):
+        """
+        Args:
+            gate_sequence (list[Callable]): List of one-qubit gate classes (e.g., qml.RY, qml.Rot).
+            entangler (Callable): Two-qubit entangling gate class (e.g., qml.CNOT, qml.CZ).
+                                  If None, no entanglement is applied.
+            entangling_layout (str): Layout for entangling layer ("linear", "all_to_all", etc.).
+        """
+        if not all(
+            issubclass(g, qml.operation.Operator) and g.num_wires == 1
+            for g in gate_sequence
+        ):
+            raise ValueError(
+                "All elements in gate_sequence must be PennyLane one-qubit gate classes."
+            )
+        self.gate_sequence = gate_sequence
+
+        if entangler not in (None, qml.CNOT, qml.CZ):
+            raise ValueError("Only qml.CNOT and qml.CZ are supported as entanglers.")
+        self.entangler = entangler
+
+        self.entangling_layout = entangling_layout
+        if entangler is None and self.entangling_layout is not None:
+            warn("`entangling_layout` provided but `entangler` is None.")
+        match self.entangling_layout:
+            case None | "linear":
+                self.entangling_layout = "linear"
+
+                self._layout_fn = lambda n_qubits: zip(
+                    range(n_qubits), range(1, n_qubits)
+                )
+            case "brick":
+                self._layout_fn = lambda n_qubits: [
+                    (i, i + 1) for r in range(2) for i in range(r, n_qubits - 1, 2)
+                ]
+            case "circular":
+                self._layout_fn = lambda n_qubits: zip(
+                    range(n_qubits), [(i + 1) % n_qubits for i in range(n_qubits)]
+                )
+            case "all-to-all":
+                self._layout_fn = lambda n_qubits: (
+                    (i, j) for i in range(n_qubits) for j in range(i + 1, n_qubits)
+                )
+            case _:
+                if not all(
+                    isinstance(ent, tuple)
+                    and len(ent) == 2
+                    and isinstance(ent[0], int)
+                    and isinstance(ent[1], int)
+                    for ent in entangling_layout
+                ):
+                    raise ValueError(
+                        "entangling_layout must be 'linear', 'circular', "
+                        "'all_to_all', or a Sequence of tuples of integers."
+                    )
+
+                self._layout_fn = lambda _: entangling_layout
+
+    def n_params_per_layer(self, n_qubits: int, **kwargs) -> int:
+        """Total parameters = sum of gate.num_params per qubit per layer."""
+        per_qubit = sum(getattr(g, "num_params", 1) for g in self.gate_sequence)
+        return _require_trainable_params(per_qubit * n_qubits, self.name)
+
+    def build(
+        self, params, n_qubits: int, n_layers: int, **kwargs
+    ) -> list[qml.operation.Operator]:
+        # calculate how many params each gate needs per qubit
+        gate_param_counts = [getattr(g, "num_params", 1) for g in self.gate_sequence]
+        per_qubit = sum(gate_param_counts)
+
+        # reshape into [layers, qubits, per_qubit]
+        params = params.reshape(n_layers, n_qubits, per_qubit)
+        layout_gen = iter(tee(self._layout_fn(n_qubits), n_layers))
+
+        operations = []
+        wires = list(range(n_qubits))
+
+        for layer_idx in range(n_layers):
+            layer_params = params[layer_idx]
+            # Single-qubit gates
+            for w, qubit_params in zip(wires, layer_params):
+                idx = 0
+                for gate, n_p in zip(self.gate_sequence, gate_param_counts):
+                    theta = qubit_params[idx : idx + n_p]
+                    if n_p == 0:
+                        op = gate(wires=w)
+                    elif n_p == 1:
+                        op = gate(theta[0], wires=w)
+                    else:
+                        op = gate(*theta, wires=w)
+                    operations.append(op)
+                    idx += n_p
+
+            # Entangling gates
+            if self.entangler is not None:
+                for wire_a, wire_b in next(layout_gen):
+                    op = self.entangler(wires=[wire_a, wire_b])
+                    operations.append(op)
+
+        return operations
+
+
+class QAOAAnsatz(Ansatz):
+    """
+    QAOA-style ansatz using PennyLane's QAOAEmbedding.
+
+    Implements a parameterized ansatz based on the Quantum Approximate Optimization
+    Algorithm structure, alternating between problem and mixer Hamiltonians.
+    """
+
+    @staticmethod
+    def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for QAOA ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters needed per layer.
+        """
+        n_params = qml.QAOAEmbedding.shape(n_layers=1, n_wires=n_qubits)[1]
+        return _require_trainable_params(n_params, QAOAAnsatz.__name__)
+
+    def build(
+        self, params, n_qubits: int, n_layers: int, **kwargs
+    ) -> list[qml.operation.Operator]:
+        """
+        Build the QAOA ansatz circuit.
+
+        Args:
+            params: Parameter array to use for the ansatz.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of QAOA layers.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            list[qml.operation.Operator]: List of operations representing the QAOA ansatz.
+        """
+        return qml.QAOAEmbedding.compute_decomposition(
+            features=[],
+            weights=params.reshape(n_layers, -1),
+            wires=range(n_qubits),
+            local_field=qml.RY,
+        )
+
+
+class HardwareEfficientAnsatz(Ansatz):
+    """
+    Hardware-efficient ansatz (not yet implemented).
+
+    This ansatz is designed to be easily implementable on near-term quantum hardware,
+    typically using native gate sets and connectivity patterns.
+
+    Note:
+        This class is a placeholder for future implementation.
+    """
+
+    @staticmethod
+    def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """Not yet implemented."""
+        raise NotImplementedError("HardwareEfficientAnsatz is not yet implemented.")
+
+    def build(
+        self, params, n_qubits: int, n_layers: int, **kwargs
+    ) -> list[qml.operation.Operator]:
+        """Not yet implemented."""
+        raise NotImplementedError("HardwareEfficientAnsatz is not yet implemented.")
+
+
+# --- Chemistry Ansaetze ---
+
+
+class UCCSDAnsatz(Ansatz):
+    """
+    Unitary Coupled Cluster Singles and Doubles (UCCSD) ansatz.
+
+    This ansatz is specifically designed for quantum chemistry calculations,
+    implementing the UCCSD approximation which includes all single and double
+    electron excitations from a reference state.
+    """
+
+    @staticmethod
+    def n_params_per_layer(n_qubits: int, n_electrons: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for UCCSD ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters (number of single + double excitations).
+        """
+        singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
+        s_wires, d_wires = qml.qchem.excitations_to_wires(singles, doubles)
+        n_params = len(s_wires) + len(d_wires)
+        return _require_trainable_params(n_params, UCCSDAnsatz.__name__)
+
+    def build(
+        self, params, n_qubits: int, n_layers: int, **kwargs
+    ) -> list[qml.operation.Operator]:
+        """
+        Build the UCCSD ansatz circuit.
+
+        Args:
+            params: Parameter array for excitation amplitudes.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of UCCSD layers (repeats).
+            **kwargs: Additional arguments:
+                n_electrons (int): Number of electrons in the system (required).
+
+        Returns:
+            list[qml.operation.Operator]: List of operations representing the UCCSD ansatz.
+        """
+        n_electrons = kwargs.pop("n_electrons")
+        singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
+        s_wires, d_wires = qml.qchem.excitations_to_wires(singles, doubles)
+        hf_state = qml.qchem.hf_state(n_electrons, n_qubits)
+
+        return qml.UCCSD.compute_decomposition(
+            params.reshape(n_layers, -1),
+            wires=range(n_qubits),
+            s_wires=s_wires,
+            d_wires=d_wires,
+            init_state=hf_state,
+            n_repeats=n_layers,
+        )
+
+
+class HartreeFockAnsatz(Ansatz):
+    """
+    Hartree-Fock-based ansatz for quantum chemistry.
+
+    This ansatz prepares the Hartree-Fock reference state and applies
+    parameterized single and double excitation gates. It's a simplified
+    alternative to UCCSD, often used as a starting point for VQE calculations.
+    """
+
+    @staticmethod
+    def n_params_per_layer(n_qubits: int, n_electrons: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for Hartree-Fock ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters (number of single + double excitations).
+        """
+        singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
+        n_params = len(singles) + len(doubles)
+        return _require_trainable_params(n_params, HartreeFockAnsatz.__name__)
+
+    def build(
+        self, params, n_qubits: int, n_layers: int, **kwargs
+    ) -> list[qml.operation.Operator]:
+        """
+        Build the Hartree-Fock ansatz circuit.
+
+        Args:
+            params: Parameter array for excitation amplitudes.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of ansatz layers.
+            **kwargs: Additional arguments:
+                n_electrons (int): Number of electrons in the system (required).
+
+        Returns:
+            list[qml.operation.Operator]: List of operations representing the Hartree-Fock ansatz.
+        """
+        n_electrons = kwargs.pop("n_electrons")
+        singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
+        hf_state = qml.qchem.hf_state(n_electrons, n_qubits)
+
+        operations = []
+        for layer_params in params.reshape(n_layers, -1):
+            operations.extend(
+                qml.AllSinglesDoubles.compute_decomposition(
+                    layer_params,
+                    wires=range(n_qubits),
+                    hf_state=hf_state,
+                    singles=singles,
+                    doubles=doubles,
+                )
+            )
+
+        # Reset the BasisState operations after the first layer
+        # for behaviour similar to UCCSD ansatz
+        for op in operations[len(operations) // 2 :]:
+            if hasattr(op, "_hyperparameters") and "hf_state" in op._hyperparameters:
+                op._hyperparameters["hf_state"] = 0
+
+        return operations

divi/qprog/algorithms/_custom_vqa.py

@@ -0,0 +1,263 @@
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+from warnings import warn
+
+import numpy as np
+import pennylane as qml
+import sympy as sp
+from qiskit import QuantumCircuit
+
+from divi.circuits import CircuitBundle, MetaCircuit
+from divi.qprog._hamiltonians import _clean_hamiltonian
+from divi.qprog.variational_quantum_algorithm import VariationalQuantumAlgorithm
+
+
+class CustomVQA(VariationalQuantumAlgorithm):
+    """Custom variational algorithm for a parameterized QuantumScript.
+
+    This implementation wraps a PennyLane QuantumScript (or converts a Qiskit
+    QuantumCircuit into one) and optimizes its trainable parameters to minimize
+    a single expectation-value measurement. Qiskit measurements are converted
+    into a PauliZ expectation on the measured wires. Parameters are bound to sympy
+    symbols to enable QASM substitution and reuse of MetaCircuit templates
+    during optimization.
+
+    Attributes:
+        qscript (qml.tape.QuantumScript): The parameterized QuantumScript.
+        param_shape (tuple[int, ...]): Shape of a single parameter set.
+        n_qubits (int): Number of qubits in the script.
+        n_layers (int): Layer count (fixed to 1 for this wrapper).
+        cost_hamiltonian (qml.operation.Operator): Observable being minimized.
+        loss_constant (float): Constant term extracted from the observable.
+        optimizer (Optimizer): Classical optimizer for parameter updates.
+        max_iterations (int): Maximum number of optimization iterations.
+        current_iteration (int): Current optimization iteration.
+    """
+
+    def __init__(
+        self,
+        qscript: qml.tape.QuantumScript | QuantumCircuit,
+        *,
+        param_shape: tuple[int, ...] | int | None = None,
+        max_iterations: int = 10,
+        **kwargs,
+    ) -> None:
+        """Initialize a CustomVQA instance.
+
+        Args:
+            qscript (qml.tape.QuantumScript | QuantumCircuit): A parameterized QuantumScript with a
+                single expectation-value measurement, or a Qiskit QuantumCircuit with
+                computational basis measurements.
+            param_shape (tuple[int, ...] | int | None): Shape of a single parameter
+                set. If None, uses a flat shape inferred from trainable parameters.
+            max_iterations (int): Maximum number of optimization iterations.
+            **kwargs: Additional keyword arguments passed to the parent class, including
+                backend and optimizer.
+
+        Raises:
+            TypeError: If qscript is not a supported PennyLane QuantumScript or Qiskit QuantumCircuit.
+            ValueError: If the script has an invalid measurement or no trainable parameters.
+        """
+        super().__init__(**kwargs)
+
+        self._qiskit_param_names = (
+            [param.name for param in qscript.parameters]
+            if isinstance(qscript, QuantumCircuit)
+            else None
+        )
+        self.qscript = self._coerce_to_quantum_script(qscript)
+
+        if len(self.qscript.measurements) != 1:
+            raise ValueError(
+                "QuantumScript must contain exactly one measurement for optimization."
+            )
+
+        measurement = self.qscript.measurements[0]
+        if not hasattr(measurement, "obs") or measurement.obs is None:
+            raise ValueError(
+                "QuantumScript must contain a single expectation-value measurement."
+            )
+
+        self._cost_hamiltonian, self.loss_constant = _clean_hamiltonian(measurement.obs)
+        if (
+            isinstance(self._cost_hamiltonian, qml.Hamiltonian)
+            and not self._cost_hamiltonian.operands
+        ):
+            raise ValueError("Hamiltonian contains only constant terms.")
+
+        self.n_qubits = self.qscript.num_wires
+        self.n_layers = 1
+        self.max_iterations = max_iterations
+        self.current_iteration = 0
+
+        trainable_param_indices = (
+            list(self.qscript.trainable_params)
+            if self.qscript.trainable_params
+            else list(range(len(self.qscript.get_parameters())))
+        )
+        if not trainable_param_indices:
+            raise ValueError("QuantumScript does not contain any trainable parameters.")
+
+        self._param_shape = self._resolve_param_shape(
+            param_shape, len(trainable_param_indices)
+        )
+        self._n_params = int(np.prod(self._param_shape))
+
+        self._trainable_param_indices = trainable_param_indices
+        self._param_symbols = (
+            np.array(
+                [sp.Symbol(name) for name in self._qiskit_param_names], dtype=object
+            ).reshape(self._param_shape)
+            if self._qiskit_param_names is not None
+            else sp.symarray("p", self._param_shape)
+        )
+
+        flat_symbols = self._param_symbols.flatten().tolist()
+        self._qscript = self.qscript.bind_new_parameters(
+            flat_symbols, self._trainable_param_indices
+        )
+
+    @property
+    def cost_hamiltonian(self) -> qml.operation.Operator:
+        """The cost Hamiltonian for the QuantumScript optimization."""
+        return self._cost_hamiltonian
+
+    @property
+    def param_shape(self) -> tuple[int, ...]:
+        """Shape of a single parameter set."""
+        return self._param_shape
+
+    def _resolve_param_shape(
+        self, param_shape: tuple[int, ...] | int | None, n_params: int
+    ) -> tuple[int, ...]:
+        """Validate and normalize the parameter shape.
+
+        Args:
+            param_shape (tuple[int, ...] | int | None): User-provided parameter shape.
+            n_params (int): Number of trainable parameters in the script.
+
+        Returns:
+            tuple[int, ...]: Normalized parameter shape.
+
+        Raises:
+            ValueError: If the shape is invalid or does not match n_params.
+        """
+        if param_shape is None:
+            return (n_params,)
+
+        param_shape = (param_shape,) if isinstance(param_shape, int) else param_shape
+
+        if any(dim <= 0 for dim in param_shape):
+            raise ValueError(
+                f"param_shape entries must be positive, got {param_shape}."
+            )
+
+        if int(np.prod(param_shape)) != n_params:
+            raise ValueError(
+                f"param_shape does not match the number of trainable parameters. "
+                f"Expected product {n_params}, got {int(np.prod(param_shape))}."
+            )
+
+        return tuple(param_shape)
+
+    def _coerce_to_quantum_script(
+        self,
+        qscript: qml.tape.QuantumScript | QuantumCircuit,
+    ) -> qml.tape.QuantumScript:
+        """Convert supported inputs into a PennyLane QuantumScript.
+
+        Args:
+            qscript (qml.tape.QuantumScript): Input QuantumScript or Qiskit QuantumCircuit.
+
+        Returns:
+            qml.tape.QuantumScript: The converted QuantumScript.
+
+        Raises:
+            TypeError: If the input type is unsupported.
+        """
+        if isinstance(qscript, qml.tape.QuantumScript):
+            return qscript
+
+        if isinstance(qscript, QuantumCircuit):
+            measured_wires = sorted(
+                {
+                    qscript.qubits.index(qubit)
+                    for instruction in qscript.data
+                    if instruction.operation.name == "measure"
+                    for qubit in instruction.qubits
+                }
+            )
+            if not measured_wires:
+                warn(
+                    "Provided QuantumCircuit has no measurement operations. "
+                    "Defaulting to measuring all wires with PauliZ.",
+                    UserWarning,
+                )
+                measured_wires = list(range(len(qscript.qubits)))
+
+            obs = (
+                qml.Z(measured_wires[0])
+                if len(measured_wires) == 1
+                else qml.sum(*(qml.Z(wire) for wire in measured_wires))
+            )
+            # Remove measurements before conversion to avoid MidMeasureMP issues
+            qc_no_measure = QuantumCircuit(qscript.num_qubits)
+            for instruction in qscript.data:
+                if instruction.operation.name != "measure":
+                    qc_no_measure.append(
+                        instruction.operation, instruction.qubits, instruction.clbits
+                    )
+            qfunc = qml.from_qiskit(qc_no_measure)
+            qiskit_params = [
+                qml.numpy.array(0.0, requires_grad=True) for _ in qscript.parameters
+            ]
+
+            def qfunc_with_measurement(*params):
+                qfunc(*params)
+                return qml.expval(obs)
+
+            return qml.tape.make_qscript(qfunc_with_measurement)(*qiskit_params)
+
+        raise TypeError(
+            "qscript must be a PennyLane QuantumScript or a Qiskit QuantumCircuit."
+        )
+
+    def _create_meta_circuits_dict(self) -> dict[str, MetaCircuit]:
+        """Create the meta-circuit dictionary for CustomVQA.
+
+        Returns:
+            dict[str, MetaCircuit]: Dictionary containing the cost circuit template.
+        """
+        return {
+            "cost_circuit": self._meta_circuit_factory(
+                self._qscript, symbols=self._param_symbols.flatten()
+            )
+        }
+
+    def _generate_circuits(self) -> list[CircuitBundle]:
+        """Generate circuits for the current parameter sets.
+
+        Returns:
+            list[CircuitBundle]: Circuit bundles tagged by parameter index.
+        """
+        return [
+            self.meta_circuits["cost_circuit"].initialize_circuit_from_params(
+                params_group, param_idx=p
+            )
+            for p, params_group in enumerate(self._curr_params)
+        ]
+
+    def _perform_final_computation(self, **kwargs) -> None:
+        """No-op by default for custom QuantumScript optimization."""
+        pass
+
+    def _save_subclass_state(self) -> dict[str, Any]:
+        """Save subclass-specific state for checkpointing."""
+        return {}
+
+    def _load_subclass_state(self, state: dict[str, Any]) -> None:
+        """Load subclass-specific state from a checkpoint."""
+        pass