Sanne initial branch (#31)

* documentation for the files dicke_initialstate, dicke1_2_initialstate, and lessthank_initialstate

* added link to where the algorithm for different cases of k is found, and added start of documentation for maxkcut_feasible_initialstate

* futher description of Dicke1_2 class, and first part of documentation for the maxkcut_feasible_initialstate file

* updates on maxkcut_feasible_initialstates

* finished documenting maxkcut_feasible_initialstate

* documentation for the plus_initialstate file

* documentaition for statevector_initialstate

* documentation for tensor_initialstate

* changing all files so that it is in the same format as Dina's (adding line with name, parent class, raises, and defaults

* updated formatting for most files in the folder problems so that it fits the format for documentation.

* formatting done for problems folder, still need to write documentation for it

* added full documentation for exactcover_problem, and started on graph_problem.

* done documentation for graph_problem inside problems folder

* updated documentation for the maxkcut_binary_fullH file in the problems folder.

* documentation for the maxkcut_binary_powertwo file

* documentation for the maxkcut_one_hot_problem file

* documentation for the portfolio_problem file

* documentation for the qubo_problem file

* documentation on the README, added new cases for initial state, mixers and problems

* documentation on the README, added comments for correction of intro + formatting equations, created subparagraphs for create_graphs_and_draw_circuits and tensorize_mixers

* finished documentation on maxkcut_binary_poweroftow (noticed some were missing)

* deleted create_graphs_and_draw_circuits as it is already a part of qiskit

* valid combinations of initial states, mixers, and problems

* added combinations for Max k-CUT binary power of two

* took away the valid combinations section

* added documentation for maxkcut_binary_fullH that i had missed previously

* indication for standard MaxCut

* removed the tensor function from initial states list due to it only being a helper function

* added that k means hamming weight in dicke1_2_initialstate

* deleted documentation on private methods for the lessthank_initialstate file

* deleted comment #subN_qubits in tensor class

* added a little bit to the example

* fixed the example so that it doesn't use the outdated function MaxCut but rather MaxKCutBinaryPowerOfTwo

* restore WithFlip.ipynb to upstream version

* Remove VSCode settings.json from repo to replace with YAML config for Black

Author: sannesg

README.md

@@ -1,6 +1,6 @@
 # QAOA
 
-This package is a flexible python implementation of the [Quantum Approximate Optimization Algorithm](https://arxiv.org/pdf/1411.4028.pdf) /[Quantum Alternating Operator ansatz](https://arxiv.org/pdf/1709.03489.pdf)  (QAOA) **aimed at researchers** to readily test the performance of a new ansatz, a new classical optimizers, etc. By default it uses qiskit as a backend.
+This package is a flexible python implementation of the [Quantum Approximate Optimization Algorithm](https://arxiv.org/pdf/1411.4028.pdf) /[Quantum Alternating Operator ansatz](https://arxiv.org/pdf/1709.03489.pdf)  (QAOA) **aimed at researchers** to readily test the performance of a new ansatz, a new classical optimizer, etc. By default it uses qiskit as a backend.
 
 Install with `pip install qaoa` or `pip install -e .`.
 
@@ -13,7 +13,7 @@ one defines a **problem Hamiltonian** $H_P$ through the action on computational
 $$ H_P |x\rangle = c(x) |x\rangle,$$
 
 which means that ground states minimize the cost function $c$.
-Given a parametrized ansatz $ | \gamma, \beta \rangle$, a classical optimizer is used to minimize the energy
+Given a parametrized ansatz $| \gamma, \beta \rangle$, a classical optimizer is used to minimize the energy
 
 $$ \langle \gamma, \beta | H_P | \gamma, \beta \rangle.$$
 
@@ -38,29 +38,38 @@ In order to create a custom QAOA ansatz, one needs to specify a [problem](qaoa/p
 This library already contains several standard implementations.
 
 - The following [problem](qaoa/problems/base_problem.py) cases are already available:
-	- [MaxCut](qaoa/problems/maxcut_problem.py)
+	- [Max k-CUT binary power of two](qaoa/problems/maxkcut_binary_powertwo.py) *
+	- [Max k-CUT binary full H](qaoa/problems/maxkcut_binary_fullH.py)
+	- [Max k-CUT binary one hot](qaoa/problems/maxkcut_binary_one_hot.py)
 	- [QUBO](qaoa/problems/qubo_problem.py)
 	- [Exact cover](qaoa/problems/exactcover_problem.py)
 	- [Portfolio](qaoa/problems/portfolio_problem.py)
+	- [Graph](qaoa/problems/graph_problem.py)
 - The following [mixer](qaoa/mixers/base_mixer.py) cases are already available:
 	- [X-mixer](qaoa/mixers/x_mixer.py)
 	- [XY-mixer](qaoa/mixers/xy_mixer.py)
 	- [Grover-mixer](qaoa/mixers/grover_mixer.py)
+	- [Max k-CUT grover](qaoa/mixers/maxkcut_grover_mixer.py)
+	- [Max k-CUT LX](qaoa/mixers/maxkcut_lx_mixer.py)
 - The following [initial state](qaoa/initialstates/base_initialstate.py) cases are already available:
 	- [Plus](qaoa/initialstates/plus_initialstate.py)
 	- [Statevector](qaoa/initialstates/statevector_initialstate.py)
 	- [Dicke](qaoa/initialstates/dicke_initialstate.py)
+	- [Dicke 1- and 2-states superposition](qaoa/initialstates/dicke1_2_initialstate.py)
+	- [Less than k](qaoa/initialstates/lessthank_initialstate.py)
+	- [Max k-CUT feasible](qaoa/initialstates/maxkcut_feasible_initialstate.py)
 
 It is **very easy to extend this list** by providing  an implementation of a circuit/cost of the base classes mentioned above. Feel free to fork the repo and create a pull request :-)
 
 To make an ansatz for the MaxCut problem, the X-mixer and the initial state $|+\rangle^{\otimes n}$  one can create an instance like this: 
 
 	qaoa = QAOA(
 		initialstate=initialstates.Plus(),
-		problem=problems.MaxCut(G="some networkx instance"),
+		problem=problems.MaxKCutBinaryPowerOfTwo(G="some networkx instance", k_cuts=2),
 		mixer=mixers.X()
 	)
 
+*(can be used for the standard MaxCut with argument k_cuts=2)
 ***
 ### Run optimization at depth $p$
 
@@ -117,6 +126,16 @@ Additionally, for each depth every time the loss function is called, the **angle
 	qaoa.optimization_results[i]
 
 
+***
+### Tensorize mixers
+To tensorize a mixer, i.e. decomposing the mixer into a tensor product of unitaries that is 
+performed on each qubit, one can call the tensor class with the arguments of mixer and number of qubits in subpart.
+
+For example, for the standard MaxCut problem above where the X mixer was used, one could find the tensor by writing:
+
+	tensorized_mixer = Tensor(mixer.X(), number_of_qubits_of_subpart)
+<!--find out the number of qubits we want here -->
+
 ***
 ### Example usage
 

qaoa/initialstates/dicke1_2_initialstate.py

@@ -9,14 +9,22 @@
 
 class Dicke1_2(InitialState):
     """
-    Returs equal superposition Dicke 1 and Dicke 2 states. Hard Coded
+    Dicke1_2 initial state.
+
+    Subclass of the `InitialState` class, and it returns equal superposition Dicke 1 and Dicke 2 states. It is Hard Coded for the case of Hamming weight k = 6
+
+    Methods:
+        create_circuit(): Creates a circuit that is a superposition of Dicke 1 and Dicke 2 states
     """
 
     def __init__(self) -> None:
         self.k = 6
         self.N_qubits = 3
 
     def create_circuit(self) -> None:
+        """
+        Circuit to prepare a superposition of Dicke 1 and Dicke 2 states
+        """
         q = QuantumRegister(self.N_qubits)
         circuit = QuantumCircuit(q)
         X = SparsePauliOp("X")

qaoa/initialstates/dicke_initialstate.py

@@ -8,6 +8,17 @@
 
 
 class Dicke(InitialState):
+    """
+    Dicke initial state.
+
+    Subclass of the `InitialState` class, and it creates a circuit that creates a Dicke state with Hamming weight k
+
+    Attributes: 
+        k (int): The Hamming weight of the Dicke states.
+
+    Methods:
+        create_circuit(): Creates the circuit to prepare the Dicke states
+    """
     def __init__(self, k) -> None:
         """
         Args:

qaoa/initialstates/lessthank_initialstate.py

@@ -6,13 +6,38 @@
 
 
 class LessThanK(InitialState):
+    """
+    LessThanK initial state.
+
+    Subclass for the `InitialState` class, and it creates a quantum circuit that creates the initial state for the for the MAX k-CUT problem for
+    different cases of k subsets.
+
+    Attributes:
+        k (int): subsets (or "colors") of the vertices in the MAX k-CUT problem is seperated into
+
+    Methods:
+        create_circuit(): creates a circuit that can create the wanted initial state for the special k
+    """
     def __init__(self, k: int) -> None:
+        """
+        Checks that the k-value is valid and initizalizes N qubits and k cuts
+        
+        Args: 
+            k (int): the number of subsets of the vertices in the MAX k-CUT problem
+
+        Raises: 
+            ValueError: if k is neither a power of 2 or between 2 and 8
+        """
         if not LessThanK.is_power_of_two_or_between_2_and_8(k):
             raise ValueError("k must be a power of two or between 2 and 8")
         self.k = k
         self.N_qubits = int(np.ceil(np.log2(self.k)))
 
     def create_circuit(self) -> None:
+        """
+        Creates a circuit by calling on the methods for different k, following the algorithm from https://arxiv.org/abs/2411.08594. 
+        k is between 2 and 8 or a power of 2.
+        """
         if self.k == 3:
             self.circuit = self.k3()
         elif self.k == 5:
@@ -25,6 +50,12 @@ def create_circuit(self) -> None:
             self.circuit = self.power_of_two()
 
     def is_power_of_two_or_between_2_and_8(k):
+        """
+        Checks the validity of the argument k, so that k is either between 2 and 8 or a power of 2
+
+        Returns:
+            True if k is a power of 2 or between 2 and 8, and False otherwise
+        """
         # Check if k is between 2 and 8
         if 2 <= k <= 8:
             return True
@@ -37,12 +68,24 @@ def is_power_of_two_or_between_2_and_8(k):
         return False
 
     def power_of_two(self) -> QuantumCircuit:
+        """
+        Creates a circuit for the case k = a power of 2
+
+        Returns:
+            QuantumCircuit: circuit that creates the initial state for k = a power of 2
+        """
         q = QuantumRegister(self.N_qubits)
         circuit = QuantumCircuit(q)
         circuit.h(q)
         return circuit
 
     def k3(self) -> QuantumCircuit:
+        """
+        Creates a circuit for the case k = 3
+
+        Returns:
+            QuantumCircuit: circuit that creates the initial state for k = 3
+        """
         q = QuantumRegister(self.N_qubits)
         circuit = QuantumCircuit(q)
         theta = np.arccos(1 / np.sqrt(3)) * 2
@@ -54,6 +97,12 @@ def k3(self) -> QuantumCircuit:
         return circuit
 
     def k5(self) -> QuantumCircuit:
+        """
+        Creates a circuit for the case k = 5
+
+        Returns:
+            QuantumCircuit: circuit that creates the initial state for k = 5
+        """
         q = QuantumRegister(self.N_qubits)
         circuit = QuantumCircuit(q)
         theta = np.arcsin(1 / np.sqrt(5)) * 2
@@ -62,6 +111,12 @@ def k5(self) -> QuantumCircuit:
         return circuit
 
     def k6(self) -> QuantumCircuit:
+        """
+        Creates a circuit for the case k = 6
+
+        Returns:
+            QuantumCircuit: circuit that creates the initial state for k = 6
+        """
         q = QuantumRegister(self.N_qubits)
         circuit = QuantumCircuit(q)
         theta = np.pi / 2
@@ -75,6 +130,12 @@ def k6(self) -> QuantumCircuit:
         return circuit
 
     def k7(self) -> QuantumCircuit:
+        """
+        Creates a circuit for the case k = 7
+
+        Returns:
+            QuantumCircuit: circuit that creates the initial state for k = 7
+        """
         q = QuantumRegister(self.N_qubits)
         circuit = QuantumCircuit(q)
         delta = np.arcsin(1 / np.sqrt(7)) * 2

qaoa/initialstates/maxkcut_feasible_initialstate.py

@@ -9,9 +9,36 @@
 
 
 class MaxKCutFeasible(InitialState):
+    """
+    MaxKCutFeasible initial state.
+
+    Subclass of the `InitialState` class, and it determines the feasible states for the type of MAX k-CUT problem that is specified by the arguments. This specifies the number of cuts, number of qubits per vertex,
+    and method for solving the special case of k = 6.
+
+    Attributes: 
+        k_cuts (int): The number of cuts (or "colors") of the vertices in the MAX k-CUT problem is separated into.
+        problem_encoding (str): description of the type of problem, either "onehot" (which corresponds to ...) or "binary" (which corresponds to ...)
+        color_encoding (str): determines the approach to solving the MAX k-cut problem by following one of three methods, 
+                            either "Dicke1_2" (which corresponds to creating an initial state that is a superposition of the valid states that represents a color(only 6/8 possible states)),
+                            "LessThanK" (which corresponds to grouping states together and make the group represent one color),
+                            or "max_balanced" (which corresponds to the onehot case where a color corresponds to a state)
+
+    Methods:
+        create_circuit(): creates a circuit that creates an initial state for only feasible initial states of the MAX k-CUT problem given constraints
+    """
     def __init__(
         self, k_cuts: int, problem_encoding: str, color_encoding: str = "LessThanK"
     ) -> None:
+        """
+        Args:
+            k_cuts (int):
+            problem_encoding (str): description of the type of problem, either "onehot" (which corresponds to ...) or "binary" (which corresponds to ...)
+            color_encoding (str): determines the approach to solving the MAX k-cut problem by following one of three methods, 
+                                either "Dicke1_2" (which corresponds to creating an initial state that is a superposition of the valid states that represents a color(only 6/8 possible states)),
+                                "LessThanK" (which corresponds to grouping states together and make the group represent one color),
+                                or "max_balanced" (which corresponds to the onehot case where a color corresponds to a state). Defaults to "LessThanK".
+
+        """
         self.k_cuts = k_cuts
         self.problem_encoding = problem_encoding
         self.color_encoding = color_encoding
@@ -39,6 +66,10 @@ def __init__(
             self.infeasible = ["111"]
 
     def create_circuit(self) -> None:
+        """
+        Creates a circuit that creates the initial state (for only feasible states) for the MAX k-CUT problem given 
+        the methods and cuts given as arguments
+        """
         if self.problem_encoding == "binary":
             self.k_bits = int(np.ceil(np.log2(self.k_cuts)))
             self.num_V = self.N_qubits / self.k_bits

qaoa/initialstates/plus_initialstate.py

@@ -5,10 +5,21 @@
 
 
 class Plus(InitialState):
+    """
+    Plus initial state.
+
+    Subclass of `InitialState` class, and it creates an initial plus state
+
+    Methods:
+        create_circuit(): Creates a circuit that sets up plus states for the initial states
+    """
     def __init__(self) -> None:
         super().__init__()
 
     def create_circuit(self):
+        """
+        Creates a circuit of Hadamard-gates, which creates an initial state that is a plus state
+        """
         q = QuantumRegister(self.N_qubits)
         self.circuit = QuantumCircuit(q)
         self.circuit.h(q)

qaoa/initialstates/statevector_initialstate.py

@@ -5,11 +5,29 @@
 
 
 class StateVector(InitialState):
+    """
+    State vector initial state. 
+
+    Subclass of the `InitialState` class, and it creates the initial statevector.
+
+    Attributes:
+        statevector (list): The statevector to initialize the circuit with.
+
+    Methods:
+        create_circuit(): Creates a circuit that creates the initial statevector.
+    """
     def __init__(self, statevector) -> None:
+        """
+        Args:
+            statevector (list): The statevector to initialize the circuit with.
+        """
         super().__init__()
         self.statevector = statevector
 
     def create_circuit(self):
+        """
+        Creates a circuit that makes the initial statevector
+        """
         q = QuantumRegister(self.N_qubits)
         self.circuit = QuantumCircuit(q)
         self.circuit.initialize(self.statevector, q)

qaoa/initialstates/tensor_initialstate.py

@@ -7,17 +7,32 @@
 
 
 class Tensor(InitialState):
+    """
+    Tensor initial state.
+
+    Subclass of the `IntialState` class that creates a tensor out of a circuit
+
+    Attributions:
+        subcircuit (InitialState): the circuit that is to be tensorised
+        num (int): number of qubits of the subpart 
+
+    Methods:
+        create_circuit(): 
+    """
     def __init__(self, subcircuit: InitialState, num: int) -> None:
         """
         Args:
             subcircuit (InitialState): the circuit that is to be tensorised
-            #subN_qubits (int): number of qubits of the subpart
+            num (int): number of qubits of the subpart #subN_qubits
         """
         self.num = num
         self.subcircuit = subcircuit
         self.N_qubits = self.num * self.subcircuit.N_qubits
 
     def create_circuit(self) -> None:
+        """
+        Creates a circuit that tensorises a given subcircuit
+        """
         self.subcircuit.create_circuit()
         self.circuit = self.subcircuit.circuit
         for v in range(self.num - 1):