Feature/documentation (#33)

* Added documentation to the Grover and MaxKCutGrover mixer classes.

* Added documentation to the MaxKCutLX class.

* Added documentation to the X, XY and XYTensor mixer classes. Also did some refining on the documentation of the mixer classes.

* Added documentation to the utility classes and functions.

* Added documentation to the OptResults and QAOA classes.

* Restore example notebooks to match original main branch.

* Fixed spelling errors, removed whitespaces and added some comments to docstring.

Author: dinasl

qaoa/mixers/grover_mixer.py

@@ -6,8 +6,25 @@
 
 
 class Grover(Mixer):
+    """
+    Grover mixer.
+
+    Subclass of the `Mixer` subclass that implements the Grover mixing operation.
+
+    Attributes:
+        subcircuit (InitialState): The initial state circuit to be tensorized.
+        circuit (QuantumCircuit): The quantum circuit representing the mixer.
+        mixer_param (Parameter): The parameter for the mixer.
+        N_qubits (int): The number of qubits in the mixer circuit.
+
+    Methods:
+        create_circuit(): Constructs the Grover mixer circuit using the subcircuit.
+    """
+
     def __init__(self, subcircuit: InitialState) -> None:
         """
+        Initializes the Grover mixer.
+
         Args:
             subcircuit (InitialState): the circuit that is to be tensorised
         """
@@ -16,9 +33,13 @@ def __init__(self, subcircuit: InitialState) -> None:
         self.N_qubits = subcircuit.N_qubits
 
     def create_circuit(self):
-        # given feasibel states f \in F,
-        # Let US the circuit that prepares US = 1/|F| \sum_{f\inF} |f>
-        # The Grover mixer has the form US^\dagger X^n C^{n-1}Phase X^n US,
+        """
+        Constructs the Grover mixer circuit using the subcircuit.
+
+        Given feasible states f \in F,
+        and let US be the circuit that prepares US = 1/|F| \sum_{f\inF} |f>.
+        The Grover mixer has the form US^\dagger X^n C^{n-1}Phase X^n US.
+        """
 
         self.subcircuit.create_circuit()
         US = self.subcircuit.circuit

qaoa/mixers/maxkcut_grover_mixer.py

@@ -9,9 +9,39 @@
 
 
 class MaxKCutGrover(Mixer):
+    """
+    Grover mixer for the Max K-Cut problem.
+
+    Subclass of the `Mixer` subclass that implements the Grover mixing operation for the Max k-cut problem.
+
+    Attributes:
+        k_cuts (int): The number of cuts in the Max k-Cut problem.
+        problem_encoding (str): The encoding of the problem, either "onehot" or "binary".
+        color_encoding (str): The encoding of colors, can be "max_balanced", "Dicke1_2", or "LessThanK".
+        tensorized (bool): Whether to use tensorization for the mixer.
+
+    Methods:
+        is_power_of_two(): Returns True if `k_cuts` is a power of two, False otherwise.
+        set_numV(k): Sets the number of vertices based on the number of cuts.
+        create_circuit(): Constructs the Grover mixer circuit for the Max k-Cut problem.
+    """
+
     def __init__(
         self, k_cuts: int, problem_encoding: str, color_encoding: str, tensorized: bool
     ) -> None:
+        """
+        Initializes the MaxKCutGrover mixer.
+
+        Args:
+            k_cuts (int): The number of cuts in the Max k-Cut problem.
+            problem_encoding (str): The encoding of the problem, either "onehot" or "binary".
+            color_encoding (str): The encoding of colors, can be "max_balanced", "Dicke1_2", or "LessThanK".
+            tensorized (bool): Whether to use tensorization for the mixer.
+
+        Raises:
+            ValueError: If `k_cuts` is less than 2 or greater than 8, or if `problem_encoding` is not valid.
+            ValueError: If `color_encoding` is not valid for the given `k_cuts`.
+        """
         if (k_cuts < 2) or (k_cuts > 8):
             raise ValueError(
                 "k_cuts must be 2 or more, and is not implemented for k_cuts > 8"
@@ -45,6 +75,15 @@ def is_power_of_two(self) -> bool:
         return False
 
     def set_numV(self, k):
+        """
+        Set the number of vertices based on the number of cuts.
+
+        Args:
+            k (int): The number of cuts in the Max k-Cut problem.
+
+        Raises:
+            ValueError: If the total number of qubits is not a multiple of k.
+        """
         num_V = self.N_qubits / k
 
         if not num_V.is_integer():
@@ -55,6 +94,10 @@ def set_numV(self, k):
         self.num_V = int(num_V)
 
     def create_circuit(self) -> None:
+        """
+        Constructs the Grover mixer circuit for the Max k-Cut problem.
+        """
+
         if self.problem_encoding == "binary":
             self.k_bits = int(np.ceil(np.log2(self.k_cuts)))
             self.set_numV(self.k_bits)

qaoa/mixers/maxkcut_lx_mixer.py

@@ -10,7 +10,36 @@
 
 
 class MaxKCutLX(Mixer):
+    """
+    Logical X (LX) mixer for the Max k-Cut problem.
+
+    Subclass of the `Mixer` subclass that implements the LX mixing operation for the Max k-Cut problem.
+
+    Attributes:
+        k_cuts (int): The number of cuts in the Max k-Cut problem.
+        color_encoding (str): The encoding of colors, can be "LessThanK", "Dicke1_2", or "max_balanced".
+        topology (str): The topology of the mixer, either "standard" or "ring".
+
+    Methods:
+        is_power_of_two(): Returns True if `k_cuts` is a power of two, False otherwise.
+        create_SparsePauliOp(): Creates the sparse Pauli operator for the given `k_cuts`.
+        create_circuit(): Constructs the LX mixer circuit for the Max k-Cut problem.
+    """
+
     def __init__(self, k_cuts: int, color_encoding: str, topology: str = "standard"):
+        """
+        Initializes the MaxKCutLX mixer.
+
+        Args:
+            k_cuts (int): The number of cuts in the Max k-Cut problem.
+            color_encoding (str): The encoding of colors, can be "LessThanK", "Dicke1_2", or "max_balanced".
+            topology (str): The topology of the mixer, either "standard" or "ring".
+
+        Raises:
+            ValueError: If `k_cuts` is a power of two.
+            ValueError: If `color_encoding` is not specified.
+            ValueError: If `k_cuts` is 3 and `topology` is not "standard" or "ring".
+        """
         if (k_cuts < 2) or (k_cuts > 8):
             raise ValueError(
                 "k_cuts must be 2 or more, and is not implemented for k_cuts > 8"
@@ -33,15 +62,16 @@ def __init__(self, k_cuts: int, color_encoding: str, topology: str = "standard")
 
     def is_power_of_two(self) -> bool:
         """
-        Return True if self.k_cuts is a power of two, False otherwise.
+        Returns:
+            bool: True if self.k_cuts is a power of two, False otherwise.
         """
         if self.k_cuts > 0 and (self.k_cuts & (self.k_cuts - 1)) == 0:
             return True
         return False
 
     def create_SparsePauliOp(self) -> None:
         """
-        Create sparse Pauli operator for given k. Hard coded
+        Create sparse Pauli operator for given k. Hard coded.
 
         Returns:
             None
@@ -108,6 +138,9 @@ def create_SparsePauliOp(self) -> None:
         self.op = SparsePauliOp(data, coeffs=coeffs)
 
     def create_circuit(self) -> None:
+        """
+        Constructs the LX mixer circuit for the Max k-Cut problem.
+        """
         self.num_V = int(self.N_qubits / self.k_bits)
         q = QuantumRegister(self.N_qubits)
         mixer_param = Parameter("x_beta")

qaoa/mixers/x_mixer.py

@@ -5,10 +5,30 @@
 
 
 class X(Mixer):
+    """
+    X mixer.
+
+    Subclass of the `Mixer` subclass that implements the X mixing operation.
+
+    Attributes:
+        mixer_param (Parameter): The parameter for the mixer.
+        N_qubits (int): The number of qubits in the circuit.
+        circuit (QuantumCircuit): The mixer's quantum circuit.
+
+    Methods:
+        create_circuit(): Constructs the X mixer circuit.
+    """
+
     def __init__(self) -> None:
+        """
+        Initializes the X mixer.
+        """
         self.mixer_param = Parameter("x_beta")
 
     def create_circuit(self):
+        """
+        Constructs the X mixer circuit.
+        """
         q = QuantumRegister(self.N_qubits)
 
         self.circuit = QuantumCircuit(q)

qaoa/mixers/xy_mixer.py

@@ -11,11 +11,38 @@
 
 
 class XY(Mixer):
+    """
+    XY mixer.
+
+    Subclass of the `Mixer` subclass that implements the XY mixing operation.
+
+    Attributes:
+        topology (list): The topology of the mixer, default is None.
+        mixer_param (Parameter): The parameter for the XY mixer.
+        N_qubits (int): The number of qubits in the mixer circuit.
+        circuit (QuantumCircuit): The quantum circuit representing the XY mixer.
+
+    Methods:
+        create_circuit(): Constructs the XY mixer circuit using the specified topology.
+        generate_pairs(n, case="ring"): Generates pairs of qubits based on the specified topology.
+    """
+
     def __init__(self, topology=None) -> None:
+        """
+        Initializes the XY mixer.
+
+        Args:
+            topology (list, optional): The topology of the mixer. If None, defaults to "ring" topology.
+        """
         self.topology = topology
         self.mixer_param = Parameter("x_beta")
 
     def create_circuit(self):
+        """
+        Constructs the XY mixer circuit using the specified topology.
+
+        If no topology is specified, it defaults to a "ring" topology.
+        """
         if not self.topology:
             print('No topology specified for the XY-mixer, assuming "ring" topology')
             self.topology = XY.generate_pairs(self.N_qubits)
@@ -28,6 +55,15 @@ def create_circuit(self):
 
     @staticmethod
     def generate_pairs(n, case="ring"):
+        """_summary_
+
+        Args:
+            n (int): The number of qubits.
+            case (str, optional): Topology. Defaults to "ring".
+
+        Returns:
+            list: A list of pairs of qubit indices based on the specified topology.
+        """
         # default ring, otherwise "chain"
         if n < 2:
             return []  # Not enough elements to form any pairs

qaoa/mixers/xy_tensor.py

@@ -8,11 +8,38 @@
 
 
 class XYTensor(Mixer):
+    """
+    XY tensor mixer for the Max k-Cut problem.
+
+    Subclass of the `Mixer` class that implements the XY tensor mixing operation for the Max k-Cut problem.
+
+    Attributes:
+        k_cuts (int): The number of cuts in the Max k-Cut problem.
+        topology (list): The topology of the mixer, default is None.
+        num_V (int): The number of vertices in the Max k-Cut problem.
+
+    Methods:
+        create_circuit(): Constructs the XY tensor mixer circuit for the Max k-Cut problem.
+    """
+
     def __init__(self, k_cuts: int, topology=None) -> None:
+        """
+        Initializes the XYTensor mixer for the Max k-Cut problem.
+
+        Args:
+            k_cuts (int): The number of cuts in the Max k-Cut problem.
+            topology (list, optional): The topology of the mixer. If None, defaults to "ring" topology.
+        """
         self.k_cuts = k_cuts
         self.topology = topology
 
     def create_circuit(self) -> None:
+        """
+        Constructs the XY tensor mixer circuit for the Max k-Cut problem.
+
+        Raises:
+            ValueError: If the total number of qubits is not a multiple of `k_cuts`.
+        """
         self.num_V = self.N_qubits / self.k_cuts
 
         if not self.num_V.is_integer():