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

divi/circuits/_core.py

@@ -0,0 +1,391 @@
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from itertools import product
+from typing import Literal, NamedTuple
+
+import dill
+import numpy as np
+import numpy.typing as npt
+import pennylane as qml
+from pennylane.transforms.core.transform_program import TransformProgram
+
+from divi.circuits import to_openqasm
+from divi.circuits.qem import QEMProtocol
+
+TRANSFORM_PROGRAM = TransformProgram()
+TRANSFORM_PROGRAM.add_transform(qml.transforms.split_to_single_terms)
+
+
+def _wire_grouping(measurements: list[qml.measurements.MeasurementProcess]):
+    """
+    Groups a list of PennyLane MeasurementProcess objects by mutually non-overlapping wires.
+
+    Each group contains measurements whose wires do not overlap with those of any other
+    measurement in the same group. This enables parallel measurement of compatible observables,
+    e.g., for grouped execution or more efficient sampling.
+
+    Returns:
+        partition_indices (list[list[int]]): Indices of the original measurements in each group.
+        mp_groups (list[list[MeasurementProcess]]): Grouped MeasurementProcess objects.
+    """
+    mp_groups = []
+    wires_for_each_group = []
+    group_mapping = {}  # original_index -> (group_idx, pos_in_group)
+
+    for i, mp in enumerate(measurements):
+        added = False
+        for group_idx, wires in enumerate(wires_for_each_group):
+            if not qml.wires.Wires.shared_wires([wires, mp.wires]):
+                mp_groups[group_idx].append(mp)
+                wires_for_each_group[group_idx] += mp.wires
+                group_mapping[i] = (group_idx, len(mp_groups[group_idx]) - 1)
+                added = True
+                break
+        if not added:
+            mp_groups.append([mp])
+            wires_for_each_group.append(mp.wires)
+            group_mapping[i] = (len(mp_groups) - 1, 0)
+
+    partition_indices = [[] for _ in range(len(mp_groups))]
+    for original_idx, (group_idx, _) in group_mapping.items():
+        partition_indices[group_idx].append(original_idx)
+
+    return partition_indices, mp_groups
+
+
+def _create_final_postprocessing_fn(coefficients, partition_indices, num_total_obs):
+    """Create a wrapper fn that reconstructs the flat results list and computes the final energy."""
+    reverse_map = [None] * num_total_obs
+    for group_idx, indices_in_group in enumerate(partition_indices):
+        for idx_within_group, original_flat_idx in enumerate(indices_in_group):
+            reverse_map[original_flat_idx] = (group_idx, idx_within_group)
+
+    missing_indices = [i for i, v in enumerate(reverse_map) if v is None]
+    if missing_indices:
+        raise RuntimeError(
+            f"partition_indices does not cover all observable indices. Missing indices: {missing_indices}"
+        )
+
+    def final_postprocessing_fn(grouped_results):
+        """
+        Takes grouped results, flattens them to the original order,
+        multiplies by coefficients, and sums to get the final energy.
+        """
+        if len(grouped_results) != len(partition_indices):
+            raise RuntimeError(
+                f"Expected {len(partition_indices)} grouped results, but got {len(grouped_results)}."
+            )
+        flat_results = np.zeros(num_total_obs, dtype=np.float64)
+        for original_flat_idx in range(num_total_obs):
+            group_idx, idx_within_group = reverse_map[original_flat_idx]
+
+            group_result = grouped_results[group_idx]
+            # When a group has one measurement, the result is a scalar.
+            if len(partition_indices[group_idx]) == 1:
+                flat_results[original_flat_idx] = group_result
+            else:
+                flat_results[original_flat_idx] = group_result[idx_within_group]
+
+        # Perform the final summation using the efficient dot product method.
+        return np.dot(coefficients, flat_results)
+
+    return final_postprocessing_fn
+
+
+class CircuitTag(NamedTuple):
+    """Structured tag for identifying circuit executions."""
+
+    param_id: int
+    qem_name: str
+    qem_id: int
+    meas_id: int
+
+
+def format_circuit_tag(tag: CircuitTag) -> str:
+    """Format a CircuitTag into its wire-safe string representation."""
+    return f"{tag.param_id}_{tag.qem_name}:{tag.qem_id}_{tag.meas_id}"
+
+
+@dataclass(frozen=True)
+class ExecutableQASMCircuit:
+    """Represents a single, executable QASM circuit with its associated tag."""
+
+    tag: CircuitTag
+    qasm: str
+
+
+@dataclass(frozen=True)
+class CircuitBundle:
+    """
+    Represents a bundle of logically related quantum circuits.
+
+    A CircuitBundle is typically generated from a single `MetaCircuit` by
+    instantiating it with concrete parameters. It may contain multiple
+    executable circuits due to measurement grouping or error mitigation
+    protocols. Each executable circuit has a QASM representation and a
+    unique tag for identification.
+    """
+
+    executables: tuple[ExecutableQASMCircuit, ...]
+    """Tuple of executable circuits."""
+
+    def __str__(self):
+        """
+        Return a string representation of the circuit bundle.
+
+        Returns:
+            str: String in format "CircuitBundle ({num_executables} executables)".
+        """
+        return f"CircuitBundle ({len(self.executables)} executables)"
+
+    @property
+    def tags(self) -> list[CircuitTag]:
+        """A list of tags for all executables in the bundle."""
+        return [e.tag for e in self.executables]
+
+    @property
+    def qasm_circuits(self) -> list[str]:
+        """A list of QASM strings for all executables in the bundle."""
+        return [e.qasm for e in self.executables]
+
+
+@dataclass(frozen=True)
+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.
+    """
+
+    source_circuit: qml.tape.QuantumScript
+    """The PennyLane quantum circuit with symbolic parameters."""
+    symbols: npt.NDArray[np.object_]
+    """Array of sympy symbols used as circuit parameters."""
+    grouping_strategy: Literal["wires", "default", "qwc", "_backend_expval"] | None = (
+        None
+    )
+    """Strategy for grouping commuting observables."""
+    qem_protocol: QEMProtocol | None = None
+    """Quantum error mitigation protocol to apply."""
+    precision: int = 8
+    """Number of decimal places for parameter values in QASM conversion."""
+
+    # --- Compiled artifacts ---
+    _compiled_circuit_bodies: tuple[str, ...] = field(init=False)
+    _measurements: tuple[str, ...] = field(init=False)
+    measurement_groups: tuple[tuple[qml.operation.Operator, ...], ...] = field(
+        init=False
+    )
+    postprocessing_fn: Callable = field(init=False)
+
+    def __post_init__(self):
+        """
+        Compiles the circuit template after initialization.
+
+        This method performs several steps:
+        1. Decomposes the source circuit's measurement into single-term observables.
+        2. Groups commuting observables according to the specified strategy.
+        3. Generates a post-processing function to correctly combine measurement results.
+        4. Compiles the circuit body and measurement instructions into QASM strings.
+        """
+        # Validate that the circuit has exactly one valid observable measurement.
+        if len(self.source_circuit.measurements) != 1:
+            raise ValueError(
+                f"MetaCircuit requires a circuit with exactly one measurement, "
+                f"but {len(self.source_circuit.measurements)} were found."
+            )
+
+        measurement = self.source_circuit.measurements[0]
+        # If the measurement is not an expectation value, we assume it is for sampling
+        # and does not require special post-processing.
+        if not hasattr(measurement, "obs") or measurement.obs is None:
+            postprocessing_fn = lambda x: x
+            measurement_groups = ((),)
+            (
+                compiled_circuit_bodies,
+                measurements,
+            ) = to_openqasm(
+                self.source_circuit,
+                measurement_groups=measurement_groups,
+                return_measurements_separately=True,
+                symbols=self.symbols,
+                qem_protocol=self.qem_protocol,
+                precision=self.precision,
+            )
+            # Use object.__setattr__ because the class is frozen
+            object.__setattr__(self, "postprocessing_fn", postprocessing_fn)
+            object.__setattr__(self, "measurement_groups", measurement_groups)
+            object.__setattr__(
+                self, "_compiled_circuit_bodies", tuple(compiled_circuit_bodies)
+            )
+            object.__setattr__(self, "_measurements", tuple(measurements))
+
+            return
+
+        # Step 1: Use split_to_single_terms to get a flat list of measurement
+        # processes. We no longer need its post-processing function.
+        measurements_only_tape = qml.tape.QuantumScript(
+            measurements=self.source_circuit.measurements
+        )
+        s_tapes, _ = TRANSFORM_PROGRAM((measurements_only_tape,))
+        single_term_mps = s_tapes[0].measurements
+
+        # Extract the coefficients, which we will now use in our own post-processing.
+        obs = self.source_circuit.measurements[0].obs
+        if isinstance(obs, (qml.Hamiltonian, qml.ops.Sum)):
+            coeffs, _ = obs.terms()
+        else:
+            # For single observables, the coefficient is implicitly 1.0
+            coeffs = [1.0]
+
+        # Step 2: Manually group the flat list of measurements based on the strategy.
+        if self.grouping_strategy in ("qwc", "default"):
+            obs_list = [m.obs for m in single_term_mps]
+            # This computes the grouping indices for the flat list of observables
+            partition_indices = qml.pauli.compute_partition_indices(obs_list)
+            measurement_groups = tuple(
+                tuple(single_term_mps[i].obs for i in group)
+                for group in partition_indices
+            )
+        elif self.grouping_strategy == "wires":
+            partition_indices, grouped_mps = _wire_grouping(single_term_mps)
+            measurement_groups = tuple(
+                tuple(m.obs for m in group) for group in grouped_mps
+            )
+        elif self.grouping_strategy is None:
+            # Each measurement is its own group
+            measurement_groups = tuple(tuple([m.obs]) for m in single_term_mps)
+            partition_indices = [[i] for i in range(len(single_term_mps))]
+        elif self.grouping_strategy == "_backend_expval":
+            measurement_groups = ((),)
+            # For backends that compute expectation values directly, no explicit
+            # measurement basis rotations (diagonalizing gates) are needed in the QASM.
+            # The `to_openqasm` function interprets an empty measurement group `()`
+            # as a signal to skip adding these gates.
+            # All observables are still tracked in a single group for post-processing.
+            partition_indices = [list(range(len(single_term_mps)))]
+        else:
+            raise ValueError(f"Unknown grouping strategy: {self.grouping_strategy}")
+
+        # Step 3: Create our own post-processing function that handles the final summation.
+        postprocessing_fn = _create_final_postprocessing_fn(
+            coeffs, partition_indices, len(single_term_mps)
+        )
+
+        compiled_circuit_bodies, measurements = to_openqasm(
+            self.source_circuit,
+            measurement_groups=measurement_groups,
+            return_measurements_separately=True,
+            # TODO: optimize later
+            measure_all=True,
+            symbols=self.symbols,
+            qem_protocol=self.qem_protocol,
+            precision=self.precision,
+        )
+        # Use object.__setattr__ because the class is frozen
+        object.__setattr__(self, "postprocessing_fn", postprocessing_fn)
+        object.__setattr__(self, "measurement_groups", measurement_groups)
+        object.__setattr__(
+            self, "_compiled_circuit_bodies", tuple(compiled_circuit_bodies)
+        )
+        object.__setattr__(self, "_measurements", tuple(measurements))
+
+    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: npt.NDArray[np.floating] | list[float],
+        param_idx: int = 0,
+        precision: int | None = None,
+    ) -> CircuitBundle:
+        """
+        Instantiate a concrete CircuitBundle by substituting symbolic parameters with values.
+
+        Takes a list of parameter values and creates a fully instantiated CircuitBundle
+        by replacing all symbolic parameters in the QASM representations with their
+        concrete numerical values.
+
+        Args:
+            param_list (npt.NDArray[np.floating] | list[float]): Array of numerical
+                parameter values to substitute for symbols.
+                Must match the length and order of self.symbols.
+            param_idx (int, optional): Parameter set index used for structured tags.
+                Defaults to 0.
+            precision (int | None, optional): Number of decimal places for parameter values
+                in the QASM output. If None, uses the precision set on this MetaCircuit instance.
+                Defaults to None.
+
+        Returns:
+            CircuitBundle: A new CircuitBundle instance with parameters substituted and proper
+                tags for identification.
+
+        Note:
+            The main circuit's parameters are still in symbol form.
+            Not sure if it is necessary for any useful application to parameterize them.
+        """
+        if precision is None:
+            precision = self.precision
+        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_bodies = [
+            pattern.sub(lambda match: mapping[match.group(0)], body)
+            for body in self._compiled_circuit_bodies
+        ]
+
+        executables = []
+        param_id = param_idx
+        for (i, body_str), (j, meas_str) in product(
+            enumerate(final_qasm_bodies), enumerate(self._measurements)
+        ):
+            qasm_circuit = body_str + meas_str
+            tag = CircuitTag(
+                param_id=param_id,
+                qem_name=(
+                    self.qem_protocol.name if self.qem_protocol else "NoMitigation"
+                ),
+                qem_id=i,
+                meas_id=j,
+            )
+            executables.append(ExecutableQASMCircuit(tag=tag, qasm=qasm_circuit))
+
+        return CircuitBundle(executables=tuple(executables))

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

@@ -5,7 +5,6 @@
 import re
 from functools import partial
 from itertools import product
-from typing import Optional
 from warnings import warn
 
 import cirq
@@ -13,10 +12,11 @@ import numpy as np
 import pennylane as qml
 from pennylane.tape import QuantumScript
 from pennylane.wires import Wires
-from sympy import Symbol
+from sympy import Expr, Symbol
 
-from divi.exp.cirq import cirq_circuit_from_qasm
-from divi.qem import QEMProtocol
+from divi.circuits.qem import QEMProtocol
+
+from ._cirq import ExtendedQasmParser as QasmParser
 
 OPENQASM_GATES = {
     "CNOT": "cx",
@@ -46,7 +46,39 @@ OPENQASM_GATES = {
 }
 
 
+def _cirq_circuit_from_qasm(qasm: str) -> cirq.Circuit:
+    """Parses an OpenQASM string to `cirq.Circuit`.
+
+    Args:
+        qasm: The OpenQASM string
+
+    Returns:
+        The parsed circuit
+    """
+
+    return QasmParser().parse(qasm).circuit
+
+
 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 = ""
 
@@ -65,9 +97,17 @@ def _ops_to_qasm(operations, precision, wires):
             # If the operation takes parameters, construct a string
             # with parameter values.
             if precision is not None:
-                params = (
-                    "(" + ",".join([f"{p:.{precision}}" for p in op.parameters]) + ")"
-                )
+                # Format parameters with precision, but use str() for sympy expressions
+                param_strs = []
+                for p in op.parameters:
+                    if isinstance(p, Expr):
+                        # Sympy expressions (Symbol, Mul, Add, etc.) should be kept as-is
+                        # (will be replaced later during parameter substitution)
+                        param_strs.append(str(p))
+                    else:
+                        # Numeric parameters can be formatted with precision
+                        param_strs.append(f"{p:.{precision}}")
+                params = "(" + ",".join(param_strs) + ")"
             else:
                 # use default precision
                 params = "(" + ",".join([str(p) for p in op.parameters]) + ")"
@@ -81,10 +121,10 @@ def to_openqasm(
     main_qscript,
     measurement_groups: list[list[qml.measurements.ExpectationMP]],
     measure_all: bool = True,
-    precision: Optional[int] = None,
+    precision: int | None = None,
     return_measurements_separately: bool = False,
     symbols: list[Symbol] = None,
-    qem_protocol: Optional[QEMProtocol] = None,
+    qem_protocol: QEMProtocol | None = None,
 ) -> list[str] | tuple[str, list[str]]:
     """
     Serialize the circuit as an OpenQASM 2.0 program.
@@ -137,7 +177,18 @@ def to_openqasm(
         return main_qasm_str
 
     if qem_protocol:
+        # Flatten symbols list to handle both individual symbols and arrays of symbols
+        flat_symbols = []
         for symbol in symbols:
+            if isinstance(symbol, np.ndarray):
+                # If it's a numpy array of symbols, flatten it
+                flat_symbols.extend(symbol.flatten())
+            else:
+                # Individual symbol
+                flat_symbols.append(symbol)
+
+        # Declare each symbol individually in QASM 3.0
+        for symbol in flat_symbols:
             main_qasm_str += f"input angle[32] {str(symbol)};\n"
 
     # create the quantum and classical registers
@@ -167,7 +218,7 @@ def to_openqasm(
 
     main_qasm_strs = []
     if qem_protocol:
-        for circ in qem_protocol.modify_circuit(cirq_circuit_from_qasm(main_qasm_str)):
+        for circ in qem_protocol.modify_circuit(_cirq_circuit_from_qasm(main_qasm_str)):
             # Convert back to QASM2.0 code, with the symbolic parameters
             qasm_str = cirq.qasm(circ)
             # Remove redundant newlines
@@ -186,9 +237,19 @@ def to_openqasm(
 
     # Create a copy of the program for every measurement that we have
     for meas_group in measurement_groups:
+        # Ensure all items in measurement group are MeasurementProcess instances
+        wrapped_group = [
+            m if isinstance(m, qml.measurements.MeasurementProcess) else qml.expval(m)
+            for m in meas_group
+        ]
+
         curr_diag_qasm_str = (
             _to_qasm(diag_ops)
-            if (diag_ops := QuantumScript(measurements=meas_group).diagonalizing_gates)
+            if (
+                diag_ops := QuantumScript(
+                    measurements=wrapped_group
+                ).diagonalizing_gates
+            )
             else ""
         )
 
@@ -197,9 +258,7 @@ def to_openqasm(
             for wire in range(len(wires)):
                 measure_qasm_str += f"measure q[{wire}] -> c[{wire}];\n"
         else:
-            measured_wires = Wires.all_wires(
-                [m.wires for m in main_qscript.measurements]
-            )
+            measured_wires = Wires.all_wires([m.wires for m in meas_group])
 
             for w in measured_wires:
                 wire_indx = main_qscript.wires.index(w)