Remove objective-direction compatibility shims and enforce canonical energy semantics

README.md

@@ -114,9 +114,6 @@ Examples:
 - **QUBO**: natural objective is the un-negated polynomial
   $x^\top Q x + c^\top x + b$.
 
-Legacy `cost(x)` is kept as a deprecated compatibility score with old behavior:
-`cost(x) = -energy(x)`.
-
 ---
 
 ## Background
@@ -253,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
-}
+}

examples/MaxCut/ComparisonPostProcessing.ipynb

@@ -139,7 +139,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Compare expectation value, with and without post-processing."
+    "Compare energy, with and without post-processing."
    ]
   },
   {
@@ -158,9 +158,9 @@
     }
    ],
    "source": [
-    "print(f\"Expected value at depth {maxdepth} without post_processing: {qaoa_post.get_Exp(maxdepth)}\")\n",
-    "print(f\"Expected value at depth {maxdepth} with post-processing: {qaoa_post.Exp_post_processed}\")\n",
-    "print(f\"Precalculated minimum cost: {mincost}\")"
+    "print(f\"Expected value at depth {maxdepth} without post_processing: {qaoa_post.get_energy(maxdepth)}\")\n",
+    "print(f\"Energy at depth {maxdepth} with post-processing: {qaoa_post.Energy_post_processed}\")\n",
+    "print(f\"Precalculated minimum objective value: {mincost}\")"
    ]
   },
   {
@@ -275,7 +275,7 @@
     "plt.plot(x, [mincost]*maxdepth, label=\"True\")\n",
     "plt.legend()\n",
     "plt.xlabel(\"depth\")\n",
-    "plt.ylabel(\"expectation value\")\n",
+    "plt.ylabel(\"energy\")\n",
     "plt.show()"
    ]
   }

examples/MaxCut/ConstrainedCase.ipynb

@@ -72,7 +72,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Precomputed maximum value of the constrained cost function."
+    "Precomputed maximum value of the constrained objective function."
    ]
   },
   {
@@ -335,8 +335,8 @@
     }
    ],
    "source": [
-    "p = np.arange(1, len(np.array(qaoa.get_Exp())) + 1)\n",
-    "plt.plot(p, -np.array(qaoa.get_Exp()) / maxval, marker=\"o\")\n",
+    "p = np.arange(1, len(np.array(qaoa.get_energy())) + 1)\n",
+    "plt.plot(p, -np.array(qaoa.get_energy()) / maxval, marker=\"o\")\n",
     "plt.xlabel(\"depth\")\n",
     "plt.ylabel(\"Approx. ratio\")\n",
     "plt.title(\"LX-QAOA\")\n",