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

divi/qprog/algorithms/_ansatze.py

@@ -143,11 +143,37 @@ class GenericLayerAnsatz(Ansatz):
 
 
 class QAOAAnsatz(Ansatz):
+    """
+    QAOA-style ansatz using PennyLane's QAOAEmbedding.
+
+    Implements a parameterized ansatz based on the Quantum Approximate Optimization
+    Algorithm structure, alternating between problem and mixer Hamiltonians.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for QAOA ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters needed per layer.
+        """
         return qml.QAOAEmbedding.shape(n_layers=1, n_wires=n_qubits)[1]
 
     def build(self, params, n_qubits: int, n_layers: int, **kwargs):
+        """
+        Build the QAOA ansatz circuit.
+
+        Args:
+            params: Parameter array to use for the ansatz.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of QAOA layers.
+            **kwargs: Additional unused arguments.
+        """
         qml.QAOAEmbedding(
             features=[],
             weights=params.reshape(n_layers, -1),
@@ -156,11 +182,23 @@ class QAOAAnsatz(Ansatz):
 
 
 class HardwareEfficientAnsatz(Ansatz):
+    """
+    Hardware-efficient ansatz (not yet implemented).
+
+    This ansatz is designed to be easily implementable on near-term quantum hardware,
+    typically using native gate sets and connectivity patterns.
+
+    Note:
+        This class is a placeholder for future implementation.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """Not yet implemented."""
         raise NotImplementedError("HardwareEfficientAnsatz is not yet implemented.")
 
     def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
+        """Not yet implemented."""
         raise NotImplementedError("HardwareEfficientAnsatz is not yet implemented.")
 
 
@@ -168,13 +206,42 @@ class HardwareEfficientAnsatz(Ansatz):
 
 
 class UCCSDAnsatz(Ansatz):
+    """
+    Unitary Coupled Cluster Singles and Doubles (UCCSD) ansatz.
+
+    This ansatz is specifically designed for quantum chemistry calculations,
+    implementing the UCCSD approximation which includes all single and double
+    electron excitations from a reference state.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, n_electrons: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for UCCSD ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters (number of single + double excitations).
+        """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         s_wires, d_wires = qml.qchem.excitations_to_wires(singles, doubles)
         return len(s_wires) + len(d_wires)
 
     def build(self, params, n_qubits: int, n_layers: int, n_electrons: int, **kwargs):
+        """
+        Build the UCCSD ansatz circuit.
+
+        Args:
+            params: Parameter array for excitation amplitudes.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of UCCSD layers (repeats).
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+        """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         s_wires, d_wires = qml.qchem.excitations_to_wires(singles, doubles)
         hf_state = qml.qchem.hf_state(n_electrons, n_qubits)
@@ -190,12 +257,41 @@ class UCCSDAnsatz(Ansatz):
 
 
 class HartreeFockAnsatz(Ansatz):
+    """
+    Hartree-Fock-based ansatz for quantum chemistry.
+
+    This ansatz prepares the Hartree-Fock reference state and applies
+    parameterized single and double excitation gates. It's a simplified
+    alternative to UCCSD, often used as a starting point for VQE calculations.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, n_electrons: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for Hartree-Fock ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters (number of single + double excitations).
+        """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         return len(singles) + len(doubles)
 
     def build(self, params, n_qubits: int, n_layers: int, n_electrons: int, **kwargs):
+        """
+        Build the Hartree-Fock ansatz circuit.
+
+        Args:
+            params: Parameter array for excitation amplitudes.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of ansatz layers.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+        """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         hf_state = qml.qchem.hf_state(n_electrons, n_qubits)
 

divi/qprog/algorithms/_qaoa.py

@@ -33,6 +33,16 @@ QUBOProblemTypes = list | np.ndarray | sps.spmatrix | QuadraticProgram
 
 
 def draw_graph_solution_nodes(main_graph, partition_nodes):
+    """
+    Visualize a graph with solution nodes highlighted.
+
+    Draws the graph with nodes colored to distinguish solution nodes (red) from
+    other nodes (light blue).
+
+    Args:
+        main_graph: NetworkX graph to visualize.
+        partition_nodes: Collection of node indices that are part of the solution.
+    """
     # Create a dictionary for node colors
     node_colors = [
         "red" if node in partition_nodes else "lightblue" for node in main_graph.nodes()
@@ -228,10 +238,9 @@ class QAOA(QuantumProgram):
         self._is_compute_probabilites = False
         self.optimizer = optimizer if optimizer is not None else MonteCarloOptimizer()
 
-        # Shared Variables
-        self.probs = kwargs.pop("probs", {})
-        self._solution_nodes = kwargs.pop("solution_nodes", [])
-        self._solution_bitstring = kwargs.pop("solution_bitstring", [])
+        self._probs = {}
+        self._solution_nodes = []
+        self._solution_bitstring = []
 
         (
             self.cost_hamiltonian,
@@ -256,18 +265,41 @@ class QAOA(QuantumProgram):
             self.loss_constant = 0.0
 
         kwargs.pop("is_constrained", None)
-        super().__init__(has_final_computation=True, **kwargs)
+        super().__init__(**kwargs)
 
         self._meta_circuits = self._create_meta_circuits_dict()
 
     @property
     def solution(self):
+        """
+        Get the solution found by QAOA optimization.
+
+        Returns:
+            list: For graph problems, returns a list of selected node indices.
+                For QUBO problems, returns a list/array of binary values.
+        """
         return (
             self._solution_nodes
             if self.graph_problem is not None
             else self._solution_bitstring
         )
 
+    @property
+    def probs(self) -> dict:
+        """
+        Get a copy of the probability distributions from final measurements.
+
+        Returns:
+            dict: Copy of the probability distributions dictionary. Keys are
+                circuit tags, values are probability distributions.
+        """
+        return self._probs.copy()
+
+    @probs.setter
+    def probs(self, value: dict):
+        """Set the probability distributions."""
+        self._probs = value
+
     def _create_meta_circuits_dict(self) -> dict[str, MetaCircuit]:
         """
         Generate the meta circuits for the QAOA problem.
@@ -341,7 +373,7 @@ class QAOA(QuantumProgram):
                 params_group, tag_prefix=f"{p}"
             )
 
-            self.circuits.append(circuit)
+            self._circuits.append(circuit)
 
     def _post_process_results(self, results):
         """
@@ -365,19 +397,26 @@ class QAOA(QuantumProgram):
         return losses
 
     def _run_final_measurement(self):
+        """
+        Execute final measurement circuits to obtain probability distributions.
+
+        Runs the optimized circuit with final parameters to get the full probability
+        distribution over all measurement outcomes, which is used to extract the
+        solution bitstring.
+        """
         self._is_compute_probabilites = True
 
-        self._curr_params = np.array(self.final_params)
+        self._curr_params = np.array(self._final_params)
 
-        self.circuits[:] = []
+        self._circuits[:] = []
 
         self._generate_circuits()
 
-        self.probs.update(self._dispatch_circuits_and_process_results())
+        self._probs.update(self._dispatch_circuits_and_process_results())
 
         self._is_compute_probabilites = False
 
-    def compute_final_solution(self):
+    def _perform_final_computation(self):
         """
         Computes and extracts the final solution from the QAOA optimization process.
         This method performs the following steps:
@@ -397,37 +436,14 @@ class QAOA(QuantumProgram):
 
         self.reporter.info(message="🏁 Computing Final Solution 🏁")
 
-        # Convert losses dict to list to apply ordinal operations
-        final_losses_list = list(self.losses[-1].values())
-
-        # Get the index of the smallest loss in the last operation
-        best_solution_idx = min(
-            range(len(final_losses_list)),
-            key=lambda x: final_losses_list.__getitem__(x),
-        )
-
-        # Insert the measurement circuit here
         self._run_final_measurement()
 
-        # Find the key matching the best_solution_idx with possible metadata in between
-        pattern = re.compile(rf"^{best_solution_idx}(?:_[^_]*)*_0$")
-        matching_keys = [k for k in self.probs.keys() if pattern.match(k)]
-
-        # Some minor sanity checks
-        if len(matching_keys) == 0:
-            raise RuntimeError("No matching key found.")
-        if len(matching_keys) > 1:
-            raise RuntimeError(f"More than one matching key found.")
+        final_measurement_probs = next(iter(self._probs.values()))
 
-        best_solution_key = matching_keys[0]
-        # Retrieve the probability distribution dictionary of the best solution
-        best_solution_probs = self.probs[best_solution_key]
-
-        # Retrieve the bitstring with the actual best solution
         # Reverse to account for the endianness difference
-        best_solution_bitstring = max(best_solution_probs, key=best_solution_probs.get)[
-            ::-1
-        ]
+        best_solution_bitstring = max(
+            final_measurement_probs, key=final_measurement_probs.get
+        )[::-1]
 
         if isinstance(self.problem, QUBOProblemTypes):
             self._solution_bitstring[:] = np.fromiter(
@@ -439,17 +455,29 @@ class QAOA(QuantumProgram):
                 m.start() for m in re.finditer("1", best_solution_bitstring)
             ]
 
-        self.reporter.info(message="Computed Final Solution!")
-
         return self._total_circuit_count, self._total_run_time
 
     def draw_solution(self):
+        """
+        Visualize the solution found by QAOA for graph problems.
+
+        Draws the graph with solution nodes highlighted in red and other nodes
+        in light blue. If the solution hasn't been computed yet, it will be
+        calculated first.
+
+        Raises:
+            RuntimeError: If called on a QUBO problem instead of a graph problem.
+
+        Note:
+            This method only works for graph problems. For QUBO problems, access
+            the solution directly via the `solution` property.
+        """
         if self.graph_problem is None:
             raise RuntimeError(
                 "The problem is not a graph problem. Cannot draw solution."
             )
 
         if not self._solution_nodes:
-            self.compute_final_solution()
+            self._perform_final_computation()
 
         draw_graph_solution_nodes(self.problem, self._solution_nodes)

divi/qprog/algorithms/_vqe.py

@@ -29,13 +29,20 @@ class VQE(QuantumProgram):
         Initialize the VQE problem.
 
         Args:
-            hamiltonain (pennylane.operation.Operator, optional): A Hamiltonian representing the problem.
-            molecule (pennylane.qchem.Molecule, optional): The molecule representing the problem.
-            n_electrons (int, optional): Number of electrons associated with the Hamiltonian.
-                Only needs to be provided when a Hamiltonian is given.
-            ansatz (Ansatz): The ansatz to use for the VQE problem
-            optimizer (Optimizers): The optimizer to use.
-            max_iterations (int): Maximum number of iteration optimizers.
+            hamiltonian (pennylane.operation.Operator, optional): A Hamiltonian
+                representing the problem.
+            molecule (pennylane.qchem.Molecule, optional): The molecule representing
+                the problem.
+            n_electrons (int, optional): Number of electrons associated with the
+                Hamiltonian. Only needs to be provided when a Hamiltonian is given.
+            n_layers (int, optional): Number of ansatz layers. Defaults to 1.
+            ansatz (Ansatz, optional): The ansatz to use for the VQE problem.
+                Defaults to HartreeFockAnsatz.
+            optimizer (Optimizer, optional): The optimizer to use. Defaults to
+                MonteCarloOptimizer.
+            max_iterations (int, optional): Maximum number of optimization iterations.
+                Defaults to 10.
+            **kwargs: Additional keyword arguments passed to the parent QuantumProgram.
         """
 
         # Local Variables
@@ -57,12 +64,33 @@ class VQE(QuantumProgram):
 
     @property
     def n_params(self):
+        """
+        Get the total number of parameters for the VQE ansatz.
+
+        Returns:
+            int: Total number of parameters (n_params_per_layer * n_layers).
+        """
         return (
             self.ansatz.n_params_per_layer(self.n_qubits, n_electrons=self.n_electrons)
             * self.n_layers
         )
 
     def _process_problem_input(self, hamiltonian, molecule, n_electrons):
+        """
+        Process and validate the VQE problem input.
+
+        Handles both Hamiltonian-based and molecule-based problem specifications,
+        extracting the necessary information (n_qubits, n_electrons, hamiltonian).
+
+        Args:
+            hamiltonian: PennyLane Hamiltonian operator or None.
+            molecule: PennyLane Molecule object or None.
+            n_electrons: Number of electrons or None.
+
+        Raises:
+            ValueError: If neither hamiltonian nor molecule is provided.
+            UserWarning: If n_electrons conflicts with the molecule's electron count.
+        """
         if hamiltonian is None and molecule is None:
             raise ValueError(
                 "Either one of `molecule` and `hamiltonian` must be provided."
@@ -175,9 +203,24 @@ class VQE(QuantumProgram):
                 "cost_circuit"
             ].initialize_circuit_from_params(params_group, tag_prefix=f"{p}")
 
-            self.circuits.append(circuit)
+            self._circuits.append(circuit)
 
     def _run_optimization_circuits(self, store_data, data_file):
+        """
+        Execute the circuits for the current optimization iteration.
+
+        Validates that the Hamiltonian is properly set before running circuits.
+
+        Args:
+            store_data (bool): Whether to save iteration data.
+            data_file (str): Path to file for saving data.
+
+        Returns:
+            dict: Loss values for each parameter set.
+
+        Raises:
+            RuntimeError: If the cost Hamiltonian is not set or empty.
+        """
         if self.cost_hamiltonian is None or len(self.cost_hamiltonian) == 0:
             raise RuntimeError(
                 "Hamiltonian operators must be generated before running the VQE"