qoro-divi 0.3.3__py3-none-any.whl → 0.3.5__py3-none-any.whl

divi/circuits/_core.py

@@ -0,0 +1,226 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from copy import deepcopy
+from itertools import product
+from typing import Literal
+
+import dill
+import pennylane as qml
+from pennylane.transforms.core.transform_program import TransformProgram
+
+from divi.circuits.qasm import to_openqasm
+from divi.circuits.qem import QEMProtocol
+
+TRANSFORM_PROGRAM = TransformProgram()
+TRANSFORM_PROGRAM.add_transform(qml.transforms.split_to_single_terms)
+TRANSFORM_PROGRAM.add_transform(qml.transforms.split_non_commuting)
+
+
+class Circuit:
+    """
+    Represents a quantum circuit with its QASM representation and metadata.
+
+    This class encapsulates a PennyLane quantum circuit along with its OpenQASM
+    serialization and associated tags for identification. Each circuit instance
+    is assigned a unique ID for tracking purposes.
+
+    Attributes:
+        main_circuit: The PennyLane quantum circuit/tape object.
+        tags (list[str]): List of string tags for circuit identification.
+        qasm_circuits (list[str]): List of OpenQASM string representations.
+        circuit_id (int): Unique identifier for this circuit instance.
+    """
+
+    _id_counter = 0
+
+    def __init__(
+        self,
+        main_circuit,
+        tags: list[str],
+        qasm_circuits: list[str] = None,
+    ):
+        """
+        Initialize a Circuit instance.
+
+        Args:
+            main_circuit: A PennyLane quantum circuit or tape object to be wrapped.
+            tags (list[str]): List of string tags for identifying this circuit.
+            qasm_circuits (list[str], optional): Pre-computed OpenQASM string
+                representations. If None, they will be generated from main_circuit.
+                Defaults to None.
+        """
+        self.main_circuit = main_circuit
+        self.tags = tags
+
+        self.qasm_circuits = qasm_circuits
+
+        if self.qasm_circuits is None:
+            self.qasm_circuits = to_openqasm(
+                self.main_circuit,
+                measurement_groups=[self.main_circuit.measurements],
+                return_measurements_separately=False,
+            )
+
+        self.circuit_id = Circuit._id_counter
+        Circuit._id_counter += 1
+
+    def __str__(self):
+        """
+        Return a string representation of the circuit.
+
+        Returns:
+            str: String in format "Circuit: {circuit_id}".
+        """
+        return f"Circuit: {self.circuit_id}"
+
+
+class MetaCircuit:
+    """
+    A parameterized quantum circuit template for batch circuit generation.
+
+    MetaCircuit represents a symbolic quantum circuit that can be instantiated
+    multiple times with different parameter values. It handles circuit compilation,
+    observable grouping, and measurement decomposition for efficient execution.
+
+    Attributes:
+        main_circuit: The PennyLane quantum circuit with symbolic parameters.
+        symbols: Array of sympy symbols used as circuit parameters.
+        qem_protocol (QEMProtocol): Quantum error mitigation protocol to apply.
+        compiled_circuits_bodies (list[str]): QASM bodies without measurements.
+        measurements (list[str]): QASM measurement strings.
+        measurement_groups (list[list]): Grouped observables for each circuit variant.
+        postprocessing_fn: Function to combine measurement results.
+    """
+
+    def __init__(
+        self,
+        main_circuit,
+        symbols,
+        grouping_strategy: Literal["wires", "default", "qwc"] | None = None,
+        qem_protocol: QEMProtocol | None = None,
+    ):
+        """
+        Initialize a MetaCircuit with symbolic parameters.
+
+        Args:
+            main_circuit: A PennyLane quantum circuit/tape with symbolic parameters.
+            symbols: Array of sympy Symbol objects representing circuit parameters.
+            grouping_strategy (str, optional): Strategy for grouping commuting
+                observables. Options are "wires", "default", or "qwc" (qubit-wise
+                commuting). Defaults to None.
+            qem_protocol (QEMProtocol, optional): Quantum error mitigation protocol
+                to apply to the circuits. Defaults to None.
+        """
+        self.main_circuit = main_circuit
+        self.symbols = symbols
+        self.qem_protocol = qem_protocol
+
+        transform_program = deepcopy(TRANSFORM_PROGRAM)
+        transform_program[1].kwargs["grouping_strategy"] = grouping_strategy
+
+        qscripts, self.postprocessing_fn = transform_program((main_circuit,))
+
+        self.compiled_circuits_bodies, self.measurements = to_openqasm(
+            main_circuit,
+            measurement_groups=[qsc.measurements for qsc in qscripts],
+            return_measurements_separately=True,
+            # TODO: optimize later
+            measure_all=True,
+            symbols=self.symbols,
+            qem_protocol=qem_protocol,
+        )
+
+        # Need to store the measurement groups for computing
+        # expectation values later on, stripped of the `qml.expval` wrapper
+        self.measurement_groups = [
+            [meas.obs for meas in qsc.measurements] for qsc in qscripts
+        ]
+
+    def __getstate__(self):
+        """
+        Prepare the MetaCircuit for pickling.
+
+        Serializes the postprocessing function using dill since regular pickle
+        cannot handle certain PennyLane function objects.
+
+        Returns:
+            dict: State dictionary with serialized postprocessing function.
+        """
+        state = self.__dict__.copy()
+        state["postprocessing_fn"] = dill.dumps(self.postprocessing_fn)
+        return state
+
+    def __setstate__(self, state):
+        """
+        Restore the MetaCircuit from a pickled state.
+
+        Deserializes the postprocessing function that was serialized with dill
+        during pickling.
+
+        Args:
+            state (dict): State dictionary from pickling with serialized
+                postprocessing function.
+        """
+        state["postprocessing_fn"] = dill.loads(state["postprocessing_fn"])
+
+        self.__dict__.update(state)
+
+    def initialize_circuit_from_params(
+        self, param_list, tag_prefix: str = "", precision: int = 8
+    ) -> Circuit:
+        """
+        Instantiate a concrete Circuit by substituting symbolic parameters with values.
+
+        Takes a list of parameter values and creates a fully instantiated Circuit
+        by replacing all symbolic parameters in the QASM representations with their
+        concrete numerical values.
+
+        Args:
+            param_list: Array of numerical parameter values to substitute for symbols.
+                Must match the length and order of self.symbols.
+            tag_prefix (str, optional): Prefix to prepend to circuit tags for
+                identification. Defaults to "".
+            precision (int, optional): Number of decimal places for parameter values
+                in the QASM output. Defaults to 8.
+
+        Returns:
+            Circuit: A new Circuit instance with parameters substituted and proper
+                tags for identification.
+
+        Note:
+            The main_circuit attribute in the returned Circuit still contains
+            symbolic parameters. Only the QASM representations have concrete values.
+        """
+        mapping = dict(
+            zip(
+                map(lambda x: re.escape(str(x)), self.symbols),
+                map(lambda x: f"{x:.{precision}f}", param_list),
+            )
+        )
+        pattern = re.compile("|".join(k for k in mapping.keys()))
+
+        final_qasm_strs = []
+        for circuit_body in self.compiled_circuits_bodies:
+            final_qasm_strs.append(
+                pattern.sub(lambda match: mapping[match.group(0)], circuit_body)
+            )
+
+        tags = []
+        qasm_circuits = []
+        for (i, body_str), (j, meas_str) in product(
+            enumerate(final_qasm_strs), enumerate(self.measurements)
+        ):
+            qasm_circuits.append(body_str + meas_str)
+
+            nonempty_subtags = filter(
+                None,
+                [tag_prefix, f"{self.qem_protocol.name}:{i}", str(j)],
+            )
+            tags.append("_".join(nonempty_subtags))
+
+        # Note: The main circuit's parameters are still in symbol form.
+        # Not sure if it is necessary for any useful application to parameterize them.
+        return Circuit(self.main_circuit, qasm_circuits=qasm_circuits, tags=tags)

divi/{qasm.py → circuits/qasm.py}

@@ -14,8 +14,8 @@ from pennylane.tape import QuantumScript
 from pennylane.wires import Wires
 from sympy import Symbol
 
-from divi.exp.cirq import cirq_circuit_from_qasm
-from divi.qem import QEMProtocol
+from divi.circuits.qem import QEMProtocol
+from divi.extern.cirq import cirq_circuit_from_qasm
 
 OPENQASM_GATES = {
     "CNOT": "cx",
@@ -46,6 +46,25 @@ OPENQASM_GATES = {
 
 
 def _ops_to_qasm(operations, precision, wires):
+    """
+    Convert PennyLane operations to OpenQASM instruction strings.
+
+    Translates a sequence of PennyLane quantum operations into their OpenQASM
+    2.0 equivalent representations. Each operation is mapped to its corresponding
+    QASM gate with appropriate parameters and wire labels.
+
+    Args:
+        operations: Sequence of PennyLane operation objects to convert.
+        precision (int | None): Number of decimal places for parameter values.
+            If None, uses default Python string formatting.
+        wires: Wire labels used in the circuit for indexing.
+
+    Returns:
+        str: OpenQASM instruction string with each operation on a new line.
+
+    Raises:
+        ValueError: If an operation is not supported by the QASM serializer.
+    """
     # create the QASM code representing the operations
     qasm_str = ""
 

divi/{exp → extern}/cirq/_validator.py

@@ -289,7 +289,12 @@ class Parser:
     # ---- gate definitions ----
     def gate_def(self):
         self.match("GATE")
-        gname = self.match("ID").value
+        gname_tok = self.match("ID")
+        gname = gname_tok.value
+        if gname in BUILTINS:
+            raise SyntaxError(
+                f"Cannot redefine built-in gate '{gname}' at {gname_tok.line}:{gname_tok.col}"
+            )
         if gname in self.user_gates:
             self._dupe(gname)
         params: tuple[str, ...] = ()
@@ -570,7 +575,6 @@ class Parser:
         if t.type == "PI":
             self.match("PI")
             return
-        # ---- NEW BLOCK TO HANDLE MATH FUNCTIONS ----
         if t.type in _MATH_FUNCS:
             self.match(t.type)  # Consume the function name (e.g., COS)
             self.match("LPAREN")
@@ -578,13 +582,11 @@ class Parser:
             # Note: QASM 2.0 math functions only take one argument
             self.match("RPAREN")
             return
-        # --------------------------------------------
         if t.type == "ID":
             # function call or plain ID
             id_tok = self.match("ID")
             ident = id_tok.value
             if self.accept("LPAREN"):
-                # This now correctly handles user-defined functions (if any)
                 if self.peek().type != "RPAREN":
                     self._expr(allow_id)
                     while self.accept("COMMA"):
@@ -637,9 +639,9 @@ def validate_qasm_raise(src: str) -> None:
     Parser(toks).parse()
 
 
-def is_valid_qasm(src: str) -> bool:
+def is_valid_qasm(src: str) -> bool | str:
     try:
         validate_qasm_raise(src)
         return True
-    except SyntaxError:
-        return False
+    except SyntaxError as e:
+        return str(e)

divi/qprog/__init__.py

@@ -5,9 +5,22 @@
 # isort: skip_file
 from .quantum_program import QuantumProgram
 from .batch import ProgramBatch
-from ._qaoa import QAOA, GraphProblem
-from ._vqe import VQE, VQEAnsatz
-from ._graph_partitioning import GraphPartitioningQAOA, PartitioningConfig
-from ._qubo_partitioning import QUBOPartitioningQAOA
-from ._vqe_sweep import VQEHyperparameterSweep, MoleculeTransformer
+from .algorithms import (
+    QAOA,
+    GraphProblem,
+    VQE,
+    Ansatz,
+    UCCSDAnsatz,
+    QAOAAnsatz,
+    HardwareEfficientAnsatz,
+    HartreeFockAnsatz,
+    GenericLayerAnsatz,
+)
+from .workflows import (
+    GraphPartitioningQAOA,
+    PartitioningConfig,
+    QUBOPartitioningQAOA,
+    VQEHyperparameterSweep,
+    MoleculeTransformer,
+)
 from .optimizers import ScipyOptimizer, ScipyMethod, MonteCarloOptimizer

divi/qprog/algorithms/__init__.py

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

divi/qprog/algorithms/_ansatze.py

@@ -0,0 +1,311 @@
+# SPDX-FileCopyrightText: 2025 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
+
+
+class Ansatz(ABC):
+    """Abstract base class for all VQE ansaetze."""
+
+    @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):
+        """
+        Builds the ansatz circuit.
+
+        Args:
+            params (array): The parameters (weights) for the ansatz.
+            n_qubits (int): The number of qubits.
+            n_layers (int): The number of layers.
+            **kwargs: Additional arguments like n_electrons for chemistry ansaetze.
+        """
+        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 per_qubit * n_qubits
+
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs):
+        # 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))
+
+        def _layer(layer_params, wires):
+            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]
+                    gate(*theta, wires=w)
+                    idx += n_p
+
+            if self.entangler is not None:
+                for wire_a, wire_b in next(layout_gen):
+                    self.entangler(wires=[wire_a, wire_b])
+
+        qml.layer(_layer, n_layers, params, wires=range(n_qubits))
+
+
+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.
+        """
+        return qml.QAOAEmbedding.shape(n_layers=1, n_wires=n_qubits)[1]
+
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs):
+        """
+        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.
+        """
+        qml.QAOAEmbedding(
+            features=[],
+            weights=params.reshape(n_layers, -1),
+            wires=range(n_qubits),
+        )
+
+
+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) -> None:
+        """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)
+        return len(s_wires) + len(d_wires)
+
+    def build(self, params, n_qubits: int, n_layers: int, n_electrons: int, **kwargs):
+        """
+        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).
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+        """
+        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)
+
+        qml.UCCSD(
+            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)
+        return len(singles) + len(doubles)
+
+    def build(self, params, n_qubits: int, n_layers: int, n_electrons: int, **kwargs):
+        """
+        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.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+        """
+        singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
+        hf_state = qml.qchem.hf_state(n_electrons, n_qubits)
+
+        qml.layer(
+            qml.AllSinglesDoubles,
+            n_layers,
+            params.reshape(n_layers, -1),
+            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 qml.QueuingManager.active_context().queue[1:]:
+            op._hyperparameters["hf_state"] = 0