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

divi/qprog/{_qubo_partitioning.py → workflows/_qubo_partitioning.py}

@@ -12,8 +12,8 @@ import numpy as np
 import scipy.sparse as sps
 from dimod import BinaryQuadraticModel
 
-from divi.interfaces import CircuitRunner
-from divi.qprog._qaoa import QAOA, QUBOProblemTypes
+from divi.backends import CircuitRunner
+from divi.qprog.algorithms import QAOA, QUBOProblemTypes
 from divi.qprog.batch import ProgramBatch
 from divi.qprog.optimizers import MonteCarloOptimizer, Optimizer
 from divi.qprog.quantum_program import QuantumProgram
@@ -49,14 +49,6 @@ def _sanitize_problem_input(qubo: T) -> tuple[T, BinaryQuadraticModel]:
     raise ValueError(f"Got an unsupported QUBO input format: {type(qubo)}")
 
 
-def _run_and_compute_solution(program: QuantumProgram):
-    program.run()
-
-    final_sol_circuit_count, final_sol_run_time = program.compute_final_solution()
-
-    return final_sol_circuit_count, final_sol_run_time
-
-
 class QUBOPartitioningQAOA(ProgramBatch):
     def __init__(
         self,
@@ -94,10 +86,10 @@ class QUBOPartitioningQAOA(ProgramBatch):
         self._partitioning = hybrid.Unwind(decomposer)
         self._aggregating = hybrid.Reduce(hybrid.Lambda(_merge_substates)) | composer
 
-        self._task_fn = _run_and_compute_solution
-
         self.max_iterations = max_iterations
 
+        self.trivial_program_ids = set()
+
         self._constructor = partial(
             QAOA,
             optimizer=optimizer if optimizer is not None else MonteCarloOptimizer(),
@@ -140,6 +132,12 @@ class QUBOPartitioningQAOA(ProgramBatch):
                 del partition["problem"]
 
             prog_id = (string.ascii_uppercase[i], len(partition.subproblem))
+            self.prog_id_to_bqm_subproblem_states[prog_id] = partition
+
+            if partition.subproblem.num_interactions == 0:
+                # Skip creating a full QAOA program for this trivial case.
+                self.trivial_program_ids.add(prog_id)
+                continue
 
             ldata, (irow, icol, qdata), _ = partition.subproblem.to_numpy_vectors(
                 partition.subproblem.variables
@@ -155,18 +153,30 @@ class QUBOPartitioningQAOA(ProgramBatch):
                 ),
                 shape=(len(ldata), len(ldata)),
             )
-            self.prog_id_to_bqm_subproblem_states[prog_id] = partition
-            self.programs[prog_id] = self._constructor(
+
+            self._programs[prog_id] = self._constructor(
                 job_id=prog_id,
                 problem=coo_mat,
-                losses=self._manager.list(),
-                probs=self._manager.dict(),
-                final_params=self._manager.list(),
-                solution_bitstring=self._manager.list(),
                 progress_queue=self._queue,
             )
 
     def aggregate_results(self):
+        """
+        Aggregate results from all QUBO subproblems into a global solution.
+
+        Collects solutions from each partitioned subproblem (both QAOA-optimized and
+        trivial ones) and uses the hybrid framework composer to combine them into
+        a final solution for the original QUBO problem.
+
+        Returns:
+            tuple: A tuple containing:
+                - solution (np.ndarray): Binary solution vector for the QUBO problem.
+                - solution_energy (float): Energy/cost of the solution.
+
+        Raises:
+            RuntimeError: If programs haven't been run or if final probabilities
+                haven't been computed.
+        """
         super().aggregate_results()
 
         if any(len(program.probs) == 0 for program in self.programs.values()):
@@ -174,14 +184,21 @@ class QUBOPartitioningQAOA(ProgramBatch):
                 "Not all final probabilities computed yet. Please call `run()` first."
             )
 
-        for prog_id, subproblem in self.programs.items():
-            bqm_subproblem_state = self.prog_id_to_bqm_subproblem_states[prog_id]
+        for (
+            prog_id,
+            bqm_subproblem_state,
+        ) in self.prog_id_to_bqm_subproblem_states.items():
+
+            if prog_id in self.trivial_program_ids:
+                # Case 1: Trivial problem. Solve classically.
+                # The solution is any bitstring (e.g., all zeros) with energy 0.
+                var_to_val = {v: 0 for v in bqm_subproblem_state.subproblem.variables}
+            else:
+                subproblem = self._programs[prog_id]
+                var_to_val = dict(
+                    zip(bqm_subproblem_state.subproblem.variables, subproblem.solution)
+                )
 
-            curr_final_solution = subproblem.solution
-
-            var_to_val = dict(
-                zip(bqm_subproblem_state.subproblem.variables, curr_final_solution)
-            )
             sample_set = dimod.SampleSet.from_samples(
                 dimod.as_samples(var_to_val), "BINARY", 0
             )

divi/qprog/{_vqe_sweep.py → workflows/_vqe_sweep.py}

@@ -14,7 +14,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pennylane as qml
 
-from divi.qprog import VQE, ProgramBatch, VQEAnsatz
+from divi.qprog import VQE, Ansatz, ProgramBatch
 from divi.qprog.optimizers import MonteCarloOptimizer, Optimizer
 
 
@@ -392,7 +392,7 @@ class VQEHyperparameterSweep(ProgramBatch):
 
     def __init__(
         self,
-        ansatze: Sequence[VQEAnsatz],
+        ansatze: Sequence[Ansatz],
         molecule_transformer: MoleculeTransformer,
         optimizer: Optimizer | None = None,
         max_iterations: int = 10,
@@ -403,7 +403,7 @@ class VQEHyperparameterSweep(ProgramBatch):
 
         Parameters
         ----------
-        ansatze: Sequence[VQEAnsatz]
+        ansatze: Sequence[Ansatz]
             A sequence of ansatz circuits to test.
         molecule_transformer: MoleculeTransformer
             A `MoleculeTransformer` object defining the configuration for
@@ -430,6 +430,15 @@ class VQEHyperparameterSweep(ProgramBatch):
         )
 
     def create_programs(self):
+        """
+        Create VQE programs for all combinations of ansatze and molecule variants.
+
+        Generates molecule variants using the configured MoleculeTransformer, then
+        creates a VQE program for each (ansatz, molecule_variant) pair.
+
+        Note:
+            Program IDs are tuples of (ansatz_name, bond_modifier_value).
+        """
         super().create_programs()
 
         self.molecule_variants = self.molecule_transformer.generate()
@@ -437,17 +446,29 @@ class VQEHyperparameterSweep(ProgramBatch):
         for ansatz, (modifier, molecule) in product(
             self.ansatze, self.molecule_variants.items()
         ):
-            _job_id = (ansatz, modifier)
-            self.programs[_job_id] = self._constructor(
+            _job_id = (ansatz.name, modifier)
+            self._programs[_job_id] = self._constructor(
                 job_id=_job_id,
                 molecule=molecule,
                 ansatz=ansatz,
-                losses=self._manager.list(),
-                final_params=self._manager.list(),
                 progress_queue=self._queue,
             )
 
     def aggregate_results(self):
+        """
+        Find the best ansatz and bond configuration from all VQE runs.
+
+        Compares the final energies across all ansatz/molecule combinations
+        and returns the configuration that achieved the lowest ground state energy.
+
+        Returns:
+            tuple: A tuple containing:
+                - best_config (tuple): (ansatz_name, bond_modifier) of the best result.
+                - best_energy (float): The lowest energy achieved.
+
+        Raises:
+            RuntimeError: If programs haven't been run or have empty losses.
+        """
         super().aggregate_results()
 
         all_energies = {key: prog.losses[-1] for key, prog in self.programs.items()}
@@ -469,37 +490,49 @@ class VQEHyperparameterSweep(ProgramBatch):
         if self._executor is not None:
             self.join()
 
-        data = []
-        colors = ["blue", "g", "r", "c", "m", "y", "k"]
+        # Get the unique ansatz objects that were actually run
+        # Assumes `self.ansatze` is a list of the ansatz instances used.
+        unique_ansatze = self.ansatze
 
-        ansatz_list = list(VQEAnsatz)
+        # Create a stable color mapping for each unique ansatz object
+        colors = ["blue", "g", "r", "c", "m", "y", "k"]
+        color_map = {
+            ansatz: colors[i % len(colors)] for i, ansatz in enumerate(unique_ansatze)
+        }
 
         if graph_type == "scatter":
-            for ansatz, modifier in self.programs.keys():
+            # Plot each ansatz's results as a separate series for clarity
+            for ansatz in unique_ansatze:
+                modifiers = []
                 min_energies = []
-
-                curr_energies = self.programs[(ansatz, modifier)].losses[-1]
-                min_energies.append(
-                    (
-                        modifier,
-                        min(curr_energies.values()),
-                        colors[ansatz_list.index(ansatz)],
-                    )
+                for modifier in self.molecule_transformer.bond_modifiers:
+                    program_key = (ansatz.name, modifier)
+                    if program_key in self._programs:
+                        modifiers.append(modifier)
+                        curr_energies = self._programs[program_key].losses[-1]
+                        min_energies.append(min(curr_energies.values()))
+
+                # Use the new .name property for the label and the color_map
+                plt.scatter(
+                    modifiers,
+                    min_energies,
+                    color=color_map[ansatz],
+                    label=ansatz.name,
                 )
-                data.extend(min_energies)
-
-            x, y, z = zip(*data)
-            plt.scatter(x, y, color=z, label=ansatz)
 
         elif graph_type == "line":
-            for ansatz in self.ansatze:
+            for ansatz in unique_ansatze:
                 energies = []
                 for modifier in self.molecule_transformer.bond_modifiers:
                     energies.append(
-                        min(self.programs[(ansatz, modifier)].losses[-1].values())
+                        min(self._programs[(ansatz.name, modifier)].losses[-1].values())
                     )
+
                 plt.plot(
-                    self.molecule_transformer.bond_modifiers, energies, label=ansatz
+                    self.molecule_transformer.bond_modifiers,
+                    energies,
+                    label=ansatz.name,
+                    color=color_map[ansatz],
                 )
 
         plt.xlabel(

divi/reporting/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ._pbar import make_progress_bar
+from ._qlogger import disable_logging, enable_logging
+from ._reporter import LoggingProgressReporter, ProgressReporter, QueueProgressReporter

divi/reporting/_pbar.py

@@ -0,0 +1,112 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    ProgressColumn,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.text import Text
+
+
+class _UnfinishedTaskWrapper:
+    """Wrapper that forces a task to appear unfinished for spinner animation."""
+
+    def __init__(self, task):
+        self._task = task
+
+    def __getattr__(self, name):
+        if name == "finished":
+            return False
+        return getattr(self._task, name)
+
+
+class ConditionalSpinnerColumn(ProgressColumn):
+    _FINAL_STATUSES = ("Success", "Failed", "Cancelled", "Aborted")
+
+    def __init__(self):
+        super().__init__()
+        self.spinner = SpinnerColumn("point")
+
+    def render(self, task):
+        status = task.fields.get("final_status")
+
+        if status in self._FINAL_STATUSES:
+            return Text("")
+
+        # Force the task to appear unfinished for spinner animation
+        return self.spinner.render(_UnfinishedTaskWrapper(task))
+
+
+class PhaseStatusColumn(ProgressColumn):
+    def __init__(self, table_column=None):
+        super().__init__(table_column)
+
+    def render(self, task):
+        final_status = task.fields.get("final_status")
+
+        if final_status == "Success":
+            return Text("• Success! ✅", style="bold green")
+        elif final_status == "Failed":
+            return Text("• Failed! ❌", style="bold red")
+        elif final_status == "Cancelled":
+            return Text("• Cancelled ⏹️", style="bold yellow")
+        elif final_status == "Aborted":
+            return Text("• Aborted ⚠️", style="dim magenta")
+
+        message = task.fields.get("message")
+
+        poll_attempt = task.fields.get("poll_attempt", 0)
+        polling_str = ""
+        service_job_id = task.fields.get("service_job_id")
+
+        if service_job_id:
+            split_job_id = service_job_id.split("-")[0]
+            job_status = task.fields.get("job_status")
+
+            if job_status == "COMPLETED":
+                polling_str = f" [Job {split_job_id} is complete.]"
+            elif poll_attempt > 0:
+                max_retries = task.fields.get("max_retries")
+                polling_str = f" [Job {split_job_id} is {job_status}. Polling attempt {poll_attempt} / {max_retries}]"
+
+        final_text = Text(f"[{message}]{polling_str}")
+        if service_job_id:
+            final_text.highlight_words([split_job_id], "blue")
+
+        return final_text
+
+
+def make_progress_bar(is_jupyter: bool = False) -> Progress:
+    """
+    Create a customized Rich progress bar for tracking quantum program execution.
+
+    Builds a progress bar with custom columns including job name, completion status,
+    elapsed time, spinner, and phase status indicators. Automatically adapts refresh
+    behavior for Jupyter notebook environments.
+
+    Args:
+        is_jupyter (bool, optional): Whether the progress bar is being displayed in
+            a Jupyter notebook environment. Affects refresh behavior. Defaults to False.
+
+    Returns:
+        Progress: A configured Rich Progress instance with custom columns for
+            quantum program tracking.
+    """
+    return Progress(
+        TextColumn("[bold blue]{task.fields[job_name]}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TimeElapsedColumn(),
+        ConditionalSpinnerColumn(),
+        PhaseStatusColumn(),
+        # For jupyter notebooks, refresh manually instead
+        auto_refresh=not is_jupyter,
+        # Give a dummy positive value if is_jupyter
+        refresh_per_second=10 if not is_jupyter else 999,
+    )

divi/{qlogger.py → reporting/_qlogger.py}

@@ -30,6 +30,18 @@ def _is_jupyter():
         return False  # IPython is not installed
 
 
+class CustomFormatter(logging.Formatter):
+    """
+    A custom log formatter that removes '._reporter' from the logger name.
+    """
+
+    def format(self, record):
+        # Modify the record's name attribute in place
+        if record.name.endswith("._reporter"):
+            record.name = record.name.removesuffix("._reporter")
+        return super().format(record)
+
+
 class OverwriteStreamHandler(logging.StreamHandler):
     def __init__(self, stream=None):
         super().__init__(stream)
@@ -100,10 +112,26 @@ class OverwriteStreamHandler(logging.StreamHandler):
 
 
 def enable_logging(level=logging.INFO):
+    """
+    Enable logging for the divi package with custom formatting.
+
+    Sets up a custom logger with an OverwriteStreamHandler that supports
+    message overwriting (for progress updates) and removes the '._reporter'
+    suffix from logger names.
+
+    Args:
+        level (int, optional): Logging level to set (e.g., logging.INFO,
+            logging.DEBUG). Defaults to logging.INFO.
+
+    Note:
+        This function clears any existing handlers and sets up a new handler
+        with custom formatting.
+    """
     root_logger = logging.getLogger(__name__.split(".")[0])
 
-    formatter = logging.Formatter(
-        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    formatter = CustomFormatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
     )
 
     handler = OverwriteStreamHandler(sys.stdout)
@@ -115,6 +143,13 @@ def enable_logging(level=logging.INFO):
 
 
 def disable_logging():
+    """
+    Disable all logging for the divi package.
+
+    Removes all handlers and sets the logging level to above CRITICAL,
+    effectively suppressing all log messages. This is useful when using
+    progress bars that provide visual feedback.
+    """
     root_logger = logging.getLogger(__name__.split(".")[0])
     root_logger.handlers.clear()
     root_logger.setLevel(logging.CRITICAL + 1)

divi/{reporter.py → reporting/_reporter.py}

@@ -29,12 +29,9 @@ class ProgressReporter(ABC):
 class QueueProgressReporter(ProgressReporter):
     """Reports progress by putting structured dictionaries onto a Queue."""
 
-    def __init__(
-        self, job_id: str, progress_queue: Queue, has_final_computation: bool = False
-    ):
+    def __init__(self, job_id: str, progress_queue: Queue):
         self._job_id = job_id
         self._queue = progress_queue
-        self.has_final_computation = has_final_computation
 
     def update(self, **kwargs):
         payload = {"job_id": self._job_id, "progress": 1}
@@ -43,20 +40,19 @@ class QueueProgressReporter(ProgressReporter):
     def info(self, message: str, **kwargs):
         payload = {"job_id": self._job_id, "progress": 0, "message": message}
 
-        # Determine if this message indicates the job is truly finished.
-        is_final_step = "Computed Final Solution" in message or (
-            "Finished Optimization" in message and not self.has_final_computation
-        )
-
-        if is_final_step:
+        if "Finished successfully!" in message:
             payload["final_status"] = "Success"
-        elif "poll_attempt" in kwargs:
+
+        if "poll_attempt" in kwargs:
             # For polling, remove the message key so the last message persists.
             del payload["message"]
             payload["poll_attempt"] = kwargs["poll_attempt"]
             payload["max_retries"] = kwargs["max_retries"]
             payload["service_job_id"] = kwargs["service_job_id"]
             payload["job_status"] = kwargs["job_status"]
+        else:
+            # For any other message, explicitly reset the polling attempt counter.
+            payload["poll_attempt"] = 0
 
         self._queue.put(payload)
 
@@ -82,9 +78,7 @@ class LoggingProgressReporter(ProgressReporter):
             return
 
         if "iteration" in kwargs:
-            logger.info(
-                f"Running Iteration #{kwargs['iteration'] + 1} circuits: {message}\r"
-            )
+            logger.info(f"Iteration #{kwargs['iteration'] + 1}: {message}\r")
             return
 
         logger.info(message)

divi/utils.py

@@ -13,8 +13,20 @@ 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.
+    """
+    Check if a QUBO matrix is either symmetric or upper triangular.
+
+    This function validates that the input QUBO matrix is in a proper format
+    for conversion to an Ising Hamiltonian. The matrix should be either
+    symmetric (equal to its transpose) or upper triangular.
 
+    Args:
+        qubo_matrix (np.ndarray | sps.spmatrix): The QUBO matrix to validate.
+            Can be a dense NumPy array or a sparse SciPy matrix.
+
+    Returns:
+        bool: True if the matrix is symmetric or upper triangular, False otherwise.
+    """
     is_sparse = sps.issparse(qubo_matrix)
 
     return (
@@ -33,17 +45,37 @@ def _is_sanitized(
 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.
+    """
+    Convert a QUBO matrix to an Ising Hamiltonian in PennyLane format.
+
+    The conversion follows the mapping from QUBO variables x_i ∈ {0,1} to
+    Ising variables σ_i ∈ {-1,1} via the transformation x_i = (1 - σ_i)/2. This
+    transforms a QUBO minimization problem into an equivalent Ising minimization
+    problem.
 
-    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
+    The function handles both dense NumPy arrays and sparse SciPy matrices efficiently.
+    If the input matrix is neither symmetric nor upper triangular, it will be
+    symmetrized automatically with a warning.
 
     Args:
-        qubo_matrix: The QUBO matrix Q where the objective is to minimize x^T Q x
+        qubo_matrix (np.ndarray | sps.spmatrix): The QUBO matrix Q where the
+            objective is to minimize x^T Q x. Can be a dense NumPy array or a
+            sparse SciPy matrix (any format). Should be square and either
+            symmetric or upper triangular.
 
     Returns:
-        A tuple of (Ising Hamiltonian as a PennyLane operator, constant term)
+        tuple[qml.operation.Operator, float]: A tuple containing:
+            - Ising Hamiltonian as a PennyLane operator (sum of Pauli Z terms)
+            - Constant offset term to be added to energy calculations
+
+    Raises:
+        UserWarning: If the QUBO matrix is neither symmetric nor upper triangular.
+
+    Example:
+        >>> import numpy as np
+        >>> qubo = np.array([[1, 2], [0, 3]])
+        >>> hamiltonian, offset = convert_qubo_matrix_to_pennylane_ising(qubo)
+        >>> print(f"Offset: {offset}")
     """
 
     if not _is_sanitized(qubo_matrix):
@@ -56,17 +88,24 @@ def convert_qubo_matrix_to_pennylane_ising(
     is_sparse = sps.issparse(qubo_matrix)
     backend = sps if is_sparse else np
 
+    symmetrized_qubo = (qubo_matrix + qubo_matrix.T) / 2
+
     # Gather non-zero indices in the upper triangle of the matrix
     triu_matrix = backend.triu(
-        qubo_matrix,
+        symmetrized_qubo,
         **(
             {"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]
+
+    if is_sparse:
+        coo_mat = triu_matrix.tocoo()
+        rows, cols, values = coo_mat.row, coo_mat.col, coo_mat.data
+    else:
+        rows, cols = triu_matrix.nonzero()
+        values = triu_matrix[rows, cols]
 
     n = qubo_matrix.shape[0]
     linear_terms = np.zeros(n)

{qoro_divi-0.3.3.dist-info → qoro_divi-0.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: qoro-divi
-Version: 0.3.3
+Version: 0.3.5
 Summary: A Python library to automate generating, parallelizing, and executing quantum programs.
 Author: Ahmed Darwish
 Author-email: ahmed@qoroquantum.de
@@ -17,6 +17,7 @@ Requires-Dist: networkx (>=3.5,<4.0)
 Requires-Dist: pennylane (>=0.42.3,<0.43.0)
 Requires-Dist: ply (>=3.11,<4.0)
 Requires-Dist: pymetis (>=2025.1.1,<2026.0.0)
+Requires-Dist: pymoo (>=0.6.1.5,<0.7.0.0)
 Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
 Requires-Dist: qiskit (<2.0)
 Requires-Dist: qiskit-aer (>=0.17.1,<0.18.0)