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

divi/__init__.py

@@ -2,7 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from .qlogger import enable_logging
-from .qoro_service import QoroService
+from .reporting import enable_logging
 
 enable_logging()

divi/backends/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ._circuit_runner import CircuitRunner
+from ._parallel_simulator import ParallelSimulator
+from ._qoro_service import JobStatus, JobType, QoroService

divi/backends/_circuit_runner.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from abc import ABC, abstractmethod
+
+
+class CircuitRunner(ABC):
+    """
+    A generic interface for anything that can "run" quantum circuits.
+    """
+
+    def __init__(self, shots: int):
+        if shots <= 0:
+            raise ValueError(f"Shots must be a positive integer. Got {shots}.")
+
+        self._shots = shots
+
+    @property
+    def shots(self):
+        """
+        Get the number of measurement shots for circuit execution.
+
+        Returns:
+            int: Number of shots configured for this runner.
+        """
+        return self._shots
+
+    @abstractmethod
+    def submit_circuits(self, circuits: dict[str, str], **kwargs):
+        """
+        Submit quantum circuits for execution.
+
+        This abstract method must be implemented by subclasses to define how
+        circuits are executed on their respective backends (simulator, hardware, etc.).
+
+        Args:
+            circuits (dict[str, str]): Dictionary mapping circuit labels to their
+                OpenQASM string representations.
+            **kwargs: Additional backend-specific parameters for circuit execution.
+
+        Returns:
+            The return type depends on the backend implementation. Typically returns
+            measurement results or a job identifier.
+        """
+        pass

divi/{parallel_simulator.py → backends/_parallel_simulator.py}

@@ -18,7 +18,7 @@ from qiskit.providers import Backend
 from qiskit_aer import AerSimulator
 from qiskit_aer.noise import NoiseModel
 
-from divi.interfaces import CircuitRunner
+from divi.backends import CircuitRunner
 
 logger = logging.getLogger(__name__)
 
@@ -66,16 +66,20 @@ class ParallelSimulator(CircuitRunner):
         simulation_seed: int | None = None,
         qiskit_backend: Backend | Literal["auto"] | None = None,
         noise_model: NoiseModel | None = None,
+        _deterministic_execution: bool = False,
     ):
         """
-        A multi-process wrapper around Qiskit's AerSimulator.
+        A parallel wrapper around Qiskit's AerSimulator using Qiskit's built-in parallelism.
 
         Args:
-            n_processes (int, optional): Number of parallel processes to use for simulation. Defaults to 2.
+            n_processes (int, optional): Number of parallel processes to use for transpilation and
+                simulation. Defaults to 2. This sets both the transpile num_processes and
+                AerSimulator's max_parallel_experiments.
             shots (int, optional): Number of shots to perform. Defaults to 5000.
             simulation_seed (int, optional): Seed for the random number generator to ensure reproducibility. Defaults to None.
-            backend (Backend or "auto, optional): A Qiskit backend to initiate the simulator from. If "auto" is passed,
-             the best-fit most recent fake backend will be chosen for the given circuit. Defaults to None, resulting in noiseless simulation.
+            qiskit_backend (Backend | Literal["auto"] | None, optional): A Qiskit backend to initiate the simulator from.
+            If "auto" is passed, the best-fit most recent fake backend will be chosen for the given circuit.
+            Defaults to None, resulting in noiseless simulation.
             noise_model (NoiseModel, optional): Qiskit noise model to use in simulation. Defaults to None.
         """
         super().__init__(shots=shots)
@@ -91,62 +95,138 @@ class ParallelSimulator(CircuitRunner):
         self.simulation_seed = simulation_seed
         self.qiskit_backend = qiskit_backend
         self.noise_model = noise_model
+        self._deterministic_execution = _deterministic_execution
 
-    @staticmethod
-    def simulate_circuit(
-        circuit_data: tuple[str, str],
-        shots: int,
-        simulation_seed: int | None = None,
-        qiskit_backend: Backend | None = None,
-        noise_model: NoiseModel | None = None,
-    ):
-        circuit_label, circuit = circuit_data
-
-        qiskit_circuit = QuantumCircuit.from_qasm_str(circuit)
+    def set_seed(self, seed: int):
+        """
+        Set the random seed for circuit simulation.
 
-        resolved_backend = (
-            _find_best_fake_backend(qiskit_circuit)[-1]()
-            if qiskit_backend == "auto"
-            else qiskit_backend
-        )
+        Args:
+            seed (int): Seed value for the random number generator used in simulation.
+        """
+        self.simulation_seed = seed
 
-        aer_simulator = (
-            AerSimulator.from_backend(resolved_backend)
-            if qiskit_backend
-            else AerSimulator(noise_model=noise_model)
-        )
-        transpiled_circuit = transpile(qiskit_circuit, aer_simulator)
+    def _execute_circuits_deterministically(
+        self, circuit_labels: list[str], transpiled_circuits: list, resolved_backend
+    ) -> list[dict]:
+        """
+        Execute circuits individually for debugging purposes.
 
-        aer_simulator.set_option("seed_simulator", simulation_seed)
-        job = aer_simulator.run(transpiled_circuit, shots=shots)
+        This method ensures deterministic results by running each circuit with its own
+        simulator instance and the same seed. Used internally for debugging non-deterministic
+        behavior in batch execution.
 
-        result = job.result()
-        counts = result.get_counts(0)
+        Args:
+            circuit_labels: List of circuit labels
+            transpiled_circuits: List of transpiled QuantumCircuit objects
+            resolved_backend: Resolved backend for simulator creation
 
-        return {"label": circuit_label, "results": dict(counts)}
+        Returns:
+            List of result dictionaries
+        """
+        results = []
+        for i, (label, transpiled_circuit) in enumerate(
+            zip(circuit_labels, transpiled_circuits)
+        ):
+            # Create a new simulator instance for each circuit with the same seed
+            if resolved_backend is not None:
+                circuit_simulator = AerSimulator.from_backend(resolved_backend)
+            else:
+                circuit_simulator = AerSimulator(noise_model=self.noise_model)
+
+            if self.simulation_seed is not None:
+                circuit_simulator.set_option("seed_simulator", self.simulation_seed)
+
+            # Run the single circuit
+            job = circuit_simulator.run(transpiled_circuit, shots=self.shots)
+            circuit_result = job.result()
+            counts = circuit_result.get_counts(0)
+            results.append({"label": label, "results": dict(counts)})
 
-    def set_seed(self, seed: int):
-        self.simulation_seed = seed
+        return results
 
     def submit_circuits(self, circuits: dict[str, str]):
+        """
+        Submit multiple circuits for parallel simulation using Qiskit's built-in parallelism.
+
+        Uses Qiskit's native batch transpilation and execution, which handles parallelism
+        internally.
+
+        Args:
+            circuits (dict[str, str]): Dictionary mapping circuit labels to OpenQASM
+                string representations.
+
+        Returns:
+            list[dict]: List of result dictionaries, each containing:
+                - 'label' (str): Circuit identifier
+                - 'results' (dict): Measurement counts as {bitstring: count}
+        """
         logger.debug(
             f"Simulating {len(circuits)} circuits with {self.n_processes} processes"
         )
 
-        with Pool(processes=self.n_processes) as pool:
-            results = pool.starmap(
-                self.simulate_circuit,
-                [
-                    (
-                        circuit,
-                        self.shots,
-                        self.simulation_seed,
-                        self.qiskit_backend,
-                        self.noise_model,
-                    )
-                    for circuit in circuits.items()
-                ],
+        # Convert QASM strings to QuantumCircuit objects
+        circuit_labels = list(circuits.keys())
+        qiskit_circuits = [
+            QuantumCircuit.from_qasm_str(qasm) for qasm in circuits.values()
+        ]
+
+        # Determine backend for transpilation
+        if self.qiskit_backend == "auto":
+            # For "auto", find the maximum number of qubits across all circuits to determine backend
+            max_qubits_circ = max(qiskit_circuits, key=lambda x: x.num_qubits)
+            resolved_backend = _find_best_fake_backend(max_qubits_circ)[-1]()
+        elif self.qiskit_backend is not None:
+            resolved_backend = self.qiskit_backend
+        else:
+            resolved_backend = None
+
+        # Create simulator
+        if resolved_backend is not None:
+            aer_simulator = AerSimulator.from_backend(resolved_backend)
+        else:
+            aer_simulator = AerSimulator(noise_model=self.noise_model)
+
+        # Set simulator options for parallelism
+        # Note: We don't set seed_simulator here because we need different seeds for each circuit
+        # to ensure deterministic results when running multiple circuits in parallel
+        aer_simulator.set_options(max_parallel_experiments=self.n_processes)
+
+        # Batch transpile all circuits (Qiskit handles parallelism internally)
+        transpiled_circuits = transpile(
+            qiskit_circuits, aer_simulator, num_processes=self.n_processes
+        )
+
+        # Use deterministic execution for debugging if enabled
+        if self._deterministic_execution:
+            return self._execute_circuits_deterministically(
+                circuit_labels, transpiled_circuits, resolved_backend
             )
+
+        # Batch execution with metadata checking for non-deterministic behavior
+        job = aer_simulator.run(transpiled_circuits, shots=self.shots)
+        batch_result = job.result()
+
+        # Check metadata to detect non-deterministic behavior
+        metadata = batch_result.metadata
+        parallel_experiments = metadata.get("parallel_experiments", 1)
+        omp_nested = metadata.get("omp_nested", False)
+
+        # If parallel execution is detected and we have a seed, warn about potential non-determinism
+        if parallel_experiments > 1 and self.simulation_seed is not None:
+            logger.warning(
+                f"Parallel execution detected (parallel_experiments={parallel_experiments}, "
+                f"omp_nested={omp_nested}). Results may not be deterministic across different "
+                "grouping strategies. Consider enabling deterministic mode for "
+                "deterministic results."
+            )
+
+        # Extract results and match with labels
+        results = []
+        for i, label in enumerate(circuit_labels):
+            counts = batch_result.get_counts(i)
+            results.append({"label": label, "results": dict(counts)})
+
         return results
 
     @staticmethod
@@ -186,15 +266,18 @@ class ParallelSimulator(CircuitRunner):
 
             op_name = node.name
 
+            # Determine qubit indices for the operation
             if node.num_clbits == 1:
                 idx = (node.cargs[0]._index,)
-
-            if op_name != "measure" and node.num_qubits > 0:
+            elif op_name != "measure" and node.num_qubits > 0:
                 idx = tuple(qarg._index for qarg in node.qargs)
+            else:
+                # Skip operations without qubits or measurements without classical bits
+                continue
 
             try:
                 total_run_time_s += (
-                    qiskit_backend.instruction_durations.duration_by_name_qubits[
+                    resolved_backend.instruction_durations.duration_by_name_qubits[
                         (op_name, idx)
                     ][0]
                 )
@@ -208,7 +291,7 @@ class ParallelSimulator(CircuitRunner):
     @staticmethod
     def estimate_run_time_batch(
         circuits: list[str] | None = None,
-        precomputed_duration: list[float] | None = None,
+        precomputed_durations: list[float] | None = None,
         n_qpus: int = 5,
         **transpilation_kwargs,
     ) -> float:
@@ -225,7 +308,7 @@ class ParallelSimulator(CircuitRunner):
         """
 
         # Compute the run time estimates for each given circuit, in descending order
-        if precomputed_duration is None:
+        if precomputed_durations is None:
             with Pool() as p:
                 estimated_run_times = p.map(
                     partial(
@@ -237,7 +320,7 @@ class ParallelSimulator(CircuitRunner):
                 )
             estimated_run_times_sorted = sorted(estimated_run_times, reverse=True)
         else:
-            estimated_run_times_sorted = sorted(precomputed_duration, reverse=True)
+            estimated_run_times_sorted = sorted(precomputed_durations, reverse=True)
 
         # Just return the longest run time if there are enough QPUs
         if n_qpus >= len(estimated_run_times_sorted):