Copilot/copilotimplement objective direction migration (#61)

core objective sense and energy semantics

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: fgfuchs <2428162+fgfuchs@users.noreply.github.com>

Author: 3 people

README.md

@@ -13,6 +13,7 @@ A flexible, modular Python library for the [Quantum Approximate Optimization Alg
 - [Installation](#installation)
 - [Requirements](#requirements)
 - [Quick Example](#quick-example)
+- [Objective direction and sign convention](#objective-direction-and-sign-convention)
 - [Background](#background)
 - [Custom Ansatz](#custom-ansatz)
 - [Running Optimization](#running-optimization-at-depth-p)
@@ -81,7 +82,8 @@ qaoa.sample_cost_landscape()
 qaoa.optimize(depth=3)
 
 # Extract results
-print("Optimal expectation value:", qaoa.get_Exp(depth=3))
+print("Optimal energy:", qaoa.get_energy(depth=3))
+print("Optimal objective:", qaoa.get_objective(depth=3))
 print("Optimal parameters (gamma):", qaoa.get_gamma(depth=3))
 print("Optimal parameters (beta):", qaoa.get_beta(depth=3))
 ```
@@ -90,14 +92,38 @@ See [examples/](examples/) for more complete worked examples.
 
 ---
 
+## Objective direction and sign convention
+
+Each problem declares an explicit objective direction via `problem.objective_sense` (`"minimize"` or `"maximize"`).
+
+- `problem.objective_value(x)` is the natural mathematical objective.
+- `problem.energy(x)` is the canonical quantity minimized by QAOA.
+
+Conversion is centralized:
+
+- `MINIMIZE`: `energy(x) = objective_value(x)`
+- `MAXIMIZE`: `energy(x) = -objective_value(x)`
+
+Phase separators follow:
+
+$$U_P(\gamma)|x\rangle = e^{-i\gamma\,\mathrm{energy}(x)}|x\rangle.$$
+
+Examples:
+
+- **MaxCut**: natural objective is positive cut value; energy is its negative.
+- **QUBO**: natural objective is the un-negated polynomial
+  $x^\top Q x + c^\top x + b$.
+
+---
+
 ## Background
-Given a **cost function** 
-$$c: \lbrace 0, 1\rbrace^n \rightarrow \mathbb{R}$$
+Given an **energy function**
+$$E: \lbrace 0, 1\rbrace^n \rightarrow \mathbb{R}$$
 one defines a **problem Hamiltonian** $H_P$ through the action on computational basis states via
 
-$$ H_P |x\rangle = c(x) |x\rangle,$$
+$$ H_P |x\rangle = E(x) |x\rangle,$$
 
-which means that ground states minimize the cost function $c$.
+which means that ground states minimize the canonical 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.$$
@@ -119,7 +145,7 @@ $U_M(\beta_l)=e^{-i\beta_l X^{\otimes n}}$,  $U_P(\gamma_l)=e^{-i\gamma_l H_P}$,
 
 ## Custom Ansatz
 
-To create a custom QAOA ansatz, specify a [problem](qaoa/problems/base_problem.py), a [mixer](qaoa/mixers/base_mixer.py), and an [initial state](qaoa/initialstates/base_initialstate.py). These base classes each have an abstract method `def create_circuit:` that must be implemented. The problem base class additionally requires `def cost:`.
+To create a custom QAOA ansatz, specify a [problem](qaoa/problems/base_problem.py), a [mixer](qaoa/mixers/base_mixer.py), and an [initial state](qaoa/initialstates/base_initialstate.py). These base classes each have an abstract method `def create_circuit:` that must be implemented. A custom problem should define `objective_sense` and `objective_value()`. The phase separator must encode `energy(x)` as above.
 
 This library already contains several standard implementations.
 
@@ -177,12 +203,12 @@ qaoa.sample_cost_landscape()
 
 Sampling high-dimensional target functions quickly becomes intractable for depth $p>1$. The library therefore **iteratively increases the depth**. At each depth a **local optimization** algorithm (e.g. COBYLA) finds a local minimum, using the following **initial guess**:
 
-- At depth $p=1$: parameters $(\gamma, \beta)$ are taken from the minimum of the sampled cost landscape.
+- At depth $p=1$: parameters $(\gamma, \beta)$ are taken from the minimum of the sampled energy landscape.
 - At depth $p>1$: two strategies are available, controlled by the `interpolate` parameter:
 
   * **Interpolation** (`interpolate=True`, default): uses the [INTERP heuristic](https://arxiv.org/pdf/1812.01041.pdf) to produce a smooth initial guess by interpolating the optimal angles from depth $p-1$. Works well for vanilla QAOA.
 
-  * **Layer-by-layer grid scan** (`interpolate=False`): the best angles from depth $p-1$ are *locked* and a 2-D grid search is performed over the new layer's parameters. Because the grid includes $(γ=0, β=0)$ — which adds an identity layer reproducing the depth-$(p-1)$ result — the initial cost at depth $p$ is guaranteed to be ≤ cost at depth $p-1$, ensuring a monotonically increasing approximation ratio. Recommended for multi-angle and orbit ansätze.
+  * **Layer-by-layer grid scan** (`interpolate=False`): the best angles from depth $p-1$ are *locked* and a 2-D grid search is performed over the new layer's parameters. Because the grid includes $(γ=0, β=0)$ — which adds an identity layer reproducing the depth-$(p-1)$ result — the initial energy at depth $p$ is guaranteed to be ≤ energy at depth $p-1$, ensuring a monotonically increasing approximation ratio. Recommended for multi-angle and orbit ansätze.
 
 ```python
 # Interpolation (default)
@@ -224,16 +250,24 @@ qaoa = QAOA(
 
 ## Extract Results
 
-Once `qaoa.optimize(depth=p)` is run, extract the expectation value, variance, and parameters for each depth $1\leq i \leq p$:
+Once `qaoa.optimize(depth=p)` is run, extract the best energy, variance,
+objective value, and parameters for each depth $1\leq i \leq p$:
 
 ```python
-qaoa.get_Exp(depth=i)
+qaoa.get_energy(depth=i)
+qaoa.get_objective(depth=i)
 qaoa.get_Var(depth=i)
 qaoa.get_gamma(depth=i)
 qaoa.get_beta(depth=i)
 ```
 
-Additionally, for every optimizer call at each depth, the **angles, expectation value, variance, maximum cost, minimum cost, and number of shots** are stored in:
+The legacy compatibility aliases `problem.cost()`, `problem.computeMinMaxCosts()`,
+and `qaoa.get_Exp()` are not part of the API anymore. Use
+`objective_value()`, `objective_bounds()`, `get_energy()`, and
+`get_objective()` directly.
+
+Additionally, for every optimizer call at each depth, the optimizer history,
+variance, best solutions, and shot counts are stored in:
 
 ```python
 qaoa.optimization_results[i]

examples/ExactCover/CompareGroverXY.ipynb

@@ -96,7 +96,7 @@
     "\n",
     "opt_sol = ec_problem.brute_force_solve()\n",
     "print(f\"Optimal solution (brute force): {opt_sol}\")\n",
-    "print(f\"Cost:                           {ec_problem.cost(opt_sol):.6f}\")"
+    "print(f\"Cost:                           {ec_problem.objective_value(opt_sol):.6f}\")"
    ]
   },
   {

examples/ExactCover/ExactCover 6 3.ipynb

@@ -101,9 +101,9 @@
     "print(\"solutions:\")\n",
     "costs=[]\n",
     "for s in [''.join(i) for i in itertools.product('01', repeat =nL)]:\n",
-    "    costs.append(-qaoa.problem.cost(s))\n",
+    "    costs.append(qaoa.problem.energy(s))\n",
     "    if qaoa.problem.isFeasible(s):\n",
-    "        print(s, -qaoa.problem.cost(s))"
+    "        print(s, qaoa.problem.energy(s))"
    ]
   },
   {
@@ -216,7 +216,7 @@
     }
    ],
    "source": [
-    "min_cost, max_cost = qaoa.problem.computeMinMaxCosts()\n",
+    "min_cost, max_cost = qaoa.problem.objective_bounds()\n",
     "min_cost, max_cost"
    ]
   },

examples/ExactCover/data/exact_cover_path_problem_example.json

@@ -73,7 +73,8 @@
       0.0,
       0.0
     ],
-    "hamming_weight": 2
+    "hamming_weight": 2,
+    "objective_sense": "minimize"
   },
   "qaoa_params": {
     "cvar": 0.7,
@@ -118,7 +119,9 @@
           "00000011": 19,
           "01000010": 503
         },
-        "opt_time": 0.7518182500207331
+        "opt_time": 0.7518182500207331,
+        "best_energy": null,
+        "best_objective": null
       },
       "2": {
         "optimal_angles": [
@@ -157,7 +160,9 @@
           "10000100": 224,
           "00000011": 150
         },
-        "opt_time": 0.31045849999645725
+        "opt_time": 0.31045849999645725,
+        "best_energy": null,
+        "best_objective": null
       },
       "3": {
         "optimal_angles": [
@@ -195,7 +200,9 @@
           "01010000": 102,
           "00000110": 439
         },
-        "opt_time": 0.438680374994874
+        "opt_time": 0.438680374994874,
+        "best_energy": null,
+        "best_objective": null
       },
       "4": {
         "optimal_angles": [
@@ -238,7 +245,9 @@
           "00010010": 33,
           "01100000": 3335
         },
-        "opt_time": 0.6514912919956259
+        "opt_time": 0.6514912919956259,
+        "best_energy": null,
+        "best_objective": null
       },
       "5": {
         "optimal_angles": [
@@ -283,7 +292,9 @@
           "00011000": 103,
           "00000110": 146
         },
-        "opt_time": 0.9302357080159709
+        "opt_time": 0.9302357080159709,
+        "best_energy": null,
+        "best_objective": null
       },
       "6": {
         "optimal_angles": [
@@ -330,7 +341,9 @@
           "00010010": 14,
           "01100000": 2922
         },
-        "opt_time": 1.1260944169771392
+        "opt_time": 1.1260944169771392,
+        "best_energy": null,
+        "best_objective": null
       },
       "7": {
         "optimal_angles": [
@@ -379,7 +392,9 @@
           "00001001": 143,
           "00000110": 132
         },
-        "opt_time": 1.5074970000132453
+        "opt_time": 1.5074970000132453,
+        "best_energy": null,
+        "best_objective": null
       },
       "8": {
         "optimal_angles": [
@@ -430,7 +445,9 @@
           "10000010": 56,
           "10000001": 17
         },
-        "opt_time": 1.9193396670161746
+        "opt_time": 1.9193396670161746,
+        "best_energy": null,
+        "best_objective": null
       },
       "9": {
         "optimal_angles": [
@@ -482,7 +499,9 @@
           "00000011": 29,
           "00000110": 180
         },
-        "opt_time": 2.4477102090022527
+        "opt_time": 2.4477102090022527,
+        "best_energy": null,
+        "best_objective": null
       },
       "10": {
         "optimal_angles": [
@@ -537,7 +556,9 @@
           "00100001": 5,
           "10010000": 4087
         },
-        "opt_time": 2.9181083750154357
+        "opt_time": 2.9181083750154357,
+        "best_energy": null,
+        "best_objective": null
       }
     }
   },
@@ -551,5 +572,6 @@
     "conda_env": "neqst-kongsberg-2025",
     "qaoa_repo_dir": "/Users/havahol/playground/quantum/QAOA/qaoa/utils",
     "qaoa_git_commit": "ff2d04cf2aa5069dcb58ba57ab7d2fc79c465513"
-  }
+  },
+  "schema_version": 3
 }

examples/MaxCut/CVaR.ipynb

@@ -35,7 +35,7 @@
    "id": "3d17ca29",
    "metadata": {},
    "source": [
-    "Create Barabási–Albert graph instance, more examples can be found here https://github.com/OpenQuantumComputing/data."
+    "Create Barab\u00e1si\u2013Albert graph instance, more examples can be found here https://github.com/OpenQuantumComputing/data."
    ]
   },
   {
@@ -55,11 +55,7 @@
      "output_type": "display_data"
     }
    ],
-   "source": [
-    "G = nx.read_gml(\"data/w_ba_n21_k4_0.gml\") # Load graph data for the 21-node, 4-regular graph (GML format) in examples/MaxCUt/data\n",
-    "nx.draw_networkx(G)\n",
-    "mincost = -25.23404480588015 # Precalculated minimum cost (for comparison)"
-   ]
+   "source": "G = nx.read_gml(\"data/w_ba_n21_k4_0.gml\") # Load graph data for the 21-node, 4-regular graph (GML format) in examples/MaxCUt/data\nnx.draw_networkx(G)\nmincost = 0  # worst feasible objective (no edges cut)\nmaxcost = 25.23404480588015  # precalculated optimal MaxCut value"
   },
   {
    "cell_type": "markdown",
@@ -222,29 +218,7 @@
      "output_type": "display_data"
     }
    ],
-   "source": [
-    "import matplotlib.pyplot as plt\n",
-    "\n",
-    "fig = plt.figure()\n",
-    "utils.plot_ApproximationRatio(\n",
-    "    qaoa,\n",
-    "    maxdepth,\n",
-    "    mincost=mincost,\n",
-    "    maxcost=0,\n",
-    "    label=\"QAOA vanilla\",\n",
-    "    style=\"o--b\",\n",
-    "    fig=fig,\n",
-    ")\n",
-    "utils.plot_ApproximationRatio(\n",
-    "    qaoa_CVaR,\n",
-    "    maxdepth,\n",
-    "    mincost=mincost,\n",
-    "    maxcost=0,\n",
-    "    label=\"QAOA CVaR\",\n",
-    "    style=\"x--k\",\n",
-    "    fig=fig,\n",
-    ")"
-   ]
+   "source": "import matplotlib.pyplot as plt\n\nfig = plt.figure()\nutils.plot_ApproximationRatio(\n    qaoa,\n    maxdepth,\n    mincost=mincost,\n    maxcost=maxcost,\n    label=\"QAOA vanilla\",\n    style=\"o--b\",\n    fig=fig,\n)\nutils.plot_ApproximationRatio(\n    qaoa_CVaR,\n    maxdepth,\n    mincost=mincost,\n    maxcost=maxcost,\n    label=\"QAOA CVaR\",\n    style=\"x--k\",\n    fig=fig,\n)"
   },
   {
    "cell_type": "markdown",
@@ -301,4 +275,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/MaxCut/ComparisonOptimizers.ipynb

@@ -37,7 +37,7 @@
    "id": "0e9efef7",
    "metadata": {},
    "source": [
-    "Create Barabási–Albert graph instance, more examples can be found here https://github.com/OpenQuantumComputing/data"
+    "Create Barab\u00e1si\u2013Albert graph instance, more examples can be found here https://github.com/OpenQuantumComputing/data"
    ]
   },
   {
@@ -57,11 +57,7 @@
      "output_type": "display_data"
     }
    ],
-   "source": [
-    "G = nx.read_gml(\"data/w_ba_n10_k4_0.gml\") # Load graph data for the 10-node, 4-regular graph (GML format) in examples/MaxCut/data\n",
-    "nx.draw_networkx(G)\n",
-    "mincost = -8.657714089848158  # Precalculated"
-   ]
+   "source": "G = nx.read_gml(\"data/w_ba_n10_k4_0.gml\") # Load graph data for the 10-node, 4-regular graph (GML format) in examples/MaxCut/data\nnx.draw_networkx(G)\nmincost = 0  # worst feasible objective (no edges cut)\nmaxcost = 8.657714089848158  # precalculated optimal MaxCut value"
   },
   {
    "cell_type": "markdown",
@@ -257,21 +253,7 @@
      "output_type": "display_data"
     }
    ],
-   "source": [
-    "import matplotlib.pyplot as plt\n",
-    "\n",
-    "fig = plt.figure()\n",
-    "for key in optimizers:\n",
-    "    utils.plot_ApproximationRatio(\n",
-    "        qaoa[key],\n",
-    "        maxdepth,\n",
-    "        mincost=mincost,\n",
-    "        maxcost=0,\n",
-    "        label=key,\n",
-    "        style=plotstyle[key] + \"-\",\n",
-    "        fig=fig,\n",
-    "    )"
-   ]
+   "source": "import matplotlib.pyplot as plt\n\nfig = plt.figure()\nfor key in optimizers:\n    utils.plot_ApproximationRatio(\n        qaoa[key],\n        maxdepth,\n        mincost=mincost,\n        maxcost=maxcost,\n        label=key,\n        style=plotstyle[key] + \"-\",\n        fig=fig,\n    )"
   },
   {
    "cell_type": "markdown",
@@ -441,4 +423,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}