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

divi/qprog/quantum_program.py

@@ -1,493 +1,324 @@
-# 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
 
-import logging
-import pickle
 from abc import ABC, abstractmethod
-from functools import partial
+from http import HTTPStatus
 from queue import Queue
-from typing import Optional
+from threading import Event
+from typing import Any
+from warnings import warn
 
-import numpy as np
-from qiskit.result import marginal_counts, sampled_expectation_value
-from scipy.optimize import OptimizeResult, minimize
+import requests
 
-from divi import QoroService
-from divi.circuits import Circuit, MetaCircuit
-from divi.exp.scipy._cobyla import _minimize_cobyla as cobyla_fn
-from divi.interfaces import CircuitRunner
-from divi.qem import _NoMitigation
-from divi.qoro_service import JobStatus
-from divi.qprog.optimizers import Optimizer
-
-logger = logging.getLogger(__name__)
+from divi.backends import CircuitRunner, JobStatus
+from divi.backends._execution_result import ExecutionResult
+from divi.circuits import CircuitBundle
+from divi.qprog.exceptions import _CancelledError
+from divi.reporting import LoggingProgressReporter, QueueProgressReporter
 
 
 class QuantumProgram(ABC):
+    """Abstract base class for quantum programs.
+
+    This class defines the interface and provides common functionality for quantum algorithms.
+    It handles circuit execution, result processing, and data persistence.
+
+    Subclasses must implement:
+        - run(): Execute the quantum algorithm
+        - _generate_circuits(): Generate quantum circuits for execution
+        - _post_process_results(): Process execution results
+
+    Attributes:
+        backend (CircuitRunner): The quantum circuit execution backend.
+        _seed (int | None): Random seed for reproducible results.
+        _progress_queue (Queue | None): Queue for progress reporting.
+        _circuits (list): List of circuits to be executed.
+    """
+
     def __init__(
         self,
         backend: CircuitRunner,
-        seed: Optional[int] = None,
-        progress_queue: Optional[Queue] = None,
+        seed: int | None = None,
+        progress_queue: Queue | None = None,
         **kwargs,
     ):
-        """
-        Initializes the QuantumProgram class.
-
-        If a child class represents a hybrid quantum-classical algorithm,
-        the instance variables `n_layers` and `n_params` must be set, where:
-        - `n_layers` is the number of layers in the quantum circuit.
-        - `n_params` is the number of parameters per layer.
-
-        For exotic algorithms where these variables may not be applicable,
-        the `_initialize_params` method should be overridden to set the parameters.
+        """Initialize the QuantumProgram.
 
         Args:
-            backend (CircuitRunner): An instance of a CircuitRunner object, which
-                can either be ParallelSimulator or QoroService.
-            seed (int): A seed for numpy's random number generator, which will
-                be used for the parameter initialization.
-                Defaults to None.
-            progress_queue (Queue): a queue for progress bar updates.
-
-            **kwargs: Additional keyword arguments that influence behaviour.
-                - grouping_strategy (Optional[Any]): A strategy for grouping operations, used in Pennylane's transforms.
-                    Defaults to None.
-                - qem_protocol (Optional[QEMProtocol]): the quantum error mitigation protocol to apply.
-                    Must be of type QEMProtocol. Defaults to None.
-
-                The following key values are reserved for internal use and should not be set by the user:
-                - losses (Optional[list]): A list to initialize the `losses` attribute. Defaults to an empty list.
-                - final_params (Optional[list]): A list to initialize the `final_params` attribute. Defaults to an empty list.
-
+            backend (CircuitRunner): Quantum circuit execution backend.
+            seed (int | None): Random seed for reproducible results. Defaults to None.
+            progress_queue (Queue | None): Queue for progress reporting. Defaults to None.
+            **kwargs: Additional keyword arguments for subclasses.
+                program_id (str | None): Program identifier for progress reporting in batch
+                operations. If provided along with progress_queue, enables queue-based
+                progress reporting.
         """
-
-        # Shared Variables
-        self.losses = kwargs.pop("losses", [])
-        self.final_params = kwargs.pop("final_params", [])
-
-        self.circuits: list[Circuit] = []
-
+        self.backend = backend
+        self._seed = seed
+        self._progress_queue = progress_queue
         self._total_circuit_count = 0
         self._total_run_time = 0.0
-        self._curr_params = []
-
-        self._seed = seed
-        self._rng = np.random.default_rng(self._seed)
+        self._curr_circuits = []
+        self._current_execution_result = None
 
-        # Lets child classes adapt their optimization
-        # step for grad calculation routine
-        self._grad_mode = False
-
-        self.backend = backend
-        self.job_id = kwargs.get("job_id", None)
-
-        self._progress_queue = progress_queue
+        # --- Progress Reporting ---
+        self.program_id = kwargs.get("program_id", None)
+        if progress_queue and self.program_id is not None:
+            self.reporter = QueueProgressReporter(self.program_id, progress_queue)
+        else:
+            self.reporter = LoggingProgressReporter()
 
-        # Needed for Pennylane's transforms
-        self._grouping_strategy = kwargs.pop("grouping_strategy", None)
+    @abstractmethod
+    def run(self, **kwargs) -> tuple[int, float]:
+        """Execute the quantum algorithm.
 
-        self._qem_protocol = kwargs.pop("qem_protocol", None) or _NoMitigation()
+        Args:
+            **kwargs: Additional keyword arguments for subclasses.
 
-        self._meta_circuit_factory = partial(
-            MetaCircuit,
-            grouping_strategy=self._grouping_strategy,
-            qem_protocol=self._qem_protocol,
-        )
+        Returns:
+            tuple[int, float]: A tuple containing:
+                - int: Total number of circuits executed
+                - float: Total runtime in seconds
+        """
+        pass
 
-    @property
-    def total_circuit_count(self):
-        return self._total_circuit_count
+    @abstractmethod
+    def _generate_circuits(self, **kwargs) -> list[CircuitBundle]:
+        """Generate quantum circuits for execution.
 
-    @property
-    def total_run_time(self):
-        return self._total_run_time
+        This method should generate and return a list of CircuitBundle objects based on
+        the current algorithm state. The circuits will be executed by the backend.
 
-    @property
-    def meta_circuits(self):
-        return self._meta_circuits
+        Args:
+            **kwargs: Additional keyword arguments for circuit generation.
 
-    @abstractmethod
-    def _create_meta_circuits_dict(self) -> dict[str, MetaCircuit]:
+        Returns:
+            list[CircuitBundle]: List of CircuitBundle objects to be executed.
+        """
         pass
 
     @abstractmethod
-    def _generate_circuits(self, **kwargs):
-        pass
-
-    def _initialize_params(self):
-        self._curr_params = np.array(
-            [
-                self._rng.uniform(0, 2 * np.pi, self.n_layers * self.n_params)
-                for _ in range(self.optimizer.n_param_sets)
-            ]
-        )
+    def _post_process_results(self, results: dict, **kwargs) -> Any:
+        """Process execution results.
 
-    def _run_optimization_circuits(self, store_data, data_file):
-        self.circuits[:] = []
+        Args:
+            results (dict): Raw results from circuit execution.
 
-        self._generate_circuits()
+        Returns:
+            Any: Processed results specific to the algorithm.
+        """
+        pass
 
-        losses = self._dispatch_circuits_and_process_results(
-            store_data=store_data, data_file=data_file
-        )
+    def _set_cancellation_event(self, event: Event):
+        """Set a cancellation event for graceful program termination.
 
-        return losses
+        This method is called by batch runners to provide a mechanism
+        for stopping the optimization loop cleanly when requested.
 
-    def _update_mc_params(self):
-        """
-        Updates the parameters based on previous MC iteration.
+        Args:
+            event (Event): Threading Event object that signals cancellation when set.
         """
+        self._cancellation_event = event
 
-        if self.current_iteration == 0:
-            self._initialize_params()
+    @property
+    def total_circuit_count(self) -> int:
+        """Get the total number of circuits executed.
 
-            self.current_iteration += 1
+        Returns:
+            int: Cumulative count of circuits submitted for execution.
+        """
+        return self._total_circuit_count
 
-            return
+    @property
+    def total_run_time(self) -> float:
+        """Get the total runtime across all circuit executions.
 
-        self._curr_params = self.optimizer.compute_new_parameters(
-            self._curr_params,
-            self.current_iteration,
-            losses=self.losses[-1],
-            rng=self._rng,
-        )
+        Returns:
+            float: Cumulative execution time in seconds.
+        """
+        return self._total_run_time
 
-        self.current_iteration += 1
+    def _prepare_and_send_circuits(self, **kwargs) -> ExecutionResult:
+        """Prepare circuits for execution and submit them to the backend.
 
-    def _prepare_and_send_circuits(self):
+        Returns:
+            ExecutionResult: Result from circuit submission. For async backends,
+                contains job_id. For sync backends, contains results directly.
+        """
         job_circuits = {}
+        self._reset_tag_cache()
 
-        for circuit in self.circuits:
-            for tag, qasm_circuit in zip(circuit.tags, circuit.qasm_circuits):
-                job_circuits[tag] = qasm_circuit
+        for bundle in self._curr_circuits:
+            for executable in bundle.executables:
+                job_circuits[self._encode_tag(executable.tag)] = executable.qasm
 
         self._total_circuit_count += len(job_circuits)
 
-        backend_output = self.backend.submit_circuits(job_circuits)
-
-        if isinstance(self.backend, QoroService):
-            self._curr_service_job_id = backend_output
+        execution_result = self.backend.submit_circuits(job_circuits, **kwargs)
 
-        return backend_output
+        return execution_result
 
-    def _dispatch_circuits_and_process_results(self, store_data=False, data_file=None):
-        """
-        Run an iteration of the program. The outputs are stored in the Program object.
-        Optionally, the data can be stored in a file.
+    def _track_runtime(self, response):
+        """Extract and track runtime from a backend response.
 
         Args:
-            store_data (bool): Whether to store the data for the iteration
-            data_file (str): The file to store the data in
+            response: Backend response containing runtime information.
+                Can be a dict or a list of responses.
         """
+        if isinstance(response, dict):
+            self._total_run_time += float(response["run_time"])
+        elif isinstance(response, list):
+            self._total_run_time += sum(float(r.json()["run_time"]) for r in response)
 
-        results = self._prepare_and_send_circuits()
-
-        def add_run_time(response):
-            if isinstance(response, dict):
-                self._total_run_time += float(response["run_time"])
-            elif isinstance(response, list):
-                self._total_run_time += sum(float(r["run_time"]) for r in response)
-
-        if isinstance(self.backend, QoroService):
-            status = self.backend.poll_job_status(
-                self._curr_service_job_id,
-                loop_until_complete=True,
-                on_complete=add_run_time,
-                **(
-                    {
-                        "pbar_update_fn": lambda n_polls: self._progress_queue.put(
-                            {
-                                "job_id": self.job_id,
-                                "progress": 0,
-                                "poll_attempt": n_polls,
-                            }
-                        )
-                    }
-                    if self._progress_queue is not None
-                    else {}
-                ),
-            )
-
-            if status != JobStatus.COMPLETED:
-                raise Exception(
-                    "Job has not completed yet, cannot post-process results"
-                )
-
-            results = self.backend.get_job_results(self._curr_service_job_id)
-
-        results = {r["label"]: r["results"] for r in results}
-
-        result = self._post_process_results(results)
-
-        if store_data:
-            self.save_iteration(data_file)
-
-        return result
-
-    def _post_process_results(
-        self, results: dict[str, dict[str, int]]
-    ) -> dict[int, float]:
-        """
-        Post-process the results of the quantum problem.
+    def _wait_for_qoro_job_completion(
+        self, execution_result: ExecutionResult
+    ) -> list[dict]:
+        """Wait for a QoroService job to complete and return results.
 
         Args:
-            results (dict): The shot histograms of the quantum execution step.
-                The keys should be strings of format {param_id}_*_{measurement_group_id}.
-                i.e. An underscore-separated bunch of metadata, starting always with
-                the index of some parameter and ending with the index of some measurement group.
-                Any extra piece of metadata that might be relevant to the specific application can
-                be kept in the middle.
+            execution_result: The ExecutionResult from circuit submission.
 
         Returns:
-            (dict) The energies for each parameter set grouping, where the dict keys
-                correspond to the parameter indices.
-        """
-
-        losses = {}
-        measurement_groups = self._meta_circuits["cost_circuit"].measurement_groups
-
-        for p in range(self._curr_params.shape[0]):
-            # Extract relevant entries from the execution results dict
-            param_results = {k: v for k, v in results.items() if k.startswith(f"{p}_")}
-
-            # Compute the marginal results for each observable
-            marginal_results = []
-            for group_idx, curr_measurement_group in enumerate(measurement_groups):
-                group_results = {
-                    k: v
-                    for k, v in param_results.items()
-                    if k.endswith(f"_{group_idx}")
-                }
-
-                curr_marginal_results = []
-                for observable in curr_measurement_group:
-                    intermediate_exp_values = [
-                        sampled_expectation_value(
-                            marginal_counts(shots_dict, observable.wires.tolist()),
-                            "Z" * len(observable.wires),
-                        )
-                        for shots_dict in group_results.values()
-                    ]
-
-                    mitigated_exp_value = self._qem_protocol.postprocess_results(
-                        intermediate_exp_values
-                    )
-
-                    curr_marginal_results.append(mitigated_exp_value)
-
-                marginal_results.append(
-                    curr_marginal_results
-                    if len(curr_marginal_results) > 1
-                    else curr_marginal_results[0]
-                )
-
-            pl_loss = (
-                self._meta_circuits["cost_circuit"]
-                .postprocessing_fn(marginal_results)[0]
-                .item()
-            )
-
-            losses[p] = pl_loss + self.loss_constant
-
-        return losses
+            list[dict]: The job results from the backend.
 
-    def run(self, store_data=False, data_file=None):
+        Raises:
+            Exception: If job fails or doesn't complete.
         """
-        Run the QAOA problem. The outputs are stored in the QAOA object. Optionally, the data can be stored in a file.
-
-        Args:
-            store_data (bool): Whether to store the data for the iteration
-            data_file (str): The file to store the data in
-        """
-
-        if self._progress_queue is not None:
-            self._progress_queue.put(
-                {
-                    "job_id": self.job_id,
-                    "message": "Finished Setup",
-                    "progress": 0,
-                }
+        job_id = execution_result.job_id
+        if job_id is None:
+            raise ValueError("ExecutionResult must have a job_id for async completion")
+
+        # Build the poll callback if reporter is available
+        if hasattr(self, "reporter"):
+            update_function = lambda n_polls, status: self.reporter.info(
+                message="",
+                poll_attempt=n_polls,
+                max_retries=self.backend.max_retries,
+                service_job_id=job_id,
+                job_status=status,
             )
         else:
-            logger.info("Finished Setup")
-
-        if self.optimizer == Optimizer.MONTE_CARLO:
-            while self.current_iteration < self.max_iterations:
-
-                self._update_mc_params()
-
-                if self._progress_queue is not None:
-                    self._progress_queue.put(
-                        {
-                            "job_id": self.job_id,
-                            "message": f"⛰️ Sampling from Loss Lansdscape ⛰️",
-                            "progress": 0,
-                        }
-                    )
-                else:
-                    logger.info(
-                        f"Running Iteration #{self.current_iteration} circuits\r"
-                    )
-
-                curr_losses = self._run_optimization_circuits(store_data, data_file)
-
-                if self._progress_queue is not None:
-                    self._progress_queue.put(
-                        {
-                            "job_id": self.job_id,
-                            "progress": 1,
-                        }
-                    )
-                else:
-                    logger.info(f"Finished Iteration #{self.current_iteration}\r\n")
-
-                self.losses.append(curr_losses)
-
-            self.final_params[:] = np.atleast_2d(self._curr_params)
-
-        elif self.optimizer in (
-            Optimizer.NELDER_MEAD,
-            Optimizer.L_BFGS_B,
-            Optimizer.COBYLA,
-        ):
-
-            def cost_fn(params):
-                task_name = "💸 Computing Cost 💸"
-
-                if self._progress_queue is not None:
-                    self._progress_queue.put(
-                        {
-                            "job_id": self.job_id,
-                            "message": task_name,
-                            "progress": 0,
-                        }
-                    )
-                else:
-                    logger.info(
-                        f"Running Iteration #{self.current_iteration + 1} circuits: {task_name}\r"
-                    )
-
-                self._curr_params = np.atleast_2d(params)
-
-                losses = self._run_optimization_circuits(store_data, data_file)
+            update_function = None
+
+        # Poll until complete
+        status = self.backend.poll_job_status(
+            execution_result,
+            loop_until_complete=True,
+            on_complete=self._track_runtime,
+            verbose=False,  # Disable the default logger in QoroService
+            progress_callback=update_function,
+        )
 
-                return losses[0]
+        if status == JobStatus.FAILED:
+            raise RuntimeError(f"Job {job_id} has failed")
+
+        if status == JobStatus.CANCELLED:
+            # If cancellation was requested (e.g., by ProgramBatch), raise _CancelledError
+            # so it's handled gracefully. Otherwise, raise RuntimeError for unexpected cancellation.
+            if (
+                hasattr(self, "_cancellation_event")
+                and self._cancellation_event
+                and self._cancellation_event.is_set()
+            ):
+                raise _CancelledError(f"Job {job_id} was cancelled")
+            raise RuntimeError(f"Job {job_id} was cancelled")
+
+        if status != JobStatus.COMPLETED:
+            raise Exception("Job has not completed yet, cannot post-process results")
+        completed_result = self.backend.get_job_results(execution_result)
+        return completed_result.results
+
+    def cancel_unfinished_job(self):
+        """Cancel the currently running cloud job if one exists.
+
+        This method attempts to cancel the job associated with the current
+        ExecutionResult. It is best-effort and will log warnings for any errors
+        (e.g., job already completed, permission denied) without raising exceptions.
+
+        This is typically called by ProgramBatch when handling cancellation
+        to ensure cloud jobs are cancelled before local threads terminate.
+        """
 
-            def grad_fn(params):
-                self._grad_mode = True
+        if self._current_execution_result is None:
+            warn("Cannot cancel job: no current execution result", stacklevel=2)
+            return
 
-                task_name = "📈 Computing Gradients 📈"
+        if self._current_execution_result.job_id is None:
+            warn("Cannot cancel job: execution result has no job_id", stacklevel=2)
+            return
 
-                if self._progress_queue is not None:
-                    self._progress_queue.put(
-                        {
-                            "job_id": self.job_id,
-                            "message": task_name,
-                            "progress": 0,
-                        }
+        try:
+            self.backend.cancel_job(self._current_execution_result)
+        except requests.exceptions.HTTPError as e:
+            # Check if this is an expected error (job already completed/failed/cancelled)
+            if (
+                hasattr(e, "response")
+                and e.response is not None
+                and e.response.status_code == HTTPStatus.CONFLICT
+            ):
+                # 409 Conflict means job is already in a terminal state - this is expected
+                # in race conditions where job completes before we can cancel it.
+                if hasattr(self, "reporter"):
+                    self.reporter.info(
+                        f"Job {self._current_execution_result.job_id} already completed or cancelled"
                     )
-                else:
-                    logger.info(
-                        f"Running Iteration #{self.current_iteration + 1} circuits: {task_name}\r"
+            else:
+                # Unexpected error (403 Forbidden, 404 Not Found, etc.) - report it
+                if hasattr(self, "reporter"):
+                    self.reporter.info(
+                        f"Failed to cancel job {self._current_execution_result.job_id}: {e}"
                     )
+        except Exception as e:
+            # Other unexpected errors - report them
+            if hasattr(self, "reporter"):
+                self.reporter.info(
+                    f"Failed to cancel job {self._current_execution_result.job_id}: {e}"
+                )
 
-                shift_mask = self.optimizer.compute_parameter_shift_mask(len(params))
-
-                self._curr_params = shift_mask + params
-
-                exp_vals = self._run_optimization_circuits(store_data, data_file)
-
-                grads = np.zeros_like(params)
-                for i in range(len(params)):
-                    grads[i] = 0.5 * (exp_vals[2 * i] - exp_vals[2 * i + 1])
-
-                self._grad_mode = False
+    def _dispatch_circuits_and_process_results(self, **kwargs):
+        """Run an iteration of the program.
 
-                return grads
+        The outputs are stored in the Program object.
 
-            def _iteration_counter(intermediate_result: OptimizeResult):
-                self.losses.append({0: intermediate_result.fun})
+        Args:
+            **kwargs: Additional keyword arguments for circuit submission and result processing.
 
-                self.final_params[:] = np.atleast_2d(intermediate_result.x)
+        Returns:
+            Any: Processed results from _post_process_results.
+        """
+        execution_result = self._prepare_and_send_circuits(**kwargs)
 
-                self.current_iteration += 1
+        # Store the execution result for potential cancellation
+        self._current_execution_result = execution_result
 
-                if self._progress_queue is not None:
-                    self._progress_queue.put(
-                        {
-                            "job_id": self.job_id,
-                            "progress": 1,
-                        }
-                    )
-                else:
-                    logger.info(f"Finished Iteration #{self.current_iteration}\r\n")
-
-                if (
-                    self.optimizer == Optimizer.COBYLA
-                    and intermediate_result.nit + 1 == self.max_iterations
-                ):
-                    raise StopIteration
-
-            if self.max_iterations is None or self.optimizer == Optimizer.COBYLA:
-                # COBYLA perceive maxiter as maxfev so we need
-                # to use the callback fn for counting instead.
-                maxiter = None
+        try:
+            # For async backends, poll for results
+            if execution_result.job_id is not None:
+                results = self._wait_for_qoro_job_completion(execution_result)
             else:
-                # Need to add one more iteration for Nelder-Mead's simplex initialization step
-                maxiter = (
-                    self.max_iterations + 1
-                    if self.optimizer == Optimizer.NELDER_MEAD
-                    else self.max_iterations
-                )
-
-            self._initialize_params()
-            self._minimize_res = minimize(
-                fun=cost_fn,
-                x0=self._curr_params[0],
-                method=(
-                    cobyla_fn
-                    if self.optimizer == Optimizer.COBYLA
-                    else self.optimizer.value
-                ),
-                jac=grad_fn if self.optimizer == Optimizer.L_BFGS_B else None,
-                callback=_iteration_counter,
-                options={"maxiter": maxiter},
-            )
-
-        if self._progress_queue:
-            self._progress_queue.put(
-                {
-                    "job_id": self.job_id,
-                    "progress": 0,
-                    "final_status": "Success",
-                }
-            )
-        else:
-            logger.info(f"Finished Optimization!")
-
-        return self._total_circuit_count, self._total_run_time
+                # For sync backends, results are already available
+                results = execution_result.results
+                if results is None:
+                    raise ValueError("ExecutionResult has neither results nor job_id")
 
-    def save_iteration(self, data_file):
-        """
-        Save the current iteration of the program to a file.
+            results = {r["label"]: r["results"] for r in results}
+            results = self._decode_tags(results)
 
-        Args:
-            data_file (str): The file to save the iteration to.
-        """
+            result = self._post_process_results(results, **kwargs)
 
-        with open(data_file, "wb") as f:
-            pickle.dump(self, f)
+            return result
+        finally:
+            # Clear the execution result after processing
+            self._current_execution_result = None
 
-    @staticmethod
-    def import_iteration(data_file):
-        """
-        Import an iteration of the program from a file.
+    def _reset_tag_cache(self) -> None:
+        """Hook to reset per-run tag caches. Default is no-op."""
 
-        Args:
-            data_file (str): The file to import the iteration from.
-        """
+    def _encode_tag(self, tag: Any) -> str:
+        """Convert a tag to a backend-safe string."""
+        return str(tag)
 
-        with open(data_file, "rb") as f:
-            return pickle.load(f)
+    def _decode_tags(self, results: dict[str, dict[str, int]]) -> dict:
+        """Restore structured tags from backend result labels."""
+        return results