Polish method by AndresFerCervell · Pull Request #1032 · gambitproject/gambit

AndresFerCervell · 2026-08-08T17:21:38Z

This PR introduces the new function PolishPoint (other name suggestions are welcome) in path.cc. Its goal is to reduce the regret of a point that is already close to an equilibrium found by the path-following algorithm. Fixing the value of a component of the point (t in HP), it uses a Newton-type method to find a nearby point with lower regret. The resolution of the system uses the already implemented methods QRDecomp and NewtonStep.

It returns a TracePathResult struct. Now, TracePathResult also stores the number of steps necessary to finish the algorithm, useful for debugging purposes.
PolishPoint is used in hp.cc to refine the equilibrium computed by the tracer.

The termination function has been updated: now it returns true if t >= 1.

The results are very positive. When adding the orientation fix from PR #1030, we see that now we can accurately control the regret of the outputs.

For example, if we set tol=1e-1 (the tolerance is extremely high, so the polish function does nothing), and test the games with a unique best response at t=0 from contrib/games, the tests that do not reach a regret lower than 1e-14 are the following:

  - todd1.nfg -> Eq: 1, Regret: 8.71e-02, Max T: 1.2008
  - 5x4x3.nfg -> Eq: 1, Regret: 1.60e-02, Max T: 1.08448
  - cent2.nfg -> Eq: 1, Regret: 3.00e-02, Max T: 1.01178
  - g3.nfg -> Eq: 1, Regret: 9.42e-03, Max T: 1.01912
  - g1.nfg -> Eq: 1, Regret: 7.63e-03, Max T: 1.32698
  - mixdom2.nfg -> Eq: 1, Regret: 7.23e-03, Max T: 1.03742
  - 2x2const.nfg -> Eq: 1, Regret: 1.12e-02, Max T: 1.03507
  - g2.nfg -> Eq: 1, Regret: 5.73e-04, Max T: 1.35734
  - 2x2x2x2x2.nfg -> Eq: 1, Regret: 4.24e-03, Max T: 1.01367

(Eq means the number of equilibria found, but that is not of interest for this PR, nor is Max T).
If we set now tol=1e-8, the results are the following:

  - 5x4x3.nfg -> Eq: 1, Regret: 3.95e-10, Max T: 1.08448
  - g3.nfg -> Eq: 1, Regret: 4.00e-10, Max T: 1.01912
  - g1.nfg -> Eq: 1, Regret: 5.15e-09, Max T: 1.32698
  - mixdom2.nfg -> Eq: 1, Regret: 3.91e-13, Max T: 1.03742
  - 2x2const.nfg -> Eq: 1, Regret: 5.17e-10, Max T: 1.03507
  - g2.nfg -> Eq: 1, Regret: 8.79e-14, Max T: 1.35734
  - 2x2x2x2x2.nfg -> Eq: 1, Regret: 5.39e-09, Max T: 1.01367

We can see that every failing game has a regret higher than the tol.
If we decide to equal the tolerance of the tests with the one in hp.cc, they all pass!
Some of these games are in test_hp.py in PR #1007 as a representation.

tturocy

The results on this polishing idea are indeed very promising. A few adjustments to make, but I don't see anything fundamentally wrong with the approach or implementation!

tturocy · 2026-08-11T07:59:46Z

-  auto termination_condition = [](const Vector<double> &point) { return point[1] >= 1.5; };
-  auto criterion_function = [](const Vector<double> &point,
-                               const Vector<double> &tangent) -> double { return point[1] - 1.0; };
+  auto termination_condition = [t_target](const Vector<double> &point) {


We don't need to specify a termination condition at all now. Actually by having both termination condition and criterion, the criterion never gets used. The result is we stop once we cross t=1. But that could be a ways past t=1, and possibly leave us with a profile that's far enough from Nash that our polishing step doesn't work.

Instead if we have no termination condition and let criterion do the work, we wind up somewhere really close to t=1. Then the polish step will work (almost for sure all the time!)

I understand, but I see two problems with removing it completely:

-The tracer will return a False status even when it is successful, because the only way that it has now of finishing is by reducing the step size to the minimum.

-vd.nfg fails because the criterion calculations become unstable near t=1, so eventually it keeps growing to infinity.

Therefore, I suggest an implementation of the termination function that makes use of the criterion, but also has a safeguard in case it fails, leaving the problem to the polishing function.

It works by comparing the current t with the last one when last_t was bigger than 1. If t > last_t, criterion is not working properly, and we have to finish the tracer before t gets too far.
It also ends if we have reached the expected equilibrium.

Good points both.

For the first point, this is a case where the step size getting small means something different in the two "modes". When we're in Newton mode, it's actually potentially a sign of success, not failure. What we should do is add a check that when in Newton mode, when the step size is tiny, check the value of the criterion function against a constant tolerance - if within that tolerance return success rather than failure.

For the second point, that game's got continua of equilibria which makes it a very good example. Here's the output from enummixed:

convex-1,1,0,0,0,0,1,0,0 convex-1,1,0,0,0,2/3,1/3,0,0 convex-2,0,0,1,0,0,0,1,0 convex-2,0,0,1,0,1,0,0,0 convex-3,0,0,3/4,1/4,0,0,1/4,3/4 convex-3,0,0,3/4,1/4,1/4,1/3,0,5/12 convex-3,0,0,3/4,1/4,1/4,0,0,3/4 convex-3,0,0,3/4,1/4,0,7/12,1/4,1/6 convex-4,0,0,0,1,0,0,0,1 convex-4,0,0,0,1,0,2/3,0,1/3

That is, the set of equilibria is the union of four convex sets (with the indicated extreme points). Seeing where the method is converging to in relation to these sets would be useful.

This will therefore also be a good practical example to include in the writeup, because it's a concrete example of where actually running this on "real" games - as opposed simply to doing the math theoretically, or running on games with randomly-generated payoffs, which will never have such positive-dimension equilibrium sets!

Interesting!
I just added that check.
I will add more tests with games like this when these branches get merged.

tturocy · 2026-08-11T08:01:15Z

  Vector<double> final_point;
  bool status; // true if path tracing terminated successfully, false if it terminated due to error
  std::string message; // error message if status is false
+  int step;            // Step at which the tracing terminated


Calling this steps feels better - yes it's the step number where it finished but also is the number of steps taken, and we use steps everywhere else

tturocy · 2026-08-11T08:03:05Z

+    p_function(x, y);
+    p_jacobian(x, jac_full);
+
+    // Square Matrix removing fixed_index column


This comment is slightly misleading, and actually the comment on jac_square above already covers what this is

tturocy · 2026-08-11T08:04:53Z

+// This function reduces the regret of a point that is close to an equilibrium that has been found
+// by the path-following algorithm.  Fixing the value of a component of the point, it uses a
+// Newton-type method to find a nearby point with lower regret.
+TracePathResult


This feels like we're abusing the return type. Even if the fields are the same, the idea behind these result return types is that they're semantically related to the method they're coming from. So I'd suggest defining its own result type for this method.

tturocy

A few minor adjustments noted but I think this is close once we clean them up.

Two actions:

You'll need to resolve the merge conflicts against the new main feature/hp branch as this interacts with the improvements on setting direction merged a bit ago today
Remember to clear out the print tracing instrumentation for the next (final) review.

tturocy · 2026-08-12T15:46:25Z

+      }
+    }
+    else {
+      // Criterion function might take t back to being minor than t_target


"less than" - I can see "minor than" is a direct calque from Spanish and/or Catalan!

tturocy · 2026-08-12T15:47:56Z

+  double h = m_hStart;              // initial stepsize
+  const double c_hmin = 1.0e-8;     // minimal stepsize
+  const int c_maxIter = 100;        // maximum iterations in corrector
+  const double newton_tol = 1.0e-8; // tolerance for Newton convergence


Would be good to keep similar naming style - c_newtonTol.

tturocy · 2026-08-12T15:48:58Z

    if (fabs(h) <= c_hmin) {
-      return {x, false, "Stepsize fell below minimum threshold.", steps};
+      if (newton && std::abs(p_criterion(x, t)) < newton_tol) {
+        return {x, true, "Path tracing terminated successfully (Newton convergence)", steps};


Probably need something more user-interpretable here: "Path following terminated successfully at point satisfying criterion function."

tturocy · 2026-08-12T15:49:14Z

      if (fabs(h) <= c_hmin) {
-        return {x, false, "Stepsize fell below minimum threshold.", steps};
+        if (newton && std::abs(p_criterion(x, t)) < newton_tol) {
+          return {x, true, "Path tracing terminated successfully (Newton convergence)", steps};


Same comment as above

tturocy · 2026-08-12T15:50:41Z

+      }
+      else {
+        // Criterion function is not working; polish will do the job
+        if (t > last_t + tol) {


Don't need this level of nesting, can pull the if up a level

tturocy

Should also have added

Would it make sense to roll in the test games from that other PR into this now, assuming they are working well with this methodology?

Removed initial tangent vector checks for path-following direction.

AndresFerCervell · 2026-08-12T22:23:37Z

I decided to add the tests in this PR to avoid conflicts merging the other one. They all pass, although I had to add the catalog games that were not available at the start of the project.

AndresFerCervell · 2026-08-14T11:28:52Z

      },
      x, direction, tracking_index, termination_condition, NullCallbackFunction,
      criterion_function);
+  if (!result.status) {


This makes some of the complex tests fail because the Tracer is not able to reach such a strict tolerance. The error message is "Maximum iterations exceeded.". I think we should let the polish function finish the work even though the tracer failed.

I noted some comments in a separate email but to keep things in one place:

The first example (fig6_8) actually the tracing is successful but incorrectly reports failure, basically because it doesn't have to Newton step at all to achieve the tolerance. That's a simple adjustment.

The second example really needs some scrutiny to understand why it's failing so we can be precise about what this implementation computes!

Polish method

9bc34b1

tturocy requested changes Aug 11, 2026

View reviewed changes

tturocy mentioned this pull request Aug 11, 2026

hp.cc modifications #1011

Closed

AndresFerCervell added 2 commits August 11, 2026 14:19

Adjustments in polish method

bbc4b4e

Newton check in tracer

d48a057

tturocy requested changes Aug 12, 2026

View reviewed changes

AndresFerCervell and others added 4 commits August 12, 2026 23:27

Format fixes

04882bf

Format fixes, test suite, merge..

5829da2

Merge branch 'feature/hp' into feature/hp_polish

3275e7f

Removing duplicated first_step logic

b38db1d

Removed initial tangent vector checks for path-following direction.

Small tidying.

41673ad

AndresFerCervell commented Aug 14, 2026

View reviewed changes

Uh oh!

Conversation

AndresFerCervell commented Aug 8, 2026

Uh oh!

tturocy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tturocy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tturocy left a comment

Choose a reason for hiding this comment

Uh oh!

AndresFerCervell commented Aug 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants