Add MaxCutFree problem and XOrbit mixer; update MixerComparison notebook with correct free and orbit ansätze

Co-authored-by: fgfuchs <2428162+fgfuchs@users.noreply.github.com>

Author: Copilot

examples/MaxCut/MixerComparison.ipynb

@@ -4,19 +4,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## QAOA Mixer Comparison: Vanilla, Free, and Orbit\n",
+    "## QAOA Ansatz Comparison: Vanilla, Free, and Orbit\n",
     "\n",
-    "This notebook compares three QAOA variants on the **house graph** (5 nodes, 6 edges):\n",
+    "This notebook compares three QAOA ansätze on the **house graph** (5 nodes, 6 edges).\n",
     "\n",
-    "| Variant | Problem | Mixer | \u03b3 / layer | \u03b2 / layer |\n",
-    "|---------|---------|-------|-----------|----------|\n",
+    "| Ansatz | Problem | Mixer | γ / layer | β / layer |\n",
+    "|--------|---------|-------|-----------|----------|\n",
     "| **Vanilla** | `MaxCut` | `X` | 1 | 1 |\n",
-    "| **Free** | `MaxCut` | `XMultiAngle` | 1 | N (one per qubit) |\n",
-    "| **Orbit** | `MaxCutOrbit` | `X` | K (one per edge orbit) | 1 |\n",
+    "| **Free** | `MaxCutFree` | `XMultiAngle` | E (one per edge) | N (one per node) |\n",
+    "| **Orbit** | `MaxCutOrbit` | `XOrbit` | K_E (one per edge orbit) | K_N (one per node orbit) |\n",
     "\n",
-    "- **Vanilla QAOA** uses the standard X mixer with a single shared \u03b3 and \u03b2 per layer.\n",
-    "- **Free QAOA** (multi-angle) gives each qubit its own independent \u03b2, increasing expressibility.\n",
-    "- **Orbit QAOA** exploits the graph's automorphism group: edges in the same symmetry orbit share a \u03b3 parameter, enabling the optimizer to differentiate structurally distinct edge types without the full multi-angle overhead."
+    "### Definitions\n",
+    "\n",
+    "- **Vanilla QAOA** uses a single shared γ for all edges and a single β for all nodes. It is the original QAOA proposal.\n",
+    "\n",
+    "- **Free QAOA** (multi-angle) maximises the number of independent parameters: each edge gets its own γ and each node gets its own β. There is no parameter sharing whatsoever.\n",
+    "\n",
+    "- **Orbit QAOA** (following [arXiv:2410.05187](https://arxiv.org/abs/2410.05187)) exploits the automorphism group Aut(G) of the graph to construct an *equivariant* ansatz. Edges related by a graph automorphism share one γ, and nodes related by a graph automorphism share one β. This is the unique parameterisation that is both equivariant and maximally expressive within the equivariant subspace."
    ]
   },
   {
@@ -49,7 +53,7 @@
    "source": [
     "### House Graph\n",
     "\n",
-    "The house graph has 5 nodes and 6 edges arranged as a square with a triangular roof."
+    "The *house graph* has 5 nodes and 6 edges: a square base with a triangular roof."
    ]
   },
   {
@@ -74,9 +78,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Compute the Optimal Cut\n",
+    "### Optimal Max Cut\n",
     "\n",
-    "Brute-force the minimum cost (maximum cut) so we can calculate approximation ratios."
+    "Brute-force the minimum QAOA cost (= maximum cut value) for reference."
    ]
   },
   {
@@ -86,22 +90,23 @@
    "outputs": [],
    "source": [
     "problem_ref = problems.MaxCut(G)\n",
-    "min_cost, max_cost = problem_ref.computeMinMaxCosts()\n",
-    "# cost() returns a positive value; the QAOA minimizes its negative\n",
-    "mincost = -min_cost   # most negative expectation value = best cut\n",
+    "min_cost, _ = problem_ref.computeMinMaxCosts()\n",
+    "# cost() is positive; QAOA minimises its negative\n",
+    "mincost = -min_cost   # most negative expectation = best cut\n",
     "maxcost = 0\n",
     "\n",
     "print(f\"Maximum cut value : {-mincost}\")\n",
-    "print(f\"mincost used for approximation ratio: {mincost}\")"
+    "print(f\"mincost (for approximation ratio): {mincost}\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Edge Orbits of the House Graph\n",
+    "### Graph Symmetry Analysis\n",
     "\n",
-    "The orbit QAOA assigns one \u03b3 parameter per edge orbit of the graph's automorphism group."
+    "The orbit QAOA uses the automorphism group Aut(G) to assign shared parameters.\n",
+    "Below we display the **node orbits** (for the β mixer parameters) and **edge orbits** (for the γ problem parameters)."
    ]
   },
   {
@@ -111,16 +116,25 @@
    "outputs": [],
    "source": [
     "orbit_problem = problems.MaxCutOrbit(G)\n",
-    "print(f\"Number of edge orbits: {orbit_problem.get_num_parameters()}\")\n",
-    "for i, orbit in enumerate(orbit_problem.edge_orbits):\n",
-    "    print(f\"  Orbit {i}: {orbit}\")"
+    "orbit_mixer  = mixers.XOrbit(G)\n",
+    "\n",
+    "print(f\"Node orbits ({len(orbit_mixer.node_orbits)} total):\")\n",
+    "for i, orb in enumerate(orbit_mixer.node_orbits):\n",
+    "    print(f\"  β_{i}: nodes {orb}\")\n",
+    "\n",
+    "print()\n",
+    "print(f\"Edge orbits ({len(orbit_problem.edge_orbits)} total):\")\n",
+    "for i, orb in enumerate(orbit_problem.edge_orbits):\n",
+    "    print(f\"  γ_{i}: edges {orb}\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Create QAOA Instances"
+    "### Create QAOA Instances\n",
+    "\n",
+    "Three instances with different parameter budgets per layer:"
    ]
   },
   {
@@ -129,7 +143,34 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Vanilla QAOA: X mixer, single \u03b3 and \u03b2 per layer\nqaoa_vanilla = QAOA(\n    problem=problems.MaxCut(G),\n    mixer=mixers.X(),\n    initialstate=initialstates.Plus(),\n)\n\n# Free QAOA: XMultiAngle mixer, one \u03b2 per qubit\nqaoa_free = QAOA(\n    problem=problems.MaxCut(G),\n    mixer=mixers.XMultiAngle(),\n    initialstate=initialstates.Plus(),\n)\n\n# Orbit QAOA: X mixer, one \u03b3 per edge orbit of the graph\nqaoa_orbit = QAOA(\n    problem=problems.MaxCutOrbit(G),\n    mixer=mixers.X(),\n    initialstate=initialstates.Plus(),\n)\n\n# Build circuits at depth 1 to inspect parameter counts\nfor q in (qaoa_vanilla, qaoa_free, qaoa_orbit):\n    q.createParameterizedCircuit(depth=1)\n\nprint(f\"Vanilla  \u2014 \u03b3/layer: {qaoa_vanilla.n_gamma}, \u03b2/layer: {qaoa_vanilla.n_beta}\")\nprint(f\"Free     \u2014 \u03b3/layer: {qaoa_free.n_gamma},    \u03b2/layer: {qaoa_free.n_beta}\")\nprint(f\"Orbit    \u2014 \u03b3/layer: {qaoa_orbit.n_gamma},   \u03b2/layer: {qaoa_orbit.n_beta}\")"
+    "# Vanilla: one shared γ and one shared β\n",
+    "qaoa_vanilla = QAOA(\n",
+    "    problem=problems.MaxCut(G),\n",
+    "    mixer=mixers.X(),\n",
+    "    initialstate=initialstates.Plus(),\n",
+    ")\n",
+    "\n",
+    "# Free: one γ per edge, one β per node\n",
+    "qaoa_free = QAOA(\n",
+    "    problem=problems.MaxCutFree(G),\n",
+    "    mixer=mixers.XMultiAngle(),\n",
+    "    initialstate=initialstates.Plus(),\n",
+    ")\n",
+    "\n",
+    "# Orbit: one γ per edge orbit, one β per node orbit (arXiv:2410.05187)\n",
+    "qaoa_orbit = QAOA(\n",
+    "    problem=problems.MaxCutOrbit(G),\n",
+    "    mixer=mixers.XOrbit(G),\n",
+    "    initialstate=initialstates.Plus(),\n",
+    ")\n",
+    "\n",
+    "# Build circuits at depth 1 to inspect parameter counts\n",
+    "for q in (qaoa_vanilla, qaoa_free, qaoa_orbit):\n",
+    "    q.createParameterizedCircuit(depth=1)\n",
+    "\n",
+    "print(f\"Vanilla — γ/layer: {qaoa_vanilla.n_gamma},  β/layer: {qaoa_vanilla.n_beta}\")\n",
+    "print(f\"Free    — γ/layer: {qaoa_free.n_gamma}  (1 per edge),  β/layer: {qaoa_free.n_beta} (1 per node)\")\n",
+    "print(f\"Orbit   — γ/layer: {qaoa_orbit.n_gamma}  (1 per edge orbit), β/layer: {qaoa_orbit.n_beta} (1 per node orbit)\")"
    ]
   },
   {
@@ -138,7 +179,8 @@
    "source": [
     "### Energy Landscape at Depth 1 (Vanilla)\n",
     "\n",
-    "Sample the energy landscape over (\u03b3, \u03b2) for the vanilla instance."
+    "Sample the cost landscape over the (γ, β) grid for the vanilla instance.  \n",
+    "This grid search also provides the starting point for deeper optimisation."
    ]
   },
   {
@@ -152,15 +194,18 @@
     "\n",
     "fig = plt.figure(figsize=(6, 5))\n",
     "plot_E(qaoa_vanilla, fig=fig)\n",
-    "plt.title(\"Vanilla QAOA \u2014 energy landscape (depth 1)\")\n",
+    "plt.title(\"Vanilla QAOA — energy landscape (depth 1)\")\n",
     "plt.show()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Run Optimization"
+    "### Run Optimisation\n",
+    "\n",
+    "Optimise all three ansätze up to `maxdepth = 5`.  \n",
+    "Each depth is initialised using the interpolation heuristic from the previous depth."
    ]
   },
   {
@@ -194,26 +239,26 @@
     "plot_ApproximationRatio(\n",
     "    qaoa_vanilla, maxdepth,\n",
     "    mincost=mincost, maxcost=maxcost,\n",
-    "    label=\"Vanilla (X mixer)\",\n",
+    "    label=f\"Vanilla  (1γ + 1β)\",\n",
     "    style=\"o--b\",\n",
     "    fig=fig,\n",
     ")\n",
     "plot_ApproximationRatio(\n",
     "    qaoa_free, maxdepth,\n",
     "    mincost=mincost, maxcost=maxcost,\n",
-    "    label=\"Free (XMultiAngle mixer)\",\n",
+    "    label=f\"Free     ({qaoa_free.n_gamma}γ + {qaoa_free.n_beta}β, one per edge/node)\",\n",
     "    style=\"s--r\",\n",
     "    fig=fig,\n",
     ")\n",
     "plot_ApproximationRatio(\n",
     "    qaoa_orbit, maxdepth,\n",
     "    mincost=mincost, maxcost=maxcost,\n",
-    "    label=\"Orbit (MaxCutOrbit + X mixer)\",\n",
+    "    label=f\"Orbit    ({qaoa_orbit.n_gamma}γ + {qaoa_orbit.n_beta}β, one per orbit)\",\n",
     "    style=\"^--g\",\n",
     "    fig=fig,\n",
     ")\n",
     "\n",
-    "plt.title(\"Approximation ratio vs. depth \u2014 House graph\")\n",
+    "plt.title(\"Approximation ratio vs. depth — House graph\")\n",
     "plt.tight_layout()\n",
     "plt.show()"
    ]
@@ -224,9 +269,7 @@
    "source": [
     "### Optimal Angles at Maximum Depth (Vanilla)\n",
     "\n",
-    "`plot_angles` expects the standard 1 \u03b3 + 1 \u03b2 per-layer format.  \n",
-    "We display it for the vanilla variant; the free and orbit instances use a\n",
-    "different layout (multiple \u03b3 or \u03b2 per layer)."
+    "`plot_angles` expects the 1 γ + 1 β per-layer format, so we display it only for the vanilla ansatz."
    ]
   },
   {
@@ -237,7 +280,7 @@
    "source": [
     "fig = plt.figure()\n",
     "plot_angles(qaoa_vanilla, maxdepth, label=\"Vanilla\", style=\"ob\", fig=fig)\n",
-    "plt.title(f\"Optimal angles \u2014 Vanilla QAOA, depth {maxdepth}\")\n",
+    "plt.title(f\"Optimal angles — Vanilla QAOA, depth {maxdepth}\")\n",
     "plt.tight_layout()\n",
     "plt.show()"
    ]
@@ -256,4 +299,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

qaoa/mixers/__init__.py

@@ -2,6 +2,7 @@
 from .xy_mixer import XY
 from .x_mixer import X
 from .x_multiangle_mixer import XMultiAngle
+from .x_orbit_mixer import XOrbit
 from .grover_mixer import Grover
 from .xy_tensor import XYTensor
 from .maxkcut_grover_mixer import MaxKCutGrover

qaoa/mixers/x_orbit_mixer.py

@@ -0,0 +1,151 @@
+from collections import defaultdict
+
+import networkx as nx
+from networkx.algorithms.isomorphism import GraphMatcher
+from qiskit import QuantumCircuit, QuantumRegister
+from qiskit.circuit import Parameter
+
+from .base_mixer import Mixer
+from qaoa.util import GraphHandler
+
+
+class XOrbit(Mixer):
+    """
+    X mixer with one independent rotation angle per node orbit.
+
+    Uses the automorphism group of the graph to identify structurally
+    equivalent nodes (qubits).  Nodes in the same orbit under the graph's
+    automorphism group share a single :math:`\\beta` parameter, implementing
+    the orbit-equivariant mixer described in *arXiv:2410.05187*.
+
+    Combined with :class:`~qaoa.problems.MaxCutOrbit` (one :math:`\\gamma`
+    per edge orbit), this gives the orbit QAOA ansatz that is equivariant
+    under the full symmetry group of the graph.
+
+    Attributes:
+        node_orbits (list[list]): List of node groups; each group contains
+            all nodes that belong to the same automorphism orbit.
+        node_to_orbit (dict): Mapping from a canonical node label to its
+            orbit index.
+
+    Args:
+        G (nx.Graph): The graph whose node orbits define the parameter
+            sharing.  A :class:`~qaoa.util.GraphHandler` is used internally
+            to obtain the same canonical node ordering as the problem circuit.
+    """
+
+    def __init__(self, G: nx.Graph) -> None:
+        """
+        Initialises the XOrbit mixer.
+
+        Args:
+            G (nx.Graph): The input graph used to compute node orbits.
+        """
+        super().__init__()
+        graph_handler = GraphHandler(G)
+        self._canonical_G = graph_handler.G
+        self._compute_node_orbits()
+
+    # ------------------------------------------------------------------
+    # Orbit computation
+    # ------------------------------------------------------------------
+
+    def _compute_node_orbits(self) -> None:
+        """
+        Compute node orbits of ``self._canonical_G`` under its automorphism
+        group.
+
+        Sets:
+            self.node_orbits: list of node-lists, one list per orbit.
+            self.node_to_orbit: dict mapping each canonical node label to
+                its orbit index.
+        """
+        G = self._canonical_G
+        # Use sorted node list so indices are stable
+        nodes: list = sorted(G.nodes())
+        n_nodes = len(nodes)
+
+        # --- Union-Find -----------------------------------------------
+        parent = list(range(n_nodes))
+
+        def find(x: int) -> int:
+            while parent[x] != x:
+                parent[x] = parent[parent[x]]
+                x = parent[x]
+            return x
+
+        def union(x: int, y: int) -> None:
+            rx, ry = find(x), find(y)
+            if rx != ry:
+                parent[rx] = ry
+
+        node_to_idx: dict[int, int] = {v: i for i, v in enumerate(nodes)}
+
+        # --- Enumerate automorphisms and union equivalent nodes --------
+        # Note: for graphs with large automorphism groups the enumeration can
+        # be expensive.  For typical QAOA problem graphs (tens of nodes) this
+        # is fast; for highly symmetric graphs (e.g. complete graphs) the
+        # number of automorphisms can be n! and you may want to limit
+        # iterations via early termination once all nodes are merged.
+        gm = GraphMatcher(G, G)
+        for auto in gm.isomorphisms_iter():
+            for idx, v in enumerate(nodes):
+                mapped_v = auto[v]
+                mapped_idx = node_to_idx[mapped_v]
+                union(idx, mapped_idx)
+            # Early exit: if all nodes are already in one orbit, stop
+            if len({find(i) for i in range(n_nodes)}) == 1:
+                break
+
+        # --- Group nodes by orbit root ---------------------------------
+        orbit_groups: dict[int, list] = defaultdict(list)
+        for idx in range(n_nodes):
+            orbit_groups[find(idx)].append(nodes[idx])
+
+        self.node_orbits: list[list] = list(orbit_groups.values())
+
+        # Build node → orbit index map
+        self.node_to_orbit: dict[int, int] = {}
+        for orbit_idx, orbit_nodes in enumerate(self.node_orbits):
+            for v in orbit_nodes:
+                self.node_to_orbit[v] = orbit_idx
+
+    # ------------------------------------------------------------------
+    # Overrides
+    # ------------------------------------------------------------------
+
+    def get_num_parameters(self) -> int:
+        """
+        Returns the number of :math:`\\beta` parameters per layer.
+
+        One parameter is used per node orbit of the graph.
+
+        Returns:
+            int: Number of node orbits (≥ 1).
+        """
+        return len(self.node_orbits)
+
+    def create_circuit(self) -> None:
+        """
+        Constructs the orbit-equivariant X mixer circuit.
+
+        Each qubit (node) :math:`i` receives an RX rotation whose parameter
+        is shared with all nodes in the same automorphism orbit.  Parameters
+        are named ``x_beta_orbit_0``, ``x_beta_orbit_1``, … (zero-padded so
+        alphabetical ordering matches orbit index order).
+        """
+        n_orbits = self.get_num_parameters()
+        n_digits = len(str(n_orbits - 1)) if n_orbits > 1 else 1
+        orbit_params = [
+            Parameter(f"x_beta_orbit_{i:0{n_digits}d}") for i in range(n_orbits)
+        ]
+
+        # Stable node ordering (sorted integers) matches qubit indices
+        nodes: list = sorted(self._canonical_G.nodes())
+
+        q = QuantumRegister(self.N_qubits)
+        self.circuit = QuantumCircuit(q)
+
+        for qubit_idx, v in enumerate(nodes):
+            orbit_idx = self.node_to_orbit[v]
+            self.circuit.rx(-2 * orbit_params[orbit_idx], q[qubit_idx])