Moreexamples (#54)

* add two examples

* Add fix_one_node highest-degree comment and new example notebooks to README

Author: fgfuchs

README.md

@@ -19,6 +19,7 @@ A flexible, modular Python library for the [Quantum Approximate Optimization Alg
 - [Further Parameters](#further-parameters)
 - [Extracting Results](#extract-results)
 - [Multi-Angle QAOA](#multi-angle-qaoa)
+- [Fixing One Node to Reduce Circuit depth/width](#fixing-one-node-to-reduce-circuit-size)
 - [Building Circuits like Lego](#building-circuits-like-lego)
 - [Minimizing Circuit Depth](#minimizing-depth-of-phase-separating-operator)
 - [Repository Structure](#repository-structure)
@@ -148,6 +149,10 @@ This library already contains several standard implementations.
 
 It is **very easy to extend this list** by implementing the abstract methods of the base classes above. Feel free to fork the repo and open a pull request!
 
+See [examples/MaxCut/OverlapInitialState.ipynb](examples/MaxCut/OverlapInitialState.ipynb) for a study of how the overlap between the initial state and the X-mixer ground state affects QAOA performance at various circuit depths.
+
+See [examples/MaxCut/KCutExamples.ipynb](examples/MaxCut/KCutExamples.ipynb) for worked examples of Max k-cut using both one-hot and binary encodings.
+
 For example, to set up QAOA for MaxCut using the X-mixer and $|+\rangle^{\otimes n}$ as the initial state:
 
 ```python
@@ -266,6 +271,22 @@ Implement `get_num_parameters()` in a custom component to enable multi-angle sup
 
 ---
 
+## Fixing One Node to Reduce Circuit Size
+
+The MaxCut (and Max k-cut) problem exhibits a **flip symmetry**: swapping all partition labels yields an equally valid solution. This symmetry allows one node to be fixed to a specific partition, removing it from the circuit entirely.
+
+The node selected for fixing is always the **highest-degree node**. Fixing this node eliminates CZ gates equal to its degree — the maximum possible reduction for a single fixed node.
+
+Enable this via the `fix_one_node` flag on any graph problem:
+
+```python
+problem = problems.MaxCut(G, fix_one_node=True)
+```
+
+See [examples/MaxCut/FixOneQubit.ipynb](examples/MaxCut/FixOneQubit.ipynb) for a worked example showing the circuit-size reduction and that the approximation quality is preserved.
+
+---
+
 ## Minimizing Depth of Phase Separating Operator
 
 Assuming all-to-all connectivity of qubits, one can minimize the circuit depth of the phase separating operator by solving the minimum edge colouring problem. This is implemented in [GraphHandler](qaoa/util/graphutils.py) and is invoked automatically. An [example](examples/MaxCut/MinimalDepth.ipynb) output is shown below:

examples/MaxCut/FixOneQubit.ipynb

@@ -15,7 +15,9 @@ class GraphProblem(Problem):
     Attributes:
         G: The graph to be used in the problem.
         N_qubits_per_node (int): Number of qubits per node.
-        fix_one_node (bool): If True, fixes the last node to "color1". 
+        fix_one_node (bool): If True, fixes the highest-degree node to "color1",
+            reducing circuit size. The highest-degree node is chosen to maximize the
+            number of entangling gates eliminated.
     
     Methods:
         create_edge_circuit(theta): Abstract method to create circuit for an edge
@@ -30,17 +32,19 @@ def __init__(
         self,
         G,
         N_qubits_per_node=1,
-        fix_one_node: bool = False,  # this fixes the last node to color 1, i.e., one qubit gets removed
+        fix_one_node: bool = False,  # fixes the highest-degree node to color 1, removing it from the circuit and eliminating entangling gates proportional to its degree
     ) -> None:
         """
         Args:
             G: The graph to be used in the problem.
             N_qubits_per_node (int): Number of qubits per node.
-            fix_one_node (bool): If True, fixes the last node to "color1".
+            fix_one_node (bool): If True, fixes the highest-degree node to "color1", reducing
+                the circuit size. The highest-degree node is chosen to maximize the number of
+                entangling gates eliminated (proportional to the degree of the fixed node).
         """
         super().__init__()
 
-        # fixes the last node to "color1"
+        # fixes the highest-degree node (node n-1 after relabeling) to "color1"
         self.fix_one_node = fix_one_node
 
         # ensure graph has labels 0, 1, ..., num_V-1

examples/MaxCut/OverlapInitialState.ipynb

@@ -36,7 +36,9 @@ def __init__(self, G):
 
         # ensure graph has labels 0, 1, ..., num_V-1
         G_int = self.__ensure_integer_labels__(G)
-        # relabel to make node n-1 the one with maximum degree
+        # relabel to make node n-1 the one with maximum degree; when fix_one_node=True
+        # this node is fixed (removed from the circuit), maximizing the number of entangling
+        # gates eliminated (proportional to the degree of the fixed node)
         self.G = self.__get_graph_maxdegree_last_node__(G_int)
         # to avoid a deep circuit, we partition the edges into sets which can be executed in parallel
         if not nx.is_isomorphic(G, self.G):

qaoa/problems/graph_problem.py

@@ -130,6 +130,10 @@ def plot_ApproximationRatio(
 
     fig, ax = _get_fig_ax(fig)
     ax.hlines(1, 1, maxdepth, linestyles="solid", colors="black")
+    # Normalized approximation ratio for a minimization objective.
+    # Here mincost is the optimal (most negative) value and maxcost the worst.
+    # This maps exp = maxcost → 0 (worst) and exp = mincost → 1 (optimal).
+    # Hence we use (maxcost - exp) / (maxcost - mincost).
     ax.plot(
         np.arange(1, maxdepth + 1),
         (maxcost - exp) / (maxcost - mincost),