qoro-divi 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

divi/qprog/algorithms/_vqe.py

@@ -1,4 +1,4 @@
-# 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
 
@@ -198,13 +198,26 @@ class VQE(VariationalQuantumAlgorithm):
 
         return [
             self.meta_circuits[circuit_type].initialize_circuit_from_params(
-                params_group, tag_prefix=f"{p}"
+                params_group, param_idx=p
             )
             for p, params_group in enumerate(self._curr_params)
         ]
 
     def _perform_final_computation(self, **kwargs):
-        """Extract the eigenstate corresponding to the lowest energy found."""
+        """Extract the eigenstate corresponding to the lowest energy found.
+
+        This method performs the following steps:
+        1. Executes measurement circuits with the best parameters (those that achieved the lowest loss).
+        2. Retrieves the bitstring representing the eigenstate with the highest probability,
+           correcting for endianness.
+        3. Converts the bitstring to a NumPy array of integers (int32) representing the eigenstate.
+        4. Stores the eigenstate in the `_eigenstate` attribute.
+
+        Returns:
+            tuple[int, float]: A tuple containing:
+                - int: The total number of circuits executed.
+                - float: The total runtime of the optimization process.
+        """
         self.reporter.info(message="🏁 Computing Final Eigenstate 🏁", overwrite=True)
 
         self._run_solution_measurement()

divi/qprog/batch.py

@@ -488,8 +488,11 @@ class ProgramBatch(ABC):
                 self._total_run_time += sum(result[1] for result in completed_futures)
                 self.futures.clear()
 
-            self._executor.shutdown(wait=False)
-            self._executor = None
+            # Shutdown executor and wait for all threads to complete
+            # This is critical for Python 3.12 to prevent process hangs
+            if self._executor is not None:
+                self._executor.shutdown(wait=True)
+                self._executor = None
 
             if self._progress_bar is not None:
                 self._queue.join()

divi/qprog/quantum_program.py

@@ -1,4 +1,4 @@
-# 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
 
@@ -147,10 +147,11 @@ class QuantumProgram(ABC):
                 contains job_id. For sync backends, contains results directly.
         """
         job_circuits = {}
+        self._reset_tag_cache()
 
         for bundle in self._curr_circuits:
             for executable in bundle.executables:
-                job_circuits[executable.tag] = executable.qasm
+                job_circuits[self._encode_tag(executable.tag)] = executable.qasm
 
         self._total_circuit_count += len(job_circuits)
 
@@ -302,6 +303,7 @@ class QuantumProgram(ABC):
                     raise ValueError("ExecutionResult has neither results nor job_id")
 
             results = {r["label"]: r["results"] for r in results}
+            results = self._decode_tags(results)
 
             result = self._post_process_results(results, **kwargs)
 
@@ -309,3 +311,14 @@ class QuantumProgram(ABC):
         finally:
             # Clear the execution result after processing
             self._current_execution_result = None
+
+    def _reset_tag_cache(self) -> None:
+        """Hook to reset per-run tag caches. Default is no-op."""
+
+    def _encode_tag(self, tag: Any) -> str:
+        """Convert a tag to a backend-safe string."""
+        return str(tag)
+
+    def _decode_tags(self, results: dict[str, dict[str, int]]) -> dict:
+        """Restore structured tags from backend result labels."""
+        return results

divi/qprog/typing.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import dimod
+import networkx as nx
+import numpy as np
+import rustworkx as rx
+import scipy.sparse as sps
+
+GraphProblemTypes = nx.Graph | rx.PyGraph
+QUBOProblemTypes = list | np.ndarray | sps.spmatrix | dimod.BinaryQuadraticModel
+
+
+def qubo_to_matrix(qubo: QUBOProblemTypes) -> np.ndarray | sps.spmatrix:
+    """Convert supported QUBO inputs to a square matrix.
+
+    Args:
+        qubo: QUBO input as list, ndarray, sparse matrix, or BinaryQuadraticModel.
+
+    Returns:
+        Square QUBO matrix as a dense ndarray or sparse matrix.
+
+    Raises:
+        ValueError: If the input cannot be converted to a square matrix or the
+            BinaryQuadraticModel is not binary.
+    """
+    if isinstance(qubo, dimod.BinaryQuadraticModel):
+        if qubo.vartype != dimod.Vartype.BINARY:
+            raise ValueError(
+                f"BinaryQuadraticModel must have vartype='BINARY', got {qubo.vartype}"
+            )
+        variables = list(qubo.variables)
+        var_to_idx = {v: i for i, v in enumerate(variables)}
+        matrix = np.diag([qubo.linear.get(v, 0) for v in variables])
+        for (u, v), coeff in qubo.quadratic.items():
+            i, j = var_to_idx[u], var_to_idx[v]
+            matrix[i, j] = matrix[j, i] = coeff
+        return matrix
+
+    if isinstance(qubo, list):
+        qubo = np.asarray(qubo)
+
+    if isinstance(qubo, np.ndarray):
+        if qubo.ndim != 2 or qubo.shape[0] != qubo.shape[1]:
+            raise ValueError(
+                "Invalid QUBO matrix."
+                f" Got array of shape {qubo.shape}."
+                " Must be a square matrix."
+            )
+        return qubo
+
+    if sps.isspmatrix(qubo):
+        if qubo.shape[0] != qubo.shape[1]:
+            raise ValueError(
+                "Invalid QUBO matrix."
+                f" Got sparse matrix of shape {qubo.shape}."
+                " Must be a square matrix."
+            )
+        return qubo
+
+    raise ValueError(f"Unsupported QUBO type: {type(qubo)}")

divi/qprog/variational_quantum_algorithm.py

@@ -1,4 +1,4 @@
-# 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
 
@@ -7,10 +7,9 @@ import pickle
 from abc import abstractmethod
 from datetime import datetime
 from functools import partial
-from itertools import groupby
 from pathlib import Path
 from queue import Queue
-from typing import Any
+from typing import Any, NamedTuple
 from warnings import warn
 
 import numpy as np
@@ -24,7 +23,7 @@ from divi.backends import (
     convert_counts_to_probs,
     reverse_dict_endianness,
 )
-from divi.circuits import CircuitBundle, MetaCircuit
+from divi.circuits import CircuitBundle, CircuitTag, MetaCircuit, format_circuit_tag
 from divi.circuits.qem import _NoMitigation
 from divi.qprog._expectation import _batched_expectation
 from divi.qprog._hamiltonians import convert_hamiltonian_to_pauli_string
@@ -50,6 +49,20 @@ from divi.qprog.quantum_program import QuantumProgram
 logger = logging.getLogger(__name__)
 
 
+class SolutionEntry(NamedTuple):
+    """A solution entry with bitstring, probability, and optional decoded value.
+
+    Args:
+        bitstring: Binary string representing a computational basis state.
+        prob: Measured probability in range [0.0, 1.0].
+        decoded: Optional problem-specific decoded representation. Defaults to None.
+    """
+
+    bitstring: str
+    prob: float
+    decoded: Any | None = None
+
+
 class SubclassState(BaseModel):
     """Container for subclass-specific state."""
 
@@ -249,6 +262,12 @@ class VariationalQuantumAlgorithm(QuantumProgram):
                 QASM sizes manageable. Consider reducing precision if you need to minimize
                 data transfer overhead, or increase it only if you require higher numerical
                 precision in your circuit parameters.
+            decode_solution_fn (callable[[str], Any] | None): Function to decode bitstrings
+                into problem-specific solution representations. Called during final computation
+                and when `get_top_solutions(include_decoded=True)` is used. The function should
+                take a binary string (e.g., "0101") and return a decoded representation
+                (e.g., a list of indices, numpy array, or custom object). Defaults to
+                `lambda bitstring: bitstring` (identity function).
         """
 
         super().__init__(
@@ -291,6 +310,11 @@ class VariationalQuantumAlgorithm(QuantumProgram):
         self._qem_protocol = kwargs.pop("qem_protocol", None) or _NoMitigation()
         self._precision = kwargs.pop("precision", 8)
 
+        # --- Solution Decoding ---
+        self._decode_solution_fn = kwargs.pop(
+            "decode_solution_fn", lambda bitstring: bitstring
+        )
+
         # --- Circuit Factory & Templates ---
         self._meta_circuits = None
         self._meta_circuit_factory = partial(
@@ -451,11 +475,42 @@ class VariationalQuantumAlgorithm(QuantumProgram):
         return self._best_loss
 
     @property
-    def best_probs(self):
-        """Get a copy of the probability distribution for the best parameters.
+    def best_probs(self) -> dict[CircuitTag, dict[str, float]]:
+        """Get normalized probabilities for the best parameters.
+
+        This property provides access to the probability distribution computed
+        by running measurement circuits with the best parameters found during
+        optimization. The distribution maps bitstrings (computational basis states)
+        to their measured probabilities.
+
+        The probabilities are normalized and have deterministic ordering when
+        iterated (dictionary insertion order is preserved in Python 3.7+).
 
         Returns:
-            dict: A copy of the best probability distribution.
+            dict[CircuitTag, dict[str, float]]: Dictionary mapping CircuitTag keys to
+                bitstring probability dictionaries. Bitstrings are binary strings
+                (e.g., "0101"), values are probabilities in range [0.0, 1.0].
+                Returns an empty dict if final computation has not been performed.
+
+        Raises:
+            RuntimeError: If attempting to access probabilities before running
+                the algorithm with final computation enabled.
+
+        Note:
+            To populate this distribution, you must run the algorithm with
+            `perform_final_computation=True` (the default):
+
+            >>> program.run(perform_final_computation=True)
+            >>> probs = program.best_probs
+
+        Example:
+            >>> program.run()
+            >>> probs = program.best_probs
+            >>> for bitstring, prob in probs.items():
+            ...     print(f"{bitstring}: {prob:.2%}")
+            0101: 42.50%
+            1010: 31.20%
+            ...
         """
         if not self._best_probs:
             warn(
@@ -466,6 +521,109 @@ class VariationalQuantumAlgorithm(QuantumProgram):
             )
         return self._best_probs.copy()
 
+    def get_top_solutions(
+        self, n: int = 10, *, min_prob: float = 0.0, include_decoded: bool = False
+    ) -> list[SolutionEntry]:
+        """Get the top-N solutions sorted by probability.
+
+        This method extracts the most probable solutions from the measured
+        probability distribution. Solutions are sorted by probability (descending)
+        with deterministic tie-breaking using lexicographic ordering of bitstrings.
+
+        Args:
+            n (int): Maximum number of solutions to return. Must be non-negative.
+                If n is 0 or negative, returns an empty list. If n exceeds the
+                number of available solutions (after filtering), returns all
+                available solutions. Defaults to 10.
+            min_prob (float): Minimum probability threshold for including solutions.
+                Only solutions with probability >= min_prob will be included.
+                Must be in range [0.0, 1.0]. Defaults to 0.0 (no filtering).
+            include_decoded (bool): Whether to populate the `decoded` field of
+                each SolutionEntry by calling the `decode_solution_fn` provided
+                in the constructor. If False, the decoded field will be None.
+                Defaults to False.
+
+        Returns:
+            list[SolutionEntry]: List of solution entries sorted by probability
+                (descending), then by bitstring (lexicographically ascending)
+                for deterministic tie-breaking. Returns an empty list if no
+                probability distribution is available or n <= 0.
+
+        Raises:
+            RuntimeError: If probability distribution is not available because
+                optimization has not been run or final computation was not performed.
+            ValueError: If min_prob is not in range [0.0, 1.0] or n is negative.
+
+        Note:
+            The probability distribution must be computed by running the algorithm
+            with `perform_final_computation=True` (the default):
+
+            >>> program.run(perform_final_computation=True)
+            >>> top_10 = program.get_top_solutions(n=10)
+
+        Example:
+            >>> # Get top 5 solutions with probability >= 5%
+            >>> program.run()
+            >>> solutions = program.get_top_solutions(n=5, min_prob=0.05)
+            >>> for sol in solutions:
+            ...     print(f"{sol.bitstring}: {sol.prob:.2%}")
+            1010: 42.50%
+            0101: 31.20%
+            1100: 15.30%
+            0011: 8.50%
+            1111: 2.50%
+
+            >>> # Get solutions with decoding
+            >>> solutions = program.get_top_solutions(n=3, include_decoded=True)
+            >>> for sol in solutions:
+            ...     print(f"{sol.bitstring} -> {sol.decoded}")
+            1010 -> [0, 2]
+            0101 -> [1, 3]
+            ...
+        """
+        # Validate inputs
+        if n < 0:
+            raise ValueError(f"n must be non-negative, got {n}")
+        if not (0.0 <= min_prob <= 1.0):
+            raise ValueError(f"min_prob must be in range [0.0, 1.0], got {min_prob}")
+
+        # Handle edge case: n == 0
+        if n == 0:
+            return []
+
+        # Require probability distribution to exist
+        if not self._best_probs:
+            raise RuntimeError(
+                "No probability distribution available. The final computation step "
+                "must be performed to compute the probability distribution. "
+                "Call run(perform_final_computation=True) to execute optimization "
+                "and compute the distribution."
+            )
+        # Extract the probability distribution (nested by parameter set)
+        # _best_probs structure: {tag: {bitstring: prob}}
+        probs_dict = next(iter(self._best_probs.values()))
+
+        # Filter by minimum probability and get top n sorted by probability (descending),
+        # then bitstring (ascending) for deterministic tie-breaking
+        top_items = sorted(
+            filter(
+                lambda bitstring_prob: bitstring_prob[1] >= min_prob, probs_dict.items()
+            ),
+            key=lambda bitstring_prob: (-bitstring_prob[1], bitstring_prob[0]),
+        )[:n]
+
+        # Build result list (decode on demand)
+        return [
+            SolutionEntry(
+                bitstring=bitstring,
+                prob=prob,
+                decoded=(
+                    self._decode_solution_fn(bitstring) if include_decoded else None
+                ),
+            )
+            for bitstring, prob in top_items
+        ]
+
     @property
     def curr_params(self) -> npt.NDArray[np.float64]:
         """Get the current parameters.
@@ -706,6 +864,110 @@ class VariationalQuantumAlgorithm(QuantumProgram):
 
         return losses
 
+    @staticmethod
+    def _parse_result_tag(tag: CircuitTag) -> tuple[int, int]:
+        """Extract (param_id, qem_id) from a result tag."""
+        if not isinstance(tag, CircuitTag):
+            raise TypeError("Result tags must be CircuitTag instances.")
+        return tag.param_id, tag.qem_id
+
+    def _group_results(
+        self, results: dict[str, dict[str, int]]
+    ) -> dict[int, dict[int, list[dict[str, int]]]]:
+        """
+        Group results by parameter id and QEM id.
+
+        Returns:
+            dict[int, dict[int, list[dict[str, int]]]]: {param_id: {qem_id: [shots...]}}
+        """
+        grouped: dict[int, dict[int, list[dict[str, int]]]] = {}
+        for tag, shots in results.items():
+            param_id, qem_id = self._parse_result_tag(tag)
+            grouped.setdefault(param_id, {}).setdefault(qem_id, []).append(shots)
+        return grouped
+
+    def _reset_tag_cache(self) -> None:
+        """Reset per-run tag cache for structured result tags."""
+        self._tag_map: dict[str, CircuitTag] = {}
+
+    def _encode_tag(self, tag: CircuitTag | str) -> str:
+        """Convert structured tags to backend-safe strings."""
+        if isinstance(tag, CircuitTag):
+            tag_str = format_circuit_tag(tag)
+            self._tag_map[tag_str] = tag
+            return tag_str
+        return str(tag)
+
+    def _decode_tags(
+        self, results: dict[str, dict[str, int]]
+    ) -> dict[CircuitTag | str, dict[str, int]]:
+        """Restore structured tags from backend result labels."""
+        if not self._tag_map:
+            return results
+        return {self._tag_map.get(tag, tag): shots for tag, shots in results.items()}
+
+    def _apply_qem_protocol(
+        self, exp_matrix: npt.NDArray[np.float64]
+    ) -> list[npt.NDArray[np.float64]]:
+        """Apply the configured QEM protocol to expectation value matrices."""
+        return [
+            self._qem_protocol.postprocess_results(exp_vals) for exp_vals in exp_matrix
+        ]
+
+    def _compute_marginal_results(
+        self,
+        qem_groups: dict[int, list[dict[str, int]]],
+        measurement_groups: list[list[qml.operation.Operator]],
+        ham_ops: str | None,
+    ) -> list[npt.NDArray[np.float64] | list[npt.NDArray[np.float64]]]:
+        """Compute marginal results, handling backend modes and QEM."""
+        if self.backend.supports_expval:
+            if ham_ops is None:
+                raise ValueError(
+                    "Hamiltonian operators (ham_ops) are required when using a backend "
+                    "that supports expectation values, but were not provided."
+                )
+            ham_ops_list = ham_ops.split(";")
+            qem_group_values = [shots for _, shots in sorted(qem_groups.items())]
+            return [
+                self._apply_qem_protocol(
+                    np.array(
+                        [
+                            [shot_dict[op] for op in ham_ops_list]
+                            for shot_dict in shots_dicts
+                        ]
+                    ).T
+                )
+                for shots_dicts in qem_group_values
+            ] or []
+
+        shots_by_qem_idx = zip(*qem_groups.values())
+        marginal_results: list[
+            npt.NDArray[np.float64] | list[npt.NDArray[np.float64]]
+        ] = []
+        wire_order = tuple(reversed(self.cost_hamiltonian.wires))
+        for shots_dicts, curr_measurement_group in zip(
+            shots_by_qem_idx, measurement_groups
+        ):
+            exp_matrix = _batched_expectation(
+                shots_dicts, curr_measurement_group, wire_order
+            )
+            mitigated = self._apply_qem_protocol(exp_matrix)
+            marginal_results.append(mitigated if len(mitigated) > 1 else mitigated[0])
+
+        return marginal_results
+
+    @staticmethod
+    def _merge_param_group_counts(
+        param_group: list[tuple[str, dict[str, int]]],
+    ) -> dict[str, int]:
+        """Merge shot histograms for a single parameter group."""
+        shots_dict: dict[str, int] = {}
+        for _, d in param_group:
+            for s, c in d.items():
+                shots_dict[s] = shots_dict.get(s, 0) + c
+        return shots_dict
+
     def _post_process_results(
         self, results: dict[str, dict[str, int]], **kwargs
     ) -> dict[int, float]:
@@ -713,12 +975,8 @@ class VariationalQuantumAlgorithm(QuantumProgram):
         Post-process the results of the quantum problem.
 
         Args:
-            results (dict[str, dict[str, int]]): 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.
+            results (dict[CircuitTag, dict[str, int]]): The shot histograms of the quantum execution
+                step. Keys are CircuitTag instances containing param, QEM, and measurement ids.
 
         Returns:
             dict[int, float]: The energies for each parameter set grouping, where the dict keys
@@ -736,58 +994,12 @@ class VariationalQuantumAlgorithm(QuantumProgram):
         losses = {}
         measurement_groups = self.meta_circuits["cost_circuit"].measurement_groups
 
-        # Define key functions for 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)
-
-            # Group by QEM ID to handle error mitigation
-            qem_groups = {
-                gid: [value for _, value in group]
-                for gid, group in groupby(param_group_iterator, key=get_qem_id)
-            }
-
-            # Apply QEM protocol to expectation values (common for both backends)
-            apply_qem = lambda exp_matrix: [
-                self._qem_protocol.postprocess_results(exp_vals)
-                for exp_vals in exp_matrix
-            ]
-
-            if self.backend.supports_expval:
-                ham_ops = kwargs.get("ham_ops")
-                if ham_ops is None:
-                    raise ValueError(
-                        "Hamiltonian operators (ham_ops) are required when using a backend "
-                        "that supports expectation values, but were not provided."
-                    )
-                marginal_results = [
-                    apply_qem(
-                        np.array(
-                            [
-                                [shot_dict[op] for op in ham_ops.split(";")]
-                                for shot_dict in shots_dicts
-                            ]
-                        ).T
-                    )
-                    for shots_dicts in sorted(qem_groups.values())
-                ] or []
-            else:
-                shots_by_qem_idx = zip(*qem_groups.values())
-                marginal_results = []
-                for shots_dicts, curr_measurement_group in zip(
-                    shots_by_qem_idx, measurement_groups
-                ):
-                    wire_order = tuple(reversed(self.cost_hamiltonian.wires))
-                    exp_matrix = _batched_expectation(
-                        shots_dicts, curr_measurement_group, wire_order
-                    )
-                    mitigated = apply_qem(exp_matrix)
-                    marginal_results.append(
-                        mitigated if len(mitigated) > 1 else mitigated[0]
-                    )
+        for p, qem_groups in self._group_results(results).items():
+            marginal_results = self._compute_marginal_results(
+                qem_groups=qem_groups,
+                measurement_groups=measurement_groups,
+                ham_ops=kwargs.get("ham_ops"),
+            )
 
             pl_loss = (
                 self.meta_circuits["cost_circuit"]
@@ -916,7 +1128,6 @@ class VariationalQuantumAlgorithm(QuantumProgram):
             if current_loss < self._best_loss:
                 self._best_loss = current_loss
                 best_idx = np.argmin(intermediate_result.fun)
-
                 self._best_params = intermediate_result.x[best_idx].copy()
 
             self.current_iteration += 1
@@ -965,6 +1176,12 @@ class VariationalQuantumAlgorithm(QuantumProgram):
 
         self._final_params = self._minimize_res.x
 
+        # Set _best_params from final result (source of truth)
+        x = np.atleast_2d(self._minimize_res.x)
+        fun = np.atleast_1d(self._minimize_res.fun)
+        best_idx = np.argmin(fun)
+        self._best_params = x[best_idx].copy()
+
         if perform_final_computation:
             self._perform_final_computation(**kwargs)
 
@@ -974,10 +1191,6 @@ class VariationalQuantumAlgorithm(QuantumProgram):
 
     def _run_solution_measurement(self) -> None:
         """Execute measurement circuits to obtain probability distributions for solution extraction."""
-        if self._best_params is None:
-            raise RuntimeError(
-                "Optimization has not been run, no best parameters available."
-            )
 
         if "meas_circuit" not in self.meta_circuits:
             raise NotImplementedError(

divi/qprog/workflows/_qubo_partitioning.py

@@ -1,4 +1,4 @@
-# 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
 
@@ -14,9 +14,10 @@ import scipy.sparse as sps
 from dimod import BinaryQuadraticModel
 
 from divi.backends import CircuitRunner
-from divi.qprog.algorithms import QAOA, QUBOProblemTypes
+from divi.qprog.algorithms import QAOA
 from divi.qprog.batch import ProgramBatch
 from divi.qprog.optimizers import MonteCarloOptimizer, Optimizer, copy_optimizer
+from divi.qprog.typing import QUBOProblemTypes
 
 
 # Helper function to merge subsamples in-place

divi/reporting/_reporter.py

@@ -1,8 +1,10 @@
-# 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 atexit
 import logging
+import os
 from abc import ABC, abstractmethod
 from queue import Queue
 
@@ -64,12 +66,26 @@ class QueueProgressReporter(ProgressReporter):
 class LoggingProgressReporter(ProgressReporter):
     """Reports progress by logging messages to the console."""
 
+    _atexit_registered = False
+
     def __init__(self):
         # Use the same console instance that RichHandler uses to avoid interference
         self._console = Console(file=None)  # file=None uses stdout, same as RichHandler
         self._status = None  # Track active status for overwriting messages
         self._current_msg = None  # Track current main message
         self._polling_msg = None  # Track current polling message
+        self._disable_progress = self._should_disable_progress()
+
+    def _ensure_atexit_hook(self):
+        if self._disable_progress or LoggingProgressReporter._atexit_registered:
+            return
+        atexit.register(self._close_status)
+        LoggingProgressReporter._atexit_registered = True
+
+    @staticmethod
+    def _should_disable_progress() -> bool:
+        disable_env = os.getenv("DIVI_DISABLE_PROGRESS", "").strip().lower()
+        return disable_env in {"1", "true", "yes", "on"}
 
     def _close_status(self):
         """Close any active status."""
@@ -90,9 +106,12 @@ class LoggingProgressReporter(ProgressReporter):
 
     def _update_or_create_status(self):
         """Update existing status or create a new one with combined message."""
+        if self._disable_progress:
+            return
         status_msg = self._build_status_msg()
         if not status_msg:
             return
+        self._ensure_atexit_hook()
         if self._status:
             self._status.update(status_msg)
         else:
@@ -105,6 +124,9 @@ class LoggingProgressReporter(ProgressReporter):
         logger.info(f"Finished Iteration #{kwargs['iteration']}")
 
     def info(self, message: str, overwrite: bool = False, **kwargs):
+        if self._disable_progress:
+            logger.info(message)
+            return
         # A special check for iteration updates to use Rich's status for overwriting
         if "poll_attempt" in kwargs:
             self._polling_msg = (