qoro-divi 0.2.0b1__py3-none-any.whl

divi/qprog/optimizers.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import Enum
+
+import numpy as np
+
+
+class Optimizer(Enum):
+    NELDER_MEAD = "Nelder-Mead"
+    COBYLA = "COBYLA"
+    MONTE_CARLO = "Monte Carlo"
+    L_BFGS_B = "L-BFGS-B"
+
+    def describe(self):
+        return self.name, self.value
+
+    @property
+    def n_param_sets(self):
+        if self in (Optimizer.NELDER_MEAD, Optimizer.L_BFGS_B, Optimizer.COBYLA):
+            return 1
+        elif self == Optimizer.MONTE_CARLO:
+            return 10
+
+    @property
+    def n_samples(self):
+        if self == Optimizer.MONTE_CARLO:
+            return 10
+        return 1
+
+    def compute_new_parameters(self, params, iteration, **kwargs):
+        if self != Optimizer.MONTE_CARLO:
+            raise NotImplementedError
+
+        rng = kwargs.pop("rng", np.random.default_rng())
+
+        losses = kwargs.pop("losses")
+        smallest_energy_keys = sorted(losses, key=lambda k: losses[k])[: self.n_samples]
+
+        new_params = []
+
+        for key in smallest_energy_keys:
+            new_param_set = [
+                rng.normal(
+                    params[int(key)],
+                    1 / (2 * iteration),
+                    size=params[int(key)].shape,
+                )
+                for _ in range(self.n_param_sets)
+            ]
+
+            for new_param in new_param_set:
+                new_param = np.clip(new_param, 0, 2 * np.pi)
+
+            new_params.extend(new_param_set)
+
+        return np.array(new_params)
+
+    def compute_parameter_shift_mask(self, n_params):
+        if self != Optimizer.L_BFGS_B:
+            raise NotImplementedError
+
+        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

divi/qprog/quantum_program.py

@@ -0,0 +1,493 @@
+# SPDX-FileCopyrightText: 2025 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 queue import Queue
+from typing import Optional
+
+import numpy as np
+from qiskit.result import marginal_counts, sampled_expectation_value
+from scipy.optimize import OptimizeResult, minimize
+
+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__)
+
+
+class QuantumProgram(ABC):
+    def __init__(
+        self,
+        backend: CircuitRunner,
+        seed: Optional[int] = None,
+        progress_queue: Optional[Queue] = 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.
+
+        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.
+
+        """
+
+        # Shared Variables
+        self.losses = kwargs.pop("losses", [])
+        self.final_params = kwargs.pop("final_params", [])
+
+        self.circuits: list[Circuit] = []
+
+        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)
+
+        # 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
+
+        # Needed for Pennylane's transforms
+        self._grouping_strategy = kwargs.pop("grouping_strategy", None)
+
+        self._qem_protocol = kwargs.pop("qem_protocol", None) or _NoMitigation()
+
+        self._meta_circuit_factory = partial(
+            MetaCircuit,
+            grouping_strategy=self._grouping_strategy,
+            qem_protocol=self._qem_protocol,
+        )
+
+    @property
+    def total_circuit_count(self):
+        return self._total_circuit_count
+
+    @property
+    def total_run_time(self):
+        return self._total_run_time
+
+    @property
+    def meta_circuits(self):
+        return self._meta_circuits
+
+    @abstractmethod
+    def _create_meta_circuits_dict(self) -> dict[str, MetaCircuit]:
+        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 _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 _update_mc_params(self):
+        """
+        Updates the parameters based on previous MC iteration.
+        """
+
+        if self.current_iteration == 0:
+            self._initialize_params()
+
+            self.current_iteration += 1
+
+            return
+
+        self._curr_params = self.optimizer.compute_new_parameters(
+            self._curr_params,
+            self.current_iteration,
+            losses=self.losses[-1],
+            rng=self._rng,
+        )
+
+        self.current_iteration += 1
+
+    def _prepare_and_send_circuits(self):
+        job_circuits = {}
+
+        for circuit in self.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)
+
+        if isinstance(self.backend, QoroService):
+            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.
+
+        Args:
+            store_data (bool): Whether to store the data for the iteration
+            data_file (str): The file to store the data in
+        """
+
+        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.
+
+        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.
+
+        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
+
+    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
+        """
+
+        if self._progress_queue is not None:
+            self._progress_queue.put(
+                {
+                    "job_id": self.job_id,
+                    "message": "Finished Setup",
+                    "progress": 0,
+                }
+            )
+        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)
+
+                return losses[0]
+
+            def grad_fn(params):
+                self._grad_mode = True
+
+                task_name = "📈 Computing Gradients 📈"
+
+                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"
+                    )
+
+                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
+
+                return grads
+
+            def _iteration_counter(intermediate_result: OptimizeResult):
+                self.losses.append({0: intermediate_result.fun})
+
+                self.final_params[:] = np.atleast_2d(intermediate_result.x)
+
+                self.current_iteration += 1
+
+                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
+            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
+
+    def save_iteration(self, data_file):
+        """
+        Save the current iteration of the program to a file.
+
+        Args:
+            data_file (str): The file to save the iteration to.
+        """
+
+        with open(data_file, "wb") as f:
+            pickle.dump(self, f)
+
+    @staticmethod
+    def import_iteration(data_file):
+        """
+        Import an iteration of the program from a file.
+
+        Args:
+            data_file (str): The file to import the iteration from.
+        """
+
+        with open(data_file, "rb") as f:
+            return pickle.load(f)

divi/utils.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from functools import reduce
+from warnings import warn
+
+import numpy as np
+import pennylane as qml
+import scipy.sparse as sps
+
+
+def _is_sanitized(
+    qubo_matrix: np.ndarray | sps.spmatrix,
+) -> np.ndarray | sps.spmatrix:
+    # Sanitize the QUBO matrix to ensure it is either symmetric or upper triangular.
+
+    is_sparse = sps.issparse(qubo_matrix)
+
+    return (
+        (
+            ((qubo_matrix != qubo_matrix.T).nnz == 0)
+            or ((qubo_matrix != sps.triu(qubo_matrix)).nnz == 0)
+        )
+        if is_sparse
+        else (
+            np.allclose(qubo_matrix, qubo_matrix.T)
+            or np.allclose(qubo_matrix, np.triu(qubo_matrix))
+        )
+    )
+
+
+def convert_qubo_matrix_to_pennylane_ising(
+    qubo_matrix: np.ndarray | sps.spmatrix,
+) -> tuple[qml.operation.Operator, float]:
+    """Convert QUBO matrix to Ising Hamiltonian in Pennylane.
+
+    The conversion follows the mapping:
+    - QUBO variables x_i ∈ {0,1} map to Ising variables s_i ∈ {-1,1} via s_i = 2x_i - 1
+    - This transforms a QUBO problem into an equivalent Ising problem
+
+    Args:
+        qubo_matrix: The QUBO matrix Q where the objective is to minimize x^T Q x
+
+    Returns:
+        A tuple of (Ising Hamiltonian as a PennyLane operator, constant term)
+    """
+
+    if not _is_sanitized(qubo_matrix):
+        warn(
+            "The QUBO matrix is neither symmetric nor upper triangular."
+            " Symmetrizing it for the Ising Hamiltonian creation."
+        )
+        qubo_matrix = (qubo_matrix + qubo_matrix.T) / 2
+
+    is_sparse = sps.issparse(qubo_matrix)
+    backend = sps if is_sparse else np
+
+    # Gather non-zero indices in the upper triangle of the matrix
+    triu_matrix = backend.triu(
+        qubo_matrix,
+        **(
+            {"format": qubo_matrix.format if qubo_matrix.format != "coo" else "csc"}
+            if is_sparse
+            else {}
+        ),
+    )
+    rows, cols = triu_matrix.nonzero()
+    values = triu_matrix[rows, cols].A1 if is_sparse else triu_matrix[rows, cols]
+
+    n = qubo_matrix.shape[0]
+    linear_terms = np.zeros(n)
+    constant_term = 0.0
+    ising_terms = []
+    ising_weights = []
+
+    for i, j, weight in zip(rows, cols, values):
+        weight = float(weight)
+        i, j = int(i), int(j)
+
+        if i == j:
+            # Diagonal elements
+            linear_terms[i] -= weight / 2
+            constant_term += weight / 2
+        else:
+            # Off-diagonal elements (i < j since we're using triu)
+            ising_terms.append([i, j])
+            ising_weights.append(weight / 4)
+
+            # Update linear terms
+            linear_terms[i] -= weight / 4
+            linear_terms[j] -= weight / 4
+
+            # Update constant term
+            constant_term += weight / 4
+
+    # Add the linear terms (Z operators)
+    for i, curr_lin_term in filter(lambda x: x[1] != 0, enumerate(linear_terms)):
+        ising_terms.append([i])
+        ising_weights.append(float(curr_lin_term))
+
+    # Construct the Ising Hamiltonian as a PennyLane operator
+    pauli_string = qml.Identity(0) * 0
+    for term, weight in zip(ising_terms, ising_weights):
+        if len(term) == 1:
+            # Single-qubit term (Z operator)
+            curr_term = qml.Z(term[0]) * weight
+        else:
+            # Two-qubit term (ZZ interaction)
+            curr_term = (
+                reduce(lambda x, y: x @ y, map(lambda x: qml.Z(x), term)) * weight
+            )
+
+        pauli_string += curr_term
+
+    return pauli_string.simplify(), constant_term