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

divi/qprog/quantum_program.py

@@ -2,211 +2,35 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-import logging
 import pickle
 from abc import ABC, abstractmethod
-from functools import lru_cache, partial
-from itertools import groupby
 from queue import Queue
 from threading import Event
+from typing import Any
 
-import numpy as np
-import pennylane as qml
-from scipy.optimize import OptimizeResult
+from divi.backends import CircuitRunner, JobStatus
+from divi.circuits import Circuit
 
-from divi.backends import CircuitRunner, JobStatus, QoroService
-from divi.circuits import Circuit, MetaCircuit
-from divi.circuits.qem import _NoMitigation
-from divi.qprog.exceptions import _CancelledError
-from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
-from divi.reporting import LoggingProgressReporter, QueueProgressReporter
 
-logger = logging.getLogger(__name__)
-
-
-def _get_structural_key(obs: qml.operation.Operation) -> tuple[str, ...]:
-    """Generates a hashable, wire-independent key from an observable's structure.
-
-    This function is used to create a canonical representation of an observable
-    based on its constituent Pauli operators, ignoring the wires they act on.
-    This key is ideal for caching computed eigenvalues, as observables with the
-    same structure (e.g., PauliX(0) @ PauliZ(1) and PauliX(2) @ PauliZ(3))
-    share the same eigenvalues. It maps PauliX and PauliY to PauliZ because
-    they are all isospectral (have eigenvalues [1, -1]).
-
-    Args:
-        obs: A PennyLane observable (e.g., qml.PauliZ(0), qml.PauliX(0) @ qml.PauliY(1)).
-
-    Returns:
-        A tuple of strings representing the structure of the observable,
-        e.g., ('PauliZ',) or ('PauliZ', 'PauliZ').
-    """
-
-    # Pennylane returns the same eigenvalues for PauliX and PauliY
-    # since it handles diagonalizing gates internally anyway
-    name_map = {
-        "PauliY": "PauliZ",
-        "PauliX": "PauliZ",
-        "PauliZ": "PauliZ",
-        "Identity": "Identity",
-    }
-
-    if isinstance(obs, qml.ops.Prod):
-        # Recursively build a tuple of operator names
-        return tuple(name_map[o.name] for o in obs.operands)
-
-    # For single operators, return a single-element tuple
-    return (name_map[obs.name],)
-
-
-@lru_cache(maxsize=512)
-def _get_eigvals_from_key(key: tuple[str, ...]) -> np.ndarray:
-    """Computes and caches eigenvalues based on a structural key.
-
-    This function takes a key generated by `_get_structural_key` and computes
-    the eigenvalues of the corresponding tensor product of operators. The results
-    are memoized using @lru_cache to avoid redundant calculations.
-
-    Args:
-        key: A tuple of strings representing the observable's structure.
-
-    Returns:
-        A NumPy array containing the eigenvalues of the observable.
-    """
-
-    # Define a mapping from name to the base eigenvalue array
-    eigvals_map = {
-        "PauliZ": np.array([1, -1], dtype=np.int8),
-        "Identity": np.array([1, 1], dtype=np.int8),
-    }
-
-    # Start with the eigenvalues of the first operator in the key
-    final_eigvals = eigvals_map[key[0]]
-
-    # Iteratively compute the kronecker product for the rest
-    for op_name in key[1:]:
-        final_eigvals = np.kron(final_eigvals, eigvals_map[op_name])
-
-    return final_eigvals
-
-
-def _batched_expectation(shots_dicts, observables, wire_order):
-    """Efficiently calculates expectation values for multiple observables across multiple shot histograms.
-
-    This function is optimized to compute expectation values in a fully vectorized
-    manner, minimizing Python loops. It operates in four main steps:
-    1. Aggregates all unique bitstrings measured across all histograms.
-    2. Builds a "reduced" eigenvalue matrix corresponding only to the unique states.
-    3. Builds a "reduced" probability matrix from the shot counts for each histogram.
-    4. Computes all expectation values with a single matrix multiplication.
-
-    Args:
-        shots_dicts (list[dict[str, int]]): A list of shot dictionaries (histograms),
-            where each dictionary maps a measured bitstring to its count.
-        observables (list[qml.operation.Operation]): A list of PennyLane observables
-            for which to calculate expectation values.
-        wire_order (tuple[int, ...]): A tuple defining the order of wires, which maps
-            the bitstring to the qubits. Note: This is typically the reverse of the
-            qubit indices (e.g., (2, 1, 0) for a 3-qubit system).
-
-    Returns:
-        np.ndarray: A 2D NumPy array of shape (n_observables, n_shots) where
-            result[i, j] is the expectation value of observables[i] for the
-            histogram in shots_dicts[j].
-    """
-
-    n_histograms = len(shots_dicts)
-    n_total_wires = len(wire_order)
-    n_observables = len(observables)
-
-    # --- 1. Aggregate all unique measured states across all shots ---
-    all_measured_bitstrings = set()
-    for sd in shots_dicts:
-        all_measured_bitstrings.update(sd.keys())
-
-    unique_bitstrings = sorted(list(all_measured_bitstrings))
-    n_unique_states = len(unique_bitstrings)
-
-    bitstring_to_idx_map = {bs: i for i, bs in enumerate(unique_bitstrings)}
-
-    # --- 2. Build REDUCED Eigenvalue Matrix: (n_observables, n_unique_states) ---
-    unique_states_int = np.array(
-        [int(bs, 2) for bs in unique_bitstrings], dtype=np.uint64
-    )
-    reduced_eigvals_matrix = np.zeros((n_observables, n_unique_states))
-    wire_map = {w: i for i, w in enumerate(wire_order)}
-
-    powers_cache = {}
-
-    for obs_idx, observable in enumerate(observables):
-        obs_wires = observable.wires
-        n_obs_wires = len(obs_wires)
-
-        if n_obs_wires in powers_cache:
-            powers = powers_cache[n_obs_wires]
-        else:
-            powers = 2 ** np.arange(n_obs_wires - 1, -1, -1, dtype=np.intp)
-            powers_cache[n_obs_wires] = powers
-
-        obs_wire_indices = np.array([wire_map[w] for w in obs_wires], dtype=np.uint32)
-        eigvals = _get_eigvals_from_key(_get_structural_key(observable))
-
-        # Vectorized mapping, but on the *reduced* set of states
-        shifts = n_total_wires - 1 - obs_wire_indices
-        bits = ((unique_states_int[:, np.newaxis] >> shifts) & 1).astype(np.intp)
-        # powers = 2 ** np.arange(n_obs_wires - 1, -1, -1)
-
-        # obs_state_indices = (bits * powers).sum(axis=1).astype(np.intp)
-        obs_state_indices = np.dot(bits, powers)
-
-        reduced_eigvals_matrix[obs_idx, :] = eigvals[obs_state_indices]
-
-    # --- 3. Build REDUCED Probability Matrix: (n_shots, n_unique_states) ---
-    reduced_prob_matrix = np.zeros((n_histograms, n_unique_states), dtype=np.float32)
-    for i, shots_dict in enumerate(shots_dicts):
-        total = sum(shots_dict.values())
-
-        for bitstring, count in shots_dict.items():
-            col_idx = bitstring_to_idx_map[bitstring]
-            reduced_prob_matrix[i, col_idx] = count / total
-
-    # --- 4. Compute Final Expectation Values ---
-    # (n_shots, n_unique_states) @ (n_unique_states, n_observables)
-    result = reduced_prob_matrix @ reduced_eigvals_matrix.T
-
-    # Transpose to (n_observables, n_shots) as expected by the calling code
-    return result.T
-
-
-def _compute_parameter_shift_mask(n_params):
-    """
-    Generate a binary matrix mask for the parameter shift rule.
-    This mask is used to determine the shifts to apply to each parameter
-    when computing gradients via the parameter shift rule in quantum algorithms.
-
-    Args:
-        n_params (int): The number of parameters in the quantum circuit.
-
-    Returns:
-        np.ndarray: A (2 * n_params, n_params) matrix where each row encodes
-            the shift to apply to each parameter for a single evaluation.
-            The values are multiples of 0.5 * pi, with alternating signs.
+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.
+        _curr_service_job_id: Current service job ID for QoroService backends.
     """
-    mask_arr = np.arange(0, 2 * n_params, 2)
-    mask_arr[0] = 1
-
-    binary_matrix = ((mask_arr[:, np.newaxis] & (1 << np.arange(n_params))) > 0).astype(
-        np.float64
-    )
-
-    binary_matrix = binary_matrix.repeat(2, axis=0)
-    binary_matrix[1::2] *= -1
-    binary_matrix *= 0.5 * np.pi
-
-    return binary_matrix
 
-
-class QuantumProgram(ABC):
     def __init__(
         self,
         backend: CircuitRunner,
@@ -214,192 +38,68 @@ class QuantumProgram(ABC):
         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 (Literal["default", "wires", "qwc"]): A strategy for grouping operations, used in Pennylane's transforms.
-                    Defaults to None.
-                - qem_protocol (QEMProtocol, optional): the quantum error mitigation protocol to apply.
-                    Must be of type QEMProtocol. Defaults to None.
+            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.
         """
-
-        self._losses = []
-        self._final_params = []
-
-        self._circuits: list[Circuit] = []
-
-        self._total_circuit_count = 0
-        self._total_run_time = 0.0
-        self._curr_params = None
-
-        self._seed = seed
-        self._rng = np.random.default_rng(self._seed)
-
-        # 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._seed = seed
         self._progress_queue = progress_queue
-        if progress_queue and self.job_id:
-            self.reporter = QueueProgressReporter(self.job_id, progress_queue)
-        else:
-            self.reporter = LoggingProgressReporter()
-
-        # Needed for Pennylane's transforms
-        self._grouping_strategy = kwargs.pop("grouping_strategy", None)
-
-        self._qem_protocol = kwargs.pop("qem_protocol", None) or _NoMitigation()
-
-        self._cancellation_event = None
-
-        self._meta_circuit_factory = partial(
-            MetaCircuit,
-            grouping_strategy=self._grouping_strategy,
-            qem_protocol=self._qem_protocol,
-        )
-
-    @property
-    def total_circuit_count(self):
-        """
-        Get the total number of circuits executed so far.
-
-        Returns:
-            int: Cumulative count of circuits submitted for execution.
-        """
-        return self._total_circuit_count
-
-    @property
-    def total_run_time(self):
-        """
-        Get the total runtime across all circuit executions.
-
-        Returns:
-            float: Cumulative execution time in seconds.
-        """
-        return self._total_run_time
-
-    @property
-    def meta_circuits(self):
-        """
-        Get the meta-circuit templates used by this program.
-
-        Returns:
-            dict[str, MetaCircuit]: Dictionary mapping circuit names to their
-                MetaCircuit templates.
-        """
-        return self._meta_circuits
-
-    @property
-    def n_params(self):
-        """
-        Get the total number of parameters in the quantum circuit.
-
-        Returns:
-            int: Total number of trainable parameters (n_layers * n_params_per_layer).
-        """
-        return self._n_params
-
-    @property
-    def circuits(self) -> list[Circuit]:
-        """
-        Get a copy of the generated circuits list.
-
-        Returns:
-            list[Circuit]: Copy of the circuits list. Modifications to this list
-                will not affect the internal state.
-        """
-        return self._circuits.copy()
+        self._total_circuit_count = 0
+        self._total_run_time = 0.0
+        self._curr_circuits = []
+        self._curr_service_job_id = None
 
-    @property
-    def losses(self) -> list[dict]:
-        """
-        Get a copy of the optimization loss history.
+    @abstractmethod
+    def run(self, data_file: str | None = None, **kwargs) -> tuple[int, float]:
+        """Execute the quantum algorithm.
 
-        Each entry is a dictionary mapping parameter indices to loss values.
+        Args:
+            data_file (str | None): The file to store the data in. If None, no data is stored. Defaults to None.
+            **kwargs: Additional keyword arguments for subclasses.
 
         Returns:
-            list[dict]: Copy of the loss history. Modifications to this list
-                will not affect the internal state.
+            tuple[int, float]: A tuple containing:
+                - int: Total number of circuits executed
+                - float: Total runtime in seconds
         """
-        return self._losses.copy()
+        pass
 
-    @property
-    def final_params(self) -> list:
-        """
-        Get a copy of the final optimized parameters.
+    @abstractmethod
+    def _generate_circuits(self, **kwargs) -> list[Circuit]:
+        """Generate quantum circuits for execution.
 
-        Returns:
-            list: Copy of the final parameters. Modifications to this list
-                will not affect the internal state.
-        """
-        return self._final_params.copy()
+        This method should generate and return a list of Circuit objects based on
+        the current algorithm state. The circuits will be executed by the backend.
 
-    @property
-    def initial_params(self) -> np.ndarray:
-        """
-        Get the current initial parameters.
+        Args:
+            **kwargs: Additional keyword arguments for circuit generation.
 
         Returns:
-            np.ndarray: Current initial parameters. If not yet initialized,
-                they will be generated automatically.
+            list[Circuit]: List of Circuit objects to be executed.
         """
-        if self._curr_params is None:
-            self._initialize_params()
-        return self._curr_params.copy()
+        pass
 
-    @initial_params.setter
-    def initial_params(self, value: np.ndarray | None):
-        """
-        Set initial parameters.
+    @abstractmethod
+    def _post_process_results(self, results: dict, **kwargs) -> Any:
+        """Process execution results.
 
         Args:
-            value (np.ndarray | None): Initial parameters with shape
-                (n_param_sets, n_layers * n_params), or None to reset
-                to uninitialized state.
+            results (dict): Raw results from circuit execution.
 
-        Raises:
-            ValueError: If parameters have incorrect shape.
+        Returns:
+            Any: Processed results specific to the algorithm.
         """
-        if value is not None:
-            self._validate_initial_params(value)
-            self._curr_params = value.copy()
-        else:
-            # Reset to uninitialized state
-            self._curr_params = None
-
-    @abstractmethod
-    def _create_meta_circuits_dict(self) -> dict[str, MetaCircuit]:
-        pass
-
-    @abstractmethod
-    def _generate_circuits(self, **kwargs):
         pass
 
     def _set_cancellation_event(self, event: Event):
-        """
-        Set a cancellation event for graceful program termination.
+        """Set a cancellation event for graceful program termination.
 
-        This internal method is called by a batch runner to provide a mechanism
+        This method is called by batch runners to provide a mechanism
         for stopping the optimization loop cleanly when requested.
 
         Args:
@@ -407,324 +107,125 @@ class QuantumProgram(ABC):
         """
         self._cancellation_event = event
 
-    def get_expected_param_shape(self) -> tuple[int, int]:
-        """
-        Get the expected shape for initial parameters.
+    @property
+    def total_circuit_count(self) -> int:
+        """Get the total number of circuits executed.
 
         Returns:
-            tuple[int, int]: Shape (n_param_sets, n_layers * n_params) that
-                initial parameters should have for this quantum program.
-        """
-        return (self.optimizer.n_param_sets, self.n_layers * self.n_params)
-
-    def _validate_initial_params(self, params: np.ndarray):
+            int: Cumulative count of circuits submitted for execution.
         """
-        Validate user-provided initial parameters.
+        return self._total_circuit_count
 
-        Args:
-            params (np.ndarray): Parameters to validate.
+    @property
+    def total_run_time(self) -> float:
+        """Get the total runtime across all circuit executions.
 
-        Raises:
-            ValueError: If parameters have incorrect shape.
+        Returns:
+            float: Cumulative execution time in seconds.
         """
-        expected_shape = self.get_expected_param_shape()
-
-        if params.shape != expected_shape:
-            raise ValueError(
-                f"Initial parameters must have shape {expected_shape}, "
-                f"got {params.shape}"
-            )
+        return self._total_run_time
 
-    def _initialize_params(self):
-        """
-        Initialize the circuit parameters randomly.
+    def _prepare_and_send_circuits(self, **kwargs):
+        """Prepare circuits for execution and submit them to the backend.
 
-        Generates random parameters with values uniformly distributed between
-        0 and 2π. The number of parameter sets depends on the optimizer being used.
+        Returns:
+            Backend output from circuit submission.
         """
-        total_params = self.n_layers * self.n_params
-        self._curr_params = self._rng.uniform(
-            0, 2 * np.pi, (self.optimizer.n_param_sets, total_params)
-        )
-
-    def _run_optimization_circuits(self, store_data, data_file):
-        self._circuits[:] = []
-
-        self._generate_circuits()
-
-        losses = self._dispatch_circuits_and_process_results(
-            store_data=store_data, data_file=data_file
-        )
-
-        return losses
-
-    def _prepare_and_send_circuits(self):
         job_circuits = {}
 
-        for circuit in self._circuits:
+        for circuit in self._curr_circuits:
             for tag, qasm_circuit in zip(circuit.tags, circuit.qasm_circuits):
                 job_circuits[tag] = qasm_circuit
 
         self._total_circuit_count += len(job_circuits)
 
-        backend_output = self.backend.submit_circuits(job_circuits)
+        backend_output = self.backend.submit_circuits(job_circuits, **kwargs)
 
-        if isinstance(self.backend, QoroService):
+        if self.backend.is_async:
             self._curr_service_job_id = backend_output
 
         return backend_output
 
-    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 _wait_for_qoro_job_completion(self, job_id: str) -> list[dict]:
+        """Wait for a QoroService job to complete and return results.
 
-        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.json()["run_time"]) for r in response
-                )
+        Args:
+            job_id: The QoroService job identifier.
 
-        if isinstance(self.backend, QoroService):
+        Returns:
+            list[dict]: The job results from the backend.
+
+        Raises:
+            Exception: If job fails or doesn't complete.
+        """
+        # 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=self._curr_service_job_id,
+                service_job_id=job_id,
                 job_status=status,
             )
+        else:
+            update_function = None
+
+        # Poll until complete
+        status = self.backend.poll_job_status(
+            job_id,
+            loop_until_complete=True,
+            on_complete=self._track_runtime,
+            verbose=False,  # Disable the default logger in QoroService
+            poll_callback=update_function,
+        )
 
-            status = self.backend.poll_job_status(
-                self._curr_service_job_id,
-                loop_until_complete=True,
-                on_complete=add_run_time,
-                verbose=False,  # Disable the default logger in QoroService
-                poll_callback=update_function,  # Use the new, more generic name
-            )
-
-            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)
+        if status != JobStatus.COMPLETED:
+            raise Exception("Job has not completed yet, cannot post-process results")
+        return self.backend.get_job_results(job_id)
 
-        return result
+    def _dispatch_circuits_and_process_results(
+        self, data_file: str | None = None, **kwargs
+    ):
+        """Run an iteration of the program.
 
-    def _post_process_results(
-        self, results: dict[str, dict[str, int]]
-    ) -> dict[int, float]:
-        """
-        Post-process the results of the quantum problem.
+        The outputs are stored in the Program object.
+        Optionally, the data can be stored in a file.
 
         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.
+            data_file (str | None): The file to store the data in. If None, no data is stored. Defaults to None.
+            **kwargs: Additional keyword arguments for circuit submission and result processing.
 
         Returns:
-            (dict) The energies for each parameter set grouping, where the dict keys
-                correspond to the parameter indices.
-        """
-        if not (self._cancellation_event and self._cancellation_event.is_set()):
-            self.reporter.info(
-                message="Post-processing output", iteration=self.current_iteration
-            )
-
-        losses = {}
-        measurement_groups = self._meta_circuits["cost_circuit"].measurement_groups
-
-        # Define key functions for both levels of grouping
-        get_param_id = lambda item: int(item[0].split("_")[0])
-        get_qem_id = lambda item: int(item[0].split("_")[1].split(":")[1])
-
-        # Group the pre-sorted results by parameter ID.
-        for p, param_group_iterator in groupby(results.items(), key=get_param_id):
-            param_group_iterator = list(param_group_iterator)
-
-            shots_by_qem_idx = zip(
-                *{
-                    gid: [value for _, value in group]
-                    for gid, group in groupby(param_group_iterator, key=get_qem_id)
-                }.values()
-            )
-
-            marginal_results = []
-            for shots_dicts, curr_measurement_group in zip(
-                shots_by_qem_idx, measurement_groups
-            ):
-                if hasattr(self, "cost_hamiltonian"):
-                    wire_order = tuple(reversed(self.cost_hamiltonian.wires))
-                else:
-                    wire_order = tuple(
-                        reversed(range(len(next(iter(shots_dicts[0].keys())))))
-                    )
-
-                expectation_matrix = _batched_expectation(
-                    shots_dicts, curr_measurement_group, wire_order
-                )
-
-                # expectation_matrix[i, j] = expectation value for observable i, histogram j
-                curr_marginal_results = []
-                for obs_idx in range(len(curr_measurement_group)):
-                    intermediate_exp_values = expectation_matrix[obs_idx, :]
-                    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
-
-    def _perform_final_computation(self):
-        """
-        Perform final computations after optimization completes.
-
-        This is an optional hook method that subclasses can override to perform
-        any post-optimization processing, such as extracting solutions, running
-        final measurements, or computing additional metrics.
-
-        Note:
-            The default implementation does nothing. Subclasses should override
-            this method if they need post-optimization processing.
-        """
-        pass
-
-    def run(self, store_data=False, data_file=None):
-        """
-        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
+            Any: Processed results from _post_process_results.
         """
+        results = self._prepare_and_send_circuits(**kwargs)
 
-        def cost_fn(params):
-            self.reporter.info(
-                message="💸 Computing Cost 💸", iteration=self.current_iteration
-            )
-
-            self._curr_params = np.atleast_2d(params)
-
-            losses = self._run_optimization_circuits(store_data, data_file)
-
-            losses = np.fromiter(losses.values(), dtype=np.float64)
-
-            if params.ndim > 1:
-                return losses
-            else:
-                return losses.item()
+        if self.backend.is_async:
+            results = self._wait_for_qoro_job_completion(self._curr_service_job_id)
 
-        self._grad_shift_mask = _compute_parameter_shift_mask(
-            self.n_layers * self.n_params
-        )
-
-        def grad_fn(params):
-            self._grad_mode = True
-
-            self.reporter.info(
-                message="📈 Computing Gradients 📈", iteration=self.current_iteration
-            )
-
-            self._curr_params = self._grad_shift_mask + params
-
-            exp_vals = self._run_optimization_circuits(store_data, data_file)
-            exp_vals_arr = np.fromiter(exp_vals.values(), dtype=np.float64)
-
-            pos_shifts = exp_vals_arr[::2]
-            neg_shifts = exp_vals_arr[1::2]
-            grads = 0.5 * (pos_shifts - neg_shifts)
-
-            self._grad_mode = False
-
-            return grads
-
-        def _iteration_counter(intermediate_result: OptimizeResult):
-
-            self._losses.append(
-                dict(
-                    zip(
-                        range(len(intermediate_result.x)),
-                        np.atleast_1d(intermediate_result.fun),
-                    )
-                )
-            )
-
-            self.current_iteration += 1
-
-            self.reporter.update(iteration=self.current_iteration)
-
-            if self._cancellation_event and self._cancellation_event.is_set():
-                raise _CancelledError("Cancellation requested by batch.")
-
-            if (
-                isinstance(self.optimizer, ScipyOptimizer)
-                and self.optimizer.method == ScipyMethod.COBYLA
-                and intermediate_result.nit + 1 == self.max_iterations
-            ):
-                raise StopIteration
-
-        self.reporter.info(message="Finished Setup")
-
-        self._initialize_params()
-
-        try:
-            self._minimize_res = self.optimizer.optimize(
-                cost_fn=cost_fn,
-                initial_params=self._curr_params,
-                callback_fn=_iteration_counter,
-                jac=grad_fn,
-                maxiter=self.max_iterations,
-                rng=self._rng,
-            )
-        except _CancelledError:
-            # The optimizer was stopped by our callback. This is not a real
-            # error, just a signal to exit this task cleanly.
-            return self._total_circuit_count, self._total_run_time
-
-        self._final_params[:] = np.atleast_2d(self._minimize_res.x)
+        results = {r["label"]: r["results"] for r in results}
 
-        self._perform_final_computation()
+        result = self._post_process_results(results, **kwargs)
 
-        self.reporter.info(message="Finished successfully!")
+        if data_file is not None:
+            self.save_iteration(data_file)
 
-        return self._total_circuit_count, self._total_run_time
+        return result
 
-    def save_iteration(self, data_file):
-        """
-        Save the current state of the quantum program to a file.
+    def save_iteration(self, data_file: str):
+        """Save the current state of the quantum program to a file.
 
         Serializes the entire QuantumProgram instance including parameters,
         losses, and circuit history using pickle.
@@ -736,14 +237,12 @@ class QuantumProgram(ABC):
             The file is written in binary mode and can be restored using
             `import_iteration()`.
         """
-
         with open(data_file, "wb") as f:
             pickle.dump(self, f)
 
     @staticmethod
-    def import_iteration(data_file):
-        """
-        Load a previously saved quantum program state from a file.
+    def import_iteration(data_file: str):
+        """Load a previously saved quantum program state from a file.
 
         Deserializes a QuantumProgram instance that was saved using `save_iteration()`.
 
@@ -754,6 +253,5 @@ class QuantumProgram(ABC):
             QuantumProgram: The restored QuantumProgram instance with all its state,
                 including parameters, losses, and circuit history.
         """
-
         with open(data_file, "rb") as f:
             return pickle.load(f)